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

ARGUMENTS

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

INVENTORY

197       Ansible stores the hosts it can potentially operate on in an inventory.
198       This  can  be  an  YAML file, ini-like file, a script, directory, list,
199       etc.    For   additional   options,   see    the    documentation    on
200       https://docs.ansible.com/.
201

ENVIRONMENT

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

FILES

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

AUTHOR

231       Ansible was originally written by Michael DeHaan.
232

COPYRIGHT

234       Copyright © 2018 Red Hat, Inc | Ansible.  Ansible is released under the
235       terms of the GPLv3 license.
236