PingDS 7.5.1

dsrepl

dsrepl — Manages data synchronization between servers

Synopsis

dsrepl {subcommand} {options}

Description

This tool manages data synchronization between servers. For replication to work you must initialize the contents of one of the servers with the contents of the others using the 'initialize' subcommand.

Options

The dsrepl command takes the following options:

Utility input/output options:

-n | --no-prompt

Use non-interactive mode. If data in the command is missing, the user is not prompted and the tool will fail. Default: false

--noPropertiesFile

No properties file will be used to get default command line argument values. Default: false

--propertiesFilePath {propertiesFilePath}

Path to the file containing default property values used for command line arguments.

General options:

-V | --version

Display Directory Server version information. Default: false

-H | --help

Display this usage information. Default: false

Subcommands

The dsrepl command supports the following subcommands:

dsrepl add-local-server-to-pre-7-0-topology

dsrepl add-local-server-to-pre-7-0-topology {options}

Adds the local server (with version 7.0 or more) to a topology with older server versions (prior to 7.0).

Options

In addition to the global dsrepl options, the dsrepl add-local-server-to-pre-7-0-topology subcommand takes the following options:

SubCommand Options:

-b | --baseDn {baseDN}

Base DN(s) to replicate.

--providerArg {argument}

Configuration argument for the PKCS#11 provider.

--providerClass {class}

Full class name of the PKCS#11 provider.

--providerName {name}

Name of the PKCS#11 provider.

LDAP connection options:

--connectTimeout {timeout}

Maximum length of time (in milliseconds) that can be taken to establish a connection. Use '0' to specify no time out. Default: 30000

-D | --bindDn {bindDN}

DN to use to bind to the server. Default: cn=admin,cn=Administrators,cn=admin data

-E | --reportAuthzId

Use the authorization identity control. Default: false

-h | --hostname {host}

Fully-qualified server host name or IP address. Default: localhost.localdomain

-N | --certNickname {nickname}

Nickname of the certificate that should be sent to the server for SSL client authentication.

-o | --saslOption {name=value}

SASL bind options.

-p | --port {port}

Directory server administration port number.

-T | --trustStorePassword[:env|:file] {trustStorePassword}

Truststore password which will be used as the cleartext configuration value.

--useJavaKeyStore {keyStorePath}

JKS keystore containing the certificate which should be used for SSL client authentication.

--useJavaTrustStore {trustStorePath}

Use a JKS truststore file for validating server certificate.

--useJceKeyStore {keyStorePath}

JCEKS keystore containing the certificate which should be used for SSL client authentication.

--useJceTrustStore {trustStorePath}

Use a JCEKS truststore file for validating server certificate.

--useJvmTrustStore

Use the JVM truststore for validating server certificate. Default: false

--usePasswordPolicyControl

Use the password policy request control. Default: false

--usePkcs11KeyStore

PKCS#11 keystore containing the certificate which should be used for SSL client authentication. Default: false

--usePkcs12KeyStore {keyStorePath}

PKCS#12 keystore containing the certificate which should be used for SSL client authentication.

--usePkcs12TrustStore {trustStorePath}

Use a PKCS#12 truststore file for validating server certificate.

-w | --bindPassword[:env|:file] {bindPassword}

Password to use to bind to the server. Omit this option while providing the bind DN to ensure that the command prompts for the password, rather than entering the password as a command argument.

-W | --keyStorePassword[:env|:file] {keyStorePassword}

Keystore password which will be used as the cleartext configuration value.

-X | --trustAll

Trust all server SSL certificates. Default: false

dsrepl cleanup-migrated-pre-7-0-topology

dsrepl cleanup-migrated-pre-7-0-topology {options}

Clean all the servers (with version 7.0 or more) that have been migrated from a topology of older servers (version prior to 7.0).

Options

In addition to the global dsrepl options, the dsrepl cleanup-migrated-pre-7-0-topology subcommand takes the following options:

SubCommand Options:

--bootstrapServer {serverSource}

Server ID of the server containing the source data.

--providerArg {argument}

Configuration argument for the PKCS#11 provider.

--providerClass {class}

Full class name of the PKCS#11 provider.

--providerName {name}

Name of the PKCS#11 provider.

LDAP connection options:

--connectTimeout {timeout}

Maximum length of time (in milliseconds) that can be taken to establish a connection. Use '0' to specify no time out. Default: 30000

