JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Oracle Fusion Middleware Command-Line Usage Guide for Oracle Unified Directory 11g Release 1 (11.1.1)
search filter icon
search icon

Document Information

Preface

1.  Server Administration Commands

create-rc-script

Synopsis

Description

Options

General Options

Examples

Code Generated by the create-rc-script Command

Exit Codes

Location

Related Commands

dsconfig

Synopsis

Description

Help Subcommands

General Subcommands

Core Server Subcommands

Database Subcommands

Logging Subcommands

Replication Subcommands

Security Subcommands

User Management Subcommands

Options

LDAP Connection Options

Command Input/Output Options

General Options

Examples

Exit Codes

Using a Properties File

Location

Related Commands

dsreplication

Synopsis

Description

Server Subcommands

Options

Configuration Options

LDAP Connection Options

Command Input/Output Options

General Options

Examples

Exit Codes

Using a Properties File

Location

Related Commands

ds2oud

Synopsis

Description

Options

Oracle Directory Server Enterprise Edition LDAP Connection Options

Oracle Unified Directory LDAP Connection Options

Command Input/Output Options

General Options

Examples

Exit Codes

Location

Related Commands

dps2oud

Synopsis

Description

Options

LDAP Connection Options

General Options

Examples

Exit Codes

Location

Related Commands

gicadm

Synopsis

Description

Options

LDAP Connection Options

Command Input/Output Options

General Options

Examples

Exit Codes

Location

Related Commands

manage-tasks

Synopsis

Description

Options

LDAP Connection Options

Command Input/Output Options

General Options

Examples

Exit Codes

Using a Properties File

Location

Related Commands

oud-replication-gateway-setup

Synopsis

Description

Options

Replication Gateway Configuration Options

Oracle Directory Server Enterprise Edition Server Options

Replication Gateway Security Options

Oracle Unified Directory Server Options

Secure Connection Options

Command Input/Output Options

General Options

Examples

Exit Codes

Using a Properties File

Log Files

Location

Related Commands

oud-setup

Synopsis

Description

Options

Command Input/Output Options

General Options

Examples

Exit Codes

Using a Properties File

Log Files

Location

Related Commands

oud-proxy-setup

Synopsis

Description

Options

Command Input/Output Options

General Options

Examples

Exit Codes

Log Files

Location

Related Commands

start-ds

Synopsis

Description

Options

Command Input/Output Options

General Options

Examples

Exit Codes

Location

Related Commands

status

Synopsis

Description

LDAP Connection Options

Command Input/Output Options

General Options

Examples

Exit Codes

Using a Properties File

Location

stop-ds

Synopsis

Description

Options

LDAP Connection Options

Command Input/Output Options

General Options

Examples

Exit Codes

Using a Properties File

Location

Related Commands

uninstall

Synopsis

Description

Removing a Directory Server

Options

LDAP Connection Options

Removing a Proxy Server

Options

LDAP Connection Options

Removing a Replication Gateway Server

Options

Gateway Connection Options

Oracle Unified Directory Server Connection Options

Oracle Directory Server Enterprise Edition Server Connection Options

Secure Connection Options

Command Input/Output Options

General Options

Examples

Exit Codes

Using a Properties File

Log Files

Location

Related Commands

windows-service

Synopsis

Description

Command Options

General Options

Examples

Exit Codes

Location

Related Commands

2.  Data Administration Commands

3.  LDAP Client Commands

4.  Other Commands

5.  General Command-Line Usage Information

dsreplication

The dsreplication command configures replication between directory servers so that the data of the servers is synchronized.

This command is not supported for the proxy.

Synopsis

dsreplication [subcommands] [options]

Description

The dsreplication command can be used to configure replication between directory servers so that the data of the servers is synchronized. First enable replication by using the enable subcommand and then initialize the contents of one directory server with the contents of another server by using the initialize subcommand.

The dsreplication command contacts the server over SSL using the administration connector (see Managing Administration Traffic to the Server in Oracle Fusion Middleware Administration Guide for Oracle Unified Directory).

