ansible/docs/man/man1/ansible.1.asciidoc.in

ansible(1)
=========
:doctype:manpage
:man source:   Ansible
:man version:  %VERSION%
:man manual:   System administration commands

NAME
----
ansible - run a command somewhere else


SYNOPSIS
--------
ansible <host-pattern> [-f forks] [-m module_name] [-a args]


DESCRIPTION
-----------

*Ansible* is an extra-simple tool/framework/API for doing \'remote things' over
SSH.


ARGUMENTS
---------

*host-pattern*::

A name of a group in the inventory file, a shell-like glob selecting
hosts in inventory file, or any combination of the two separated by
semicolons.

OPTIONS
-------

*-v*, *--verbose*::

Verbose mode, more output from successful actions will be shown. Give
up to three times for more output.

*-i* 'PATH', *--inventory=*'PATH'::

The 'PATH' to the inventory hosts file, which defaults to '/etc/ansible/hosts'.


*-f* 'NUM', *--forks=*'NUM'::

Level of parallelism. 'NUM' is specified as an integer, the default is 5.

*--private-key=*'PRIVATE_KEY_FILE'::

Use this file to authenticate the connection.


*-m* 'NAME', *--module-name=*'NAME'::

Execute the module called 'NAME'.


*-M* 'DIRECTORY', *--module-path=*'DIRECTORY'::

The 'DIRECTORY' search path to load modules from. The default is
'/usr/share/ansible'. This can also be set with the ANSIBLE_LIBRARY
environment variable.

*-a* \'_ARGUMENTS_', *--args=*\'_ARGUMENTS_'::

The 'ARGUMENTS' to pass to the module.

*-k*, *--ask-pass*::

Prompt for the SSH password instead of assuming key-based authentication with ssh-agent.

*-K*, *--ask-sudo-pass*::

Prompt for the password to use with --sudo, if any

*-o*, *--one-line*::

Try to output everything on one line.

*-s*, *--sudo*::

Run the command as the user given by -u and sudo to root.

*-t* 'DIRECTORY', *--tree=*'DIRECTORY'::

Save contents in this output 'DIRECTORY', with the results saved in a
file named after each host.

*-T* 'SECONDS', *--timeout=*'SECONDS'::

Connection timeout to use when trying to talk to hosts, in 'SECONDS'.

*-B* 'NUM', *--background=*'NUM'::

Run commands in the background, killing the task after 'NUM' seconds.

*-P* 'NUM', *--poll=*'NUM'::

Poll a background job every 'NUM' seconds. Requires *-B*.

*-u* 'USERNAME', *--user=*'USERNAME'::

Use this remote 'USERNAME' instead of the current user.

*-U* 'SUDO_USERNAME', *--sudo-user=*'SUDO_USERNAME'::

Sudo to 'SUDO_USERNAME' instead of root.  Implies --sudo.

*-c* 'CONNECTION', *--connection=*'CONNECTION'::

Connection type to use.  Possible options are 'paramiko' (SSH), 'ssh',
and 'local'.  'local' is mostly useful for crontab or kickstarts.

*-l* 'SUBSET', *--limit=*'SUBSET'::

Further limits the selected host/group patterns.

*-l* '\~REGEX', *--limit=*'~REGEX'::

Further limits hosts with a regex pattern.

*--list-hosts*::

Outputs a list of matching hosts; does not execute anything else.

INVENTORY
---------

Ansible stores the hosts it can potentially operate on in an inventory
file. The 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.

Ranges of hosts are also supported.  For more information and
additional options, see the documentation on http://docs.ansible.com/.

FILES
-----

/etc/ansible/hosts -- Default inventory file

/usr/share/ansible/ -- Default module library

/etc/ansible/ansible.cfg -- Config file, used if present

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

ENVIRONMENT
-----------

The following environment variables may be specified.

ANSIBLE_HOSTS  -- Override the default ansible hosts file

