diff options
Diffstat (limited to 'lib/ansible/modules/fetch.py')
-rw-r--r-- | lib/ansible/modules/fetch.py | 108 |
1 files changed, 108 insertions, 0 deletions
diff --git a/lib/ansible/modules/fetch.py b/lib/ansible/modules/fetch.py new file mode 100644 index 0000000000..d87ec1274f --- /dev/null +++ b/lib/ansible/modules/fetch.py @@ -0,0 +1,108 @@ +#!/usr/bin/python +# -*- 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 + +ANSIBLE_METADATA = {'metadata_version': '1.1', + 'status': ['stableinterface'], + 'supported_by': 'core'} + +DOCUMENTATION = r''' +--- +module: fetch +short_description: Fetch files from remote nodes +description: +- This module works like M(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(yes), 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(yes) 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 +notes: +- When running fetch with C(become), the M(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(no) to get the + non-failing behaviour. +- This module is also supported for Windows targets. +seealso: +- module: copy +- module: slurp +author: +- Ansible Core Team +- Michael DeHaan +''' + +EXAMPLES = r''' +- name: Store file into /tmp/fetched/host.example.com/tmp/somefile + fetch: + src: /tmp/somefile + dest: /tmp/fetched + +- name: Specifying a path directly + fetch: + src: /tmp/somefile + dest: /tmp/prefix-{{ inventory_hostname }} + flat: yes + +- name: Specifying a destination path + fetch: + src: /tmp/uniquefile + dest: /tmp/special/ + flat: yes + +- name: Storing in a path relative to the playbook + fetch: + src: /tmp/uniquefile + dest: special/prefix-{{ inventory_hostname }} + flat: yes +''' |