Document the user module

YAMLSyntax.html

@@ -245,7 +245,7 @@ languages:
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 21, 2012.<br/>
+      Last updated on Mar 22, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

api.html

@@ -330,7 +330,7 @@ a conf.d file appropriately or something similar.  Who knows.</p>
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 21, 2012.<br/>
+      Last updated on Mar 22, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

examples.html

@@ -132,6 +132,7 @@ s.parentNode.insertBefore(ga, s);
 <li><a class="reference internal" href="#parallelism-and-shell-commands">Parallelism and Shell Commands</a></li>
 <li><a class="reference internal" href="#file-transfer-templating">File Transfer &amp; Templating</a></li>
 <li><a class="reference internal" href="#managing-packages">Managing Packages</a></li>
+<li><a class="reference internal" href="#users-and-groups">Users and Groups</a></li>
 <li><a class="reference internal" href="#deploying-from-source-control">Deploying From Source Control</a></li>
 <li><a class="reference internal" href="#managing-services">Managing Services</a></li>
 <li><a class="reference internal" href="#time-limited-background-operations">Time Limited Background Operations</a></li>
@@ -250,6 +251,16 @@ ansible webservers -m file -a "dest=/srv/foo/b.txt mode=600 owner=mdehaan group=
 for other package manages using the command module or contribute a module
 for other package managers.  Stop by the mailing list for info/details.</p>
 </div>
+<div class="section" id="users-and-groups">
+<h2>Users and Groups<a class="headerlink" href="#users-and-groups" title="Permalink to this headline">¶</a></h2>
+<p>The user module allows easy creation and manipulation of existing user accounts, as well
+as removal of user accounts that may exist:</p>
+<div class="highlight-python"><pre>ansible all -m user -a "name=foo password=&lt;crypted password here&gt;"
+
+ansible all -m user -a "name=foo state=absent"</pre>
+</div>
+<p>See the <a class="reference internal" href="modules.html"><em>Ansible Modules</em></a> section for details on all of the available options.</p>
+</div>
 <div class="section" id="deploying-from-source-control">
 <h2>Deploying From Source Control<a class="headerlink" href="#deploying-from-source-control" title="Permalink to this headline">¶</a></h2>
 <p>Deploy your webapp straight from git:</p>
@@ -318,7 +329,7 @@ a simplified syntax for this.</p>
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 21, 2012.<br/>
+      Last updated on Mar 22, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

faq.html

@@ -336,7 +336,7 @@ tasks – whether for a QA sytem, build system, or anything you can think of
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 21, 2012.<br/>
+      Last updated on Mar 22, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

genindex.html

@@ -160,7 +160,7 @@ s.parentNode.insertBefore(ga, s);
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 21, 2012.<br/>
+      Last updated on Mar 22, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

gettingstarted.html

@@ -299,7 +299,7 @@ explore, but you already have a fully working infrastructure!</p>
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 21, 2012.<br/>
+      Last updated on Mar 22, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

index.html

@@ -253,6 +253,7 @@ Email: <input type=text name=email>&nbsp;&nbsp;<input type=submit name="sub" val
 <li class="toctree-l2"><a class="reference internal" href="examples.html#parallelism-and-shell-commands">Parallelism and Shell Commands</a></li>
 <li class="toctree-l2"><a class="reference internal" href="examples.html#file-transfer-templating">File Transfer &amp; Templating</a></li>
 <li class="toctree-l2"><a class="reference internal" href="examples.html#managing-packages">Managing Packages</a></li>
+<li class="toctree-l2"><a class="reference internal" href="examples.html#users-and-groups">Users and Groups</a></li>
 <li class="toctree-l2"><a class="reference internal" href="examples.html#deploying-from-source-control">Deploying From Source Control</a></li>
 <li class="toctree-l2"><a class="reference internal" href="examples.html#managing-services">Managing Services</a></li>
 <li class="toctree-l2"><a class="reference internal" href="examples.html#time-limited-background-operations">Time Limited Background Operations</a></li>
