Docs: Clean up of 'fetch' module docs (#46330)
* Docs: Clean up of 'fetch' module docs This is part of a series of module doc cleanups. * Fixes as suggested by review
This commit is contained in:
Dag Wieers
Alicia Cozine
parent
21d23829be
commit
12d688c006
1 changed files with 56 additions and 56 deletions
|
|
@ -1,101 +1,101 @@
|
|||
# this is a virtual module that is entirely implemented server side
|
||||
#!/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 = '''
|
||||
DOCUMENTATION = r'''
|
||||
---
|
||||
module: fetch
|
||||
short_description: Fetches a file from remote nodes
|
||||
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.
|
||||
- This module is also supported for Windows targets.
|
||||
version_added: "0.2"
|
||||
- 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.
|
||||
- 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: true
|
||||
- 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)
|
||||
required: true
|
||||
- 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).
|
||||
required: yes
|
||||
fail_on_missing:
|
||||
version_added: "1.1"
|
||||
version_added: '1.1'
|
||||
description:
|
||||
- When set to '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 "yes" in Ansible-2.5.
|
||||
- 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'
|
||||
default: yes
|
||||
validate_checksum:
|
||||
version_added: "1.4"
|
||||
version_added: '1.4'
|
||||
description:
|
||||
- Verify that the source and destination checksums match after the files are fetched.
|
||||
- Verify that the source and destination checksums match after the files are fetched.
|
||||
type: bool
|
||||
default: 'yes'
|
||||
default: yes
|
||||
flat:
|
||||
version_added: "1.2"
|
||||
version_added: '1.2'
|
||||
description:
|
||||
- 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.
|
||||
Obviously this is only handy if the filenames are unique.
|
||||
- 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.
|
||||
- Obviously this is only handy if the filenames are unique.
|
||||
type: bool
|
||||
default: 'no'
|
||||
default: no
|
||||
author:
|
||||
- "Ansible Core Team"
|
||||
- "Michael DeHaan"
|
||||
- Ansible Core Team
|
||||
- Michael DeHaan
|
||||
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 fail_on_missing was set. In Ansible-2.5+,
|
||||
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.
|
||||
- This module is also supported for Windows targets.
|
||||
- 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.
|
||||
'''
|
||||
|
||||
EXAMPLES = '''
|
||||
# Store file into /tmp/fetched/host.example.com/tmp/somefile
|
||||
- fetch:
|
||||
EXAMPLES = r'''
|
||||
- name: Store file into /tmp/fetched/host.example.com/tmp/somefile
|
||||
fetch:
|
||||
src: /tmp/somefile
|
||||
dest: /tmp/fetched
|
||||
|
||||
# Specifying a path directly
|
||||
- fetch:
|
||||
- name: Specifying a path directly
|
||||
fetch:
|
||||
src: /tmp/somefile
|
||||
dest: /tmp/prefix-{{ inventory_hostname }}
|
||||
flat: yes
|
||||
|
||||
# Specifying a destination path
|
||||
- fetch:
|
||||
- name: Specifying a destination path
|
||||
fetch:
|
||||
src: /tmp/uniquefile
|
||||
dest: /tmp/special/
|
||||
flat: yes
|
||||
|
||||
# Storing in a path relative to the playbook
|
||||
- fetch:
|
||||
- name: Storing in a path relative to the playbook
|
||||
fetch:
|
||||
src: /tmp/uniquefile
|
||||
dest: special/prefix-{{ inventory_hostname }}
|
||||
flat: yes
|
||||
|
|
|
|||
Loading…
Reference in a new issue