Symas OpenLDAP Knowledge Base

Symas OpenLDAP 2.5 Quick Start

This leads you through a few steps to get a sandbox OpenLDAP LDAP Directory Service running. It is intended to be a quick introduction to the basics of running OpenLDAP. It helps you get comfortable with things you’ll be doing many times, setting up various servers (or virtual servers) for development and testing.

We don’t expect this exercise will do anything other than get the general framework of working with OpenLDAP clarified. And introduce, without a lot of detailed explanation, a lot of concepts you’ll need.

1. “Get” the software

Symas has a repository for its binary packages for OpenLDAP 2.5 at https://repo.symas.com/soldap/. The home page of that repository points to instructions for configuring your system’s package manager to point to our repository, installing Symas’s binary packages of OpenLDAP 2.5, and updating those packages going forward. Click For More

2. Configure the OpenLDAP Server (slapd)

Use your favorite editor to edit the provided slapd.ldif example (usually installed as /usr/local/etc/slapd.ldif) to contain a MDB database definition of the form:

dn: olcDatabase=mdb,cn=config 
objectClass: olcDatabaseConfig 
objectClass: olcMdbConfig 
olcDatabase: mdb 
OlcDbMaxSize: 1073741824 
olcSuffix: dc=<MY-DOMAIN>,dc=<COM> 
olcRootDN: cn=Manager,dc=<MY-DOMAIN>,dc=<COM> 
olcRootPW: secret 
olcDbDirectory: /usr/local/var/openldap-data 
olcDbIndex: objectClass eq

For an annotated version of this click here. For a downloadable copy right-click herenull.

Be sure to replace and with the appropriate domain components of your domain name. For example, for example.com, use:

dn: olcDatabase=mdb,cn=config 
objectClass: olcDatabaseConfig 
objectClass: olcMdbConfig 
olcDatabase: mdb 
OlcDbMaxSize: 1073741824 
olcSuffix: dc=example,dc=com 
olcRootDN: cn=Manager,dc=example,dc=com 
olcRootPW: secret 
olcDbDirectory: /usr/local/var/openldap-data 
olcDbIndex: objectClass eq

If your domain contains additional components, such as eng.uni.edu.eu, use:

dn: olcDatabase=mdb,cn=config 
objectClass: olcDatabaseConfig 
objectClass: olcMdbConfig 
olcDatabase: mdb 
OlcDbMaxSize: 1073741824 
olcSuffix: dc=eng,dc=uni,dc=edu,dc=eu 
olcRootDN: cn=Manager,dc=eng,dc=uni,dc=edu,dc=eu 
olcRootPW: secret 
olcDbDirectory: /usr/local/var/openldap-data 
olcDbIndex: objectClass eq

For the rest of the quick-start steps, we use assume that olcsuffix is set to dc=sample,dc=com.

Details regarding configuring slapd(8) can be found in the slapd-config(5) manual page and the Configuring slapd chapter of this document. Note that the specified olcDbDirectory must exist prior to starting slapd(8).

3. Import the configuration database

You are now ready to import your configuration database for use by slapd(8), by running the command:

sudo -c /usr/local/sbin/slapadd -n 0 -F /usr/local/etc/slapd.d \
    -l /usr/local/etc/openldap/slapd.ldif

For a crib sheet on the command click here

slapadd is a special form of the slapd daemon. It only reads LDIF data and adds it to a directory database. It checks the data for schema and value validity as it loads it. When it is done loading it, it stops. It does not leave the directory “running.”

4. Start slapd (the server software)

You are now ready to start the Standalone LDAP Daemon, slapd, by running the command:

sudo -c /usr/local/libexec/slapd -F /usr/local/etc/slapd.d

Here we provide only one input parameter to slapd, the LDIF database we loaded in the previous step. There are many other parameters you can specify when bringing up slapd. None are needed right now.

To check to see if the server is running and configured correctly, you can run a search against it with ldapsearch(1). By default, ldapsearch is installed as /usr/local/bin/ldapsearch and should already be in your $PATH:

ldapsearch -x -b '' -s base '(objectclass=*)' namingContexts

Note the use of single quotes around command parameters to prevent special characters from being interpreted by the shell. This should return:

 dn: 
 namingContexts: dc=example,dc=com

This is a search against the root of the entire database. OpenLDAP has internal databases which were not set up in this tiny configuration: a configuration database and a monitoring database are very common. access log and session log are two others. In addition, an OpenLDAP server can actually manage more than one directory. You might have another directory for dc=example,dc=org with completely different user data. Both COULD run on just one instance of slapd. If that were the case, both would be listed in the output from that command.

5. Add initial entries to your directory

Use the ldapadd command to add entries to your LDAP directory. ldapadd expects input in LDIF form. We’ll do it in two steps:

  • create an LDIF file
  • run ldapadd

At this point, the directory only contains a naming context for the database. The root entry has to be inserted. And the cn=Manager,dc=sample,dc=com entry has to be set up. So we’ll do that next.

Use your favorite editor and create an LDIF file that contains:

dn: dc=sample,dc=com
objectclass: dcObject 
objectclass: organization 
o: Sample Co. 
dc: sample

dn: cn=Manager,dc=sample,dc=com 
objectclass: organizationalRole 
cn: Manager

Now, run ldapadd to insert these entries into your directory.

    ldapadd -x -D "cn=Manager,dc=sample,dc=com -W -f example.ldif

where example.ldif is the file you created above. A breakdown of this command can be found here.

You will be prompted for the “secret” specified in slapd.ldif. If you “hashed” the password (“secret”), here you provide the password you asked ldappasswd to hash.

6. See if it works

Now we’re ready to verify the added entries are in your directory. You can use any LDAP client to do this, but our example uses the ldapsearch tool:

ldapsearch -x -b 'dc=example,dc=com' '(objectclass=*)'

This command will search for and retrieve every entry in the database. You are now ready to add more entries using ldapadd or another LDAP client, experiment with various configuration options, backend arrangements, etc..

7. Let’s Add some users

  1. Create some place to put user entries

    There’s nothing wrong with having your user entries right under the root node of the directory. That works if the only thing you’ll use the LDAP directory for is user entries. Most of the time, that’s too simple because there will be entries for machines or applications, or other things.

    LDAP has entries you use to organize the contents of the directory. One is OrganizationalUnit (usually coded as ou that is commonly used to provide a home for things like people. We will create an ou called “people”. This entry has no data. It is a placeholder. Put into an LDIF file named example1.ldif. In the next step we will add the first user entry. The LDIF looks like:

dn: ou=people,dc=example,dc=com
objectclass: ou
ou: people
  1. Now add a user

    For now, we will use organizationalPerson as the objectClass for user entries. There are other objectClasses with varying attributes but organizationalPerson is one of the defaults available to us.

    Add the following lines to the bottom of the example1.ldif file.

dn: uid=bowser,ou=people,dc=example,dc=com
objectclass: organizationalPerson
uid: bowser
cn: Bowser
sn: Bulldog
mail: bowser@example.com
  1. Update the directory

    Note that we defined the container (ou=people) and the entry in one LDIF file.

    Run the following command:

    ldapadd -x -D "cn=Manager,dc=sample,dc=com -W -f example1.ldif