ANSIBLE_LIBRARY -- Override the default ansible module library path

ANSIBLE_CONFIG -- Override the default ansible config file


AUTHOR
------

Ansible was originally written by Michael DeHaan. See the AUTHORS file
for a complete list of contributors.


COPYRIGHT
---------

Copyright © 2012, Michael DeHaan

Ansible is released under the terms of the GPLv3 License.


SEE ALSO
--------

*ansible-playbook*(1), *ansible-pull*(1), *ansible-doc*(1)

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>
Because everything should have a man page 2012-02-25 01:05:05 +00:00			`ansible(1)`
			`=========`
			`:doctype:manpage`
			`:man source: Ansible`
Update %description and auto-add version to manpages Conflicts: docs/man/man1/ansible-playbook.1 docs/man/man1/ansible.1 Update %description 2012-04-17 14:31:29 +00:00			`:man version: %VERSION%`
Because everything should have a man page 2012-02-25 01:05:05 +00:00			`:man manual: System administration commands`

			`NAME`
			`----`
			`ansible - run a command somewhere else`


			`SYNOPSIS`
			`--------`
-p has been replaced by a required option. Various docs changes. 2012-03-02 03:10:47 +00:00			`ansible <host-pattern> [-f forks] [-m module_name] [-a args]`
Because everything should have a man page 2012-02-25 01:05:05 +00:00

			`DESCRIPTION`
			`-----------`

Manpage and doc updates 2012-02-28 07:51:19 +00:00			`Ansible is an extra-simple tool/framework/API for doing \'remote things' over`
Because everything should have a man page 2012-02-25 01:05:05 +00:00			`SSH.`


-p has been replaced by a required option. Various docs changes. 2012-03-02 03:10:47 +00:00			`ARGUMENTS`
			`---------`

Update constants.py to pull module path and the hosts file from the environment (ANSIBLE_{LIBRARY,HOSTS}) if defined. Update manpages to represent this. Also update the env-setup script to set ANSIBLE_{LIBRARY,HOSTS}. 2012-03-05 21:06:02 +00:00			`host-pattern::`
-p has been replaced by a required option. Various docs changes. 2012-03-02 03:10:47 +00:00
Show when options require arguments in the man pages. 2012-03-24 02:29:51 +00:00			`A name of a group in the inventory file, a shell-like glob selecting`
			`hosts in inventory file, or any combination of the two separated by`
			`semicolons.`
-p has been replaced by a required option. Various docs changes. 2012-03-02 03:10:47 +00:00
Because everything should have a man page 2012-02-25 01:05:05 +00:00			`OPTIONS`
			`-------`

Fully document the -v option. 2012-08-15 14:13:38 +00:00			`-v, --verbose::`

			`Verbose mode, more output from successful actions will be shown. Give`
			`up to three times for more output.`
Because everything should have a man page 2012-02-25 01:05:05 +00:00
Show when options require arguments in the man pages. 2012-03-24 02:29:51 +00:00			`-i 'PATH', --inventory='PATH'::`
Because everything should have a man page 2012-02-25 01:05:05 +00:00
Show when options require arguments in the man pages. 2012-03-24 02:29:51 +00:00			`The 'PATH' to the inventory hosts file, which defaults to '/etc/ansible/hosts'.`
Because everything should have a man page 2012-02-25 01:05:05 +00:00

Show when options require arguments in the man pages. 2012-03-24 02:29:51 +00:00			`-f 'NUM', --forks='NUM'::`
Because everything should have a man page 2012-02-25 01:05:05 +00:00
Show when options require arguments in the man pages. 2012-03-24 02:29:51 +00:00			`Level of parallelism. 'NUM' is specified as an integer, the default is 5.`
Because everything should have a man page 2012-02-25 01:05:05 +00:00
Update man pages and the message for an exception. 2012-07-06 02:21:57 +00:00			`--private-key='PRIVATE_KEY_FILE'::`

			`Use this file to authenticate the connection.`

