ansible-core/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] [-k]
11              [--private-key PRIVATE_KEY_FILE] [-u  REMOTE_USER]  [-c  CONNEC‐
12              TION]    [-T    TIMEOUT]   [--ssh-common-args   SSH_COMMON_ARGS]
13              [--sftp-extra-args  SFTP_EXTRA_ARGS]  [--scp-extra-args  SCP_EX‐
14              TRA_ARGS]    [--ssh-extra-args    SSH_EXTRA_ARGS]    [--vault-id
15              VAULT_IDS]   [--ask-vault-password    |    --vault-password-file
16              VAULT_PASSWORD_FILES]  [-e  EXTRA_VARS]  [-t  TAGS] [--skip-tags
17              SKIP_TAGS] [-i INVENTORY] [--list-hosts] [-l  SUBSET]  [-M  MOD‐
18              ULE_PATH] [-K] [--purge] [-o] [-s SLEEP] [-f] [-d DEST] [-U URL]
19              [--full]  [-C  CHECKOUT]  [--accept-host-key]  [-m  MODULE_NAME]
20              [--verify-commit]  [--clean]  [--track-subs]  [--check] [--diff]
21              [playbook.yml [playbook.yml ...]]
22

DESCRIPTION

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

COMMON OPTIONS

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

ENVIRONMENT

167       The following environment variables may be specified.
168
169       ANSIBLE_CONFIG -- Specify override location for the ansible config file
170
171       Many more are available for most options in ansible.cfg
172
173       For  a  full  list  check  https://docs.ansible.com/.  or use the ansi‐
174       ble-config command.
175

FILES

177       /etc/ansible/ansible.cfg -- Config file, used if present
178
179       ~/.ansible.cfg -- User config file, overrides  the  default  config  if
180       present
181
182       ./ansible.cfg  --  Local config file (in current working directory) as‐
183       sumed to be 'project specific' and overrides the rest if present.
184
185       As mentioned above, the ANSIBLE_CONFIG environment variable will  over‐
186       ride all others.
187

AUTHOR

189       Ansible was originally written by Michael DeHaan.
190

COPYRIGHT

192       Copyright © 2018 Red Hat, Inc | Ansible.  Ansible is released under the
193       terms of the GPLv3 license.
194