<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Ansible Modules &mdash; Ansible - SSH-Based Configuration Management &amp; Deployment</title>
    <link rel="stylesheet" href="_static/default.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <link rel="stylesheet" href="_static/bootstrap.css" type="text/css" />
    <link rel="stylesheet" href="_static/bootstrap-sphinx.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '',
        VERSION:     '0.01',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <script type="text/javascript" src="_static/bootstrap-dropdown.js"></script>
    <script type="text/javascript" src="_static/bootstrap-scrollspy.js"></script>
    <link rel="top" title="Ansible - SSH-Based Configuration Management &amp; Deployment" href="index.html" />
    <link rel="next" title="YAML Syntax" href="YAMLSyntax.html" />
    <link rel="prev" title="Command Line Examples" href="examples.html" />
<script type="text/javascript">
(function () {
  /**
   * Patch TOC list.
   *
   * Will mutate the underlying span to have a correct ul for nav.
   *
   * @param $span: Span containing nested UL's to mutate.
   * @param minLevel: Starting level for nested lists. (1: global, 2: local).
   */
  var patchToc = function ($span, minLevel) {
    var $tocList = $("<ul/>").attr('class', "dropdown-menu"),
      findA;

    // Find all a "internal" tags, traversing recursively.
    findA = function ($elem, level) {
      var level = level || 0,
        $items = $elem.find("> li > a.internal, > ul, > li > ul");

      // Iterate everything in order.
      $items.each(function (index, item) {
        var $item = $(item),
          tag = item.tagName.toLowerCase(),
          pad = 10 + ((level - minLevel) * 10);

        if (tag === 'a' && level >= minLevel) {
          // Add to existing padding.
          $item.css('padding-left', pad + "px");
          // Add list element.
          $tocList.append($("<li/>").append($item));
        } else if (tag === 'ul') {
          // Recurse.
          findA($item, level + 1);
        }
      });
    };

    // Start construction and return.
    findA($span);

    // Wipe out old list and patch in new one.
    return $span.empty("ul").append($tocList);
  };

  $(document).ready(function () {
    // Patch the global and local TOC's to be bootstrap-compliant.
    patchToc($("span.globaltoc"), 1);
    patchToc($("span.localtoc"), 2);

    // Activate.
    $('#topbar').dropdown();
  });
}());
</script>
<script type="text/javascript">

 var _gaq = _gaq || [];
 _gaq.push(['_setAccount', 'UA-29861888-1']);
 _gaq.push(['_trackPageview']);

 (function() {
   var ga = document.createElement('script'); ga.type =
'text/javascript'; ga.async = true;
   ga.src = ('https:' == document.location.protocol ? 'https://ssl' :
'http://www') + '.google-analytics.com/ga.js';
   var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(ga, s);
 })();

</script>

  </head>
  <body>
  <div class="topbar" data-scrollspy="scrollspy" >
    <div class="topbar-inner">
      <div class="container">
        <a class="brand" href="index.html">Ansible</a>
        <ul class="nav">
          
            <li class="dropdown" data-dropdown="dropdown">
  <a href="index.html"
     class="dropdown-toggle">Chapter</a>
  <span class="globaltoc"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="gettingstarted.html">Downloads &amp; Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="patterns.html">The Inventory File, Patterns, and Groups</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Command Line Examples</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="">Ansible Modules</a></li>
<li class="toctree-l1"><a class="reference internal" href="YAMLSyntax.html">YAML Syntax</a></li>
<li class="toctree-l1"><a class="reference internal" href="playbooks.html">Playbooks</a></li>
<li class="toctree-l1"><a class="reference internal" href="api.html">API &amp; Integrations</a></li>
<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a></li>
<li class="toctree-l1"><a class="reference internal" href="man.html">Man Pages</a></li>
</ul>
</span>
</li>
            <li class="dropdown" data-dropdown="dropdown">
  <a href="#"
     class="dropdown-toggle">Page</a>
  <span class="localtoc"><ul>
<li><a class="reference internal" href="#">Ansible Modules</a><ul>
<li><a class="reference internal" href="#command">command</a></li>
<li><a class="reference internal" href="#copy">copy</a></li>
<li><a class="reference internal" href="#facter">facter</a></li>
<li><a class="reference internal" href="#file">file</a></li>
<li><a class="reference internal" href="#git">git</a></li>
<li><a class="reference internal" href="#ohai">ohai</a></li>
<li><a class="reference internal" href="#ping">ping</a></li>
<li><a class="reference internal" href="#service">service</a></li>
<li><a class="reference internal" href="#setup">setup</a></li>
<li><a class="reference internal" href="#shell">shell</a></li>
<li><a class="reference internal" href="#template">template</a></li>
<li><a class="reference internal" href="#yum">yum</a></li>
<li><a class="reference internal" href="#writing-your-own-modules">Writing your own modules</a></li>
</ul>
</li>
</ul>
</span>
</li>
          
        </ul>
        <ul class="nav secondary-nav">
          
            
