LDAP System Administration – Read Now and Download Mobi

LDAP System Administration

Table of Contents

A Note Regarding Supplemental Files

Preface

How This Book Is Organized

Part I : LDAP Basics

Part II : Application Integration

Part III: Appendixes

Conventions Used in This Book

Comments and Questions

Acknowledgments

I. LDAP Basics

1. "Now where did I put that...?", or "What is a directory?"

1.1. The Lightweight Directory Access Protocol

1.2. What Is LDAP?

1.2.1. Lightweight

1.2.2. Directory

1.2.3. Access Protocol

1.3. LDAP Models

2. LDAPv3 Overview

2.1. LDIF

2.1.1. Distinguished Names and Relative Distinguished Names

2.1.2. Back to Our Regularly Scheduled Program . . .

2.2. What Is an Attribute?

2.2.1. Attribute Syntax

2.2.2. What Does the Value of the objectClass Attribute Mean?

2.3. What Is the dc Attribute?

2.3.1. Where Is dc=org?

2.4. Schema References

2.5. Authentication

2.5.1. Anonymous Authentication

2.5.2. Simple Authentication

2.5.3. Simple Authentication Over SSL/TLS

2.5.4. Simple Authentication and Security Layer (SASL)

2.6. Distributed Directories

2.7. Continuing Standardization

3. OpenLDAP

3.1. Obtaining the OpenLDAP Distribution

3.2. Software Requirements

3.2.1. Threads

3.2.2. SSL/TLS Libraries

3.2.3. Database Backend Modules

3.2.4. SASL Libraries

3.3. Compiling OpenLDAP 2

3.4. OpenLDAP Clients and Servers

3.5. The slapd.conf Configuration File

3.5.1. Schema Files

3.5.2. Logging

3.5.3. SASL Options

3.5.4. SSL/TLS Options

3.5.5. More Security-Related Parameters

3.5.6. Serving Up Data

3.6. Access Control Lists (ACLs)

4. OpenLDAP: Building a Company White Pages

4.1. A Starting Point

4.2. Defining the Schema

4.3. Updating slapd.conf

4.4. Starting slapd

4.5. Adding the Initial Directory Entries

4.5.1. Verifying the Directory's Contents

4.5.2. Updating What Is Already There

4.6. Graphical Editors

5. Replication, Referrals, Searching, and SASL Explained

5.1. More Than One Copy Is "a Good Thing"

5.1.1. Building slurpd

5.1.2. Replication in a Nutshell

5.1.3. Configuring the Master Server

5.1.4. Configuring the Replica Server

5.1.5. slurpd's replogfile

5.2. Distributing the Directory

5.3. Advanced Searching Options

5.3.1. Following Referrals with ldapsearch

5.3.2. Limiting Your Searches

5.4. Determining a Server's Capabilities

5.5. Creating Custom Schema Files for slapd

5.6. SASL and OpenLDAP

II. Application Integration

6. Replacing NIS

6.1. More About NIS

6.2. Schemas for Information Services

6.3. Information Migration

6.4. The pam_ldap Module

6.4.1. Configuring /etc/ldap.conf

6.5. The nss_ldap Module

6.6. OpenSSH, PAM, and NSS

6.7. Authorization Through PAM

6.7.1. One Host and a Group of Users

6.7.2. One User and a Group of Hosts

6.8. Netgroups

6.9. Security

6.10. Automount Maps

6.11. PADL's NIS/LDAP Gateway

7. Email and LDAP

7.1. Representing Users

7.2. Email Clients and LDAP

7.2.1. Mozilla Mail

7.2.2. Pine 4

7.2.3. Eudora

7.2.4. Microsoft Outlook Express

7.3. Mail Transfer Agents (MTAs)

7.3.1. Sendmail

7.3.2. Postfix

7.3.3. Exim

8. Standard Unix Services and LDAP

8.1. The Directory Namespace

8.2. An FTP/HTTP Combination

8.2.1. ProFTPD

8.2.2. Apache

8.3. User Authentication with Samba

8.3.1. Configuring Samba

8.3.2. Adding and Using a sambaAccount

8.4. FreeRadius

8.4.1. FreeRadius and OpenLDAP

8.5. Resolving Hosts

8.6. Central Printer Management

9. LDAP Interoperability

9.1. Interoperability or Integration?

9.2. Directory Gateways

9.3. Cross-Platform Authentication Services

9.3.1. A Short Discussion About Kerberos

9.4. Distributed, Multivendor Directories

9.5. Metadirectories

9.6. Push/Pull Agents for Directory Synchronization

9.6.1. The Directory Services Markup Language

10. Net::LDAP and Perl

10.1. The Net::LDAP Module

10.2. Connecting, Binding, and Searching

10.3. Working with Net::LDAP::LDIF

10.4. Updating the Directory

10.4.1. Adding New Entries

10.4.2. Deleting Entries

10.4.3. Modifying Entries

10.5. Advanced Net::LDAP Scripting

10.5.1. References and Referrals

10.5.2. Scripting Authentication with SASL

10.5.3. Extensions and Controls

III. Appendixes

A. PAM and NSS

A.1. Pluggable Authentication Modules

A.1.1. Configuring PAM

A.2. Name Service Switch (NSS)

B. OpenLDAP Command-Line Tools

B.1. Debugging Options

B.2. Slap Tools

B.2.1. slapadd(8c)

B.2.2. slapcat(8c)

B.2.3. slapindex(8c)

B.2.4. slappasswd(8c)

B.3. LDAP Tools

B.3.1. ldapadd(1), ldapmodify(1)

B.3.2. ldapcompare(1)

B.3.3. ldapdelete(1)

B.3.4. ldapmodrdn(1)

B.3.5. ldappasswd(1)

B.3.6. ldapsearch(1)

C. Common Attributes and Objects

C.1. Schema Files

C.2. Attributes

C.3. Object Classes

D. LDAP RFCs, Internet-Drafts, and Mailing Lists

D.1. Requests for Comments

D.2. Mailing Lists

E. slapd.conf ACLs

E.1. What?

E.2. Who?

E.3. How Much?

E.4. Examples

LDAP System Administration

Gerald Carter

Editor

Mike Loukides

Copyright © 2009 O'Reilly Media, Inc.

O'Reilly Media

A Note Regarding Supplemental Files

Supplemental files and examples for this book can be found at http://examples.oreilly.com/9781565924918/. Please use a standard desktop web browser to access these files, as they may not be accessible from all ereader devices.

All code files or examples referenced in the book will be available online. For physical books that ship with an accompanying disc, whenever possible, we’ve posted all CD/DVD content. Note that while we provide as much of the media content as we are able via free download, we are sometimes limited by licensing restrictions. Please direct any questions or concerns to [email protected].

Preface

In 1999 I began experimenting with the Lightweight Directory Access Protocol (LDAP) and immediately became frustrated by lack of documentation. I set out to write the book that I needed, and I believe that I accomplished that goal. After teaching instructional courses on LDAP for the past few years, I have come to the belief that many people share the same frustration I felt at the beginning of my LDAP career. Managers and administrators alike can sometimes be dazzled (or disgusted) by the plethora of acronyms in the IT industry. The goal of this book is to cut through the glossy vendor brochures and give you the knowledge and tools necessary to deploy a working directory on your network complete with integrated client applications.

Directory services have been a part of networks in one way or another for a long time. LDAP directories have been growing roots in networks for as long as people have been proclaiming the current year to be the "year of LDAP." With increasing support from vendors in the form of clients and servers, LDAP has already become a staple for many networks. Because of this gradual but steady growth, people waiting for the LDAP big bang may be disappointed. You may wake up one morning and find that one of your colleagues has already deployed an LDAP-based directory service. If so, this book will help you understand how you can use the services that LDAP provides. If you are at the beginning of a project, this book will help you focus on the important points that are necessary to succeed.

How This Book Is Organized

This book is divided into two sections of five chapters each and a section of appendixes. You will most likely get the most out of this book if you implement the example directories as they are covered. With only a few exceptions, all client and server applications presented here are freely available or in common use.

Part I : LDAP Basics

Part I focuses on getting acquainted with LDAP and with the OpenLDAP server. In this part, I answer questions such as: "What is lightweight about LDAP?," "What security mechanisms does LDAP support for preventing unauthorized access to data?," and "How can I build a fault-tolerant directory service?" In addition, the first part of the book helps you gain practical experience with your own directory using the community-developed and freely available OpenLDAP server.

Chapter 1 is a high-level overview of directory services and LDAP in particular.

Chapter 2 digs into the details of the Lightweight Directory Access Protocol.

Chapter 3 uses the free server distribution from OpenLDAP.org as an example to present practical experience with an LDAP directory.

Chapter 4 provides some hands-on experience adding, modifying, and deleting information from a working directory service.

Chapter 5 wraps up the loose ends of some of the more advanced LDAPv3 and OpenLDAP features.

Part II : Application Integration

Part II is all about implementation. Rather than present an LDAP cookbook, I bring different applications together in such a way that information common to one or more clients can be shared via the directory. You will see how to use LDAP as a practical data store for items such as user and group accounts, host information, general contact information, and application configurations. I also discuss integration with other directory services such as Microsoft's Active Directory, and how to develop your own Perl scripts to manage your directory service.

Chapter 6 explains how an LDAP directory can be used to replace Sun's Network Information Service (NIS) as the means to distribute user and group accounts, host information, automount maps, and other system files.

Chapter 7 presents information related to both mail clients (Eudora, Mozilla, Outlook, and Pine) and servers (Sendmail, Postfix, and Exim).

Chapter 8 explains how to use an LDAP directory to share information among essential network services such as FTP, HTTP, LPD, RADIUS, DNS, and Samba.

Chapter 9 examines what to do when your LDAP directory must coexist with other directory technologies.

Chapter 10 provides the information necessary to roll your own LDAP management tools using Perl and the Net::LDAP module.

Part III: Appendixes

The appendixes provide a quick reference for LDAP standards, common schema items used in this book, and the command-line syntax for OpenLDAP client tools.

Conventions Used in This Book

The following conventions are used in this book:

Italic

Used for file, directory, user, and group names. It is also used for URLs and to emphasize new terms and concepts when they are introduced.

Constant Width

Used for code examples, system output, parameters, directives, and attributes.

Constant Width Italic

Used in examples for variable input or output (e.g., a filename).

Constant Width Bold

Used in code examples for user input and for emphasis.

Tip

This icon designates a note, which is an important aside to the nearby text.

Warning

This icon designates a warning relating to the nearby text.

Comments and Questions

We at O'Reilly have tested and verified the information in this book to the best of our abilities, but you may find that features have changed (or even that we have made mistakes!). Please let us know about any errors you find, as well as your suggestions for future editions, by writing to:

You can also contact O'Reilly by email. To be put on the mailing list or request a catalog, send a message to:

We have a web page for this book, which lists errata, examples, and any additional information. You can access this page at:

To comment or ask technical questions about this book, send email to:

For more information about O'Reilly books, conferences, Resource Centers, and the O'Reilly Network, see the O'Reilly web site at:

Acknowledgments

At the end of every project, I am acutely aware that I could never have reached the end without the grace provided to me by God through my Savior, Jesus Christ. I hope He is proud of how I have spent my time. I am also very conscious of the patience bestowed upon me by my wife, Kristi, who is always there to listen when I need to talk and laugh when I need a smile. Thank you.

There is a long list of people who have helped make this book possible. I do not claim that this is a complete list. Mike Loukides has shown almost as much patience as my wife waiting on this book to be completed. I am in great debt to the technical reviewers who each provided comments on some version of this manuscript: Robbie Allen, David Blank-Edelman, Æleen Frisch, Robert Haskins, Luke Howard, Scott McDaniel, and Kurt Zeilenga. Thanks to Æleen for convincing me to do this (even if I complained more than once). I must also mention the various coffee shops, particularly the Books-A-Million in Auburn, AL, that have allowed me to consume far more than my fair share of caffeine and electricity.

Finally, a huge amount of recognition must be given to the developers who made various pieces of software available under open source and free software licenses. It is such an enjoyable experience to be able to send and receive feedback on problems, bugs, and solutions. Any other way would just be too painful.

Part I. LDAP Basics

Chapter 1

Chapter 2

Chapter 3

Chapter 4

Chapter 5

Chapter 1. "Now where did I put that...?", or "What is a directory?"

I have a fairly good memory for numbers, phone numbers in particular. This fact amazes my wife. For those numbers I cannot recall to the exact digit, I have a dozen or so slots in my cell phone. However, as the company I worked for grew, so did the list of people with whom I needed to stay in contact. And I didn't just need phone numbers; I needed email and postal addresses as well. My cell phone's limited capabilities were no longer adequate for maintaining the necessary information.

So I eventually broke down and purchased a PDA. I was then able to store contact information for thousands of people. Still, two or three times a day I found myself searching the company's contact database for someone's number or address. And I still had to go to other databases (phone books, corporate client lists, and so on) when I needed to look up someone who worked for a different company.

Computer systems have exactly the same problem as humans—both require the capability to locate certain types of information easily, efficiently, and quickly. During the early days of the ARPAnet, a listing of the small community of hosts could be maintained by a central authority—SRI's Network Information Center (NIC). As TCP/IP became more widespread and more hosts were added to the ARPAnet, maintaining a centralized list of hosts became a pipe dream. New hosts were added to the network before everyone had even received the last, now outdated, copy of the famous HOSTS.TXT file. The only solution was to distribute the management of the host namespace. Thus began the Domain Name System (DNS), one of the most successful directory services ever implemented on the Internet.^[1]

DNS is a good starting point for our overview of directory services. The global DNS shares many characteristics with a directory service. While directory services can take on many different forms, the following five characteristics hold true (at a minimum):

• A directory service is highly optimized for reads. While this is not a restriction on the DNS model, for performance reasons many DNS servers cache the entire zone information in memory. Adding, modifying, or deleting an entry forces the server to reparse the zone files. Obviously, this is much more expensive than a simple DNS query.
• A directory service implements a distributed model for storing information. DNS is managed by thousands of local administrators and is connected by root name servers managed by the InterNIC.
• A directory service can extend the types of information it stores. Recent RFCs, such as RFC 2782, have extended the types of DNS records to include such things as server resource records (RRs).
• A directory service has advanced search capabilities. DNS supports searches by any implemented record type (e.g., NS, MX, A, etc.).
• A directory service has loosely consistent replication among directory servers. All popular DNS software packages support secondary DNS servers via periodic "zone transfers" that contain the latest copy of the DNS zone information.

The Lightweight Directory Access Protocol

Of course, you didn't buy this book to read about the Domain Name System. And it's not likely that you were looking for a general discussion of directory services. This book is about a particular kind of directory service—namely, a service for directories that implement the Lightweight Directory Access Protocol (LDAP). LDAP has become somewhat of a buzzword in contemporary IT shops. If you are like me, sometimes you just have to ask, "Why all the fuss?" The fuss is not so much about LDAP itself, but about the potential of LDAP to consolidate existing services into a single directory that can be accessed by LDAP clients from various vendors. These clients can be web browsers, email clients, mail servers, or any one of a myriad of other applications.

By consolidating information into a single directory, you are not simply pouring the contents of your multitude of smaller pots into a larger pot. By organizing your information well and thinking carefully about the common information needed by client applications, you can reduce data redundancy in your directories and therefore reduce the administrative overhead needed to maintain that data. Think about all the directory services that run on your network and consider how much information is duplicated. Perhaps hosts on your network use a DHCP server. This server has a certain amount of information about IP addresses, Ethernet addresses, hostnames, network topology, and so forth in its configuration files. Which other applications use the same or similar information and could share it if it were stored in a directory server? DNS comes immediately to mind, as does NIS. If you have networked printers as well, think about the amount of information that's replicated on each client of the printing system (for example, /etc/printcap files).

Now consider the applications that use your user account information. The first ones that probably come to mind are authentication services: users need to type usernames and passwords to log in. Your mail server probably uses the same username information for mail routing, as well as for services such as mailing lists. There may also be online phone books that keep track of names, addresses, and phone numbers, as well as personnel systems that keep track of job classifications and pay scales.

Imagine the administrative savings that would result if all the redundant data on your network could be consolidated in a single location. What would it take to delete a user account? We all know what that takes now: you delete the user from /etc/passwd, remove him by hand from any mailing lists, remove him from the company phone list, and so on. If you're clever, you've probably written a script or two to automate the process, but you're still manipulating the same information that's stored in several different places. What if there was a single directory that was the repository for all this information, and deleting a user was simply a matter of removing some records from this directory? Life would become much simpler. Likewise, what would it take to track host-related information? What would it be worth to you if you could minimize the possibility that machines and users use out-of-date information?

This sounds like a network administrator's utopia. However, I believe that as more and more client applications use LDAP directories, making an investment in setting up an LDAP server will have a huge payoff long-term. Realistically, we're not headed for a utopia. We're going to be responsible for more servers and more services, running on more platforms. The dividends of our LDAP investment come when we significantly reduce the number of directory technologies that we have to understand and administer. That is our goal.

