Directory Server Documentation Index
Command-Line Tool Reference Home

dsreplication

↓Description
↓Examples
↓Subcommands
↓Arguments

Description

Manage data replication between two or more Directory Server instances.

For replication to work, you must first to enable replication using the 'enable'. Then, you initialize the contents of one of the servers with the contents of the other using the 'initialize' subcommand.

Examples

Start dsreplication in interactive mode: 
dsreplication


Enable replication between two Directory Server instances in non-interactive mode: 
dsreplication enable --host1 server1.example.com --port1 1389 \
     --bindDN1 "cn=Directory Manager" --bindPassword1 secret1 \
     --replicationPort1 8989 --host2 server2.example.com --port2 1389 \
     --bindDN2 "cn=Directory Manager" --bindPassword2 secret2 \
     --replicationPort2 8989 --baseDN dc=example,dc=com --adminUID admin \
     --adminPassword secret --no-prompt


Display the replication status of all replicated base DNs in non-interactive mode using the Directory Server listening on port 1389 of host.example.com: 
dsreplication status --hostname host.example.com --port 1389 --adminUID admin \
     --adminPassword secret --no-prompt

Subcommands

↓cleanup-local-server
↓disable
↓enable
↓initialize
↓initialize-all
↓post-external-initialization
↓pre-external-initialization
↓remove-defunct-server
↓status

cleanup-local-server

This subcommand is no longer supported. If this server is defunct, then the remove-defunct-server standalone tool may be used to delete any replication artifacts from its configuration and remove it from the replication topology. If this server can reach other servers in the topology, then running remove-defunct-server from it will cleanly remove it from the topology. If it cannot reach the other servers though, then remove-defunct-server must also be run from one of the online servers

disable

Disable replication on the specified server for the provided base DN and removes references to this server in the other servers with which it is replicating data


disable Examples

Disable replication on base DN dc=example,dc=com in non-interactive mode on the Directory Server listening on port 1389 of host.example.com: 
dsreplication disable --hostname host.example.com --port 1389 \
     --baseDN dc=example,dc=com --adminUID admin --adminPassword secret \
     --no-prompt

disable Arguments

-h {host}
--hostname {host}

Description Directory Server hostname or IP address
Default Value localhost
Required No
Multi-Valued No

-p {port}
--port {port}

Description Directory Server port number
Default Value 389
Required No
Multi-Valued No

-Z
--useSSL

Description Use SSL for secure communication with the server

-q
--useStartTLS

Description Use StartTLS to secure communication with the server

-a
--disableAll

Description Disable replication on all domains

enable

Update the configuration of the servers to replicate the data under the specified base DN. If one of the servers is already replicating the data under the base DN with other servers, executing this subcommand will update the configuration of all the servers (so it is sufficient to execute the command-line once for each server you add to the replication topology). The server-to-server replication communication is always secured with SSL.


enable Examples

Enable replication between two Directory Server instances in non-interactive mode: 
dsreplication enable --host1 server1.example.com --port1 1389 \
     --bindDN1 "cn=Directory Manager" --bindPassword1 secret1 \
     --replicationPort1 8989 --host2 server2.example.com --port2 2389 \
     --bindDN2 "cn=Directory Manager" --bindPassword2 secret2 \
     --replicationPort2 9989 --baseDN dc=example,dc=com --adminUID admin \
     --adminPassword secret --no-prompt


Add the server specified by host and port to the replication topology using the first available server (preferably in the same location as the server) defined in an exported topology registry file in non-interactive mode. This can make deployment automation more fault-tolerant since it is not necessary for a specific server instance to be available. Instead, the command will succeed as long as a single instance in the topology is online. An export of the topology registry may be obtained by running the manage-topology export command: 
dsreplication enable --topologyFilePath topology.json \
     --bindDN1 "cn=Directory Manager" --bindPassword1 secret1 \
     --replicationPort1 8989 --host2 server2.example.com --port2 2389 \
     --bindDN2 "cn=Directory Manager" --bindPassword2 secret2 \
     --replicationPort2 9989 --baseDN dc=example,dc=com --adminUID admin \
     --adminPassword secret --no-prompt

