nsDS5Replica

Directory Server replication configuration

Description

Note:

In most cases you do not need to know how to manage the object classes and attributes mentioned here. Instead you handle replication configuration through Directory Service Control Center or the dsconf(1M) command. The information here is included primarily for those of you who are familiar with command-line configuration for replication in previous Directory Server versions.

Replication works in Directory Server using extended operations. Changes to a suffix on a supplier server are replayed on the consumer server. Each server stores configuration information defining its role in replication, and defining the user account that has access to perform replication operations. The supplier server also stores configuration information about the replication agreement it has with the consumer.

Replication configuration is reflected in object classes and attributes under cn=config of the Directory Server instance.

Replica Configuration

The configuration entry that indicates a suffix is replicated has a DN of the following form.

cn=replica,cn=suffix name,cn=mapping tree,cn=config

For example, the following configuration entry DN corresponds to the suffix dc=example,dc=com.

cn=replica,cn=dc\=example\,dc\=com,cn=mapping tree,cn=config

Such entries have the object class nsDS5Replica.

Replication Agreement Configuration

The configuration entries that describe replication agreements with other servers have DNs of the following form.

cn=agreement name,cn=replica,cn=suffix name,cn=mapping tree,
 cn=config

For example, the following configuration entry DN corresponds to the suffix dc=example,dc=com.

cn=ds.example.com:389,cn=replica,cn=dc\=example\,dc\=com,
 cn=mapping tree,cn=config

Replication agreement entries have the object class nsDS5ReplicationAgreement.

Replication Priority Configuration

The configuration entries that describe replication priority rules have DNs of the form:

cn=rule name,cn=replica,cn=suffix name,cn=mapping tree,
 cn=config

For example, the following configuration entry DN corresponds to the suffix dc=example,dc=com.

cn=pwdReplPrio,cn=replica,cn=dc\=example\,dc\=com,cn=mapping tree,
 cn=config

Replication priority rule entries have the object class ReplPriorityRule.

Replication Manager Configuration

The configuration entry for the account used to bind and perform replication has, by default, the DN:

cn=replication manager,cn=replication,cn=config

The account entry is a standard person(5DSOC) object class. It defines the DN and userPassword for replication. The password policy for the account used to bind and perform replication has, by default, the DN:

cn=Password Policy,cn=replication manager,cn=replication,
 cn=config

The password policy entry is governed by the schema for pwpolicy(5DSSD). As both person and pwpolicy related object classes and attribute types are described elsewhere, they are not further described here.

Extended Description

This section examines replication configuration on a master supplier server, and on a dedicated consumer server. The sample configurations shown here were created using the dsconf to configure replication.

Supplier Side Configuration

On the supplier side, the key configuration entries are the replica configuration and the replication agreement.

Supplier Replica Configuration

For a master supplier, an nsDS5Replica configuration entry looks something like the following:

dn: cn=replica,cn=\dc=example\,dc\=com,cn=mapping tree,cn=config
nsDS5ReplicaRoot: dc=example,dc=com
nsDS5ReplicaBindDN: cn=replication manager,cn=replication,cn=config
objectClass: top
objectClass: nsDS5Replica
nsDS5ReplicaId: 1
nsDS5Flags: 1
nsDS5ReplicaType: 3
cn: replica
creatorsName: cn=directory manager
modifiersName: cn=directory manager
nsState:: AAEAAAAAAAAAAAAAQ4rs0AAAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAA==
nsDS5ReplicaName: d2e14d02-600311da-80ace5db-c83e55ac
numSubordinates: 1

In this example, the key attributes are the following:

nsDS5ReplicaRoot

Holds the DN of the root of the replicated suffix. Once set, it must not be modified.

nsDS5ReplicaBindDN

Holds the DN of the account used to bind for replication. If replication is performed over SSL, this attribute can hold the certificate identity associated with the DN.

nsDS5ReplicaId

Specifies the unique ID of this master supplier server, a value from 1-65534, inclusive.

A hub uses the same replica ID as a consumer, 65535.

