From dab677b887c19f49a0e298f80f55c9ef8d81a85b Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Fri, 17 Jan 2014 15:54:40 +0000
Subject: [PATCH] CR-2851 Fix for OPENDJ-1267: Document behavior of 'dsreplication enable' with regards to schema initialization and --host1/--host2 parameters

---
 opends/resource/man/man1/dsreplication.1 |  440 +++++++++++++++++++++++++++++++++++++++++++++++-------
 1 files changed, 380 insertions(+), 60 deletions(-)

diff --git a/opends/resource/man/man1/dsreplication.1 b/opends/resource/man/man1/dsreplication.1
index 8fab1e0..7fe736f 100644
--- a/opends/resource/man/man1/dsreplication.1
+++ b/opends/resource/man/man1/dsreplication.1
@@ -2,12 +2,12 @@
 .\"     Title: dsreplication
 .\"    Author: 
 .\" Generator: DocBook XSL-NS Stylesheets v1.76.1 <http://docbook.sf.net/>
-.\"      Date: 05/16/2013
+.\"      Date: 01/17/2014
 .\"    Manual: Tools Reference
-.\"    Source: OpenDJ 2.6.0
+.\"    Source: OpenDJ 2.7.0-SNAPSHOT
 .\"  Language: English
 .\"
-.TH "DSREPLICATION" "1" "05/16/2013" "OpenDJ 2\&.6\&.0" "Tools Reference"
+.TH "DSREPLICATION" "1" "01/17/2014" "OpenDJ 2\&.7\&.0\-SNAPSHOT" "Tools Reference"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -39,62 +39,7 @@
 subcommand and then initialize the contents of one of the servers with the contents of the other using the
 \fBinitialize\fR
 subcommand\&.
-.SH "SUBCOMMANDS"
-.PP
-The following subcommands are supported\&.
-.PP
-\fBdisable\fR
-.RS 4
-Disable replication on the specified server for the provided base DN and removes references in the other servers with which it is replicating data\&.
-.RE
-.PP
-\fBenable\fR
-.RS 4
-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\&.
-.RE
-.PP
-\fBinitialize\fR
-.RS 4
-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\&.
-\fBinitialize\-all\fR
-can also be used for this purpose\&.
-.RE
-.PP
-\fBinitialize\-all\fR
-.RS 4
-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
-\fBinitialize\fR
-for each server to achieve the same effect\&.
-.RE
-.PP
-\fBpost\-external\-initialization\fR
-.RS 4
-This subcommand must be called after initializing the contents of all the replicated servers using the
-\fBimport\-ldif\fR
-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
-\fBpre\-external\-initialization \-\-help\fR
-for more information\&.
-.RE
-.PP
-\fBpre\-external\-initialization\fR
-.RS 4
-This subcommand must be called before initializing the contents of all the replicated servers using the
-\fBimport\-ldif\fR
-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
-\fBpost\-external\-initialization\fR
-subcommand\&.
-.RE
-.PP
-\fBpurge\-historical\fR
-.RS 4
-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\&.
-.RE
-.PP
-\fBstatus\fR
-.RS 4
-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\&.
-.RE
-.SH "OPTIONS"
+.SH "GLOBAL OPTIONS"
 .PP
 The following options are supported\&.
 .PP
@@ -248,6 +193,381 @@
 .RS 4
 An error occurred\&.
 .RE
