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

ARGUMENTS

183       playbook.yml
184
185       The  name  of  one  the  YAML  format  files to run as an Ansible play‐
186       book.This can be a relative path within the checkout. By default, Ansi‐
187       ble  willlook for a playbook based on the host's fully-qualified domain
188       name,on the host hostname and finally a playbook named local.yml.
189

INVENTORY

191       Ansible stores the hosts it can potentially operate on in an inventory.
192       This  can  be  an  YAML file, ini-like file, a script, directory, list,
193       etc.    For   additional   options,   see    the    documentation    on
194       https://docs.ansible.com/.
195

ENVIRONMENT

197       The following environment variables may be specified.
198
199       ANSIBLE_INVENTORY  -- Override the default ansible inventory sources
200
201       ANSIBLE_LIBRARY -- Override the default ansible module library path
202
203       ANSIBLE_CONFIG -- Specify override location for the ansible config file
204
205       Many more are available for most options in ansible.cfg
206
207       For  a  full  list  check  https://docs.ansible.com/.  or use the ansi‐
208       ble-config command.
209

FILES

211       /etc/ansible/hosts -- Default inventory file
212
213       /etc/ansible/ansible.cfg -- Config file, used if present
214
215       ~/.ansible.cfg -- User config file, overrides  the  default  config  if
216       present
217
218       ./ansible.cfg  --  Local config file (in current working directory) as‐
219       sumed to be 'project specific' and overrides the rest if present.
220
221       As mentioned above, the ANSIBLE_CONFIG environment variable will  over‐
222       ride all others.
223

AUTHOR

225       Ansible was originally written by Michael DeHaan.
226

COPYRIGHT

228       Copyright © 2018 Red Hat, Inc | Ansible.  Ansible is released under the
229       terms of the GPLv3 license.
230