enable Arguments

--topologyFilePath {topologyFilePath}

Description The topology hosts file containing the list of hosts that are already in the topology. This can make deployment automation more fault-tolerant since it is not necessary for a specific server instance to be available. Instead, the command will succeed as long as a single instance in the topology is online. This option may be used in lieu of or in addition to the host1/port1 options and will take precedence if also specified with those options. A connection is attempted to be established to each host in the hosts file preferably in the same location as the server. The first successful connection is used to perform the action, and the remaining hosts are ignored. The LDAP connection options specified on the command-line for host1 will be used for each server in the hosts file. The hosts file may be obtained by running the manage-topology export command on an online topology host using the hostname/port options
Required No
Multi-Valued No

-h {host}
--host1 {host}

Description Fully qualified host name or IP address of the first server whose contents will be replicated
Required No
Multi-Valued No

-p {port}
--port1 {port}

Description Port number of the first server whose contents will be replicated
Default Value 389
Required No
Multi-Valued No

-D {bindDN}
--bindDN1 {bindDN}

Description DN used to bind to the first server whose contents will be replicated. If not specified, the topology-wide administrator will be used to bind
Default Value cn=Directory Manager
Required No
Multi-Valued No

--bindPassword1 {bindPassword}

Description Password used to bind to the first server whose contents will be replicated. If no bind DN was specified, the password of the topology-wide administrator will be used to bind
Required No
Multi-Valued No

--bindPasswordFile1 {bindPasswordFile}

Description File containing the password used to bind to the first server whose contents will be replicated. If no bind DN is specified, the password of the topology-wide administrator will be used to bind
Required No
Multi-Valued No

-q
--startTLS1

Description Use StartTLS to secure communication with the first server

-Z
--useSSL1

Description Use SSL for secure communication with the first server

-r {port}
--replicationPort1 {port}

Description 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 on the first server.
Default Value 8989
Required No
Multi-Valued No

-g {priority}
--gatewayPriority1 {priority}

Description Gateway priority of the first server. Specify this option only if replication was not previously configured on the first server
Default Value 5
Required No
Multi-Valued No

--location1 {location}

Description The location of the first server. Specify this option only if replication was not previously configured on this server
Required No
Multi-Valued No

-O {host}
--host2 {host}

Description Fully qualified host name or IP address of the second server whose contents will be replicated
Required No
Multi-Valued No

--port2 {port}

Description Port number of the second server whose contents will be replicated
Default Value 389
Required No
Multi-Valued No

--bindDN2 {bindDN}

Description DN used to bind to the second server whose contents will be replicated. If not specified, the topology-wide administrator will be used to bind
Default Value cn=Directory Manager
Required No
Multi-Valued No

--bindPassword2 {bindPassword}

Description Password used to bind to the second server whose contents will be replicated. If not specified, the password of the topology-wide administrator will be used to bind
Required No
Multi-Valued No

-F {bindPasswordFile}
--bindPasswordFile2 {bindPasswordFile}

Description File containing the password used to bind to the second server whose contents will be replicated. If no bind DN was specified, the password of the topology-wide administrator will be used to bind
Required No
Multi-Valued No

--startTLS2

Description Use StartTLS to secure communication with the second server

-z
--useSSL2

Description Use SSL for secure communication with the second server

-R {port}
--replicationPort2 {port}

Description 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 on the second server.
Default Value 8989
Required No
Multi-Valued No

-G {priority}
--gatewayPriority2 {priority}

Description Gateway priority of the second server. Specify this option only if replication was not previously configured on the second server
Default Value 5
Required No
Multi-Valued No

--location2 {location}

