delphij's Chaos


04 Dec 2005

HOWTO: upgrade OpenLDAP from a major release to another

Just for reference for future upgrades.

Today I managed to upgrade from OpenLDAP 2.2.29 to OpenLDAP 2.3.11. This is a large upgrade, so all and foremost thing is to backup. Additionally, to keep downtime as less as possible, build these stuff first!

On FreeBSD, the recommended way of installing third party software is to use ports(7). Note that OpenLDAP is separated into two ports, openldap2X-server and openldap2X-client, and building the server requires the client library, therefore, you can not easily do build on the production server (and this SHOULD be avoided anyway).

A solution is to use a separated box (or jail for smaller deployments, to build packages and use pkg_add to install them.

To backup the OpenLDAP installation, you need the /var/db/openldap-* directories, and your configuration files. This can be archieved by doing:

tar cvfj ~/backup-openldap-20051204.tar.bz2 /var/db/openldap-* /usr/local/etc/openldap

The backup is for safe. You only need them when you want to rollback to previous openldap release but don’t want to re-import the data again. Since different major release of OpenLDAP can change the database schema, do a export of the data:

slapcat > ~/backup-openldap-20051204.ldif

Now build the packages. This is a bit tricky, but not that hard. First, install portupgrade in the build environment:

cd /usr/ports/sysutils/portupgrade && make install clean

Then, set up your make.conf(5) configuration. Mine was:


The first line is to make sharing the ports tree around many boxes through NFS easier; The second and thrid has appointed the database format as Berkeley DB 4.3.x and use OpenLDAP 2.3.x series.

To be safe, now create a directory called “/usr/ports/packages” which will store all packages. In order to avoid conflicit between many build boxes you can specify an alternative one PACKAGES= in /etc/make.conf.

To build the necessary packages:

portinstall -rp openldap-server

And perhaps your other application, like postfix, etc.

Now, stop the services that you are running. Before this, make sure that the package could be easily reached through either HTTP/FTP or NFS, or upload these to your server through sftp(1) or zmodem.

For a jailed environment you may want to run this inside your jail (first use jexec to enter the jail from the host):

sh /etc/rc.shutdown

Now remove all installed packages, that is:

pkg_delete -a

Then, install your packages through pkg_add. To make this easy, I usually roll my own super port that works like misc/instant-server or so, and make a package for it.

Before you resume the services, you need to upgrade the database. First, remove all stuff found in /var/db/openldap-*:

find -type f /var/db/openldap-* -delete -print

Then, use slapadd to import the backed up data:

slapadd -l ~/backup-openldap-20051204.ldif

Now that you have everything ready to start the service again. Issue:

sh /etc/rc

Now things goes smoothly.