Like the dsconfig command, dsreplication can be run in interactive mode, which walks you through the replication setup process. To run dsreplication in interactive mode, type the command name with no parameters, as shown in the following example:

$ dsreplication
What do you want to do?

1)  Enable Replication
2)  Disable Replication
3)  Initialize Replication on one Server
4)  Initialize All Servers
5)  Pre External Initialization
6)  Post External Initialization
7)  Display Replication Status
8)  Purge Historical
9)  Set the trust flag of the Directory Server

c)  cancel

Enter choice: 1
...

To display the equivalent non-interactive command, use the --displayCommand or --commandFilePath option.

Server Subcommands

The following subcommands are used with the dsreplication command.

disable

Disable replication on the specified directory server for the specified base DN. This subcommand removes references to the specified server in the configuration of the servers with which this server is replicating data. Suboptions are as follows:

-D, --bindDN bindDN. The DN used to bind to the server on which replication will be disabled. This option must be used if no global administrator has been defined on the server or if you do not want to remove references in the other replicated servers. The password provided for the global administrator is used when this option is specified.

-a, --disableAll. Disable the replication configuration on the specified server. The contents of the server are no longer replicated and the replication server (change log and replication port) is disabled, if it is configured.

--disableReplicationServer. Disable the replication server. The replication port and change log are disabled on the specified server.

-h, --hostname host. Directory server host name or IP address.

-p, --port port. Directory server administration port number.

enable

Update the configuration of the directory servers to replicate data under the specified base DN. If one of the specified servers is already replicating the data under the base DN to other servers, executing this subcommand updates the configuration of all the servers. It is therefore sufficient to execute the subcommand once for each server that is added to the replication topology. Suboptions are as follows:

--bindDN2 bindDN. The DN used to bind to the second server whose contents will be replicated. If no bind DN is specified, the global administrator is used to bind.

--bindPassword1 bindPassword. The password used 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 is used to bind.

--bindPassword2 password. The password used 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 is used to bind.

--bindPasswordFile1 filename. The file containing the password used 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 is used to bind.

-D, --bindDN1 bindDN. The DN used to bind to the first server whose contents will be replicated. If no bind DN is specified, the global administrator is used to bind.

-F, --bindPasswordFile2 filename. The file containing the password used 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 is used to bind.

-h, --host1 host. Host name or IP address of the first server whose contents will be replicated.

--noReplicationServer1. 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.

--noReplicationServer2. 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.

--noSchemaReplication. Do not replicate the schema between the servers. Note that schema replication is enabled by default. Use this option if you do not want the schema to be synchronized between servers.

--onlyReplicationServer1. 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.

--onlyReplicationServer2. 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.

-O, --host2 host. Hostname or IP address of the second server whose contents will be replicated.

-p, --port1 port. Directory server administration port number of the first server whose contents will be replicated.

--port2 port. Directory server administration port number of the second server whose contents will be replicated.

-r, --replicationPort1 port. The port that will be used by the replication mechanism in the first directory server to communicate with other servers. Only specify this option if replication was not previously configured on the first directory server.

-R, --replicationPort2 port. The port that will be used by the replication mechanism in the second directory server to communicate with other servers. Only specify this option if replication was not previously configured in the second server.

-S, --skipPortCheck. Skip the check to determine whether the specified replication ports are usable. If this argument is not specified, the server checks that the port is available only if you are configuring the local host.

--secureReplication1. Specifies whether communication through the replication port of the first server is encrypted. This option is only taken into account the first time replication is configured on the first server.

--secureReplication2. Specifies whether communication through the replication port of the second server is encrypted. This option is only taken into account the first time replication is configured on the second server.

--useSecondServerAsSchemaSource. Use the second server to initialize the schema of the first server. If neither this option nor the --noSchemaReplication option is specified, the schema of the first server is used to initialize the schema of the second server.

initialize

