path: root/docs/man/man1/ansible.1

.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "ANSIBLE" 1 "" "Ansible 2.14.3" "System administration commands"
.SH NAME
ansible \- Define and run a single task 'playbook' against a set of hosts
.SH SYNOPSIS
.INDENT 0.0
.TP
.B usage: ansible [\-h] [\-\-version] [\-v] [\-b] [\-\-become\-method BECOME_METHOD]
[\-\-become\-user BECOME_USER]
[\-K | \-\-become\-password\-file BECOME_PASSWORD_FILE]
[\-i INVENTORY] [\-\-list\-hosts] [\-l SUBSET] [\-P POLL_INTERVAL]
[\-B SECONDS] [\-o] [\-t TREE] [\-\-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]
[\-k | \-\-connection\-password\-file CONNECTION_PASSWORD_FILE] [\-C]
[\-\-syntax\-check] [\-D] [\-e EXTRA_VARS] [\-\-vault\-id VAULT_IDS]
[\-\-ask\-vault\-password | \-\-vault\-password\-file VAULT_PASSWORD_FILES]
[\-f FORKS] [\-M MODULE_PATH] [\-\-playbook\-dir BASEDIR]
[\-\-task\-timeout TASK_TIMEOUT] [\-a MODULE_ARGS] [\-m MODULE_NAME]
pattern
.UNINDENT
.SH DESCRIPTION
.sp
is an extra\-simple tool/framework/API for doing \(aqremote things\(aq.
this command allows you to define and run a single task \(aqplaybook\(aq against a
set of hosts
.SH COMMON OPTIONS
.INDENT 0.0
.INDENT 3.5
host pattern
.UNINDENT
.UNINDENT
.sp
\fB\-\-ask\-vault\-password\fP, \fB\-\-ask\-vault\-pass\fP
.INDENT 0.0
.INDENT 3.5
ask for vault password
.UNINDENT
.UNINDENT
.sp
\fB\-\-become\-method\fP \(aqBECOME_METHOD\(aq
.INDENT 0.0
.INDENT 3.5
privilege escalation method to use (default=sudo), use \fIansible\-doc \-t become \-l\fP to list valid choices.
.UNINDENT
.UNINDENT
.sp
\fB\-\-become\-password\-file\fP \(aqBECOME_PASSWORD_FILE\(aq, \fB\-\-become\-pass\-file\fP \(aqBECOME_PASSWORD_FILE\(aq
.INDENT 0.0
.INDENT 3.5
Become password file
.UNINDENT
.UNINDENT
.sp
\fB\-\-become\-user\fP \(aqBECOME_USER\(aq
.INDENT 0.0
.INDENT 3.5
run operations as this user (default=root)
.UNINDENT
.UNINDENT
.sp
\fB\-\-connection\-password\-file\fP \(aqCONNECTION_PASSWORD_FILE\(aq, \fB\-\-conn\-pass\-file\fP \(aqCONNECTION_PASSWORD_FILE\(aq
.INDENT 0.0
.INDENT 3.5
Connection password file
.UNINDENT
.UNINDENT
.sp
\fB\-\-list\-hosts\fP
.INDENT 0.0
.INDENT 3.5
outputs a list of matching hosts; does not execute anything else
.UNINDENT
.UNINDENT
.sp
\fB\-\-playbook\-dir\fP \(aqBASEDIR\(aq
.INDENT 0.0
.INDENT 3.5
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/ etc.
.UNINDENT
.UNINDENT
.sp
\fB\-\-private\-key\fP \(aqPRIVATE_KEY_FILE\(aq, \fB\-\-key\-file\fP \(aqPRIVATE_KEY_FILE\(aq
.INDENT 0.0
.INDENT 3.5
use this file to authenticate the connection
.UNINDENT
.UNINDENT
.sp
\fB\-\-scp\-extra\-args\fP \(aqSCP_EXTRA_ARGS\(aq
.INDENT 0.0
.INDENT 3.5
specify extra arguments to pass to scp only (e.g. \-l)
.UNINDENT
.UNINDENT
.sp
\fB\-\-sftp\-extra\-args\fP \(aqSFTP_EXTRA_ARGS\(aq
.INDENT 0.0
.INDENT 3.5
specify extra arguments to pass to sftp only (e.g. \-f, \-l)
.UNINDENT
.UNINDENT
.sp
\fB\-\-ssh\-common\-args\fP \(aqSSH_COMMON_ARGS\(aq
.INDENT 0.0
.INDENT 3.5
specify common arguments to pass to sftp/scp/ssh (e.g. ProxyCommand)
.UNINDENT
.UNINDENT
.sp
\fB\-\-ssh\-extra\-args\fP \(aqSSH_EXTRA_ARGS\(aq
.INDENT 0.0
.INDENT 3.5
specify extra arguments to pass to ssh only (e.g. \-R)
.UNINDENT
.UNINDENT
.sp
\fB\-\-syntax\-check\fP
.INDENT 0.0
.INDENT 3.5
perform a syntax check on the playbook, but do not execute it
.UNINDENT
.UNINDENT
.sp
\fB\-\-task\-timeout\fP \(aqTASK_TIMEOUT\(aq
.INDENT 0.0
.INDENT 3.5
set task timeout limit in seconds, must be positive integer.
.UNINDENT
.UNINDENT
.sp
\fB\-\-vault\-id\fP
.INDENT 0.0
.INDENT 3.5
the vault identity to use
.UNINDENT
.UNINDENT
.sp
\fB\-\-vault\-password\-file\fP, \fB\-\-vault\-pass\-file\fP
.INDENT 0.0
.INDENT 3.5
vault password file
.UNINDENT
.UNINDENT
.sp
\fB\-\-version\fP
.INDENT 0.0
.INDENT 3.5
show program\(aqs version number, config file location, configured module search path, module location, executable location and exit
.UNINDENT
.UNINDENT
.sp
\fB\-B\fP \(aqSECONDS\(aq, \fB\-\-background\fP \(aqSECONDS\(aq
.INDENT 0.0
.INDENT 3.5
run asynchronously, failing after X seconds (default=N/A)
.UNINDENT
.UNINDENT
.sp
\fB\-C\fP, \fB\-\-check\fP
.INDENT 0.0
.INDENT 3.5
don\(aqt make any changes; instead, try to predict some of the changes that may occur
.UNINDENT
.UNINDENT
.sp
\fB\-D\fP, \fB\-\-diff\fP
.INDENT 0.0
.INDENT 3.5
when changing (small) files and templates, show the differences in those files; works great with \-\-check
.UNINDENT
.UNINDENT
.sp
\fB\-K\fP, \fB\-\-ask\-become\-pass\fP
.INDENT 0.0
.INDENT 3.5
ask for privilege escalation password
.UNINDENT
.UNINDENT
.sp
\fB\-M\fP, \fB\-\-module\-path\fP
.INDENT 0.0
.INDENT 3.5
prepend colon\-separated path(s) to module library (default={{ ANSIBLE_HOME ~ \(dq/plugins/modules:/usr/share/ansible/plugins/modules\(dq }})
.UNINDENT
.UNINDENT
.sp
\fB\-P\fP \(aqPOLL_INTERVAL\(aq, \fB\-\-poll\fP \(aqPOLL_INTERVAL\(aq
.INDENT 0.0
.INDENT 3.5
set the poll interval if using \-B (default=15)
.UNINDENT
.UNINDENT
.sp
\fB\-T\fP \(aqTIMEOUT\(aq, \fB\-\-timeout\fP \(aqTIMEOUT\(aq
.INDENT 0.0
.INDENT 3.5
override the connection timeout in seconds (default=10)
.UNINDENT
.UNINDENT
.sp
\fB\-a\fP \(aqMODULE_ARGS\(aq, \fB\-\-args\fP \(aqMODULE_ARGS\(aq
.INDENT 0.0
.INDENT 3.5
The action\(aqs options in space separated k=v format: \-a \(aqopt1=val1 opt2=val2\(aq or a json string: \-a \(aq{\(dqopt1\(dq: \(dqval1\(dq, \(dqopt2\(dq: \(dqval2\(dq}\(aq
.UNINDENT
.UNINDENT
.sp
\fB\-b\fP, \fB\-\-become\fP
.INDENT 0.0
.INDENT 3.5
run operations with become (does not imply password prompting)
.UNINDENT
.UNINDENT
.sp
\fB\-c\fP \(aqCONNECTION\(aq, \fB\-\-connection\fP \(aqCONNECTION\(aq
.INDENT 0.0
.INDENT 3.5
connection type to use (default=smart)
.UNINDENT
.UNINDENT
.sp
\fB\-e\fP, \fB\-\-extra\-vars\fP
.INDENT 0.0
.INDENT 3.5
set additional variables as key=value or YAML/JSON, if filename prepend with @
.UNINDENT
.UNINDENT
.sp
\fB\-f\fP \(aqFORKS\(aq, \fB\-\-forks\fP \(aqFORKS\(aq
.INDENT 0.0
.INDENT 3.5
specify number of parallel processes to use (default=5)
.UNINDENT
.UNINDENT
.sp
\fB\-h\fP, \fB\-\-help\fP
.INDENT 0.0
.INDENT 3.5
show this help message and exit
.UNINDENT
.UNINDENT
.sp
\fB\-i\fP, \fB\-\-inventory\fP, \fB\-\-inventory\-file\fP
.INDENT 0.0
.INDENT 3.5
specify inventory host path or comma separated host list. \-\-inventory\-file is deprecated
.UNINDENT
.UNINDENT
.sp
\fB\-k\fP, \fB\-\-ask\-pass\fP
.INDENT 0.0
.INDENT 3.5
ask for connection password
.UNINDENT
.UNINDENT
.sp
\fB\-l\fP \(aqSUBSET\(aq, \fB\-\-limit\fP \(aqSUBSET\(aq
.INDENT 0.0
.INDENT 3.5
further limit selected hosts to an additional pattern
.UNINDENT
.UNINDENT
.sp
\fB\-m\fP \(aqMODULE_NAME\(aq, \fB\-\-module\-name\fP \(aqMODULE_NAME\(aq
.INDENT 0.0
.INDENT 3.5
Name of the action to execute (default=command)
.UNINDENT
.UNINDENT
.sp
\fB\-o\fP, \fB\-\-one\-line\fP
.INDENT 0.0
.INDENT 3.5
condense output
.UNINDENT
.UNINDENT
.sp
\fB\-t\fP \(aqTREE\(aq, \fB\-\-tree\fP \(aqTREE\(aq
.INDENT 0.0
.INDENT 3.5
log output to this directory
.UNINDENT
.UNINDENT
.sp
\fB\-u\fP \(aqREMOTE_USER\(aq, \fB\-\-user\fP \(aqREMOTE_USER\(aq
.INDENT 0.0
.INDENT 3.5
connect as this user (default=None)
.UNINDENT
.UNINDENT
.sp
\fB\-v\fP, \fB\-\-verbose\fP
.INDENT 0.0
.INDENT 3.5
Causes Ansible to print more debug messages. Adding multiple \-v will increase the verbosity, the builtin plugins currently evaluate up to \-vvvvvv. A reasonable level to start is \-vvv, connection debugging might require \-vvvv.
.UNINDENT
.UNINDENT
.SH ENVIRONMENT
.sp
The following environment variables may be specified.
.sp
ANSIBLE_CONFIG \-\- Specify override location for the ansible config file
.sp
Many more are available for most options in ansible.cfg
.sp
For a full list check \fI\%https://docs.ansible.com/\fP\&. or use the \fIansible\-config\fP command.
.SH FILES
.sp
/etc/ansible/ansible.cfg \-\- Config file, used if present
.sp
~/.ansible.cfg \-\- User config file, overrides the default config if present
.sp
\&./ansible.cfg \-\- Local config file (in current working directory) assumed to be \(aqproject specific\(aq and overrides the rest if present.
.sp
As mentioned above, the ANSIBLE_CONFIG environment variable will override all others.
.SH AUTHOR
.sp
Ansible was originally written by Michael DeHaan.
.SH COPYRIGHT
.sp
Copyright © 2018 Red Hat, Inc | Ansible.
Ansible is released under the terms of the GPLv3 license.
.SH SEE ALSO
.sp
\fBansible\-config\fP (1), \fBansible\-console\fP (1), \fBansible\-doc\fP (1), \fBansible\-galaxy\fP (1), \fBansible\-inventory\fP (1), \fBansible\-playbook\fP (1), \fBansible\-pull\fP (1), \fBansible\-vault\fP (1)
.sp
Extensive documentation is available in the documentation site:
<\fI\%https://docs.ansible.com\fP>.
IRC and mailing list info can be found in file CONTRIBUTING.md,
available in: <\fI\%https://github.com/ansible/ansible\fP>
.\" Generated by docutils manpage writer.
.