ansible/docs/man/man1/ansible-playbook.1

'\" t
.\"     Title: ansible-playbook
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\"      Date: 06/03/2013
.\"    Manual: System administration commands
.\"    Source: Ansible 1.2
.\"  Language: English
.\"
.TH "ANSIBLE\-PLAYBOOK" "1" "06/03/2013" "Ansible 1\&.2" "System administration commands"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
ansible-playbook \- run an ansible playbook
.SH "SYNOPSIS"
.sp
ansible\-playbook <filename\&.yml> \&... [options]
.SH "DESCRIPTION"
.sp
\fBAnsible playbooks\fR are a configuration and multinode deployment system\&. Ansible\-playbook is the tool used to run them\&. See the project home page (link below) for more information\&.
.SH "ARGUMENTS"
.PP
\fBfilename\&.yml\fR
.RS 4
The names of one or more YAML format files to run as ansible playbooks\&.
.RE
.SH "OPTIONS"
.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\-i\fR \fIPATH\fR, \fB\-\-inventory=\fR\fIPATH\fR
.RS 4
The
\fIPATH\fR
to the inventory hosts file, which defaults to
\fI/etc/ansible/hosts\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\-e\fR \fIVARS\fR, \fB\-\-extra\-vars=\fR\fIVARS\fR
.RS 4
Extra variables to inject into a playbook, in key=value key=value format or as quoted JSON (hashes and arrays)\&.
.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\-k\fR, \fB\-\-ask\-pass\fR
.RS 4
Prompt for the SSH password instead of assuming key\-based authentication with ssh\-agent\&.
.RE
.PP
\fB\-K\fR, \fB\-\-ask\-sudo\-pass\fR
.RS 4
Prompt for the password to use for playbook plays that request sudo access, if any\&.
.RE
.PP
\fB\-U\fR, \fISUDO_USER\fR, \fB\-\-sudo\-user=\fR\fISUDO_USER\fR
.RS 4
Desired sudo user (default=root)\&.
.RE
.PP
\fB\-\-tags\fR
.RS 4
Run only these tags from the playbook
.RE
.PP
\fB\-\-syntax\-check\fR
.RS 4
Look for syntax errors in the playbook, but don\(cqt run anything
.RE
.PP
\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\-\-diff\fR
.RS 4
When changing any templated files, show the unified diffs of how they changed\&. When used with \-\-check, shows how the files would have changed if \-\-check were not used\&.
.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\-s\fR, \fB\-\-sudo\fR
.RS 4
Force all plays to use sudo, even if not marked as such\&.
.RE
.PP
\fB\-u\fR \fIUSERNAME\fR, \fB\-\-remote\-user=\fR\fIUSERNAME\fR
.RS 4
Use this remote user name on playbook steps that do not indicate a user name to run as\&.
.RE
.PP
\fB\-c\fR \fICONNECTION\fR, \fB\-\-connection=\fR\fICONNECTION\fR
.RS 4
Connection type to use\&. Possible options are
\fIparamiko\fR
(SSH),
\fIssh\fR, and
\fIlocal\fR\&.
\fIlocal\fR
is mostly useful for crontab or kickstarts\&.
.RE
.PP
\fB\-l\fR \fISUBSET\fR, \fB\-\-limit=\fR\fISUBSET\fR
.RS 4
Further limits the selected host/group patterns\&.
.RE
.SH "ENVIRONMENT"
.sp
The following environment variables may specified\&.
.sp
ANSIBLE_HOSTS  \(em Override the default ansible hosts file
.sp
ANSIBLE_LIBRARY \(em Override the default ansible module library path
.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
.sp
Ansible is released under the terms of the GPLv3 License\&.
.SH "SEE ALSO"
.sp
\fBansible\fR(1), \fBansible\-pull\fR(1), \fBansible\-doc\fR(1)
.sp
Extensive documentation as well as IRC and mailing list info is available on the ansible home page: https://ansible\&.github\&.com/
host file must be marked config(noreplace), update rpm build to use checked in manpage src 2012-03-31 15:08:42 +00:00			`'\" t`
			`.\" Title: ansible-playbook`
			`.\" Author: [see the "AUTHOR" section]`
Add --limit to manpage 2012-09-06 22:42:18 +00:00			`.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>`
Disable inventory test 2013-06-03 15:52:42 +00:00			`.\" Date: 06/03/2013`
host file must be marked config(noreplace), update rpm build to use checked in manpage src 2012-03-31 15:08:42 +00:00			`.\" Manual: System administration commands`
Update release version. 2013-04-03 00:47:57 +00:00			`.\" Source: Ansible 1.2`
host file must be marked config(noreplace), update rpm build to use checked in manpage src 2012-03-31 15:08:42 +00:00			`.\" Language: English`
			`.\"`
Disable inventory test 2013-06-03 15:52:42 +00:00			`.TH "ANSIBLE\-PLAYBOOK" "1" "06/03/2013" "Ansible 1\&.2" "System administration commands"`
host file must be marked config(noreplace), update rpm build to use checked in manpage src 2012-03-31 15:08:42 +00:00			`.\" -----------------------------------------------------------------`
			`.\" * set default formatting`
			`.\" -----------------------------------------------------------------`
			`.\" disable hyphenation`
			`.nh`
			`.\" disable justification (adjust text to left margin only)`
			`.ad l`
			`.\" -----------------------------------------------------------------`
			`.\" * MAIN CONTENT STARTS HERE *`
			`.\" -----------------------------------------------------------------`
			`.SH "NAME"`
			`ansible-playbook \- run an ansible playbook`
			`.SH "SYNOPSIS"`
			`.sp`
			`ansible\-playbook <filename\&.yml> \&... [options]`
			`.SH "DESCRIPTION"`
			`.sp`
			`\fBAnsible playbooks\fR are a configuration and multinode deployment system\&. Ansible\-playbook is the tool used to run them\&. See the project home page (link below) for more information\&.`
			`.SH "ARGUMENTS"`
			`.PP`
			`\fBfilename\&.yml\fR`
			`.RS 4`
			`The names of one or more YAML format files to run as ansible playbooks\&.`
			`.RE`
			`.SH "OPTIONS"`
Fully document the -v option. 2012-08-15 14:13:38 +00:00			`.PP`
Remove the -D module debug flag, which no longer is functional due to sudo pty requirements, and replace with -v/--verbose. This flag will show playbook output from non-failing commands. -v is also added to /usr/bin/ansible, but not yet used. I also gutted some internals code dealing with 'invocations' which allowed the callback to know what module invoked it. This is not something 0.5 does or needed, so callbacks have been simplified. 2012-06-20 01:55:57 +00:00			`\fB\-v\fR, \fB\-\-verbose\fR`
Fully document the -v option. 2012-08-15 14:13:38 +00:00			`.RS 4`
			`Verbose mode, more output from successful actions will be shown\&. Give up to three times for more output\&.`
			`.RE`
host file must be marked config(noreplace), update rpm build to use checked in manpage src 2012-03-31 15:08:42 +00:00			`.PP`
Show when options require arguments in the man pages. 2012-03-24 02:29:51 +00:00			`\fB\-i\fR \fIPATH\fR, \fB\-\-inventory=\fR\fIPATH\fR`
host file must be marked config(noreplace), update rpm build to use checked in manpage src 2012-03-31 15:08:42 +00:00			`.RS 4`
Show when options require arguments in the man pages. 2012-03-24 02:29:51 +00:00			`The`
			`\fIPATH\fR`
			`to the inventory hosts file, which defaults to`
			`\fI/etc/ansible/hosts\fR\&.`
host file must be marked config(noreplace), update rpm build to use checked in manpage src 2012-03-31 15:08:42 +00:00			`.RE`
			`.PP`
Show when options require arguments in the man pages. 2012-03-24 02:29:51 +00:00			`\fB\-M\fR \fIDIRECTORY\fR, \fB\-\-module\-path=\fR\fIDIRECTORY\fR`
host file must be marked config(noreplace), update rpm build to use checked in manpage src 2012-03-31 15:08:42 +00:00			`.RS 4`
Show when options require arguments in the man pages. 2012-03-24 02:29:51 +00:00			`The`
			`\fIDIRECTORY\fR`
Manpage tweaks, docs rebuild 2013-05-29 14:30:04 +00:00			`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\&.`
host file must be marked config(noreplace), update rpm build to use checked in manpage src 2012-03-31 15:08:42 +00:00			`.RE`
			`.PP`
Reinstate --extra-vars, which can do things in playbooks like: ansible-playbook release-my-app.yml --extra-vars="version=123" And make $version available in the playbook without re-editing the file 2012-04-26 23:56:10 +00:00			`\fB\-e\fR \fIVARS\fR, \fB\-\-extra\-vars=\fR\fIVARS\fR`
			`.RS 4`
Disable inventory test 2013-06-03 15:52:42 +00:00			`Extra variables to inject into a playbook, in key=value key=value format or as quoted JSON (hashes and arrays)\&.`
Reinstate --extra-vars, which can do things in playbooks like: ansible-playbook release-my-app.yml --extra-vars="version=123" And make $version available in the playbook without re-editing the file 2012-04-26 23:56:10 +00:00			`.RE`
			`.PP`
Show when options require arguments in the man pages. 2012-03-24 02:29:51 +00:00			`\fB\-f\fR \fINUM\fR, \fB\-\-forks=\fR\fINUM\fR`
host file must be marked config(noreplace), update rpm build to use checked in manpage src 2012-03-31 15:08:42 +00:00			`.RS 4`
Show when options require arguments in the man pages. 2012-03-24 02:29:51 +00:00			`Level of parallelism\&.`
			`\fINUM\fR`
			`is specified as an integer, the default is 5\&.`
host file must be marked config(noreplace), update rpm build to use checked in manpage src 2012-03-31 15:08:42 +00:00			`.RE`
			`.PP`
			`\fB\-k\fR, \fB\-\-ask\-pass\fR`
			`.RS 4`
			`Prompt for the SSH password instead of assuming key\-based authentication with ssh\-agent\&.`
			`.RE`
			`.PP`
manpage updates 2012-04-13 23:40:40 +00:00			`\fB\-K\fR, \fB\-\-ask\-sudo\-pass\fR`
			`.RS 4`
Add some docs/examples Add a basic ansible-pull man page. Add the example playbooks/scripts to the RPM package. Closes #841 2012-08-14 14:46:16 +00:00			`Prompt for the password to use for playbook plays that request sudo access, if any\&.`
			`.RE`
			`.PP`
			`\fB\-U\fR, \fISUDO_USER\fR, \fB\-\-sudo\-user=\fR\fISUDO_USER\fR`
			`.RS 4`
			`Desired sudo user (default=root)\&.`
manpage updates 2012-04-13 23:40:40 +00:00			`.RE`
			`.PP`
update manpage for new options. 2013-02-16 20:38:59 +00:00			`\fB\-\-tags\fR`
			`.RS 4`
			`Run only these tags from the playbook`
			`.RE`
			`.PP`
align manpages with actual code for --syntax-check 2013-03-05 23:42:53 +00:00			`\fB\-\-syntax\-check\fR`
update manpage for new options. 2013-02-16 20:38:59 +00:00			`.RS 4`
			`Look for syntax errors in the playbook, but don\(cqt run anything`
			`.RE`
			`.PP`
			`\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\-\-diff\fR`
			`.RS 4`
			`When changing any templated files, show the unified diffs of how they changed\&. When used with \-\-check, shows how the files would have changed if \-\-check were not used\&.`
			`.RE`
			`.PP`
Show when options require arguments in the man pages. 2012-03-24 02:29:51 +00:00			`\fB\-T\fR \fISECONDS\fR, \fB\-\-timeout=\fR\fISECONDS\fR`
host file must be marked config(noreplace), update rpm build to use checked in manpage src 2012-03-31 15:08:42 +00:00			`.RS 4`
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`
			`\fISECONDS\fR\&.`
host file must be marked config(noreplace), update rpm build to use checked in manpage src 2012-03-31 15:08:42 +00:00			`.RE`
manpage updates 2012-04-13 23:40:40 +00:00			`.PP`
Update docs to reflect --port going away and --sudo and --remote-user being added to ansible-playbook 2012-04-17 02:22:37 +00:00			`\fB\-s\fR, \fB\-\-sudo\fR`
Fix man page option description indentation. 2012-04-17 15:39:51 +00:00			`.RS 4`
Update docs to reflect --port going away and --sudo and --remote-user being added to ansible-playbook 2012-04-17 02:22:37 +00:00			`Force all plays to use sudo, even if not marked as such\&.`
Fix man page option description indentation. 2012-04-17 15:39:51 +00:00			`.RE`
			`.PP`
Update docs to reflect --port going away and --sudo and --remote-user being added to ansible-playbook 2012-04-17 02:22:37 +00:00			`\fB\-u\fR \fIUSERNAME\fR, \fB\-\-remote\-user=\fR\fIUSERNAME\fR`
Fix man page option description indentation. 2012-04-17 15:39:51 +00:00			`.RS 4`
Update docs to reflect --port going away and --sudo and --remote-user being added to ansible-playbook 2012-04-17 02:22:37 +00:00			`Use this remote user name on playbook steps that do not indicate a user name to run as\&.`
Fix man page option description indentation. 2012-04-17 15:39:51 +00:00			`.RE`
Add some docs/examples Add a basic ansible-pull man page. Add the example playbooks/scripts to the RPM package. Closes #841 2012-08-14 14:46:16 +00:00			`.PP`
			`\fB\-c\fR \fICONNECTION\fR, \fB\-\-connection=\fR\fICONNECTION\fR`
			`.RS 4`
			`Connection type to use\&. Possible options are`
			`\fIparamiko\fR`
			`(SSH),`
			`\fIssh\fR, and`
			`\fIlocal\fR\&.`
			`\fIlocal\fR`
			`is mostly useful for crontab or kickstarts\&.`
			`.RE`
Add --limit to manpage 2012-09-06 22:42:18 +00:00			`.PP`
			`\fB\-l\fR \fISUBSET\fR, \fB\-\-limit=\fR\fISUBSET\fR`
			`.RS 4`
			`Further limits the selected host/group patterns\&.`
			`.RE`
host file must be marked config(noreplace), update rpm build to use checked in manpage src 2012-03-31 15:08:42 +00:00			`.SH "ENVIRONMENT"`
			`.sp`
			`The following environment variables may specified\&.`
			`.sp`
			`ANSIBLE_HOSTS \(em Override the default ansible hosts file`
			`.sp`
			`ANSIBLE_LIBRARY \(em Override the default ansible module library path`
HP and vsphere modules are crazy awesome but I am thinking these belong in contrib not core. 2012-10-12 21:49:48 +00:00			`.SH "FILES"`
			`.sp`
			`/etc/ansible/hosts \(em Default inventory file`
			`.sp`
			`/usr/share/ansible/ \(em Default module library`
			`.sp`
Manpage documentation ALSO should be sorted 2012-11-03 22:54:38 +00:00			`/etc/ansible/ansible\&.cfg \(em Config file, used if present`
HP and vsphere modules are crazy awesome but I am thinking these belong in contrib not core. 2012-10-12 21:49:48 +00:00			`.sp`
Manpage documentation ALSO should be sorted 2012-11-03 22:54:38 +00:00			`~/\&.ansible\&.cfg \(em User config file, overrides the default config if present`
host file must be marked config(noreplace), update rpm build to use checked in manpage src 2012-03-31 15:08:42 +00:00			`.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`
			`.sp`
			`Ansible is released under the terms of the GPLv3 License\&.`
			`.SH "SEE ALSO"`
			`.sp`
Update release version. 2013-04-03 00:47:57 +00:00			`\fBansible\fR(1), \fBansible\-pull\fR(1), \fBansible\-doc\fR(1)`
host file must be marked config(noreplace), update rpm build to use checked in manpage src 2012-03-31 15:08:42 +00:00			`.sp`
			`Extensive documentation as well as IRC and mailing list info is available on the ansible home page: https://ansible\&.github\&.com/`