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 [play‐
23              book.yml ...]]
24

DESCRIPTION

26       Used to pull a remote copy of ansible on each managed node, each set to
27       run  via cron and update playbook source via a source repository.  This
28       inverts the default push architecture of ansible into a pull  architec‐
29       ture, which has near-limitless scaling potential.
30
31       The  setup  playbook can be tuned to change the cron frequency, logging
32       locations, and parameters to ansible-pull.  This is useful both for ex‐
33       treme  scale-out as well as periodic remediation.  Usage of the 'fetch'
34       module to retrieve logs from ansible-pull runs would  be  an  excellent
35       way to gather and analyze remote logs from ansible-pull.
36

COMMON OPTIONS

38          Playbook(s)
39
40       --accept-host-key
41          adds the hostkey for the repo url if not already added
42
43       --ask-vault-password, --ask-vault-pass
44          ask for vault password
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
85
86       --ssh-common-args 'SSH_COMMON_ARGS'
87          specify common arguments to pass to sftp/scp/ssh (e.g. ProxyCommand)
88
89       --ssh-extra-args 'SSH_EXTRA_ARGS'
90          specify extra arguments to pass to ssh only (e.g. -R)
91
92       --track-subs
93          submodules  will  track  the  latest  changes. This is equivalent to
94          specifying the --remote flag to git submodule update
95
96       --vault-id
97          the vault identity to use
98
99       --vault-password-file, --vault-pass-file
100          vault password file
101
102       --verify-commit
103          verify GPG signature of checked out commit, if it fails  abort  run‐
104          ning  the  playbook. This needs the corresponding VCS module to sup‐
105          port such an operation
106
107       --version
108          show program's version number, config file location, configured mod‐
109          ule search path, module location, executable location and exit
110
111       -C 'CHECKOUT', --checkout 'CHECKOUT'
112          branch/tag/commit  to  checkout.  Defaults to behavior of repository
113          module.
114
115       -K, --ask-become-pass
116          ask for privilege escalation password
117
118       -M, --module-path
119          prepend colon-separated path(s) to module library  (default=~/.ansi‐
120          ble/plugins/modules:/usr/share/ansible/plugins/modules)
121
122       -T 'TIMEOUT', --timeout 'TIMEOUT'
123          override the connection timeout in seconds (default=10)
124
125       -U 'URL', --url 'URL'
126          URL of the playbook repository
127
128       -c 'CONNECTION', --connection 'CONNECTION'
129          connection type to use (default=smart)
130
131       -d 'DEST', --directory 'DEST'
132          absolute  path  of repository checkout directory (relative paths are
133          not supported)
134
135       -e, --extra-vars
136          set additional variables as  key=value  or  YAML/JSON,  if  filename
137          prepend with @
138
139       -f, --force
140          run the playbook even if the repository could not be updated
141
142       -h, --help
143          show this help message and exit
144
145       -i, --inventory, --inventory-file
146          specify  inventory  host path or comma separated host list. --inven‐
147          tory-file is deprecated
148
149       -k, --ask-pass
150          ask for connection password
151
152       -l 'SUBSET', --limit 'SUBSET'
153          further limit selected hosts to an additional pattern
154
155       -m 'MODULE_NAME', --module-name 'MODULE_NAME'
156          Repository module name, which ansible will  use  to  check  out  the
157          repo.  Choices  are  ('git',  'subversion', 'hg', 'bzr'). Default is
158          git.
159
160       -o, --only-if-changed
161          only run the playbook if the repository has been updated
162
163       -s 'SLEEP', --sleep 'SLEEP'
164          sleep for random interval (between 0 and n number of seconds) before
165          starting. This is a useful way to disperse git requests
166
167       -t, --tags
168          only run plays and tasks tagged with these values
169
170       -u 'REMOTE_USER', --user 'REMOTE_USER'
171          connect as this user (default=None)
172
173       -v, --verbose
174          verbose mode (-vvv for more, -vvvv to enable connection debugging)
175

ENVIRONMENT

177       The following environment variables may be specified.
178
179       ANSIBLE_CONFIG -- Specify override location for the ansible config file
180
181       Many more are available for most options in ansible.cfg
182
183       For  a  full  list  check  https://docs.ansible.com/.  or use the ansi‐
184       ble-config command.
185

FILES

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

AUTHOR

199       Ansible was originally written by Michael DeHaan.
200

COPYRIGHT

202       Copyright © 2018 Red Hat, Inc | Ansible.  Ansible is released under the
203       terms of the GPLv3 license.
204