<?xml version="1.0" encoding="UTF-8"?>

<refentry xml:id='dsreplication-1'

xmlns='http://docbook.org/ns/docbook'

version='5.0' xml:lang='en'

xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'

xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'

xmlns:xlink='http://www.w3.org/1999/xlink'

xmlns:xinclude='http://www.w3.org/2001/XInclude'>

<info><copyright><year>2011-2013</year><holder>ForgeRock AS</holder></copyright></info>

<refmeta>

<refentrytitle>dsreplication</refentrytitle><manvolnum>1</manvolnum>

<refmiscinfo class="software">OpenDJ</refmiscinfo>

<refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>

</refmeta>

<refnamediv>

<refname>dsreplication</refname>

<refpurpose>manage OpenDJ directory data replication</refpurpose>

</refnamediv>

<refsynopsisdiv>

<cmdsynopsis>

<command>dsreplication</command>

<command><replaceable>subcommand</replaceable></command>

<arg>options</arg>

</cmdsynopsis>

</refsynopsisdiv>

<refsect1>

<title>Description</title>

<para>This utility can be used to configure replication between servers so

that the data of the servers is synchronized. For replication to work you

must first enable replication using the <command>enable</command> subcommand

and then initialize the contents of one of the servers with the contents of

the other using the <command>initialize</command> subcommand.</para>

</refsect1>

<refsect1>

<title>Subcommands</title>

<para>The following subcommands are supported.</para>

<variablelist>

<varlistentry>

<term><command>disable</command></term>

<listitem>

<para>Disable replication on the specified server for the provided base

DN and removes references in the other servers with which it is

replicating data.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><command>enable</command></term>

<listitem>

<para>Update the configuration of the servers to replicate the data

under the specified base DN. If one of the specified servers is already

replicating the data under the base DN with other servers, executing this

subcommand will update the configuration of all the servers. Thus it is

sufficient to execute the command line once for each server added to the

replication topology.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><command>initialize</command></term>

<listitem>

<para>Initialize the contents of the data under the specified base DN

on the destination server with the contents on the source server. This

operation is required after enabling replication in order replication to

work. <command>initialize-all</command> can also be used for this

purpose.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><command>initialize-all</command></term>

<listitem>

<para>Initialize the contents of the data under the specified base DN

on all the servers whose contents are being replicated with the contents

on the specified server. This operation is required after enabling

replication for replication to work. Run <command>initialize</command>

for each server to achieve the same effect.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><command>post-external-initialization</command></term>

<listitem>

<para>This subcommand must be called after initializing the contents of

all the replicated servers using the <command>import-ldif</command>

command, or by copying the database. You must specify the list of base DNs

that have been initialized, and you must provide the credentials of any

of the servers that are being replicated. See

<command>pre-external-initialization --help</command> for more

information.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><command>pre-external-initialization</command></term>

<listitem>

<para>This subcommand must be called before initializing the contents

of all the replicated servers using the <command>import-ldif</command>

command, or by copying the database. You must specify the list of base DNs

that have been initialized, and you must provide the credentials of any

of the servers that are being replicated. After calling this subcommand,

initialize the contents of all the servers in the topology, either by

using the same LDIF file or by copying the database to each of the

servers, then call the <command>post-external-initialization</command>

subcommand.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><command>purge-historical</command></term>

<listitem>

<para>Launch a purge processing of the historical information stored

in the user entries by replication. Since this processing may take a

while, you must specify a maximum duration.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><command>status</command></term>

<listitem>

<para>Display a list with the basic replication configuration of the

base DNs of the servers defined in the registration information. If

no base DNs are specified as parameter, information for all base DNs

is displayed.</para>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1>

<title>Options</title>

<para>The following options are supported.</para>

<variablelist>

<varlistentry>

<term><option>--advanced</option></term>

<listitem>

<para>Access advanced settings when running this command in interactive

mode.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-b, --baseDN {baseDN}</option></term>

<listitem>

<para>Base DN of the data to be replicated, initialized or for which you

want to disable replication. Multiple base DNs can be provided by using

this option multiple times.</para>

</listitem>

</varlistentry>

</variablelist>

<refsect2>

<title>LDAP Connection Options</title>

<variablelist>

<varlistentry>

<term><option>--connectTimeout {timeout}</option></term>

<listitem>

<para>Maximum length of time (in milliseconds) that can be taken to

establish a connection. Use '0' to specify no time out.</para>

<para>Default value: 30000</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-h, --hostname {host}</option></term>

<listitem>

<para>Directory server hostname or IP address</para>

<para>Default value: localhost.localdomain</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-I, --adminUID {adminUID}</option></term>

<listitem>

<para>User ID of the global administrator to use to bind to the server.

For the <command>enable</command> subcommand, if no global administrator

was defined previously for any servers, the global administrator will be

created using the UID provided.</para>

<para>Default value: admin</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-j, --adminPasswordFile {bindPasswordFile}</option></term>

<listitem>

<para>Global administrator password file</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-K, --keyStorePath {keyStorePath}</option></term>

<listitem>

<para> Certificate key store path</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-N, --certNickname {nickname}</option></term>

