zhmc_lpar_command – Execute OS console command in an LPAR (classic mode)

Synopsis

  • Execute a command in the console of the OS running in an LPAR and get back the command output.

  • Note: The OS console interface provided by the HMC WS-API does not allow separating multiple concurrent interactions. For example, when OS console commands are executed via the HMC GUI at the same time when executing this Ansible module, the command output returned by the Ansible module may be mixed with output from the concurrently executed command.

  • Note: The logic for determining which lines on the OS console belong to the executed command is as follows: The OS console messages are started to be captured just before the console command is sent. The captured console messages are then searched for the occurrence of the command. The command itself and all messages following the command are considered part of the command output, until there are no more new messages for 2 seconds. If there is a lot of traffic on the OS console, that may lead to other messages being included in the command output.

Requirements

  • The targeted CPC must be in the classic operational mode.

  • The targeted LPAR must be loaded (i.e. running an operating system).

  • The HMC userid must have these task permissions: ‘Operating System Messages’ (view-only is sufficient)

  • The HMC userid must have object-access permissions to these objects: Target CPC, target LPAR.

Parameters

hmc_host

The hostnames or IP addresses of a single HMC or of a list of redundant HMCs. A single HMC can be specified as a string type or as an HMC list with one item. An HMC list can be specified as a list type or as a string type containing a Python list representation.

The first available HMC of a list of redundant HMCs is used for the entire execution of the module.

required: True
type: raw
hmc_auth

The authentication credentials for the HMC.

required: True
type: dict
userid

The userid (username) for authenticating with the HMC. This is mutually exclusive with providing hmc_auth.session_id.

required: False
type: str
password

The password for authenticating with the HMC. This is mutually exclusive with providing hmc_auth.session_id.

required: False
type: str
session_id

HMC session ID to be used. This is mutually exclusive with providing hmc_auth.userid and hmc_auth.password and can be created as described in the zhmc_session module.

required: False
type: str
ca_certs

Path name of certificate file or certificate directory to be used for verifying the HMC certificate. If null (default), the path name in the REQUESTS_CA_BUNDLE environment variable or the path name in the CURL_CA_BUNDLE environment variable is used, or if neither of these variables is set, the certificates in the Mozilla CA Certificate List provided by the ‘certifi’ Python package are used for verifying the HMC certificate.

required: False
type: str
verify

If True (default), verify the HMC certificate as specified in the hmc_auth.ca_certs parameter. If False, ignore what is specified in the hmc_auth.ca_certs parameter and do not verify the HMC certificate.

required: False
type: bool
default: True
cpc_name

The name of the CPC with the target LPAR.

required: True
type: str
name

The name of the target LPAR.

required: True
type: str
command

The OS console command to be executed.

required: True
type: str
is_priority

Controls whether the command is executed as a priority command.

required: False
type: bool
log_file

File path of a log file to which the logic flow of this module as well as interactions with the HMC are logged. If null, logging will be propagated to the Python root logger.

required: False
type: str

Examples

---
# Note: The following examples assume that some variables named 'my_*' are set.

- name: Get z/OS system time via OS console command
  zhmc_lpar_command:
    hmc_host: "{{ my_hmc_host }}"
    hmc_auth: "{{ my_hmc_auth }}"
    cpc_name: "{{ my_cpc_name }}"
    name: "{{ my_lpar_name }}"
    command: "D T"
  register: zos_time_output

Return Values

changed

Indicates if any change has been made by the module.

This will always be true, because it is not clear whether the command has performed a change. Note that a playbook using this module with a command that does not perform a change can override that by specifying changed_when: false.

returned: always
type: bool
msg

An error message that describes the failure.

returned: failure
type: str
output

The command and its output, as one item per line, without any trailing newlines.

The format of each message text depends on the type of OS. Typical formats are, showing the message with the command:

z/VM: 04:30:02 Q CPLEVEL

z/OS: D T

Linux: uname -a

returned: success
type: list
elements: str
sample:
[
    "D T",
    "RESPONSE=GR1       IEE136I LOCAL: TIME=09.25.08 DATE=2024.194  UTC:",
    "RESPONSE=TIME=07.25.08 DATE=2024.194"
]