diff options
author | Sol Jerome <sol.jerome@gmail.com> | 2011-01-22 13:06:14 -0600 |
---|---|---|
committer | Sol Jerome <sol.jerome@gmail.com> | 2011-01-22 13:07:17 -0600 |
commit | e0a0a027917ca876dd059a13b71a5aea5e2af012 (patch) | |
tree | 40e25e1a2f65265662c7c7e724fca7adb1d04796 | |
parent | 9c73b2945a841bb0f1cbd45706d9c33dd9ad057c (diff) | |
download | bcfg2-e0a0a027917ca876dd059a13b71a5aea5e2af012.tar.gz bcfg2-e0a0a027917ca876dd059a13b71a5aea5e2af012.tar.bz2 bcfg2-e0a0a027917ca876dd059a13b71a5aea5e2af012.zip |
doc: More documentation build fixes
Signed-off-by: Sol Jerome <sol.jerome@gmail.com>
-rw-r--r-- | doc/server/plugins/generators/tcheetah.txt | 2 | ||||
-rw-r--r-- | doc/server/plugins/grouping/ldap.txt | 250 | ||||
-rw-r--r-- | doc/server/plugins/index.txt | 14 | ||||
-rw-r--r-- | doc/server/plugins/misc/guppy.txt | 4 | ||||
-rw-r--r-- | doc/server/plugins/probes/index.txt | 7 | ||||
-rw-r--r-- | doc/server/plugins/probes/ohai.txt (renamed from doc/server/plugins/misc/ohai.txt) | 2 |
6 files changed, 268 insertions, 11 deletions
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/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/misc/ohai.txt b/doc/server/plugins/probes/ohai.txt index e9fec7cc0..f44a64c58 100644 --- a/doc/server/plugins/misc/ohai.txt +++ b/doc/server/plugins/probes/ohai.txt @@ -1,6 +1,6 @@ .. -*- mode: rst -*- -.. _server-plugins-misc-ohai: +.. _server-plugins-probes-ohai: Ohai ==== |