2371 lines
90 KiB
HTML
2371 lines
90 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 Examples And Next Steps" 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 Examples And Next Steps</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="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="#introduction">Introduction</a></li>
|
|
<li><a class="reference internal" href="#apt-repository">apt_repository</a></li>
|
|
<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="#easy-install">easy_install</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="#lineinfile">lineinfile</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="#nagios">nagios</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="#pip">pip</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="#seboolean">seboolean</a></li>
|
|
<li><a class="reference internal" href="#selinux">selinux</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="#subversion">subversion</a></li>
|
|
<li><a class="reference internal" href="#supervisorctl">supervisorctl</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="#wait-for">wait_for</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="#additional-contrib-modules">Additional Contrib Modules</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><a class="toc-backref" href="#contents">Ansible Modules</a><a class="headerlink" href="#ansible-modules" title="Permalink to this headline">¶</a></h1>
|
|
<div class="contents topic" id="contents">
|
|
<p class="topic-title first">Contents</p>
|
|
<ul class="simple">
|
|
<li><a class="reference internal" href="#ansible-modules" id="id38">Ansible Modules</a><ul>
|
|
<li><a class="reference internal" href="#introduction" id="id39">Introduction</a></li>
|
|
<li><a class="reference internal" href="#apt-repository" id="id40">apt_repository</a></li>
|
|
<li><a class="reference internal" href="#apt" id="id41">apt</a></li>
|
|
<li><a class="reference internal" href="#assemble" id="id42">assemble</a></li>
|
|
<li><a class="reference internal" href="#authorized-key" id="id43">authorized_key</a></li>
|
|
<li><a class="reference internal" href="#command" id="id44">command</a></li>
|
|
<li><a class="reference internal" href="#copy" id="id45">copy</a></li>
|
|
<li><a class="reference internal" href="#easy-install" id="id46">easy_install</a></li>
|
|
<li><a class="reference internal" href="#facter" id="id47">facter</a></li>
|
|
<li><a class="reference internal" href="#fetch" id="id48">fetch</a></li>
|
|
<li><a class="reference internal" href="#file" id="id49">file</a></li>
|
|
<li><a class="reference internal" href="#get-url" id="id50">get_url</a></li>
|
|
<li><a class="reference internal" href="#git" id="id51">git</a></li>
|
|
<li><a class="reference internal" href="#group" id="id52">group</a></li>
|
|
<li><a class="reference internal" href="#lineinfile" id="id53">lineinfile</a></li>
|
|
<li><a class="reference internal" href="#mount" id="id54">mount</a></li>
|
|
<li><a class="reference internal" href="#mysql-db" id="id55">mysql_db</a></li>
|
|
<li><a class="reference internal" href="#mysql-user" id="id56">mysql_user</a></li>
|
|
<li><a class="reference internal" href="#nagios" id="id57">nagios</a></li>
|
|
<li><a class="reference internal" href="#ohai" id="id58">ohai</a></li>
|
|
<li><a class="reference internal" href="#ping" id="id59">ping</a></li>
|
|
<li><a class="reference internal" href="#pip" id="id60">pip</a></li>
|
|
<li><a class="reference internal" href="#postgresql-db" id="id61">postgresql_db</a></li>
|
|
<li><a class="reference internal" href="#postgresql-user" id="id62">postgresql_user</a></li>
|
|
<li><a class="reference internal" href="#raw" id="id63">raw</a></li>
|
|
<li><a class="reference internal" href="#service" id="id64">service</a></li>
|
|
<li><a class="reference internal" href="#seboolean" id="id65">seboolean</a></li>
|
|
<li><a class="reference internal" href="#selinux" id="id66">selinux</a></li>
|
|
<li><a class="reference internal" href="#setup" id="id67">setup</a></li>
|
|
<li><a class="reference internal" href="#shell" id="id68">shell</a></li>
|
|
<li><a class="reference internal" href="#subversion" id="id69">subversion</a></li>
|
|
<li><a class="reference internal" href="#supervisorctl" id="id70">supervisorctl</a></li>
|
|
<li><a class="reference internal" href="#template" id="id71">template</a></li>
|
|
<li><a class="reference internal" href="#user" id="id72">user</a></li>
|
|
<li><a class="reference internal" href="#wait-for" id="id73">wait_for</a></li>
|
|
<li><a class="reference internal" href="#virt" id="id74">virt</a></li>
|
|
<li><a class="reference internal" href="#yum" id="id75">yum</a></li>
|
|
<li><a class="reference internal" href="#additional-contrib-modules" id="id76">Additional Contrib Modules</a></li>
|
|
<li><a class="reference internal" href="#writing-your-own-modules" id="id77">Writing your own modules</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="section" id="introduction">
|
|
<h2><a class="toc-backref" href="#contents">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
|
|
<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>
|
|
<div class="section" id="apt-repository">
|
|
<span id="id1"></span><h2><a class="toc-backref" href="#contents">apt_repository</a><a class="headerlink" href="#apt-repository" title="Permalink to this headline">¶</a></h2>
|
|
<p class="versionadded">
|
|
<span class="versionmodified">New in version 0.7.</span></p>
|
|
<p>Manages apt repositores</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="9%" />
|
|
<col width="8%" />
|
|
<col width="66%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr class="row-odd"><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 class="row-even"><td>repo</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>The repository name/value</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>state</td>
|
|
<td>no</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>apt_repository repo=ppa:nginx/stable
|
|
apt_repository repo='deb http://archive.canonical.com/ubuntu hardy partner'</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="apt">
|
|
<span id="id2"></span><h2><a class="toc-backref" href="#contents">apt</a><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 class="row-odd"><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 class="row-even"><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 class="row-odd"><td>state</td>
|
|
<td>no</td>
|
|
<td>present</td>
|
|
<td>‘absent’, ‘present’, or ‘latest’.</td>
|
|
</tr>
|
|
<tr class="row-even"><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 class="row-odd"><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 class="row-even"><td>default_release</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>Corresponds to the -t option for apt and sets pin priorities</td>
|
|
</tr>
|
|
<tr class="row-odd"><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 class="row-even"><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="id3"></span><h2><a class="toc-backref" href="#contents">assemble</a><a class="headerlink" href="#assemble" title="Permalink to this headline">¶</a></h2>
|
|
<p class="versionadded">
|
|
<span class="versionmodified">New in version 0.5.</span></p>
|
|
<p>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 class="row-odd"><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 class="row-even"><td>src</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>An already existing directory full of source files</td>
|
|
</tr>
|
|
<tr class="row-odd"><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 class="row-even"><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="id4"></span><h2><a class="toc-backref" href="#contents">authorized_key</a><a class="headerlink" href="#authorized-key" title="Permalink to this headline">¶</a></h2>
|
|
<p class="versionadded">
|
|
<span class="versionmodified">New in version 0.5.</span></p>
|
|
<p>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 class="row-odd"><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 class="row-even"><td>user</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>Name of the user who should have access to the remote host</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>key</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>the SSH public key, as a string</td>
|
|
</tr>
|
|
<tr class="row-even"><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="id5"></span><h2><a class="toc-backref" href="#contents">command</a><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 class="row-odd"><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 class="row-even"><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 class="row-odd"><td>creates</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>a filename, when it already exists, this step will NOT be run</td>
|
|
</tr>
|
|
<tr class="row-even"><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>
|
|
<div class="admonition note">
|
|
<p class="first admonition-title">Note</p>
|
|
<p class="last">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>
|
|
</div>
|
|
<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="id6"></span><h2><a class="toc-backref" href="#contents">copy</a><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 class="row-odd"><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 class="row-even"><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 class="row-odd"><td>dest</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>Remote absolute path where the file should end up</td>
|
|
</tr>
|
|
<tr class="row-even"><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="easy-install">
|
|
<span id="id7"></span><h2><a class="toc-backref" href="#contents">easy_install</a><a class="headerlink" href="#easy-install" title="Permalink to this headline">¶</a></h2>
|
|
<p class="versionadded">
|
|
<span class="versionmodified">New in version 0.7.</span></p>
|
|
<p>The easy_install module installs Python libraries.</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="9%" />
|
|
<col width="8%" />
|
|
<col width="66%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr class="row-odd"><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 class="row-even"><td>name</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>a Python library name</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>virtualenv</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>an optional virtualenv directory path to install into, if the virtualenv
|
|
does not exist it is created automatically</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Please note that the easy_install command can only install Python libraries.
|
|
Thus this module is not able to remove libraries. It is generally recommended to
|
|
use the <a class="reference internal" href="#pip"><em>pip</em></a> module which you can first install using easy_install.</p>
|
|
<p>Also note that <a class="reference external" href="http://www.virtualenv.org/">virtualenv</a> must be installed on
|
|
the remote host if the <cite>virtualenv</cite> parameter is specified.</p>
|
|
<p>Example action from Ansible <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
|
|
<div class="highlight-python"><pre>easy_install name=pip
|
|
easy_install name=flask==0.8
|
|
easy_install name=flask virtualenv=/srv/webapps/my_app/venv</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="facter">
|
|
<span id="id8"></span><h2><a class="toc-backref" href="#contents">facter</a><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 facter</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="fetch">
|
|
<span id="id9"></span><h2><a class="toc-backref" href="#contents">fetch</a><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 class="row-odd"><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 class="row-even"><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 class="row-odd"><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="id10"></span><h2><a class="toc-backref" href="#contents">file</a><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 class="row-odd"><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 class="row-even"><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 class="row-odd"><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 class="row-even"><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 class="row-odd"><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 class="row-even"><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 class="row-odd"><td>src</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>path of the file to link to (applies only to state=link)</td>
|
|
</tr>
|
|
<tr class="row-even"><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 class="row-odd"><td>serole</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>role part of SELinux file context, ‘_default’ feature works as above.</td>
|
|
</tr>
|
|
<tr class="row-even"><td>setype</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>type part of SELinux file context, ‘_default’ feature works as above</td>
|
|
</tr>
|
|
<tr class="row-odd"><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 class="row-even"><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="id11"></span><h2><a class="toc-backref" href="#contents">get_url</a><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 class="row-odd"><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 class="row-even"><td>url</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>http, https, or ftp URL</td>
|
|
</tr>
|
|
<tr class="row-odd"><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. If a
|
|
directory, thirsty=yes must also be set.</td>
|
|
</tr>
|
|
<tr class="row-even"><td>thirsty</td>
|
|
<td>no</td>
|
|
<td>‘no’</td>
|
|
<td>(new in 0.7) if yes, will download the file every time and replace the
|
|
file if the contents change. if no, the file will only be downloaded
|
|
if the destination does not exist. Generally should be ‘yes’ only for
|
|
small local files. prior to 0.6, acts if ‘yes’ by default.</td>
|
|
</tr>
|
|
<tr class="row-odd"><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>- action: get_url url=http://example.com/path/file.conf dest=/etc/foo.conf mode=0444</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="git">
|
|
<span id="id12"></span><h2><a class="toc-backref" href="#contents">git</a><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 class="row-odd"><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 class="row-even"><td>repo</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>git, ssh, or http protocol address of the git repo</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>dest</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>absolute path of where the repo should be checked out to</td>
|
|
</tr>
|
|
<tr class="row-even"><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 class="row-odd"><td>remote</td>
|
|
<td>no</td>
|
|
<td>origin</td>
|
|
<td>name of the remote branch</td>
|
|
</tr>
|
|
<tr class="row-even"><td>force</td>
|
|
<td>no</td>
|
|
<td>yes</td>
|
|
<td>(new in 0.7) If yes, any modified files in the working repository will be
|
|
discarded. Prior to 0.7, this was always ‘yes’ and could not be disabled.</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="id13"></span><h2><a class="toc-backref" href="#contents">group</a><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 class="row-odd"><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 class="row-even"><td>name</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>name of the group</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>gid</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>optional git to set for the group</td>
|
|
</tr>
|
|
<tr class="row-even"><td>state</td>
|
|
<td> </td>
|
|
<td>present</td>
|
|
<td>‘absent’ or ‘present’</td>
|
|
</tr>
|
|
<tr class="row-odd"><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="lineinfile">
|
|
<span id="id14"></span><h2><a class="toc-backref" href="#contents">lineinfile</a><a class="headerlink" href="#lineinfile" title="Permalink to this headline">¶</a></h2>
|
|
<p class="versionadded">
|
|
<span class="versionmodified">New in version 0.7.</span></p>
|
|
<p>This module will search a file for a line, and ensure that it is present or
|
|
absent.</p>
|
|
<p>This is primarily useful when you only want to change a single line in a file.
|
|
For other cases, see the copy or template modules.</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="9%" />
|
|
<col width="8%" />
|
|
<col width="66%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr class="row-odd"><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 class="row-even"><td>state</td>
|
|
<td>no</td>
|
|
<td>present</td>
|
|
<td>‘absent’ or ‘present’</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>name</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>The file to modify.</td>
|
|
</tr>
|
|
<tr class="row-even"><td>regexp</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>The regular expression to look for in the file. For state=present, the
|
|
pattern to replace. For state=absent, the pattern of the line to
|
|
remove.</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>line</td>
|
|
<td>maybe</td>
|
|
<td> </td>
|
|
<td>Required for state=present. The line to insert/replace into the file. Must
|
|
match the value given to ‘regexp’.</td>
|
|
</tr>
|
|
<tr class="row-even"><td>insertafter</td>
|
|
<td>no</td>
|
|
<td>EOF</td>
|
|
<td>Used with state=present. If specified, the line will be inserted after the
|
|
specified regular expression. Two special values are available: BOF for
|
|
inserting the line at the beginning of the file, and EOF for inserting the
|
|
line at the end of 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>lineinfile name=/etc/selinux/config regexp=^SELINUX= line=SELINUX=disabled
|
|
lineinfile name=/etc/sudoers regexp="^#includedir" line="#includedir /etc/sudoers.d"
|
|
lineinfile name=/etc/httpd/conf/httpd.conf regexp="^ServerName " insertafter="^#ServerName " line="ServerName ansible.example.com"
|
|
lineinfile name=/etc/sudoers state=absent regexp="^%wheel"</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="mount">
|
|
<span id="id15"></span><h2><a class="toc-backref" href="#contents">mount</a><a class="headerlink" href="#mount" title="Permalink to this headline">¶</a></h2>
|
|
<p class="versionadded">
|
|
<span class="versionmodified">New in version 0.6.</span></p>
|
|
<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 class="row-odd"><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 class="row-even"><td>name</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>path to the mountpoint, ex: /mnt/foo</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>src</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>device to be mounted</td>
|
|
</tr>
|
|
<tr class="row-even"><td>fstype</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>fstype</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>opts</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>mount options (see fstab docs)</td>
|
|
</tr>
|
|
<tr class="row-even"><td>dump</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>dump (see fstab docs)</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>passno</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>passno (see fstab docs)</td>
|
|
</tr>
|
|
<tr class="row-even"><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="id16"></span><h2><a class="toc-backref" href="#contents">mysql_db</a><a class="headerlink" href="#mysql-db" title="Permalink to this headline">¶</a></h2>
|
|
<p class="versionadded">
|
|
<span class="versionmodified">New in version 0.6.</span></p>
|
|
<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 class="row-odd"><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 class="row-even"><td>name</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>name of the database to add or remove</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>login_user</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>user name used to authenticate with</td>
|
|
</tr>
|
|
<tr class="row-even"><td>login_password</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>password used to authenticate with</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>login_host</td>
|
|
<td>no</td>
|
|
<td>localhost</td>
|
|
<td>host running the database</td>
|
|
</tr>
|
|
<tr class="row-even"><td>state</td>
|
|
<td>no</td>
|
|
<td>present</td>
|
|
<td>‘absent’ or ‘present’</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>collation</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>collation mode</td>
|
|
</tr>
|
|
<tr class="row-even"><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">
|
|
<span id="id17"></span><h2><a class="toc-backref" href="#contents">mysql_user</a><a class="headerlink" href="#mysql-user" title="Permalink to this headline">¶</a></h2>
|
|
<p class="versionadded">
|
|
<span class="versionmodified">New in version 0.6.</span></p>
|
|
<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 class="row-odd"><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 class="row-even"><td>name</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>name of the user (role) to add or remove</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>password</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>set the user’s password</td>
|
|
</tr>
|
|
<tr class="row-even"><td>host</td>
|
|
<td>no</td>
|
|
<td>localhost</td>
|
|
<td>the ‘host’ part of the MySQL username</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>login_user</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>user name used to authenticate with</td>
|
|
</tr>
|
|
<tr class="row-even"><td>login_password</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>password used to authenticate with</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>login_host</td>
|
|
<td>no</td>
|
|
<td>localhost</td>
|
|
<td>host running MySQL.</td>
|
|
</tr>
|
|
<tr class="row-even"><td>priv</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>MySQL privileges string in the format: db.table:priv1,priv2</td>
|
|
</tr>
|
|
<tr class="row-odd"><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="nagios">
|
|
<span id="id18"></span><h2><a class="toc-backref" href="#contents">nagios</a><a class="headerlink" href="#nagios" title="Permalink to this headline">¶</a></h2>
|
|
<p class="versionadded">
|
|
<span class="versionmodified">New in version 0.7.</span></p>
|
|
<p>Perform common tasks in Nagios related to downtime and notifications.</p>
|
|
<p>The Nagios module has two basic functions: scheduling downtime and
|
|
toggling alerts for services or hosts.</p>
|
|
<p>The following parameters are common to all <em>actions</em> in the nagios
|
|
module:</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="12%" />
|
|
<col width="8%" />
|
|
<col width="27%" />
|
|
<col width="53%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr class="row-odd"><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 class="row-even"><td>action</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>one of: ‘downtime’, ‘enable_alerts’/’disable_alerts’, or
|
|
‘silence’/’unsilence’</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>host</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>host to operate on in nagios</td>
|
|
</tr>
|
|
<tr class="row-even"><td>cmdfile</td>
|
|
<td>no</td>
|
|
<td>auto-detected</td>
|
|
<td>path to the nagios <em>command file</em> (FIFO pipe)</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>The following parameters may be used with the <strong>downtime</strong> action:</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="12%" />
|
|
<col width="8%" />
|
|
<col width="27%" />
|
|
<col width="53%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr class="row-odd"><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 class="row-even"><td>author</td>
|
|
<td>no</td>
|
|
<td>Ansible</td>
|
|
<td>author to leave downtime comments as</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>minutes</td>
|
|
<td>no</td>
|
|
<td>30</td>
|
|
<td>minutes to schedule downtime for</td>
|
|
</tr>
|
|
<tr class="row-even"><td>services</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>what to manage downtime/alerts for. separate multiple services
|
|
with commas.
|
|
<strong>service</strong> is an alias for <strong>services</strong></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>The following parameter must be used with the <strong>enable_alerts</strong> and <strong>disable_alerts</strong> actions:</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="12%" />
|
|
<col width="8%" />
|
|
<col width="27%" />
|
|
<col width="53%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr class="row-odd"><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 class="row-even"><td>services</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>what to manage downtime/alerts for. separate multiple services
|
|
with commas.
|
|
<strong>service</strong> is an alias for <strong>services</strong></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<div class="admonition note">
|
|
<p class="first admonition-title">Note</p>
|
|
<p class="last">The <strong>silence</strong> and <strong>unsilence</strong> actions have no additional
|
|
parameters that may be used with them.</p>
|
|
</div>
|
|
<p>All actions require the <strong>host</strong> parameter to be given explicitly. In
|
|
playbooks you can use the <tt class="docutils literal"><span class="pre">$inventory_hostname</span></tt> variable to refer to
|
|
the host the playbook is currently running on.</p>
|
|
<p>You can specify multiple services at once by separating them with
|
|
commas, .e.g., <tt class="docutils literal"><span class="pre">services=httpd,nfs,puppet</span></tt>.</p>
|
|
<p>When specifying what service to handle there is a special service value,
|
|
<strong>host</strong>, which will handle alerts/downtime for the <strong>host itself</strong>,
|
|
e.g., <tt class="docutils literal"><span class="pre">service=host</span></tt>. This keyword may <em>not</em> be given with other
|
|
services at the same time. <em>Handling alerts/downtime for a host does
|
|
not affect alerts/downtime for any of the services running on it.</em></p>
|
|
<p>Examples from <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
|
|
<div class="highlight-python"><pre>---
|
|
- hosts: webservers
|
|
user: root
|
|
tasks:
|
|
- name: set 30 minutes of apache downtime
|
|
action: nagios action=downtime minutes=30 service=httpd host=$inventory_hostname
|
|
delegate_to: nagios.example.com
|
|
|
|
- name: schedule an hour of HOST downtime
|
|
action: nagios action=downtime minutes=60 service=host host=$inventory_hostname
|
|
delegate_to: nagios.example.com
|
|
|
|
# Use the default of 30 minutes
|
|
# Schedule downtime for three services at once
|
|
- name: schedule downtime for a few services
|
|
action: nagios action=downtime services=frob,foobar,qeuz host=$inventory_hostname
|
|
delegate_to: nagios.example.com
|
|
|
|
- name: enable SMART disk alerts
|
|
action: nagios action=enable_alerts service=smart host=$inventory_hostname
|
|
delegate_to: nagios.example.com
|
|
|
|
# you can disable multiple at once
|
|
- name: disable httpd alerts
|
|
action: nagios action=disable_alerts service=httpd,nfs host=$inventory_hostname
|
|
delegate_to: nagios.example.com
|
|
|
|
# host alerts must be disabled as a seperate action
|
|
- name: disable HOST alerts
|
|
action: nagios action=disable_alerts service=host host=$inventory_hostname
|
|
delegate_to: nagios.example.com
|
|
|
|
- name: silence ALL alerts
|
|
action: nagios action=silence host=$inventory_hostname
|
|
delegate_to: nagios.example.com
|
|
|
|
- name: unsilence all alerts
|
|
action: nagios action=unsilence host=$inventory_hostname
|
|
delegate_to: nagios.example.com</pre>
|
|
</div>
|
|
<p><strong>Troubleshooting Tips</strong></p>
|
|
<p>The nagios module may not operate for you out of the box. The most
|
|
likely problem is with your <strong>cmdfile</strong> permissions/paths. You will
|
|
receive this error if that is the case:</p>
|
|
<div class="highlight-python"><div class="highlight"><pre><span class="p">{</span><span class="s">"msg"</span><span class="p">:</span> <span class="s">"unable to write to nagios command file"</span><span class="p">,</span> <span class="s">"failed"</span><span class="p">:</span> <span class="n">true</span><span class="p">,</span> <span class="s">"cmdfile"</span><span class="p">:</span> <span class="s">"/var/spool/nagios/cmd/nagios.cmd"</span><span class="p">}</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>Steps to correct this:</p>
|
|
<ol class="arabic simple">
|
|
<li>Ensure you are running the nagios module as a user who has
|
|
<strong>write</strong> permissions to the <strong>cmdfile</strong>.</li>
|
|
<li>Ensure you have <strong>cmdfile</strong> set correctly.</li>
|
|
</ol>
|
|
</div>
|
|
<div class="section" id="ohai">
|
|
<span id="id19"></span><h2><a class="toc-backref" href="#contents">ohai</a><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="id20"></span><h2><a class="toc-backref" href="#contents">ping</a><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="pip">
|
|
<span id="id21"></span><h2><a class="toc-backref" href="#contents">pip</a><a class="headerlink" href="#pip" title="Permalink to this headline">¶</a></h2>
|
|
<p class="versionadded">
|
|
<span class="versionmodified">New in version 0.7.</span></p>
|
|
<p>Manages Python library dependencies.</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="9%" />
|
|
<col width="8%" />
|
|
<col width="66%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr class="row-odd"><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 class="row-even"><td>name</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>The name of a Python library to install</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>version</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>The version number to install of the Python library specified in the
|
|
‘name’ parameter</td>
|
|
</tr>
|
|
<tr class="row-even"><td>requirements</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>The path to a pip requirements file</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>virtualenv</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>An optional path to a virtualenv directory to install into</td>
|
|
</tr>
|
|
<tr class="row-even"><td>state</td>
|
|
<td>no</td>
|
|
<td>present</td>
|
|
<td>‘present’, ‘absent’ or ‘latest’</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Please note that <a class="reference external" href="http://www.virtualenv.org/">virtualenv</a> must be installed on
|
|
the remote host if the <cite>virtualenv</cite> parameter is specified.</p>
|
|
<p>Examples:</p>
|
|
<div class="highlight-python"><pre>pip name=flask
|
|
pip name=flask version=0.8
|
|
pip name=flask virtualenv=/srv/webapps/my_app/venv
|
|
pip requirements=/srv/webapps/my_app/src/requirements.txt
|
|
pip requirements=/srv/webapps/my_app/src/requirements.txt virtualenv=/srv/webapps/my_app/venv</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="postgresql-db">
|
|
<span id="id23"></span><h2><a class="toc-backref" href="#contents">postgresql_db</a><a class="headerlink" href="#postgresql-db" title="Permalink to this headline">¶</a></h2>
|
|
<p class="versionadded">
|
|
<span class="versionmodified">New in version 0.6.</span></p>
|
|
<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 class="row-odd"><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 class="row-even"><td>name</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>name of the database to add or remove</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>login_user</td>
|
|
<td>no</td>
|
|
<td>postgres</td>
|
|
<td>user (role) used to authenticate with PostgreSQL</td>
|
|
</tr>
|
|
<tr class="row-even"><td>login_password</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>password used to authenticate with PostgreSQL</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>login_host</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>host running PostgreSQL. Default (blank) implies localhost</td>
|
|
</tr>
|
|
<tr class="row-even"><td>owner</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>name of the role to set as owner of the database</td>
|
|
</tr>
|
|
<tr class="row-odd"><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">
|
|
<span id="id24"></span><h2><a class="toc-backref" href="#contents">postgresql_user</a><a class="headerlink" href="#postgresql-user" title="Permalink to this headline">¶</a></h2>
|
|
<p class="versionadded">
|
|
<span class="versionmodified">New in version 0.6.</span></p>
|
|
<p>Add or remove PostgreSQL users (roles) from a remote host and, optionally, grant the users
|
|
access to an existing database or tables.</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 class="row-odd"><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 class="row-even"><td>name</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>name of the user (role) to add or remove</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>password</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>set the user’s password</td>
|
|
</tr>
|
|
<tr class="row-even"><td>db</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>name of database where permissions will be granted</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>priv</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>PostgreSQL privileges string in the format: table:priv1,priv2</td>
|
|
</tr>
|
|
<tr class="row-even"><td>fail_on_user</td>
|
|
<td>no</td>
|
|
<td>yes</td>
|
|
<td>if yes, fail when user can’t be removed. Otherwise just log and continue</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>login_user</td>
|
|
<td>no</td>
|
|
<td>postgres</td>
|
|
<td>user (role) used to authenticate with PostgreSQL</td>
|
|
</tr>
|
|
<tr class="row-even"><td>login_password</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>password used to authenticate with PostgreSQL</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>login_host</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>host running PostgreSQL. Default (blank) implies localhost</td>
|
|
</tr>
|
|
<tr class="row-even"><td>state</td>
|
|
<td> </td>
|
|
<td>present</td>
|
|
<td>‘absent’ or ‘present’</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>The fundamental function of the module is to create, or delete, roles from a PostgreSQL cluster.
|
|
Privilege assignment, or removal, is an optional step, which works on one database at a time.
|
|
This allows for the module to be called several times in the same module to modify the permissions on
|
|
different databases, or to grant permissions to already existing users.</p>
|
|
<p>A user cannot be removed untill all the privileges have been stripped from the user. In such situation,
|
|
if the module tries to remove the user it will fail. To avoid this from happening the <em>fail_on_user</em> option
|
|
signals the module to try to remove the user, but if not possible keep going; the module will report if changes
|
|
happened and separately if the user was removed or not.</p>
|
|
<p>Example privileges string format:</p>
|
|
<blockquote>
|
|
<div>INSERT,UPDATE/table:SELECT/anothertable: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 django user and grant access to database and products table
|
|
postgresql_user db=acme user=django password=ceec4eif7ya privs=CONNECT/products:ALL
|
|
|
|
- name: Remove test user privileges from acme
|
|
postgresql_user db=acme user=test privs=ALL/products:ALL state=absent fail_on_user=no
|
|
- name: Remove test user from test database and the cluster
|
|
postgresql_user db=test user=test privs=ALL state=absent</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="raw">
|
|
<span id="id25"></span><h2><a class="toc-backref" href="#contents">raw</a><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 -m raw -a "yum -y install python-simplejson"</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="service">
|
|
<span id="id26"></span><h2><a class="toc-backref" href="#contents">service</a><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 class="row-odd"><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 class="row-even"><td>name</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>name of the service</td>
|
|
</tr>
|
|
<tr class="row-odd"><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 class="row-even"><td>pattern</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>(new in 0.7) if the service does not respond to the status command,
|
|
name a substring to look for as would be found in the output of the ‘ps’
|
|
command as a stand-in for a status result. If the string is found, the
|
|
service will be assumed to be running.</td>
|
|
</tr>
|
|
<tr class="row-odd"><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 actions 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
|
|
service name=foo pattern=/usr/bin/foo state=started</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="seboolean">
|
|
<span id="id27"></span><h2><a class="toc-backref" href="#contents">seboolean</a><a class="headerlink" href="#seboolean" title="Permalink to this headline">¶</a></h2>
|
|
<p class="versionadded">
|
|
<span class="versionmodified">New in version 0.7.</span></p>
|
|
<p>Toggles SELinux booleans.</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="16%" />
|
|
<col width="8%" />
|
|
<col width="17%" />
|
|
<col width="60%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr class="row-odd"><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 class="row-even"><td>name</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>name of the boolean to configure</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>persistent</td>
|
|
<td>no</td>
|
|
<td>no</td>
|
|
<td>set to ‘yes’ if the boolean setting should survive a reboot</td>
|
|
</tr>
|
|
<tr class="row-even"><td>state</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>desired boolean value. ‘true’ or ‘false’.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Example from Ansible <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
|
|
<div class="highlight-python"><pre>seboolean name=httpd_can_network_connect state=true persistent=yes</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="selinux">
|
|
<span id="id28"></span><h2><a class="toc-backref" href="#contents">selinux</a><a class="headerlink" href="#selinux" title="Permalink to this headline">¶</a></h2>
|
|
<p class="versionadded">
|
|
<span class="versionmodified">New in version 0.7.</span></p>
|
|
<p>Configures the SELinux mode and policy. A reboot may be required after usage. Ansible will not issue this reboot but
|
|
will let you know when it is required.</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="16%" />
|
|
<col width="8%" />
|
|
<col width="17%" />
|
|
<col width="60%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr class="row-odd"><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 class="row-even"><td>policy</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>name of the SELinux policy to use (example: ‘targeted’)</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>state</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>the SELinux mode. ‘enforcing’, ‘permissive’, or ‘disabled’</td>
|
|
</tr>
|
|
<tr class="row-even"><td>conf</td>
|
|
<td>no</td>
|
|
<td>/etc/selinux/config</td>
|
|
<td>path to the SELinux configuration file, if non-standard</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Example from Ansible <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
|
|
<div class="highlight-python"><pre>selinux policy=targeted state=enforcing
|
|
selinux policy=targeted state=disabled</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="setup">
|
|
<span id="id29"></span><h2><a class="toc-backref" href="#contents">setup</a><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_facts": {
|
|
"ansible_all_ipv4_addresses": [
|
|
"192.168.144.180",
|
|
"192.168.122.1"
|
|
],
|
|
"ansible_all_ipv6_addresses": [
|
|
"ffff::fff:ffff:ffff:ffff"
|
|
],
|
|
"ansible_architecture": "x86_64",
|
|
"ansible_bios_date": "06/02/2011",
|
|
"ansible_bios_version": "6.00",
|
|
"ansible_default_ipv4": {
|
|
"address": "192.168.144.180",
|
|
"alias": "eth0",
|
|
"gateway": "192.168.144.2",
|
|
"interface": "eth0",
|
|
"macaddress": "AA:BB:CC:DD:EE:FF",
|
|
"mtu": "1500",
|
|
"netmask": "255.255.255.0",
|
|
"network": "192.168.144.0",
|
|
"type": "ether"
|
|
},
|
|
"ansible_default_ipv6": {},
|
|
"ansible_distribution": "CentOS",
|
|
"ansible_distribution_release": "Final",
|
|
"ansible_distribution_version": "6.2",
|
|
"ansible_eth0": {
|
|
"device": "eth0",
|
|
"ipv4": {
|
|
"address": "192.168.144.180",
|
|
"netmask": "255.255.255.0",
|
|
"network": "192.16.144.0"
|
|
},
|
|
"ipv6": [
|
|
{
|
|
"address": "ffff::fff:ffff:ffff:ffff",
|
|
"prefix": "64",
|
|
"scope": "link"
|
|
}
|
|
],
|
|
"macaddress": "00:0c:29:b6:a2:62",
|
|
"mtu": "1500",
|
|
"type": "ether"
|
|
},
|
|
"ansible_form_factor": "Other",
|
|
"ansible_fqdn": "localhost.localdomain",
|
|
"ansible_hostname": "localhost",
|
|
"ansible_interfaces": [
|
|
"lo",
|
|
"virbr0",
|
|
"eth0"
|
|
],
|
|
"ansible_kernel": "2.6.32-220.2.1.el6.x86_64",
|
|
"ansible_lo": {
|
|
"device": "lo",
|
|
"ipv4": {
|
|
"address": "127.0.0.1",
|
|
"netmask": "255.0.0.0",
|
|
"network": "127.0.0.0"
|
|
},
|
|
"ipv6": [
|
|
{
|
|
"address": "::1",
|
|
"prefix": "128",
|
|
"scope": "host"
|
|
}
|
|
],
|
|
"macaddress": "00:00:00:00:00:00",
|
|
"mtu": "16436",
|
|
"type": "loopback"
|
|
},
|
|
"ansible_machine": "x86_64",
|
|
"ansible_memfree_mb": 166,
|
|
"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_selinux": {
|
|
"config_mode": "enforcing",
|
|
"mode": "permissive",
|
|
"policyvers": 24,
|
|
"status": "enabled",
|
|
"type": "targeted"
|
|
},
|
|
"ansible_ssh_host_key_dsa_public": "REDACTED",
|
|
"ansible_ssh_host_key_rsa_public": "REDACTED",
|
|
"ansible_swapfree_mb": 1933,
|
|
"ansible_swaptotal_mb": 2015,
|
|
"ansible_system": "Linux",
|
|
"ansible_system_vendor": "VMware, Inc.",
|
|
"ansible_virbr0": {
|
|
"device": "virbr0",
|
|
"ipv4": {
|
|
"address": "192.168.122.1",
|
|
"netmask": "255.255.255.0",
|
|
"network": "192.168.122.0"
|
|
},
|
|
"macaddress": "AA:BB:CC:DD:EE:FF",
|
|
"mtu": "1500",
|
|
"type": "ether"
|
|
},
|
|
"ansible_virtualization_role": "guest",
|
|
"ansible_virtualization_type": "VMware",</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="id30"></span><h2><a class="toc-backref" href="#contents">shell</a><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 class="row-odd"><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 class="row-even"><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 class="row-odd"><td>creates</td>
|
|
<td>no</td>
|
|
<td> </td>
|
|
<td>a filename, when it already exists, this step will NOT be run</td>
|
|
</tr>
|
|
<tr class="row-even"><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>
|
|
<div class="admonition note">
|
|
<p class="first admonition-title">Note</p>
|
|
<p class="last">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>
|
|
</div>
|
|
<p>Example action from a playbook:</p>
|
|
<div class="highlight-python"><pre>shell somescript.sh >> somelog.txt</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="subversion">
|
|
<span id="id31"></span><h2><a class="toc-backref" href="#contents">subversion</a><a class="headerlink" href="#subversion" title="Permalink to this headline">¶</a></h2>
|
|
<p class="versionadded">
|
|
<span class="versionmodified">New in version 0.7.</span></p>
|
|
<p>Deploys a subversion repository.</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="9%" />
|
|
<col width="8%" />
|
|
<col width="66%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr class="row-odd"><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 class="row-even"><td>repo</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>The subversion URL to the repository.</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>dest</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>Absolute path where the repository should be deployed.</td>
|
|
</tr>
|
|
<tr class="row-even"><td>force</td>
|
|
<td>no</td>
|
|
<td>yes</td>
|
|
<td>If yes, any modified files in the working repository will be
|
|
discarded. If no, this module will fail if it encounters modified files.</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>subversion repo=svn+ssh://an.example.org/path/to/repo dest=/src/checkout</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="supervisorctl">
|
|
<span id="id32"></span><h2><a class="toc-backref" href="#contents">supervisorctl</a><a class="headerlink" href="#supervisorctl" title="Permalink to this headline">¶</a></h2>
|
|
<p class="versionadded">
|
|
<span class="versionmodified">New in version 0.7.</span></p>
|
|
<p>Manage the state of a program or group of programs running via Supervisord</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="9%" />
|
|
<col width="8%" />
|
|
<col width="66%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr class="row-odd"><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 class="row-even"><td>name</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>The name of the supervisord program/process to manage</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>state</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>‘started’, ‘stopped’ or ‘restarted’</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Example action from a playbook:</p>
|
|
<div class="highlight-python"><pre>supervisorctl name=my_app state=started</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="template">
|
|
<span id="id33"></span><h2><a class="toc-backref" href="#contents">template</a><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 class="row-odd"><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 class="row-even"><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 class="row-odd"><td>dest</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>Location to render the template on the remote server</td>
|
|
</tr>
|
|
<tr class="row-even"><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="id34"></span><h2><a class="toc-backref" href="#contents">user</a><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 class="row-odd"><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 class="row-even"><td>name</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>name of the user to create, remove, or edit</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>comment</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>optionally sets the description of the user</td>
|
|
</tr>
|
|
<tr class="row-even"><td>uid</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>optionally sets the uid of the user</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>group</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>optionally sets the user’s primary group (takes a group name)</td>
|
|
</tr>
|
|
<tr class="row-even"><td>groups</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>puts the user in this comma-delimited list of groups</td>
|
|
</tr>
|
|
<tr class="row-odd"><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 class="row-even"><td>shell</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>optionally set the user’s shell</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>createhome</td>
|
|
<td> </td>
|
|
<td>yes</td>
|
|
<td>unless ‘no’, a home directory will be made for the user</td>
|
|
</tr>
|
|
<tr class="row-even"><td>home</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>sets where the user’s homedir should be, if not the default</td>
|
|
</tr>
|
|
<tr class="row-odd"><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 class="row-even"><td>state</td>
|
|
<td> </td>
|
|
<td>present</td>
|
|
<td>when ‘absent’, removes the user.</td>
|
|
</tr>
|
|
<tr class="row-odd"><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 class="row-even"><td>force</td>
|
|
<td> </td>
|
|
<td>no</td>
|
|
<td>when used with state=absent, behavior is as with userdel –force</td>
|
|
</tr>
|
|
<tr class="row-odd"><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="wait-for">
|
|
<span id="id35"></span><h2><a class="toc-backref" href="#contents">wait_for</a><a class="headerlink" href="#wait-for" title="Permalink to this headline">¶</a></h2>
|
|
<p class="versionadded">
|
|
<span class="versionmodified">New in version 0.7.</span></p>
|
|
<p>Waits for a given port to become accessible (or inaccessible) on a local or remote server.</p>
|
|
<p>This is useful for when services are not immediately available after their init scripts return – which is true of certain
|
|
Java application servers. It is also useful when starting guests with the virt module and
|
|
needing to pause until they are ready.</p>
|
|
<table border="1" class="docutils">
|
|
<colgroup>
|
|
<col width="17%" />
|
|
<col width="9%" />
|
|
<col width="9%" />
|
|
<col width="65%" />
|
|
</colgroup>
|
|
<thead valign="bottom">
|
|
<tr class="row-odd"><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 class="row-even"><td>host</td>
|
|
<td>no</td>
|
|
<td>127.0.0.1</td>
|
|
<td>hostname or IP to wait for</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>timeout</td>
|
|
<td>no</td>
|
|
<td>300</td>
|
|
<td>maximum number of seconds to wait</td>
|
|
</tr>
|
|
<tr class="row-even"><td>delay</td>
|
|
<td>no</td>
|
|
<td>0</td>
|
|
<td>number of seconds to wait before starting to poll</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>port</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>port to poll for openness or closedness</td>
|
|
</tr>
|
|
<tr class="row-even"><td>state</td>
|
|
<td>no</td>
|
|
<td>started</td>
|
|
<td>either ‘started’, or ‘stopped’ depending on whether the module should poll
|
|
for the port being open or closed.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Example from Ansible <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
|
|
<div class="highlight-python"><pre>wait_for port=8080 delay=10</pre>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="virt">
|
|
<span id="id36"></span><h2><a class="toc-backref" href="#contents">virt</a><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 class="row-odd"><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 class="row-even"><td>name</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>name of the guest VM being managed</td>
|
|
</tr>
|
|
<tr class="row-odd"><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 class="row-even"><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="id37"></span><h2><a class="toc-backref" href="#contents">yum</a><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 class="row-odd"><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 class="row-even"><td>name</td>
|
|
<td>yes</td>
|
|
<td> </td>
|
|
<td>package name, or package specifier with version, like ‘name-1.0’</td>
|
|
</tr>
|
|
<tr class="row-odd"><td>state</td>
|
|
<td> </td>
|
|
<td>present</td>
|
|
<td>‘present’, ‘latest’, or ‘absent’.</td>
|
|
</tr>
|
|
<tr class="row-even"><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-contrib-modules">
|
|
<h2><a class="toc-backref" href="#contents">Additional Contrib Modules</a><a class="headerlink" href="#additional-contrib-modules" title="Permalink to this headline">¶</a></h2>
|
|
<p>In addition to the following built-in modules, community modules are available at <a class="reference external" href="http://github.com/ansible/ansible-resources">Ansible Resources</a>.</p>
|
|
</div>
|
|
<div class="section" id="writing-your-own-modules">
|
|
<h2><a class="toc-backref" href="#contents">Writing your own modules</a><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">Ansible Resources (Contrib)</a></dt>
|
|
<dd>User contributed playbooks, modules, and articles</dd>
|
|
<dt><a class="reference internal" href="examples.html"><em>Command Line Examples And Next Steps</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 Sep 11, 2012.<br/>
|
|
</p>
|
|
</div>
|
|
</footer>
|
|
</body>
|
|
</html>
|