path: root/doc/server/plugins/grouping/ldap.txt

.. -*- mode: rst -*-

.. _server-plugins-grouping-ldap:

====
Ldap
====

.. warning::
    This plugin is considered experimental.

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

    __queries__ = ['ExampleQuery']

    conn_default = LdapConnection(
        binddn="uid=example,ou=People,dc=example,dc=com",
        bindpw = "foobat")

    class ExampleQuery(LdapQuery):
        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 the two required classes for dealing with connections and queries.

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["ExampleQuery"]["admin_name"]}

Connection retry
++++++++++++++++

If the LDAP server is down during a request, the LDAP plugin tries to reconnect after a
short delay. By default, it waits 3 seconds during the retries and tries to reconnect
up to three times.

If you wish, you could customize these values in your ``bcfg2.conf``::

    [ldap]
    retries = 3
    retry_delay = 3.0

Caching
+++++++

This module could not know, if a value changed on the LDAP server. So it does not cache
the results of the LDAP queries by default.

You could enable the cache of the results in your ``bcfg2.conf``:

    [ldap]
    cache = on

If you enable the caching, you have to expire it manually. This module provides a XML-RPC
method for this purpose: :func:`Ldap.expire_cache
<Bcfg2.Server.Plugins.Ldap.expire_cache>`.

Even without enabling caching, the results of the LDAP queries are cached, but are
discarded before each client run. If you access the Ldap results of different client, you
may get cached results of the last run of this client. If you do not want this behaviour,
you can disable the caching completely by setting it to ``off``.

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). If you use
   port 636 this module will use ldaps to connect to the server.

.. attribute:: LdapConnection.uri

   LDAP URI of the LDAP server to connect to. This is prefered over
   :attr:`LdapConnection.host` and :attr:`LdapConnection.port`.

   .. note::

      If you are using ldaps you may have to specify additional options
      for enabling the certificate validation or setting the path for
      the trusted certificates with :attr:`LdapConnection.options`.

.. attribute:: LdapConnection.options

   Arbitrary options for the LDAP connection. You should specify it
   as a dict and use the ``OPT_*`` constants from ``python-ldap``.

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"]`` (defaults to the class name).

.. 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, \**kwargs)

   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, \**kwargs)

   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)

.. method:: LdapQuery.get_result(self, metadata, \**kwargs)

   This executes the query. First it will call ``prepare_query()`` for you, then it will try
   to execute the query with the specified connection and last it will call ``process_result()``
   and return that return value.

If you use a LdapQuery class by yourself, you could pass additional keyword arguments to
``get_result()``. It will call ``prepare_query()`` and ``process_result()`` for you and
also supply this additional arguments to this methods.

Here is an example::

	__queries__ = ['WebPackageQuery']

	class WebSitesQuery(LdapQuery):
	    filter = "(objectClass=webHostingSite)"
	    attrs = ["dc"]
	    connection = conn_default

	    def prepare_query(self, metadata, base_dn):
	        self.base = base_dn

	    def process_result(self, metadata, **kwargs):
	        [...] # build sites dict from returned dc attributes
	        return sites

	class WebPackagesQuery(LdapQuery):
	    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 the ``WebPackagesQuery`` 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 LdapQuery to only
search below that DN.

You do not need to add all LdapQueries to the ``__queries__`` list. Only add those to
that list, that should be called automatically and whose results should be added to the
client metadata.