1593 lines
56 KiB
HTML
1593 lines
56 KiB
HTML
|
|
<!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 — Ansible - SSH-Based Configuration Management & 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="shortcut icon" href="_static/favicon.ico"/>
|
|
<link rel="top" title="Ansible - SSH-Based Configuration Management & Deployment" href="index.html" />
|
|
<link rel="next" title="YAML Syntax" href="YAMLSyntax.html" />
|
|
<link rel="prev" title="Command Line" 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>
|
|
|
|
<script type="text/javascript">
|
|
(function() {
|
|
var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
|
|
po.src = 'https://apis.google.com/js/plusone.js';
|
|
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
|
|
})();
|
|
</script>
|
|
|
|
<script>(function(d, s, id) {
|
|
var js, fjs = d.getElementsByTagName(s)[0];
|
|
if (d.getElementById(id)) return;
|
|
js = d.createElement(s); js.id = id;
|
|
js.src = "//connect.facebook.net/en_US/all.js#xfbml=1";
|
|
fjs.parentNode.insertBefore(js, fjs);
|
|
}(document, 'script', 'facebook-jssdk'));</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">Getting Started</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="patterns.html">Inventory & Patterns</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="examples.html">Command Line</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="playbooks2.html">Advanced Playbooks</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="bestpractices.html">Best Practices</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="api.html">API & Integrations</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="faq.html">FAQ</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="glossary.html">Glossary</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="who_uses_ansible.html">Who Uses Ansible</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="#apt">apt</a></li>
|
|
<li><a class="reference internal" href="#assemble">assemble</a></li>
|
|
<li><a class="reference internal" href="#authorized-key">authorized_key</a></li>
|
|
<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="#fetch">fetch</a></li>
|
|
<li><a class="reference internal" href="#file">file</a></li>
|
|
<li><a class="reference internal" href="#get-url">get_url</a></li>
|
|
<li><a class="reference internal" href="#git">git</a></li>
|
|
<li><a class="reference internal" href="#group">group</a></li>
|
|
<li><a class="reference internal" href="#mount">mount</a></li>
|
|
<li><a class="reference internal" href="#mysql-db">mysql_db</a></li>
|
|
<li><a class="reference internal" href="#mysql-user">mysql_user</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="#postgresql-db">postgresql_db</a></li>
|
|
<li><a class="reference internal" href="#postgresql-user">postgresql_user</a></li>
|
|
<li><a class="reference internal" href="#raw">raw</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="#user">user</a></li>
|
|
<li><a class="reference internal" href="#virt">virt</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>
|
|
<a href="http://github.com/ansible/ansible"><img style="position: absolute; right: 0; border: 0;" src="http://ansible.github.com/github.png" alt="Fork me on GitHub"></a>
|
|
|
|
|
|
<div class="container">
|
|
<a href="http://ansible.github.com"><img src="http://ansible.github.com/ansible-logo.png" alt="Ansible"/></a><br/>
|
|
<br/>
|
|
|
|
<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 ‘module library’)
|
|
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’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’t really need to know much about
|
|
that. If you’re writing your own module, you care, and this means you do
|
|
not have to write modules in any particular language – you get to choose.</p>
|
|
<p>Modules 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 ‘change events’ in the form of notifying ‘handlers’
|
|
to run additional tasks.</p>
|
|
<p>Let’s see what’s available in the Ansible module library, out of the box:</p>
|
|
<div class="section" id="apt">
|
|
<span id="id1"></span><h2>apt<a class="headerlink" href="#apt" title="Permalink to this headline">¶</a></h2>
|
|
<p>Manages apt-packages (such as for Debian/Ubuntu).</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="9%" />
|
|
<col width="8%" />
|
|
<col width="66%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th class="head">parameter</th>
|
|
<th class="head">required</th>
|
|
<th class="head">default</th>
|
|
<th class="head">comments</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>name</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>A package name or package specifier with version, like <cite>foo</cite> or <cite>foo=1.0</cite></td>
|
|
</tr>
|
|
<tr><td>state</td>
|
|
<td>no</td>
|
|
<td>present</td>
|
|
<td>‘absent’, ‘present’, or ‘latest’.</td>
|
|
</tr>
|
|
<tr><td>update_cache</td>
|
|
<td>no</td>
|
|
<td>no</td>
|
|
<td>Run the equivalent of apt-get update before the operation.
|
|
Can be run as part of the package installation or a seperate step</td>
|
|
</tr>
|
|
<tr><td>purge</td>
|
|
<td>no</td>
|
|
<td>no</td>
|
|
<td>Will forge purge of configuration files if state is set to ‘absent’.</td>
|
|
</tr>
|
|
<tr><td>default_release</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>Corresponds to the -t option for apt and sets pin priorities</td>
|
|
</tr>
|
|
<tr><td>install_recommends</td>
|
|
<td>no</td>
|
|
<td>yes</td>
|
|
<td>Corresponds to the –no-install-recommends option for apt, default
|
|
behavior works as apt’s default behavior, ‘no’ does not install
|
|
recommended packages. Suggested packages are never installed.</td>
|
|
</tr>
|
|
<tr><td>force</td>
|
|
<td>no</td>
|
|
<td>no</td>
|
|
<td>If ‘yes’, force installs/removes.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Example action from Ansible <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
|
|
<div class="highlight-python"><pre>apt pkg=foo update-cache=yes
|
|
apt pkg=foo state=removed
|
|
apt pkg=foo state=installed
|
|
apt pkg=foo=1.00 state=installed
|
|
apt pkg=nginx state=latest default-release=squeeze-backports update-cache=yes
|
|
apt pkg=openjdk-6-jdk state=latest install-recommends=no</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="assemble">
|
|
<span id="id2"></span><h2>assemble<a class="headerlink" href="#assemble" title="Permalink to this headline">¶</a></h2>
|
|
<p>(new in 0.5) Assembles a configuration file from fragments. Often a particular program will take a single configuration file
|
|
and does not support a conf.d style structure where it is easy to build up the configuration from multiple sources.
|
|
Assmeble will take a directory of files that have already been transferred to the system, and concatenate them
|
|
together to produce a destination file. Files are assembled in string sorting order. Puppet calls this idea
|
|
“fragments”.</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="9%" />
|
|
<col width="8%" />
|
|
<col width="66%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th class="head">parameter</th>
|
|
<th class="head">required</th>
|
|
<th class="head">default</th>
|
|
<th class="head">comments</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>src</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>An already existing directory full of source files</td>
|
|
</tr>
|
|
<tr><td>dest</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>A file to create using the concatenation of all of the source files</td>
|
|
</tr>
|
|
<tr><td>OTHERS</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>All arguments that the file module takes may also be used</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Example action from Ansible <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
|
|
<div class="highlight-python"><pre>assemble src=/etc/someapp/fragments dest=/etc/someapp/someapp.conf</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="authorized-key">
|
|
<span id="id3"></span><h2>authorized_key<a class="headerlink" href="#authorized-key" title="Permalink to this headline">¶</a></h2>
|
|
<p>(new in 0.5). Adds or removes an authorized key for a user from a remote host.</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="9%" />
|
|
<col width="8%" />
|
|
<col width="66%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th class="head">parameter</th>
|
|
<th class="head">required</th>
|
|
<th class="head">default</th>
|
|
<th class="head">comments</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>user</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>Name of the user who should have access to the remote host</td>
|
|
</tr>
|
|
<tr><td>key</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>the SSH public key, as a string</td>
|
|
</tr>
|
|
<tr><td>state</td>
|
|
<td>no</td>
|
|
<td>present</td>
|
|
<td>whether the given key should or should not be in the file</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Example action from Ansible <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
|
|
<div class="highlight-python"><pre>authorized_key user=charlie key="ssh-dss ASDF1234L+8BTwaRYr/rycsBF1D8e5pTxEsXHQs4iq+mZdyWqlW++L6pMiam1A8yweP+rKtgjK2httVS6GigVsuWWfOd7/sdWippefq74nppVUELHPKkaIOjJNN1zUHFoL/YMwAAAEBALnAsQN10TNGsRDe5arBsW8cTOjqLyYBcIqgPYTZW8zENErFxt7ij3fW3Jh/sCpnmy8rkS7FyK8ULX0PEy/2yDx8/5rXgMIICbRH/XaBy9Ud5bRBFVkEDu/r+rXP33wFPHjWjwvHAtfci1NRBAudQI/98DbcGQw5HmE89CjgZRo5ktkC5yu/8agEPocVjdHyZr7PaHfxZGUDGKtGRL2QzRYukCmWo1cZbMBHcI5FzImvTHS9/8B3SATjXMPgbfBuEeBwuBK5EjL+CtHY5bWs9kmYjmeo0KfUMH8hY4MAXDoKhQ7DhBPIrcjS5jPtoGxIREZjba67r6/P2XKXaCZH6Fc= charlie@example.org 2011-01-17"</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="command">
|
|
<span id="id4"></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>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="9%" />
|
|
<col width="8%" />
|
|
<col width="66%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th class="head">parameter</th>
|
|
<th class="head">required</th>
|
|
<th class="head">default</th>
|
|
<th class="head">comments</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>(free form)</td>
|
|
<td>N/A</td>
|
|
<td>N/A</td>
|
|
<td>the command module takes a free form command to run</td>
|
|
</tr>
|
|
<tr><td>creates</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>a filename, when it already exists, this step will NOT be run</td>
|
|
</tr>
|
|
<tr><td>chdir</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>cd into this directory before running the command (0.6 and later)</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>The given command will be executed on all selected nodes. It will not
|
|
be processed through the shell, so variables like “$HOME” and
|
|
operations like “<”, “>”, “|”, and “&” will not work. As such, all
|
|
paths to commands must be fully qualified.</p>
|
|
<p>NOTE:: If you want to run a command through the shell (say you are using
|
|
‘<’, ‘>’, ‘|’, etc), you actually want the ‘shell’ module instead.
|
|
The ‘command’ module is much more secure as it’s not affected by the user’s environment.</p>
|
|
<p>Example action from Ansible <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
|
|
<div class="highlight-python"><pre>command /sbin/shutdown -t now</pre>
|
|
</div>
|
|
<p>creates and chdir can be specified after the command. For instance, if you only want to run a command if a certain file does not exist, you can do the following:</p>
|
|
<div class="highlight-python"><pre>command /usr/bin/make_database.sh arg1 arg2 creates=/path/to/database</pre>
|
|
</div>
|
|
<p>The <cite>creates=</cite> and <cite>chdir</cite> options will not be passed to the actual executable.</p>
|
|
</div>
|
|
<div class="section" id="copy">
|
|
<span id="id5"></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>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="9%" />
|
|
<col width="8%" />
|
|
<col width="66%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th class="head">parameter</th>
|
|
<th class="head">required</th>
|
|
<th class="head">default</th>
|
|
<th class="head">comments</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>src</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>Local path to a file to copy to the remote server, can be absolute or
|
|
relative.</td>
|
|
</tr>
|
|
<tr><td>dest</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>Remote absolute path where the file should end up</td>
|
|
</tr>
|
|
<tr><td>OTHERS</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>All arguments the file module takes are also supported</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Example action from Ansible <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
|
|
<div class="highlight-python"><pre>copy src=/srv/myfiles/foo.conf dest=/etc/foo.conf owner=foo group=foo mode=0644</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="facter">
|
|
<span id="id6"></span><h2>facter<a class="headerlink" href="#facter" title="Permalink to this headline">¶</a></h2>
|
|
<p>Runs the discovery program ‘facter’ on the remote system, returning
|
|
JSON data that can be useful for inventory purposes.</p>
|
|
<p>Requires that ‘facter’ and ‘ruby-json’ be installed on the remote end.</p>
|
|
<p>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>
|
|
<p>Example from /usr/bin/ansible:</p>
|
|
<div class="highlight-python"><pre>ansible foo.example.org -m ohai</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="fetch">
|
|
<span id="id7"></span><h2>fetch<a class="headerlink" href="#fetch" title="Permalink to this headline">¶</a></h2>
|
|
<p>This module works like ‘copy’, but in reverse. It is used for fetching files
|
|
from remote machines and storing them locally in a file tree, organized by hostname.</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="9%" />
|
|
<col width="8%" />
|
|
<col width="66%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th class="head">parameter</th>
|
|
<th class="head">required</th>
|
|
<th class="head">default</th>
|
|
<th class="head">comments</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>src</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>The file on the remote system to fetch. This needs to be a file, not
|
|
a directory. Recursive fetching may be supported in a later release.</td>
|
|
</tr>
|
|
<tr><td>dest</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>A directory to save the file into. For example, if the ‘dest’ directory
|
|
is ‘/foo’, a src file named ‘/tmp/bar’ on host ‘host.example.com’, would
|
|
be saved into ‘/foo/host.example.com/tmp/bar’</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Example:</p>
|
|
<div class="highlight-python"><pre>fetch src=/var/log/messages dest=/home/logtree</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="file">
|
|
<span id="id8"></span><h2>file<a class="headerlink" href="#file" title="Permalink to this headline">¶</a></h2>
|
|
<p>Sets attributes of files, symlinks, and directories, or removes files/symlinks/directories. Many other modules
|
|
support the same options as the file module – including ‘copy’, ‘template’, and ‘assmeble’.</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="9%" />
|
|
<col width="8%" />
|
|
<col width="66%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th class="head">parameter</th>
|
|
<th class="head">required</th>
|
|
<th class="head">default</th>
|
|
<th class="head">comments</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>dest</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>defines the file being managed, unless when used with state=link, and
|
|
then sets the destination to create a symbolic link to using ‘src’</td>
|
|
</tr>
|
|
<tr><td>state</td>
|
|
<td> </td>
|
|
<td>file</td>
|
|
<td>values are ‘file’, ‘link’, ‘directory’, or ‘absent’. If directory,
|
|
all immediate subdirectories will be created if they do not exist. If
|
|
‘file’, the file will NOT be created if it does not exist, see the ‘copy’
|
|
or ‘template’ module if you want that behavior. If ‘link’, the symbolic
|
|
link will be created or changed. If absent, directories will be
|
|
recursively deleted, and files or symlinks will be unlinked.</td>
|
|
</tr>
|
|
<tr><td>mode</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>mode the file or directory shoudl be, such as 0644 as would be fed to
|
|
chmod. English modes like ‘g+x’ are not yet supported</td>
|
|
</tr>
|
|
<tr><td>owner</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>name of the user that should own the file/directory, as would be fed to
|
|
chown</td>
|
|
</tr>
|
|
<tr><td>group</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>name of the group that should own the file/directory, as would be fed to
|
|
group</td>
|
|
</tr>
|
|
<tr><td>src</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>path of the file to link to (applies only to state=link)</td>
|
|
</tr>
|
|
<tr><td>seuser</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>user part of SELinux file context. Will default to system policy, if
|
|
applicable. If set to ‘_default’, it will use the ‘user’ portion of the
|
|
the policy if available</td>
|
|
</tr>
|
|
<tr><td>serole</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>role part of SELinux file context, ‘_default’ feature works as above.</td>
|
|
</tr>
|
|
<tr><td>setype</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>type part of SELinux file context, ‘_default’ feature works as above</td>
|
|
</tr>
|
|
<tr><td>selevel</td>
|
|
<td> </td>
|
|
<td>s0</td>
|
|
<td>level part of the SELinux file context. This is the MLS/MCS attribute,
|
|
sometimes known as the ‘range’. ‘_default’ feature works as above</td>
|
|
</tr>
|
|
<tr><td>context</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>accepts only ‘default’ as a value. This will restore a file’s selinux
|
|
context in the policy. Does nothing if no default is available.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Example action from Ansible <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
|
|
<div class="highlight-python"><pre>file path=/etc/foo.conf owner=foo group=foo mode=0644
|
|
file path=/some/path owner=foo group=foo state=directory
|
|
file path=/path/to/delete state=absent
|
|
file src=/file/to/link/to dest=/path/to/symlink owner=foo group=foo state=link
|
|
file path=/some/path state=directory setype=httpd_sys_content_t
|
|
file path=/some/path state=directory context=default</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="get-url">
|
|
<span id="id9"></span><h2>get_url<a class="headerlink" href="#get-url" title="Permalink to this headline">¶</a></h2>
|
|
<p>Downloads files from http, https, or ftp to the remote server. The remote server must have direct
|
|
access to the remote resource.</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="9%" />
|
|
<col width="8%" />
|
|
<col width="66%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th class="head">parameter</th>
|
|
<th class="head">required</th>
|
|
<th class="head">default</th>
|
|
<th class="head">comments</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>url</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>http, https, or ftp URL</td>
|
|
</tr>
|
|
<tr><td>dest</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>absolute path of where to download the file to. If dest is a directory,
|
|
the basename of the file on the remote server will be used.</td>
|
|
</tr>
|
|
<tr><td>OTHERS</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>all arguments accepted by the file module also work here</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Example action from Ansible <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
|
|
<div class="highlight-python"><pre>- name: Grab a bunch of jQuery stuff
|
|
action: get_url url=http://code.jquery.com/$item dest=${jquery_directory} mode=0444
|
|
with_items:
|
|
- jquery.min.js
|
|
- mobile/latest/jquery.mobile.min.js
|
|
- ui/jquery-ui-git.css</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="git">
|
|
<span id="id10"></span><h2>git<a class="headerlink" href="#git" title="Permalink to this headline">¶</a></h2>
|
|
<p>Deploys software (or files) from git checkouts.</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="9%" />
|
|
<col width="8%" />
|
|
<col width="66%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th class="head">parameter</th>
|
|
<th class="head">required</th>
|
|
<th class="head">default</th>
|
|
<th class="head">comments</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>repo</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>git, ssh, or http protocol address of the git repo</td>
|
|
</tr>
|
|
<tr><td>dest</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>absolute path of where the repo should be checked out to</td>
|
|
</tr>
|
|
<tr><td>version</td>
|
|
<td>no</td>
|
|
<td>HEAD</td>
|
|
<td>what version to check out – either the git SHA, the literal string
|
|
‘HEAD’, branch name, or a tag name.</td>
|
|
</tr>
|
|
<tr><td>remote</td>
|
|
<td>no</td>
|
|
<td>origin</td>
|
|
<td>name of the remote branch</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Example action from Ansible <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
|
|
<div class="highlight-python"><pre>git repo=git://foosball.example.org/path/to/repo.git dest=/srv/checkout version=release-0.22</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="group">
|
|
<span id="id11"></span><h2>group<a class="headerlink" href="#group" title="Permalink to this headline">¶</a></h2>
|
|
<p>Adds or removes groups.</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="9%" />
|
|
<col width="8%" />
|
|
<col width="66%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th class="head">parameter</th>
|
|
<th class="head">required</th>
|
|
<th class="head">default</th>
|
|
<th class="head">comments</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>name</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>name of the group</td>
|
|
</tr>
|
|
<tr><td>gid</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>optional git to set for the group</td>
|
|
</tr>
|
|
<tr><td>state</td>
|
|
<td> </td>
|
|
<td>present</td>
|
|
<td>‘absent’ or ‘present’</td>
|
|
</tr>
|
|
<tr><td>system</td>
|
|
<td> </td>
|
|
<td>no</td>
|
|
<td>if ‘yes’, indicates that the group being created is a system group.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>To control members of the group, see the users resource.</p>
|
|
<p>Example action from Ansible <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
|
|
<div class="highlight-python"><pre>group name=somegroup state=present</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="mount">
|
|
<span id="id12"></span><h2>mount<a class="headerlink" href="#mount" title="Permalink to this headline">¶</a></h2>
|
|
<p>The mount module controls active and configured mount points (fstab).</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="9%" />
|
|
<col width="8%" />
|
|
<col width="66%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th class="head">parameter</th>
|
|
<th class="head">required</th>
|
|
<th class="head">default</th>
|
|
<th class="head">comments</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>name</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>path to the mountpoint, ex: /mnt/foo</td>
|
|
</tr>
|
|
<tr><td>src</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>device to be mounted</td>
|
|
</tr>
|
|
<tr><td>fstype</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>fstype</td>
|
|
</tr>
|
|
<tr><td>opts</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>mount options (see fstab docs)</td>
|
|
</tr>
|
|
<tr><td>dump</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>dump (see fstab docs)</td>
|
|
</tr>
|
|
<tr><td>passno</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>passno (see fstab docs)</td>
|
|
</tr>
|
|
<tr><td>state</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>‘present’, ‘absent’, ‘mounted’, or ‘unmounted’. If mounted/unmounted,
|
|
the device will be actively mounted or unmounted as well as just
|
|
configured in fstab. ‘absent’, and ‘present’ only deal with fstab.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="section" id="mysql-db">
|
|
<span id="id13"></span><h2>mysql_db<a class="headerlink" href="#mysql-db" title="Permalink to this headline">¶</a></h2>
|
|
<p>Add or remove MySQL databases from a remote host.</p>
|
|
<p>Requires the MySQLdb Python package on the remote host. For Ubuntu, this is as easy as
|
|
apt-get install python-mysqldb.</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="8%" />
|
|
<col width="9%" />
|
|
<col width="65%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th class="head">parameter</th>
|
|
<th class="head">required</th>
|
|
<th class="head">default</th>
|
|
<th class="head">comments</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>name</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>name of the database to add or remove</td>
|
|
</tr>
|
|
<tr><td>login_user</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>user name used to authenticate with</td>
|
|
</tr>
|
|
<tr><td>login_password</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>password used to authenticate with</td>
|
|
</tr>
|
|
<tr><td>login_host</td>
|
|
<td>no</td>
|
|
<td>localhost</td>
|
|
<td>host running the database</td>
|
|
</tr>
|
|
<tr><td>state</td>
|
|
<td>no</td>
|
|
<td>present</td>
|
|
<td>‘absent’ or ‘present’</td>
|
|
</tr>
|
|
<tr><td>collation</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>collation mode</td>
|
|
</tr>
|
|
<tr><td>encoding</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>encoding mode</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Both ‘login_password’ and ‘login_username’ are required when you are passing credentials.
|
|
If none are present, the module will attempt to read the credentials from ~/.my.cnf, and
|
|
finally fall back to using the MySQL default login of ‘root’ with no password.</p>
|
|
<p>Example action from Ansible <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
|
|
<div class="highlight-python"><pre>- name: Create database
|
|
action: mysql_db db=bobdata state=present</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="mysql-user">
|
|
<h2>mysql_user<a class="headerlink" href="#mysql-user" title="Permalink to this headline">¶</a></h2>
|
|
<p>Adds or removes a user from a MySQL database.</p>
|
|
<p>Requires the MySQLdb Python package on the remote host. For Ubuntu, this is as easy as
|
|
apt-get install python-mysqldb.</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="8%" />
|
|
<col width="10%" />
|
|
<col width="64%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th class="head">parameter</th>
|
|
<th class="head">required</th>
|
|
<th class="head">default</th>
|
|
<th class="head">comments</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>name</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>name of the user (role) to add or remove</td>
|
|
</tr>
|
|
<tr><td>password</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>set the user’s password</td>
|
|
</tr>
|
|
<tr><td>host</td>
|
|
<td>no</td>
|
|
<td>localhost</td>
|
|
<td>the ‘host’ part of the MySQL username</td>
|
|
</tr>
|
|
<tr><td>login_user</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>user name used to authenticate with</td>
|
|
</tr>
|
|
<tr><td>login_password</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>password used to authenticate with</td>
|
|
</tr>
|
|
<tr><td>login_host</td>
|
|
<td>no</td>
|
|
<td>localhost</td>
|
|
<td>host running MySQL.</td>
|
|
</tr>
|
|
<tr><td>priv</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>MySQL privileges string in the format: db.table:priv1,priv2</td>
|
|
</tr>
|
|
<tr><td>state</td>
|
|
<td>no</td>
|
|
<td>present</td>
|
|
<td>‘absent’ or ‘present’</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Both ‘login_password’ and ‘login_username’ are required when you are passing credentials.
|
|
If none are present, the module will attempt to read the credentials from ~/.my.cnf, and
|
|
finally fall back to using the MySQL default login of ‘root’ with no password.</p>
|
|
<p>Example privileges string format:</p>
|
|
<blockquote>
|
|
<div>mydb.*:INSERT,UPDATE/anotherdb.*:SELECT/yetanotherdb.*:ALL</div></blockquote>
|
|
<p>Example action from Ansible <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
|
|
<div class="highlight-python"><pre>- name: Create database user
|
|
action: mysql_user name=bob passwd=12345 priv=*.*:ALL state=present
|
|
|
|
- name: Ensure no user named 'sally' exists, also passing in the auth credentials.
|
|
action: mysql_user login_user=root login_password=123456 name=sally state=absent</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="ohai">
|
|
<span id="id14"></span><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 ‘ohai’ be installed on the remote end.</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>
|
|
<p>Example:</p>
|
|
<div class="highlight-python"><pre>ansible foo.example.org -m ohai</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="ping">
|
|
<span id="id15"></span><h2>ping<a class="headerlink" href="#ping" title="Permalink to this headline">¶</a></h2>
|
|
<p>A trivial test module, this module always returns ‘pong’ on
|
|
successful contact. It does not make sense in playbooks, but is useful
|
|
from /usr/bin/ansible:</p>
|
|
<div class="highlight-python"><pre>ansible webservers -m ping</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="postgresql-db">
|
|
<h2>postgresql_db<a class="headerlink" href="#postgresql-db" title="Permalink to this headline">¶</a></h2>
|
|
<p>Add or remove PostgreSQL databases from a remote host.</p>
|
|
<p>The default authentication assumes that you are either logging in as or
|
|
sudo’ing to the postgres account on the host.</p>
|
|
<p>This module uses psycopg2, a Python PostgreSQL database adapter. You must
|
|
ensure that psycopg2 is installed on the host before using this module. If
|
|
the remote host is the PostgreSQL server (which is the default case), then
|
|
PostgreSQL must also be installed on the remote host. For Ubuntu-based systems,
|
|
install the postgresql, libpq-dev, and python-psycopg2 packages on the remote
|
|
host before using this module.</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="9%" />
|
|
<col width="9%" />
|
|
<col width="66%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th class="head">parameter</th>
|
|
<th class="head">required</th>
|
|
<th class="head">default</th>
|
|
<th class="head">comments</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>name</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>name of the database to add or remove</td>
|
|
</tr>
|
|
<tr><td>login_user</td>
|
|
<td>no</td>
|
|
<td>postgres</td>
|
|
<td>user (role) used to authenticate with PostgreSQL</td>
|
|
</tr>
|
|
<tr><td>login_password</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>password used to authenticate with PostgreSQL</td>
|
|
</tr>
|
|
<tr><td>login_host</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>host running PostgreSQL. Default (blank) implies localhost</td>
|
|
</tr>
|
|
<tr><td>state</td>
|
|
<td> </td>
|
|
<td>present</td>
|
|
<td>‘absent’ or ‘present’</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Example action from Ansible <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
|
|
<div class="highlight-python"><pre>postgresql_db db=acme</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="postgresql-user">
|
|
<h2>postgresql_user<a class="headerlink" href="#postgresql-user" title="Permalink to this headline">¶</a></h2>
|
|
<p>Add or remove PostgreSQL users (roles) from a remote host, and grant the users
|
|
access to an existing database.</p>
|
|
<p>The default authentication assumes that you are either logging in as or
|
|
sudo’ing to the postgres account on the host.</p>
|
|
<p>This module uses psycopg2, a Python PostgreSQL database adapter. You must
|
|
ensure that psycopg2 is installed on the host before using this module. If
|
|
the remote host is the PostgreSQL server (which is the default case), then
|
|
PostgreSQL must also be installed on the remote host. For Ubuntu-based systems,
|
|
install the postgresql, libpq-dev, and python-psycopg2 packages on the remote
|
|
host before using this module.</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="9%" />
|
|
<col width="9%" />
|
|
<col width="66%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th class="head">parameter</th>
|
|
<th class="head">required</th>
|
|
<th class="head">default</th>
|
|
<th class="head">comments</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>name</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>name of the user (role) to add or remove</td>
|
|
</tr>
|
|
<tr><td>password</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>set the user’s password</td>
|
|
</tr>
|
|
<tr><td>db</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>name of an existing database to grant user access to</td>
|
|
</tr>
|
|
<tr><td>login_user</td>
|
|
<td>no</td>
|
|
<td>postgres</td>
|
|
<td>user (role) used to authenticate with PostgreSQL</td>
|
|
</tr>
|
|
<tr><td>login_password</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>password used to authenticate with PostgreSQL</td>
|
|
</tr>
|
|
<tr><td>login_host</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>host running PostgreSQL. Default (blank) implies localhost</td>
|
|
</tr>
|
|
<tr><td>state</td>
|
|
<td> </td>
|
|
<td>present</td>
|
|
<td>‘absent’ or ‘present’</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Example action from Ansible <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
|
|
<div class="highlight-python"><pre>postgresql_user db=acme user=django password=ceec4eif7ya</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="raw">
|
|
<span id="id16"></span><h2>raw<a class="headerlink" href="#raw" title="Permalink to this headline">¶</a></h2>
|
|
<p>Executes a low-down and dirty SSH command, not going through the module subsystem.</p>
|
|
<p>This is useful and should only be done in two cases. The first case is installing
|
|
python-simplejson on older (python 2.4 and before) hosts that need it as a dependency
|
|
to run modules, since nearly all core modules require it. Another is speaking to any
|
|
devices such as routers that do not have any Python installed. In any other case,
|
|
using the ‘shell’ or ‘command’ module is much more appropriate.</p>
|
|
<p>Arguments given to ‘raw’ are run directly through the configured remote shell and
|
|
only output is returned. There is no error detection or change handler support
|
|
for this module.</p>
|
|
<p>Example from <cite>/usr/bin/ansible</cite> to bootstrap a legacy python 2.4 host:</p>
|
|
<div class="highlight-python"><pre>ansible newhost.example.com raw -a "yum install python-simplejson"</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="service">
|
|
<span id="id17"></span><h2>service<a class="headerlink" href="#service" title="Permalink to this headline">¶</a></h2>
|
|
<p>Controls services on remote machines.</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="9%" />
|
|
<col width="8%" />
|
|
<col width="66%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th class="head">parameter</th>
|
|
<th class="head">required</th>
|
|
<th class="head">default</th>
|
|
<th class="head">comments</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>name</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>name of the service</td>
|
|
</tr>
|
|
<tr><td>state</td>
|
|
<td>no</td>
|
|
<td>started</td>
|
|
<td>‘started’, ‘stopped’, ‘reloaded’, or ‘restarted’. Started/stopped are
|
|
idempotent actions that will not run commands unless neccessary.
|
|
‘restarted’ will always bounce the service, ‘reloaded’ will always reload.</td>
|
|
</tr>
|
|
<tr><td>enabled</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>Whether the service should start on boot. Either ‘yes’ or ‘no’.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Example action from Ansible <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
|
|
<div class="highlight-python"><pre>service name=httpd state=started
|
|
service name=httpd state=stopped
|
|
service name=httpd state=restarted
|
|
service name=httpd state=reloaded</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="setup">
|
|
<span id="id18"></span><h2>setup<a class="headerlink" href="#setup" title="Permalink to this headline">¶</a></h2>
|
|
<p>This module is automatically called by playbooks to gather useful variables about remote hosts that can be used
|
|
in playbooks. It can also be executed directly by /usr/bin/ansible to check what variables are available
|
|
to a host.</p>
|
|
<p>Ansible provides many ‘facts’ about the system, automatically.</p>
|
|
<p>Some of the variables that are supplied are listed below. These in particular
|
|
are from a VMWare Fusion 4 VM running CentOS 6.2:</p>
|
|
<div class="highlight-python"><pre>"ansible_architecture": "x86_64",
|
|
"ansible_distribution": "CentOS",
|
|
"ansible_distribution_release": "Final",
|
|
"ansible_distribution_version": "6.2",
|
|
"ansible_eth0": {
|
|
"ipv4": {
|
|
"address": "REDACTED",
|
|
"netmask": "255.255.255.0"
|
|
},
|
|
"ipv6": [
|
|
{
|
|
"address": "REDACTED",
|
|
"prefix": "64",
|
|
"scope": "link"
|
|
}
|
|
],
|
|
"macaddress": "REDACTED"
|
|
},
|
|
"ansible_form_factor": "Other",
|
|
"ansible_fqdn": "localhost.localdomain",
|
|
"ansible_hostname": "localhost",
|
|
"ansible_interfaces": [
|
|
"lo",
|
|
"eth0"
|
|
],
|
|
"ansible_kernel": "2.6.32-220.2.1.el6.x86_64",
|
|
"ansible_lo": {
|
|
"ipv4": {
|
|
"address": "127.0.0.1",
|
|
"netmask": "255.0.0.0"
|
|
},
|
|
"ipv6": [
|
|
{
|
|
"address": "::1",
|
|
"prefix": "128",
|
|
"scope": "host"
|
|
}
|
|
],
|
|
"ansible_machine": "x86_64",
|
|
"ansible_memfree_mb": 89,
|
|
"ansible_memtotal_mb": 993,
|
|
"ansible_processor": [
|
|
"Intel(R) Core(TM) i7-2677M CPU @ 1.80GHz"
|
|
],
|
|
"ansible_processor_cores": "NA",
|
|
"ansible_processor_count": 1,
|
|
"ansible_product_name": "VMware Virtual Platform",
|
|
"ansible_product_serial": "REDACTED",
|
|
"ansible_product_uuid": "REDACTED",
|
|
"ansible_product_version": "None",
|
|
"ansible_python_version": "2.6.6",
|
|
"ansible_product_version": "None",
|
|
"ansible_python_version": "2.6.6",
|
|
"ansible_ssh_host_key_dsa_public": REDACTED",
|
|
"ansible_ssh_host_key_rsa_public": "REDACTED",
|
|
"ansible_swapfree_mb": 1822,
|
|
"ansible_swaptotal_mb": 2015,
|
|
"ansible_system": "Linux",
|
|
"ansible_system_vendor": "VMware, Inc.",
|
|
"ansible_virtualization_role": "None",
|
|
"ansible_virtualization_type": "None",</pre>
|
|
</div>
|
|
<p>More ansible facts will be added with successive releases.</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’s easy to
|
|
tell their source.</p>
|
|
<p>All variables are bubbled up to the caller. Using the ansible facts and choosing
|
|
to not install facter and ohai means you can avoid ruby-dependencies
|
|
on your remote systems.</p>
|
|
<p>Example action from <cite>/usr/bin/ansible</cite>:</p>
|
|
<div class="highlight-python"><pre>ansible testserver -m setup</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="shell">
|
|
<span id="id19"></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 user’s configured shell on the remote node.</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="9%" />
|
|
<col width="8%" />
|
|
<col width="66%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th class="head">parameter</th>
|
|
<th class="head">required</th>
|
|
<th class="head">default</th>
|
|
<th class="head">comments</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>(free form)</td>
|
|
<td>N/A</td>
|
|
<td>N/A</td>
|
|
<td>the command module takes a free form command to run</td>
|
|
</tr>
|
|
<tr><td>creates</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>a filename, when it already exists, this step will NOT be run</td>
|
|
</tr>
|
|
<tr><td>chdir</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>cd into this directory before running the command (0.6 and later)</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>The given command will be executed on all selected nodes.</p>
|
|
<p>NOTE:: If you want to execute a command securely and predicably, it may
|
|
be better to use the ‘command’ module instead. Best practices
|
|
when writing playbooks will follow the trend of using ‘command’
|
|
unless ‘shell’ is explicitly required. When running ad-hoc commands,
|
|
use your best judgement.</p>
|
|
<p>Example action from a playbook:</p>
|
|
<div class="highlight-python"><pre>shell somescript.sh >> somelog.txt</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="template">
|
|
<span id="id20"></span><h2>template<a class="headerlink" href="#template" title="Permalink to this headline">¶</a></h2>
|
|
<p>Templates a file out to a remote server.</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="9%" />
|
|
<col width="8%" />
|
|
<col width="66%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th class="head">parameter</th>
|
|
<th class="head">required</th>
|
|
<th class="head">default</th>
|
|
<th class="head">comments</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>src</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>Path of a Jinja2 formatted template on the local server. This can be
|
|
a relative or absolute path.</td>
|
|
</tr>
|
|
<tr><td>dest</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>Location to render the template on the remote server</td>
|
|
</tr>
|
|
<tr><td>OTHERS</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>This module also supports all of the arguments to the file module</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Example action from a playbook:</p>
|
|
<div class="highlight-python"><pre>template src=/srv/mytemplates/foo.j2 dest=/etc/foo.conf owner=foo group=foo mode=0644</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="user">
|
|
<span id="id21"></span><h2>user<a class="headerlink" href="#user" title="Permalink to this headline">¶</a></h2>
|
|
<p>Creates user accounts, manipulates existing user accounts, and removes user accounts.</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="9%" />
|
|
<col width="8%" />
|
|
<col width="66%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th class="head">parameter</th>
|
|
<th class="head">required</th>
|
|
<th class="head">default</th>
|
|
<th class="head">comments</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>name</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>name of the user to create, remove, or edit</td>
|
|
</tr>
|
|
<tr><td>comment</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>optionally sets the description of the user</td>
|
|
</tr>
|
|
<tr><td>uid</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>optionally sets the uid of the user</td>
|
|
</tr>
|
|
<tr><td>group</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>optionally sets the user’s primary group (takes a group name)</td>
|
|
</tr>
|
|
<tr><td>groups</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>puts the user in this comma-delimited list of groups</td>
|
|
</tr>
|
|
<tr><td>append</td>
|
|
<td> </td>
|
|
<td>no</td>
|
|
<td>if ‘yes’, will only add groups, not set them to just the list in ‘groups’</td>
|
|
</tr>
|
|
<tr><td>shell</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>optionally set the user’s shell</td>
|
|
</tr>
|
|
<tr><td>createhome</td>
|
|
<td> </td>
|
|
<td>yes</td>
|
|
<td>unless ‘no’, a home directory will be made for the user</td>
|
|
</tr>
|
|
<tr><td>home</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>sets where the user’s homedir should be, if not the default</td>
|
|
</tr>
|
|
<tr><td>password</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>optionally set the user’s password to this crypted value. See the user’s
|
|
example in the github examples directory for what this looks like in a
|
|
playbook</td>
|
|
</tr>
|
|
<tr><td>state</td>
|
|
<td> </td>
|
|
<td>present</td>
|
|
<td>when ‘absent’, removes the user.</td>
|
|
</tr>
|
|
<tr><td>system</td>
|
|
<td> </td>
|
|
<td>no</td>
|
|
<td>only when initially creating, setting this to ‘yes’ makes the user a
|
|
system account. This setting cannot be changed on existing users.</td>
|
|
</tr>
|
|
<tr><td>force</td>
|
|
<td> </td>
|
|
<td>no</td>
|
|
<td>when used with state=absent, behavior is as with userdel –force</td>
|
|
</tr>
|
|
<tr><td>remove</td>
|
|
<td> </td>
|
|
<td>no</td>
|
|
<td>when used with state=remove, behavior is as with userdel –remove</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Example action from Ansible <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
|
|
<div class="highlight-python"><pre>user name=mdehaan comment=awesome passwd=awWxVV.JvmdHw createhome=yes
|
|
user name=mdehaan groups=wheel,skynet
|
|
user name=mdehaan state=absent force=yes</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="virt">
|
|
<span id="id22"></span><h2>virt<a class="headerlink" href="#virt" title="Permalink to this headline">¶</a></h2>
|
|
<p>Manages virtual machines supported by libvirt. Requires that libvirt be installed
|
|
on the managed machine.</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="9%" />
|
|
<col width="8%" />
|
|
<col width="66%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th class="head">parameter</th>
|
|
<th class="head">required</th>
|
|
<th class="head">default</th>
|
|
<th class="head">comments</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>name</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>name of the guest VM being managed</td>
|
|
</tr>
|
|
<tr><td>state</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>‘running’, ‘shutdown’, ‘destroyed’, or ‘undefined’. Note that there may
|
|
be some lag for state requests like ‘shutdown’ since these refer only to
|
|
VM states. After starting a guest, it may not be immediately accessible.</td>
|
|
</tr>
|
|
<tr><td>command</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>in addition to state management, various non-idempotent commands are
|
|
available. See examples below.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Example action from Ansible <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
|
|
<div class="highlight-python"><pre>virt guest=alpha state=running
|
|
virt guest=alpha state=shutdown
|
|
virt guest=alpha state=destroyed
|
|
virt guest=alpha state=undefined</pre>
|
|
</div>
|
|
<p>Example guest management commands from /usr/bin/ansible:</p>
|
|
<div class="highlight-python"><pre>ansible host -m virt -a "guest=foo command=status"
|
|
ansible host -m virt -a "guest=foo command=pause"
|
|
ansible host -m virt -a "guest=foo command=unpause"
|
|
ansible host -m virt -a "guest=foo command=get_xml"
|
|
ansible host -m virt -a "guest=foo command=autostart"</pre>
|
|
</div>
|
|
<p>Example host (hypervisor) management commands from /usr/bin/ansible:</p>
|
|
<div class="highlight-python"><pre>ansible host -m virt -a "command=freemem"
|
|
ansible host -m virt -a "command=list_vms"
|
|
ansible host -m virt -a "command=info"
|
|
ansible host -m virt -a "command=nodeinfo"
|
|
ansible host -m virt -a "command=virttype"</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="yum">
|
|
<span id="id23"></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>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="9%" />
|
|
<col width="8%" />
|
|
<col width="66%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr><th class="head">parameter</th>
|
|
<th class="head">required</th>
|
|
<th class="head">default</th>
|
|
<th class="head">comments</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody valign="top">
|
|
<tr><td>name</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>package name, or package specifier with version, like ‘name-1.0’</td>
|
|
</tr>
|
|
<tr><td>state</td>
|
|
<td> </td>
|
|
<td>present</td>
|
|
<td>‘present’, ‘latest’, or ‘absent’.</td>
|
|
</tr>
|
|
<tr><td>list</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>various non-idempotent commands for usage with /usr/bin/ansible and not
|
|
playbooks. See examples below.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Example action from Ansible <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
|
|
<div class="highlight-python"><pre>yum name=httpd state=latest
|
|
yum name=httpd state=removed
|
|
yum name=httpd state=installed</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="additional-modules">
|
|
<h2>Additional Contrib Modules</h2>
|
|
<p>In addition to the following built-in modules, community modules are available at <a href="http://github.com/ansible/ansible-resources">http://github.com/ansible/ansible-resources</a>.</p>
|
|
</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</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 external" href="https://github.com/ansible/ansible-resources"><em>Ansible Resources</em></a></dt>
|
|
<dd>User contributed playbooks, modules, and articles</dd>
|
|
<dt><a class="reference internal" href="examples.html"><em>Command Line</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</em></a></dt>
|
|
<dd>How to write your own modules</dd>
|
|
<dt><a class="reference internal" href="api.html"><em>API & 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>
|
|
|
|
|
|
<br/>
|
|
</div>
|
|
<footer class="footer">
|
|
|
|
<div class="container">
|
|
<div id="fb-root"></div>
|
|
<p>
|
|
<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
|
|
<input type="hidden" name="cmd" value="_donations">
|
|
<input type="hidden" name="business" value="michael.dehaan@gmail.com">
|
|
<input type="hidden" name="lc" value="US">
|
|
<input type="hidden" name="item_name" value="Ansible">
|
|
<input type="hidden" name="no_note" value="0">
|
|
<input type="hidden" name="currency_code" value="USD">
|
|
<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHostedGuest">
|
|
<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
|
|
<img alt="" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">
|
|
</form>
|
|
</p>
|
|
<p>
|
|
<a href="https://twitter.com/share" class="twitter-share-button" data-text="ansible.github.com">Share On Twitter</a>
|
|
<script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src="//platform.twitter.com/widgets.js";fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");</script>
|
|
<g:plusone annotation="inline"></g:plusone>
|
|
<div class="fb-like" data-href="http://ansible.github.com" data-send="true" data-width="450" data-show-faces="false"></div>
|
|
</p>
|
|
<p>
|
|
© Copyright 2012 Michael DeHaan.<br/>
|
|
Last updated on Aug 08, 2012.<br/>
|
|
</p>
|
|
</div>
|
|
</footer>
|
|
</body>
|
|
</html>
|