Because everything should have a man page 2012-02-25 01:05:05 +00:00
Show when options require arguments in the man pages. 2012-03-24 02:29:51 +00:00			`-m 'NAME', --module-name='NAME'::`
Because everything should have a man page 2012-02-25 01:05:05 +00:00
Show when options require arguments in the man pages. 2012-03-24 02:29:51 +00:00			`Execute the module called 'NAME'.`
Because everything should have a man page 2012-02-25 01:05:05 +00:00

Show when options require arguments in the man pages. 2012-03-24 02:29:51 +00:00			`-M 'DIRECTORY', --module-path='DIRECTORY'::`
Because everything should have a man page 2012-02-25 01:05:05 +00:00
use the same text for -M in ansible.1 and ansible-playbook.1 2013-05-23 19:34:33 +00:00			`The 'DIRECTORY' search path to load modules from. The default is`
improve wording, thanks to Michael DeHaan 2013-05-25 06:53:20 +00:00			`'/usr/share/ansible'. This can also be set with the ANSIBLE_LIBRARY`
			`environment variable.`
Because everything should have a man page 2012-02-25 01:05:05 +00:00
Show when options require arguments in the man pages. 2012-03-24 02:29:51 +00:00			`-a \'_ARGUMENTS_', --args=\'_ARGUMENTS_'::`
Add manpage for ansible-playbook, since it is a command. More detailed docs will remain on the web site. 2012-03-10 03:06:44 +00:00
Show when options require arguments in the man pages. 2012-03-24 02:29:51 +00:00			`The 'ARGUMENTS' to pass to the module.`
Add manpage for ansible-playbook, since it is a command. More detailed docs will remain on the web site. 2012-03-10 03:06:44 +00:00
Fix man page option description indentation. 2012-04-17 15:39:51 +00:00			`-k, --ask-pass::`
Add manpage for ansible-playbook, since it is a command. More detailed docs will remain on the web site. 2012-03-10 03:06:44 +00:00
			`Prompt for the SSH password instead of assuming key-based authentication with ssh-agent.`

Fix man page option description indentation. 2012-04-17 15:39:51 +00:00			`-K, --ask-sudo-pass::`
Update manpages, fix missing variable assignment 2012-04-13 23:33:19 +00:00
			`Prompt for the password to use with --sudo, if any`
Add manpage for ansible-playbook, since it is a command. More detailed docs will remain on the web site. 2012-03-10 03:06:44 +00:00
Fix man page option description indentation. 2012-04-17 15:39:51 +00:00			`-o, --one-line::`
Add manpage for ansible-playbook, since it is a command. More detailed docs will remain on the web site. 2012-03-10 03:06:44 +00:00
			`Try to output everything on one line.`

Fix man page option description indentation. 2012-04-17 15:39:51 +00:00			`-s, --sudo::`
Update manpages, fix missing variable assignment 2012-04-13 23:33:19 +00:00
			`Run the command as the user given by -u and sudo to root.`
Add manpage for ansible-playbook, since it is a command. More detailed docs will remain on the web site. 2012-03-10 03:06:44 +00:00
Fix man page option description indentation. 2012-04-17 15:39:51 +00:00			`-t 'DIRECTORY', --tree='DIRECTORY'::`
Add manpage for ansible-playbook, since it is a command. More detailed docs will remain on the web site. 2012-03-10 03:06:44 +00:00
Show when options require arguments in the man pages. 2012-03-24 02:29:51 +00:00			`Save contents in this output 'DIRECTORY', with the results saved in a`
			`file named after each host.`
