cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

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.

Browse source
This commit is contained in:
Tim Bielawa 2012-02-26 20:42:13 -05:00
parent 86bf871e07
commit b4fd0042f6
2 changed files with 175 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

165
docs/man/man5/ansible-modules.5 Normal file
View file

@ -0,0 +1,165 @@
'\" t
.\" Title: ansible-modules
.\" 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-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/

20
docs/man/man5/ansible-modules.5.asciidoc
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
@ -204,6 +204,6 @@ SEE ALSO
ansible(1)
ansible-playbook(1) - pending
ansible-playbook(5) - pending
Ansible home page: <https://github.com/mpdehaan/ansible/>