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(
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
Option
Description
-c
Instructs ldapmodrdn to continue if errors occur. By default, it terminates if there is an error.
-r
Removes the old RDN value. The default behavior is to add another RDN value and leave the old value intact. The default behavior makes it easier to modify a directory without leaving orphaned entries.
-s new_superior_node
Defines the new superior, or parent, entry under which the renamed entry should be located.
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(
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:
Stop the master server's slapd daemon.
Reconfigure the master server's slapd.conf to enable replication to the new slave server.
Copy the database from the master server to the replica.
Configure the replica server's slapd.conf.
Start the replica server's slapd process
Start the master server's slapd process.
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
First, you need to add the name of the log file in which slapd will record all LDAP modifications. This is specified using the replogfile parameter.
## -- master slapd --
# Specify the location of the file to append changes to.
replogfile /var/ldap/slapd.replog
* * *
Warning
The slurpd daemon will use only the first instance of the replogfile parameter in a configuration file. On a server that is configured to hold multiple databases, all of these partitions must use a single replogfile value. The best way to do this is to define the replogfile parameter in the configuration file's global section. In this way, the value will be used for all databases defined later in slapd.conf. The alternative is to start a separate slurpd instance, each with its own configuration file, for each database section.
* * *
The second parameter you need to add informs slurpd where to send the changes. You add this parameter, replica , just below the replogfile directive.
## -- master slapd --
# Set the hostname and bind credentials used to propagate the changes in the
# replogfile.
replica host=replica1.plainjoe.org:389
suffix="dc=plainjoe,dc=org"
binddn="cn=replica,dc=plainjoe,dc=org"
credentials=MyPass
bindmethod=simple
tls=yes
replica specifies the host and port to which the data should be sent, the portion of the partition to be replicated, the DN to use when binding to the replicated server, any credentials that are acquired, and information about the binding method and protocols. Note that the binddn used in the replica directive must possess write access to the slave server. The most common binddn to use is the the rootdn specified in the replica's slapd.conf. However, any DN that has the appropriate level of access (possibly granted by ACLs on the directory) will work. The credentials parameter specifies the password used for simple binds and SASL binds to the slave server. The bindmethod option for the replica directive accepts one of the following two values: simple or sasl. Examples using SASL accounts with OpenLDAP will be presented later in this chapter.
In our example, the slave server replica1.plainjoe.org must be listening on the default LDAP port of 389. TLS is enabled (tls=yes) to protect the privacy of information as it is replicated. Because the LDAP connection will be made on port 389, it is essential that the slave server support the StartTLS extended command to ensure secure replication. Regardless of how careful you are about securing the data in your directory, if you
are replicating the directory to a slave server over an insecure link and do not use some type of transport layer security such as TLS or IPSec, all of your efforts will be in vain.
Configuring the Replica Server
The first step in creating a replica is to initialize its database with a current copy of the directory from the master server. There are two ways to accomplish this:
Copy the master's database files to the replica.
Export the master's database to an LDIF file and reimport the entries into the replica.
There are a few restrictions to keep in mind when copying the actual database files from the master to the slave server:
Both hosts must have the same (or compatible) versions of the DBM libraries.
In most cases, both hosts must use the same byte ordering (little-endian versus big-endian).
Some methods of copying DBM sparse files, such as using cp, will fill in the holes, resulting in much larger files on the replica host.
For these reasons, a more general way to transfer the master's database is to export the database to an LDIF file using slapcat. The file can then be imported into the replica's directory using the slapadd command. Using the slapd.conf file from your directory, the following commands initialize the replica's directory:
LDAP System Administration Page 11
