Installing OpenLDAP
Like many other distributions, Ubuntu breaks OpenLDAP up into small packages.
The daemons (slapd and slurpd) are packaged in the slapd package. The clients are
packaged in ldap-utils, and the libraries are packaged in libldap-2.3-0. When
Ubuntu 7.04 was released, OpenLDAP version 2.3.30 was provided. As security
fixes are made, Ubuntu may release newer versions via online updates. While legacy
2.2.26 packages are still available, they should be avoided.
To install Ubuntu we can use the Synaptic graphical installer or any of the
command-line package management utilities. For the sake of simplicity, we will use
apt-get. This will download all of the necessary packages (including dependencies)
from the official Ubuntu repository and install them for us. Note that installing
this way will require access to the Internet (or, alternatively, to some other form
of Ubuntu distribution media, such as a CD-ROM). We need to run the
following command.
$ sudo apt-get install libldap-2.3-0 slapd ldap-utils
It may take a little while for the packages to download and install.
Once apt-get is done, the LDAP server and all of its clients should be installed.
Next, we will begin the process of configuring the SLAPD server.
Configuring the SLAPD Server
There are two daemons that come packaged with OpenLDAP: SLAPD server and
SLURPD server. SLAPD, sometimes called the OpenLDAP server, handles client
requests and directory management, while SLURPD manages replicating changes
to other directories. SLURPD is now deprecated in favor of a newer, more robust
replication process, and will be removed from future versions of OpenLDAP.
In the next chapter we will talk more about what these two daemons do. Right now
we are only concerned with getting the SLAPD server up and running so we can
start connecting to (and using) our directory.
SLAPD has one main configuration file and any number of auxiliary configuration
files. In this section we are going to edit the main configuration file. It is called
slapd.conf, and in Ubuntu’s distribution it is located at /etc/ldap/ (if you built
from source, the default location is /usr/local/etc/openldap/).
Use find . –type f –name slapd.conf or if the locate service is
enabled, you can use locate slapd.conf.
While Ubuntu provides a good basic slapd.conf file that you can work with, if
you choose, we will not use it. For our purpose, we will start with an empty file
and create a slapd.conf configuration from scratch. You may want to make a
backup copy of the original slapd.conf file before we begin. You can do this from a
terminal by running:
$ sudo mv /etc/ldap/slapd.conf /etc/ldap/slapd.conf.orig
This will rename the file from slapd.conf to slapd.conf.orig.
By default, Ubuntu does not activate the root account. Any time you
want to perform a function as the superuser, you should use sudo.
However, if you need to become root (to run, for instance, several
commands in sequence), you can type sudo su.
Now we are ready to create our new slapd.conf file. Open the text editor and create
a basic slapd.conf file:
# slapd.conf - Configuration file for LDAP SLAPD
##########
# Basics #
##########
include /etc/ldap/schema/core.schema
include /etc/ldap/schema/cosine.schema
include /etc/ldap/schema/inetorgperson.schema
pidfile /var/run/slapd/slapd.pid
argsfile /var/run/slapd/slapd.args
loglevel none
modulepath /usr/lib/ldap
# modulepath /usr/local/libexec/openldap
moduleload back_hdb
##########################
# Database Configuration #
##########################
database hdb
suffix "dc=example,dc=com"
rootdn "cn=Manager,dc=example,dc=com"
rootpw secret
directory /var/lib/ldap
# directory /usr/local/var/openldap-data
index objectClass,cn eq
########
# ACLs #
########
access to attrs=userPassword
by anonymous auth
by self write
by * none
access to *
by self write
by * none
There are three headings in the file (Basics, Database Configuration, and ACLs),
and we will now see each heading in detail.
If you built from source, the paths in the above file need to be adjusted
(or, alternately, you can relocate files on your file system). Look in the
/usr/local portion of your file system to locate the correct location (for
example, modulepath is in /usr/local/libexex/openldap/).
Basics
The first section of the configuration file, labeled Basics, contains a variety of
configuration parameters:
##########
# Basics #
##########
include /etc/ldap/schema/core.schema
include /etc/ldap/schema/cosine.schema
include /etc/ldap/schema/inetorgperson.schema
pidfile /var/run/slapd/slapd.pid
argsfile /var/run/slapd/slapd.args
loglevel none
modulepath /usr/lib/ldap
# modulepath /usr/local/libexec/openldap
moduleload back_hdb
First note that all lines that start with a hash (#) are treated as comments, and ignored
by SLAPD.
The first three functional (non-comment) lines all begin with the include directive.
The include directive should always be followed by a full path to a file on the
file system. When SLAPD finds the include directive it will attempt to load the
indicated file. Those files will then be treated as part of the current configuration
file. So, when SLAPD reads these three lines, it will try to load the three schema files
(core.schema, cosine.schema, and inetorgperson.schema).
The include directive can be used to load any configuration parameters (in the next
chapter, we will use it to include a file that contains ACLs). Traditionally, the schema
information is stored separately from other configuration directives, and loaded
(using include directives) at server startup. This improves the readability of the
code and helps prevent the accidental modification of the schema information.
Schemas
Schemas provide definitions of (amongst other things) the different object classes
and attribute types that OpenLDAP should support. Using these, OpenLDAP can
determine what entries it is allowed to store, whether any given entry is valid, and
how entries should optimally be stored.
The three schemas loaded here contain the most frequently used options.
core.schema contains all of the attribute and object class definitions from the LDAP
v.3 specification. The cosine.schema and inteorgperson.schema files contain
schema definitions for commonly used standardized extensions (see RFCs 4524 and
2798). There are a host of other schemas available with OpenLDAP, and we will look
at some of those in Chapter 6.
More Directives
After the schemas are included the next two directives, pidfile and argsfile, tell
SLAPD where to store (and look for) files that contain information on:
- The process ID for the SLAPD server process
- The arguments that were passed into the slapd command at startup
Since SLAPD needs to write to these files, the user that runs slapd needs
to have permissions to read from and write to these files. Since the
files are removed when the SLAPD server shuts down, the user that runs
slapd will also need write permissions on the directory where these files
are stored (/var/run/slapd/, in this case).
Next, the loglevel directive is set to none. The loglevel directive specifies how
much information SLAPD should send to the system log (by way of syslogd).
The loglevel directive accepts keywords (any, none, trace, and so on), integers
(0, 128, 32768), and hexidecimal numbers (0×2, 0×80, 0×100).
Setting this to none will cause SLAPD to only log critical events. In order to turn off
the logging altogether, use 0. To turn on all the logging, which will generate massive
amounts of logging for every request, use any. The SLAPD man page (man slapd)
provides a complete list of all the supported log levels.
Module Directives
The last few directives in the Basics section are modulepath and moduleload. These
are instructions for loading OpenLDAP modules.
A module is a special type of library that can be loaded when SLAPD starts up.
Instead of compiling all of SLAPD’s code into one large binary, the modules make it
possible to create smaller library files for discrete functional units of LDAP code.
Typically, there are two different kinds of modules:
- Backends: The OpenLDAP server can use different storage backends,
including BDB, SQL database, flat files (in LDIF format), or even another
LDAP directory server. Each of these backends can be compiled into its own
module. Then, during configuration, we have the option of only loading the
module (or modules) that we need. - Overlays: OpenLDAP includes a number of optional extensions, called
overlays, which can modify behavior of the server (we will look at several
overlays in the course of this book). These, too, are stored in modules.
Let’s have a look at the directives we have used in our slapd.conf file:
- The modulepath directive provides the full path to the directory where the
modules (the compiled libraries) are stored. By default, Ubuntu puts LDAP
libraries in /usr/lib/ldap. If, for some reason, you have modules stored in
multiple directories you can specify a list of paths, separated by colons:modulepath /usr/lib/ldap:/usr/local/lib/custom-ldap - The moduleload directive instructs OpenLDAP to load a particular module.
The directive takes either the file name of the module to be loaded (such as
back_hdb) or a full path (beginning with /) to a module file. If just the name
is specified, SLAPD will look in the directories specified in modulepath. If
the entire path is specified, it will attempt to load from exactly that path (it
will not use modulepath at all). - moduleload back_hdb instructs SLAPD to load the module that provides
services for storing the directory in the Hierarchical Database (HDB)
backend. This is the database that we will configure in the Database
Configuration section.
For now these are the only directives we need in the Basics section. There are other
options though, and we will look at many of them in Chapters 4 and 5.
Database Configuration
The next section of our slapd.conf file is the database configuration section. This
section handles the configuration of the database storage mechanisms. OpenLDAP
is not limited to one database. More than one database can be used per server,
where each database stores its own directory tree (or subtree). For example, a single
OpenLDAP instance can serve a directory tree whose base is o=My Company,c=US
from one database, and a directory tree whose root is dc=example,dc=com from a
second database.
As we saw in Chapter 1, the base DN for a directory tree is made up
of attribute name/attribute value pairs. For example, the DN o=My
Company, c=US indicates that the organization name (o) is My Company,
and its country of origin (c) is United States (whose two-letter ISO code is
US). Likewise, the second DN is composed of attribute name/value pairs,
this time representing domain components (dc) from the organization's
registered domain name, here, the fictitious Example.Com.
We will look at this option in Chapter 5. In our simple slapd.conf file, we are
defining only one database:
##########################
# Database Configuration #
##########################
database hdb
suffix "dc=example,dc=com"
rootdn "cn=Manager,dc=example,dc=com"
rootpw secret
directory /var/lib/ldap
# directory /usr/local/var/openldap-data
index objectClass,cn eq
The first directive in the database configuration section is the database directive.
This specifies which database backend will be used. In this case we will be using the
Hierarchical Database (HDB), so we specify hdb.
HDB is the new generation storage mechanism for OpenLDAP. Like
its predecessor, the BDB backend, HDB uses the Oracle Berkeley DB
database for storage, but HDB stores entries hierarchically, a perfect fit for
LDAP's tree strucutre. The old BDB backend is still supported, and you
can use it by specificing bdb instead of hdb in the database directive.
The next directive, suffix, indicates which parts of the directory tree this database
will hold. Basically, it indicates that this database’s base will be the entry with the
Distinguished Name (DN) specified in the suffix directive (dc=example,dc=com).
We have discussed Distinguished Names in Chapter 1.
When the server receives a request for something in that tree (for example,
cn=Matt,dc=example,dc=com), it will search in this database. The following figure
gives a better idea:
Here, the client is searching for a specific DN, cn=Matt, dc=example,
dc=com. The SLAPD server contains a directory information tree whose base DN
is dc=example, dc=com.
The DN cn=Matt,dc=example,dc=com is subordinate to dc=example,dc=com. It
exists in the dc=example,dc=com tree. So, SLAPD searches the dc=example,dc=com
database for a record whose DN is cn=Matt,dc=example,dc=com. Once the record is
found, it is returned to the client.
What will happen if a client requests the record of cn=Matt,dc=test,dc=net? Since
this DN does not contain a base DN handled by this server, the server will not search
for the record. Depending on the configuration, it may either send an error back to
the client or redirect the client to another server that might be able to handle such
a request.
Likewise, if a client tries to add a record with a base DN other than the one specified
in the suffix directive, the LDAP server will refuse to add the record to the directory
information tree.
The suffix directive in slapd.conf specifies what the base DN will be for
information stored or referenced in this database. This will determine, to a large
degree, what records this database will contain, search for, or allow to be added.
One database can have multiple trees (this is covered in Chapter 5).
The next two lines assign a record for the directory manager and give the manager
entry a password. The rootdn directive specifies the DN that will be considered the
administrator of this directory. By convention, the root DN is created by prepending
cn=Manager to the base DN of the directory tree. Thus, our directory manager is
cn=Manager,dc=example,dc=com. The next field, rootpw, is used to assign a
password for the directory manager. Note that this is stored outside the directory
rather than inside it. For example, the userPassword attribute of a record in the
directory. This is to prevent the manager from being locked out of the directory.
The directory manager is a special user with special privileges. The manager’s
requests are not filtered through ACLs—the manager’s access cannot be restricted.
Furthermore, the manager has write access to all records in the directory under the
specified suffix or suffixes. For that reason, the manager DN should be used for
administrative tasks only and not for anything else.
Further, since the necessary fields for the manager are stored here in the
slapd.conf file, there should not be a record in the directory with the manager’s
DN (this is recommended for best practices, though it is not explicitly prevented
by SLAPD).
Since the manager’s DN and password are stored in the slapd.conf file, and since
the manager has access to everything in the directory, we should keep file system
permissions on the slapd.conf file as restrictive as possible.
Encrypting the Manager's Password
You can also give rootpw an encrypted password by using the
ldappasswd utility, described in the next chapter.
The directory directive indicates which directory on the file system should hold the
database files. In this case the database is stored at /var/lib/ldap/.
Finally, the index directive is composed of a list of attributes that should be indexed,
followed by the type of matching that the index will be used for. Our example
looked like this:
index objectClass,cn eq
This means that we are creating an index that will support equality (eq) matching on
the attributes objectClass and cn. When the server gets a request for all the entries
with cn Rob or commonName Rob, the server can greatly expedite service by accessing
the index instead of searching the entire database. However, if the request was for
Rob* (note the * wildcard character), then the server would not be looking for a CN
that equals “Rob*”, but for any CN that starts with “Rob”. In this case, the index we
created would not be used.
Multiple index directives can be used, and we could support faster CN searches for
queries like Rob* by splitting the index directive into two different directives:
index objectClass eq
index cn eq,sub
In the given example, an equality (eq) index is maintained for objectClass
attributes, while the cn attribute is indexed for equality matches (eq) and substring
matches (sub).
Certain attributes do not support all index types. The objectClass attribute, for
example, does not support substring (sub) index matching. When we will look at
performance tuning in Chapter 5, we will see the indexing directive more carefully.
Once you have a database created, every time you modify the index directives in
slapd.conf, you should rebuild the indexes with the slapindex command-line
utility. Since we have not yet put any data in the database though, we don’t need to
run this command now.
Now we are ready to move on to the third and final section of our configuration file.
October 25, 2009
Uncategorized