Added documentation on the 'shell' module, which is a virtual module and isn't…

Added documentation on the 'shell' module, which is a virtual module and isn't really in the library folder.
Docs build.

YAMLSyntax.html

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

api.html

@@ -244,7 +244,7 @@ command line tools <tt class="docutils literal"><span class="pre">ansible</span>
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 13, 2012.<br/>
+      Last updated on Mar 14, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

examples.html

@@ -285,8 +285,8 @@ Be sure to use a high enough <cite>&#8211;forks</cite> value if you want to get
 very quickly. After the time limit (in seconds) runs out (<tt class="docutils literal"><span class="pre">-B</span></tt>), the process on
 the remote nodes will be terminated.</p>
 <p>Any module other than <a class="reference internal" href="modules.html#copy"><em>copy</em></a> or <a class="reference internal" href="modules.html#template"><em>template</em></a> can be
-backgrounded.  Typically you&#8217;ll be backgrounding shell commands or
-software upgrades only.</p>
+backgrounded.  Typically you&#8217;ll be backgrounding long-running
+shell commands or software upgrades only.</p>
 </div>
 </div>
 
@@ -297,7 +297,7 @@ software upgrades only.</p>
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 13, 2012.<br/>
+      Last updated on Mar 14, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

faq.html

@@ -346,7 +346,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 13, 2012.<br/>
+      Last updated on Mar 14, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

genindex.html

@@ -173,7 +173,7 @@ alt="Fork me on GitHub"
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 13, 2012.<br/>
+      Last updated on Mar 14, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

gettingstarted.html

@@ -288,7 +288,7 @@ you already have a 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 13, 2012.<br/>
+      Last updated on Mar 14, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

index.html

@@ -267,6 +267,7 @@ you with questions about Ansible.</p>
 <li class="toctree-l2"><a class="reference internal" href="modules.html#ping">ping</a></li>
 <li class="toctree-l2"><a class="reference internal" href="modules.html#service">service</a></li>
 <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#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>
@@ -345,7 +346,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 13, 2012.<br/>
+      Last updated on Mar 14, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

man.html

@@ -191,7 +191,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 13, 2012.<br/>
+      Last updated on Mar 14, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

man/ansible-playbook.1.html

 <?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="id352863"></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="id459632"></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

 <?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="id371943"></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="id303813"></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>

modules.html

@@ -136,6 +136,7 @@ s.parentNode.insertBefore(ga, s);
 <li><a class="reference internal" href="#ping">ping</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>
 <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>
@@ -193,9 +194,9 @@ on remote hosts or through ansible playbooks.</p>
 <dd>Examples of using modules with the Python API</dd>
 </dl>
 </div>
-<p>Nearly all modules take <tt class="docutils literal"><span class="pre">key=value</span></tt> parameters.  Some modules take
-no parameters, and the command module just takes arguments for the
-command you want to run.</p>
+<p>Nearly all modules take <tt class="docutils literal"><span class="pre">key=value</span></tt> parameters, space delimited.  Some modules take
+no parameters, and the command/shell modules simply take the string
+of the command you want to run.</p>
 <p>All modules return JSON format data, though if you are using the
 command line or playbooks, you don&#8217;t really need to know much about
 that.</p>
@@ -207,12 +208,17 @@ noted, all modules support change hooks.</p>
 <div class="section" id="command">
 <span id="id1"></span><h2>command<a class="headerlink" href="#command" title="Permalink to this headline">¶</a></h2>
 <p>The command module takes the command name followed by a list of
-arguments, space delimited.  This is the only module that does not use
-<tt class="docutils literal"><span class="pre">key=value</span></tt> style parameters.</p>
+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 shell command will be executed on all selected nodes.</p>
+<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
+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>
@@ -309,8 +315,26 @@ tell their source.  All variables are then bubbled up to the caller.</p>
 </ul>
 </div></blockquote>
 </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
+when writing playbooks will follow the trend of using &#8216;command&#8217;
+unless &#8216;shell&#8217; is explicitly required.  When running ad-hoc commands,
+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>
+</div>
 <div class="section" id="template">
-<span id="id5"></span><h2>template<a class="headerlink" href="#template" title="Permalink to this headline">¶</a></h2>
+<span id="id6"></span><h2>template<a class="headerlink" href="#template" title="Permalink to this headline">¶</a></h2>
 <p>Templates a file out to a remote server.  Call the <a class="reference internal" href="#setup"><em>setup</em></a> module
 prior to usage if you are not running from a playbook.</p>
 <p><em>src</em>:</p>
@@ -325,7 +349,7 @@ be a relative or absolute path.</li>
 <p>This module also returns md5sum information about the resultant file.</p>
 </div>
 <div class="section" id="yum">
-<span id="id6"></span><h2>yum<a class="headerlink" href="#yum" title="Permalink to this headline">¶</a></h2>
+<span id="id7"></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">
@@ -380,7 +404,7 @@ arguments just like they would be passed with ansible.</p>
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 13, 2012.<br/>
+      Last updated on Mar 14, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

patterns.html

@@ -242,7 +242,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 13, 2012.<br/>
+      Last updated on Mar 14, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

playbooks.html

@@ -540,7 +540,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 13, 2012.<br/>
+      Last updated on Mar 14, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>

rst/examples.rst

@@ -132,8 +132,8 @@ very quickly. After the time limit (in seconds) runs out (``-B``), the process o
 the remote nodes will be terminated.
 
 Any module other than :ref:`copy` or :ref:`template` can be
-backgrounded.  Typically you'll be backgrounding shell commands or
-software upgrades only.
+backgrounded.  Typically you'll be backgrounding long-running 
+shell commands or software upgrades only.
 
   
 

rst/modules.rst

@@ -13,9 +13,9 @@ on remote hosts or through ansible playbooks.
    :doc:`api`
        Examples of using modules with the Python API
 
-Nearly all modules take ``key=value`` parameters.  Some modules take
-no parameters, and the command module just takes arguments for the
-command you want to run.
+Nearly all modules take ``key=value`` parameters, space delimited.  Some modules take
+no parameters, and the command/shell modules simply take the string
+of the command you want to run.
 
 All modules return JSON format data, though if you are using the
 command line or playbooks, you don't really need to know much about
@@ -34,19 +34,26 @@ command
 ```````
 
 The command module takes the command name followed by a list of
-arguments, space delimited.  This is the only module that does not use
-``key=value`` style parameters.
+arguments, space delimited.  
+
+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 shell command will be executed on all selected nodes.
+The given command will be executed on all selected nodes.  It will not
+be processed through the shell, so variables like "$HOME" and 
+operations like "<", ">", "|", and "&" will not work.  As such, all
+paths to commands must be fully qualified.
 
 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.
 
+
 .. _copy:
 
 copy
@@ -167,6 +174,32 @@ tell their source.  All variables are then bubbled up to the caller.
    ``key=value`` pair in the JSON file for use in templating.
 
 
+.. _shell:
+
+shell
+`````
+
+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
+be better to use the 'command' module instead.  Best practices
+when writing playbooks will follow the trend of using 'command'
+unless 'shell' is explicitly required.  When running ad-hoc commands,
+use your best judgement.
+
+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.
+
+
 .. _template:
 
 template

search.html

@@ -187,7 +187,7 @@ alt="Fork me on GitHub"
     <p class="pull-right"><a href="#">Back to top</a></p>
     <p>
         &copy; Copyright 2012 Michael DeHaan.<br/>
-      Last updated on Mar 13, 2012.<br/>
+      Last updated on Mar 14, 2012.<br/>
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
     </p>
   </div>