Skip to content

A
ansible
Commit 505d3942 by Michael DeHaan
Options

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.
parent 38e87717
Showing with 90 additions and 32 deletions
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 &#8211; 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>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment