'\" t
.\"     Title: ansible
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: 01/16/2017
.\"    Manual: System administration commands
.\"    Source: Ansible 2.2.1.0
.\"  Language: English
.\"
.TH "ANSIBLE" "1" "01/16/2017" "Ansible 2\&.2\&.1\&.0" "System administration commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
ansible-pull \- pull playbooks from VCS server and run them using this machine as the target\&.
.SH "SYNOPSIS"
.sp
ansible\-pull \-U URL [options] [ <filename\&.yml> ]
.SH "DESCRIPTION"
.sp
\fBAnsible\fR is an extra\-simple tool/framework/API for doing \*(Aqremote things\*(Aq\&.
.sp
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 \fBpush\fR architecture of ansible into a \fBpull\fR architecture, which has near\-limitless scaling potential\&.
.sp
The setup playbook can be tuned to change the cron frequency, logging locations, and parameters to ansible\-pull\&.
.sp
This is useful both for extreme scale\-out as well as periodic remediation\&. Usage of the \fIfetch\fR module to retrieve logs from ansible\-pull runs would be an excellent way to gather and analyze remote logs from ansible\-pull\&.
.SH "OPTIONAL ARGUMENT"
.PP
\fBfilename\&.yml\fR
.RS 4
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\(cqs fully\-qualified domain name, on the host hostname and finally a playbook named
\fBlocal\&.yml\fR\&.
.RE
.SH "OPTIONS"
.PP
\fB\-\-accept\-host\-key\fR
.RS 4
Adds the hostkey for the repo URL if not already added\&.
.RE
.PP
\fB\-b\fR, \fB\-\-become\fR
.RS 4
Use privilege escalation (specific one depends on become_method), this does not imply prompting for passwords\&.
.RE
.PP
\fB\-K\fR, \fB\-\-ask\-become\-pass\fR
.RS 4
Ask for privilege escalation password\&.
.RE
.PP
\fB\-k\fR, \fB\-\-ask\-pass\fR
.RS 4
Prompt for the connection password, if it is needed for the transport used\&. For example, using ssh and not having a key\-based authentication with ssh\-agent\&.
.RE
.PP
\fB\-\-ask\-su\-pass\fR
.RS 4
Prompt for su password, used with \-\-su (deprecated, use become)\&.
.RE
.PP
\fB\-\-ask\-sudo\-pass\fR
.RS 4
Prompt for the password to use with \-\-sudo, if any (deprecated, use become)\&.
.RE
.PP
\fB\-\-ask\-vault\-pass\fR
.RS 4
Prompt for vault password\&.
.RE
.PP
\fB\-C\fR \fICHECKOUT\fR, \fB\-\-checkout=\fR\fICHECKOUT\fR
.RS 4
Branch/Tag/Commit to checkout\&. If not provided, uses default behavior of module used to check out playbook repository\&.
.RE
.PP
\fB\-d\fR \fIDEST\fR, \fB\-\-directory=\fR\fIDEST\fR
.RS 4
Directory to checkout repository into\&. If not provided, a subdirectory of ~/\&.ansible/pull/ will be used\&.
.RE
.PP
\fB\-e\fR \fIEXTRA_VARS\fR, \fB\-\-extra\-vars=\fR\*(AqEXTRA_VARS
.RS 4
Extra variables to inject into a playbook, in key=value key=value format or as quoted YAML/JSON (hashes and arrays)\&. To load variables from a file, specify the file preceded by @ (e\&.g\&. @vars\&.yml)\&.
.RE
.PP
\fB\-f\fR, \fB\-\-force\fR
.RS 4
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\&.
.RE
.PP
\fB\-\-full\fR
.RS 4
Do a full clone of the repository\&. By default ansible\-pull will do a shallow clone based on the last revision\&.
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Show the help message and exit\&.
.RE
.PP
\fB\-i\fR \fIPATH\fR, \fB\-\-inventory=\fR\fIPATH\fR
.RS 4
The
\fIPATH\fR
to the inventory, which defaults to
\fI/etc/ansible/hosts\fR\&. Alternatively you can use a comma separated list of hosts or single host with traling comma
\fIhost,\fR\&.
.RE
.PP
\fB\-\-private\-key=\fR\fIPRIVATE_KEY_FILE\fR
.RS 4
Use this file to authenticate the connection\&.
.RE
.PP
\fB\-m\fR \fINAME\fR, \fB\-\-module\-name=\fR\fINAME\fR
.RS 4
Module used to checkout playbook repository\&. Defaults to git\&.
.RE
.PP
\fB\-o\fR, \fB\-\-only\-if\-changed\fR
.RS 4
Only run the playbook if the repository has been updated\&.
.RE
.PP
\fB\-\-purge\fR
.RS 4
Purge the checkout after the playbook is run\&.
.RE
.PP
\fB\-s\fR \fISLEEP\fR, \fB\-\-sleep=\fR\fISLEEP\fR
.RS 4
Sleep for random interval (between 0 and SLEEP number of seconds) before starting\&. This is a useful way ot disperse git requests\&.
.RE
.PP
\fB\-\-ssh\-common\-args=\fR\fI\*(Aq\-o ProxyCommand="ssh \-W %h:%p \&..." \&...\fR\*(Aq
.RS 4
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\&.
.RE
.PP
\fB\-\-sftp\-extra\-args=\fR\fI\*(Aq\-f \&...\fR\*(Aq
.RS 4
Add the specified arguments to any sftp command\-line\&.
.RE
.PP
\fB\-\-scp\-extra\-args=\fR\fI\*(Aq\-l \&...\fR\*(Aq
.RS 4
Add the specified arguments to any scp command\-line\&.
.RE
.PP
\fB\-\-ssh\-extra\-args=\fR\fI\*(Aq\-R \&...\fR\*(Aq
.RS 4
Add the specified arguments to any ssh command\-line\&.
.RE
.PP
\fB\-t\fR \fITAGS\fR, \fB\-\-tags=\fR\fITAGS\fR
.RS 4
Only run plays and tasks tagged with these values\&.
.RE
.PP
\fB\-U\fR \fIURL\fR, \fB\-\-url=\fR\fIURL\fR
.RS 4
URL of the playbook repository to checkout\&.
.RE
.PP
\fB\-\-vault\-password\-file=\fR\fIVAULT_PASSWORD_FILE\fR
.RS 4
Vault password file\&.
.RE
.PP
\fB\-\-clean\fR
.RS 4
Modified files in the working repository will be discarded\&.
.RE
.PP
\fB\-\-track\-subs\fR
.RS 4
Submodules will track the latest changes\&.
.RE
.PP
\fB\-v\fR, \fB\-\-verbose\fR
.RS 4
Pass \-vvv to ansible\-playbook\&.
.RE
.SH "INVENTORY"
.sp
Ansible stores the hosts it can potentially operate on in an inventory\&. This can be an ini\-like file, a script, directory or a list\&. The ini syntax is one host per line\&. Groups headers are allowed and are included on their own line, enclosed in square brackets that start the line\&.
.sp
Ranges of hosts are also supported\&. For more information and additional options, see the documentation on http://docs\&.ansible\&.com/\&.
.SH "ENVIRONMENT"
.sp
The following environment variables may be specified\&.
.sp
ANSIBLE_INVENTORY  \(em Override the default ansible inventory file
.sp
ANSIBLE_LIBRARY \(em Override the default ansible module library path
.sp
ANSIBLE_CONFIG \(em Override the default ansible config file
.sp
Many more are available for most options in ansible\&.cfg
.SH "FILES"
.sp
/etc/ansible/hosts \(em Default inventory file
.sp
/usr/share/ansible/ \(em Default module library
.sp
/etc/ansible/ansible\&.cfg \(em Config file, used if present
.sp
~/\&.ansible\&.cfg \(em User config file, overrides the default config if present
.SH "AUTHOR"
.sp
Ansible was originally written by Michael DeHaan\&. See the AUTHORS file for a complete list of contributors\&.
.SH "COPYRIGHT"
.sp
Copyright \(co 2012, Michael DeHaan Ansible is released under the terms of the GPLv3 License\&.
.SH "SEE ALSO"
.sp
\fBansible\fR(1) \fBansible\-playbook\fR(1), \fBansible\-doc\fR(1), \fBansible\-vault\fR(1), \fBansible\-galaxy\fR(1)
.sp
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