ansible.builtin.fetch module – Fetch files from remote nodes

Note

This module is part of ansible-core and included in all Ansible installations. In most cases, you can use the short module name fetch even without specifying the collections keyword. However, we recommend you use the Fully Qualified Collection Name (FQCN) ansible.builtin.fetch for easy linking to the module documentation and to avoid conflicting with other collections that may have the same module name.

Synopsis

  • This module works like ansible.builtin.copy, but in reverse.

  • It is used for fetching files from remote machines and storing them locally in a file tree, organized by hostname.

  • Files that already exist at dest will be overwritten if they are different than the src.

  • This module is also supported for Windows targets.

Note

This module has a corresponding action plugin.

Parameters

Parameter

Comments

dest

string / required

A directory to save the file into.

For example, if the dest directory is /backup a src file named /etc/profile on host host.example.com, would be saved into /backup/host.example.com/etc/profile. The host name is based on the inventory name.

fail_on_missing

boolean

When set to true, the task will fail if the remote file cannot be read for any reason.

Prior to Ansible 2.5, setting this would only fail if the source file was missing.

The default was changed to true in Ansible 2.5.

Choices:

  • false

  • true ← (default)

flat

boolean

Allows you to override the default behavior of appending hostname/path/to/file to the destination.

If dest ends with ‘/’, it will use the basename of the source file, similar to the copy module.

This can be useful if working with a single host, or if retrieving files that are uniquely named per host.

If using multiple hosts with the same filename, the file will be overwritten for each host.

Choices:

  • false ← (default)

  • true

src

string / required

The file on the remote system to fetch.

This must be a file, not a directory.

Recursive fetching may be supported in a later release.

validate_checksum

boolean

Verify that the source and destination checksums match after the files are fetched.

Choices:

  • false

  • true ← (default)

Attributes

Attribute

Support

Description

action

Support: full

Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller

async

Support: none

Supports being used with the async keyword

bypass_host_loop

Support: none

Forces a ‘global’ task that does not execute per host, this bypasses per host templating and serial, throttle and other loop considerations

Conditionals will work as if run_once is being used, variables used will be from the first available host

This action will not work normally outside of lockstep strategies

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped.

diff_mode

Support: full

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode

platform

Platforms: posix, windows

Target OS/families that can be operated against

safe_file_operations

Support: none

Uses Ansible’s strict file operation functions to ensure proper permissions and avoid data corruption

vault

Support: none

Can automatically decrypt Ansible vaulted files

Notes

Note

  • When running fetch with become, the ansible.builtin.slurp module will also be used to fetch the contents of the file for determining the remote checksum. This effectively doubles the transfer size, and depending on the file size can consume all available memory on the remote or local hosts causing a MemoryError. Due to this it is advisable to run this module without become whenever possible.

  • Prior to Ansible 2.5 this module would not fail if reading the remote file was impossible unless fail_on_missing was set.

  • In Ansible 2.5 or later, playbook authors are encouraged to use fail_when or ignore_errors to get this ability. They may also explicitly set fail_on_missing to false to get the non-failing behaviour.

See Also

See also

ansible.builtin.copy

Copy files to remote locations.

ansible.builtin.slurp

Slurps a file from remote nodes.

Examples

- name: Store file into /tmp/fetched/host.example.com/tmp/somefile
  ansible.builtin.fetch:
    src: /tmp/somefile
    dest: /tmp/fetched

- name: Specifying a path directly
  ansible.builtin.fetch:
    src: /tmp/somefile
    dest: /tmp/prefix-{{ inventory_hostname }}
    flat: yes

- name: Specifying a destination path
  ansible.builtin.fetch:
    src: /tmp/uniquefile
    dest: /tmp/special/
    flat: yes

- name: Storing in a path relative to the playbook
  ansible.builtin.fetch:
    src: /tmp/uniquefile
    dest: special/prefix-{{ inventory_hostname }}
    flat: yes

Authors

  • Ansible Core Team

  • Michael DeHaan