add a user + docs rebuild

api.html

@@ -156,6 +156,7 @@ s.parentNode.insertBefore(ga, s);
 <li><a class="reference internal" href="#external-inventory">External Inventory</a><ul>
 <li><a class="reference internal" href="#script-conventions">Script Conventions</a></li>
 <li><a class="reference internal" href="#example-the-cobbler-external-inventory-script">Example: The Cobbler External Inventory Script</a></li>
+<li><a class="reference internal" href="#example-aws-ec2-external-inventory-script">Example: AWS EC2 External Inventory Script</a></li>
 </ul>
 </li>
 </ul>
@@ -330,6 +331,97 @@ override any that have the same name.</p>
 <p>So in other words, you can use those variables in arguments/actions as well.  You might use this to name
 a conf.d file appropriately or something similar.  Who knows?</p>
 <p>So that&#8217;s the Cobbler integration support &#8211; using the cobbler script as an example, it should be trivial to adapt Ansible to pull inventory, as well as variable information, from any data source.  If you create anything interesting, please share with the mailing list, and we can keep it in the source code tree for others to use.</p>
+</div>
+<div class="section" id="example-aws-ec2-external-inventory-script">
+<h3>Example: AWS EC2 External Inventory Script<a class="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 <a class="reference external" href="https://github.com/ansible/ansible/blob/devel/examples/scripts/ec2_external_inventory.py">EC2 external inventory</a> script.</p>
+<p>You can use this script in one of two ways. The easiest is to use Ansible&#8217;s <tt class="docutils literal"><span class="pre">-i</span></tt> command line option and specify the path to the script.</p>
+<blockquote>
+<div>ansible -i examples/scripts/ec2_external_inventory.py -u ubuntu us-east-1d -m ping</div></blockquote>
+<p>The second option is to copy the script to <cite>/etc/ansible/hosts</cite> and <cite>chmod +x</cite> it. You will also need to copy the <tt class="docutils literal"><span class="pre">ec2.ini</span></tt> file to <cite>/etc/ansible/ec2.ini</cite>. Then you can run ansible as you would normally.</p>
+<p>To successfully make an API call to AWS, you will need to configure Boto (the Python interface to AWS). There are a <a class="reference external" href="http://docs.pythonboto.org/en/latest/boto_config_tut.html">variety of methods</a> available, but the simplest is just to export two environment variables:</p>
+<blockquote>
+<div>export AWS_ACCESS_KEY_ID=&#8217;AK123&#8217;
+export AWS_SECRET_ACCESS_KEY=&#8217;abc123&#8217;</div></blockquote>
+<p>You can test the script by itself to make sure your config is correct</p>
+<blockquote>
+<div>cd examples/scripts
+./ec2_external_inventory.py &#8211;list</div></blockquote>
+<p>After a few moments, you should see your entire EC2 inventory across all regions in JSON.</p>
+<p>Since each region requires its own API call, if you are only using a small set of regions, feel free to edit <tt class="docutils literal"><span class="pre">ec2.ini</span></tt> and list only the regions you are interested in. There are other config options in <tt class="docutils literal"><span class="pre">ec2.ini</span></tt> including cache control, and destination variables.</p>
+<p>At their heart, inventory files are simply a mapping from some name to a destination address. The default <tt class="docutils literal"><span class="pre">ec2.ini</span></tt> settings are configured for running Ansible from outside EC2 (from your laptop for example). If you are running Ansible from within EC2, internal DNS names and IP addresses may make more sense than public DNS names. In this case, you can modify the <tt class="docutils literal"><span class="pre">destination_variable</span></tt> in <tt class="docutils literal"><span class="pre">ec2.ini</span></tt> to be the private DNS name of an instance. This is particularly important when running Ansible within a private subnet inside a VPC, where the only way to access an instance is via its private IP address. For VPC instances, <cite>vpc_destination_variable</cite> in <tt class="docutils literal"><span class="pre">ec2.ini</span></tt> provides a means of using which ever <a class="reference external" href="http://docs.pythonboto.org/en/latest/ref/ec2.html#module-boto.ec2.instance">boto.ec2.instance variable</a> makes the most sense for your use case.</p>
+<p>The EC2 external inventory provides mappings to instances from several groups:</p>
+<dl class="docutils">
+<dt>Instance ID</dt>
+<dd>These are groups of one since instance IDs are unique.
+e.g.
+<tt class="docutils literal"><span class="pre">i-00112233</span></tt>
+<tt class="docutils literal"><span class="pre">i-a1b1c1d1</span></tt></dd>
+<dt>Region</dt>
+<dd>A group of all instances in an AWS region.
+e.g.
+<tt class="docutils literal"><span class="pre">us-east-1</span></tt>
+<tt class="docutils literal"><span class="pre">us-west-2</span></tt></dd>
+<dt>Availability Zone</dt>
+<dd>A group of all instances in an availability zone.
+e.g.
+<tt class="docutils literal"><span class="pre">us-east-1a</span></tt>
+<tt class="docutils literal"><span class="pre">us-east-1b</span></tt></dd>
+<dt>Security Group</dt>
+<dd>Instances belong to one or more security groups. A group is created for each security group, with all characters except alphanumerics, dashes (-) converted to underscores (_). Each group is prefixed by <tt class="docutils literal"><span class="pre">security_group_</span></tt>
+e.g.
+<tt class="docutils literal"><span class="pre">security_group_default</span></tt>
+<tt class="docutils literal"><span class="pre">security_group_webservers</span></tt>
+<tt class="docutils literal"><span class="pre">security_group_Pete_s_Fancy_Group</span></tt></dd>
+<dt>Tags</dt>
+<dd>Each instance can have a variety of key/value pairs associated with it called Tags. The most common tag key is &#8216;Name&#8217;, though anything is possible. Each key/value pair is its own group of instances, again with special characters converted to underscores, in the format <tt class="docutils literal"><span class="pre">tag_KEY_VALUE</span></tt>
+e.g.
+<tt class="docutils literal"><span class="pre">tag_Name_Web</span></tt>
+<tt class="docutils literal"><span class="pre">tag_Name_redis-master-001</span></tt>
+<tt class="docutils literal"><span class="pre">tag_aws_cloudformation_logical-id_WebServerGroup</span></tt></dd>
+</dl>
+<p>When the Ansible is interacting with a specific server, the EC2 inventory script is called again with the <tt class="docutils literal"><span class="pre">--host</span> <span class="pre">HOST</span></tt> option. This looks up the HOST in the index cache to get the instance ID, and then makes an API call to AWS to get information about that specific instance. It then makes information about that instance available as variables to your playbooks. Each variable is prefixed by <tt class="docutils literal"><span class="pre">ec2_</span></tt>. Here are some of the variables available:</p>
+<ul class="simple">
+<li>ec2_architecture</li>
+<li>ec2_description</li>
+<li>ec2_dns_name</li>
+<li>ec2_id</li>
+<li>ec2_image_id</li>
+<li>ec2_instance_type</li>
+<li>ec2_ip_address</li>
+<li>ec2_kernel</li>
+<li>ec2_key_name</li>
+<li>ec2_launch_time</li>
+<li>ec2_monitored</li>
+<li>ec2_ownerId</li>
+<li>ec2_placement</li>
+<li>ec2_platform</li>
+<li>ec2_previous_state</li>
+<li>ec2_private_dns_name</li>
+<li>ec2_private_ip_address</li>
+<li>ec2_public_dns_name</li>
+<li>ec2_ramdisk</li>
+<li>ec2_region</li>
+<li>ec2_root_device_name</li>
+<li>ec2_root_device_type</li>
+<li>ec2_security_group_ids</li>
+<li>ec2_security_group_names</li>
+<li>ec2_spot_instance_request_id</li>
+<li>ec2_state</li>
+<li>ec2_state_code</li>
+<li>ec2_state_reason</li>
+<li>ec2_status</li>
+<li>ec2_subnet_id</li>
+<li>ec2_tag_Name</li>
+<li>ec2_tenancy</li>
+<li>ec2_virtualization_type</li>
+<li>ec2_vpc_id</li>
+</ul>
+<p>Both <tt class="docutils literal"><span class="pre">ec2_security_group_ids</span></tt> and <tt class="docutils literal"><span class="pre">ec2_security_group_names</span></tt> are comma-separated lists of all security groups. Each EC2 tag is a variable in the format <tt class="docutils literal"><span class="pre">ec2_tag_KEY</span></tt>.</p>
+<p>To see the complete list of variables available for an instance, run the script by itself:</p>
+<blockquote>
+<div>cd examples/scripts
+./ec2_external_inventory.py &#8211;host ec2-12-12-12-12.compute-1.amazonaws.com</div></blockquote>
 <div class="admonition-see-also admonition seealso">
 <p class="first admonition-title">See also</p>
 <dl class="last docutils">

