path: root/docs/man/man1/ansible-pull.1

.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "ANSIBLE-PULL" 1 "" "Ansible 2.14.3" "System administration commands"
.SH NAME
ansible-pull \- pulls playbooks from a VCS repo and executes them for the local host
.SH SYNOPSIS
.INDENT 0.0
.TP
.B usage: ansible\-pull [\-h] [\-\-version] [\-v] [\-\-private\-key PRIVATE_KEY_FILE]
[\-u REMOTE_USER] [\-c CONNECTION] [\-T TIMEOUT]
[\-\-ssh\-common\-args SSH_COMMON_ARGS]
[\-\-sftp\-extra\-args SFTP_EXTRA_ARGS]
[\-\-scp\-extra\-args SCP_EXTRA_ARGS]
[\-\-ssh\-extra\-args SSH_EXTRA_ARGS]
[\-k | \-\-connection\-password\-file CONNECTION_PASSWORD_FILE]
[\-\-vault\-id VAULT_IDS]
[\-\-ask\-vault\-password | \-\-vault\-password\-file VAULT_PASSWORD_FILES]
[\-e EXTRA_VARS] [\-t TAGS] [\-\-skip\-tags SKIP_TAGS]
[\-i INVENTORY] [\-\-list\-hosts] [\-l SUBSET] [\-M MODULE_PATH]
[\-K | \-\-become\-password\-file BECOME_PASSWORD_FILE]
[\-\-purge] [\-o] [\-s SLEEP] [\-f] [\-d DEST] [\-U URL] [\-\-full]
[\-C CHECKOUT] [\-\-accept\-host\-key] [\-m MODULE_NAME]
[\-\-verify\-commit] [\-\-clean] [\-\-track\-subs] [\-\-check]
[\-\-diff]
[playbook.yml ...]
.UNINDENT
.SH DESCRIPTION
.sp
Used to pull 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 \fIpush\fP architecture of ansible into a \fIpull\fP
architecture,
which has near\-limitless scaling potential.
.sp
None of the CLI tools are designed to run concurrently with themselves,
you should use an external scheduler and/or locking to ensure there are no
clashing operations.
.sp
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 \(aqfetch\(aq module to retrieve logs from ansible\-pull runs would be an
excellent way to gather and analyze remote logs from ansible\-pull.
.SH COMMON OPTIONS
.INDENT 0.0
.INDENT 3.5
Playbook(s)
.UNINDENT
.UNINDENT
.sp
\fB\-\-accept\-host\-key\fP
.INDENT 0.0
.INDENT 3.5
adds the hostkey for the repo url if not already added
.UNINDENT
.UNINDENT
.sp
\fB\-\-ask\-vault\-password\fP, \fB\-\-ask\-vault\-pass\fP
.INDENT 0.0
.INDENT 3.5
ask for vault password
.UNINDENT
.UNINDENT
.sp
\fB\-\-become\-password\-file\fP \(aqBECOME_PASSWORD_FILE\(aq, \fB\-\-become\-pass\-file\fP \(aqBECOME_PASSWORD_FILE\(aq
.INDENT 0.0
.INDENT 3.5
Become password file
.UNINDENT
.UNINDENT
.sp
\fB\-\-check\fP
.INDENT 0.0
.INDENT 3.5
don\(aqt make any changes; instead, try to predict some of the changes that may occur
.UNINDENT
.UNINDENT
.sp
\fB\-\-clean\fP
.INDENT 0.0
.INDENT 3.5
modified files in the working repository will be discarded
.UNINDENT
.UNINDENT
.sp
\fB\-\-connection\-password\-file\fP \(aqCONNECTION_PASSWORD_FILE\(aq, \fB\-\-conn\-pass\-file\fP \(aqCONNECTION_PASSWORD_FILE\(aq
.INDENT 0.0
.INDENT 3.5
Connection password file
.UNINDENT
.UNINDENT
.sp
\fB\-\-diff\fP
.INDENT 0.0
.INDENT 3.5
when changing (small) files and templates, show the differences in those files; works great with \-\-check
.UNINDENT
.UNINDENT
.sp
\fB\-\-full\fP
.INDENT 0.0
.INDENT 3.5
Do a full clone, instead of a shallow one.
.UNINDENT
.UNINDENT
.sp
\fB\-\-list\-hosts\fP
.INDENT 0.0
.INDENT 3.5
outputs a list of matching hosts; does not execute anything else
.UNINDENT
.UNINDENT
.sp
\fB\-\-private\-key\fP \(aqPRIVATE_KEY_FILE\(aq, \fB\-\-key\-file\fP \(aqPRIVATE_KEY_FILE\(aq
.INDENT 0.0
.INDENT 3.5
use this file to authenticate the connection
.UNINDENT
.UNINDENT
.sp
\fB\-\-purge\fP
.INDENT 0.0
.INDENT 3.5
purge checkout after playbook run
.UNINDENT
.UNINDENT
.sp
\fB\-\-scp\-extra\-args\fP \(aqSCP_EXTRA_ARGS\(aq
.INDENT 0.0
.INDENT 3.5
specify extra arguments to pass to scp only (e.g. \-l)
.UNINDENT
.UNINDENT
.sp
\fB\-\-sftp\-extra\-args\fP \(aqSFTP_EXTRA_ARGS\(aq
.INDENT 0.0
.INDENT 3.5
specify extra arguments to pass to sftp only (e.g. \-f, \-l)
.UNINDENT
.UNINDENT
.sp
\fB\-\-skip\-tags\fP
.INDENT 0.0
.INDENT 3.5
only run plays and tasks whose tags do not match these values
.UNINDENT
.UNINDENT
.sp
\fB\-\-ssh\-common\-args\fP \(aqSSH_COMMON_ARGS\(aq
.INDENT 0.0
.INDENT 3.5
specify common arguments to pass to sftp/scp/ssh (e.g. ProxyCommand)
.UNINDENT
.UNINDENT
.sp
\fB\-\-ssh\-extra\-args\fP \(aqSSH_EXTRA_ARGS\(aq
.INDENT 0.0
.INDENT 3.5
specify extra arguments to pass to ssh only (e.g. \-R)
.UNINDENT
.UNINDENT
.sp
\fB\-\-track\-subs\fP
.INDENT 0.0
.INDENT 3.5
submodules will track the latest changes. This is equivalent to specifying the \-\-remote flag to git submodule update
.UNINDENT
.UNINDENT
.sp
\fB\-\-vault\-id\fP
.INDENT 0.0
.INDENT 3.5
the vault identity to use
.UNINDENT
.UNINDENT
.sp
\fB\-\-vault\-password\-file\fP, \fB\-\-vault\-pass\-file\fP
.INDENT 0.0
.INDENT 3.5
vault password file
.UNINDENT
.UNINDENT
.sp
\fB\-\-verify\-commit\fP
.INDENT 0.0
.INDENT 3.5
verify GPG signature of checked out commit, if it fails abort running the playbook. This needs the corresponding VCS module to support such an operation
.UNINDENT
.UNINDENT
.sp
\fB\-\-version\fP
.INDENT 0.0
.INDENT 3.5
show program\(aqs version number, config file location, configured module search path, module location, executable location and exit
.UNINDENT
.UNINDENT
.sp
\fB\-C\fP \(aqCHECKOUT\(aq, \fB\-\-checkout\fP \(aqCHECKOUT\(aq
.INDENT 0.0
.INDENT 3.5
branch/tag/commit to checkout. Defaults to behavior of repository module.
.UNINDENT
.UNINDENT
.sp
\fB\-K\fP, \fB\-\-ask\-become\-pass\fP
.INDENT 0.0
.INDENT 3.5
ask for privilege escalation password
.UNINDENT
.UNINDENT
.sp
\fB\-M\fP, \fB\-\-module\-path\fP
.INDENT 0.0
.INDENT 3.5
prepend colon\-separated path(s) to module library (default={{ ANSIBLE_HOME ~ \(dq/plugins/modules:/usr/share/ansible/plugins/modules\(dq }})
.UNINDENT
.UNINDENT
.sp
\fB\-T\fP \(aqTIMEOUT\(aq, \fB\-\-timeout\fP \(aqTIMEOUT\(aq
.INDENT 0.0
.INDENT 3.5
override the connection timeout in seconds (default=10)
.UNINDENT
.UNINDENT
.sp
\fB\-U\fP \(aqURL\(aq, \fB\-\-url\fP \(aqURL\(aq
.INDENT 0.0
.INDENT 3.5
URL of the playbook repository
.UNINDENT
.UNINDENT
.sp
\fB\-c\fP \(aqCONNECTION\(aq, \fB\-\-connection\fP \(aqCONNECTION\(aq
.INDENT 0.0
.INDENT 3.5
connection type to use (default=smart)
.UNINDENT
.UNINDENT
.sp
\fB\-d\fP \(aqDEST\(aq, \fB\-\-directory\fP \(aqDEST\(aq
.INDENT 0.0
.INDENT 3.5
absolute path of repository checkout directory (relative paths are not supported)
.UNINDENT
.UNINDENT
.sp
\fB\-e\fP, \fB\-\-extra\-vars\fP
.INDENT 0.0
.INDENT 3.5
set additional variables as key=value or YAML/JSON, if filename prepend with @
.UNINDENT
.UNINDENT
.sp
\fB\-f\fP, \fB\-\-force\fP
.INDENT 0.0
.INDENT 3.5
run the playbook even if the repository could not be updated
.UNINDENT
.UNINDENT
.sp
\fB\-h\fP, \fB\-\-help\fP
.INDENT 0.0
.INDENT 3.5
show this help message and exit
.UNINDENT
.UNINDENT
.sp
\fB\-i\fP, \fB\-\-inventory\fP, \fB\-\-inventory\-file\fP
.INDENT 0.0
.INDENT 3.5
specify inventory host path or comma separated host list. \-\-inventory\-file is deprecated
.UNINDENT
.UNINDENT
.sp
\fB\-k\fP, \fB\-\-ask\-pass\fP
.INDENT 0.0
.INDENT 3.5
ask for connection password
.UNINDENT
.UNINDENT
.sp
\fB\-l\fP \(aqSUBSET\(aq, \fB\-\-limit\fP \(aqSUBSET\(aq
.INDENT 0.0
.INDENT 3.5
further limit selected hosts to an additional pattern
.UNINDENT
.UNINDENT
.sp
\fB\-m\fP \(aqMODULE_NAME\(aq, \fB\-\-module\-name\fP \(aqMODULE_NAME\(aq
.INDENT 0.0
.INDENT 3.5
Repository module name, which ansible will use to check out the repo. Choices are (\(aqgit\(aq, \(aqsubversion\(aq, \(aqhg\(aq, \(aqbzr\(aq). Default is git.
.UNINDENT
.UNINDENT
.sp
\fB\-o\fP, \fB\-\-only\-if\-changed\fP
.INDENT 0.0
.INDENT 3.5
only run the playbook if the repository has been updated
.UNINDENT
.UNINDENT
.sp
\fB\-s\fP \(aqSLEEP\(aq, \fB\-\-sleep\fP \(aqSLEEP\(aq
.INDENT 0.0
.INDENT 3.5
sleep for random interval (between 0 and n number of seconds) before starting. This is a useful way to disperse git requests
.UNINDENT
.UNINDENT
.sp
\fB\-t\fP, \fB\-\-tags\fP
.INDENT 0.0
.INDENT 3.5
only run plays and tasks tagged with these values
.UNINDENT
.UNINDENT
.sp
\fB\-u\fP \(aqREMOTE_USER\(aq, \fB\-\-user\fP \(aqREMOTE_USER\(aq
.INDENT 0.0
.INDENT 3.5
connect as this user (default=None)
.UNINDENT
.UNINDENT
.sp
\fB\-v\fP, \fB\-\-verbose\fP
.INDENT 0.0
.INDENT 3.5
Causes Ansible to print more debug messages. Adding multiple \-v will increase the verbosity, the builtin plugins currently evaluate up to \-vvvvvv. A reasonable level to start is \-vvv, connection debugging might require \-vvvv.
.UNINDENT
.UNINDENT
.SH ENVIRONMENT
.sp
The following environment variables may be specified.
.sp
ANSIBLE_CONFIG \-\- Specify override location for the ansible config file
.sp
Many more are available for most options in ansible.cfg
.sp
For a full list check \fI\%https://docs.ansible.com/\fP\&. or use the \fIansible\-config\fP command.
.SH FILES
.sp
/etc/ansible/ansible.cfg \-\- Config file, used if present
.sp
~/.ansible.cfg \-\- User config file, overrides the default config if present
.sp
\&./ansible.cfg \-\- Local config file (in current working directory) assumed to be \(aqproject specific\(aq and overrides the rest if present.
.sp
As mentioned above, the ANSIBLE_CONFIG environment variable will override all others.
.SH AUTHOR
.sp
Ansible was originally written by Michael DeHaan.
.SH COPYRIGHT
.sp
Copyright © 2018 Red Hat, Inc | Ansible.
Ansible is released under the terms of the GPLv3 license.
.SH SEE ALSO
.sp
\fBansible\fP (1), \fBansible\-config\fP (1), \fBansible\-console\fP (1), \fBansible\-doc\fP (1), \fBansible\-galaxy\fP (1), \fBansible\-inventory\fP (1), \fBansible\-playbook\fP (1), \fBansible\-vault\fP (1)
.sp
Extensive documentation is available in the documentation site:
<\fI\%https://docs.ansible.com\fP>.
IRC and mailing list info can be found in file CONTRIBUTING.md,
available in: <\fI\%https://github.com/ansible/ansible\fP>
.\" Generated by docutils manpage writer.
.