^[1] For more information on the Domain Name System and its roots, see DNS and BIND, by Paul Albitz and Cricket Liu (O'Reilly).

What Is LDAP?

The best place to begin when explaining LDAP is to examine how it got its name. Let's start at the beginning. The latest incarnation of LDAP (Version 3) is defined in a set of nine documents outlined in RFC 3377. This list includes:

RFC 2251-2256

The original core set of LDAPv3 RFCs

RFC 2829

"Authentication Methods for LDAP"

RFC 2830

"Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security"

RFC 3377

"Lightweight Directory Access Protocol (v3): Technical Specification"

Lightweight

Why is LDAP considered lightweight? Lightweight compared to what? (As we look at LDAP in more detail, you'll certainly be asking how something this complex could ever be considered lightweight.) To answer these questions, it is necessary to look at LDAP's origins. The roots of LDAP are closely tied to the X.500 directory service; LDAP was originally designed as a lighter desktop protocol used to gateway requests to X.500 servers. X.500 is actually a set of standards; anything approaching thorough coverage of X.500 is beyond the scope of this book.^[2]

X.500 earned the title "heavyweight." It required the client and server to communicate using the Open Systems Interface (OSI) protocol stack. This seven-layered stack was a good academic exercise in designing a network protocol suite, but when compared to the TCP/IP protocol suite, it is akin to traveling the European train system with four fully loaded footlockers.^[3]

LDAP is lightweight in comparison because it uses low overhead messages that are mapped directly onto the TCP layer (port 389 is the default) of the TCP/IP protocol stack.^[4] Because X.500 was an application layer protocol (in terms of the OSI model), it carried far more baggage, as network headers were wrapped around the packet at each layer before it was finally transmitted on the network (see Figure 1-1).

Figure 1-1. X.500 over OSI versus LDAP over TCP/IP

LDAP is also considered lightweight because it omits many X.500 operations that are rarely used. LDAPv3 has only nine core operations and provides a simpler model for programmers and administrators. Providing a smaller and simpler set of operations allows developers to focus on the semantics of their programs without having to understand rarely used features of the protocol. In this way, LDAP designers hoped to increase adoption by providing easier application development.

Directory

Network directory services are nothing new; we're all familiar with the rise of DNS. However, a directory service is often confused with a database. It is easy to understand why. Directory services and databases share a number of important characteristics, such as fast searches and an extendable schema. They differ in that a directory is designed to be read much more than it is written; in contrast, a database assumes that read and write operations occur with roughly the same frequency. The assumption that a directory is read often but written rarely means that certain features that are essential to a database, such as support for transactions and write locks, are not essential for a directory service such as LDAP.

At this point, it's important to make the distinction between LDAP and the backend used to store the persistent data. Remember that LDAP is just a protocol; we'll discuss what that means shortly, but essentially, it's a set of messages for accessing certain kinds of data. The protocol doesn't say anything about where the data is stored. A software vendor implementing an LDAP server is free to use whatever backend it desires, ranging from flat text files on one extreme to highly scalable, indexed relational databases on the other. So when I say that LDAP doesn't have support for transactions and other features of databases, I mean that the protocol doesn't have the messages that you would need to take advantage of these features (remember, it's lightweight) and doesn't require that the backend data store provide these features.

The point is that the client will never (and should never) see or even know about the backend storage mechanism (see Figure 1-2). For this reason, LDAP-compliant clients written by vendor A should interoperate with an LDAP-compliant server written by vendor Z. Standards can be a wonderful thing when followed.

Figure 1-2. Relationship between an LDAP client, LDAP server, and data storage facility

It has been suggested that an LDAP server could be used as backend storage for a web server. All HTML and graphic files would be stored within the directory and could be queried by mutiple web servers. After all, a web server typically only reads files and sends them to clients; the files themselves change infrequently. While it's certainly possible to implement a web server that uses LDAP to access its backend storage, a special type of directory already exists that is better suited to meet the needs of serving files, namely a filesystem. So, for example, while an LDAP directory might not be a good location for storing spooled files in transit to a printer, using it to store printer configuration settings (e.g., /etc/printcap) shared among clients would be a big win.

This brings up two good points about the intended function of LDAP:

1. LDAP is not a generalized replacement for specialized directories such as filesystems or DNS.
2. While storing certain types of binary information (e.g., JPEG photos) in directories can be useful, LDAP is not intended for storing arbitrary "blobs" (Binary Lumps of Bits).

What about storing individual application settings for roaming users on an LDAP server? It is a judgment call whether this is better served by a filesystem or a directory. For example, it is possible to store basic application settings for Netscape Communicator in LDAP. Such things as an address book, a bookmarks file, and personal preference settings are certainly appropriate for storage in a directory. However, using your directory as a location for browser cache files would violate rule #2.

Access Protocol

All of this talk of directory services makes it is easy to forget that LDAP is a protocol. It is not uncommon to hear someone refer to an LDAP server or LDAP tree. I have done so and will continue to do so. LDAP does provide a treelike view of data, and it is this treelike view to which people refer when speaking of an LDAP server.

This introduction won't go into the specifics of the actual protocol. It is enough to think of LDAP as the message-based, client/server protocol defined in RFC 2251. LDAP is asynchronous (although many development kits provide both blocking and nonblocking APIs), meaning that a client may issue multiple requests and that responses to those requests may arrive in an order different from that in which they were issued. Notice in Figure 1-3 that the client sends Requests 1 and 2 prior to receiving a response, and the response to Request 3 is returned before the response to Request 2.

Figure 1-3. LDAP requests and responses

More aspects of programming with LDAP operations will be covered in Chapter 10.

^[2] Understanding X.500—The Directory, by David W. Chadwick, provides a good explanation of X.500 directories. While the book itself is out of print, an HTML version of it can be accessed from http://www.salford.ac.uk/its024/X500.htm.

^[3] For a quick, general comparison of the OSI model and the TCP/IP protocol stack, see Computer Networks, by Andrew S. Tanenbaum (Prentice Hall).

^[4] A connectionless version of LDAP that provided access via UDP was defined by an Internet-Draft produced by the LDAP Extension Working Group of the IETF. However, the current draft expired in November, 2001. You can access the group's web site at http://www.ietf.org/html.charters/ldapext-charter.html.

LDAP Models

LDAP models represent the services provided by a server, as seen by a client. They are abstract models that describe the various facets of an LDAP directory. RFC 2251 divides an LDAP directory into two components: the protocol model and the data model. However, in Understanding and Deploying LDAP Directory Services, by Timothy A. Howes, Mark C. Smith, and Gordon S. Good (MacMillan), four models are defined:

Information model

The information model provides the structures and data types necessary for building an LDAP directory tree. An entry is the basic unit in an LDAP directory. You can visualize an entry as either an interior or exterior node in the Directory Information Tree (DIT). An entry contains information about an instance of one or more objectClasses. These objectClasses have certain required or optional attributes. Attribute types have defined encoding and matching rules that govern such things as the type of data the attribute can hold and how to compare this data during a search. This information model will be covered extensively in the next chapter when we examine LDAP schema.

Naming model

The naming model defines how entries and data in the DIT are uniquely referenced. Each entry has an attribute that is unique among all siblings of a single parent. This unique attribute is called the relative distinguished name (RDN). You can uniquely identify any entry within a directory by following the RDNs of all the entries in the path from the desired node to the root of the tree. This string created by combining RDNs to form a unique name is called the node's distinguished name (DN).

In Figure 1-4, the directory entry outlined in the dashed square has an RDN of cn=gerald carter. Note that the attribute name as well as the value are included in the RDN. The DN for this node would be cn=gerald carter,ou=people, dc=plainjoe,dc=org.

Functional model

The functional model is the LDAP protocol itself. This protocol provides the means for accessing the data in the directory tree. Access is implemented by authentication operations (bindings), query operations (searches and reads), and update operations (writes).

Security model

The security model provides a mechanism for clients to prove their identity (authentication) and for the server to control an authenticated client's access to data (authorization). LDAPv3 provides several authentication methods not available in previous protocol versions. Some features, such as access control lists, have not been standardized yet, leaving vendors to their own devices.

Figure 1-4. Example LDAP directory tree

At this high level, LDAP is relatively simple. It is a protocol for building highly distributed directories. In the next chapter, we will examine certain LDAP concepts such as schemas, referrals, and replication in much more depth.

Chapter 2. LDAPv3 Overview

Chapter 1 should have helped you understand the characteristics of a directory in general, and an LDAP directory in particular. If you still feel a little uncomfortable about LDAP, relax. This chapter is designed to flesh out some of the details that we glossed over. Your immediate goal should be to understand the basic building blocks of any LDAPv3 directory server. In the next chapter, we will start building an LDAP directory.

LDIF

Most system administrators prefer to use plain-text files for server configuration information, as opposed to some binary store of bits. It is more comfortable to deal with data in vi, Emacs, or notepad than to dig though raw bits and bytes. Therefore, it seems fitting to begin an exploration of LDAP internals with a discussion of representing directory data in text form.

The LDAP Interchange Format (LDIF), defined in RFC 2849, is a standard text file format for storing LDAP configuration information and directory contents. In its most basic form, an LDIF file is:

• A collection of entries separated from each other by blank lines
• A mapping of attribute names to values
• A collection of directives that instruct the parser how to process the information

The first two characteristics provide exactly what is needed to describe the contents of an LDAP directory. We'll return to the third characteristic when we discuss modifying the information in the directory in Chapter 4.

LDIF files are often used to import new data into your directory or make changes to existing data. The data in the LDIF file must obey the schema rules of your LDAP directory. You can think of the schema as a data definition for your directory. Every item that is added or changed in the directory is checked against the schema for correctness. A schema violation occurs if the data does not correspond to the existing rules.

Figure 2-1 shows a simple directory information tree. Each entry in the directory is represented by an entry in the LDIF file. Let's begin with the topmost entry in the tree labeled with the distinguished name (DN) dc=plainjoe,dc=org:

# LDIF listing for the entry dn: dc=plainjoe,dc=org
dn: dc=plainjoe,dc=org
objectClass: domain
dc: plainjoe

Figure 2-1. An LDAP directory tree

We can make a few observations about LDIF syntax on the basis of this short listing:

• Comments in an LDIF file begin with a pound character (#) at position one and continue to the end of the current line.
• Attributes are listed on the lefthand side of the colon (:), and values are presented on the righthand side. The colon character is separated from the value by a space.
• The dn attribute uniquely identifies the DN of the entry.

Distinguished Names and Relative Distinguished Names

It is important to realize that the full DN of an entry does not actually need to be stored as an attribute within that entry, even though this seems to be implied by the previous LDIF extract; it can be generated on the fly as needed. This is analogous to how a filesystem is organized. A file or directory does not store the absolute path to itself from the root of the filesystem. Think how hard it would be to move files if this were true.

If the DN is like the absolute path between the root of a filesystem and a file, a relative distinguished name (RDN) is like a filename. We've already seen that a DN is formed by stringing together the RDNs of every entity from the element in question to the root of the directory tree. In this sense, an RDN works similarly to a filename. However, unlike a filename, an RDN can be made up of multiple attributes. This is similar to a compound index in a relational database system in which two or more fields are used in combination to generate a unique index key.

While a multivalued RDN is not shown in our example, it is not hard to imagine. Suppose that there are two employees named Jane Smith in your company: one in the Sales Department and one in the Engineering Department. Now suppose the entries for these employees have a common parent. Neither the common name (cn) nor the organizational unit (ou) attribute is unique in its own right. However, both can be used in combination to generate a unique RDN. This would look like:

# Example of two entries with a multivalued RDN
dn: cn=Jane Smith+ou=Sales,dc=plainjoe,dc=org
cn: Jane Smith
ou: Sales
<...remainder of entry deleted...>
      
dn: cn=Jane Smith+ou=Engineering,dc=plainjoe,dc=org
cn: Jane Smith
ou: Engineering
<...remainder of entry deleted...>

For both of these entries, the first component of the DN is an RDN composed of two values: cn=Jane Smith+ou=Sales and cn=Jane Smith+ou=Engineering.

In the multivalued RDN, the plus character (+) separates the two attribute values used to form the RDN. What if one of the attributes used in the RDN contained the + character? To prevent the + character from being interpreted as a special character, we need to escape it using a backslash (\). The other special characters that require a backslash-escape if used within an attribute value are:

• A space or pound (#) character occurring at the beginning of the string
• A space occurring at the end of the string
• A comma (,), a plus character (+), a double quote ("), a backslash (\), angle brackets (< or >), or a semicolon (;)

Although multivalued RDNs have their place, using them excessively can become confusing, and can often be avoided by a better namespace design. In the previous example, it is obvious that the multivalued RDN could be avoided by creating different organizationalUnits (ou) in the directory for both Sales and Engineering, as illustrated in Figure 2-2. Using this strategy, the DN for the first entry would be cn=Jane Smith,ou=Sales,dc=plainjoe,dc=org. This design does not entirely eliminate the need for multivalued RDNs; we could still have two people named Jane Smith in the Engineering organization. But that will occur much less frequently than having two Jane Smiths in the company. Look for ways to organize namespaces to avoid multivalued RDNs as much as is possible and logical.

Figure 2-2. A namespace that represents Jane Smith with a unique, multivalued RDN

One final note about DNs. RFC 2253 defines a method of unambiguously representing a DN using a UTF-8 string representation. This normalization process boils down to:

• Removing all nonescaped whitespace surrounding the equal sign (=) in each RDN
• Making sure the appropriate characters are escaped
• Removing all nonescaped spaces surrounding the multi-value RDN join character (+)
• Removing all nonescaped trailing spaces on RDNs

Therefore, the normalized version of:

cn=gerald carter + ou=sales,  dc=plainjoe ,dc=org

would be:

cn=gerald carter+ou=sales,dc=plainjoe,dc=org

Without getting ahead of ourselves, I should mention that the string representation of a distinguished name is normally case-preserving, and the logic used to determine if two DNs are equal is usually a case-insensitive match. Therefore:

cn=Gerald Carter,ou=People,dc=plainjoe,dc=org

would be equivalent to:

cn=gerald carter,ou=people,dc=plainjoe,dc=org

However, this case-preserving, case-insensitive behavior is based upon the syntax and matching rules (see Section 2.2 later in this chapter) of the attribute type used in each relative component of the complete DN. So while DNs are often case-insensitive, do not assume that they will always be so.

Subsequent examples use the normalized versions of all DNs to prevent confusion, although I may tend to be lax on capitalization.

Back to Our Regularly Scheduled Program . . .

Going back to Figure 2-1, your next question is probably, "Where did the extra lines in the LDIF listing come from?" After all, the top entry in Figure 2-1 is simply dc=plainjoe,dc=org. But the LDIF lines corresponding to this entry also contain an objectClass: line and a dc: line. These extra lines provide additional information stored inside each entry. The next few sections answer the following questions:

• What is an attribute?
• What does the value of the objectClass attribute mean?
• What is the dc attribute?
• If dc=plainjoe,dc=org is the top entry in the directory, where is the entry for dc=org?

What Is an Attribute?

The concepts of attribute types and attribute syntax were mentioned briefly in the previous chapter. Attribute types and the associated syntax rules are similar to variable and data type declarations found in many programming languages. The comparison is not that big of a stretch. Attributes are used to hold values. Variables in programs perform a similar task—they store information.

When a variable is declared in a program, it is defined to be of a certain data type. This data type specifies what type of information can be stored in the variable, along with certain other rules, such as how to compare the variable's value to the data stored in another variable of the same type. For example, declaring a 16-bit integer variable in a program and then assigning it a value of 1,000,000 would make no sense (the maximum value represented by a signed 16-bit integer is 32,767). The data type of a 16-bit integer determines what data can be stored. The data type also determines how values of like type can be compared. Is 3 < 5? Yes, of course it is. How do you know? Because there exists a set of rules for comparing integers with other integers. The syntax of LDAP attribute types performs a similar function as the data type in these examples.

Unlike variables, however, LDAP attributes can be multivalued. Most procedural programming languages today enforce "store and replace" semantics of variable assignment, and so my analogy falls apart. That is, when you assign a new value to a variable, its old value is replaced. As you'll see, this isn't true for LDAP; assigning a new value to an attribute adds the value to the list of values the attribute already has. Here's the LDIF listing for the ou=devices,dc=plainjoe,dc=org entry from Figure 2-1; it demonstrates the purpose of multivalued attributes:

# LDIF listing for dn: ou=devices,dc=plainjoe,dc=org
dn: ou=devices,dc=plainjoe,dc=org
objectclass: organizationalUnit
ou: devices
telephoneNumber: +1 256 555-5446
telephoneNumber: +1 256 555-5447
description: Container for all network enabled
 devices existing within the plainjoe.org domain

Tip

Note that the description attribute spans two lines. Line continuation in LDIF is implemented by leaving exactly one space at the beginning of a line. LDIF does not require a backslash (\) to continue one line to the next, as is common in many Unix configuration files.

The LDIF file lists two values for the telephoneNumber attribute. In real life, it's common for an entity to be reachable via two or more phone numbers. Be aware that some attributes can contain only a single value at any given time. Whether an attribute is single- or multivalued depends on the attribute's definition in the server's schema. Examples of single-valued attributes include an entry's country (c), displayable name (displayName), or a user's Unix numeric ID (uidNumber).

Attribute Syntax

An attribute type's definition lays the groundwork for answers to questions such as, "What type of values can be stored in this attribute?", "Can these two values be compared?", and, if so, "How should the comparison take place?"

Continuing with our telephoneNumber example, suppose you search the directory for the person who owns the phone number 555-5446. This may seem easy when you first think about it. However, RFC 2252 explains that a telephone number can contain characters other than digits (0-9) and a hyphen (-). A telephone number can include:

• a-z
• A-Z
• 0-9
• Various punctuation characters such as commas, periods, parentheses, hyphens, colons, question marks, and spaces

555.5446 or 555 5446 are also correct matches to 555-5446. What about the area code? Should we also use it in a comparison of phone numbers?

Attribute type definitions include matching rules that tell an LDAP server how to make comparisons—which, as we've seen, isn't as easy as it seems. In Figure 2-3, taken from RFC 2256, the telephoneNumber attribute has two associated matching rules. The telephoneNumberMatch rule is used for equality comparisons. While RFC 2552 defines telephoneNumberMatch as a whitespace-insensitive comparison only, this rule is often implemented to be case-insensitive as well. The telephoneNumberSubstringsMatch rule is used for partial telephone number matches—for example, when the search criteria includes wildcards, such as "555*5446".

Figure 2-3. telephoneNumber attribute type definition

The SYNTAX keyword specifies the object identifier (OID) of the encoding rules used for storing and transmitting values of the attribute type. The number enclosed by curly braces ({ }) specifies the minimum recommended maximum length of the attribute's value that a server should support.

Object Identifiers (OIDs)

LDAPv3 uses OIDs such as those used in SNMP MIBs. SNMP OIDs are allocated by the Internet Assigned Numbers Authority (IANA) under the mgmt(2) branch of the number space displayed in Figure 2-4. Newly created LDAPv3 OIDs generally fall under the private(4), enterprise(1) branch of the tree. However, it is also common to see numbers under the joint-ISO-ccitt(2) branch of the number tree. OIDs beginning with 2.5.4 come from the user attribute specifications defined by X.500.

An OID is a string of dotted numbers that uniquely identifies items such as attributes, syntaxes, object classes, and extended controls. The allocation of enterprise numbers by IANA is similar to the central distribution of IP address blocks; once you have been assigned an enterprise number by the IANA, you can create your own OIDs underneath that number. Unlike the IP address space, there is no limit to the number of OIDs you can create because there's no limit to the length of an OID.

For example, assume that you were issued the enterprise number 55555. Therefore, all OIDs belonging to your branch of the OID tree would begin with 1.3.6.1.4.1.55555. How this subtree is divided is at your discretion. You may choose to allocate 1.3.6.1.4.1.55555.1 to department A and 1.3.6.1.4.1.55555.2 to department B. Each allocated branch of your OID is referred to as an arc. The local administrators of these departments could then subdivide their arcs according to the needs of their network.

OID assignments must be unique worldwide. If you ever need to make custom schema files for your directory (a common practice), go to http://www.iana.org/cgi-bin/enterprise.pl and request a private enterprise number. The form is short and normally takes one to two weeks to be processed. Once you have your own enterprise number, you can create your own OIDs without worrying about conflicts with OIDs that have already been assigned. RFC 3383 describes some best practices for registering new LDAP values with IANA.

Figure 2-4. Private enterprise OID number space

What Does the Value of the objectClass Attribute Mean?

All entries in an LDAP directory must have an objectClass attribute, and this attribute must have at least one value. Multiple values for the objectClass attribute are both possible and common given certain requirements, as you shall soon see. Each objectClass value acts as a template for the data to be stored in an entry. It defines a set of attributes that must be present in the entry and a set of optional attributes that may or may not be present.

Let's go back and reexamine the LDIF representation of the ou=devices,dc=plainjoe,dc=org entry:

# LDIF listing for dn: ou=devices,dc=plainjoe,dc=org
dn: ou=devices,dc=plainjoe,dc=org
objectclass: organizationalUnit
ou: devices
telephoneNumber: +1 256 555-5446
telephoneNumber: +1 256 555-5447
description: Container for all network enabled
 devices existing within the plainjoe.org domain

In this case, the entry's objectClass is an organizationalUnit. (The schema definition for this is illustrated by two different representations in Figure 2-5.) The listing on the right shows the actual definition of the objectClass from RFC 2256; the box on the left summarizes the required and optional attributes.

Figure 2-5. organizationalUnit object class

Here's how to understand an objectClass definition:

• An objectClass possesses an OID, just like attribute types, encoding syntaxes, and matching rules.
• The keyword MUST denotes a set of attributes that must be present in any instance of this object. In this case, "present" means "possesses at least one value."

  Note

  To represent a zero-length attribute value in LDIF syntax, the attribute name must be followed by a colon and zero or more spaces, and then a CR or CF/LF. For example, the following LDIF line stores a zero-length description:

  description:<ENTER>

• The keyword MAY defines a set of attributes whose presence is optional in an instance of the object.
• The keyword SUP specifies the parent object from which this object was derived. A derived object possesses all the attribute type requirements of its parent. Attributes can be derived from other attributes as well, inheriting the syntax of its parent as well as matching rules, although the latter can be locally overridden by the new attribute. LDAP objects do not support multiple inheritance; they have a single parent object, like Java objects.
• It is possible for two object classes to have common attribute members. Because the attribute type namespace is flat for an entire schema, the telephoneNumber attribute belonging to an organizationalUnit is the same attribute type as the telephoneNumber belonging to some other object class, such as a person (which is covered later in this chapter).

Object Class Types

Three types of object class definitions are used in LDAP directory servers:

Structural object classes

Represent a real-world object, such as a person or an organizationalUnit. Each entry within an LDAP directory must have exactly one structural object class listed in the objectClass attribute. According to the LDAP data model, once an entry's structural object class has been instantiated, it cannot be changed without deleting and re-adding the entire entry.

Auxiliary object classes

Add certain characteristics to a structural class. These classes cannot be used on their own, but only to supplement an existing structural object. There is a special auxiliary object class referred to in RFC 2252 named extensibleObject, which an LDAP server may support. This object class implicitly includes all attributes defined in the server's schema as optional members.

Abstract object classes

Act the same as their counterparts in object-oriented programming. These classes cannot be used directly, but only as ancestors of derived classes. The most common abstract class relating to LDAP (and X.500) that you will use is the top object class, which is the parent or ancestor of all LDAP object classes.

Note that the type of an object cannot be changed by a derived class.

What Is the dc Attribute?

Returning to our discussion of the topmost entry in Figure 2-1, we can now explain the meaning of the domain object class and the dc attribute. Here is the original LDIF listing for the entry:

# LDIF listing for the entry dn: dc=plainjoe,dc=org
dn: dc=plainjoe,dc=org
objectclass: domain
dc: plainjoe

The original recommendation for dividing the X.500 namespace was based on geographic and national regions. You frequently see this convention in LDAP directories as well, given the heritage that LDAP shares with X.500. For example, under X.500, the distinguished name for a directory server in the plainjoe.org domain might be:

dn: o=plainjoe,l=AL,c=US

Here, the o attribute is the organizationName, the l attribute is the locality of the organization, and the c attribute represents the country in which the organization exists. However, there is no central means of registering such names, and therefore no general way to refer to the naming context of a directory server. RFC 2247 introduced a system by which LDAP directory naming contexts can be piggybacked on top of an organization's existing DNS infrastructure. Because DNS domain names are guaranteed to be unique across the Internet and can be located easily, mapping an organization's domain name to an LDAP DN provides a simple way of determining the base suffix served by a directory and ensures that the naming context will be globally unique.

Note

A directory's naming context is the DN of its topmost entry. The naming context of the directory in our examples is dc=plainjoe,dc=org. This context is used by the LDAP server to determine whether it will be able to service a client request. For example, our directory server will return an error (or possibly a referral) to a client who attempts to look up the information in an entry named cn=gerald carter,ou=people,dc=taco,dc=org because the entry would be outside our naming context.

However, the server would search the directory (and return no information) if the client attempts to look up cn=gerald carter,ou=people,dc=taco,dc=plainjoe,dc=org. In this case, the directory's naming context does match the rightmost substring of the requested entry's DN. The server just does not have any information on the entry.

To support a mapping between a DNS domain name and an LDAP directory namespace, RFC 2247 defines two objects, shown in Figures 2-6 and 2-7, for storing domain components. The dcObject is an auxiliary class to augment an existing entry containing organizational information (e.g., an organizationalUnit). The domain object class acts as a standalone container for both the organizational information and the domain name component (i.e., the dc attribute). The organizationalUnit and domain objects have many common attributes.

Figure 2-6. domain object class

Figure 2-7. dcObject object class

Generating an LDAP DN to represent a DNS domain name is a simple process. An empty DN is used as a starting point. An RDN of dc= domain component is appended to the DN for each portion of the domain name. For example, the domain name plainjoe.org maps to our naming context of dc=plainjoe,dc=org.

Where Is dc=org?

As we saw in the previous section, dc=plainjoe,dc=org is the directory's naming context. If the directory's root entry was dc=org, with a child entry of dc=plainjoe,dc=org, then the naming context would have been dc=org. Our server would then unnecessarily respond to queries for any entry whose DN ended with dc=org, even though it only has knowledge of entries underneath dc=plainjoe,dc=org.

In this respect, designing an LDAP namespace is similar to designing a DNS hierarchy. Domain name servers for plainjoe.org have no need to service requests for the .org domain. These requests should be referred to the server that actually contains information about the requested hosts.

Schema References

One of the most frequent questions asked by newly designated LDAP administrators is, "What do all of these abbreviations mean?" Of course, the question refers to things such as cn, c, and sn. There is no single source of information describing all possible LDAPv3 attribute types and object classes, but there are a handful of online sites that can be consulted to cover the most common schema items:

RFC 3377 and related LDAPv3 standards (http://www.rfc-editor.org/)

The documents outlined in RFC 3377 provide a list of references for researching related LDAPv3 and X.500 topics. RFC 2256 in particular describes a set of X.500 schema items used with LDAPv3 directory servers.

LDAP Schema Viewer (http://ldap.akbkhome.com/)

This site, maintained by Alan Knowles, provides a nice means of browsing descriptions and dependencies among common LDAP attributes, object classes, and OIDs.

Object Identifiers Registry (http://www.alvestrand.no/objectid/)

This site can be helpful in tracking down the owner of specific OID arcs.

Sun Microsystems Product Documentation (http://docs.sun.com)

The SunOne Directory Server, formerly owned by Netscape Communications, includes a large set of reference documentation on various LDAP schema items. Even if you are not using the SunOne DS product, the schema reference can be helpful in understanding the meaning of various LDAP acronyms. Search the site for "LDAP schema reference" to locate the most recent versions of the product documentation.

Authentication

Why is authentication needed in an LDAP directory? Remember that LDAP is a connection-oriented, message-based protocol. The authentication process is used to establish the client's privileges for each session. All searches, queries, etc. are controlled by the authorization level of the authenticated user.

Figure 2-8 describes the person object class and gives you an idea of what other attributes are available for the cn=gerald carter entry in Figure 2-1. In particular, you will need to define a userPassword attribute value to further explore LDAP authentication.

Figure 2-8. person objectClass

The LDIF representation for the expanded version cn=gerald carter is:

dn: cn=gerald carter,ou=people,dc=plainjoe,dc=org
objectClass: person
cn: gerald carter
sn: carter
telephoneNumber: 555-1234
userPassword: {MD5}Xr4ilOzQ4PCOq3aQ0qbuaQ=  =

We have added an attribute named userPassword. This attribute stores a representation of the credentials necessary to authenticate a user. The prefix (in this case, {MD5}) describes how the credentials are encoded. The value in this case is simply the Base64 encoding of the MD5 hash of the word "secret."

RFC 2307 defines prefixes for several encryption algorithms. These are vendor-dependent, and you should consult your server's documentation to determine which are supported. Generating userPassword values will be covered in more detail in the context of various programming languages and APIs in later chapters. Some common encoding types are:

{CRYPT}

The password hash should be generated using the local system's crypt( ) function, which is normally included in the standard C library. The {CRYPT} prefix will be seen quite a bit in Chapter 6 when we discuss using LDAP as a replacement for NIS.

{MD5}

The password hash is the Base64 encoding of the MD5 digest of the user's password.

{SHA} (Secure Hash Algorithm)

The password hash is the Base64 encoding of the 160-bit SHA-1 hash (RFC 3174) of the user's password.

{SSHA} (Salted Secure Hash Algorithm)

This password-hashing algorithm developed by Netscape is a salted version of the previous SHA-1 mechanism. {SSHA} is the recommended scheme for securely storing password information in an LDAP directory.

The act of being authenticated by an LDAP directory is called binding. Most users are accustomed to providing a username and password pair when logging onto a system. When authenticating an LDAP client, the username is specified as a DN—in our example, cn=gerald carter,ou=people,dc=plainjoe,dc=org. The credentials used to authenticate this entry are given by the value of the userPassword attribute.

The LDAPv3 specifications define several mechanisms for authenticating clients:

• Anonymous Authentication
• Simple Authentication
• Simple Authentication over SSL/TLS
• Simple Authentication and Security Layer (SASL)

Anonymous Authentication

Anonymous Authentication is the process of binding to the directory using an empty DN and password. This form of authentication is very common; it's frequently used by client applications (for example, email clients searching an address book).

Simple Authentication

For Simple Authentication, the login name in the form of a DN is sent with a password in clear text to the LDAP server. The server then attempts to match this password with the userPassword value, or with some other predefined attribute that is contained in the entry for the specified DN. If the password is stored in a hashed format, the server must generate the hash of the transmitted password and compare it to the stored version. However, the original password has been transmitted over the network in the clear. If both passwords (or password hashes) match, the client is successfully authenticated. While this authentication method is supported by virtually all existing LDAP servers (including LDAPv2 servers), its major drawback is its dependency on the client transmitting clear-text values across the network.

Simple Authentication Over SSL/TLS

If sending usernames and passwords over the network is not particularly tasty to you, perhaps wrapping the information in an encrypted transport layer will make it more palatable. LDAP can negotiate an encrypted transport layer prior to performing any bind operations. Thus, all user information is kept secure (as well as anything else transmitted during the session).

There are two means of using SSL/TLS with LDAPv3:

• LDAP over SSL (LDAPS - tcp/636) is well supported by many LDAP servers, both commercial and open source. Although frequently used, it has been deprecated in favor of the StartTLS LDAP extended operation.
• RFC 2830 introduced an LDAPv3 extended operation for negotiating TLS over the standard tcp/389 port. This operation, which is known as StartTLS, allows a server to support both encrypted and nonencrypted sessions on the same port, depending on the clients' requests.

With the exception of the transport layer security negotiation, the binding process is the same as for Simple Authentication.

Tip

Designers of LDAPv3 defined two pieces of functionality, Extended Operations and Controls, to allow for additions to the original protocol without requiring a new version to be standardized. LDAP Controls apply only to individual requests and responses, similar to the way an adjective extends a noun. Depending on the client's needs, if a server does not support a specified Control, the request may fail, or the Control may simply be ignored and the request will continue normally. An Extended Operation is the equivalent of defining a new word that must be understood by both the client and server.

Simple Authentication and Security Layer (SASL)

SASL is an extensible security scheme defined in RFC 2222 that can be used to add additional authentication mechanisms to connection-oriented protocols such as IMAP and LDAP. In essence, SASL supports a pluggable authentication scheme by allowing a client and server to negotiate the authentication mechanism prior to the transmission of any user credentials.

In addition to negotiating an authentication mechanism, the communicating hosts may also negotiate a security layer (such as SSL/TLS) that will be used to encrypt all data during the session. The negotiation of transport layer security within SASL is not related either to the StartTLS Extended Operation or to LDAPS.

RFC 2222 defines the several authentication schemes for SASL, including:

• Kerberos v4 (KERBEROS_V4)
• The Generic Security Service Application Program Interface, Version 2 (GSSAPI), which is defined in RFC 2078
• The S/Key mechanism (SKEY), which is a one-time password scheme based on the MD5 message digest algorithm
• The External (EXTERNAL) mechanism, which allows an application to make use of a user's credentials provided by a lower protocol layer, such as authentication provided by SSL/TLS

In addition to these, RFC 2831 has added an SASL/DIGEST-MD5 mechanism. This mechanism is compatible with HTTP/1.1 Digest Access Authentication.

During the binding process, the client asks the server to authenticate its request using a particular SASL plug-in. The client and server then perform any extra steps necessary to validate the user's credentials. Once a success or failure condition has been reached, the server returns a response to the client's bind request as usual, and LDAP communication continues normally.

Distributed Directories

At this point we have completed examining the simple directory of Figure 2-1. Since we have covered the basics, let's expand Figure 2-1 to create a distributed directory. In a distributed directory, different hosts possess different portions of the directory tree.

Figure 2-9 illustrates how the directory would look if the people ou were housed on a separate host. There are many reasons for distributing the directory tree across multiple hosts. These can include, but are not limited to:

Performance

Perhaps one section of the directory tree is heavily used. Placing this branch on a host by itself lets clients access the remaining subtrees more quickly.

Geographic location

Are all the clients that access a particular branch of the directory in one location? If so, it would make more sense to place this section of the directory closer to the client hosts that require it. In this way, trips across a possibly slow WAN link can be avoided.

Administrative boundaries

It is sometimes easier to delegate administrative control of a directory branch by placing the branch on a server controlled by the group responsible for the information in that branch. In this way, the server operators can have full access for duties such as replication and backups without interfering with a larger, more public server.

Figure 2-9. Building a distributed directory

To divide the directory tree between the two servers in Figure 2-9, you must configure two links between the main directory server and the server that holds people ou. To do so, create the superior and subordinate knowledge reference links as shown.

A subordinate knowledge link, often called simply a reference , logically connects a node within a directory tree to the naming context of another server. Most often, the naming context of the second server is a continuation of the directory. In this example, the people ou in the main directory tree has no children because all queries of entries in the ou=people,dc=plainjoe,dc=org tree should be served by the second server. The entry ou=people,dc=plainjoe,dc=org on the main directory server is now a placeholder that contains the referral to the actual directory server for this entry. Figure 2-10 shows the definition for the the referral object class defined in RFC 3296.

Figure 2-10. The referral object class

Warning

LDAPv2 servers based on the original University of Michigan LDAP server supported an experimental means of using referrals that is incompatible with the standardized referrals included in LDAPv3.

The referral object contains only a single required attribute, ref. This attribute holds the URI that points to the host that contains the subtree. The format of this URI is defined in RFC 2255 as:

ldap://[host:port]/[/dn[?attribute][?scope][?filter][?extensions]]

This syntax will make more sense when we have covered LDAP search parameters in Chapter 4. For our purposes, the most common URI used as a ref value looks like:

ldap://[host:port]/dn

For example, the LDIF listing for the new people ou entry is:

# LDIF listing for the entry ou=people,dc=plainjoe,dc=org
dn: ou=people,dc=plainjoe,dc=org
objectClass: referral
ref: ldap://server2.plainjoe.org/ou=people,dc=plainjoe,dc=org

Configuring the superior knowledge reference link, also called simply a referral but not to be confused with the referral object class, from the second server back to the main directory is a vendor-dependent operation, so it is difficult to tell you exactly what to expect. However, the purpose is to define an LDAP URI (just like the one used as the ref attribute value) that should be returned to clients who attempt to search or query entries outside of the naming context of the subordinate server. In the example discussed here, server2 would be configured to return ldap://server1.plainjoe.org/dc=plainjoe,dc=org to all clients who attempt to go outside of ou=people,dc=plainjoe,dc=org.

Who should follow the referral link? There are two possible answers:

• The server follows and resolves any referrals that it runs into during an LDAP operation. The client receives only the result and never knows that the referral happened. This is known as "chaining" and is similar to a recursive DNS server. Chaining has not been standardized. If you are interested, you should consult the documentation for your server to determine whether chaining is supported.
• The client follows links for itself. The LDAP client library normally follows the link, but the URI can be handed to the calling application, which is then responsible for following the link itself. This method is supported by all LDAPv3-compliant clients and servers.

Tip

There is one more mechanism for redirecting a client. An alias is a symbolic link in the directory pointing from one entry to another (possibly on a different server). Aliases can be used only on an entry, not on individual attributes. There may be specific situations that require the use of aliases, but these are likely to be few. For this reason, aliases are not stressed beyond the discussion here.

Continuing Standardization

LDAP is continuing to evolve as a protocol. There are currently two working groups within the IETF to help shepherd this process:

• The LDAP Duplication/Replication/Update Protocols (LDUP) working group focuses on data replication and consistency in LDAP directories. More information on the group's current activities can be found at http://ietf.org/html.charters/ldup-charter.html.
• The LDAPv3 Revision (LDAPbis) working group directs its efforts toward attempting to clarify parts of the original LDAPv3 specifications. This does not include work on a Version 4 of the LDAP protocol. More information on the LDAPbis working group can be found at http://ietf.org/html.charters/ldapbis-charter.html.

While not related to standardization processes, the LDAPzone web site (http://www.ldapzone.com) does provide a nice collection of LDAP-related topics, forums, and downloads.

Chapter 3. OpenLDAP

While reading this book, you may find yourself feeling a little like a sky diver who has just jumped out of an airplane. As you approach the ground, things come more into focus. As you squint and try to make out the color of that house far below, you suddenly realize that you are plummeting closer and closer toward the very thing you are trying to observe.

Conceptual ideas need concrete implementations in order to solidify our understanding of them. A directory access protocol is of no use without an actual implementation that allows us to put the protocol to work to solve real information problems on a network. This chapter introduces OpenLDAP, a popular, open source LDAPv3-compliant server. There are a number of popular commercial products, including Sun Microsystem's SunOne directory server (formally owned by Netscape), Novell's eDirectory (formally referred to as NDS), and Microsoft's Active Directory, although this directory encompasses much more than just LDAP.

Why are we using the OpenLDAP^[1] server instead of one from another vendor? OpenLDAP is attractive for several reasons:

• The OpenLDAP source code is available for download from http://www.openldap.org/ under the OpenLDAP Public License. Source code can provide a great deal of information to supplement existing (or absent) documentation.
• OpenLDAP 2 is compliant with the core LDAPv3 specifications.
• OpenLDAP is available for multiple platforms, including Linux, Solaris, Mac OS 10.2, and Windows (in its various incarnations). For more information regarding OpenLDAP on Mac OS 10.2, see http://www.padl.com//Articles/AdvancedOpenDirectoryConf.html.
• The OpenLDAP project is a continuation of the original University of Michigan LDAP server. The relationship between Michigan's LDAP server and many modern, commercial LDAP servers can be compared to the relationship between modern web browsers and the original NCSA Mosaic code base.

The examples presented in this chapter configure OpenLDAP on a Unix-based server. Therefore, they use standard Unix command-line tools such as tar, gzip, and make.

Obtaining the OpenLDAP Distribution

The OpenLDAP project does not make binary distributions of its software available. The reason for this has a lot to do with the number of dependencies it has on other packages. Many Linux vendors include precompiled versions of OpenLDAP with their distributions. Still, we'll discuss how to compile the OpenLDAP source code distribution; you'll need to build OpenLDAP to stay up to date, and studying the build process gives you a chance to learn more about the LDAP protocol.

Tip

Symas Corporation also provides some precompiled OpenLDAP packages (including requisite software components) for Solaris and HP-UX at http://www.symas.com/.

The latest version of OpenLDAP can be obtained from http://www.OpenLDAP.org/software/download/. There are two major incarnations of OpenLDAP. The older 1.2 releases are essentially enhancements or small bug fixes to the original University of Michigan code base and implement only LDAPv2. The OpenLDAP 2 branch is an LDAPv3-compliant implementation.

There are several advantages of LDAPv3 over the previous version, such as:

• The ability to refer clients to other LDAP servers for information. The LDAPv2 RFCs contained no provision for returning a referral to a client. While the University of Michigan server supported an experimental implementation of referrals, the concept was not standardized until the LDAPv3 specifications. Standardization made interoperability between servers and clients from different vendors possible, something that was missing under LDAPv2.
• The ability to publish the server's schema via LDAP operations, which makes it easier for clients to learn the server's schema before performing searches. The only way to determine the schema supported by an LDAPv2 server was to examine the server's configuration files. Publishing the server's schema as entries within the directory allows for such things as real-time updates via standard LDAP operations. (Note that LDAPv3 does not require dynamic updates.)
• Internationalization support through the use of UTF-8 characters in strings (RFC 2253) and language tags for attribute descriptions (RFC 2596).
• Improved security and flexibility for authentication credentials and data via SASL and SSL/TLS. LDAPv2 supported only simple binds or Kerberos 4 authentication.
• Support for protocol extensions as a mechanism to enhance existing operations or add new commands without requiring that a new revision of the LDAP protocol be defined.

The OpenLDAP 2 release is an LDAPv3 server. However, LDAPv2 clients are not going away anytime soon. Therefore, OpenLDAP 2 and the majority of other LDAP servers can support both LDAPv2 and v3 clients.^[2]

^[1] The "Open" in OpenLDAP refers to the open engineering process and community used to create OpenLDAP software.

^[2] Most people are referring to the University of Michigan LDAP client and server implementation when using the term LDAPv2. LDAPv2 as specified in the original RFCs has been moved to historic status.

Software Requirements

The examples presented in this book for building the client tools and server components are based on the latest OpenLDAP 2.1 release available at the current time (Version 2.1.8). As with any piece of software, version numbers and dependencies change. Make sure to consult the documentation included with future OpenLDAP releases before building your server.

Our OpenLDAP server will require several external software packages:

• Support for POSIX threads, either by the operating system or an external library.
• SSL/TLS libraries (such as the OpenSSL package, which is available from http://www.openssl.org/).
• A database manager library that supports DBM type storage facilities. The current library of choice is the Berkeley DB 4.1 package from Sleepycat Software (http://www.sleepycat.com/).
• Release 2.1 of the SASL libraries from Carnegie Mellon University (http://asg.web.cmu.edu/sasl/sasl-library.html).

Threads

If your server's operating system supports threads, OpenLDAP 2 can take advantage of this feature. This support works fine out of the box on most current Linux systems, Solaris, and several other platforms.

If you run into problems related to POSIX thread support, your first option is to check the OpenLDAP.org web site for installation notes specific to your platform. You may also wish to visit http://www.gnu.ai.mit.edu/software/pth/related.html for a list of known POSIX thread libraries for Unix systems. It is possible to disable thread support in the OpenLDAP server, slapd , by specifying the —disable-threads option in the OpenLDAP configure script prior to compiling. However, the replication helper daemon, slurpd, which is covered in Chapter 5, requires thread support.

SSL/TLS Libraries

RFC 2246 describes TLS 1.0, which resembles SSL 3.0. The StartTLS extended operation defined in RFC 2830 allows LDAP clients and servers to negotiate a TLS session at any point during a conversation (even prior to authenticating the client). To enable support for this extended operation or the LDAPS protocol, you need to obtain and install the latest version of the OpenSSL libraries. These can be downloaded from the OpenSSL Project at http://www.openssl.org/.

Building and installing the OpenSSL libraries is straightforward. Just remember that, as of release 0.9.6g, shared libraries are not built by default. To build shared libraries, pass the shared option to the OpenSSL build script. The —openssldir option is used to define the install directory:

$ ./config shared --openssldir=/usr/local

Then follow with the obligatory:

$ make
$ /bin/su -c "make install"

to install the development libraries and tools in /usr/local/.

Database Backend Modules

In order to build a standalone OpenLDAP server, it is necessary to provide libraries for some type of database manager (DBM). OpenLDAP presently supports two categories of local DB storage. The first, referred to as ldbm , can use either the GNU Database Manager from the Free Software Foundation (http://www.fsf.org/) or the BerkeleyDB package from Sleepycat software (http://www.sleepycat.com/). The second database type introduced in OpenLDAP 2.1, called bdb , has been customized to use only the Berkeley DB 4 libraries. The newer bdb backend type is preferred to the ldbm interface for servers that maintain local copies of data, such as those we will build in this book.

To obtain and install the Berkeley DB 4.1 libraries, begin by downloading the source code from http://www.sleepycat.com/download/index.shtml. Next, extract the source code to a temporary directory such as /usr/local/src/. This example uses the release 4.1.24:

$ cd /usr/local/src/
$ gzip -dc {path-to-download-directory}/db-4.1.24.tar.gz | tar xvf -

The instructions for building the software on Unix-like systems are linked from the beginning page of the software's documentation in db-<version>/docs/index.html. For most purposes, this boils down to:

$ cd db-version/build_unix
$ ../dist/configure --prefix=/usr/local/
$ make
$ /bin/su -c "make install"

You can choose an installation directory other than /usr/local/ as long as you remember to take any necessary steps to ensure that the libraries and development files can be found by both the Cyrus SASL libraries and OpenLDAP when compiling these packages.

Once the process is completed, verify that the file libdb-4.1.so exists in the lib/ directory below the installation root (e.g., /usr/local/lib/).

SASL Libraries

Chapter 2 introduced the concept of pluggable authentication mechanisms. While the SASL libraries are not required to build OpenLDAP 2, the resulting LDAP server will not be completely LDAPv3-compliant if SASL is absent.

The Computing Services Department at Carnegie-Mellon University has made a set of SASL libraries available for download under a BSD-like license. The latest version can be found at ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/. The cyrus-sasl libraries v2.1 support several SASL mechanisms, including:

Tip

To support the Kerberos plug-ins, you must obtain libraries from either Heimdal Kerberos (http://www.pdc.kth.se/heimdal/) or the MIT Kerberos distribution (http://web.mit.edu/kerberos/www/).

Understanding SASL is somewhat of an undertaking. You don't need to install the SASL libraries if you plan to support only simple (clear-text) binds and simple binds over SSL/TLS. The most common reasons for requiring SASL integration with LDAP are Kerberos authentication and integration with other SASL-enabled applications, such as Sendmail or CMU's Cyrus IMAPD server.

For the sake of flexibility, we will build the server with SASL support. I recommend reading the SASL System Administrator's HOWTO (sysadmin.html) included as part of the CMU distribution. This document gives some general setup and configuration information. You may also wish to review the "GSSAPI Tutorial" mentioned in the HOWTO and the Programmer's Guide. All of these are included in the Cyrus SASL distribution under the doc/ directory. You may also wish to refer to RFC 2222 for a general overview of SASL. The sample/ subdirectory also includes a program for testing the SASL libraries. Chapter 9 includes examples of using the GSSAPI SASL mechanism when exploring interoperability with Microsoft's Active Directory.

Building the SASL distribution requires only a few familar steps. In most environments, the following commands will install the libraries and development files in /usr/local/:

$ gzip -dc cyrus-sasl-2.1.9.tar.gz | tar xf -
$ cd cyrus-sasl-2.1.9
$ ./configure
$ make
$ /bin/su -c "make install && \
  ln -s /usr/local/lib/sasl2 /usr/lib/sasl2"

The symbolic link is needed because the SASL library will look for installed mechanisms in /usr/lib/sasl2/ (as described in the cyrus-sasl documentation).

Compiling OpenLDAP 2

Once the necessary software libraries have been installed and correctly configured, compiling and installing OpenLDAP becomes a matter defining the appropriate options for the configure script and executing the make command. For the sake of simplicity, all examples in this book assume that the root directory for the OpenLDAP installation is /usr/local, which is the default.

Most of the configuration options are set to reasonable defaults or will be set appropriately by the configure script itself. I've already mentioned the —disable-threads option, which you can use if you don't want thread support. You should also be aware of the —enable-wrappers option, which uses the tcp_wrappers libraries for restricting access via the standard /etc/hosts.allow and /etc/hosts.deny. In order to use this option, the tcpd.h header file and libwrap.a library must be installed on a local system.

Tip

For more information on tcp_wrappers, refer to the hosts_access(5) manpage or Wietse Venema's tcp_wrappers web page, which is located at ftp://ftp.porcupine.org/pub/security/index.html.

After extracting the source files using the command:

$ gzip -dc openldap-2.1.8.tar.gz | tar xvf -

go into the newly created directory and execute the ./configure script, defining any options you wish to enable or disable. For example:

$ cd openldap-2.1.8/
$ ./configure --enable-wrappers

Be sure to examine the output that follows this command to verify that the correct DBM libraries were located and any other options you defined were correctly configured. Once you are satisfied with the configuration process, building the OpenLDAP clients and servers is a four-step process:

$ make depend
$ make
$ make test
$ /bin/su -c "make install"

Here are some things to check if you have any problems:

• On systems that support it, the ldd tool can be used to verify that the LDAP server binary, slapd, is linked with the correct shared libraries. For example, if libsasl.so cannot be located but is installed in /usr/local/lib/, check your system's documentation for adding directories to the library search path. Under Linux, add the directory to /etc/ld.so.conf and rerun ldconfig -v; under Solaris (or Linux), set the LD_LIBRARY_PATH environment variable.
• Verify that DNS resolution for your host is configured correctly. In particular, reverse DNS resolution is important. Problems with DNS resolution can make it appear that the OpenLDAP server is not responding.
• Verify that the network interface on the host is configured and functioning properly. I experience this problem quite often when using my laptop as a test server.

OpenLDAP Clients and Servers

The OpenLDAP package includes clients, servers, and development libraries. Table 3-1 gives an overview of the utilities that come with the package. All pathnames are relative to the installation location, which defaults to /usr/local.

Table 3-1. Installed components included with OpenLDAP

The slapd.conf Configuration File

The slapd.conf file is the central source of configuration information for the OpenLDAP standalone server (slapd), the replication helper daemon (slurpd), and related tools, such as slapcat and slapadd. As a general rule, the OpenLDAP client tools such as ldapmodify and ldapsearch use ldap.conf (not slapd.conf) for default settings.

In the tradition of Unix configuration files, slapd.conf is an ASCII file with the following rules:

• Blank lines and lines beginning with a pound sign (#) are ignored.
• Parameters and associated values are separated by whitespace characters (space or tab).
• A line with a blank space in the first column is considered to be a continuation of the previous one. There is no need for a line continuation character such as a backslash (\).

For general needs, the slapd.conf file used by OpenLDAP 2 can be broken into two sections. The first section contains parameters that affect the overall behavior of the OpenLDAP servers (for example, the level of information sent to log files). The second section is composed of parameters that relate to a particular database backend used by the slapd daemon. It is possible to define some default settings for these in the global section of slapd.conf. However, any value specified in the database section will override default settings.

Here's a partial listing that shows how these two sections look:

# /usr/local/etc/openldap/slapd.conf
      
# Global section
      
## Global parameters removed for brevity's sake, for now . . .
      
#######################################################
# Database #1 - Berkeley DB
database      bdb
      
## Database parameters and directives would go here.
      
#######################################################
# Database #2 - Berkeley DB
database      bdb
      
## Database parameters and directives would go here.
      
## And so on . . .

The global section starts at the beginning of the file and continues until the first database directive. We will revisit the few parameters listed here in a few moments.

The start of a database backend section is marked by the database parameter; the section continues until the beginning of the next database section or the end of the file. It is possible to define multiple databases that are served by a single installation of slapd. Each one is logically independent, and the associated database files will be stored separately.

Warning

For security reasons, the slapd.conf file should be readable and writable only by the user who runs the slapd daemon, which is normally the superuser. A working server's slapd.conf often contains sensitive information that should be restricted from unauthorized viewing.

Schema Files

The first step in configuring your LDAP server is to decide which schema the directory should support. It's not easy to answer this question in a few lines. We'll start our example with the bare minimum.

OpenLDAP 2 includes several popular schema files to be used at the administrator's discretion. The needs of the applications that will use the directory determine which schema you use. All the attributeType and objectClass definitions required for a bare-bones server are included in the file core.schema. Some of these attributeTypes and objectClasses are:

• Attributes for storing the timestamp of the last update on an entry
• Attributes for representing name, locations, etc.
• Objects to represent an organization or person
• Objects to represent DNS domain names
• And so on . . .

By default, this file is located in the directory /usr/local/etc/openldap/schema/ after installation. In the configuration file, the include parameter specifies schemas to be included by the server. Here's how the file looks for a minimal configuration:

# /usr/local/etc/openldap/slapd.conf
      
# Global section
      
## Include the minimum schema required.
include     /usr/local/etc/openldap/schema/core.schema
      
#######################################################
## Database sections omitted

Tip

I won't discuss the details of what is contained in core.schema yet. I'll delay this discussion until adequate time can be spent on the syntax of the file. If you would like a head start, reading RFC 2552 will provide the necessary knowledge for understanding the majority of OpenLDAP's schema files.

There are several schema files included with a default OpenLDAP 2.1 installation:

corba.schema

A schema for storing Corba objects in an LDAP directory, as described in RFC 2714.

core.schema

OpenLDAP's required core schema. This schema defines basic LDAPv3 attributes and objects described in RFCs 2251-2256.

cosine.schema

A schema for supporting the COSINE and X.500 directory pilots. Based on RFC 1274.

inetorgperson.schema

The schema that defines the inetOrgPerson object class and its associated attributes defined in RFC 2798. This object is frequently used to store contact information for people.

java.schema

A schema defined in RFC 2713 for storing a Java serialized object, a Java marshalled object, a remote Java object, or a JNDI reference in an LDAP directory.

misc.schema

A schema that defines a small group of miscellaneous objects and attributes. Currently, this file contains the schema necessary to implement LDAP-based mail routing in Sendmail 8.10+.

nis.schema

A schema that defines attributes and objects necessary for using LDAP with the Network Information Service (NIS) as described in RFC 2307 (see Chapter 6).

openldap.schema

Miscellaneous objects used by the OpenLDAP project. Provided for information purposes only.

The client applications that you want to support may require you to include schema files in addition to core.schema. Make sure you are aware of dependencies between schema files. Dependencies are normally described at the beginning of the file. For example, many applications require you to include the inetOrgPerson object class, which is frequently used to store contact information. The beginning of the inetorgperson.schema file tells you that you must also include cosine.schema.

Logging

The next group of parameters that you frequently find in the global section of slapd.conf control where slapd logs information during execution, as well as how much information is actually written to the log. Here's our configuration file with logging added:

# /usr/local/etc/openldap/slapd.conf
      
# Global section
      
## Include the minimum schema required.
include     /usr/local/etc/openldap/schema/core.schema
      
## Added logging parameters
loglevel     296
pidfile      /usr/local/var/slapd.pid
argsfile     /usr/local/var/slapd.args
      
#######################################################
## Database sections omitted

The first new parameter is loglevel . This directive accepts an integer representing the types of information that should be recorded in the system logs. It is helpful to think of loglevel as a set of bit flags that can be logically ORed together. The flags are listed in Table 3-2. In this example, the logging level is set to 296, which equals 8 + 32 + 256. Table 3-2 tells us that this value causes slapd to log the following information:

8

Connection management

32

Search filter processing

256

Statistics for connection, operations, and results

Table 3-2. OpenLDAP logging levels

All debugging information is logged using the LOG_LEVEL4 syslog facility. Therefore, to instruct slapd to write log entries to a separate log file, add the following line to /etc/syslog.conf and instruct the syslogd daemon to reread its configuration file by sending it a hangup (kill -HUP) signal:

local4.debug          /var/log/slapd.log

The syntax of syslog.conf on your system may be slightly different, so you should consult the syslog.conf manpage for details.

Warning

Some syslogd daemons require that the specified logging file exists before they write information to the log. If you think you have set up syslog correctly, but no data is being collected and your file doesn't exist, try creating the logging file with the touch command.

The remaining two parameters introduced in this section can be summed up in a sentence or two:

pidfile filename

This parameter specifies the absolute location of a file that will contain the process ID of the currently running master slapd process.

argsfile filename

This parameter specifies the absolute path to a file containing the command-line parameters used by the currently running master slapd. This parameter is processed only if slapd is started without the debug command-line argument.

SASL Options

When I first introduced the topic of installing the Cyrus SASL libraries, I said that SASL is not needed if only simple binds will be used to access the directory. However, it's often useful to allow a combination of simple binds and SASL mechanisms for user connections. For example, we might want to allow most users (who are only allowed to look up data) to authenticate via a simple bind, while requiring administrators (who are allowed to change data) to authenticate via SASL. So let's see how to configure the directory server to require the use of SASL for certain administrative accounts, while still allowing simple binds (possibly over TLS) for most clients.

slapd.conf has three SASL-related global options. These are:

sasl-host is the fully qualified domain name of the host used for SASL authentication. For local authentication mechanisms such as DIGEST-MD5, this will be the host and domain name of the slapd server. sasl-realm is the SASL domain used for authentication. If you are unsure of this value, use sasldblistusers to dump the /etc/sasldb database and obtain the realm name to use.

The third parameter, sasl-secprops, allows you to define various conditions that affect SASL security properties. The possible values for this parameter are given in Table 3-3. Note that it is legal to use multiple values in combination. The default security properties are noanonymous and noplain.

Table 3-3. sasl-secprops parameter values and descriptions

To fully understand the sasl-secprops parameter, you must also understand the effects of the various cyrus-sasl plug-ins. Table 3-4 summarizes the available mechanisms and property flags.

Table 3-4. SASL authentication mechanism security properties

Consider if you had added the following line to the global section of your current slapd.conf:

## No PLAIN or ANONYMOUS mechanisms; use DES encrpytion
sasl-secprops     noplain,noanonymous,minssf=56

Comparing the value of sasl-secprops with the mechanisms listed in Table 3-4 shows that your server will allow only the following mechanisms for authentication:

This configuration assumes that all of these SASL plug-ins have been installed as well. Also remember that configuring these SASL parameters does not require that an SASL mechanism must always be used for authentication.

SSL/TLS Options

Like the SASL parameters, slapd.conf offers several options for configuring settings related to SSL and TLS. These parameters include:

The TLSCipherSuite parameter allows you to specify which ciphers the server will accept. It also specifies a preference order for the ciphers. The value for TLSCipherSuite should be a colon-separated list of cipher suites. The explanation of available cipher suites is lengthy, so I won't reproduce it; refer to the ciphers(1) manpage distributed with OpenSSL. Here are a few common options; the order of preference is from left to right:

The next two parameters, TLSCertificateFile and TLSCertificateKeyFile , inform slapd of the location of the server's certificate and the associated private key. This will be used to implement both LDAP over SSL (LDAPS) and the StartTLS extended operation. However, you have yet to create a certificate for your server.

Generating the server's certificate

The CA.pl Perl script, installed in /usr/local/misc/ as part of the OpenSSL installation, provides a nice wrapper around the openssl tool and its command-line arguments. To use this script, openssl must be located in the current search path.

Crypto 101

In my own work configuring OpenSSL and the services that use these libraries, I have found the documentation a little sparse. If you are interested in learning more about SSL, cryptography, or digital certificates, the following sources are a good place to start:

• "An Introduction to SSL," http://developer.netscape.com/docs/manuals/security/sslin/content.htm.
• T. Dierks, et al., "The TLS Protocol Version 1.0", RFC2246, January 1999.
• C. Kaufman, et al., Network Security: PRIVATE Communication in a PUBLIC World (Prentice Hall).
• Peter Gutmann's "Godzilla Crypto Tutorials Slides," http://www.cs.auckland.ac.nz/~pgut001/.
• Bruce Schneier, Applied Cryptography: Protocols, Algorithms, and Source Code in C (John Wiley & Sons).
• John Viéga, et al., Network Security with OpenSSL (O'Reilly).

The CA.pl script greatly simplifies the creation of server certificates. In order to create a new certificate, use the -newcert command-line option and answer the questions as prompted. Here's how to use CA.pl to create a new certificate:

$ /usr/local/misc/CA.pl -newcert
Enter PEM pass phrase:test
Verifying password - Enter PEM pass phrase:test
-----
You are about to be asked to enter information that will be incorporated into your
certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [GB]:US
State or Province Name (full name) [Berkshire]:Alabama
Locality Name (eg, city) [Newbury]:Somewhere
Organization Name (eg, company) [My Company Ltd]:PlaineJoe Dot Org
Organizational Unit Name (eg, section) [  ]:IT
Common Name (eg, your name or your server's hostname) [  ]:pogo.plainjoe.org
Email Address [  ]:[email protected]
Certificate (and private key) is in newreq.pem

This command creates a file named newreq.pem that contains a password-protected private key and a self-signed certificate. Here are the contents of newreq.pem:

-----BEGIN RSA PRIVATE KEY-----
Proc-Type: 4,ENCRYPTED
DEK-Info: DES-EDE3-CBC,D8851189E7EA85CE
      
ImZpOfzqhNhNa6MRQBtYxjPbWmHw+3XxVAowO1FJyFQRQhuRDqrUia1IW7Tikb4d
rvjbv8T1+SN9vRGWBpz3nAERnS6uEnzPu201b9X413uXaF80TYYId7OUalG5mjqr
GG0oHaYwbmvAIRyhq3zhqCnBgscZ0l5DCXGTw0T1TeqaTfD8BpRE4ES+F0dlKjRf
yXuXmLrTg0C9ITokzRj4Xtu0nJfQ5LKouooeI43FHqFBFV4Jw5IIKOuAg/tkinez
VqVesaV707PLqdlYNAVx26z/nPwbbAT2JY4fqemBzjBJPDN6Tr/QncYgbMcG+H5/
7z7mBmOWq7nCpgFSwV1KgvtDIOjqZmGSpTLbZ/pY+JUT3iPsRAaL5XHDZDM6pF0l
R70ePd3Z5sUcg1TJlnuPYejyTi1OM/hoKrNnjM+4bTY8St14zAaMV15G/3GGJue0
jeJkBZba8UpQ539yPfuPINueJFG+QipDUnHWVHSWIGhqiKVZxPTZWCZrgHx7UbYw
fQVORGQ6ddu6vYNiODYXUnN3YtvD02OkbiGVl53OXlYv5hOydqdWRhA1hfR8SKAG
fnt1OV9yjC/0K2mj+nMNOu5kHMfA+Q6hw7mvWAsR/2ldX+/QTA8n1oRi7U4zySUL
iaAycSQl/yFHeHBhjOqFzKhvJU9Ux1A/lDzmFZ/vPGsSCvyv3GD1IzK1wvbUgxKE
3DzA1OuuUCl36HYTEgeFG2DqHPxzjhtqPyGgTG4xmB3dOndMys4VxeWB3Y+3vy3I
B6faH3/UKv1S6Fhj6xzxODjlLLt2zV0obi3F67QBXEvD08FCYtLIww=  =
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
MIIDsDCCAxmgAwIBAgIBADANBgkqhkiG9w0BAQQFADCBnTELMAkGA1UEBhMCVVMx
EDAOBgNVBAgTB0FsYWJhbWExEjAQBgNVBAcTCVNvbWV3aGVyZTEaMBgGA1UEChMR
UGxhaW5lSm9lIERvdCBPcmcxCzAJBgNVBAsTAklUMRwwGgYDVQQDExNnYXJpb24u
cGxhaW5qb2Uub3JnMSEwHwYJKoZIhvcNAQkBFhJqZXJyeUBwbGFpbmpvZS5vcmcw
HhcNMDIxMTE2MjI0MzA5WhcNMDMxMTE2MjI0MzA5WjCBnTELMAkGA1UEBhMCVVMx
EDAOBgNVBAgTB0FsYWJhbWExEjAQBgNVBAcTCVNvbWV3aGVyZTEaMBgGA1UEChMR
UGxhaW5lSm9lIERvdCBPcmcxCzAJBgNVBAsTAklUMRwwGgYDVQQDExNnYXJpb24u
cGxhaW5qb2Uub3JnMSEwHwYJKoZIhvcNAQkBFhJqZXJyeUBwbGFpbmpvZS5vcmcw
gZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBALV0pZLKCwqioakJtgKr0+DScZ9h
C/nLcOxw9t6RUHlWSD9aGC9rMaMGrxG5YqI+dEuhbGWhnVo37IsMlHC+oJsXwY/2
r/RQT5dk1jyC4qt+2r4mGGC/QbCX0GRjT0gn3obB570XZ19qBCfYwIXOtYncIX0P
0fUwFVRG5frBL5QDAgMBAAGjgf0wgfowHQYDVR0OBBYEFPVRTbSjVJ4v4pOb0N0k
oJk8YZIGMIHKBgNVHSMEgcIwgb+AFPVRTbSjVJ4v4pOb0N0koJk8YZIGoYGjpIGg
MIGdMQswCQYDVQQGEwJVUzEQMA4GA1UECBMHQWxhYmFtYTESMBAGA1UEBxMJU29t
ZXdoZXJlMRowGAYDVQQKExFQbGFpbmVKb2UgRG90IE9yZzELMAkGA1UECxMCSVQx
HDAaBgNVBAMTE2dhcmlvbi5wbGFpbmpvZS5vcmcxITAfBgkqhkiG9w0BCQEWEmpl
cnJ5QHBsYWluam9lLm9yZ4IBADAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBBAUA
A4GBAIM+ySiITRXb/d1qcO/XUQSKdU3IXqPgS8jY3U12Bll/kCZFcZxjksg6xBib
91Y/bonSEisJG74zn/0ts3sjsr3QKZp5xFcYCyK3IYjaqnFeAOh+eUp54vLpmQZX
e4QaeTkg/8MnS3vFvWoxfo4Z1Zu/wWhp9WMRRwIVAR99Ppps
-----END CERTIFICATE-----

Notice that the CA.pl script places a private key in the same file as the public certificate. You must remove the password for the private key unless you always want to start the OpenLDAP server manually. It is extremely important to protect this key carefully. Public key cryptography is no good if the private key is readily available to anyone.

Because this private key is password protected, it will require some modification before integrating it into the server's setup. The following command removes the password from the private key and places the modified version of the key in a separate file:

$ openssl rsa -in newreq.pem -out newkey.pem
read RSA key
Enter PEM pass phrase:test
writing RSA key

The newkey.pem file can be renamed to a filename of your choosing. Something like slapd-key.pem would be appropriate. Make sure that the new file is safely secured using the appropriate filesystem permissions (i.e., rw-------).

Finally, using your favorite text editor, remove the original private key from newreq.pem. I'll rename the certificate file to slapd-cert.pem for the remaining examples in this chapter. At this point, we have the following files:

slapd-key.pem

LDAP server's private key

slapd-cert.pem

LDAP server's public certificate

Here are the TLS configuration parameters in the context of slapd.conf:

# /usr/local/etc/openldap/slapd.conf
      
# Global section
      
## Include the minimum schema required.
include     /usr/local/etc/openldap/schema/core.schema
      
## Added logging parameters
loglevel     296
pidfile      /usr/local/var/slapd.pid
argsfile     /usr/local/var/slapd.args
      
## TLS options for slapd
TLSCipherSuite          HIGH
TLSCertificateFile      /etc/local/slapd-cert.pem
TLSCertificateKeyFile   /etc/local/slapd-key.pem
      
#######################################################
## Database sections omitted

More Security-Related Parameters

There are also five other security-related global options to be covered prior to continuing on to the database section. These are:

The security parameter allows us to specify general security strength factors. Table 3-5 lists the options and values for the security parameter. All of these options take an integer value specifying the strength factor; the integer must be one of the values used for the minssf and maxssf parameters described in Table 3-3.

Table 3-5. Possible values for the slapd.conf security parameter

For example, we can require very strong authentication and transport layer security when performing updates by adding the following line to the global section of slapd.conf:

## Require strong authentication and transport layer security for update operations.
## NOTE: This is just an example and will not be added to our final slapd.conf.
security     update_sasl=128,update_tls=128

To take full advantage of the security parameter, you must disable simple binds and use only SASL mechanisms for authentication. See the disallow parameter in this section for details of how this can be done.

The require parameter differs from the security parameter by allowing an administrator to define general conditions that must be met to provide access to the directory. This setting may be done globally or on a per-database basis. The require parameter accepts a comma-separated list of the strings described in Table 3-6.

Table 3-6. Values for the require parameter

The effect of some of the require settings can be obtained by other means as well. For example, if anonymous users should have no access to directory information, OpenLDAP provides access control lists within a database that can restrict access in a much more flexible way.

The allow (and complementary disallow) parameters provide another means of enabling and disabling certain features. Currently, the allow parameter supports only two options:

none

This is the default setting.

tls_2_anon

Allows TLS to force the current session to anonymous status.

The disallow parameter, however, offers many more options. These include:

bind_v2

Disables LDAPv2 bind requests

bind_anon

Disables anonymous binds

bind_anon_cred

Disables anonymous credentials when the DN is empty

bind_anon_dn

Disables anonymous binds when the DN is nonempty

bind_simple

Disables simple binds

bind_krbv4

Disables Kerberos 4 bind requests

tls_authc

Disables StartTLS if the client is authenticated

Finally, the password-hash parameter defines the default password encryption scheme used to store values in the userPassword attribute. This setting can be overridden on an individual attribute basis by prefixing the password with the appropriate directive. The default encryption scheme is {SSHA}. Other possibilities include:

The security parameters and examples presented here are enough for our needs. Refer to the openssl(1) manpage for more information on OpenSSL tools and configuration.

After covering these final parameters, you can complete the global section of your slapd.conf:

# /usr/local/etc/openldap/slapd.conf
      
# Global section
      
## Include the minimum schema required.
include     /usr/local/etc/openldap/schema/core.schema
      
## Added logging parameters
loglevel     296
pidfile      /usr/local/var/slapd.pid
argsfile     /usr/local/var/slapd.args
      
## TLS options for slapd
TLSCipherSuite          HIGH
TLSCertificateFile      /etc/local/slapd-cert.pem
TLSCertificateKeyFile   /etc/local/slapd-key.pem
      
## Misc security settings
password-hash     {SSHA}
      
#######################################################
## Database sections omitted

Serving Up Data

Following the global section of slapd.conf will be one or more database sections, each defining a directory partition. A database section begins with the database directive and continues until the next occurrence of the database directive or the end of the file. This parameter has several possible values:

bdb

This backend has been specifically written to take advantage of the Berkley DB 4 database manager. This backend makes extensive use of indexing and caching to speed up performance; it is the recommended backend used on an OpenLDAP server.

ldbm

An ldbm database is implemented via either the GNU Database Manager or the Sleepycat Berkeley DB software package. This backend is the older implementation of the bdb backend. The details of this backend are described in the slapd-ldbm(5) manpage.

passwd

The passwd backend is a quick and dirty means of providing a directory interface to the system passwd(5) file. It has only one configuration parameter: the file directive, which defines the location of the password file (if different from /etc/passwd) used to respond to directory queries. The details of this backend are described in the slapd-passwd(5) manpage.

shell

The shell backend directive allows the use of alternative (and external) databases. This directive lets you specify external programs that are called for each of the LDAPv3 core operations. The details of this backend are described in the slapd-shell(5) manpage.

The first step in writing a database section is defining the type of backend. The examples in the remainder of this book almost exclusively use the bdb database value.

## Begin a new database section.
database     bdb

The next item is to define the directory partition's naming context. The naming context allows slapd to serve multiple, potentially disconnected partitions from a single server. Each partition has a unique naming context that identifies the root entry in the tree. The following example defines the naming context of the database to correspond with the local domain name, a practice recommended by RFC 2247 ("Using Domains in LDAP/X.500 Distinguished Names"):

## Define the beginning of example database.
database     bdb
      
## Define the root suffix you serve.
suffix          "dc=plainjoe,dc=org"

Each LDAP directory can have a root DN (rootdn), which is similar to the superuser account on Unix systems. When authenticated, this DN is authorized to do whatever the user desires; access control restrictions do not apply. For this reason, some administrators prefer not to configure a root DN at all, or at least remove it once the directory has been sufficiently populated to hand over control to existing user accounts.

The naming of the root DN is arbitrary, although the cn values of "admin" and "Manager" have become common choices. The root DN also requires a corresponding root password (rootpw), which can be stored in clear text or encrypted form using one of the prefixes accepted by the password-hash parameter. OpenLDAP 2 provides the slappasswd(8c) utility for generating {CRYPT} , {MD5}, {SMD5}, {SSHA}, and {SHA} passwords. Do not place the root password in plain text regardless of what the permissions on slapd.conf are. Even if the password is encrypted, it is extremely important not to allow unauthorized users to view slapd.conf.

## Define a root DN for superuser privileges.
rootdn      "cn=Manager,dc=plainjoe,dc=org"
      
## Define the password used with rootdn. This is a salted secure hash of the phrase
## "secret."
rootpw          {SSHA}2aksIaicAvwc+DhCrXUFlhgWsbBJPLxy

You aren't required to define a root password. If no rootpw directive is present, the rootdn is authenticated using the server's default authentication method (e.g., SASL). OpenLDAP 2.1 uses a DN representation of an SASL identify. The general syntax is:

uid=name,[cn=realm],cn=SASL Mechanism,cn=auth

The cn= realm portion on the DN is omitted if the mechanism does not support the concept of realms or if the one specified is the default realm for the server. If your OpenLDAP server existed within the PLAINJOE.ORG realm and you chose to use a Kerberos 5 principal named [email protected] as the rootdn, it would appear as:

rootdn "uid=ldapadmin,cn=gssapi,cn=auth"

The next two parameters should be left to their default values:

lastmod

This parameter determines whether slapd will maintain the operational attributes modifiersName, modifyTimestamp, creatorsName, and createTimestamp for all entries defined in core.schema. The default behavior is to maintain the information for all entries. The option accepts a value of off or on. Disabling this parameter means that client-side caching of information is not possible because no marker exists to test whether an entry has been updated.

readonly

The readonly parameter allows a server to disable all update access, including update access by the rootdn. Directory data is writable by default, assuming that there are no access control lists in place. Under some circumstances, such as backing up the data, you may want to prevent the directory from accepting modifications. Like the lastmod parameter, the readonly options also accept the values off or on.

bdb backend-specific parameters

The database parameters discussed up to this point are applicable to OpenLDAP's various database backends in general. This section examines several parameters that are used only by the bdb database.

The directory and mode parameters define the physical location and filesystem permissions of the created database files. These parameters are necessary because, when using an ldbm backend, slapd manages the data store itself. In the following configuration file, the directory and mode parameters tell slapd and the other LDAP tools how to locate and store the database files for this partition. The files are stored in the directory /var/ldap/plainjoe.org/ and created with read/write permission (0600) for the owner only (the account under which the slapd daemon runs).

## Define the beginning of example database.
database        bdb
      
## Define the root suffix you serve.
suffix          "dc=plainjoe,dc=org"
      
## Define a root DN for superuser privileges.
rootdn          "cn=Manager,dc=plainjoe,dc=org"
      
## Define the password used with rootdn. This is the Base64-encoded MD5 hash of
## "secret."
rootpw          {SSHA}2aksIaicAvwc+DhCrXUFlhgWsbBJPLxy
      
## Directory containing the database files
directory       /var/ldap/plainjoe.org
      
## Files should be created rw for the owner **only**.
mode            0600

Warning

It's a good idea to maintain tight security on the physical database files even if the directory server is a closed box (i.e., no users can log into the server and run a shell). It is easier to manage the server when the only way to access the backend storage is via slapd itself.

The index parameter specifies the attributes on which slapd should maintain indexes. These indexes are used to optimize searches, similar to the indexes used by a relational database management system. slapd supports four types of indexes. However, not all attributes support all four index types. Each index type corresponds to one of the matching rules defined in the directory schema.

approx (approximate)

Indexes the information for an approximate, or phonetic, match of an attribute's value.

eq (equality)

Indexes the information necessary to perform an exact match of an attribute value. The match may be case-sensitive or whitespace-sensitive, depending on the matching rules defined in the attribute's syntax.

pres (presence)

Indexes the information necessary to determine if an attribute has any value at all. If an attribute does not possess a value, then the attribute is not present in the directory entry.

sub (substring)

Indexes the information necessary to perform a simple substring match on attribute values.

There can be multiple index definitions for the same database—and even multiple attributes or index types—on the same line. Each attribute or index type should be separated by a comma; use whitespace to separate the attribute list from the list of index types. Here's how to define an equality and presence index on the cn attribute:

## Maintain presence and equality searches on the cn and uid attributes.
index          cn          pres,eq

Which indexes should be maintained depends on the client applications that the server will support and the types of searches that those applications will perform. The best way to determine which indexes to maintain is to include the search processing debug output (loglevel 32) in the server's log file.

Note

OpenLDAP 2 requires an equality index on the objectClass attribute for performance reasons.

## Must be maintained for performance reasons
index          objectClass          eq

I cannot stress the use of proper indexes enough. Misconfigured indexes are probably the number one reason administrators experience performance problems with OpenLDAP servers. Many of the applications and scenarios presented later in the book focus on functionality and not necessarily performance. This should not be construed as lessening the importance of properly indexing the attributes used freqently in searches. It simply means that I assume you have learned your lesson about indexes here and can fill in the blanks later.

While an indexed database offers many performance benefits over flat text files, these benefits can be increased by caching entries and indexes in memory to prevent disk I/O in response to common searches. The cachesize parameter allows you to tune caching according to the needs of the directory.

The cachesize parameter defines the number of entries that should be cached in memory. The default is to cache 1,000 entries. If your total directory size is less than 1,000 entries, there is no need to modify this setting. If, however, your directory contains 1,000,000 entries, a cache size of 100,000 would not be unusual.

Warning

When setting parameters to integer values in slapd.conf, make sure to remove commas from the number. For example, 100,000 should be entered as 100000.

Here is what the database section looks like so far:

## Define the beginning of example database.
database        bdb
      
## Define the root suffix you serve.
suffix          "dc=plainjoe,dc=org"
      
## Define a root DN for superuser privileges. This is the Base64-encoded MD5 hash of
## "secret."
rootdn          "cn=Manager,dc=plainjoe,dc=org"
      
## Define the password used with rootdn.
rootpw          {SSHA}2aksIaicAvwc+DhCrXUFlhgWsbBJPLxy
      
## Directory containing the database files
directory       /var/ldap/plainjoe.org
      
## Files should be created rw for the owner **only**.
mode            0600
      
## Indexes to maintain
index           objectClass     eq
index           cn              pres,eq
      
## db tuning parameters; cache 2,000 entries in memory
cachesize       2000

Access Control Lists (ACLs)

The Directory ACLs provided by OpenLDAP are simple in their syntax, yet very flexible and powerful in their implementation. The basic idea is to define Who has Access to What? The most frequent forms of "Who" include:

*

Matches any connected user, including anonymous connection

self

The DN of the currently connected user, assuming he has been successfully authenticated by a previous bind request

anonymous

Nonauthenticated user connections

users

Authenticated user connections

Regular expression

Matches a DN or an SASL identity

Remember that the login name used to specify a user for authentication takes the form of a DN (e.g., dn="cn=gerald carter,ou=people,dc=plainjoe,dc=org") or an SASL identify (e.g., dn="uid=jerry,cn=gssapi,cn=auth"). The self value is used as a shortcut for the DN of the authenticated user of the current session. The examples later in this section will help clarify this concept.

The notion of an access level is a new concept. Table 3-7 summarizes the various access privileges. Higher levels possess all of the capabilities of the lower levels. For example, compare access implies auth access, and write access implies read, search, compare, and auth.

Table 3-7. Summary of access levels from most (top) to least (bottom)

The simplest way to control access is to define a default level of authorization. A global slapd.conf parameter defines the default access given to a user in the absence of a more explicit rule. For example, adding the following lines to the global section of slapd.conf gives all users search access unless an explicit ACL says otherwise:

## Give users search access when no other ACL applies.
defaultaccess     search

Finally, the "What" defines the entry and attributes to which the ACL should apply. It is composed of three basic parts, all of which are optional.

• A regular expression defining the DN of the proposed target of the ACL. The actual syntax is dn.targetstyle = regex, in which targetstyle is one of base, subtree, one, or children, and regex is a regular expression representing a DN. The targetstyle, which defaults to subtree, is used to broaden or narrow the scope of the ACL. If, for example, the targetstyle is set to one, the ACL applies only to children immediately below the defined DN. Very rarely does this setting need be changed from its default. The regex follows normal regular expression rules, with the addition that the DN must be in normalized form. The most common error is to add extra whitespace between components of the DN—for example, you can't add a space after the comma in dc=plainjoe,dc=org.
• An LDAP search filter that conforms to RFC 2254. (More on LDAP searches will be covered in the next chapter.) The syntax for specifying a filter is filter= ldapFilter.
• A comma-separated list of attribute names taking the form attrs= attributeList. If this item is not present, the ACL applies to all attributes held by the entry that matches the DN regular expression pattern.

If none of these components are present, a single asterisk (*) is used as a placeholder (for "What") to include everything.

Now that we've looked at the parts of an ACL, let's see how to put an ACL together. It is easiest to understand the syntax of an ACL by examining some practical uses. The following ACL grants read access to everyone:

# Simple ACL granting read access to the world
access to *
     by * read

The space at the beginning of the second line indicates that this is a continuation of the previous line. This control list could have been written on a single line, but the multiline style is more readable for complex ACLs.

This next example restricts access to the userPassword attribute; any user can access the attribute, but can access it only for authentication purposes. Users can't read or write this attribute.

# Restrict userPassword to be used for authentication only.
access to attrs=userPassword
     by * auth

If a user should be allowed to modify her own password in the directory, the ACL would need to be rewritten as follows:

# Restrict userPassword to be used for authentication only, but allow users to modify
# their own passwords.
access to attrs=userPassword
     by self write
     by * auth

Once authenticated, a user can write her own password. Anyone is allowed to use passwords for authentication purposes.

ACLs are evaluated on a "first match wins" basis. An ACL listed first takes precedence over ACLs mentioned later. This means that more restrictive ACLs should be listed prior to more general ones. Consider what behavior would result from the following two ACLs. What sort of access would be granted to the userPassword attribute?

# Simple ACL granting read access to the world
access to *
     by * read
      
# Restrict userPassword to be used for authentication only, but allow users to modify
# their own passwords.
access to attrs=userPassword
     by self write
     by * auth

The previous ACLs grant all users (anonymous and authenticated) read access to userPassword. This clearly isn't a policy you would want. To achieve the desired effect of restricting read privileges to this attribute, the ACLs should be ordered as follows:

# Restrict userPassword to be used for authentication only, but allow users to modify
# their own passwords.
access to attrs=userPassword
     by self write
     by * auth
      
# Simple ACL granting read access to the world
access to *
     by * read

For the next example, assume that the following conditions are met:

• Administrative user accounts are located beneath the DN ou=admins,ou=eng, dc=plainjoe,dc=org.
• Normal user accounts are located beneath ou=users,ou=eng,dc=plainjoe,dc=org.
• Normal users should not be able to view passwords of other users.
• A user should be able to modify his password.
• Administrative users should be able to modify any user's password.

We can model these rules with the following ACL:

# Set control on the userPassword attribute.
access to dn=".*,ou=eng,dc=plainjoe,dc=org"
  attrs=userPassword
  by self write
  by * auth
  by dn=".*,ou=admins,ou=eng,dc=plainjoe,dc=org" write

ACLs can very often be written in more than one equivalent form. The following access rule is functionally identical to the one just presented:

# Set control on the userPassword attribute.
access to dn.children="ou=eng,dc=plainjoe,dc=org"
  attrs=userPassword
  by self write
  by * auth
  by dn.children="ou=admins,ou=eng,dc=plainjoe,dc=org" write

These examples are only a few possibilities of what can be done. We will continue to explore ACLs as a means of securing our server as we add more information into the directory in later chapters.

Chapter 4. OpenLDAP: Building a Company White Pages

The previous chapter discussed how to install OpenLDAP and provided an overview of the slapd configuration file, slapd.conf. However, we have yet to launch the server, let alone add any data to the directory. Using the slapd.conf from Chapter 3 as a starting point, this chapter shows you how to create a company directory for storing employee contact information, including postal addresses, email addresses, and phone numbers.

A Starting Point

Here is the slapd configuration file developed in Chapter 3. We will change some of the entries in this listing as things progress.

# /usr/local/etc/openldap/slapd.conf
      
# Global section
      
## Include the minimum schema required.
include       /usr/local/etc/openldap/schema/core.schema
      
## Added logging parameters
loglevel      296
pidfile       /usr/local/var/slapd.pid
argsfile      /usr/local/var/slapd.args
      
## TLS options for slapd
TLSCipherSuite             HIGH
TLSCertificateFile         /etc/local/slapd-cert.pem
TLSCertificateKeyFile      /etc/local/slapd-key.pem
      
## Misc security settings
password-hash         {SSHA}
      
#######################################################
## Define the beginning of example database.
database     bdb
      
## Define the root suffix you serve.
suffix                "dc=plainjoe,dc=org"
      
## Define a root DN for superuser privileges.
rootdn                "cn=Manager,dc=plainjoe,dc=org"
      
## Define the password used with rootdn. This is the base64-encoded MD5 hash of
## "secret."
rootpw                {SSHA}2aksIaicAvwc+DhCrXUFlhgWsbBJPLxy
      
## Directory containing the database files
directory             /var/ldap/plainjoe.org
      
## Files should be created rw for the owner **only**.
mode                  0600
      
## Indexes to maintain
index                 objectClass          eq
index                 cn                   pres,eq
      
## db tuning parameters; cache 2,000 entries in memory
cachesize             2000
      
# Simple ACL granting read access to the world
access to *
   by * read

Defining the Schema

The first step in implementing a directory is determining what information to store in the directory. The naming context of your server has already been defined as:

dc=plainjoe,dc=org

Store contact information for employees in the people organizational unit:

ou=people,dc=plainjoe,dc=org

There are several ways to identify the data that should be placed in an employee's entry. Information stored in an existing Human Resources database can provide a good starting point. Of course, you may not want to place all of this information in your directory. As a general rule, I prefer not to put information in a directory if that data probably won't be used. If it turns out that the data is actually necessary, you can always add it later. Eliminating unnecessary data at the start means that there's less to worry about when you start thinking about protecting the directory against unauthorized access.

An alternative to starting with an existing database is to determine which employee attributes you wish to make available and define a schema to match that list. The reverse also works: you can select a standard schema and use the attributes already defined. I prefer this approach because it makes it easy to change from one server vendor to another. Widely used, standard schemas are more likely to be supported by a wide range of vendors. Custom, in-house schemas may need to be redesigned to adapt to a new vendor (or even a new version from the same vendor).

For your directory, the inetOrgPerson schema defined in RFC 2798 is more than adequate. From Section 3.5.1 in Chapter 3, we know that this object class and associated attributes are defined in OpenLDAP's inetorgperson.schema file. As shown in Figure 4-1, an inetOrgPerson is a descendant of the organizationalPerson , which was itself derived from the person object class.

Figure 4-1. Hierarchy of the inetOrgPerson object class

The union of these object classes defines the set of required and optional attributes that are available. This means that the only required attributes in an inetOrgPerson object are the cn and sn attributes derived from the person object class.

Tip

From this point on, diagrams of an object class will not include RFC 2252-style schema definitions. If you wish to study the exact syntax of any object class, refer to the schema files included with OpenLDAP or the relevant RFC (or Internet-Draft).

Your directory will use the cn attribute as the RDN for each entry. Remember that the RDN of an entry must be unique among siblings of a common parent. In larger organizations, two people may have the same first and last name. In these cases, using a more specific value for the cn, such as including a middle name (or initial), can alleviate name collisions.

Another way to reduce the number of name collisions is to redesign the directory layout to reduce the total number of user entries sharing a common parent. In other words, group employees in some type of logical container, such as a departmental organizational unit. Figure 4-2 illustrates how this design avoids namespace conflicts. In this directory the "John Arbuckle" in sales is different from the "John Arbuckle" in engineering because the entries possess different parent nodes.

Figure 4-2. Using organizational unit to avoid collisions of common names (cn)

For our example, going with a single container of ou=people is fine; furthermore, our employee base is small enough to use an employee's common name (cn) without fear of conflict. Figure 4-3 shows the directory namespace developed so far.

Figure 4-3. Directory namespace for company address book

Here is an employee entry that contains the attributes needed for our directory. Notice that the two required attributes outlined in Figure 4-1, cn and sn, are present in addition to several optional attributes.

## LDIF entry for employee "Gerald W. Carter"
dn: cn=Gerald W. Carter,ou=people,dc=plainjoe,dc=org
objectClass: inetOrgPerson
cn: Gerald W. Carter
sn: Carter
mail: [email protected]
mail: [email protected]
labeledURI: http://www.plainjoe.org/
roomNumber: 1234 Dudley Hall
departmentNumber: Engineering
telephoneNumber: 222-555-2345
pager: 222-555-6789
mobile: 222-555-1011

Deep or Wide?

Is it better to maintain a shallow (and wide) tree or a deep (and narrow) directory? The best structure for your directory depends on two factors.

First, how likely is it for a change to force an entry (in our case, a person) to be moved from one organizational unit to another? The answer to this question is based on a solid understanding of your organization and its needs. Deeper directory trees imply that an entry must meet more requirements in order to be placed in a certain container. For example, rather than placing all employees under the ou=people, using characteristics such as departments, job description, and geographic location makes for a more defined grouping. However, if these characteristics are likely to change frequently, you will only be creating more work for yourself in the long term. It is also good to note that deep directories require longer DNs to reference entries. This can become an annoyance over time.

Second, does the implementation of your LDAP directory server favor one design over another? For OpenLDAP, this answer depends on your needs. The determining factor will be the number of updates, or writes, that will be made to the directory. To update an entry, the slapd server obtains a lock on the parent entry for the requesting client. Now suppose that you have a very shallow directory tree with 10,000 entries under a single parent. If many updates occur at the same time, the contention for the lock on the parent entry will be very high. The end result will be slower updates because processes will block waiting for the lock.

A deeper tree means that you can often make searches more efficient by giving a more detailed search base. For more information on designing LDAP namespaces, you may wish to read Howes, et al., Understanding and Deploying LDAP Directory Services (MacMillan Technical Press).

Updating slapd.conf

Once the schema has been selected, the next step is to modify slapd.conf to support the selected attribute types and object classes. In order to support the inetOrgPerson object class, you must include inetorgperson.schema , core.schema , and cosine.schema in slapd.conf. The comments that begin inetorgperson.schema outline the dependency on the COSINE schema. Here are the modifications to the global section of slapd.conf:

# /usr/local/etc/openldap/slapd.conf
      
# Global section
      
## Include the minimum schema required.
include         /usr/local/etc/openldap/schema/core.schema
      
## Added to support the inetOrgPerson object.
include         /usr/local/etc/openldap/schema/cosine.schema
include         /usr/local/etc/openldap/schema/inetorgperson.schema
      
## Added logging parameters
 . . .

The database section is currently in working condition, so only a few changes are needed. To better support searches for employees, you should modify the set of indexes to include a more complete list of attributes. In addition to creating an index for the cn attribute, you'll also index the surname (sn) and email address (mail) attributes. In addition to the equality (eq) index, you'll add a substring (sub) index to support searches such as "All employees whose last names begin with C." Finally, you will add an equality index for the departmentNumber attribute so that users can search for employees within a given department. This index would not be necessary if the directory were laid out as shown in Figure 4-2 because the same effect could be achieved by beginning the search at the department ou. Here are the changes to the database section:

## Indexes to maintain
index         objectClass         eq
index         cn,sn,mail          eq,sub
index         departmentNumber    eq
 . . .

At this point, it's a good idea to verify that the location specified by the directory parameter exists and has the proper permissions. In our example, that directory is /var/ldap/plainjoe.org. If this directory does not exist, the following two commands ensure that the filesystem is ready to store data:

root# mkdir -p /var/ldap/plainjoe.org
root# chmod 700 /var/ldap/plainjoe.org

Starting slapd

Once the final tweaks have been added to the configuration file, the next step is to start the slapd daemon by executing the following command as root:

root# /usr/local/libexec/slapd

Use the ps command to verify that slapd is running. On a Linux system, the output should appear similar to:

$ ps -ef | grep slapd
root   8235     1  0 12:37 ?   00:00:00 /usr/local/libexec/slapd
root   8241  8235  0 12:37 ?   00:00:00 /usr/local/libexec/slapd
root   8242  8241  0 12:37 ?   00:00:00 /usr/local/libexec/slapd

On Linux and IRIX, multiple threads of a process will show up as individual entries in the output from ps. On Solaris, slapd will be displayed as a single process.

Stopping the OpenLDAP server requires that the daemon have a chance to flush modified directory data to disk. The best way to do this is to send the parent slapd process an INT signal, as shown here (the pidfile location was defined in the server's configuration file):

root# kill -INT 'cat /var/run/slapd.pid'

Shutting down slapd by more drastic means, such as kill -9 , can result in data corruption and should be avoided at all costs.

In the absence of any command-line options, slapd's behavior is governed by compile-time defaults or options defined in the slapd.conf file. At times, it is necessary to override some of these settings via the command line. Table 4-1 lists the available slapd options.

Table 4-1. Command-line options for the slapd server

Of course, starting slapd from the command line is something you do only while testing. In practice, it would be started by one of the system's boot time initialization scripts—either rc.local for BSD systems, or one of the /etc/rc.d/rc?.d/ (or /etc/init.d/ ) scripts for System V hosts. You should refer to the init(8) manpage for a brief description of run levels and which levels are used (and for what functions) on your system. On most Linux systems, the slapd daemon should be launched at run levels 3 and 5. Run level 5 is basically the same as run level 3 with the addition of X11.

Adding the Initial Directory Entries

A directory without data isn't of much use. There are two ways to add information to your directory; which method to use depends on the directory's state. First, slapadd and the other slap* commands were presented in Chapter 3 as database maintenance tools. They allow an administrator to import entries directly into the database files and export the entire directory as an LDIF file. They work directly with the database, and don't interact with slapd at all. Second, the OpenLDAP distribution includes a number of tools, such as ldapmodify , that can update a live directory using the LDAPv3 network operations. These tools access the directory through the server.

What are the advantages and disadvantages of these approaches? The offline tools can be much faster; furthermore, there are circumstances when you can't start the server without first adding data (for example, when restoring the directory's contents from a backup). The disadvantage of the offline tools, of course, is that they must be run locally on the server.

In contrast to the offline tools, the LDAP client utilities are more flexible and allow a directory administrator greater control by forcing user authentication and by using access control lists on directory entries. A good rule of thumb is that the slap* tools are used for getting your LDAP server online, and the ldap* tools are for day-to-day administration of the directory.

Warning

OpenLDAP 2.1 removed the restriction that slapd must not be running before any of the slap* tools can be used. However, OpenLDAP 2.0 caches data in memory, so using the slap* tools while the directory is running can present an inconsistent view of the directory at best, and corrupt data at worst.

The tools for offline manipulation of directory information are slapadd, slapcat, slapindex, and slappasswd (covered in Chapter 3). The slapadd tool determines which files and indexes to update based on the slapd.conf file. Because it is possible for a given configuration file to define more than one database partition, slapadd provides options for specifying a database partition by either the directory suffix (-b suffix) or the numbered occurrence (-n integer) in slapd.conf. Referring to a particular database using a numbered instance is confusing and error-prone. It is far more intuitive to refer to the same database by using the directory suffix. Note that the -b and -n options are mutually exclusive. A summary of the various slapadd command-line options is provided in Table 4-2.

Table 4-2. Summary of slapadd command-line arguments

The slapcat utility dumps the contents of an entire directory (including persistent operational attributes such as modifyTimeStamp) in LDIF format. The command-line options for slapcat are identical to the options for slapadd (Table 4-2), except that the -l switch specifies an output filename instead of an input filename. In the absence of this switch, slapcat writes all entries to standard output. slapcat can provide a useful means of backing up the directory. Unlike the actual DBM datafiles, which are machine- and version-dependent, LDIF is very portable and allows easier editing in case of corrupted data. I don't mean to discourage you from backing up the DBM files, but you could do worse than backing up the directory in both forms.

The slapindex command can be used to regenerate the indexes for a bdb backend. This might be necessary if a new index was added to slapd.conf after the directory was populated with entries. The slapindex tool shares the same command-line options as slapadd, with the exception of -l. The -l option isn't used for slapindex because neither an input nor an output file is needed.

To start populating your directory, create a file containing the LDIF entries of the top-level nodes. These LDIF entries build the root node and the people organizational unit.

## Build the root node.
dn: dc=plainjoe,dc=org
dc: plainjoe
objectClass: dcObject
objectClass: organizationalUnit
ou: PlainJoe Dot Org
      
## Build the people ou.
dn: ou=people,dc=plainjoe,dc=org
ou: people
objectClass: organizationalUnit

Assuming that these entries are stored in a file named /tmp/top.ldif, you can add them to the directory by executing:

root# slapadd -v -l /tmp/top.ldif
added: "dc=plainjoe,dc=org" (00000001)
added: "ou=people,dc=plainjoe,dc=org" (00000002)

The output indicates that the entries were added successfully.

Verifying the Directory's Contents

Next, you will bring the directory online so that you can use it in conjunction with ldapsearch, ldapmodify, and the other tools for working on a live directory:

root# /usr/local/libexec/slapd

After the directory server has started, you can use ldapsearch to query the server. ldapsearch allows you to dig through your directory, test for the existence of data, and test whether access control has been set up correctly.

OpenLDAP's ldapsearch began life as a simple wrapper for the LDAP search operation. The list of search possibilities is lengthy; I won't cover it until Chapter 5. For now, I will focus on very simple searches that assure you the directory is up and running correctly. In its simplest form, a query requires the following information:

• The LDAP server's hostname or IP address
• The credentials (i.e., user DN and password) to use to bind to the host
• The search base in the form of a DN
• The scope of the directory to search
• A search filter
• A list of attributes to return

We'll start with a "Show me everything" search. Here, you ask the directory to return all entries that have a value for the objectClass attribute (which is all entries).

$ ldapsearch -x -b "dc=plainjoe,dc=org" "(objectclass=*)"
version: 2
    
#
# filter: (objectclass=*)
# requesting: ALL
#
    
# plainjoe,dc=org
dn: dc=plainjoe,dc=org
dc: plainjoe.org
objectClass: dcObject
objectClass: organizationalUnit
ou: PlainJoe Dot Org
    
# people,dc=plainjoe,dc=org
dn: ou=people,dc=plainjoe,dc=org
ou: people
objectClass: organizationalUnit
    
# Search result
search: 2
result: 0 Success
    
# numResponses: 3
# numEntries: 2

The ldapsearch options used here are:

-x

Instructs ldapsearch to perform a simple bind (i.e., do not use SASL for authentication).

-b dc=plainjoe,dc=org

Defines the DN dc=plainjoe,dc=org as the search's base suffix. This DN specifies the point at which the search begins. Therefore, it must be a DN that is held by the LDAP server. All entries located higher in the tree will be ignored.

(objectclass=*)

The search filter. If you are familiar with filename globbing, or just general wildcard patterns, this filter should be familiar. RFC 2254 defines ways to represent an LDAP search filter as a string. The syntax of filters is covered in Chapter 5. For now, it's sufficient to know that this filter matches any value of the objectClass attribute.

The surprising thing about this command is that it doesn't explicitly contain most of the items that I said were necessary for any search. In fact, the only two items that we can clearly see are the search base and the search filter. What's going on? Let's look at the missing items one at a time:

The LDAP server's hostname (or IP address)

ldapsearch queries the local host if the server isn't specified explicitly. The -h hostname option specifies the hostname or IP address. In this case, though, you're running the server locally, so you don't need it.

Credentials used to bind to the directory

The ACL defined in slapd.conf gave read permission to all users. Therefore, you don't need to authenticate to perform this search. When authentication is required, the -D DN and -w password options specify the login DN and password to be used.

The search scope

By default, ldapsearch queries the server for all entries contained in the subtree of the root node defined by the -b option. Other possibilities include searching only the immediate children of the base suffix entry or searching this entry alone. The search scope (-s) option can be used to specify either sub, base, or one.

A list of attributes to return

By default, slapd returns all nonoperational attributes. On a complex directory, you might get an extremely long list of attributes for every entry in the directory. To limit the result to a few specific attributes, list the attributes you want on the command line, separated by commas. Operational attributes such as modifyTimestamp and modifiersName are not returned unless specifically asked for by name or by using the plus character (+) as the attribute list in the search.

The default values for many LDAP client parameters can be controlled via the system-wide ldap.conf configuration file (located in the same directory as slapd.conf) or the user-specific version in $HOME/.ldaprc. For more details, refer to the ldap.conf(5) manpage. Our examples explicitly list all parameters required by the command-line tools unless the compile-time defaults can be used, which was the case in the previous ldapsearch listing.

Table 4-3 and Table 4-4 list all the options and arguments for ldapsearch. Don't worry about understanding them all now.

Table 4-3. Command-line options common to ldapsearch, ldapadd, ldapdelete, ldapmodify, and ldapmodrdn

Table 4-4. Command-line options specific to ldapsearch

Updating What Is Already There

Eventually, the information stored in a directory will need to be updated or deleted. While a directory isn't designed to be updated as frequently as a database, there are very few applications in which the data never changes. This section covers how to update the data in the directory using ldapmodify. The name ldapmodify is a little misleading; this utility can add new entries and delete or update existing entries using some of the advanced features of LDIF for its input language.

The following LDIF listing defines two entries that we will add to our directory:

## filename: /tmp/users.ldif
      
## LDIF entry for "Gerald W. Carter"
dn: cn=Gerald W. Carter,ou=people,dc=plainjoe,dc=org
cn: Gerald W. Carter
sn: Carter
mail: [email protected]
mail: [email protected]
labeledURI: http://www.plainjoe.org/
roomNumber: 1234 Dudley Hall
departmentNumber: Engineering
telephoneNumber: 222-555-2345
pager: 222-555-6789
mobile: 222-555-1011
objectclass: inetOrgPerson
      
## LDIF entry for "Jerry Carter"
dn: cn=Jerry Carter,ou=people,dc=plainjoe,dc=org
cn: Jerry Carter
sn: Carter
mail: [email protected]
telephoneNumber: 555-123-1234
objectclass: inetOrgPerson

The following command shows how to add these entries to the directory while it is running. Because write privileges are required to add new entries, ldapmodify binds to the directory using the credentials from the rootdn and rootpw slapd.conf parameters.

$ ldapmodify -D "cn=Manager,dc=plainjoe,dc=org" -w secret \
> -x -a -f /tmp/users.ldif
adding new entry "cn=Gerald W. Carter,ou=people,dc=plainjoe,dc=org"
      
adding new entry "cn=Jerry Carter,ou=people,dc=plainjoe,dc=org"

The output indicates that both entries were added successfully. The -D, -w, and -x options to ldapmodify should be familiar; they specify the DN to use for the modification, specify the password for the modification, and request simple authentication, respectively. This leaves only two new options to discuss:

-a

Entries are to be added to the directory. The default for ldapmodify is to update existing information.

-f filename

Reads the new entries from the given filename. By default, ldapmodify reads from standard input.

If ldapmodify returns an error message such as the following, try enabling verbose messages via the -v command-line switch:

ldap_add: Invalid syntax
additional info: value contains invalid data

There are two common causes of this error message. You may have forgotten to include all the necessary schema files in slapd.conf, or you may have extra whitespace at the end of line in the LDIF file. The set list command in vi can help you track down extra whitespace.

Refer again to Table 4-3 for a list of the common options for all of these ldap client tools. Table 4-5 lists those options specific to ldapmodify and ldapadd. Note that ldapadd and ldapmodify are the same executable; ldapadd is only a hard link to ldapmodify. The commands differ only in their default behavior, which depends on the name by which the program was invoked.

Table 4-5. Command-line options specific to ldapadd and ldapmodify

Now let's see how a modification works. Suppose you want to add a URL to the entry for cn=Jerry Carter,ou=people,dc=plainjoe,dc=org. To add a URL, use the labeledURI attribute:

labeledURI: http://www.plainjoe.org/~jerry/

In addition, you should delete the [email protected] email address for "Gerald W. Carter" because it has become invalid. You can place both changes in a single LDIF file:

## /tmp/update.ldif
      
## Add a web page location to Jerry Carter.
dn: cn=Jerry Carter,ou=people,dc=plainjoe,dc=org
changetype: modify
add: labeledURI
labeledURI: http://www.plainjoe.org/~jerry/
      
## Remove an email address from Gerald W. Carter.
dn: cn=Gerald W. Carter,ou=people,dc=plainjoe,dc=org
changetype: modify
delete: mail
mail: [email protected]

The changetype keyword in the LDIF file is the key to modifying existing entries. This keyword can accept the following values:

add

Adds the entry to the directory.

delete

Deletes the entry from the directory.

modify

Modifies the attributes of an entry. With this keyword, you can both add and delete attribute values.

modrdn

Changes the RDN of an entry.

moddn

Changes the DN of an entry.

This LDIF file tells ldapmodify what changes to make. We'll invoke ldapmodify with the verbose (-v) option so you can follow the update operations more closely. The -a option isn't needed because you're not adding new entries.

$ ldapmodify -D "cn=Manager,dc=plainjoe,dc=org" -w secret
> -x -v -f /tmp/update.ldif
ldap_initialize( <DEFAULT> )
add labeledURI:
        http://www.plainjoe.org/~jerry/
modifying entry "cn=Jerry Carter,ou=people,dc=plainjoe,dc=org"
modify complete
    
delete mail:
        [email protected]
modifying entry "cn=Gerald W. Carter,ou=people,dc=plainjoe,dc=org"
modify complete

Notice that the LDIF file is parsed sequentially from the top. Therefore, later LDIF entries can modify entries created previously in the file. You can also create an LDIF file with entries having different changetype values. For example, the following LDIF file adds an entry for user Peabody Soup, adds a new telephoneNumber to Jerry Carter's entry, and finally deletes the previously created entry for Peabody Soup.

## /tmp/changetypes.ldif
      
## Add entry for Peabody Soup.
dn: cn=Peabody Soup,ou=people,dc=plainjoe,dc=org
changetype: add
cn: Peabody Soup
sn: Soup
objectclass: inetOrgPerson
      
## Add new telephoneNumber for Jerry Carter.
dn: cn=Jerry Carter,ou=people,dc=plainjoe,dc=org
changetype: modify
delete: telephoneNumber
telephoneNumber: 555-123-1234
-
add: telephoneNumber
telephoneNumber: 234-555-6789
      
## Remove the entry for Peabody Soup.
dn: cn=Peabody Soup,ou=people,dc=plainjoe,dc=org
changetype: delete

A couple of facts about this LDIF file are worth mentioning:

• Entries are separated by a blank line, as noted earlier.
• Multiple changes to a single entry using the modify changetype are separated by a single dash (-) on a line by itself. These should be handled as a single change by the server. Either all the changes for this DN take effect or none are applied.

The modify changetype supports add and delete keywords for adding and deleting attribute values. In order to delete the value of an attribute, the delete: must immediately be followed by an attributetype:value pair. It's necessary to specify the value you're deleting because some attributes can hold multiple values. Specifying which value to remove eliminates any ambiguity about what you want to do. When the last value of an attribute is removed from an entry, that attribute is no longer present in the entry.

Here's how to apply this second set of changes to the directory. Again, we've specified the -v option to see how ldapmodify processes the LDIF file.

$ ldapmodify -D "cn=Manager,dc=plainjoe,dc=org" -w secret -x -v -f
/tmp/changetype.ldif
ldap_initialize( <DEFAULT> )
add cn:
        Peabody Soup
add sn:
        Soup
add objectclass:
        inetOrgPerson
adding new entry "cn=Peabody Soup,ou=people,dc=plainjoe,dc=org"
modify complete
    
delete telephoneNumber:
        555-123-1234
add telephoneNumber:
        234-555-6789
modifying entry "cn=Jerry Carter,ou=people,dc=plainjoe,dc=org"
modify complete
    
deleting entry "cn=Peabody Soup,ou=people,dc=plainjoe,dc=org"
delete complete

Modifying the RDN of an entry takes a little more thought than adding an entry or changing an attribute of an entry. If the entry is not a leaf node, changing its RDN orphans the children in the directory because the DN of their parent has changed. You should make sure that you don't leave orphaned nodes in the directory—you should move the nodes with their parent or give them a new parent. With that in mind, let's think about how to change the RDN of the entry:

dn: cn=Jerry Carter,ou=people,dc=plainjoe,dc=org

from cn: Jerry Carter to cn: Gerry Carter. Here's the LDIF file that makes the changes:

## /tmp/modrdn.ldif
      
## Change the RDN from "Jerry Carter" to "Gerry Carter."
dn: cn=Jerry Carter,ou=people,dc=plainjoe,dc=org
changetype: modrdn
newrdn: cn=Gerry Carter
deleteoldrdn: 1

You can also use the ldapmodrdn command to perform the same task:

$ ldapmodrdn \
> "cn=Jerry Carter,ou=people,dc=plainjoe,dc=org" \
> "cn=Gerry Carter"

Not counting the DN of the entry to be changed and the new RDN value, the ldapmodrdn tool has three command-line options besides those common to the other OpenLDAP client tools (Table 4-3). These additional options are listed in Table 4-6.

Table 4-6. Command-line options specific to ldapmodrdn

If an entire subtree of the directory needs to be moved, a better solution may be to export the subtree to an LDIF file, modify all occurrences of the changed attribute in all the DNs, and finally re-add the subtree to the new location. Once the information has been entered correctly into a location, you can then use a recursive ldapdelete to remove the old subtree.

ldapdelete possesses all of the command-line options common to ldapsearch and ldapmodify. The only new option is -r (recursive), which deletes all entries below the one specified on the command line, in addition to the named entry. Note that this deletion is not atomic; entries are deleted individually. The following command deletes the entire ou=people subtree:

$ ldapdelete -D "cn=Manager,dc=plainjoe,dc=org" -w secret -x \
>  -r -v "ou=people,dc=plainjoe,dc=org"
      
ldap_initialize( <DEFAULT> )
deleting entry "ou=people,dc=plainjoe,dc=org"
deleting children of: ou=people,dc=plainjoe,dc=org
deleting children of: cn=Gerald W. Carter,ou=people,dc=plainjoe,dc=org
    removing cn=Gerald W. Carter,ou=people,dc=plainjoe,dc=org
    cn=Gerald W. Carter,ou=people,dc=plainjoe,dc=org removed
deleting children of: cn=Gerry Carter,ou=people,dc=plainjoe,dc=org
   removing cn=Gerry Carter,ou=people,dc=plainjoe,dc=org
   cn=Gerry Carter,ou=people,dc=plainjoe,dc=org removed
Delete Result: Success (0)

Now that you have a working directory, a good exercise would be to experiment with various ACLs to restrict access to certain attributes. This exercise will also help you become more comfortable with the tools presented in this chapter. Use the slapcat tool to dump the directory to an LDIF file and start over from scratch until you are comfortable with adding, deleting, and modifying entries. The next chapter explores creating a distributed directory, replicating information to multiple servers, more searching techniques, and some advanced ACL configurations.

Graphical Editors

Working with command-line tools and LDIF files is constructive, but certainly not convenient. There are a number of graphical editors and browsers for LDAP that make it easier to see what you're doing. I won't discuss any of these in detail, but I'll give you some pointers to some tools that are worth looking at:

GQ (http://biot.com/gq/)

GQ is a GTK+-based LDAPv3 client capable of browsing the subSchema entry on LDAPv3 servers. It is distributed under the GNU GPL and includes features such as:

• Support for browsing or searching LDAP servers
• Support for editing and deleting directory entries
• Support for creating template entries based on existing ones
• Support for exporting subtrees or an entire directory to an LDIF file
• Support for multiple server profiles
• SASL authentication

Java LDAP Browser/Editor (http://www.iit.edu/~gawojar/ldap/)

This is an editor written in Java using the JNDI class libraries. It supports:

• LDAPv2 and v3 servers, including SSL connections
• Editing attribute values
• Searching for specific entries
• Exporting and importing data using LDIF files
• Creating template entries
• Utilizing multiple server profiles

Softerra LDAP Browser (http://www.ldapbrowser.com/)

The Softerra LDAP Browser is a freely available, Win32-based browser and editor for Windows 98/NT/2000 clients. The browser has the following qualities:

• Support for a familiar Windows Explorer-like interface
• Support for LDAPv2 and v3
• Support for SSL connections for v3 sessions
• Support for multiple server profiles, similar to the GQ editor
• Support for exporting entries and subtrees to an LDIF file

Chapter 5. Replication, Referrals, Searching, and SASL Explained

The previous chapters have prepared the foundation for understanding and building an LDAP-based directory server. This chapter presents some of the more advanced features provided by LDAP and shows how to use these features in your directory service. As such, this chapter ties up a lot of loose ends that have been left hanging by the previous discussions.

More Than One Copy Is "a Good Thing"

We begin by exploring directory replication. This feature hasn't been standardized yet; our example focuses on the OpenLDAP project. The concepts and principles that I will present are applicable to all LDAP directories, but the examples themselves are specific to OpenLDAP.

Because LDAP replication is vendor-specific at the moment, it is not possible to replicate data from one vendor's server to another vendor's server. It is possible to achieve cross-vendor replication by using tricks such as parsing a change log, but these tricks are themselves vendor-dependent.

Tip

The LDAP Duplication/Replication/Update Protocols (LDUP) Working Group of the IETF attempted to define a standardized replication protocol that would allow for interoperability between all LDAPv3-compliant servers. However, there appears to be more demand for an LDAP client update protocol (LCUP) that would allow clients to synchronize a local cache of a directory as well as be notified of updates. Details of the group's progress can be found at http://www.ietf.org/html.charters/ldup-charter.html.

A frequently asked question is: "When should I install a replica for all or part of my directory?" The answer depends heavily on your particular environment. Here are a few symptoms that indicate the need for directory replicas:

• If one application makes heavy use of the directory and slows down the server's response to other client applications, you may want to consider installing a replica and dedicating the second server solely to the application that is causing the congestion.
• If the directory server does not have enough CPU power to handle the number of requests it is receiving, installing a replica can improve response time. You may also wish to install several read-only replicas and use some means of load balancing, such as round-robin DNS or a virtual server software package. Before taking this route, make sure that the limiting factor is CPU and not other finite resources such as memory or disk I/O.
• If a group of clients is located on the other side of a slow network link, installing a local replica (i.e., a replica that is close to the clients making the request) will decrease traffic over the link and improve response time for the remote clients.
• If the directory server cannot be taken offline for backups, consider implementing a read-only replica to provide service while the master server is taken down for backups or normal maintenance.
• If your directory is a critical part of the services provided by your network, using replicas can help provide failover and redundancy.

Once the questions of "When?" and "Why?" have been answered, the next question is "How?" The OpenLDAP project uses the original design for replication that was implemented by the University of Michigan's LDAP server. This design uses a secondary daemon (slurpd) to process a change log written by the standalone LDAP server (slapd). slurpd then forwards the changes to the replica's local slapd instance using normal LDAP modify commands. Figure 5-1 displays the relationship between slapd and slurpd on the master directory server and the replica.

Figure 5-1. Dependencies between slapd, the change log, and the slurpd replication helper

Building slurpd

When you built the OpenLDAP package in Chapter 3, you didn't build the slurpd binary. To build slurpd, you must pass the command-line option —enable-slurpd to the configure script. Note that thread support is required for slurpd; there is no nonthreaded version.

After running ./configure with the —enable-slurpd option, executing make creates the server in the servers/slurpd/ subdirectory of the OpenLDAP source code tree. This binary can then be copied to the same location as slapd. You can copy slurpd to the appropriate location by hand or by running make install. All of the examples in this chapter assume that slurpd has been installed in the default location of /usr/local/libexec/.

Replication in a Nutshell

Before implementing replication in a directory, you must have a working LDAP master server. The directory server built in previous chapters will be used as a starting point. Once the master slapd server has been created, implementing a replica server can be accomplished by following these steps:

1. Stop the master server's slapd daemon.
2. Reconfigure the master server's slapd.conf to enable replication to the new slave server.
3. Copy the database from the master server to the replica.
4. Configure the replica server's slapd.conf.
5. Start the replica server's slapd process
6. Start the master server's slapd process.
7. Start the master server's slurpd process.

This quick list glosses over a few details, such as how to configure a server to send updates and how to configure a server to accept updates from a master server. Let's start with step 2 (if step 1 is not obvious, refer to Chapter 4 for a refresher on starting and stopping slapd).

Configuring the Master Server

To configure your master server to log changes that can be processed by the slurpd helper daemon, you need to add two directives to the database section of slapd.conf. It is possible to give slurpd its own configuration file using the -f command-line option, but because of the producer/consumer relationship between slapd and slurpd, the most common setup is to use a single configuration file for both daemons. Here's the database configuration developed in the previous chapter:

## -- master slapd --
#######################################################
## Define the beginning of example database.
database        bdb
      
## Define the root suffix you serve.
suffix          "dc=plainjoe,dc=org"
      
## Define a root DN for superuser privileges.
rootdn          "cn=Manager,dc=plainjoe,dc=org"
      
## Define the password used with rootdn. This is the Base64-encoded MD5 hash of
## "secret."
rootpw          {SSHA}2aksIaicAvwc+DhCrXUFlhgWsbBJPLxy
      
## Directory containing the database files
directory       /var/ldap/plainjoe.org
      
## Files should be created rw for the owner **only**.
mode            0600
      
## Indexes to maintain
index           objectClass     eq
index           cn              pres,eq
      
## db tuning parameters; cache 2,000 entries in memory
cachesize       2000
      
# Simple ACL granting read access to the world
access to *
     by * read