diff --git a/docs/man/man5/ansible-modules.5 b/docs/man/man5/ansible-modules.5 new file mode 100644 index 00000000000..61a13dac57b --- /dev/null +++ b/docs/man/man5/ansible-modules.5 @@ -0,0 +1,150 @@ +'\" 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\&. +.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\&. It makes no changes on the remote system\&. +.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\&. +.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 but makes no changes on the remote system\&. +.sp +Requires that \fIohai\fR be installed on the remote end\&. +.sp +This module takes no parameters & does not support change hooks\&. +.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\&. +.sp +This module does not support change hooks\&. +.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\&. +.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\&. +.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 can be easily created using the +\fIsetup\fR +module\&. +.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/