Running Icingaweb2 on Ubuntu 16.04.1 LTS

I recently installed and configured icingaweb2 on Ubuntu 16.04.01 LTS system.

The documentation to do this seems rather sparse, and what is out there doesn’t really take into account some apparent bugs that I found in Ubuntu 16.10. I don’t know why an LTS system should have these problems, but here they are.

The package for libzend-framework-php puts all of its PHP files into the directory /usr/share/php/libzend-framework-php – but PHP itself will not find these files. PHP needs to be configured to find these files, but looks in /usr/share/php/Zend instead.

It appears that PHP 7.0 is configured to handle this, but 7.1 and 5.6 are not. Rather than mess with it all the time, I moved everything to the already existing directory /usr/share/Zend. After that, PHP worked – I was using 5.6 on the basis that Icinga2 has compatibility problems with 7 – can’t say if that is true or not, but it is something to watch for.

I fixed the problem of /usr/share/php/libzend-framework-php this way:

cd /usr/share/php/libzend-framework-php/Zend/
mv ./* /usr/share/php/Zend/

That moves everything, but be aware that this “breaks” the package and updates will not happen correctly unless you move those too. You could create a link named /usr/share/php/libzend-framework-php and point it to the current directory, but what if the upgrade process removes everything in that directory? I wouldn’t recommend it.

Another problem was with the HTMLPurifier package. When it installs, everything named HTMLPurifier* is put into /usr/share/php. What this means is that all of the PHP files named HTMLPurifier.something.php are placed in the wrong directory.

You can fix this with:

cd /usr/share/php
mv HTMLPurifier.* HTMLPurifier/

Again, unless they fix this problem in upgrades, this will need to be done on future upgrades.

These problems really surprised me, as the LTS versions are supposed to be solid and get bugs fixed quickly. Problems like these should have been caught early on.

AppStream Error in Ubuntu 16.04 Xenial

I’d been seeing this error recently:

AppStream cache update completed, but some metadata was ignored due to errors.

According to a Q&A on AskUbuntu, this is the result of a bug in the app stream package.

The package has as of 24 December is not yet in the package updates for 16.04; therefore, to fix it one either needs to add it from the proposed repository or from the backports repository.

Once you’ve enabled the backports repository (which you may not have to do at all) you can specifically pull the package from backports with this command:

sudo apt install appstream/xenial-backports

Now instead of the default version 0.9.4, you should have the updated version (0.10.1 of this writing):

appstreamcli —version
AppStream CLI tool version: 0.10.1

To complete the process, you need to update the cache data:

sudo appstreamcli refresh —force

Then make sure to do an update and upgrade to get any missed updates:

sudo apt-get update
sudo apt-get upgrade

And clean up the last of the update by removing the now unneeded libappstream3:

sudo apt-get autoremove

This should fix the problem once and for all.

Installing Xubuntu 15.04

I installed Xubuntu onto a SSD recently, and and some things I had to work through.

One big one was the setting up of the system to be able to handle foreign language input. There were a couple of problems here.

First, there are several aspects and they get confused and mixed together frequently:

• Language
• Regional preferences
• Keyboard layout
• Input method

The first place one might go to is the Language preferences; however, this only sets the desktop and application language, such as in menus, menu bars, application dialogs, and so forth. This sets the language of the system, nothing more. It is relatively straight-forward to add languages here: click on the Install/Remove Languages button and place a checkmark on the ones you want and remove it from those you don’t.

The next place one will probably check or think to check is the Region settings for date, time, numbers, currency, and related. For example, in North America a number might be shown as 250,000.00 – whereas in Europe, one would see 250.000,00 for the same number.

Chances are, once you set your region to what you use locally, this won’t change even if the language you are using does.

Then the problem of how to type in a foreign language comes up. Not much use to a language if you can’t type in it, right? For me, the challenges in this case are French, Esperanto, Japanese, and Russian. Definitely not your typical mix!

French was the easiest. Since the French use the Latin alphabet, like English, the question was how to make the French accents. There is no way on the normal keyboard to do this. Using a French keyboard makes it easy, but I don’t have one – but rather the typical US keyboard. What to do?

There are two possible fixes – the AltGr or Compose method, and the dead keys method. I chose the dead keys method. What this does is makes some of the standard keys act like modifiers, providing the accents necessary for French and similar languages (it works for Esperanto, for example). To use a dead key like the single quote, double quote, back-quote, or tilde, you type it and then the character desired. For example, consider the French verb éspèrer, the Esperanto word ĉe, or the Spanish word señor – all created with the US keyboard with dead keys.

You set this up using the Keyboard setting panel. Add a new layout, and choose the English (US, international with dead keys) layout. There is also a English (UK, international with dead keys) layout, as well as the English (US, international with AltGr keys) layout alluded to before. I have not tried those.

Now with this keyboard added, this will make the accented Latin characters available to you. The Change Layout Option shortcut makes it easy.

However, this leaves Russian and Japanese as a final challenge. Both require a modification to the input method – but there is no input method configuration or set up on Xubuntu. Input methods on Xubuntu use something called iBus – which can be installed from the command line:

apt-get install ibus

What this does is to install iBus using the standard Xubuntu packaging system. IBus can be installed with the Ubuntu Software Center: add the item called Keyboard Input Methods.

To get the system set for Japanese, add a product called Anthy:

apt-get install anthy

This should install the Anthy setup and configure it for you. You need to log out and back in to make Anthy active and operational.

After a relog, go to the Language Support setting panel and choose IBus for the input method. Then go to the Keyboard Input Methods panel and select the Input Method tab, and add the appropriate language input methods. I added the following:

• Japanese – Anthy
• Russian – Russian Phonetic

Close that out and you should have the input methods available to you. Note that having English, English with dead keys, Japanese (Anthy) and Russian available makes life a bit complicated.

You can switch input methods using the shortcut defined within the Keyboard Input Methods panel. The default is <super>space which works well. If you wish to have a shortcut to be able to change keyboard layouts, make sure it doesn’t conflict with the shortcut for input methods or any other.

Anthy allows you to be able to input Japanese with a standard US keyboard layout (with or without dead keys). It uses the phonetic spelling to create hiragana: typing ohio generates おひお for instance. Using Anthy is pretty straight-forward, and I won’t cover it here.

Using the Russian input method acts more like a “new” keyboard layout – which can make things a little confusing, but not too much. It allows you to type Russian using the keyboard phonetically – so the Latin letters are mapped to their Russian equivalents: typing pa-russki generates па-русски for instance.

You can add the keyboard layouts (not input methods!) to the Xubuntu panel easily: right-click on an item on the panel, and select the menu item Panel… then Add New Items. If you see something totally unrelated – select a different item to right-click on the panel. Look for Keyboard Layouts and add that to where you want it on the panel.

The interaction between the input methods and the Keyboard Layouts panel is a bit interesting. I have four input methods that I can select: English (US), English (US, international with dead keys), Anthy, and Russian (phonetic). Selecting one of the English options selects that keyboard layout and shows an English flag in the Keyboard Layouts panel. Selecting Anthy shows an English flag as well – using the English keyboard to generate Japanese. Selecting Russian shows the Russian flag and generates Russian.

There is also the once popular SCIM method of input – this is still supported but it appears that IBus is the future, and SCIM was not tried.

It should be a lot easier to support only French or Japanese or Russian – but now you know how, and supporting all three is doable. Once again, Linux and Ubuntu show their high-quality support for international languages.

Converting a Red Hat Linux 5.8 install to CentOS

Recently, we wanted to convert from Red Hat Enterprise Linux to CentOS. CentOS is a build of Red Hat Enterprise Linux from all of the open source packages that are released by Red Hat. There are a number of instructions in this regard, but the overall process is the same. My conversion was a Red Hat Enterprise Linux 5.8 to CentOS 5.8.

I started by following these instructions from saylinux.net (or thuannvn.blogspot.com). However, I had to adjust the instructions for RHEL 5.8 – just look in the directory on mirror.centos.org for the proper version of the packages you need. You won’t be able to use yum to download the packages because you want to pull not from RHEL but from CentOS – and yum will be getting updated as well.

Firstly, do a cleanup:

yum clean all

Then, create a working space where RPMs can be downloaded:

mkdir ~/centos
cd ~/centos

Now download the relevant CentOS key and import it:

wget http://mirror.centos.org/centos/RPM-GPG-KEY-CentOS-5
rpm --import RPM-GPG-KEY-CentOS-5

Then, get relevant packages from CentOS – note these instructions will pull i386 packages or x86_64 packages depending on your system:

wget http://mirror.centos.org/centos/5/os/`uname -m`/CentOS/centos-release-5-8.el5.centos.i386.rpm
wget http://mirror.centos.org/centos/5/os/`uname -m`/CentOS/centos-release-notes-5.8-0.i386.rpm
wget http://mirror.centos.org/centos/5/os/`uname -m`/CentOS/yum-3.2.22-39.el5.centos.noarch.rpm
wget http://mirror.centos.org/centos/5/os/`uname -m`/CentOS/yum-updatesd-0.9-2.el5.noarch.rpm
wget http://mirror.centos.org/centos/5/os/`uname -m`/CentOS/yum-fastestmirror-1.1.16-21.el5.noarch.rpm

You don’t have to use wget either; you could – if you want – instead use a text browser like elinks to get the same packages. Using elinks allows you to get the most recent version without stumbling over the version number – if the package is updated, you don’t have to guess at the version numbers in the filename.

elinks http://mirror.centos.org/centos/5/os/`uname -m`/CentOS/

Delete unnecessary packages from RHEL – in particular, those that use the Red Hat Network (RHN):

rpm -e yum-rhn-plugin rhn-client-tools rhn-setup rhn-check rhnsd

If there are any other packages that require yum-rhn-plugin or related packages, add it to the list of packages to remove.

Now update all of the packages that were downloaded:

rpm -Uvh --force *.rpm

Lastly, perform an upgrade to fully update the system from the new CentOS repositories:

yum upgrade

For best practices, you probably should reboot here as well – thus loading new libraries, deleting old files, and activating new kernels.

Moving a VMware ESXi 4.0 Guest From One Host to Another

To move an ESXi 4.0 guest is not all that hard – but you must be aware of several things along the way. Taken one step at a time, it won’t be difficult. In this discussion, we assume that you are moving from one ESXi 4.0 host to another – both with the same architecture. (Anything other than that gets much more complicated.)

First, make sure there are no snapshots. Snapshots are not compatible with this process and must be eliminated altogether.

Then, shut down the guest system. We don’t want the guest changing as it is copied across.

The next step is to copy the guest files from the original host to the destination host. This is the longest step considering you probably have gigabytes of data to transfer. This is also done from the ESXi command line.

I would normally use rsync but it doesn’t exist on an ESXi 4.0 system; use scp to copy the files. Your files for the guest should be located in /vmfs/volumes/datastoreX/guest/ where datastoreX is the data store containing the guest and guest is the name of the guest host. If you renamed the host in one of the GUIs such as VSphere Client, then this will reflect the original name.

Make a directory in the remote host (using the ESXi command line interface) in one of the data stores, and then use commands like these from the original host:

cd /vmfs/volumes/datastoreX/guest
scp * remotehost:/vmfs/volumes/datastoreY/guest/

This will copy the files to the remote host.

However, copying is not enough. Log into the remote host and go to the place you copied the files to. Check over the file ending in .vmx for any references to disks that must be changed. Convert remote host paths to local disk paths – you will probably need to know the long hexadecimal path for any paths, so list that before you start editing. If you execute a cd command to the directory containing the guest host, the long path will be in the prompt.

Next you must register the host so the system knows about it. Use this command at the command line to do this:

vim-cmd solo/registervm /vmfs/volumes/datastoreY/guest/guest.vmx

Now, to get the host started: start the host from VSphere Client. The client will give you a question to answer about where the guest came from. Click on the guest’s Summary tab and select I copied it. (which should be the default) and click Ok.

The guest will start up – and discover that the MAC address of its network interface has changed. For Linux, this means a new ethernet interface, and the configuration of the old interface is ignored: that means that there will be no network connectivity. Enter the console and change the old configuration from eth0 to eth1 (or whatever is appropriate; find out with ifconfig -a). This change varies by which Linux distribution you use; for Ubuntu, the configuration is in /etc/network/interfaces.

While you don’t have to reboot, it doesn’t hurt to do so after this change – and it tests the system in a clean reboot. The system should start up cleanly.

Now don’t forget to remove the original. Using the VSphere Client, right-click on the host and select Delete from Disk. This will remove the guest host entirely from the system and delete all of its files. If you want to retain the files, instead select Remove from Inventory which essentially unregisters the host, so that the system is not managing it – but the disk files remain.

Window Manager and xcompmgr

In my current Window Maker configuration, I use xcompmgr to create some nice shadows for the windows. The problem is that xcompmgr sometimes doesn’t realize that a window has closed, and thus the shading remains while the window is actually no longer there. It is possible to “fix” this problem by reopening the window and closing it, but this is ot workable: the only workable work-around is to restart xcompmgr; since xcompmgr is small and fast, this is not a problem.

There are a number of ways to automate this…

Currently, xcompmgr is started in ~/GNUstep/Library/WindowMaker/autostart:

xcompmgr -c -C -r 8 -l -12 -t -12 &

To make it easy to restart xcompmgr, let’s put a program around it that automatically starts the program again if it dies. Since xcompmgr does not go into the background, we can just start it up and when it exits, restart (in a loop).

With Ruby, we can do this:

#!/usr/bin/ruby
#
# xcompmgr2: run xcompmgr and keep it running:
#            permits autorestart of xcompmgr

# Get rid of any programs already running...
`pkill -x xcompmgr`

while (1==1) do

    # Main program: run it!
    `/usr/bin/xcompmgr -c -C -r 8 -l -12 -t -12`

    # Catch and log unusual exitstatus...
    if ($?.exitstatus != 15 && $?.exitstatus != 0) then
        # Not good
    end
end

If xcompmgr exits for any reason, it loops again in the infinite loop. This sort of program could be done in almost any language: certainly Perl, ksh, and PHP are up to the task (as are many others).

Thus, when xcompmgr gets confused, do this command to fix it:

pkill -x xcompmgr

The -x option makes it so that xcompmgr is killed, and not xcompmgr2: -x matches a command name exactly.

Choosing Your Linux Distribution

For enterprise servers, the choices are (basically) easy: Red Hat Enterprise Linux, SUSE Linux Enterprise, or Ubuntu Server – all very good environments with good support from their companies and supported by various hardware manufacturers. What about your desktop?

The choice is usually easy: most of us choose one of the common distributions – like Fedora, OpenSUSE, Ubuntu, Debian, or Linux Mint. What if you want to stretch a little – try something more avant-garde?

You must define your boundaries – what do you want to have or to accomplish? Here are some possibilities:

• Do you want to build the software from source?
• Do you want extensive packages already built?
• Do you want to start from a minimal system and build up?
• Do you want run on old or minimal hardware?
• Do you want stable releases or a rolling release?
• Do you want a full-featured desktop?
• Do you want to run Linux?
• Do you want to run Flash, MP3, DVDs, etc.?
• Do you want to configure everything yourself?
• Do you want to build everything yourself?
• Do you want a special purpose distribution (e.g., penetration testing, multimedia, scientific, etc.)?

I find myself in the situation of trying to fix some hardware which requires installation of a new system – thus, I thought I would try something new. My criteria are:

• Support for lots of packages
• Everything mostly works on install
• Window manager other than GNOME or KDE
• Good security
• Good support for Java, DVD, MP3, and Flash
• Not mainstream
• Actively supported and with active community

So far, the choices seem to be:

• Linux Mint Debian Edition (LMDE)
• aptosid
• Sabayon
• CrunchBang
• Linux From Scratch

Almost all of these are based on Debian unstable or testing; Sabayon is based on Gentoo, and LFS is based on nothing at all…

I’ve always wanted to try a Linux that had the equivalent of FreeBSD’s ports tree…

A First Attempt with Arch Linux

Having heard great things about Arch Linux, I thought I would give it a try. I’ve enjoyed trying different Linux versions over the years, and have found some good environments.

Unfortunately, Arch Linux is not one of them – at least judging according to my initial installation.

The initial install gives you a text-based environment – no GUI here. This can be almost forgivable – but the installation had some hiccups. If you decide to install Arch Linux, don’t select anything other than the core resource: adding extras will only cause things to break. Stick with your CDROM installation media and forget the rest.

Then, after installation, there are a number of tasks to do. As long as you stick with the Beginner’s Guide, all should work just fine. The problems begin when you get into the extras. Most of these problems have solutions; however, one should not come across one problem after another.

Here are the problems I’ve experienced in just a few hours time after initial installation:

• xdm spawning too many times; pausing for 5 minutes – this because xdm wasn’t installed but /etc/inittab was trying to start it.
• package conflict with /etc/mtab
• package conflict with /etc/profile.d/locale.sh
• configuration of Window Maker overwrites ~/.xinitrc
• configuring PAM to use ecryptfs didn’t work
• encrypting home directory appears to have encrypted ~/Private and not ~
• ecryptfs documentation is obsolete
• running XDM loops back to login screen after successful login
• running GDM fails
• sudo wasn’t part of the main install
• a new user wasn’t part of the main install
• the documentation for adding a new user puts the user in the wheel group if you do it manually – but not if you do it with useradd
• during installation, old install messages are not removed
• perl is not part of the base install
• X installs with a network listener active

The two biggest problems are the following:

1. Bugs are just documented, not fixed.
2. Nothing is configured!

When a package is installed, it should be ready to go – it should “just work.” Nothing “just works” on Arch. It is one thing to let us choose which packages we want and how we want; however, there should not be a day’s worth (or more!) of work to get things working. Every package seemed to have bugs and things that didn’t work right – and needed special instructions to configure it.

To do anything with Arch, it requires a huge effort to install a large number of packages – and to hand-configure most. It is a minimalist distribution that is built up to be what someone wants. However, I thought their choice of simplicity quotes was ironic:

Perfection is achieved not when there is nothing more to add, but rather when there is nothing more to take away.

I say ironic because there is nothing that can be taken away from Arch Linux; packages must be added.

This is a big disappointment; I had such high hopes for Arch Linux. I thought it would be an simpler version of Gentoo or Slackware; not so.

OpenLDAP with SSL in Ubuntu Lucid Lynx

In researching configuration tasks for OpenLDAP, I found this article about using sudo with OpenLDAP. As I am going to implement SSL with OpenLDAP, problems with sudo and SSL could be fatal, so I decided to investigate further.

It turns out that the problem is embedded in GnuTLS, a GPL-licensed OpenSSL replacement. GnuTLS was used by Debian because of a licensing conflict between OpenSSL and OpenLDAP. A backend library used by GnuTLS (libgcrypt11) causes problems based on the way it is initialized and the way it handles the dropping of privilege (that is, it gets rid of its “root” access). This shows up as suid applications failing when run against LDAP users; Ubuntu bugs 926350 (GnuTLS) and 423252 (sudo) are this exact problem.

GnuTLS is replacing libgcrypt11 with the nettle backend as of 2.11.x, but Ubuntu Lucid Lynx continues to use GnuTLS with the original (flawed) backend. The “fix” espoused by some is to use nscd – but this is acknowledged to be a workaround.

There is a GnuTLS version compiled not against libgcrypt11 but libnettle which should the problem. I did not test this PPA; if you wish to stick with OpenLDAP and GnuTLS this might be the way to go.

However, there is also a version of OpenLDAP compiled against OpenSSL. Add the PPA to your APT configuration and then perform a system update (apt-get update && apt-get upgrade). This will upgrade your OpenLDAP and cause it to stop at least temporarily; thus, make sure you allow for some server downtime.

This version of OpenLDAP works except for a few initial problems that must be overcome. When you first install, it may refuse to run.

First, it seems to add an openldap user and group – and while this is good, it does not completely change appropriate files to give access to the openldap user. There are two locations that need to be fixed:

• /var/lib/ldap (the location of the LDAP data store)
• /etc/ssl (the location of the SSL certificates)

Fixing the first is simple:

chown -R openldap:openldap /var/lib/ldap

The second is not as straight-forward; in my case, I added the user openldap to the group ssl-cert which has access into the /etc/ssl directory and subdirectories. Use the vigr command to make this happen: add openldap to the end of the ssl-cert group line (your group id might be different):

ssl-cert:x:108:openldap

Note that if the SSL certificates aren’t set up right, then running the new OpenLDAP will not work – even if LDAPS is not enabled at startup. (There is a fantastic message showing how to make sure your certificates match from OpenVPN.net.) You also need to make sure that the certificates are not expired; it is reported that OpenLDAP will also fail to start with expired certificates.

As the final step, change the /etc/default/slapd file to start LDAPS:

SLAPD_SERVICES="ldap:/// ldapi:/// ldaps:///"

Eventually, the best thing to do is to remove LDAP support entirely (and use LDAPS completely):

SLAPD_SERVICES="ldapi:/// ldaps:///"

Tips and Tidbits About LDAP

Setting up and understanding LDAP is not easy. In my opinion, nothing is obfuscated more and unnecessarily so than LDAP. There are a number of tips that can help you to understand LDAP.

LDAP is not authentication. This was the number one problem I had when I started (a while back). The first time user might search for documents on setting up LDAP when in fact they are looking for documents on how to set up UNIX and Linux authentication using LDAP. An LDAP server at its most basic doesn’t understand UNIX uids, doesn’t understand GECOS fields, doesn’t understand UNIX gids, and doesn’t understand Linux shadow files. Support for all of this must be added.

Support for UNIX authentication must be added. You would think that the most common usage for LDAP would come bundled and ready to go with the server; however, often this is not the case. Even if it is the case, you may find that for certain capabilities you are expected to add new LDIF files to support the fields in LDAP.

LDAP is not just another database server. Virtually everything in LDAP has a different name; it is unlike anything you’ve done before. Take heart: X.500 (where LDAP comes from) was worse. You’ll have to slog through a pile of new terms, but after a while it will become easier to understand.

OpenLDAP is not synonymous with LDAP. There are other servers out there. OpenLDAP does come with virtually every Linux platform; there are however, many others – many of which may be easier to use. There is the 389 Directory Server from Red Hat, the ApacheDS (part of the Apache Directory Project) from Apache, and OpenDJ from ForgeRock. OpenDJ itself is a spin-off from OpenDS, originally from Sun.

OpenLDAP is known for making non-backwards-compatible changes. The most recent example is the complete replacement of the configuration system.

OpenLDAP no longer uses slapd.conf. This will cause you no end of problems: there are a lot of people trying to explain how to set up OpenLDAP, and with a single strike (as of version 2.3) OpenLDAP made all of that documentation obsolete and useless. This is incomprehensible, but it is a fact.

Using and administering LDAP requires command line expertise. This is basically true, but like many things, it is not the complete truth. There are many programs designed to make it easy to browse LDAP stores, along with editing capabilities. Some of the more interesting products include Jxplorer, Luma, and the Apache Directory Studio. Of these, the Apache Directory Studio is the most capable, robust, and actively developed – and by far the largest.

Some LDAP entries can be present more than once or have more than one value. If you are comparing LDAP to a database, then this will come as a surprise. One valuable example is UNIX groups: the original UNIX systems only had one group per user; later, secondary groups were added – thus presenting a single user with multiple groups. This is handled in LDAP in a variety of ways, but they all amount to having multiple entries with different values.

Limiting user logins by host is not available in LDAP. This capability is most likely to be done by using the client host. There are a number of ways to do it, but all require LDAP client configuration, and all are limited in their application. Without client configuration, all LDAP users will have authenticated access to the host.

Be prepared to do a lot of web searches for documentation and solutions. The best places to go for searches are: Google (of course) and Ubuntu Documentation.

There are also very good articles and documents on using LDAP for authentication. There is an article about OpenLDAP authentication on FreeBSD (FreeBSD articles tend to be very well-written). Similarly, Ubuntu documentation is well-written as well; each of the Ubuntu versions has a section in the documentation on using and configuring OpenLDAP for authentication. Ubuntu 11.04 documentation has a good article on OpenLDAP for example.

Ubuntu documentation also includes a lot of well-written (and current) articles. For example, there are articles on OpenLDAP Server (a general article), LDAP Client Authentication, Samba and LDAP (from the 10.04 Server documentation), and Securing OpenLDAP Conenctions. If you plan to use 389 Server instead, there are even a couple of articles on using it with Ubuntu: Fedora Directory Server (the original name of 389 Server) and Fedora Directory Server Client Howto.

A nice overview of LDAP comes from Brian Jones at O’Reilly: specifically, his 2006 articles on Demystifying LDAP and Demystifying LDAP Data. Linux Journal also has myriad different articles on LDAP (not to mention an OpenLDAP theme for the December 2002 issue). Linux Journal also has an article from 2007 on Fedora Directory Server (now 389 Server).

Lastly, an excellent resource is the “book” LDAP for Rocket Scientists from Zytrax.com. You simply must go and read portions of this book. One very apt quote from the introduction to the book which sums up the state of LDAP documentation generally:

The bad news is that [in our humble opinion] never has so much been written so incomprehensibly about a single topic with the possible exceptions of BIND and … and …

(It should be noted that the other book at Zytrax is about DNS. Is it any surprise?)

UPDATE:

Yet another trick to LDAP:

The cn= attribute is not solely a leaf attribute. This can be seen in OpenLDAP’s cn=config tree with OpenLDAP configuration. For example, a typical admin user can be designated like so:

cn=admin,dc=bigcorp,dc=com

However, when you use OpenLDAP’s configuration, the designation for the admin user is this:

cn=admin,cn=config

When you look into the configuration tree, there are more cn= entries – like this:

cn={4}misc,cn=schema,cn=config