Home|Cudeso|Linux|*NIX / BSD|Misc|
 

LDAP

Contents

1. Introduction

2. Useful resources

3. Getting the package

4. DB4 - Berkeley DB

5. Cyrus-SASL

6. OpenLDAP

7. Configuration

8. Start / Stop

9. Initial data

10. Filling the directory

11. Schema definitions

12. GUI-tools

13. Outlook / Outlook Express

14. Evolution





1. Introduction

What is LDAP? I quote the OpenLDAP-home page :
LDAP stands for Lightweight Directory Access Protocol. As the name suggests, it is a lightweight protocol for accessing directory services, specifically X.500-based directory services. LDAP runs over TCP/IP or other connection oriented transfer services.
This document is not intended as a guide for LDAP for authentication, dhcp or user-collections. I wanted an easy and speedy solution that could contain my contacts (addressbook) in one central location. I first considered a PHP-solution but that would be like rebuilding a mail-client and wasn't worth the effort. LDAP, in the way that I'm using it, serves well and does the trick fast.

2. Useful resources

Off course, you can pay a visit to the OpenLDAP homepage at http://www.openldap.org. Beside the Administrator Guide I found http://www.direct-to-linux.com/TUTORIALS/LinuxTutorialLDAP.html very useful.

3. Getting the packages

First you can start downloading LDAP from http://www.openldap.org/software/download/. The additional packages are : I will not cover the installation of OpenSSL, it's up to you to get it right.

4. DB4 - Berkeley DB

We will start with the first component, the database-backend. I choose for DB4 from Sleepycat Software. OpenLDAP supports a wide variaty of database backends but for some reason DB4 seemed like the logical choose.
I assume you already have the package. Move it to your source directory, unpack it and build it.
tar zxvf db-4.1.25.tar.gz
cd db-4.1.25
cd build_unix
../dist/configure
make
make install (as superuser)
By default the db-tools are located in /usr/local/BerkeleyDB.4.1/bin/. This makes no sense for me and therefore I made some symlinks so that these binaries reside in the 'default' locations.
ln -s /usr/local/BerkeleyDB.4.1/bin/db_archive /usr/local/bin/db_archive
ln -s /usr/local/BerkeleyDB.4.1/bin/db_archive /usr/bin/db_archive
... and this for every binary in /usr/local/BerkeleyDB.4.1/bin/
If you have any installation from rpm, you will need to manually adjust the libraries.
ln -s /usr/local/BerkeleyDB.4.1/include/db.h /usr/include/db.h
ln -s /usr/local/BerkeleyDB.4.1/include/ /usr/local/include/db4/
ln -s /usr/local/BerkeleyDB.4.1/lib/ /usr/local/lib/db4/
The first symlinks is for the db.h file. Replace the old symlink by the new one. The second and third symlink allows the configure script of LDAP to find the right include-files and libraries.

Afterwards, update ld.so.cache with
ldconfig

5. Cyrus-SASL

SASL is the Simple Authentication and Security Layer. At first this option was not selected, but the OpenLDAP Admin Guide states that the system "will not be fully LDAPv3 compliant unless it detects a usable Cyrus SASL installation. So ... who are we to complain? Installation is fairly easy.
tar zxvf cyrus-sasl-2.1.14.tar.gz
cd cyrus-sasl-2.1.14
./configure --with-bdb-libdir=/usr/local/BerkeleyDB.4.1/lib
            --with-bdb-incdir=/usr/local/BerkeleyDB.4.1/include/
            --with-openssl=/usr/local/ssl/
make
make install (as superuser)
Just like with DB4 we need to add a symlink for the library.
ln -s /usr/local/lib/sasl2/ /usr/lib/sasl2
Make sure that /usr/local/include/sasl is readeable by group and world!

6. OpenLDAP

As with the other stuff, unpack it, move to the newly created directory and configure the 'thing'.
tar zxvf openldap-openldap-2.1.21.tar.gz
cd openldap-2.1.21
env CPPFLAGS="-I/usr/local/include -I/usr/local/include/ssl -I/usr/local/include/db4"
    LDFLAGS="-L/usr/local/ssl/lib -L/usr/local/lib/db4"
    ./configure --with-tls --with-cyrus-sasl --enable-wrappers --enable-crypt --enable-bdb
make
make test
make install (as superuser)
The env directive sets some environment variables so that the configure scripts finds the right libraries and header files. Check with the man page for a detailed description. Normally a setting for CPPFLAGS of /usr/local/include would be enough but for some reasen it didn't work ... therefore... I changed it to the one above.

7. Configuration

The main configuration file for OpenLDAP is /usr/local/etc/openldap/slapd.conf.

