ibm / ibm.ibm_zos_zosmf / 2.5.0 / module / zmf_file_fetch Fetch 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 communityibm.ibm_zos_zosmf.zmf_file_fetch (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
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 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