bigip_ucs_fetch – Fetches a UCS file from remote nodes

New in version 1.0.0.

Synopsis

  • This module is used for fetching UCS files from remote machines and storing them locally in a file tree, organized by hostname. Note that this module is written to transfer UCS files that might not be present, so a missing remote UCS won’t be an error unless fail_on_missing is set to ‘yes’.

Parameters

Parameter Choices/Defaults Configuration Comments
backup
boolean
    Choices:
  • no ←
  • yes
Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly.
create_on_missing
boolean
    Choices:
  • no
  • yes ←
Creates the UCS based on the value of src if the file does not already exist on the remote system.
dest
path / required
A directory to save the UCS file into.
encryption_password
string
Password to use to encrypt the UCS file if desired.
fail_on_missing
boolean
    Choices:
  • no ←
  • yes
Make the module fail if the UCS file on the remote system is missing.
force
boolean
    Choices:
  • no
  • yes ←
If no, the file will only be transferred if the destination does not exist.
src
string
The name of the UCS file to create on the remote server for downloading.
If not given the name will be randomly generated when creating UCS file on device.
The parameter is required when task_id is defined otherwise file download will fail.
task_id
string
The ID of the async task as returned by the system in a previous module run.
Used to query the status of the task on the device, useful with longer running operations that require restarting services.
timeout
integer
Default:
150
Parameter used when creating s new UCS file on the device.
The amount of time in seconds to wait for the API async interface to complete its task.
The accepted value range is between 150 and 1800 seconds.

Notes

Note

  • BIG-IP provides no way to get a checksum of the UCS files on the system via any interface except, perhaps, logging in directly to the box (which would not support appliance mode). Therefore, the best this module can do is check for the existence of the file on disk; no check-summing.
  • If you are using this module with either Ansible Tower or Ansible AWX, you should be aware of how these Ansible products execute jobs in restricted environments. More information can be found here https://clouddocs.f5.com/products/orchestration/ansible/devel/usage/module-usage-with-tower.html
  • Some longer running tasks might cause the REST interface on BIG-IP to time out, to avoid this adjust the timers as per this KB article https://support.f5.com/csp/article/K94602685

Examples

- hosts: all
  collections:
    - f5networks.f5_bigip
  connection: httpapi

  vars:
    ansible_host: "lb.mydomain.com"
    ansible_user: "admin"
    ansible_httpapi_password: "secret"
    ansible_network_os: f5networks.f5_bigip.bigip
    ansible_httpapi_use_ssl: yes

  tasks:
    - name: Create a new UCS
      bigip_ucs_fetch:
        dest: /tmp/cs_backup.ucs
      register: task

    - name: Check for task completion and download created UCS
      bigip_ucs_fetch:
        dest: /tmp/cs_backup.ucs
        src: "{{ task.src }}"
        task_id: "{{ task.task_id }}"
        timeout: 300

    - name: Download an existing UCS
      bigip_ucs_fetch:
        src: cs_backup.ucs
        dest: /tmp/cs_backup.ucs

Return Values

The following are the fields unique to this module:

Key Returned Description
backup_file
string
changed and if backup=yes
Name of backup file created

Sample:
/path/to/file.txt.2015-02-12@22:09~
checksum
string
success or changed
The SHA1 checksum of the downloaded file

Sample:
7b46bbe4f8ebfee64761b5313855618f64c64109
dest
string
success
Location on the ansible host that the UCS was saved to

Sample:
/path/to/file.txt
gid
integer
success
Group id of the UCS file, after execution

Sample:
100
group
string
success
Group of the UCS file, after execution

Sample:
httpd
md5sum
string
changed or success
The MD5 checksum of the downloaded file

Sample:
96cacab4c259c4598727d7cf2ceb3b45
message
dictionary
changed
Informative message of the task status.

Sample:
Import success
mode
string
success
Permissions of the target UCS, after execution

Sample:
420
owner
string
success
Owner of the UCS file, after execution

Sample:
httpd
size
integer
success
Size of the target UCS, after execution

Sample:
1220
src
string
changed
Name of the UCS file on the remote BIG-IP to download. If not specified, then this will be a randomly generated filename

Sample:
cs_backup.ucs
task_id
dictionary
changed
The task ID returned by the system.

Sample:
hash/dictionary of values
uid
integer
success
Owner id of the UCS file, after execution

Sample:
100


Status

Authors

  • Wojciech Wypior (@wojtek0806)