4. Usage

4.1. Arguments

usage: ansible [-h] [--version] [-v] [-b] [--become-method BECOME_METHOD]
               [--become-user BECOME_USER] [-K] [-i INVENTORY] [--list-hosts]
               [-l SUBSET] [-P POLL_INTERVAL] [-B SECONDS] [-o] [-t TREE] [-k]
               [--private-key PRIVATE_KEY_FILE] [-u REMOTE_USER]
               [-c CONNECTION] [-T TIMEOUT]
               [--ssh-common-args SSH_COMMON_ARGS]
               [--sftp-extra-args SFTP_EXTRA_ARGS]
               [--scp-extra-args SCP_EXTRA_ARGS]
               [--ssh-extra-args SSH_EXTRA_ARGS] [-C] [--syntax-check] [-D]
               [-e EXTRA_VARS] [--vault-id VAULT_IDS]
               [--ask-vault-pass | --vault-password-file VAULT_PASSWORD_FILES]
               [-f FORKS] [-M MODULE_PATH] [--playbook-dir BASEDIR]
               [-a MODULE_ARGS] [-m MODULE_NAME]
$ ansible localhost -m shell -a 'whoami'
localhost | CHANGED | rc=0 >>

$ ansible localhost --become -m shell -a 'whoami'
localhost | CHANGED | rc=0 >>
$ ansible localhost -m shell -a 'python3 --version'
localhost | CHANGED | rc=0 >>
Python 3.10.4
$ ansible localhost --become -m shell -a 'apt install -y python3'
localhost | CHANGED | rc=0 >>
Reading package lists...
Building dependency tree...
Reading state information...
python3 is already the newest version (3.10.4-0ubuntu2).
python3 set to manually installed.
0 upgraded, 0 newly installed, 0 to remove and 47 not upgraded.

WARNING: apt does not have a stable CLI interface. Use with caution in scripts.
$ cat > hosts << EOF

$ ansible -i hosts myserver --become -m raw -a 'apt install -y python3'
$ ansible -i hosts all --become -m raw -a 'apt install -y python3'

4.2. Positional arguments

  • Define and run a single task 'playbook' against a set of hosts

pattern               host pattern

4.3. Optional arguments

--ask-vault-pass      ask for vault password
--list-hosts          outputs a list of matching hosts; does not execute
                      anything else
--playbook-dir BASEDIR
                      Since this tool does not use playbooks, use this as a
                      substitute playbook directory.This sets the relative
                      path for many features including roles/ group_vars/
--syntax-check        perform a syntax check on the playbook, but do not
                      execute it
--vault-id VAULT_IDS  the vault identity to use
--vault-password-file VAULT_PASSWORD_FILES
                      vault password file
--version             show program's version number, config file location,
                      configured module search path, module location,
                      executable location and exit
-B SECONDS, --background SECONDS
                      run asynchronously, failing after X seconds
-C, --check           don't make any changes; instead, try to predict some
                      of the changes that may occur
-D, --diff            when changing (small) files and templates, show the
                      differences in those files; works great with --check
                      prepend colon-separated path(s) to module library (def
                      set the poll interval if using -B (default=15)
                      module arguments
-e EXTRA_VARS, --extra-vars EXTRA_VARS
                      set additional variables as key=value or YAML/JSON, if
                      filename prepend with @
-f FORKS, --forks FORKS
                      specify number of parallel processes to use
-h, --help            show this help message and exit
-i INVENTORY, --inventory INVENTORY, --inventory-file INVENTORY
                      specify inventory host path or comma separated host
                      list. --inventory-file is deprecated
-l SUBSET, --limit SUBSET
                      further limit selected hosts to an additional pattern
-m MODULE_NAME, --module-name MODULE_NAME
                      module name to execute (default=command)
-o, --one-line        condense output
-t TREE, --tree TREE  log output to this directory
-v, --verbose         verbose mode (-vvv for more, -vvvv to enable
                      connection debugging)

4.4. Privilege Escalation Options

  • control how and which user you become as on target hosts

--become-method BECOME_METHOD
                      privilege escalation method to use (default=sudo), use
                      `ansible-doc -t become -l` to list valid choices.
--become-user BECOME_USER
                      run operations as this user (default=root)
-K, --ask-become-pass
                      ask for privilege escalation password
-b, --become          run operations with become (does not imply password

4.5. Connection Options

  • control as whom and how to connect to hosts

--private-key PRIVATE_KEY_FILE, --key-file PRIVATE_KEY_FILE
                      use this file to authenticate the connection
--scp-extra-args SCP_EXTRA_ARGS
                      specify extra arguments to pass to scp only (e.g. -l)
--sftp-extra-args SFTP_EXTRA_ARGS
                      specify extra arguments to pass to sftp only (e.g. -f,
--ssh-common-args SSH_COMMON_ARGS
                      specify common arguments to pass to sftp/scp/ssh (e.g.
--ssh-extra-args SSH_EXTRA_ARGS
                      specify extra arguments to pass to ssh only (e.g. -R)
                      override the connection timeout in seconds
                      connection type to use (default=smart)
-k, --ask-pass        ask for connection password
                      connect as this user (default=None)

4.6. Config

  • /etc/ansible/ansible.cfg – Config file, used if present

  • ~/.ansible.cfg – User config file, overrides the default config if present

  • /etc/ansible/hosts - Default inventory file location, If any other location, then specify ansible -i hosts ... for file named hosts More info

4.7. Ansible Pull

  • The ansible-pull is a small script that will checkout a repo of configuration instructions from git, and then run ansible-playbook against that content.

# ansible-pull setup
# on remote hosts, set up ansible to run periodically using the latest code
# from a particular checkout, in pull based fashion, inverting Ansible's
# usual push-based operating mode.
# This particular pull based mode is ideal for:
# (A) massive scale out
# (B) continual system remediation

- hosts: pull_mode_hosts
  remote_user: root


    # schedule is fed directly to cron
    schedule: '*/15 * * * *'

    # User to run ansible-pull as from cron
    cron_user: root

    # File that ansible will use for logs
    logfile: /var/log/ansible-pull.log

    # Directory to where repository will be cloned
    workdir: /var/lib/ansible/local

    # Repository to check out
    # repo must contain a local.yml file at top level
    repo_url: git://github.com/myuser/ansible-playbooks.git


    - name: Install ansible
      apt: pkg=ansible state=installed

    - name: Create local directory to work from
      file: path={{workdir}} state=directory owner=root group=root mode=0751

    - name: Copy ansible inventory file to client
      copy: src=/etc/ansible/hosts dest=/etc/ansible/hosts
              owner=root group=root mode=0644

    - name: Create crontab entry to clone/pull git repository
      template: src=templates/etc_cron.d_ansible-pull.j2 dest=/etc/cron.d/ansible-pull owner=root group=root mode=0644

    - name: Create logrotate entry for ansible-pull.log
      template: src=templates/etc_logrotate.d_ansible-pull.j2 dest=/etc/logrotate.d/ansible-pull owner=root group=root mode=0644