Description The location of the second server. Specify this option only if replication was not previously configured on this server
Required No
Multi-Valued No

-S
--skipPortCheck

Description Skip the check to determine whether the specified replication ports are usable

--noSchemaReplication

Description Do not replicate the schema between the servers

--useSecondServerAsSchemaSource

Description Use the second server to initialize the schema of the first server. If neither this option nor option --noSchemaReplication are specified, the schema of the first server will be used to initialize the schema of the second server

--restricted {baseDN}

Description The specified base DN is configured as an entry-balancing point in the Directory Proxy Server. Replication for this base DN will be limited to server instances with the same replication set name
Required No
Multi-Valued Yes

--saslOption1 {name=value}

Description SASL bind options for the first server
Required No
Multi-Valued Yes

--saslOption2 {name=value}

Description SASL bind options for the second server
Required No
Multi-Valued Yes

initialize

Initialize the data under a specified base DN on the destination server with the contents on a source server ('initialize-all' can also be used for this purpose)


initialize Examples

Initialize a replica for the dc=example,dc=com base DN listening on port 2389 at dst.example.com with the contents of the replica listening on port 1389 of src.example.com in non-interactive mode: 
dsreplication initialize --hostSource src.example.com --portSource 1389 \
     --hostDestination dst.example.com --portDestination 2389 \
     --baseDN dc=example,dc=com --adminUID admin --adminPassword secret \
     --no-prompt


Initialize a replica for the dc=example,dc=com base DN listening on port 2389 at dst.example.com with the contents of the replica listening on the first available host (preferably in the same location as the server) in the topology.json file in non-interactive mode. This can make deployment automation more fault-tolerant since it is not necessary for a specific server instance to be available. Instead, the command will succeed as long as a single instance in the topology is online. An export of the topology registry may be obtained by running the manage-topology export command: 
dsreplication initialize --topologyFilePath topology.json \
     --hostDestination dst.example.com --portDestination 2389 \
     --baseDN dc=example,dc=com --adminUID admin --adminPassword secret \
     --no-prompt

initialize Arguments

--topologyFilePath {topologyFilePath}

Description The topology hosts file containing the list of hosts that are already in the topology. This can make deployment automation more fault-tolerant since it is not necessary for a specific server instance to be available. Instead, the command will succeed as long as a single instance in the topology is online. This option may be used in lieu of or in addition to the hostSource/portSource options and will take precedence if also specified with those options. A connection is attempted to be established to each host in the hosts file preferably in the same location as the server. The first successful connection is used to perform the action, and the remaining hosts are ignored. The LDAP connection options specified on the command-line for hostSource will be used for each server in the hosts file. The hosts file may be obtained by running the manage-topology export command on an online topology host using the hostname/port options
Required No
Multi-Valued No

-h {host}
--hostSource {host}

Description Fully qualified host name or IP address of the source server whose contents will be used to initialize the destination server
Required No
Multi-Valued No

-p {port}
--portSource {port}

Description Port number of the source server whose contents will be used to initialize the destination server
Default Value 389
Required No
Multi-Valued No

-Z
--useSSLSource

Description Use SSL for secure communication with the source server

-q
--startTLSSource

Description Use StartTLS to secure communication with the source server

-O {host}
--hostDestination {host}

Description Fully qualified host name or IP address of the destination server whose contents will be initialized
Required No
Multi-Valued No

--portDestination {port}

Description Port number of the destination server whose contents will be initialized
Default Value 389
Required No
Multi-Valued No

-z
--useSSLDestination

Description Use SSL for secure communication with the destination server

--startTLSDestination

Description Use StartTLS to secure communication with the destination server

initialize-all

Initialize the data under a specified base DN on all the servers in the replication topology with the contents on a specified server ('initialize' applied to each server can also be used for this purpose)


initialize-all Examples