@@ -270,6 +271,7 @@ Email: <input type=text name=email>&nbsp;&nbsp;<input type=submit name="sub" val
 <li class="toctree-l2"><a class="reference internal" href="modules.html#setup">setup</a></li>
 <li class="toctree-l2"><a class="reference internal" href="modules.html#shell">shell</a></li>
 <li class="toctree-l2"><a class="reference internal" href="modules.html#template">template</a></li>
+<li class="toctree-l2"><a class="reference internal" href="modules.html#user">user</a></li>
 <li class="toctree-l2"><a class="reference internal" href="modules.html#yum">yum</a></li>
 <li class="toctree-l2"><a class="reference internal" href="modules.html#writing-your-own-modules">Writing your own modules</a></li>
 </ul>
@@ -368,7 +370,7 @@ Puppet Labs, and rPath.  Reach Michael by email <a class="reference external" hr
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 21, 2012.<br/>
+      Last updated on Mar 22, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

man.html

@@ -194,7 +194,7 @@ examples of these tools in use.</p>
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 21, 2012.<br/>
+      Last updated on Mar 22, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

man/ansible-playbook.1.html

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!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-playbook</title><link rel="stylesheet" href="./docbook-xsl.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div xml:lang="en" class="refentry" title="ansible-playbook" lang="en"><a id="id323406"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ansible-playbook — run an ansible playbook</p></div><div class="refsynopsisdiv" title="Synopsis"><a id="_synopsis"></a><h2>Synopsis</h2><p>ansible-playbook &lt;filename.yml&gt; … [options]</p></div><div class="refsect1" title="DESCRIPTION"><a id="_description"></a><h2>DESCRIPTION</h2><p><span class="strong"><strong>Ansible playbooks</strong></span> are a configuration and multinode deployment system.  Ansible-playbook is the tool
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ansible-playbook</title><link rel="stylesheet" href="./docbook-xsl.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div xml:lang="en" class="refentry" title="ansible-playbook" lang="en"><a id="id554898"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ansible-playbook — run an ansible playbook</p></div><div class="refsynopsisdiv" title="Synopsis"><a id="_synopsis"></a><h2>Synopsis</h2><p>ansible-playbook &lt;filename.yml&gt; … [options]</p></div><div class="refsect1" title="DESCRIPTION"><a id="_description"></a><h2>DESCRIPTION</h2><p><span class="strong"><strong>Ansible playbooks</strong></span> are a configuration and multinode deployment system.  Ansible-playbook is the tool
 used to run them.   See the project home page (link below) for more information.</p></div><div class="refsect1" title="ARGUMENTS"><a id="_arguments"></a><h2>ARGUMENTS</h2><div class="variablelist"><dl><dt><span class="term">
 <span class="strong"><strong>filename.yml</strong></span>
 </span></dt><dd>

man/ansible.1.html

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!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</title><link rel="stylesheet" href="./docbook-xsl.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div xml:lang="en" class="refentry" title="ansible" lang="en"><a id="id395564"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ansible — run a command somewhere else</p></div><div class="refsynopsisdiv" title="Synopsis"><a id="_synopsis"></a><h2>Synopsis</h2><p>ansible &lt;host-pattern&gt; [-f forks] [-m module_name] [-a args]</p></div><div class="refsect1" title="DESCRIPTION"><a id="_description"></a><h2>DESCRIPTION</h2><p><span class="strong"><strong>Ansible</strong></span> is an extra-simple tool/framework/API for doing 'remote things' over
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ansible</title><link rel="stylesheet" href="./docbook-xsl.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /></head><body><div xml:lang="en" class="refentry" title="ansible" lang="en"><a id="id575958"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ansible — run a command somewhere else</p></div><div class="refsynopsisdiv" title="Synopsis"><a id="_synopsis"></a><h2>Synopsis</h2><p>ansible &lt;host-pattern&gt; [-f forks] [-m module_name] [-a args]</p></div><div class="refsect1" title="DESCRIPTION"><a id="_description"></a><h2>DESCRIPTION</h2><p><span class="strong"><strong>Ansible</strong></span> is an extra-simple tool/framework/API for doing 'remote things' over
 SSH.</p></div><div class="refsect1" title="ARGUMENTS"><a id="_arguments"></a><h2>ARGUMENTS</h2><div class="variablelist"><dl><dt><span class="term">
 <span class="strong"><strong>host-pattern</strong></span>
 </span></dt><dd>

