'\" t
.\"     Title: ansible
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: 01/16/2017
.\"    Manual: System administration commands
.\"    Source: Ansible 2.2.1.0
.\"  Language: English
.\"
.TH "ANSIBLE" "1" "01/16/2017" "Ansible 2\&.2\&.1\&.0" "System administration commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
ansible \- run a task on a target host(s)
.SH "SYNOPSIS"
.sp
ansible <host\-pattern> [\-m module_name] [\-a args] [options]
.SH "DESCRIPTION"
.sp
\fBAnsible\fR is an extra\-simple tool/framework/API for doing \*(Aqremote things\*(Aq\&. This is the adhoc command that allows for a \*(Aqsingle task playbook\*(Aq run\&.
.SH "ARGUMENTS"
.PP
\fBhost\-pattern\fR
.RS 4
A name of a group in the inventory, a shell\-like glob selecting hosts in inventory or any combination of the two separated by commas\&.
.RE
.SH "OPTIONS"
.PP
\fB\-a\fR \*(Aq\fIARGUMENTS\fR\*(Aq, \fB\-\-args=\fR\*(Aq\fIARGUMENTS\fR\*(Aq
.RS 4
The
\fIARGUMENTS\fR
to pass to the module\&.
.RE
.PP
\fB\-b\fR, \fB\-\-become\fR
.RS 4
Use privilege escalation (specific one depends on become_method), this does not imply prompting for passwords\&.
.RE
.PP
\fB\-K\fR, \fB\-\-ask\-become\-pass\fR
.RS 4
Ask for privilege escalation password\&.
.RE
.PP
\fB\-k\fR, \fB\-\-ask\-pass\fR
.RS 4
Prompt for the connection password, if it is needed for the transport used\&. For example, using ssh and not having a key\-based authentication with ssh\-agent\&.
.RE
.PP
\fB\-\-ask\-su\-pass\fR
.RS 4
Prompt for su password, used with \-\-su (deprecated, use become)\&.
.RE
.PP
\fB\-\-ask\-sudo\-pass\fR
.RS 4
Prompt for the password to use with \-\-sudo, if any (deprecated, use become)\&.
.RE
.PP
\fB\-\-ask\-vault\-pass\fR
.RS 4
Prompt for vault password\&.
.RE
.PP
\fB\-B\fR \fINUM\fR, \fB\-\-background=\fR\fINUM\fR
.RS 4
Run commands in the background, killing the task after
\fINUM\fR
seconds\&.
.RE
.PP
\fB\-\-become\-method=\fR\fIBECOME_METHOD\fR
.RS 4
Privilege escalation method to use (default=sudo), valid choices: [ sudo | su | pbrun | pfexec | doas | dzdo | ksu ]
.RE
.PP
\fB\-\-become\-user=\fR\fIBECOME_USER\fR
.RS 4
Run operations as this user (default=root)\&.
.RE
.PP
\fB\-C\fR, \fB\-\-check\fR
.RS 4
Do not make any changes on the remote system, but test resources to see what might have changed\&. Note this can not scan all possible resource types and is only a simulation\&.
.RE
.PP
\fB\-c\fR \fICONNECTION\fR, \fB\-\-connection=\fR\fICONNECTION\fR
.RS 4
Connection type to use\&. Most common options are
\fIparamiko\fR
(SSH),
\fIssh\fR,
\fIwinrm\fR
and
\fIlocal\fR\&.
\fIlocal\fR
is mostly useful for crontab or kickstarts\&.
.RE
.PP
\fB\-e\fR \fIEXTRA_VARS, \fR\fI\fB\-\-extra\-vars=\fR\fR\fI\*(AqEXTRA_VARS\fR
.RS 4
Extra variables to inject into a playbook, in key=value key=value format or as quoted YAML/JSON (hashes and arrays)\&. To load variables from a file, specify the file preceded by @ (e\&.g\&. @vars\&.yml)\&.
.RE
.PP
\fB\-f\fR \fINUM\fR, \fB\-\-forks=\fR\fINUM\fR
.RS 4
Level of parallelism\&.
\fINUM\fR
is specified as an integer, the default is 5\&.
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Show help message and exit\&.
.RE
.PP
\fB\-i\fR \fIPATH\fR, \fB\-\-inventory=\fR\fIPATH\fR
.RS 4
The
\fIPATH\fR
to the inventory, which defaults to
\fI/etc/ansible/hosts\fR\&. Alternatively you can use a comma separated list of hosts or single host with trailing comma
\fIhost,\fR\&.
.RE
.PP
\fB\-l\fR \fISUBSET\fR, \fB\-\-limit=\fR\fISUBSET\fR
.RS 4
Further limits the selected host/group patterns\&. You can prefix it with
\fI~\fR
to indicate that the pattern is a regex\&.
.RE
.PP
\fB\-\-list\-hosts\fR
.RS 4
Outputs a list of matching hosts; does not execute anything else\&.
.RE
.PP
\fB\-m\fR \fINAME\fR, \fB\-\-module\-name=\fR\fINAME\fR
.RS 4
Execute the module called
\fINAME\fR\&.
.RE
.PP
\fB\-M\fR \fIDIRECTORY\fR, \fB\-\-module\-path=\fR\fIDIRECTORY\fR
.RS 4
The
\fIDIRECTORY\fR
search path to load modules from\&. The default is
\fI/usr/share/ansible\fR\&. This can also be set with the ANSIBLE_LIBRARY environment variable\&.
.RE
.PP
\fB\-o\fR, \fB\-\-one\-line\fR
.RS 4
Try to output everything on one line\&.
.RE
.PP
\fB\-P\fR \fINUM\fR, \fB\-\-poll=\fR\fINUM\fR
.RS 4
Poll a background job every
\fINUM\fR
seconds\&. Requires
\fB\-B\fR\&.
.RE
.PP
\fB\-\-private\-key=\fR\fIPRIVATE_KEY_FILE\fR
.RS 4
Use this file to authenticate the connection\&.
.RE
.PP
\fB\-S\fR, \fB\-\-su\fR
.RS 4
Run operations with su (deprecated, use become)\&.
.RE
.PP
\fB\-R\fR \fISU_USER\fR, \fB\-\-se\-user=\fR\fISUDO_USER\fR
.RS 4
Run operations with su as this user (default=root) (deprecated, use become)\&.
.RE
.PP
\fB\-s\fR, \fB\-\-sudo\fR
.RS 4
Run the command as the user given by \-u and sudo to root (deprecated, use become)\&.
.RE
.PP
\fB\-\-ssh\-common\-args=\fR\fI\*(Aq\-o ProxyCommand="ssh \-W %h:%p \&..." \&...\fR\*(Aq
.RS 4
Add the specified arguments to any sftp/scp/ssh command\-line\&. Useful to set a ProxyCommand to use a jump host, but any arguments that are accepted by all three programs may be specified\&.
.RE
.PP
\fB\-\-sftp\-extra\-args=\fR\fI\*(Aq\-f \&...\fR\*(Aq
.RS 4
Add the specified arguments to any sftp command\-line\&.
.RE
.PP
\fB\-\-scp\-extra\-args=\fR\fI\*(Aq\-l \&...\fR\*(Aq
.RS 4
Add the specified arguments to any scp command\-line\&.
.RE
.PP
\fB\-\-ssh\-extra\-args=\fR\fI\*(Aq\-R \&...\fR\*(Aq
.RS 4
Add the specified arguments to any ssh command\-line\&.
.RE
.PP
\fB\-U\fR \fISUDO_USERNAME\fR, \fB\-\-sudo\-user=\fR\fISUDO_USERNAME\fR
.RS 4
Sudo to
\fISUDO_USERNAME\fR
default is root\&. (deprecated, use become)\&.
.RE
.PP
\fB\-t\fR \fIDIRECTORY\fR, \fB\-\-tree=\fR\fIDIRECTORY\fR
.RS 4
Save contents in this output
\fIDIRECTORY\fR, with the results saved in a file named after each host\&.
.RE
.PP
\fB\-T\fR \fISECONDS\fR, \fB\-\-timeout=\fR\fISECONDS\fR
.RS 4
Connection timeout to use when trying to talk to hosts, in
\fISECONDS\fR\&.
.RE
.PP
\fB\-u\fR \fIUSERNAME\fR, \fB\-\-user=\fR\fIUSERNAME\fR
.RS 4
Use this
\fIUSERNAME\fR
to login to the target host, instead of the current user\&.
.RE
.PP
\fB\-\-vault\-password\-file=\fR\fIVAULT_PASSWORD_FILE\fR
.RS 4
A file containing the vault password to be used during the decryption of vault encrypted files\&. Be sure to keep this file secured if it is used\&. If the file is executable, it will be run and its standard output will be used as the password\&.
.RE
.PP
\fB\-v\fR, \fB\-\-verbose\fR
.RS 4
Verbose mode, more output from successful actions will be shown\&. Give up to three times for more output\&.
.RE
.PP
\fB\-\-version\fR
.RS 4
Show program version number and exit\&.
.RE
.SH "INVENTORY"
.sp
Ansible stores the hosts it can potentially operate on in an inventory\&. This can be an ini\-like file, a script, directory or a list\&. The ini syntax is one host per line\&. Groups headers are allowed and are included on their own line, enclosed in square brackets that start the line\&.
.sp
Ranges of hosts are also supported\&. For more information and additional options, see the documentation on http://docs\&.ansible\&.com/\&.
.SH "ENVIRONMENT"
.sp
The following environment variables may be specified\&.
.sp
ANSIBLE_INVENTORY  \(em Override the default ansible inventory file
.sp
ANSIBLE_LIBRARY \(em Override the default ansible module library path
.sp
ANSIBLE_CONFIG \(em Override the default ansible config file
.sp
Many more are available for most options in ansible\&.cfg
.SH "FILES"
.sp
/etc/ansible/hosts \(em Default inventory file
.sp
/usr/share/ansible/ \(em Default module library
.sp
/etc/ansible/ansible\&.cfg \(em Config file, used if present
.sp
~/\&.ansible\&.cfg \(em User config file, overrides the default config if present
.SH "AUTHOR"
.sp
Ansible was originally written by Michael DeHaan\&. See the AUTHORS file for a complete list of contributors\&.
.SH "COPYRIGHT"
.sp
Copyright \(co 2012, Michael DeHaan Ansible is released under the terms of the GPLv3 License\&.
.SH "SEE ALSO"
.sp
\fBansible\-playbook\fR(1), \fBansible\-pull\fR(1), \fBansible\-doc\fR(1), \fBansible\-vault\fR(1), \fBansible\-galaxy\fR(1)
.sp
Extensive documentation is available in the documentation site: http://docs\&.ansible\&.com\&. IRC and mailing list info can be found in file CONTRIBUTING\&.md, available in: https://github\&.com/ansible/ansible