Chapter 11. Managing Replication

Replication is the mechanism by which directory data is automatically copied from one Red Hat Directory Server instance to another; it is an important mechanism for extending the directory service beyond a single server configuration. This chapter describes the tasks to be performed on the master and consumer servers to set up single-master replication, multi-master replication, and cascading replication.

11.1. Replication Overview

Replication is the mechanism by which directory data is automatically copied from one Directory Server to another. Updates of any kind — entry additions, modifications, or even deletions — are automatically mirrored to other Directory Servers using replication.

11.1.1. What Directory Units Are Replicated

The smallest unit of of the directory which can be replicated is a database. This means that one can replicate an entire database but not a subtree within a database. Therefore, when creating the directory tree, consider any replication plans as part of determining how to distribute information.
Replication also requires that one database correspond to one suffix. This means that a suffix (or namespace) that is distributed over two or more databases using custom distribution logic cannot be replicated. For more information on this topic, see Section 2.2, “Creating and Maintaining Databases”.

11.1.2. Read-Write and Read-Only Replicas

A database that participates in replication is called a replica. There are two kinds of replicas: read-write or read-only. A read-write replica contains master copies of directory information and can be updated. A read-only replica services read, search, and compare requests, but refers all update operations to read-write replicas. A server can hold any number of read-only or read-write replicas.

11.1.3. Suppliers and Consumers

A server that holds a replica that is copied to a replica on a different server is called a supplier for that replica. A server that holds a replica that is copied from a different server is called a consumer for that replica. Generally, the replica on the supplier server is a read-write replica, and the one on the consumer server is a read-only replica, with two exceptions:
Replication is always initiated by the supplier server, never by the consumer (supplier-initiated replication). Supplier-initiated replication allows a supplier server to be configured to push data to multiple consumer servers.

11.1.4. Changelog

Every supplier server maintains a changelog, a record of all changes that a supplier or hub needs to send to its consumers. A changelog is a special kind of database that describes the modifications that have occurred on a replica. The supplier server then replays these modifications to the replicas stored on consumer servers or to other suppliers, in the case of multi-master replication.
When an entry is modified, a change record describing the LDAP operation that was performed is recorded in the changelog.
The changelog uses the same database environment as the main database. Implementing the changelog as part of the main database ensures the database and changelog are always synchronized, reduces the required database cache size (10MB by default), and simplifies backup and restore operations.

Important

When the database of a master server is backed up, then it should be backed up using the db2bak.pl Perl script or using the Directory Server Console if the server is kept running. The changelog only writes its RUV entries to the database when the server is shut down; while the server is running, the changelog keeps its changes in memory. For the Perl script and the Console, these changelog RUVs are written to the database before the backup process runs. However, that step is not performed by the command-line script.
The db2bak should not be run on a running master server. Either use the Perl script or stop the server before performing the backup.
In Directory Server, the changelog is only intended for internal use by the server. For other applications to read the changelog, use the Retro Changelog Plug-in, as described in Section 11.21, “Using the Retro Changelog Plug-in”.

11.1.5. Replication Identity

When replication occurs between two servers, the replication process uses a special entry, called the replication manager entry, to identify replication protocol exchanges and to control access to the directory data. The replication manager entry, or any entry used during replication, must meet the following criteria:
  • It is created on the consumer server (or hub) and not on the supplier server.
  • Create this entry on every server that receives updates from another server, meaning on every hub or dedicated consumer.
  • When a replica is configured as a consumer or hub (a replica which receives updates from another server), this entry must be specified as the one authorized to perform replication updates.
  • The replication agreement is created on the supplier server, the DN of this entry must be specified in the replication agreement.
  • The supplier bind DN entry must not be part of the replicated database for security reasons.
  • This entry, with its special user profile, bypasses all access control rules defined on the consumer server for the database involved in that replication agreement.

Note

In the Directory Server Console, this replication manager entry is referred to as the supplier bind DN, which may be misleading because the entry does not actually exist on the supplier server. It is called the supplier bind DN because it is the entry which the supplier uses to bind to the consumer. This entry actually exists, then, on the consumer.
For more information on creating the replication manager entry, see Section 11.3, “Creating the Supplier Bind DN Entry”.

11.1.6. Replication Agreement

Directory Servers use replication agreements to define their replication configuration. A replication agreement describes replication between one supplier and one consumer only. The agreement is configured on the supplier server and must specify all required replication information:
  • The database to be replicated.
  • The consumer server to which the data is pushed.
  • The days and times during which replication can occur.
  • The DN and credentials that the supplier server must use to bind (the replication manager entry or supplier bind DN).
  • How the connection is secured (SSL, client authentication).
  • Any attributes that will not be replicated (fractional replication).