This configuration file can be quite lengthy and complex but for my purposes (that is, only serving as a central contactbook) it is fairly easy.
include /usr/local/etc/openldap/schema/core.schema
include /usr/local/etc/openldap/schema/cosine.schema
include /usr/local/etc/openldap/schema/inetorgperson.schema
include /usr/local/etc/openldap/schema/officeperson.schema

### SSL-certificates
TLSCACertificateFile /usr/local/ssl/certs/ca.crt
TLSCertificateFile /usr/local/ssl/certs/ldap.crt
TLSCertificateKeyFile /usr/local/ssl/certs/ldap.key

### Database definitions
database    bdb
suffix      "dc=example, dc=com"
rootdn      "dc=example, dc=com"
rootpw      secret
directory   /usr/local/var/openldap-data
index       objectClass eq
The first 4 lines contain the schema's that I use for my addressbook. The core.schema, cosine.schema and inetorgperson.schema are installed by default with OpenLDAP. The officeperson.schema is available through ftp at ftp://ftp.kalamazoolinux.org/pub/projects/awilliam/misc-ldap/officeperson.schema. Be careful when adding many schema's because they can either conflict with eachother or can call other schema's that are not valid for your situation.

The three lines starting with TLS define my SSL certificate-settings. I don't like it when my data goes un-encrypted through the wire, so I wanted SSL. Installation and creation of the certificate goes as follows :
openssl req -new -x509 -nodes -keyout /usr/local/ssl/certs/ldap.key -out /usr/local/ssl/certs/ldap.crt
openssl genrsa -des3 -out /usr/local/ssl/certs/ca.key 1024
openssl rsa -in /usr/local/ssl/certs/ca.key -out /usr/local/ssl/certs/ca.key
openssl req -new -x509 -days 365 -key /usr/local/ssl/certs/ca.key -out /usr/local/ssl/certs/ca.crt
Make sure that you enter the name of your machine (or at least, the fqdn which you're using to address your LDAP-directory) as the CN (Common Name).

The other configuration that's in use by OpenLDAP is ldap.conf. I have not changed a lot in this file.
HOST 192.168.0.5
BASE dc=example,dc=com
URI ldaps://ldap.example.com
TIMELIMIT 25
SIZELIMIT 12
TLS_REQCERT allow
Do not forget to add TLS_REQCERT because otherwise you won't have access to the ldaps server from the command-line (at least, I couldn't find out how to connect with user-certificates).

8. Start / Stop

The default install places the ldap binary in /usr/local/libexec. For starters, you can start the ldap daemon in debug mode.
/usr/local/libexec/slapd -4 -d -1 -f /usr/local/etc/openldap/slapd.conf -h "ldaps:///"
This will start the ldap daemon, listening only for IPv4, showing all debug messages, using the configuration file at /usr/local/etc/openldap/slapd.conf and only running in SSL-mode.

Stopping the server goes with
kill -TERM <pid-slapd> (fill in the pid for the slapd process)

9. Initial data

Before we can enter any data, we need to create the objects that will contain our data. All data that gets in the ldap-directory comes in the form of an ldif file. This is a regular textfile than can be edited with your favorite editor.
dn: dc=example, dc=com
objectclass: top
objectclass: dcObject
objectclass: organization
o: example
dc: example

dn: ou=addressbook, dc=example, dc=com
objectclass: top
objectclass: organizationalUnit
ou: addressbook
Please take care that there are NO TRAILING SPACES because this will render your ldif file useless. Read this again.
I've found my self shouting "what the f**k" after receiving an error like "no emech found" ... just to found out that there was one space to many.

You can add this definition to the directory with
ldapadd -x -W -D 'cn=Manager,dc=example, dc=com' -f myfile.ldif -H "ldaps://ldap.example.com"
The x allows simple authentication; W asks for the password; D binds to the DN; f defines the file to use and H passes the LDAP URI to the LDAP-server.

10. Filling the directory

As with initial data, filling the directory goes the same way with ldif files.

Before you start entering data, you need to decide what information to store for each entry. Once you know that, you can map your needs to the right LDAP attributes.

Every entry you add requires a DN that should be unique. For my purposes I will use the commonname (CN) attribute. My entry would be something like this :
dn: cn=Koen Van Impe, ou=addressbook, dc=example, dc=com
When this DN is defined you can go ahead and add other attributes. When you enter data in the directory (attached to an attribute), this data gets collected upon request of a client application. These attributes gets matched depending on the implementation of LDAP for that specific application. Because every application needs other attrbiutes and not all attributes are matched well, it can be quite hard to get a good attribute listing. For this purpose I've added my results when comparing Evolution and Outlook to the next section. I must say that, allthough Evolution is a far better e-mail and calender client than Outlook it lacks a good LDAP-implementation. Some attributes get matched falsely, others don't get matched at all.

