ibm / ibm.ibm_zos_zosmf / 2.5.0 / module / zmf_console_command Issue MVS command | "added in version" 2.9 of ibm.ibm_zos_zosmf" Authors: Yang Cao (@zosmf-Young), Yun Juan Yang (@zosmf-Robyn) preview | supported by communityibm.ibm_zos_zosmf.zmf_console_command (2.5.0) — module
Install with ansible-galaxy collection install ibm.ibm_zos_zosmf:==2.5.0
collections: - name: ibm.ibm_zos_zosmf version: 2.5.0
Issue MVS command by using a system console through z/OS console RESTful services.
Retrieve command response and define success condition based on specified keywords in the command response or broadcast messages.
Save the command response on Ansible control node.
- name: Issue command to display active jobs zmf_console_command: zmf_host: "sample.ibm.com" console_cmd: "display a,l" console_system: "{{ inventory_hostname }}"
- name: Issue command to display active jobs and save the command response zmf_console_command: zmf_host: "sample.ibm.com" console_cmd: "display a,l" console_system: "{{ inventory_hostname }}" console_save_output_localpath: "/tmp/cmd_output"
- name: Issue command to start CIM server and detect if it is started successfully or not zmf_console_command: zmf_host: "sample.ibm.com" console_cmd: "start pegasus" console_system: "{{ inventory_hostname }}" console_cmdresponse_keyword: "SLP registration initiated"
- name: Issue command to start CIM server and detect if it is started successfully or not zmf_console_command: zmf_host: "sample.ibm.com" console_cmd: "start pegasus" console_system: "{{ inventory_hostname }}" console_broadcastmsg_keyword: "started CIM server"
zmf_crt: default: null description: - Location of the PEM-formatted certificate chain file to be used for HTTPS client authentication. - If I(zmf_credential) is supplied, I(zmf_crt) is ignored. - If I(zmf_credential) is not supplied, I(zmf_crt) is required when I(zmf_user) and I(zmf_password) are not supplied. required: false type: str zmf_key: default: null description: - Location of the PEM-formatted file with your private key to be used for HTTPS client authentication. - If I(zmf_credential) is supplied, I(zmf_key) is ignored. - If I(zmf_credential) is not supplied, I(zmf_key) is required when I(zmf_user) and I(zmf_password) are not supplied. required: false type: str zmf_host: default: null description: - Hostname of the z/OSMF server. - If I(zmf_credential) is supplied, I(zmf_host) is ignored. - If I(zmf_credential) is not supplied, I(zmf_host) is required. required: false type: str zmf_port: default: null description: - Port number of the z/OSMF server. - If I(zmf_credential) is supplied, I(zmf_port) is ignored. required: false type: int zmf_user: default: null description: - User name to be used for authenticating with z/OSMF server. - If I(zmf_credential) is supplied, I(zmf_user) is ignored. - If I(zmf_credential) is not supplied, I(zmf_user) is required when I(zmf_crt) and I(zmf_key) are not supplied. - If I(zmf_credential) is not supplied and I(zmf_crt) and I(zmf_key) are supplied, I(zmf_user) and I(zmf_password) are ignored. required: false type: str console_cmd: description: - Specifies the command to issue. required: true type: str console_name: default: null description: - Name of the EMCS console that is used to issue the command. - If this value is omitted, the console name is generated by adding CN to the logon user ID. required: false type: str zmf_password: default: null description: - Password to be used for authenticating with z/OSMF server. - If I(zmf_credential) is supplied, I(zmf_password) is ignored. - If I(zmf_credential) is not supplied, I(zmf_password) is required when I(zmf_crt) and I(zmf_key) are not supplied. - If I(zmf_credential) is not supplied and I(zmf_crt) and I(zmf_key) are supplied, I(zmf_user) and I(zmf_password) are ignored. required: false type: str console_system: description: - Nickname of the target z/OS system in the same sysplex that the command is routed to. - This variable should be specified as C({{ inventory_hostname }}), and its value should be specified in the inventory file as a managed node. required: true type: str zmf_credential: default: null description: - Authentication credentials, returned by module C(zmf_authenticate), for the successful authentication with z/OSMF server. - If I(zmf_credential) is supplied, I(zmf_host), I(zmf_port), I(zmf_user), I(zmf_password), I(zmf_crt) and I(zmf_key) are ignored. required: false suboptions: LtpaToken2: default: null description: - The value of Lightweight Third Party Access (LTPA) token, which supports strong encryption. - If I(jwtToken) is not supplied, I(LtpaToken2) is required. required: false type: str jwtToken: default: null description: - The value of JSON Web token, which supports strong encryption. - If I(LtpaToken2) is not supplied, I(jwtToken) is required. required: false type: str zmf_host: description: Hostname of the z/OSMF server. required: true type: str zmf_port: default: null description: Port number of the z/OSMF server. required: false type: int type: dict console_cmdresponse_reg: default: false description: - If I(console_cmdresponse_keyword) is specified, this variable specifies whether I(console_cmdresponse_keyword) represents a regular expression. required: false type: bool console_broadcastmsg_reg: default: false description: - If I(console_broadcastmsg_keyword) is specified, this variable specifies whether I(console_broadcastmsg_keyword) represents a regular expression. required: false type: bool console_cmdresponse_keyword: default: null description: - Specifies a keyword that you want to detect in the command response. Case is not significant. - This value can be a string or a regular expression. To use a regular expression, you must also set I(console_cmdresponse_reg=true). - This variable is designed to help user determine whether the command response matches with user's expectation. - If I(console_broadcastmsg_keyword) is not specified, the module will fail if the specified keyword can not be detected from the command response. - Otherwise, the module will fail if the specified keywords can not be detected from both command response and broadcast messages. required: false type: str console_broadcastmsg_keyword: default: null description: - Specifies a keyword that you want to detect in broadcast messages. Case is not significant. - This value can be a string or a regular expression. To use a regular expression, you must also set I(console_broadcastmsg_reg=true). - This variable is designed to help user determine whether the broadcast messages issued after the command matches with user's expectation. - If I(console_cmdresponse_keyword) is not specified, the module will fail if the specified keyword can not be detected from broadcast messages. - Otherwise, the module will fail if the specified keywords can not be detected from both command response and broadcast messages. required: false type: str console_save_output_localpath: default: null description: - The local path on control node where the command response should be saved to. For example, C(/tmp/cmd_output). - This path can be absolute or relative. The module will fail if parent directory of I(console_save_output_localpath) is a read-only file system. - The directory C({{ console_save_output_localpath }}/{{ inventory_hostname }}/) will be created to save the command response. - For example, C(/tmp/cmd_output/SY1/). - The command response will be saved as separate file and named as C({{ console_cmd }}), in which comma and space will be replaced with underline. - For example, C(/tmp/cmd_output/SY1/display_a_l). required: false type: str console_cmdresponse_retrieve_times: default: 1 description: - Specifies how many times the console attempts to retrieve the command response. - If the command response contains a large volume of messages, it will not arrive within a certain time interval. - In this case you might retrieve again several times to ensure that all messages related to the command are retrieved. required: false type: int console_broadcastmsg_detect_timeout: default: 30 description: - Specifies how long, in seconds, the console attempts to detect the value of I(console_broadcastmsg_keyword) in broadcast messages. required: false type: int
broadcastmsg_keyword_detected: description: Indicate whether the specified keyword is detected in broadcast messages. returned: on success when `console_broadcastmsg_keyword` is specified type: bool changed: description: Indicates if any change is made during the module operation. returned: always type: bool cmd_response: description: The command response. returned: on success sample: - ' CNZ4105I 04.32.31 DISPLAY ACTIVITY 458' - ' JOBS M/S TS USERS SYSAS INITS ACTIVE/MAX VTAM OAS' - ' 00002 00015 00002 00032 00005 00001/00020 00011' - ' VLF VLF VLF NSW S IGVDGNPP IGVDGNPP PRIMEPSA OWT S' - ' VTAM44 VTAM44 VTAM NSW S RACF RACF RACF NSW S' - ' GRSSTMON GRSSTMON STEP1 OWT S SDSF23 SDSF23 SDSF NSW S' - ' HZR HZR IEFPROC NSW S JES2 JES2 IEFPROC NSW S' - ' SDSFAUX SDSFAUX SDSFAUX NSW S TCAS TCAS TSO OWT S' - ' TCPIP TCPIP TCPIP NSW SO RESOLVER RESOLVER EZBREINI NSW SO' - ' RRS RRS RRS NSW S OMPROUTE OMPROUTE OMPROUTE NSW SO' - ' INETD1 STEP1 INETD OWT AO FTPDEV1 STEP1 FTPD OWT AO' - ' PEGASUS PEGASUS *OMVSEX IN SO' - ' IBMUSER OWT ZOSMFAD IN O' type: list cmdresponse_keyword_detected: description: Indicate whether the specified keyword is detected in the command response. returned: on success when `console_cmdresponse_keyword` is specified type: bool detected_broadcastmsg: description: The message that contains the specified keyword that was detected in broadcast messages. returned: on success when `console_broadcastmsg_keyword` is specified sample: - ' BPXM023I (ZOSMFAD) CFZ10030I: Started CIM Server version 2.14.2.' type: list message: description: - The output message generated by the module to indicate whether the command is successful. - If either `console_cmdresponse_keyword` or `console_broadcastmsg_keyword` is specified, indicate whether the specified keyword is detected. - If `console_save_output_localpath` is specified, indicate whether the command response is saved on control node. returned: on success sample: sample1: The command is issued successfully. sample2: The command is issued successfully. The specified keyword is detected in the command response. sample3: The command is issued successfully. The specified keyword is detected in broadcast messages. sample4: 'The command is issued successfully. The command response is saved in: /tmp/output/SY1/display_a_l' type: str