fetch 2.06 KB
Newer Older
1
# this is a virtual module that is entirely implemented server side
2 3 4 5 6 7 8 9

DOCUMENTATION = '''
---
module: fetch
short_description: Fetches a file 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,
James Martin committed
10
       organized by hostname. Note that this module is written to transfer
11 12
       log files that might not be present, so a missing remote file won't
       be an error unless fail_on_missing is set to 'yes'.
13 14 15 16
version_added: "0.2"
options:
  src:
    description:
Jan-Piet Mens committed
17
      - The file on the remote system to fetch. This I(must) be a file, not a
18 19 20 21 22 23 24
        directory. Recursive fetching may be supported in a later release.
    required: true
    default: null
    aliases: []
  dest:
    description:
      - A directory to save the file into. For example, if the I(dest)
Jan-Piet Mens committed
25
        directory is C(/backup) a I(src) file named C(/etc/profile) on host
26 27 28 29
        C(host.example.com), would be saved into
        C(/backup/host.example.com/etc/profile)
    required: true
    default: null
30
  fail_on_missing:
31
    version_added: "1.1"
32
    description:
33
      - Makes it fails when the source file is missing.
34 35 36
    required: false
    choices: [ "yes", "no" ]
    default: "no"
James Martin committed
37 38 39 40 41
  flat:
    version_added: "1.2"
    description:
      Allows you to override the default behavior of prepending hostname/path/to/file to
      the destination.  If dest ends with '/', it will use the basename of the source
Ben Podoll committed
42
      file, similar to the copy module.  Obviously this is only handy if the filenames
James Martin committed
43
      are unqiue.
44 45 46
requirements: []
author: Michael DeHaan
'''
47 48 49

EXAMPLES = '''
# Store file into /tmp/fetched/host.example.com/tmp/somefile
50
- fetch: src=/tmp/somefile dest=/tmp/fetched
51 52

# Specifying a path directly
53
- fetch: src=/tmp/somefile dest=/tmp/prefix-{{ ansible_hostname }} flat=yes
54 55

# Specifying a destination path
56
- fetch: src=/tmp/uniquefile dest=/tmp/special/ flat=yes
57 58

# Storing in a path relative to the playbook
59
- fetch: src=/tmp/uniquefile dest=special/prefix-{{ ansible_hostname }} flat=yes
60
'''