archive
/
ansible
mirror of https://github.com/ansible/ansible.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #32 from tbielawa/DocsFixin

Browse Source 
Docs fixin
pull/3/head
Michael DeHaan 12 years ago
parent f7cff27f3d 6612772711
commit 5781e6e02f
9 changed files with 114 additions and 209 deletions
Show Stats Download Patch File Download Diff File

2
Makefile
Unescape Escape View File

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

6
docs/man/man1/ansible.1
Unescape Escape View File

@ -2,12 +2,12 @@
.\" Title: ansible
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\" 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,6 @@ Copyright \(co 2012, Michael DeHaan
Ansible is released under the terms of the MIT license\&.
.SH "SEE ALSO"
.sp
\fBansible\-modules\fR(5), \fBansible\-playbook\fR(5)
.sp
Ansible home page: https://github\&.com/mpdehaan/ansible/

4
docs/man/man1/ansible.1.asciidoc
Unescape Escape View File

@ -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: <https://github.com/mpdehaan/ansible/>

28
docs/man/man5/ansible-modules.5
Unescape Escape View File

@ -1,7 +1,7 @@
'\" t
.\" Title: ansible-modules
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\" Date: 02/26/2012
.\" Manual: System administration commands
.\" Source: Ansible-modules 0.0.1
@ -9,6 +9,15 @@
.\"
.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
@ -29,10 +38,11 @@ Most modules other than command are idempotent, meaning they will seek to avoid
.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"
.PP
Example usage
.RS 4
/sbin/shutdown \-t now
.RE
.sp
This module does not support change hooks\&.
.sp
@ -60,7 +70,7 @@ Runs the discovery program \fIfacter\fR on the remote system, returning JSON dat
.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\&.
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\&.
@ -86,7 +96,7 @@ A trivial test module, this module always returns the integer \fI1\fR on success
.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\&.
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\&.
@ -148,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(1) \- pending
\fBansible\-playbook\fR(5) \- pending
.sp
Ansible home page: https://github\&.com/mpdehaan/ansible/

22
docs/man/man5/ansible-modules.1.asciidoc → docs/man/man5/ansible-modules.5.asciidoc
Unescape Escape View File

@ -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
@ -202,8 +202,8 @@ for a complete list of contributors.
SEE ALSO
--------
ansible(1)
*ansible*(1)
ansible-playbook(1) - pending
*ansible-playbook*(5) - pending
Ansible home page: <https://github.com/mpdehaan/ansible/>

196
docs/man/man5/ansible-playbook.5
Unescape Escape View File

@ -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 <http://docbook.sf.net/>
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\" 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:
.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:
.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
.\}
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/

60
docs/man/man5/ansible-playbook.1.asciidoc → docs/man/man5/ansible-playbook.5.asciidoc
Unescape Escape View File

@ -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
@ -106,8 +114,8 @@ for a complete list of contributors.
SEE ALSO
--------
ansible(1)
*ansible*(1)
ansible-playbook(1) - pending
*ansible-playbook*(5) - pending
Ansible home page: <https://github.com/mpdehaan/ansible/>

1
examples/playbook.yml
Unescape Escape View File

@ -1,3 +1,4 @@
---
- pattern: '*'
hosts: /etc/ansible/hosts
tasks:

4
setup.py
Unescape Escape View File

@ -22,6 +22,10 @@ setup(name='ansible',
]),
('man/man1', [
'docs/man/man1/ansible.1'
]),
('man/man5', [
'docs/man/man5/ansible-modules.5',
'docs/man/man5/ansible-playbook.5'
])
],
scripts=[

Write Preview
Loading…
Cancel
Save