Add manpage for ansible-playbook, since it is a command. More detailed docs will remain on the web site. 2012-03-10 03:06:44 +00:00
Fix man page option description indentation. 2012-04-17 15:39:51 +00:00			`-T 'SECONDS', --timeout='SECONDS'::`
Add manpage for ansible-playbook, since it is a command. More detailed docs will remain on the web site. 2012-03-10 03:06:44 +00:00
Show when options require arguments in the man pages. 2012-03-24 02:29:51 +00:00			`Connection timeout to use when trying to talk to hosts, in 'SECONDS'.`
Add manpage for ansible-playbook, since it is a command. More detailed docs will remain on the web site. 2012-03-10 03:06:44 +00:00
Fix man page option description indentation. 2012-04-17 15:39:51 +00:00			`-B 'NUM', --background='NUM'::`
Add manpage for ansible-playbook, since it is a command. More detailed docs will remain on the web site. 2012-03-10 03:06:44 +00:00
Show when options require arguments in the man pages. 2012-03-24 02:29:51 +00:00			`Run commands in the background, killing the task after 'NUM' seconds.`
Add manpage for ansible-playbook, since it is a command. More detailed docs will remain on the web site. 2012-03-10 03:06:44 +00:00
Fix man page option description indentation. 2012-04-17 15:39:51 +00:00			`-P 'NUM', --poll='NUM'::`
add polling info to manpage 2012-03-12 01:09:44 +00:00
Show when options require arguments in the man pages. 2012-03-24 02:29:51 +00:00			`Poll a background job every 'NUM' seconds. Requires -B.`
add polling info to manpage 2012-03-12 01:09:44 +00:00
minor correction --remote-user= does not work: ansible: error: no such option: --remote-user --user= does. Updating docs 2013-10-31 22:56:52 +00:00			`-u 'USERNAME', --user='USERNAME'::`
Add manpage for ansible-playbook, since it is a command. More detailed docs will remain on the web site. 2012-03-10 03:06:44 +00:00
Correct -u description in ansible man page 2013-02-10 03:24:53 +00:00			`Use this remote 'USERNAME' instead of the current user.`
Because everything should have a man page 2012-02-25 01:05:05 +00:00
Update manpage to mention -U (--sudo-user). 2012-05-06 22:32:43 +00:00			`-U 'SUDO_USERNAME', --sudo-user='SUDO_USERNAME'::`

			`Sudo to 'SUDO_USERNAME' instead of root. Implies --sudo.`

Fix man page option description indentation. 2012-04-17 15:39:51 +00:00			`-c 'CONNECTION', --connection='CONNECTION'::`
Update ansible.1 manpage for option -c, --connection 2012-04-11 16:32:29 +00:00
Update man pages and the message for an exception. 2012-07-06 02:21:57 +00:00			`Connection type to use. Possible options are 'paramiko' (SSH), 'ssh',`
			`and 'local'. 'local' is mostly useful for crontab or kickstarts.`
Update ansible.1 manpage for option -c, --connection 2012-04-11 16:32:29 +00:00
Add --limit to manpage 2012-09-06 22:42:18 +00:00			`-l 'SUBSET', --limit='SUBSET'::`

			`Further limits the selected host/group patterns.`
Because everything should have a man page 2012-02-25 01:05:05 +00:00
Moved docs about "--limit=~REGEX" from man page to asciidoc. 2012-12-04 20:08:29 +00:00			`-l '\~REGEX', --limit='~REGEX'::`

			`Further limits hosts with a regex pattern.`

Add --list-hosts to man pages. Fixes #9574 2015-02-27 13:38:45 +00:00			`--list-hosts::`

			`Outputs a list of matching hosts; does not execute anything else.`

Because everything should have a man page 2012-02-25 01:05:05 +00:00			`INVENTORY`
			`---------`

			`Ansible stores the hosts it can potentially operate on in an inventory`
README/doc/example updates to go with group support and CLI option changes. Minimizing manpage until CLI options stabilize. 2012-03-02 02:18:32 +00:00			`file. The syntax is one host per line. Groups headers are allowed and`
Small change to previous patch, make ranges of hosts inclusive. 2012-07-25 00:10:05 +00:00			`are included on their own line, enclosed in square brackets that`
			`start the line.`

			`Ranges of hosts are also supported. For more information and`