Initialize the contents of the data under the specified base DN on the destination directory server with the contents on the source server. This operation is required after enabling replication. Suboptions are as follows:

-h, --hostSource host. Directory server host name or IP address of the source server whose contents will be used to initialize the destination server.

-O, --hostDestination host. Directory server hostname or IP address of the destination server whose contents will be initialized.

-p, --portSource port. Directory server administration port number of the source server whose contents will be used to initialize the destination server.

--portDestination port. Directory server administration port number of the destination server whose contents will be initialized.

initialize-all

Initialize the data under the specified base DN, on all the directory servers in the topology, with the data on the specified server. This operation is required after enabling replication for replication to work. Alternatively, you can use the initialize subcommand on each individual server in the topology. Suboptions are as follows:

-h, --hostname host. Directory server host name or IP address of the source server.

-p, --port port. Directory server administration port number of the source server.

post-external-initialization

Enable replication to work after the entire topology has been reinitialized by using import-ldif or binary copy. This subcommand must be called after you initialize the contents of all directory servers in a topology by using import-ldif or binary copy. If you do not run this subcommand, replication will no longer work after the initialization. Suboptions are as follows:

-h, --hostname host. Directory server host name or IP address.

-p, --port port. Directory server administration port number.

pre-external-initialization

Prepare a replication topology for initialization by using import-ldif or binary copy. This subcommand must be called before you initialize the contents of all directory servers in a topology by using import-ldif or binary copy. If you do not run this subcommand, replication will no longer work after the initialization. After running this subcommand, initialize the contents of all the servers in the topology, then run the subcommand post-external-initialization. Suboptions are as follows:

-h, --hostname host. Directory server host name or IP address.

-l, --local-only. Use this option when the contents of only the specified directory server will be initialized with an external method.

-p, --port port. Directory server administration port number.

purge-historical

Launches a purge processing of the historical information stored in the user entries by replication. Since this processing may take a while, you must specify the maximum duration for this processing. Suboptions are as follows:

-h, --hostname host. Directory server host name or IP address.

-p, --port port. Directory server administration port number.

--maximumDuration maximum duration. Specifies the maximum duration the purge processing must last expressed in seconds. The default value is 3600.

-t, --start startTime. Specifies the date and 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. Use 0 to schedule the task for immediate execution. When this option is specified the operation is scheduled to start at the specified time after which the utility exits immediately.

--recurringTask schedulePattern. Indicates the task is recurring and will be scheduled according to the value argument expressed in crontab(5) compatible time/date pattern.

--completionNotify emailAddress. Indicates the e-mail address of the recipient to be notified when the task completes. You can specify this option more than once.

--errorNotify emailAddress. Indicates the e-mail address of the recipient to be notified if an error occurs when this task executes. You can specify this option more than once.

--dependency taskID. Indicates the ID of a task upon which this task depends. A task will not start execution until all its dependent tasks have completed execution.

--failedDependencyAction action. Indicates the action that should take place if one if its dependent tasks fail. It must have one of the following values: PROCESS,CANCEL, or DISABLE. The default value is CANCEL.

set-trust

Set the trust flag of a Directory Server. Any change sent by an untrusted Directory Server will be discarded by the rest of the topology. Only trusted Directory Servers are allowed to send changes to be replayed by other Directory Servers. Suboptions are as follows:

-h, --trustedHost host. Specifies the fully qualified host name or IP address of the Directory Server that will perform the change.

-p, --trustedPort port. Specifies the Directory Server administration port number of the Directory Server that will perform the change.

-M, --modifiedHost host. Specifies the fully qualified host name or IP address of the Directory Server whose trust flag is modified.

-c, --modifiedPort port. Specifies the Directory Server administration port number of the Directory Server whose trust flag is modified.

-t, --trustValue trusted|untrusted. Specifies the new value of the trust flag for the Directory Server to be modified. It can be trusted or untrusted. The default value is trusted.

status

List the replication configuration for the specified base DNs of all directory servers defined in the registration information. If no base DNs are specified, the information for all base DNs is displayed. Suboptions are as follows:

-h, --hostname host. Directory server host name or IP address.

-p, --port port. Directory server administration port number.

-s, --script-friendly. Display the status in a format that can be parsed by a script.

The status subcommand can have the following values:

  • Normal: The connection to a replication server is established with the right data set. Replication is working. If assured mode is used, then acks signal from this directory server are sent.

  • Degraded: The connection to a replication server is established with the right data set. Replication is working in degraded mode as the directory server has a lot of changes to be replayed pending in the replication server queue. If assured mode is used, then acks signal from this directory server are not expected.

  • Full Update: The connection to a replication server is established and a new data set is received from this connection (online import), to initialize the local back end.

  • Bad Data Set: The connection to a replication server is established with a data set that is different from the rest of the topology. The replication is not working. Either the other directory servers of the topology should be initialized with a compatible data set, or this server should be initialized with another data set compatible with other servers'.

  • Not Connected: The directory server is not connected to any replication server.

Options

The dsreplication command accepts an option in either its short form (for example, -H) or its long form equivalent (for example, --help).

-b, --baseDN baseDN

Specify the base DN of the data to be replicated or initialized, or for which replication should be disabled. Multiple base DNs can be specified by using this option multiple times.

Configuration Options

--advanced

Use this option to access advanced settings when running this command in interactive mode.

LDAP Connection Options

-I, --adminUID adminUID

Specify the User ID of the global administrator to bind to the server. If no global administrator was defined previously for any of the servers, this option creates a global administrator by using the data provided.

-w, --adminPassword bindPassword

Use the global administrator password when authenticating to the directory server.

-j, --adminPasswordFile bindPasswordFile

Use the global administrator password in the specified file when authenticating to the directory server. This option must not be used in conjunction with --adminPassword.

-o, --saslOption name=value

Use the specified options for SASL authentication.

SASL is not supported for Oracle Unified Directory proxy.

-X, --trustAll

Trust any certificate that the server might present during SSL or StartTLS negotiation. This option can be used for convenience and testing purposes, but for security reasons a trust store should be used to determine whether the client should accept the server certificate.

-P, --trustStorePath trustStorePath

Use the client trust store certificate in the specified path. This option is not needed if --trustAll is used, although a trust store should be used when working in a production environment.

-T, --trustStorePassword trustStorePassword

Use the password needed to access the certificates in the client trust store. This option is only required if --trustStorePath is used and the specified trust store requires a password in order to access its contents (which most trust stores do not require). This option must not be used in conjunction with --trustStorePasswordFile.

-U, --TrustStorePasswordFile path

Use the password in the specified file to access the certificates in the client trust store. This option is only required if --trustStorePath is used and the specified trust store requires a password in order to access its contents (most trust stores do not require this). This option must not be used in conjunction with --trustStorePassword.

-K, --keyStorePath keyStorePath

Use the client keystore certificate in the specified path.

-W, --keyStorePassword keyStorePassword

Use the password needed to access the certificates in the client keystore. This option is only required if --keyStorePath is used. This option must not be used in conjunction with --keyStorePasswordFile.

-u, --keyStorePasswordFile keyStorePasswordFile

Use the password in the specified file to access the certificates in the client keystore. This option is only required if --keyStorePath is used. This option must not be used in conjunction with --keyStorePassword.

-N, --certNickname nickname

Use the specified certificate for authentication.

--connectTimeout timeout

Specifies the maximum length of time (in milliseconds) that can be taken to establish a connection. Use 0to specify no time out. The default value is 30000.

Command Input/Output Options

--commandFilePath path

Specify the full path to the file in which the equivalent non-interactive commands are written when the command is run in interactive mode.

--displayCommand

Display the equivalent non-interactive command in the standard output when the command is run in interactive mode.

-n, --no-prompt

Run in non-interactive mode. If some data in the command is missing, the user will not be prompted and the command will fail.

--noPropertiesFile

Indicate that the command will not use a properties file to get the default command-line options.

