To configure OpenLDAP, open the slapd.conf configuration file. Either /etc/ldap/slapd.conf or /usr/local/openldap/etc/openldap/slapd.conf or /usr/local/openldap/etc/ldap-2.3.x/slapd.conf, depending on how you opened it. You now need to:
configure the hdb backend. OpenLDAP can store data on the hard drive in different "formats". The default "format" is bdb. PigeonDeliver can use both bdb or hdb. If you plan to use PigeonAdmin, however, we strongly suggest you to use HDB.
add PigeonDeliver and PigeonAdmin schema files. The LDAP protocol uses "schema" files to understand the "structure" of a database. In order to use PigeonDeliver and PigeonAdmin, you must let OpenLDAP know the structure of the PigeonDeliver database.
initialize the OpenLDAP database, in order to insert the basic data needed for PigeonDeliver to start.
finally, start slapd.
Before going on with the following steps, make sure slapd, the OpenLDAP daemon, is not active and not answering queries, especially if you are using linux distributions that automatically start slapd after installation.
To stop it, try something like:
# /etc/init.d/slapd stopor, in alternative, something like:
# killall slapd(watch out that the above command will terminate all the slapd instances running on your machine).
You now need to configure the OpenLDAP backend and database. On my system, I had to add:
backend hdb checkpoint 1024 10 database "hdb" suffix "dc=foobar,dc=org" rootdn "cn=admin,dc=foobar,dc=org"to slapd.conf. Instead of "dc=foobar,dc=org", write your own domain name. If your domain name is foo.bar.org, you need to write "dc=foo,dc=bar,dc=org", which is your basedn (that will be necessary later on in this document). If you don't have a domain name, you can use something like "o=Your organization name". However, it is much better if you have a domain name. This name is just a "label" used to identify your system. You can write almost anything you like, it has no effect on your emails or PigeonDeliver usage. Make also sure:
there are no other "database" sections. In case there are, just remove all the corresponding lines.
if you have compiled openldap with support for dso modules, make sure there two lines like:
modulepath /usr/local/openldap/libexec/openldap moduleload back_hdb.lawhere the directory /usr/local/openldap/libexec/openldap is the directory where the file back_hdb.la can be found.
After the above steps, my slapd.conf file looked something like (note that lines starting with # are just comments):
include /usr/local/openldap/etc/openldap/schema/core.schema pidfile /usr/local/openldap/var/run/slapd.pid argsfile /usr/local/openldap/var/run/slapd.args # here, before my changes, I add something like: # database bdb # suffix "dc=my-domain,dc=com" # rootdn "cn=Manager,dc=my-domain,dc=com" # Instead of the above lines, I put the following: backend hdb checkpoint 1024 10 database hdb suffix "dc=foobar,dc=org" rootdn "cn=admin,dc=foobar,dc=org" # Those lines where already in the configuration file rootpw secret directory /usr/local/openldap/var/openldap-data index objectClass eq
%%TODO%% if you are going to run a big email service or you are going to have a lot of users, you may want to optimize the database parameters. Please consider adding a "cachesize" parameter and a couple more "indexes". Also remember that, if you have valuable data in your database, every time you change the indexing parameters you should run the "slapindex" command.
To add the PigeonDeliver schema files:
create a directory named "pigeonair", in /usr/local/openldap/etc/openldap/, the directory containing your configuration files.
put the pigeondeliver schema in the right place: copy the files in /usr/src/pigeondeliver-x.y.z/examples/schema/ in /usr/local/openldap/etc/openldap/pigeonair/, with something like:
# cp -a /usr/src/pigeondeliver-x.y.z/examples/schema \ /usr/local/openldap/etc/openldap/pigeonair
tell slapd about the new schema files, by adding the following lines in your slapd.conf configuration, right after the line "include .../core.schema", file:
## pigeonair required schemes include /usr/local/openldap/etc/openldap/pigeonair/generic.schema include /usr/local/openldap/etc/openldap/pigeonair/domains.schema ## modules schema include /usr/local/openldap/etc/openldap/pigeonair/mailStore.schema include /usr/local/openldap/etc/openldap/pigeonair/mailForward.schema include /usr/local/openldap/etc/openldap/pigeonair/mailHidden.schema include /usr/local/openldap/etc/openldap/pigeonair/mailAlias.schema include /usr/local/openldap/etc/openldap/pigeonair/mailAntivirus.schema include /usr/local/openldap/etc/openldap/pigeonair/mailNewsletter.schema include /usr/local/openldap/etc/openldap/pigeonair/mailSanitizer.schema include /usr/local/openldap/etc/openldap/pigeonair/mailVacation.schema include /usr/local/openldap/etc/openldap/pigeonair/mailAntispam.schema
To initialize the OpenLDAP database, there are two steps to be performed:
remove any file that may already be there. If you installed OpenLDAP from the .tar.gz, there will be an "example" database, almost useless. If you installed from your distribution packages, you may already have a "good" database. However, most linux distributions use bdb as the default backend, so you must recreate it anyway to switch to the new format.
create a DB_CONFIG file.
create the standard OpenLDAP root of the database.
create the PigeonDeliver entires, as needed.
To remove the current database:
make sure your slapd daemon is stopped, and no other processes are using it. You can either:
/etc/init.d/slapd stopor
killall slapd
make a backup of the current database, "just in case...". To backup your DB, run something like:
# slapcat > file.backup.ldiffIf you get an error like "Command not found", you didn't read the section %%TODO%% carefully. Please read it one more time, and make sure to run the command:
export PATH="/usr/local/openldap/bin:/usr/local/openldap/sbin:$PATH"
remove all the files in /var/lib/ldap/, with something like:
# cd /var/lib/ldap # rm -f *
The DB_CONFIG file is extremely important to OpenLDAP. It is not just a matter of performance: without a properly configured DB_CONFIG file, some versions of slapd and BDB would just hang, crash, or not work properly.
For a good DB_CONFIG file, I suggest you to start with the file /usr/src/pigeondeliver-x.y.z/examples/slapd/DB_CONFIG. Just copy it with something like:
# cp /usr/src/pigeondeliver-x.y.z/examples/slapd/DB_CONFIG \
/usr/local/openldap/var/openldap-data/
The only change I made to the provided DB_CONFIG file was to add the DB_LOG_AUTOREMOVE option, with something like:
set_flags DB_LOG_AUTOREMOVEYou can write the option wherever you like in the file. I just uncommented the corresponding option.
This option tells BDB and OpenLDAP to automatically remove log files as soon as they are no longer needed. By default, BDB leaves those files so you can back them up from a cron job, and in case your hard drive explodes, you can replay them saving all your data. However, there are many different ways to back your OpenLDAP data up, so, you probably do not need to use BDB infrastructures for catastrophic recovery.
In case you do not enable this flag, make sure you sometime either remove or backup all log.* files as indicated by the db4.2_archive or db_archive utility, which you must run with something like:
# cd /usr/local/openldap/var/openldap-data/ # db_archive log.0000000 log.0000001 [...]as shown above, this utility will return the list of log files no longer needed, that can safely be removed.
Now that you have your OpenLDAP ready to have a database and to answer queries, you need to start to populate the database.
You have two choices here:
use the script provided with PigeonDeliver
perform the steps manually
With the script provided with PigeonDeliver, you just need to run pd-ldap-init-root, which can be found in pigeondeliver-x.y.z/examples/slapd, with something like:
# cd /usr/src/pigeondeliver-x.y.z/examples/slapd # ./pd-ldap-init-root dc=foobar,dc=orgThe script will then prompt you for a password to be inserted into the database. Insert the password twice, and wait for it to complete. Note that while you type the password, nothing will be displayed on the screen. Note also that dc=foobar,dc=org is the basedn, as we wrote it in the slapd.conf configuration file (look to %%TODO%%).
If the script is succesful, you will see something like:
------ inserted root of OpenLDAP database. created - basedn: dc=pippo,dc=it, rootdn: cn=admin,dc=pippo,dc=it, password: [youknowit]on the screen (line has been split into multiple lines for readability purposes).
If you don't trust the script to add your data, or if the script fails for some reason, you can run the command:
# cd /usr/src/pigeondeliver-x.y.z/examples/slapd # ./pd-ldap-init-root -d dc=foobar,dc=org > /tmp/template.ldifthis command will save, in the file template.ldif, the data that would otherwise be added to your database (the -d parameter makes the difference).
If you then want to add that data by yourself, run the command:
# slapadd < /tmp/template.ldif
The most common error to encounter is due to the script not being able to find the needed commands. If you get an error like:
couldn't find an usable 'xxxxxx'first export and setup the PATH correctly, as indicated in the previous sections:
export PATH="/usr/local/openldap/bin:/usr/local/openldap/sbin:$PATH"
If you have troubles or you really want to do everything by hand, you can open the file pippo.it-base.ldiff in the directory /usr/src/pigeondeliver-x.y.z/examples/ldiff. In this file, you need to change all occurrences of dc=pippo,dc=it with your own base dn, watching out to change also 'dc: pippo' with 'dc: foobar'.
The final result should look something like:
dn: dc=foobar,dc=org objectClass: top objectClass: dcObject objectClass: organization o: nodomain dc: foobar structuralObjectClass: organization entryUUID: 49e67d38-c9c2-1029-908c-82c0a376e204 creatorsName: cn=anonymous modifiersName: cn=anonymous createTimestamp: 20051005080342Z modifyTimestamp: 20051005080342Z entryCSN: 20051005080342Z#000001#00#000000 dn: cn=domains,dc=foobar,dc=org objectClass: organizationalRole cn: domains structuralObjectClass: organizationalRole entryUUID: a4bffcb2-c9d0-1029-9a63-cb91ce934d26 creatorsName: cn=admin,dc=foobar,dc=org createTimestamp: 20051005094627Z entryCSN: 20051005094627Z#000001#00#000000 modifiersName: cn=admin,dc=foobar,dc=org
Once you changed that file, you can load the data into the database, with something like:
# slapadd < pippo.it-base.ldiff
After adding this file, you also need to create an administrator, by also adding the file: cn=admin,dc=pippo,dc=it-base.ldiff in this same directory. Before adding this file, however you need to open it with an editor and make some changes.
As before, you need to change every occurrence of dc=pippo,dc=it with dc=foobar,dc=org. After changing the dn, you also need to change the password of the administrator, unless you want to leave the default of 'pippo'. To change the password, run the command:
# slappasswdand type your password twice. slappasswd will encrypt your password and print it on the screen:
{SSHA}AfBntJxBBqCvH2rbYQ2UDDuE+JiS6lzI
copy this string and put it in the file, in
the userPassword field. The final result should
look something like:
dn: cn=admin,dc=foobar,dc=org
objectClass: simpleSecurityObject
objectClass: organizationalRole
cn: admin
description: LDAP administrator
userPassword: {SSHA}AfBntJxBBqCvH2rbYQ2UDDuE+JiS6lzI
structuralObjectClass: organizationalRole
entryUUID: 49e77bb6-c9c2-1029-908d-82c0a376e204
creatorsName: cn=anonymous
modifiersName: cn=anonymous
createTimestamp: 20051005080342Z
modifyTimestamp: 20051005080342Z
entryCSN: 20051005080342Z#000002#00#000000
note that the double colon (::) near userPassword
has been also replaced by a single colon.
To add this file, simply run the command:
# slapadd < cn=admin,dc=pippo,dc=it-base.ldiff
Well, if you got up here, now it should be quite easy. Just run something like:
# cd /usr/local/openldap/libexec # ./slapd #If we did everything right, we shouldn't have any message at all, anything else but our prompt back. In the log file, /var/log/daemon.log or /var/log/syslog, there should be something like:
Jan 14 12:45:00 localhost slapd[4639]: @(#) $OpenLDAP: slapd 2.3.18 (Jan 13 2006 22:21:14) $ ^Iroot@joshua:/usr/src/openldap/servers/slapd
Depending on your linux distribution, you may want to start slapd automatically at boot, adding something like:
/usr/local/openldap/libexec/slapdto the script executed at boot, and something like:
kill `cat /usr/local/openldap/run/slapd.pid`to your shoutdown scripts, in order to properly stop slapd before turning off your computer. This is especially important since every time slapd is not properly stopped, you need to recover your database.
To verify that the database is properly working, you can run a command like:
$ ldapsearch -b "dc=foobar,dc=org" -x \ -W -D cn=admin,dc=foobar,dc=orgwhich means: "please, search all records (ldapsearch) inserted in dc=foobar,dc=org (-b), since I am the administrator whose record in the database is cn=admin,dc=foobar,dc=org (-D) who will authenitcate using simple authentication (-x) and providing a password (-W) as soon as I will be asked to do so". If everything is working, you should now see all the records we just inserted.