From 86bf871e0727f2777292c9be207a0534ab826aea Mon Sep 17 00:00:00 2001 From: Tim Bielawa Date: Sun, 26 Feb 2012 20:36:38 -0500 Subject: [PATCH 1/8] Fixup the naming of the docs. --- Makefile | 2 +- docs/man/man5/ansible-modules.5 | 155 ------------------ ....1.asciidoc => ansible-modules.5.asciidoc} | 0 3 files changed, 1 insertion(+), 156 deletions(-) delete mode 100644 docs/man/man5/ansible-modules.5 rename docs/man/man5/{ansible-modules.1.asciidoc => ansible-modules.5.asciidoc} (100%) diff --git a/Makefile b/Makefile index 428fc01b68..5a5e9f26d8 100644 --- a/Makefile +++ b/Makefile @@ -2,7 +2,7 @@ ASCII2MAN = a2x -D $(dir $@) -d manpage -f manpage $< ASCII2HTMLMAN = a2x -D docs/html/man/ -d manpage -f xhtml -MANPAGES := docs/man/man1/ansible.1 docs/man/man5/ansible-modules.1 docs/man/man5/ansible-playbook.1 +MANPAGES := docs/man/man1/ansible.1 docs/man/man5/ansible-modules.1 docs/man/man5/ansible-playbook.5 SITELIB = $(shell python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()") docs: manuals diff --git a/docs/man/man5/ansible-modules.5 b/docs/man/man5/ansible-modules.5 deleted file mode 100644 index 80dc1ef98a..0000000000 --- a/docs/man/man5/ansible-modules.5 +++ /dev/null @@ -1,155 +0,0 @@ -'\" t -.\" Title: ansible-modules -.\" Author: [see the "AUTHOR" section] -.\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 02/26/2012 -.\" Manual: System administration commands -.\" Source: Ansible-modules 0.0.1 -.\" Language: English -.\" -.TH "ANSIBLE\-MODULES" "5" "02/26/2012" "Ansible\-modules 0\&.0\&.1" "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-modules \- stock modules shipped with ansible -.SH "DESCRIPTION" -.sp -Ansible ships with a number of modules that can be executed directly on remote hosts or through ansible playbooks\&. -.SH "IDEMPOTENCE" -.sp -Most modules other than command are idempotent, meaning they will seek to avoid changes unless a change needs to be made\&. When using ansible playbooks, these modules can trigger change events\&. Unless otherwise noted, all modules support change hooks\&. -.SH "COMMAND" -.sp -The command module takes the command name followed by a list of arguments, space delimited\&. This is the only module that does not use key=value style parameters\&. -.sp -Example usage: -.sp -"/sbin/shutdown \-t now" -.sp -This module does not support change hooks\&. -.sp -Returns the return code from the program as well as timing information\&. -.sp -Async command running and command execution time limits are in plan\&. These will probably be special keyvalue parameters expressed on the end of the command line, like ANSTIMEOUT=1 and ANS_ASYNC=1 or similar\&. -.SH "COPY" -.sp -The copy module takes a list of source files -.PP -\fBsrc=\fR -.RS 4 -Local absolute path to a file to copy to the remote server -.RE -.PP -\fBdest=\fR -.RS 4 -Remote absolute path where the file should end up -.RE -.sp -This module also returns md5sum information about the resultant file\&. -.SH "FACTER" -.sp -Runs the discovery program \fIfacter\fR on the remote system, returning JSON data that can be useful for inventory purposes\&. -.sp -Requires that \fIfacter\fR and \fIruby\-json\fR be installed on the remote end\&. -.sp -This module is information only \- it takes no parameters & does not support change hooks, nor does it make any changes on the system\&. -.SH "FILE" -.sp -Ensures the ownership and permissions of files are as desired\&. -.sp -Use copy or template first if you need to make sure a file is on the box\&. -.sp -In plan\&. -.SH "GIT" -.sp -Deploys software from git checkouts\&. -.sp -This module is in plan\&. -.SH "OHAI" -.sp -Similar to the facter module, this returns JSON inventory data\&. Ohai data is a bit more verbose and nested than facter\&. -.sp -Requires that \fIohai\fR be installed on the remote end\&. -.sp -This module is information only \- it takes no parameters & does not support change hooks, nor does it make any changes on the system\&. -.SH "PING" -.sp -A trivial test module, this module always returns the integer \fI1\fR on successful contact\&. -.sp -This module does not support change hooks\&. -.sp -This module is information only \- it takes no parameters & does not support change hooks, nor does it make any changes on the system\&. -.SH "SERVICE" -.sp -Controls services on remote machines\&. -.PP -\fBensure=\fR -.RS 4 -Values are -\fIstarted\fR, -\fIstopped\fR, or -\fIrestarted\fR\&. Started/stopped are idempotent actions that will not run commands unless neccessary\&. -\fIrestarted\fR -will always bounce the service -.RE -.PP -\fBname=\fR -.RS 4 -The name of the service -.RE -.SH "SETUP" -.sp -Writes a JSON file containing key/value data, for use in templating\&. Call this once before using the template modules, usually as the very first step in your playbook\&. -.PP -\fBmetadata=\fR -.RS 4 -Optionally overrides the default JSON file location of /etc/ansible/setup\&. If used, also supply the metadata parameter to -\fItemplate\fR\&. Change if running as a non\-root remote user who does not have permissions on /etc/ansible\&. -.RE -.SH "TEMPLATE" -.sp -Templates a file out to a remote server\&. Call the setup module prior to usage\&. -.PP -\fBsrc=\fR -.RS 4 -path of a Jinja2 formatted template on the local server -.RE -.PP -\fBdest\fR -.RS 4 -location to render the template on the remote server -.RE -.PP -\fBmetadata\fR -.RS 4 -location of a JSON file to use to supply template data\&. Default is /etc/ansible/setup which is the same as the default for the setup module\&. Change if running as a non\-root remote user who does not have permissions on /etc/ansible\&. -.RE -.sp -This module also returns md5sum information about the resultant file\&. -.SH "USER" -.sp -This module is in plan\&. -.SH "YUM" -.sp -This module is in plan\&. -.SH "WRITING YOUR OWN MODULES" -.sp -To write your own modules, simply follow the convention of those already available in /usr/share/ansible\&. Modules must return JSON but can be written in any language\&. To support change hooks, modules should return hashes, with a changed: True/False element at the top level\&. Modules can also choose to indicate a failure scenario by returning a top level \fIfailure\fR element with a True value\&. -.SH "AUTHOR" -.sp -Ansible was originally written by Michael DeHaan\&. See the AUTHORS file for a complete list of contributors\&. -.SH "SEE ALSO" -.sp -ansible(1) -.sp -ansible\-playbook(1) \- pending -.sp -Ansible home page: https://github\&.com/mpdehaan/ansible/ diff --git a/docs/man/man5/ansible-modules.1.asciidoc b/docs/man/man5/ansible-modules.5.asciidoc similarity index 100% rename from docs/man/man5/ansible-modules.1.asciidoc rename to docs/man/man5/ansible-modules.5.asciidoc From b4fd0042f61c9164416e7336ec3195c1d1b35e39 Mon Sep 17 00:00:00 2001 From: Tim Bielawa Date: Sun, 26 Feb 2012 20:42:13 -0500 Subject: [PATCH 2/8] Fix up some wording/formatting in ansible-modyles.5. Also: Section 5 is for configuration, update the see-also to reflect this with respect to ansible-playbook. --- docs/man/man5/ansible-modules.5 | 165 +++++++++++++++++++++++ docs/man/man5/ansible-modules.5.asciidoc | 20 +-- 2 files changed, 175 insertions(+), 10 deletions(-) create mode 100644 docs/man/man5/ansible-modules.5 diff --git a/docs/man/man5/ansible-modules.5 b/docs/man/man5/ansible-modules.5 new file mode 100644 index 0000000000..b699ff4924 --- /dev/null +++ b/docs/man/man5/ansible-modules.5 @@ -0,0 +1,165 @@ +'\" t +.\" Title: ansible-modules +.\" Author: [see the "AUTHOR" section] +.\" Generator: DocBook XSL Stylesheets v1.76.1 +.\" Date: 02/26/2012 +.\" Manual: System administration commands +.\" Source: Ansible-modules 0.0.1 +.\" Language: English +.\" +.TH "ANSIBLE\-MODULES" "5" "02/26/2012" "Ansible\-modules 0\&.0\&.1" "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-modules \- stock modules shipped with ansible +.SH "DESCRIPTION" +.sp +Ansible ships with a number of modules that can be executed directly on remote hosts or through ansible playbooks\&. +.SH "IDEMPOTENCE" +.sp +Most modules other than command are idempotent, meaning they will seek to avoid changes unless a change needs to be made\&. When using ansible playbooks, these modules can trigger change events\&. Unless otherwise noted, all modules support change hooks\&. +.SH "COMMAND" +.sp +The command module takes the command name followed by a list of arguments, space delimited\&. This is the only module that does not use key=value style parameters\&. +.PP +Example usage +.RS 4 +/sbin/shutdown \-t now +.RE +.sp +This module does not support change hooks\&. +.sp +Returns the return code from the program as well as timing information\&. +.sp +Async command running and command execution time limits are in plan\&. These will probably be special keyvalue parameters expressed on the end of the command line, like ANSTIMEOUT=1 and ANS_ASYNC=1 or similar\&. +.SH "COPY" +.sp +The copy module takes a list of source files +.PP +\fBsrc=\fR +.RS 4 +Local absolute path to a file to copy to the remote server +.RE +.PP +\fBdest=\fR +.RS 4 +Remote absolute path where the file should end up +.RE +.sp +This module also returns md5sum information about the resultant file\&. +.SH "FACTER" +.sp +Runs the discovery program \fIfacter\fR on the remote system, returning JSON data that can be useful for inventory purposes\&. +.sp +Requires that \fIfacter\fR and \fIruby\-json\fR be installed on the remote end\&. +.sp +This module is informative only \- it takes no parameters & does not support change hooks, nor does it make any changes on the system\&. +.SH "FILE" +.sp +Ensures the ownership and permissions of files are as desired\&. +.sp +Use copy or template first if you need to make sure a file is on the box\&. +.sp +In plan\&. +.SH "GIT" +.sp +Deploys software from git checkouts\&. +.sp +This module is in plan\&. +.SH "OHAI" +.sp +Similar to the facter module, this returns JSON inventory data\&. Ohai data is a bit more verbose and nested than facter\&. +.sp +Requires that \fIohai\fR be installed on the remote end\&. +.sp +This module is information only \- it takes no parameters & does not support change hooks, nor does it make any changes on the system\&. +.SH "PING" +.sp +A trivial test module, this module always returns the integer \fI1\fR on successful contact\&. +.sp +This module does not support change hooks\&. +.sp +This module is informative only \- it takes no parameters & does not support change hooks, nor does it make any changes on the system\&. +.SH "SERVICE" +.sp +Controls services on remote machines\&. +.PP +\fBensure=\fR +.RS 4 +Values are +\fIstarted\fR, +\fIstopped\fR, or +\fIrestarted\fR\&. Started/stopped are idempotent actions that will not run commands unless neccessary\&. +\fIrestarted\fR +will always bounce the service +.RE +.PP +\fBname=\fR +.RS 4 +The name of the service +.RE +.SH "SETUP" +.sp +Writes a JSON file containing key/value data, for use in templating\&. Call this once before using the template modules, usually as the very first step in your playbook\&. +.PP +\fBmetadata=\fR +.RS 4 +Optionally overrides the default JSON file location of /etc/ansible/setup\&. If used, also supply the metadata parameter to +\fItemplate\fR\&. Change if running as a non\-root remote user who does not have permissions on /etc/ansible\&. +.RE +.SH "TEMPLATE" +.sp +Templates a file out to a remote server\&. Call the setup module prior to usage\&. +.PP +\fBsrc=\fR +.RS 4 +path of a Jinja2 formatted template on the local server +.RE +.PP +\fBdest\fR +.RS 4 +location to render the template on the remote server +.RE +.PP +\fBmetadata\fR +.RS 4 +location of a JSON file to use to supply template data\&. Default is /etc/ansible/setup which is the same as the default for the setup module\&. Change if running as a non\-root remote user who does not have permissions on /etc/ansible\&. +.RE +.sp +This module also returns md5sum information about the resultant file\&. +.SH "USER" +.sp +This module is in plan\&. +.SH "YUM" +.sp +This module is in plan\&. +.SH "WRITING YOUR OWN MODULES" +.sp +To write your own modules, simply follow the convention of those already available in /usr/share/ansible\&. Modules must return JSON but can be written in any language\&. To support change hooks, modules should return hashes, with a changed: True/False element at the top level\&. Modules can also choose to indicate a failure scenario by returning a top level \fIfailure\fR element with a True value\&. +.SH "AUTHOR" +.sp +Ansible was originally written by Michael DeHaan\&. See the AUTHORS file for a complete list of contributors\&. +.SH "SEE ALSO" +.sp +ansible(1) +.sp +ansible\-playbook(5) \- pending +.sp +Ansible home page: https://github\&.com/mpdehaan/ansible/ diff --git a/docs/man/man5/ansible-modules.5.asciidoc b/docs/man/man5/ansible-modules.5.asciidoc index 7a1724fba6..6e3b1a2296 100644 --- a/docs/man/man5/ansible-modules.5.asciidoc +++ b/docs/man/man5/ansible-modules.5.asciidoc @@ -32,9 +32,9 @@ command The command module takes the command name followed by a list of arguments, space delimited. This is the only module that does not use key=value style parameters. -Example usage: +Example usage:: -"/sbin/shutdown -t now" +/sbin/shutdown -t now This module does not support change hooks. @@ -70,7 +70,7 @@ JSON data that can be useful for inventory purposes. Requires that 'facter' and 'ruby-json' be installed on the remote end. -This module is information only - it takes no parameters & does not support change hooks, +This module is informative only - it takes no parameters & does not support change hooks, nor does it make any changes on the system. @@ -95,13 +95,13 @@ This module is in plan. ohai ---- -Similar to the facter module, this returns JSON inventory data. Ohai data -is a bit more verbose and nested than facter. +Similar to the facter module, this returns JSON inventory data. Ohai +data is a bit more verbose and nested than facter. Requires that 'ohai' be installed on the remote end. -This module is information only - it takes no parameters & does not support change hooks, -nor does it make any changes on the system. +This module is information only - it takes no parameters & does not +support change hooks, nor does it make any changes on the system. ping @@ -112,8 +112,8 @@ successful contact. This module does not support change hooks. -This module is information only - it takes no parameters & does not support change hooks, -nor does it make any changes on the system. +This module is informative only - it takes no parameters & does not +support change hooks, nor does it make any changes on the system. service @@ -204,6 +204,6 @@ SEE ALSO ansible(1) -ansible-playbook(1) - pending +ansible-playbook(5) - pending Ansible home page: From d44e0bbb6197f2a21d7f6f7aa0079af42408a306 Mon Sep 17 00:00:00 2001 From: Tim Bielawa Date: Sun, 26 Feb 2012 20:45:20 -0500 Subject: [PATCH 3/8] Update the python setup script to install the ansible modules man page. --- setup.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/setup.py b/setup.py index 0749f73a8f..088c18db3f 100644 --- a/setup.py +++ b/setup.py @@ -22,6 +22,9 @@ setup(name='ansible', ]), ('man/man1', [ 'docs/man/man1/ansible.1' + ]), + ('man/man5', [ + 'docs/man/man5/ansible-modules.5' ]) ], scripts=[ From cdbc2168c117835a583ce2b73c2fc09277b47364 Mon Sep 17 00:00:00 2001 From: Tim Bielawa Date: Sun, 26 Feb 2012 21:01:29 -0500 Subject: [PATCH 4/8] Fix makefile manpage targets --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 5a5e9f26d8..93759b6009 100644 --- a/Makefile +++ b/Makefile @@ -2,7 +2,7 @@ ASCII2MAN = a2x -D $(dir $@) -d manpage -f manpage $< ASCII2HTMLMAN = a2x -D docs/html/man/ -d manpage -f xhtml -MANPAGES := docs/man/man1/ansible.1 docs/man/man5/ansible-modules.1 docs/man/man5/ansible-playbook.5 +MANPAGES := docs/man/man1/ansible.1 docs/man/man5/ansible-modules.5 docs/man/man5/ansible-playbook.5 SITELIB = $(shell python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()") docs: manuals From 9680de37c97c7e4362f7236fad4ce600e74ecd87 Mon Sep 17 00:00:00 2001 From: Tim Bielawa Date: Sun, 26 Feb 2012 21:03:18 -0500 Subject: [PATCH 5/8] Manpages formatting --- docs/man/man1/ansible.1 | 8 ++++++-- docs/man/man1/ansible.1.asciidoc | 4 +--- docs/man/man5/ansible-modules.5.asciidoc | 4 ++-- docs/man/man5/ansible-playbook.1.asciidoc | 4 ++-- 4 files changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/man/man1/ansible.1 b/docs/man/man1/ansible.1 index 7ff7233b0e..7e05a2f9a5 100644 --- a/docs/man/man1/ansible.1 +++ b/docs/man/man1/ansible.1 @@ -2,12 +2,12 @@ .\" Title: ansible .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets v1.76.1 -.\" Date: 02/24/2012 +.\" Date: 02/26/2012 .\" Manual: System administration commands .\" Source: Ansible 0.0.1 .\" Language: English .\" -.TH "ANSIBLE" "1" "02/24/2012" "Ansible 0\&.0\&.1" "System administration commands" +.TH "ANSIBLE" "1" "02/26/2012" "Ansible 0\&.0\&.1" "System administration commands" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -105,4 +105,8 @@ Copyright \(co 2012, Michael DeHaan Ansible is released under the terms of the MIT license\&. .SH "SEE ALSO" .sp +ansible\-modules (5) +.sp +ansible\-playbook (5) +.sp Ansible home page: https://github\&.com/mpdehaan/ansible/ diff --git a/docs/man/man1/ansible.1.asciidoc b/docs/man/man1/ansible.1.asciidoc index ae32d3cb71..da2d429345 100644 --- a/docs/man/man1/ansible.1.asciidoc +++ b/docs/man/man1/ansible.1.asciidoc @@ -106,8 +106,6 @@ Ansible is released under the terms of the MIT license. SEE ALSO -------- -ansible-modules (5) - -ansible-playbook (5) +*ansible-modules*(5), *ansible-playbook*(5) Ansible home page: diff --git a/docs/man/man5/ansible-modules.5.asciidoc b/docs/man/man5/ansible-modules.5.asciidoc index 6e3b1a2296..f82ae6ed5c 100644 --- a/docs/man/man5/ansible-modules.5.asciidoc +++ b/docs/man/man5/ansible-modules.5.asciidoc @@ -202,8 +202,8 @@ for a complete list of contributors. SEE ALSO -------- -ansible(1) +*ansible*(1) -ansible-playbook(5) - pending +*ansible-playbook*(5) - pending Ansible home page: diff --git a/docs/man/man5/ansible-playbook.1.asciidoc b/docs/man/man5/ansible-playbook.1.asciidoc index 04212cbc87..3568447217 100644 --- a/docs/man/man5/ansible-playbook.1.asciidoc +++ b/docs/man/man5/ansible-playbook.1.asciidoc @@ -106,8 +106,8 @@ for a complete list of contributors. SEE ALSO -------- -ansible(1) +*ansible*(1) -ansible-playbook(1) - pending +*ansible-playbook*(5) - pending Ansible home page: From afc7f4d246fc41be60af5abd6262ec79f252a533 Mon Sep 17 00:00:00 2001 From: Tim Bielawa Date: Sun, 26 Feb 2012 21:03:55 -0500 Subject: [PATCH 6/8] This is configuration, not command. Rename to section 5 --- .../{ansible-playbook.1.asciidoc => ansible-playbook.5.asciidoc} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/man/man5/{ansible-playbook.1.asciidoc => ansible-playbook.5.asciidoc} (100%) diff --git a/docs/man/man5/ansible-playbook.1.asciidoc b/docs/man/man5/ansible-playbook.5.asciidoc similarity index 100% rename from docs/man/man5/ansible-playbook.1.asciidoc rename to docs/man/man5/ansible-playbook.5.asciidoc From 6027c16ddd85339b9ceec39370a1e50df93f71e7 Mon Sep 17 00:00:00 2001 From: Tim Bielawa Date: Sun, 26 Feb 2012 21:04:38 -0500 Subject: [PATCH 7/8] Update distutils setup script to install the new manual page --- setup.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/setup.py b/setup.py index 088c18db3f..a88c213ad9 100644 --- a/setup.py +++ b/setup.py @@ -24,7 +24,8 @@ setup(name='ansible', 'docs/man/man1/ansible.1' ]), ('man/man5', [ - 'docs/man/man5/ansible-modules.5' + 'docs/man/man5/ansible-modules.5', + 'docs/man/man5/ansible-playbook.5' ]) ], scripts=[ From 66127727110532ed943724904e79c4d82bb41874 Mon Sep 17 00:00:00 2001 From: Tim Bielawa Date: Sun, 26 Feb 2012 21:09:56 -0500 Subject: [PATCH 8/8] Update man pages. Fix formatting in playbook example. Also, YAML documents by definition start with '---', so I have added this to the example and the manpage --- docs/man/man1/ansible.1 | 4 +- docs/man/man5/ansible-modules.5 | 4 +- docs/man/man5/ansible-playbook.5 | 196 +++++----------------- docs/man/man5/ansible-playbook.5.asciidoc | 56 ++++--- examples/playbook.yml | 1 + 5 files changed, 75 insertions(+), 186 deletions(-) diff --git a/docs/man/man1/ansible.1 b/docs/man/man1/ansible.1 index 7e05a2f9a5..23fd3d48df 100644 --- a/docs/man/man1/ansible.1 +++ b/docs/man/man1/ansible.1 @@ -105,8 +105,6 @@ Copyright \(co 2012, Michael DeHaan Ansible is released under the terms of the MIT license\&. .SH "SEE ALSO" .sp -ansible\-modules (5) -.sp -ansible\-playbook (5) +\fBansible\-modules\fR(5), \fBansible\-playbook\fR(5) .sp Ansible home page: https://github\&.com/mpdehaan/ansible/ diff --git a/docs/man/man5/ansible-modules.5 b/docs/man/man5/ansible-modules.5 index b699ff4924..5ab7966999 100644 --- a/docs/man/man5/ansible-modules.5 +++ b/docs/man/man5/ansible-modules.5 @@ -158,8 +158,8 @@ To write your own modules, simply follow the convention of those already availab Ansible was originally written by Michael DeHaan\&. See the AUTHORS file for a complete list of contributors\&. .SH "SEE ALSO" .sp -ansible(1) +\fBansible\fR(1) .sp -ansible\-playbook(5) \- pending +\fBansible\-playbook\fR(5) \- pending .sp Ansible home page: https://github\&.com/mpdehaan/ansible/ diff --git a/docs/man/man5/ansible-playbook.5 b/docs/man/man5/ansible-playbook.5 index 83bf903f14..02904edc2c 100644 --- a/docs/man/man5/ansible-playbook.5 +++ b/docs/man/man5/ansible-playbook.5 @@ -1,7 +1,7 @@ '\" t .\" Title: ansible-modules -.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] -.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Author: [see the "AUTHOR" section] +.\" Generator: DocBook XSL Stylesheets v1.76.1 .\" Date: 02/26/2012 .\" Manual: System administration commands .\" Source: Ansible-playbook 0.0.1 @@ -9,6 +9,15 @@ .\" .TH "ANSIBLE\-MODULES" "5" "02/26/2012" "Ansible\-playbook 0\&.0\&.1" "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 @@ -28,163 +37,33 @@ Ansible ships with a ansible\-playbook tool for running playbooks\&. Playbooks c Playbooks are currently writeable in YAML\&. Other formats (JSON?) may be supported in the future\&. .SH "EXAMPLE" .sp +.if n \{\ .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c .\} -.el \{\ -.sp -1 -.IP \(bu 2.3 -.\} -pattern: -\fI*\fR -hosts: -\fI/etc/ansible/hosts\fR -tasks: +.nf +\-\-\- +\- pattern: \*(Aq*\*(Aq + hosts: \*(Aq/etc/ansible/hosts\*(Aq + tasks: + \- do: + \- configure template & module variables for future template calls + \- setup http_port=80 max_clients=200 + \- do: + \- write the apache config file + \- template src=/srv/mytemplates/httpd\&.j2 dest=/etc/httpd/conf + notify: + \- restart apache + \- do + \- ensure apache is running + \- service name=httpd ensure=started + handlers: + \- do: + \- restart apache + \- service name=httpd ensure=restarted +.fi +.if n \{\ .RE -.sp -.RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c .\} -.el \{\ -.sp -1 -.IP \(bu 2.3 -.\} -do: -.RE -.sp -.RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -.sp -1 -.IP \(bu 2.3 -.\} -configure template & module variables for future template calls -.RE -.sp -.RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -.sp -1 -.IP \(bu 2.3 -.\} -setup http_port=80 max_clients=200 -.RE -.sp -.RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -.sp -1 -.IP \(bu 2.3 -.\} -do: -.RE -.sp -.RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -.sp -1 -.IP \(bu 2.3 -.\} -write the apache config file -.RE -.sp -.RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -.sp -1 -.IP \(bu 2.3 -.\} -template src=/srv/mytemplates/httpd\&.j2 dest=/etc/httpd/conf notify: -.RE -.sp -.RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -.sp -1 -.IP \(bu 2.3 -.\} -restart apache -.RE -.sp -.RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -.sp -1 -.IP \(bu 2.3 -.\} -do -.RE -.sp -.RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -.sp -1 -.IP \(bu 2.3 -.\} -ensure apache is running -.RE -.sp -.RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -.sp -1 -.IP \(bu 2.3 -.\} -service name=httpd ensure=started handlers: -.RE -.sp -.RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -.sp -1 -.IP \(bu 2.3 -.\} -do: -.RE -.sp -.RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -.sp -1 -.IP \(bu 2.3 -.\} -restart apache -.RE -.sp -.RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -.sp -1 -.IP \(bu 2.3 -.\} -service name=httpd ensure=restarted -.RE .SH "WHAT THE EXAMPLE MEANS" .sp Here\(cqs what the above example will do\&. @@ -212,10 +91,13 @@ Handlers are like tasks, but are conditionally executed\&. If a module reports a .SH "FUTURE BEHAVIOR" .sp What the playbook run does with a host when an error is detected is currently being refined and is subject to change\&. +.SH "AUTHOR" +.sp +Ansible was originally written by Michael DeHaan\&. See the AUTHORS file for a complete list of contributors\&. .SH "SEE ALSO" .sp -ansible(1) +\fBansible\fR(1) .sp -ansible\-playbook(1) \- pending +\fBansible\-playbook\fR(5) \- pending .sp Ansible home page: https://github\&.com/mpdehaan/ansible/ diff --git a/docs/man/man5/ansible-playbook.5.asciidoc b/docs/man/man5/ansible-playbook.5.asciidoc index 3568447217..a01025a85a 100644 --- a/docs/man/man5/ansible-playbook.5.asciidoc +++ b/docs/man/man5/ansible-playbook.5.asciidoc @@ -14,19 +14,23 @@ ansible-playbook - format and function of an ansible playbook file DESCRIPTION ----------- -Ansible ships with a ansible-playbook tool for running playbooks. Playbooks can represent -frequent tasks, desired system configurations, or deployment processes. +Ansible ships with a ansible-playbook tool for running playbooks. +Playbooks can represent frequent tasks, desired system configurations, +or deployment processes. FORMAT ------ -Playbooks are currently writeable in YAML. Other formats (JSON?) may be supported in the future. +Playbooks are currently writeable in YAML. Other formats (JSON?) may +be supported in the future. EXAMPLE ------- +[literal] +--- - pattern: '*' hosts: '/etc/ansible/hosts' tasks: @@ -52,48 +56,52 @@ WHAT THE EXAMPLE MEANS Here's what the above example will do. -For all hosts in /etc/ansible/hosts (one host per line) that are named 'webserver-anything', first -write a JSON file into /etc/ansible/setup on each remote system with the values -max_clients and http_port. +For all hosts in /etc/ansible/hosts (one host per line) that are named +'webserver-anything', first write a JSON file into /etc/ansible/setup +on each remote system with the values max_clients and http_port. -Next, use a Jinja2 template locally residing -at /srv/mytemplates/httpd.j2 to write the Apache config file on each host +Next, use a Jinja2 template locally residing at +/srv/mytemplates/httpd.j2 to write the Apache config file on each host to the path /etc/httpd/conf, using the previous values. Ensure that apache is running if stopped. -If and only if the config file changed, note that we need to restart apache at the end of -the run, otherwise, don't bother because we already know it is running. +If and only if the config file changed, note that we need to restart +apache at the end of the run, otherwise, don't bother because we +already know it is running. HIGH LEVEL EXPLANATION ---------------------- -Playbooks are executed top down and can contain multiple references to patterns. -For instance, a playbook could do something to all webservers, then do something -to all database servers, then do something different to all webservers again. +Playbooks are executed top down and can contain multiple references to +patterns. For instance, a playbook could do something to all +webservers, then do something to all database servers, then do +something different to all webservers again. -For each pattern, the tasks in the 'tasks' list are executed in order for all -hosts in the host file matching the pattern. +For each pattern, the tasks in the 'tasks' list are executed in order +for all hosts in the host file matching the pattern. -For each task, a "do" statement describes what the task is and what ansible -module to use to accomplish the task, along with any arguments. The first -line in the "do" is the name of the task -- this will appear in any log output. +For each task, a "do" statement describes what the task is and what +ansible module to use to accomplish the task, along with any +arguments. The first line in the "do" is the name of the task -- this +will appear in any log output. -The second line in each "do" is the module name followed by module arguments. +The second line in each "do" is the module name followed by module +arguments. Most modules accept key=value format arguments. -Handlers are like tasks, but are conditionally executed. If a module reports -a 'change', it can choose to notify a handler by name. If notified, it will -run only for hosts that changed. +Handlers are like tasks, but are conditionally executed. If a module +reports a 'change', it can choose to notify a handler by name. If +notified, it will run only for hosts that changed. FUTURE BEHAVIOR --------------- -What the playbook run does with a host when an error is detected is currently being refined -and is subject to change. +What the playbook run does with a host when an error is detected is +currently being refined and is subject to change. AUTHOR diff --git a/examples/playbook.yml b/examples/playbook.yml index 70277eca93..05228c21e1 100644 --- a/examples/playbook.yml +++ b/examples/playbook.yml @@ -1,3 +1,4 @@ +--- - pattern: '*' hosts: /etc/ansible/hosts tasks: