zmf_console_command – Issue MVS command¶
Synopsis¶
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.
Parameters¶
- console_broadcastmsg_detect_timeout
Specifies how long, in seconds, the console attempts to detect the value of console_broadcastmsg_keyword in broadcast messages.
required: Falsetype: intdefault: 30- console_broadcastmsg_keyword
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 console_broadcastmsg_reg=true.
This parameter is designed to help user determine whether the broadcast messages issued after the command matches with user’s expectation.
If 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: Falsetype: str- console_broadcastmsg_reg
If console_broadcastmsg_keyword is specified, this variable specifies whether console_broadcastmsg_keyword represents a regular expression.
required: Falsetype: booldefault: false- console_cmd
Specifies the command to issue.
required: Truetype: str- console_cmdresponse_keyword
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 console_cmdresponse_reg=true.
This parameter is designed to help user determine whether the command response matches with user’s expectation.
If 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: Falsetype: str- console_cmdresponse_reg
If console_cmdresponse_keyword is specified, this variable specifies whether console_cmdresponse_keyword represents a regular expression.
required: Falsetype: booldefault: false- console_cmdresponse_retrieve_times
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: Falsetype: intdefault: 1- console_name
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: Falsetype: str- console_save_output_localpath
The local path on control node where the command response should be saved to. For example,
/tmp/cmd_output
.This path can be absolute or relative. The module will fail if parent directory of console_save_output_localpath is a read-only file system.
The directory
{{ console_save_output_localpath }}/{{ inventory_hostname }}/
will be created to save the command response.For example,
/tmp/cmd_output/SY1/
.The command response will be saved as separate file and named as
{{ console_cmd }}
, in which comma and space will be replaced with underline.For example,
/tmp/cmd_output/SY1/display_a_l
.required: Falsetype: str- console_system
Nickname of the target z/OS system in the same sysplex that the command is routed to.
This variable should be specified as
{{ inventory_hostname }}
, and its value should be specified in the inventory file as a managed node.required: Truetype: str- zmf_credential
Authentication credentials, returned by module
zmf_authenticate
, for the successful authentication with z/OSMF server.If zmf_credential is supplied, zmf_host, zmf_port, zmf_user, zmf_password, zmf_crt and zmf_key are ignored.
required: Falsetype: dict- jwtToken
The value of JSON Web token, which supports strong encryption.
If LtpaToken2 is not supplied, jwtToken is required.
required: Falsetype: str- LtpaToken2
The value of Lightweight Third Party Access (LTPA) token, which supports strong encryption.
If jwtToken is not supplied, LtpaToken2 is required.
required: Falsetype: str- zmf_host
Hostname of the z/OSMF server.
required: Truetype: str- zmf_port
Port number of the z/OSMF server.
required: Falsetype: int
- zmf_crt
Location of the PEM-formatted certificate chain file to be used for HTTPS client authentication.
If zmf_credential is supplied, zmf_crt is ignored.
If zmf_credential is not supplied, zmf_crt is required when zmf_user and zmf_password are not supplied.
required: Falsetype: str- zmf_host
Hostname of the z/OSMF server.
If zmf_credential is supplied, zmf_host is ignored.
If zmf_credential is not supplied, zmf_host is required.
required: Falsetype: str- zmf_key
Location of the PEM-formatted file with your private key to be used for HTTPS client authentication.
If zmf_credential is supplied, zmf_key is ignored.
If zmf_credential is not supplied, zmf_key is required when zmf_user and zmf_password are not supplied.
required: Falsetype: str- zmf_password
Password to be used for authenticating with z/OSMF server.
If zmf_credential is supplied, zmf_password is ignored.
If zmf_credential is not supplied, zmf_password is required when zmf_crt and zmf_key are not supplied.
If zmf_credential is not supplied and zmf_crt and zmf_key are supplied, zmf_user and zmf_password are ignored.
required: Falsetype: str- zmf_port
Port number of the z/OSMF server.
If zmf_credential is supplied, zmf_port is ignored.
required: Falsetype: int- zmf_user
User name to be used for authenticating with z/OSMF server.
If zmf_credential is supplied, zmf_user is ignored.
If zmf_credential is not supplied, zmf_user is required when zmf_crt and zmf_key are not supplied.
If zmf_credential is not supplied and zmf_crt and zmf_key are supplied, zmf_user and zmf_password are ignored.
required: Falsetype: str
Examples¶
- 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"
Return Values¶
- changed
Indicates if any change is made during the module operation.
returned: alwaystype: bool- message
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 successtype: strsample:
"The command is issued successfully." "The command is issued successfully. The specified keyword is detected in the command response." "The command is issued successfully. The specified keyword is detected in broadcast messages." "The command is issued successfully. The command response is saved in: /tmp/output/SY1/display_a_l"- cmd_response
The command response.
returned: on successtype: listsample:
[" 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"]- cmdresponse_keyword_detected
Indicate whether the specified keyword is detected in the command response.
returned: on success when console_cmdresponse_keyword is specifiedtype: bool- broadcastmsg_keyword_detected
Indicate whether the specified keyword is detected in broadcast messages.
returned: on success when console_broadcastmsg_keyword is specifiedtype: bool- detected_broadcastmsg
The message that contains the specified keyword that was detected in broadcast messages.
returned: on success when console_broadcastmsg_keyword is specifiedtype: listsample:
[" BPXM023I (ZOSMFAD) CFZ10030I: Started CIM Server version 2.14.2."]