From d9c626e686e080555ac4ebc751f45489e66d9789 Mon Sep 17 00:00:00 2001
From: Michael DeHaan <michael.dehaan@gmail.com>
Date: Wed, 14 Mar 2012 12:50:40 -0400
Subject: [PATCH] Added start of a module development guide, prob needs some
 editing and maybe some simpler examples

---
 YAMLSyntax.html             |   1 +
 api.html                    |   7 +-
 examples.html               |   1 +
 faq.html                    |   7 +-
 genindex.html               |   1 +
 gettingstarted.html         |   1 +
 index.html                  |  14 ++
 man.html                    |   1 +
 man/ansible-playbook.1.html |   2 +-
 man/ansible.1.html          |   2 +-
 modules.html                |   1 +
 patterns.html               |   1 +
 playbooks.html              |   5 +-
 rst/index.rst               |   1 +
 rst/moduledev.rst           | 253 ++++++++++++++++++++++++++++++++++++
 rst/playbooks.rst           |   4 +-
 search.html                 |   1 +
 searchindex.js              |   2 +-
 18 files changed, 294 insertions(+), 11 deletions(-)
 create mode 100644 rst/moduledev.rst

diff --git a/YAMLSyntax.html b/YAMLSyntax.html
index 8dfde3ee58..861e78c429 100644
--- a/YAMLSyntax.html
+++ b/YAMLSyntax.html
@@ -118,6 +118,7 @@ s.parentNode.insertBefore(ga, s);
 <li class="toctree-l1 current"><a class="current reference internal" href="">YAML Syntax</a></li>
 <li class="toctree-l1"><a class="reference internal" href="playbooks.html">Playbooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">Using the Python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development Guide</a></li>
 <li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a></li>
 <li class="toctree-l1"><a class="reference internal" href="man.html">Man Pages</a></li>
 </ul>
diff --git a/api.html b/api.html
index 6c9cf05efa..8a0f87854c 100644
--- a/api.html
+++ b/api.html
@@ -26,7 +26,7 @@
     <script type="text/javascript" src="_static/bootstrap-dropdown.js"></script>
     <script type="text/javascript" src="_static/bootstrap-scrollspy.js"></script>
     <link rel="top" title="Ansible - SSH-Based Configuration Management &amp; Deployment" href="index.html" />