-D | --bindDn {bindDN}

DN to use to bind to the server. Default: uid=admin

-E | --reportAuthzId

Use the authorization identity control. Default: false

-h | --hostname {host}

Fully-qualified server host name or IP address. Default: localhost.localdomain

-N | --certNickname {nickname}

Nickname of the certificate that should be sent to the server for SSL client authentication.

-o | --saslOption {name=value}

SASL bind options.

-p | --port {port}

Directory server administration port number.

-T | --trustStorePassword[:env|:file] {trustStorePassword}

Truststore password which will be used as the cleartext configuration value.

--useJavaKeyStore {keyStorePath}

JKS keystore containing the certificate which should be used for SSL client authentication.

--useJavaTrustStore {trustStorePath}

Use a JKS truststore file for validating server certificate.

--useJceKeyStore {keyStorePath}

JCEKS keystore containing the certificate which should be used for SSL client authentication.

--useJceTrustStore {trustStorePath}

Use a JCEKS truststore file for validating server certificate.

--useJvmTrustStore

Use the JVM truststore for validating server certificate. Default: false

--usePasswordPolicyControl

Use the password policy request control. Default: false

--usePkcs11KeyStore

PKCS#11 keystore containing the certificate which should be used for SSL client authentication. Default: false

--usePkcs12KeyStore {keyStorePath}

PKCS#12 keystore containing the certificate which should be used for SSL client authentication.

--usePkcs12TrustStore {trustStorePath}

Use a PKCS#12 truststore file for validating server certificate.

-w | --bindPassword[:env|:file] {bindPassword}

Password to use to bind to the server. Omit this option while providing the bind DN to ensure that the command prompts for the password, rather than entering the password as a command argument.

-W | --keyStorePassword[:env|:file] {keyStorePassword}

Keystore password which will be used as the cleartext configuration value.

-X | --trustAll

Trust all server SSL certificates. Default: false

dsrepl clear-changelog

dsrepl clear-changelog

Clears all replication server changelog data for the offline local server; the other replication servers in the topology will transfer any needed data when the server restarts.

dsrepl decode-csn

dsrepl decode-csn csn [csn …​]

Decodes one or more CSNs and displays them in a human readable JSON format.

dsrepl disaster-recovery

dsrepl disaster-recovery {options}

Performs disaster recovery on the local server. The subcommand has two forms.

The first form verifies each replica has the same data after recovery: on a replica, run

dsrepl disaster-recovery --baseDn dc=example,dc=com --generate-recovery-id

The command prints the identifier to use on all other servers with the --generated-id option:

dsrepl disaster-recovery --baseDn dc=example,dc=com --generated-id {identifier}

The second form uses an identifier you provide. It lets you automate the recovery process when you cannot use the first form. Do not use this form if the topology has standalone replication servers. With this form of the subcommand, you must ensure you recover each replica with the same data. Run the same subcommand on all servers.

Example:

dsrepl disaster-recovery --baseDn dc=example,dc=com --user-generated-id Recovery_Date_20240101

Read the documentation on disaster recovery carefully before using this command.

Options

In addition to the global dsrepl options, the dsrepl disaster-recovery subcommand takes the following options:

-b | --baseDn {baseDN}

Base DN of the domain to be recovered.

--generate-recovery-id

Generate a disaster recovery identifier during recovery. Use this for the first directory server in a replication topology with standalone RS servers. For all subsequent servers to recover, omit this option and use --generated-id {generatedRecoveryId} with the generated identifier. Default: false

--generated-id {generatedRecoveryId}

Use the disaster recovery identifier generated on the first server. You must use the same identifier for all servers involved in the same disaster recovery procedure.

--user-generated-id {userGeneratedRecoveryId}

Set the identifier for this recovery to {userGeneratedRecoveryId}, a string of your choice. Do not use this option if the replication topology has standalone RS servers. You must use the same identifier for all servers involved in the same disaster recovery procedure.

dsrepl initialize

dsrepl initialize {options}

Initialize replication data for the server.

Options

In addition to the global dsrepl options, the dsrepl initialize subcommand takes the following options:

SubCommand Options:

-b | --baseDn {baseDN}

Base DN(s) to use. Multiple base DNs can be provided by using this option multiple times.

--fromServer {serverSource}

Server ID of the server containing the source data.