modules.html

@@ -161,8 +161,10 @@ s.parentNode.insertBefore(ga, s);
 <li><a class="reference internal" href="#group">group</a></li>
 <li><a class="reference internal" href="#ohai">ohai</a></li>
 <li><a class="reference internal" href="#ping">ping</a></li>
+<li><a class="reference internal" href="#postgresql-db">postgresql_db</a></li>
+<li><a class="reference internal" href="#postgresql-user">postgresql_user</a></li>
 <li><a class="reference internal" href="#raw">raw</a></li>
-<li><a class="reference internal" href="#id13">service</a></li>
+<li><a class="reference internal" href="#service">service</a></li>
 <li><a class="reference internal" href="#setup">setup</a></li>
 <li><a class="reference internal" href="#shell">shell</a></li>
 <li><a class="reference internal" href="#template">template</a></li>
@@ -689,8 +691,133 @@ successful contact.</p>
 takes no parameters &amp; does not support change hooks, nor does it make
 any changes on the system.</p>
 </div>
+<div class="section" id="postgresql-db">
+<h2>postgresql_db<a class="headerlink" href="#postgresql-db" title="Permalink to this headline">¶</a></h2>
+<p>Add or remove PostgreSQL databases from a remote host.</p>
+<p>The default authentication assumes that you are either logging in as or
+sudo&#8217;ing to the postgres account on the host.</p>
+<p>This module uses psycopg2, a Python PostgreSQL database adapter. You must
+ensure that psycopg2 is installed on the host before using this module. If
+the remote host is the PostgreSQL server (which is the default case), then
+PostgreSQL must also be installed on the remote host. For Ubuntu-based systems,
+install the postgresql, libpq-dev, and python-psycopg2 packages on the remote
+host before using this module.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="17%" />
+<col width="9%" />
+<col width="9%" />
+<col width="66%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head">parameter</th>
+<th class="head">required</th>
+<th class="head">default</th>
+<th class="head">comments</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td>db</td>
+<td>yes</td>
+<td>&nbsp;</td>
+<td>name of the database to add or remove</td>
+</tr>
+<tr><td>login_user</td>
+<td>no</td>
+<td>postgres</td>
+<td>user (role) used to authenticate with PostgreSQL</td>
+</tr>
+<tr><td>login_password</td>
+<td>no</td>
+<td>&nbsp;</td>
+<td>password used to authenticate with PostgreSQL</td>
+</tr>
+<tr><td>login_host</td>
+<td>no</td>
+<td>&nbsp;</td>
+<td>host running PostgreSQL. Default (blank) implies localhost</td>
+</tr>
+<tr><td>state</td>
+<td>&nbsp;</td>
+<td>present</td>
+<td>&#8216;absent&#8217; or &#8216;present&#8217;</td>
+</tr>
+</tbody>
+</table>
+<p>Example action from Ansible <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
+<div class="highlight-python"><pre>postgresql_db db=acme</pre>
+</div>
+</div>
+<div class="section" id="postgresql-user">
+<h2>postgresql_user<a class="headerlink" href="#postgresql-user" title="Permalink to this headline">¶</a></h2>
+<p>Add or remove PostgreSQL users (roles) from a remote host, and grant the users
+access to an existing database.</p>
+<p>The default authentication assumes that you are either logging in as or
+sudo&#8217;ing to the postgres account on the host.</p>
+<p>This module uses psycopg2, a Python PostgreSQL database adapter. You must
+ensure that psycopg2 is installed on the host before using this module. If
+the remote host is the PostgreSQL server (which is the default case), then
+PostgreSQL must also be installed on the remote host. For Ubuntu-based systems,
+install the postgresql, libpq-dev, and python-psycopg2 packages on the remote
+host before using this module.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="17%" />
+<col width="9%" />
+<col width="9%" />
+<col width="66%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head">parameter</th>
+<th class="head">required</th>
+<th class="head">default</th>
+<th class="head">comments</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td>user</td>
+<td>yes</td>
+<td>&nbsp;</td>
+<td>name of the user (role) to add or remove</td>
+</tr>
+<tr><td>password</td>
+<td>yes</td>
+<td>&nbsp;</td>
+<td>set the user&#8217;s password</td>
+</tr>
+<tr><td>db</td>
+<td>yes</td>
+<td>&nbsp;</td>
+<td>name of an existing database to grant user access to</td>
+</tr>
+<tr><td>login_user</td>
+<td>no</td>
+<td>postgres</td>
+<td>user (role) used to authenticate with PostgreSQL</td>
+</tr>
+<tr><td>login_password</td>
+<td>no</td>
+<td>&nbsp;</td>
+<td>password used to authenticate with PostgreSQL</td>
+</tr>
+<tr><td>login_host</td>
+<td>no</td>
+<td>&nbsp;</td>
+<td>host running PostgreSQL. Default (blank) implies localhost</td>
+</tr>
+<tr><td>state</td>
+<td>&nbsp;</td>
+<td>present</td>
+<td>&#8216;absent&#8217; or &#8216;present&#8217;</td>
+</tr>
+</tbody>
+</table>
+<p>Example action from Ansible <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>:</p>
+<div class="highlight-python"><pre>postgresql_user db=acme user=django password=ceec4eif7ya</pre>
+</div>
+</div>
 <div class="section" id="raw">