<listitem>

<para>Nickname of certificate for SSL client authentication</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-o, --saslOption {name=value}</option></term>

<listitem>

<para>SASL bind options</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-p, --port {port}</option></term>

<listitem>

<para>Directory server administration port number</para>

<para>Default value: 4444</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-P, --trustStorePath {trustStorePath}</option></term>

<listitem>

<para>Certificate trust store path</para>

<para>Default value: /path/to/opendj/config/admin-truststore</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-T, --trustStorePassword {trustStorePassword}</option></term>

<listitem>

<para>Certificate trust store PIN</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-u, --keyStorePasswordFile {keyStorePasswordFile}</option></term>

<listitem>

<para>Certificate key store PIN file</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-U, --trustStorePasswordFile {path}</option></term>

<listitem>

<para>Certificate trust store PIN file</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-w, --adminPassword {bindPassword}</option></term>

<listitem>

<para>Password for the global administrator</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-W, --keyStorePassword {keyStorePassword}</option></term>

<listitem>

<para>Certificate key store PIN</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-X, --trustAll</option></term>

<listitem>

<para>Trust all server SSL certificates</para>

</listitem>

</varlistentry>

</variablelist>

</refsect2>

<refsect2>

<title>Utility Input/Output Options</title>

<variablelist>

<varlistentry>

<term><option>--commandFilePath {path}</option></term>

<listitem>

<para>The full path to the file where the equivalent non-interactive

commands will be written when this command is run in interactive

mode.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>--displayCommand</option></term>

<listitem>

<para>Display the equivalent non-interactive option on standard output

when this command is run in interactive mode.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-n, --no-prompt</option></term>

<listitem>

<para>Use non-interactive mode. If data in the command is missing, the

user is not prompted and the command exits with an error.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>--noPropertiesFile</option></term>

<listitem>

<para>No properties file will be used to get default command line

argument values</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>--propertiesFilePath {propertiesFilePath}</option></term>

<listitem>

<para>Path to the file containing default property values used for

command line arguments</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-Q, --quiet</option></term>

<listitem>

<para>Do not write progress information to standard output</para>

</listitem>

</varlistentry>

</variablelist>

</refsect2>

<refsect2>

<title>General Options</title>

<variablelist>

<varlistentry>

<term><option>--version</option></term>

<listitem>

<para>Display version information</para>

</listitem>

</varlistentry>

<varlistentry>

<term><option>-?, -H, --help</option></term>

<listitem>

<para>Display usage information</para>

</listitem>

</varlistentry>

</variablelist>

</refsect2>

</refsect1>

<refsect1>

<title>Exit Codes</title>

<variablelist>

<varlistentry>

<term>0</term>

<listitem>

<para>The command completed successfully.</para>

</listitem>

</varlistentry>

<varlistentry>

<term>&gt; 0</term>

<listitem>

<para>An error occurred.</para>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1>

<title>Examples</title>

<para>The following example enables and then initializes replication

for a new replica on <literal>opendj2.example.com</literal> from an existing

replica on <literal>opendj.example.com</literal>.</para>

<screen>$ dsreplication enable -I admin -w password -X -n -b dc=example,dc=com

--host1 opendj.example.com --port1 4444 --bindDN1 "cn=Directory Manager"

--bindPassword1 password --replicationPort1 8989

--host2 opendj2.example.com --port2 4444 --bindDN2 "cn=Directory Manager"

--bindPassword2 password --replicationPort2 8989

Establishing connections ..... Done.

Checking registration information ..... Done.

Updating remote references on server opendj.example.com:4444 ..... Done.

Configuring Replication port on server opendj2.example.com:4444 ..... Done.

Updating replication configuration for baseDN dc=example,dc=com on server

opendj.example.com:4444 ..... Done.

Updating replication configuration for baseDN dc=example,dc=com on server

opendj2.example.com:4444 ..... Done.

Updating registration configuration on server

opendj.example.com:4444 ..... Done.

Updating registration configuration on server

opendj2.example.com:4444 ..... Done.

Updating replication configuration for baseDN cn=schema on server

opendj.example.com:4444 ..... Done.

Updating replication configuration for baseDN cn=schema on server

opendj2.example.com:4444 ..... Done.

Initializing registration information on server opendj2.example.com:4444 with

the contents of server opendj.example.com:4444 ..... Done.

Initializing schema on server opendj2.example.com:4444 with the contents of

server opendj.example.com:4444 ..... Done.

Replication has been successfully enabled. Note that for replication to

work you must initialize the contents of the base DN's that are being

replicated (use dsreplication initialize to do so).

See

/var/.../opends-replication-7958637258600693490.log

for a detailed log of this operation.

$ dsreplication initialize-all -I admin -w password -X -n -b dc=example,dc=com

-h opendj.example.com -p 4444

Initializing base DN dc=example,dc=com with the contents from

opendj.example.com:4444: 160 entries processed (100 % complete).

Base DN initialized successfully.

See

/var/.../opends-replication-5020375834904394170.log

for a detailed log of this operation.</screen>

</refsect1>

</refentry>