--providerArg {argument}

Configuration argument for the PKCS#11 provider.

--providerClass {class}

Full class name of the PKCS#11 provider.

--providerName {name}

Name of the PKCS#11 provider.

--toAllServers

Initialize all the other servers in the topology. Default: false

--toServer {serverToInitialize}

Server ID of the server to be initialized.

LDAP connection options:

--connectTimeout {timeout}

Maximum length of time (in milliseconds) that can be taken to establish a connection. Use '0' to specify no time out. Default: 30000

-D | --bindDn {bindDN}

DN to use to bind to the server. Default: uid=admin

-E | --reportAuthzId

Use the authorization identity control. Default: false

-h | --hostname {host}

Fully-qualified server host name or IP address. Default: localhost.localdomain

-N | --certNickname {nickname}

Nickname of the certificate that should be sent to the server for SSL client authentication.

-o | --saslOption {name=value}

SASL bind options.

-p | --port {port}

Directory server administration port number.

-T | --trustStorePassword[:env|:file] {trustStorePassword}

Truststore password which will be used as the cleartext configuration value.

--useJavaKeyStore {keyStorePath}

JKS keystore containing the certificate which should be used for SSL client authentication.

--useJavaTrustStore {trustStorePath}

Use a JKS truststore file for validating server certificate.

--useJceKeyStore {keyStorePath}

JCEKS keystore containing the certificate which should be used for SSL client authentication.

--useJceTrustStore {trustStorePath}

Use a JCEKS truststore file for validating server certificate.

--useJvmTrustStore

Use the JVM truststore for validating server certificate. Default: false

--usePasswordPolicyControl

Use the password policy request control. Default: false

--usePkcs11KeyStore

PKCS#11 keystore containing the certificate which should be used for SSL client authentication. Default: false

--usePkcs12KeyStore {keyStorePath}

PKCS#12 keystore containing the certificate which should be used for SSL client authentication.

--usePkcs12TrustStore {trustStorePath}

Use a PKCS#12 truststore file for validating server certificate.

-w | --bindPassword[:env|:file] {bindPassword}

Password to use to bind to the server. Omit this option while providing the bind DN to ensure that the command prompts for the password, rather than entering the password as a command argument.

-W | --keyStorePassword[:env|:file] {keyStorePassword}

Keystore password which will be used as the cleartext configuration value.

-X | --trustAll

Trust all server SSL certificates. Default: false

dsrepl purge-meta-data

dsrepl purge-meta-data {options}

Purges old replication meta-data from application data.

Options

In addition to the global dsrepl options, the dsrepl purge-meta-data subcommand takes the following options:

SubCommand Options:

-b | --baseDn {baseDN}

Base DN(s) to use. Multiple base DNs can be provided by using this option multiple times.

--completionNotify {emailAddress}

Email address of a recipient to be notified when the task completes. This option may be specified more than once.

--dependency {taskID}

ID of a task upon which this task depends. A task will not start execution until all its dependencies have completed execution.

--description {description}

Gives a description to the task.

--errorNotify {emailAddress}

Email address of a recipient to be notified if an error occurs when this task executes. This option may be specified more than once.

--failedDependencyAction {action}

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.

--maximumDuration {maximum duration in seconds}

Maximum duration of the command in seconds. Default: 3600

--providerArg {argument}

Configuration argument for the PKCS#11 provider.

--providerClass {class}

Full class name of the PKCS#11 provider.

--providerName {name}

Name of the PKCS#11 provider.

--recurringTask {schedulePattern}

Indicates the task is recurring and will be scheduled according to the value argument expressed in crontab(5) compatible time/date pattern. The schedule pattern for a recurring task supports only the following crontab features:

Field Allowed Values

minute

0-59

hour

0-23

day of month

1-31

month

1-12 (or names)

day of week

0-7 (0 or 7 is Sunday, or use names)

A field can contain an asterisk, * . An asterisk stands for first-last .

Fields can include ranges of numbers. A range is two numbers separated by a hyphen, and is inclusive. For example, 8-10 for an "hour" field means execution at hours 8, 9, and 10.

Fields can include lists. A list is a set of numbers or ranges separated by commas. For example, 4,8-10 for an "hour" field means execution at hours 4, 8, 9, and 10.

When using names for in "month" or "day of week" fields, use the first three letters of the particular month or day of the week. Case does not matter. Ranges and lists of names are not supported.