-<span id="service"></span><h2>raw<a class="headerlink" href="#raw" title="Permalink to this headline">¶</a></h2>
+<span id="id13"></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.
 This module is new in Ansible 0.4.</p>
 <p>This is useful and should only be done in two cases.  The first case is installing
@@ -705,8 +832,8 @@ for this module.</p>
 <div class="highlight-python"><pre>ansible newhost.example.com raw -a "yum install python-simplejson"</pre>
 </div>
 </div>
-<div class="section" id="id13">
+<div class="section" id="service">
-<h2>service<a class="headerlink" href="#id13" title="Permalink to this headline">¶</a></h2>
+<span id="id14"></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>
@@ -757,7 +884,7 @@ service name=httpd state=reloaded</pre>
 </div>
 </div>
 <div class="section" id="setup">
-<span id="id14"></span><h2>setup<a class="headerlink" href="#setup" title="Permalink to this headline">¶</a></h2>
+<span id="id15"></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>
@@ -839,7 +966,7 @@ on your remote systems.</p>
 </div>
 </div>
 <div class="section" id="shell">
-<span id="id15"></span><h2>shell<a class="headerlink" href="#shell" title="Permalink to this headline">¶</a></h2>
+<span id="id16"></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>
@@ -857,7 +984,7 @@ command was running.</p>
 </div>
 </div>
 <div class="section" id="template">
