Added new modules for executing OS console commands (#1033)

* Added new modules for executing OS console commands

Details:

* Added new modules 'zhmc_lpar_command' and 'zhmc_partition_command' for
  executing an OS consosle command in the OS running in an LPAR or
  partition. (issue #938)

* In support of the above, added a new class 'NotificationThread' for
  running the message receiver thread.

* Enabled notification logging via the 'zhmcclient.jms' Python logger.
  (related to issue #938)

Signed-off-by: Andreas Maier <[email protected]>

* Squash: Added disclaimer notes

Signed-off-by: Andreas Maier <[email protected]>

---------

Signed-off-by: Andreas Maier <[email protected]>

docs/source/modules.rst

@@ -75,6 +75,7 @@ Modules supported only with CPCs in DPM operational mode:
    modules/zhmc_nic
    modules/zhmc_nic_list
    modules/zhmc_partition
+   modules/zhmc_partition_command
    modules/zhmc_partition_list
    modules/zhmc_partition_messages
    modules/zhmc_storage_group
@@ -89,6 +90,7 @@ Modules supported only with CPCs in classic operational mode:
    :glob:
 
    modules/zhmc_lpar
+   modules/zhmc_lpar_command
    modules/zhmc_lpar_list
    modules/zhmc_lpar_messages
 

docs/source/modules/zhmc_lpar_command.rst

@@ -0,0 +1,197 @@
+
+:github_url: https://github.com/ansible-collections/ibm_zos_core/blob/dev/plugins/modules/zhmc_lpar_command.py
+
+.. _zhmc_lpar_command_module:
+
+
+zhmc_lpar_command -- Execute OS console command in an LPAR (classic mode)
+=========================================================================
+
+
+
+.. contents::
+   :local:
+   :depth: 1
+
+
+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 \ :literal:`hmc\_auth.session\_id`\ .
+
+    | **required**: False
+    | **type**: str
+
+
+  password
+    The password for authenticating with the HMC. This is mutually exclusive with providing \ :literal:`hmc\_auth.session\_id`\ .
+
+    | **required**: False
+    | **type**: str
+
+
+  session_id
+    HMC session ID to be used. This is mutually exclusive with providing \ :literal:`hmc\_auth.userid`\  and \ :literal:`hmc\_auth.password`\  and can be created as described in the \ :ref:`zhmc\_session module <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 \ :envvar:`REQUESTS\_CA\_BUNDLE`\  environment variable or the path name in the \ :envvar:`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 \ :literal:`hmc\_auth.ca\_certs`\  parameter. If False, ignore what is specified in the \ :literal:`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
+--------
+
+.. code-block:: yaml+jinja
+
+
+   ---
+   # 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 \ :literal:`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: \ :literal:`04:30:02 Q CPLEVEL`\ 
+
+  z/OS: \ :literal:`D T`\ 
+
+  Linux: \ :literal:`uname -a`\ 
+
+  | **returned**: success
+  | **type**: list
+  | **elements**: str
+  | **sample**:
+
+    .. code-block:: json
+
+        [
+            "D T",
+            "RESPONSE=GR1       IEE136I LOCAL: TIME=09.25.08 DATE=2024.194  UTC:",
+            "RESPONSE=TIME=07.25.08 DATE=2024.194"
+        ]
+