-t | --start {startTime}

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 '0' 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.

--taskId {taskID}

Gives an ID to the task.

LDAP connection options:

--connectTimeout {timeout}

Maximum length of time (in milliseconds) that can be taken to establish a connection. Use '0' to specify no time out. Default: 30000

-D | --bindDn {bindDN}

DN to use to bind to the server. Default: uid=admin

-E | --reportAuthzId

Use the authorization identity control. Default: false

-h | --hostname {host}

Fully-qualified server host name or IP address. Default: localhost.localdomain

-N | --certNickname {nickname}

Nickname of the certificate that should be sent to the server for SSL client authentication.

-o | --saslOption {name=value}

SASL bind options.

-p | --port {port}

Directory server administration port number.

-T | --trustStorePassword[:env|:file] {trustStorePassword}

Truststore password which will be used as the cleartext configuration value.

--useJavaKeyStore {keyStorePath}

JKS keystore containing the certificate which should be used for SSL client authentication.

--useJavaTrustStore {trustStorePath}

Use a JKS truststore file for validating server certificate.

--useJceKeyStore {keyStorePath}

JCEKS keystore containing the certificate which should be used for SSL client authentication.

--useJceTrustStore {trustStorePath}

Use a JCEKS truststore file for validating server certificate.

--useJvmTrustStore

Use the JVM truststore for validating server certificate. Default: false

--usePasswordPolicyControl

Use the password policy request control. Default: false

--usePkcs11KeyStore

PKCS#11 keystore containing the certificate which should be used for SSL client authentication. Default: false

--usePkcs12KeyStore {keyStorePath}

PKCS#12 keystore containing the certificate which should be used for SSL client authentication.

--usePkcs12TrustStore {trustStorePath}

Use a PKCS#12 truststore file for validating server certificate.

-w | --bindPassword[:env|:file] {bindPassword}

Password to use to bind to the server. Omit this option while providing the bind DN to ensure that the command prompts for the password, rather than entering the password as a command argument.

-W | --keyStorePassword[:env|:file] {keyStorePassword}

Keystore password which will be used as the cleartext configuration value.

-X | --trustAll

Trust all server SSL certificates. Default: false

dsrepl reset-change-number

dsrepl reset-change-number {options}

Re-synchronizes the change-log change number of the target server with the change-log change number of the source server.

Options

In addition to the global dsrepl options, the dsrepl reset-change-number subcommand takes the following options:

SubCommand Options:

--change-number {change number}

The change number to use as the basis for re-synchronization.

--providerArg {argument}

Configuration argument for the PKCS#11 provider.

--providerClass {class}

Full class name of the PKCS#11 provider.

--providerName {name}

Name of the PKCS#11 provider.

--sourceBindDn {bindDN}

DN to use to bind to the server. Default: uid=admin

--sourceBindPassword[:env|:file] {bindPassword}

Password to use to bind to the server. Omit this option while providing the bind DN to ensure that the command prompts for the password, rather than entering the password as a command argument.

--sourceHostname {host}

Directory server hostname or IP address. Default: localhost.localdomain

--sourcePort {port}

Directory server administration port number.

--targetBindDn {bindDN}

DN to use to bind to the server. Default: uid=admin

--targetBindPassword[:env|:file] {bindPassword}

Password to use to bind to the server. Omit this option while providing the bind DN to ensure that the command prompts for the password, rather than entering the password as a command argument.

--targetHostname {host}

Directory server hostname or IP address. Default: localhost.localdomain

--targetPort {port}

Directory server administration port number.

LDAP connection options:

--connectTimeout {timeout}

Maximum length of time (in milliseconds) that can be taken to establish a connection. Use '0' to specify no time out. Default: 30000

-E | --reportAuthzId

Use the authorization identity control. Default: false

-N | --certNickname {nickname}

Nickname of the certificate that should be sent to the server for SSL client authentication.

-o | --saslOption {name=value}

SASL bind options.

-T | --trustStorePassword[:env|:file] {trustStorePassword}

Truststore password which will be used as the cleartext configuration value.

--useJavaKeyStore {keyStorePath}

JKS keystore containing the certificate which should be used for SSL client authentication.

--useJavaTrustStore {trustStorePath}

Use a JKS truststore file for validating server certificate.

