# this is a virtual module that is entirely implemented server side

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,
       organized by hostname. Note that this module was originally written to
       transfer log files that were not necessarily present, therefore, by
       default, if the source file is missing, it does not fail ; 
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
    default: null
    aliases: []
  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
    default: null
  fail_on_missing:
    description:
      - Makes it fails when the source file is missing.
    required: false
    choices: [ "yes", "no" ]
    default: "no"
examples:
   - code: "fetch: src=/var/log/messages dest=/home/logtree"
     description: "Example from Ansible Playbooks"
requirements: []
author: Michael DeHaan
'''