nsDS5Flags

Governs change logging and automatic referrals. It takes one of the following values:

0: No changes are logged. Automatic referrals are not overwritten.
1: Changes are logged. Automatic referrals are not overwritten.
4: No changes are logged. Automatic referrals are overwritten.
5: Changes are logged. Automatic referrals are overwritten.

nsDS5ReplicaType

Defines the role this replica plays in replicating with other servers. It takes one of the following values:

0: Reserved for internal use
1: Dedicated supplier
2: Dedicated consumer (read-only)
3: Supplier/consumer (read-write)

cn

This attribute names the replica. Once set, it must not be modified.

nsState

Stores the state of the clock for handling synchronization. Reserved for internal use.

nsDS5ReplicaName

Read-only unique identifier for the replica.

The replica configuration entry can also hold the following attributes not shown here:

ds5BeginReplicaAcceptUpdates(5DSCONF)
ds5ReplicaConsumerTimeout(5DSCONF)
ds5LastInitTimeStamp(5DSCONF)
ds5ReferralDelayAfterInit(5DSCONF)
dsChangelogMaxAge(5DSCONF)
dsChangelogMaxentries(5DSCONF)
dsFilterSPConfigchecksum(5DSCONF)
nsDS5ReplicaAutoReferral(5DSCONF)
nsDS5ReplicaChangeCount(5DSCONF)
nsDS5ReplicaPurgeDelay(5DSCONF)
nsDS5ReplicaReferral(5DSCONF)
nsDS5ReplicaTombstonePurgeInterval(5DSCONF)
nsDS5Task(5DSCONF)

Supplier Replication Agreement

For a master supplier, an nsDS5ReplicationAgreement configuration entry looks something like the following:

dn: cn=ds.example.com:389,cn=replica,cn=dc\=example\,dc\=com,
 cn=mapping tree,cn=config
nsDS5ReplicaHost: ds.example.com
nsDS5ReplicaUpdateSchedule: *
nsDS5ReplicaTransportInfo: LDAP
objectClass: top
objectClass: nsDS5ReplicationAgreement
nsDS5ReplicaPort: 389
nsDS5ReplicaBindMethod: SIMPLE
cn: ds.example.com:389
nsDS5ReplicaRoot: dc=example,dc=com
nsDS5ReplicaBindDN: cn=replication manager,cn=replication,
 cn=config
nsDS5ReplicaCredentials:: e0RFU31JakduS3VZSWhEcThEcExDQlU2
 VlN2QTdjcUw4emhDdXl3Sldmc3NTZ2t3eS9mWmR4VmpUZlVYRE1NLzR2T
 UVBDQpyZVdYU3A3U1ZwYz0=

In this example, the key attributes are the following:

nsDS5ReplicaHost: Holds the host name where the consumer runs.
nsDS5ReplicaUpdateSchedule: Specifies when replication happens. If you must restrict the time when replication can happen, set this attribute. This attribute can take multiple values of the form hhmm-hhmm 0123456, where the first element specifies the time span, and the second specifies which days, starting with Sunday (0) to Saturday (6).
nsDS5ReplicaTransportInfo: Specifies the transport used for replication, LDAP or SSL.
nsDS5ReplicaPort: Holds port number on which the consumer listens.
cn: This attribute names the replication agreement. Once set, it must not be modified.
nsDS5ReplicaBindMethod: Specifies bind protocol, SIMPLE, SSLCLIENTAUTH.
nsDS5ReplicaRoot: Holds the DN of the root of the replicated suffix. Once set, it must not be modified.
nsDS5ReplicaBindDN: Holds the DN of the account on the consumer used for replication.
nsDS5ReplicaCredentials: Holds the bind credentials of the account on the consumer used for replication.

The replication agreement entry can also hold the following attributes not shown here:

description_5dsat(5DSAT)
ds5AgreementEnable(5DSCONF)
ds5ReplicaAutomaticInit(5DSCONF)
ds5ReplicaTransportCompressionLevel(5DSCONF)
ds5ReplicaTransportConcurrencyLevel(5DSCONF)
ds5ReplicaTransportGroupSize(5DSCONF)
ds5ReplicaTransportGrpPktSize(5DSCONF)
ds5ReplicaTransportWindowSize(5DSCONF)
ds6ruv(5DSCONF)
dsReplFractionalExclude(5DSCONF)
dsReplFractionalInclude(5DSCONF)
nsDS5ReplicaUpdateSchedule(5DSCONF)
nsds50ruv(5DSCONF)
nsds5BeginReplicaRefresh(5DSCONF)
nsds5ReplicaTimeout(5DSCONF)
nsds5replicaChangesSentSinceStartup(5DSCONF)
nsds5replicaLastInitEnd(5DSCONF)
nsds5replicaLastInitStart(5DSCONF)
nsds5replicaLastInitStatus(5DSCONF)
nsds5replicaLastUpdateEnd(5DSCONF)
nsds5replicaLastUpdateStart(5DSCONF)
nsds5replicaLastUpdateStatus(5DSCONF)
nsds5replicaUpdateInProgress(5DSCONF)

Supplier Priority Rule

For a master supplier, a ReplPriorityRule configuration entry looks something like the following:

dn: cn=pwdReplPrio,cn=replica,cn=dc\=example\,dc\=com,cn=mapping tree,cn=config
objectClass: top
objectClass: ReplPriorityRule
replPriorityType: mod
replPriorityAttribute: userPassword
nsDS5ReplicaRoot: dc=example,dc=com
cn: pwdReplPrio

In this example, the key attributes are the following:

replPriorityType: Specifies the type of operation which are replicated with high priority.
replPriorityAttribute: Specifies the attribute whose changes are replicated with high priority.
nsDS5ReplicaRoot: Holds the DN of the root of the replicated suffix to which this priority rule applies.
cn: This attribute names the priority rule.

The replication priority rule entry can also hold the following attributes not shown here:

replPriorityBaseDN(5DSCONF)
replPriorityBindDN(5DSCONF)

Consumer Side Configuration

On the consumer side, the key configuration entry is the replica configuration. On a dedicated consumer, it is also useful to see how the mapping tree entry for the suffix is configured to refer updates to the supplier.

Consumer Replica Configuration

For a dedicated consumer, an nsDS5Replica configuration entry looks something like the following:

dn: cn=replica,cn=dc\=example\,dc\=com,cn=mapping tree,cn=config
nsDS5ReplicaRoot: dc=example,dc=com
nsDS5ReplicaBindDN: cn=replication manager,cn=replication,cn=config
objectClass: top
objectClass: nsDS5Replica
nsDS5Flags: 0
nsDS5ReplicaType: 2
cn: replica
nsDS5ReplicaId: 65535
nsState:: //8AAAAAAAAAAAAAQ4rtPAAAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAA==
nsDS5ReplicaName: 07ed9f82-600411da-8096d729-0ba76005
dsFilterSPConfigchecksum: 0
ds5LastInitTimeStamp: 0

Key attributes in this example are explained in Supplier Replica Configuration.

A hub uses the same replica ID as a consumer, 65535.

Referrals On Consumer

For a dedicated consumer suffix, the mapping tree configuration entry refers client applications to the supplier for write operations:

dn: cn=dc\=example\,dc\=com,cn=mapping tree,cn=config
objectClass: top
objectClass: extensibleObject
objectClass: nsMappingTree
nsslapd-backend: example
cn: dc=example,dc=com
numSubordinates: 1
nsslapd-referral: ldap://master.example.com:389/dc%3Dexample,dc%3Dcom
nsslapd-state: referral on update

Notice that the nsslapd-referral attribute refers clients to the master on host master.example.com and port 389 when they request update operations that would write to the directory. These attributes are set by the server when replication is initialized. The dedicated consumer then accepts write operations only from the supplier replica.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWdsee7
Stability Level	Obsolete: Scheduled for removal after this release