+.SH "SUBCOMMANDS"
+.PP
+The following subcommands are supported\&.
+.PP
+\fBdisable\fR
+.RS 4
+Disable replication on the specified server for the provided base DN and removes references in the other servers with which it is replicating data\&.
+In addition to global options, these subcommand options are supported\&.
+.PP
+\fB\-a, \-\-disableAll\fR
+.RS 4
+Disable the replication configuration on the specified server\&. The contents of the server are no longer replicated and the replication server (changelog and replication port) is disabled if it is configured\&.
+.RE
+.PP
+\fB\-D, \-\-bindDN {bindDN}\fR
+.RS 4
+DN to use to bind to the server where we want to disable replication\&. This option must be used when no Global Administrator has been defined on the server or if the user does not want to remove references in the other replicated servers\&. The password provided for the Global Administrator will be used when specifying this option\&.
+.sp
+Default value: cn=Directory Manager
+.RE
+.PP
+\fB\-\-disableReplicationServer\fR
+.RS 4
+Disable the replication server\&. The replication port and change log are disabled on the specified server\&.
+.RE
+.PP
+\fB\-h, \-\-hostname {host}\fR
+.RS 4
+Directory server hostname or IP address
+.sp
+Default value:
+\fIconfigured\-hostname\fR
+.RE
+.PP
+\fB\-p, \-\-port {port}\fR
+.RS 4
+Directory server administration port number
+.sp
+Default value:
+\fIconfigured\-admin\-port\fR
+.RE
+.RE
+.PP
+\fBenable\fR
+.RS 4
+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\&.
+In addition to global options, these subcommand options are supported\&.
+.PP
+\fB\-h, \-\-host1 {host}\fR
+.RS 4
+Fully qualified host name or IP address of the first server whose contents will be replicated\&.
+.sp
+Default value:
+\fIconfigured\-hostname\fR
+.RE
+.PP
+\fB\-p, \-\-port1 {port}\fR
+.RS 4
+Directory server administration port number of the first server whose contents will be replicated\&.
+.sp
+Default value:
+\fIconfigured\-admin\-port\fR
+.RE
+.PP
+\fB\-D, \-\-bindDN1 {bindDN}\fR
+.RS 4
+DN to use to bind to the first server whose contents will be replicated\&. If not specified the global administrator will be used to bind\&.
+.sp
+Default value: cn=Directory Manager
+.RE
+.PP
+\fB\-\-bindPassword1 {bindPassword}\fR
+.RS 4
+Password to use to bind to the first server whose contents will be replicated\&. If no bind DN was specified for the first server the password of the global administrator will be used to bind\&.
+.RE
+.PP
+\fB\-\-bindPasswordFile1 {bindPasswordFile}\fR
+.RS 4
+File containing the password to use to bind to the first server whose contents will be replicated\&. If no bind DN was specified for the first server the password of the global administrator will be used to bind\&.
+.RE
+.PP
+\fB\-r, \-\-replicationPort1 {port}\fR
+.RS 4
+Port that will be used by the replication mechanism in the first server to communicate with the other servers\&. You have to specify this option only if replication was not previously configured in the first server\&.
+.sp
+Default value: 8989
+.RE
+.PP
+\fB\-\-secureReplication1\fR
+.RS 4
+Specifies whether or not the communication through the replication port of the first server is encrypted or not\&. This option will only be taken into account the first time replication is configured on the first server\&.
+.RE
+.PP
+\fB\-\-noReplicationServer1\fR
+.RS 4
+Do not configure a replication port or change log on the first server\&. The first server will contain replicated data but will not contain a change log of modifications made to the replicated data\&. Note that each replicated topology must contain at least two servers with a change log to avoid a single point of failure\&.
+.RE
+.PP
+\fB\-\-onlyReplicationServer1\fR
+.RS 4
+Configure only a change log and replication port on the first server\&. The first server will not contain replicated data, but will contain a change log of the modifications made to the replicated data on other servers\&.
+.RE
+.PP
+\fB\-O, \-\-host2 {host}\fR
+.RS 4
+Fully qualified host name or IP address of the second server whose contents will be replicated\&.
+.sp
+Default value:
+\fIconfigured\-hostname\fR
+.RE
+.PP
+\fB\-\-port2 {port}\fR
+.RS 4
+Directory server administration port number of the second server whose contents will be replicated\&.
+.sp
+Default value:
+\fIconfigured\-admin\-port\fR
+.RE
+.PP
+\fB\-\-bindDN2 {bindDN}\fR
+.RS 4
+DN to use to bind to the second server whose contents will be replicated\&. If not specified the global administrator will be used to bind\&.
+.sp
+Default value: cn=Directory Manager
+.RE
+.PP
+\fB\-\-bindPassword2 {bindPassword}\fR
+.RS 4
+Password to use to bind to the second server whose contents will be replicated\&. If no bind DN was specified for the second server the password of the global administrator will be used to bind\&.
+.RE
+.PP
+\fB\-F, \-\-bindPasswordFile2 {bindPasswordFile}\fR
+.RS 4
+File containing the password to use to bind to the second server whose contents will be replicated\&. If no bind DN was specified for the second server the password of the global administrator will be used to bind\&.
+.RE
+.PP
+\fB\-R, \-\-replicationPort2 {port}\fR
+.RS 4
+Port that will be used by the replication mechanism in the second server to communicate with the other servers\&. You have to specify this option only if replication was not previously configured in the second server\&.
+.sp
+Default value: 8989
+.RE
+.PP
+\fB\-\-secureReplication2\fR
+.RS 4
+Specifies whether or not the communication through the replication port of the second server is encrypted or not\&. This option will only be taken into account the first time replication is configured on the second server\&.
+.RE
+.PP
+\fB\-\-noReplicationServer2\fR
+.RS 4
+Do not configure a replication port or change log on the second server\&. The second server will contain replicated data but will not contain a change log of modifications made to the replicated data\&. Note that each replicated topology must contain at least two servers with a change log to avoid a single point of failure\&.
+.RE
+.PP
+\fB\-\-onlyReplicationServer2\fR
+.RS 4
+Configure only a change log and replication port on the second server\&. The second server will not contain replicated data, but will contain a change log of the modifications made to the replicated data on other servers\&.
+.RE
+.PP
+\fB\-S, \-\-skipPortCheck\fR
+.RS 4
+Skip the check to determine whether the specified replication ports are usable\&.
+.RE
+.PP
+\fB\-\-noSchemaReplication\fR
+.RS 4
+Do not replicate the schema between the servers\&.
+.RE
+.PP
+\fB\-\-useSecondServerAsSchemaSource\fR
+.RS 4
+Use the second server to initialize the schema of the first server\&. If this option nor option \-\-noSchemaReplication are specified the schema of the first server will be used to initialize the schema of the second server\&.
+.RE
+.RE
+.PP
+\fBinitialize\fR
+.RS 4
+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\&.
+\fBinitialize\-all\fR
+can also be used for this purpose\&.
+In addition to global options, these subcommand options are supported\&.
+.PP
+\fB\-h, \-\-hostSource {host}\fR
+.RS 4
+Fully qualified host name or IP address of the source server whose contents will be used to initialize the destination server\&.
+.sp
+Default value:
+\fIconfigured\-hostname\fR
+.RE
+.PP
+\fB\-p, \-\-portSource {port}\fR
+.RS 4
+Directory server administration port number of the source server whose contents will be used to initialize the destination server\&.
+.sp
+Default value:
+\fIconfigured\-admin\-port\fR
+.RE
+.PP
+\fB\-O, \-\-hostDestination {host}\fR
+.RS 4
+Fully qualified host name or IP address of the destination server whose contents will be initialized\&.
+.sp
+Default value:
+\fIconfigured\-hostname\fR
+.RE
+.PP
+\fB\-\-portDestination {port}\fR
+.RS 4
+Directory server administration port number of the destination server whose contents will be initialized\&.
+.sp
+Default value:
+\fIconfigured\-admin\-port\fR
+.RE
+.RE
+.PP
+\fBinitialize\-all\fR
+.RS 4
+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
+\fBinitialize\fR
+for each server to achieve the same effect\&.
+In addition to global options, these subcommand options are supported\&.
+.PP
+\fB\-h, \-\-hostname {host}\fR
+.RS 4
+Directory server hostname or IP address
+.sp
+Default value:
+\fIconfigured\-hostname\fR
+.RE
+.PP
+\fB\-p, \-\-port {port}\fR
+.RS 4
+Directory server administration port number
+.sp
+Default value:
+\fIconfigured\-admin\-port\fR
+.RE
+.RE
+.PP
+\fBpost\-external\-initialization\fR
+.RS 4
+This subcommand must be called after initializing the contents of all the replicated servers using the
+\fBimport\-ldif\fR
+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
+\fBpre\-external\-initialization \-\-help\fR
+for more information\&.
+In addition to global options, these subcommand options are supported\&.
+.PP
+\fB\-h, \-\-hostname {host}\fR
+.RS 4
+Directory server hostname or IP address
+.sp
+Default value:
+\fIconfigured\-hostname\fR
+.RE
+.PP
+\fB\-p, \-\-port {port}\fR
+.RS 4
+Directory server administration port number
+.sp
+Default value:
+\fIconfigured\-admin\-port\fR
+.RE
+.RE
+.PP
+\fBpre\-external\-initialization\fR
+.RS 4
+This subcommand must be called before initializing the contents of all the replicated servers using the
+\fBimport\-ldif\fR
+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
+\fBpost\-external\-initialization\fR
+subcommand\&.
+In addition to global options, these subcommand options are supported\&.
+.PP
+\fB\-h, \-\-hostname {host}\fR
+.RS 4
+Directory server hostname or IP address
+.sp
+Default value:
+\fIconfigured\-hostname\fR
+.RE
+.PP
+\fB\-p, \-\-port {port}\fR
+.RS 4
+Directory server administration port number
+.sp
+Default value:
+\fIconfigured\-admin\-port\fR
+.RE
+.RE
+.PP
+\fBpurge\-historical\fR
+.RS 4
+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\&.
+In addition to global options, these subcommand options are supported\&.
+.PP
+\fB\-h, \-\-hostname {host}\fR
+.RS 4
+Directory server hostname or IP address
+.sp
+Default value:
+\fIconfigured\-hostname\fR
+.RE
+.PP
+\fB\-p, \-\-port {port}\fR
+.RS 4
+Directory server administration port number
+.sp
+Default value:
+\fIconfigured\-admin\-port\fR
+.RE
+.PP
+\fB\-\-maximumDuration {maximum duration}\fR
+.RS 4
+This argument specifies the maximum duration the purge processing must last expressed in seconds\&.
+.sp
+Default value: 3600
+.RE
+.PP
+\fB\-t, \-\-start {startTime}\fR
+.RS 4
+Indicates the date/time at which this operation will start when scheduled as a server task expressed in YYYYMMDDhhmmssZ format for UTC time or YYYYMMDDhhmmss for local time\&. A value of \*(Aq0\*(Aq will cause the task to be scheduled for immediate execution\&. When this option is specified the operation will be scheduled to start at the specified time after which this utility will exit immediately\&.
+.RE
+.PP
+\fB\-\-recurringTask {schedulePattern}\fR
+.RS 4
+Indicates the task is recurring and will be scheduled according to the value argument expressed in crontab(5) compatible time/date pattern
+.RE
+.PP
+\fB\-\-completionNotify {emailAddress}\fR
+.RS 4
+Email address of a recipient to be notified when the task completes\&. This option may be specified more than once\&.
+.RE
+.PP
+\fB\-\-errorNotify {emailAddress}\fR
+.RS 4
+Email address of a recipient to be notified if an error occurs when this task executes\&. This option may be specified more than once\&.
+.RE
+.PP
+\fB\-\-dependency {taskID}\fR
+.RS 4
+ID of a task upon which this task depends\&. A task will not start execution until all its dependencies have completed execution\&.
+.RE
+.PP
+\fB\-\-failedDependencyAction {action}\fR
+.RS 4
+Action this task will take should one if its dependent tasks fail\&. The value must be one of PROCESS,CANCEL,DISABLE\&. If not specified defaults to CANCEL\&.
+.RE
+.RE
+.PP
+\fBstatus\fR
+.RS 4
+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\&.
+In addition to global options, these subcommand options are supported\&.
+.PP
+\fB\-h, \-\-hostname {host}\fR
+.RS 4
+Directory server hostname or IP address
+.sp
+Default value:
+\fIconfigured\-hostname\fR
+.RE
+.PP
+\fB\-p, \-\-port {port}\fR
+.RS 4
+Directory server administration port number
+.sp
+Default value:
+\fIconfigured\-admin\-port\fR
+.RE
+.PP
+\fB\-s, \-\-script\-friendly\fR
+.RS 4
+Use script\-friendly mode\&.
+.RE
+.RE
 .SH "EXAMPLES"
 .PP
 The following example enables and then initializes replication for a new replica on
@@ -309,5 +629,5 @@
 .\}
 .SH "COPYRIGHT"
 .br
-Copyright \(co 2011-2013 ForgeRock AS
+Copyright \(co 2011-2014 ForgeRock AS
 .br

--
Gitblit v1.10.0