From e0a0a027917ca876dd059a13b71a5aea5e2af012 Mon Sep 17 00:00:00 2001
From: Sol Jerome <sol.jerome@gmail.com>
Date: Sat, 22 Jan 2011 13:06:14 -0600
Subject: doc: More documentation build fixes

Signed-off-by: Sol Jerome <sol.jerome@gmail.com>
---
 doc/server/plugins/generators/tcheetah.txt |   2 +-
 doc/server/plugins/grouping/ldap.txt       | 250 +++++++++++++++++++++++++++++
 doc/server/plugins/index.txt               |  14 +-
 doc/server/plugins/misc/guppy.txt          |   4 +-
 doc/server/plugins/misc/ohai.txt           |  36 -----
 doc/server/plugins/probes/index.txt        |   7 +-
 doc/server/plugins/probes/ohai.txt         |  36 +++++
 7 files changed, 303 insertions(+), 46 deletions(-)
 create mode 100644 doc/server/plugins/grouping/ldap.txt
 delete mode 100644 doc/server/plugins/misc/ohai.txt
 create mode 100644 doc/server/plugins/probes/ohai.txt

(limited to 'doc')

diff --git a/doc/server/plugins/generators/tcheetah.txt b/doc/server/plugins/generators/tcheetah.txt
index 8077d313e..f2ca6c87c 100644
--- a/doc/server/plugins/generators/tcheetah.txt
+++ b/doc/server/plugins/generators/tcheetah.txt
@@ -48,7 +48,7 @@ self.metadata is an instance of the class ClientMetadata and documented
 :ref:`here <server-plugins-grouping-metadata-clientmetadata>`.
 
 self.metadata.Properties.data
-========================
+=============================
 
 Properties.data is a python `ElementTree <http://codespeak.net/lxml/>`_
 object, loaded from the data in ``/var/lib/bcfg2/Properties/<properties