<form class="pull-left" action="search.html" method="get">
  <input type="text" name="q" placeholder="Search" />
  <input type="hidden" name="check_keywords" value="yes" />
  <input type="hidden" name="area" value="default" />
</form>
          
        </ul>
      </div>
    </div>
  </div>


<div class="container">
   
  <div class="section" id="ansible-modules">
<h1>Ansible Modules<a class="headerlink" href="#ansible-modules" title="Permalink to this headline">¶</a></h1>
<p>Ansible ships with a number of modules (called the &#8216;module library&#8217;)
that can be executed directly on remote hosts or through <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>.
Users can also write their own modules.   These modules can control system
resources, like services, packages, or files (anything really), or
handle executing system commands.</p>
<p>Let&#8217;s review how we execute three different modules from the command line:</p>
<div class="highlight-python"><pre>ansible webservers -m service -a "name=httpd state=running"
ansible webservers -m ping
ansible webservers -m command -a "/sbin/reboot -t now"</pre>
</div>
<p>Each module supports taking arguments.  Nearly all modules take <tt class="docutils literal"><span class="pre">key=value</span></tt>
arguments, space delimited.  Some modules take
no arguments, and the command/shell modules simply take the string
of the command you want to run.</p>
<p>From playbooks, Ansible modules are executed in a very similar way:</p>
<div class="highlight-python"><pre>- name: reboot the servers
  action: command /sbin/reboot -t now</pre>
</div>
<p>All modules technically return JSON format data, though if you are using the
command line or playbooks, you don&#8217;t really need to know much about
that.  If you&#8217;re writing your own module, you care, and this means you do
not have to write modules in any particular language &#8211; you get tho choose.</p>
<p>Most modules other than command are <cite>idempotent</cite>, meaning they will seek
to avoid changes to the system unless a change needs to be made.  When using ansible
playbooks, these modules can trigger &#8216;change events&#8217;.  Unless otherwise
noted, any given module does support change hooks.</p>
<p>Let&#8217;s see what&#8217;s available in the Ansible module library, out of the box:</p>
<div class="section" id="command">
<span id="id1"></span><h2>command<a class="headerlink" href="#command" title="Permalink to this headline">¶</a></h2>
<p>The command module takes the command name followed by a list of
arguments, space delimited.</p>
<p>If you want to run a command through the shell (say you are using
&#8216;&lt;&#8217;, &#8216;&gt;&#8217;, &#8216;|&#8217;, etc), you actually want the &#8216;shell&#8217; module instead.
The &#8216;command&#8217; module is much more secure as it&#8217;s not affected by the user&#8217;s environment.</p>
<p>Example usage:</p>
<div class="highlight-python"><pre>/sbin/shutdown -t now</pre>
</div>
<p>The given command will be executed on all selected nodes.  It will not
be processed through the shell, so variables like &#8220;$HOME&#8221; and
operations like &#8220;&lt;&#8221;, &#8220;&gt;&#8221;, &#8220;|&#8221;, and &#8220;&amp;&#8221; will not work.  As such, all
paths to commands must be fully qualified.</p>
<p>This module does not support change hooks and returns the return code
from the program as well as timing information about how long the
command was running for.</p>
</div>
<div class="section" id="copy">
<span id="id2"></span><h2>copy<a class="headerlink" href="#copy" title="Permalink to this headline">¶</a></h2>
<p>The copy module moves a file on the local box to remote locations.  In addition to the options
listed below, the arguments available to the <cite>file</cite> module can also be passed to the copy
module.</p>
<p><em>src</em>:</p>
<ul class="simple">
<li>Local path to a file to copy to the remote server.  This can be an
absolute or relative path.</li>
</ul>
<p><em>dest</em>:</p>
<ul class="simple">
<li>Remote absolute path where the file should end up.</li>
</ul>
<p>This module also returns md5sum information about the resultant file.</p>
</div>
<div class="section" id="facter">
<span id="id3"></span><h2>facter<a class="headerlink" href="#facter" title="Permalink to this headline">¶</a></h2>
<p>Runs the discovery program &#8216;facter&#8217; on the remote system, returning
JSON data that can be useful for inventory purposes.</p>
<p>Requires that &#8216;facter&#8217; and &#8216;ruby-json&#8217; be installed on the remote end.</p>
<p>This module is informative only - it takes no parameters &amp; does not
support change hooks, nor does it make any changes on the system.
Playbooks do not actually use this module, they use the <a class="reference internal" href="#setup"><em>setup</em></a>
module behind the scenes.</p>
</div>
<div class="section" id="file">
<h2>file<a class="headerlink" href="#file" title="Permalink to this headline">¶</a></h2>
<p>Sets attributes of files and directories, or removes files/directories.  All parameters available
to the file module are also available when running the <cite>copy</cite> or <cite>template</cite> modules.</p>
<p><em>dest</em>:</p>
<ul class="simple">
<li>absolute path to a file on the filesystem.</li>
</ul>
<p><em>state</em>:</p>
<ul class="simple">
<li>either &#8216;file&#8217;, &#8216;directory&#8217;, or &#8216;absent&#8217;.  The default is &#8216;file&#8217;.  If &#8216;directory&#8217;, the directory and all immediate subdirectories will be created if they do not exist.  If &#8216;file&#8217;, the file will NOT be created if it does not exist, specify <cite>copy</cite> or <cite>template</cite> for the module name instead if you need to put content at the specified location.  If &#8216;absent&#8217;, directories will be recursively deleted, and files or symlinks will be unlinked.</li>
</ul>
<p><em>mode</em>:</p>
<ul class="simple">
<li>the mode the file or directory should be, such as 644, as would be given to <cite>chmod</cite>.  English modes like &#8220;g+x&#8221; are not yet supported.</li>
</ul>
<p><em>owner</em>:</p>
<ul class="simple">
<li>name of user that should own the file or directory, as would be given to <cite>chown</cite>.</li>
</ul>
<p><em>group</em>:</p>
<ul class="simple">
<li>name of group that should own the file or directory, as would be given to <cite>chgrp</cite></li>
</ul>
</div>
<div class="section" id="git">
<h2>git<a class="headerlink" href="#git" title="Permalink to this headline">¶</a></h2>
<p>Deploys software (or files) from git checkouts.</p>
<p><em>repo</em>:</p>
<ul class="simple">
<li>git or http protocol address of the repo to checkout.</li>
</ul>
<p><em>dest</em>:</p>
<ul class="simple">
<li>Where to check it out, an absolute directory path.</li>
</ul>
<p><em>version</em>:</p>
<ul class="simple">
<li>What version to check out &#8211; either the git SHA, the literal string
<tt class="docutils literal"><span class="pre">HEAD</span></tt>, or a tag name.</li>
</ul>
</div>
<div class="section" id="ohai">
<h2>ohai<a class="headerlink" href="#ohai" title="Permalink to this headline">¶</a></h2>
<p>Similar to the <a class="reference internal" href="#facter"><em>facter</em></a> module, this returns JSON inventory data.
Ohai data is a bit more verbose and nested than facter.</p>
<p>Requires that &#8216;ohai&#8217; be installed on the remote end.</p>
<p>This module is information only - it takes no parameters &amp; does not
support change hooks, nor does it make any changes on the system.</p>
<p>Playbooks should not call the ohai module, playbooks call the
<a class="reference internal" href="#setup"><em>setup</em></a> module behind the scenes instead.</p>
</div>
<div class="section" id="ping">
<h2>ping<a class="headerlink" href="#ping" title="Permalink to this headline">¶</a></h2>
<p>A trivial test module, this module always returns the integer <tt class="docutils literal"><span class="pre">1</span></tt> on
successful contact.</p>
<p>This module does not support change hooks and is informative only - it
takes no parameters &amp; does not support change hooks, nor does it make
any changes on the system.</p>
</div>
<div class="section" id="service">
<h2>service<a class="headerlink" href="#service" title="Permalink to this headline">¶</a></h2>
<p>Controls services on remote machines.</p>
<p><em>state</em>:</p>
<ul class="simple">
<li>Values are <tt class="docutils literal"><span class="pre">started</span></tt>, <tt class="docutils literal"><span class="pre">stopped</span></tt>, or <tt class="docutils literal"><span class="pre">restarted</span></tt>.
Started/stopped are idempotent actions that will not run commands
unless necessary.  <tt class="docutils literal"><span class="pre">restarted</span></tt> will always bounce the service.</li>
</ul>
<p><em>name</em>:</p>
<ul class="simple">
<li>The name of the service.</li>
</ul>
</div>
<div class="section" id="setup">
<span id="id4"></span><h2>setup<a class="headerlink" href="#setup" title="Permalink to this headline">¶</a></h2>
<p>Writes a JSON file containing key/value data, for use in templating.
Call this once before using the <a class="reference internal" href="#template"><em>template</em></a> module.  Playbooks
will execute this module automatically as the first step in each play
using the variables section, so it is unnecessary to make explicit
calls to setup within a 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 <tt class="docutils literal"><span class="pre">facter_</span></tt> and <tt class="docutils literal"><span class="pre">ohai_</span></tt> so it&#8217;s easy to
tell their source.  All variables are then bubbled up to the caller.</p>
<p><em>anything</em>:</p>
<blockquote>
<div><ul class="simple">
<li>Any other parameters can be named basically anything, and set a
<tt class="docutils literal"><span class="pre">key=value</span></tt> pair in the JSON file for use in templating.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="shell">
<span id="id5"></span><h2>shell<a class="headerlink" href="#shell" title="Permalink to this headline">¶</a></h2>
<p>The shell module takes the command name followed by a list of
arguments, space delimited.  It is almost exactly like the command module
but runs the command through the shell rather than directly.</p>
<p>Example usage:</p>
<div class="highlight-python"><pre>find . | grep *.txt</pre>
</div>
<p>The given command will be executed on all selected nodes.</p>
<p>If you want to execute a command securely and predicably, it may
be better to use the &#8216;command&#8217; module instead.  Best practices
when writing playbooks will follow the trend of using &#8216;command&#8217;
unless &#8216;shell&#8217; is explicitly required.  When running ad-hoc commands,
use your best judgement.</p>
<p>This module does not support change hooks and returns the return code
from the program as well as timing information about how long the
command was running for.</p>
</div>
<div class="section" id="template">
<span id="id6"></span><h2>template<a class="headerlink" href="#template" title="Permalink to this headline">¶</a></h2>
<p>Templates a file out to a remote server.  Call the <a class="reference internal" href="#setup"><em>setup</em></a> module
prior to usage if you are not running from a playbook.   In addition to the options
listed below, the arguments available to the <cite>file</cite> module can also be passed to the copy
module.</p>
<p><em>src</em>:</p>
<ul class="simple">
<li>Path of a Jinja2 formatted template on the local server.  This can
be a relative or absolute path.</li>
</ul>
<p><em>dest</em>:</p>
<ul class="simple">
<li>Location to render the template on the remote server.</li>
</ul>
<p>This module also returns md5sum information about the resultant file.</p>
</div>
<div class="section" id="yum">
<span id="id7"></span><h2>yum<a class="headerlink" href="#yum" title="Permalink to this headline">¶</a></h2>
<p>Will install, upgrade, remove, and list packages with the yum package manager.</p>
<p><em>pkg</em>:</p>
<ul class="simple">
<li>A package name or package specifier with version, like name-1.0</li>
</ul>
<p><em>state</em>:</p>
<ul class="simple">
<li>Can be either &#8216;installed&#8217;, &#8216;latest&#8217;, or &#8216;removed&#8217;</li>
</ul>
<p><em>list</em>:</p>
<ul class="simple">
<li>When &#8216;list&#8217; is supplied instead of &#8216;state&#8217;, the yum module can list
various configuration attributes.  Values include &#8216;installed&#8217;, &#8216;updates&#8217;,
&#8216;available&#8217;, &#8216;repos&#8217;, or any package specifier.</li>
</ul>
</div>
<div class="section" id="writing-your-own-modules">
<h2>Writing your own modules<a class="headerlink" href="#writing-your-own-modules" title="Permalink to this headline">¶</a></h2>
<p>See <a class="reference internal" href="moduledev.html"><em>Module Development Guide</em></a>.</p>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<dl class="last docutils">
<dt><a class="reference internal" href="examples.html"><em>Command Line Examples</em></a></dt>
<dd>Examples of using modules in /usr/bin/ansible</dd>
<dt><a class="reference internal" href="playbooks.html"><em>Playbooks</em></a></dt>
<dd>Examples of using modules with /usr/bin/ansible-playbook</dd>
<dt><a class="reference internal" href="moduledev.html"><em>Module Development Guide</em></a></dt>
<dd>How to write your own modules</dd>
<dt><a class="reference internal" href="api.html"><em>API &amp; Integrations</em></a></dt>
<dd>Examples of using modules with the Python API</dd>
<dt><a class="reference external" href="http://groups.google.com/group/ansible-project">Mailing List</a></dt>
<dd>Questions? Help? Ideas?  Stop by the list on Google Groups</dd>
<dt><a class="reference external" href="http://irc.freenode.net">irc.freenode.net</a></dt>
<dd>#ansible IRC chat channel</dd>
</dl>
</div>
</div>
</div>


</div>
<footer class="footer">
  <div class="container">
    <p class="pull-right"><a href="#">Back to top</a></p>
    <p>
        &copy; Copyright 2012 Michael DeHaan.<br/>
      Last updated on Mar 19, 2012.<br/>
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
    </p>
  </div>
</footer>
  </body>
</html>