-<span id="id16"></span><h2>template<a class="headerlink" href="#template" title="Permalink to this headline">¶</a></h2>
+<span id="id17"></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>
@@ -897,7 +1024,7 @@ a relative or absolute path.</td>
 </div>
 </div>
 <div class="section" id="user">
-<span id="id17"></span><h2>user<a class="headerlink" href="#user" title="Permalink to this headline">¶</a></h2>
+<span id="id18"></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>
@@ -996,7 +1123,7 @@ user name=mdehaan state=absent force=yes</pre>
 </div>
 </div>
 <div class="section" id="virt">
-<span id="id18"></span><h2>virt<a class="headerlink" href="#virt" title="Permalink to this headline">¶</a></h2>
+<span id="id19"></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">
@@ -1056,7 +1183,7 @@ ansible host -m virt -a "command=virttype"</pre>
 </div>
 </div>
 <div class="section" id="yum">
-<span id="id19"></span><h2>yum<a class="headerlink" href="#yum" title="Permalink to this headline">¶</a></h2>
+<span id="id20"></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>

rst/who_uses_ansible.rst

@@ -6,12 +6,13 @@ Ansible is used by all sorts of organizations from hosted web applications, medi
 ==================================================  ===================================================
 Who They Are                                        What They Do
 ==================================================  ===================================================