Fix documentation url 2014-02-11 15:55:10 +00:00			`additional options, see the documentation on http://docs.ansible.com/.`
Because everything should have a man page 2012-02-25 01:05:05 +00:00
			`FILES`
			`-----`

Add manpage for ansible-playbook, since it is a command. More detailed docs will remain on the web site. 2012-03-10 03:06:44 +00:00			`/etc/ansible/hosts -- Default inventory file`
Because everything should have a man page 2012-02-25 01:05:05 +00:00
Add manpage for ansible-playbook, since it is a command. More detailed docs will remain on the web site. 2012-03-10 03:06:44 +00:00			`/usr/share/ansible/ -- Default module library`
Because everything should have a man page 2012-02-25 01:05:05 +00:00
- Fixed some typos for the ansible config file - added the ANSIBLE_CONFIG environment variable 2012-10-30 16:08:12 +00:00			`/etc/ansible/ansible.cfg -- Config file, used if present`
Add FILES to manpage 2012-10-12 21:31:13 +00:00
- Fixed some typos for the ansible config file - added the ANSIBLE_CONFIG environment variable 2012-10-30 16:08:12 +00:00			`~/.ansible.cfg -- User config file, overrides the default config if present`
Because everything should have a man page 2012-02-25 01:05:05 +00:00
Update constants.py to pull module path and the hosts file from the environment (ANSIBLE_{LIBRARY,HOSTS}) if defined. Update manpages to represent this. Also update the env-setup script to set ANSIBLE_{LIBRARY,HOSTS}. 2012-03-05 21:06:02 +00:00			`ENVIRONMENT`
			`-----------`

Minor grammar fix in manpages 2014-02-11 15:50:10 +00:00			`The following environment variables may be specified.`
Update constants.py to pull module path and the hosts file from the environment (ANSIBLE_{LIBRARY,HOSTS}) if defined. Update manpages to represent this. Also update the env-setup script to set ANSIBLE_{LIBRARY,HOSTS}. 2012-03-05 21:06:02 +00:00
			`ANSIBLE_HOSTS -- Override the default ansible hosts file`

			`ANSIBLE_LIBRARY -- Override the default ansible module library path`

- Fixed some typos for the ansible config file - added the ANSIBLE_CONFIG environment variable 2012-10-30 16:08:12 +00:00			`ANSIBLE_CONFIG -- Override the default ansible config file`

Update constants.py to pull module path and the hosts file from the environment (ANSIBLE_{LIBRARY,HOSTS}) if defined. Update manpages to represent this. Also update the env-setup script to set ANSIBLE_{LIBRARY,HOSTS}. 2012-03-05 21:06:02 +00:00
Because everything should have a man page 2012-02-25 01:05:05 +00:00			`AUTHOR`
			`------`

			`Ansible was originally written by Michael DeHaan. See the AUTHORS file`
			`for a complete list of contributors.`


			`COPYRIGHT`
			`---------`

			`Copyright © 2012, Michael DeHaan`

Relicensing to GPLv3, all previous committers ok'd on mailing list. 2012-02-29 00:08:09 +00:00			`Ansible is released under the terms of the GPLv3 License.`
Because everything should have a man page 2012-02-25 01:05:05 +00:00

			`SEE ALSO`
			`--------`

Mention of ansible-doc and man pages for modules. 2013-03-19 02:31:42 +00:00			`ansible-playbook(1), ansible-pull(1), ansible-doc(1)`
Fixup RPM building: Makefile, Spec File, .gitignore Fixup distutils: setup.py Clean old cruft: section 5 man pages 2012-03-10 19:02:25 +00:00
Update doc, irc and mailing list information in manpages input 2014-02-11 15:59:40 +00:00			`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>`