--propertiesFilePath propertiesFilePath

Specify the path to the properties file that contains the default command-line options.

-Q, --quiet

Run in quiet mode. No output will be generated unless a significant error occurs during the process.

General Options

-?, -H, --help

Display command-line usage information for the command and exit without making any attempt to stop or restart the server.

-V, --version

Display the version information for the server and exit rather than attempting to run this command.

Examples

The following examples assume that two directory servers are installed: host1 and host2. Both servers are configured with the default administration port (4444). The base DN dc=example,dc=com is populated with data on host1. The base DN exists on host2, but is empty. The examples configure replication between the two servers and initialize host2 with data.


Note - The easiest way to use dsreplication is in interactive mode, in which case you are prompted for all of the relevant arguments. However, to illustrate which arguments are configured, these examples do not use the interactive mode.


Example 1-11 Enabling Directory Server Replication

The following command enables replication for the base DN dc=example,dc=com on host1 and host2. The command runs in non-interactive mode (-n) and specifies that all server certificates should be accepted (-X).

$ dsreplication enable \
  --host1 host1 --port1 4444 --bindDN1 "cn=Directory Manager" \
  --bindPassword1 password --replicationPort1 8989 \
  --host2 host2 --port2 4444 --bindDN2 "cn=Directory Manager" \
  --bindPassword2 password  --replicationPort2 8989 \
  --adminUID admin --adminPassword password --baseDN "dc=example,dc=com" -X -n

Example 1-12 Initializing Directory Server Replication

To initialize one replica from another, use the initialize subcommand. The following command initializes the base DN dc=example,dc=com on host2 with the data contained on host1. The command runs in non-interactive mode (-n) and specifies that all server certificates should be accepted (-X).

$ dsreplication initialize --baseDN "dc=example,dc=com" \
  --adminUID admin --adminPassword password \
  --hostSource host1 --portSource 4444 \
  --hostDestination host2 --portDestination 4444 -X -n

To initialize an entire topology, use the initialize-all subcommand. This subcommand takes the details of the source directory server as options and initializes all other replicas for which replication has been enabled.

Example 1-13 Obtaining the Directory Server Replication Status

The following command obtains the replication status of the directory servers in the topology.

$ dsreplication status --hostname host1 \
--port 4444 --adminUID admin --adminPassword password -X -n 

dc=example,dc=com - Replication Enabled
=======================================
Server    :Entries:M.C.[1]:A.O.M.C.[2]:Port[3]:Encryption[4]:Trust[5]:U.C.[6]:Status[7]
----------:-------:-------:-----------:-------:-------------:--------:-------:-----------
host1:1444:200000 :0      :N/A        :1898   :Disabled     :Trusted :N/A    :Normal
host2:2444:200000 :0      :N/A        :2898   :Disabled     :Trusted :N/A    :Normal

[1] The number of changes that are still missing on this server (and that have been 
    applied to at least one of the other servers).
[2] Age of oldest missing change: the age (in seconds) of the oldest change that
    has not yet arrived on this server.
[3] The port used to communicate between the servers whose contents are being 
    replicated.
[4] Whether the replication communication through the replication port is encrypted 
    or not.
[5] Whether this directory server is trusted or not. Updates coming from an
    untrusted server are discarded and not propagated.
[6] The number of untrusted changes. These are changes generated on this server 
    while it is untrusted. Those changes are not propagated to the rest of the topology 
    but are effective on the untrusted server.
[7] The status of the replication domain on this directory server.

Example 1-14 Obtaining the Replication Status

The following command obtains the replication status of two directory servers and one replication server in the topology.

$ dsreplication status --hostname host1 \
--port 4444 --adminUID admin --adminPassword password -X -n 

dc=example,dc=com - Replication Disabled
========================================
Server           : Entries
--------------------------
host2:2444       : 1