-`The Fedora Project <http://fedoraproject.org>`_    produces the popular Linux distribution
 `Basho <http://basho.com>`_                         makers of NoSQL key-value store Riak
-`Four Kitchens <http://fourkitchens.com>`_          "the Drupal Experts"
-`Steelhouse <http://steelhouse.com>`_               Behavioral Commerce
 `Cygate AB <http://cygate.se>`_                     IT solutions from Malmö, Sweden
+`Fedora Project <http://fedoraproject.org>`_        produces the popular Linux distribution
+`Four Kitchens <http://fourkitchens.com>`_          "the Drupal Experts"
+`Schmooze Com <http://www.schmoozecom.com/>`_       Creators of Industry-Leading PBX Platforms
 `Skyline.es <http://skylin.es>`_                    Realtime Photo Search Engine
+`Steelhouse <http://steelhouse.com>`_               Behavioral Commerce
 ==================================================  ===================================================
 
 and lots of other people (you should see our Google Analytics data).  Tweet at `Michael DeHaan <http://twitter.com/laserllama>`_ or `email him <mailto:michael.dehaan@gmail.com>`_ to get your company or project listed here.  (It's free!)

who_uses_ansible.html

@@ -187,24 +187,27 @@ s.parentNode.insertBefore(ga, s);
 </tr>
 </thead>
 <tbody valign="top">
-<tr><td><a class="reference external" href="http://fedoraproject.org">The Fedora Project</a></td>
-<td>produces the popular Linux distribution</td>
-</tr>
 <tr><td><a class="reference external" href="http://basho.com">Basho</a></td>
 <td>makers of NoSQL key-value store Riak</td>
 </tr>
-<tr><td><a class="reference external" href="http://fourkitchens.com">Four Kitchens</a></td>
-<td>&#8220;the Drupal Experts&#8221;</td>
-</tr>
-<tr><td><a class="reference external" href="http://steelhouse.com">Steelhouse</a></td>
-<td>Behavioral Commerce</td>
-</tr>
 <tr><td><a class="reference external" href="http://cygate.se">Cygate AB</a></td>
 <td>IT solutions from Malmö, Sweden</td>
 </tr>
+<tr><td><a class="reference external" href="http://fedoraproject.org">Fedora Project</a></td>
+<td>produces the popular Linux distribution</td>
+</tr>
+<tr><td><a class="reference external" href="http://fourkitchens.com">Four Kitchens</a></td>
+<td>&#8220;the Drupal Experts&#8221;</td>
+</tr>
+<tr><td><a class="reference external" href="http://www.schmoozecom.com/">Schmooze Com</a></td>
+<td>Creators of Industry-Leading PBX Platforms</td>
+</tr>
 <tr><td><a class="reference external" href="http://skylin.es">Skyline.es</a></td>
 <td>Realtime Photo Search Engine</td>
 </tr>
+<tr><td><a class="reference external" href="http://steelhouse.com">Steelhouse</a></td>
+<td>Behavioral Commerce</td>
+</tr>
 </tbody>
 </table>
 <p>and lots of other people (you should see our Google Analytics data).  Tweet at <a class="reference external" href="http://twitter.com/laserllama">Michael DeHaan</a> or <a class="reference external" href="mailto:michael&#46;dehaan&#37;&#52;&#48;gmail&#46;com">email him</a> to get your company or project listed here.  (It&#8217;s free!)</p>