11.1.7. Replicating a Subset of Attributes with Fractional Replication

Fractional replication sets a specific subset of attributes that will not be transmitted from a supplier to the consumer (or another supplier). Administrators can therefore replicate a database without replicating all the information that it contains or all of the information in every entry.
Fractional replication is enabled and configured per replication agreement, not per entry. Excluding attributes from replication is applied equally to all entries within the replication agreement's scope.
As far as the consumer server is concerned, the excluded attributes always have no value. Therefore, a client performing a search against the consumer server will never see the excluded attributes. Similarly, should it perform a search that specifies those attributes in its filter, no entries will match.
It is possible to set different attributes to be replicated for an incremental update and a total update. The incremental update list (nsDS5ReplicatedAttributeList) must always be set to enable fractional replication; if that is the only attribute set, then it applies to both incremental and total updates. The optional nsDS5ReplicatedAttributeListTotal attribute sets an additional fractional replication list for total updates. This is described in Section 11.9.1, “Setting Different Fractional Replication Attributes for Total and Incremental Updates”.

Note

An update to an excluded attribute still triggers a modify event and generates an empty replication update. The nsds5ReplicaStripAttrs attribute adds a list of attributes which cannot be sent in an empty replication event and are stripped from the update sequence. This logically includes operational attribtes like modifiersName.
If a replication event is not empty, the stripped attributes are replicated. These attributes are removed from updates only if the event would otherwise be emtpy.

11.1.7.1. The Replication Keep-alive Entry

When you update an attribute on a master, the change sequence number (CSN) is increased on the master. In a replication topology, this server now connects to the first consumer and compares the local CSN with the CSN on the consumer. If it is lower, the update is retrieved from the local changelog and replicated to the consumer. In a replication topology with fractional replication enabled, this can cause problems: For example, if only attributes are updated on the master that are excluded from replication, no update to replicate is found, and therefore the CSN is not updated on the consumer. In certain scenarios, such as when only attributes are updated on a master that are excluded from replication, unnecessary searching for updates on the supplier can cause other servers to receive the data later than needed . To work around this problem, Directory Server uses keep-alive entries.
If all updated attributes on the master are excluded from replication and the number of skipped updates exceeds 100, the keepalivetimestamp attribute is updated on the supplier and replicated to the consumer. Because the keepalivetimestamp attribute is not excluded from replication, the update of the keep-alive entry is replicated, the CSN on the consumer is updated, and then equal to the one on the supplier. The next time the supplier connects to the consumer, only updates that are newer than the CSN on the consumer are searched. This reduces the amount of time spent by a supplier to search for new updates to send.
The replication keep-alive entry is created on demand on a master and contains the replica ID of the master in the distinguished name (DN). Each keep-alive entry is specific to a given master. For example:
dn: cn=repl keep alive 14,dc=example,dc=com
objectclass: top
objectclass: ldapsubentry
objectclass: extensibleObject
cn: repl keep alive 14
keepalivetimestamp: 20170227190346Z
The keep-alive entry is updated in the following situations (if it does not exist before the update, it is created first):
  • When a fractional replication agreement skips more than 100 updates and does not send any updates before ending the replication session.
  • When a master initializes a consumer, initially it creates its own keep-alive entry. A consumer that is also a master does not create its own keep-alive entry unless it also initializes another consumer.

11.1.8. Replication with 4.x Versions of Directory Server

The replication mechanism in Directory Server 9.0 is different from the mechanism used in 4.x of Directory Server. Compatibility with Netscape 4.x and iPlanet versions of Directory Server is provided through two Directory Server plug-ins:
  • Legacy Replication Plug-in. The Legacy Replication Plug-in makes a Directory Server 9.0 instance behave as a 4.x Directory Server in a consumer role. For information on how to implement legacy replication using this plug-in, see Section 11.20, “Replication with Earlier Releases”.
  • Retro Changelog Plug-in. The Retro Changelog Plug-in can be used for a Directory Server supplier to maintain a 4.x-style changelog. This is sometimes necessary for legacy applications that have a dependency on the Directory Server 4.x changelog format because they read information from the changelog. For more information on the Retro Changelog Plug-in, see Section 11.21, “Using the Retro Changelog Plug-in”.

Note

Replication with 8.x versions of Red Hat Directory Server, including multi-master replication and using 8.x replicas with 9.0 masters, is fully supported. The replication mechanisms used for Directory Server 7.x and 8.x is similar to the mechanism used in Directory Server 9.0. No additional plug-ins or configuration are required for replication to work with versions 6.x, 7.x, 8.x, or 9.x of Directory Server.
Any incompatibilities are related to enhanced features, additional schema, and other features that are available in Directory Server 9.0 which may not be available in 7.x or 8.x servers.