diff --git a/doc/server/plugins/grouping/ldap.txt b/doc/server/plugins/grouping/ldap.txt
new file mode 100644
index 000000000..90590a272
--- /dev/null
+++ b/doc/server/plugins/grouping/ldap.txt
@@ -0,0 +1,250 @@
+.. -*- mode: rst -*-
+
+.. _server-plugins-grouping-ldap:
+
+====
+Ldap
+====
+
+.. warning::
+    This plugin is considered experimental and has known issues (see below).
+
+Purpose
+-------
+
+This plugin makes it possible to fetch data from an LDAP directory, process it
+and attach it to your metadata.
+
+Installation
+------------
+
+__ http://www.python-ldap.org/
+
+First, you need to install the `python-ldap library`__. On debian-based systems this is
+accomplished by::
+
+    aptitude install python-ldap
+
+To enable the plugin, add "Ldap" to the plugins line in your ``bcfg2.conf``.
+Then add a new directory called "Ldap" to the root of your Bcfg2 repository and
+define your queries in a file called ``config.py`` using the information in the
+next section.
+
+Configuration
+-------------
+
+As processing LDAP search results can get pretty complex, the configuration has 
+to be written in Python.
+
+Here is a minimal example to get you started::
+
+    from Bcfg2.Server.Plugins.Ldap import LdapConnection, LdapQuery, LdapSubQuery, register_query
+    
+    conn_default = LdapConnection()
+    conn_default.binddn = "uid=example,ou=People,dc=example,dc=com"
+    conn_default.bindpw = "foobat"
+    
+    @register_query
+    class ExampleQuery(LdapQuery):
+        name = "example"
+        base = "ou=People,dc=example,dc=com"
+        scope = "one"
+        attrs = ["cn", "uid"]
+        connection = conn_default
+    
+        def prepare_query(self, metadata):
+            self.filter = "(personalServer=" + metadata.hostname + ")"
+    
+        def process_result(self, metadata):
+            if not self.result:
+                admin_uid = None
+                admin_name = "This server has no admin."
+            return { 
+                "admin_uid" : self.result[0][1]["uid"],
+                "admin_name" : self.result[0][1]["cn"]
+            }
+
+The first line provides three classes for dealing with connections and queries
+(details below) and a decorator function for registering your queries with the plugin.
+
+In this example our LDAP directory has a number of user objects in it. Each of those
+may have a personal server they administer. Whenever metadata for this machine is being
+generated by the Bcfg2 server, the UID and name of the admin are retrieved from LDAP.
+
+In your bundles and config templates, you can access this data via the metadata object::
+
+    ${metadata.Ldap["example"]["admin_name"]}
+
+Class reference
+---------------
+
+LdapConnection
+++++++++++++++
+
+.. class:: LdapConnection
+
+   This class represents an LDAP connection. Every query must be associated with exactly 
+   one connection.
+   
+.. attribute:: LdapConnection.binddn 
+   
+   DN used to authenticate against LDAP (required).
+   
+.. attribute:: LdapConnection.bindpw
+   
+   Password for the previously mentioned **binddn** (required).
+  
+.. attribute:: LdapConnection.host
+   
+   Hostname of host running the LDAP server (defaults to "localhost").
+
+.. attribute:: LdapConnection.port
+   
+   Port where LDAP server is listening (defaults to 389).
+
+You may pass any of these attributes as keyword arguments when creating the connection object.
+
+LdapQuery
++++++++++
+
+.. class:: LdapQuery
+   
+   This class defines a single query that may adapt itself depending on the current metadata.
+
+.. attribute:: LdapQuery.attrs
+   
+   Can be used to retrieve only a certain subset of attributes. May either be a list of
+   strings (attribute names) or ``None``, meaning all attributes (defaults to ``None``).
+
+.. attribute:: LdapQuery.base
+   
+   This is the search base. Only LDAP entries below this DN will be included in your 
+   search results (required).
+   
+.. attribute:: LdapQuery.connection
+   
+   Set this to an instance of the LdapConnection class (required).
+
+.. attribute:: LdapQuery.filter
+   
+   LDAP search filter used to narrow down search results (defaults to ``(objectClass=*)``).
+
+.. attribute:: LdapQuery.name
+   
+   This will be used as the dictionary key that provides access to the query results from
+   the metadata object (``metadata.Ldap["NAMEGOESHERE"]``) (required).
+
+.. attribute:: LdapQuery.scope
+   
+   Set this to one of "base", "one" or "sub" to specify LDAP search depth (defaults to "sub"). 
+
+.. method:: LdapQuery.is_applicable(self, metadata)
+   
+   You can override this method to indicate whether this query makes sense for a given
+   set of metadata (e.g. you need a query only for a certain bundle or group).
+   
+   (defaults to returning True)
+   
+.. method:: LdapQuery.prepare_query(self, metadata)
+   
+   Override this method to alter the query prior to execution. This is useful if your filter
+   depends on the current metadata, e.g.::
+   
+       self.filter = "(cn=" + metadata.hostname + ")"
+   
+   (defaults to doing nothing)
+
+.. method:: LdapQuery.process_result(self, metadata)
+   
+   You will probably override this method in every query to reformat the results from LDAP.
+   The raw result is stored in ``self.result``, you must return the altered data. Note that LDAP
+   search results are presented in this structure::
+   
+      (
+          ("DN of first entry returned",
+              {
+                  "firstAttribute" : 1,
+                  "secondAttribute" : 2,
+              } 
+          ),
+          ("DN of second entry returned",
+              {
+                  "firstAttribute" : 1,
+                  "secondAttribute" : 2,
+              } 
+          ),
+      )
+   
+   Therefore, to return just the value of the firstAttribute of the second object returned,
+   you'd write::
+   
+      return self.result[1][1][0]
+   
+   (defaults to returning ``self.result`` unaltered)
+
+LdapSubQuery
+++++++++++++
+
+.. class:: LdapSubQuery
+
+   Sometimes you need more than one query to obtain the data you need (e.g. use the first
+   query to return all websites running on metadata.hostname and another query to find all
+   customers that should have access to those sites).
+   
+   LdapSubQueries are the same as LdapQueries, except for that the methods
+   
+   * ``get_result()``
+   * ``prepare_query()``
+   * ``process_result()``
+     
+   allow any additional keyword arguments that may contain additional data as needed. Note 
+   that ``get_result()`` will call ``prepare_query()`` and ``process_result()`` for you,
+   so you shouldn't ever need to invoke these yourself, just override them.
+   
+Here is another example that uses LdapSubQuery::
+
+	class WebSitesQuery(LdapSubQuery):
+	    name = "web_sites"
+	    filter = "(objectClass=webHostingSite)"
+	    attrs = ["dc"]
+	    connection = conn_default
+	    
+	    def prepare_query(self, metadata, base_dn):
+	        self.base = base_dn
+	    
+	    def process_result(self, metadata):
+	        [...] # build sites dict from returned dc attributes
+	        return sites
+	
+	@register_query
+	class WebPackagesQuery(LdapQuery):
+	    name = "web_packages"
+	    base = "dc=example,dc=com"
+	    attrs = ["customerId"]
+	    connection = conn_default
+	    
+	    def prepare_query(self, metadata):
+	        self.filter = "(&(objectClass=webHostingPackage)(cn:dn:=" + metadata.hostname + "))"
+	    
+	    def process_result(self, metadata):
+	        customers = {}
+	        for customer in self.result:
+	            dn = customer[0]
+	            cid = customer[1]["customerId"][0]
+	            customers[cid]["sites"] = WebSitesQuery().get_result(metadata, base_dn = dn)
+	        return customers
+
+This example assumes that we have a number of webhosting packages that contain various
+sites. We need a first query ("web_packages") to get a list of the packages our customers
+have and another query for each of those to find out what sites are contained in each 
+package. The magic happens in the second class where ``WebSitesQuery.get_result()`` is 
+called with the additional ``base_dn`` parameter that allows our LdapSubQuery to only 
+search below that DN.
+
+.. warning::
+    Do NOT apply the ``register_query`` decorator to LdapSubQueries.
+
+Known Issues
+------------
+
+* At this point there is no support for SSL/TLS.
diff --git a/doc/server/plugins/index.txt b/doc/server/plugins/index.txt
index d6e736278..8ef3d5af3 100644
--- a/doc/server/plugins/index.txt
+++ b/doc/server/plugins/index.txt
@@ -11,8 +11,12 @@ perform one of several tasks:
 
 #. Generating configuration inventory lists for clients
 #. Generating configuration entry contents for clients
