summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--doc/client/index.txt1
-rw-r--r--doc/quickstart/index.txt6
-rw-r--r--doc/server/plugins/generators/rules.txt320
-rw-r--r--doc/server/plugins/grouping/metadata.txt2
-rw-r--r--doc/server/plugins/index.txt7
-rw-r--r--doc/server/plugins/probes.txt114
-rw-r--r--doc/server/plugins/probes/current-kernel.txt15
-rw-r--r--doc/server/plugins/probes/group.txt88
-rw-r--r--doc/server/plugins/probes/grub-serial-order.txt46
-rw-r--r--doc/server/plugins/probes/index.txt128
-rw-r--r--doc/server/plugins/probes/manufacturer.txt49
-rw-r--r--doc/server/plugins/probes/producttype.txt79
-rw-r--r--doc/server/plugins/probes/serial-console-speed.txt49
-rw-r--r--doc/server/plugins/probes/vserver.txt30
-rw-r--r--doc/server/plugins/properties.txt46
-rw-r--r--doc/server/plugins/structures/base.txt3
-rw-r--r--doc/server/plugins/structures/bundler/index.txt (renamed from doc/server/plugins/structures/bundler.txt)75
-rw-r--r--doc/server/plugins/trigger.txt36
-rw-r--r--doc/unsorted/index.txt9
19 files changed, 853 insertions, 250 deletions
diff --git a/doc/client/index.txt b/doc/client/index.txt
index 96787814f..438e43dcd 100644
--- a/doc/client/index.txt
+++ b/doc/client/index.txt
@@ -21,6 +21,7 @@ architecture, as opposed to one with a smarter client, for a few reasons:
agent
debugging
metadata
+ paranoid
.. toctree::
:maxdepth: 2
diff --git a/doc/quickstart/index.txt b/doc/quickstart/index.txt
index 7fcbc5e02..1f197e52c 100644
--- a/doc/quickstart/index.txt
+++ b/doc/quickstart/index.txt
@@ -229,9 +229,9 @@ you will find that we now have a correct entry::
Done! Now we just have 242 (or more) entries to take care of!
-:ref:`server-plugins-structures-bundler` is a relatively easy directory to
-populate. You can find many samples of Bundles in the `Bundle
-Repository`_, many of which can be used without editing.
+:ref:`server-plugins-structures-bundler-index` is a relatively easy
+directory to populate. You can find many samples of Bundles in the
+`Bundle Repository`_, many of which can be used without editing.
.. _Bundle Repository: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Plugins/Bundler/examples
diff --git a/doc/server/plugins/generators/rules.txt b/doc/server/plugins/generators/rules.txt
index 34be180bf..ca40eae70 100644
--- a/doc/server/plugins/generators/rules.txt
+++ b/doc/server/plugins/generators/rules.txt
@@ -9,24 +9,29 @@ Rules
The Rules plugin resolves the following Abstract Configuration Entities:
* Service
-* Directory
-* SymLink
* Package
* Path
-* Permissions
* Action
-to literal configuration entries suitable for the client drivers to consume.
+to literal configuration entries suitable for the client drivers to
+consume.
-For an entity specification to be included in the Literal configuration the name attribute from an Abstract Entity Tag (from Base or Bundler) must match the name attribute of an Entity tag in Rules, along with the appropriate group associations of course.
+For an entity specification to be included in the Literal configuration
+the name attribute from an Abstract Entity Tag (from Base or Bundler)
+must match the name attribute of an Entity tag in Rules, along with the
+appropriate group associations of course.
-Each file in the Rules directory has a priority. This allows the same Entities to be served by multiple files. The priorities can be used to break ties in the case that multiple files serve data for the same Entity.
+Each file in the Rules directory has a priority. This allows the same
+Entities to be served by multiple files. The priorities can be used to
+break ties in the case that multiple files serve data for the same Entity.
Usage of Groups in Rules
========================
-Groups are used by the Rules plugin, along with host metadata, for selecting the Configuration Entity entries to include in the clients literal configuration. They can be thought of as::
+Groups are used by the Rules plugin, along with host metadata, for
+selecting the Configuration Entity entries to include in the clients
+literal configuration. They can be thought of as::
if client is a member of group1 then
assign to literal config
@@ -46,44 +51,62 @@ Rules Tag
The Rules Tag may have the following attributes:
-|| '' '''Name''' '' || '' '''Description''' '' || '' '''Values''' '' ||
-|| priority || Sets the priority for Rules in this Rules list.The higher value wins. || String ||
++----------+-------------------------------------+--------+
+| Name | Description | Values |
++==========+=====================================+========+
+| priority | Sets the priority for Rules in this | String |
+| | Rules list.The higher value wins. | |
++----------+-------------------------------------+--------+
Rules Group Tag
---------------
The Rules Group Tag may have the following attributes:
-|| '' '''Name''' '' || '' '''Description''' '' || '' '''Values''' '' ||
-|| name || Group Name || String ||
-|| negate || Negate group membership (is not a member of) || (True|False) ||
++--------+-------------------------+--------------+
+| Name | Description | Values |
++========+=========================+==============+
+| name | Group Name | String |
++--------+-------------------------+--------------+
+| negate | Negate group membership | (True|False) |
+| | (is not a member of) | |
++--------+-------------------------+--------------+
Package Tag
-----------
The Package Tag may have the following attributes:
-|| '' '''Name''' '' || '' '''Description''' '' || '' '''Values''' '' ||
-|| name || Package Name || String ||
-|| version || Package Version orversion='noverify' to not do version checking in the Yum driver only (temporary work a round). || String ||
-|| file || Package file name. Several other attributes (name, version) can be automatically defined based on regular expressions defined in the Pkgmgr plugin. || String ||
-|| simplefile || Package file name. No name parsing is performed, so no extra fields get set || String ||
-|| verify || verify='false' - do not do package verification || String ||
-|| reloc || RPM relocation path. || String ||
-|| multiarch || Comma separated list of the architectures of this package that should be installed. || String ||
-|| srcs || Filename creation rules for multiarch packages. || String ||
-|| type || Package type. (rpm, yum, apt,sysv,blast) || String ||
-
-Permissions Tag
----------------
-
-The Permissions tag is
-
-|| '' '''Name''' '' || '' '''Description''' '' || '' '''Values''' '' ||
-|| name || Name of the file. || String ||
-|| perms || Permissions of the file. || ||
-|| owner || Owner of the file. || ||
-|| group || Group of the file. || ||
++------------+----------------------------------------------+--------+
+| Name | Description | Values |
++============+==============================================+========+
+| name | Package Name | String |
++------------+----------------------------------------------+--------+
+| version | Package Version or version='noverify' to | String |
+| | not do version checking in the Yum driver | |
+| | only (temporary work a round). | |
++------------+----------------------------------------------+--------+
+| file | Package file name. Several other attributes | String |
+| | (name, version) can be automatically defined | |
+| | based on regular expressions defined in the | |
+| | Pkgmgr plugin. | |
++------------+----------------------------------------------+--------+
+| simplefile | Package file name. No name parsing is | String |
+| | performed, so no extra fields get set | |
++------------+----------------------------------------------+--------+
+| verify | verify='false' - do not do package | String |
+| | verification | |
++------------+----------------------------------------------+--------+
+| reloc | RPM relocation path. | String |
++------------+----------------------------------------------+--------+
+| multiarch | Comma separated list of the architectures of | String |
+| | this package that should be installed. | |
++------------+----------------------------------------------+--------+
+| srcs | Filename creation rules for multiarch | String |
+| | packages. | |
++------------+----------------------------------------------+--------+
+| type | Package type. (rpm, yum, apt,sysv,blast) | String |
++------------+----------------------------------------------+--------+
Action Tag
----------
@@ -93,102 +116,187 @@ See [wiki:Plugins/Actions Actions]
Service Tag
-----------
-The Service tag is
-
-|| '' '''Name''' '' || '' '''Description''' '' || '' '''Values''' '' ||
-|| name || Service Name || String ||
-|| status || Should the service be on or off. || (on|off) ||
-|| restart || Service command for restart (default:restart) || String ||
-|| type || Driver to use on the client to manage this service. || (chkconfig|deb|rc-update|smf) ||
-|| sequence || Order for service startup (debian services only) || integer ||
-
-Directory Tag
--------------
-
-The Directory tag is
-
-|| '' '''Name''' '' || '' '''Description''' '' || '' '''Values''' '' ||
-|| name || Directory Name || String ||
-|| perms || Permissions of the directory. || String ||
-|| owner || Owner of the directory || String ||
-|| group || Group Owner of the directory || String ||
-|| prune || prune unspecified entries from the Directory || true|false ||
-
-SymLink Tag
------------
-
-The SymLink tag is
-
-|| '' '''Name''' '' || '' '''Description''' '' || '' '''Values''' '' ||
-|| name || Name of the symlink. || String ||
-|| to || File to link to || String ||
++----------+-----------------------------+-------------------------------+
+| Name | Description | Values |
++==========+=============================+===============================+
+| name | Service Name | String |
++----------+-----------------------------+-------------------------------+
+| status | Should the service be on or | (on|off) |
+| | off. | |
++----------+-----------------------------+-------------------------------+
+| restart | Service command for restart | String |
+| | (default:restart) | |
++----------+-----------------------------+-------------------------------+
+| type | Driver to use on the client | (chkconfig|deb|rc-update|smf) |
+| | to manage this service. | |
++----------+-----------------------------+-------------------------------+
+| sequence | Order for service startup | integer |
+| | (debian services only) | |
++----------+-----------------------------+-------------------------------+
Client Tag
----------
-The Client Tag is used in Rules for selecting the package entries to include in the clients literal configuration. Its function is similar to the Group tag in this context. It can be thought of as::
+The Client Tag is used in Rules for selecting the package entries to
+include in the clients literal configuration. Its function is similar
+to the Group tag in this context. It can be thought of as::
if client is name then
assign to literal config
The Client Tag may have the following attributes:
-|| '' '''Name''' '' || '' '''Description''' '' || '' '''Values''' '' ||
-|| name || Client Name || String ||
-|| negate || Negate client selection (if not client name) || (True|False) ||
++--------+-------------------------+--------------+
+| Name | Description | Values |
++========+=========================+==============+
+| name | Client Name | String |
++--------+-------------------------+--------------+
+| negate | Negate client selection | (True|False) |
+| | (if not client name) | |
++--------+-------------------------+--------------+
Path Tag
--------
-The Path tag is
-
-|| '' '''Name''' '' || '' '''Description''' '' || '' '''Values''' '' ||
-|| name || Name of the file || String ||
-|| type || Type of file || nonexistent ||
-
+The Path tag has different values depending on the *type* attribute of
+the path specified in your configuration. Below is a set of tables which
+describe the attributes available for various Path types.
+
+device
+^^^^^^
+
++----------+---------------------+-------------------+
+| Name | Description | Values |
++==========+=====================+===================+
+| name | Name of the device | String |
++----------+---------------------+-------------------+
+| dev_type | Type of device | (block|char|fifo) |
++----------+---------------------+-------------------+
+| owner | Device owner | String |
++----------+---------------------+-------------------+
+| group | Device group | String |
++----------+---------------------+-------------------+
+| major | Major number (block | integer |
+| | or char devices) | |
++----------+---------------------+-------------------+
+| minor | Minor number (block | integer |
+| | or char devices) | |
++----------+---------------------+-------------------+
+
+directory
+^^^^^^^^^
+
++-------+------------------------------+------------+
+| Name | Description | Values |
++=======+==============================+============+
+| name | Directory Name | String |
++-------+------------------------------+------------+
+| perms | Permissions of the directory | String |
++-------+------------------------------+------------+
+| owner | Owner of the directory | String |
++-------+------------------------------+------------+
+| group | Group Owner of the directory | String |
++-------+------------------------------+------------+
+| prune | prune unspecified entries | true|false |
+| | from the Directory | |
++-------+------------------------------+------------+
+
+hardlink
+^^^^^^^^
+
++------+----------------------+--------+
+| Name | Description | Values |
++======+======================+========+
+| name | Name of the hardlink | String |
++------+----------------------+--------+
+| to | File to link to | String |
++------+----------------------+--------+
+
+nonexistent
+^^^^^^^^^^^
+
++------+--------------------+-------------+
+| Name | Description | Values |
++======+====================+=============+
+| name | Name of the | String |
+| | (nonexistent) file | |
++------+--------------------+-------------+
+| type | Type of file | nonexistent |
++------+--------------------+-------------+
+
+permissions
+^^^^^^^^^^^
+
++-------+--------------------------+--------+
+| Name | Description | Values |
++=======+==========================+========+
+| name | Name of the file. | String |
++-------+--------------------------+--------+
+| perms | Permissions of the file. | String |
++-------+--------------------------+--------+
+| owner | Owner of the file. | String |
++-------+--------------------------+--------+
+| group | Group of the file. | String |
++-------+--------------------------+--------+
+
+symlink
+^^^^^^^
+
++------+----------------------+--------+
+| Name | Description | Values |
++======+======================+========+
+| name | Name of the symlink. | String |
++------+----------------------+--------+
+| to | File to link to | String |
++------+----------------------+--------+
Rules Directory
===============
-The Rules/ directory keeps the XML files that define what rules are available for a host. All the files in the directory are processed.
+The Rules/ directory keeps the XML files that define what rules are
+available for a host. All the files in the directory are processed.
-The names of the XML files have no special meaning to Bcfg2; they are simply named so it's easy for the administrator to know what the contents hold. All Rules could be kept in a single file if so desired. Bcfg2 simply uses the Groups in the files and priorities to determine how to assign Rules to a host's literal configuration.
+The names of the XML files have no special meaning to Bcfg2; they
+are simply named so it's easy for the administrator to know what the
+contents hold. All Rules could be kept in a single file if so desired.
+Bcfg2 simply uses the Groups in the files and priorities to determine
+how to assign Rules to a host's literal configuration.
.. code-block:: xml
<Rules priority="0">
- <Directory group="root" name="/autonfs" owner="root" perms="0755"/>
- <Directory group="utmp" name="/var/run/screen" owner="root" perms="0775"/>
- <Directory group="root" name="/autonfs/stage" owner="root" perms="0755"/>
- <Directory group="root" name="/exports" owner="root" perms="0755"/>
- <Directory name="/etc/condor" owner="root" group="root" perms="0755"/>
- <Directory name="/logs" group="wwwtrans" owner="root" perms="0775"/>
- <Directory name="/mnt" group="root" owner="root" perms="0755"/>
- <Directory name="/my" owner="root" group="root" perms="0755"/>
- <Directory name="/my/bin" owner="root" group="root" perms="0755"/>
- <Directory name="/nfs" owner="root" group="root" perms="0755"/>
- <Directory name="/sandbox" perms="0777" owner="root" group="root"/>
- <Directory name="/software" group="root" owner="root" perms="0755"/>
- <Permissions perms="0555" group="audio" owner="root" name="/dev/dsp"/>
- <Permissions perms="0555" group="audio" owner="root" name="/dev/mixer"/>
- <SymLink name="/bin/whatami" to="/mcs/adm/bin/whatami"/>
- <SymLink name="/chibahomes" to="/nfs/chiba-homefarm"/>
- <SymLink name="/home" to="/nfs/mcs-homefarm"/>
- <SymLink name="/homes" to="/home"/>
- <SymLink name="/mcs" to="/nfs/mcs"/>
- <SymLink name="/my/bin/bash" to="/bin/bash"/>
- <SymLink name="/my/bin/tcsh" to="/bin/tcsh"/>
- <SymLink name="/my/bin/zsh" to="/bin/zsh"/>
- <SymLink name="/software/common" to="/nfs/software-common"/>
- <SymLink name="/software/linux" to="/nfs/software-linux"/>
- <SymLink name="/software/linux-debian_sarge" to="/nfs/linux-debian_sarge"/>
- <SymLink name="/usr/bin/passwd" to="/usr/bin/yppasswd"/>
- <SymLink name="/usr/bin/yppasswd" to="/mcs/bin/passwd"/>
- <SymLink name="/usr/lib/libgd.so.1.8" to="/usr/lib/libgd.so.1.8.4"/>
- <SymLink name="/usr/lib/libtermcap.so.2" to="/usr/lib/libtermcap.so"/>
- <SymLink name="/usr/local/bin/perl" to="/usr/bin/perl"/>
- <SymLink name="/usr/local/bin/perl5" to="/usr/bin/perl"/>
- <SymLink name="/usr/local/bin/tcsh" to="/bin/tcsh"/>
+ <Path type='directory' group="root" name="/autonfs" owner="root" perms="0755"/>
+ <Path type='directory' group="utmp" name="/var/run/screen" owner="root" perms="0775"/>
+ <Path type='directory' group="root" name="/autonfs/stage" owner="root" perms="0755"/>
+ <Path type='directory' group="root" name="/exports" owner="root" perms="0755"/>
+ <Path type='directory' name="/etc/condor" owner="root" group="root" perms="0755"/>
+ <Path type='directory' name="/logs" group="wwwtrans" owner="root" perms="0775"/>
+ <Path type='directory' name="/mnt" group="root" owner="root" perms="0755"/>
+ <Path type='directory' name="/my" owner="root" group="root" perms="0755"/>
+ <Path type='directory' name="/my/bin" owner="root" group="root" perms="0755"/>
+ <Path type='directory' name="/nfs" owner="root" group="root" perms="0755"/>
+ <Path type='directory' name="/sandbox" perms="0777" owner="root" group="root"/>
+ <Path type='directory' name="/software" group="root" owner="root" perms="0755"/>
+ <Path type='permissions' perms="0555" group="audio" owner="root" name="/dev/dsp"/>
+ <Path type='permissions' perms="0555" group="audio" owner="root" name="/dev/mixer"/>
+ <Path type='symlink' name="/bin/whatami" to="/mcs/adm/bin/whatami"/>
+ <Path type='symlink' name="/chibahomes" to="/nfs/chiba-homefarm"/>
+ <Path type='symlink' name="/home" to="/nfs/mcs-homefarm"/>
+ <Path type='symlink' name="/homes" to="/home"/>
+ <Path type='symlink' name="/mcs" to="/nfs/mcs"/>
+ <Path type='symlink' name="/my/bin/bash" to="/bin/bash"/>
+ <Path type='symlink' name="/my/bin/tcsh" to="/bin/tcsh"/>
+ <Path type='symlink' name="/my/bin/zsh" to="/bin/zsh"/>
+ <Path type='symlink' name="/software/common" to="/nfs/software-common"/>
+ <Path type='symlink' name="/software/linux" to="/nfs/software-linux"/>
+ <Path type='symlink' name="/software/linux-debian_sarge" to="/nfs/linux-debian_sarge"/>
+ <Path type='symlink' name="/usr/bin/passwd" to="/usr/bin/yppasswd"/>
+ <Path type='symlink' name="/usr/bin/yppasswd" to="/mcs/bin/passwd"/>
+ <Path type='symlink' name="/usr/lib/libgd.so.1.8" to="/usr/lib/libgd.so.1.8.4"/>
+ <Path type='symlink' name="/usr/lib/libtermcap.so.2" to="/usr/lib/libtermcap.so"/>
+ <Path type='symlink' name="/usr/local/bin/perl" to="/usr/bin/perl"/>
+ <Path type='symlink' name="/usr/local/bin/perl5" to="/usr/bin/perl"/>
+ <Path type='symlink' name="/usr/local/bin/tcsh" to="/bin/tcsh"/>
<Service name='ntpd' status='on' type='chkconfig'/>
<Service name='haldaemon' status='on' type='chkconfig'/>
<Service name='messagebus' status='on' type='chkconfig'/>
diff --git a/doc/server/plugins/grouping/metadata.txt b/doc/server/plugins/grouping/metadata.txt
index 085d09717..fbfe42210 100644
--- a/doc/server/plugins/grouping/metadata.txt
+++ b/doc/server/plugins/grouping/metadata.txt
@@ -217,4 +217,4 @@ Probes
======
The metadata plugin includes client-side probing functionality. This
-is fully documented :ref:`here <server-plugins-probes>`.
+is fully documented :ref:`here <server-plugins-probes-index>`.
diff --git a/doc/server/plugins/index.txt b/doc/server/plugins/index.txt
index 5fcdc281b..37879d207 100644
--- a/doc/server/plugins/index.txt
+++ b/doc/server/plugins/index.txt
@@ -10,7 +10,7 @@ Plugins are the source of all logic used in building a config. They can perform
#. Generating configuration inventory lists for clients
#. Generating configuration entry contents for clients
-#. Probing client-side state (like hardware inventory, etc) -- the generic client probing mechanism is described at :ref:`server-plugins-probes`.
+#. Probing client-side state (like hardware inventory, etc) -- the generic client probing mechanism is described at :ref:`server-plugins-probes-index`.
#. Automating administrative tasks (e.g. :ref:`server-plugins-generators-sshbase` which automates ssh key management)
#. Generating client per-entry installation decision-lists
@@ -44,6 +44,7 @@ Abstract Configuration (Structures)
:maxdepth: 2
:glob:
+ structures/bundler/index
structures/*
Each of these plugins has a corresponding subdirectory with the same name in the Bcfg2 repository.
@@ -90,4 +91,6 @@ More details can be found in :ref:`server-plugins-plugin-roles`
:hidden:
plugin-roles
- probes
+ probes/index
+ properties
+ trigger
diff --git a/doc/server/plugins/probes.txt b/doc/server/plugins/probes.txt
deleted file mode 100644
index 57f12a840..000000000
--- a/doc/server/plugins/probes.txt
+++ /dev/null
@@ -1,114 +0,0 @@
-.. -*- mode: rst -*-
-
-.. _server-plugins-probes:
-
-======
-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
-:ref:`server-plugins-generators-tcheetah` 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:
-
-.. code-block:: xml
-
- <ConfigFile name='/etc/auto.master'/>
-
-Other examples
-==============
-
-Dynamically assign a group based on the Ubuntu version:
-
-.. code-block:: sh
-
- #!/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:
-
-.. code-block:: sh
-
- #!/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.
diff --git a/doc/server/plugins/probes/current-kernel.txt b/doc/server/plugins/probes/current-kernel.txt
new file mode 100644
index 000000000..f057f189b
--- /dev/null
+++ b/doc/server/plugins/probes/current-kernel.txt
@@ -0,0 +1,15 @@
+.. -*- mode: rst -*-
+
+.. _server-plugins-probes-current-kernel:
+
+current-kernel
+==============
+
+Probe the currently running kernel.
+
+.. code-block:: sh
+
+ #!/bin/sh
+ #
+ # PROBE_NAME : current-kernel
+ echo `uname -r`
diff --git a/doc/server/plugins/probes/group.txt b/doc/server/plugins/probes/group.txt
new file mode 100644
index 000000000..41b3e83f3
--- /dev/null
+++ b/doc/server/plugins/probes/group.txt
@@ -0,0 +1,88 @@
+.. -*- mode: rst -*-
+
+.. _server-plugins-probes-group:
+
+group
+=====
+
+Probe used to dynamically set client groups based on OS/distro.
+
+.. note::
+
+ Some parts of this script may depend on having lsb-release
+ installed.
+
+.. code-block:: sh
+
+ #!/bin/sh
+
+ OUTPUT=""
+ ARGS=""
+
+ if [ -e /etc/debian_version ]; then
+ # debian based
+ OUTPUT=$OUTPUT'\n'`echo group:deb`
+ if [ -e /etc/lsb-release ]; then
+ # variant
+ . /etc/lsb-release
+ OS_GROUP=$DISTRIB_CODENAME
+ DEBIAN_VERSION=$(echo "$DISTRIB_ID" | tr '[A-Z' '[a-z]')
+ case "$OS_GROUP" in
+ "hardy")
+ OUTPUT=$OUTPUT'\n'`echo group:$DISTRIB_CODENAME`
+ OUTPUT=$OUTPUT'\n'`echo group:$DEBIAN_VERSION`
+ ;;
+ esac
+ else
+ # debian
+ ARGS="-e"
+ OS_GROUP=`cat /etc/debian_version`
+ OUTPUT=$OUTPUT'\n'`echo group:debian`
+ case "$OS_GROUP" in
+ "5.0")
+ OUTPUT=$OUTPUT'\n'`echo group:lenny`
+ ;;
+ "sid")
+ OUTPUT=$OUTPUT'\n'`echo group:sid`
+ ;;
+ esac
+ fi
+ elif [ -e /etc/redhat-release ]; then
+ # redhat based
+ ARGS="-e"
+ OUTPUT=$OUTPUT'\n'`echo group:rpm`
+ OS_GROUP=`cat /etc/redhat-release | cut -d' ' -f1 | tr '[A-Z]' '[a-z]'`
+ REDHAT_VERSION=`cat /etc/redhat-release | cut -d' ' -f3`
+ case "$OS_GROUP" in
+ "centos" | "fedora")
+ OUTPUT=$OUTPUT'\n'`echo group:$OS_GROUP`
+ OUTPUT=$OUTPUT'\n'`echo group:$OS_GROUP$REDHAT_VERSION`
+ ;;
+ esac
+ elif [ -e /etc/gentoo-release ]; then
+ # gentoo
+ ARGS="-e"
+ OUTPUT=$OUTPUT'\n'`echo group:gentoo`
+ elif [ -x /usr/sbin/system_profiler ]; then
+ # os x
+ ### NOTE: Think about using system_profiler SPSoftwareDataType here
+ OSX_VERSION=`sw_vers | grep 'ProductVersion:' | grep -o '[0-9]*\.[0-9]*\.[0-9]*'`
+ OUTPUT=$OUTPUT'\n'`echo group:osx`
+ OUTPUT=$OUTPUT'\n'`echo group:$OSX_VERSION`
+ else
+ exit 0
+ fi
+ # get the proper architecture
+ ARCH=`uname -m`
+ case "$ARCH" in
+ "x86_64")
+ OUTPUT=$OUTPUT'\n'`echo group:amd64`
+ ;;
+ "i386" | "i686")
+ OUTPUT=$OUTPUT'\n'`echo group:i386`
+ ;;
+ esac
+
+ # output the result of all the group probing
+ # (interpreting the backslashed newlines)
+ echo $ARGS $OUTPUT
diff --git a/doc/server/plugins/probes/grub-serial-order.txt b/doc/server/plugins/probes/grub-serial-order.txt
new file mode 100644
index 000000000..fee420572
--- /dev/null
+++ b/doc/server/plugins/probes/grub-serial-order.txt
@@ -0,0 +1,46 @@
+.. -*- mode: rst -*-
+
+.. _server-plugins-probes-grub-serial-order:
+
+grub-serial-order
+=================
+
+A basic hardware probe to determine if you should change the default
+serial ordering in grub.conf. This pre-supposes that you know your
+hardware is broken. You can tell something is wrong with your hardware
+if it takes lots of time to iterate through the "Press a key" option
+and present you with the grub menu. In some cases, I've seen this take
+as long as 20 minutes.
+
+.. code-block:: sh
+
+ #!/bin/sh
+ #
+ #
+ # We need to modify the order of the --serial line in grub
+ # in order to fix silly hardware bugs. In some cases, having
+ # this in the wrong order causes grub to take an inordinate
+ # amount of time to do anything before it actually auto-picks
+ # the default menu option to boot.
+ #
+
+ PATH=/bin:/usr/bin:/sbin:/usr/sbin; export PATH
+ # let's figure out what product type this is
+ os=`uname -s`
+ productname="product-no-dmidecode"
+
+ if [ $os = "Linux" ] ; then
+ productname=`dmidecode -s system-product-name 2>&1`
+ case $productname in
+ "PowerEdge M600")
+ echo "console serial"
+ ;;
+ *)
+ echo "serial console"
+ ;;
+ esac
+ fi
+ if [ $os = "SunOS" ] ; then
+ # Bcfg2 server is unhappy with null output from probes
+ echo "console"
+ fi
diff --git a/doc/server/plugins/probes/index.txt b/doc/server/plugins/probes/index.txt
new file mode 100644
index 000000000..f723ad528
--- /dev/null
+++ b/doc/server/plugins/probes/index.txt
@@ -0,0 +1,128 @@
+.. -*- mode: rst -*-
+
+.. _server-plugins-probes-index:
+
+======
+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
+:ref:`server-plugins-generators-tcheetah` 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"]``, 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:
+
+.. code-block:: xml
+
+ <Path name='/etc/auto.master'/>
+
+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.
+
+Other examples
+==============
+
+.. toctree::
+ :maxdepth: 1
+
+ current-kernel
+ group
+ vserver
+ grub-serial-order
+ manufacturer
+ producttype
+ serial-console-speed
diff --git a/doc/server/plugins/probes/manufacturer.txt b/doc/server/plugins/probes/manufacturer.txt
new file mode 100644
index 000000000..8f0a12ed9
--- /dev/null
+++ b/doc/server/plugins/probes/manufacturer.txt
@@ -0,0 +1,49 @@
+.. -*- mode: rst -*-
+
+.. _server-plugins-probes-manufacturer:
+
+manufacturer
+============
+
+Probe to output some standardized group names based on the manufacturer
+information.
+
+.. code-block:: sh
+
+ #!/bin/sh
+ #
+ PATH=/bin:/usr/bin:/sbin:/usr/sbin; export PATH
+
+ manufacturer=manuf-no-demidecode
+
+ os=`uname -s`
+ if [ $os = "Linux" ] ; then
+ manufacturer=`dmidecode -s system-manufacturer 2>&1| sed -e 's/[ ]\+$//g'`
+ case $manufacturer in
+ "Dell Inc.")
+ manufacturer="manuf-dell"
+ ;;
+ "Sun Microsystems")
+ manufacturer="manuf-sun"
+ ;;
+ "VMware, Inc.")
+ manufacturer="manuf-vmware"
+ ;;
+ *)
+ manufacturer="manuf-unknown"
+ ;;
+ esac
+ fi
+
+ if [ $os = "SunOS" ]; then
+ case `uname -i` in
+ SUNW,*)
+ manufacturer="manuf-sun"
+ ;;
+ *)
+ manufacturer="manuf-unknown"
+ ;;
+ esac
+ fi
+
+ echo group:$manufacturer
diff --git a/doc/server/plugins/probes/producttype.txt b/doc/server/plugins/probes/producttype.txt
new file mode 100644
index 000000000..46510c6af
--- /dev/null
+++ b/doc/server/plugins/probes/producttype.txt
@@ -0,0 +1,79 @@
+.. -*- mode: rst -*-
+
+.. _server-plugins-probes-producttype:
+
+producttype
+===========
+
+A probe to set up dynamic groups based on the producttype and possibly
+some internal components of the system.
+
+Defined products are product-name.
+
+Defined component information is has_some_component. In the example
+below, we can infer that we have Emulex Lightpulse gear and set the
+group has_hardware_emulex_lightpulse.
+
+.. code-block:: sh
+
+ !/bin/sh
+ #
+ #
+
+ PATH=/bin:/usr/bin:/sbin:/usr/sbin; export PATH
+ # let's figure out what product type this is
+ os=`uname -s`
+ productname="product-no-dmidecode"
+
+ if [ $os = "Linux" ] ; then
+ productname=`dmidecode -s system-product-name 2>&1`
+ case $productname in
+ "PowerEdge M600")
+ productname="product-bladem600"
+ ;;
+ "Sun Fire X4100 M2")
+ productname="product-x4100m2"
+ ;;
+ "Sun Fire X4440")
+ productname="product-x4440"
+ ;;
+ "VMware Virtual Platform")
+ productname="product-vmware-vm"
+ ;;
+ *)
+ productname="product-unknown"
+ ;;
+ esac
+
+ # check for emulex lightpulse fiber channel HBA
+ check_emulex_lightpulse=`lspci -d 10df: | grep -c LightPulse`
+ if [ $check_emulex_lightpulse -gt 0 ]; then
+ echo group:has_hardware_emulex_lightpulse
+ fi
+
+ # check for broadcom nics
+ check_broadcom_nic=`lspci -d 14e4: | grep -c NetXtreme`
+ if [ $check_broadcom_nic -gt 0 ]; then
+ echo group:has_hardware_broadcom_nic
+ fi
+
+ # check for intel pro/1000 MT nics
+ check_intel_pro1000mt_nic=`lspci -d 8086:1010 | wc -l`
+ if [ $check_intel_pro1000mt_nic -gt 0 ]; then
+ echo group:has_hardware_intel_pro1000mt_nic
+ fi
+
+ fi
+
+ if [ $os = "SunOS" ] ; then
+ case `uname -i` in
+ SUNW,*)
+ productname=`uname -i`
+ ;;
+ *)
+ productname=product-unknown
+ ;;
+ esac
+ fi
+
+ echo group:$productname
diff --git a/doc/server/plugins/probes/serial-console-speed.txt b/doc/server/plugins/probes/serial-console-speed.txt
new file mode 100644
index 000000000..731948d25
--- /dev/null
+++ b/doc/server/plugins/probes/serial-console-speed.txt
@@ -0,0 +1,49 @@
+.. -*- mode: rst -*-
+
+.. _server-plugins-probes-serial-console-speed:
+
+serial-console-speed
+====================
+
+A probe to tell us what the serial console speed should be for a given
+piece of hardware. This pre-supposed some knowledge of the hardware
+because you define the speeds in here instead of attempting to probe
+bios or something in the hardware in most cases (like x86).
+
+.. code-block:: sh
+
+ #!/bin/sh
+ #
+ #
+ # figure out what serial speed we should tell bcfg2 to use.
+ # since there's no way to probe, we need to set this up by external
+ # knowledge of the system hardware type (and just make sure we
+ # standardize on that serial speed for that hardware class)
+
+ PATH=/bin:/usr/bin:/sbin:/usr/sbin; export PATH
+ # let's figure out what product type this is
+ os=`uname -s`
+ productname="product-no-dmidecode"
+
+ if [ $os = "Linux" ] ; then
+ productname=`dmidecode -s system-product-name 2>&1`
+ case $productname in
+ "PowerEdge M600")
+ echo "115200"
+ ;;
+ *)
+ echo "9600"
+ ;;
+ esac
+ fi
+ if [ $os = "SunOS" ]; then
+ platform=`uname -i`
+ case $platform in
+ SUNW,*)
+ eeprom ttya-mode | sed 's/ttya-mode=//'|awk -F, '{print $1}'
+ ;;
+ *)
+ echo "9600"
+ ;;
+ esac
+ fi
diff --git a/doc/server/plugins/probes/vserver.txt b/doc/server/plugins/probes/vserver.txt
new file mode 100644
index 000000000..f95390e99
--- /dev/null
+++ b/doc/server/plugins/probes/vserver.txt
@@ -0,0 +1,30 @@
+.. -*- mode: rst -*-
+
+.. _server-plugins-probes-vserver:
+
+vserver
+=======
+
+Detect if the server is a Linux-VServer host.
+
+.. code-block:: sh
+
+ #!/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
diff --git a/doc/server/plugins/properties.txt b/doc/server/plugins/properties.txt
new file mode 100644
index 000000000..fa8bfd884
--- /dev/null
+++ b/doc/server/plugins/properties.txt
@@ -0,0 +1,46 @@
+.. -*- mode: rst -*-
+
+.. _server-plugins-properties:
+
+==========
+Properties
+==========
+
+The Properties plugin is a connector plugin that adds information from
+properties files into client metadata instances.
+
+Enabling Properties
+===================
+
+First, ``mkdir /var/lib/bcfg2/Properties``. Each property XML file goes
+in this directory. Each will automatically be cached by the server,
+and reread/reparsed upon changes. Add **Properties** to your ``plugins``
+line in ``/etc/bcfg2.conf``.
+
+Data Structures
+===============
+
+Properties adds a new dictionary to client metadata instances that maps
+property file names to PropertyFile instances. PropertyFile instances
+contain parsed XML data as the "data" attribute.
+
+Usage
+=====
+
+Specific property files can be referred to in
+templates as metadata.Properties[<filename>]. The
+data attribute is an LXML element object. (Documented
+`here <http://codespeak.net/lxml/tutorial.html#the-element-class>`_)
+
+Currently, no access methods are defined for this data, but as we
+formulate common use cases, we will add them to the !PropertyFile class
+as methods. This will simplify templates.
+
+Accessing Properties contest from TGenshi
+=========================================
+
+Access contents of ``Properties/auth.xml``
+
+::
+
+ ${metadata.Properties['auth.xml'].data.find('file').find('bcfg2.key').text}
diff --git a/doc/server/plugins/structures/base.txt b/doc/server/plugins/structures/base.txt
index 8f28997b0..21244172e 100644
--- a/doc/server/plugins/structures/base.txt
+++ b/doc/server/plugins/structures/base.txt
@@ -11,4 +11,5 @@ lists of unrelated entries into client configuration entry inventories.
Base works much like Bundler in its file format. The main difference
between Base and Bundler is that Base files are included in all clients'
configuration whereas bundles must be included explicitly in your
-Metadata. See the :ref:`server-plugins-structures-bundler` page for details.
+Metadata. See the :ref:`server-plugins-structures-bundler-index` page
+for details.
diff --git a/doc/server/plugins/structures/bundler.txt b/doc/server/plugins/structures/bundler/index.txt
index 5437b35f1..2f4275a96 100644
--- a/doc/server/plugins/structures/bundler.txt
+++ b/doc/server/plugins/structures/bundler/index.txt
@@ -1,14 +1,28 @@
.. -*- mode: rst -*-
-.. _server-plugins-structures-bundler:
+.. _server-plugins-structures-bundler-index:
=======
Bundler
=======
-Bundler is used to describe groups of inter-dependent configuration entries, such as the combination of packages, configuration files, and service activations that comprise typical Unix daemons. Bundles are used to add groups of configuration entries to the inventory of client configurations, as opposed to describing particular versions of those entries. For example, a bundle could say that the configuration file "/etc/passwd" should be included in a configuration, but will not describe the particular version of "/etc/passwd" that a given client will receive.
-
-Groups can be used inside of bundles to differentiate which entries particular clients will recieve; this is useful for the case where entries are named differently across systems; for example, one linux distro may have a package called openssh while another uses the name ssh. Configuration entries nested inside of Group elements only apply to clients who are a member of those groups; multiply nested groups must all apply. Also, groups may be negated; entries included in such groups will only apply to clients who are not a member of said group.
+Bundler is used to describe groups of inter-dependent configuration
+entries, such as the combination of packages, configuration files,
+and service activations that comprise typical Unix daemons. Bundles are
+used to add groups of configuration entries to the inventory of client
+configurations, as opposed to describing particular versions of those
+entries. For example, a bundle could say that the configuration file
+"/etc/passwd" should be included in a configuration, but will not describe
+the particular version of "/etc/passwd" that a given client will receive.
+
+Groups can be used inside of bundles to differentiate which entries
+particular clients will recieve; this is useful for the case where
+entries are named differently across systems; for example, one linux
+distro may have a package called openssh while another uses the name
+ssh. Configuration entries nested inside of Group elements only apply
+to clients who are a member of those groups; multiply nested groups must
+all apply. Also, groups may be negated; entries included in such groups
+will only apply to clients who are not a member of said group.
The following is an annotated copy of a bundle:
@@ -42,7 +56,15 @@ The following is an annotated copy of a bundle:
</Group>
</Bundle>
-In this bundle, most of the entries are common to all systems. Clients in group "deb" get one extra package and service, while clients in group "rpm" get two extra packages and an extra service. In addition, clients in group "fedora" and group "rpm" get one extra package entries, unless they are not in the fc4 group, in which case, they get an extra package. Notice that this file doesn't describe which versions of these entries that clients should get, only that they should get them. (Admittedly, this example is slightly contrived, but demonstrates how group entries can be used in bundles)
+In this bundle, most of the entries are common to all systems. Clients
+in group "deb" get one extra package and service, while clients in group
+"rpm" get two extra packages and an extra service. In addition, clients in
+group "fedora" and group "rpm" get one extra package entries, unless they
+are not in the fc4 group, in which case, they get an extra package. Notice
+that this file doesn't describe which versions of these entries that
+clients should get, only that they should get them. (Admittedly, this
+example is slightly contrived, but demonstrates how group entries can
+be used in bundles)
+----------------------------+-------------------------------+
| Group | Entry |
@@ -83,12 +105,24 @@ In this bundle, most of the entries are common to all systems. Clients in group
Genshi templates
================
-Genshi templates are used by adding a Genshi xml-style template to the Bundler directory with a `.genshi` file extension. Version 0.4 or newer of genshi is required.
+Genshi templates are used by adding a Genshi xml-style template to the
+Bundler directory with a `.genshi` file extension. Version 0.4 or newer
+of genshi is required.
Motivation
----------
-Static Bundles have served us relatively well, but have a relatively weak set of interal per-client differentiation mechanisms. In static Bundles, the group hierarchy (from the perspective of the current client) is available for use via boolean constraints with negation. This notion does not mesh well with the use of Probes, which can result in freeform data. In the presence of probe results, clients can have a wide array of data, and rendering down to a boolean logic may not always be desirable. Moreover, while static Bundles allow entry inclusion or exclusion based on group memberships, they do not allow programatic entry rendering. Hence, Genshi templates not only provide more control options, but it also provide the ability to perform new entry rendering operations.
+Static Bundles have served us relatively well, but have a relatively
+weak set of interal per-client differentiation mechanisms. In static
+Bundles, the group hierarchy (from the perspective of the current
+client) is available for use via boolean constraints with negation. This
+notion does not mesh well with the use of Probes, which can result in
+freeform data. In the presence of probe results, clients can have a wide
+array of data, and rendering down to a boolean logic may not always
+be desirable. Moreover, while static Bundles allow entry inclusion or
+exclusion based on group memberships, they do not allow programatic entry
+rendering. Hence, Genshi templates not only provide more control options,
+but it also provide the ability to perform new entry rendering operations.
The `Genshi templating system`_ is used internally.
@@ -97,14 +131,20 @@ The `Genshi templating system`_ is used internally.
Use
---
-Bcfg uses the Genshi API for templates, and performs a XML format stream rendering of the template into an lxml entry, which is included in the client configuration. Client metadata is avilable inside of the template using the 'metadata' name. Note that only the markup Genshi template format can be used, as the target output format is XML.
+Bcfg uses the Genshi API for templates, and performs a XML format stream
+rendering of the template into an lxml entry, which is included in the
+client configuration. Client metadata is avilable inside of the template
+using the 'metadata' name. Note that only the markup Genshi template
+format can be used, as the target output format is XML.
-An Genshi template looks much like a Bundler file, except the Bundle tag has an additional `xmlns:py` attribute. See the examples.
+A Genshi template looks much like a Bundler file, except the Bundle tag
+has an additional `xmlns:py` attribute. See the examples.
Examples
--------
-In some cases, configuration files need to include the client's hostname in their name. The following template produces such a config file entry.
+In some cases, configuration files need to include the client's hostname
+in their name. The following template produces such a config file entry.
.. code-block:: xml
@@ -114,9 +154,13 @@ In some cases, configuration files need to include the client's hostname in thei
Depending on the circumstance, these configuration files can either be
handled by individual entries in :ref:`server-plugins-generators-cfg`,
-:ref:`server-plugins-generators-tcheetah`, or :ref:`server-plugins-generators-tgenshi`, or can be mapped to a single entry by using the [wiki:altsrc] feature.
+:ref:`server-plugins-generators-tcheetah`, or
+:ref:`server-plugins-generators-tgenshi`, or can be mapped to a single
+entry by using the [wiki:altsrc] feature.
-In this example, configuration file names are built using probed results from the client. getmac is a probe that gathers client MAC addresses and returns them in a newline delimited string.
+In this example, configuration file names are built using probed results
+from the client. getmac is a probe that gathers client MAC addresses
+and returns them in a newline delimited string.
.. code-block:: xml
@@ -131,7 +175,8 @@ In this example, configuration file names are built using probed results from th
* The use of the altsrc directive causes all ifcfg files to be handled by the same plugin and entry.
* The <?python ?> blocks have only been available in genshi since 0.4 (http://genshi.edgewall.org/ticket/84)
-If you want a file to be only on a per-client basis, you can use an if declaration:
+If you want a file to be only on a per-client basis, you can use an
+if declaration:
.. code-block:: xml
@@ -155,7 +200,9 @@ or alternately:
</py:if>
</Bundle>
-The latter form is preferred if the if block contains multiple files. While this example is simple, the test in the if block can in fact be any python statement.
+The latter form is preferred if the if block contains multiple
+files. While this example is simple, the test in the if block can in
+fact be any python statement.
Examples
--------
diff --git a/doc/server/plugins/trigger.txt b/doc/server/plugins/trigger.txt
new file mode 100644
index 000000000..065bc5ad2
--- /dev/null
+++ b/doc/server/plugins/trigger.txt
@@ -0,0 +1,36 @@
+.. -*- mode: rst -*-
+
+.. _server-plugins-trigger:
+
+=======
+Trigger
+=======
+
+Trigger is a plugin that calls external scripts when clients are
+configured.
+
+Setup
+=====
+
+::
+
+ mkdir /var/lib/bcfg2/Trigger
+ echo "#!/bin/sh\necho $1\n" > /var/lib/bcfg2/Trigger/test.sh
+ chmod +x /var/lib/bcfg2/Trigger/test.sh
+
+Use cases
+=========
+
+#. Completing network builds (ie resetting from the build target to the boot pxe target)
+#. Integration with external systems
+
+Trigger Arguments
+=================
+
+Triggers are run with a series of arguments.
+
+#. client hostname
+#. -p
+#. client profile
+#. -g
+#. group1:group2:..:groupN (all client groups)
diff --git a/doc/unsorted/index.txt b/doc/unsorted/index.txt
index 364a10407..02f09d640 100644
--- a/doc/unsorted/index.txt
+++ b/doc/unsorted/index.txt
@@ -25,13 +25,6 @@ list below.
* `Plugins/Bundler/examples/torque.xml`
* `Plugins/Bundler/examples/yp.xml`
* `Plugins/Ohai`
-* `Plugins/Probes/examples/current-kernel`
-* `Plugins/Probes/examples/group`
-* `Plugins/Probes/examples/grub-serial-order`
-* `Plugins/Probes/examples/manufacturer`
-* `Plugins/Probes/examples/producttype`
-* `Plugins/Probes/examples/serial-console-speed`
-* `Plugins/Properties`
* `Plugins/Snapshots`
* `Plugins/TGenshi/examples/bcfg2_cron`
* `Plugins/TGenshi/examples/clients.xml`
@@ -42,7 +35,6 @@ list below.
* `Plugins/TGenshi/examples/motd`
* `Plugins/TGenshi/examples/my.cnf`
* `Plugins/TGenshi/examples/test`
-* `Plugins/Trigger`
* `PrecompiledPackages`
* `Prereqs`
* `Publications`
@@ -53,7 +45,6 @@ list below.
* `ServerSideOverview`
* `TGenshi/examples/Templated_Access`
* `TOC`
-* `TrackingDevelopmentTrunk`
* `Troubleshooting`
* `UpgradeTesting`
* `UsingRcache`