-    <link rel="next" title="Frequently Asked Questions" href="faq.html" />
+    <link rel="next" title="Module Development Guide" href="moduledev.html" />
     <link rel="prev" title="Playbooks" href="playbooks.html" />
 <script type="text/javascript">
 (function () {
@@ -118,6 +118,7 @@ s.parentNode.insertBefore(ga, s);
 <li class="toctree-l1"><a class="reference internal" href="YAMLSyntax.html">YAML Syntax</a></li>
 <li class="toctree-l1"><a class="reference internal" href="playbooks.html">Playbooks</a></li>
 <li class="toctree-l1 current"><a class="current reference internal" href="">Using the Python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development Guide</a></li>
 <li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a></li>
 <li class="toctree-l1"><a class="reference internal" href="man.html">Man Pages</a></li>
 </ul>
@@ -139,8 +140,8 @@ s.parentNode.insertBefore(ga, s);
             
   <li><a href="playbooks.html"
          title="previous chapter">&laquo; Playbooks</a></li>
-  <li><a href="faq.html"
-         title="next chapter">Frequently Asked Questions &raquo;</a></li>
+  <li><a href="moduledev.html"
+         title="next chapter">Module Development Guide &raquo;</a></li>
           
           
             
diff --git a/examples.html b/examples.html
index 9b91894516..0a5577da30 100644
--- a/examples.html
+++ b/examples.html
@@ -118,6 +118,7 @@ s.parentNode.insertBefore(ga, s);
 <li class="toctree-l1"><a class="reference internal" href="YAMLSyntax.html">YAML Syntax</a></li>
 <li class="toctree-l1"><a class="reference internal" href="playbooks.html">Playbooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">Using the Python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development Guide</a></li>
 <li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a></li>
 <li class="toctree-l1"><a class="reference internal" href="man.html">Man Pages</a></li>
 </ul>
diff --git a/faq.html b/faq.html
index b4982e4bf8..bdb3f9d5b0 100644
--- a/faq.html
+++ b/faq.html
@@ -27,7 +27,7 @@
     <script type="text/javascript" src="_static/bootstrap-scrollspy.js"></script>
     <link rel="top" title="Ansible - SSH-Based Configuration Management &amp; Deployment" href="index.html" />
     <link rel="next" title="Man Pages" href="man.html" />
-    <link rel="prev" title="Using the Python API" href="api.html" />
+    <link rel="prev" title="Module Development Guide" href="moduledev.html" />
 <script type="text/javascript">
 (function () {
   /**
@@ -118,6 +118,7 @@ s.parentNode.insertBefore(ga, s);
 <li class="toctree-l1"><a class="reference internal" href="YAMLSyntax.html">YAML Syntax</a></li>
 <li class="toctree-l1"><a class="reference internal" href="playbooks.html">Playbooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">Using the Python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development Guide</a></li>
 <li class="toctree-l1 current"><a class="current reference internal" href="">Frequently Asked Questions</a></li>
 <li class="toctree-l1"><a class="reference internal" href="man.html">Man Pages</a></li>
 </ul>
@@ -150,8 +151,8 @@ s.parentNode.insertBefore(ga, s);
           
           
             
-  <li><a href="api.html"
-         title="previous chapter">&laquo; Using the Python API</a></li>
+  <li><a href="moduledev.html"
+         title="previous chapter">&laquo; Module Development Guide</a></li>
   <li><a href="man.html"
          title="next chapter">Man Pages &raquo;</a></li>
           
diff --git a/genindex.html b/genindex.html
index 443c2308bc..4fac68cba6 100644
--- a/genindex.html
+++ b/genindex.html
@@ -116,6 +116,7 @@ s.parentNode.insertBefore(ga, s);
 <li class="toctree-l1"><a class="reference internal" href="YAMLSyntax.html">YAML Syntax</a></li>
 <li class="toctree-l1"><a class="reference internal" href="playbooks.html">Playbooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">Using the Python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development Guide</a></li>
 <li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a></li>
 <li class="toctree-l1"><a class="reference internal" href="man.html">Man Pages</a></li>
 </ul>
diff --git a/gettingstarted.html b/gettingstarted.html
index e44ecde3c0..366bff1429 100644
--- a/gettingstarted.html
+++ b/gettingstarted.html
@@ -118,6 +118,7 @@ s.parentNode.insertBefore(ga, s);
 <li class="toctree-l1"><a class="reference internal" href="YAMLSyntax.html">YAML Syntax</a></li>
 <li class="toctree-l1"><a class="reference internal" href="playbooks.html">Playbooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">Using the Python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development Guide</a></li>
 <li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a></li>
 <li class="toctree-l1"><a class="reference internal" href="man.html">Man Pages</a></li>
 </ul>
diff --git a/index.html b/index.html
index 085399eace..2bd0d92967 100644
--- a/index.html
+++ b/index.html
@@ -117,6 +117,7 @@ s.parentNode.insertBefore(ga, s);
 <li class="toctree-l1"><a class="reference internal" href="YAMLSyntax.html">YAML Syntax</a></li>
 <li class="toctree-l1"><a class="reference internal" href="playbooks.html">Playbooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">Using the Python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development Guide</a></li>
 <li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a></li>
 <li class="toctree-l1"><a class="reference internal" href="man.html">Man Pages</a></li>
 </ul>
@@ -300,6 +301,19 @@ you with questions about Ansible.</p>
 <li class="toctree-l2"><a class="reference internal" href="api.html#detailed-api-example">Detailed API Example</a></li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development Guide</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="moduledev.html#tutorial">Tutorial</a></li>
+<li class="toctree-l2"><a class="reference internal" href="moduledev.html#testing-modules">Testing Modules</a></li>
+<li class="toctree-l2"><a class="reference internal" href="moduledev.html#reading-input">Reading Input</a></li>
+<li class="toctree-l2"><a class="reference internal" href="moduledev.html#common-pitfalls">Common Pitfalls</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="moduledev.html#conventions">Conventions</a></li>
+<li class="toctree-l3"><a class="reference internal" href="moduledev.html#shorthand-vs-json">Shorthand Vs JSON</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="moduledev.html#sharing-your-module">Sharing Your Module</a></li>
+<li class="toctree-l2"><a class="reference internal" href="moduledev.html#getting-your-module-into-core">Getting Your Module Into Core</a></li>
+</ul>
+</li>
 <li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="faq.html#what-inspired-ansible">What inspired Ansible?</a></li>
 <li class="toctree-l2"><a class="reference internal" href="faq.html#comparisons">Comparisons</a><ul>
diff --git a/man.html b/man.html
index 01a7a20cdf..54335ea6ba 100644
--- a/man.html
+++ b/man.html
@@ -117,6 +117,7 @@ s.parentNode.insertBefore(ga, s);
 <li class="toctree-l1"><a class="reference internal" href="YAMLSyntax.html">YAML Syntax</a></li>
 <li class="toctree-l1"><a class="reference internal" href="playbooks.html">Playbooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">Using the Python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development Guide</a></li>
 <li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a></li>
 <li class="toctree-l1 current"><a class="current reference internal" href="">Man Pages</a></li>
 </ul>
diff --git a/man/ansible-playbook.1.html b/man/ansible-playbook.1.html
index cbca4f0988..032b0aa1bc 100644
--- a/man/ansible-playbook.1.html
+++ b/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="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
+<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="id530459"></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>
diff --git a/man/ansible.1.html b/man/ansible.1.html
index 569f03818c..f6ebe3b200 100644
--- a/man/ansible.1.html
+++ b/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="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
+<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="id345285"></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>
diff --git a/modules.html b/modules.html
index a9f63efcfc..84e86c7293 100644
--- a/modules.html
+++ b/modules.html
@@ -118,6 +118,7 @@ s.parentNode.insertBefore(ga, s);
 <li class="toctree-l1"><a class="reference internal" href="YAMLSyntax.html">YAML Syntax</a></li>
 <li class="toctree-l1"><a class="reference internal" href="playbooks.html">Playbooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">Using the Python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development Guide</a></li>
 <li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a></li>
 <li class="toctree-l1"><a class="reference internal" href="man.html">Man Pages</a></li>
 </ul>
diff --git a/patterns.html b/patterns.html
index 6cf24f5f54..a753a3ec03 100644
--- a/patterns.html
+++ b/patterns.html
@@ -118,6 +118,7 @@ s.parentNode.insertBefore(ga, s);
 <li class="toctree-l1"><a class="reference internal" href="YAMLSyntax.html">YAML Syntax</a></li>
 <li class="toctree-l1"><a class="reference internal" href="playbooks.html">Playbooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">Using the Python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development Guide</a></li>
 <li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a></li>
 <li class="toctree-l1"><a class="reference internal" href="man.html">Man Pages</a></li>
 </ul>
diff --git a/playbooks.html b/playbooks.html
index eb386730e9..bf45345d8b 100644
--- a/playbooks.html
+++ b/playbooks.html
@@ -118,6 +118,7 @@ s.parentNode.insertBefore(ga, s);
 <li class="toctree-l1"><a class="reference internal" href="YAMLSyntax.html">YAML Syntax</a></li>
 <li class="toctree-l1 current"><a class="current reference internal" href="">Playbooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">Using the Python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development Guide</a></li>
 <li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a></li>
 <li class="toctree-l1"><a class="reference internal" href="man.html">Man Pages</a></li>
 </ul>
@@ -191,7 +192,9 @@ alt="Fork me on GitHub"
 <dt><a class="reference internal" href="YAMLSyntax.html"><em>YAML Syntax</em></a></dt>
 <dd>Learn about YAML syntax</dd>
 <dt><a class="reference internal" href="modules.html"><em>Ansible Modules</em></a></dt>
-<dd>Learn about available modules and writing your own</dd>
+<dd>Learn about available modules</dd>
+<dt><a class="reference internal" href="moduledev.html"><em>Module Development Guide</em></a></dt>
+<dd>Learn how to extend Ansible by writing your own modules</dd>
 <dt><a class="reference internal" href="patterns.html"><em>The Inventory File, Patterns, and Groups</em></a></dt>
 <dd>Learn about how to select hosts</dd>
 <dt><a class="reference external" href="https://github.com/ansible/ansible/tree/master/examples/playbooks">Github examples directory</a></dt>
diff --git a/rst/index.rst b/rst/index.rst
index 9cbc990a1e..25e50d3ca5 100644
--- a/rst/index.rst
+++ b/rst/index.rst
@@ -91,6 +91,7 @@ Contents
    YAMLSyntax
    playbooks
    api
+   moduledev
    faq
    man
 
diff --git a/rst/moduledev.rst b/rst/moduledev.rst
new file mode 100644
index 0000000000..fe503675fa
--- /dev/null
+++ b/rst/moduledev.rst
@@ -0,0 +1,253 @@
+Module Development Guide
+========================
+
+.. seealso::
+
+   :doc:`modules`
+       Learn about available modules
+   `Github modules directory <https://github.com/ansible/ansible/tree/master/library>`_
+       Browse source of core modules
+
+
+Ansible modules are reusable units of magic that can be used by the Ansible API, 
+or by the `ansible` or `ansible-playbook` programs.
+
+Modules can be written in any language and are found in the path specified 
+by `ANSIBLE_LIBRARY_PATH` or the `--module-path` command line option.
+ 
+Tutorial 
+````````
+
+Let's build a module to get and set the system time.  For starters, let's build
+a module that just outputs the current time.  
+
+We are going to use Python here but any language is possible.  Only File I/O and outputing to standard
+out are required.  So, bash, C++, clojure, Python, Ruby, whatever you want
+is fine.
+
+It's obvious that you would never really need to build a module to set the system time,
+the 'command' module could already be used to do this.  However, it makes for a decent example.
+Reading the modules that come with ansible (linked above) is a great way to learn how to write
+modules.   Keep in mind, though, that some modules in ansible's source tree are internalisms,
+so look at `service` or `yum`, and don't stare too close into things like `async_wrapper` or
+you'll turn to stone.  Nobody ever executes async_wrapper directly.
+
+Ok, let's get going with an example.  We'll use Python.  For starters, save this as a file named `time`::
+
+    #!/usr/bin/python
+
+    import datetime
+    import json
+
+    date = str(datetime.datetime.now())
+    print json.dumps({
+        "time" : date
+    })
+
+Testing Modules
+```````````````
+
+There's a useful test script in the source checkout for ansible::
+
+    git clone git@github.com:ansible/ansible.git
+    chmod +x ansible/hacking/test-module
+
+Let's run the script you just wrote with that::
+
+    ansible/hacking/test-module ./time
+
+You should see output that looks something like this::
+
+    {u'time': u'2012-03-14 22:13:48.539183'}
+
+If you did not, you might have a typo in your module, so recheck it and try again
+
+Reading Input
+`````````````
+
+Let's modify the module to allow setting the current time.  We'll do this by seeing
+if a key value pair in the form `time=<string>` is passed in to the module.
+
+Ansible internally saves arguments to a arguments file.  So we must read the file
+and parse it.  The arguments file is just a string, so any form of arguments are legal.
+Here we'll do some basic parsing to treat the input as key=value.
+
+The example usage we are trying to achieve to set the time is::
+
+   time time="March 14 22:10"
+
+If no time parameter is set, we'll just leave the time as is and return the current time.
+
+.. note:
+   This is obviously an unrealistic idea for a module.  You'd most likely just
+   use the shell module.  However, it probably makes a decent tutorial.
+
+Let's look at the code.  Read the comments as we'll explain as we go.  Note that this
+highly verbose because it's intended as an educational example.  You can write modules 
+a lot shorter than this::
+
+    #!/usr/bin/python
+
+    # import some python modules that we'll use.  These are all
+    # available in Python's core
+
+    import datetime
+    import sys
+    import json
+    import os
+    import shlex
+
+    # read the argument string from the arguments file
+    args_file = sys.argv[1]
+    args_data = file(args_file).read()
+
+    # for this module, we're going to do key=value style arguments
+    # this is up to each module to decide what it wants, but all
+    # core modules besides 'command' and 'shell' take key=value
+    # so this is highly recommended
+    
+    arguments = shlex.split(args_data)
+    for arg in arguments:
+
+        # ignore any arguments without an equals in it
+        if arg.find("=") != -1:
+ 
+            (key, value) = arg.split("=")
+
+            # if setting the time, the key 'time'
+            # will contain the value we want to set the time to
+
+            if key == "time":
+
+                # now we'll affect the change.  Many modules
+                # will strive to be 'idempotent', meaning they
+                # will only make changes when the desired state
+                # expressed to the module does not match
+                # the current state.  Look at 'service'
+                # or 'yum' in the main git tree for an example
+                # of how that might look.
+
+                rc = os.system("date -s \"%s\"" % value)
+
+                # always handle all possible errors
+                #
+                # when returning a failure, include 'failed'
+                # in the return data, and explain the failure
+                # in 'msg'.  Both of these conventions are
+                # required however additional keys and values
+                # can be added.
+
+                if rc != 0:
+                    print json.dumps({
+                        "failed" : True,
+                        "msg"    : "failed setting the time"
+                    })
+                    sys.exit(1)
+
+                # when things do not fail, we do not
+                # have any restrictions on what kinds of
+                # data are returned, but it's always a 
+                # good idea to include whether or not
+                # a change was made, as that will allow
+                # notifiers to be used in playbooks.  
+
+                date = str(datetime.datetime.now())
+                print json.dumps({
+                    "time" : date,
+                    "changed" : True
+                })
+                sys.exit(0)
+
+    # if no parameters are sent, the module may or 
+    # may not error out, this one will just
+    # return the time
+
+    date = str(datetime.datetime.now())
+    print json.dumps({
+        "time" : date
+    })
+
+Let's test that module::
+
+    ../ansible/hacking/test-module ./rst/time time=\"March 14 12:23\"
+
+This should return something like::
+
+    {"changed": true, "time": "2012-03-14 12:23:00.000307"}
+
+
+Common Pitfalls
+```````````````
+
+If writing a module in Python and you have managed nodes running
+Python 2.4 or lower, this is generally a good idea, because
+json isn't in the Python standard library until 2.5.::
+
+    try:
+        import json
+    except ImportError:
+        import simplejson as json
+
+You should also never do this in a module::
+
+    print "some status message"
+    
+Because the output is supposed to be valid JSON.  Except that's not quite true,
+but we'll get to that later.
+
+Conventions
+-----------
+
+As a reminder from the example code above, here are some basic conventions
+and guidelines:
+
+* Include a minimum of dependencies if possible.  If there are dependencies, document them at the top of the module file
+
+* Modules must be self contained in one file to be auto-transferred by ansible
+
+* If packaging modules in an RPM, they only need to be installed on the control machine and should be dropped into /usr/share/ansible.  This is entirely optional.
+
+* Modules should return JSON or key=value results all on one line.  JSON is best if you can do JSON.  All return types must be hashes (dictionaries) although they can be nested.
+
+* In the event of failure, a key of 'failed' should be included, along with a string explanation in 'msg'.  Modules that raise tracebacks (stacktraces) are generally considered 'poor' modules, though Ansible can deal with these returns and will automatically convert anything unparseable into a failed result.
+
+* Return codes are actually not signficant, but continue on with 0=success and non-zero=failure for reasons of future proofing.
+
+* As results from many hosts will be aggregrated at once, modules should return only relevant output.  Returning the entire contents of a log file is generally bad form.
+
+
+Shorthand Vs JSON
+-----------------
+
+To make it easier to write modules in bash and in cases where a JSON
+module might not be available, it is acceptable for a module to return
+key=value output all on one line, like this.   The Ansible parser
+will know what to do.::
+
+    somekey=1 somevalue=two favcolor=red
+
+If you're writing a module in Python or Ruby or whatever, though, returning
+JSON is probably the simplest way to go.
+
+
+Sharing Your Module
+```````````````````
+
+If you think your module is generally useful to others, Ansible is preparing
+an 'ansible-contrib' repo.  Stop by the mailing list and we'll help you to
+get your module included.  Contrib modules can be implemented in a variety
+of languages.  Including a README with your module is a good idea so folks
+can understand what arguments it takes and so on.  We would like to build
+up as many of these as possible in as many languages as possible.
+
+`Ansible Mailing List <http://groups.google.com/group/ansible-project>`_
+
+Getting Your Module Into Core
+`````````````````````````````
+
+High-quality modules with minimal dependencies 
+can be included in the core, but core modules (just due to the programming
+preferences of the developers) will need to be implemented in Python.
+Stop by the mailing list to inquire about requirements.
+
+
diff --git a/rst/playbooks.rst b/rst/playbooks.rst
index dfae05b9b0..88f6d7116d 100644
--- a/rst/playbooks.rst
+++ b/rst/playbooks.rst
@@ -6,7 +6,9 @@ Playbooks
    :doc:`YAMLSyntax`
        Learn about YAML syntax
    :doc:`modules`
-       Learn about available modules and writing your own
+       Learn about available modules
+   :doc:`moduledev`
+       Learn how to extend Ansible by writing your own modules
    :doc:`patterns`
        Learn about how to select hosts
    `Github examples directory <https://github.com/ansible/ansible/tree/master/examples/playbooks>`_
diff --git a/search.html b/search.html
index 9c89b00805..6bb09a3bb0 100644
--- a/search.html
+++ b/search.html
@@ -122,6 +122,7 @@ s.parentNode.insertBefore(ga, s);
 <li class="toctree-l1"><a class="reference internal" href="YAMLSyntax.html">YAML Syntax</a></li>
 <li class="toctree-l1"><a class="reference internal" href="playbooks.html">Playbooks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="api.html">Using the Python API</a></li>
+<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development Guide</a></li>
 <li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a></li>
 <li class="toctree-l1"><a class="reference internal" href="man.html">Man Pages</a></li>
 </ul>
diff --git a/searchindex.js b/searchindex.js
index b7bc16a398..2bb4e034d8 100644
--- a/searchindex.js
+++ b/searchindex.js
@@ -1 +1 @@
-Search.setIndex({objects:{},terms:{all:[0,1,2,3,4,5,6,7,8],concept:8,forget:5,myapp:8,perl:8,selinux:5,consum:3,pluggabl:3,invent:5,prefix:[4,5,8],code:[2,3,4,8],sleep:5,higher:5,abil:3,follow:[3,4,5,6,7,8],scp:8,content:[0,3,5,2],decid:[3,8],middl:[],depend:[3,5],wish:[0,1,3,5,6,7],sensit:[2,5],graph:3,elsewher:8,specif:[6,7,8],program:[2,3,4,5,1],mcollect:2,leav:5,blindingli:2,spec:5,introduc:2,emploi:1,sourc:[2,3,4,5,7,8],everi:[5,1,8],string:4,fals:[4,1],multi:[2,3,5],liter:4,failur:[7,3,4],veri:[7,2,3,5,8],affect:[4,5],implicitli:3,parameter:5,magic:[3,5],level:[4,5,1],id_rsa:[0,8],list:[2,1,3,4,5,6,8,9],"try":3,item:[7,1],sane:3,form:[5,1],team:3,dotnet:1,saltstack:2,spent:3,servic:[2,4,5,8],playbook:[0,1,2,3,4,5,6,7,8,9],pleas:3,alic:5,trend:4,natur:[4,5],seper:3,direct:[3,5],straighten:3,chef:[2,3],second:[5,8],design:[2,3,5],pass:[4,5],download:[0,2],further:[5,1],submit:3,port:[3,8],even:[3,5,8],what:[0,1,2,3,4,5],compar:3,favcolor:[5,8],fine:3,section:[2,4,5],async_statu:8,current:[3,8],"public":5,abbrevi:1,version:[4,5,8],suspect:3,"new":3,net:[],varnam:5,ever:2,method:7,told:5,impact:3,hasn:3,hash:[4,1],facter_hostnam:5,eckersberg:[3,1],gener:3,never:3,privat:5,here:[2,4,5,8],shouldn:[3,5],let:[5,1,8],address:[6,3,4],path:4,along:5,sinc:8,valu:[4,5,1,8],wait:5,box:[2,4],great:[2,3,5],pretti:[7,3],ahead:5,precursor:2,likin:3,fixm:[],adopt:3,host:[0,2,3,4,5,6,7,8],prior:4,pick:[3,8],action:[2,4,5],extrem:0,implement:7,commonli:[8,1],ourselv:5,employe:1,via:[0,2],regardless:[2,3,5,1],extra:3,apach:[3,5,8],modul:[0,2,3,4,5,7,8],ask:[2,3],unix:3,"boolean":1,instal:[0,2,3,4,5,8],total:5,cloud:3,kei:[0,4,5,1],httpd:[5,8],from:[0,2,3,4,5,8],describ:[4,5],would:[4,5,8],commun:3,"super":2,visit:2,two:[0,5,6],noarch:0,few:5,live:0,handler:[2,5,8],call:[4,5,1],usr:[7,4,5,8],msg:[7,4],somevar:5,kick:[3,5,8],type:[7,3],tell:[4,5,8],more:[0,2,3,4,5,6],sort:3,flat:5,exit:7,desir:5,idempot:[3,4,5,8],src:[4,5,8],python:[0,1,2,3,4,7,8],notif:3,sshd:2,notic:3,train:3,agent:[0,8],particular:[2,5],actual:[3,4,5],compani:3,easiest:[2,5],starter:5,must:[4,5],placehold:5,none:7,join:2,ibm:2,module_arg:7,alia:6,setup:[2,4,8],work:[0,2,3,4,5,6,8],knows_oop:1,dev:3,remain:2,minimum:5,can:[0,1,2,3,4,5,6,7,8],erb:3,learn:[0,1,2,3,5,6],under:5,purpos:4,root:[2,5],control:[2,4,5,8],congratul:0,want:[1,3,4,5,7,8],tar:0,give:1,process:[2,3,4,5,8],lock:5,chip:2,sudo:[0,5],share:[4,5],templat:[0,2,3,4,5,8],high:8,critic:2,tag:[0,4],surround:[],explor:0,onlin:1,occur:[],contribut:[2,8],alwai:[3,4,5],cours:3,multipl:[6,3,5,8],newlin:[],lame:1,rather:[3,4],anoth:[3,1],ping:[0,7,4,2],uptim:7,write:[2,1,3,4,5,8],how:[0,1,2,3,4,5,6,7,8],anyon:3,hop:3,instead:[3,4],somevalu:5,config:[2,5],stock:4,map:5,express:[2,7,5,1],resourc:[2,3,5],referenc:[6,5],max:8,clone:0,after:[3,5,8],lab:[2,3],befor:[3,4,5,8],ohai_:[4,5],tier:5,end:[3,4,5],data:[2,1,3,4,5,7,8],parallel:[2,3,5,8],man:[2,9],"short":[2,3],orchestr:[2,3,5],practic:[3,4,1],read:[0,7,1],secur:[3,4],explicit:4,element:4,issu:[2,3],inform:[7,4],mango:1,combin:1,allow:[3,5],exclus:5,order:[3,5],talk:[0,5],oper:[2,4,5,8],help:[2,1],portion:6,xmpp:3,over:[2,3,8],move:[4,5],orang:1,becaus:[3,1],elit:1,rpmbuild:0,comma:[],hierarchi:3,suffer:3,mainli:3,paramet:[4,5],facter_:[4,5],jid:8,overlord:0,group:[2,7,5,6],cli:7,minim:0,taboot:3,better:4,yaml:[2,3,5,1],pend:5,rapidli:7,infrastructur:[6,0,3,5,2],bin:[0,7,4,5,8],mail:[2,3,8,6],job_statu:[],main:5,might:5,easier:[3,1],wouldn:3,them:[1,3,4,5,6,8],good:3,"return":[7,2,3,4],thei:[3,4,5,6,7,8],food:1,safe:5,dai:3,number:4,"break":5,framework:[7,2,3],jinja2:[0,3,4,5,8],half:3,aka:5,now:[0,3,4,5,6],discuss:3,nor:4,choic:[2,5],multiprocess:[0,3],vidal:3,name:[2,1,4,5,6,8],anyth:[3,4],edit:0,simpl:[2,1,3,5,7,8],didn:3,instruct:[0,3],separ:5,exampl:[0,1,2,3,4,5,6,7,8,9],mode:[3,5,8],timeout:5,each:[3,4,5,1,8],debug:1,found:7,updat:[4,8],spend:3,mean:[3,4,5,1],harm:[],mental:3,michael:2,laserllama:2,hard:3,idea:[2,3,5],realli:[3,4,5,1],backport:0,expect:5,our:1,happen:[3,4],event:[3,4,5],out:[2,3,4,5,7,8],variabl:[2,3,4,5,8],safeti:6,network:2,space:4,reboot:[5,8],bubbl:[4,5],adapt:[],rel:4,internet:2,print:7,got:3,merg:3,correct:[2,3,5,1],red:[2,3,8],qualifi:4,insid:5,advanc:[7,3,5],ntp:8,differ:[8,0,3,5,2],pub:8,small:[3,5,1],reason:3,base:[2,3,5],believ:3,dictionari:[5,1],put:[0,5,8],org:0,bash:[0,3,8],basi:5,pyyaml:0,sytem:3,indent:1,recogn:5,launch:5,argument:[4,5],could:[7,3,5],synchron:5,fqdn:8,keep:5,thing:[2,3,5,1,6],yum:[2,4,5,8],isn:[2,3],adrian:3,retain:3,think:3,frequent:[2,3,5],first:[0,2,3,4,5,8],origin:2,softwar:[2,3,4,8],rang:2,notifi:[2,3,5,8],render:4,feel:1,onc:[3,4,5],scene:4,yourself:0,mai:[0,1,3,4,5,7],unlik:[3,5],alreadi:[0,3,4,5],puppet:[2,3],"long":[2,3,4,5,8],massiv:2,open:[3,5],given:[3,4,8],bracket:6,convent:4,script:[7,2,3,8],associ:1,top:[3,4,5],mkdir:[],system:[0,2,3,4,5,6,8],construct:[7,3],inventori:[2,4,5,6],appl:1,too:[2,3,5,1],statement:[2,5],gather:3,termin:8,john:[3,1],"final":[],rpath:2,iptabl:[],shell:[2,4,8],option:[7,3,8,9],especi:3,tool:[2,3,4,5,7,8,9],copi:[2,4,8],took:3,specifi:[3,4,5,1,8],retyp:0,github:[0,5,2],pars:3,kept:[3,5],exactli:4,than:[0,1,2,3,4,5,8],wide:3,kind:3,silli:[],target:[2,6],keyword:[3,5],provid:1,remov:[4,5,8],dive:5,richer:3,structur:[],banana:[],project:[8,0,3,5,2],reus:[2,5],architect:2,were:[3,5],minut:[3,8],uses_cv:1,provis:3,pre:0,sai:[3,4,5,8],bootstrap:[2,3],runner:7,favorit:2,mind:3,ani:[2,3,4,5,7,8],seth:3,dash:1,packag:[2,3,4,8],aforement:6,complet:[3,5],have:[0,1,2,3,5,6],interfac:3,need:[0,1,3,4,5,8],seem:3,cfengin:3,seek:4,paramiko:0,sat:3,imagin:5,engin:8,squar:[],contact:[7,0,3,4],note:[6,4,5,8],also:[0,1,2,3,4,5,6,7,8],ideal:[2,3],client:2,build:[7,0,3],indic:[4,5],environ:4,datacent:5,hook:4,singl:[3,5],blue:5,begin:[8,1],sure:[5,8],unless:[4,5],distribut:[0,3,2],deploy:[2,3,5,8],track:8,reach:2,deleg:3,discov:5,most:[3,4,1],plai:[4,5],regular:5,plan:3,deploi:[2,3,4,5,8],bsd:3,why:2,strawberri:1,don:[6,3,4,5,8],doc:2,later:[5,8],cover:[3,8],doe:[2,3,4,6],meanwhil:3,declar:5,snapshot:4,runtim:5,clean:3,pattern:[2,7,5,6],built:[0,3,8],latest:[4,5,8],awesom:[2,5],show:[5,8],cheat:3,text:3,verbos:4,syntax:[2,3,5,1],connect:5,bring:[3,5],directli:[4,5,8],raleigh:2,particularli:5,pkg:[4,5,8],hack:2,radic:2,identifi:3,trivial:[2,4],find:[3,4],rotat:5,xml:1,absolut:4,onli:[0,3,4,5,8],explicitli:[4,5],locat:4,execut:[7,2,3,4,5],tire:3,transact:5,configur:[0,1,2,3,4,5,6,8],solut:3,written:[2,4,5,8],somefil:5,should:[3,4,1],suppos:5,about:[0,1,2,3,4,5],local:4,yml:5,custom:[3,5],long_running_oper:8,nearli:[4,5,1],variou:[3,4,5],get:[0,1,2,3,5,8],financ:2,stop:[3,4,8],autom:[3,5],repo:[4,8],ssl:3,obviou:2,ssh:[0,3,8,2],increas:5,grep:4,requir:[0,3,4,5,2],uvh:0,mdehaan:5,bar:[6,5],patch:3,sha:4,releas:[0,3],stuff:8,common:[5,1],contain:[3,4,5],usabl:[2,5],through:[0,4,2],where:[2,3,4],view:[2,9],respond:5,set:[0,3,4,5],hierachi:3,arbitari:1,see:[0,1,2,3,4,5,6,8,9],sec:5,result:[7,4,5],fail:[7,3,5],charact:1,setsebool:5,best:[3,4,5],subject:5,asynchron:[2,5],statu:[5,8],still:3,extend:[2,3],expert:3,down:[7,5],databas:5,someth:[2,3,4,5,8],discoveri:4,restart:[3,4,5,8],state:[3,4,5,8],won:[5,8],between:[3,5],"import":[7,5],experi:3,across:3,attribut:4,altern:[5,8],solo:3,manpag:0,style:[],extens:[2,3],job:[8,1],entir:[3,5],aserv:0,webapp:[3,8],timmi:5,addit:[2,5],both:3,delimit:4,goal:2,howev:3,equal:3,against:[2,3,5,6],etc:[0,2,3,4,5,6,8],instanc:5,logic:5,mani:[5,8],com:[0,7,5,6],among:3,assur:5,simpli:[4,5],figur:3,overview:1,format:[2,1,3,4,5,6,8],inspir:[2,3],chmod:5,distil:3,fashion:3,colon:5,shutdown:4,linux:[2,3],poll:[2,5,8],mission:2,coupl:3,platform:3,multiplay:2,three:6,been:[2,3],json:[7,2,3,4,1],much:[2,3,4,5,1],treat:3,basic:[0,1,2,3,4,5,6],futur:0,quickli:[2,8],capistrano:[2,3],fire:[2,3,5],rubi:[3,4,8,1],anywher:5,upgrad:[4,8],togeth:5,func:[2,3],predic:4,atlanta:[5,8],those:[3,4,5],"case":3,authorized_kei:0,exception:3,look:[6,5,8],replac:[],hoc:[2,3,4,5,8],straight:8,md5sum:4,permit:[],batch:3,vars_fil:5,trick:[2,5],defin:5,"while":[3,5],match:5,abov:[5,8],error:3,cobbler:[2,3],dehaan:2,layer:3,motd:[5,8],max_client:5,stdout:7,almost:[3,4],technolog:2,site:[3,9],memcach:5,dag:3,conf:[5,8],module_nam:7,sever:[3,5,1],around:3,http_port:5,develop:[0,3,1,2],welcom:2,author:2,perform:3,make:[0,3,4,5,8],ohai:[2,3,4,5,8],cross:3,same:[6,5,1,8],member:1,handl:3,complex:[2,3,5],document:[0,1,3,5,7,8],ansibl:[0,1,2,3,4,5,6,7,8,9],difficult:3,http:4,hostnam:[7,5],again:[3,5],nest:4,painless:2,rail:3,effect:[],remot:[0,4,5,8],assign:[2,5],fruit:1,user:[2,3,4,5],extern:[2,5],php:8,distutil:[0,2],typic:[3,8],tune:[],recent:3,dark:7,lower:3,appropri:3,off:[2,3,5],scenario:4,mention:5,setenforc:5,compos:5,well:[0,3,4,5],hypothet:[],non:[2,5],without:3,command:[0,2,3,4,5,6,7,8,9],thi:[0,1,3,4,5,6,8],choos:4,programm:[7,3],model:5,dereferenc:5,usual:[],protocol:4,just:[0,1,2,3,4,5,8],less:[0,3,2],when:[3,4,5,8],rest:9,detail:[2,7,8],kill:[],irc:2,human:1,heavili:3,skill:1,simultan:8,languag:[0,1,2,3,4,5,6],web:[7,3,5,9,8],versu:2,easi:[2,3,4,6],mix:[6,5],except:[],littl:[2,3],add:[0,3,8],other:[0,1,2,3,4,5,8],notori:3,els:[2,5],save:5,hat:[2,3],app:3,smart:8,take:[3,4,5],real:0,applic:[7,3,5],which:[0,6,5,1,2],quirk:1,dest:[4,5,8],judgement:4,game:2,know:[3,4,1],background:[2,8],world:[0,3],bit:[3,4],password:[0,5],daemon:[2,3],motorola:2,like:[1,3,4,5,6,8],success:4,header:6,signal:[3,5],arbitrari:3,manual:[3,5],integ:4,divers:2,api:[7,2,3,4],necessari:[4,8],either:[3,4],lose:8,popular:2,async:[3,5],external_var:5,page:[9,0,3,1,2],emerg:2,shed:3,drop:4,often:3,webserv:[6,5,8],suppli:4,some:[0,3,4,5,2],back:[3,5],dead:2,born:3,heritag:3,server:[2,3,4,5,8],transport:[2,3],tmp:8,txt:4,forcibl:[],lead:3,bottom:5,rpm:[0,2],avoid:[0,3,4],though:[2,3,4,5],definit:5,thank:3,per:7,tracker:2,larg:3,select:[2,4,5,6],foo:[6,5,8],complic:[2,3],refer:8,machin:[0,3,4,5,8],core:[2,3],encourag:3,yamllint:1,run:[0,1,3,4,5,7,8],power:[7,2,3,5],usag:[4,8],asciidoc:0,web2:7,vhost:5,step:[3,4,5],web1:7,promot:3,repositori:0,output:[3,5],meantim:3,appli:3,task:[2,3,5,8],soon:[],simpler:[3,8],comparison:[2,3],sbin:[4,5,8],central:3,othervar:[],acm:8,simul:5,srv:[5,8],messag:[7,3],done:[3,5],industri:2,disabl:5,block:5,ntp_server:8,own:[2,3,4,5],effici:[3,5],bounc:[4,5],within:[3,4],contriv:[],sneaker:[],automat:4,due:3,noth:[5,1],pair:[4,1],multinod:3,ensur:[3,5,8],chang:[4,5,8],next:5,bserver:0,your:[0,2,3,4,5,6,8],risk:5,manag:[0,1,2,3,4,5,6,8],behind:[3,4],git:[0,3,4,8,2],fabric:[2,3],wai:[0,3,5,8],aren:3,transfer:[2,8],support:[2,3,4,5],question:[2,3],fast:2,happi:2,avail:[0,1,3,4,5,7,8,9],start:[0,1,2,3,4,5,8],trigger:[3,4,5],wordpress:5,includ:[2,4,5],lot:[2,8],suit:[3,5],"var":[2,5],datastructur:7,individu:6,fork:[7,3,5,8],head:[4,8],simplejson:0,enough:[6,3,8],lint:1,yeah:[],taken:[3,5],line:[0,1,2,3,4,5,6,7,8,9],"true":[4,1],freenod:2,info:8,pull:3,"throw":3,made:[3,4,8],possibl:[6,5,8],whether:[7,3],checkout:[3,4],caller:4,maximum:5,until:[0,5],planet:2,record:1,below:5,limit:[2,5,8],rerun:5,otherwis:4,problem:[3,1],similar:[2,4,5],email:2,facter:[2,3,4,5,8],curv:[2,3],featur:[6,3,5],tasti:1,creat:[2,3],certain:[3,5],doesn:[2,5,1],repres:[5,1],strongli:3,exist:[2,5],file:[0,1,2,4,5,6,8],home:4,bob:5,ship:4,check:[3,4,5,8],probabl:[3,5],echo:[0,5],denot:6,coder:3,googl:2,dbserver:[6,5],excel:[2,3],unnecessari:4,"default":[2,3,5,6],likes_emac:1,librari:1,varieti:3,test:[0,3,4],assum:5,you:[0,1,2,3,4,5,6,8],architectur:[2,3],node:[0,2,3,4,5,8],contend:3,sysadmin:3,wildcard:6,fulli:4,sequenc:2,"class":[2,5],devop:2,push:[3,5],scale:[2,3],intent:[],log:5,deferenc:[],gap:3,"60k":[2,3],stai:5,sphinx:0,faster:5,amp:0,directori:[4,5],reliabl:3,itself:7,place:2,potenti:[],time:[0,1,2,3,4,5,6,8],far:[2,1],hello:0},objtypes:{},titles:["Downloads &amp; Getting Started","YAML Syntax","Introducing Ansible","Frequently Asked Questions","Ansible Modules","Playbooks","The Inventory File, Patterns, and Groups","Using the Python API","Command Line Examples","Man Pages"],objnames:{},filenames:["gettingstarted","YAMLSyntax","index","faq","modules","playbooks","patterns","api","examples","man"]})
\ No newline at end of file
+Search.setIndex({objects:{},terms:{all:[0,1,2,3,4,5,6,7,8,9],concept:9,forget:6,myapp:9,perl:9,selinux:6,consum:4,pluggabl:4,invent:6,prefix:[3,6,9],code:[2,5,4,3,9],sleep:6,higher:6,abil:4,follow:[4,3,6,7,8,9],scp:9,content:[0,4,5,6,2],decid:[4,5,9],middl:[],depend:[4,5,6],wish:[0,1,4,6,7,8],sensit:[2,6],graph:4,elsewher:9,specif:[7,8,9],program:[2,1,3,4,5,6],mcollect:2,leav:[5,6],blindingli:2,spec:6,introduc:2,emploi:1,sourc:[2,3,4,5,6,8,9],everi:[6,1,9],string:[5,3],fals:[3,1],multi:[2,4,6],signfic:5,failur:[8,5,4,3],veri:[8,2,4,6,9],affect:[5,3,6],implicitli:4,parameter:6,brows:5,relev:5,magic:[4,5,6],question:[2,4],level:[3,6,1],did:5,id_rsa:[0,9],list:[2,1,3,4,5,6,7,9,10],"try":[4,5],item:[8,1],sane:4,shlex:5,team:4,dotnet:1,saltstack:2,spent:4,servic:[2,5,3,6,9],playbook:[0,1,2,3,4,5,6,7,8,9,10],pleas:4,alic:6,trend:3,natur:[3,6],seper:4,direct:[4,6],straighten:4,chef:[2,4],second:[6,9],design:[2,4,6],pass:[5,3,6],download:[0,2],further:[6,1],submit:4,port:[4,9],folk:5,even:[4,6,9],what:[0,1,2,3,4,5,6],compar:4,favcolor:[5,6,9],fine:[4,5],section:[2,3,6],async_statu:9,current:[4,5,9],"public":6,abbrevi:1,version:[3,6,9],suspect:4,"new":4,net:[],ever:[2,5],method:8,told:6,impact:4,hasn:4,hash:[5,3,1],facter_hostnam:6,eckersberg:[4,1],gener:[4,5],never:[4,5],privat:6,here:[2,5,3,6,9],shouldn:[4,6],let:[5,6,1,9],argv:5,address:[7,4,3],path:[5,3],along:[5,6],args_fil:5,modifi:5,sinc:9,valu:[5,3,6,1,9],wait:6,box:[2,3],great:[2,4,5,6],pretti:[8,4],ahead:6,precursor:2,likin:4,fixm:[],adopt:4,host:[0,2,3,4,5,6,7,8,9],prior:3,pick:[4,9],action:[2,3,6],extrem:0,implement:[8,5],explain:5,commonli:[9,1],ourselv:6,employe:1,via:[0,2],regardless:[2,4,6,1],although:5,extra:4,apach:[4,6,9],modul:[0,2,3,4,5,6,8,9],prefer:5,ask:[2,4],unix:4,"boolean":1,instal:[0,2,3,4,5,6,9],total:6,cloud:4,highli:5,kei:[0,5,3,6,1],httpd:[6,9],from:[0,2,3,4,5,6,9],describ:[3,6],would:[5,3,6,9],commun:4,"super":2,visit:2,two:[0,5,6,7],noarch:0,few:6,live:0,handler:[2,6,9],call:[3,6,1],usr:[5,8,3,6,9],typo:5,recommend:5,msg:[5,8,3],somevar:6,kick:[4,6,9],type:[8,4,5],tell:[3,6,9],more:[0,2,4,3,6,7],sort:4,flat:6,exit:[8,5],desir:[5,6],idempot:[5,4,3,6,9],src:[3,6,9],python:[0,1,2,3,4,5,8,9],notif:4,stone:5,notic:4,train:4,agent:[0,9],particular:[2,6],actual:[5,4,3,6],compani:4,easiest:[2,6],starter:[5,6],must:[5,3,6],placehold:6,none:8,join:2,ibm:2,module_arg:8,alia:7,setup:[2,3,9],work:[0,2,4,3,6,7,9],knows_oop:1,dev:4,other:[0,1,2,3,4,5,6,9],remain:2,minimum:[5,6],whatev:5,erb:4,learn:[0,1,2,4,5,6,7],under:6,purpos:3,root:[2,6],proof:5,control:[2,5,3,6,9],congratul:0,want:[1,3,4,5,6,8,9],tar:0,give:1,process:[2,4,3,6,9],lock:6,chip:2,sudo:[0,6],share:[2,5,3,6],templat:[0,2,4,3,6,9],high:[5,9],critic:2,tag:[0,3],surround:[],explor:0,onlin:1,occur:[],contribut:[2,9],alwai:[5,4,3,6],cours:4,multipl:[7,4,6,9],newlin:[],lame:1,rather:[4,3],anoth:[4,1],ping:[0,8,3,2],uptim:8,write:[2,1,3,4,5,6,9],how:[0,1,2,3,4,5,6,7,8,9],anyon:4,hop:4,instead:[4,3],somevalu:[5,6],config:[2,6],stock:3,map:6,express:[2,8,5,6,1],resourc:[2,4,6],referenc:[7,6],max:9,clone:[0,5],after:[4,6,9],lab:[2,4],befor:[4,3,6,9],ohai_:[3,6],tier:6,end:[4,3,6],args_data:5,data:[2,1,3,4,5,6,8,9],parallel:[2,4,6,9],man:[2,10],"short":[2,4],orchestr:[2,4,6],practic:[4,3,1],read:[0,8,5,1,2],secur:[4,3],explicit:3,element:3,issu:[2,4],inform:[8,3],mango:1,combin:1,allow:[4,5,6],exclus:6,order:[4,6],talk:[0,6],oper:[2,3,6,9],help:[2,5,1],portion:7,xmpp:4,over:[2,4,9],move:[3,6],orang:1,becaus:[4,5,1],elit:1,rpmbuild:0,comma:[],hierarchi:4,suffer:4,mainli:4,paramet:[5,3,6],facter_:[3,6],jid:9,overlord:0,group:[2,8,6,7],cli:8,minim:[0,5],taboot:4,better:3,yaml:[2,4,6,1],pend:6,rapidli:8,infrastructur:[7,0,4,6,2],bin:[0,3,5,6,8,9],mail:[2,4,5,9,7],job_statu:[],main:[5,6],might:[5,6],easier:[4,5,1],wouldn:4,them:[1,3,4,5,6,7,9],good:[4,5],"return":[8,2,5,4,3],thei:[3,4,5,6,7,8,9],food:1,auto:5,safe:6,dai:4,number:3,"break":6,framework:[8,2,4],jinja2:[0,4,3,6,9],half:4,aka:6,now:[0,3,4,5,6,7],discuss:4,nor:3,strive:5,choic:[2,6],multiprocess:[0,4],vidal:4,name:[2,1,3,5,6,7,9],anyth:[5,4,3],edit:0,simpl:[2,1,4,6,8,9],didn:4,instruct:[0,4],separ:6,achiev:5,exampl:[0,1,2,3,4,5,6,7,8,9,10],mode:[4,6,9],timeout:6,each:[1,3,4,5,6,9],debug:1,found:[8,5],updat:[3,9],spend:4,mean:[5,4,3,6,1],harm:[],mental:4,michael:2,laserllama:2,hard:4,idea:[2,4,5,6],realli:[5,4,3,6,1],contrib:5,backport:0,expect:6,our:1,happen:[4,3],event:[5,4,3,6],out:[2,3,4,5,6,8,9],variabl:[2,4,3,6,9],safeti:7,network:2,space:3,reboot:[6,9],bubbl:[3,6],adapt:[],rel:3,internet:2,print:[8,5],got:4,merg:4,correct:[2,4,6,1],red:[2,4,5,9],qualifi:3,insid:6,advanc:[8,4,6],ntp:9,unpars:5,differ:[9,0,4,6,2],pub:9,standard:5,small:[4,6,1],reason:[4,5],base:[2,4,6],believ:4,dictionari:[5,6,1],put:[0,6,9],org:0,bash:[0,4,5,9],basi:6,reusabl:5,pyyaml:0,sytem:4,indent:1,recogn:6,launch:6,argument:[5,3,6],could:[8,4,5,6],traceback:5,synchron:6,fqdn:9,keep:[5,6],thing:[2,1,4,5,6,7],rais:5,yum:[2,5,3,6,9],isn:[2,4,5],adrian:4,retain:4,think:[4,5],frequent:[2,4,6],first:[0,2,4,3,6,9],origin:2,softwar:[2,4,3,9],rang:2,notifi:[2,4,5,6,9],render:3,feel:1,onc:[5,4,3,6],qualiti:5,scene:3,yourself:0,restrict:5,mai:[0,1,3,4,5,6,8],unlik:[4,6],alreadi:[0,5,4,3,6],puppet:[2,4],"long":[2,4,3,6,9],massiv:2,open:[4,6],avail:[0,1,3,4,5,6,8,9,10],given:[4,3,9],convent:[2,5,3],script:[8,2,4,5,9],associ:1,top:[5,4,3,6],mkdir:[],system:[0,2,3,4,5,6,7,9],construct:[8,4],inventori:[2,3,6,7],appl:1,too:[2,4,5,6,1],statement:[2,6],gather:4,termin:9,john:[4,1],"final":[],rpath:2,iptabl:[],shell:[2,5,3,9],option:[8,4,5,9,10],especi:4,tool:[2,4,3,6,8,9,10],copi:[2,3,9],took:4,specifi:[1,3,4,5,6,9],retyp:0,github:[0,5,6,2],pars:[4,5],rst:5,kept:[4,6],exactli:3,than:[0,1,2,3,4,5,6,9],wide:4,liter:3,silli:[],target:[2,7],keyword:[4,6],instanc:6,provid:1,remov:[3,6,9],dive:6,tree:5,richer:4,structur:[],banana:[],project:[9,0,4,6,2],inquir:5,reus:[2,6],architect:2,str:5,were:[4,6],minut:[4,9],uses_cv:1,recheck:5,provis:4,pre:0,sai:[4,3,6,9],bootstrap:[2,4],runner:8,favorit:2,mind:[4,5],ani:[2,3,4,5,6,8,9],seth:4,dash:1,packag:[2,5,4,3,9],aforement:7,async_wrapp:5,complet:[4,6],have:[0,1,2,4,5,6,7],interfac:4,need:[0,1,3,4,5,6,9],seem:4,predic:3,seek:3,paramiko:0,sat:4,imagin:6,date:5,squar:[],zero:5,self:5,contact:[8,0,4,3],note:[9,5,3,6,7],also:[0,1,2,3,4,5,6,7,8,9],ideal:[2,4],client:2,build:[8,0,4,5],indic:[3,6],environ:3,datacent:6,hook:3,singl:[4,6],blue:6,begin:[9,1],sure:[6,9],unless:[3,6],distribut:[0,4,2],deploy:[2,4,6,9],track:9,reach:2,deleg:4,discov:6,most:[4,3,1],plai:[3,6],regular:6,plan:4,deploi:[2,4,3,6,9],bsd:4,why:2,strawberri:1,don:[3,4,5,6,7,9],external_var:6,doc:2,later:[5,6,9],cover:[4,9],doe:[2,5,4,3,7],meanwhil:4,bracket:7,snapshot:3,place:2,clean:4,pattern:[2,8,6,7],built:[0,4,9],latest:[3,6,9],awesom:[2,6],show:[6,9],cheat:4,text:4,sent:5,aggregr:5,page:[10,0,4,1,2],syntax:[2,4,6,1],connect:6,bring:[4,6],directli:[5,3,6,9],raleigh:2,particularli:6,pkg:[3,6,9],hack:[2,5],radic:2,identifi:4,trivial:[2,3],find:[5,4,3],varnam:6,xml:1,absolut:3,onli:[0,3,4,5,6,9],explicitli:[3,6],locat:3,execut:[2,3,4,5,6,8],tire:4,transact:6,configur:[0,1,2,4,3,6,7,9],solut:4,figur:4,somefil:6,should:[5,4,3,1],suppos:[5,6],about:[0,1,2,3,4,5,6],local:3,yml:6,custom:[4,6],long_running_oper:9,nearli:[3,6,1],variou:[4,3,6],get:[0,1,2,4,5,6,9],financ:2,stop:[5,4,3,9],kind:[4,5],autom:[4,6],repo:[5,3,9],ssl:4,obviou:[2,5],ssh:[0,4,9,2],increas:6,grep:3,requir:[0,2,3,4,5,6],uvh:0,mdehaan:6,bar:[7,6],releas:[0,4],patch:4,sha:3,bad:5,stuff:9,common:[2,5,6,1],contain:[5,4,3,6],usabl:[2,6],through:[0,3,2],where:[2,5,4,3],wrote:5,view:[2,10],respond:6,set:[0,5,4,3,6],dump:5,hierachi:4,arbitari:1,see:[0,1,2,3,4,5,6,7,9,10],sec:6,result:[5,8,3,6],arg:5,fail:[8,4,5,6],close:5,charact:1,setsebool:6,best:[5,4,3,6],subject:6,asynchron:[2,6],statu:[5,6,9],still:4,extend:[2,4,6],expert:4,down:[8,6],databas:6,someth:[2,3,4,5,6,9],discoveri:3,restart:[4,3,6,9],state:[5,4,3,6,9],won:[6,9],between:[4,6],"import":[8,5,6],experi:4,across:4,attribut:3,altern:[6,9],solo:4,manpag:0,style:5,extens:[2,4],job:[9,1],entir:[4,5,6],aserv:0,webapp:[4,9],come:5,timmi:6,addit:[2,5,6],both:[4,5],delimit:3,goal:2,howev:[4,5],equal:[4,5],against:[2,4,6,7],etc:[0,2,4,3,6,7,9],tutori:[2,5],logic:6,mani:[5,6,9],com:[0,8,5,6,7],comment:5,among:4,assur:6,simpli:[3,6],author:2,can:[0,1,2,3,4,5,6,7,8,9],overview:1,format:[2,1,4,3,6,7,9],inspir:[2,4],chmod:[5,6],distil:4,fashion:4,colon:6,shutdown:3,linux:[2,4],written:[2,5,3,6,9],poll:[2,6,9],mission:2,quit:5,coupl:4,platform:4,multiplay:2,decent:5,ansible_library_path:5,three:7,been:[2,4],json:[2,1,3,4,5,8],much:[2,4,3,6,1],besid:5,treat:[4,5],basic:[0,1,2,3,4,5,6,7],futur:[0,5],quickli:[2,9],capistrano:[2,4],fire:[2,4,6],rubi:[5,4,3,9,1],convert:5,anywher:6,upgrad:[3,9],likes_emac:1,understand:5,togeth:6,func:[2,4],turn:5,atlanta:[6,9],educ:5,those:[4,3,6],"case":[4,5],authorized_kei:0,exception:4,look:[7,5,6,9],replac:[],hoc:[2,4,3,6,9],straight:9,md5sum:3,permit:[],batch:4,vars_fil:6,trick:[2,6],defin:6,"while":[4,6],match:[5,6],abov:[5,6,9],error:[4,5],cfengin:4,dehaan:2,layer:4,motd:[6,9],max_client:6,stdout:8,almost:[4,3],technolog:2,readm:5,site:[4,10],memcach:6,unit:5,dag:4,conf:[6,9],module_nam:8,somekei:5,ship:3,sever:[4,6,1],around:4,http_port:6,develop:[0,1,2,4,5,6],welcom:2,datetim:5,perform:4,make:[0,3,4,5,6,9],ohai:[2,4,3,6,9],cross:4,same:[7,6,1,9],member:1,handl:[4,5],complex:[2,4,6],split:5,document:[0,1,4,5,6,8,9],ansibl:[0,1,2,3,4,5,6,7,8,9,10],difficult:4,http:3,hostnam:[8,6],again:[4,5,6],nest:[5,3],painless:2,rail:4,effect:[],remot:[0,3,6,9],assign:[2,6],fruit:1,user:[2,4,3,6],extern:[2,6],engin:9,php:9,distutil:[0,2],typic:[4,9],tune:[],recent:4,dark:8,lower:[4,5],appropri:4,off:[2,4,6],scenario:3,mention:6,setenforc:6,compos:6,well:[0,4,3,6],hypothet:[],non:[2,5,6],without:[4,5],command:[0,2,3,4,5,6,7,8,9,10],thi:[0,1,3,4,5,6,7,9],choos:3,programm:[8,4],model:6,guidelin:5,dereferenc:6,usual:[],explan:5,protocol:3,prepar:5,just:[0,1,2,3,4,5,6,9],less:[0,4,2],when:[5,4,3,6,9],rest:10,detail:[2,8,9],kill:[],irc:2,human:1,heavili:4,shorthand:[2,5],skill:1,simultan:9,languag:[0,1,2,3,4,5,6,7],web:[8,4,6,10,9],versu:2,easi:[2,4,3,7],mix:[7,6],except:5,littl:[2,4],add:[0,4,9],valid:5,simplejson:[0,5],notori:4,els:[2,6],save:[5,6],hat:[2,4],app:4,smart:9,take:[5,4,3,6],real:0,applic:[8,4,6],march:5,which:[0,7,6,1,2],quirk:1,dest:[3,6,9],judgement:3,game:2,know:[5,4,3,1],background:[2,9],guid:[2,5,6],world:[0,4],bit:[4,3],password:[0,6],daemon:[2,4],motorola:2,like:[1,3,4,5,6,7,9],success:[5,3],header:7,signal:[4,6],arbitrari:4,manual:[4,6],integ:3,divers:2,remind:5,api:[8,2,5,4,3],necessari:[3,9],either:[4,3],lose:9,popular:2,async:[4,6],architectur:[2,4],manag:[0,1,2,3,4,5,6,7,9],poor:5,shed:4,drop:[5,3],often:4,deal:5,webserv:[7,6,9],suppli:3,some:[0,2,3,4,5,6],back:[4,6],dead:2,clojur:5,born:4,intern:5,heritag:4,server:[2,4,3,6,9],transport:[2,4],tmp:9,txt:3,forcibl:[],lead:4,bottom:6,rpm:[0,5,2],avoid:[0,4,3],though:[2,5,4,3,6],definit:6,thank:4,legal:5,tracker:2,larg:4,select:[2,3,6,7],foo:[7,6,9],complic:[2,4],refer:9,machin:[0,3,4,5,6,9],core:[2,4,5],encourag:4,yamllint:1,run:[0,1,3,4,5,6,8,9],power:[8,2,4,6],importerror:5,usag:[5,3,9],asciidoc:0,web2:8,vhost:6,step:[4,3,6],web1:8,promot:4,repositori:0,output:[4,5,6],meantim:4,appli:4,task:[2,4,6,9],soon:[],simpler:[4,9],continu:5,comparison:[2,4],sshd:2,simplest:5,central:4,othervar:[],acm:9,simul:6,srv:[6,9],messag:[8,4,5],done:[4,6],industri:2,disabl:6,block:6,ntp_server:9,own:[2,4,3,6],effici:[4,6],bounc:[3,6],within:[4,3],contriv:[],sneaker:[],automat:[5,3],due:[4,5],noth:[6,1],pair:[5,3,1],multinod:4,ensur:[4,6,9],chang:[5,3,6,9],pitfal:[2,5],next:6,bserver:0,your:[0,2,3,4,5,6,7,9],risk:6,per:8,stare:5,behind:[4,3],git:[0,2,3,4,5,9],fabric:[2,4],wai:[0,4,5,6,9],aren:4,transfer:[2,5,9],support:[2,4,3,6],rotat:6,fast:2,happi:2,verbos:[5,3],start:[0,1,2,4,3,6,9],trigger:[4,3,6],wordpress:6,includ:[2,5,3,6],lot:[2,5,9],suit:[4,6],"var":[2,6],datastructur:8,individu:7,fork:[8,4,6,9],head:[3,9],form:[5,6,1],enough:[7,4,9],lint:1,yeah:[],taken:[4,6],shorter:5,link:5,line:[0,1,2,3,4,5,6,7,8,9,10],"true":[5,3,1],freenod:2,info:9,pull:4,"throw":4,made:[5,4,3,9],input:[2,5],possibl:[7,5,6,9],whether:[8,4,5],checkout:[5,4,3],caller:3,maximum:6,until:[0,5,6],planet:2,record:1,below:6,stacktrac:5,limit:[2,6,9],rerun:6,otherwis:3,problem:[4,1],similar:[2,3,6],email:2,facter:[2,4,3,6,9],curv:[2,4],featur:[7,4,6],tasti:1,creat:[2,4],certain:[4,6],nobodi:5,parser:5,doesn:[2,6,1],repres:[6,1],strongli:4,cobbler:[2,4],file:[0,1,2,3,5,6,7,9],home:3,bob:6,exist:[2,6],check:[4,3,6,9],probabl:[4,5,6],echo:[0,6],denot:7,coder:4,googl:2,dbserver:[7,6],excel:[2,4],unnecessari:3,"default":[2,4,6,7],declar:6,librari:[5,1],varieti:[4,5],test:[0,5,4,3,2],assum:6,you:[0,1,2,3,4,5,6,7,9],runtim:6,node:[0,2,3,4,5,6,9],contend:4,sysadmin:4,intend:5,wildcard:7,fulli:3,sequenc:2,"class":[2,6],devop:2,push:[4,6],scale:[2,4],intent:[],log:[5,6],consid:5,sbin:[3,6,9],deferenc:[],gap:4,"60k":[2,4],stai:6,sphinx:0,faster:6,amp:0,directori:[5,3,6],accept:5,reliabl:4,itself:8,emerg:2,ignor:5,potenti:[],time:[0,1,2,3,4,5,6,7,9],far:[2,1],hello:0},objtypes:{},titles:["Downloads &amp; Getting Started","YAML Syntax","Introducing Ansible","Ansible Modules","Frequently Asked Questions","Module Development Guide","Playbooks","The Inventory File, Patterns, and Groups","Using the Python API","Command Line Examples","Man Pages"],objnames:{},filenames:["gettingstarted","YAMLSyntax","index","modules","faq","moduledev","playbooks","patterns","api","examples","man"]})
\ No newline at end of file