<htmlxmlns="http://www.w3.org/1999/xhtml"><head><metahttp-equiv="Content-Type"content="text/html; charset=UTF-8"/><title>ansible-modules</title><linkrel="stylesheet"type="text/css"href="./docbook-xsl.css"/><metaname="generator"content="DocBook XSL Stylesheets V1.76.1"/></head><body><divxml:lang="en"class="refentry"title="ansible-modules"lang="en"><aid="id475130"></a><divclass="titlepage"></div><divclass="refnamediv"><h2>Name</h2><p>ansible-modules — stock modules shipped with ansible</p></div><divclass="refsect1"title="DESCRIPTION"><aid="_description"></a><h2>DESCRIPTION</h2><p>Ansible ships with a number of modules that can be executed directly on remote hosts or through
ansible playbooks.</p></div><divclass="refsect1"title="IDEMPOTENCE"><aid="_idempotence"></a><h2>IDEMPOTENCE</h2><p>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 <spanclass="strong"><strong>ansible-playbooks</strong></span>(5).</p><p>Unless otherwise noted, all modules support change hooks.</p></div><divclass="refsect1"title="command"><aid="_command"></a><h2>command</h2><p>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.</p><divclass="variablelist"><dl><dt><spanclass="term">
Example usage
</span></dt><dd>
/sbin/shutdown -t now
</dd></dl></div><p>This module does not support change hooks.</p><p>Returns the return code from the program as well as timing information.</p><p>(Async command running and command execution time limits are in plan.)</p></div><divclass="refsect1"title="copy"><aid="_copy"></a><h2>copy</h2><p>The copy module moves a file on the local box to remote locations.</p><divclass="variablelist"><dl><dt><spanclass="term">
<spanclass="strong"><strong>src=</strong></span>
</span></dt><dd>
Local absolute path to a file to copy to the remote server
</dd><dt><spanclass="term">
<spanclass="strong"><strong>dest=</strong></span>
</span></dt><dd>
Remote absolute path where the file should end up
</dd></dl></div><p>This module also returns md5sum information about the resultant file.</p></div><divclass="refsect1"title="facter"><aid="_facter"></a><h2>facter</h2><p>Runs the discovery program <spanclass="emphasis"><em>facter</em></span> on the remote system, returning
JSON data that can be useful for inventory purposes.</p><p>Requires that <spanclass="emphasis"><em>facter</em></span> and <spanclass="emphasis"><em>ruby-json</em></span> be installed on the remote end.</p><p>This module is informative only - it takes no parameters & does not support change hooks,
nor does it make any changes on the system.</p></div><divclass="refsect1"title="file"><aid="_file"></a><h2>file</h2><p>Ensures the ownership and permissions of files are as desired.</p><p>Use copy or template first if you need to make sure a file is on the box.</p><p>In plan.</p></div><divclass="refsect1"title="git"><aid="_git"></a><h2>git</h2><p>Deploys software from git checkouts.</p><divclass="variablelist"><dl><dt><spanclass="term">
<spanclass="strong"><strong>repo=</strong></span>
</span></dt><dd>
git or http protocol address of the repo to checkout
what version to check out—either the git SHA, the literal string <spanclass="emphasis"><em>HEAD</em></span>, or a tag name
</dd></dl></div></div><divclass="refsect1"title="ohai"><aid="_ohai"></a><h2>ohai</h2><p>Similar to the facter module, this returns JSON inventory data. Ohai
data is a bit more verbose and nested than facter.</p><p>Requires that <spanclass="emphasis"><em>ohai</em></span> be installed on the remote end.</p><p>This module is information only - it takes no parameters & does not
support change hooks, nor does it make any changes on the system.</p></div><divclass="refsect1"title="ping"><aid="_ping"></a><h2>ping</h2><p>A trivial test module, this module always returns the integer <spanclass="emphasis"><em>1</em></span> on
successful contact.</p><p>This module does not support change hooks.</p><p>This module is informative only - it takes no parameters & does not
support change hooks, nor does it make any changes on the system.</p></div><divclass="refsect1"title="service"><aid="_service"></a><h2>service</h2><p>Controls services on remote machines.</p><divclass="variablelist"><dl><dt><spanclass="term">
Values are <spanclass="emphasis"><em>started</em></span>, <spanclass="emphasis"><em>stopped</em></span>, or <spanclass="emphasis"><em>restarted</em></span>. Started/stopped
are idempotent actions that will not run commands unless neccessary.
<spanclass="emphasis"><em>restarted</em></span> will always bounce the service
</dd><dt><spanclass="term">
<spanclass="strong"><strong>name=</strong></span>
</span></dt><dd>
The name of the service
</dd></dl></div></div><divclass="refsect1"title="setup"><aid="_setup"></a><h2>setup</h2><p>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.</p><p>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 <spanclass="emphasis"><em>facter_</em></span> and 'ohai_" so it’s easy to tell their source.</p><divclass="variablelist"><dl><dt><spanclass="term">
any other parameters can be named basically anything, and set a key=value
pair in the JSON file for use in templating.
</dd></dl></div></div><divclass="refsect1"title="template"><aid="_template"></a><h2>template</h2><p>Templates a file out to a remote server. Call the setup module prior to usage.</p><divclass="variablelist"><dl><dt><spanclass="term">
<spanclass="strong"><strong>src=</strong></span>
</span></dt><dd>
path of a Jinja2 formatted template on the local server
</dd><dt><spanclass="term">
<spanclass="strong"><strong>dest</strong></span>
</span></dt><dd>
location to render the template on the remote server
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.
</dd></dl></div><p>This module also returns md5sum information about the resultant file.</p></div><divclass="refsect1"title="user"><aid="_user"></a><h2>user</h2><p>This module is in plan.</p></div><divclass="refsect1"title="yum"><aid="_yum"></a><h2>yum</h2><p>This module is in plan.</p></div><divclass="refsect1"title="WRITING YOUR OWN MODULES"><aid="_writing_your_own_modules"></a><h2>WRITING YOUR OWN MODULES</h2><p>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 <spanclass="emphasis"><em>failure</em></span> element with a True value.</p></div><divclass="refsect1"title="ENVIRONMENT"><aid="_environment"></a><h2>ENVIRONMENT</h2><p>ANSIBLE_LIBRARY—Override the default ansible module library path</p></div><divclass="refsect1"title="AUTHOR"><aid="_author"></a><h2>AUTHOR</h2><p>Ansible was originally written by Michael DeHaan. See the AUTHORS file
for a complete list of contributors.</p></div><divclass="refsect1"title="SEE ALSO"><aid="_see_also"></a><h2>SEE ALSO</h2><p><spanclass="strong"><strong>ansible</strong></span>(1)</p><p><spanclass="strong"><strong>ansible-playbook</strong></span>(5)</p><p>Ansible home page: <aclass="ulink"href="https://github.com/mpdehaan/ansible/"target="_top">https://github.com/mpdehaan/ansible/</a></p></div></div></body></html>