--useJceKeyStore {keyStorePath}

JCEKS keystore containing the certificate which should be used for SSL client authentication.

--useJceTrustStore {trustStorePath}

Use a JCEKS truststore file for validating server certificate.

--useJvmTrustStore

Use the JVM truststore for validating server certificate. Default: false

--usePasswordPolicyControl

Use the password policy request control. Default: false

--usePkcs11KeyStore

PKCS#11 keystore containing the certificate which should be used for SSL client authentication. Default: false

--usePkcs12KeyStore {keyStorePath}

PKCS#12 keystore containing the certificate which should be used for SSL client authentication.

--usePkcs12TrustStore {trustStorePath}

Use a PKCS#12 truststore file for validating server certificate.

-W | --keyStorePassword[:env|:file] {keyStorePassword}

Keystore password which will be used as the cleartext configuration value.

-X | --trustAll

Trust all server SSL certificates. Default: false

dsrepl status

dsrepl status {options}

Displays the status of the replication service and various diagnostics about it. The information is derived from reading cn=monitor on all the servers in the replication topology.

The status of a server is one of the following.

  • BAD - DATA MISMATCH: either the fractional replication configuration does not match the backend data, or the initial state of the replicated data does not match other servers and this server must be re-initialized;

  • BAD - TOO LATE: the server has fallen further behind than the replication purge delay and must be re-initialized;

  • GOOD: normal operation, nothing to do;

  • SLOW: the server’s replay delay is greater than five seconds;

  • UNHEALTHY: read the server health errors in the server monitoring data for details.

Options

In addition to the global dsrepl options, the dsrepl status subcommand takes the following options:

SubCommand Options:

-b | --baseDn {baseDN}

Base DN(s) to display. Multiple base DNs can be provided by using this option multiple times. If no base DNs are provided, then all the base DNs will be displayed.

--providerArg {argument}

Configuration argument for the PKCS#11 provider.

--providerClass {class}

Full class name of the PKCS#11 provider.

--providerName {name}

Name of the PKCS#11 provider.

--showChangelogs

Displays individual changelog servers in the output. Default: false

--showGroups

Display replication group information in the output. Default: false

--showReplicas

Displays individual replicas in the output. Default: false

LDAP connection options:

--connectTimeout {timeout}

Maximum length of time (in milliseconds) that can be taken to establish a connection. Use '0' to specify no time out. Default: 30000

-D | --bindDn {bindDN}

DN to use to bind to the server. Default: uid=monitor

-E | --reportAuthzId

Use the authorization identity control. Default: false

-h | --hostname {host}

Fully-qualified server host name or IP address. Default: localhost.localdomain

-N | --certNickname {nickname}

Nickname of the certificate that should be sent to the server for SSL client authentication.

-o | --saslOption {name=value}

SASL bind options.

-p | --port {port}

Directory server administration port number.

-T | --trustStorePassword[:env|:file] {trustStorePassword}

Truststore password which will be used as the cleartext configuration value.

--useJavaKeyStore {keyStorePath}

JKS keystore containing the certificate which should be used for SSL client authentication.

--useJavaTrustStore {trustStorePath}

Use a JKS truststore file for validating server certificate.

--useJceKeyStore {keyStorePath}

JCEKS keystore containing the certificate which should be used for SSL client authentication.

--useJceTrustStore {trustStorePath}

Use a JCEKS truststore file for validating server certificate.

--useJvmTrustStore

Use the JVM truststore for validating server certificate. Default: false

--usePasswordPolicyControl

Use the password policy request control. Default: false

--usePkcs11KeyStore

PKCS#11 keystore containing the certificate which should be used for SSL client authentication. Default: false

--usePkcs12KeyStore {keyStorePath}

PKCS#12 keystore containing the certificate which should be used for SSL client authentication.

--usePkcs12TrustStore {trustStorePath}

Use a PKCS#12 truststore file for validating server certificate.

-w | --bindPassword[:env|:file] {bindPassword}

Password to use to bind to the server. Omit this option while providing the bind DN to ensure that the command prompts for the password, rather than entering the password as a command argument.

-W | --keyStorePassword[:env|:file] {keyStorePassword}

Keystore password which will be used as the cleartext configuration value.

-X | --trustAll

Trust all server SSL certificates. Default: false

Exit codes

0

The command completed successfully.

> 0

An error occurred.