ansible/docs/man/man1/ansible-pull.1.asciidoc.in

ansible(1)
=========
:doctype:manpage
:man source:   Ansible
:man version:  %VERSION%
:man manual:   System administration commands

NAME
----
ansible-pull - set up a remote copy of ansible on each managed node


SYNOPSIS
--------
ansible-pull -d DEST -U URL [options] [ <filename.yml> ]


DESCRIPTION
-----------

*Ansible* is an extra-simple tool/framework/API for doing \'remote things' over
SSH.

Use ansible-pull to set up a remote copy of ansible on each managed
node, each set to run via cron and update playbook source via
a source repository. This inverts the default *push* architecture of
ansible into a *pull* architecture, which has near-limitless scaling
potential.

The setup playbook can be tuned to change the cron frequency, logging
locations, and parameters to ansible-pull.

This is useful both for extreme scale-out as well as periodic
remediation. Usage of the 'fetch' module to retrieve logs from
ansible-pull runs would be an excellent way to gather and analyze
remote logs from ansible-pull.


OPTIONAL ARGUMENT
-----------------

*filename.yml*::

The name of one the YAML format files to run as an ansible playbook.  This can
be a relative path within the checkout.  If not provided, ansible-pull
will look for a playbook based on the host's fully-qualified domain name, on the
host hostname and finally a playbook named *local.yml*.


OPTIONS
-------

*--accept-host-key*::

Adds the hostkey for the repo URL if not already added.

*-K*, *--ask-sudo-pass*::

Ask for sudo password.
 
*-C* 'CHECKOUT', *--checkout=*'CHECKOUT'::

Branch/Tag/Commit to checkout.  If not provided, uses default behavior of module used to check out playbook repository.

*-d* 'DEST', *--directory=*'DEST'::

Directory to checkout repository into. If not provided, a subdirectory of
~/.ansible/pull/ will be used.

*-e* 'EXTRA_VARS', *--extra-vars=*'EXTRA_VARS*::

Set additional variables as key=value or YAML/JSON

*-f*, *--force*::

Force running of playbook even if unable to update playbook repository.  This
can be useful, for example, to enforce run-time state when a network
connection may not always be up or possible.

*-h*, *--help*::

Show the help message and exit.

*-i* 'PATH', *--inventory=*'PATH'::

The 'PATH' to the inventory hosts file.  This can be a relative path within the checkout.

*--key-file=*'KEYFILE'::

Pass '-i <key_file>' to the SSH arguments used by git.

*-m* 'NAME', *--module-name=*'NAME'::

Module used to checkout playbook repository.  Defaults to git.

*-o*, *--only-if-changed*::

Only run the playbook if the repository has been updated.

*--purge*::

Purge the checkout after the playbook is run.

*-s* 'SLEEP', *--sleep=*'SLEEP'::

Sleep for random interval (between 0 and SLEEP number of seconds) before starting.  This is a useful way ot disperse git requests.

*--ssh-common-args=*''-o ProxyCommand="ssh -W %h:%p ..." ...''::

Add the specified arguments to any sftp/scp/ssh command-line. Useful to
set a ProxyCommand to use a jump host, but any arguments that are
accepted by all three programs may be specified.

*--sftp-extra-args=*''-f ...''::

Add the specified arguments to any sftp command-line.

*--scp-extra-args=*''-l ...''::

Add the specified arguments to any scp command-line.

*--ssh-extra-args=*''-R ...''::

Add the specified arguments to any ssh command-line.

*-t* 'TAGS', *--tags=*'TAGS'::

Only run plays and tasks tagged with these values.

*-U* 'URL', *--url=*'URL'::

URL of the playbook repository to checkout.

*--vault-password-file=*'VAULT_PASSWORD_FILE'::

Vault password file.

*-v*, *--verbose*::

Pass -vvv to ansible-playbook.


AUTHOR
------

Ansible was originally written by Michael DeHaan. See the AUTHORS file
for a complete list of contributors.


COPYRIGHT
---------

Copyright © 2012, Michael DeHaan

Ansible is released under the terms of the GPLv3 License.


SEE ALSO
--------

*ansible*(1), *ansible-playbook*(1), *ansible-doc*(1)

Extensive documentation is available in the documentation site:
<http://docs.ansible.com>. IRC and mailing list info can be found
in file CONTRIBUTING.md, available in: <https://github.com/ansible/ansible>