Try SpotterFetch USS file from z/OS
| "added in version" 2.9 of ibm.ibm_zos_zosmf"
Authors: Yang Cao (@zosmf-Young), Yun Juan Yang (@zosmf-Robyn)
preview | supported by community
Install with ansible-galaxy collection install ibm.ibm_zos_zosmf:==3.0.1
collections:
- name: ibm.ibm_zos_zosmf
version: 3.0.1Retrieve 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 I(file_dest) will be overwritten if it is different than the I(file_src).
- 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"
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
file_src:
description:
- USS file on z/OS system to fetch.
- This variable must consist of a fully qualified path and file name. For example,
C(/etc/profile).
required: true
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
file_dest:
description:
- The local directory on control node where the USS file should be saved to. For example,
C(/tmp/file_output).
- This directory can be absolute or relative. The module will fail if the parent directory
of I(file_dest) is a read-only file system.
- The directory C({{ file_dest }}/{{ zmf_host }}/) will be created to save the USS
file, where I(zmf_host) is the hostname of the z/OSMF server.
- For example, if I(zmf_host=zosmf.ibm.com), a USS file named C(/etc/profile) would
be saved into C(/tmp/file_output/zosmf.ibm.com/etc/profile).
required: true
type: str
file_flat:
default: false
description:
- Specifies whether to override the default behavior of appending hostname/path/to/file
to the destination.
- If I(file_flat=true), the USS file will be fetched to the destination directory
using its basename without appending I(zmf_host).
- For example, if I(file_dest=/tmp/file_output), a USS file named C(/etc/profile)
would be saved into C(/tmp/file_output/profile).
required: false
type: bool
file_range:
default: null
description:
- Specifies a range that is used to retrieve the USS file.
- If I(file_data_type=text), the module will retrieve a range of records (lines delimited
by '\n') from the USS file.
- If I(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 C({{ file_dest }}/{{ zmf_host
}}/{ file_src }}.range) on control node.
- For example, the retrieved range of the USS file named C(/etc/profile) would be
saved as C(....../etc/profile.range).
required: false
suboptions:
end:
description:
- If I(file_data_type=text), this variable identifies the end record in the range
to be retrieved.
- If I(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: false
type: int
start:
description:
- If I(file_data_type=text), this variable identifies the start record in the
range to be retrieved.
- If I(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: false
type: int
type: dict
file_search:
default: null
description:
- Specifies a series of parameters that are used to search the USS file.
- This variable only take effects when I(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 C({{ file_dest }}/{{ zmf_host
}}/{ file_src }}.search) on control node.
- For example, the matched contents in the USS file named C(/etc/profile) would be
saved as C(....../etc/profile.search).
required: false
suboptions:
insensitive:
default: true
description:
- Specifies whether the comparison of I(keyword) is case insensitive.
- This variable only take effects when I(keyword) is defined.
required: false
type: bool
keyword:
description:
- 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: true
type: str
maxreturnsize:
default: 100
description:
- Specifies how many lines of contents from the first matched line in the USS
file will be returned.
- This variable only take effects when I(keyword) is defined.
required: false
type: int
type: dict
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
file_checksum:
default: null
description:
- 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: false
type: str
file_encoding:
default: null
description:
- Specifies which encodings the fetched USS file should be converted from and to.
- This variable only take effects when I(file_data_type=text).
required: false
suboptions:
from:
description:
- 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: true
type: str
to:
description:
- 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: true
type: str
type: dict
file_data_type:
choices:
- text
- binary
default: text
description:
- Specifies whether data conversion is to be performed on the returned data.
- When I(file_data_type=text), data conversion is performed.
- You can use I(file_encoding) to specify which encodings the fetched USS file should
be converted from and to.
- If I(file_encoding) is not supplied, the data transfer process converts each record
from C(IBM-1047) to C(ISO8859-1) by default.
- When I(file_data_type=binary), no data conversion is performed. The data transfer
process returns each line of data as-is, without translation.
required: false
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
changed:
description: Indicates if any change is made during the module operation.
returned: always
type: bool
file_checksum:
description: The checksum of the fetched USS file.
returned: on success when I(file_search) and I(file_range) are not specified
sample: 93822124D6E66E2213C64B0D10800224
type: str
file_content:
description: The retrieved contents of the USS file.
returned: on success when I(file_data_type=text)
sample:
- '# This is a sample profile defining system wide variables. The'
- '# variables set here may be overridden by a user''s personal .profile'
- '# in their $HOME directory.'
type: list
file_matched_content:
description: 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 specified
sample:
- NLSPATH=/usr/lib/nls/msg/%L/%N
type: list
file_matched_range:
description:
- The range of the matched contents of the USS file with the specified search keyword.
- Return I(file_matched_range=p,q), where I(p) is the first matched line in the
USS file and I(q) is the number of lines returned.
returned: on success when I(file_data_type=text) and I(file_search) is specified
sample: 0,500
type: str
message:
description: The output message generated by the module to indicate whether the
USS file is successfully fetched.
returned: on success
sample:
sample1: 'The USS file /etc/profile is fetched successfully and saved in: /tmp/file_output/sample.ibm.com/etc/profile'
sample2: 'The matched contents in the USS file /etc/profile is fetched successfully
and saved in: /tmp/file_output/sample.ibm.com/etc/profile.serarch'
sample3: The USS file /etc/profile is not fetched since no matched contents is
found with the specified search keyword.
sample4: 'A range of records in the USS file /etc/profile is fetched successfully
and saved in: /tmp/file_output/SY1/etc/profile.range'
sample5: 'A range of bytes in the USS file /etc/profile is fetched successfully
and saved in: /tmp/file_output/SY1/etc/profile.range'
sample6: The USS file /etc/profile is not fetched since no contents is returned
in the specified range.
sample7: The USS file /etc/profile is not fetched since it is not changed.
type: str