zmf_file_fetch – Fetch USS file from z/OS¶
Synopsis¶
Retrieve the contents of a z/OS UNIX System Services (USS) file from z/OS system, and save them on Ansible control node.
USS file that already exists at file_dest will be overwritten if it is different than the file_src.
Parameters¶
- file_checksum
Specifies the checksum to be used to verify that the USS file to be fetched is not changed since the checksum was generated.
If the checksum is matched which means the USS file is not changed, the USS file won’t be fetched.
required: Falsetype: str- file_data_type
Specifies whether data conversion is to be performed on the returned data.
When file_data_type=text, data conversion is performed.
You can use file_encoding to specify which encodings the fetched USS file should be converted from and to.
If file_encoding is not supplied, the data transfer process converts each record from
IBM-1047
toISO8859-1
by default.When file_data_type=binary, no data conversion is performed. The data transfer process returns each line of data as-is, without translation.
required: Falsetype: strdefault: textchoices: text, binary- file_dest
The local directory on control node where the USS file should be saved to. For example,
/tmp/file_output
.This directory can be absolute or relative. The module will fail if the parent directory of file_dest is a read-only file system.
The directory
{{ file_dest }}/{{ zmf_host }}/
will be created to save the USS file, where zmf_host is the hostname of the z/OSMF server.For example, if zmf_host=zosmf.ibm.com, a USS file named
/etc/profile
would be saved into/tmp/file_output/zosmf.ibm.com/etc/profile
.required: Truetype: str- file_encoding
Specifies which encodings the fetched USS file should be converted from and to.
This variable only take effects when file_data_type=text.
required: Falsetype: dict- from
The character set of the source USS file.
Supported character sets rely on the charset conversion utility (iconv) version. The most common character sets are supported.
required: Truetype: str- to
The destination character set for the output to be written as.
Supported character sets rely on the charset conversion utility (iconv) version. The most common character sets are supported.
required: Truetype: str
- file_flat
Specifies whether to override the default behavior of appending hostname/path/to/file to the destination.
If file_flat=true, the USS file will be fetched to the destination directory using its basename without appending zmf_host.
For example, if file_dest=/tmp/file_output, a USS file named
/etc/profile
would be saved into/tmp/file_output/profile
.required: Falsetype: booldefault: false- file_range
Specifies a range that is used to retrieve the USS file.
If file_data_type=text, the module will retrieve a range of records (lines delimited by ‘n’) from the USS file.
If file_data_type=binary, the module will retrieve a range of bytes from the USS file.
If this variable is specified, only the retrieved range of the USS file will be fetched to the destination directory.
The retrieved range of the USS file will be saved as
{{ file_dest }}/{{ zmf_host }}/{ file_src }}.range
on control node.For example, the retrieved range of the USS file named
/etc/profile
would be saved as....../etc/profile.range
.required: Falsetype: dict- end
If file_data_type=text, this variable identifies the end record in the range to be retrieved.
If file_data_type=binary, this variable identifies the byte-offset of the last byte in the range to be retrieved.
If this value is omitted or is set to 0, the range extends to the end of the USS file.
required: Falsetype: int- start
If file_data_type=text, this variable identifies the start record in the range to be retrieved.
If file_data_type=binary, this variable identifies the byte-offset of the first byte in the range to be retrieved.
If this value is omitted, a tail range is returned.
required: Falsetype: int
- file_search
Specifies a series of parameters that are used to search the USS file.
This variable only take effects when file_data_type=text.
If this variable is specified, only the matched contents in the USS file will be fetched to the destination directory.
The matched contents in the USS file will be saved as
{{ file_dest }}/{{ zmf_host }}/{ file_src }}.search
on control node.For example, the matched contents in the USS file named
/etc/profile
would be saved as....../etc/profile.search
.required: Falsetype: dict- insensitive
Specifies whether the comparison of keyword is case insensitive.
This variable only take effects when keyword is defined.
required: Falsetype: booldefault: true- keyword
Specifies a string or a regular expression that is used to search the USS file.
The USS file is searched for the first line that contains the string or matches the given extended regular expression.
required: Truetype: str- maxreturnsize
Specifies how many lines of contents from the first matched line in the USS file will be returned.
This variable only take effects when keyword is defined.
required: Falsetype: intdefault: 100
- file_src
USS file on z/OS system to fetch.
This variable must consist of a fully qualified path and file name. For example,
/etc/profile
.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: Fetch a USS file and store in /tmp/file_output/sample.ibm.com/etc/profile
zmf_file_fetch:
zmf_host: "sample.ibm.com"
file_src: "/etc/profile"
file_dest: "/tmp/file_output"
- name: Fetch a USS file and store in /tmp/file_output/profile
zmf_file_fetch:
zmf_host: "sample.ibm.com"
file_src: "/etc/profile"
file_dest: "/tmp/file_output"
file_flat: true
- name: Fetch a USS file as binary
zmf_file_fetch:
zmf_host: "sample.ibm.com"
file_src: "/etc/profile"
file_dest: "/tmp/file_output"
file_data_type: "binary"
- name: Fetch a USS file and convert from IBM-037 to ISO8859-1
zmf_file_fetch:
zmf_host: "sample.ibm.com"
file_src: "/etc/profile"
file_dest: "/tmp/file_output"
file_encoding:
from: IBM-037
to: ISO8859-1
- name: Fetch a range of records from a USS file (the first 500 lines)
zmf_file_fetch:
zmf_host: "sample.ibm.com"
file_src: "/etc/profile"
file_dest: "/tmp/file_output"
file_range:
start: 0
end: 499
- name: Fetch a range of records from a USS file (the final 500 lines)
zmf_file_fetch:
zmf_host: "sample.ibm.com"
file_src: "/etc/profile"
file_dest: "/tmp/file_output"
file_range:
end: 500
- name: Fetch 100 lines of records from the first matched line that contains "Health Checker" in a USS file
zmf_file_fetch:
zmf_host: "sample.ibm.com"
file_src: "/etc/profile"
file_dest: "/tmp/file_output"
file_search:
keyword: "Health Checker"
- name: Fetch a USS file and validate its checksum
zmf_file_fetch:
zmf_host: "sample.ibm.com"
file_src: "/etc/profile"
file_dest: "/tmp/file_output"
file_checksum: "93822124D6E66E2213C64B0D10800224"
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 USS file is successfully fetched.
returned: on successtype: strsample:
"The USS file /etc/profile is fetched successfully and saved in: /tmp/file_output/sample.ibm.com/etc/profile" "The matched contents in the USS file /etc/profile is fetched successfully and saved in: /tmp/file_output/sample.ibm.com/etc/profile.serarch" "The USS file /etc/profile is not fetched since no matched contents is found with the specified search keyword." "A range of records in the USS file /etc/profile is fetched successfully and saved in: /tmp/file_output/SY1/etc/profile.range" "A range of bytes in the USS file /etc/profile is fetched successfully and saved in: /tmp/file_output/SY1/etc/profile.range" "The USS file /etc/profile is not fetched since no contents is returned in the specified range." "The USS file /etc/profile is not fetched since it is not changed."- file_content
The retrieved contents of the USS file.
returned: on success when I(file_data_type=text)type: listsample:
["# This is a sample profile defining system wide variables. The", "# variables set here may be overridden by a user\u0027s personal .profile", "# in their $HOME directory."]- file_matched_content
The matched contents in the USS file with the specified search keyword.
returned: on success when I(file_data_type=text) and I(file_search) is specifiedtype: listsample:
["NLSPATH=/usr/lib/nls/msg/%L/%N"]- file_matched_range
The range of the matched contents of the USS file with the specified search keyword.
Return file_matched_range=p,q, where p is the first matched line in the USS file and q is the number of lines returned.
returned: on success when I(file_data_type=text) and I(file_search) is specifiedtype: strsample:
"0,500"
- file_checksum
The checksum of the fetched USS file.
returned: on success when I(file_search) and I(file_range) are not specifiedtype: strsample:
"93822124D6E66E2213C64B0D10800224"