From 77a7ddeebc8c6035e5b4eb70a52a1df158a35991 Mon Sep 17 00:00:00 2001 From: Michael DeHaan Date: Sun, 26 Feb 2012 18:52:42 -0500 Subject: [PATCH] Add start of documentation for modules --- Makefile | 2 +- docs/man/man5/ansible-modules.1.asciidoc | 195 +++++++++++++++++++++++ 2 files changed, 196 insertions(+), 1 deletion(-) create mode 100644 docs/man/man5/ansible-modules.1.asciidoc diff --git a/Makefile b/Makefile index dca3a50308a..946af4abad2 100644 --- a/Makefile +++ b/Makefile @@ -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 +MANPAGES := docs/man/man1/ansible.1 docs/man/man5/ansible-modules.1 SITELIB = $(shell python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()") docs: manuals diff --git a/docs/man/man5/ansible-modules.1.asciidoc b/docs/man/man5/ansible-modules.1.asciidoc new file mode 100644 index 00000000000..26d9fa99683 --- /dev/null +++ b/docs/man/man5/ansible-modules.1.asciidoc @@ -0,0 +1,195 @@ +ansible-modules(5) +================= +:doctype:manpage +:man source: Ansible-modules +:man version: 0.0.1 +:man manual: System administration commands + + +NAME +---- +ansible-modules - stock modules shipped with ansible + + +DESCRIPTION +----------- + +Ansible ships with a number of modules that can be executed directly on remote hosts or through +ansible playbooks. + + +IDEMPOTENCE +----------- + +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. + + +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: + +"/sbin/shutdown -t now" + +This module does not support change hooks. + +Returns the return code from the program as well as timing information. + +Async command running and command execution time limits are in plan. + + +copy +---- + +The copy module takes a list of source files + +*src=*:: + +Local absolute path to a file to copy to the remote server + + +*dest=*:: + +Remote absolute path where the file should end up + + +This module also returns md5sum information about the resultant file. + + +facter +------ + +Runs the discovery program 'facter' on the remote system, returning +JSON data that can be useful for inventory purposes. It makes +no changes on the remote system. + +Requires that 'facter' and 'ruby-json' be installed on the remote end. + +This module takes no parameters & does not support change hooks. + + +git +--- + +Deploys software from git checkouts. + +This module is in plan. + + +ohai +---- + +Similar to the facter module, this returns JSON inventory data but +makes no changes on the remote system. + +Requires that 'ohai' be installed on the remote end. + +This module takes no parameters & does not support change hooks. + + +ping +---- + +A trivial test module, this module always returns the integer '1' on +successful contact. It makes no changes on the remote system. + +This module does not support change hooks. + + +service +------- + +Controls services on remote machines. + +*ensure=*:: + +Values are 'started', 'stopped', or 'restarted'. Started/stopped +are idempotent actions that will not run commands unless neccessary. +'restarted' will always bounce the service + + +*name=*:: + +The name of the service + + +setup +----- + +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. + +*metadata=*:: + +Optionally overrides the default JSON file location of /etc/ansible/setup. +If used, also supply the metadata parameter to 'template'. + + +Does not support change hooks yet, but in plan. + + +template +-------- + +Templates a file out to a remote server. Call the setup module prior to usage. + +*src=*:: + +path of a Jinja2 formatted template on the local server + + +*dest*:: + +location to render the template on the remote server + + +*metadata*:: + +location of a JSON file to use to supply template data. Default is /etc/ansible/setup +which can be easily created using the 'setup' module. + + +This module also returns md5sum information about the resultant file. + + +user +---- + +This module is in plan. + + +yum +--- + +This module is in plan. + + +WRITING YOUR OWN MODULES +------------------------ + +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 'failure' element with a True value. + +AUTHOR +------ + +Ansible was originally written by Michael DeHaan. See the AUTHORS file +for a complete list of contributors. + +SEE ALSO +-------- + +ansible(1) + +ansible-playbook(1) - pending + +Ansible home page: