ansible/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2024-09-14 20:13:21 +02:00
Code Releases Activity

Docs: Clean up of 'fetch' module docs (#46330)

Browse source 
* 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 2018-10-04 05:31:31 +02:00 committed by Alicia Cozine
parent 21d23829be
commit 12d688c006
1 changed files with 56 additions and 56 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

100
lib/ansible/modules/files/fetch.py
View file

@ -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.
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
- 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.
- 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