<h2><aclass="toc-backref"href="#table-of-contents">Plugins Repository</a><aclass="headerlink"href="#plugins-repository"title="Permalink to this headline">¶</a></h2>
<p>The remainder of features in the API docs have components available in the <aclass="reference external"href="http://github.com/ansible/ansible-plugins">ansible-plugins</a> repository. Please consult this repository for more information. Send us a github pull request if you develop any interesting features.</p>
<p>The remainder of features in the API docs have components available in <aclass="reference external"href="https://github.com/ansible/ansible/blob/devel/plugins">ansible-plugins</a>. Send us a github pull request if you develop any interesting features.</p>
<h2><aclass="toc-backref"href="#table-of-contents">External Inventory Scripts</a><aclass="headerlink"href="#external-inventory-scripts"title="Permalink to this headline">¶</a></h2>
<p>Often a user of a configuration management system will want to keep inventory
in a different system. Frequent examples include LDAP, <aclass="reference external"href="http://cobbler.github.com">Cobbler</a>,
or a piece of expensive enterprisey CMDB software. Ansible easily supports all
of these options via an external inventory system. The ansible-plugins repo contains some of these already – including options for EC2/Eucalyptus and OpenStack, which will be detailed below.</p>
of these options via an external inventory system. The plugins directory contains some of these already – including options for EC2/Eucalyptus and OpenStack, which will be detailed below.</p>
<p>It’s possible to write an external inventory script in any language. If you are familiar with Puppet terminology, this concept is basically the same as ‘external nodes’, with the slight difference that it also defines which hosts are managed.</p>
<divclass="section"id="script-conventions">
<h3>Script Conventions<aclass="headerlink"href="#script-conventions"title="Permalink to this headline">¶</a></h3>
@ -314,7 +299,7 @@ if the script does not wish to do this, returning an empty hash/dictionary is th
layer that allows it to represent data for multiple configuration management systems (even at the same time), and has
been referred to as a ‘lightweight CMDB’ by some admins. This particular script will communicate with Cobbler
using Cobbler’s XMLRPC API.</p>
<p>To tie Ansible’s inventory to Cobbler (optional), copy <aclass="reference external"href="https://github.com/ansible/ansible-plugins/blob/master/inventory/cobbler.py">this script</a> to /etc/ansible/hosts and <cite>chmod +x</cite> the file. cobblerd will now need
<p>To tie Ansible’s inventory to Cobbler (optional), copy <aclass="reference external"href="https://raw.github.com/ansible/ansible/devel/plugins/inventory/cobbler.py">this script</a> to /etc/ansible/hosts and <cite>chmod +x</cite> the file. cobblerd will now need
to be running when you are using Ansible.</p>
<p>Test the file by running <cite>./etc/ansible/hosts</cite> directly. You should see some JSON data output, but it may not have
anything in it just yet.</p>
@ -355,7 +340,7 @@ a conf.d file appropriately or something similar. Who knows?</p>
<h3>Example: AWS EC2 External Inventory Script<aclass="headerlink"href="#example-aws-ec2-external-inventory-script"title="Permalink to this headline">¶</a></h3>
<p>If you use Amazon Web Services EC2, maintaining an inventory file might not be the best approach. For this reason, you can use the <aclass="reference external"href="https://github.com/ansible/ansible-plugins/blob/master/inventory/ec2.py">EC2 external inventory</a> script.</p>
<p>If you use Amazon Web Services EC2, maintaining an inventory file might not be the best approach. For this reason, you can use the <aclass="reference external"href="https://raw.github.com/ansible/ansible/devel/plugins/inventory/ec2.py">EC2 external inventory</a> script.</p>
<p>You can use this script in one of two ways. The easiest is to use Ansible’s <ttclass="docutils literal"><spanclass="pre">-i</span></tt> command line option and specify the path to the script.</p>
<h3>Example: OpenStack<aclass="headerlink"href="#example-openstack"title="Permalink to this headline">¶</a></h3>
<p>Though not detailed here in as much depth as the EC2 module, there’s also a OpenStack Nova external inventory source in the ansible-plugins repository. See the inline comments in the module source.</p>
<p>Though not detailed here in as much depth as the EC2 module, there’s also a OpenStack Nova external inventory source in the plugins directory. See the inline comments in the module source.</p>
</div>
</div>
<divclass="section"id="callback-plugins">
<h2><aclass="toc-backref"href="#table-of-contents">Callback Plugins</a><aclass="headerlink"href="#callback-plugins"title="Permalink to this headline">¶</a></h2>
<p>Ansible can be configured via code to respond to external events. This can include enhancing logging, signalling an external software
system, or even (yes, really) making sound effects. Some examples are contained in the ansible-plugins repository.</p>
system, or even (yes, really) making sound effects. Some examples are contained in the plugins directory.</p>
</div>
<divclass="section"id="connection-type-plugins">
<h2><aclass="toc-backref"href="#table-of-contents">Connection Type Plugins</a><aclass="headerlink"href="#connection-type-plugins"title="Permalink to this headline">¶</a></h2>
@ -468,7 +453,7 @@ JSON is probably the simplest way to go.</p>
<divclass="section"id="sharing-your-module">
<h2><aclass="toc-backref"href="#contents">Sharing Your Module</a><aclass="headerlink"href="#sharing-your-module"title="Permalink to this headline">¶</a></h2>
<p>If you think your module is generally useful to others, a good place to share it
is in <aclass="reference external"href="https://github.com/ansible/ansible-resources">Ansible Resources</a>. This is maintained
is in <aclass="reference external"href="https://github.com/ansible/ansible/tree/devel/contrib">Ansible Resources</a>. This is maintained
as a simple repo with pointers to other github projects.</p>
<p>Contrib modules here can be implemented in a variety of languages.
We would like to build up as many of these as possible in as many languages as possible.</p>
@ -486,7 +471,7 @@ the program. Stop by the mailing list to inquire about requirements.</p>
<spanid="id8"></span><h2><aclass="toc-backref"href="#contents">cron</a><aclass="headerlink"href="#cron"title="Permalink to this headline">¶</a></h2>
<pclass="versionadded">
<spanclass="versionmodified">New in version 0.9.</span></p>
<p>Use this module to manage crontab entries. This module allows you to create named crontab entries, update, or delete them.
The module include one line with the description of the crontab entry “#Ansible: <name>” corresponding to the “name” passed to the module, which is used by future ansible/module calls to find/check the state.</p>
<table>
<tr>
<thclass="head">parameter</th>
<thclass="head">required</th>
<thclass="head">default</th>
<thclass="head">choices</th>
<thclass="head">comments</th>
</tr>
<tr>
<td>name</td>
<td>yes</td>
<td></td>
<td><ul></ul></td>
<td>Description of a crontab entry.</td>
</tr>
<tr>
<td>hour</td>
<td>no</td>
<td>*</td>
<td><ul></ul></td>
<td>Hour when the job should run ( 0-23, *, */2, etc )</td>
</tr>
<tr>
<td>job</td>
<td>no</td>
<td></td>
<td><ul></ul></td>
<td>The command to execute.Required if state=present.</td>
</tr>
<tr>
<td>month</td>
<td>no</td>
<td>*</td>
<td><ul></ul></td>
<td>Month of the year the job should run ( 1-12, *, */2, etc )</td>
</tr>
<tr>
<td>state</td>
<td>no</td>
<td>present</td>
<td><ul></ul></td>
<td>Whether to ensure the job is present or absent.</td>
</tr>
<tr>
<td>user</td>
<td>no</td>
<td>root</td>
<td><ul></ul></td>
<td>The specific user who's crontab should be modified.</td>
</tr>
<tr>
<td>backup</td>
<td>no</td>
<td></td>
<td><ul></ul></td>
<td>If set, then create a backup of the crontab before it is modified.The location of the backup is returned in the 'backup' variable by this module.</td>
</tr>
<tr>
<td>day</td>
<td>no</td>
<td>*</td>
<td><ul></ul></td>
<td>Day of the month the job should run ( 1-31, *, */2, etc )</td>
</tr>
<tr>
<td>minute</td>
<td>no</td>
<td>*</td>
<td><ul></ul></td>
<td>Minute when the job should run ( 0-59, *, */2, etc )</td>
</tr>
<tr>
<td>weekday</td>
<td>no</td>
<td>*</td>
<td><ul></ul></td>
<td>Day of the week that the job should run ( 0-7 for Sunday - Saturday, or mon, tue, * etc )</td>
</tr>
</table><p>Ensure a job that runs at 2 and 5 exists. Creates an entry like "* 5,2 * * ls -alh > /dev/null"</p><p><pre>
<p>Ensure an old job is no longer present. Removes any job that is preceded by "#Ansible: an old job" in the crontab</p><p><pre>
name="an old job" cron job="/some/dir/job.sh" state=absent
</pre></p>
<br/></div>
<divclass="section"id="debug">
<spanid="id9"></span><h2><aclass="toc-backref"href="#contents">debug</a><aclass="headerlink"href="#debug"title="Permalink to this headline">¶</a></h2>
<pclass="versionadded">
<spanclass="versionmodified">New in version 0.8.</span></p>
<p>This module prints statements during execution and can be useful for debugging variables or expressions without necessarily halting the playbook. Useful for debugging together with the only_if directive.
In order to see the debug message, you need to run ansible in verbose mode (using the -v option).</p>
<table>
<tr>
<thclass="head">parameter</th>
<thclass="head">required</th>
<thclass="head">default</th>
<thclass="head">choices</th>
<thclass="head">comments</th>
</tr>
<tr>
<td>msg</td>
<td>no</td>
<td>Hello world!</td>
<td><ul></ul></td>
<td>The customized message that is printed. If ommited, prints a generic message.</td>
</tr>
<tr>
<td>fail</td>
<td>no</td>
<td>no</td>
<td><ul></ul></td>
<td>A boolean that indicates whether the debug module should fail or not.</td>
</tr>
<tr>
<td>rc</td>
<td>no</td>
<td></td>
<td><ul></ul></td>
<td>The return code of the module. If fail=yes, this will default to 1.</td>
</tr>
</table><p>Example that prints the loopback address and gateway for each host</p><p><pre>
[{'local_action': 'debug msg="System $inventory_hostname has uuid $ansible_product_uuid"'}, {'only_if': "is_unset('${ansible_default_ipv4.gateway}')", 'local_action': 'debug msg="System $inventory_hostname lacks a gateway" fail=yes'}, {'only_if': "is_set('${ansible_default_ipv4.gateway}')", 'local_action': 'debug msg="System $inventory_hostname has gateway ${ansible_default_ipv4.gateway}"'}]
</pre></p>
<br/></div>
<divclass="section"id="easy-install">
<spanid="id8"></span><h2><aclass="toc-backref"href="#contents">easy_install</a><aclass="headerlink"href="#easy-install"title="Permalink to this headline">¶</a></h2>
<spanid="id10"></span><h2><aclass="toc-backref"href="#contents">easy_install</a><aclass="headerlink"href="#easy-install"title="Permalink to this headline">¶</a></h2>
<pclass="versionadded">
<spanclass="versionmodified">New in version 0.7.</span></p>
<p>Installs Python libraries, optionally in a <em>virtualenv</em></p>
<p>Please note that the <spanclass='module'>easy_install</span> module can only install Python libraries. Thus this module is not able to remove libraries. It is generally recommended to use the <spanclass='module'>pip</span> module which you can first install using <spanclass='module'>easy_install</span>.</p>
<p>Also note that <em>virtualenv</em> must be installed on the remote host if the <code>virtualenv</code> parameter is specified.</p></div>
<divclass="section"id="facter">
<spanid="id9"></span><h2><aclass="toc-backref"href="#contents">facter</a><aclass="headerlink"href="#facter"title="Permalink to this headline">¶</a></h2>
<spanid="id11"></span><h2><aclass="toc-backref"href="#contents">facter</a><aclass="headerlink"href="#facter"title="Permalink to this headline">¶</a></h2>
<pclass="versionadded">
<spanclass="versionmodified">New in version 0.2.</span></p>
<p>Runs the <em>facter</em> discovery program (<aclass="reference external"href="https://github.com/puppetlabs/facter">https://github.com/puppetlabs/facter</a>) on the remote system, returning JSON data that can be useful for inventory purposes.</p>
<td>The return code of the failure. This is currently not used by Ansible, but might be used in the future.</td>
</tr>
</table><p>Example of how a playbook may fail when a condition is not met</p><p><pre>
[{'action': 'fail msg="The system may not be provisioned according to the CMDB status."', 'only_if': "'$cmdb_status' != 'to-be-staged'"}]
</pre></p>
<br/></div>
</table><p>Example playbook using fail and only_if together</p><p><pre>
action: fail msg="The system may not be provisioned according to the CMDB status." rc=100<p>only_if: “’$cmdb_status’ != ‘to-be-staged’”</p>
<blockquote>
<div></pre></p>
<br/></div></blockquote>
</div>
<divclass="section"id="fetch">
<spanid="id11"></span><h2><aclass="toc-backref"href="#contents">fetch</a><aclass="headerlink"href="#fetch"title="Permalink to this headline">¶</a></h2>
<spanid="id13"></span><h2><aclass="toc-backref"href="#contents">fetch</a><aclass="headerlink"href="#fetch"title="Permalink to this headline">¶</a></h2>
<pclass="versionadded">
<spanclass="versionmodified">New in version 0.2.</span></p>
<p>This module works like <ttclass="docutils literal"><spanclass="pre">copy</span></tt>, but in reverse. It is used for fetching files from remote machines and storing them locally in a file tree, organized by hostname.</p>
<spanid="id12"></span><h2><aclass="toc-backref"href="#contents">file</a><aclass="headerlink"href="#file"title="Permalink to this headline">¶</a></h2>
<spanid="id14"></span><h2><aclass="toc-backref"href="#contents">file</a><aclass="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 <ttclass="docutils literal"><spanclass="pre">copy</span></tt>, <ttclass="docutils literal"><spanclass="pre">template</span></tt>, and <ttclass="docutils literal"><spanclass="pre">assmeble</span></tt>.</p>
<p>See also <spanclass='module'>copy</span>, <spanclass='module'>template</span>, <spanclass='module'>assemble</span></p></div>
<divclass="section"id="fireball">
<spanid="id13"></span><h2><aclass="toc-backref"href="#contents">fireball</a><aclass="headerlink"href="#fireball"title="Permalink to this headline">¶</a></h2>
<spanid="id15"></span><h2><aclass="toc-backref"href="#contents">fireball</a><aclass="headerlink"href="#fireball"title="Permalink to this headline">¶</a></h2>
<pclass="versionadded">
<spanclass="versionmodified">New in version 0.9.</span></p>
<p>This modules launches an ephemeral <em>fireball</em> ZeroMQ message bus daemon on the remote node which Ansible can to communicate with nodes at high speed.
@ -886,7 +1013,7 @@ Fireball mode is AES encrypted</p>
<br/><h4>Notes</h4>
<p>See the advanced playbooks chapter for more about using fireball mode.</p></div>
<divclass="section"id="get-url">
<spanid="id14"></span><h2><aclass="toc-backref"href="#contents">get_url</a><aclass="headerlink"href="#get-url"title="Permalink to this headline">¶</a></h2>
<spanid="id16"></span><h2><aclass="toc-backref"href="#contents">get_url</a><aclass="headerlink"href="#get-url"title="Permalink to this headline">¶</a></h2>
<pclass="versionadded">
<spanclass="versionmodified">New in version 0.6.</span></p>
<p>Downloads files from HTTP, HTTPS, or FTP to the remote server. The remote server must have direct access to the remote resource.</p>
<spanid="id16"></span><h2><aclass="toc-backref"href="#contents">group</a><aclass="headerlink"href="#group"title="Permalink to this headline">¶</a></h2>
<spanid="id18"></span><h2><aclass="toc-backref"href="#contents">group</a><aclass="headerlink"href="#group"title="Permalink to this headline">¶</a></h2>
<pclass="versionadded">
<spanclass="versionmodified">New in version 0.0.2.</span></p>
<spanid="id19"></span><h2><aclass="toc-backref"href="#contents">hpilo_boot</a><aclass="headerlink"href="#hpilo-boot"title="Permalink to this headline">¶</a></h2>
<pclass="versionadded">
<spanclass="versionmodified">New in version 0.8.</span></p>
<p>This module boots a system through its HP iLO interface. The boot media can be one of: cdrom, floppy, hdd, network or usb.
This module requires the hpilo python module.</p>
<table>
<tr>
<thclass="head">parameter</th>
<thclass="head">required</th>
<thclass="head">default</th>
<thclass="head">choices</th>
<thclass="head">comments</th>
</tr>
<tr>
<td>force</td>
<td>no</td>
<td></td>
<td><ul><li>yes</li><li>no</li></ul></td>
<td>Whether to force a reboot (even when the system is already booted)</td>
<td>The URL of a cdrom, floppy or usb boot media image. <code>protocol://username:password@hostname:port/filename</code>protocol is either <code>http</code> or <code>https</code>username:password is optionalport is optional</td>
</tr>
<tr>
<td>host</td>
<td>yes</td>
<td></td>
<td><ul></ul></td>
<td>The HP iLO hostname/address that is linked to the physical system.</td>
<td>The state of the boot media.no_boot: Do not boot from the deviceboot_once: Boot from the device once and then notthereafterboot_always: Boot from the device each time the serveris rebootedconnect: Connect the virtual media device and set to boot_alwaysdisconnect: Disconnects the virtual media device and set to no_boot</td>
</tr>
<tr>
<td>login</td>
<td>no</td>
<td>Administrator</td>
<td><ul></ul></td>
<td>The login name to authenticate to the HP iLO interface.</td>
</tr>
<tr>
<td>password</td>
<td>no</td>
<td>admin</td>
<td><ul></ul></td>
<td>The password to authenticate to the HP iLO interface.</td>
</tr>
<tr>
<td>match</td>
<td>no</td>
<td></td>
<td><ul></ul></td>
<td>An optional string to match against the iLO server name.This is a safety measure to prevent accidentally using the wrong HP iLO interface with dire consequences.</td>
</tr>
</table><p>Task to boot a system using an ISO from an HP iLO interface only if the system is an HP server</p><p><pre>
<p>To use a USB key image you need to specify floppy as boot media.</p>
<p>This module ought to be run from a system that can access the HP iLO interface directly, either by using <code>local_action</code> or <code>using delegate</code>_to.</p></div>
<divclass="section"id="hpilo-facts">
<spanid="id20"></span><h2><aclass="toc-backref"href="#contents">hpilo_facts</a><aclass="headerlink"href="#hpilo-facts"title="Permalink to this headline">¶</a></h2>
<pclass="versionadded">
<spanclass="versionmodified">New in version 0.8.</span></p>
<p>This module gathers facts for a specific system using its HP iLO interface. These facts include hardware and network related information useful for provisioning (e.g. macaddress, uuid).
This module requires the hpilo python module.</p>
<table>
<tr>
<thclass="head">parameter</th>
<thclass="head">required</th>
<thclass="head">default</th>
<thclass="head">choices</th>
<thclass="head">comments</th>
</tr>
<tr>
<td>host</td>
<td>yes</td>
<td></td>
<td><ul></ul></td>
<td>The HP iLO hostname/address that is linked to the physical system.</td>
</tr>
<tr>
<td>password</td>
<td>no</td>
<td>admin</td>
<td><ul></ul></td>
<td>The password to authenticate to the HP iLO interface.</td>
</tr>
<tr>
<td>login</td>
<td>no</td>
<td>Administrator</td>
<td><ul></ul></td>
<td>The login name to authenticate to the HP iLO interface.</td>
</tr>
<tr>
<td>match</td>
<td>no</td>
<td></td>
<td><ul></ul></td>
<td>An optional string to match against the iLO server name.This is a safety measure to prevent accidentally using the wrong HP iLO interface with dire consequences.</td>
</tr>
</table><p>Task to gather facts from a HP iLO interface only if the system is an HP server</p><p><pre>
<p>This module ought to be run from a system that can access the HP iLO interface directly, either by using <code>local_action</code> or <code>using delegate</code>_to.</p></div>
<divclass="section"id="ini-file">
<spanid="id17"></span><h2><aclass="toc-backref"href="#contents">ini_file</a><aclass="headerlink"href="#ini-file"title="Permalink to this headline">¶</a></h2>
<spanid="id21"></span><h2><aclass="toc-backref"href="#contents">ini_file</a><aclass="headerlink"href="#ini-file"title="Permalink to this headline">¶</a></h2>
<pclass="versionadded">
<spanclass="versionmodified">New in version 0.9.</span></p>
<p>Manage (add, remove, change) individual settings in an INI-style file without having to manage the file as a whole with, say, <ttclass="docutils literal"><spanclass="pre">template</span></tt> or <ttclass="docutils literal"><spanclass="pre">assemble</span></tt>. Adds missing sections if they don’t exist.</p>
<p>While it is possible to add an <em>option</em> without specifying a <em>value</em>, this makes no sense.</p></div>
<divclass="section"id="lineinfile">
<spanid="id18"></span><h2><aclass="toc-backref"href="#contents">lineinfile</a><aclass="headerlink"href="#lineinfile"title="Permalink to this headline">¶</a></h2>
<spanid="id22"></span><h2><aclass="toc-backref"href="#contents">lineinfile</a><aclass="headerlink"href="#lineinfile"title="Permalink to this headline">¶</a></h2>
<pclass="versionadded">
<spanclass="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.
@ -1109,6 +1394,13 @@ This is primarily useful when you want to change a single line in a file only. F
<thclass="head">default</th>
<thclass="head">choices</th>
<thclass="head">comments</th>
</tr>
<tr>
<td>insertafter</td>
<td>no</td>
<td>EOF</td>
<td><ul><li>BOF</li><li>EOF</li></ul></td>
<td>Used with <code>state=present</code>. If specified, the line will be inserted after the specified regular expression. Two special values are available; <code>BOF</code> for inserting the line at the beginning of the file, and <code>EOF</code> for inserting the line at the end of the file.</td>
</tr>
<tr>
<td>state</td>
@ -1118,18 +1410,11 @@ This is primarily useful when you want to change a single line in a file only. F
<td>Whether the line should be there or not.</td>
</tr>
<tr>
<td>name</td>
<td>dest</td>
<td>yes</td>
<td></td>
<td><ul></ul></td>
<td>The file to modify</td>
</tr>
<tr>
<td>insertafter</td>
<td>no</td>
<td>EOF</td>
<td><ul><li>BOF</li><li>EOF</li></ul></td>
<td>Used with <code>state=present</code>. If specified, the line will be inserted after the specified regular expression. Two special values are available; <code>BOF</code> for inserting the line at the beginning of the file, and <code>EOF</code> for inserting the line at the end of the file.</td>
</tr>
<tr>
<td>regexp</td>
@ -1153,14 +1438,14 @@ This is primarily useful when you want to change a single line in a file only. F
<td>Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly.</td>
<spanid="id19"></span><h2><aclass="toc-backref"href="#contents">mount</a><aclass="headerlink"href="#mount"title="Permalink to this headline">¶</a></h2>
<spanid="id23"></span><h2><aclass="toc-backref"href="#contents">mount</a><aclass="headerlink"href="#mount"title="Permalink to this headline">¶</a></h2>
<pclass="versionadded">
<spanclass="versionmodified">New in version 0.6.</span></p>
<p>This module controls active and configured mount points in <ttclass="docutils literal"><spanclass="pre">/etc/fstab</span></tt>.</p>
@ -1226,7 +1511,7 @@ mount name=/mnt/dvd src=/dev/sr0 fstype=iso9660 opts=ro
</pre></p>
<br/></div>
<divclass="section"id="mysql-db">
<spanid="id20"></span><h2><aclass="toc-backref"href="#contents">mysql_db</a><aclass="headerlink"href="#mysql-db"title="Permalink to this headline">¶</a></h2>
<spanid="id24"></span><h2><aclass="toc-backref"href="#contents">mysql_db</a><aclass="headerlink"href="#mysql-db"title="Permalink to this headline">¶</a></h2>
<pclass="versionadded">
<spanclass="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>
<p>Both <code>login_password</code> and <code>login_username</code> are required when you are passing credentials. If none are present, the module will attempt to read the credentials from <code>~/.my.cnf</code>, and finally fall back to using the MySQL default login of 'root' with no password.</p></div>
<divclass="section"id="mysql-user">
<spanid="id21"></span><h2><aclass="toc-backref"href="#contents">mysql_user</a><aclass="headerlink"href="#mysql-user"title="Permalink to this headline">¶</a></h2>
<spanid="id25"></span><h2><aclass="toc-backref"href="#contents">mysql_user</a><aclass="headerlink"href="#mysql-user"title="Permalink to this headline">¶</a></h2>
<pclass="versionadded">
<spanclass="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>
<p>Both <code>login_password</code> and <code>login_username</code> are required when you are passing credentials. If none are present, the module will attempt to read the credentials from <code>~/.my.cnf</code>, and finally fall back to using the MySQL default login of 'root' with no password.</p></div>
<divclass="section"id="nagios">
<spanid="id22"></span><h2><aclass="toc-backref"href="#contents">nagios</a><aclass="headerlink"href="#nagios"title="Permalink to this headline">¶</a></h2>
<spanid="id26"></span><h2><aclass="toc-backref"href="#contents">nagios</a><aclass="headerlink"href="#nagios"title="Permalink to this headline">¶</a></h2>
<pclass="versionadded">
<spanclass="versionmodified">New in version 0.7.</span></p>
<p>The <ttclass="docutils literal"><spanclass="pre">nagios</span></tt> module has two basic functions: scheduling downtime and toggling alerts for services or hosts.
<spanid="id23"></span><h2><aclass="toc-backref"href="#contents">ohai</a><aclass="headerlink"href="#ohai"title="Permalink to this headline">¶</a></h2>
<spanid="id27"></span><h2><aclass="toc-backref"href="#contents">ohai</a><aclass="headerlink"href="#ohai"title="Permalink to this headline">¶</a></h2>
<pclass="versionadded">
<spanclass="versionmodified">New in version 0.6.</span></p>
<p>Similar to the <ttclass="docutils literal"><spanclass="pre">facter</span></tt> module, this runs the <em>ohai</em> discovery program (<aclass="reference external"href="http://wiki.opscode.com/display/chef/Ohai">http://wiki.opscode.com/display/chef/Ohai</a>) on the remote host and returns JSON inventory data. <em>Ohai</em> data is a bit more verbose and nested than <em>facter</em>.</p>
<spanid="id24"></span><h2><aclass="toc-backref"href="#contents">pause</a><aclass="headerlink"href="#pause"title="Permalink to this headline">¶</a></h2>
<spanid="id28"></span><h2><aclass="toc-backref"href="#contents">pause</a><aclass="headerlink"href="#pause"title="Permalink to this headline">¶</a></h2>
<pclass="versionadded">
<spanclass="versionmodified">New in version 0.8.</span></p>
<p>Pauses playbook execution for a set amount of time, or until a prompt is acknowledged. All parameters are optional. The default behavior is to pause with a prompt.
@ -1514,14 +1799,14 @@ pause prompt=Make sure org.foo.FooOverload exception is not present
</pre></p>
<br/></div>
<divclass="section"id="ping">
<spanid="id25"></span><h2><aclass="toc-backref"href="#contents">ping</a><aclass="headerlink"href="#ping"title="Permalink to this headline">¶</a></h2>
<spanid="id29"></span><h2><aclass="toc-backref"href="#contents">ping</a><aclass="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 <ttclass="docutils literal"><spanclass="pre">/usr/bin/ansible</span></tt></p>
<p>Test 'webservers' status</p><p><pre>
ansible webservers -m ping
</pre></p>
<br/></div>
<divclass="section"id="pip">
<spanid="id26"></span><h2><aclass="toc-backref"href="#contents">pip</a><aclass="headerlink"href="#pip"title="Permalink to this headline">¶</a></h2>
<spanid="id30"></span><h2><aclass="toc-backref"href="#contents">pip</a><aclass="headerlink"href="#pip"title="Permalink to this headline">¶</a></h2>
<pclass="versionadded">
<spanclass="versionmodified">New in version 0.7.</span></p>
<p>Please note that <ahref='http://www.virtualenv.org/, virtualenv'>http://www.virtualenv.org/, virtualenv</a> must be installed on the remote host if the virtualenv parameter is specified.</p></div>
<divclass="section"id="postgresql-db">
<spanid="id27"></span><h2><aclass="toc-backref"href="#contents">postgresql_db</a><aclass="headerlink"href="#postgresql-db"title="Permalink to this headline">¶</a></h2>
<spanid="id31"></span><h2><aclass="toc-backref"href="#contents">postgresql_db</a><aclass="headerlink"href="#postgresql-db"title="Permalink to this headline">¶</a></h2>
<pclass="versionadded">
<spanclass="versionmodified">New in version 0.6.</span></p>
<p>Add or remove PostgreSQL databases from a remote host.</p>
@ -1647,7 +1932,7 @@ postgresql_db db=acme
<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></div>
<divclass="section"id="postgresql-user">
<spanid="id28"></span><h2><aclass="toc-backref"href="#contents">postgresql_user</a><aclass="headerlink"href="#postgresql-user"title="Permalink to this headline">¶</a></h2>
<spanid="id32"></span><h2><aclass="toc-backref"href="#contents">postgresql_user</a><aclass="headerlink"href="#postgresql-user"title="Permalink to this headline">¶</a></h2>
<pclass="versionadded">
<spanclass="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>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></div>
<divclass="section"id="raw">
<spanid="id29"></span><h2><aclass="toc-backref"href="#contents">raw</a><aclass="headerlink"href="#raw"title="Permalink to this headline">¶</a></h2>
<spanid="id33"></span><h2><aclass="toc-backref"href="#contents">raw</a><aclass="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. 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 <ttclass="docutils literal"><spanclass="pre">shell</span></tt> or <ttclass="docutils literal"><spanclass="pre">command</span></tt> module is much more appropriate. Arguments given to <ttclass="docutils literal"><spanclass="pre">raw</span></tt> 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 /usr/bin/ansible to bootstrap a legacy python 2.4 host</p><p><pre>
ansible newhost.example.com -m raw -a "yum -y install python-simplejson"
</pre></p>
<br/></div>
<divclass="section"id="seboolean">
<spanid="id30"></span><h2><aclass="toc-backref"href="#contents">seboolean</a><aclass="headerlink"href="#seboolean"title="Permalink to this headline">¶</a></h2>
<spanid="id34"></span><h2><aclass="toc-backref"href="#contents">seboolean</a><aclass="headerlink"href="#seboolean"title="Permalink to this headline">¶</a></h2>
<pclass="versionadded">
<spanclass="versionmodified">New in version 0.7.</span></p>
<p>Not tested on any debian based system</p></div>
<divclass="section"id="selinux">
<spanid="id31"></span><h2><aclass="toc-backref"href="#contents">selinux</a><aclass="headerlink"href="#selinux"title="Permalink to this headline">¶</a></h2>
<spanid="id35"></span><h2><aclass="toc-backref"href="#contents">selinux</a><aclass="headerlink"href="#selinux"title="Permalink to this headline">¶</a></h2>
<pclass="versionadded">
<spanclass="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>
<p>Not tested on any debian based system</p></div>
<divclass="section"id="service">
<spanid="id32"></span><h2><aclass="toc-backref"href="#contents">service</a><aclass="headerlink"href="#service"title="Permalink to this headline">¶</a></h2>
<spanid="id36"></span><h2><aclass="toc-backref"href="#contents">service</a><aclass="headerlink"href="#service"title="Permalink to this headline">¶</a></h2>
<pclass="versionadded">
<spanclass="versionmodified">New in version 0.1.</span></p>
<td>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 <em>ps</em> command as a stand-in for a status result. If the string is found, the servie will be assumed to be running. (added in Ansible 0.7)</td>
<td>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 <em>ps</em> command as a stand-in for a status result. If the string is found, the service will be assumed to be running. (added in Ansible 0.7)</td>
</tr>
<tr>
<td>state</td>
@ -1885,7 +2170,7 @@ service name=foo pattern=/usr/bin/foo state=started
</pre></p>
<br/></div>
<divclass="section"id="setup">
<spanid="id33"></span><h2><aclass="toc-backref"href="#contents">setup</a><aclass="headerlink"href="#setup"title="Permalink to this headline">¶</a></h2>
<spanid="id37"></span><h2><aclass="toc-backref"href="#contents">setup</a><aclass="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 <ttclass="docutils literal"><spanclass="pre">/usr/bin/ansible</span></tt> to check what variables are available to a host. Ansible provides many <em>facts</em> about the system, automatically.</p>
<p>Obtain facts from all hosts and store them indexed by hostname at /tmp/facts.</p><p><pre>
ansible all -m setup -tree /tmp/facts
@ -1893,10 +2178,10 @@ ansible all -m setup -tree /tmp/facts
<br/><h4>Notes</h4>
<p>More ansible facts will be added with successive releases. If <em>facter</em> or <em>ohai</em> are installed, variables from these programs will also be snapshotted into the JSON file for usage in templating. These variables are prefixed with <code>facter_</code> and <code>ohai_</code> so it's easy to tell their source. All variables are bubbled up to the caller. Using the ansible facts and choosing to not install <em>facter</em> and <em>ohai</em> means you can avoid Ruby-dependencies on your remote systems.</p></div>
<divclass="section"id="shell">
<spanid="id34"></span><h2><aclass="toc-backref"href="#contents">shell</a><aclass="headerlink"href="#shell"title="Permalink to this headline">¶</a></h2>
<spanid="id38"></span><h2><aclass="toc-backref"href="#contents">shell</a><aclass="headerlink"href="#shell"title="Permalink to this headline">¶</a></h2>
<pclass="versionadded">
<spanclass="versionmodified">New in version 0.2.</span></p>
<p>The shell module takes the command name followed by a list of arguments, space delimited. It is almost exactly like the <ttclass="docutils literal"><spanclass="pre">command</span></tt> module but runs the command through the user’s configured shell on the remote node.</p>
<p>The shell module takes the command name followed by a list of arguments, space delimited. It is almost exactly like the <ttclass="docutils literal"><spanclass="pre">command</span></tt> module but runs the command through a shell (<ttclass="docutils literal"><spanclass="pre">/bin/sh</span></tt>) on the remote node.</p>
<p>If you want to execute a command securely and predicably, it may be better to use the <spanclass='module'>command</span> module instead. Best practices when writing playbooks will follow the trend of using <spanclass='module'>command</span> unless <spanclass='module'>shell</span> is explicitly required. When running ad-hoc commands, use your best judgement.</p></div>
<divclass="section"id="slurp">
<spanid="id35"></span><h2><aclass="toc-backref"href="#contents">slurp</a><aclass="headerlink"href="#slurp"title="Permalink to this headline">¶</a></h2>
<spanid="id39"></span><h2><aclass="toc-backref"href="#contents">slurp</a><aclass="headerlink"href="#slurp"title="Permalink to this headline">¶</a></h2>
<p>This module works like <ttclass="docutils literal"><spanclass="pre">fetch</span></tt>. It is used for fetching a base64- encoded blob containing the data in a remote file.</p>
<spanid="id36"></span><h2><aclass="toc-backref"href="#contents">subversion</a><aclass="headerlink"href="#subversion"title="Permalink to this headline">¶</a></h2>
<spanid="id40"></span><h2><aclass="toc-backref"href="#contents">subversion</a><aclass="headerlink"href="#subversion"title="Permalink to this headline">¶</a></h2>
<pclass="versionadded">
<spanclass="versionmodified">New in version 0.7.</span></p>
<p>This module is really simple, so for now this checks out from the given branch of a repo at a particular SHA or tag. Latest is not supported, you should not be doing that.</p>
<p>Requires subversion and grep on the client.</p></div>
<divclass="section"id="supervisorctl">
<spanid="id37"></span><h2><aclass="toc-backref"href="#contents">supervisorctl</a><aclass="headerlink"href="#supervisorctl"title="Permalink to this headline">¶</a></h2>
<spanid="id41"></span><h2><aclass="toc-backref"href="#contents">supervisorctl</a><aclass="headerlink"href="#supervisorctl"title="Permalink to this headline">¶</a></h2>
<pclass="versionadded">
<spanclass="versionmodified">New in version 0.7.</span></p>
<p>Manage the state of a program or group of programs running via Supervisord</p>
<spanid="id38"></span><h2><aclass="toc-backref"href="#contents">template</a><aclass="headerlink"href="#template"title="Permalink to this headline">¶</a></h2>
<spanid="id42"></span><h2><aclass="toc-backref"href="#contents">template</a><aclass="headerlink"href="#template"title="Permalink to this headline">¶</a></h2>
<p>Templates are processed by the Jinja2 templating language (<aclass="reference external"href="http://jinja.pocoo.org/docs/">http://jinja.pocoo.org/docs/</a>) - documentation on the template formatting can be found in the Template Designer Documentation (<aclass="reference external"href="http://jinja.pocoo.org/docs/templates/">http://jinja.pocoo.org/docs/templates/</a>).</p>
<spanid="id45"></span><h2><aclass="toc-backref"href="#contents">vsphere_facts</a><aclass="headerlink"href="#vsphere-facts"title="Permalink to this headline">¶</a></h2>
<pclass="versionadded">
<spanclass="versionmodified">New in version 0.8.</span></p>
<p>This module gathers facts for a specific guest on VMWare vSphere. These facts include hardware and network related information useful for provisioning (e.g. macaddress, uuid).
This module requires the pysphere python module.</p>
<table>
<tr>
<thclass="head">parameter</th>
<thclass="head">required</th>
<thclass="head">default</th>
<thclass="head">choices</th>
<thclass="head">comments</th>
</tr>
<tr>
<td>host</td>
<td>yes</td>
<td></td>
<td><ul></ul></td>
<td>The vSphere server from the cluster the virtual server is located on.</td>
</tr>
<tr>
<td>password</td>
<td>yes</td>
<td></td>
<td><ul></ul></td>
<td>The password to authenticate on the vSphere cluster.</td>
</tr>
<tr>
<td>login</td>
<td>yes</td>
<td></td>
<td><ul></ul></td>
<td>The login name to authenticate on the vSphere cluster.</td>
</tr>
<tr>
<td>guest</td>
<td>yes</td>
<td></td>
<td><ul></ul></td>
<td>The virtual server to gather facts for on the vSphere cluster.</td>
</tr>
</table><p>Task to gather facts from a vSphere cluster only if the system is a VMWare guest</p><p><pre>
<p>This module ought to be run from a system that can access vSphere directly. Either by using <code>local_action</code>, or <code>using delegate</code>_to.</p></div>
<divclass="section"id="wait-for">
<spanid="id41"></span><h2><aclass="toc-backref"href="#contents">wait_for</a><aclass="headerlink"href="#wait-for"title="Permalink to this headline">¶</a></h2>
<spanid="id46"></span><h2><aclass="toc-backref"href="#contents">wait_for</a><aclass="headerlink"href="#wait-for"title="Permalink to this headline">¶</a></h2>
<pclass="versionadded">
<spanclass="versionmodified">New in version 0.7.</span></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 <ttclass="docutils literal"><spanclass="pre">virt</span></tt> module and needing to pause until they are ready.</p>
@ -2280,7 +2617,7 @@ wait_for port=8000 delay=10
</pre></p>
<br/></div>
<divclass="section"id="yum">
<spanid="id42"></span><h2><aclass="toc-backref"href="#contents">yum</a><aclass="headerlink"href="#yum"title="Permalink to this headline">¶</a></h2>
<spanid="id47"></span><h2><aclass="toc-backref"href="#contents">yum</a><aclass="headerlink"href="#yum"title="Permalink to this headline">¶</a></h2>
<p>Will install, upgrade, remove, and list packages with the <em>yum</em> package manager.</p>
@ -17,6 +17,13 @@ This is primarily useful when you want to change a single line in a file only. F
<th class="head">default</th>
<th class="head">choices</th>
<th class="head">comments</th>
</tr>
<tr>
<td>insertafter</td>
<td>no</td>
<td>EOF</td>
<td><ul><li>BOF</li><li>EOF</li></ul></td>
<td>Used with <code>state=present</code>. If specified, the line will be inserted after the specified regular expression. Two special values are available; <code>BOF</code> for inserting the line at the beginning of the file, and <code>EOF</code> for inserting the line at the end of the file.</td>
</tr>
<tr>
<td>state</td>
@ -26,18 +33,11 @@ This is primarily useful when you want to change a single line in a file only. F
<td>Whether the line should be there or not.</td>
</tr>
<tr>
<td>name</td>
<td>dest</td>
<td>yes</td>
<td></td>
<td><ul></ul></td>
<td>The file to modify</td>
</tr>
<tr>
<td>insertafter</td>
<td>no</td>
<td>EOF</td>
<td><ul><li>BOF</li><li>EOF</li></ul></td>
<td>Used with <code>state=present</code>. If specified, the line will be inserted after the specified regular expression. Two special values are available; <code>BOF</code> for inserting the line at the beginning of the file, and <code>EOF</code> for inserting the line at the end of the file.</td>
</tr>
<tr>
<td>regexp</td>
@ -65,10 +65,10 @@ This is primarily useful when you want to change a single line in a file only. F
@ -22,7 +22,7 @@ Controls services on remote hosts.
<td>no</td>
<td></td>
<td><ul></ul></td>
<td>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 <em>ps</em> command as a stand-in for a status result. If the string is found, the servie will be assumed to be running. (added in Ansible 0.7)</td>
<td>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 <em>ps</em> command as a stand-in for a status result. If the string is found, the service will be assumed to be running. (added in Ansible 0.7)</td>
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.
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 a shell (``/bin/sh``) on the remote node.
Michael DeHaan
12 years ago