Initialize all replicas for the dc=example,dc=com base DN in the topology in non-interactive mode with the contents of the replica listening on port 1389 of source.example.com. The administrator password is provided in the password file password.txt: 
dsreplication initialize-all --hostname source.example.com --port 1389 \
     --baseDN dc=example,dc=com --adminUID admin \
     --adminPasswordFile password.txt --no-prompt

initialize-all Arguments

-h {host}
--hostname {host}

Description Directory Server hostname or IP address
Default Value localhost
Required No
Multi-Valued No

-p {port}
--port {port}

Description Directory Server port number
Default Value 389
Required No
Multi-Valued No

-Z
--useSSL

Description Use SSL for secure communication with the server

-q
--useStartTLS

Description Use StartTLS to secure communication with the server

post-external-initialization

This subcommand must be called after replacing the data for one or more base DNs across all servers. You must specify the list of base DNs that have been initialized and apply the subcommand, once, to any of the replicating servers. See the usage of the 'post-external-initialization' subcommand for more information


post-external-initialization Examples

Perform post-external initialization on base DNs dc=example,dc=com and ou=people,dc=example,dc=com for all replicas in the topology: 
dsreplication post-external-initialization --hostname host.example.com \
     --port 1389 --baseDN dc=example,dc=com \
     --baseDN ou=people,dc=example,dc=com --adminUID admin \
     --adminPassword secret

post-external-initialization Arguments

-h {host}
--hostname {host}

Description Directory Server hostname or IP address
Default Value localhost
Required No
Multi-Valued No

-p {port}
--port {port}

Description Directory Server port number
Default Value 389
Required No
Multi-Valued No

-Z
--useSSL

Description Use SSL for secure communication with the server

-q
--useStartTLS

Description Use StartTLS to secure communication with the server

pre-external-initialization

This subcommand must be called once before replacing the data for one or more replicating base DNs. You must specify the list of base DNs that will have the data replaced and apply the subcommand to any of the servers taking part in replication of the base DNs. After calling this subcommand, replace the data on one server for the base DNs using import-ldif or restore. Then initialize all other servers in the topology with the initialize subcommand, followed finally by the 'post-external-initialization' subcommand


pre-external-initialization Examples

Performs pre-external initialization of base DN dc=example,dc=com: 
dsreplication pre-external-initialization --hostname host.example.com \
     --port 1389 --baseDN dc=example,dc=com --adminUID admin \
     --adminPassword secret

pre-external-initialization Arguments

-h {host}
--hostname {host}

Description Directory Server hostname or IP address
Default Value localhost
Required No
Multi-Valued No

-p {port}
--port {port}

Description Directory Server port number
Default Value 389
Required No
Multi-Valued No

-Z
--useSSL

Description Use SSL for secure communication with the server

-q
--useStartTLS

Description Use StartTLS to secure communication with the server

remove-defunct-server

This subcommand is no longer supported. Use the remove-defunct-server standalone tool to remove it from the replication topology. If this server can reach other servers in the topology, then running remove-defunct-server from it will cleanly remove it from the topology. If it cannot reach the other servers though, then remove-defunct-server must also be run from one of the online servers

status

Display the basic replication configuration information for the base DNs of the servers defined in the registration information. If no base DNs are specified as parameters, the information for all base DNs is displayed


status Examples

Display the replication status of all replicated base DNs in non-interactive mode using the Directory Server listening on port 1389 of host.example.com: 
dsreplication status --hostname host.example.com --port 1389 --adminUID admin \
     --adminPassword secret --no-prompt


Display the replication status of the base DN dc=example,dc=com in the Austin location: 
dsreplication status --baseDN dc=example,dc=com --location Austin


Display the status of both Replicas and Replication Servers with all available information: 
dsreplication status --displayServerTable --showAll

status Arguments

-h {host}
--hostname {host}

Description Directory Server hostname or IP address
Default Value localhost
Required No
Multi-Valued No

-p {port}
--port {port}

Description Directory Server port number
Default Value 389
Required No
Multi-Valued No

