diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-28 16:04:21 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-28 16:04:21 +0000 |
commit | 8a754e0858d922e955e71b253c139e071ecec432 (patch) | |
tree | 527d16e74bfd1840c85efd675fdecad056c54107 /lib/ansible/modules/fetch.py | |
parent | Initial commit. (diff) | |
download | ansible-core-upstream/2.14.3.tar.xz ansible-core-upstream/2.14.3.zip |
Adding upstream version 2.14.3.upstream/2.14.3upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r-- | lib/ansible/modules/fetch.py | 124 |
1 files changed, 124 insertions, 0 deletions
diff --git a/lib/ansible/modules/fetch.py b/lib/ansible/modules/fetch.py new file mode 100644 index 0000000..646f78d --- /dev/null +++ b/lib/ansible/modules/fetch.py @@ -0,0 +1,124 @@ +# -*- coding: utf-8 -*- + +# Copyright: (c) 2017, Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +# This is a virtual module that is entirely implemented as an action plugin and runs on the controller + +from __future__ import absolute_import, division, print_function +__metaclass__ = type + + +DOCUMENTATION = r''' +--- +module: fetch +short_description: Fetch files from remote nodes +description: +- This module works like M(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 I(dest) will be overwritten if they are different than the I(src). +- This module is also supported for Windows targets. +version_added: '0.2' +options: + src: + description: + - The file on the remote system to fetch. + - This I(must) be a file, not a directory. + - Recursive fetching may be supported in a later release. + required: yes + dest: + description: + - A directory to save the file into. + - For example, if the I(dest) directory is C(/backup) a I(src) file named C(/etc/profile) on host + C(host.example.com), would be saved into C(/backup/host.example.com/etc/profile). + The host name is based on the inventory name. + required: yes + fail_on_missing: + version_added: '1.1' + description: + - When set to C(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 C(true) in Ansible 2.5. + type: bool + default: yes + validate_checksum: + version_added: '1.4' + description: + - Verify that the source and destination checksums match after the files are fetched. + type: bool + default: yes + flat: + version_added: '1.2' + description: + - Allows you to override the default behavior of appending hostname/path/to/file to the destination. + - If C(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. + type: bool + default: no +extends_documentation_fragment: + - action_common_attributes + - action_common_attributes.files + - action_common_attributes.flow +attributes: + action: + support: full + async: + support: none + bypass_host_loop: + support: none + check_mode: + support: full + diff_mode: + support: full + platform: + platforms: posix, windows + safe_file_operations: + support: none + vault: + support: none +notes: +- When running fetch with C(become), the M(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 C(MemoryError). Due to this it is + advisable to run this module without C(become) whenever possible. +- Prior to Ansible 2.5 this module would not fail if reading the remote + file was impossible unless C(fail_on_missing) was set. +- In Ansible 2.5 or later, playbook authors are encouraged to use + C(fail_when) or C(ignore_errors) to get this ability. They may + also explicitly set C(fail_on_missing) to C(false) to get the + non-failing behaviour. +seealso: +- module: ansible.builtin.copy +- module: ansible.builtin.slurp +author: +- Ansible Core Team +- Michael DeHaan +''' + +EXAMPLES = r''' +- 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 +''' |