doc: Add Probes plugin documentation for ticket #829

Signed-off-by: Sol Jerome <solj@ices.utexas.edu>

git-svn-id: https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2@5668 ce84e21b-d406-0410-9b95-82705330c041

1 files changed, 100 insertions, 0 deletions

diff --git a/doc/plugins/probes.txt b/doc/plugins/probes.txt
index 62dab61e7..b6b69d754 100644
--- a/doc/plugins/probes.txt
+++ b/doc/plugins/probes.txt
@@ -3,3 +3,103 @@
 ======
 Probes
 ======
+
+At times you need to gather information from a client machine before you can generate its configuration.  For example, if some of your machines have both a local scratch disk and a system disk while others only have the system disk, you would want to know this information to correctly generate an `/etc/auto.master` autofs config file for each type.  Here we will look at how to do this.
+
+First you will need to set up the TCheetah plugin, as described on the [wiki:Plugins/TCheetah TCheetah Plugin] page.
+
+Next, we need to create a `Probes` directory in our toplevel repository location::
+
+    mkdir /var/lib/bcfg2/Probes
+
+This directory will hold any small scripts we want to use to grab information from client machines.  These scripts can be in any scripting language; the shebang line (the `#!/usr/bin/env some_interpreter_binary` line at the very top of the script) is used to determine the script's interpreter.
+
+.. note::
+
+    Bcfg2 uses python mkstemp to create the Probe scripts on the client. If your /tmp directory is mounted **noexec**, you will likely need to modify the TMPDIR so that the bcfg2 client creates the temporary files in a directory from which it can execute.
+
+Now we need to figure out what exactly we want to do.  In this case, we want to hand out an `/etc/auto.master` file that looks like::
+
+    /software  /etc/auto.software --timeout 3600
+    /home      /etc/auto.home --timeout 3600
+    /hometest  /etc/auto.hometest --timeout 3600
+    /nfs       /etc/auto.nfs --timeout 3600
+    /scratch   /etc/auto.scratch --timeout 3600
+
+for machines that have a scratch disk.  For machines without an extra disk, we want to get rid of that last line::
+
+    /software  /etc/auto.software --timeout 3600
+    /home      /etc/auto.home --timeout 3600
+    /hometest  /etc/auto.hometest --timeout 3600
+    /nfs       /etc/auto.nfs --timeout 3600
+
+So, from the Probes standpoint we want to create a script that counts the number of SCSI disks in a client machine.  To do this, we create a very simple `Probes/scratchlocal` script::
+
+    cat /proc/scsi/scsi | grep Vendor | wc -l
+
+Running this on a node with `n` disks will return the number `n+1`, as it also counts the controller as a device.  To differentiate between the two classes of machines we care about, we just need to check the output of this script for numbers greater than 2.  We do this in the template.
+
+The `TCheetah/` directory is laid out much like the `Cfg/` directory.  For this example we will want to create a `TCheetah/etc/auto.master` directory to hold the template of the file in question.  Inside of this template we will need to check the result of the Probe script that got run and act accordingly.  The `TCheetah/etc/auto.master/template` file looks like::
+
+    /software  /etc/auto.software --timeout 3600
+    /home      /etc/auto.home --timeout 3600
+    /hometest  /etc/auto.hometest --timeout 3600
+    /nfs       /etc/auto.nfs --timeout 3600
+    #if int($self.metadata.probes["scratchlocal"]) > 2
+    /scratch   /etc/auto.scratch --timeout 3600
+    #end if
+
+Any Probe script you run will store its output in `$self.metadata.probes["scriptname"]` ('''NOTE:''' `$self.metadata.Probes["scriptname"]` in 1.0.0 or later), so we get to our `scratchlocal` script's output as seen above.  Note that we had to wrap the output in an `int()` call; the script output is treated as a string, so it needs to be converted before it can be tested numerically.
+
+With all of these pieces in place, the following series of events will happen when the client is run:
+
+#. Client runs
+#. Server hands down our `scratchlocal` probe script
+#. Client runs the `scratchlocal` probe script and hands its output back up to the server
+#. Server generates `/etc/auto.master` from its template, performing any templating substitutions/actions needed in the process.
+#. Server hands `/etc/auto.master` down to the client
+#. Client puts file contents in place.
+
+Now we have a nicely dynamic `/etc/auto.master` that can gracefully handle machines with different numbers of disks.  All that's left to do is to add the `/etc/auto.master` to a Bundle::
+
+    <ConfigFile name='/etc/auto.master'/>
+
+Other examples
+==============
+
+Dynamically assign a group based on the Ubuntu version::
+
+    #!/bin/sh
+
+    if [ ! -e /etc/lsb-release ]; then exit 0; fi
+    . /etc/lsb-release
+    echo group:$DISTRIB_CODENAME
+
+Detect if the server is a Linux-VServer host::
+
+    #!/bin/sh
+
+    # Test the proc
+    TEST=`cat /proc/self/status|grep s_context| cut -d":" -f2|cut -d" " -f 2`
+
+    case "$TEST" in
+      "")
+        # Not a vserver kernel
+        echo group:host
+        ;;
+      "0")
+        # Vserver kernel but it is the HOST
+        echo group:host
+        ;;
+      [0-9]*)
+        # Vserver
+        echo group:vserver
+        ;;
+    esac
+
+Host and Group Specific probes
+==============================
+
+Bcfg2 has the ability to alter probes based on client hostname and group membership. These files work similarly to files in Cfg.
+
+If multiple files with the same basename apply to a client, the most specific one is used. Only one instance of a probe is served to a given client, so if a host-specific version and generic version apply, only the client-specific one will be used.