-Z
--useSSL

Description Use SSL for secure communication with the server

-q
--useStartTLS

Description Use StartTLS to secure communication with the server

-r {setName}
--setName {setName}

Description Display status for the provided replication set names only
Required No
Multi-Valued Yes

-l {location}
--location {location}

Description Display status for the provided locations only
Required No
Multi-Valued Yes

-S
--displayServerTable

Description Include the Replication Server status table in the output

-a
--showAll

Description Include all optional columns in the output

Arguments

-V
--version

Description Display Directory Server version information

-H
--help

Description Display general usage information

--help-debug

Description Display help for using debug options
Advanced Yes

--help-subcommands

Description Display all subcommands

--useNoSecurity

Description Use no security when communicating with the server

-o {name=value}
--saslOption {name=value}

Description SASL bind options
Required No
Multi-Valued Yes

-X
--trustAll

Description Trust all server SSL certificates

-P {truststorePath}
--trustStorePath {truststorePath}

Description Certificate truststore path
Default Value /home/centos/workspace/Core-Release/build/package/PingDirectory/config/truststore
Required No
Multi-Valued No

-T {truststorePassword}
--trustStorePassword {truststorePassword}

Description Certificate truststore PIN
Required No
Multi-Valued No

-U {path}
--trustStorePasswordFile {path}

Description Certificate truststore PIN file
Required No
Multi-Valued No

-K {keystorePath}
--keyStorePath {keystorePath}

Description Certificate keystore path
Required No
Multi-Valued No

-W {keystorePassword}
--keyStorePassword {keystorePassword}

Description Certificate keystore PIN
Required No
Multi-Valued No

-u {keystorePasswordFile}
--keyStorePasswordFile {keystorePasswordFile}

Description Certificate keystore PIN file
Required No
Multi-Valued No

-N {nickname}
--certNickname {nickname}

Description Nickname of the certificate for SSL client authentication
Required No
Multi-Valued No

--propertiesFilePath {propertiesFilePath}

Description Path to the file that contains default property values used for command-line arguments
Required No
Multi-Valued No

--noPropertiesFile

Description Specify that no properties file will be used to get default command-line argument values

--script-friendly

Description Use script-friendly mode

-b {baseDN}
--baseDN {baseDN}

Description Base DN of the data to be replicated, initialized, or have replication disabled
Required No
Multi-Valued Yes

-I {adminUID}
--adminUID {adminUID}

Description User ID of the topology-wide administrator used to bind to the server. For the 'enable' subcommand, if no topology-wide administrator was defined previously on any of the servers, the topology-wide administrator will be created using the provided data.
Default Value admin
Required No
Multi-Valued No

-w {bindPassword}
--adminPassword {bindPassword}

Description The topology-wide administrator password
Required No
Multi-Valued No

-j {bindPasswordFile}
--adminPasswordFile {bindPasswordFile}

Description The file containing the password of the topology-wide administrator
Required No
Multi-Valued No

-n
--no-prompt

Description Use non-interactive mode. If data in the command is missing, you will not be prompted and the tool will fail

-Q
--quiet

Description Perform a quiet operation (no progress information is written to the standard output)

--ignoreWarnings

Description Tool should continue should warnings occur when used non-interactively. This option should be used with caution

--ignoreLock

Description Tool should continue even if the replication topology has been locked by another tool invocation. This option should be used with caution

--retryTimeoutSeconds {retryTimeoutSeconds}

Description If the command fails, then it will continue to be retried up to this timeout specified in seconds. The command will not be aborted if the timeout has expired mid-execution, so it will be executed at least once. A value of zero (which is the default if this argument is not provided) indicates that the command does not have a timeout and so will not be retried upon initial failure. Note that this option is especially helpful in automated deployments where internal retries may significantly improve the chance of the command succeeding
Lower Bound 0
Upper Bound 86400
Default Value 0
Required No
Multi-Valued No