Added stub for ansible-playbook (format) docs. Docs on ansible-playbook script TBD once

written.

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
+MANPAGES := docs/man/man1/ansible.1 docs/man/man5/ansible-modules.1 docs/man/man5/ansible-playbook.1
 SITELIB = $(shell python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()")
 
 docs: manuals

docs/man/man5/ansible-modules.5

@@ -38,7 +38,7 @@ 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\&.
+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
@@ -56,11 +56,18 @@ Remote absolute path where the file should end up
 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\&. It makes no changes on the remote system\&.
+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 takes no parameters & 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\&.
+.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\&.
@@ -68,16 +75,18 @@ Deploys software from git checkouts\&.
 This module is in plan\&.
 .SH "OHAI"
 .sp
-Similar to the facter module, this returns JSON inventory data but makes no changes on the remote system\&.
+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 takes no parameters & 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\&.
 .SH "PING"
 .sp
-A trivial test module, this module always returns the integer \fI1\fR on successful contact\&. It makes no changes on the remote system\&.
+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\&.
@@ -103,10 +112,8 @@ Writes a JSON file containing key/value data, for use in templating\&. Call this
 \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\&.
+\fItemplate\fR\&. Change if running as a non\-root remote user who does not have permissions on /etc/ansible\&.
 .RE
-.sp
-Does not support change hooks yet, but in plan\&.
 .SH "TEMPLATE"
 .sp
 Templates a file out to a remote server\&. Call the setup module prior to usage\&.
@@ -123,9 +130,7 @@ location to render the template on the remote server
 .PP
 \fBmetadata\fR
 .RS 4
-location of a JSON file to use to supply template data\&. Default is /etc/ansible/setup which can be easily created using the
+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\&.
-\fIsetup\fR
-module\&.
 .RE
 .sp
 This module also returns md5sum information about the resultant file\&.

docs/man/man5/ansible-playbook.1.asciidoc

@@ -0,0 +1,113 @@
+ansible-modules(5)
+=================
+:doctype:manpage
+:man source: Ansible-playbook
+:man version: 0.0.1
+:man manual: System administration commands
+
+
+NAME
+----
+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.
+
+
+FORMAT
+------
+
+Playbooks are currently writeable in YAML.  Other formats (JSON?) may be supported in the future.
+
+
+EXAMPLE
+-------
+
+- pattern: '*'
+  hosts: '/etc/ansible/hosts'
+  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
+
+
+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.
+
+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.
+
+
+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.
+
+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.
+
+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.
+
+
+FUTURE BEHAVIOR
+---------------
+
+What the playbook run does with a host when an error is detected is currently being refined
+and is subject to change. 
+
+
+AUTHOR
+------
+
+Ansible was originally written by Michael DeHaan. See the AUTHORS file
+for a complete list of contributors.
+
+
+SEE ALSO
+--------
+
+ansible(1)
+
+ansible-playbook(1) - pending
+
+Ansible home page: <https://github.com/mpdehaan/ansible/>

docs/man/man5/ansible-playbook.5

@@ -0,0 +1,221 @@
+'\" t
+.\"     Title: ansible-modules
+.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
+.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
+.\"      Date: 02/26/2012
+.\"    Manual: System administration commands
+.\"    Source: Ansible-playbook 0.0.1
+.\"  Language: English
+.\"
+.TH "ANSIBLE\-MODULES" "5" "02/26/2012" "Ansible\-playbook 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-playbook \- format and function of an ansible playbook file
+.SH "DESCRIPTION"
+.sp
+Ansible ships with a ansible\-playbook tool for running playbooks\&. Playbooks can represent frequent tasks, desired system configurations, or deployment processes\&.
+.SH "FORMAT"
+.sp
+Playbooks are currently writeable in YAML\&. Other formats (JSON?) may be supported in the future\&.
+.SH "EXAMPLE"
+.sp
+.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:
+.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\&.
+.sp
+For all hosts in /etc/ansible/hosts (one host per line) that are named \fIwebserver\-anything\fR, first write a JSON file into /etc/ansible/setup on each remote system with the values max_clients and http_port\&.
+.sp
+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\&.
+.sp
+Ensure that apache is running if stopped\&.
+.sp
+If and only if the config file changed, note that we need to restart apache at the end of the run, otherwise, don\(cqt bother because we already know it is running\&.
+.SH "HIGH LEVEL EXPLANATION"
+.sp
+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\&.
+.sp
+For each pattern, the tasks in the \fItasks\fR list are executed in order for all hosts in the host file matching the pattern\&.
+.sp
+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 \(em this will appear in any log output\&.
+.sp
+The second line in each "do" is the module name followed by module arguments\&.
+.sp
+Most modules accept key=value format arguments\&.
+.sp
+Handlers are like tasks, but are conditionally executed\&. If a module reports a \fIchange\fR, it can choose to notify a handler by name\&. If notified, it will run only for hosts that changed\&.
+.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 "SEE ALSO"
+.sp
+ansible(1)
+.sp
+ansible\-playbook(1) \- pending
+.sp
+Ansible home page: https://github\&.com/mpdehaan/ansible/