ansible-pull(1)

1ANSIBLE-PULL(1)         System administration commands         ANSIBLE-PULL(1)
2
3
4

NAME

6       ansible-pull  -  pulls  playbooks from a VCS repo and executes them for
7       the local host
8

SYNOPSIS

10       usage:  ansible-pull  [-h]   [--version]   [-v]   [--private-key   PRI‐
11       VATE_KEY_FILE]
12              [-u REMOTE_USER] [-c CONNECTION] [-T TIMEOUT] [--ssh-common-args
13              SSH_COMMON_ARGS] [--sftp-extra-args SFTP_EXTRA_ARGS]  [--scp-ex‐
14              tra-args SCP_EXTRA_ARGS] [--ssh-extra-args SSH_EXTRA_ARGS] [-k |
15              --connection-password-file CONNECTION_PASSWORD_FILE] [--vault-id
16              VAULT_IDS]    [--ask-vault-password    |   --vault-password-file
17              VAULT_PASSWORD_FILES] [-e  EXTRA_VARS]  [-t  TAGS]  [--skip-tags
18              SKIP_TAGS]  [-i  INVENTORY]  [--list-hosts] [-l SUBSET] [-M MOD‐
19              ULE_PATH]  [-K  |  --become-password-file  BECOME_PASSWORD_FILE]
20              [--purge]  [-o]  [-s SLEEP] [-f] [-d DEST] [-U URL] [--full] [-C
21              CHECKOUT] [--accept-host-key] [-m MODULE_NAME] [--verify-commit]
22              [--clean] [--track-subs] [--check] [--diff] [playbook.yml ...]
23

DESCRIPTION

25       Used to pull a remote copy of ansible on each managed node, each set to
26       run via cron and update playbook source via a source repository.   This
27       inverts  the default push architecture of ansible into a pull architec‐
28       ture, which has near-limitless scaling potential.
29
30       None of the CLI tools are designed to run concurrently with themselves,
31       you should use an external scheduler and/or locking to ensure there are
32       no clashing operations.
33
34       The setup playbook can be tuned to change the cron  frequency,  logging
35       locations, and parameters to ansible-pull.  This is useful both for ex‐
36       treme scale-out as well as periodic remediation.  Usage of the  'fetch'
37       module  to  retrieve  logs from ansible-pull runs would be an excellent
38       way to gather and analyze remote logs from ansible-pull.
39

COMMON OPTIONS

