pull/1256/head
Michael DeHaan 12 years ago
parent be6b9b0594
commit 47542aefc5

@ -165,6 +165,7 @@ s.parentNode.insertBefore(ga, s);
<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>
@ -236,6 +237,59 @@ not have to write modules in any particular language &#8211; you get to choose.<
playbooks, these modules can trigger &#8216;change events&#8217; in the form of notifying &#8216;handlers&#8217;
to run additional tasks.</p>
<p>Let&#8217;s see what&#8217;s available in the Ansible module library, out of the box:</p>
<table border="1" class="docutils">
<colgroup>
<col width="33%" />
<col width="33%" />
<col width="33%" />
</colgroup>
<tbody valign="top">
<tr><td><a class="reference internal" href="#apt-repository"><em>apt_repository</em></a></td>
<td><a class="reference internal" href="#apt"><em>apt</em></a></td>
<td><a class="reference internal" href="#assemble"><em>assemble</em></a></td>
</tr>
<tr><td><a class="reference internal" href="#authorized-key"><em>authorized_key</em></a></td>
<td><a class="reference internal" href="#command"><em>command</em></a></td>
<td><a class="reference internal" href="#copy"><em>copy</em></a></td>
</tr>
<tr><td><a class="reference internal" href="#easy-install"><em>easy_install</em></a></td>
<td><a class="reference internal" href="#facter"><em>facter</em></a></td>
<td><a class="reference internal" href="#fetch"><em>fetch</em></a></td>
</tr>
<tr><td><a class="reference internal" href="#file"><em>file</em></a></td>
<td><a class="reference internal" href="#get-url"><em>get_url</em></a></td>
<td><a class="reference internal" href="#git"><em>git</em></a></td>
</tr>
<tr><td><a class="reference internal" href="#group"><em>group</em></a></td>
<td><a class="reference internal" href="#mount"><em>mount</em></a></td>
<td><a class="reference internal" href="#mysql-db"><em>mysql_db</em></a></td>
</tr>
<tr><td><a class="reference internal" href="#mysql-user"><em>mysql_user</em></a></td>
<td><a class="reference internal" href="#nagios"><em>nagios</em></a></td>
<td><a class="reference internal" href="#ohai"><em>ohai</em></a></td>
</tr>
<tr><td><a class="reference internal" href="#ping"><em>ping</em></a></td>
<td><a class="reference internal" href="#pip"><em>pip</em></a></td>
<td><a class="reference internal" href="#postgresql-db"><em>postgresql_db</em></a></td>
</tr>
<tr><td><a class="reference internal" href="#postgresql-user"><em>postgresql_user</em></a></td>
<td><a class="reference internal" href="#raw"><em>raw</em></a></td>
<td><a class="reference internal" href="#service"><em>service</em></a></td>
</tr>
<tr><td><a class="reference internal" href="#setup"><em>setup</em></a></td>
<td><a class="reference internal" href="#shell"><em>shell</em></a></td>
<td><a class="reference internal" href="#supervisorctl"><em>supervisorctl</em></a></td>
</tr>
<tr><td><a class="reference internal" href="#template"><em>template</em></a></td>
<td><a class="reference internal" href="#user"><em>user</em></a></td>
<td><a class="reference internal" href="#virt"><em>virt</em></a></td>
</tr>
<tr><td><a class="reference internal" href="#yum"><em>yum</em></a></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>
</tbody>
</table>
<div class="section" id="apt-repository">
<span id="id1"></span><h2>apt_repository<a class="headerlink" href="#apt-repository" title="Permalink to this headline"></a></h2>
<p class="versionadded">
@ -990,7 +1044,7 @@ finally fall back to using the MySQL default login of &#8216;root&#8217; with no
</div>
</div>
<div class="section" id="mysql-user">
<h2>mysql_user<a class="headerlink" href="#mysql-user" title="Permalink to this headline"></a></h2>
<span id="id16"></span><h2>mysql_user<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>
@ -1067,8 +1121,215 @@ finally fall back to using the MySQL default login of &#8216;root&#8217; with no
action: mysql_user login_user=root login_password=123456 name=sally state=absent</pre>
</div>
</div>
<div class="section" id="nagios">
<span id="id17"></span><h2>nagios<a class="headerlink" href="#nagios" title="Permalink to this headline"></a></h2>
<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><th class="head">parameter</th>
<th class="head">required</th>
<th class="head">default</th>
<th class="head">comments</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>action</td>
<td>yes</td>
<td>&nbsp;</td>
<td>one of: &#8216;downtime&#8217;, &#8216;enable_alerts&#8217;/&#8217;disable_alerts&#8217;, or
&#8216;silence&#8217;/&#8217;unsilence&#8217;</td>
</tr>
<tr><td>host</td>
<td>yes</td>
<td>&nbsp;</td>
<td>host to operate on in nagios</td>
</tr>
<tr><td>cmdfile</td>
<td>no</td>
<td>/var/spool/nagios/cmd/nagios.cmd</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><th class="head">parameter</th>
<th class="head">required</th>
<th class="head">default</th>
<th class="head">comments</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>author</td>
<td>no</td>
<td>Ansible</td>
<td>author to leave downtime comments as</td>
</tr>
<tr><td>minutes</td>
<td>no</td>
<td>30</td>
<td>minutes to schedule downtime for</td>
</tr>
<tr><td>services</td>
<td>no</td>
<td>&nbsp;</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><th class="head">parameter</th>
<th class="head">required</th>
<th class="head">default</th>
<th class="head">comments</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>services</td>
<td>no</td>
<td>&nbsp;</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 keyword,
<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 of Scheduling Downtime in <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=15 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</pre>
</div>
<p>And from the command line:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible nagios.example.com -m nagios -a <span class="s2">&quot;action=downtime minutes=15 service=httpd host=server01.example.com&quot;</span>
<span class="nv">$ </span>ansible nagios.example.com -m nagios -a <span class="s2">&quot;action=downtime minutes=60 service=host host=server01.example.com&quot;</span>
<span class="nv">$ </span>ansible nagios.example.com -m nagios -a <span class="s2">&quot;action=downtime services=frob,foobar,qeuz host=server01.example.com&quot;</span>
</pre></div>
</div>
<p>Examples of handling specific host/service alerts in <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
<div class="highlight-python"><pre>---
- hosts: webservers
user: root
tasks:
- name: enable SMART disk alerts
action: nagios action=enable_alerts service=smart host=$inventory_hostname
delegate_to: nagios.example.com
# Note that 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
# And disabling HOST alerts
- name: disable HOST alerts
action: nagios action=disable_alerts service=host host=$inventory_hostname
delegate_to: nagios.example.com</pre>
</div>
<p>And from the command line:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible nagios.example.com -m nagios -a <span class="s2">&quot;action=enable_alerts service=smart host=server01.example.com&quot;</span>
<span class="nv">$ </span>ansible nagios.example.com -m nagios -a <span class="s2">&quot;action=disable_alerts service=httpd,nfs host=server01.example.com&quot;</span>
<span class="nv">$ </span>ansible nagios.example.com -m nagios -a <span class="s2">&quot;action=disable_alerts service=host host=server01.example.com&quot;</span>
</pre></div>
</div>
<p>Examples of Silencing all host/service alerts in <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
<div class="highlight-python"><pre>---
- hosts: webservers
user: root
tasks:
- 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>And from the command line:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible nagios.example.com -m nagios -a <span class="s2">&quot;action=silence host=server01.example.com&quot;</span>
<span class="nv">$ </span>ansible nagios.example.com -m nagios -a <span class="s2">&quot;action=unsilence host=server01.example.com&quot;</span>
</pre></div>
</div>
<p><strong>Optional Configuration</strong></p>
<p>If your nagios <strong>cmdfile</strong> is not <tt class="docutils literal"><span class="pre">/var/spool/nagios/cmd/nagios.cmd</span></tt>
you can configure ansible (on your nagios server) to use the correct
one by making a file called <tt class="docutils literal"><span class="pre">/etc/ansible/modules/nagios.conf</span></tt> that
looks like this:</p>
<div class="highlight-ini"><div class="highlight"><pre><span class="k">[main]</span>
<span class="na">cmdfile</span> <span class="o">=</span> <span class="s">/path/to/your/nagios.cmd</span>
</pre></div>
</div>
<p>Or, use the <strong>cmdfile</strong> parameter to set it explicitly.</p>
<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">&quot;msg&quot;</span><span class="p">:</span> <span class="s">&quot;unable to write to nagios command file&quot;</span><span class="p">,</span> <span class="s">&quot;failed&quot;</span><span class="p">:</span> <span class="n">true</span><span class="p">,</span> <span class="s">&quot;cmdfile&quot;</span><span class="p">:</span> <span class="s">&quot;/var/spool/nagios/cmd/nagios.cmd&quot;</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="id16"></span><h2>ohai<a class="headerlink" href="#ohai" title="Permalink to this headline"></a></h2>
<span id="id18"></span><h2>ohai<a class="headerlink" href="#ohai" title="Permalink to this headline"></a></h2>
<p>Similar to the <a class="reference internal" href="#facter"><em>facter</em></a> module, this returns JSON inventory data.
Ohai data is a bit more verbose and nested than facter.</p>
<p>Requires that &#8216;ohai&#8217; be installed on the remote end.</p>
@ -1079,7 +1340,7 @@ Ohai data is a bit more verbose and nested than facter.</p>
</div>
</div>
<div class="section" id="ping">
<span id="id17"></span><h2>ping<a class="headerlink" href="#ping" title="Permalink to this headline"></a></h2>
<span id="id19"></span><h2>ping<a class="headerlink" href="#ping" title="Permalink to this headline"></a></h2>
<p>A trivial test module, this module always returns &#8216;pong&#8217; on
successful contact. It does not make sense in playbooks, but is useful
from /usr/bin/ansible:</p>
@ -1087,7 +1348,7 @@ from /usr/bin/ansible:</p>
</div>
</div>
<div class="section" id="pip">
<span id="id18"></span><h2>pip<a class="headerlink" href="#pip" title="Permalink to this headline"></a></h2>
<span id="id20"></span><h2>pip<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>
@ -1145,7 +1406,7 @@ pip requirements=/srv/webapps/my_app/src/requirements.txt virtualenv=/srv/webapp
</div>
</div>
<div class="section" id="postgresql-db">
<span id="id20"></span><h2>postgresql_db<a class="headerlink" href="#postgresql-db" title="Permalink to this headline"></a></h2>
<span id="id22"></span><h2>postgresql_db<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>
@ -1192,6 +1453,11 @@ host before using this module.</p>
<td>&nbsp;</td>
<td>host running PostgreSQL. Default (blank) implies localhost</td>
</tr>
<tr><td>owner</td>
<td>no</td>
<td>&nbsp;</td>
<td>name of the role to set as owner of the database</td>
</tr>
<tr><td>state</td>
<td>&nbsp;</td>
<td>present</td>
@ -1204,11 +1470,11 @@ host before using this module.</p>
</div>
</div>
<div class="section" id="postgresql-user">
<span id="id21"></span><h2>postgresql_user<a class="headerlink" href="#postgresql-user" title="Permalink to this headline"></a></h2>
<span id="id23"></span><h2>postgresql_user<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 grant the users
access to an existing database.</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&#8217;ing to the postgres account on the host.</p>
<p>This module uses psycopg2, a Python PostgreSQL database adapter. You must
@ -1243,9 +1509,19 @@ host before using this module.</p>
<td>set the user&#8217;s password</td>
</tr>
<tr><td>db</td>
<td>yes</td>
<td>no</td>
<td>&nbsp;</td>
<td>name of database where permissions will be granted</td>
</tr>
<tr><td>priv</td>
<td>no</td>
<td>&nbsp;</td>
<td>name of an existing database to grant user access to</td>
<td>PostgreSQL privileges string in the format: table:priv1,priv2</td>
</tr>
<tr><td>fail_on_user</td>
<td>no</td>
<td>yes</td>
<td>if yes, fail when user can&#8217;t be removed. Otherwise just log and continue</td>
</tr>
<tr><td>login_user</td>
<td>no</td>
@ -1269,12 +1545,29 @@ host before using this module.</p>
</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>postgresql_user db=acme user=django password=ceec4eif7ya</pre>
<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="id22"></span><h2>raw<a class="headerlink" href="#raw" title="Permalink to this headline"></a></h2>
<span id="id24"></span><h2>raw<a class="headerlink" href="#raw" title="Permalink to this headline"></a></h2>
<p>Executes a low-down and dirty SSH command, not going through the module subsystem.</p>
<p>This is useful and should only be done in two cases. The first case is installing
python-simplejson on older (python 2.4 and before) hosts that need it as a dependency
@ -1289,7 +1582,7 @@ for this module.</p>
</div>
</div>
<div class="section" id="service">
<span id="id23"></span><h2>service<a class="headerlink" href="#service" title="Permalink to this headline"></a></h2>
<span id="id25"></span><h2>service<a class="headerlink" href="#service" title="Permalink to this headline"></a></h2>
<p>Controls services on remote machines.</p>
<table border="1" class="docutils">
<colgroup>
@ -1342,7 +1635,7 @@ service name=foo pattern=/usr/bin/foo state=started</pre>
</div>
</div>
<div class="section" id="setup">
<span id="id24"></span><h2>setup<a class="headerlink" href="#setup" title="Permalink to this headline"></a></h2>
<span id="id26"></span><h2>setup<a class="headerlink" href="#setup" title="Permalink to this headline"></a></h2>
<p>This module is automatically called by playbooks to gather useful variables about remote hosts that can be used
in playbooks. It can also be executed directly by /usr/bin/ansible to check what variables are available
to a host.</p>
@ -1424,7 +1717,7 @@ on your remote systems.</p>
</div>
</div>
<div class="section" id="shell">
<span id="id25"></span><h2>shell<a class="headerlink" href="#shell" title="Permalink to this headline"></a></h2>
<span id="id27"></span><h2>shell<a class="headerlink" href="#shell" title="Permalink to this headline"></a></h2>
<p>The shell module takes the command name followed by a list of
arguments, space delimited. It is almost exactly like the command module
but runs the command through the user&#8217;s configured shell on the remote node.</p>
@ -1474,7 +1767,7 @@ your best judgement.</p>
</div>
</div>
<div class="section" id="subversion">
<span id="id26"></span><h2>subversion<a class="headerlink" href="#subversion" title="Permalink to this headline"></a></h2>
<span id="id28"></span><h2>subversion<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>
@ -1516,7 +1809,7 @@ discarded. If no, this module will fail if it encounters modified files.</td>
</div>
</div>
<div class="section" id="supervisorctl">
<span id="id27"></span><h2>supervisorctl<a class="headerlink" href="#supervisorctl" title="Permalink to this headline"></a></h2>
<span id="id29"></span><h2>supervisorctl<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>
@ -1552,7 +1845,7 @@ discarded. If no, this module will fail if it encounters modified files.</td>
</div>
</div>
<div class="section" id="template">
<span id="id28"></span><h2>template<a class="headerlink" href="#template" title="Permalink to this headline"></a></h2>
<span id="id30"></span><h2>template<a class="headerlink" href="#template" title="Permalink to this headline"></a></h2>
<p>Templates a file out to a remote server.</p>
<table border="1" class="docutils">
<colgroup>
@ -1592,7 +1885,7 @@ a relative or absolute path.</td>
</div>
</div>
<div class="section" id="user">
<span id="id29"></span><h2>user<a class="headerlink" href="#user" title="Permalink to this headline"></a></h2>
<span id="id31"></span><h2>user<a class="headerlink" href="#user" title="Permalink to this headline"></a></h2>
<p>Creates user accounts, manipulates existing user accounts, and removes user accounts.</p>
<table border="1" class="docutils">
<colgroup>
@ -1691,7 +1984,7 @@ user name=mdehaan state=absent force=yes</pre>
</div>
</div>
<div class="section" id="virt">
<span id="id30"></span><h2>virt<a class="headerlink" href="#virt" title="Permalink to this headline"></a></h2>
<span id="id32"></span><h2>virt<a class="headerlink" href="#virt" title="Permalink to this headline"></a></h2>
<p>Manages virtual machines supported by libvirt. Requires that libvirt be installed
on the managed machine.</p>
<table border="1" class="docutils">
@ -1751,7 +2044,7 @@ ansible host -m virt -a "command=virttype"</pre>
</div>
</div>
<div class="section" id="yum">
<span id="id31"></span><h2>yum<a class="headerlink" href="#yum" title="Permalink to this headline"></a></h2>
<span id="id33"></span><h2>yum<a class="headerlink" href="#yum" title="Permalink to this headline"></a></h2>
<p>Will install, upgrade, remove, and list packages with the yum package manager.</p>
<table border="1" class="docutils">
<colgroup>

File diff suppressed because one or more lines are too long
Loading…
Cancel
Save