You should check your schema files (in /usr/local/etc/openldap/schema) for a good list of all available attributes. This is my example entry :
dn: cn=John Foo, ou=addressbook, dc=example, dc=com
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: officePerson
cn: John Foo 
gn: John
sn: Foo
mail: john.foo@example.com
postalAddress: Green Street 5
title: Uhh?
l: Brussels
o: cudeso.be
ou: Software
postalCode: B-1000
telephoneNumber: +32-2-xxx.xx.xx
mobile: +32-xxx-xx.xx.xx
homePhone: +32-2-xxx.xx.xx
URL: linux.cudeso.be
displayName: cudeso
initials: jf
c: Belgium
Adding this entry (saved to the file entry.ldif) to the directory goes like this :
ldapadd -x -W -D 'dc=example,dc=com' -f entry.ldif -H "ldaps://ldap.example.com"
After entering your password, it should be available through a simple search-operation (which will return everything).
ldapsearch -H "ldaps://ldap.example.com" -D 'dc=example,dc=com' -x -W

11. Schema definitions

keycontentOutlookEvolution
cnFull namexx
gnFirst namexx
snLast namexx
mailE-mailxx
physicalDeliveryOfficeNameOfficex-
postalAddressAddressStreet AddressAddress
titleJob titlexx
lCityx-
oOrganizationxx
ouDepartmentxx
stStatex-
postalCodePostalcode (business)x-
telephoneNumberTelephone (business)x-
facsimileTelephoneNumberFax (business)x-
pagerPagerx-
mobileMobile phonexx
homePhoneTelephone (home)xx
commentCommentx-
URLURL (business)x-
roomNumberOfficex-
displayNameNickname-x
initialsInitialsx-
cCountryx-

When you want to provide an address, both readeable in Outlook and Evolution, then you have to add it to the attribute postalAddress (that is, with street, number, postal and city). If only Outlook comes in place, then you can use postalAddress as the 'street address' and l and c for city and country. If someone comes up with a good scheme for the address in Evolution...do not hesitate to contact me!

12. GUI-tools

When you're administrating LDAP, you will mostly use the command-line tools. If, for a change, you want to 'browse' or 'modify' the directory with a GUI then take a look at the different projects on Sourceforge that handle this (thanks to Roberto Nervi for pointing out that http://www.iit.edu/~gawojar/ldap/ is dead).

13. Outlook / Outlook Express

Both Outlook and Outlook Express offer a fairly good implementation of LDAP. I will only cover the steps for Outlook Express, it's up to you to adapt these for Outlook.

If you are using LDAP over SSL, you first need to add the certificate to Internet Explorer. To do so, open Internet Explorer and enter the name of your server, preceded with https and followed by the SSL-port. So for our example this would be
https://ldap.example.com:636/
This will show the following dialogbox :


Click View certificate
Now you can review and check the certificate details.


Click Next


Choose for Automatically .... when prompted for the method for importing.

Click Finish


Click Yes




Now for Outlook.

First, go to Tools - Accounts and select the tab Directory Service.


Now choose Add - Directory Service. Enter the name that you're going to use to refer to the LDAP directory and click Next.


Choose Yes when asked for 'Do you want to check addresses using this directory service?'. This offers you the possiblity for autocompletian when composing an e-mail.


Click Finish. The directory-service is now available.
<

Before you can use it with SSL, you need to reopen the properties page. Do this by clicking on Properties. Switch to the Advanced tab and check the checkbox before 'This server requires a secure connection (SSL)'. The Search Base for our setup is
ou=addressbook,dc=example,dc=com


Searching for people in the directory goes very easy.
Start a new e-mail and click on the To button. Then click on Find.


You can now enter your search criteria and click Find now. This will show all the available results.

One minor thing, if you have both a 'local' addressbook (like a contactlist) and an LDAP addressbook then automatic name-completation will first look in the contaclist and then in the LDAP directory. I did not find a way to change this order.

14. Evolution

Just like with Outlook it is very easy to add a directory service to Evolution.

First off, go to Tools - Settings and then click on the icon for Directory Servers.


Click Add and then choose Forward.


Now you must enter the real server name. Make sure this is the same name that you used for the SSL certificate! Click Forward.


Choose 636 as the port-number. This should change Use SSL/TLS to 'Always'. Then click Forward.


The search base is for our example ou=addressbook, dc=example, dc=com. Click Forward when finished.


Now you can enter the display name, this is how you will refer to the LDAP directory through Evolution.


Click Apply and then Close. This will add this LDAP directory to Evolution.


You can access the directory from Other contacts.



As oppossed to Outlook Express you don't need to supply a search filter in Evolution. This gives you the possibilty to get a listing of all the contacts in the LDAP-directory.
Copyleft 2002-2007 - cudeso.bewebmaster@cudeso.betop