Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide

Initializing Replicas

After you have created a replication agreement and after both replicas have been configured, you must initialize the consumer replicated suffix before replication can begin. During initialization, you physically copy data from the supplier replicated suffix to the consumer replicated suffix.

In addition, certain error conditions or configuration changes require you to reinitialize replicas. For example, if the data in a single master replicated suffix is restored from a backup for any reason, you need to reinitialize all of the replicas that it updates.

When reinitializing, the contents of the replicated suffix are deleted on the consumer and replaced with the contents of the suffix on the master. This ensures that the replicas are synchronized and that replication updates can resume. All of the initialization methods described in this section automatically rebuild the indexes of the consumer replica so that the consumer is ready to respond optimally to client read requests.

With multimaster replication, consumers might not need to be reinitialized if they have been updated by the other masters in the topology.

ProcedureTo Initialize a Replicated Suffix from a Remote (Supplier) Server

You can initialize a suffix from a remote server by using an existing replication agreement. Use this method of initializing if possible, because it is less complicated than the other methods. Use the other methods only for large quantities of data that make the import too time consuming.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

Online initialization of a replicated suffix by using DSCC is an easy way to initialize or reinitialize a consumer. However, if you are initializing a large number of entries, this process can be time consuming. In this case, you might find offline consumer initialization with the command line more efficient.

  1. Initialize your replica.


    $ dsconf init-repl-dest -h host -p port suffix-DN destination-host:destination-port [destination-host:destination-port]

    where destination-host:destination-port is the host and port of the destination server that you are initializing from the remote server.

  2. (Optional) For each agreement, check that the suffix appears as initialized.


    $ dsconf show-repl-agmt-status -h host -p port suffix-DN destination-host:destination-port 
    

Replica Initialization From LDIF

ProcedureTo Initialize a Replicated Suffix From LDIF

This procedure outlines the general steps to use to initialize a replicated suffix from an LDIF file.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

Online initialization of a replicated suffix by using DSCC is an easy way to initialize or reinitialize a consumer. However, if you are initializing a large number of entries, this process can be time consuming. In this case, you might find offline consumer initialization with the command line more efficient.

  1. Ensure that you have set up replication agreements.

    You must do this before you initialize replicas.

  2. Export the original copy of the suffix data from a master replicated suffix to an LDIF file.

    See To Export a Replicated Suffix to LDIF.

    In a multimaster replication environment, you can use the LDIF file exported from the original master to initialize both the other masters and any consumers. In a cascading replication environment, you can use the same file to initialize both the hub replicas and their consumers.

    In all cases, you must start with an LDIF file that has been exported from a configured master replica. You cannot use an arbitrary LDIF file to initialize all replicas because it does not contain replication meta-data.

  3. If you are initializing a fractional replica, filter the file to keep only the replicated attributes, then transfer that file to all of the consumer servers.

    See Filtering an LDIF File for Fractional Replication.

  4. Initialize your replica.

    Do one of the following:

    • For fast initialization on a server that is offline (stopped), use the dsadm import command.


      $ dsadm import instance-path LDIF_file suffix-DN
      
    • To initialize a replica online from an LDIF file, use the dsconf import command.


      $ dsconf import -h host -p port LDIF_file suffix-DN
      

      Using dsconf import is slower than using dsadm import, but you do not need to stop your server while performing the import operation.

    For more detailed information about initializing suffixes, and for examples, see Initializing a Suffix. For detailed command usage, see dsadm(1M) and dsconf(1M).

  5. (Optional) For each agreement, check that the suffix appears as initialized.


    $ dsconf show-repl-agmt-status -h host -p port suffix-DN destination-host:destination-port 
    

ProcedureTo Export a Replicated Suffix to LDIF

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

    Export the replicated suffix contents in an LDIF file by using one of the following commands:

    • For an offline export, type:


      $ dsadm export instance-path suffix-DN LDIF_file
      
    • For an online export, type:


      $ dsconf export -h host -p port suffix-DN LDIF_file
      

    The following example will export the entire dc=example,dc=com replicated suffix and replication information to the file example_replica_export.ldif:


    $ dsconf export -h host2 -p 1389 dc=example,dc=com  \
     /local/ds/ldif/example_export_replica.ldif

    For more information, see Backing Up to LDIF and the dsadm(1M) and dsconf(1M) man pages.

Filtering an LDIF File for Fractional Replication

Initializing a replica with fractional replication configured is transparent when using DSCC. Only the selected attributes will be sent to the consumer during the initialization.

If you have configured fractional replication, you should filter out any unused attributes before copying the exported LDIF file to the consumer servers. Directory Server provides the fildif tool for this purpose. This tool filters the given LDIF file to keep only the attributes that are allowed by the attribute set defined in your replication agreement.

This tool reads the server’s configuration to determine the attribute set definition. To read the configuration file, the fildif tool must be run as root or as the user who owns the process and the files (specified by the nsslapd-localuser attribute). For example, the following command filters the file exported from the dc=example,dc=com suffix in the previous example:


$ fildif -i /local/ds1/ldif/example_master.ldif \
 -o /local/ds1/ldif/filtered.ldif -b "cn=host2.example.com:1389, \
 cn=replica,cn=\\"dc=example,dc=com\\",cn=mapping tree,cn=config" -p /local/ds1

For the location of the fildif command, see Command Locations.

The -i and -o options are the input and output files, respectively. The -b option is the DN of the replication agreement where fractional replication is defined. You can find this DN by using this command:


$ ldapsearch -h host -p port -D cn=admin,cn=Administrators,cn=config -w - \
 -b "cn=config" "(&(objectclass=nsds5replicationagreement) (nsDS5ReplicaPort=replica-port) \
 (nsDS5ReplicaHost=replica-host))" dn

For example:


$ ldapsearch -h host2 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - \
 -b "cn=config" "(&(objectclass=nsds5replicationagreement) \
 (nsDS5ReplicaPort=2090)(nsDS5ReplicaHost=host2))" dn
Enter bind password:
version: 1
dn: cn=host2:1389,cn=replica,cn=dc\=example\,dc\=com,cn=mapping tree,cn=config

For the full command-line syntax for the fildif tool, see the fildif(1) man page.

You can then use the filtered.ldif file produced by fildif to initialize the consumer in this replication agreement. Transfer the file to the consumer server and import it as described in Importing Data From an LDIF File.

Initializing a Replicated Suffix by Using Binary Copy

A binary copy enables you to clone an entire server by using the binary backup files from one server to restore the identical directory contents onto another server. You can use a binary copy to initialize or reinitialize any server from the binary copy of a master or hub server, or a consumer from the binary copy of another consumer server.


Note –

This advanced procedure interacts with the database files of Directory Server and should only be used by experienced administrators.

Certain restrictions on this feature make it practical and time efficient only for replicas with very large database files, for example, replicas containing millions of entries.


Restrictions for Using Binary Copy With Replication

Because a binary copy moves database files from one machine to another, the mechanism is subject to the following strict limitations:

Making a Binary Copy for Initializing a Server

This section describes how to make a binary copy for initializing a server, and how to make a binary copy that uses minimum disk space.

ProcedureTo Make a Binary Copy For Initializing a Server

Use this procedure to perform a binary copy for initializing a replicated server because it uses the normal backup functionality to create a copy of the server’s database files. Performing a normal backup ensures that all database files are in a coherent state without requiring you to stop the server.

This procedure has certain limitations. The backup and restore operations create copies of the database files on the same machine, thereby doubling the amount of disk space required by those files on each machine. Additionally, the actual copy operation on these files might take a significant amount time if your directory contains gigabytes of data.

For parts of this procedure, you can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help. Other parts of the procedure can only be done using the command line.

  1. Install Directory Server on the target machine for the new replicated suffix, create a new instance of the server if necessary, and configure the server according to Restrictions for Using Binary Copy With Replication.

  2. Create all replication agreements in your replication topology that involve this replicated suffix.

    Include agreements from suppliers to this replica. If this replica is not a dedicated consumer, include agreements from this replica to its consumers. See Creating Replication Agreements.

  3. Select a fully configured and initialized replica of the same type as you want to initialize, either master, hub, or consumer, and perform a normal backup on it according to Binary Backup.

  4. Copy or transfer the files from the backup directory to a directory on the target machine by using the ftp command, for example.

  5. If you have initialized a new master in a multimaster replication scenario, follow the procedures in Restoring a Master in a Multi-Master Scenario.

ProcedureTo Use Binary Copy for Initializing a Server Using Minimum Disk Space

This procedure uses less disk space and takes less time because it does not make backup copies of the database files. However, it requires you to stop the server that is being cloned to order to ensure that the database files are in a coherent state.


Caution – Caution –

This procedure must not be used to reinitialize a master that has already participated in a multimaster replication scenario. It can only be used to reinitialize a consumer server or to initialize a new master server. To reinitialize an existing master replica, use online initialization, import an LDIF file, or follow the procedure in Making a Binary Copy for Initializing a Server.


For parts of this procedure, you can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help. Other parts of the procedure can only be done using the command line.

  1. Install Directory Server on the target machine for the new replicated suffix, create a new instance of the server if necessary, and configure the server according to Restrictions for Using Binary Copy With Replication.

  2. Create all replication agreements in your replication topology that involve this replica.

    Include agreements from suppliers to this replica. If this replica is not a dedicated consumer, include agreements from this replica to its consumers. See Creating Replication Agreements.

  3. Stop the target server that will be initialized or reinitialized, as described in Starting, Stopping, and Restarting a Directory Server Instance .

  4. Select a fully configured and initialized replica of the same type that you want to initialize, either master, hub, or consumer, and stop this server as well.

    If you are cloning a master replica in a multimaster configuration, ensure that it is fully up-to-date with all of the latest changes from the other masters before stopping it.

  5. Remove all database files from the target server, including transaction logs, change logs, and region files (__db.xxx files).

    Unless the files have been relocated, database files and transaction logs are located in the instance-path/db directory.

  6. Copy or transfer all database files, including transaction logs and change logs, from the source replica machine to the target machine, by using the ftp command, for example.

    Unless the files have been relocated, database files and transaction logs are located in the instance-path/db directory.

    If you are initializing a master or hub replica, you must also copy all files in the change log, which is located in instance-path/changelog by default.

  7. Restart both the source and the target servers.

Initializing Replicas in Cascading Replication

In the case of cascading replication, always initialize replicas in the order shown in the following procedure.

ProcedureTo Initialize Replicas in Cascading Replication

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. If you also have multimaster replication, ensure that one master has the complete set of data to replicate, then use this master to initialize the replica on each of the other masters.

  2. Initialize the replicas on the first-level hub replicas from their master replicas.

  3. If you have several levels of hubs, initialize each level from the previously initialized level of hubs.

  4. From the last level of hub replicas, initialize the replicas on the dedicated consumers.