-#. Probing client-side state (like hardware inventory, etc) -- the genericclient 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)
+#. 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
 
 Enabling Plugins
@@ -24,9 +28,8 @@ the *plugins* line in ``bcfg2.conf``.
 Default Plugins
 ===============
 
-The `Bcfg2 repository`_ contains the all plugin currently distributed
-with Bcfg2:
-http://trac.mcs.anl.gov/projects/bcfg2/browser/src/lib/Server/Plugins
+The `Bcfg2 repository`_ contains the all plugins currently distributed
+with Bcfg2.
 
 .. _Bcfg2 repository: http://trac.mcs.anl.gov/projects/bcfg2/browser/src/lib/Server/Plugins
 
@@ -121,4 +124,3 @@ More details can be found in :ref:`server-plugins-plugin-roles`
 
    plugin-roles
    probes/index
-   trigger
diff --git a/doc/server/plugins/misc/guppy.txt b/doc/server/plugins/misc/guppy.txt
index 0b8ef8203..8307218e3 100644
--- a/doc/server/plugins/misc/guppy.txt
+++ b/doc/server/plugins/misc/guppy.txt
@@ -8,8 +8,8 @@ Guppy
 
 This plugin is used to trace memory leaks within the bcfg2-server
 process using Guppy_. By default the remote debugger is started
