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 thesrc
.This module is also supported for Windows targets.
Note
This module has a corresponding action plugin.
Parameters
Parameter |
Comments |
---|---|
When set to Prior to Ansible 2.5, setting this would only fail if the source file was missing. The default was changed to Choices:
|
|
Allows you to override the default behavior of appending hostname/path/to/file to the destination. If 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:
|
|
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. |
|
Verify that the source and destination checksums match after the files are fetched. Choices:
|
Attributes
Attribute |
Support |
Description |
---|---|---|
Support: full |
Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller |
|
Support: none |
Supports being used with the |
|
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 This action will not work normally outside of lockstep strategies |
|
Support: full |
Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped. |
|
Support: full |
Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode |
|
Platforms: posix, windows |
Target OS/families that can be operated against |
|
Support: none |
Uses Ansible’s strict file operation functions to ensure proper permissions and avoid data corruption |
|
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 aMemoryError
. Due to this it is advisable to run this module withoutbecome
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
orignore_errors
to get this ability. They may also explicitly setfail_on_missing
tofalse
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