moduledev.html

@@ -394,7 +394,7 @@ Stop by the mailing list to inquire about requirements.</p>
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 21, 2012.<br/>
+      Last updated on Mar 22, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

modules.html

@@ -140,6 +140,7 @@ s.parentNode.insertBefore(ga, s);
 <li><a class="reference internal" href="#setup">setup</a></li>
 <li><a class="reference internal" href="#shell">shell</a></li>
 <li><a class="reference internal" href="#template">template</a></li>
+<li><a class="reference internal" href="#user">user</a></li>
 <li><a class="reference internal" href="#yum">yum</a></li>
 <li><a class="reference internal" href="#writing-your-own-modules">Writing your own modules</a></li>
 </ul>
@@ -202,9 +203,6 @@ arguments, space delimited.</p>
 <p>If you want to run a command through the shell (say you are using
 &#8216;&lt;&#8217;, &#8216;&gt;&#8217;, &#8216;|&#8217;, etc), you actually want the &#8216;shell&#8217; module instead.
 The &#8216;command&#8217; module is much more secure as it&#8217;s not affected by the user&#8217;s environment.</p>
-<p>Example usage:</p>
-<div class="highlight-python"><pre>/sbin/shutdown -t now</pre>
-</div>
 <p>The given command will be executed on all selected nodes.  It will not
 be processed through the shell, so variables like &#8220;$HOME&#8221; and
 operations like &#8220;&lt;&#8221;, &#8220;&gt;&#8221;, &#8220;|&#8221;, and &#8220;&amp;&#8221; will not work.  As such, all
@@ -212,6 +210,9 @@ paths to commands must be fully qualified.</p>
 <p>This module does not support change hooks and returns the return code
 from the program as well as timing information about how long the
 command was running for.</p>
+<p>Example action from a <tt class="xref doc docutils literal"><span class="pre">playbook</span></tt>:</p>
+<div class="highlight-python"><pre>command /sbin/shutdown -t now</pre>
+</div>
 </div>
 <div class="section" id="copy">
 <span id="id2"></span><h2>copy<a class="headerlink" href="#copy" title="Permalink to this headline">¶</a></h2>
@@ -228,6 +229,9 @@ absolute or relative path.</li>
 <li>Remote absolute path where the file should end up.</li>
 </ul>
 <p>This module also returns md5sum information about the resultant file.</p>
+<p>Example action from a <tt class="xref doc docutils literal"><span class="pre">playbook</span></tt>:</p>
+<div class="highlight-python"><pre>copy src=/srv/myfiles/foo.conf dest=/etc/foo.conf owner=foo group=foo mode=0644</pre>
+</div>
 </div>
 <div class="section" id="facter">
 <span id="id3"></span><h2>facter<a class="headerlink" href="#facter" title="Permalink to this headline">¶</a></h2>
@@ -263,6 +267,11 @@ to the file module are also available when running the <cite>copy</cite> or <cit
 <ul class="simple">
 <li>name of group that should own the file or directory, as would be given to <cite>chgrp</cite></li>
 </ul>
+<p>Example action from a <tt class="xref doc docutils literal"><span class="pre">playbook</span></tt>:</p>
+<div class="highlight-python"><pre>file dest=/etc/foo.conf owner=foo group=foo mode=0644
+file dest=/some/path owner=foo group=foo state=directory
+file dest/path/to/delete state=absent</pre>
+</div>
 </div>
 <div class="section" id="git">
 <h2>git<a class="headerlink" href="#git" title="Permalink to this headline">¶</a></h2>
@@ -280,6 +289,9 @@ to the file module are also available when running the <cite>copy</cite> or <cit
 <li>What version to check out &#8211; either the git SHA, the literal string
 <tt class="docutils literal"><span class="pre">HEAD</span></tt>, or a tag name.</li>
 </ul>
+<p>Example action from a <tt class="xref doc docutils literal"><span class="pre">playbook</span></tt>:</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="ohai">
 <h2>ohai<a class="headerlink" href="#ohai" title="Permalink to this headline">¶</a></h2>
@@ -312,6 +324,11 @@ unless necessary.  <tt class="docutils literal"><span class="pre">restarted</spa
 <ul class="simple">
 <li>The name of the service.</li>
 </ul>
+<p>Example action from a <tt class="xref doc docutils literal"><span class="pre">playbook</span></tt>:</p>
+<div class="highlight-python"><pre>service name=httpd state=started
+service name=httpd state=stopped
+service name=httpd state=restarted</pre>
+</div>
 </div>
 <div class="section" id="setup">
 <span id="id4"></span><h2>setup<a class="headerlink" href="#setup" title="Permalink to this headline">¶</a></h2>
@@ -331,15 +348,20 @@ tell their source.  All variables are then bubbled up to the caller.</p>
 <tt class="docutils literal"><span class="pre">key=value</span></tt> pair in the JSON file for use in templating.</li>
 </ul>
 </div></blockquote>
+<p>Example action from a <tt class="xref doc docutils literal"><span class="pre">playbook</span></tt>:</p>
+<div class="highlight-python"><pre>vars:
+    ntpserver: 'ntp.example.com'
+    xyz: 1234</pre>
+</div>
+<p>Example action from <cite>/usr/bin/ansible</cite>:</p>
+<div class="highlight-python"><pre>ansible -m all setup -a "ntpserver=ntp.example.com xyz=1234"</pre>
+</div>
 </div>
 <div class="section" id="shell">
 <span id="id5"></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 shell rather than directly.</p>
-<p>Example usage:</p>
-<div class="highlight-python"><pre>find . | grep *.txt</pre>
-</div>
 <p>The given command will be executed on all selected nodes.</p>
 <p>If you want to execute a command securely and predicably, it may
 be better to use the &#8216;command&#8217; module instead.  Best practices
@@ -349,6 +371,9 @@ use your best judgement.</p>
 <p>This module does not support change hooks and returns the return code
 from the program as well as timing information about how long the
 command was running for.</p>
+<p>Example action from a playbook:</p>
+<div class="highlight-python"><pre>shell somescript.sh &gt;&gt; somelog.txt</pre>
+</div>
 </div>
 <div class="section" id="template">
 <span id="id6"></span><h2>template<a class="headerlink" href="#template" title="Permalink to this headline">¶</a></h2>
@@ -366,9 +391,49 @@ be a relative or absolute path.</li>
 <li>Location to render the template on the remote server.</li>
 </ul>
 <p>This module also returns md5sum information about the resultant file.</p>
+<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="id7"></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>
+<p><em>name</em>:</p>
+<ul class="simple">
+<li>Name of the user to create, remove, or edit</li>
+</ul>
+<p><em>comment</em>:</p>
+<ul class="simple">
+<li>Optionally sets the description of the user</li>
+</ul>
+<p><em>gid</em>:</p>
+<ul class="simple">
+<li>Optionally sets the primary group GID.  The user module will also be able to manipulate this.</li>
+</ul>
+<p><em>shell</em>:</p>
+<ul class="simple">
+<li>Optionally sets the user&#8217;s shell.</li>
+</ul>
+<p><em>createhome</em>:</p>
+<ul class="simple">
+<li>Whether to create the user&#8217;s home directory.  Takes &#8216;yes&#8217;, or &#8216;no&#8217;.  The default is &#8216;yes&#8217;.</li>
+</ul>
+<p><em>password</em>:</p>
+<ul class="simple">
+<li>Sets the user&#8217;s password to this crypted value.  Pass in a result from crypt.  See the users
+example in the github examples directory for what this looks like in a playbook.</li>
+</ul>
+<p><em>state</em>:</p>
+<ul class="simple">
+<li>Defaults to &#8216;present&#8217;.  When &#8216;absent&#8217;, the user account will be removed if present.</li>
+</ul>
+<p>Example action from a <tt class="xref doc docutils literal"><span class="pre">playbook</span></tt>:</p>
+<div class="highlight-python"><pre>user name=mdehaan comment=awesome passwd=awWxVV.JvmdHw createhome=yes
+user name=mdehaan state=absent</pre>
+</div>
 </div>
 <div class="section" id="yum">
-<span id="id7"></span><h2>yum<a class="headerlink" href="#yum" title="Permalink to this headline">¶</a></h2>
+<span id="id8"></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>
 <p><em>pkg</em>:</p>
 <ul class="simple">
@@ -384,6 +449,11 @@ be a relative or absolute path.</li>
 various configuration attributes.  Values include &#8216;installed&#8217;, &#8216;updates&#8217;,
 &#8216;available&#8217;, &#8216;repos&#8217;, or any package specifier.</li>
 </ul>
+<p>Example action from a <tt class="xref doc docutils literal"><span class="pre">playbook</span></tt>:</p>
+<div class="highlight-python"><pre>yum pkg=httpd ensure=latest
+yum pkg=httpd ensure=removed
+yum pkg=httpd ensure=installed</pre>
+</div>
 </div>
 <div class="section" id="writing-your-own-modules">
 <h2>Writing your own modules<a class="headerlink" href="#writing-your-own-modules" title="Permalink to this headline">¶</a></h2>
@@ -415,7 +485,7 @@ various configuration attributes.  Values include &#8216;installed&#8217;, &#821
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 21, 2012.<br/>
+      Last updated on Mar 22, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

patterns.html

@@ -240,7 +240,7 @@ wildcards:</p>
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 21, 2012.<br/>
+      Last updated on Mar 22, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

playbooks.html

@@ -386,6 +386,7 @@ and allows usage of variables from anywhere in ansible, either denoted with <cit
 <cite>{{ braces_syntax }}</cite> and then evaluates them with a Python expression.   Don&#8217;t panic &#8211; it&#8217;s actually
 pretty simple.:</p>
 <div class="highlight-python"><pre>vars:
+  favcolor: blue
   is_favcolor_blue: "'$favcolor' == 'blue'"
   is_centos: "'$facter_operatingsystem' == 'CentOS'"
 tasks:
@@ -621,7 +622,7 @@ Let&#8217;s run a playbook using a parallelism level of 10:</p>
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 21, 2012.<br/>
+      Last updated on Mar 22, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

rst/examples.rst

@@ -107,6 +107,19 @@ Currently Ansible only has a module for managing packages with yum.  You can ins
 for other package manages using the command module or contribute a module
 for other package managers.  Stop by the mailing list for info/details.
 
+Users and Groups
+````````````````
+
+The user module allows easy creation and manipulation of existing user accounts, as well
+as removal of user accounts that may exist::
+
+    ansible all -m user -a "name=foo password=<crypted password here>"
+
+    ansible all -m user -a "name=foo state=absent"
+
+See the :doc:`modules` section for details on all of the available options.
+
+
 Deploying From Source Control
 `````````````````````````````
 

rst/modules.rst

@@ -47,10 +47,6 @@ 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.
 
-Example usage::
-
-    /sbin/shutdown -t now
-
 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
@@ -60,6 +56,10 @@ This module does not support change hooks and returns the return code
 from the program as well as timing information about how long the
 command was running for.
 
+Example action from a :doc:`playbook`::
+
+    command /sbin/shutdown -t now
+
 
 .. _copy:
 
@@ -80,9 +80,12 @@ module.
 
 * Remote absolute path where the file should end up.
 
-
 This module also returns md5sum information about the resultant file.
 
+Example action from a :doc:`playbook`::
+
+    copy src=/srv/myfiles/foo.conf dest=/etc/foo.conf owner=foo group=foo mode=0644
+
 
 .. _facter:
 
@@ -125,6 +128,12 @@ to the file module are also available when running the `copy` or `template` modu
 
 * name of group that should own the file or directory, as would be given to `chgrp`
 
+Example action from a :doc:`playbook`::
+
+    file dest=/etc/foo.conf owner=foo group=foo mode=0644
+    file dest=/some/path owner=foo group=foo state=directory
+    file dest/path/to/delete state=absent
+
 
 git
 ```
@@ -144,6 +153,10 @@ Deploys software (or files) from git checkouts.
 * What version to check out -- either the git SHA, the literal string
   ``HEAD``, or a tag name.
 
+Example action from a :doc:`playbook`::
+
+    git repo=git://foosball.example.org/path/to/repo.git dest=/srv/checkout version=release-0.22
+
 
 ohai
 ````
@@ -181,11 +194,16 @@ Controls services on remote machines.
   Started/stopped are idempotent actions that will not run commands
   unless necessary.  ``restarted`` will always bounce the service.
 
-
 *name*:
 
 * The name of the service.
 
+Example action from a :doc:`playbook`::
+
+    service name=httpd state=started
+    service name=httpd state=stopped
+    service name=httpd state=restarted
+
 
 .. _setup:
 
@@ -208,6 +226,16 @@ tell their source.  All variables are then bubbled up to the caller.
  * Any other parameters can be named basically anything, and set a
    ``key=value`` pair in the JSON file for use in templating.
 
+Example action from a :doc:`playbook`::
+
+    vars:
+        ntpserver: 'ntp.example.com'
+        xyz: 1234
+
+Example action from `/usr/bin/ansible`::
+
+    ansible -m all setup -a "ntpserver=ntp.example.com xyz=1234"
+
 
 .. _shell:
 
@@ -218,10 +246,6 @@ 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 shell rather than directly.
 
-Example usage::
-
-    find . | grep *.txt
-
 The given command will be executed on all selected nodes.  
 
 If you want to execute a command securely and predicably, it may
@@ -234,6 +258,10 @@ This module does not support change hooks and returns the return code
 from the program as well as timing information about how long the
 command was running for.
 
+Example action from a playbook::
+
+    shell somescript.sh >> somelog.txt
+
 
 .. _template:
 
@@ -254,9 +282,54 @@ module.
 
 * Location to render the template on the remote server.
 
-
 This module also returns md5sum information about the resultant file.
 
+Example action from a playbook::
+
+    template src=/srv/mytemplates/foo.j2 dest=/etc/foo.conf owner=foo group=foo mode=0644
+
+
+.. _user:
+
+user
+````
+
+Creates user accounts, manipulates existing user accounts, and removes user accounts.
+
+*name*:
+
+* Name of the user to create, remove, or edit
+
+*comment*:
+
+* Optionally sets the description of the user
+
+*gid*:
+
+* Optionally sets the primary group GID.  The user module will also be able to manipulate this.
+
+*shell*:
+
+* Optionally sets the user's shell.
+
+*createhome*:
+
+* Whether to create the user's home directory.  Takes 'yes', or 'no'.  The default is 'yes'.
+    
+*password*:
+
+* Sets the user's password to this crypted value.  Pass in a result from crypt.  See the users
+  example in the github examples directory for what this looks like in a playbook.
+
+*state*:
+
+* Defaults to 'present'.  When 'absent', the user account will be removed if present.
+
+Example action from a :doc:`playbook`::
+
+    user name=mdehaan comment=awesome passwd=awWxVV.JvmdHw createhome=yes
+    user name=mdehaan state=absent
+
 .. _yum:
 
 yum
@@ -278,6 +351,13 @@ Will install, upgrade, remove, and list packages with the yum package manager.
   various configuration attributes.  Values include 'installed', 'updates',
   'available', 'repos', or any package specifier.
 
+Example action from a :doc:`playbook`::
+
+    yum pkg=httpd ensure=latest
+    yum pkg=httpd ensure=removed
+    yum pkg=httpd ensure=installed
+
+
 Writing your own modules
 ````````````````````````
 

search.html

@@ -177,7 +177,7 @@ s.parentNode.insertBefore(ga, s);
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 21, 2012.<br/>
+      Last updated on Mar 22, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>