41          Playbook(s)
42
43       --accept-host-key
44          adds the hostkey for the repo url if not already added
45
46       --ask-vault-password, --ask-vault-pass
47          ask for vault password
48
49       --become-password-file 'BECOME_PASSWORD_FILE', --become-pass-file  'BE‐
50       COME_PASSWORD_FILE'
51          Become password file
52
53       --check
54          don't  make any changes; instead, try to predict some of the changes
55          that may occur
56
57       --clean
58          modified files in the working repository will be discarded
59
60       --connection-password-file 'CONNECTION_PASSWORD_FILE', --conn-pass-file
61       'CONNECTION_PASSWORD_FILE'
62          Connection password file
63
64       --diff
65          when  changing  (small) files and templates, show the differences in
66          those files; works great with --check
67
68       --full
69          Do a full clone, instead of a shallow one.
70
71       --list-hosts
72          outputs a list of matching hosts; does not execute anything else
73
74       --private-key 'PRIVATE_KEY_FILE', --key-file 'PRIVATE_KEY_FILE'
75          use this file to authenticate the connection
76
77       --purge
78          purge checkout after playbook run
79
80       --scp-extra-args 'SCP_EXTRA_ARGS'
81          specify extra arguments to pass to scp only (e.g. -l)
82
83       --sftp-extra-args 'SFTP_EXTRA_ARGS'
84          specify extra arguments to pass to sftp only (e.g. -f, -l)
85
86       --skip-tags
87          only run plays and tasks whose tags do not match these values
88
89       --ssh-common-args 'SSH_COMMON_ARGS'
90          specify common arguments to pass to sftp/scp/ssh (e.g. ProxyCommand)
91
92       --ssh-extra-args 'SSH_EXTRA_ARGS'
93          specify extra arguments to pass to ssh only (e.g. -R)
94
95       --track-subs
96          submodules will track the latest  changes.  This  is  equivalent  to
97          specifying the --remote flag to git submodule update
98
99       --vault-id
100          the vault identity to use
101
102       --vault-password-file, --vault-pass-file
103          vault password file
104
105       --verify-commit
106          verify  GPG  signature of checked out commit, if it fails abort run‐
107          ning the playbook. This needs the corresponding VCS module  to  sup‐
108          port such an operation
109
110       --version
111          show program's version number, config file location, configured mod‐
112          ule search path, module location, executable location and exit
113
114       -C 'CHECKOUT', --checkout 'CHECKOUT'
115          branch/tag/commit to checkout. Defaults to  behavior  of  repository
116          module.
117
118       -K, --ask-become-pass
119          ask for privilege escalation password
120
121       -M, --module-path
122          prepend  colon-separated path(s) to module library (default={{ ANSI‐
123          BLE_HOME ~ "/plugins/modules:/usr/share/ansible/plugins/modules" }})
124
125       -T 'TIMEOUT', --timeout 'TIMEOUT'
126          override the connection timeout in seconds (default=10)
127
128       -U 'URL', --url 'URL'
129          URL of the playbook repository
130
131       -c 'CONNECTION', --connection 'CONNECTION'
132          connection type to use (default=smart)
133
134       -d 'DEST', --directory 'DEST'
135          absolute path of repository checkout directory (relative  paths  are
136          not supported)
137
138       -e, --extra-vars
139          set  additional  variables  as  key=value  or YAML/JSON, if filename
140          prepend with @
141
142       -f, --force
143          run the playbook even if the repository could not be updated
144
145       -h, --help
146          show this help message and exit
147
148       -i, --inventory, --inventory-file
149          specify inventory host path or comma separated host  list.  --inven‐
150          tory-file is deprecated
151
152       -k, --ask-pass
153          ask for connection password
154
155       -l 'SUBSET', --limit 'SUBSET'
156          further limit selected hosts to an additional pattern
157
158       -m 'MODULE_NAME', --module-name 'MODULE_NAME'
159          Repository  module  name,  which  ansible  will use to check out the
160          repo. Choices are ('git', 'subversion',  'hg',  'bzr').  Default  is
161          git.
162
163       -o, --only-if-changed
164          only run the playbook if the repository has been updated
165
166       -s 'SLEEP', --sleep 'SLEEP'
167          sleep for random interval (between 0 and n number of seconds) before
168          starting. This is a useful way to disperse git requests
169
170       -t, --tags
171          only run plays and tasks tagged with these values
172
173       -u 'REMOTE_USER', --user 'REMOTE_USER'
174          connect as this user (default=None)
175
176       -v, --verbose
177          Causes Ansible to print more debug messages. Adding multiple -v will
178          increase the verbosity, the builtin plugins currently evaluate up to
179          -vvvvvv. A reasonable level to start is -vvv,  connection  debugging
180          might require -vvvv.
181

ENVIRONMENT

183       The following environment variables may be specified.
184
185       ANSIBLE_CONFIG -- Specify override location for the ansible config file
186
187       Many more are available for most options in ansible.cfg
188
189       For  a  full  list  check  https://docs.ansible.com/.  or use the ansi‐
190       ble-config command.
191

FILES

193       /etc/ansible/ansible.cfg -- Config file, used if present
194
195       ~/.ansible.cfg -- User config file, overrides  the  default  config  if
196       present
197
198       ./ansible.cfg  --  Local config file (in current working directory) as‐
199       sumed to be 'project specific' and overrides the rest if present.
200
201       As mentioned above, the ANSIBLE_CONFIG environment variable will  over‐
202       ride all others.
203

AUTHOR

205       Ansible was originally written by Michael DeHaan.
206

COPYRIGHT

208       Copyright © 2018 Red Hat, Inc | Ansible.  Ansible is released under the
209       terms of the GPLv3 license.
210