From e766bb6a6c13d0845a9a31d6a34da1b01a648c97 Mon Sep 17 00:00:00 2001 From: Michael DeHaan Date: Mon, 27 Feb 2012 22:49:14 -0500 Subject: [PATCH] update manpage output --- docs/man/man5/ansible-modules.5 | 35 +++++++++++++++++++++++++------- docs/man/man5/ansible-playbook.5 | 26 +++++++++++------------- 2 files changed, 40 insertions(+), 21 deletions(-) diff --git a/docs/man/man5/ansible-modules.5 b/docs/man/man5/ansible-modules.5 index 132ddba00b..7baf69b469 100644 --- a/docs/man/man5/ansible-modules.5 +++ b/docs/man/man5/ansible-modules.5 @@ -2,12 +2,12 @@ .\" Title: ansible-modules .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 02/26/2012 +.\" Date: 02/27/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" +.TH "ANSIBLE\-MODULES" "5" "02/27/2012" "Ansible\-modules 0\&.0\&.1" "System administration commands" .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- @@ -25,7 +25,9 @@ ansible-modules \- stock modules shipped with ansible 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\&. +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, as described in ansible\-playbooks (5)\&. +.sp +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\&. @@ -39,10 +41,10 @@ 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\&. +(Async command running and command execution time limits are in plan\&.) .SH "COPY" .sp -The copy module takes a list of source files +The copy module moves a file on the local box to remote locations\&. .PP \fBsrc=\fR .RS 4 @@ -72,8 +74,22 @@ In plan\&. .SH "GIT" .sp Deploys software from git checkouts\&. -.sp -This module is in plan\&. +.PP +\fBrepo=\fR +.RS 4 +git or http protocol address of the repo to checkout +.RE +.PP +\fBdest=\fR +.RS 4 +where to check it out, an absolute directory path +.RE +.PP +\fBversion=\fR +.RS 4 +what version to check out \(em either the git SHA, the literal string +\fIHEAD\fR, or a tag name +.RE .SH "OHAI" .sp Similar to the facter module, this returns JSON inventory data\&. Ohai data is a bit more verbose and nested than facter\&. @@ -115,6 +131,11 @@ Writes a JSON file containing key/value data, for use in templating\&. Call this 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 +.PP +\fBanything=\fR +.RS 4 +any other parameters can be named basically anything, and set a key=value pair in the JSON file for use in templating\&. +.RE .SH "TEMPLATE" .sp Templates a file out to a remote server\&. Call the setup module prior to usage\&. diff --git a/docs/man/man5/ansible-playbook.5 b/docs/man/man5/ansible-playbook.5 index aabea67071..5ec7a1cca9 100644 --- a/docs/man/man5/ansible-playbook.5 +++ b/docs/man/man5/ansible-playbook.5 @@ -2,12 +2,12 @@ .\" Title: ansible-modules .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 02/26/2012 +.\" Date: 02/27/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" +.TH "ANSIBLE\-MODULES" "5" "02/27/2012" "Ansible\-playbook 0\&.0\&.1" "System administration commands" .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- @@ -28,8 +28,6 @@ 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 -FIXME: verify this is correct below -.sp .if n \{\ .RS 4 .\} @@ -38,17 +36,17 @@ FIXME: verify this is correct below \- pattern: \'*\' hosts: \'/etc/ansible/hosts\' tasks: - \- name:configure template & module variables for future template calls + \- name: configure template & module variables for future template calls action: setup http_port=80 max_clients=200 \- name: write the apache config file - action: template src=/srv/mytemplates/httpd\&.j2 dest=/etc/httpd/conf + action: template src=/srv/templates/httpd\&.j2 dest=/etc/httpd/conf notify: \- restart apache \- name: ensure apache is running - action: service name=httpd ensure=started + action: service name=httpd state=started handlers: \- name: restart apache - \- action: service name=httpd ensure=restarted + \- action: service name=httpd state=restarted .fi .if n \{\ .RE @@ -59,9 +57,9 @@ 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\&. +Next, use a Jinja2 template locally residing at /srv/templates/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\&. +We\(cqll 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" @@ -70,14 +68,14 @@ Playbooks are executed top down and can contain multiple references to patterns\ .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 name/action pair describes what the task is and what ansible module to use to accomplish the task, along with any arguments\&. Additional fields like \fIcomment:\fR can be added and will be ignored\&. +For each task, a name/action pair describes what the task is and what ansible module to use to accomplish the task, along with any arguments\&. Additional fields like \fIcomment:\fR can be added and will be ignored, so feel free to take notes in the file\&. .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" +Handlers are like tasks, but are conditionally executed\&. If a module reports a \fIchange\fR, it can notify one or more handler by name\&. If notified, it will run only for hosts that changed\&. +.SH "ERROR HANDLING" .sp -What the playbook run does with a host when an error is detected is currently being refined and is subject to change\&. +If a host has a failure, the host will be ignored for the remainder of the playbook execution\&. .SH "AUTHOR" .sp Ansible was originally written by Michael DeHaan\&. See the AUTHORS file for a complete list of contributors\&.