-when this plugin is enabled. The debugger can be shutoff in a running
-process using ``bcfg2-admin xcmd Guppy.Disable`` and reenabled using
+when this plugin is enabled. The debugger can be disabled in a running
+process using ``bcfg2-admin xcmd Guppy.Disable`` and enabled using
 ``bcfg2-admin xcmd Guppy.Enable``.
 
 .. _Guppy: http://pypi.python.org/pypi/guppy/0.1.8
diff --git a/doc/server/plugins/misc/ohai.txt b/doc/server/plugins/misc/ohai.txt
deleted file mode 100644
index e9fec7cc0..000000000
--- a/doc/server/plugins/misc/ohai.txt
+++ /dev/null
@@ -1,36 +0,0 @@
-.. -*- mode: rst -*-
-
-.. _server-plugins-misc-ohai:
-
-Ohai
-====
-
-.. _Ohai: http://wiki.opscode.com/display/ohai/Home
-.. _Ohai-Install: http://wiki.opscode.com/display/ohai/Installation
-
-The `Ohai`_ plugin is used to detect information about the client
-operating system. The data is reported back to the server using JSON.
-
-Client prerequisites
---------------------
-
-On the client, you need to install `Ohai`_. See `Ohai-Install`_ for more
-information.
-
-Server prerequisites
---------------------
-
-If you have python 2.6 or later installed, you can continue on to
-:ref:`ohai-setup`. Otherwise, you will need to install the
-python-simplejson module found packaged in most distributions.
-
-.. _ohai-setup:
-
-Setup
------
-
-To enable the Ohai plugin, you need to first create an ``Ohai`` directory
-in your Bcfg2 repository (e.g. ``/var/lib/bcfg2/Ohai``). You then need
-to add **Ohai** to the plugins line in ``bcfg2.conf``. Once this is done,
-restart the server and start a client run. You will have the JSON output
-from the client in the ``Ohai`` directory you created previously.
diff --git a/doc/server/plugins/probes/index.txt b/doc/server/plugins/probes/index.txt
index 45ff3fb5b..33ec6f444 100644
--- a/doc/server/plugins/probes/index.txt
+++ b/doc/server/plugins/probes/index.txt
@@ -122,7 +122,7 @@ client, so if a host-specific version and generic version apply, only
 the client-specific one will be used.
 
 If you want to to detect information about the client operating system,
-the :ref:`server-plugins-misc-ohai` plugin can help.
+the :ref:`server-plugins-probes-ohai` plugin can help.
 
 
 Other examples
@@ -138,3 +138,8 @@ Other examples
    manufacturer
    producttype
    serial-console-speed
+
+.. toctree::
+   :hidden:
+
+   ohai
diff --git a/doc/server/plugins/probes/ohai.txt b/doc/server/plugins/probes/ohai.txt
new file mode 100644
index 000000000..f44a64c58
--- /dev/null
+++ b/doc/server/plugins/probes/ohai.txt
@@ -0,0 +1,36 @@
+.. -*- mode: rst -*-
+
+.. _server-plugins-probes-ohai:
+
+Ohai
+====
+
+.. _Ohai: http://wiki.opscode.com/display/ohai/Home
+.. _Ohai-Install: http://wiki.opscode.com/display/ohai/Installation
+
+The `Ohai`_ plugin is used to detect information about the client
+operating system. The data is reported back to the server using JSON.
+
+Client prerequisites
+--------------------
+
+On the client, you need to install `Ohai`_. See `Ohai-Install`_ for more
+information.
+
+Server prerequisites
+--------------------
+
+If you have python 2.6 or later installed, you can continue on to
+:ref:`ohai-setup`. Otherwise, you will need to install the
+python-simplejson module found packaged in most distributions.
+
+.. _ohai-setup:
+
+Setup
+-----
+
+To enable the Ohai plugin, you need to first create an ``Ohai`` directory
+in your Bcfg2 repository (e.g. ``/var/lib/bcfg2/Ohai``). You then need
+to add **Ohai** to the plugins line in ``bcfg2.conf``. Once this is done,
+restart the server and start a client run. You will have the JSON output
+from the client in the ``Ohai`` directory you created previously.
-- 
cgit v1.2.3-1-g7c22