ansible/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-pass | --vault-password-file VAULT_PASS‐
16              WORD_FILES]  [-e  EXTRA_VARS]  [-t TAGS] [--skip-tags SKIP_TAGS]
17              [-i INVENTORY] [--list-hosts] [-l SUBSET] [-M MODULE_PATH]  [-K]
18              [--purge]  [-o]  [-s SLEEP] [-f] [-d DEST] [-U URL] [--full] [-C
19              CHECKOUT] [--accept-host-key] [-m MODULE_NAME] [--verify-commit]
20              [--clean] [--track-subs] [--check] [--diff] [playbook.yml [play‐
21              book.yml ...]]
22

DESCRIPTION

24       is used to up a remote copy of ansible on each managed node,  each  set
25       to  run  via  cron  and update playbook source via a source repository.
26       This inverts the default push architecture of ansible into a  pull  ar‐
27       chitecture, 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-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
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          directory to checkout repository to
123
124       -e, --extra-vars
125          set  additional  variables  as  key=value  or YAML/JSON, if filename
126          prepend with @
127
128       -f, --force
129          run the playbook even if the repository could not be updated
130
131       -h, --help
132          show this help message and exit
133
134       -i, --inventory, --inventory-file
135          specify inventory host path or comma separated host  list.  --inven‐
136          tory-file is deprecated
137
138       -k, --ask-pass
139          ask for connection password
140
141       -l 'SUBSET', --limit 'SUBSET'
142          further limit selected hosts to an additional pattern
143
144       -m 'MODULE_NAME', --module-name 'MODULE_NAME'
145          Repository  module  name,  which  ansible  will use to check out the
146          repo. Choices are ('git', 'subversion',  'hg',  'bzr').  Default  is
147          git.
148
149       -o, --only-if-changed
150          only run the playbook if the repository has been updated
151
152       -s 'SLEEP', --sleep 'SLEEP'
153          sleep for random interval (between 0 and n number of seconds) before
154          starting. This is a useful way to disperse git requests
155
156       -t, --tags
157          only run plays and tasks tagged with these values
158
159       -u 'REMOTE_USER', --user 'REMOTE_USER'
160          connect as this user (default=None)
161
162       -v, --verbose
163          verbose mode (-vvv for more, -vvvv to enable connection debugging)
164

ENVIRONMENT

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

FILES

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

AUTHOR

188       Ansible was originally written by Michael DeHaan.
189

COPYRIGHT

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