summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorTim Bielawa <tbielawa@redhat.com>2011-12-14 17:00:26 (GMT)
committerTim Bielawa <tbielawa@redhat.com>2011-12-15 23:01:05 (GMT)
commit8950e5b607860dfb44308bc0d39ee7a96df3e661 (patch)
tree6c1fe8d13af06f09683311ed8e5ad3135847d11c
parent5553e36cd05ee8bfdf95cdd9911b1d80c22c1ded (diff)
downloadTaboot-8950e5b607860dfb44308bc0d39ee7a96df3e661.zip
Taboot-8950e5b607860dfb44308bc0d39ee7a96df3e661.tar.gz
Taboot-8950e5b607860dfb44308bc0d39ee7a96df3e661.tar.xz
Docs
-rw-r--r--docs/conf.py2
-rw-r--r--docs/man/man5/taboot-tasks.57
-rw-r--r--docs/man/man5/taboot-tasks.5.asciidoc3
-rw-r--r--docs/rst/YAMLScripts.rst2
-rw-r--r--docs/rst/development.rst5
-rw-r--r--docs/rst/exampleoutput/htmloutput.html92
-rw-r--r--docs/rst/gettingstarted.rst408
-rw-r--r--docs/rst/index.rst6
-rw-r--r--docs/rst/man.rst2
-rw-r--r--docs/rst/tasks/nagios.rst4
-rw-r--r--docs/rst/tasks/puppet.rst2
-rw-r--r--docs/rst/tasks/rpm.rst4
-rw-r--r--docs/rst/tasks/yum.rst2
-rw-r--r--docs/rst/troubleshooting.rst3
-rw-r--r--taboot/output.py9
15 files changed, 493 insertions, 58 deletions
diff --git a/docs/conf.py b/docs/conf.py
index 4674364..89df71d 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -32,7 +32,7 @@ from taboot import __version__, __author__
# Add any Sphinx extension module names here, as strings.
# They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['.templates']
diff --git a/docs/man/man5/taboot-tasks.5 b/docs/man/man5/taboot-tasks.5
index 148e19c..2bbc7cd 100644
--- a/docs/man/man5/taboot-tasks.5
+++ b/docs/man/man5/taboot-tasks.5
@@ -2,12 +2,12 @@
.\" Title: taboot-tasks
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
-.\" Date: 12/08/2011
+.\" Date: 12/14/2011
.\" Manual: Taboot
.\" Source: Taboot 0.4.x
.\" Language: English
.\"
-.TH "TABOOT\-TASKS" "5" "12/08/2011" "Taboot 0\&.4\&.x" "Taboot"
+.TH "TABOOT\-TASKS" "5" "12/14/2011" "Taboot 0\&.4\&.x" "Taboot"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
@@ -49,7 +49,8 @@ The \fIoutput\fR block lets you choose zero or more methods to log the taboot ru
output:
# CLIOutput is the default
\- CLIOutput
- # You can also log to a file, \*(Aqtaboot\&.log\*(Aq is the default name
+ # You can also log to a file, \*(Aqtaboot\-YYYY\-MM\-DD\-HHMMSS\&.log\*(Aq is
+ # the default format
\- LogOutput
# The \*(Aqlogfile\*(Aq keyword lets you choose a different name
\- LogOutput: {logfile: update\-httpd\&.log}
diff --git a/docs/man/man5/taboot-tasks.5.asciidoc b/docs/man/man5/taboot-tasks.5.asciidoc
index b907403..76087fb 100644
--- a/docs/man/man5/taboot-tasks.5.asciidoc
+++ b/docs/man/man5/taboot-tasks.5.asciidoc
@@ -44,7 +44,8 @@ documentation to learn how to set system-wide defaults for the
output:
# CLIOutput is the default
- CLIOutput
- # You can also log to a file, 'taboot.log' is the default name
+ # You can also log to a file, 'taboot-YYYY-MM-DD-HHMMSS.log' is
+ # the default format
- LogOutput
# The 'logfile' keyword lets you choose a different name
- LogOutput: {logfile: update-httpd.log}
diff --git a/docs/rst/YAMLScripts.rst b/docs/rst/YAMLScripts.rst
index e7f6247..1037b2e 100644
--- a/docs/rst/YAMLScripts.rst
+++ b/docs/rst/YAMLScripts.rst
@@ -17,7 +17,7 @@ For `taboot`, every YAML script must be a list at it's root-most
element. Each item in the list is a dictionary. These dictionaries
represent all the options you can use to write a `taboot` script. In
addition, all YAML files (regardless of their association with
-`taboot` or not) should start with ```---```.
+`taboot` or not) should start with ``---``.
In YAML a list can be represented in two ways. In one way all members
of a list are lines beginning at the same indentation level starting
diff --git a/docs/rst/development.rst b/docs/rst/development.rst
index 8fd6441..fc2e7e6 100644
--- a/docs/rst/development.rst
+++ b/docs/rst/development.rst
@@ -16,9 +16,14 @@ Required Tools
#. `Func <https://fedorahosted.org/func/>`_ - The Fedora Unified Network Controller
#. `an <http://www.vim.org>`_ `editor <http://www.gnu.org/software/emacs/>`_ or `ide <http://pida.co.uk/>`_ `that <http://scribes.sourceforge.net/>`_ doesn't suck
+
+
Optional Tools
``````````````
+These should be available via your package manager:
+
#. `rpm-build <http://www.rpm.org/max-rpm-snapshot/rpmbuild.8.html>`_ - Should be packaged in your RPM distribution
+ #. `pep8 <https://github.com/jcrocholl/pep8>`_ - Check your patches for pep8 compliance with ``make pep8``
Source
diff --git a/docs/rst/exampleoutput/htmloutput.html b/docs/rst/exampleoutput/htmloutput.html
new file mode 100644
index 0000000..68dc8ae
--- /dev/null
+++ b/docs/rst/exampleoutput/htmloutput.html
@@ -0,0 +1,92 @@
+<p><tt><a name='1068718107623486553' href='#1068718107623486553'><b><font color='#0000FF'><tt>www01.ext.friendfrobber.com</tt></font></b></a>:</tt></p>
+<p><tt>2011-12-09 11:00:17 Starting Task[taboot.tasks.command.Run('echo "oh hi"',)]
+</tt><p><tt><b><font color='#0000FF'><tt>www01.ext.friendfrobber.com</tt></font></b>:
+</tt></p>
+<p><tt>2011-12-09 11:00:20 Finished Task[taboot.tasks.command.Run('echo "oh hi"',)]: <font color='#008000'><tt><b>OK</b></tt></font></tt></p>
+<pre>oh hi</pre>
+<br /><br />
+<p><tt><a name='1068718107620486550' href='#1068718107620486550'><b><font color='#0000FF'><tt>www01.ext.friendfrobber.com</tt></font></b></a>:</tt></p>
+<p><tt>2011-12-09 11:00:21 Starting Task[taboot.tasks.rpm.PreManifest('rpm -qa | sort',)]
+</tt><p><tt><b><font color='#0000FF'><tt>www01.ext.friendfrobber.com</tt></font></b>:
+</tt></p>
+<p><tt>2011-12-09 11:00:25 Finished Task[taboot.tasks.rpm.PreManifest('rpm -qa | sort',)]: <font color='#008000'><tt><b>OK</b></tt></font></tt></p>
+<pre></pre>
+<br /><br />
+<p><tt><a name='1068718107620486546' href='#1068718107620486546'><b><font color='#0000FF'><tt>www01.ext.friendfrobber.com</tt></font></b></a>:</tt></p>
+<p><tt>2011-12-09 11:00:25 Starting Task[taboot.tasks.puppet.Run('puppetd --test --color=false || true',)]
+</tt><p><tt><b><font color='#0000FF'><tt>www01.ext.friendfrobber.com</tt></font></b>:
+</tt></p>
+<p><tt>2011-12-09 11:00:28 Finished Task[taboot.tasks.puppet.Run('puppetd --test --color=false || true',)]: <font color='#008000'><tt><b>OK</b></tt></font></tt></p>
+<font color='#FF0000'><tt>err: Could not request certificate: getaddrinfo: Name or service not known</tt></font><br />
+<font color='#000000'><tt>Exiting; failed to retrieve certificate and waitforcert is disabled</tt></font><br />
+<br /><br />
+<p><tt><a name='1068718107620486559' href='#1068718107620486559'><b><font color='#0000FF'><tt>www01.ext.friendfrobber.com</tt></font></b></a>:</tt></p>
+<p><tt>2011-12-09 11:00:28 Starting Task[taboot.tasks.yum.Update('yum update -y ',)]
+</tt><p><tt><b><font color='#0000FF'><tt>www01.ext.friendfrobber.com</tt></font></b>:
+</tt></p>
+<p><tt>2011-12-09 11:00:32 Finished Task[taboot.tasks.yum.Update('yum update -y ',)]: <font color='#008000'><tt><b>OK</b></tt></font></tt></p>
+<pre>Loaded plugins: langpacks, presto, refresh-packagekit
+Adding en_US to language list
+Setting up Update Process
+No Packages marked for Update</pre>
+<br /><br />
+<p><tt><a name='1068718107621486550' href='#1068718107621486550'><b><font color='#0000FF'><tt>www01.ext.friendfrobber.com</tt></font></b></a>:</tt></p>
+<p><tt>2011-12-09 11:00:32 Starting Task[taboot.tasks.command.Run('/bin/false || true',)]
+</tt><p><tt><b><font color='#0000FF'><tt>www01.ext.friendfrobber.com</tt></font></b>:
+</tt></p>
+<p><tt>2011-12-09 11:00:34 Finished Task[taboot.tasks.command.Run('/bin/false || true',)]: <font color='#008000'><tt><b>OK</b></tt></font></tt></p>
+<pre></pre>
+<br /><br />
+<p><tt><a name='1068718107621486544' href='#1068718107621486544'><b><font color='#0000FF'><tt>www01.ext.friendfrobber.com</tt></font></b></a>:</tt></p>
+<p><tt>2011-12-09 11:00:34 Starting Task[taboot.tasks.yum.Remove('yum remove -y trang',)]
+</tt><p><tt><b><font color='#0000FF'><tt>www01.ext.friendfrobber.com</tt></font></b>:
+</tt></p>
+<p><tt>2011-12-09 11:00:41 Finished Task[taboot.tasks.yum.Remove('yum remove -y trang',)]: <font color='#008000'><tt><b>OK</b></tt></font></tt></p>
+<pre>Loaded plugins: langpacks, presto, refresh-packagekit
+Adding en_US to language list
+Setting up Remove Process
+Resolving Dependencies
+--&gt; Running transaction check
+---&gt; Package trang.noarch 0:20091111-7.fc14 set to be erased
+--&gt; Finished Dependency Resolution
+
+Dependencies Resolved
+
+================================================================================
+ Package Arch Version Repository Size
+================================================================================
+Removing:
+ trang noarch 20091111-7.fc14 @updates 835 k
+
+Transaction Summary
+================================================================================
+Remove 1 Package(s)
+
+Installed size: 835 k
+Downloading Packages:
+Running rpm_check_debug
+Running Transaction Test
+Transaction Test Succeeded
+Running Transaction
+
+ Erasing : trang-20091111-7.fc14.noarch 1/1
+
+Removed:
+ trang.noarch 0:20091111-7.fc14
+
+Complete!</pre>
+<br /><br />
+<p><tt><a name='1068718107618486540' href='#1068718107618486540'><b><font color='#0000FF'><tt>www01.ext.friendfrobber.com</tt></font></b></a>:</tt></p>
+<p><tt>2011-12-09 11:00:41 Starting Task[taboot.tasks.command.Run('echo "I just got excited because this is still running!"',)]
+</tt><p><tt><b><font color='#0000FF'><tt>www01.ext.friendfrobber.com</tt></font></b>:
+</tt></p>
+<p><tt>2011-12-09 11:00:44 Finished Task[taboot.tasks.command.Run('echo "I just got excited because this is still running!"',)]: <font color='#008000'><tt><b>OK</b></tt></font></tt></p>
+<pre>I just got excited because this is still running!</pre>
+<br /><br />
+<p><tt><a name='1068718107618486537' href='#1068718107618486537'><b><font color='#0000FF'><tt>www01.ext.friendfrobber.com</tt></font></b></a>:</tt></p>
+<p><tt>2011-12-09 11:00:44 Starting Task[taboot.tasks.rpm.PostManifest('rpm -qa | sort',)]
+</tt><p><tt><b><font color='#0000FF'><tt>www01.ext.friendfrobber.com</tt></font></b>:
+</tt></p>
+<p><tt>2011-12-09 11:00:47 Finished Task[taboot.tasks.rpm.PostManifest('rpm -qa | sort',)]: <font color='#008000'><tt><b>OK</b></tt></font></tt></p>
+<font color='#FF0000'><tt>- trang-20091111-7.fc14.noarch</tt></font><br />
+<br /><br />
diff --git a/docs/rst/gettingstarted.rst b/docs/rst/gettingstarted.rst
index f37e562..e5c93ce 100644
--- a/docs/rst/gettingstarted.rst
+++ b/docs/rst/gettingstarted.rst
@@ -17,7 +17,7 @@ A Func Infrastructure
`````````````````````
A working `Func installation <http://fedorahosted.org/func>`_ is
-requried. Func is the system over which Taboot executes all of it's
+required. Func is the system over which Taboot executes all of it's
commands. It's comparable to the cell phone network you would have a
conversation over.
@@ -34,7 +34,7 @@ A Repetitive Task
Taboot is ideal for scripting a task that needs to happen over and
over again. An example of this is a software release script, or a
-maintenance script for rolling updates to a cluster.
+maintenance script for rolling updates to a cluster.
@@ -64,7 +64,7 @@ goes a long way when debugging the inevitable syntax error.
Complete documentation of the YAML syntax `taboot` understands.
:ref:`tasks`
- Documentation for each of the built-in tasks `taboot` provides.
+ Documentation for each of the built-in tasks `taboot` provides.
Writing Your First Script
@@ -76,7 +76,7 @@ Concepts Covered
Lets get started and write a Taboot script. This example will build up
to a script that performs a rolling update of a web server cluster in
-our fictitious domain: ``foobar.com``. When complete it will
+our fictitious domain: ``friendfrobber.com``. When complete it will
demonstrate:
* Using `globbing` to select hosts
@@ -88,22 +88,48 @@ demonstrate:
* Showing a summary of all changed RPMs
-Hosts in foobar.com
-```````````````````
+The FriendFrobber.com Infrastructure
+````````````````````````````````````
-Our webservers will consist of the following:
+ **MegaFrobber**: `Reach out and Frob some one!` ™
-* ``www01.ext.foobar.com``
-* ``www02.ext.foobar.com``
-* ``www11.ext.foobar.com``
-* ``www12.ext.foobar.com``
+You are a sysadmin for `FriendFrobber.com`, makers of the widely
+popular social networking service `MegaFrobber`. As such, you are
+responsible for maintaining the application servers in their
+high-availability web cluster. Part of that responsibility includes
+releasing updates to the server component of `MegaFrobber`. These are
+your hosts:
-There is also a Nagios server:
+* ``www01.ext.friendfrobber.com``
+* ``www02.ext.friendfrobber.com``
+* ``www11.ext.friendfrobber.com``
+* ``www12.ext.friendfrobber.com``
-* ``nagios.int.foobar.com``
+For the sake of simplicity we're going to assume that the wizards in
+networking have taken care of all the load balancing to the webserver
+pool. To further simplify things, unhealthy nodes are removed from
+service automatically (thanks networking!).
-On the Nagios server each webserver is monitored with an ``http``
-check.
+Also living in the `FriendFrobber.com` domain is a monitoring server
+with Nagios installed. This server watches the ``wwwXX`` hosts and
+pages the sysadmin team if it notices any webserver isn't responsing
+to requests.
+
+* ``monitor.util.friendfrobber.com``
+
+``monitor`` has the `Func` Nagios Server plugin installed so that
+downtime can be handled remotely.
+
+Finally there is your administration center:
+
+* ``overlord.util.friendfrobber.com``
+
+``overord`` is the command center on which you store and run your
+Taboot scripts.
+
+.. seealso::
+
+ * `Nagios <http://www.nagios.com>`_ - `The Industry Standard in IT Infrastructure Monitoring`
Script Elements
@@ -123,19 +149,59 @@ called an `element` (see: :ref:`elements`).
The only required elements are ``hosts`` and ``tasks``. The rest
are optional or have sane defaults.
+The data of the ``hosts`` element is a list. Each item in the list is
+a hostname, or a glob that can be expanded into a hostname. When
+Taboot executes your script it will iterate over each host represented
+in this list.
+
+.. versionchanged:: 0.4.0
+ Prior to this version the order that hosts appeared in this list
+ was not guaranteed to be representative of the actual order of
+ execution.
+
+ From version 0.4.0 onward Taboot implements **strict ordering** and
+ (except for expanded globs) guarantees that the order of execution
+ will match the order of definition.
+
+The ``concurrency`` element specifies how many hosts Taboot will run a
+script against at a single time.
+
+The ``output`` element allows you to mix and match exactly which
+logging mechanisms to process the scripts output with.
+
+The ``preflight`` and ``tasks`` elements define sequences of actions
+to perform for each host. The ``preflight`` sequence is ran at maximum
+concurrency before the main ``tasks`` body is executed. When
+completed, script execution prompts for input before continuing.
+
+These sequences are composed of items called `tasks`. Each task
+represents an action or step to be repeated for each host. These
+actions are things like restarting a service, deleting files,
+installing packages, or disabling a member in a load balancing pool.
+
+Some tasks, like ``service.Restart``, take arguments which are
+represented as hashes or "key-value pairs" in YAML. Some tasks, like
+``puppet.Run`` require no arguments at all. Other may have arguments
+that are entirely optional.
+
+
+.. seealso::
+
+ * :ref:`Taboot Tasks stdlib <tasks>`
+
Updating Just One Host
``````````````````````
Lets start simple and do a yum update on one webserver,
-``www01.ext.foobar.com``. In the ``hosts`` element we specify a list
+``www01.ext.friendfrobber.com``. In the ``hosts`` element we specify a list
with just one item (our web server) and in our tasks element we use
the ``yum.Update`` task::
# www01-yum-update.yaml
---
- - hosts: [www01.ext.foobar.com]
+ - hosts: [www01.ext.friendfrobber.com]
tasks:
- yum.Update
@@ -150,8 +216,8 @@ the output only updates once a task finishes.
.. seealso::
- :ref:`hosts`
- Main ``hosts`` documentation
+ * :ref:`hosts` - Complete ``hosts`` documentation
+ * :ref:`yum` - Complete ``yum`` task documentation
Output
@@ -160,10 +226,10 @@ Output
You should see a screen similar to this when it finishes::
- [root@griddle ~]# taboot www01-yum-update.yaml
- www01.ext.foobar.com:
+ [root@overlord.util.friendfrobber.com ~]# taboot www01-yum-update.yaml
+ www01.ext.friendfrobber.com:
2011-12-13 17:32:38 Starting Task[taboot.tasks.yum.Update('yum update -y ',)]
- www01.ext.foobar.com:
+ www01.ext.friendfrobber.com:
2011-12-13 17:36:11 Finished Task[taboot.tasks.yum.Update('yum update -y ',)]:
Loaded plugins: langpacks, presto, refresh-packagekit
Adding en_US to language list
@@ -176,9 +242,9 @@ You should see a screen similar to this when it finishes::
---> Package tito.noarch 0:0.4.0-1.fc14 set to be updated
---> Package ypbind.x86_64 3:1.32-3.fc14 set to be updated
--> Finished Dependency Resolution
-
+
Dependencies Resolved
-
+
================================================================================
Package Arch Version Repository Size
================================================================================
@@ -188,11 +254,11 @@ You should see a screen similar to this when it finishes::
parted x86_64 2.3-5.fc14 updates 632 k
tito noarch 0.4.0-1.fc14 updates 100 k
ypbind x86_64 3:1.32-3.fc14 updates 56 k
-
+
Transaction Summary
================================================================================
Upgrade 5 Package(s)
-
+
Total download size: 1.7 M
Downloading Packages:
Setting up and reading Presto delta metadata
@@ -204,7 +270,7 @@ You should see a screen similar to this when it finishes::
Running Transaction Test
Transaction Test Succeeded
Running Transaction
-
+
Updating : 3:ypbind-1.32-3.fc14.x86_64 1/10
Updating : parted-2.3-5.fc14.x86_64 2/10
Updating : lftp-4.3.3-1.fc14.x86_64 3/10
@@ -215,12 +281,12 @@ You should see a screen similar to this when it finishes::
Cleanup : lftp-4.0.9-3.fc14.x86_64 8/10
Cleanup : tito-0.3.2-1.fc14.noarch 9/10
Cleanup : mock-1.1.17-1.fc14.noarch 10/10
-
+
Updated:
lftp.x86_64 0:4.3.3-1.fc14 mock.noarch 0:1.1.18-1.fc14
parted.x86_64 0:2.3-5.fc14 tito.noarch 0:0.4.0-1.fc14
ypbind.x86_64 3:1.32-3.fc14
-
+
Complete!
@@ -228,7 +294,7 @@ RPM Pre/Post Manifest
`````````````````````
Two more bundled tasks are the RPM ``PreManifest`` and
-``PostManifest`` tasks. The ``PostManifest`` task is used (it
+``PostManifest`` tasks. The ``PostManifest`` task is used (in
conjunction with the ``PreManifest`` task) to show you a summary of
the changes to your installed packages. This is especially useful for
verification in systems where an update should only upgrade/install
@@ -236,7 +302,7 @@ specific packages::
# package-install.yaml
---
- - hosts: [griddle]
+ - hosts: [www0*]
tasks:
- rpm.PreManifest
@@ -245,9 +311,10 @@ specific packages::
- rpm.PostManifest
+.. seealso::
-
-
+ * :ref:`rpm` - Complete ``rpm`` task documentation
+ * :ref:`examplepostmanifest`
Updating Multiple Hosts
@@ -258,16 +325,27 @@ additional hosts in a few ways. We could enumerate each host::
# www-yum-update.yaml
---
- - hosts: [www01.ext.foobar.com,www02.ext.foobar.com,www11.ext.foobar.com,www12.ext.foobar.com]
+ - hosts: [www01.ext.friendfrobber.com,www02.ext.friendfrobber.com,www11.ext.friendfrobber.com,www12.ext.friendfrobber.com]
tasks:
- yum.Update
+ # Again, but demonstrating the alternative YAML syntax for list items
+ ---
+ - hosts:
+ - www01.ext.friendfrobber.com
+ - www02.ext.friendfrobber.com
+ - www11.ext.friendfrobber.com
+ - www12.ext.friendfrobber.com
+ tasks:
+ - yum.Update
+
+
Or we could use `globbing`, a technique where you give part of a name
and the rest is filled in automatically::
# www-yum-update.yaml
---
- - hosts: [www*.ext.foobar.com]
+ - hosts: [www*.ext.friendfrobber.com]
tasks:
- yum.Update
@@ -279,7 +357,7 @@ and the rest is filled in automatically::
.. seealso::
- `Func Glob Documentation <https://fedorahosted.org/func/wiki/CommandLineGlobbing>`_
+ * `Func Glob Documentation <https://fedorahosted.org/func/wiki/CommandLineGlobbing>`_
Concurrency: Multiple Updates At Once
@@ -302,7 +380,7 @@ Concurrency can be permanently set in your Taboot scripts via the
# www-yum-update-concurrent.yaml
---
- - hosts: [www*.ext.foobar.com]
+ - hosts: [www*.ext.friendfrobber.com]
concurrency: 2
tasks:
- yum.Update
@@ -312,19 +390,263 @@ Concurrency can be permanently set in your Taboot scripts via the
Via Command Line
++++++++++++++++
-Concurrency can also be specified or overridden via command line::
+Additionally, concurrency may be specified or overridden via command
+line with the ``-C`` parameter::
$ taboot -C 2 www-yum-update.yaml
-Advanced Logging Techniques
-```````````````````````````
+Conncurrencies "Gotcha"
++++++++++++++++++++++++
+One "gotcha" when running with ``concurrency`` > 1 is that logs are
+not guaranteed to maintain any logical ordering. This is because we
+have multiple threads of execution happening in parallel. In this
+situation there will be tasks entering and exiting at different times
+based on when they originally started and how long they took to run.
+
+The result is, for example, the log the messages for a script running
+on ``www01`` becoming interleaved with the logs for a script running
+on ``www02`` at the same time.
-The Preflight Element
-`````````````````````
-Scheduling Downtime In Nagios
+Additional Logging Techniques
`````````````````````````````
+By default Taboot just prints progress on your console. This
+``output`` type is called ``CLIOutput``. Some other types available
+for formatting results are:
+
+* ``LogOutput`` - Logs to a plain text file
+* ``HTMLOutput`` - Creates a colored HTML file with anchors
+
+You aren't limited to just one! Taboot can log to multiple logging
+systems at the same time.
+
+.. seealso::
+
+ * :ref:`output` - Complete ``output`` documentation
+
+
+Logging To a Text File
+++++++++++++++++++++++
+
+Logging to a text file is another thing that can be controlled from
+the command line at run-time. To add text file logging at run-time you
+can use the :option:`-L` option. The default file name is formatted with a
+timestamp (``taboot-YYYY-MM-DD-HHMMSS.log``).
+
+It's called in one of two ways:
+
+#. By itself (uses default ``LOGFILE`` value) ::
+
+ $ taboot -L www-frobnicate.yaml
+
+#. With the ``LOGFILE`` option ::
+
+ $ taboot -L megafrobber.log www-frobnicate.yaml
+
+
+Logging to HTML
++++++++++++++++
+
+``HTMLOutput`` is another available logging mechanism. Unlike the
+``LogOutput`` type, ``HTMLOutput`` does not support any command line
+options. However, it does have a system available for saving its
+configuration in a configuration file.
+
+
+``HTMLOutput`` is formatted using colors. Each task result is
+formatted with an HTML anchor, allowing you to directly link to that
+result.
+
+Some tasks are ``HTMLOutput`` aware and will produce enhanced output
+with extra styling. For example the ``rpm.PostManifest`` task will
+color deletions in red and additions in green. ``puppet.Run`` will
+colorize messages by severity. For instance, **err** messages are red,
+**warning** messages are yellow, and **info** messages are in
+green. ::
+
+ # www-yum-update.yaml
+ ---
+ - hosts: [www*.ext.friendfrobber.com]
+ output:
+ - CLIOutput
+ - HTMLOutput
+ tasks:
+ - yum.Update
+
+.. important::
+
+ Keep in mind that if you define the ``output`` element in your
+ Taboot script then you must specify **every** logging mechanism you
+ want to use. That includes defining the ``CLIOutput`` type!
+
+
+.. seealso::
+
+ * :ref:`html-output` - Complete ``HTMLOutput`` documentation
+ * Source code for :py:meth:`taboot.output.HTMLOutput._write`
+ * :download:`Example HTMLOutput <exampleoutput/htmloutput.html>`
+
+Complete Example
+----------------
+
+.. note::
+
+ This final section will combine everything described above into a
+ realistic example suitable for the real world. It will also
+ introduce the ``nagios`` task.
+
+The ``preflight`` element allows you to execute a set of tasks against
+all of the nodes concurrently. Before execution continues into the
+main ``tasks`` body you are prompted to continue. This is especially
+useful for giving you time to run or finish any preparation steps that
+are required before you start running a script.
+
+For example, a common infrastructure configuration would use Nagios
+for host monitoring and ``Puppet`` + ``git`` for configuration
+management.
+
+A typical release, or *rolling upgrade*, has steps that include:
+scheduling downtime for each affected service (on each host) in
+Nagios. To prevent early-updates, before you commit your puppet
+changes to git you would likely disable the puppet agent on all of the
+target nodes. This might also be where you promote new RPMs into your
+production yum mirror as well.
+
+The ``preflight`` element was built to automate this exact
+workflow. Lets see how that would look implemented as a Taboot script
+using the hosts described earlier in this document. ::
+
+
+ # www-rolling-update.yaml
+ ---
+ - hosts: [www*.ext.friendfrobber.com]
+ output: [CLIOutput, HTMLOutput]
+ preflight:
+ - puppet.Disable
+ - nagios.ScheduleDowntime:
+ nagios_url: monitor.util.friendfrobber.com
+ minutes: 10
+ service: http
+
+ tasks:
+ - rpm.PreManifest
+
+ - service.Stop: {service: httpd}
+
+ # Puppet handles our system configuration,
+ # so, no need for yum here.
+ - puppet.Enable
+ - puppet.Run
+
+ - rpm.PostManifest
+
+
+Lets highlight what's happening here
+
+#. We're using a glob in the ``hosts`` element to target all of our
+ web servers
+
+#. Our ``preflight`` disables puppet and schedules 10 minutes of
+ downtime for the ``http`` service on our Nagios server
+
+#. After the preflight finishes all execution stops and we are
+ prompted to continue::
+
+ Pre-Flight complete, press enter to continue:
+
+#. At this point we would commit, push all puppet code changes into
+ git, promote our new RPMs, and then continue the release
+
+#. A manifest of installed RPMs is taken on the target node
+
+#. Apache HTTPD is stopped
+
+#. We re-enable puppet and then force a manual catalog run
+
+#. A manifest of the installed RPMs is taken and the diff is displayed
+ against the manifest from the ``PreManifest`` so we can verify our
+ intended changes landed
+
+
+When it comes time to run this we decide to alter the described work
+flow a little bit. We'll add the ``LogOutput`` type, so we have
+something to send to our boss later. Because we're running late to the
+Wednesday IT meetup at the local watering hole we elect to skip the
+pre-flight too. (Ouch, no Nagios downtime? Our co-workers are going to
+hate us for that later) We're also going to run this against
+everything at once (who needs rolling-updates anyway?) ::
+
+ $ taboot -sC 4 -L new-megafrobber-update.log www-rolling-update.yaml && \
+ mail -s "Megafrobber release logs for `date`" \
+ pointy-haired-boss@friendfrobber.com < www-rolling-update.yaml
+
+.. seealso::
+
+ * :ref:`nagios` - Complete ``nagios`` task documentation
+ * :ref:`puppet` - Complete ``puppet`` task documentation
+ * `Puppet <http://puppetlabs.com/>`_ - System Configuration Management
+
+
+More Command Line Features
+--------------------------
+
+The ``taboot`` command offers additional features not described above.
+
+.. option:: -p, --printonly
+.. option:: -n, --checkonly
+
+ The :option:`-n` and :option:`-p` options are very similar. The
+ former loads a script and does basic syntax validation. The latter
+ also validates, as well as prints out the optimized YAML.
+
+ The :option:`-n` and :option:`-p` options occur late in the parsing
+ sequence. Therefore they both are able to validate the result of
+ any edits made with :option:`-E` or with :option:`-L`.
+
+ Taboots document validation catches basic script errors.
+
+ Dispite it's best attempts, validation isn't accurate 100% of the
+ time when describing illegal syntax. Note however, it will never
+ throw a false positive either. t's 100% better than a stack
+ trace in the middle of a release.
+
+
+.. option:: -E, --edit
+
+ :option:`-E` opens an editor and lets you make quick one-off edits
+ to a script. Great if you need to make a temporary change without
+ having to first make a copy of the source script.
+
+
+.. option:: -L [LOGFILE], --logfile [LOGFILE]
+
+ Adds ``LogOutput`` to the ``output`` element. The default file name
+ is formatted with a timestamp
+ (``taboot-YYYY-MM-DD-HHMMSS.log``). You can specify an alternative
+ log file name by specifying ``LOGFILE`` after giving the
+ :option:`-L` flag.
+
+
+.. option:: -s, --skippreflight
+
+ The :option:`-s` option allows you to skip all ``preflight``
+ elements.
+
+
+.. option:: -C [CONCURRENCY], --concurrency [CONCURRENCY]
+
+ Allows you to change the concurrency at run-time. Give the
+ :option:`-C` option followed by the desired level of concurrency
+ (as an integer).
+
+
+.. seealso::
+
+ * :ref:`man` - The :manpage:`taboot(1)` man page. For
+ quick-reference there is also a :manpage:`taboot-tasks(5)` man
+ page which describes the syntax and provides examples of each
+ built-in task as well as the different ``output`` types.
diff --git a/docs/rst/index.rst b/docs/rst/index.rst
index add391e..b3dc008 100644
--- a/docs/rst/index.rst
+++ b/docs/rst/index.rst
@@ -2,8 +2,8 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
-Welcome to Taboot's documentation!
-====================================
+Documentation for Taboot!
+=========================
Contents:
@@ -18,8 +18,6 @@ Contents:
development
code
man
- troubleshooting
-
Indices and tables
==================
diff --git a/docs/rst/man.rst b/docs/rst/man.rst
index 8debcec..8a6e966 100644
--- a/docs/rst/man.rst
+++ b/docs/rst/man.rst
@@ -1,3 +1,5 @@
+.. _man:
+
Man Pages
=========
diff --git a/docs/rst/tasks/nagios.rst b/docs/rst/tasks/nagios.rst
index 2b7a691..6e65e82 100644
--- a/docs/rst/tasks/nagios.rst
+++ b/docs/rst/tasks/nagios.rst
@@ -1,3 +1,5 @@
+.. _nagios:
+
Nagios
^^^^^^
@@ -232,7 +234,7 @@ UnsilenceHost
* API: :class:`taboot.tasks.nagios.UnsilenceHost`
* Keys
-p * ``nagios_url``
+ * ``nagios_url``
* Type: String
* Default: None
diff --git a/docs/rst/tasks/puppet.rst b/docs/rst/tasks/puppet.rst
index f97d77d..d1b6060 100644
--- a/docs/rst/tasks/puppet.rst
+++ b/docs/rst/tasks/puppet.rst
@@ -1,3 +1,5 @@
+.. _puppet:
+
Puppet
^^^^^^
diff --git a/docs/rst/tasks/rpm.rst b/docs/rst/tasks/rpm.rst
index 8be6bf8..f7c4369 100644
--- a/docs/rst/tasks/rpm.rst
+++ b/docs/rst/tasks/rpm.rst
@@ -1,3 +1,5 @@
+.. _rpm:
+
RPM
^^^
@@ -82,6 +84,8 @@ Example::
- rpm.PostManifest
+.. _examplepostmanifest:
+
Example PostManifest Output
***************************
diff --git a/docs/rst/tasks/yum.rst b/docs/rst/tasks/yum.rst
index e2f8e34..31e3fae 100644
--- a/docs/rst/tasks/yum.rst
+++ b/docs/rst/tasks/yum.rst
@@ -1,3 +1,5 @@
+.. _yum:
+
Yum
^^^
diff --git a/docs/rst/troubleshooting.rst b/docs/rst/troubleshooting.rst
deleted file mode 100644
index 3440ba1..0000000
--- a/docs/rst/troubleshooting.rst
+++ /dev/null
@@ -1,3 +0,0 @@
-Troubleshooting
-===============
-
diff --git a/taboot/output.py b/taboot/output.py
index 3feed6d..e6cd702 100644
--- a/taboot/output.py
+++ b/taboot/output.py
@@ -354,6 +354,9 @@ class HTMLOutput(_FileLikeOutputObject):
"""
Output a :class:`taboot.tasks.TaskResult` to the command line
with pretty formatting and colors.
+
+ .. document private functions
+ .. automethod:: _write
"""
logfile_path = None
@@ -448,7 +451,11 @@ class HTMLOutput(_FileLikeOutputObject):
def _write(self, result):
"""
- DO IT!
+ Write a tasks `result` out to HTML. Handles enhanced stylizing
+ for task results that support such as:
+
+ - :py:mod:`taboot.tasks.puppet.PuppetTaskResult`
+ - :py:mod:`taboot.tasks.rpm.RPMTaskResult`
"""
import types
import sys