'\" t .\" Title: ansible-modules .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 .\" Date: 02/27/2012 .\" Manual: System administration commands .\" Source: Ansible-modules 0.0.1 .\" Language: English .\" .TH "ANSIBLE\-MODULES" "5" "02/27/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, 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\&. .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\&.) .SH "COPY" .sp The copy module moves a file on the local box to remote locations\&. .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\&. .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\&. .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 \fBstate=\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\&. .sp If facter or ohai are installed, variables from these programs will also be snapshotted into the JSON file for usage in templating\&. These variables are prefixed with \fIfacter_\fR and \'ohai_" so it\(cqs easy to tell their source\&. .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 .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\&. .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 \fBansible\fR(1) .sp \fBansible\-playbook\fR(5) \- pending .sp Ansible home page: https://github\&.com/mpdehaan/ansible/