Replica server

Initialization, or population, of a replica directory requires several steps.

With basic replication, changes to the LDAP server schema entry on the replicating server are not replicated. A separate update of the LDAP server schema on the replica is required each time the schema is updated on the replicating server.

Replica servers must support the LDAP Version 3 protocol.

Populating a replica

  1. Either start the replica and replicating servers in maintenance mode or use the LDAP server MAINTMODE ON operator modify command on each of these LDAP servers to put these servers into maintenance mode.
  2. Unload the replicating server’s directory contents if there are any entries. For TDBM or LDBM, use the ds2ldif utility (see ds2ldif utility).
  3. Ensure that the schema for the replica server is the same as the schema for the replicating server.

    If the replica and replicating server are both z/OS servers, the schema can be unloaded from the replicating server using ds2ldif and reloaded into the replica by an LDAP root or schema administrator with the ldapmodify utility.

  4. Using a root administrator user, run the ldapadd utility to add a single replica entry into the backend directory on the replicating server to identify the new replica being populated.

    Note that in order to load the replica entry, it is also necessary to load any parent entries in the directory hierarchy in hierarchy order.

  5. If the replicating server does not contain any entries, go to step 8.
  6. Transport the LDIF file created in step 2 to the replica server’s location.
  7. Load the LDIF file from 6 into the replica server. This can be done using an LDAP root administrator to run the ldapadd utility to load the LDIF file. Alternatively for TDBM, the replica server can be stopped and then the ldif2ds utility used to load the LDIF file.
  8. Configure the replica (see next section).
  9. Stop the replica server (if it is running) and then restart it in maintenance mode. If it contains a replica entry that defines this server as a replica of itself, use an LDAP root administrator to run the ldapdelete utility to remove that entry.
  10. Use the LDAP server MAINTMODE OFF command on the replica server and the replicating server to change these servers to normal mode.

Configuring the replica

The key to a successful replica configuration rests in ensuring that the values in the replica entry on the replicating server (master or peer) accurately represent the relevant values on the replica server (read-only or peer). Configuring the replica involves specifying appropriate LDAP server configuration file option values to identify:
  • the IP address and port on which the replica server should listen for communication from the replicating server
  • the type of connection expected by the replicating server when it communicates to the replica server, either over a non-secure or secure connection
  • the DN and password used by the replicating server

The following table identifies the relationship between the attributes in the replica entry on a z/OS LDAP replicating server and the configuration options on an IBM® replica server. The values specified for these options must be equivalent. An example of what is meant by equivalent is when the replica server is listening on all of its network interfaces, then replicaHost must specify either the corresponding host name or an IP address of one of the addresses.

Attribute in replica entry on replicating server Corresponding replica server configuration option or command line parameter
replicaHost The host name or IP address specified on the listen configuration option or the -l LDAP server command line parameter.
replicaPort The port number that is specified on the listen configuration option or the -l LDAP server command line parameter.
replicaUseSSL Use of ldaps:// in the prefix of the listen configuration option or the -l LDAP server command line parameter corresponds to TRUE for replicaUseSSL; use of ldap:// corresponds to FALSE.
replicaBindDn masterServerDN or peerServerDN configuration option
replicaCredentials masterServerPW or peerServerPW configuration option
Note:
  1. If the replica server is a non-IBM server, you should consult their documentation for parameters that correspond to the parameters mentioned in the above table.
  2. The value of the listen configuration option or –l command line parameter is an LDAP URL. For additional information about the listen option, see Customizing the LDAP server configuration.
  3. It is preferred that the masterServerDN or peerServerDN be a DN that is dedicated specifically to replication. It should not be used for any other operations.
  4. The masterServer, masterServerDN, masterServerPW, peerServerDN, and peerServerPW options must follow the database option for that backend in the LDAP server configuration file.
  5. Usage of the masterServerPW or peerServerPW configuration option is strongly discouraged in production environments. See Establishing the root administrator DN and basic replication replica server DN and passwords for alternatives.
  6. The replicaCredentials attribute is encrypted if the secretEncryption configuration option is specified. This improves directory security because the bind password is no longer stored in the directory in clear text. The secretEncryption configuration option is also used to encrypt pending updates while they are stored in the replication queue.

LDAP update operations on read-only replicas

Update operations, such as add, delete, modify, and rename, should not be performed against a read-only replica server. Changes must be made to the master server, which then propagates the change to the read-only replica.

If update operations are sent to a read-only replica server, the replica server returns a referral containing the value in the masterServer option in the backend section of the LDAP server configuration file on the replica. The client then redirects the request to the master server. After the master server makes the update, it propagates the change to the read-only replica server, binding as the replicaBindDn value in the replica entry corresponding to that replica server (the replicaBindDn value must match the masterServerDN value in the replica server configuration file).

See SSL/TLS and basic replication for information about securing a directory.