Viper - LDAP data structure

One of the very important elements in the whole system is data organization within LDAP. Until you get a hold of it and its implications, do not start introducing any changes, as often both names and positions of the entries are relevant.

(Technically speaking, Viper itself does not care about the tree structure. It's the set of dynamic behavior rules in slapd.conf that is configured to operate in the following structure.)

Here's the tree:

On the top level, we have three suffixes defined in slapd.conf: ou=dhcp, ou=defaults, and ou=clients.

(You'll notice that these do not look like the common LDAP DNs that end in something like "dc=example,dc=com". This is perfectly alright from the LDAP standpoint, offers us certain advantages, and should not be changed).

  • ou=dhcp: specialized suffix intended to be used only by the ISC DHCP LDAP-enabled server. It contains appropriate configuration which rewrites incoming queries (sent by DHCP) to the the form required to find the data and return it as expected back to DHCP.
    LDIF data for this suffix is in ldifs/1-dhcp.ldif

  • ou=defaults: suffix that is also generally not intended to be used for direct access. It contains various global-level default values, default entries and default attributes. Specifically, it defines the following subentries:

    • ou=hosts,ou=defaults: add global-default Debconf values here, such as cn=partman-auto/method,ou=hosts,ou=defaults

    • ou=templates,ou=defaults: same as ou=hosts, but it contains the template part of Debconf question

    • ou=objectClasses,ou=defaults: it is often useful to append an entry that belogs to a certain objectClass with some default attribute values, and this is organized under this tree. If you want entries of class dhcpHost to get appended some default values, add entry cn=dhcpHost,ou=objectClasses,ou=defaults, and list attributes there (this, of course, also requires an appropriate searchAppend rule in slapd.conf to actually trigger the append, it is not automatic behavior).

    • ou=partitioning,ou=defaults: this should contain various disk partitioning recipes used by Partman. By default, a couple recipes are created, corresponding to examples shown in Debian preseed files and Partman documentation. For example, we have "regular_root" and "regular_home" recipes.

    LDIF data for ou=defaults suffix and all in it is in ldifs/0-defaults.ldif, so you can read it to verify what we've just said.

    You'll note that some of the values in ldifs/0-defaults.ldif, especially extendedDescription, are often base64-encoded. This is required to preserve exact value of the key within LDIF file format, and should not bother you (extendedDescription is not important anyway). However, to really see what's in there, you can run base64 -d on the command line, paste base64-encoded value in there, and press Enter, Ctrl+D. Decoded value will be printed.

    Also, reading ldifs/0-defaults.ldif is useful to give you a feeling of how we achieve dynamic attribute values. The top and the bottom of the file contain many interesting and mostly self-explanatory rules that implement serious magic.

  • ou=clients: This is the primary suffix intended for direct access by all components or scripts that use LDAP (except DHCP, as explained above).

    The tree supports multiple clients (domains), and is organized like this (example of client "c1.com"):

    • o=c1.com,ou=clients: toplevel entry for a client. (Value of o= must be the chosen domain name of the client, not arbitrary string, to allow mapping of host's FQDN to a specific host under a specific client, and the client's starting point must be in o=DOM.AIN,ou=clients)

      • ou=defaults,o=c1.com,ou=clients: per-site defaults, must have subentries the same as global-level ou=defaults tree, so that mapping between site and global level is possible just by removing or adding last two components (o=c1.com,ou=clients).

        • ou=objectClasses
        • ou=hosts
        • ou=templates

      • ou=networks,o=c1.com,ou=clients: list of subnets and their parameters used by a client. (Currently only one network per client is supported. To have multiple networks, your best bet is to create them as multiple clients.)

        • cn=default: pointer to the actual subnet (cn=10.0.1.0 in this case)

        • cn=10.0.1.0

      • ou=hosts,o=c1.com,ou=clients: all host definitions

        • cn=h2: specific host, h2.c1.com. Host-specific configuration

          • cn=key/name: all Debconf keys for a host, host-specific level

      • ou=templates,o=c1.com,ou=clients:
        • cn=h2

          • cn=key/name

    LDIF data for client c1.com is in ldifs/c1.com.ldif.