dc=example,dc=com - Replication Enabled
=======================================
Server    :Entries:M.C.[1]:A.O.M.C.[2]:Port[3]:Encryption[4]:Trust[5]:U.C.[6]:Status[7]
----------:-------:-------:-----------:-------:-------------:--------:-------:----------
host2:2444:-- [9] :--     :--         :2898   :Disabled     :--      :--     :--    
host1:1444:200000 :0      :N/A        :-- [8] :--           :Trusted :N/A    :Normal
host3:3444:200000 :0      :N/A        :-- [8] :--           :Trusted :N/A    :Normal

[1] The number of changes that are still missing on this server (and that have been 
    applied to at least one of the other servers).
[2] Age of oldest missing change: the age (in seconds) of the oldest change that
    has not yet arrived on this server.
[3] The port used to communicate between the servers whose contents are being 
    replicated.
[4] Whether the replication communication through the replication port is encrypted 
    or not.
[5] Whether this directory server is trusted or not. Updates coming from an
    untrusted server are discarded and not propagated.
[6] The number of untrusted changes. These are changes generated on this server 
    while it is untrusted. Those changes are not propagated to the rest of the 
    topology but are effective on the untrusted server.
[7] The status of the replication domain on this directory server.
[8] Server not configured as a replication server (no replication changelog).
[9] Server does not contain replicated data for the suffix.

Example 1-15 Disabling Directory Server Replication

The following command disables replication for the base DN dc=example,dc=com on host2. Disabling replication on one directory server removes all references to that server from the other directory servers in the replication topology.

$ dsreplication disable --baseDN "dc=example,dc=com" \
  --hostname host2 --port 4444 --adminUID admin --adminPassword password -X -n
Establishing connections ..... Done.
Disabling replication on base DN cn=admin data of server host2:4444 ..... Done.
Disabling replication on base DN dc=example,dc=com of server host2:4444 ..... Done.
Disabling replication on base DN cn=schema of server host2:4444 ..... Done.
Removing references on base DN cn=admin data of server host1:4444 ..... Done.
Removing references on base DN dc=example,dc=com of server host1:4444 ..... Done.
Removing references on base DN cn=schema of server host1:4444 ..... Done.
Disabling replication port 8990 of server host2:4444 ..... Done.

Exit Codes

0

Successful.

1

Unable to initialize arguments.

2

Cannot parse arguments because the provided arguments are not valid or there was an error checking the user data.

3

The user canceled the operation in non-prompt mode.

4

Unexpected error.

5

The specified base DNs cannot be used to enable replication.

6

The specified base DNs cannot be used to disable replication.

7

The specified base DNs cannot be used to initialize the contents of the replicas.

8

Error connecting with the credentials provided.

9

Could not find the replication ID of the domain to be used to initialize the replica.

10

The maximum number of attempts to start the initialization has been exceeded. A systematic “peer not found error” was received.

11

Error enabling replication on base DN.

12

Error initializing base DN.

13

Error reading configuration.

14

Error updating ADS.

15

Error reading ADS.

16

Error reading Topology Cache.

17

Error configuring the replication server.

18

Unsupported ADS scenario.

19

Error disabling replication on base DN.

20

Error removing replication port reference on base DN.

21

Error initializing Administration Framework.

22

Error seeding trust store.

23

Error launching pre-external initialization.

24

Error launching post-external initialization.

25

Error disabling replication server.

26

Error executing purge historical.

27

Historical cannot be purged on base DN.

28

Error launching purge historical.

29

Error local purge historical class load.

30

Error local purge historical server start.

31

Error local purge historical timeout.

32

Error local purge historical executing.

33

Trusted host not found.

34

Modified host not found.

Using a Properties File

The directory server supports the use of a properties file that passes in any default option values used with the dsreplication command. The properties file is convenient when working in different configuration environments, especially in scripted or embedded applications. For more information, see Using a Properties File With Server Commands.

The following options can be stored in a properties file:

Entries in the properties file have the following format:

toolname.propertyname=propertyvalue

For example:

dsreplication.baseDN=dc=example,dc=com

Location

Related Commands

dsconfig