A Oracle Unified Directory Command Line Interface

Oracle Unified Directory includes a number of command-line utilities that are used to interact with the directory server and the proxy server. Utilities are also provided to prepare a server to be part of a multi-version topology using the replication gateway.

This appendix describes all of the commands that are provided with Oracle Unified Directory 11g Release 2 (11.1.2). Some of these commands are specific to a directory server instance and cannot be used to configure a proxy server. Similarly, a number of the commands are specific to the proxy and cannot be used to configure a directory server.

This appendix covers the following topics:

Section A.1, "General Command-Line Usage Information"
Section A.2, "Server Administration Commands"
Section A.3, "Data Administration Commands"
Section A.4, "LDAP Client Commands"

A.1 General Command-Line Usage Information

The following sections provide general information about command usage:

Section A.1.1, "Summary of Server Commands and Their Use"
Section A.1.2, "Using a Properties File With Server Commands"

A.1.1 Summary of Server Commands and Their Use

The tables in this section provide a summary of the server commands and how they can be used. The tables use the following legend:

Remote: The command can be launched on a remote server
Offline: The command can be launched when the server is stopped
Online: The command connects to a running server instance
Administration Port Only: The command must use the administration connector to access the server (on port 4444 by default)

Note:

Not all the commands listed in the following tables are supported for a proxy server instance.

Table A-1 Server Administration Commands

Command	Remote	Offline	Online	Administration Connector
create-rc-script
dsconfig	`X`		`X`	`X`
dsjavaproperties		`X`
dsreplication	`X`		`X`	`X`
gicadm	`X`		`X`	`X`
oudExtractMovePlan		`X`	`X`
oudCopyConfig		`X`	`X`
oudPasteConfig		`X`
start-ds		`X`
status	`X`	`X`	`X`	`X`
stop-ds	`X`		`X`	`X`
uninstall		`X`	`X`	`X`
upgrade		`X`
windows-service		`X`

Table A-2 Data Administration Commands

Command	Remote	Offline	Online	Administration Connector
backup	`X` *	`X`	`X`	`X`
base64		`X`
dbtest		`X`
encode-password		`X`
export-ldif	`X` *	`X`	`X`	`X`
import-ldif	`X` *	`X`	`X`	`X`
ldapcompare	`X`		`X`
ldapdelete	`X`		`X`
ldapmodify	`X`		`X`
ldappasswordmodify	`X`		`X`
ldapsearch	`X`		`X`
ldif-diff		`X`
ldifmodify		`X`
ldifsearch		`X`
list-backends		`X`
make-ldif		`X`
manage-account	`X`		`X`	`X`
manage-tasks	`X`		`X`	`X`
rebuild-index		`X`
restore	`X` *	`X`	`X`	`X`
split-ldif		`X`	`X`
verify-index		`X`

* The command can be launched remotely but the data files must be on the host on which the server is running.

A.1.2 Using a Properties File With Server Commands

Certain command-line utilities can use a common properties file to provide default values for options such as the following:

The host name and port number of the server
Whether to use SSL or StartTLS to communicate with the server
The bind DN to use when connecting to the server

The following utilities can use a properties file:

backup
dsconfig
dsreplication
export-ldif
gicadm
import-ldif
split-ldif
ldapcompare
ldapdelete
ldapmodify
ldappasswordmodify
ldapsearch
manage-tasks
oud-setup
oud-proxy-setup
oud-replication-gateway-setup
restore
status
stop-ds
uninstall

The following mutually exclusive options are used with the command-line utilities to indicate whether a properties files is used:

--propertiesFilePath path: Specify the path to the file that contains default values for command-line options.
--noPropertiesFile: Indicates that the properties file is not used to obtain default values for command-line options.

A.1.2.1 Locating the Properties File

Utilities that use the common properties file have the following default behavior:

If the --noPropertiesFile option is specified, the command-line interface does not try to locate a properties file. Only options specified on the command line are evaluated.
If the --propertiesFilePath option is specified, property values are read from this file.
If neither --propertiesFilePath nor --noPropertiesFile is specified, the command-line interface attempts to find a properties file in the following locations:
- USERDIRECTORY/.opends/tools.properties
- INSTANCE_DIR/OUD/config/tools.properties
If no properties file is found in either of these locations, the default behavior is applied (only arguments specified on the command line are evaluated).

A.1.2.2 Order of Precedence of Options and Properties

If an option is provided on the command line, this option and its corresponding value are used by the command-line interface. In other words, options specified on the command line take precedence over the properties defined in the properties file.

The properties file has the standard JAVA properties file format (property-name=value). As such, the file supports variations on property names to enable them to be overridden according to the command that uses them. For example, the properties file might contain the following:

hostname=localhost
port=4444
bindDN=cn=Directory Manager
bindPasswordFile=/path/pwd-file
baseDN=dc=example,dc=com
searchScope=sub
sortOrder=givenName
virtualListView=0:2:1:0

If a command-line interface uses the port property, the command first tries to locate a toolname.port definition. If this is not defined, the command tries to locate a port definition. For example, the properties file might have several port options defined for different utilities:

port=4444
ldapsearch.port=1389
ldapcompare.port=1389
ldapmodify.port=1389
ldapdelete.port=1389

Note:

Do not use quotation marks around the values in the properties file (for example, port="4444").

A.2 Server Administration Commands

The following sections describe the server administration commands:

Section A.2.1, "create-rc-script"
Section A.2.2, "dps2oud"
Section A.2.3, "ds2oud"
Section A.2.4, "dsconfig"
Section A.2.5, "dsjavaproperties"
Section A.2.6, "dsreplication"
Section A.2.7, "gicadm"
Section A.2.8, "manage-tasks"
Section A.2.9, "oudCopyConfig"
Section A.2.10, "oudExtractMovePlan"
Section A.2.11, "oudPasteConfig"
Section A.2.12, "oud-replication-gateway-setup"
Section A.2.13, "oud-setup"
Section A.2.14, "oud-proxy-setup"
Section A.2.15, "start-ds"
Section A.2.16, "status"
Section A.2.17, "stop-ds"
Section A.2.18, "uninstall"
Section A.2.19, "windows-service"

A.2.1 create-rc-script

The create-rc-script command generates a shell script to start, stop, and restart the directory server.

A.2.1.1 Synopsis

create-rc-script [options]

A.2.1.2 Description

The create-rc-script command can be used to generate a shell script to start, stop, and restart the directory server. You can update the resulting script to suit the needs of your directory service. This command is available for UNIX or Linux systems only.

The create-rc-script command uses the OPENDS_JAVA_* and JAVA_* variables.

A.2.1.3 Options

The create-rc-script command accepts an option in either its short form (for example, -f filename) or its long form equivalent (for example, --outputFile filename).

-f, --outputFile filename: Specify the path to the output file.
-j, --javaHome javaHomePath: Specify the path to the Java installation that should be used to run the server.
-J, --javaArgs javaArgs: Specify the set of arguments that should be passed to the JVM when running the server.
-u, --userName userName: Specify the name of the user account under which the server should run. The user account must have the appropriate permissions to run the script.

A.2.1.4 General Options

--version: Display the version information for the directory server.
-?, -H, --help: Display command-line usage information for the create-rc-script command.

A.2.1.5 Examples

The following examples show how to use the create-rc-script command.

Example A-1 Creating the Script

The following command generates the script to start, stop, and restart the directory server. It creates the file called myscript, specified by the -f option:

$ create-rc-script -f myscript

Example A-2 Starting the Directory Server by Using the New Script

The following command uses the newly created script (see previous example) to start the directory server.

$ myscript start

Example A-3 Stopping the Directory Server by Using the New Script

The following command uses the newly created script (see first example) to stop the directory server.

$ myscript stop

Example A-4 Restarting the Directory Server by Using the New Script

The following command uses the newly created script (see first example) to restart the directory server.

$ myscript restart

Example A-5 Specifying JAVA_HOME and JAVA_ARGS in the Script

The following command uses the -u (--userName), -j (--javaHome) and -J (--javaArgs) options.

$ create-rc-script -f myscript -u sysAdmin -j /usr/java -J "-Xms128m -Xmx128m"

A.2.1.6 Code Generated by the `create-rc-script` Command

The create-rc-script command from the example above generates the following code:

# /bin/sh
#
# CDDL HEADER START
#
# The contents of this file are subject to the terms of the
# Common Development and Distribution License, Version 1.0 only
# (the "License").  You may not use this file except in compliance
# with the License.
#
# You can obtain a copy of the license at
# https://OpenDS.dev.java.net/OpenDS.LICENSE.
# See the License for the specific language governing permissions
# and limitations under the License.
#
# When distributing Covered Code, include this CDDL HEADER in each
# file and include the License file at
# trunk/opends/resource/legal-notices/OpenDS.LICENSE.  If applicable,
# add the following below this CDDL HEADER, with the fields enclosed
# by brackets "[]" replaced with your own identifying information:
#      Portions Copyright [yyyy] [name of copyright owner]
#
# CDDL HEADER END

# Set the path to the OpenDS instance to manage
INSTANCE_ROOT="/usr/local/opends/standalone/ds-server-1"
export INSTANCE_ROOT

# Specify the path to the Java installation to use
OPENDS_JAVA_HOME="/usr/java"
export OPENDS_JAVA_HOME

# Specify arguments that should be provided to the JVM
JAVA_ARGS="-Xms128m -Xmx128m"
export JAVA_ARGS

# Determine what action should be performed on the server
case "${1}" in
start)
/bin/su sysAdmin "${INSTANCE_ROOT}/bin/start-ds" --quiet
exit ${?}
;;
stop)
/bin/su sysAdmin "${INSTANCE_ROOT}/bin/stop-ds" --quiet
exit ${?}
;;
restart)
/bin/su sysAdmin "${INSTANCE_ROOT}/bin/stop-ds" --restart --quiet
exit ${?}
;;
*)

echo "Usage:  $0 { start | stop | restart }"
exit 1
;;
esac

A.2.1.7 Exit Codes

An exit code of 0 indicates success. A non-zero exit code indicates that an error occurred.

A.2.1.8 Location

The create-rc-script command is located at this path:

UNIX and Linux: INSTANCE_DIR/OUD/bin

A.2.1.9 Related Commands

Section A.2.15, "start-ds"

Section A.2.17, "stop-ds"

A.2.2 dps2oud

The dps2oud command allows you to migrate a Directory Proxy Server (DPS) configuration to an Oracle Unified Directory configuration.

A.2.2.1 Synopsis

dps2oud [options]

A.2.2.2 Description

The dps2oud command allows you to migrate a DPS configuration to an Oracle Unified Directory configuration. The dps2oud command takes a DPS configuration as the input and generates a batch file that comprises dsconfig commands, which are used to create an equivalent Oracle Unified Directory configuration. The dps2oud command reads the DPS configuration either through a file or through the LDAP protocol on a running DPS instance.

A.2.2.3 Options

The dps2oud command accepts the following options.

-o, --outputFile file: The output file for dsconfig commands.
-f, --dpsConfigFile file: Specifies the name of the DPS config file to use.
-c, --createDisabledObjects: Creates DPS-disabled objects.
-P, --printDsConfigCmds: Prints dsconfig commands.

A.2.2.4 LDAP Connection Options

-h, --hostname host: DPS server hostname or IP address.
-j, --bindPasswordFile filename: The full path to the file containing the bind password.
-p, --port port: DPS server port number.
-D, --BindDN bindDN: DN to use to bind to the DPS server.

A.2.2.5 General Options

-?, -H, --help: Displays command-line usage information for the command and exit without making any attempt to stop or restart the directory server.
-V, --version: Displays the version information for the directory server.

A.2.2.6 Examples

The following examples show how to use the dps2oud command.

Example A-6 Viewing the Global Help Subcommands

The following command displays the available global Help subcommands:

$ dps2oud --help

Example A-7 Migrating a Directory Proxy Server Configuration to an Oracle Unified Directory Configuration

You can migrate a DPS configuration to an Oracle Unified Directory configuration using one of the following methods:

Method 1: Reading a DPS configuration from an LDIF file

The following command displays how to read a DPS configuration from an LDIF file:

$ dps2oud -f dse.ldif -o oud_conf_cmds

The following command provides the path to a batch file containing a set of dsconfig commands to be executed:

$ dsconfig -F oud_conf_cmds

Method 2: Reading a DPS configuration from a running DPS instance

The following command displays how to read a DPS configuration from a DPS instance:

$ dps2oud -h dpsHost -p 389 -D "cn=Proxy Manager"  -j /path/pwd-file -o oud_conf_cmds

The following command provides the path to a batch file containing a set of dsconfig commands to be executed:

$ dsconfig -F oud_conf_cmds

A.2.2.7 Exit Codes

An exit code of 0 indicates that the operation completed successfully. A nonzero exit code indicates that an error occurred during processing.

A.2.2.8 Location

UNIX and Linux: INSTANCE_DIR/OUD/bin/dps2oud
Windows: INSTANCE_DIR\OUD\bat\dps2oud.bat

A.2.2.9 Related Commands

Section A.2.4, "dsconfig"

A.2.3 ds2oud

The ds2oud command manages the migration from an Oracle Directory Server Enterprise Edition directory server instance to Oracle Unified Directory.

A.2.3.1 Synopsis

ds2oud [options]

A.2.3.2 Description

The ds2oud command enables you to manage the migration from an Oracle Directory Server Enterprise Edition directory server instance to Oracle Unified Directory. The ds2oud command first allows you to diagnose the targeted Oracle Directory Server Enterprise Edition directory server, and then performs the migration task. It is based on the premise that the existing Oracle Unified Directory instance is modified to be compatible with the Oracle Directory Server Enterprise Edition directory server to be migrated. The ds2oud command runs in interactive mode, if you do not specify options. Interactive mode works much like a wizard, walking you through every aspect of the migration.

You can also run the ds2oud command in batch mode. In batch mode, a batch file that comprises dsconfig commands is generated. These commands are used to create an equivalent Oracle Unified Directory configuration. So, you can run ds2oud once, and create a single batch file that can be used to configure any number of Oracle Unified Directory instances.

You must ensure while running the ds2oud command that the Oracle Unified Directory instance (to which the Oracle Directory Server Enterprise Edition instance is being migrated) is configured without any suffixes.

A.2.3.3 Options

The ds2oud command accepts the following options.

-d, --diagnose

Diagnoses the targeted Oracle Directory Server Enterprise Edition directory server.

-f, --ldifDBFile file

Diagnoses the Oracle Directory Server Enterprise Edition directory server LDIF database file.

-u, --userSchemaFile file

Specifies the user schema to be taken into consideration. It applies to -f subcommand.

-a, --migrateAll

Propagates schema and configuration elements from Oracle Directory Server Enterprise Edition directory server to Oracle Unified Directory server.

-s, --migrateUserSchema

Propagates the User schema from Oracle Directory Server Enterprise Edition directory server to Oracle Unified Directory server.

You must migrate the schema before you migrate the configuration, otherwise the migration can produce unpredictable results.

-c, --migrateConfiguration

Propagates configuration elements from Oracle Directory Server Enterprise Edition directory server to Oracle Unified Directory server.

You must migrate the schema before you migrate the configuration, otherwise the migration can produce unpredictable results.

-w, --uniqueWorkflowElement

Use a unique workflow element for all the naming contexts to migrate. This applies to -c subcommand.

A.2.3.4 Oracle Directory Server Enterprise Edition LDAP Connection Options

-D, --odseeBindDN bindDN: DN to use to bind to the Oracle Directory Server Enterprise Edition server.
-j, --odseeBindPasswordFile filename: Oracle Directory Server Enterprise Edition bind password file.
-h, --odseeHostname host: Oracle Directory Server Enterprise Edition server hostname. The default value is localhost.
-p, --odseePort port: Oracle Directory Server Enterprise Edition server port number. The default value is 389.
-Z, --odseeUseSSL: Establishes an Oracle Directory Server Enterprise Edition SSL-encrypted connection.
-P, --odseeTrustStorePath trustStorePath: Use the Oracle Directory Server Enterprise Edition trust store certificate in the specified path. This option is not needed if -X is used, although a trust store should be used when working in a production environment.
-U, --odseeTrustStorePasswordFile filename: Use the password in the specified file to access the certificates in the Oracle Directory Server Enterprise Edition trust store. This option is only required if --odseeTrustStorePath is used and the specified trust store requires a password to access its contents (most trust stores do not require this).
-X, --odseeTrustAll: Trust all certificate that the Oracle Directory Server Enterprise Edition server presents. This option can be used for testing purposes, but for security reasons, a trust store should be used to determine whether the Oracle Directory Server Enterprise Edition should accept the server certificate.

A.2.3.5 Oracle Unified Directory LDAP Connection Options

--oudBindDN bindDN: DN to use to bind to the Oracle Unified Directory server.
--oudBindPasswordFile filename: Oracle Unified Directory bind password file.
--oudHostname host: Oracle Unified Directory server hostname. The default value is localhost.
--oudPort port: Oracle Unified Directory server port number. The default value is 389.
--oudAdminPort port: Oracle Unified Directory server administration port. The default value is 444.
--oudUseSSL: Establishes an Oracle Unified Directory SSL-encrypted connection.
--oudTrustStorePath trustStorePath: Use the Oracle Unified Directory trust store certificate in the specified path.
--oudTrustStorePasswordFile filename: Use the password in the specified file to access the certificates in the Oracle Unified Directory trust store. This option is only required if --oudTrustStorePath is used and the specified trust store requires a password to access its contents (most trust stores do not require this).
--oudTrustAll: Trust all certificate that the Oracle Unified Directory server presents. This option can be used for testing purposes, but for security reasons, a trust store should be used to determine whether the Oracle Unified Directory should accept the server certificate.

A.2.3.6 Command Input/Output Options

-n, --no-prompt

Use the non-interactive mode. If data in the command is missing, the user is not prompted and the tool fails.

-o, --outputFile filename

Redirects the output into the specified output file.

-F, --batchFilePath filename

This option specifies the name of the output file that contains a set of dsconfig commands to execute to migrate the configuration.

When you run ds2oud with this option, a batch file is generated that includes all of the dsconfig commands required to create the equivalent Oracle Unified Directory configuration. So, you can run ds2oud once, and create a single batch file that can be used to configure any number of Oracle Unified Directory instances.

--displayCommand

Display the equivalent non-interactive dsconfig commands (for the migration of Oracle Directory Server Enterprise Edition configuration parameters).

A.2.3.7 General Options

-?, -H, --help: Displays command-line usage information for the command and exit without making any attempt to stop or restart the directory server.
-V, --version: Displays the version information for the directory server.

A.2.3.8 Examples

The following examples show how to use the ds2oud command.

Example A-8 Viewing the Global Help Subcommands

The following command displays the available global Help subcommands:

$ ds2oud --help

Example A-9 Running ds2oud in Interactive Mode From the Command Line

The ds2oud command can be run in interactive mode, where you are prompted for migration options. To run ds2oud in interactive mode, type the following command:

$ ds2oud
What do you want to do ?

1)  Diagnose an ODSEE directory server instance
2)  Diagnose an ODSEE LDIF data file
3)  Migrate all ( user schema + configuration )
4)  Migrate the user schema
5)  Migrate global configuration parameters

c)  cancel

For each preceding action, you must first provide the connection options for the Oracle Directory Server Enterprise Edition server (for diagnosis) or both the Oracle Directory Server Enterprise Edition and Oracle Unified Directory servers (for migration).

Example A-10 Running ds2oud for Diagnosing Data

The following command is run to diagnose the data present in the Oracle Directory Server Enterprise Edition directory server:

$ ds2oud -f odseeDataFile.ldif -u 99user.ldif

*******************************************************************************
* Diagnose ODSEE LDIF data file :  odseeDataFile.ldif
*******************************************************************************
The data were validated successfully regarding the OUD schema

Example A-11 Migrating an Existing Oracle Directory Server Enterprise Edition Configuration to an Oracle Unified Directory Configuration

Use the following commands to migrate an existing Oracle Directory Server Enterprise Edition Configuration to a new Oracle Unified Directory Configuration

The following command migrates an existing Oracle Directory Server Enterprise Edition configuration and schema:

$ ds2oud --migrateAll -D "cn=directory manager"
-j /tmp/pwd -h hostname -p ldapPort  
--oudBindDN "cn=directory manager" --oudBindPasswordFile /tmp/pwd
--oudHostname hostname2 --oudPort ldapPort2 --oudAdminPort adminPort  -n

The following command provides the path to a batch file containing a set of dsconfig commands to be executed to create a new Oracle Unified Directory configuration:

$ ds2oud --migrateConfiguration --batchFilePath batchFile
-D "cn=directory manager" -j /tmp/pwd -h hostname 
-p ldapPort --oudBindDN "cn=directory manager"
--oudBindPasswordFile /tmp/pwd  --oudHostname hostname2 
--oudPort ldapPort2 --oudAdminPort adminPort -n

A.2.3.9 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: At least one step into the migration process has failed.
4: The user canceled the operation in interactive mode.

A.2.3.10 Location

UNIX and Linux: INSTANCE_DIR/OUD/bin/ds2oud
Windows: INSTANCE_DIR\OUD\bat\ds2oud.bat

A.2.3.11 Related Commands

Section A.2.4, "dsconfig"

A.2.4 dsconfig

The dsconfig command configures a directory server instance.

A.2.4.1 Synopsis

dsconfig [subcommands] [globalOptions]

A.2.4.2 Description

The dsconfig command enables you to create, manage, and remove the base configuration for a server instance. The server configuration is organized as a set of components that dsconfig can access by using one or more subcommands. All components have zero or more configurable properties. These properties can be queried and modified to change the behavior of the component.

The dsconfig command accesses the server over SSL through the administration connector (described in Section 13.3, "Managing Administration Traffic to the Server").

Unless you specify all configuration parameters and the -n (--no-prompt) option, dsconfig runs in interactive mode. Interactive mode works much like a wizard, walking you through every aspect of the server configuration. For more information, see Section 13.1.2, "Using dsconfig in Interactive Mode."

A.2.4.3 Help Subcommands

The dsconfig command provides help functions that list the component subcommands needed to manage your configurations.

--help-core-server

Display subcommands relating to the core server.

--help-database

Display subcommands relating to caching and the back ends.

These subcommands are not supported for a proxy server instance.

--help-logging

Display subcommands relating to logging.

--help-replication

Display subcommands relating to directory server replication.

These subcommands are not supported for a proxy server instance.

--help-security

Display subcommands relating to security.

--help-user-management

Display subcommands relating to caching and user management.

These subcommands are not supported for a proxy server instance.

--help-all

Display all subcommands.

A.2.4.4 General Subcommands

The following subcommand lists the objects and properties of the server instance.

list-properties

Displays the managed objects and properties. Option types are as follows:

r — Property values are readable.

w — Property values are writable.

m — The property is mandatory.

s — The property is single-valued.

a — Administrative action is required for changes to take effect.

Suboptions are as follows:

-t, --type type. Component type.

-c, --category category. Category of the component. The value for type must be one of the component types associated with the category that is specified using the --category suboption.

--inherited. Modifies the display output to show the inherited properties of components.

--advanced. Modifies the display output to show the advanced properties of components.

--property property. The name of a property to be displayed.

A.2.4.5 Core Server Subcommands

The following subcommands configure the core server. When objects are created using dsconfig, their names are case-insensitive. If you create two objects, whose names differ in case only, dsconfig returns an error stating that an object with that name already exists.

create-alert-handler

Creates alert handlers. Suboptions are as follows:

--handler-name name. Name of the new alert handler.

--advanced. Allows the configuration of advanced properties during interactive mode.

-t,--type type. Type of alert handler that should be created (default: generic). The value of type can be one of custom, jmx, or smtp.

create-attribute-syntax

This command is not supported for the proxy.

Creates attribute syntaxes. Suboptions are as follows:

--syntax-name name. Name of the new attribute syntax.

--advanced. Allows the configuration of advanced properties during interactive mode.

-t,--type type. Type of attribute syntax that should be created (default: generic). The value of type can be one of attribute-type-description, directory-string, generic, or telephone-number.

create-connection-handler

Creates connection handlers. Suboptions are as follows:

--handler-name name. Name of the new connection handler.

--advanced. Allows the configuration of advanced properties during interactive mode.

-t,--type type. Type of connection handler that should be created (default: generic). The value of type can be one of custom, jmx, ldap, snmp, or ldif.

create-distribution-algorithm

This command is supported only for the proxy.

Creates distribution algorithms. Suboptions are as follows:

--element-name name. Name of the distribution workflow element.

-t,--type type. Type of distribution algorithm that should be created. The value for type can be one of: capacity, dnpattern, lexico, or numeric.

create-distribution-partition

This command is supported only for the proxy.

Creates distribution partitions. Suboptions are as follows:

--element-name name. The name of the distribution workflow element.

--partition-name name. The name of the new distribution partition.

-t,--type type. Type of extension that should be created. The value of type can be one of capacity, dnpattern, lexico, or numeric.

create-extended-operation-handler

This command is not supported for the proxy.

Creates extended operation handlers. Suboptions are as follows:

--handler-name name. Name of the new extended operation handler.

--advanced. Allows the configuration of advanced properties during interactive mode.

--set property:value. Assigns a value to a property, where property is the name of the property and value is the single value to be assigned. Specify the same property multiple times to assign more than one value to it.

-t,--type type. Type of extended operation handler that should be created (default: generic). The value of type can be one of cancel, custom, get-connection-id, get-symmetric-key, password-modify, password-policy-state, start-tls, or who-am-i.

create-extension

Creates extensions. Suboptions are as follows:

--extension-name name. Name of the new extension.

-t,--type type. Type of extension that should be created. The value of type can be one of custom, global-index-catalog, or ldap-server.

-t,--type type. Type of extension that should be created. The value of type can custom.

The value global-index-catalog is not supported for the proxy. See Section A.2.7, "gicadm."

create-global-index

This command is supported only for the proxy.

To manage the global index see Section A.2.7, "gicadm."

create-global-index-catalog-replication-domain

This command is supported only for the proxy.

create-group-implementation

This command is not supported for the proxy.

Creates group implementations. Suboptions are as follows:

--implementation-name name. Name of the new group implementation.

--advanced. Allows the configuration of advanced properties during interactive mode.

-t, --type type. The type of group implementation that should be created. The value for type can be one of custom, dynamic. static, or virtual-static.

create-load-balancing-algorithm

This command is supported only for the proxy.

Creates load balancing algorithms. Suboptions are as follows:

--element-name name. The name of the load balancing workflow element.

-t,--type type. Type of load balancing algorithm that should be created. The value of type can be failover, generic, optimal, proportional, saturation, or searchfilter. The default value is generic.

create-load-balancing-route

This command is supported only for the proxy.

Creates load balancing routes. Suboptions are as follows:

--element-name name. The name of the load balancing workflow element.

--route-name name. The name of the new load balancing route.

create-matching-rule

This command is not supported for the proxy.

Creates matching rules. Suboptions are as follows:

--rule-name name. Name of the new matching rule.

--advanced. Allows the configuration of advanced properties during interactive mode.

-t,--type type. Type of matching rule that should be created. The value of type can be one of approximate, equality, ordering, substring.

create-monitor-provider

Creates monitor providers. Suboptions are as follows:

--provider-name name. Name of the new monitor provider.

--advanced. Allows the configuration of advanced properties during interactive mode.

-t, --type type. The type of monitor provider that should be created. The value for type can be one of the following: client-connection, custom, entry-cache, memory-usage, stack-trace, system-info, or version.

create-network-group

This command is supported only for the proxy.

Creates network groups. Suboptions are as follows:

--group-name name. The name of the new network group.

create-network-group-qos-policy

This command is supported only for the proxy.

Creates network group resource limits. Suboptions are as follows:

--group-name name. The name of the network group.

-t, --typetype. The type of quality of service policy that should be created. The value for type can be one of the following: affinity, referral, request-filtering, or resource-limits

create-plugin

Creates plug-ins. Suboptions are as follows:

--plugin-name name. Name of the new plug-in.

--advanced. Allows the configuration of advanced properties during interactive mode.

-t,--type type. Type of plug-in that should be created (default: generic). The value of type can be one of custom, entry-uuid, last-mod, ldap-attribute-description-list, password-policy-import, profiler, referential-integrity, seven-bit-clean, or unique-attribute.

create-virtual-attribute

This command is not supported for the proxy.

Creates virtual attributes. Suboptions are as follows:

--name name. Name of the new virtual attribute.

--advanced. Allows the configuration of advanced properties during interactive mode.

-t,--type type. Type of virtual attribute that should be created (default: generic). The value of type can be one of custom, entry-dn, entry-uuid, has-subordinates, is-member-of, member, num-subordinates, subschema-subentry, or user-defined.

create-workflow

This command is supported only for the proxy.

Creates workflows. Suboptions are as follows:

--workflow-name name. The name of the new workflow. This name will also be used as the value of the workflow-idproperty.

create-workflow-element

This command is supported only for the proxy.

Creates workflow elements. Suboptions are as follows:

--element-name name. The name of the new workflow element. This name will also be used as the value of the workflow-element-idproperty.

-t, --type type. The type of Workflow Element which should be created. The value of type can be one of: custom, distribution, load-balancing, db-local-backend, or proxy-ldap. The value db-local-backend is not supported for the proxy.

delete-alert-handler

Deletes alert handlers. Suboptions are as follows:

--handler-name name. Name of the alert handler.

-f,--force. Ignore nonexistent alert handlers.

delete-attribute-syntax

This command is not supported for the proxy.

Deletes attribute syntaxes. Suboptions are as follows:

--syntax-name name. Name of the attribute syntax.

-f,--force. Ignore nonexistent attribute syntaxes.

delete-connection-handler

Deletes connection handlers. Suboptions are as follows:

--handler-name name. Name of the connection handler.

-f,--force. Ignore nonexistent connection handlers.

delete-distribution-algorithm

This command is supported only for the proxy.

Deletes distribution algorithm. Suboptions are as follows:

--element-name name. The name of the distribution workflow element.

-f,--force. Ignore nonexistent distribution algorithms.

delete-distribution-partition

This command is supported only for the proxy.

Deletes distribution partitions. Suboptions are as follows:

--element-name name. The name of the distribution workflow element.

--partition-name name. The name of the distribution partition.

-f,--force. Ignore nonexistent distribution partitions.

delete-extended-operation-handler

Deletes extended operation handlers. Suboptions are as follows:

--handler-name name. The name of the extended operation handler.

-f,--force. Ignore nonexistent extended operation handlers.

delete-extension

Deletes extension. Suboptions are as follows:

--extension-name name. The name of the extension.

-f,--force. Ignore nonexistent extensions.

delete-global-index

This command is supported only for the proxy. To manage the global index see Section A.2.7, "gicadm".

delete-global-index-catalog-replication-domain

This command is supported only for the proxy. To manage the global index see Section A.2.7, "gicadm."

delete-group-implementation

This command is not supported for the proxy.

Deletes group implementations. Suboptions are as follows:

--implementation-name name. Name of the group implementation.

-f,--force. Ignore nonexistent group implementations.

delete-load-balancing-route

This command is supported only for the proxy.

Deletes load balancing routes. Suboptions are as follows:

--element-name name. The name of the load balancing workflow element.

--route-name name. The name of the load balancing route.

-f,--force. Ignore nonexistent load balancing routes.

delete-load-balancing-algorithm

This command is supported only for the proxy.

Deletes load balancing algorithm. Suboptions are as follows:

--element-name name. The name of the load balancing workflow element.

-f,--force. Ignore nonexistent load balancing algorithms.

delete-matching-rule

This command is not supported for the proxy.

Deletes matching rules. Suboptions are as follows:

--rule-name name. Name of the matching rule.

-f,--force. Ignore nonexistent matching rules.

delete-monitor-provider

Deletes monitor providers. Suboptions are as follows:

--provider-name name. Name of the monitor provider.

-f,--force. Ignore nonexistent monitor providers.

delete-network-group

This command is supported only for the proxy.

Deletes network group. Suboptions are as follows:

--group-name name. The name of the network group.

-f,--force. Ignore nonexistent network groups.

delete-network-group-qos-policy

This command is supported only for the proxy.

Deletes network group quality of service policy. Suboptions are as follows:

--group-name name. The name of the network group.

--policy-type namne. The name of the QOS policy.

-f,--force. Ignore nonexistent network group resource limits.

delete-plugin

Deletes plug-ins. Suboptions are as follows:

--plugin-name name. Name of the plug-in.

-f,--force. Ignore nonexistent plug-ins.

delete-virtual-attribute

This command is not supported for the proxy.

Deletes virtual attributes. Suboptions are as follows:

--name name. Name of the virtual attribute.

-f,--force. Ignore nonexistent virtual attributes.

delete-workflow

This command is supported only for the proxy.

Deletes workflow. Suboptions are as follows:

-f,--force. Ignore nonexistent workflows.

--workflow-name name. The name of the workflow.

delete-workflow-element

This command is supported only for the proxy.

Deletes workflow elements. Suboptions are as follows:

--element-name name. The name of the workflow element.

-f,--force. Ignore nonexistent workflow elements.

get-administration-connector-prop

Shows administration connector properties. Suboptions are as follows:

-E,--record. Modifies the display output to show one property value per line.

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-alert-handler-prop

Shows alert handler properties. Suboptions are as follows:

--advanced. Modifies the display output to show the advanced properties of the alert handler.

--handler-name name. Name of the alert handler.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-attribute-syntax-prop

This command is not supported for the proxy.

Shows attribute syntax properties. Suboptions are as follows:

--syntax-name name. Name of the attribute syntax.

--property property. The name of a property to be displayed.

--advanced. Modifies the display output to show the advanced properties of the attribute syntax.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-connection-handler-prop

Shows extended operation handler properties. Suboptions are as follows:

--handler-name name. Name of the extended operation handler.

--property property. The name of a property to be displayed.

--advanced. Modifies the display output to show the advanced properties of the extended operation handler.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-distribution-algorithm-prop

This command is supported only for the proxy.

Shows distribution algorithm properties. Suboptions are as follows:

--element-name name. The name of the distribution workflow element.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-distribution-partition-prop

This command is supported only for the proxy.

Shows distribution partition properties. Suboptions are as follows:

--element-name name. The name of the distribution workflow element.

--partition-name name. The name of the distribution partition.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-extended-operation-handler-prop

Shows extended operation handler properties. Suboptions are as follows:

--handler-name name. The name of the extended operation handler.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-extension-prop

Shows extension properties. Suboptions are as follows:

--extension-name name. The name of the extension.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-global-configuration-prop

Shows global properties. Suboptions are as follows:

--advanced. Modifies the display output to show the advanced properties of the global configuration.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-global-index-prop

This command is supported only for the proxy. To manage the global index see Section A.2.7, "gicadm."

get-global-index-catalog-replication-domain-prop

This command is supported only for the proxy. To manage the global index see Section A.2.7, "gicadm."

get-group-implementation-prop

This command is not supported for the proxy.

Shows group implementation properties. Suboptions are as follows:

--implementation-name name. Name of the group implementation.

--advanced. Modifies the display output to show the advanced properties of the group implementation.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-load-balancing-algorithm-prop

This command is supported only for the proxy.

Shows load balancing algorithm properties. Suboptions are as follows:

--element-name name. The name of the load balancing workflow element.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-load-balancing-route-prop

This command is supported only for the proxy.

Shows load balancing route properties. Suboptions are as follows:

--element-name name. The name of the load balancing workflow element.

--route-name name. The name of the load balancing route.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-matching-rule-prop

This command is not supported for the proxy.

Shows matching rule properties. Suboptions are as follows:

--advanced. Modifies the display output to show the advanced properties of the matching rule.

--rule-name name. Name of the matching rule.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-monitor-provider-prop

Shows monitor provider properties. Suboptions are as follows:

--provider-name name. Name of the monitor provider.

--advanced. Modifies the display output to show the advanced properties of the monitor provider.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-network-group-prop

This command is supported only for the proxy.

Shows network group properties. Suboptions are as follows:

--group-name name. The name of the network group.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-network-group-qos-policy-prop

This command is supported only for the proxy.

Shows network group quality of service policy properties. Suboptions are as follows:

--group-name name. The name of the network group.

--policy-type name. The name of the quality of service policy.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-plugin-prop

Shows plug-in properties. Suboptions are as follows:

--plugin-name name. Name of the plug-in.

--advanced. Modifies the display output to show the advanced properties of the plug-in.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-plugin-root-prop

Shows plug-in root properties. Suboptions are as follows:

--advanced. Modifies the display output to show the advanced properties of the plug-in root.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-root-dn-prop

Shows Root DN properties. Suboptions are as follows:

--advanced. Modifies the display output to show the advanced properties of the Root DN.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-root-dse-backend-prop

Shows root DSE back end properties. Suboptions are as follows:

--advanced. Modifies the display output to show the advanced properties of the root DSE back end.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-virtual-attribute-prop

This command is not supported for the proxy.

Shows virtual attribute properties. Suboptions are as follows:

--advanced. Modifies the display output to show the advanced properties of the virtual attribute.

--name name. Name of the virtual attribute.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-work-queue-prop

Shows work queue properties. Suboptions are as follows:

--advanced. Modifies the display output to show the advanced properties of the work queue.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-workflow-element-prop

This command is supported only for the proxy.

Show workflow element properties. Suboptions are as follows:

--element-name name. The name of the workflow element.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-workflow-prop

This command is supported only for the proxy.

Shows workflow properties. Suboptions are as follows:

--workflow-name name. The name of the workflow.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-alert-handlers

Lists existing alert handlers. Suboptions are as follows:

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-attribute-syntaxes

This command is not supported for the proxy.

Lists existing attribute syntaxes. Suboptions are as follows:

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-connection-handlers

Lists existing connection handlers. Suboptions are as follows:

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-distribution-algorithm

This command is supported only for the proxy.

Lists existing distribution algorithms. Suboptions are as follows:

--element-name name. The name of the distribution workflow element.

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-distribution-partitions

This command is supported only for the proxy.

Lists existing distribution partitions. Suboptions are as follows:

--element-name name. The name of the distribution workflow element.

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-extended-operation-handlers

Lists existing extended operation handlers. Suboptions are as follows:

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-extensions

This command is supported only for the proxy.

Lists existing extensions. Suboptions are as follows:

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-global-index

This command is supported only for the proxy. To manage the global index see Section A.2.7, "gicadm."

list-global-index-catalog-replication-domain

This command is supported only for the proxy. To manage the global index see Section A.2.7, "gicadm."

list-group-implementations

This command is not supported for the proxy.

Lists existing group implementations. Suboptions are as follows:

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-load-balancing-algorithm

This command is supported only for the proxy.

Lists existing load balancing algorithm. Suboptions are as follows:

--element-name name. The name of the load balancing workflow element.

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-load-balancing-routes

This command is supported only for the proxy.

Lists existing load balancing routes. Suboptions are as follows:

--element-name name. The name of the load balancing workflow element.

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-matching-rules

This command is not supported for the proxy.

Lists existing matching rules. Suboptions are as follows:

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-monitor-providers

Lists existing monitor providers. Suboptions are as follows:

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-network-group-qos-policies

This command is supported only for the proxy.

Lists existing network group quality of service policies. Suboptions are as follows:

--group-name name. The name of the network group.

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-network-groups

This command is supported only for the proxy.

Lists existing network groups. Suboptions are as follows:

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-plugins

Lists existing plug-ins. Suboptions are as follows:

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-virtual-attributes

This command is not supported for the proxy.

Lists existing virtual attributes. Suboptions are as follows:

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-workflow-elements

This command is supported only for the proxy.

Lists existing workflow elements. Suboptions are as follows:

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-workflows

This command is supported only for the proxy.

Lists existing workflows. Suboptions are as follows:

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

set-administration-connector-prop

This command is supported only for the proxy.

Modifies existing administration connector properties. Suboptions are as follows:

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-alert-handler-prop

Modifies alert handler properties. Suboptions are as follows:

--handler-name name Name of the alert handler.

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-attribute-syntax-prop

This command is not supported for the proxy.

Modifies attribute syntax properties. Suboptions are as follows:

--syntax-name name Name of the attribute syntax.

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-connection-handler-prop

Modifies connection handler properties. Suboptions are as follows:

--handler-name name Name of the connection handler.

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-distribution-algorithm-prop

This command is supported only for the proxy.

Modifies distribution algorithm properties. Suboptions are as follows:

--element-name name. The name of the distribution workflow element.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-distribution-partition-prop

This command is supported only for the proxy.

Modifies distribution partition properties. Suboptions are as follows:

--element-name name. The name of the distribution workflow element.

--partition-name name. The name of the distribution partition.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-extended-operation-handler-prop

Modifies extended operation handler properties. Suboptions are as follows:

--handler-name name Name of the extended operation handler.

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-global-configuration-prop

Modifies global configuration properties. Suboptions are as follows:

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-global-index-prop

This command is supported only for the proxy.

set-global-index-catalog-replication-domain-prop

This command is supported only for the proxy.

set-group-implementation-prop

This command is not supported for the proxy.

Modifies group implementation properties. Suboptions are as follows:

--implementation-name name Name of the group implementation.

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-load-balancing-algorithm-prop

This command is supported only for the proxy.

Modifies load-balancing algorithm properties. Suboptions are as follows:

--element-name name. The name of the load balancing workflow element.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-load-balancing-route-prop

This command is supported only for the proxy.

Modifies load balancing algorithm properties. Suboptions are as follows:

--element-name name. The name of the load balancing workflow element.

--route-name name. The name of the load balancing route.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-matching-rule-prop

This command is not supported for the proxy.

Modifies matching rule properties. Suboptions are as follows:

--rule-name name Name of the matching rule.

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-monitor-provider-prop

Modifies monitor provider properties. Suboptions are as follows:

--provider-name name Name of the monitor provider.

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-network-group-prop

This command is supported only for the proxy.

Modifies network group properties. Suboptions are as follows:

--group-name name. The name of the network group.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-network-group-qos-policy-prop

This command is supported only for the proxy.

Modifies network group quality of service policy properties. Suboptions are as follows:

--group-name name. The name of the network group.

--policy-type name. The name of the QOS policy.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-plugin-prop

Modifies plug-in properties. Suboptions are as follows:

--plugin-name name Name of the plug-in.

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-plugin-root-prop

Modifies plug-in root properties. Suboptions are as follows:

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-root-dn-prop

Modifies root DN properties. Suboptions are as follows:

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-root-dse-backend-prop

Modifies root DSE back end properties. Suboptions are as follows:

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-virtual-attribute-prop

This command is not supported for the proxy.

Modifies virtual attribute properties. Suboptions are as follows:

--name name Name of the virtual attribute.

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-work-queue-prop

Modifies work queue properties. Suboptions are as follows:

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-workflow-element-prop

This command is supported only for the proxy.

Modifies workflow element properties. Suboptions are as follows:

--element-name name. The name of the workflow element.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-workflow-prop

This command is supported only for the proxy.

Modifies workflow properties. Suboptions are as follows:

--workflow-name name. The name of the workflow.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

A.2.4.6 Database Subcommands

The following subcommands configure caching and back ends.

These commands are not supported for a proxy server instance.

create-entry-cache

Creates entry caches. Suboptions are as follows:

--cache-name name. The name of the new entry cache.

-t,--type type. The type of entry cache that should be created. The value for type can be one of custom, fifo, file-system, or soft-reference.

create-local-db-index

Creates local DB indexes. Suboptions are as follows:

--element-name name. Name of the local DB back end workflow element.

--index-name name. Name of the new local DB index, which will also be used as the value of the attribute property. This specifies the name of the attribute for which the index is to be maintained.

--advanced. Allows the configuration of advanced properties during interactive mode.

create-local-db-vlv-index

Creates local DB VLV indexes. Suboptions are as follows:

--element-name name. Name of the local DB back end workflow element.

--index-name name. Name of the new local DB VLV index, which is also used as the value of the name property. This property specifies a unique name for this VLV index.

--advanced. Allows the configuration of advanced properties during interactive mode.

delete-local-db-index

Deletes local DB indexes. Suboptions are as follows:

--element-name name. Name of the local DB back end workflow element.

--index-name name. Name of the local DB index.

-f,--force. Ignore nonexistent local DB indexes.

delete-local-db-vlv-index

Deletes local DB VLV indexes. Suboptions are as follows:

--element-name name. Name of the local DB back end workflow element.

--index-name name. Name of the local DB VLV index.

-f,--force. Ignore nonexistent local DB VLV indexes.

get-entry-cache-prop

Shows entry cache properties. Suboptions are as follows:

--advanced. Modifies the display output to show the advanced properties of the entry cache.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-local-db-index-prop

Shows local DB index properties. Suboptions are as follows:

--element-name name. Name of the local DB back end workflow element.

--index-name name. Name of the local DB index.

--advanced. Modifies the display output to show the advanced properties of the local DB index.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-root-dse-backend-prop

Shows root DSE backend properties. Suboptions are as follows:

--advanced. Modifies the display output to show the advanced properties of the root DSE back end.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-local-db-vlv-index-prop

Shows the local DB VLV index properties. Suboptions are as follows:

--element-name name. Name of the local DB back end.

--index-name name. Name of the local DB VLV index.

--advanced. Modifies the display output to show the advanced properties of the local DB VLV index.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-local-db-vlv-indexes

Lists existing local DB VLV indexes. Suboptions are as follows:

--element-name name. Name of the local DB back end workflow element.

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

set-entry-cache-prop

Modifies Entry Cache properties. Suboptions are as follows:

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-local-db-index-prop

Modifies local DB Index properties. Suboptions are as follows:

--element-name name. Name of the local DB back end workflow element.

--index-name name. Name of the local DB Index.

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-root-dse-backend-prop

Modifies root DSE back end properties. Suboptions are as follows:

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-local-db-vlv-index-prop

Modifies local DB VLV Index properties. Suboptions are as follows:

--element-name name. Name of the local DB back end element name.

--index-name name. Name of the local DB VLV Index.

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

A.2.4.7 Logging Subcommands

The following subcommands configure a server's logging settings.

create-debug-target

Creates debug targets. Suboptions are as follows:

--publisher-name name. Name of the debug log publisher.

--target-name java-name. Name of the new debug target, which will also be used as the value of the debug-scope property: The fully-qualified Oracle Unified Directory Java package, class, or method affected by the settings in this target definition. Use the hash symbol (#) to separate the class name and the method name (for example, org.opends.server.core.DirectoryServer#startUp).

create-log-publisher

Creates log publishers. Suboptions are as follows:

--publisher-name name. Name of the new log publisher.

--advanced. Allows the configuration of advanced properties during interactive mode.

-t,--type type. The type of log publisher that should be created. The value for type can be one of file-based-access, file-based-debug, or file-based-error.

create-log-retention-policy

Creates Log Retention Policies. Suboptions are as follows:

--policy-name name. Name of the new log retention policy.

--advanced. Allows the configuration of advanced properties during interactive mode.

-t,--type type. The type of log retention policy that should be created. The value for type can be one of file-count, free-disk-space, or size-limit.

create-log-rotation-policy

Creates log rotation policies. Suboptions are as follows:

--policy-name name. Name of the new log rotation policy.

--advanced. Allows the configuration of advanced properties during interactive mode.

-t,--type type. The type of log rotation policy that should be created. The value for type can be one of fixed-time, size-limit, or time-limit.

delete-debug-target

Deletes debug targets. Suboptions are as follows:

--publisher-name name. Name of the debug log publisher.

--target-name name. Name of the debug target.

-f,--force. Ignore nonexistent debug targets.

delete-log-publisher

Deletes log publishers. Suboptions are as follows:

--publisher-name name. Name of the log publisher.

-f,--force. Ignore nonexistent log publishers.

delete-log-retention-policy

Deletes Log Retention Policies. Suboptions are as follows:

--policy-name name. Name of the log retention policy.

-f,--force. Ignore nonexistent Log Retention Policies.

delete-log-rotation-policy

Deletes log rotation policies. Suboptions are as follows:

--policy-name name. Name of the log rotation policy.

-f,--force. Ignore nonexistent log rotation policies.

get-debug-target-prop

Shows debug target properties. Suboptions are as follows:

--advanced. Modifies the display output to show the advanced properties of the debug target.

--publisher-name name. Name of the debug log publisher.

--target-name name. Name of the debug target.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-log-publisher-prop

Shows log publisher properties. Suboptions are as follows:

--publisher-name name. Name of the log publisher.

--advanced. Modifies the display output to show the advanced properties of the log publisher.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-log-retention-policy-prop

Shows log retention policy properties. Suboptions are as follows:

--policy-name name. Name of the log retention policy.

--advanced. Modifies the display output to show the advanced properties of the log retention policy.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-log-rotation-policy-prop

Shows log rotation policy properties. Suboptions are as follows:

--policy-name name. Name of the log rotation policy.

--advanced. Modifies the display output to show the advanced properties of the log rotation policy.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-debug-targets

Lists existing debug targets. Suboptions are as follows:

--publisher-name name. Name of the debug log publisher.

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-log-publishers

Lists existing log publishers. Suboptions are as follows:

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-log-retention-policies

Lists existing Log Retention Policies. Suboptions are as follows:

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-log-rotation-policies

Lists existing log rotation policies. Suboptions are as follows:

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

set-debug-target-prop

Modifies debug target properties. Suboptions are as follows:

--publisher-name name. Name of the debug log publisher.

--target-name name. Name of the debug target.

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-log-publisher-prop

Modifies log publisher properties. Suboptions are as follows:

--publisher-name name. Name of the log publisher.

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-log-retention-policy-prop

Modifies log retention policy properties. Suboptions are as follows:

--policy-name name. Name of the log retention policy.

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-log-rotation-policy-prop

Modifies log rotation policy properties. Suboptions are as follows:

--policy-name name. Name of the log rotation policy.

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

A.2.4.8 Replication Subcommands

The following subcommands configure server replication.

These subcommands are not supported for a proxy server instance.

create-replication-domain

Creates replication domains. Suboptions are as follows:

--provider-name name. Name of the multi-master synchronization provider.

--domain-name name. Name of the new replication domain.

--advanced. Allows the configuration of advanced properties during interactive mode.

create-replication-server

Creates replication servers. Suboptions are as follows:

--provider-name name. Name of the multi-master synchronization provider.

--advanced. Allows the configuration of advanced properties during interactive mode.

create-synchronization-provider

Creates synchronization providers. Suboptions are as follows:

--provider-name name. Name of the new synchronization provider.

--advanced. Allows the configuration of advanced properties during interactive mode.

-t,--type type. The type of synchronization provider that should be created. The value for type is multimaster.

delete-replication-domain

Deletes replication domains. Suboptions are as follows:

--provider-name name. Name of the synchronization provider.

--domain-name name. Name of the replication domain.

-f,--force. Ignore nonexistent replication domains.

delete-replication-server

Deletes replication servers. Suboptions are as follows:

--provider-name name. Name of the synchronization provider.

-f,--force. Ignore nonexistent replication servers.

delete-synchronization-provider

Deletes synchronization providers. Suboptions are as follows:

--provider-name name. Name of the synchronization provider.

-f,--force. Ignore nonexistent synchronization providers.

get-replication-domain-prop

Shows replication domain properties. Suboptions are as follows:

--provider-name name. Name of the multi-master synchronization provider.

--domain-name name. Name of the replication domain.

--advanced. Modifies the display output to show the advanced properties of the replication domain.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-replication-server-prop

Shows replication server properties. Suboptions are as follows:

--provider-name name. Name of the multi-master synchronization provider.

--advanced. Modifies the display output to show the advanced properties of the replication server.

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-synchronization-provider-prop

Shows synchronization provider properties. Suboptions are as follows:

--provider-name name. Name of the synchronization provider.

--advanced. Modifies the display output to show the advanced properties of the synchronization provider.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-replication-domains

Lists existing replication domains. Suboptions are as follows:

--provider-name name. Name of the replication synchronization provider.

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-replication-server

Lists existing replication server. Suboptions are as follows:

--provider-name name. Name of the replication synchronization provider.

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-synchronization-providers

Lists existing synchronization providers. Suboptions are as follows:

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

set-replication-domain-prop

Modifies replication domain properties. Suboptions are as follows:

--provider-name name. Name of the replication synchronization provider.

--domain-name name. Name of the replication domain.

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-synchronization-provider-prop

Modifies synchronization provider properties. Suboptions are as follows:

--provider-name name. Name of the synchronization provider.

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

A.2.4.9 Security Subcommands

The following subcommands configure a server's security settings.

create-certificate-mapper

Creates certificate mappers. Suboptions are as follows:

--mapper-name name. Name of the new certificate mapper.

--advanced. Allows the configuration of advanced properties during interactive mode.

-t,--type type. The type of certificate mapper that should be created (default: generic). The value for type can be one of custom, fingerprint, subject-attribute-to-user-attribute, subject-dn-to-user-attribute, or subject-equals-dn.

create-identity-mapper

Creates identity mappers. Suboptions are as follows:

--mapper-name name. Name of the new identity mapper.

--advanced. Allows the configuration of advanced properties during interactive mode.

-t,--type type. The type of identity mapper that should be created. The value for type can be one of exact-match or regular-expression.

create-key-manager-provider

Creates key manager providers. Suboptions are as follows:

--provider-name name. Name of the new key manager provider.

--advanced. Allows the configuration of advanced properties during interactive mode.

-t,--type type. The type of key manager provider that should be created (default: generic). The value for type can be one of file-based, generic, or pkcs11.

PKCS#11 is not supported for a proxy server instance.

create-sasl-mechanism-handler

This command is not supported for the proxy.

Creates SASL mechanism handlers. Suboptions are as follows:

--handler-name name. Name of the new SASL mechanism handler.

--advanced. Allows the configuration of advanced properties during interactive mode.

-t,--type type. The type of SASL mechanism handler that should be created (default: generic). The value for type can be one of anonymous, cram-md5, digest-md5, external, generic, gssapi, or plain.

create-trust-manager-provider

Creates trust manager providers. Suboptions are as follows:

--provider-name name. Name of the new trust manager provider.

--advanced. Allows the configuration of advanced properties during interactive mode.

-t,--type type. The type of trust manager provider that should be created (default: generic). The value for type can be one of blind, file-based, or generic.

delete-certificate-mapper

Deletes certificate mappers. Suboptions are as follows:

--mapper-name name. Name of the certificate mapper.

-f,--force. Ignore nonexistent certificate mappers.

delete-identity-mapper

Deletes identity mappers. Suboptions are as follows:

--mapper-name name. Name of the identity mapper.

-f,--force. Ignore nonexistent identity mappers.

delete-key-manager-provider

Deletes key manager providers. Suboptions are as follows:

--provider-name name. Name of the key manager provider.

-f,--force. Ignore nonexistent key manager providers.

delete-sasl-mechanism-handler

This command is not supported for the proxy.

Deletes SASL mechanism handlers. Suboptions are as follows:

--handler-name name. Name of the SASL mechanism handler.

-f,--force. Ignore nonexistent SASL mechanism handlers.

delete-trust-manager-provider

Deletes trust manager providers. Suboptions are as follows:

--provider-name name. Name of the trust manager provider.

-f,--force. Ignore nonexistent trust manager providers.

get-access-control-handler-prop

Shows access control handler properties. Suboptions are as follows:

--advanced. Modifies the display output to show the advanced properties of the access control handler.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-certificate-mapper-prop

Shows certificate mapper properties. Suboptions are as follows:

--mapper-name name. Name of the certificate mapper.

--advanced. Modifies the display output to show the advanced properties of the certificate mapper.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-crypto-manager-prop

Show crypto manager properties. Suboptions are as follows:

--advanced. Modifies the display output to show the advanced properties of the crypto manager.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-identity-mapper-prop

Shows identity mapper properties. Suboptions are as follows:

--mapper-name name. Name of the identity mapper.

--advanced. Modifies the display output to show the advanced properties of the identity mapper.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-key-manager-provider-prop

Shows key manager provider properties. Suboptions are as follows:

--provider-name name. Name of the key manager provider.

--advanced. Modifies the display output to show the advanced properties of the key manager provider.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-sasl-mechanism-handler-prop

This command is not supported for the proxy.

Shows SASL mechanism handler properties. Suboptions are as follows:

--handler-name name. Name of the SASL mechanism handler.

--advanced. Modifies the display output to show the advanced properties of the SASL mechanism handler.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-trust-manager-provider-prop

Shows trust manager provider properties. Suboptions are as follows:

--provider-name name. Name of the trust manager provider.

--advanced. Modifies the display output to show the advanced properties of the trust manager provider.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-certificate-mappers

Lists existing certificate mappers. Suboptions are as follows:

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-identity-mappers

Lists existing identity mappers. Suboptions are as follows:

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-key-manager-providers

Lists existing key manager providers. Suboptions are as follows:

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-sasl-mechanism-handlers

This command is not supported for the proxy.

Lists existing SASL mechanism handlers. Suboptions are as follows:

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-trust-manager-providers

Lists existing trust manager providers. Suboptions are as follows:

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

set-access-control-handler-prop

Modifies access control handler properties. Suboptions are as follows:

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-certificate-mapper-prop

Modifies certificate mapper properties. Suboptions are as follows:

--mapper-name name. Name of the certificate mapper.

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-crypto-manager-prop

Modifies crypto manager properties. Suboptions are as follows:

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-identity-mapper-prop

Modifies identity mapper properties. Suboptions are as follows:

--mapper-name name. Name of the identity mapper.

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-key-manager-provider-prop

Modifies key manager provider properties. Suboptions are as follows:

--provider-name name. Name of the key manager provider.

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-sasl-mechanism-handler-prop

This command is not supported for the proxy.

Modifies SASL mechanism handler properties. Suboptions are as follows:

--handler-name name. Name of the SASL mechanism handler.

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-trust-manager-provider-prop

Modifies trust manager provider properties. Suboptions are as follows:

--provider-name name. Name of the trust manager provider.

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

A.2.4.10 User Management Subcommands

The following subcommands configure a server's user management settings.

These subcommands are not supported for the proxy server.

create-account-status-notification-handler

Creates account status notification handlers. Suboptions are as follows:

--handler-name name. Name of the new account status notification handler.

--advanced. Allows the configuration of advanced properties during interactive mode.

-t,--type type. The type of account status notification handler that should be created (default: custom). The value for type can be one of custom, error-log, or smtp.

create-certificate-mapper

Creates certificate mappers. Suboptions are as follows:

--mapper-name name. Name of the new certificate mapper.

--advanced. Allows the configuration of advanced properties during interactive mode.

-t,--type type. The type of certificate mapper that should be created (default: custom). The value for type can be one of custom, fingerprint, subject-attribute-to-user-attribute, subject-dn-to-user-attribute, or subject-equals-dn.

create-identity-mapper

Creates identity mappers. Suboptions are as follows:

--mapper-name name. Name of the new identity mapper.

--advanced Allows the configuration of advanced properties during interactive mode.

-t,--type type. The type of identity mapper that should be created. The value for type can be one of exact-match or regular-expression.

create-password-generator

Creates password generators. Suboptions are as follows:

--generator-name name. Name of the new password generator.

--advanced. Allows the configuration of advanced properties during interactive mode.

-t,--type type. The type of password generator that should be created (default: generic). The value for type can be one of generic or random.

create-password-policy

Creates password policies. Suboptions are as follows:

--policy-name name. Name of the new password policy.

--advanced. Allows the configuration of advanced properties during interactive mode.

create-password-storage-scheme

Creates password storage schemes. Suboptions are as follows:

--scheme-name name. Name of the new password storage scheme.

--advanced. Allows the configuration of advanced properties during interactive mode.

-t,--type type. The type of password storage scheme that should be created (default: generic). The value for type can be one of aes, base64, blowfish, clear, crypt, custom, md5, rc4, salted-md5, salted-sha1, salted-sha256, salted-sha384, salted-sha512, sha1, or triple-des.

create-password-validator

Creates password validators. Suboptions are as follows:

--validator-name name. Name of the new password validator.

--advanced. Allows the configuration of advanced properties during interactive mode.

-t,--type type. The type of password validator that should be created (default: generic). The value for type can be one of attribute-value, character-set, dictionary, generic, length-based, repeated-characters, similarity-based, or unique-characters.

delete-account-status-notification-handler

Deletes account status notification handlers. Suboptions are as follows:

--handler-name name. Name of the account status notification handler.

-f,--force. Ignore nonexistent account status notification handlers.

delete-certificate-mapper

Deletes certificate mappers. Suboptions are as follows:

--mapper-name name. Name of the certificate mapper.

-f,--force. Ignore nonexistent certificate mappers.

delete-identity-mapper

Deletes identity mappers. Suboptions are as follows:

--mapper-name name. Name of the identity mapper.

-f,--force. Ignore nonexistent identity mappers.

delete-password-generator

Deletes password generators. Suboptions are as follows:

--generator-name name. Name of the password generator.

-f,--force. Ignore nonexistent password generators.

delete-password-policy

Deletes password policies. Suboptions are as follows:

--policy-name name. Name of the password policy.

-f,--force. Ignore nonexistent password policies.

delete-password-storage-scheme

Deletes password storage schemes. Suboptions are as follows:

--scheme-name name. Name of the password storage scheme.

-f,--force. Ignore nonexistent password storage schemes.

delete-password-validator

Deletes password validators. Suboptions are as follows:

--validator-name name. Name of the password validator.

-f,--force. Ignore nonexistent password validators.

get-account-status-notification-handler-prop

Shows account status notification handler properties. Suboptions are as follows:

--handler-name name. Name of the account status notification handler.

--advanced. Modifies the display output to show the advanced properties of the account status notification handler.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-certificate-mapper-prop

Shows certificate mapper properties. Suboptions are as follows:

--mapper-name name. Name of the certificate mapper.

--advanced. Modifies the display output to show the advanced properties of the certificate mapper.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-identity-mapper-prop

Shows identity mapper properties. Suboptions are as follows:

--mapper-name name. Name of the identity mapper.

--advanced. Modifies the display output to show the advanced properties of the identity mapper.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-password-generator-prop

Shows password generator properties. Suboptions are as follows:

--generator-name name. Name of the password generator.

--advanced. Modifies the display output to show the advanced properties of the password generator.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-password-policy-prop

Shows password policy properties. Suboptions are as follows:

--policy-name name. Name of the password policy.

--advanced. Modifies the display output to show the advanced properties of the password policy.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-password-storage-scheme-prop

Shows password storage scheme properties. Suboptions are as follows:

--scheme-name name. Name of the password storage scheme.

--advanced. Modifies the display output to show the advanced properties of the password storage scheme.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

get-password-validator-prop

Shows password validator properties. Suboptions are as follows:

--validator-name name. Name of the password validator.

--advanced. Modifies the display output to show the advanced properties of the password validator.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-account-status-notification-handler

Lists existing account status notification handlers. Suboptions are as follows:

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-certificate-mappers

Lists existing certificate mappers. Suboptions are as follows:

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-identity-mappers

Lists existing identity mappers. Suboptions are as follows:

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-password-generators

Lists existing password generators. Suboptions are as follows:

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-password-policies

Lists existing password policies. Suboptions are as follows:

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-password-storage-schemes

Lists existing password storage schemes. Suboptions are as follows:

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

list-password-validators

Lists existing password validators. Suboptions are as follows:

--property property. The name of a property to be displayed.

-z,--unit-size unit. Displays size data using the specified unit. The value for unit can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes).

-m,--unit-time unit. Displays time data using the specified unit. The value for unit can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks).

set-account-status-notification-handler-prop

Modifies account status notification handler properties. Suboptions are as follows:

--handler-name name. Name of the account status notification handler.

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-certificate-mapper-prop

Modifies certificate mapper properties. Suboptions are as follows:

--mapper-name name. Name of the certificate mapper.

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-identity-mapper-prop

Modifies identity mapper properties. Suboptions are as follows:

--mapper-name name. Name of the identity mapper.

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-password-generator-prop

Modifies password generator properties. Suboptions are as follows:

--generator-name name. Name of the password generator.

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-password-policy-prop

Modifies password policy properties. Suboptions are as follows:

--policy-name name. Name of the password policy.

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-password-storage-scheme-prop

Modifies password storage scheme properties. Suboptions are as follows:

--scheme-name name. Name of the password storage scheme.

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

set-password-validator-prop

Modifies password validator properties. Suboptions are as follows:

--validator-name name. Name of the password validator.

--advanced. Allows the configuration of advanced properties during interactive mode.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed.

A.2.4.11 Options

The dsconfig command accepts an option in either its short form (for example, -h hostname) or its long form equivalent (for example, --hostname hostname).

--advanced: Allows the configuration of advanced components and properties.

A.2.4.12 LDAP Connection Options

The dsconfig command contacts the directory server over SSL through the administration connector (described in Section 13.3, "Managing Administration Traffic to the Server"). These connection options are used to contact the directory server.

-D, --bindDN bindDN

Use the bind DN to authenticate to the server. This option is used when performing simple authentication and is not required if SASL authentication is to be used. The default value for this option is cn=Directory Manager.

SASL is not supported for a proxy server instance.

-h, --hostname hostname

Contact the server on the specified hostname or IP address. If this option is not provided, a default of localhost is used.

-j, --bindPasswordFile filename

Use the bind password in the specified file when authenticating to the server.

-K, --keyStorePath path

Use the client keystore certificate in the specified path.

-N, --certNickname nickname

Use the specified certificate for client authentication.

-o, --saslOption name = value

Use the specified options for SASL authentication.

SASL is not supported for a proxy server instance.

-p, --port port

Contact the server at the specified administration port. If this option is not provided, the administration port of the local configuration is used.

-P, --trustStorePath path

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.

-u, --keyStorePasswordFile filename

Use the password in the specified file to access the certificates in the client keystore. This option is only required if --keyStorePath is used.

-U, --trustStorePasswordFile filename

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

-X, --trustAll

Trust all server SSL certificates that the server presents. 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. If the client and the server are running in the same instance, there is no certificate interaction.

A.2.4.13 Command Input/Output Options

--commandFilePath path: Specify the full path to the file, where the equivalent non-interactive commands will be written when this command is run in interactive mode.
--displayCommand: Display the equivalent non-interactive option in the standard output when this command is run in interactive mode.
-F, --batchFilePath batchFilePath: Specifies the path to a file that contains a set of dsconfig commands to be executed. This option supports line splitting, backslash ('\'), quotes (") escaped quotes (\") inside a quoted string, and hash for comments ('#').
-n, --no-prompt: Use non-interactive mode. If some data in the command is missing, you are not prompted and the command will fail.
--noPropertiesFile: Indicate that the command will not use a properties file to get the default command-line options.
--sortMenuItems: Allows to sort the menu items if the interactive mode is used. The order is the user locale alphabetic order.
--propertiesFilePath path: 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.
-s, --script-friendly: Run in "script friendly" mode. Display the output in a format that can be easily parsed by a script.
-v, --verbose: Run in verbose mode, displaying diagnostics on standard output.

A.2.4.14 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.

A.2.4.15 Examples

The following examples show how to use the dsconfig command. For additional dsconfig examples, see Section 13.1, "Managing the Server Configuration With dsconfig."

Example A-12 Viewing the Global Help Subcommands and Global Options

The following command displays the available global help subcommands and global options for the server:

$ dsconfig --help

Example A-13 Viewing a Component's Subcommand Help Information

The following command displays the help information for the database subcommands:

$ dsconfig --help-database

Example A-14 Viewing Help on an Individual Subcommand

The following command displays the help information for the create-local-db-index subcommand:

$ dsconfig create-local-db-index --help

Example A-15 Displaying a Component's Properties

The following command displays the properties for local-db-index. If -t is not specified, the command displays the properties for all components.

$ dsconfig list-properties -c local-db-index
Option Types:

 r -- Property value(s) are readable
 w -- Property value(s) are writable
 m -- The property is mandatory
 s -- The property is single-valued
 a -- Administrative action is required for changes to take effect

Component       Type     Property                        Options  Syntax
------------------------------------------------------------------------------
local-db-index  generic  attribute                       r-ms-    OID
local-db-index  generic  index-entry-limit               rw-sa    INTEGER
local-db-index  generic  index-extensible-matching-rule  rw--a    LOCALE | OID
local-db-index  generic  index-type                      rwm-a    TYPE

The following command displays the properties for crypto-manager.

$ dsconfig list-properties -c crypto-manager
Option Types:

 r -- Property value(s) are readable
 w -- Property value(s) are writable
 m -- The property is mandatory
 s -- The property is single-valued
 a -- Administrative action is required for changes to take effect

Component       Type     Property                     Options  Syntax
----------------------------------------------------------------------
crypto-manager  generic  key-wrapping-transformation  rw-s-    STRING
crypto-manager  generic  ssl-cert-nickname            rw-sa    STRING
crypto-manager  generic  ssl-cipher-suite             rw---    STRING
crypto-manager  generic  ssl-encryption               rw-s-    BOOLEAN
crypto-manager  generic  ssl-protocol                 rw---    STRING

Example A-16 Parameters Supported by the -F, --batchFilePath subcommand

This example describes the various parameters supported by the -F, --batchFilePath subcommand.

Executing the -F, --batchFilePath subcommand using the line splitting approach. The file /tmp/batch contains the following set of commands:

create-workflow-element \
--type db-local-backend \
--set base-dn:cn=myexample,cn=com \
--set enabled:true \
--element-name myBackend

Running the -F, --batchFilePath subcommand.

dsconfig -X -j /path/pwd-file -F /tmp/batch -n

Executing the -F, --batchFilePath subcommand using quotes (") and escaped quotes (\") inside a quoted string. The file /tmp/batch contains the following set of commands:

set-access-control-handler-prop \
--add global-aci:"(targetattr != \"description || mail\") \
(version 3.0; acl \"Allow self entry modification except for \
description and mail attributes\"; allow (write)userdn =\"ldap:///self\";) "

Running the -F, --batchFilePath subcommand.

dsconfig -X  -j /path/pwd-file -F /tmp/batch -n

Example A-17 Using the sortMenuItem Option to Display Information as per Locale

This example describes how to display information as per the user locale using --sortMenuItems subcommand. In this example, the dsconfig command is run with and without the --sortMenuItems subcommand to highlight the difference in the way information is displayed. Step 2 displays the menu in US order, whereas Step 3 displays the menu in French order.

Set the desired locale using the following command:
```
export LC_ALL=fr_FR.UTF-8
```

Run the dsconfig command without the --sortMenuItems subcommand.

dsconfig -j /path/pwd-file

>>>> SpÃ©cifiez les paramÃ¨tres de connexion LDAP Oracle Unified Directory

Nom d'hÃ´te ou adresse IP du serveur d'annuaire [nixes] : 
NumÃ©ro de port d'administration du serveur d'annuaire [11444] : 
DN de liaison de l'administrateur [cn=Directory Manager] : 

>>>> Menu principal de la console de configuration Oracle Unified Directory

Que voulez-vous configurer ?

    1)   Gestionnaire de contrÃ´le      26)  Index VLV de base de donnÃ©es
         d'accÃ¨s                             locale
    2)   Gestionnaire de notification   27)  Editeur de journal
         de statuts de comptes               
    3)   Connecteur d'administration    28)  StratÃ©gie de conservation de
                                             journal
    4)   Gestionnaire d'alertes         29)  StratÃ©gie de rotation des
                                             journaux
    5)   Syntaxe d'attribut             30)  RÃ¨gle de correspondance
    6)   Mappeur de certificats         31)  Fournisseur de surveillance
    7)   Gestionnaire de connexions     32)  Groupe de rÃ©seaux
    8)   Gestionnaire de cryptage       33)  StratÃ©gie de qualitÃ© de service
                                             (QoS) du groupe de rÃ©seaux
    9)   Cible de dÃ©bogage             34)  GÃ©nÃ©rateur de mot de passe
    10)  Algorithme de distribution     35)  StratÃ©gie de mot de passe
    11)  Partition de distribution      36)  SchÃ©ma de stockage de mot de
                                             passe
    12)  Cache d'entrÃ©e                37)  Valideur de mot de passe
    13)  Gestionnaire d'opÃ©rations     38)  Plug-in
         d'extension                         
    14)  Extension                      39)  Racine de plug-in
    15)  Domaine de journal des         40)  Domaine de rÃ©plication
         modifications externe               
    16)  Domaine de passerelle          41)  Serveur de rÃ©plication
    17)  Configuration globale          42)  Nom distinctif (DN) racine
    18)  Index global                   43)  Back-end de la DSE racine
    19)  Domaine de rÃ©plication du     44)  Gestionnaire de mÃ©canisme SASL
         catalogue d'index globaux           
    20)  ImplÃ©mentation de groupe      45)  Fournisseur de synchronisation
    21)  Mappeur d'identitÃ©s           46)  Fournisseur de gestionnaire de
                                             sÃ©curisation
    22)  Fournisseur de gestionnaire    47)  Attribut virtuel
         de clÃ©s                             
    23)  Algorithme d'Ã©quilibrage de   48)  File d'attente de travaux
         charge                              
    24)  Route d'Ã©quilibrage de charge  49)  Workflow
    25)  Index de base de donnÃ©es       50)  ElÃ©ment de workflow

q)   quit

Entrez votre choix :

Run the dsconfig command with the --sortMenuItems subcommand.

dsconfig -j /path/pwd-file --sortMenuItems

>>>> SpÃ©cifiez les paramÃ¨tres de connexion LDAP Oracle Unified Directory

Nom d'hÃ´te ou adresse IP du serveur d'annuaire [nixes] : 
NumÃ©ro de port d'administration du serveur d'annuaire [11444] : 
DN de liaison de l'administrateur [cn=Directory Manager] : 

>>>> Menu principal de la console de configuration Oracle Unified Directory

Que voulez-vous configurer ?

    1)   Algorithme d'Ã©quilibrage de   26)  Gestionnaire de mÃ©canisme SASL
         charge                              
    2)   Algorithme de distribution     27)  Gestionnaire de notification de
                                             statuts de comptes
    3)   Attribut virtuel               28)  Groupe de rÃ©seaux
    4)   Back-end de la DSE racine      29)  GÃ©nÃ©rateur de mot de passe
    5)   Cache d'entrÃ©e                30)  ImplÃ©mentation de groupe
    6)   Cible de dÃ©bogage             31)  Index de base de donnÃ©es locale
    7)   Configuration globale          32)  Index global
    8)   Connecteur d'administration    33)  Index VLV de base de donnÃ©es
                                             locale
    9)   Domaine de journal des         34)  Mappeur d'identitÃ©s
         modifications externe               
    10)  Domaine de passerelle          35)  Mappeur de certificats
    11)  Domaine de rÃ©plication        36)  Nom distinctif (DN) racine
    12)  Domaine de rÃ©plication du     37)  Partition de distribution
         catalogue d'index globaux           
    13)  Editeur de journal             38)  Plug-in
    14)  ElÃ©ment de workflow           39)  Racine de plug-in
    15)  Extension                      40)  Route d'Ã©quilibrage de charge
    16)  File d'attente de travaux      41)  RÃ¨gle de correspondance
    17)  Fournisseur de gestionnaire    42)  SchÃ©ma de stockage de mot de
         de clÃ©s                             passe
    18)  Fournisseur de gestionnaire    43)  Serveur de rÃ©plication
         de sÃ©curisation                     
    19)  Fournisseur de surveillance    44)  StratÃ©gie de conservation de
                                             journal
    20)  Fournisseur de                 45)  StratÃ©gie de mot de passe
         synchronisation                     
    21)  Gestionnaire d'alertes         46)  StratÃ©gie de qualitÃ© de service
                                             (QoS) du groupe de rÃ©seaux
    22)  Gestionnaire d'opÃ©rations     47)  StratÃ©gie de rotation des
         d'extension                         journaux
    23)  Gestionnaire de connexions     48)  Syntaxe d'attribut
    24)  Gestionnaire de contrÃ´le      49)  Valideur de mot de passe
         d'accÃ¨s                             
    25)  Gestionnaire de cryptage       50)  Workflow

q)   quit

Entrez votre choix :

A.2.4.16 Exit Codes

An exit code of 0 indicates that the operation completed successfully. An exit code of 1 or greater indicates that an error occurred during processing.

A.2.4.17 Using a Properties File

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

The following options can be stored in a properties file:

bindDN
bindPasswordFile
certNickname
hostname
keyStorePasswordFile
keyStorePath
port
saslOption

SASL is not supported for a proxy server instance.
trustAll
trustStorePasswordFile
trustStorePath
useSSL
useStartTLS

Entries in the properties file have the following format:

toolname.propertyname=propertyvalue

For example:

dsconfig.trustAll=Yes

A.2.4.18 Location

UNIX and Linux: INSTANCE_DIR/OUD/bin/dsconfig
Windows: INSTANCE_DIR\OUD\bat\dsconfig.bat

A.2.4.19 Related Commands

Section A.2.7, "gicadm"

Section A.2.6, "dsreplication"

A.2.5 dsjavaproperties

The dsjavaproperties command specifies the JVM version and Java arguments that are used by each server command.

A.2.5.1 Synopsis

dsjavaproperties [options]

A.2.5.2 Description

The dsjavaproperties command can be used to specify the JVM version and Java arguments that are used by each server command. The JVM and Java arguments for each command are specified in a properties file, located at INSTANCE_DIR/OUD/config/java.properties. The properties file is not used unless you run the dsjavaproperties command. If you edit the properties file, you must run dsjavaproperties again for the new settings to be taken into account.

dsjavaproperties can be used to specify (among other arguments) whether a command runs using the JVM in -server mode or -client mode. By default, all client applications run in -client mode, and all of the server utilities run in -server mode. Generally, -server mode provides higher throughput than -client mode, at the expense of slightly longer startup times.

For certain commands (import-ldif, export-ldif, backup, and restore) you can also specify different Java arguments (and a different JVM) depending on whether the command is run in online or offline mode.

If the value of the overwrite-env-java-home property is set to false in the java.properties file, the OPENDS_JAVA_HOME environment variable takes precedence over the arguments specified in the properties file. Similarly, if the value of the overwrite-env-java-args property is set to false in the java.properties file, the OPENDS_JAVA_ARGS environment variable takes precedence over the arguments specified in the properties file.

A.2.5.3 Options

The dsjavaproperties command accepts an option in either its short form (for example, -Q) or their long form equivalent (for example, --quiet).

-Q, --quiet: Run in quiet mode. Quiet mode does not output progress information to standard output.
-?, -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.

A.2.5.4 Example

The following example shows how to use the export—ldif command.

Example A-18 Modifying a Script

This example shows how to change the export-ldif script to use a maximum JVM heap size of 256 Mbytes when the command is run with the server online.

Edit the INSTANCE_DIR/OUD/config/java.properties file and set the export-ldif.online arguments as follows:
```
export-ldif.online.java-args=-client -Xms8m -Xmx256m
```

Run the dsjavaproperties command for the change to take effect.

$ dsjavaproperties
 The script files were successfully updated.  The Oracle Unified Directory 
 command-line utilities will use the java properties specified in the 
 properties file INSTANCE_DIR/OUD/config/java.properties

A.2.5.5 Exit Codes

An exit code of 0 indicates that the operation completed successfully. A nonzero exit code indicates that an error occurred during processing.

A.2.5.6 Location

UNIX and Linux: INSTANCE_DIR/OUD/bin/dsjavaproperties
Windows: INSTANCE_DIR\OUD\bat\dsjavaproperties.bat

A.2.6 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.

A.2.6.1 Synopsis

dsreplication [subcommands] [options]

A.2.6.2 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 Section 13.3, "Managing Administration Traffic to the Server").

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
10) Enable External Changelog
11) Disable External Changelog

c)  cancel

Enter choice: 1
...

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

A.2.6.3 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.

disable-changelog

Disables the external change log for a set of base DNs. If there is no data to replicate, then all the associated replication configuration is removed. For more information about external change log, see Section 25.5, "Using the External Change Log." Suboptions are as follows:

-h, --hostname host

Directory server host name or IP address.

-p, --port port

The Directory Server administration port number.

-D, --bindDN bindDN

The DN to bind with the server where you want to configure the external change log. The default value is cn=Directory Manager.

enable-changelog

Creates an external change log for a set of base DNs. The external change log feature allows you to retrieve the modifications performed under a specific base DN. For more information about external change log, see Section 25.5, "Using the External Change Log." Suboptions are as follows:

-h, --hostname host

Directory server host name or IP address.

-p, --port port

The Directory Server administration port number.

-D, --bindDN bindDN

The DN to bind with the server where you want to configure the external change log. The default value is cn=Directory Manager.

-r, --replicationPort port

The port required to configure the change log. You have to specify this option only if the changelog (or replication) is not previously configured in the server. The default value is 8989.

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.

--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 that is 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 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 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. The value 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 sub command 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, acknowledgement signals 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, acknowledgement signals 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.

A.2.6.4 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.

A.2.6.5 Configuration Options

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

A.2.6.6 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.

-j, --adminPasswordFile bindPasswordFile

Use the global administrator password in the specified file when authenticating to the directory server.

-o, --saslOption name=value

Use the specified options for SASL authentication.

SASL is not supported for a proxy server instance.

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

-U, --TrustStorePasswordFile path

-K, --keyStorePath keyStorePath

Use the client keystore certificate in the specified path.

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

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

A.2.6.7 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.

A.2.6.8 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.

A.2.6.9 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 A-19 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" \
  --bindPasswordFile1 /tmp/pwd-file --replicationPort1 8989 \
  --host2 host2 --port2 4444 --bindDN2 "cn=Directory Manager" \
  --bindPasswordFile2 /tmp/pwd-file --replicationPort2 8989 \
  --adminUID admin --adminPasswordFile /tmp/pwd-file --baseDN "dc=example,dc=com" -X -n

Example A-20 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 --adminPasswordFile /tmp/pwd-file \
  --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 A-21 Obtaining the Directory Server Replication Status

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

$ dsreplication status --adminUID admin --adminPasswordFile /tmp/pwd-file -X --hostname host1 --port 4444

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]:ChangeLog[8]:Group ID[9]:Connected to[10]
-----------:--------:-------:-----------:-------:-------------:--------:-------:---------:------------:-----------:-------------------------
host1:4444 : 200000 : 0     : N/A       : 1898  : Disabled    :Trusted : N/A   : Normal  : Enabled    : 1         :host1/203.0.113.24:1898
host2:5444 : 200000 : 0     : N/A       : 2898  : Disabled    :Trusted : N/A   : Normal  : Enabled    : 1         :host2/203.0.113.24:2898

[1] The number of changes that are still missing on this server (and that have been applied to at least one 
    other server).
[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] Whether the external change log is enabled or not for the base DN on this server.
[9] The ID of the replication group to which the server belongs.
[10] The replication this server is connected to.

Example A-22 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 --adminPasswordFile /tmp/pwd-file \
-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.

Example A-23 Configuring the External Change Log on a Non-replicated Server

The following command enables the external change log on a non-replicated sever.

$ dsreplication status -h localhost -p 4444 -D "cn=directory manager" --adminPasswordFile /tmp/pwd-file -X -n

dc=example,dc=com - Replication Disabled
========================================
Server         : Entries : ChangeLog [8]
---------------:---------:--------------
localhost:4444 : 0       : Disabled

dsreplication enable-changelog -h localhost -p 4444 -D "cn=directory manager" --adminPasswordFile /tmp/pwd-file -X -b dc=example,dc=com -n

Establishing connections ..... Done.
Enabling Changelog on base DN 'dc=example,dc=com' ...... Done.
Configuring Replication port on server localhost:4444 ..... Done.

dsreplication status -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -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]:ChangeLog[8]:Group ID[9]:Connected to[10]
-----------:--------:-------:-----------:-------:-------------:--------:-------:---------:------------:----------:-------------------------
host1:4444 : 200000 : N/A   : N/A       : 1898  : Disabled    :Trusted : N/A   : Normal  : Enabled    : 1        : host1/203.0.113.24:1898

[1] The number of changes that are still missing on this server (and that have been applied to at least one 
    other server).
[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] Whether the external change log is enabled or not for the base DN on this server.
[9] The ID of the replication group to which the server belongs.
[10] The replication this server is connected to.

A.2.6.10 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 interactive mode.
4: Conflicting arguments.
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: The specified base DN cannot be purged.
28: Error launching purge historical.
29: Error loading configuration class in local purge historical.
30: Error starting server in local purge historical.
31: Timeout error in local purge historical.
32: Generic error executing local purge historical.
33: The trusted host was not found in the ADS.
34: The modified host was not found in the ADS.
35: The changelog cannot be enabled on this base DN.
36: The changelog cannot be disabled on this base DN.
37: An error occurred configuring the changelog.
38: The specified host was not found in the configuration.

A.2.6.11 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 Section A.1.2, "Using a Properties File With Server Commands."

The following options can be stored in a properties file:

adminUID
baseDN
certNickname
keyStorePasswordFile
keyStorePath
saslOption

SASL is not supported for a proxy server instance.
trustAll
trustStorePasswordFile
trustStorePath

Entries in the properties file have the following format:

toolname.propertyname=propertyvalue

For example:

dsreplication.baseDN=dc=example,dc=com

A.2.6.12 Location

UNIX and Linux: INSTANCE_DIR/OUD/bin/dsreplication
Windows: INSTANCE_DIR\OUD\bat\dsreplication.bat

A.2.6.13 Related Commands

Section A.2.4, "dsconfig"

A.2.7 gicadm

The gicadm command manages global indexes and global index catalogs.

This command is supported only for the proxy.

A.2.7.1 Synopsis

gicadm [subcommand] [options]

A.2.7.2 Description

The gicadm command enables you to create and delete a global index catalog, as well as add, modify, and delete global indexes in a global index catalog, and manage replication of global index catalogs. It also allows you to associate a global index to a distribution.

The gicadm command accesses the server over SSL through the administration connector.

A.2.7.3 Options

The gicadm command accepts the following options.

add-index

Adds a new global index to a global index catalog. Suboptions are as follows:

-c, --catalogName name. A unique identifier for the global index catalog. This is a required argument.

--attributeName attribute-name. The identifier for the global index attribute. This identifier should be unique in the context of the global index catalog and it is used to identify the global index.

associate

Associates a global index catalog to a distribution workflow element. Suboptions are as follows:

-c, --catalogName name. A unique identifier for the global index catalog. This is a required argument.

-d, --distributionWorkflowElement distribution-workflow-element. Name of the distribution workflow element object using this global index catalog, from which the global index catalog is to be disassociated.

create-catalog

Creates a new global index catalog. Suboptions are as follows:

-c, --catalogName name. A unique identifier for the global index catalog. This is a required argument.

delete-catalog

Deletes a global index catalog. Suboptions are as follows:

-c, --catalogName name. A unique identifier for the global index catalog. This is a required argument.

disable-replication

Disables replication on the specified server for the specified global index catalog and removes any references to this server from the other servers in the replication topology. Suboptions are as follows:

-c, --catalogName name. A unique identifier for the global index catalog. This is a required argument.

--adminUID adminUID. User ID of the global administrator used to bind to the server. For the enable-replication subcommand if no global administrator was defined previously the global administrator will be created using the provided data.

disassociate

Disassociates a global index catalog from a distribution workflow element. Suboptions are as follows:

enable-replication

Updates the server configuration to replicate the global index catalog and all its global indexes. If one of the specified servers already replicates the global index catalog for a given global index, executing this subcommand will update the configuration of all servers in the topology. Therefore, it is sufficient to execute this command once for each server added to the replication topology. Suboptions are as follows:

-c, --catalogName name. A unique identifier for the global index catalog. This is a required argument.

--adminUID adminUID. User ID of the global administrator used to bind to the server. For the enable-replication subcommand, if no global administrator was defined previously, the global administrator will be created using the provided data.

--adminPasswordFile bindPasswordFile. The file containing the password of the global administrator.

--localReplicationPort port. Replication port number of the first server whose content will be replicated.

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

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

--remoteHost host. Fully qualified directory server host name or IP address of the second server whose contents will be replicated.

--remoteBindDN bindDN. DN to use to bind to the second server whose content will be replicated. If not specified the global administrator will be used to bind.

--remoteBindPasswordFile bindPasswordFile. File containing the password to use to bind to the second server whose content will be replicated. If no bind DN was specified for the second server the password of the global administrator will be used to bind.

--remoteReplicationPort port. Replication port number of the second server whose content will be replicated.

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

export

Exports a global index catalog to file. Suboptions are as follows:

-c, --catalogName name. A unique identifier for the global index catalog. This is a required argument.

--exportDirectory directory. Path to the directory to be used to export the global index catalog. This is a required argument.

-a, --attributeName attribute-name. The name of the global index attribute. This option can be used multiple times to specify multiple indexed attributes. If this option is provided, any indexed attribute in the import source that does not match is skipped.

get-catalog-prop

Shows global index catalog properties. Suboptions are as follows:

-c, --catalogName name. A unique identifier for the global index catalog. This is a required argument.

--property property. The name of a property to be displayed.

-E,--record. Modifies the display output to show one property value per line.

get-index-prop

Shows index properties. Suboptions are as follows:

-c, --catalogName name. A unique identifier for the global index catalog. This is a required argument.

-a, --attributeName attribute-name. The identifier for the global index attribute. This identifier should be unique in the context of the global index catalog and it is used to identify the global index.

--property property. The name of a property to be displayed. Valid property names are:all, global-index-deleted-entry-retention-timeout, db-cleaner-min-utilization, db-log-file-max, db-checkpointer-bytes-interval, db-checkpointer-wakeup-interval, db-num-lock-tables, db-num-cleaner-threads, db-txn-no-sync, db-txn-write-no-sync, je-property, db-directory, db-directory-permissions, global-index-catalogs-shared-cache, and global-index-attribute.

import

Imports content of a file into a specified global index catalog. Suboptions are as follows:

-c, --catalogName name. A unique identifier for the global index catalog. This is a required argument.

--importDirectory directory. Path to the file to be used to import the global index catalog. This is a required argument.

--attributeName attribute-name. The identifier for the global index attribute. This identifier should be unique in the context of the global index catalog and it is used to identify the global index.

--append. Append to an existing global index rather than overwriting it.

initialize-replication

Initializes the replication of a global index catalog. All the replicated global index catalogs (part of the replication topology) can be initialized at once or the local global index catalog is initialized from a given global index catalog (also part of the replication topology). Suboptions are as follows:

-c, --catalogName name. A unique identifier for the global index catalog. This is a required argument.

--adminUID adminUID. User ID of the global administrator used to bind to the server. For the initialize-replication subcommand, if no global administrator was defined previously, the global administrator will be created using the provided data.

--fromServerPort port. Directory server port number of the source server whose contents will be used to initialize the destination server.

--fromServerHost host. Directory server hostname or IP address of the source server whose contents will be used to initialize the destination server.

--all. Initializes the contents of the global index attribute on all the servers whose contents is being replicated with the contents on the specified server.

list-catalogs

Lists the global index catalogs that have been defined. Suboptions are as follows:

--property property. The name of a property to be displayed. Valid property names are:all, replication-server, server-id, window-size, heartbeat-interval and group-id.

list-indexes

Lists the global indexes that have been defined in the global index catalog. Suboptions are as follows:

-c, --catalogName name. A unique identifier for the global index catalog. This is a required argument.

post-external-initialization

This subcommand must be called after initializing the contents of all the replicated global indexes using the import subcommand of this tool. It will use the generation id of the targeted instance as the valid one. Suboptions are as follows:

-c, --catalogName name. A unique identifier for the global index catalog. This is a required argument.

-a, --attributeName attribute-name. The identifier for the global index attribute. This option can be used multiple times to specify multiple indexed attributes. If this option is provided, any indexed attribute in the import source that does not match is skipped.

pre-external-initialization

This subcommand can be called before initializing the contents of all the replicated servers using the import subcommand of this tool. It will erase the replication change logs stored in the replication servers. Suboptions are as follows:

-c, --catalogName name. A unique identifier for the global index catalog. This is a required argument.

remove-index

Removes a global index from a global index catalog. Suboptions are as follows:

-c, --catalogName name. A unique identifier for the global index catalog. This is a required argument.

set-catalog-prop

Modifies the properties of the global index catalog. Suboptions are as follows:

-c, --catalogName name. A unique identifier for the global index catalog. This is a required argument.

--set property:value. Assigns a value to a property, where property is the name of the property and value is the single value to be assigned. Specify the same property multiple times to assign more than one value to it. Valid property names are: all, global-index-deleted-entry-retention-timeout, db-cleaner-min-utilization, db-log-file-max, db-checkpointer-bytes-interval, db-checkpointer-wakeup-interval, db-num-lock-tables, db-num-cleaner-threads, db-txn-no-sync, db-txn-write-no-sync, je-property, db-directory, db-directory-permissions, global-index-catalogs-shared-cache, and global-index-attribute.

--reset property. Resets a property back to its default values, where property is the name of the property to be reset. Valid property names are: all, global-index-deleted-entry-retention-timeout, db-cleaner-min-utilization, db-log-file-max, db-checkpointer-bytes-interval, db-checkpointer-wakeup-interval, db-num-lock-tables, db-num-cleaner-threads, db-txn-no-sync, db-txn-write-no-sync, je-property, db-directory, db-directory-permissions, global-index-catalogs-shared-cache, and global-index-attribute.

--add property:value. Adds a single value to a property, where property is the name of the property and value is the single value to be added.

--remove property:value. Removes a single value from a property, where property is the name of the property and value is the single value to be removed. Valid property names are: all, global-index-deleted-entry-retention-timeout, db-cleaner-min-utilization, db-log-file-max, db-checkpointer-bytes-interval, db-checkpointer-wakeup-interval, db-num-lock-tables, db-num-cleaner-threads, db-txn-no-sync, db-txn-write-no-sync, je-property, db-directory, db-directory-permissions, global-index-catalogs-shared-cache, and global-index-attribute.

set-index-prop

Modifies the properties of an index. Suboptions are as follows:

-c, --catalogName name. A unique identifier for the global index catalog. This is a required argument.

status-replication

Displays a list with the basic replication configuration of the global index catalog. If no global index catalog is specified, the information for all replicated global index catalogs is displayed. Suboptions are as follows:

-c, --catalogName name. A unique identifier for the global index catalog. This is a required argument.

--adminUID adminUID. User ID of the global administrator used to bind to the server. For the status-replication subcommand, if no global administrator was defined previously, the global administrator will be created using the provided data.

-s, --scriptFriendly. Use the script-friendly mode.

A.2.7.4 LDAP Connection Options

The gicadm command contacts the directory server over SSL through the administration connector (described in Section 13.3, "Managing Administration Traffic to the Server"). These connection options are used to contact the directory server.

-h, --hostname host: Directory server hostname or IP address.
-D, --bindDN bindDN: DN to use to bind to the server.
-j, --bindPasswordFile filename: The full path to the file containing the bind password.
-K, --keyStorePath path: Use the client keystore certificate in the specified path.
-N, --certNickname nickname: Use the certificate for SSL client authentication.
-o, --saslOptionname=value: SASL bind option.
-p, --port port: Directory server administration port number.
-P, --trustStorePath path: 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.
-u, --keyStorePasswordFile filename: Use the password in the specified file to access the certificates in the client keystore. This option is only required if --keyStorePath is used.
-U, --trustStorePasswordFile filename: 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 to access its contents (most trust stores do not require this).
-X, --trustAll: Trust any certificate that the server presents. This option can be used for testing purposes, but for security reasons, a trust store should be used to determine whether the client should accept the server certificate.
--connectTimeout timeout: Specifies the maximum duration of time (in milliseconds) that can be taken to establish a connection. Use Oto indicate no time out. The default value is 30000 milliseconds.

A.2.7.5 Command Input/Output Options

--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.
-v, --verbose: Run in verbose mode, displaying diagnostics on standard output.

A.2.7.6 General Options

-?, -H, --help: Displays command-line usage information for the command and exit without making any attempt to stop or restart the directory server.
-V, --version: Displays the version information for the directory server.

A.2.7.7 Examples

The following examples show how to use the gicadm command.

Note:

The following examples for creating a global index catalog, adding a global index, and associating a global index catalog to a distribution are the three steps required to use a global index catalog in a distribution deployment.

Example A-24 Viewing the Global Help Subcommands and Global Options

The following command displays the available global Help subcommands and global options for managing the global index catalog:

$ gicadm --help

Example A-25 Viewing Help on an Individual Subcommand

The following command displays the help information for the create-catalog subcommand:

$ gicadm create-catalog --help

Example A-26 Using gicadm to Create a Global Index Catalog

You must have deployed the proxy with distribution before running this command.

$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j /path/pwd-file -X \
create-catalog --catalogName myCatalog

Example A-27 Using gicadm to Add a Global Index to a Global Index Catalog

You must have deployed the proxy with distribution before running this command. Moreover, you must already have created the global index catalog before running this command.

$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j /tmp-pwd-file -X \
add-index --catalogName myCatalog --attributeName telephoneNumber

Example A-28 Using gicadm to Associate a Global Index Catalog to a Distribution

You must have deployed the proxy with distribution before running this command. Moreover, you must already have created the global index catalog before running this command.

$ gicadm -h localhost -p 4444 -D "cn=Directory Manager" -j /tmp-pwd-file -X \
associate --catalogName myCatalog --distributionWorkflowElement myDistributionName

A.2.7.8 Exit Codes

An exit code of 0 indicates that the operation completed successfully. A nonzero exit code indicates that an error occurred during processing.

A.2.7.9 Location

UNIX and Linux: INSTANCE_DIR/OUD/bin/gicadm
Windows: INSTANCE_DIR\OUD\bat\gicadm.bat

A.2.7.10 Related Commands

dsconfig
split-ldif

A.2.8 manage-tasks

The manage-tasks command manages and monitors tasks that have been scheduled to run on the directory server.

This command is not supported for the proxy.

A.2.8.1 Synopsis

manage-tasks [options]

A.2.8.2 Description

The manage-tasks command can be used to manage and monitor tasks that have been scheduled to run on the directory server. Tasks are scheduled by providing the appropriate scheduling information when the task is invoked (see Section 13.4, "Configuring Commands As Tasks"). The manage-tasks command can be used to list tasks that are currently scheduled or that have already been executed. In addition, you can get more detailed information about a task's scheduled and execution time, its log messages, and its options.

The manage-tasks command can only be run on an online server instance, and accesses the task back end over SSL through the administration connector (described in Section 13.3, "Managing Administration Traffic to the Server".)

A.2.8.3 Options

The manage-tasks command accepts an option in either its short form (for example, -c taskID) or its long form equivalent (for example, --cancel taskID).

-c, --cancel taskID: Specify a particular task to cancel.
-i, --info taskID: Display information for a particular task.
-s, --summary: Print a summary of tasks.

A.2.8.4 LDAP Connection Options

-D, --bindDN bindDN: Use the bind DN to authenticate to the directory server. This option is used when performing simple authentication and is not required if SASL authentication is used. The default value for this option is cn=Directory Manager.
-h, --hostname hostname: Contact the directory server on the specified hostname or IP address. If this option is not provided, a default of localhost is used.
-j, --bindPasswordFile filename: Use the bind password in the specified file when authenticating to the directory server.
-K, --keyStorePath path: Use the client keystore certificate in the specified path.
-N, --certNickname nickname: Use the specified certificate for client authentication.
-o, --saslOption name=value: Use the specified options for SASL authentication.
-p, --port port: Contact the directory server at the specified administration port. If this option is not provided, a default administration port of 4444 is used.
-P, --trustStorePath path: 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.
-u, --keyStorePasswordFile filename: Use the password in the specified file to access the certificates in the client keystore. This option is only required if --keyStorePath is used.
-U, --trustStorePasswordFile filename: 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).
-X, --trustAll: Trust all server SSL certificates that the directory server presents. 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.

A.2.8.5 Command Input/Output Options

-n,--no-prompt: Use non-interactive mode. If required option values are missing, you are not prompted and the command will fail.
--noPropertiesFile: Indicates that a properties file is not used to obtain the default command-line options.
--propertiesFilePath path: Specify the path to the properties file that contains the default command-line options.

A.2.8.6 General Options

-?, -H, --help: Display command-line usage information for the command and exit without making any attempt to manage tasks.
-V, --version: Display the version information for the directory server and exit rather than attempting to run this command.

A.2.8.7 Examples

The following examples show how to use the manage-tasks command.

Example A-29 Displaying a Summary of Scheduled Tasks

The following command displays a list of scheduled tasks:

$ manage-tasks -h localhost -p 4444 -D "cn=directory manager" -j /path/pwd-file \
  -X -s

  ID                Type     Status
  -------------------------------------------------
  2008101610361710  Backup   Completed successfully
  2008101610403710  Restore  Completed successfully
  2008101610442610  Restore  Waiting on start time

Example A-30 Obtaining Task Information

The following command returns information about a specific task:

$ manage-tasks -h localhost -p 4444 -D "cn=directory manager" -j /path/pwd-file \
  -X -i 2008101610442610
  Task Details
  -------------------------------------------------------
  ID                        2008101610442610
  Type                      Restore
  Status                    Waiting on start time
  Scheduled Start Time      Jan 25, 2009 12:15:00 PM SAST
  Actual Start Time
  Completion Time
  Dependencies              None
  Failed Dependency Action  None
  Email Upon Completion     admin@example.com
  Email Upon Error          admin@example.com

  Restore Options
  ----------------------------------
  Backup Directory  /backup/userRoot

Example A-31 Canceling a Scheduled Task

The following command cancels a scheduled task. The command uses the --no-prompt option to run in non-interactive mode.

$ manage-tasks -h localhost -p 4444 -D "cn=directory manager" -j /path/pwd-file \
  -X -c 2008101610442610
Task 2008101610442610 canceled

A.2.8.8 Exit Codes

An exit code of 0 indicates that the operation completed successfully. An exit code of 1 indicates that an error occurred during processing.

A.2.8.9 Using a Properties File

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

A.2.8.10 Location

UNIX and Linux: OUD_ORACLE_HOME/bin/manage-tasks
Windows: OUD_ORACLE_HOME\bat\manage-tasks.bat

A.2.9 oudCopyConfig

The oudCopyConfig command is used to obtain a copy of an existing configuration, from the source environment.

For more information about moving from a test to production environment, see Chapter 27, "Moving From a Test to a Production Environment."

A.2.9.1 Synopsis

oudCopyConfig [options]

A.2.9.2 Description

To obtain a copy of an existing configuration, run the oudCopyConfig command in the source environment.

The oudCopyConfig command performs the following actions:

It creates an archive (archivePath) that contains the required configuration data to move the test instance (instHomePath) to a production environment. The -archiveLoc option specifies the full path to the archive.
It creates a move plan in the archive.
Logs any messages to log_directory. If not specified, the default location of logged messages is the system temporary directory.

A.2.9.3 Options

The oudCopyConfig command accepts an option in the form:

-javaHome, javaHomePath: Absolute path of JDK.
-al, -archiveLoc archivePath: Absolute path of archive location. It contains the required configuration data to move the test instance (instHomePath) to a production environment.
-sih, -sourceInstanceHomeLoc instHomePath: Absolute path of an existing instance that you want to copy to a production environment.
-h, -help: Show this help message and exit. This parameter is optional.
-ldl, -logDirLoc logPath: Existing log directory location. Default location is system temporary location. This parameter is optional.

A.2.9.4 Examples

The following examples show how to use the oudCopyConfig command.

Example A-32 Obtaining a Copy of an Existing Configuration

The following command obtains a copy of an existing configuration.

$ OUD_ORACLE_HOME/bin/oudCopyConfig -javaHome /usr/jdk \
-sourceInstanceHomeLoc /local/asinst_1 -archiveLoc /tmp/oud.jar \
-logDirLoc /tmp/logs

Example A-33 Running the Help Command Option

$ OUD_ORACLE_HOME/bin/oudCopyConfig -javaHome /usr/jdk -help

A.2.9.5 Location

UNIX and Linux: OUD_ORACLE_HOME/bin/oudCopyConfig
Windows: OUD_ORACLE_HOME\bat\oudCopyConfig.bat

A.2.9.6 Related Commands

Section A.2.10, "oudExtractMovePlan"
Section A.2.11, "oudPasteConfig"

A.2.10 oudExtractMovePlan

The oudExtractMovePlan command is used to create an editable version of the configuration in a file named moveplan.xml, in the location specifed by the -planDirLoc argument. This directory must exist, and be writable.

For more information about moving from a test to production environment, see Chapter 27, "Moving From a Test to a Production Environment."

A.2.10.1 Synopsis

oudExtractMovePlan [options]

A.2.10.2 Description

You can modify certain configuration parameters by editing the move plan. A move plan is an XML file that exposes customizable parameters during the move across environments.

The move plan is generated when you run the oudCopyConfig command and is used by the oudPasteConfig command to duplicate the configuration.

A.2.10.3 Options

The oudExtractMovePlan command accepts an option in the form:

-javaHome, javaHomePath: Absolute path of JDK.
-al, -archiveLoc archivePath: Absolute path of archive location.
-pdl, -planDirLoc planPath: Absolute path to directory where moveplan is to be extracted. The name of move plan file is moveplan.xml.
-h, -help: Show this help message and exit. This parameter is optional.
-ldl, -logDirLoc logPath: Existing log directory location. Default location is system temporary location. This parameter is optional.

A.2.10.4 Examples

The following examples show how to use the oudExtractMovePlan command.

Example A-34 Editing the Configuration

The following command allows you to edit the configuration.

$ OUD_ORACLE_HOME/bin/oudExtractMovePlan -javaHome /usr/jdk \
-al /tmp/oud.jar -pdl /tmp -logDirLoc /tmp/logs

Example A-35 Running the Help Command Option

$ OUD_ORACLE_HOME/bin/oudExtractMovePlan -javaHome /usr/jdk -help

A.2.10.5 Location

UNIX and Linux: OUD_ORACLE_HOME/bin/oudExtractMovePlan
Windows: OUD_ORACLE_HOME\bat\oudExtractMovePlan.bat

A.2.10.6 Related Commands

Section A.2.9, "oudCopyConfig"
Section A.2.11, "oudPasteConfig"

A.2.11 oudPasteConfig

The oudPasteConfig command is used to paste the configuration in the target environment.

For more information about moving from a test to production environment, see Chapter 27, "Moving From a Test to a Production Environment."

A.2.11.1 Synopsis

oudPasteConfig [options]

A.2.11.2 Description

To obtain the configuration in the target environment, run the oudPasteConfig command.

The oudPasteConfig command creates a new server instance with the configuration obtained from the archive and the amended move plan.

A.2.11.3 Options

The oudPasteConfig command accepts an option in the form:

-javaHome, javaHomePath: Absolute path of JDK.
-al, -archiveLoc archivePath: Absolute path of archive location.
-mpl, -movePlanLoc planPath: Absolute path to the moveplan extracted during extract plan operation.
-tih, -targetInstanceHomeLoc instHomePath: Absolute path of instance home under which Oracle Unified Directory configuration will be restored.
-toh, -targetOracleHomeLoc oracleHomePath: Absolute path of the Oracle home associated with the instance home.
-tin, -targetInstanceName instanceName: Target instance name. If specified, must be consistent with target instance path. This parameter is optional.
-h, -help: Show this help message and exit. This parameter is optional.
-ldl, -logDirLoc logPath: Existing log directory location. Default location is system temporary location. This parameter is optional.

A.2.11.4 Examples

The following examples show how to use the oudPasteConfig command.

Example A-36 Pasting the Configuration

The following command allows you to paste the configuration.

$ OUD_ORACLE_HOME/bin/oudPasteConfig -javaHome /usr/jdk -al /tmp/oud.jar \
-tih /tmp/asinst_2 -toh /tmp/Oracle_OUD1 \
-mpl /tmp/moveplan.xml -tin asinst_2

Example A-37 Running the Help Command Option

$ OUD_ORACLE_HOME/bin/oudPasteConfig -javaHome /usr/jdk -help

A.2.11.5 Location

UNIX and Linux: OUD_ORACLE_HOME/bin/oudPasteConfig
Windows: OUD_ORACLE_HOME\bat\oudPasteConfig.bat

A.2.11.6 Related Commands

Section A.2.9, "oudCopyConfig"
Section A.2.10, "oudExtractMovePlan"

A.2.12 oud-replication-gateway-setup

The oud-replication-gateway-setup command is used to setup the replication gateway instance.

A.2.12.1 Synopsis

oud-replication-gateway-setup [options]

A.2.12.2 Description

The oud-replication-gateway-setup command installs and configures a replication gateway instance, including specifying the ports on which it will listen, the DN and password for the initial root user, and the base DN for the replication gateway data. The replication gateway allows replication to work between a set of Oracle Directory Server Enterprise Edition servers and a set of Oracle Unified Directory servers.

The utility can be run in one of the following modes:

Graphical-user interface (GUI) mode. GUI mode is the default and recommended installation option. The oud-replication-gateway-setup GUI provides an easy interface for installing and configuring replication servers in replicated multi-network environments. GUI mode also allows for easy server setup using SSL or StartTLS if desired.

The utility launches the graphical installer and creates the Oracle Unified Directory instance in OUD_BASE_LOCATION/INSTANCE_DIR. The default instance directory name is asinst_1, with subsequent instances on the same server named asinst_2, asinst_3, and so on.
Command-line interface (CLI) mode. The command-line mode is either interactive or non-interactive. The interactive CLI mode prompts you for any required information before the configuration begins, and is used with the --cli option, or if no GUI is available.

The utility launches the command-line installer and creates the Oracle Unified Directory instance in OUD_BASE_LOCATION/INSTANCE_DIR. The default instance directory name is asinst_1, with subsequent instances on the same server named asinst_2, asinst_3, and so on.

The non-interactive CLI mode enables you to set up the server without user intervention. Use the --no-prompt and the --quiet options to suppress interactivity and output information, respectively.

When the oud-replication-gateway-setup command is run without any options, it starts in GUI mode but falls back to interactive command-line mode if no GUI is available. To run the setup in interactive command-line mode use the --cli option. Note that no options are allowed if the command is run in GUI mode.

A.2.12.3 Options

The oud-replication-gateway-setup command accepts an option in either its short form (for example, -i) or its long form equivalent (for example, --cli).

-i, --cli: Use the command line install. If not specified the graphical interface will be launched. The rest of the options (excluding help and version) will only be taken into account if this option is specified.

A.2.12.4 Replication Gateway Configuration Options

-h, --hostname hostname: The fully-qualified name of the host where the replication gateway will be installed. The Oracle Directory Server Enterprise Edition and Oracle Unified Directory servers in the replication topology must be able to access this hostname. If this option is not provided, a default of localhost is used.
--adminConnectorPort port: Specifies the port on which the administration connector should listen for administration traffic. For information about the administration connector, see Section 13.3, "Managing Administration Traffic to the Server." The configuration and administration tools use this port to connect to the replication gateway. The default value is 4444.
--replicationPortForLegacy port: Specifies the port that is used by the Oracle Directory Server Enterprise Edition server to communicate with the replication gateway to replicate contents.
-S, --skipPortCheck: Do not make any attempt to determine whether the specified port is available. Normally, when this option is not present, the oud-replication-gateway-setup command verifies if that port is in use or not, and if not in use then the user running the command can bind to that port. With the --skipPortCheck option, the oud-replication-gateway-setup command skips the port check.
-D, --rootUserDN rootUserDN: DN for the initial root user for the replication gateway.
-j, --rootUserPasswordFile rootUserPasswordFile: Path to a file containing the password for the initial root user for the replication gateway.
-O, --doNotStart: Do not start the replication gateway when the configuration is completed.
-b, --baseDN baseDN: Specify the base DN of the data to be replicated between the Oracle Unified Directory and the Oracle Directory Server Enterprise Edition server. Multiple base DN's can be provided by using this option multiple times.

A.2.12.5 Oracle Directory Server Enterprise Edition Server Options

--hostNameLegacy hostname: The fully-qualified name of the host or IP address of the Oracle Directory Server Enterprise Edition server whose contents will be replicated.
--portLegacy port: Specifies the port number of the Oracle Directory Server Enterprise Edition server whose contents will be replicated. This port is used by the replication mechanism to replicate contents.
--bindDNLegacy bindDN: Specifies the DN that is used to bind the Oracle Directory Server Enterprise Edition server whose contents will be replicated.
--bindPasswordFileLegacy bindPasswordFile: Specifies the file that stores the password that is used to bind the Oracle Directory Server Enterprise Edition server whose contents will be replicated.
--secureReplicationLegacy: Specifies if the replication updates between the Oracle Directory Server Enterprise Edition server and the replication gateway are sent encrypted or not. If you enable this option, then you must specify the certificate to be used by the server using the options in Replication Gateway Security Options and the port specified using argument --portLegacy must be an LDAP port.
--clientAuthenticationToLegacy: Uses client authentication to send replication updates from the replication gateway to the Oracle Directory Server Enterprise Edition server. You can use this argument only if attribute --secureReplicationLegacy is used.
--certFileForClientAuthenticationToLegacy certificateFile: Specifies the file that contains the certificate to be used in client authentication mode when the replication gateway connects to the Oracle Directory Server Enterprise Edition server to send replication updates. The file must contain the certificate in X.509 format.
--doNotSendUpdatesToLegacyServer: Do not propagate the updates made in the Oracle Unified Directory servers to the Oracle Directory Server Enterprise Edition server. If you use this option the changes made directly in the Oracle Unified Directory servers will not be propagated to the Oracle Directory Server Enterprise Edition servers replication topology.
--doNotUpdateTrustStoreWithLegacyCertsArg: If you specify this argument and the replication gateway sends replication updates to the Oracle Directory Server Enterprise Edition server using an encrypted communication (specified using the --secureReplicationLegacy argument), then you will have to update the trust store used by the replication gateway with the server certificate of the Oracle Directory Server Enterprise Edition server for replication to work.
--clientAuthenticationFromLegacy: Uses client authentication to send replication updates from the Oracle Directory Server Enterprise Edition server to the replication gateway. You can use this argument only if attribute --secureReplicationLegacy is used.

A.2.12.6 Replication Gateway Security Options

--generateSelfSignedCertificate: Generates a self-signed certificate that the replication gateway will use as server certificate when accepting encrypted connections from the Oracle Directory Server Enterprise Edition server.
--usePkcs11Keystore: Use a certificate in a PKCS#11 token that the replication gateway will use as server certificate when accepting encrypted connections from the Oracle Directory Server Enterprise Edition server.
--useJavaKeystore keyStorePath: Specifies the path of a Java Key Store (JKS) that contains a certificate that the replication gateway will use as server certificate when accepting encrypted connections from the Oracle Directory Server Enterprise Edition server.
--useJCEKS keyStorePath: Specifies the path of a JCEKS that contains a certificate that the replication gateway will use as server certificate when accepting encrypted connections from the Oracle Directory Server Enterprise Edition server.
--usePkcs12keyStore keyStorePath: Path of a PKCS#12 key store that contains the certificate that the replication gateway will use as server certificate when accepting encrypted connections from the Oracle Directory Server Enterprise Edition server.
--gatewayKeyStorePasswordFile keyStorePasswordFile: Specifies the file containing the certificate key store PIN. It is required to access the key store that contains the certificate (JKS, JCEKS, PKCS#12, or PKCS#11) that the replication gateway will use as server certificate. This is required when the replication gateway is configured for encrypted replication communication with the Oracle Directory Server Enterprise Edition server.
--gatewayCertNickname nickname: Specifies the nickname of the certificate that the replication gateway will use when accepting encrypted connections from the Oracle Directory Server Enterprise Edition server.

A.2.12.7 Oracle Unified Directory Server Options

--hostNameNg hostname: The fully-qualified name of the host or IP address of the Oracle Unified Directory server whose contents will be replicated.
--portNg port: Specifies the port number of the Oracle Unified Directory server whose contents will be replicated.
--bindDNNg bindDN: Specifies the DN that is used to bind the Oracle Unified Directory server whose contents will be replicated. If this attribute is not specified the global administrator is used to bind.
--bindPasswordFileNg bindPasswordFile: Specifies the file that stores the password that is used to bind the Oracle Unified Directory server whose contents will be replicated. If no bind DN is specified for this server the password of the global administrator is used to bind.
--replicationPortNg port: Specifies the port used by the replication mechanism in the Oracle Unified Directory server to communicate with other Oracle Unified Directory servers. You have to specify this option only if you have not configured replication for the provided Oracle Unified Directory server.
--secureReplicationNg: Specifies whether or not the communication through the replication port of the Oracle Unified Directory server is encrypted or not. This option is only taken into account if replication is not configured on the Oracle Unified Directory server.
-I, --adminUID adminUID: Specifies the user ID of the Global Administrator to use to bind to the Oracle Unified Directory server. If you have not defined a Global Administrator in the Oracle Unified Directory, then the Global Administrator is created using the provided data. The default value is admin.
--adminPasswordFile bindPasswordFile: The file that contains the password of the global administrator.

A.2.12.8 Secure Connection Options

-o, --saslOption name=value

These are SASL bind options.

SASL is not supported for a proxy instance.

-X, --trustAll

-P, --trustStorePath path

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.

-U, --trustStorePasswordFile path

-K, --keyStorePath path

Use the client keystore certificate in the specified path.

-u, --keyStorePasswordFile filename

Use the password in the specified file to access the certificates in the client keystore. This option is only required if --keyStorePath is used.

-N, --certNickname nickname

Use the specified certificate for SSL client 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.

A.2.12.9 Command Input/Output Options

-n, --no-prompt: Run setup in non-interactive mode. If some data in the command is missing, the user will not be prompted and the command will fail.
-Q, --quiet: Run in quiet mode. No output will be generated unless a significant error occurs during the process.
-v, --verbose: Run in verbose mode, displaying diagnostics on standard output.
--noPropertiesFile: Indicate that the command will not use a properties file to get the default command-line options.
--propertiesFilePath path: Specify the path to the properties file that contains the default command-line options.

A.2.12.10 General Options

-?, -H, --help: Display command-line usage information for the command and exit without making any attempt to stop or restart the server.
--version: Display the version information for the directory server and exit rather than attempting to run this command.

A.2.12.11 Examples

The following examples show how to use the replication server commands.

Example A-38 Running oud-replication-gateway-setup in GUI Mode

The following command runs an installation in GUI mode:

$ oud-replication-gateway-setup

The utility launches the graphical installer and creates the Oracle Unified Directory instance in OUD_BASE_LOCATION/INSTANCE_DIR. The default instance directory name is asinst_1, with subsequent instances on the same server named asinst_2, asinst_3, and so on. To specify a different instance name, set the INSTANCE_NAME environment variable before you run the setup, for example:

$ export INSTANCE_NAME=my-oud-instance

The GUI is launched and provides several screens that walk you through setting up your replication server in standalone or replicated environments. You also have the option to set up SSL or StartTLS certificates.

Example A-39 Running oud-replication-gateway-setup in Interactive Mode From the Command Line

The oud-replication-gateway-setup command can be run in interactive mode, where you are prompted for installation options. To run oud-replication-gateway-setup in interactive mode, type the following command:

$ oud-replication-gateway-setup --cli

The command prompts you for the required setup values. Press Enter or Return to accept the default, or enter a value at the prompt.

The utility launches the command-line installer and creates the Oracle Unified Directory instance in OUD_BASE_LOCATION/INSTANCE_DIR. The default instance directory name is asinst_1, with subsequent instances on the same server named asinst_2, asinst_3, and so on. To specify a different instance name, set the INSTANCE_NAME environment variable before you run the setup, for example:

$ export INSTANCE_NAME=my-oud-instance

A.2.12.12 Exit Codes

0: Successful completion or successful no-op.
1: Error unexpected. Potential bug.
2: Error user data. Cannot parse options, or data provided by user is not valid.
4: Error initializing server.

A.2.12.13 Using a Properties File

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

All the oud-replication-gateway-setup options can be stored in a properties file. Entries in the properties file have the following format:

toolname.propertyname=propertyvalue

For example:

oud-replication-gateway-setup.hostname=grevalon:1444

A.2.12.14 Log Files

The oud-replication-gateway-setup command writes a log file named oud-setup-IDnumber where IDnumber is a decimal number. The log files are located at these paths:

UNIX (Solaris): /var/tmp/
Linux: /tmp/
Windows: %TEMP%

By default, this folder is C:\Documents and Settings\User\Local Settings\Temp.

A.2.12.15 Location

The oud-replication-gateway-setup command is located at these paths:

UNIX and Linux: OUD_BASE_LOCATION/OUD_ORACLE_HOME/oud-replication-gateway-setup
Windows: OUD_BASE_LOCATION\OUD_ORACLE_HOME\oud-replication-gateway-setup.bat

A.2.12.16 Related Commands

Section A.2.13, "oud-setup"
Section A.2.14, "oud-proxy-setup"

A.2.13 oud-setup

The oud-setup command installs and minimally configures a directory server instance.

This command sets up a directory server instance. For information about setting up a proxy server instance, see Section A.2.14, "oud-proxy-setup."

A.2.13.1 Synopsis

oud-setup [options]

A.2.13.2 Description

The oud-setup command installs and configure a directory server instance, including specifying the ports on which it will listen, the DN and password for the initial root user, the base DN for the directory data, and the manner in which the database should be populated. It can be run in one of the following modes:

Graphical-user interface (GUI) mode. GUI mode is the default and recommended installation option. The oud-setup GUI provides an easy interface for installing and configuring standalone directory servers or replication servers in replicated multi-network environments. GUI mode also allows for easy server setup using SSL or StartTLS if desired.

The utility launches the graphical installer and creates the Oracle Unified Directory instance in OUD_BASE_LOCATION/INSTANCE_DIR. The default instance directory name is asinst_1, with subsequent instances on the same server named asinst_2, asinst_3, and so on.
Command-line interface (CLI) mode. The command-line mode is either interactive or non-interactive. The interactive CLI mode prompts you for any required information before the configuration begins, and is used with the --cli option, or if no GUI is available.

The utility launches the command-line installer and creates the Oracle Unified Directory instance in OUD_BASE_LOCATION/INSTANCE_DIR. The default instance directory name is asinst_1, with subsequent instances on the same server named asinst_2, asinst_3, and so on.

The non-interactive CLI mode enables you to set up the server without user intervention. Use the --no-prompt and the --quiet options to suppress interactivity and output information, respectively.

When the oud-setup command is run without any options, it starts in GUI mode but falls back to interactive command-line mode if no GUI is available. To run oud-setup in command-line mode, use the --cli option. The options that can be provided are listed below. Note that no options are allowed if the command is run in GUI mode.

A.2.13.3 Options

The oud-setup command accepts an option in either its short form (for example, -a) or its long form equivalent (for example, --addBaseEntry).

-a, --addBaseEntry: Indicates whether to create the base entry in the directory server database.
-i, --cli: Run the setup command in command-line interactive mode rather than in GUI mode. If setup is run without the --cli option, it cannot accept other options.
-b, --baseDN baseDN: Use the base DN for user information in the Directory Server. The default value for this option is dc=example,dc=com. Multiple base DNs can be specified by providing this option multiple times.
-l, --ldifFile filename: Use the specified LDIF file to populate the database. Data can be imported from multiple files by providing this option multiple times, in which case the files are processed in the order they are provided in the option list. This option must not be used in conjunction with either the --addBaseEntry or --sampleData option. If this option is not provided, then the database is left empty.
-R, --rejectFile filename: Write rejected entries to the specified file. Rejected entries occur if they do not comply with the default schema during an import using the -l or --ldifFile option.
--skipFile filename: Write skipped entries to the specified file. Skipped entries occur if entries cannot be placed under any specified base DN during an import using the -l or --ldifFile option.
-d, --sampleData number-of-entries: Populate the database with the specified number of sample user entries. The entries are generated by using the MakeLDIF facility of the import command and are based on the default example.template template. This option must not be used in conjunction with either --addBaseEntry or --ldifFile. If this option is not provided, then the database is left empty.
--eus: Configure the server for Oracle's Enterprise User Security (EUS).
-p,--ldapPort port: Contact the directory server at the specified port. If it is not provided, then the default port of 1389 as non-root and 389 as root is used.
--adminConnectorPort port: Specifies the port on which the administration connector should listen for administration traffic. For information about the administration connector, see Section 13.3, "Managing Administration Traffic to the Server." The default value is 4444.
-x, --jmxPort port: Specify the port for a JMX MBeans server connection. The default value for this option is 1689.
-S, --skipPortCheck: Do not make any attempt to determine whether the specified port is available. Normally, when this option is not present, the oud-setup command verifies that the port is not in use and that the user running the setup command can bind to that port. With the --skipPortCheck option, the oud-setup command skips the port check.
-D, --rootUserDN rootUserDN: Use the specified root user DN to authenticate the directory server. This option is used when performing simple authentication and is not required if SASL authentication is used. The default value for this option is cn=Directory Manager.
-j, --rootUserPasswordFile filename: Specifies the file containing the password for the initial root user while authenticating the directory server.
-O, --doNotStart: Do not start the directory server when the configuration is completed.
-q, --enableStartTLS: Enable StartTLS to allow secure communication with the directory server by using the LDAP port.
-Z, --ldapsPort port: Contact the directory server at the specified port for LDAP SSL (LDAPS) communication. The LDAPS port will be configured and SSL will be enabled only if this option is explicitly specified. The default value is 1636.
--generateSelfSignedCertificate: Generate a self-signed certificate that the directory server should use when accepting SSL-based connection or performing StartTLS negotiation.
-h, --hostname host: Name of the directory server host or IP address that is used to generate the self-signed certificate. This argument is considered only if the self-signed certificate argument, --generateSelfSignedCertificate is specified
--usePkcs11Keystore: Use a certificate in a PKCS#11 format that the server should use when accepting SSL-based connections or performing StartTLS negotiation
--useJavaKeystore path: Specify the path to the Java Keystore (JKS) that contains the server certificate.
--useJCEKS path: Specify the path to the Java Cryptography Extension Keystore (JCEKS) that contains the server certificate.
--usePkcs12Keystore path: Specify the path to the PKCS#12 keystore that contains the server certificate.
-u, --keyStorePasswordFile filename: Use the password in the specified file to access the certificate keystore. A password is required when you specify an existing certificate (JKS, JCEKS, PKCS#11, or PKCS#12) as a server certificate.
-N, --certNickname nickname: Use the specified certificate for SSL or StartTLS client authentication.
-e, --enableWindowsService: Enable the directory server as a Windows service. For Windows-platforms only.

A.2.13.4 Command Input/Output Options

-n, --no-prompt: Run setup 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 path: 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.
-v, --verbose: Run in verbose mode, displaying diagnostics on standard output.

A.2.13.5 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 directory server and exit rather than attempting to run this command.

A.2.13.6 Examples

The following examples show how to use the directory server commands.

Example A-40 Running oud-setup in GUI Mode

The following command runs an installation in GUI mode:

$ oud-setup

The GUI is launched and provides several screens that walk you through setting up your directory server in standalone or replicated environments. You also have the option to set up SSL or StartTLS certificates.

The utility creates the Oracle Unified Directory instance in OUD_BASE_LOCATION /INSTANCE_DIR. The default instance directory name is asinst_1, with subsequent instances on the same server named asinst_2, asinst_3, and so on. To specify a different instance name, set the INSTANCE_NAME environment variable before you run the setup, for example:

$ export INSTANCE_NAME=my-oud-instance

Example A-41 Running oud-setup in Interactive Mode From the Command Line

The oud-setup command can be run in interactive mode, where you are prompted for installation options. To run oud-setup in interactive mode, type the following command:

$ oud-setup --cli

The command prompts you for the required setup values. Press Enter or Return to accept the default, or enter a value at the prompt.

$ export INSTANCE_NAME=my-oud-instance

Example A-42 Running oud-setup in Non-Interactive CLI Mode

The non-interactive CLI mode enables you to create installation scripts with the oud-setup command when many directory server instances must be configured for large replicated environments. This mode requires the --no-prompt and --quiet options to be provided. If no option is present, the oud-setup command defaults to interactive mode.

The following command runs the installation in non-interactive (--no-prompt) and quiet (-Q) modes. It sets the LDAP port (-p), the administration connector port (--adminConnectorPort), the root DN (-D), the file containing the root DN password (-j), and adds a base entry (-a) with the specified base DN (-b),

$ oud-setup --cli --no-prompt -Q -p 1389 --adminConnectorPort 4444 \
  -D "cn=Directory Manager" -j /path/pwd-file -a -b dc=example,dc=com

Example A-43 Running oud-setup in Non-Interactive CLI Mode With LDIF Import

The following command runs the installation in non-interactive (--no-prompt) and quiet (-Q) modes. It sets the LDAP port (-p), the administration connector port (--adminConnectorPort), the root DN (-D), the file containing the root DN password (-j), and adds the baseDN (-b) with data imported from an LDIF file (-l).

$ oud-setup --cli --no-prompt -Q -p 1389 --adminConnectorPort 4444 \
  -D "cn=Directory Manager" -j /path/pwd-file -b dc=example,dc=com \
  -l "/home/ldif/company.ldif"

Example A-44 Running oud-setup in Non-Interactive Mode With Sample Entry Generation

The following command runs the installation in non-interactive (--no-prompt) and quiet (-Q) modes. It sets the LDAP port (-p), the administration connector port (--adminConnectorPort), the root DN (-D), the file containing the root DN password (-j), the baseDN (-b) and generates 2000 sample entries (-d).

$ oud-setup --cli --no-prompt -Q -p 1389 --adminConnectorPort 4444 \
  -D "cn=Directory Manager" -j /path/pwd-file -b dc=example,dc=com -d 2000

Example A-45 Running oud-setup on Windows

The following command enables the directory server to run as a Windows service (-e). It sets the LDAP port (-p), the administration connector port (--adminConnectorPort), the JMX port (-x), the rootDN (-D), the file containing the root DN password (-j), and the baseDN (-b), and generates 10000 sample entries.

C:\> oud-setup.bat --cli -e -p 1389 --adminConnectorPort 4444 -x 1689 \
  -D "cn=Directory Manager" -j /path/pwd-file -b dc=example,dc=com -d 10000

The utility launches the graphical installer and creates the Oracle Unified Directory instance in OUD_BASE_LOCATION/INSTANCE_DIR. The default instance directory name is asinst_1, with subsequent instances on the same server named asinst_2, asinst_3, and so on. To specify a different instance name, set the INSTANCE_NAME environment variable before you run the setup, for example:

$ export INSTANCE_NAME=my-oud-instance

A.2.13.7 Exit Codes

0: Successful completion or successful no-op.
1: Error unexpected. Potential bug.
2: Error user data. Cannot parse options, or data provided by user is not valid.
4: Error initializing server.

A.2.13.8 Using a Properties File

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

The following options can be stored in a properties file:

certNickname
hostname
keyStorePasswordFile

All the preceding oud-setup options can be stored in a properties file. Entries in the properties file have the following format:

toolname.propertyname=propertyvalue

For example:

oud-setup.hostname=grevalon:1444

A.2.13.9 Log Files

The oud-setup command writes a log file named oud-setup-IDnumber where IDnumber is a decimal number. The log files are located at these paths:

UNIX (Solaris): /var/tmp/
Linux: /tmp/
Windows: %TEMP%

By default, this folder is C:\Documents and Settings\User\Local Settings\Temp.

A.2.13.10 Location

The oud-setup command is located at these paths:

UNIX and Linux: OUD_BASE_LOCATION/OUD_ORACLE_HOME/oud-setup
Windows: OUD_BASE_LOCATION\OUD_ORACLE_HOME\oud-setup.bat

A.2.13.11 Related Commands

Section A.2.12, "oud-replication-gateway-setup"
Section A.2.14, "oud-proxy-setup"

A.2.14 oud-proxy-setup

The oud-proxy-setup command manages the setup and configuration of a proxy server instance.

A.2.14.1 Synopsis

oud-proxy-setup [options]

A.2.14.2 Description

The oud-proxy-setup command installs and configures a proxy server instance, including specifying the ports on which it will listen, the DN and password for the initial root user, the base DN for the directory data, authentication methods, as well load balancing, distribution, and a global index catalog, depending on the deployment chosen.

The oud-proxy-setup can only be launched once. It can be run in one of the following modes:

Graphical-user interface (GUI) mode. GUI mode is the default and recommended installation option. The setup GUI provides an easy interface for defining and deploying the proxy instance.

The utility launches the graphical installer and creates the proxy instance in OUD_BASE_LOCATION/INSTANCE_DIR. The default instance directory name is asinst_1, with subsequent instances on the same server named asinst_2, asinst_3, and so on.
Command-line interface (CLI) mode. The command-line setup defines the proxy port, host name, and security configuration. If you specify the --cli option with oud-proxy-setup then you must provide the required values in the command line, else the default values are used. If you do not provide any value for a parameter that has no default value then the setup fails, and an error message is displayed.

The utility launches the command-line installer and creates the proxy instance in OUD_BASE_LOCATION/INSTANCE_DIR. The default instance directory name is asinst_1, with subsequent instances on the same server named asinst_2, asinst_3, and so on.

The proxy setup CLI mode prompts the user to accept the license. Use the --no-prompt option to automatically accept the license.

A.2.14.3 Options

The oud-proxy-setup command accepts an option in either its short form (for example, -i) or its long form equivalent (for example, --cli).

-i, --cli: Use the command line install. If not specified the graphical interface will be launched. The rest of the options (excluding help and version) will only be taken into account if this option is specified.
-p, --ldapPort port: Port on which the Directory Server should listen for LDAP communication. The default value is 389.
--adminConnectorPort port: Port on which the Administration Connector should listen for communication. The default value is 4444.
-S, --skipPortCheck: Skip the check to determine whether the specified ports are usable.
-D, --rootUserDN rootUserDN: DN for the initial root user for the proxy server.
-j, --rootUserPasswordFile rootUserPasswordFile: Path to a file containing the password for the initial root user for the proxy server.
-q, --enableStartTLS: Enable StartTLS to allow secure communication with the server using the LDAP port.
-Z, --ldapsPort port: Port on which the Directory Server should listen for LDAP SSL (LDAPS) communication. The LDAPS port will be configured and SSL will be enabled only if this argument is explicitly specified. The default value is 636.
--generateSelfSignedCertificate: Generate a self-signed certificate that the server should use when accepting SSL-based connections or performing StartTLS negotiation.
--usePkcs11keyStore keyStorePath: Path of a PKCS#11 key store containing the certificate that the server should use when accepting SSL-based connections or performing StartTLS negotiation.
--useJavaKeystore keyStorePath: Path of a Java Key Store (JKS) containing a certificate to be used as the server certificate.
--useJCEKS keyStorePath: Path of a JCEKS containing a certificate to be used as the server certificate.
--usePkcs12keyStore keyStorePath: Path of a PKCS#12 key store containing the certificate that the server should use when accepting SSL-based connections or performing StartTLS negotiation.
-u, --keyStorePasswordFile keyStorePasswordFile: Certificate key store PIN file. A PIN is required when you specify to use an existing certificate (JKS, JCEKS, PKCS#12, or PKCS#11) as server certificate.
-N, --certNickname nickname: Nickname of the certificate that the server should use when accepting SSL-based connections or performing StartTLS negotiation.
-O, --doNotStart: Do not start the server when the configuration is completed.

A.2.14.4 Command Input/Output Options

-Q, --quiet: Run in quiet mode. No output will be generated unless a significant error occurs during the process.
-v, --verbose: Use verbose mode
--propertiesFilePath path: Specify the path to the properties file that contains the default command-line options.
--noPropertiesFile: Indicate that a properties file will not be used to get the default command-line options.
-n, --no-prompt: Perform an installation in non-interactive mode, for license acceptance only. If some data in the command is missing the user will not be prompted and the command will fail.

A.2.14.5 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 directory server and exit rather than attempting to run this command.

A.2.14.6 Examples

The following examples show how to use the oud-proxy-setup command.

Example A-46 Running oud-proxy-setup in GUI Mode

The following command runs an installation in GUI mode:

$ oud-proxy-setup

The utility launches the graphical installer and creates the proxy instance in OUD_BASE_LOCATION/INSTANCE_DIR. The default instance directory name is asinst_1, with subsequent instances on the same server named asinst_2, asinst_3, and so on. To specify a different instance name, set the INSTANCE_NAME environment variable before you run the setup, for example:

$ export INSTANCE_NAME=my-oud-proxy-instance

Example A-47 Running oud-proxy-setup in Non-Interactive CLI Mode

The non-interactive CLI mode enables you to create installation scripts with the setup command when many proxy server instances must be configured for large replicated environments. This mode requires the --no-prompt and --quiet options to be provided. If no option is present, the setup command defaults to interactive mode.

The following command runs the installation in non-interactive (--no-prompt) and quiet (-Q) modes. It sets the LDAP port (-p), the administration connector port (--adminConnectorPort), the root DN (-D), and the file containing the root DN password (-j).

$ oud-proxy-setup --cli --no-prompt -Q -p 1389 --adminConnectorPort 4444 \
  -D "cn=Directory Manager" -j /path/pwd-file

The utility launches the command-line installer and creates the proxy instance in OUD_BASE_LOCATION/INSTANCE_DIR. The default instance directory name is asinst_1, with subsequent instances on the same server named asinst_2, asinst_3, and so on. To specify a different instance name, set the INSTANCE_NAME environment variable before you run the setup, for example:

$ export INSTANCE_NAME=my-oud-proxy-instance

A.2.14.7 Exit Codes

An exit code of 0 indicates that the operation completed successfully. A nonzero exit code indicates that an error occurred during processing.

A.2.14.8 Log Files

The oud-proxy-setup command writes a log file named oud-proxy-setup.log, once the setup in complete. The log file is located at these paths:

UNIX (Solaris):/var/tmp/
Linux:/tmp/
Windows: The %TEMP% folder. By default, this folder is C:\Documents and Settings\user\Local Settings\Temp

A.2.14.9 Location

UNIX and Linux: OUD_BASE_LOCATION/OUD_ORACLE_HOME/oud-proxy-setup
Windows: OUD_BASE_LOCATION\OUD_ORACLE_HOME\oud-proxy-setup.bat

A.2.14.10 Related Commands

Section A.2.12, "oud-replication-gateway-setup"

Section A.2.17, "stop-ds"

A.2.15 start-ds

The start-ds command starts an installed server instance.

A.2.15.1 Synopsis

start-ds [options]

A.2.15.2 Description

The start-ds command is used to start the server and to provide general server information.

You can run start-ds without any options, which starts the server as a background process. In this case, the script will not exit until the server has either started successfully or has encountered an error that prevents it from starting.

On UNIX systems, the server will not start if it cannot log the process ID at INSTANCE_DIR/logs/server.pid. Ensure that the file is writable by the user account that the server uses.

A.2.15.3 Options

The start-ds command accepts an option in either its short form (for example, -N) or its long form equivalent (for example, --nodetach).

-L, --useLastKnownGoodConfig: Attempt to start using the configuration that was in place at the last successful startup (if it is available) rather than using the current active configuration.
-N, --nodetach: Start the server as a foreground process that does not detach from the terminal. When the server is running in this mode, it can be stopped by using the stop-ds command from another window, or by pressing Control+C in the terminal window in which the server is running.
-s, --systemInfo: Display general information about the system on which the server is installed, including the instance and installation paths, and then exit rather than attempting to start the server.
-t, --timeout seconds: Wait no longer than the maximum time (in seconds) before the command returns. (The server continues the startup process, regardless). A value of 0 indicates an infinite timeout, which means that the command returns only when the server startup is completed. The default value is 60 seconds. This option cannot be used with the -N, --nodetach option.

A.2.15.4 Command Input/Output Options

-Q, --quiet: Run in quiet mode. No output is generated unless a significant error occurs during the process.

A.2.15.5 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.

A.2.15.6 Examples

The following examples show how to use the start—ds command.

Example A-48 Starting the Server

The following command starts the server:

$ start-ds

Example A-49 Starting the Server as a Foreground Process

The following command starts the server as a foreground process. You can stop the server by running the stop-ds command from another window or by pressing Control+C in the terminal window in which the server is running.

$ start-ds -N

[25/Jul/2007:10:39:17 -0500] category=CORE severity=NOTICE msgID=458887
msg=The Directory Server has started successfully

A.2.15.7 Exit Codes

Exit Code	Description
`0`	Server started successfully.
`1`	Check error. Generated from incompatible options.
`98`	Server already started.
`99`	Server must start as a detached process.
`100`	Server must start as a non-detached process.
`101`	Server must start as a Windows service.
`102`	Server must start as a detached process and it is being called from a Windows service.

A.2.15.8 Location

UNIX and Linux: INSTANCE_DIR/OUD/bin/start-ds
Windows: INSTANCE_DIR\OUD\bat\start-ds.bat

A.2.15.9 Related Commands

Section A.2.17, "stop-ds"

A.2.16 status

The status command displays basic server status information.

A.2.16.1 Synopsis

status [options]

A.2.16.2 Description

The status command can be used to display basic server information, such as the status of the server (started or stopped), the configured connection handlers, or the list of defined back ends and suffixes.

If the server is started, the status command connects to the server over SSL, through the administration connector.

For more information, see Section 13.3, "Managing Administration Traffic to the Server."

If the server is stopped, you must run this command as a user with file system access rights to read the configuration files (particularly the config.ldif file).

Note:

Certain monitoring data can only be displayed when the server is running (for example, the number of entries in a back end).

A.2.16.3 LDAP Connection Options

The status command contacts the server over SSL through the administration connector (described in Section 13.3, "Managing Administration Traffic to the Server"). These connection options are used to contact the server.

-D, --bindDN bindDN

-j, --bindPasswordFile filename

Use the bind password in the specified file when authenticating to the server.

-K, --keyStorePath path

Use the client keystore certificate in the specified path.

-N, --certNickname nickname

Use the specified certificate for client authentication.

-o, --saslOption name=value

Use the specified options for SASL authentication.

SASL is not supported for a proxy server instance.

-P, --trustStorePath path

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.

-u, --keyStorePasswordFile filename

Use the password in the specified file to access the certificates in the client keystore. This option is only required if --keyStorePath is used.

-U, --trustStorePasswordFile filename

-X, --trustAll

A.2.16.4 Command Input/Output Options

-n, --no-prompt: Use non-interactive mode. If some data in the command is missing, you are not prompted and the command will fail.
--noPropertiesFile: Indicate that the command should not use a properties file to get the default command-line options.
--propertiesFilePath path: Specify the path to the properties file that contains the default command-line options.
-r, --refresh period: When this argument is specified, the status command will display its contents periodically. Used to specify the period (in seconds) between two displays of the status.
-s, --script-friendly: Run in "script friendly" mode. Display the output in a format that can be easily parsed by a script.

A.2.16.5 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.

A.2.16.6 Examples

The following examples show how to use the status command.

Example A-50 Displaying the Server Status

The following example displays the current status of a standalone server that is currently online:

$ status -D "cn=directory manager" -j /path/pwd-file -X -n

          --- Server Status ---
Server Run Status:        Started
Open Connections:         1

          --- Server Details ---
Host Name:                hostname
Administrative Users:     cn=Directory Manager
Installation Path:        /path/OracleUnifiedDirectory
Instance Path:            /path/asinst_1/OUD
Version:                  Oracle Unified Directory 11.1.1.5.0
Java Version:             1.6.0_24
Administration Connector: Port 4444 (LDAPS)

          --- Connection Handlers ---
Address:Port : Protocol    : State
-------------:-------------:---------
--           : LDIF        : Disabled
8989         : Replication : Enabled
0.0.0.0:161  : SNMP        : Disabled
0.0.0.0:636  : LDAPS       : Disabled
0.0.0.0:1389 : LDAP        : Enabled
0.0.0.0:1689 : JMX         : Disabled

          --- Data Sources ---
Base DN:                      dc=example,dc=com
Backend ID:                   userRoot
Entries:                      7
Replication:                  Enabled
Missing Changes:              0
Age Of Oldest Missing Change: not available

A.2.16.7 Exit Codes

An exit code of 0 indicates that the operation completed successfully. A nonzero exit code indicates that an error occurred during processing.

A.2.16.8 Using a Properties File

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

The following options can be stored in a properties file:

bindDN
bindPasswordFile
certNickname
hostname
keyStorePasswordFile
keyStorePath
port
saslOption

SASL is not supported for a proxy server instance.
trustAll
trustStorePasswordFile
trustStorePath

Entries in the properties file have the following format:

toolname.propertyname=propertyvalue

For example:

status.bindPasswordFile=/path/pwd-file

A.2.16.9 Location

UNIX and Linux: INSTANCE_DIR/OUD/bin/status
Windows: INSTANCE_DIR\OUD\bat\status.bat

A.2.17 stop-ds

The stop-ds command stops a server instance.

A.2.17.1 Synopsis

stop-ds [options]

A.2.17.2 Description

The stop-ds command is used to stop or restart the server. It can operate on either a local or remote server instance.

The ability to perform a local stop of the server is currently only available on UNIX based systems. When run locally, stop-ds sends a kill signal to the server process. This method of stopping the server is used if stop-ds is run without any options and if a PID file (INSTANCE_DIR/OUD/logs/server.pid) exists.

The remote shutdown mechanism issues an LDAP request to create a task entry in the server. The command can be run from any system that can communicate with the server (local or remote). It can also be used to restart the server. In this case, the server does an "in-core" restart, which reinitializes itself without shutting down the JVM.

When it is run remotely, stop-ds communicates with the server over SSL, through the administration connector. For more information, see Section 13.3, "Managing Administration Traffic to the Server."

A.2.17.3 Options

The stop-ds command accepts an option in either its short form (for example, -D bindDN) or its long form equivalent (for example, --bindDN bindDN).

-r,--stopReason reason: Provide a human-readable reason for the shutdown. If a reason is provided, it appears in the server's error log, and is provided to shut down plug-ins and shut down listeners.
-R,--restart: Restart the server rather than shutting it down. If the --restart option is used along with authentication options, the server will reinitialize itself without shutting down the JVM. Because the JVM is not stopped, any configuration changes that require a JVM restart will not take effect. If the --restart option is used without authenticating, the server will first stop, then start. A new process will replace the original server.
-t,--stopTime time: Indicates the date and time at which the shutdown operation begins as a server task, expressed in the format YYYYMMDDhhmmss. A value of 0 causes the shutdown to be scheduled for immediate execution. When this option is used, the operation is scheduled to start at the specified time, after which this command exits immediately.
-Y,--proxyAs authzID: Use authorization control during the shutdown request. The value provided for this option should be an authorization ID, which can be in the form dn: followed by a user DN or u: followed by a user name. Clients will use the proxy authorization v2 control as described in RFC 4370 (http://www.ietf.org/rfc/rfc4370.txt).

A.2.17.4 LDAP Connection Options

The stop-ds command contacts the server over SSL through the administration connector (described in Section 13.3, "Managing Administration Traffic to the Server"). These connection options are used to contact the server.

-D, --bindDN bindDN

-h, --hostname hostname

Contact the server on the specified hostname or IP address. If this option is not provided, a default of localhost is used.

-j, --bindPasswordFile filename

Use the bind password in the specified file when authenticating to the server.

-K, --keyStorePath path

Use the client keystore certificate in the specified path.

-N, --certNickname nickname

Use the specified certificate for client authentication.

-o, --saslOption name=value

Use the specified options for SASL authentication.

SASL is not supported for a proxy server instance.

-p, --port port

Contact the server at the specified administration port. If this option is not provided, a default administration port of 4444 is used.

-P, --trustStorePath path

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.

-u, --keyStorePasswordFile filename

Use the password in the specified file to access the certificates in the client keystore. This option is only required if --keyStorePath is used.

-U, --trustStorePasswordFile filename

-X, --trustAll

A.2.17.5 Command Input/Output Options

--noPropertiesFile: Indicate that a properties file will not be used to get the default command-line options.
--propertiesFilePath path: 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.

A.2.17.6 General Options

-?, -H, --help: Display command-line usage information for the command and exit without making any attempt to stop or restart the server.
--version: Display the version information for the server and exit rather than attempting to run this command.

A.2.17.7 Examples

The following examples show how to use the stop-ds command.

Example A-51 Stopping a Server Locally

The following command stops the server:

$ stop-ds

Example A-52 Stopping a Server Remotely

The following command stops a remote server instance.

$ stop-ds -h remotehost -p 4444 -D "cn=directory manager" -j /path/pwd-file -X

Example A-53 Restarting a Server Remotely

The following command restarts a remote server instance.

$ stop-ds -R -h remotehost -p 4444 -D "cn=directory manager" -j /path/pwd-file -X

A.2.17.8 Exit Codes

Exit Code	Description
`0`	Server stopped successfully.
`98`	Server already stopped.
`99`	Server must be started.
`100`	Server must be stopped using a system call.
`101`	Server must be restarted using a system call.
`102`	Server must be stopped using a protocol.
`103`	Server must be stopped as a Windows service.
`104`	Server must be restarted as a Windows service.

A.2.17.9 Using a Properties File

The server supports the use of a properties file that passes in any default option values used with the stop-ds command. The properties file is convenient when working in different configuration environments, especially in scripted or embedded applications.

For more information, see Section A.1.2, "Using a Properties File With Server Commands."

The following options can be stored in a properties file:

bindDN
bindPasswordFile
certNickname
hostname
keyStorePasswordFile
keyStorePath
saslOption

SASL is not supported for a proxy server instance.
trustAll
trustStorePasswordFile
trustStorePath

Entries in the properties file have the following format:

toolname.propertyname=propertyvalue

For example:

stop-ds.trustAll=yes

A.2.17.10 Location

UNIX and Linux: INSTANCE_DIR/OUD/bin/stop-ds
Windows: INSTANCE_DIR\OUD\bat\stop-ds.bat

A.2.17.11 Related Commands

Section A.2.15, "start-ds"

A.2.18 uninstall

The uninstall command is used to uninstall the server instance. It is applicable for directory servers, proxy servers, and replication gateway servers. The command removes the server instance, and not the software.

A.2.18.1 Synopsis

uninstall [options]

A.2.18.2 Description

The uninstall command is used to uninstall a server instance. It can be run in one of the following modes:

Graphical-user interface (GUI) mode. GUI mode is the default and recommended uninstallation option. The uninstall GUI provides an easy interface for removing instance files.
Command-line interface (CLI) mode. The command-line mode is either interactive or non-interactive. The interactive CLI mode prompts you for any required information before the uninstallation begins, and is used with the --cli option, or if no GUI is available.

The non-interactive CLI mode enables you to uninstall the instance files without user intervention. Use the --no-prompt and the --quiet options to suppress interactivity and output information, respectively.

Whether running in GUI mode or in command-line mode, uninstall lists the components that you can remove. If uninstall cannot remove all of the instance files, it displays a message that lists any directories that are still present.

Depending on the type of server installed, you are presented with different uninstall options. These are broadly categorized into the following:

Section A.2.18.3, "Removing a Directory Server"
Section A.2.18.4, "Removing a Proxy Server"
Section A.2.18.5, "Removing a Replication Gateway Server"

Note:

For any instance (directory server, proxy, or replication gateway) type that you decide to remove, the uninstall procedure also stops the server. In addition, for a server instance that is part of a replication topology, the uninstall procedure removes the server that is under deletion from that topology. On a Windows platform, if the instance was installed as a windows service, the windows service is unregistered.

A.2.18.3 Removing a Directory Server

This section describes the options to remove a directory server instance.

A.2.18.3.1 Options

The uninstall command accepts an option in either its short form (for example, -i) or its long form equivalent (for example, --cli).

-i, --cli: Use the command line install. If not specified the graphical interface will be launched. The rest of the options (excluding help and version) will only be taken into account if this option is specified.
-a, --remove-all: Remove all components of the server (this option is not compatible with the rest of the remove options).
-l, --server-libraries: Remove server libraries and administrative tools.
-d, --databases: Remove all database content.
-L, --log-files: Remove all log files.
-c, --configuration-files: Remove configuration files.
-b, --backup-files: Remove all backup files.
-e, --ldif-files: Remove LDIF files.
-f, --forceOnError: Specifies whether the uninstall should continue if there is an error updating references to this server in remote server instances or not. This argument can only be used with the --no-prompt argument.

A.2.18.3.2 LDAP Connection Options

-I, --adminUID user-ID: Specify the user ID of the global administrator to bind to the server.
-j, --bindPasswordFile filename: Use the bind password in the specified file when authenticating to the directory server.
-o, --saslOption name=value: Use the specified options for SASL authentication.
-X, --trustAll: Trust any certificate that the server presents. This option can be used for testing purposes, but for security reasons, a trust store should be used to determine whether the client should accept the server certificate.
-P, --trustStorePath path: 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.
-U, --trustStorePasswordFile filename: 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 to access its contents (most trust stores do not require this).
-K, --keyStorePath path: Use the client keystore certificate in the specified path.
-u, --keyStorePasswordFile filename: Use the password in the specified file to access the certificates in the client keystore. This option is only required if --keyStorePath is used.
-N, --certNickname nickname: Use the certificate for SSL client authentication.
--connectTimeout timeout: Maximum length of time that can be taken to establish a connect in milliseconds. Use 0 to specify no timeout. The default value is 30000.
-h, --referencedHostName host: Specify the name of this host (or IP address) as it is referenced in remote servers for replication.

A.2.18.4 Removing a Proxy Server

This section describes the options to remove a proxy server instance.

A.2.18.4.1 Options

The uninstall command accepts an option in either its short form (for example, -i) or its long form equivalent (for example, --cli).

-i, --cli: Use the command line install. If not specified the graphical interface will be launched. The rest of the options (excluding help and version) will only be taken into account if this option is specified.
-a, --remove-all: Remove all components of the server (this option is not compatible with the rest of the remove options).
-l, --server-libraries: Remove server libraries and administrative tools.
-L, --log-files: Remove all log files.
-c, --configuration-files: Remove configuration files.
-b, --backup-files: Remove all backup files.
-e, --ldif-files: Remove LDIF files.
-f, --forceOnError: Specifies whether the uninstall should continue if there is an error updating references to this server in remote server instances or not. This argument can only be used with the --no-prompt argument.

A.2.18.4.2 LDAP Connection Options

-I, --adminUID user-ID: Specify the user ID of the global administrator to bind to the server.
-j, --bindPasswordFile filename: Use the bind password in the specified file when authenticating to the directory server.
-o, --saslOption name=value: Use the specified options for SASL authentication.
-X, --trustAll: Trust any certificate that the server presents. This option can be used for testing purposes, but for security reasons, a trust store should be used to determine whether the client should accept the server certificate.
-P, --trustStorePath path: 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.
-U, --trustStorePasswordFile filename: 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 to access its contents (most trust stores do not require this).
-K, --keyStorePath path: Use the client keystore certificate in the specified path.
-u, --keyStorePasswordFile filename: Use the password in the specified file to access the certificates in the client keystore. This option is only required if --keyStorePath is used.
-N, --certNickname nickname: Use the certificate for SSL client authentication.
--connectTimeout timeout: Maximum length of time that can be taken to establish a connect in milliseconds. Use 0 to specify no timeout. The default value is 30000.
-h, --referencedHostName host: Specify the name of this host (or IP address) as it is referenced in remote servers for replication.

A.2.18.5 Removing a Replication Gateway Server

This section describes the options for removing an instance of the replication gateway server.

A.2.18.5.1 Options

The uninstall command accepts an option in either its short form (for example, -i) or its long form equivalent (for example, --cli).

-i, --cli: Use the command line install. If not specified the graphical interface will be launched. The rest of the options (excluding help and version) will only be taken into account if this option is specified.
-f, --forceOnError: Specifies whether the uninstall should continue if there is an error updating references to this server in remote server instances or not. This argument can only be used with the --no-prompt argument.

A.2.18.5.2 Gateway Connection Options

-h, --hostname hostname: The fully-qualified name of the host where the replication gateway is installed. This name must be the one provided during the setup of the replication gateway.

A.2.18.5.3 Oracle Unified Directory Server Connection Options

-I, --adminUID adminUID: User ID of the Global Administrator to use to bind to the Oracle Unified Directory server. If no Global Administrator was defined previously in the new generation server, then provide a Bind DN. The default value is admin.
--adminPasswordFile bindPasswordFile: File containing the password of the Global Administrator (or of the bind DN) to use to bind to the Oracle Unified Directory server.

A.2.18.5.4 Oracle Directory Server Enterprise Edition Server Connection Options

--bindDNLegacy bindDN: Specifies the DN that is used to bind theOracle Directory Server Enterprise Edition server whose contents whose contents are replicated through the replication gateway. The default value is cn=Directory Manager.
--bindPasswordFileLegacy bindPasswordFile: Specifies the file that stores the password that is used to bind theOracle Directory Server Enterprise Edition server whose contents are replicated through the replication gateway.

A.2.18.5.5 Secure Connection Options

-o, --saslOption name=value

These are SASL bind options.

SASL is not supported for a proxy server instance.

-X, --trustAll

-P, --trustStorePath path

Use the 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.

-U, --trustStorePasswordFile path

Use the password in the specified file to access the certificates in the 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).

-K, --keyStorePath path

Use the keystore certificate in the specified path.

-u, --keyStorePasswordFile filename

Use the password in the specified file to access the certificates in the keystore. This option is only required if --keyStorePath is used.

-N, --certNickname nickname

Use the specified certificate for SSL client 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.

A.2.18.6 Command Input/Output Options

-n, --no-prompt: Run setup in non-interactive mode. If some data in the command is missing, the user will not be prompted and the command will fail.
-Q, --quiet: Run in quiet mode. No output will be generated unless a significant error occurs during the process.
-v, --verbose: Run in verbose mode, displaying diagnostics on standard output.
--noPropertiesFile: Indicate that the command will not use a properties file to get the default command-line options.
--propertiesFilePath path: Specify the path to the properties file that contains the default command-line options.

A.2.18.7 General Options

-?, -H, --help: Display command-line usage information for the command and exit without making any attempt to stop or restart the server.
--version: Display the version information for the directory server and exit rather than attempting to run this command.

A.2.18.8 Examples

The following examples show how to use the server commands.

Example A-54 Uninstalling by Using the Graphical Uninstaller

The following command opens the Uninstaller GUI and prompts you to select the components that must be deleted:

$ uninstall

Example A-55 Uninstalling by Using the Command Line

The following command prompts you to indicate whether all components, or specific components, should be removed, and then runs the uninstall command. If the server is running, you are prompted to stop the server before continuing.

$ uninstall --cli

Example A-56 Uninstalling in Non-Interactive CLI Mode

This mode enables you to create an uninstallation script with the uninstall command. It requires the --no-prompt (-n) and --quiet (-Q) options to be provided. If no option is present, the uninstall command defaults to interactive mode. Both, -n and -Q options work in the CLI mode only.

The following command uninstalls all instance components in non-interactive CLI mode.

$ uninstall --cli -a -n -Q

A.2.18.9 Exit Codes

The following exit codes are applicable for a directory server and a proxy server:

0: Successful.
1: User cancelled the operation.
2: User provided invalid data.
3: Error accessing file system (reading/writing).
5: Error during the configuration of the Directory Server.
7: Error starting the Oracle Unified Directory server.
8: Error stopping the Oracle Unified Directory server.
9: Error disabling the Windows service.
10: Application specific error.
11: Error invoking an Oracle Unified Directory tool.
12: Bug.
13: Java version non-compatible.
14: User provided invalid input.
50: Print Version.
51: Print Usage.
100: Return code for errors that are non-specified.

The following exit codes are applicable for a gateway server:

0: Successful uninstall.
1: Unexpected error (potential bug).
2: Cannot parse arguments or data provided by user is not valid.
3: The user canceled the uninstall.
4: Incompatible Java version.
5: Error initializing the replication gateway configuration (loading the admin framework classes, and so on).
6: Error stopping the replication gateway.
7: Error unconfiguring windows service.
8: Error input limit.
9: Error updating ADS Contents.
10: An error with the configuration of the legacy server. The base DN specified in the replica configuration is not a valid DN.
11: One of the specified legacy (Oracle Directory Server Enterprise Edition) servers is not compatible.
12: One of the specified new generation (Oracle Unified Directory based) servers is not compatible.
13: The user does not accept the certificate.
14: The user does not want to continue because there were issues loading the configuration of some servers.
15: An error with the configuration of the replication gateway.
16: The user overcame the maximum number of tries in interactive mode.
17: The user aborted the uninstall.
18: Error accessing file system (for instance deleting installation files).

A.2.18.10 Using a Properties File

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

The following options can be stored in a properties file:

adminUID
bindPasswordFile
certNickname
hostname
keyStorePasswordFile
keyStorePath
saslOption

SASL is not supported for Oracle Unified Directory.
trustAll
trustStorePasswordFile
trustStorePath

Entries in the properties file have the following format:

toolname.propertyname=propertyvalue

For example:

uninstall.bindPasswordFile=/path/pwd-file

A.2.18.11 Log Files

The uninstall command writes a log file named oud-uninstall-IDnumber, where IDnumber is a decimal number. The log files are located at these paths:

UNIX (Solaris): /var/tmp/
Linux: /tmp/
Windows: The %TEMP% folder. By default, this folder is C:\Documents and Settings\user\Local Settings\Temp.

A.2.18.12 Location

The uninstall command is located at these paths:

UNIX and Linux: INSTANCE_DIR/OUD/uninstall
Windows: INSTANCE_DIR\OUD\uninstall.bat

A.2.18.13 Related Commands

Section A.2.12, "oud-replication-gateway-setup"
Section A.2.13, "oud-setup"

A.2.19 windows-service

The windows-service command manually enables or disables the server as a Windows service.

A.2.19.1 Synopsis

windows-service [options]

A.2.19.2 Description

The windows-service command can be used to manually enable (or disable) the server as a Windows service. Windows services are applications similar to UNIX daemons that run in the background and are not in direct control by the user.

A.2.19.3 Command Options

The windows-service command accepts an option in either its short form (for example, -d) or its long form equivalent (for example, --disableService):

-c,--cleanupService service-name: Disable the service and clean up the Windows registry information associated with the provided service name.
-d, --disableService: Disable server as a Windows service.
-e, --enableService: Enable server as a Windows service.
-s, --serviceState: Display the state of the server as a Windows service.

A.2.19.4 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.

A.2.19.5 Examples

The following examples show how to use the windows-service command.

Example A-57 Enabling the Server as a Windows Service

The following command enables the server as a Windows service:

$ windows-service -e

Example A-58 Disabling the Server as a Windows Service

The following command disables the server as a Windows service:

$ windows-service -d

Example A-59 Displaying a Status

The following command displays a status of the server as a Windows service:

$ windows-service -s

A.2.19.6 Exit Codes

0: Server started/stopped successfully.
1: Service not found.
2: Server start error. Server already stopped
3: Server stop error.

A.2.19.7 Location

INSTANCE_DIR\OUD\bat\windows-service.bat

A.2.19.8 Related Commands

Section A.2.13, "oud-setup"

Section A.2.14, "oud-proxy-setup"

Section A.2.12, "oud-replication-gateway-setup"

A.3 Data Administration Commands

The following sections describe the data administration commands:

Section A.3.1, "backup"
Section A.3.2, "base64"
Section A.3.3, "dbtest"
Section A.3.4, "encode-password"
Section A.3.5, "export-ldif"
Section A.3.6, "import-ldif"
Section A.3.7, "ldif-diff"
Section A.3.8, "ldifmodify"
Section A.3.9, "ldifsearch"
Section A.3.10, "list-backends"
Section A.3.11, "make-ldif"
Section A.3.12, "manage-account"
Section A.3.13, "rebuild-index"
Section A.3.14, "restore"
Section A.3.15, "split-ldif"
Section A.3.16, "verify-index"

A.3.1 backup

The backup command archives the contents of one or more directory server back ends.

A.3.1.1 Synopsis

backup [options]

A.3.1.2 Description

The backup command archives the contents of one or more directory server back ends. The command can perform this operation immediately or at a scheduled time. For more information, see Section 13.4, "Configuring Commands As Tasks."

The backup command can be run when the server is online or offline. If the backup is run while the server is online, the command contacts the server over SSL, through the administration connector, and registers a backup task. For more information about the administration connector, see Section 13.3, "Managing Administration Traffic to the Server."

A.3.1.3 Options

The backup command accepts an option in either its short form (for example, -B backupID) or its long form equivalent (for example, --incrementalBaseID backupID).

-a, --backUpAll

Back up all configured back ends. This option must not be used in conjunction with --backendID.

-A, --hash

Generate a hash, or message digest, of the contents of the backup archive. The hash can be used as a checksum during the restore process to ensure that the backup has not been altered.

-B, --incrementalBaseID backupID

Specify the backup ID for the existing backup against which to take an incremental backup. If this ID is not provided, the incremental backup is based on the latest incremental or full backup contained in the backup directory.

-c, --compress

Compress the contents of the backup archive. The compression algorithm used may vary based on the back end type.

-d, --backupDirectory path

Write the backup files to the specified directory. If multiple back ends are archived, a subdirectory is created below this path for each back end. Otherwise, the backup files are placed directly in this directory. Note that multiple backups for the same back end can be placed in the same directory. If an incremental backup is to be performed, the backup directory must already contain at least one full backup. This is a required option.

For an online backup, the root for relative paths is the instance directory, and not the current working directory. For example, if you specify -d bknov2011, the backup files will be placed in instance-dir/bknov2011.

-i, --incremental

Perform an incremental backup rather than a full backup. An incremental backup includes only the data that has changed since a previous incremental or full backup. Thus, running an incremental backup can be notably faster than a full backup. When restoring an incremental backup, it is first necessary to restore the original full backup and then any intermediate incremental backups, which can make the restore process somewhat slower than restoring just a full backup. Note that some types of back ends might not support performing incremental backups. In this case, this option is ignored and a full backup is performed.

-I, --backupID backupID

Specify an identifier to use for the backup. If this is not provided, a backup ID is generated, based on the current time. The backup ID must be unique among all backups in the provided backup directory.

-n, --backendID backendID

Specify the ID of the back-end to be saved. This option can be used multiple times in a single command to indicate that multiple back ends should be backed up. The available back ends in the server can be determined by using the dsconfig list-backends command.

-s, --signHash

Generate a signed hash. This provides even stronger assurance that neither the backup archive nor the hash of its contents have been altered. This option can only be used if a connection to an online directory server instance is present. In this case, you must specify the --hostname, --port, --bindDN, and --bindPasswordFile options of the online directory server that will generate a signed hash of the archive.

-y, --encrypt

Encrypt the contents of the backup archive. This option can only be used if a connection to an online server instance is present. In this case, you must specify the --hostname, --port, --bindDN, and --bindPasswordFile options of the online directory server that will encrypt the archive.

A.3.1.4 Task Back End Connection Options

Running an online backup requires access to the tasks back end. Access to the tasks back end is provided over SSL through the administration connector. These connection options are used when the backup runs online.

-D, --bindDN bindDN: Use the bind DN to authenticate to the directory server. This option is used when performing simple authentication and is not required if SASL authentication is to be used. The default value for this option is cn=Directory Manager.
-h, --hostname hostname: Contact the directory server on the specified hostname or IP address. If this option is not provided, a default of localhost is used.
-j, --bindPasswordFile filename: Use the bind password in the specified file when authenticating to the directory server.
-K, --keyStorePath path: Use the client keystore certificate in the specified path.
-N, --certNickname nickname: Use the specified certificate for client authentication.
-o, --saslOption name=value: Use the specified options for SASL authentication.
-p, --port port: Contact the directory server at the specified administration port. If this option is not provided, a default administration port of 4444 is used.
-P, --trustStorePath path: 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.
-u, --keyStorePasswordFile filename: Use the password in the specified file to access the certificates in the client keystore. This option is only required if --keyStorePath is used.
-U, --trustStorePasswordFile filename: 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).
-X, --trustAll: Trust all server SSL certificates that the directory server presents. 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.

A.3.1.5 Task Scheduling Options

These options are used when you specify that the backup should run as a scheduled task.

--completionNotify emailAddress: Specify the email address of a recipient to be notified when the task completes. This option can be specified more than once in a single command.
--dependency taskId: Specify the ID of a task upon which this task depends. A task does not start executing until all of its dependencies have completed execution.
--errorNotify emailAddress: Specify the email address of a recipient to be notified if an error occurs when this task executes. This option can be specified more than once in a single command.
--failedDependencyAction action: Specify the action that this task will take if one of its dependent tasks fails. The value must be one of PROCESS, CANCEL, or DISABLE. If no value is specified, the default action is CANCEL.
--recurringTask schedulePattern: Indicates that the task is recurring and will be scheduled according to the schedulePattern, expressed as a crontab(5) compatible time and date pattern.
-t, --start startTime: Indicates the date and time at which the operation starts when scheduled as a directory server task expressed in the format YYYYMMDDhhmmss. A value of 0 schedules the task for immediate execution. When this option is specified, the operation is scheduled to start at the specified time after which the command exits immediately.

A.3.1.6 Command Input/Output Options

--noPropertiesFile: Indicates that a properties file is not used to obtain the default command-line options.
--propertiesFilePath path: Specify the path to the properties file that contains the default command-line options.

A.3.1.7 General Options

-?, -H, --help: Display command-line usage information for the command and exit without making any attempt to back up data.
-V, --version: Display the version information for the directory server and exit rather than attempting to run this command.

A.3.1.8 Examples

The following examples show how to use the directory server commands.

Example A-60 Backing Up All Configured Back Ends

The following command archives all directory server back ends (-a), compresses them (-c), and saves them to a specified directory (-d).

$ backup -a -c -d /tmp/backup

Display the contents of the backup directory, to see the subdirectories for each back end:

$ ls /tmp/backup
config    schema    tasks     userRoot

Display the contents of a subdirectory, to see that the system assigned a backup ID based on the current time.

$ ls /tmp/backup/userRoot/
backup-userRoot-20081015151640Z  backup.info

You can assign your own unique backup ID by using the -I option. For example:

$ backup -a -c -d /tmp/backup -I October08

Display the contents of the userRoot subdirectory to see the assigned backup ID.

$ ls /tmp/backup/userRoot/
backup-userRoot-October08        backup.info

Example A-61 Backing Up a Specific Back End

Use the -n option to specify a back end to be backed up. The following command archives the userRoot back end only.

$ backup -n userRoot -d /tmp/backup

Example A-62 Running an Incremental Backup

The following command archives all directory server back ends (-a), using incremental backup (-i), compresses them (-c), and saves the data to a directory (-d).

$ backup -a -i -c -d /tmp/backup

Example A-63 Running an Incremental Backup on a Specific Back End

Use the list-backends command to display the current configured back ends.

$ list-backends
Backend ID     : Base DN
---------------:--------------------
adminRoot      : cn=admin data
ads-truststore : cn=ads-truststore
backup         : cn=backups
config         : cn=config
monitor        : cn=monitor
schema         : cn=schema
tasks          : cn=tasks
userRoot       : "dc=example,dc=com"

The following command runs an incremental backup (-i) on the userRoot back end (-n), compresses the backup (-c), and saves the data to a directory (-d).

$ backup -i -n userRoot -c -d /tmp/backup/userRoot

Example A-64 Running an Incremental Backup Against an Existing Backup

Assume that you have created two archived incremental backup files by using the -I or --backupID option and assigned the IDs 1234 and 4898 to the two files, respectively:

/tmp/backup/userRoot> ls
./     backup-userRoot-1234   backup.info
../    backup-userRoot-4898   backup.info.save

The following command runs an incremental backup (-i) on all configured back ends (-a) based on the backup ID 1234 (-B), assigns a backup ID of 5438 to the incremental backup, and saves the data to a directory (-d).

$ backup -a -i -B 1234 -I 5438 -d /tmp/backup

The contents of backup.info show that the latest incremental backup (backup_id=5438) has a dependency on backup_id=1234:

$ backend_dn=ds-cfg-backend-id=userRoot,cn=Backends,cn=config

backup_id=4898
backup_date=20070727202906Z
incremental=false
compressed=false
encrypted=false
signed_hash=VmBG/VkfMAMMPnR6M8b5kZil7FQ=
property.last_logfile_name=00000000.jdb
property.archive_file=backup-userRoot-4898
property.cipher_algorithm=AES/CBC/PKCS5Padding
property.mac_algorithm=HmacSHA1
property.last_logfile_size=490554

backup_id=1234
backup_date=20070727202934Z
incremental=false
compressed=false
encrypted=false
signed_hash=VmBG/VkfMAMMPnR6M8b5kZil7FQ=
property.last_logfile_name=00000000.jdb
property.archive_file=backup-userRoot-1234
property.cipher_algorithm=AES/CBC/PKCS5Padding
property.mac_algorithm=HmacSHA1
property.last_logfile_size=490554

backup_id=5438
backup_date=20070727203107Z
incremental=true
compressed=false
encrypted=false
dependency=1234
property.last_logfile_name=00000000.jdb
property.archive_file=backup-userRoot-5438
property.last_logfile_size=490554

Example A-65 Backing Up All Configured Back Ends with Encryption and Signed Hash

The directory server provides support for backup encryption (using --encrypt), hash generation (using --hash), and signed hash (using --signHash) to secure archived data. These options require a connection to an online server instance, over SSL through the administration connector. When you use these options, you must therefore specify the connection details, including the host, administration port, bind DN and bind password file. You must also specify the certificate details for the SSL connection.

The following command archives all directory server back ends (-a), compresses them (-c), generates a hash (-A), signs the hash (-s), encrypts the data while archiving the data (-y), assigns a back end ID of 123, and saves the data to a directory (-d). The self signed certificate is trusted using the -X (--trustAll) option.

$ backup -h localhost -D "cn=Directory Manager" -j /path/pwd-file -p 4444 -X \
  -a -c -A -s -y -I 123 -d /tmp/backup
Backup task 2008101609295810 scheduled to start immediately
...

Example A-66 Scheduling a Backup

Scheduling a backup requires online access to the tasks back end. Access to this back end is provided over SSL through the administration connector. When you schedule a backup, you must therefore specify the connection details, including the host, administration port, bind DN and bind password file. You must also specify the certificate details for the SSL connection.

The following command schedules a backup of all components (-a) and writes it to the /tmp/backups directory (-d). The start time is specified with the --start option. The backup sends a completion notification and error notification to admin@example.com. The self signed certificate is trusted using the -X (--trustAll) option.

$ backup -h localhost -D "cn=Directory Manager" -j /path/pwd-file -p 4444 -X \
  -a -d /tmp/backups --start 20090124121500 --completionNotify admin@example.com \
  --errorNotify admin@example.com
Backup task 2007102914530410 scheduled to start Jan 24, 2009 12:15:00 PM SAST

You can view this scheduled task by using the manage-tasks command. For more information, see Section 13.4, "Configuring Commands As Tasks."

A.3.1.9 Exit Codes

An exit code of 0 indicates that the operation completed successfully. An exit code of 1 indicates that an error occurred during processing.

A.3.1.10 Using a Properties File

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

A.3.1.11 Location

The backup command is located at these paths:

UNIX and Linux: INSTANCE_DIR/OUD/bin/backup
Windows: INSTANCE_DIR\OUD\bat\backup.bat

A.3.1.12 Related Commands

Section A.3.14, "restore"
Section A.3.10, "list-backends"
Section A.2.8, "manage-tasks"

A.3.2 base64

The base64 command encodes binary strings using the base64 encoding format.

A.3.2.1 Synopsis

base64 subcommand[options]

A.3.2.2 Description

The base64 command encodes binary strings into text representations using the base64 encoding format. Base64 encoding is often used in LDIF files to represent non-ASCII character strings. It is also frequently used to encode certificate contents or the output of message digests such as MD5 or SHA.

A.3.2.3 Subcommands

The following subcommands are used with the base64 command.

decode

Decodes base64-encoded information into raw data. Suboptions are as follows:

-d, --encodedData encoded-data. Base64-encoded data to be decoded to raw data.

-f, --encodedDataFile filename. Path to the file that contains the base64-encoded data to be decoded.

-o, --toRawFile filename. Path to the file to which the raw data should be written.

encode

Encodes raw data to base64. Suboptions are as follows:

-d, --rawData raw-data. Raw data to be base64-encoded.

-f, --rawDataFile filename. Path to the file that contains the raw data to be base64-encoded.

-o, --toEncodedFile filename. Path to the file to which the base64-encoded data should be written.

A.3.2.4 Global Options

-?, -H, --help: Display usage information.
-V, --version: Display directory server version information.

A.3.2.5 Examples

The following examples show how to use the directory server commands.

Example A-67 Base64 Encoding a String

The following command base64-encodes the string opends.

$ base64 encode -d opends
b3BlbmRz

Example A-68 Base64 Encoding the Contents of a File

The following command base64-encodes the file (-f) and writes to an output file (-o).

$ base64 encode -f myrawdata -o myencodeddata

Example A-69 Decoding a Base64-Encoded String

The following command decodes a base64-encoded string.

$ base64 decode -d b3BlbmRz
opends

Example A-70 Decoding the Contents of a Base64-Encoded File

The following command decodes the file base64-encoded file (-f) and writes to an output file (-o).

$ base64 encode -f myencodeddata -o myoutput

Example A-71 Base64-Encoding and Decoding on Linux Systems

The following command encodes and decodes on Linux from the command-line. After you enter the clear-text string, press Control-D to signal the end of input on the command line.

$ base64 encode
hello world
<CTRL-D>
aGVsbGBqd29ybGQK

$ base64 decode
aGVsbG8gd29ybGQK
<CTRL-D>
hello world

A.3.2.6 Exit Codes

An exit code of 0 indicates that the operation completed successfully. An exit code of 1 indicates that an error occurred during processing.

A.3.2.7 Location

UNIX and Linux: INSTANCE_DIR/OUD/bin/base64
Windows: INSTANCE_DIR\OUD\bat\base64.bat

A.3.3 dbtest

The dbtest command debugs an Oracle Berkeley Java Edition (JE) back end.

A.3.3.1 Synopsis

dbtest subcommands [options]

A.3.3.2 Description

The dbtest command is used to debug an Oracle Berkeley Java Edition (JE) back end. The command lists the root, entry, database containers, and the status of indexes in the database. The command also provides a dump of the database for debugging purposes.

A back end is a repository for storing data on a directory server. The back end uses some type of database (DB) to store data and to maintain a set of indexes that allow the back end to locate the entries in the directory. The primary database for the directory server is the Berkeley Java Edition (JE) database, which organizes its data as a single collection of keyed records in B-tree form.

You can use the dbtest command to access the following information:

Root container. Specifies the back end ID and the directory for the back end.
Entry container. Specifies the base DN that the entry container stores on disk, the database prefix to use for the database names, and the number of entries in the database. Each base DN of a JE back end is given its own entry container.
Database container. Specifies the database name, type, and JE database name for the specific back end ID.
Index Status. Specifies the index name, type, status and associated JE database.

Currently, the dbtest command is a read-only command and cannot alter the database. The command can run in online or offline mode. However, running dbtest in online mode can take considerably longer than running it in offline mode.

A.3.3.3 Subcommands

dump-database-container

Dump records from the database container. Suboptions are as follows:

-b, --baseDN baseDN. Base DN of the entry container to debug. Required.

-d, --databaseName databaseName. Name of the database container to debug. Required.

-k, --minKeyValue value. Only show records with keys that should be ordered after the provided value using the comparator for the database container.

-K, --maxKeyValue value. Only show records with keys that should be ordered before the provided value using the comparator for the database container.

-n, --backendID backendID. ID of the local DB back end to debug. Required.

-p, --skipDecode. Skip decoding the local database to its appropriate types.

-q, --statsOnly. Display the statistics only, rather than the complete data.

-s, --minDataSize size. Only show records whose data is no smaller than the provided value.

-S, --maxDataSize size. Only show records whose data is no larger than the provided value.

list-database-containers

List the database containers for the entry container. Suboptions are as follows:

-b, --baseDN baseDN. Base DN of the entry container to debug. Required.

-n, --backendID backendID. ID of the local DB back end to debug. Required.

list-entry-containers

List the entry containers for a root container. Suboptions are as follows:

-n, --backendID backendID. ID of the local DB back end to debug. Required.

list-index-status

List the status of indexes in an entry container. Suboptions are as follows:

-b, --baseDN baseDN. Base DN of the entry container to debug. Required.

-n, --backendID backendID. ID of the local DB back end to debug. Required.

list-root-containers

List the root containers used by all local DB back ends.

A.3.3.4 Global Options

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

-?, -H, --help: Display the usage information.
-V, --version: Display directory server version information.

A.3.3.5 Examples

The following examples show how to use the directory server commands.

Example A-72 Displaying the List of Root Containers

The following command lists the root containers used by all local DB back ends:

$ dbtest list-root-containers
Backend ID  Database Directory
------------------------------
userRoot    db

Total: 1

Example A-73 Displaying a List of Entry Containers

The following command displays the list of entry containers on the local DB back end:

$ dbtest list-entry-containers -n userRoot
Base DN            JE Database Prefix  Entry Count
--------------------------------------------------
dc=example,dc=com  dc_example_dc_com   102

Total: 1

Example A-74 Displaying a List of Database Containers

The following command displays the list of database containers on the local DB back end:

$ dbtest list-database-containers -b dc=example,dc=com -n userRoot
Database Name              Database  JE Database Name                       Entry Count
                           Type
---------------------------------------------------------------------------------------
dn2id                      DN2ID     dc_example_dc_com_dn2id                      102
id2entry                   ID2Entry  dc_example_dc_com_id2entry                   102
referral                   DN2URI    dc_example_dc_com_referral                   0
id2children                Index     dc_example_dc_com_id2children                2
id2subtree                 Index     dc_example_dc_com_id2subtree                 2
state                      State     dc_example_dc_com_state                      19
objectClass.equality       Index     dc_example_dc_com_objectClass.equality       6
givenName.equality         Index     dc_example_dc_com_givenName.equality         100
givenName.substring        Index     dc_example_dc_com_givenName.substring        396
member.equality            Index     dc_example_dc_com_member.equality            0
uid.equality               Index     dc_example_dc_com_uid.equality               100
cn.equality                Index     dc_example_dc_com_cn.equality                100
cn.substring               Index     dc_example_dc_com_cn.substring               1137
uniqueMember.equality      Index     dc_example_dc_com_uniqueMember.equality      0
telephoneNumber.equality   Index     dc_example_dc_com_telephoneNumber.equality   100
telephoneNumber.substring  Index     dc_example_dc_com_telephoneNumber.substring  956
sn.equality                Index     dc_example_dc_com_sn.equality                100
sn.substring               Index     dc_example_dc_com_sn.substring               541
ds-sync-hist.ordering      Index     dc_example_dc_com_ds-sync-hist.ordering      0
mail.equality              Index     dc_example_dc_com_mail.equality              100
mail.substring             Index     dc_example_dc_com_mail.substring             525
entryUUID.equality         Index     dc_example_dc_com_entryUUID.equality         102
aci.presence               Index     dc_example_dc_com_aci.presence               0

Total: 23

Example A-75 Dumping the Contents of a Database and Skipping Decode

The following command dumps the contents of a database and displays the indexed values of the entry, but skips the decode.

$ dbtest dump-database-container -b dc=example,dc=com -n userRoot \
  -d objectClass.equality -p

Key (6 bytes):
64 6F 6D 61 69 6E domain

Data (8 bytes):
00 00 00 00 00 00 00 01

Key (18 bytes):
67 72 6F 75 70 6F 66 75 6E 69 71 75 65 6E 61 6D groupofu niquenam
65 73 es

Data (40 bytes):
00 00 00 00 00 00 00 03 00 00 00 00 00 00 00 9C
00 00 00 00 00 00 00 9D 00 00 00 00 00 00 00 9E
00 00 00 00 00 00 00 9F
...

A.3.3.6 Exit Codes

An exit code of 0 indicates that the operation completed successfully. An exit code of 1 indicates that an error occurred during processing.

A.3.3.7 Location

UNIX and Linux: INSTANCE_DIR/OUD/bin/dbtest
Windows: INSTANCE_DIR\OUD\bat\dbtest.bat

A.3.3.8 Related Commands

Section A.2.4, "dsconfig"
Section A.3.6, "import-ldif"
Section A.3.5, "export-ldif"

A.3.4 encode-password

The encode-password command encodes and compares user passwords.

This command is not supported for the proxy.

A.3.4.1 Synopsis

encode-password options

A.3.4.2 Description

The encode-password command can be used to interact with the password storage schemes defined in the directory server. It has three modes of operation:

List schemes mode. List the password storage schemes that are available in the directory server. In this mode, only the --listSchemes option is required.
Encode clear-text mode. Encode a clear-text password using a provided password storage scheme. In this mode, the --storageScheme option is required, along with a clear-text password that is read from a file (--clearPasswordFile).
Validate password mode. Determine whether a given clear-text password is correct for a provided encoded password. In this mode, a clear-text password (from --clearPasswordFile) and an encoded password (from --encodedPasswordFile) are required.

The set of authentication passwords available for use in the directory server can be retrieved from the supportedAuthPasswordSchemes attribute of the root DSE entry. You can use ldapsearch to view this information.

A.3.4.3 Options

The encode-password command accepts an option in either its short form (for example, -f filename) or its long form equivalent (for example, --clearPasswordFile filename).

-a, --authPasswordSyntax: Use the Authentication Password Syntax (as defined in RFC 3112 (http://www.ietf.org/rfc/rfc3112.txt)), which encodes values in a form scheme$authInfo$authValue. If this option is not provided, then the user password syntax (which encodes values in a form scheme$value will be used.
-E, --encodedPasswordFile filename: Use the encoded password from the specified file to compare against a given clear-text password. If the --authPasswordSyntax option is also provided, then this password must be encoded using the authentication password syntax. Otherwise, it should be encoded using the user password syntax.
-f, --clearPasswordFile filename: Use the clear-text password from the specified file when either encoding a clear-text password or comparing a clear-text password against an encoded password.
-i, --interactivePassword: The password to encode or to compare against an encoded password is interactively requested from the user.
-l, --listSchemes: Display a list of the password storage schemes that are available for use in the directory server. If the option is used by itself, it displays the names of the password storage schemes that support the user password syntax. If the option used in conjunction with --authPasswordSyntax, it displays the names of the password storage schemes that support the authentication password syntax.
-r, --useCompareResultCode: Use an exit code that indicates whether a given clear-text password matched a provided encoded password. If this option is provided, the directory server results in an exit code of 6 (COMPARE_TRUE) or an exit code of 5 (COMPARE_FALSE). Any other exit code indicates that the command failed to complete its processing to make the necessary determination. If this option is not provided, an exit code of zero will be used to indicate that the command completed its processing successfully, or something other than zero if an error occurred.
-s, --storageScheme storageScheme: Specify the name of the password storage scheme to use when encoding a clear-text password. If the --authPasswordSyntax option is provided, the value must be the name of a supported authentication password storage scheme. Otherwise, specify the name of a supported user password storage scheme.
-?, -H, --help: Display the command-line usage information for the command and exit immediately without taking any other action.
-V, --version: Display the version information for the directory server.

A.3.4.4 Examples

The following examples show how to use the encode-password command.

Example A-76 Listing the Storage Schemes on the Server

The following command lists the storage schemes (-l) available for use on the directory server.

$ encode-password -l
3DES
AES
BASE64
BLOWFISH
CLEAR
CRYPT
MD5
RC4
SHA
SMD5
SSHA
SSHA256
SSHA384
SSHA512

Example A-77 Listing the Authenticated Passcode Syntax Storage Schemes on the Server

The following command lists the storage schemes (-l) that support the authentication passcode syntax (-a) on the directory server.

$ encode-password -l -a

MD5
SHA1
SHA256
SHA384
SHA512

Example A-78 Encoding a Clear-Text Password to Another Scheme

The following command encodes a clear-text password in a file (-f) using the specified scheme (-s).

$ encode-password -f /path/clear-pwd-file -s MD5

Encoded Password:  "{MD5}AjxHKRFkRwxx3j9lM2HMow=="

Example A-79 Encoding a Clear-Text Password to Another Scheme using the Authentication Password Syntax

The following command encodes a clear-text password in a file (-f) using the specified scheme (-s) and the authentication password syntax (-a).

$ encode-password -f /path/clear-pwd-file -s MD5 -a

Encoded Password:  "MD5$/imERhcEu3U=$AFqmpZi8EiTIvMFwkcrf8A=="

Example A-80 Comparing a Clear-Text Password to an Encoded Password

The following command compares a clear-text password in a file (-f) with an encoded password in a file (-E). Do not include the password scheme (for example, MD5) in your encoded password.

$ encode-password -f /path/clear-pwd-file -E /path/encoded-pwd-file -s MD5

The provided clear-text and encoded passwords match

Example A-81 Compare a Clear-Text Password to an Encoded Password and Return an Exit Code

The following command compares a clear-text password in a file (-f) with an encoded password in a file (-E) using the scheme (-s) and returns the exit code (-r) (6 for COMPARETRUE; 5 for COMPAREFALSE). Do not include the password scheme (for example, MD5) in your encoded password.

$ encode-password -f /path/clear-pwd-file -E /path/encoded-pwd-file -s MD5 -r

The provided clear-text and encoded passwords match

echo $?
6

Example A-82 Encoding a Password Contained in a File using SSHA

The following command encodes a clear-text password in a file (-f) using the specified scheme (-s). For Windows platforms, specify the path to your clear-text password file (for example, -f \temp\testpassword):

$ encode-password -s SSHA -f /path/clear-pwd-file

Encoded Password:   "{SSHA}QX2fMu+2N22N9qI+zu6fIZxsBVID3EsUlYYEbQ=="

A.3.4.5 Exit Codes

Table A-3 Exit Codes

Exit Code	Description
`0`	Operation completed successfully.
`1`	Error occurred during operation.
`5`	COMPARE_FALSE. Used with the `--r` or `--useCompareCodeResult` option, an exit code of `5` indicates a given clear-text password does not match the provided encoded password.
`6`	COMPARE_TRUE. Used with the `--r` or `--useCompareCodeResult` option, an exit code of `6` indicates that a given clear-text password matches the provided encoded password.

A.3.4.6 Location

UNIX and Linux: INSTANCE_DIR/OUD/bin/encode-password
Windows: INSTANCE_DIR\OUD\bat\encode-password.bat

A.3.5 export-ldif

The export-ldif command exports the contents of a directory server back end to LDIF format.

A.3.5.1 Synopsis

export-ldif [options]

A.3.5.2 Description

The export-ldif command exports the contents of a directory server back end to LDIF format. This command can run the export immediately or can be scheduled to run at a specified date and time. For more information, see Section 13.4, "Configuring Commands As Tasks."

Because some back ends cannot be imported to the directory server, the export-ldif command does not export the following back ends: monitor, ads-truststore, backup, and config-file-handler.

You can run the export-ldif command in online or offline mode.

Online mode. In online mode, export-ldif contacts a running directory server instance over SSL, through the administration connector, and registers an export task. The command runs in online mode automatically if you specify any of the task back end connection options. For more information about the administration connector, see Section 13.3, "Managing Administration Traffic to the Server."
Offline mode. In offline mode, export-ldif accesses the database directly rather than through a directory server instance. To perform an offline export, the directory server must be stopped.

A.3.5.3 Options

The export-ldif command accepts an option in either its short form (for example, -b branchDN) or its long form equivalent (for example, --includeBranch branchDN).

-a, --appendToLDIF

Append the export to an existing LDIF file rather than overwriting it. If this option is not provided, the directory server overwrites the specified LDIF file, if it exists.

-b, --includeBranch branchDN

Specify the base DN for a branch or subtree of the data to be exported. This option can be used multiple times to specify multiple base DNs. If this option is provided, entries contained in the back end that are not at or below one of the provided base DNs are skipped.

-B, --excludeBranch branchDN

Specify the base DN for a branch or subtree of the data to be omitted from the export. This option can be used multiple times to specify multiple base DNs. If this option is provided, any entries contained in the back end that are at or below one of the provided base DNs are skipped. Note that the use of the --excludeBranch option takes precedence over the --includeBranch option. If an entry is at or below a DN contained in both the included and excluded lists, it is not included. This capability makes it possible to include data for only part of a branch. For example, you can include all entries below dc=example,dc=com except those below ou=People,dc=example,dc=com.

-c, --compress

Compress the LDIF data as it is written. The data is compressed using the GZIP format, which is the format used by the --isCompressed option of the import-ldif command.

-e, --excludeAttribute attribute

Exclude the specified attribute name during the export. This option can be used multiple times to specify multiple attributes. If this option is provided, any attributes listed are omitted from the entries that are exported.

-E, --excludeFilter filter

Exclude the entries identified by the specified search filter during the export. This option can be used multiple times to specify multiple filters. If this option is provided, any entry in the back end that matches the filter is skipped. Note that the use of the --excludeFilter option takes precedence over the --includeFilter option. If an entry matches filters in both the included and excluded lists, the entry is skipped.

-i, --includeAttribute attribute

Include the specified attribute name in the export. This option can be used multiple times to specify multiple attributes. If this option is provided, any attributes not listed are omitted from the entries that are exported.

-I, --includeFilter filter

Include the entries identified by the specified search filter in the export. This option can be used multiple times to specify multiple filters. If this option is provided, any entry in the back end that does not match the filter is skipped.

-l, --ldifFile filename

Export the data to the specified LDIF file. This is a required option.

For online exports, the root for relative paths is the instance root, rather than the current working directory. So, for example, a path of exports/ldif.ldif here refers to instance-root/exports/ldif.ldif.

-n, --backendID backendID

Specify the back end ID of the data to be exported. The available back ends in the directory server can be determined using the list-backends command. This is a required option.

-O, --excludeOperational

Exclude operational attributes in the export.

--wrapColumn column

Specify the column at which to wrap long lines when writing to the LDIF file. A value of 0 indicates that the data should not be wrapped.

A.3.5.4 Task Back End Connection Options

Running an online export requires access to the tasks back end. Access to the tasks back end is provided over SSL through the administration connector. These connection options are used when the export runs online.

-D, --bindDN bindDN: Use the bind DN to authenticate to the directory server. This option is used when performing simple authentication and is not required if SASL authentication is to be used. The default value for this option is cn=Directory Manager.
-h, --hostname hostname: Contact the directory server on the specified hostname or IP address. If this option is not provided, a default of localhost is used.
-j, --bindPasswordFile filename: Use the bind password in the specified file when authenticating to the directory server.
-K, --keyStorePath path: Use the client keystore certificate in the specified path.
-N, --certNickname nickname: Use the specified certificate for client authentication.
-o, --saslOption name=value: Use the specified options for SASL authentication.
-p, --port port: Contact the directory server at the specified administration port. If this option is not provided, a default administration port of 4444 is used.
-P, --trustStorePath path: 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.
-u, --keyStorePasswordFile filename: Use the password in the specified file to access the certificates in the client keystore. This option is only required if --keyStorePath is used.
-U, --trustStorePasswordFile filename: 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).
-X, --trustAll: Trust all server SSL certificates that the directory server presents. 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.

A.3.5.5 Task Scheduling Options

These options are used when you specify that the export should run as a scheduled task.

--completionNotify emailAddress: Specify the email address of a recipient to be notified when the task completes. This option can be specified more than once in a single command.
--dependency taskId: Specify the ID of a task upon which this task depends. A task does not start executing until all of its dependencies have completed execution.
--errorNotify emailAddress: Specify the email address of a recipient to be notified if an error occurs when this task executes. This option can be specified more than once in a single command.
--failedDependencyAction action: Specify the action that this task will take if one of its dependent tasks fails. The value must be one of PROCESS, CANCEL, or DISABLE. If no value is specified, the default action is CANCEL.
--recurringTask schedulePattern: Indicates that the task is recurring and will be scheduled according to the schedulePattern, expressed as a crontab(5) compatible time and date pattern.
-t, --start startTime: Indicates the date and time at which the operation starts when scheduled as a directory server task expressed in the format YYYYMMDDhhmmss. A value of 0 schedules the task for immediate execution. When this option is specified, the operation is scheduled to start at the specified time after which the command exits immediately.

A.3.5.6 Command Input/Output Options

--noPropertiesFile: Indicates that a properties file is not used to obtain the default command-line options.
--propertiesFilePath path: Specify the path to the properties file that contains the default command-line options.

A.3.5.7 General Options

-?, -H, --help: Display command-line usage information for the command and exit without making any attempt to run an export.
-V, --version: Display the version information for the directory server and exit rather than attempting to run this command.

A.3.5.8 Examples

The following examples show how to use the directory server commands.

Example A-83 Performing an Offline Export

The following example exports the userRoot back end, starting at the base DN specified by the -b option. The command exports the data to an LDIF file specified by -l. The directory server must be stopped before performing an offline export.

$ stop-ds
$ export-ldif -b dc=example,dc=com -n userRoot -l /usr/tmp/export.ldif
[17/Oct/2008:12:24:33 +0200] category=JEB severity=NOTICE msgID=8847447 
msg=Exported 102 entries and skipped 0 in 0 seconds (average rate 159.4/sec)

Example A-84 Performing an Online Export

An export is automatically run online if you specify any of the task back end connection options. Because an online export contacts the server over SSL, you must specify how to trust the SSL server certificate. This examples uses the -X option to trust all certificates.

$ export-ldif -h localhost -p 4444 -D "cn=Directory Manager" -j /path/pwd-file -X \
  --includeBranch "dc=example,dc=com" --backendID userRoot \
  --ldifFile /usr/tmp/export.ldif

Example A-85 Scheduling an Export

You can schedule an export to run at some future date by using the -t or --start option to specify the start time. Like a regular online export, a scheduled export contacts the task back end of a running directory server and the relevant task back end connection options must be specified.

This example schedules an export of the userRoot back end to start on December 24.

$ export-ldif -h localhost -p 4444 -D "cn=Directory Manager" -j /path/pwd-file -X \
  --includeBranch "dc=example,dc=com" --backendID userRoot \
  --ldifFile /usr/tmp/export.ldif --start 20081224121500
Export task 2008101712361910 scheduled to start Dec 24, 2008 12:15:00 PM SAST

You can view a scheduled task by using the manage-tasks command. For more information, see Section 13.4, "Configuring Commands As Tasks."

A.3.5.9 Exit Codes

Offline mode. An exit code of 0 indicates that the operation completed successfully. A non-zero exit code indicates that an error occurred during processing.
Online mode. If -t or --start is specified, an exit code of 0 indicates that the task was created successfully. A nonzero exit code indicates that an error occurred when the task was created. If -t or --start is not specified, the exit codes are the same as those specified for offline mode.

A.3.5.10 Using a Properties File

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

A.3.5.11 Location

UNIX and Linux: INSTANCE_DIR/OUD/bin/export-ldif
Windows: INSTANCE_DIR\OUD\bat\export-ldif.bat

A.3.5.12 Related Commands

Section A.3.6, "import-ldif"
Section A.3.7, "ldif-diff"
Section A.3.8, "ldifmodify"
Section A.3.9, "ldifsearch"
Section A.2.8, "manage-tasks"

A.3.6 import-ldif

The import-ldif command populates an Oracle Berkeley DB Java Edition (JE) back end with data that is read from an LDIF file.

A.3.6.1 Synopsis

import-ldif options

A.3.6.2 Description

The import-ldif command populates an Oracle Berkeley DB Java Edition (JE) back end with data that is read from an LDIF file, or with data generated based on a MakeLDIF template. In most cases, using import-ldif is significantly faster than adding entries by using ldapmodify. Note that a complete import to an entire JE back end has better performance than a partial import to a branch of the JE back end.

The import-ldif command can run the import immediately or can schedule the import to run at a specified date and time. For more information, see Section 13.4, "Configuring Commands As Tasks."

You can run the import-ldif command in online or offline mode.

Online mode. In online mode, import-ldif contacts a running directory server instance over SSL, through the administration connector, and registers an import task. The command runs in online mode automatically if you specify any of the task back end connection options. For more information about the administration connector, see Section 13.3, "Managing Administration Traffic to the Server."
Offline mode. In offline mode, import-ldif accesses the database directly rather than through a directory server instance. To perform an offline import, the directory server must be stopped.

A.3.6.3 Options

The import-ldif command accepts an option in either its short form (for example, -b baseDN) or its long form equivalent (for example, --includeBranch baseDN).

-a, --append

Append the imported data to the data that already exists in the back end, rather than clearing the back end before starting the import.

-A, --templateFile filename

Specify the path to a MakeLDIF template to generate the import data.

-b, --includeBranch branchDN

Specify the base DN for a branch or subtree of the data that should be included in the import. This option can be used multiple times to specify multiple base DNs. If this option is provided, entries contained in the import source that are not at or below one of the provided base DNs are skipped. Any existing entries above the provided base DNs are preserved.

-B, --excludeBranch branchDN

Specify the base DN branch or subtree that should be omitted from the import. This option can be used multiple times to specify multiple base DNs. If this option is provided, entries contained in the import source that are at or below one of the base DNs are skipped. Note that the use of the --excludeBranch option takes precedence over the --includeBranch option. If an entry is at or below a DN contained in both the included and excluded lists, it is omitted from the import. This capability makes it possible to include data for only a part of a branch (for example, all entries below dc=example,dc=com except those below ou=People,dc=example,dc=com).

-c, --isCompressed

Specify that the LDIF import file is compressed. The file should be compressed using the GZIP format, which is the format used by the --compressLDIF option of the export-ldif command.

--countRejects

Return the number of rejected entries during import. If the number of rejected entries is between 0 and 255, that number is returned. If the number of rejected entries is greater than 255, the command returns the value 255. For example, if you run import-ldif with the --countRejects option and get 16 rejected entries, the command returns the value 16. If you run import-ldif and get 300 rejected entries, the command returns the value 255. Note that this option is not supported for online imports.

-e, --excludeAttribute attribute

Specify the name of an attribute that should be excluded from the import. This option can be used multiple times to specify multiple attributes.

-E, --excludeFilter filter

Specify the search filter to identify entries that should be excluded from the import. This option can be used multiple times to specify multiple filters. If this option is provided, any entry in the import source that matches the filter is skipped. Note that the --excludeFilter option takes precedence over the --includeFilter option. If an entry matches filters in both the include and exclude filters, the entry is skipped during import.

-F, --clearBackend

Confirm deletion of all existing entries for all base DNs in the specified back end when importing without the --append option. This only applies when importing a multiple base DN back end specified by the back end ID. This option is implied for back ends with only one base DN.

-i, --includeAttribute attribute

Specify the attributes that should be included in the import. This option can be used multiple times to specify multiple attributes. If this option is used, attributes not listed in this set are omitted from the entries that are imported.

-I, --includeFilter filter

Specify the search filter to identify entries that should be included in the import. This option can be used multiple times to specify multiple filters. If this option is provided, any entry in the import source that does not match the results of the filter is skipped.

-l, --ldifFile filename

Read the LDIF file located at the specified path. This option must not be used in conjunction with --templateFile.

For online imports, the root for relative paths is the instance root, rather than the current working directory. So, for example, a path of imports/ldif.ldif here refers to instance-root/imports/ldif.ldif.

-n, --backendID backendID

Specify the ID of the back end into which the data should be imported. To display the available back ends in the server, use the list-backends command.

-O, --overwrite

Overwrite the specified skip file or reject file, if it already exists. If this option is not provided, any skipped or rejected entries are appended to their corresponding files rather than overwriting them. This option is only applicable if the --rejectFile or --skipFile options are provided.

-r, --replaceExisting

Replace existing data with the content from the import. If this option is not provided, existing entries are not overwritten. This is only applicable if the --append option has also been provided.

-R, --rejectFile filename

Use the specified file to hold any rejected entries during the import. Rejected entries occur if entries are not compliant with the default schema. A comment is included before the entry indicating the reason that it was rejected. If this option is not provided, no reject file is written.

-s, --randomSeed seed

Use the specified seed number for the random number generator when generating entries from a MakeLDIF template. Seeding the random number generator with a particular value can help to ensure that the same template and random seed always generate exactly the same data.

--skipDNValidation

Perform limited parental DN validation during a later part of the LDIF import. If this option is specified, no duplicate DN checking is done. Do not use this option if you are not certain that your LDIF import file is correct.

--skipFile filename

Use the specified file to identify entries that were skipped during the import. Skipped entries occur if entries cannot be placed under any specified base DN during an import or if the --excludeBranch, --excludeAttribute, or --excludeFilter option is used.

-S, --skipSchemaValidation

Do not perform any schema validation on the entries as they are imported. This option can provide improved import performance, but should only be used if you are certain that the import data is valid.

--threadCount count

Specify the number of threads that are used to read the LDIF file. If this option is not specified, a default of two threads per CPU is used.

You can use this option to increase the number of threads if you are importing particularly large LDIF files, but you should not use the option unless you are certain of the resulting impact on performance.

--tmpDirectory directory

Use the specified directory for index scratch files created during the import. If no directory is specified, the default INSTANCE_DIR/OUD/import-tmp is used.

A.3.6.4 Task Back End Connection Options

Running an online import requires access to the tasks back end. Access to the tasks back end is provided over SSL through the administration connector. These connection options are used when the import runs online.

-D, --bindDN bindDN: Use the bind DN to authenticate to the directory server. This option is used when performing simple authentication and is not required if SASL authentication is to be used. The default value for this option is cn=Directory Manager.
-h, --hostname hostname: Contact the directory server on the specified hostname or IP address. If this option is not provided, a default of localhost is used.
-j, --bindPasswordFile filename: Use the bind password in the specified file when authenticating to the directory server.
-K, --keyStorePath path: Use the client keystore certificate in the specified path.
-N, --certNickname nickname: Use the specified certificate for client authentication.
-o, --saslOption name=value: Use the specified options for SASL authentication.
-p, --port port: Contact the directory server at the specified administration port. If this option is not provided, a default administration port of 6664 is used.
-P, --trustStorePath path: 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.
-u, --keyStorePasswordFile filename: Use the password in the specified file to access the certificates in the client keystore. This option is only required if --keyStorePath is used.
-U, --trustStorePasswordFile filename: 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).
-X, --trustAll: Trust all server SSL certificates that the directory server presents. 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.

A.3.6.5 Task Scheduling Options

These options are used when you specify that the import should run as a scheduled task.

--completionNotify emailAddress: Specify the email address of a recipient to be notified when the task completes. This option can be specified more than once in a single command.
--dependency taskId: Specify the ID of a task upon which this task depends. A task does not start executing until all of its dependencies have completed execution.
--errorNotify emailAddress: Specify the email address of a recipient to be notified if an error occurs when this task executes. This option can be specified more than once in a single command.
--failedDependencyAction action: Specify the action that this task will take if one of its dependent tasks fails. The value must be one of PROCESS, CANCEL, or DISABLE. If no value is specified, the default action is CANCEL.
--recurringTask schedulePattern: Indicates that the task is recurring and will be scheduled according to the schedulePattern, expressed as a crontab(5) compatible time and date pattern.
-t, --start startTime: Indicates the date and time at which the operation starts when scheduled as a directory server task expressed in the format YYYYMMDDhhmmss. A value of 0 schedules the task for immediate execution. When this option is specified, the operation is scheduled to start at the specified time after which the command exits immediately.

A.3.6.6 Command Input/Output Options

--noPropertiesFile: Indicates that a properties file is not used to obtain the default command-line options.
--propertiesFilePath path: Specify the path to the properties file that contains the default command-line options.
-Q, --quiet: Run in quiet mode. Using quiet mode, no output is generated unless a significant error occurs during the import process.
-d, --debug: Use debug mode (verbose). Using debug mode, all advanced or debug messages are output.

A.3.6.7 General Options

-?, -H, --help: Display command-line usage information for the command and exit without making any attempt to run an import.
-V, --version: Display the version information for the directory server and exit rather than attempting to run this command.

A.3.6.8 Examples

The following examples show how to use the directory server commands.

Example A-86 Running an Offline Import

This example imports an LDIF file to the userRoot back end. The LDIF file path must be an absolute path on all platforms. The directory server must be stopped before running an offline import.

$ stop-ds
$ import-ldif -b dc=example,dc=com -n userRoot -l /usr/tmp/Example.ldif

Example A-87 Importing Part of an LDIF File Offline

This example imports part of an LDIF file to the userRoot back end. The import includes the base DN dc=example,dc=com but excludes the branch ou=people. Existing entries are replaced (-r) and information about any rejected entries are written to /usr/tmp/rejects.ldif. The LDIF file path must be an absolute path on all platforms. The directory server must be stopped before running an offline import.

$ stop-ds
$ import-ldif -b dc=example,dc=com -B "ou=people,dc=example,dc=com" \
  -l /usr/tmp/Example.ldif -n userRoot -r -R /usr/tmp/rejects.ldif

Example A-88 Importing Data From a MakeLDIF Template

This example imports sample data from a MakeLDIF template to the userRoot back end. The random seed (-s) determines the randomness of the data. The directory server must be stopped before running an offline import.

$ stop-ds
$ import-ldif -n userRoot -A example.template -s 0

Example A-89 Importing User Attributes Only

This example imports an LDIF file to the userRoot back end. Only user attributes are imported, specified by -i "*". The LDIF file path must be an absolute path on all platforms. On some systems, you might be required to enclose the asterisk in quotation marks ("*") or to escape the asterisk using a character appropriate to your shell. The directory server must be stopped before running an offline import.

$ stop-ds
$ import-ldif -b dc=example,dc=com -n userRoot -l /usr/tmp/Example.ldif -i "*"

Example A-90 Importing User Attributes and Excluding an Attribute

This example imports an LDIF file to the userRoot back end. All user attributes are imported, specified by -i "*", but the roomnumber attribute is excluded. The LDIF file path must be an absolute path on all platforms. On some systems, you might be required to enclose the asterisk in quotation marks ("*") or to escape the asterisk using a character appropriate to your shell. The directory server must be stopped before running an offline import.

$ stop-ds
$ import-ldif -b dc=example,dc=com -n userRoot -l /usr/tmp/Example.ldif \
  -i "*" -e "roomnumber"

Example A-91 Importing Operational Attributes Only

This example imports an LDIF file to the userRoot back end. Only operational attributes are imported, specified by -i "+". The LDIF file path must be an absolute path on all platforms. On some systems, you might be required to enclose the plus sign in quotation marks ("+") or to escape the plus sign using a character appropriate to your shell. The directory server must be stopped before running an offline import.

$ stop-ds
$ import-ldif -b dc=example,dc=com -n userRoot -l /usr/tmp/Example.ldif -i "+"

Example A-92 Importing Selected User and Operational Attributes

This example imports an LDIF file to the userRoot back end. Only the uid, cn, sn, dc, and creatorsname attributes are imported. The LDIF file path must be an absolute path on all platforms. The directory server must be stopped before running an offline import.

$ stop-ds
$ import-ldif -b dc=example,dc=com -n userRoot -l /var/tmp/Example.ldif \
  -i "uid" -i "cn" -i "sn" -i "dc" -i "creatorsname"

Example A-93 Running an Online Import

An import is automatically run online if you specify any of the task back end connection options. Because an online import contacts the server over SSL, you must specify how to trust the SSL server certificate. This examples uses the -X option to trust all certificates.

$ import-ldif -h localhost -p 6664 -D "cn=Directory Manager" -j /path/pwd-file \
  -X -b dc=example,dc=com -n userRoot -l /usr/tmp/Example.ldif

Example A-94 Scheduling an Import

You can schedule an import to run at some future date by using the -t or --start option to specify the start time. Like a regular online import, a scheduled import contacts the task back end of a running directory server and the relevant task back end connection options must be specified.

This example schedules an import to the userRoot back end to start on December 24.

$ import-ldif -h localhost -p 6664 -D "cn=Directory Manager" -j /path/pwd-file \
  -X -b dc=example,dc=com -n userRoot -l /usr/tmp/Example.ldif \
  --start 20081224121500
Import task 2008101712361910 scheduled to start Dec 24, 2008 12:15:00 PM SAST

You can view a scheduled task by using the manage-tasks command. For more information, see Section 13.4, "Configuring Commands As Tasks."

A.3.6.9 Exit Codes

Offline mode. An exit code of 0 indicates that the operation completed successfully. A non-zero exit code indicates that an error occurred during processing.
Online mode. If -t or --start is specified, an exit code of 0 indicates that the task was created successfully. A nonzero exit code indicates that an error occurred when the task was created. If -t or --start is not specified, the exit codes are the same as those specified for offline mode.

A.3.6.10 Using a Properties File

A.3.6.11 Location

UNIX and Linux: INSTANCE_DIR/OUD/bin/import-ldif
Windows: INSTANCE_DIR\OUD\bat\import-ldif.bat

A.3.6.12 Related Commands

Section A.3.5, "export-ldif"
Section A.3.7, "ldif-diff"
Section A.3.8, "ldifmodify"
Section A.3.9, "ldifsearch"
Section A.2.8, "manage-tasks"

A.3.7 ldif-diff

The ldif-diff command identifies the differences between two LDIF files.

A.3.7.1 Synopsis

ldif-diff options

A.3.7.2 Description

The ldif-diff command can be used to identify the differences between two LDIF files. The resulting output can be displayed on the terminal or saved to an output file. The resulting output contains all of the information necessary for someone to reverse any changes if necessary. For modify operations, only sets of add and delete change types are used, not the replace change type. For delete operations, the contents of the entry that has been removed are included in the changes displayed in the form of comments.

This command was designed to work on small data sets. It is only suitable in cases in which both the source and target data sets can fit entirely in memory at the same time. It is not intended for use on large data sets that cannot fit in available memory.

A.3.7.3 Options

The ldif-diff command accepts an option in either its short form (for example, -o outputFile) or its long form equivalent (for example, --outputLDIF outputFile).

-a, --ignoreAttrs file: Specify a file containing a list of attributes to ignore when computing the difference
--checkSchema: Consider the syntax of the attributes as defined in the schema to make the value comparison. The specified LDIF files must be conform to the server schema.
-e, --ignoreEntries file: Specify a file containing a list of entries (DNs) to ignore when computing the difference
-o, --outputLDIF outputLDIF: Specify the path to the output file to record the changes between the source and target LDIF data. If this is not provided, then the change information will be written to standard output.
-O, --overwriteExisting: Overwrite the output file specified with the --outputLDIF option. This option indicates that if the specified output file already exists that the file should be overwritten rather than appending to it. The option is only applicable if --outputLDIF is used.
-s, --sourceLDIF sourceLDIF: Specify the path to the source LDIF file, which contains the original data with no changes applied. This option is required.
-S, --singleValueChanges: Run in Single Value Change mode, in which each modify operation is broken into a separate modification per attribute value. For example, if a single modification adds five values to an attribute, the changes appear in the output as five separate modifications, each adding one attribute.
-t, --targetLDIF targetLDIF: Specify the path to the target LDIF file that contains the differences from the source LDIF. This option is required.
-?, -H, --help: Display command usage information and exit without attempting to perform any additional processing.
-V, --version: Display the directory server version information and exit rather than attempting to run this command.

A.3.7.4 Examples

The following examples show how to use the ldif-diff command.

Example A-95 Comparing Two LDIF files and Sending the Differences to Standard Output

The following command compares a source file (-s) with a target file (-t) and outputs the differences. For Windows platforms, specify the paths for the source file (for example, -s \temp\quentin.ldif) and the target file (for example, -t \temp\quentin.ldif):

$ ldif-diff -s /usr/local/quentin.ldif -t /usr/local/quentinr.ldif

dn: uid=qcubbins,ou=People,dc=example,dc=com
changetype: delete
# objectClass: person
# objectClass: organizationalPerson
# objectClass: top
# objectClass: inetOrgPerson
# cn: Quentin Cubbins
# sn: Cubbins
# uid: qcubbins
# userPassword: qcubbins
# givenName: Quentin
# description: This is Quentin's description.
# mail: qcubbins@example.com

dn: uid=qrcubbins,ou=People,dc=example,dc=com
changetype: add
objectClass: person
objectClass: organizationalPerson
objectClass: top
objectClass: inetOrgPerson
cn: Quentin R Cubbins
sn: Cubbins
uid: qrcubbins
userPassword: qrcubbins
givenName: Quentin
description: This is Quentin R's description.
mail: qrcubbins@example.com

Example A-96 Comparing Two LDIF files and Sending the Differences to a File

The following command compares a source file (-s) with a target file (-t) and sends the output to a file (-o). For Windows platforms, specify the paths for the source file (for example, -s \temp\quentin.ldif) and the target file (for example, -t \temp\quentin.ldif):

$ ldif-diff -s /usr/local/quentin.ldif -t /usr/local/quentinr.ldif \
  -o output.ldif

A.3.7.5 Exit Codes

An exit code of 0 indicates that the operation completed successfully. An exit code of 1 or greater indicates that an error occurred during processing.

A.3.7.6 Location

UNIX and Linux: INSTANCE_DIR/OUD/bin/ldif-diff
Windows: INSTANCE_DIR\OUD\bat\ldif-diff.bat

A.3.7.7 Related Commands

Section A.3.9, "ldifsearch"
Section A.3.8, "ldifmodify"
Section A.3.11, "make-ldif"

A.3.8 ldifmodify

The ldifmodify command makes changes to the contents of an LDIF file.

A.3.8.1 Synopsis

ldifmodify options

A.3.8.2 Description

The ldifmodify command can be used to make changes to the contents of an LDIF file. Although similar to the ldapmodify command, the ldifmodify command does not connect to the directory server but rather operates locally on the LDIF file. The command also does not accept change information on standard input. It must read all changes from a file.

To make it possible to operate on very large LDIF files with limited amounts of memory, the following limitations will be enforced on the types of changes that can be made:

No modify DNs. Modify DN operations are not supported. Only add, delete, and modify operations will be allowed.
No concurrent modify or delete operations. It is not possible to modify or delete an entry that is to be added during the course of processing.

A.3.8.3 Options

All options (with the exception of --help and --version) are required. The ldifmodify command accepts an option in either its short form (for example, -m changeFile) or its long form equivalent (for example, --changesLDIF changeFile).

-m, --changesLDIF changeFile: Specify the path to the file containing the changes to apply. The contents of this file must be in LDIF change format.
-s, --sourceLDIF sourceFile: Specify the path to the source LDIF file, which contains the data to be updated.
-t, --targetLDIF targetFile: Specify the path to the target LDIF file, which will consist of the data from the source LDIF with all of the specified changes applied.
-?, -H, --help: Display command usage information and exit without attempting to perform any additional processing.
-V, --version: Display the directory server version information and exit rather than attempting to run this command.

A.3.8.4 Examples

The following examples show how to use the ldifmodify command.

Example A-97 Modifying an LDIF File

Suppose that the source file is as follows:

dn: uid=qcubbins,ou=People,dc=example,dc=com
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
uid: qcubbins
givenName: Quentin
sn: Cubbins
cn: Quentin Cubbins
mail: qcubbins@example.com
userPassword: qcubbins
description: This is Quentin's description.

And suppose that the update (change) file is as follows:

## Add new telephone number for Quentin Cubbins
dn: uid=qcubbins,ou=People,dc=example,dc=com
changetype: modify
add: telephoneNumber
telephoneNumber: 512-401-1241

The following command updates a source file (-s) with changes listed in a modify file (-m) and outputs to a target file (-t). For Windows platforms, use the file paths for the modify file (for example, -m \temp\update.ldif), the source file (for example, -s \temp\quentin.ldif), and the target file (for example, -s \temp\quentin_updated.ldif):

$ ldifmodify -m /usr/local/update.ldif -s /usr/local/quentin.ldif \
-t /usr/local/quentin_updated.ldif

The updated file is as follows:

dn: uid=qcubbins,ou=People,dc=example,dc=com
objectClass: inetOrgPerson
objectClass: person
objectClass: top
objectClass: organizationalPerson
sn: Cubbins
userPassword: qcubbins
description: This is Quentin's description.
cn: Quentin Cubbins
telephoneNumber: 512-401-1241
givenName: Quentin
uid: qcubbins
mail: qcubbins@example.com

A.3.8.5 Exit Codes

An exit code of 0 indicates that the operation completed successfully. An exit code of 1 or greater indicates that an error occurred during processing.

A.3.8.6 Location

UNIX and Linux: INSTANCE_DIR/OUD/bin/ldifmodify
Windows: INSTANCE_DIR\OUD\bat\ldifmodify.bat

A.3.8.7 Related Commands

Section A.3.9, "ldifsearch"
Section A.3.7, "ldif-diff"
Section A.3.11, "make-ldif"

A.3.9 ldifsearch

The ldifsearch command performs searches in an LDIF file.

A.3.9.1 Synopsis

ldifsearch [options]

A.3.9.2 Description

The ldifsearch command can be used to perform searches in an LDIF file. Although similar to the ldapsearch command, the ldifsearch command does not perform any LDAP communication with the directory server but rather operates locally on the LDIF file.

A.3.9.3 Options

The ldifsearch command accepts an option in either its short form (for example, -b baseDN) or its long form equivalent (for example, --baseDN baseDN).

-b, -baseDN baseDN

Specify the base DN to use for the search operation. Multiple base DNs can be provided by using this option multiple times. If multiple values are provided, then an entry will be examined if it is within the scope of any of the search bases. If no search base is provided, then any entry contained in the LDIF files will be considered in the scope of the search.

-f, --filterFile filterFile

Specify the path to a file containing one or more filters to use when processing the search operation. If there are to be multiple filters, then the file should be structured with one filter per line. If this option is used, then any trailing options will be treated as separate attributes. Otherwise, the first trailing option must be the search filter.

-l, -ldifFile ldifFile

Specify the path to the LDIF file containing the data to be searched. Multiple LDIF files can be specified by providing this option multiple times. This option is required.

-o, -outputFile outputFile

Specify the path to the output file that contains the entries matching the provided search criteria. If this option is not provided, the matching entries will be written to standard output.

-O, --overwriteExisting

Overwrite the output file specified with the --outputFile option. This option indicates that if the specified output file already exists that the file should be overwritten rather than appending the data to existing data. This is only applicable if the --outputFile option is used.

-s, -searchScope searchScope

Specify the scope of the search operation. Its value must be one of the following:

base Examine only the entry specified by the --baseDN option.
one Examine only the entry specified by the --baseDN option and its immediate children.
sub or subordinate Examine the entry specified by the --baseDN option and its subtree.

Default value sub if the option is not specified.

-t, --timeLimit numSeconds

Indicate the maximum length of time in seconds that should be spent performing the searches. After this length of time has elapsed, the search ends.

-z, --sizeLimit sizeLimit

Set the maximum number of matching entries that the directory server should return to the client. If this is not provided, then there will be no maximum requested by the client. Note that the directory server can enforce a lower size limit than the one requested by the client.

-T, --dontWrap

Do not wrap long lines when displaying matching entries. If this option is not provided, long lines will be wrapped (in a manner compatible with the LDIF specification) to fit on an 80-column terminal.

-?, -H, --help

Display command usage information and exit without attempting to perform any additional processing.

-V, --version

Display the version information for the directory server.

A.3.9.4 Examples

The following examples show how to use the ldifsearch command.

Example A-98 Searching an LDIF File

The following command specifies the base DN (-b) and searches an LDIF file (-l) for an entry and returns its result to the screen if any entries match the search filter cn=Sam Carter. For Windows platforms, use the path where the LDIF file resides (for example, -l \temp\Example.ldif.

$ ldifsearch -b dc=example,dc=com -l /usr/local/Example.ldif "(cn=Sam Carter)"

dn: uid=scarter,ou=People,dc=example,dc=com
objectClass: inetOrgPerson
objectClass: person
objectClass: top
objectClass: organizationalPerson
ou: Accounting
ou: People
sn: Carter
facsimiletelephonenumber: +1 408 555 9751
roomnumber: 4600
userpassword: sprain
l: Sunnyvale
cn: Sam Carter
telephonenumber: +1 408 555 4798
uid: scarter
givenname: Sam
mail: scarter@example.com

Example A-99 Searching an LDIF File by Using a Filter File

Suppose that the file, filter.ldif, which contains the following search filter:

(&(ou=Accounting)(l=Cupertino))

The following command searches the LDIF file for entries that match the filter in the search filter file and outputs the results in an output file. The command specifies the base DN (-b) and searches the LDIF file (-l) using the search filter file (-f) and outputs the results in a file (-o). For Windows platforms, use the file paths for the LDIF file (for example, -l \temp\Example.ldif), the filter file (for example, -f \temp\filter.ldif), and the output file (for example, -o \temp\results.ldif):

$ ldifsearch -b dc=example,dc=com -l /usr/local/Example.ldif -f /usr/local/filter.ldif \
-o /home/local/results.ldif

A.3.9.5 Exit Codes

An exit code of 0 indicates that the operation completed successfully. An exit code of 1 or greater indicates that an error occurred during processing.

A.3.9.6 Location

UNIX and Linux: INSTANCE_DIR/OUD/bin/ldifsearch
Windows: INSTANCE_DIR\OUD\bat\ldifsearch.bat

A.3.9.7 Related Commands

Section A.3.8, "ldifmodify"
Section A.3.7, "ldif-diff"

A.3.10 list-backends

The list-backends command displays information about the available back ends.

A.3.10.1 Synopsis

list-backends [options]

A.3.10.2 Description

The list-backends command can be used to obtain information about the back ends defined in a directory server instance. Back ends are responsible for providing access to the server database.

The list-backends command has three modes of operation:

No options. When invoked with no options, display the back-end IDs for all back ends configured in the server, along with the base DNs for those back ends.
With backend ID. When used with the --backendID, list all of the base DNs for the back end with the specified back-end ID.
With baseDN. When used with the --baseDN option, list the back-end ID of the back end that should be used to hold the entry with the given DN and also indicate whether that DN is one of the configured base DNs for that back end.

A.3.10.3 Options

The following are available for use but are not required. The list-backends command accepts an option in either its short form (for example, -b baseDN) or its long form equivalent (for example, --baseDN baseDN).

A.3.10.4 Command Options

-b, --baseDN baseDN Specify the base DN from which the list-backends command should list the back-end ID. The option also indicates whether the specified DN is a baseDN for that back end.

-n, --backendID backendID Specify the back-end ID from which the command should display the associated base DN. This option can be used multiple times to display the base DNs for multiple back ends.

A.3.10.5 General Options

-?, -H, --help Display the command usage information and exit immediately without taking any other action.

-V, --version Display the directory server version information and exit rather than attempting to run this command.

A.3.10.6 Examples

The following examples show how to use the list-backends command.

Example A-100 Listing the Current Back Ends

The following command lists the current back ends on the directory server:

$ list-backends

Backend ID  Base DN
----------  -----------------
backup      cn=backups
config      cn=config
monitor     cn=monitor
schema      cn=schema
tasks       cn=tasks
userRoot    dc=example,dc=com

Example A-101 Listing the Back-end ID

The following command lists the back-end ID on the directory server:

$ list-backends --backendID monitor

Backend ID  Base DN
----------  ----------
monitor     cn=monitor

Example A-102 Listing the Base DN

The following command lists the base DN on the directory server:

$ list-backends --baseDN cn=backups

The provided DN 'cn=backups' is a base DN for the back end 'backup'

A.3.10.7 Exit Codes

An exit code of 0 indicates that the operation completed successfully. An exit code of 1 indicates that an error occurred during processing.

A.3.10.8 Location

UNIX and Linux: INSTANCE_DIR/OUD/bin/list-backends
Windows: INSTANCE_DIR\OUD\bat\list-backends.bat

A.3.11 make-ldif

The make-ldif command generates LDIF data based on a template file.

A.3.11.1 Synopsis

make-ldif [options]

A.3.11.2 Description

The make-ldif command can be used to generate LDIF data based on a template file. The command allows you to construct any amount of realistic sample data that is suitable for use in applications, such as performance and scalability testing, or to attempt to reproduce a problem observed in a production environment.

A.3.11.3 Options

The make-ldif command accepts an option in either its short form (for example, -o ldifFile) or its long form equivalent (for example, --ldifFile ldifFile).

-o, --ldifFile ldifFile: Specify the path to the LDIF file to which the generated data should be written. This is a required option.
-s, --randomSeed seed: Specify the integer value that should be used to seed the random number generator. If a random seed is provided, then generating data based on the same template file with the same seed will always generate exactly the same LDIF output. If no seed is provided, then the same template file will likely generate different LDIF output each time it is used.
-t, --templateFile templateFile: Specify the path to the template file that describes the data to be generated. This is a required option. You must specify an absolute path to the template file.
-?, -H, --help: Display command-line usage information for the command and exit without making any attempt to run the command.
-V, --version: Display the version information for the directory server.

A.3.11.4 Examples

The following examples show how to use the make-ldif command.

Example A-103 Creating a Sample LDIF File

The following command creates an LDIF file using the template (-t), writes to an output file (-o), and specifies the random seed (-s). For Windows platforms, enter the file paths to your output LDIF file (for example, -o path\to\Example.ldif) and to your template file (for example, -t INSTANCE_DIR\OUD\config\MakeLDIF\example.template).

The example.template file is located in the INSTANCE_DIR/OUD/config/MakeLDIF directory.

$ make-ldif -o /path/to/sample.ldif -s 0 \
-t INSTANCE_DIR/OUD/config/MakeLDIF/example.template

Processed 1000 entries
Processed 2000 entries
Processed 3000 entries
Processed 4000 entries
Processed 5000 entries
Processed 6000 entries
Processed 7000 entries
Processed 8000 entries
Processed 9000 entries
Processed 10000 entries
LDIF processing complete.  10003 entries written

Example A-104 Creating a Large Sample LDIF File

The example.template file (located in the installation directory under INSTANCE_DIR/OUD/config/MakeLDIF) contains a variable that sets the number of entries generated by the make-ldif command. You can change the number to create a very large sample LDIF file for your tests.

Open the example.template file, and change the numusers variable. By default, the variable is set to 10001. In this example, set the variable to 1000001:

define suffix=dc=example,dc=com
define maildomain=example.com
define numusers=1000001
...

Rerun the make-ldif command:

$ make-ldif -o /path/to/sample.ldif -s 0 \
-t INSTANCE_DIR/OUD/config/MakeLDIF/example.template
...
Processed 999000 entries
Processed 1000000 entries
LDIF processing complete.  1000003 entries written

A.3.11.5 Exit Codes

An exit code of 0 indicates that the operation completed successfully. An exit code of 1 indicates that an error occurred during processing.

A.3.11.6 Locations

UNIX and Linux: INSTANCE_DIR/OUD/bin/make-ldif
Windows: INSTANCE_DIR\OUD\bat\make-ldif.bat

A.3.11.7 Related Commands

Section A.3.9, "ldifsearch"
Section A.3.8, "ldifmodify"
Section A.3.7, "ldif-diff"

A.3.12 manage-account

The manage-account command manages user account information, primarily related to password policy state details.

A.3.12.1 Synopsis

manage-account subcommands options

A.3.12.2 Description

The manage-account command manages user account information, primarily related to password policy state details. The command interacts with the Password Policy State extended operation, which returns account, login, and password information for a user. Although the Password Policy State extended operation allows multiple operations per use, the manage-account command can run only one operation at a time. Users must have the password-reset privilege to use the Password Policy State extended operation.

Note that all time values are returned in generalized time format. All duration values are returned in seconds.

The manage-account command connects to the server over SSL through the administration connector (described in Section 13.3, "Managing Administration Traffic to the Server").

A.3.12.3 Subcommands

clear-account-is-disabled

Clear the disabled state for the user account. This will have the effect of enabling the account if it is disabled.

get-account-expiration-time

Return the account expiration time.

get-account-is-disabled

Return the disabled state for the user account.

get-all

Return all Password Policy State information for the user account.

get-authentication-failure-times

Return the authentication failure times for the user account.

get-grace-login-use-times

Return the grace login use times for the user account.

get-last-login-time

Return the last login time for the user.

get-password-changed-by-required-time

Return the password changed by the required time for the user.

get-password-changed-time

Return the time the password was last changed.

get-password-expiration-warned-time

Return the time the user was first warned about an upcoming password expiration.

get-password-history

Return the password history for the user account.

get-password-is-reset

Return the password reset state for the user, which indicates whether the user will be forced to change his password on the next login.

get-password-policy-dn

Return the DN of the password policy for a given user.

get-remaining-authentication-failure-count

Return the number of remaining authentication failures for the user before the user's account is locked.

get-remaining-grace-login-count

Return the number of remaining grace logins for the user.

get-seconds-until-account-expiration

Return the length of time before the account expires.

get-seconds-until-authentication-failure-unlock

Return the length of time before the user's account is automatically unlocked.

get-seconds-until-idle-lockout

Return the length of time before the account is idle-locked.

get-seconds-until-password-expiration

Return the length of time before the password expires.

get-seconds-until-password-expiration-warning

Return the length of time before the user is first warned about an upcoming password expiration.

get-seconds-until-password-reset-lockout

Return the length of time before the password reset lockout occurs.

get-seconds-until-required-change-time

Return the length of time before the user is required to change his password due to the required change time.

set-account-is-disabled

Disable the account. Required suboption:

--operationValue true/false. If set to TRUE, disable the user. If set to FALSE, enable the user.

A.3.12.4 Options

The manage-account command accepts an option in either its short form (for example, -b targetDN) or its long form equivalent (for example, --targetDN targetDN).

-b, --targetDN targetDN: Specify the DN of the user entry for which to get and set password policy state information.

A.3.12.5 LDAP Connection Options

The manage-account command contacts the directory server over SSL through the administration connector. These connection options are used to contact the directory server.

-D, --bindDN bindDN: Use the bind DN to authenticate to the directory server. This option is used when performing simple authentication and is not required if SASL authentication is to be used. The default value for this option is cn=Directory Manager.
-h, --hostname hostname: Contact the directory server on the specified hostname or IP address. If this option is not provided, a default of localhost is used.
-j, --bindPasswordFile filename: Use the bind password in the specified file when authenticating to the directory server.
-K, --keyStorePath path: Use the client keystore certificate in the specified path.
-N, --certNickname nickname: Use the specified certificate for client authentication.
-o, --saslOption name=value: Use the specified options for SASL authentication.
-p, --port port: Contact the directory server at the specified administration port. If this option is not provided, a default administration port of 4444 is used.
-P, --trustStorePath path: 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.
-u, --keyStorePasswordFile filename: Use the password in the specified file to access the certificates in the client keystore. This option is only required if --keyStorePath is used.
-U, --trustStorePasswordFile filename: 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).
-X, --trustAll: Trust all server SSL certificates that the directory server presents. 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.

A.3.12.6 General Options

-?, -H, --help: Display command-line usage information for the command and exit without making any attempt to run the command.
-V, --version: Display the version information for the directory server.

A.3.12.7 Examples

The following examples show how to use the directory server commands.

Example A-105 Viewing All Password Policy State Information for a User

The following command returns the password policy state information for a user:

$ manage-account get-all -h localhost -p 4444 -D "cn=Directory Manager" \
  -j /path/pwd-file -X -b "uid=scarter,ou=People,dc=example,dc=com" \

Password Policy DN:  cn=Default Password Policy,cn=Password Policies,cn=config
Account Is Disabled:  false
Account Expiration Time:
Seconds Until Account Expiration:
Password Changed Time:  19700101000000.000Z
Password Expiration Warned Time:
Seconds Until Password Expiration:
Seconds Until Password Expiration Warning:
Authentication Failure Times:
Seconds Until Authentication Failure Unlock:
Remaining Authentication Failure Count:
Last Login Time:
Seconds Until Idle Account Lockout:
Password Is Reset:  false
Seconds Until Password Reset Lockout:
Grace Login Use Times:
Remaining Grace Login Count:  0
Password Changed by Required Time:
Seconds Until Required Change Time:

Example A-106 Disabling a User Account

The following command disables a user's account uid=scarter:

$ manage-account set-account-is-disabled --operationValue true \
  -h localhost -p 4444 -D "cn=Directory Manager" -j /path/pwd-file -X \
  -b "uid=scarter,ou=People,dc=example,dc=com"

Account Is Disabled:  true

Example A-107 Enabling a User Account

The following command re-enables a user's disabled account:

$ manage-account clear-account-is-disabled \
  -h localhost -p 4444 -D "cn=Directory Manager" -j /path/pwd-file -X \
  -b "uid=scarter,ou=People,dc=example,dc=com"

Account Is Disabled:  false

A.3.12.8 Exit Codes

An exit code of 0 indicates that the operation completed successfully. A nonzero exit code indicates that an error occurred during processing.

A.3.12.9 Location

UNIX and Linux: INSTANCE_DIR/OUD/bin/manage-account
Windows: INSTANCE_DIR\OUD\bat\manage-account.bat

A.3.12.10 Related Commands

Section A.3.16, "verify-index"

A.3.13 rebuild-index

The rebuild-index command rebuilds a directory server index.

A.3.13.1 Synopsis

rebuild-index options

A.3.13.2 Description

The rebuild-index command is used to rebuild directory server indexes. Indexes are files that contain lists of values, where each value is associated with a list of entry identifiers to suffixes in the directory server database. When the directory server processes a search request, it searches the database using the list of entry identifiers in the indexes, thus speeding up the search. If indexes did not exist, the directory server would have to look up each entry in the database, which dramatically degrades performance.

The rebuild-index command is useful in the following cases:

When the index-entry-limit property of an index changes
When a new index is created

The rebuild-index command can be run with the server online. However, the backend database is unavailable while rebuild-index is running. Also, the rebuild-index command usually runs faster with the server offline, especially if the --rebuildAll option is specified.

Note:

As time progresses, the list of entry identifiers becomes unordered. As this happens, the performance of the rebuild-index command gradually decreases.

If you can avoid reindexing large databases, you should do so. Otherwise, if the performance of the rebuild-index command is severely compromised, reimport the database, to start with a fresh, ordered list of entry identifiers.

A.3.13.3 Options

The rebuild-index command accepts an option in either its short form (for example, -b baseDN) or its long form equivalent (for example, --baseDN baseDN).

A.3.13.4 Command Options

-b, --baseDN baseDN: Specify the base DN of a back end that supports indexing. The rebuild operation is performed on indexes within the scope of the given base DN.
-i, --index index: Specify the name of the indexes to rebuild. For an attribute index, this is simply an attribute name. At least one index must be specified for rebuild.
--rebuildAll: Rebuild all indexes that are contained in the back end that is specified by the base DN. This option not only re-indexes all attribute indexes but also the dn2id system index, any extensible and VLV indexes, and the dn2uri index. The rebuildAll option cannot be used with the -i option.
--tmpDirectory: Specify the location of a temporary work directory for scratch index files. The default temporary work directory is INSTANCE_DIR/OUD/import-tmp.

A.3.13.5 Task Back End Connection Options

Rebuilding an index online requires access to the tasks back end. Access to the tasks back end is provided over SSL through the administration connector. These connection options are used when the rebuild runs online.

-D, --bindDN bindDN: Use the bind DN to authenticate to the directory server. This option is used when performing simple authentication and is not required if SASL authentication is used. The default value for this option is cn=Directory Manager.
-h, --hostname hostname: Contact the directory server on the specified hostname or IP address. If this option is not provided, a default of localhost is used.
-j, --bindPasswordFile filename: Use the bind password in the specified file when authenticating to the directory server.
-K, --keyStorePath path: Use the client keystore certificate in the specified path.
-N, --certNickname nickname: Use the specified certificate for client authentication.
-o, --saslOption name=value: Use the specified options for SASL authentication.
-p, --port port: Contact the directory server at the specified administration port. If this option is not provided, the default administration port of 4444 is used.
-P, --trustStorePath path: 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.
-u, --keyStorePasswordFile filename: Use the password in the specified file to access the certificates in the client keystore. This option is only required if --keyStorePath is used.
-U, --trustStorePasswordFile filename: 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).
-X, --trustAll: Trust all server SSL certificates that the directory server presents. 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.

A.3.13.6 Task Scheduling Options

These options are used when you specify that the index should be rebuilt as a scheduled task.

--completionNotify emailAddress: Specify the email address of a recipient to be notified when the task completes. This option can be specified more than once in a single command.
--dependency taskId: Specify the ID of a task upon which this task depends. A task does not start executing until all of its dependencies have completed execution.
--errorNotify emailAddress: Specify the email address of a recipient to be notified if an error occurs when this task executes. This option can be specified more than once in a single command.
--failedDependencyAction action: Specify the action that this task will take if one of its dependent tasks fails. The value must be one of PROCESS, CANCEL, or DISABLE. If no value is specified, the default action is CANCEL.
--recurringTask schedulePattern: Indicates that the task is recurring and will be scheduled according to the schedulePattern, expressed as a crontab(5) compatible time and date pattern.
-t, --start startTime: Indicates the date and time at which the operation starts when scheduled as a directory server task expressed in the format YYYYMMDDhhmmss. A value of 0 schedules the task for immediate execution. When this option is specified, the operation is scheduled to start at the specified time after which the command exits immediately.

A.3.13.7 Utility Input/Output Options

--propertiesFilePath propertiesFilePath: Path to the file containing default property values used for command line
--noPropertiesFile: No properties file will be used to get default command line argument values.

A.3.13.8 General Options

-?, -H, --help: Display command-line usage information for the command and exit without making any attempt to stop or restart the directory server.
-V, --version: Display the version information for the directory server and exit rather than attempting to run this command.

A.3.13.9 Examples

The following examples show how to use the rebuild-index command.

Example A-108 Rebuilding an Index

First, display a list of indexes by using the dsconfig command as follows:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j /path/pwd-file -X \
  -n list-local-db-indexes --element-name userRoot

Local DB Index    : Type    : index-type
------------------:---------:--------------------
aci               : generic : presence
cn                : generic : equality, substring
displayName       : generic : equality, substring
ds-sync-conflict  : generic : equality
ds-sync-hist      : generic : ordering
entryUUID         : generic : equality
givenName         : generic : equality, substring
mail              : generic : equality, substring
member            : generic : equality
objectClass       : generic : equality
orclMTTenantGuid  : generic : equality
orclMTTenantUName : generic : equality, substring
orclMTUid         : generic : equality
sn                : generic : equality, substring
telephoneNumber   : generic : equality, substring
uid               : generic : equality
uniqueMember      : generic : equality

The following command rebuilds indexes (-i) with a base DN (-b).

Because this command runs offline, the directory server must be stopped before you run it.

$ rebuild-index -b dc=example,dc=com -i uid -i mail
[15/Dec/2011:15:28:01 +0100] category=JEB severity=NOTICE msgID=8847497 
  msg=Rebuild of index(es) uid started with 202 total entries to process
...
[15/Dec/2011:15:28:02 +0100] category=JEB severity=NOTICE msgID=8847493 
  msg=Rebuild complete. Processed 202 entries in 1 seconds (average rate 135.2/sec)

Example A-109 Rebuilding All Indexes

This example uses the --rebuildAll option to rebuild all indexes.

$ rebuild-index -b "dc=example,dc=com" --rebuildAll

Example A-110 Rebuilding Extensible Indexes

You can rebuild an extensible index in any of three ways:

Rebuild all indexes by specifying the --rebuildAll option.
Rebuild the attribute index on which the extensible index is based, by specifying the -i option. For example, -i cn.

All indexes based on this attribute are rebuilt, including any extensible indexes that are associated with the attribute.
Rebuild a specific extensible index by specifying it with the -i option. For example, -i cn.es.lte or -i sn.en.sub.

A.3.13.10 Exit Codes

An exit code of 0 indicates that the operation completed successfully. An exit code of 1 indicates that an error occurred during processing.

A.3.13.11 Location

UNIX and Linux: INSTANCE_DIR/OUD/bin/rebuild-index
Windows: INSTANCE_DIR\OUD\bat\rebuild-index.bat

A.3.13.12 Related Commands

Section A.3.16, "verify-index"
Section A.2.4, "dsconfig"

A.3.14 restore

The restore command restores a backup of a directory server back end.

A.3.14.1 Synopsis

restore options

A.3.14.2 Description

The restore command restores a backup of a directory server back end. Only one back end can be restored at a time. You can use this command to perform a restore operation immediately, or to schedule a restore to run at a later time. For more information, see Section 13.4, "Configuring Commands As Tasks."

You can restore a back end when the server is offline or schedule a task when the server is online to restore a back end at a later stage. If the server is online, the restore command connects to the server over SSL through the administration connector. For more information about the administration connector, see Section 13.3, "Managing Administration Traffic to the Server."

A.3.14.3 Options

The restore command accepts an option in either its short form (for example, -I backupID) or its long form equivalent (for example, --backupID backupID).

-d, --backupDirectory path: Restore using the directory that contains the backup archive. This directory must exist and must contain a backup descriptor file and one or more backups for a given back end. The backup descriptor file is read to obtain information about the available backups and the options used to create them. This is a required option.
-I, --backupID backupID: Specify the backup ID of the backup to be restored. If this option is not provided, the latest backup contained in the backup directory is restored.
-l, --listBackups: Display information about the available backups contained in the backup directory. This option causes the command to exit without performing any restore.
-n, --dry-run: Verify that the specified backup is valid (that is, ensure that it appears to be a valid archive, and that any hash, signature matches its contents, or both). This option does not actually attempt to restore the backup.

A.3.14.4 Task Back End Connection Options

Running an online restore requires access to the tasks back end. Access to the tasks back end is provided over SSL through the administration connector. These connection options are used when the restore runs online.

-D, --bindDN bindDN: Use the bind DN to authenticate to the directory server. This option is used when performing simple authentication and is not required if SASL authentication is to be used. The default value for this option is cn=Directory Manager.
-h, --hostname hostname: Contact the directory server on the specified hostname or IP address. If this option is not provided, a default of localhost is used.
-j, --bindPasswordFile filename: Use the bind password in the specified file when authenticating to the directory server.
-K, --keyStorePath path: Use the client keystore certificate in the specified path.
-N, --certNickname nickname: Use the specified certificate for client authentication.
-o, --saslOption name=value: Use the specified options for SASL Authentication.
-p, --port port: Contact the directory server at the specified administration port. If this option is not provided, a default administration port of 4444 is used.
-P, --trustStorePath path: 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.
-u, --keyStorePasswordFile filename: Use the password in the specified file to access the certificates in the client keystore. This option is only required if --keyStorePath is used.
-U, --trustStorePasswordFile filename: 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).
-X, --trustAll: Trust all server SSL certificates that the directory server presents. 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.

A.3.14.5 Task Scheduling Options

--completionNotify emailAddress: Specify the email address of a recipient to be notified when the task completes. This option can be specified more than once in a single command.
--dependency taskId: Specify the ID of a task upon which this task depends. A task does not start executing until all of its dependencies have completed execution.
--errorNotify emailAddress: Specify the email address of a recipient to be notified if an error occurs when this task executes. This option can be specified more than once in a single command.
--failedDependencyAction action: Specify the action this task will take should one if its dependent tasks fail. The value must be one of PROCESS,CANCEL,DISABLE. If not specified, the backup defaults to CANCEL.
--recurringTask schedulePattern: Indicates that the task is recurring and will be scheduled according to the schedulePattern, expressed as a crontab(5) compatible time and date pattern.
-t, --start startTime: Indicates the date and time at which the operation starts when scheduled as a directory server task expressed in the format YYYYMMDDhhmmss. A value of 0 causes the task to be scheduled for immediate execution. When this option is specified, the operation is scheduled to start at the specified time after which this command exits immediately.

A.3.14.6 Command Input/Output Options

--noPropertiesFile: Indicate that a properties file will not be used to get the default command-line options.
--propertiesFilePath path: Specify the path to the properties file that contains the default command-line options.

A.3.14.7 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 directory server and exit rather than attempting to run this command.

A.3.14.8 Examples

The following examples show how to use the restore command.

Example A-111 Displaying the Backup Information

The following command lists (-l) the backup information in the backup descriptor file (backup.info) for the directory server. You can use this option to display backup information whether the server is running or stopped.

$ restore -l -d /tmp/backup/userRoot
Backup ID:          20081016050258Z
Backup Date:        16/Oct/2008:09:30:00 +0200
Is Incremental:     false
Is Compressed:      true
Is Encrypted:       true
Has Unsigned Hash:  false
Has Signed Hash:    true
Dependent Upon:     none

Example A-112 Restoring a Backup

The following command restores a back end from the backup directory. You can only restore one back end at a time. The server must be stopped before you run this command.

$ stop-ds
$ restore -d /tmp/backup/userRoot
[16/Oct/2008:10:32:52 +0200] category=JEB severity=NOTICE msgID=8847445 
msg=Restored: 00000000.jdb (size 321954)

Example A-113 Restoring an Encrypted Backup

Restoring a hashed or encrypted backup requires a connection to an online server instance, over SSL through the administration connector. When you restore an encrypted backup, you must therefore specify the connection details, including the host, administration port, bind DN and bind password. You must also specify the certificate details for the SSL connection.

The following command restores an encrypted, hashed backup. The self signed certificate is trusted using the -X (--trustAll) option.

$ restore -h localhost -p 4444 -D "cn=directory manager" -j /path/pwd-file -X \
  -d /tmp/backup/userRoot/
Restore task 2008101610403710 scheduled to start immediately
[16/Oct/2008:10:40:38 +0200] severity="NOTICE" msgCount=0 msgID=9896306 
 message="The backend userRoot is now taken offline"
[16/Oct/2008:10:40:39 +0200] severity="NOTICE" msgCount=1 msgID=8847445 
 message="Restored: 00000000.jdb (size 331434)"
[16/Oct/2008:10:40:40 +0200] severity="NOTICE" msgCount=2 msgID=8847402 
 message="The database backend userRoot containing 102 entries has started"
Restore task 2008101610403710 has been successfully completed

Example A-114 Scheduling a Restore

Scheduling a restore requires online access to the tasks back end. Access to this back end is provided over SSL through the administration connector. When you schedule a restore, you must therefore specify the connection details, including the host, administration port, bind DN and bind password. You must also specify the certificate details for the SSL connection.

The following command schedules a task to restore the userRoot back end at a specific start time by using the --start option. The command sends a completion and error notification to admin@example.com. The self signed certificate is trusted using the -X (--trustAll) option.

You can view this scheduled task by using the manage-tasks command. For more information, see Section 13.4, "Configuring Commands As Tasks." You must ensure that the server is running prior to the scheduled restore date and time.

$ restore -h localhost -p 4444 -D "cn=directory manager" -j /path/pwd-file -X \
  -d /backup/userRoot --start 20081025121500 --completionNotify admin@example.com \
  --errorNotify admin@example.com
Restore task 2008101610442610 scheduled to start Oct 25, 2008 12:15:00 PM SAST

A.3.14.9 Exit Codes

An exit code of 0 indicates that the operation completed successfully. An exit code of 1 indicates that an error occurred during processing.

A.3.14.10 Using a Properties File

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

A.3.14.11 Location

UNIX and Linux: INSTANCE_DIR/OUD/bin/restore
Windows: INSTANCE_DIR\OUD\bat\restore.bat

A.3.14.12 Related Commands

Section A.3.3, "dbtest"
Section A.2.8, "manage-tasks"

A.3.15 split-ldif

The split-ldif command splits an LDIF file into multiple LDIF files according to a given distribution workflow element. The generated LDIF files are used to populate the partitions of a distribution deployment.

A.3.15.1 Synopsis

split-ldif options

A.3.15.2 Description

The split-ldif command splits an LDIF file into multiple LDIF files according to a given distribution workflow element. The data in the LDIF file is split based on the attributes indicated and based on the distribution type defined. The generated LDIF files are then used to populate the partitions. For each partition the split-ldif command creates a partition file as follows:

outputDirectory/outputFilenamePrefix-partitionID.ldif

Sometimes, the distribution algorithm is not able to determine the partition to which an entry should be sent, either because the entry does not contain all the parameters required by the algorithm, or the required parameters are present but they match no partition. In such a scenario, the output is written to an error file.

All the entries that do not have all the required parameters are written to the following error file:

outputDirectory/outputFilenamePrefix-missingrequired-param.ldif

All the entries that have the required parameters but whose parameters do not match any configured partition are written to the following error file:

outputDirectory/outputFilenamePrefix-partition-not-found.ldif

However, for the global index initialization you use the directory containing the files compatible with the global index format. The split-ldif command creates one directory per attribute to be indexed, and each directory contains files for initializing the global index.

The global index catalog is populated using the files in the directory created, which do not have a LDIF format. For more information, see Section A.2.7, "gicadm."

A.3.15.3 Options

The split-ldif command accepts an option in either its short form (for example, -i ldifFile) or its long form equivalent (for example, --ldifFile ldifFile).

-i, --ldifFile ldifFile: Name of the LDIF file to split. Global Index Options and Split Options can be used to customize the behavior.
-l, --listDistributionNames: Lists the enabled distribution workflow elements from the directory server's configuration.

Note:

The -l, --listDistributionNames option lists only the enabled distributions, because you cannot use a disabled distribution to split an ldif file.

A.3.15.4 Global Index Options

-x, --index attributeTypeName: Generates an index file to be used for the global index catalog, for the listed attribute type.
-c, --onlyCatalog: Generates only the index file.

A.3.15.5 Split Options

-d, --distributionName distributionName: Name of the distribution workflow element to split the data.
-p, --forcePartitionId partitionId: Generates an index file where all the entries are distributed to the same single partition having the listed partitionId.
-o, --outputDirectory outputDirectory: The directory where output LDIF files will be generated.
-O, --outputFilenamePrefix outputFilePrefix: The prefix of the filename to generate (will contain the partition ID and the.ldif extension).
-f, --force: Overwrites generated files that may already exist from previous use.

A.3.15.6 General Options

-V, --version: Display the version information for the directory server.
-e, --help-examples: Display examples of the usage.
-?, -H, --help: Display command-line usage information for the command and exit without making any attempt to stop or restart the directory server.

A.3.15.7 Examples

Example A-115 Using split-ldif to Populate a Global Index with One Indexed Attribute

The following command uses an existing database file (-i) which it splits into several files, based on the distribution information already defined in the proxy deployment. The command defines the distribution workflow element name (-d), the database file (-i) to be split, and the attribute to be indexed in the global index files (-x). Indicating -f will overwrite any existing LDIF files.

You must have deployed a proxy instance with distribution before running this command.

$ split-ldif -d "distrib-we" -i database.ldif -x employeenumber -f

Assuming, for this example, that your distribution algorithm was numeric, and that you set two partitions with boundaries 1-1000 and 1000-2000. When you run the command above, the following directory and LDIF files are created:

database-1.ldif: This file contains all the entries from database with employee numbers from 1-999, which will be used to populate partition 1.
database-2.ldif: This file contains all the entries from database with employee numbers from 1000-1999, which will be used to populate partition 2.
catalog\employeenumber: This directory contains the global index files for the employee number attribute.

Example A-116 Using split-ldif to Populate a Global Index with Several Indexed Attributes

The following command uses an existing database file (-i) which it splits into several files, based on the distribution information already defined in the proxy deployment. The command defines the distribution workflow element name (-d), the database file (-i) to be split, and the attributes to be indexed in the global index files (-x). Indicating -f will overwrite any existing LDIF files.

You must have deployed a proxy instance with distribution before running this command.

$ split-ldif -d "distrib-we" -i database.ldif \

-x employeenumber -x uid -f

Assuming, for this example, that your distribution algorithm was numeric, and that you set two partitions with boundaries 1-50000 and 50000-100001. When you run the command above, the following LDIF files and directories are created:

database-1.ldif - This file contains all the entries from database with employee numbers from 1-49999, which will be used to populate partition 1.
database-2.ldif - This file contains all the entries from database with employee numbers from 50000-100000, which will be used to populate partition 2.
catalog\employeenumber - This directory contains the global index files for the employee number attribute.
catalog\uid - This directory contains the global index files for the uid attribute.

A.3.15.8 Location

UNIX and Linux: INSTANCE_DIR/OUD/bin/split-ldif
Windows: INSTANCE_DIR\OUD\bat\split-ldif.bat

A.3.15.9 Related Commands

gicadm

A.3.16 verify-index

The verify-index command validates directory index data.

A.3.16.1 Synopsis

verify-index options

A.3.16.2 Description

The verify-index command is used to check the consistency between the index and entry data within the directory server database. This command also provides information about the number of index keys that have reached the index entry limit.

The command checks the following information:

All entries are properly indexed
All index data reference entries exist
Data matches the corresponding index data

At the present time, this command is only available for a directory server back end that uses Oracle Berkeley DB Java Edition to store its information. None of the other back end types currently available maintain on-disk indexes. Therefore, there is no need to have any command that can verify index consistency.

Directory administrators can use this command when the directory server is running or stopped. Note, however, that using verify-index when the server is running impacts the overall performance of the directory server as well as the command. For example, on a very busy online server, the verify-index command could take significantly longer to process compared to running the command on an offline, or stopped, directory server.

To use this command, the --baseDN option must be used to specify the base DN of the back end below which to perform the validation.

A.3.16.3 Options

The verify-index command accepts an option in either its short form (for example, -b baseDN) or its long form equivalent (for example, --baseDN baseDN).

A.3.16.4 Command Options

-b, --baseDN baseDN

Specify the base DN for which to perform the verification. The provided value must be a base DN for a back end based on the Berkeley DB Java Edition. This is a required option, and only one base DN may be provided.

-c, --clean

Verify that an index is "clean", which means that all of the entry IDs in all of the index keys refer to entries that actually exist and match the criteria for that index key. If this option is provided, then exactly one index should be specified using the --index option. If this option is not given, then the verification process will clean the id2entry database (which is a mapping of each entry ID to the actual data for that entry) and ensure that all of the entry contents are properly indexed.

--countErrors

Count the number of errors found during the verification and return that value as the exit code. Values greater than 255 will be returned as 255 due to exit code restrictions.

-i, --index index

Specify the name of an index for which to perform the verification. If the --clean option is provided, then this argument must be provided exactly once. Otherwise, it may be specified zero or more times. If the option is not provided, then all indexes will be checked. For an attribute index, the index name should be the name of the attribute, and an index must be configured for that attribute in the associated back end. You can also specify the following internal indexes, which are used internally on the server:

dn2id — A mapping of entry DNs to their corresponding entry IDs.

id2children — A mapping of the entry ID for an entry to the entry IDs of its immediate children.

id2subtree — A mapping of the entry ID for an entry to the entry IDs of all of its subordinates.

A.3.16.5 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 directory server and exit rather than attempting to run this command.

A.3.16.6 Examples

The following examples show how to use the verify-index command.

Example A-117 Verifying an Index

The following command verifies that the uid index (-i uid) under dc=example,dc=com (-b dc=example,dc=com) is "clean" (-c). This "clean" option checks that each entry in the uid index maps to an actual database entry with the uid attribute.

$ verify-index -b dc=example,dc=com -c -i uid

[26/Jul/2007:16:42:31 -0500] category=BACKEND severity=NOTICE msgID=8388709
msg=Checked 150 records and found 0 error(s) in 0 seconds (average rate 331.1/sec)

Example A-118 Verifying an Index and Counting Errors

The following command counts the number of discrepancies (--countErrors) in the sn (surname) index (-i sn) under the dc=example,dc=com base DN (-b dc=example,dc=com):

$ verify-index -b dc=example,dc=com -c -i sn --countErrors

[31/Jul/2007:02:23:52 -0500] category=BACKEND severity=NOTICE msgID=8388709 msg=
Checked 466 records and found 0 error(s) in 0 seconds (average rate 1298.1/sec)
[31/Jul/2007:02:23:52 -0500] category=BACKEND severity=NOTICE msgID=8388710 msg=
Number of records referencing more than one entry: 225
[31/Jul/2007:02:23:52 -0500] category=BACKEND severity=NOTICE msgID=8388711 msg=
Number of records that exceed the entry limit: 0
[31/Jul/2007:02:23:52 -0500] category=BACKEND severity=NOTICE msgID=8388712 msg=
Average number of entries referenced is 2.59/record
[31/Jul/2007:02:23:52 -0500] category=BACKEND severity=NOTICE msgID=8388713 msg=
Maximum number of entries referenced by any record is 150

A.3.16.7 Exit Codes

An exit code of 0 indicates that the operation completed successfully. An exit code of 1 or greater indicates that an error occurred during processing.

A.3.16.8 Location

UNIX and Linux: INSTANCE_DIR/OUD/bin/verify-index
Windows: INSTANCE_DIR\OUD\bat\verify-index.bat

A.3.16.9 Related Commands

Section A.3.13, "rebuild-index"

A.4 LDAP Client Commands

The following sections describe the LDAP client utilities:

Section A.4.1, "ldapcompare"
Section A.4.2, "ldapdelete"
Section A.4.3, "ldapmodify"
Section A.4.4, "ldappasswordmodify"
Section A.4.5, "ldapsearch"

A.4.1 ldapcompare

The ldapcompare command compares LDAP entries.

A.4.1.1 Synopsis

ldapcompare options

A.4.1.2 Description

The ldapcompare command is used to issue LDAP compare requests to the directory server. Compare requests can be used to determine whether a given entry or set of entries have a particular attribute-value combination. The only information returned from a successful compare operation is an indication as to whether the comparison evaluated to true or false. No other information about the entry is provided.

The syntax of the ldapcompare tool on the command-line can take any of these forms:

ldapcompare [ options ] attribute:value [ "targetDN" ... | -f DNfile]
ldapcompare [ options ] attribute::base64value [ "targetDN" ... | -f DNfile ]
ldapcompare [ options ] attribute:fileURL [ "targetDN" ... | -f DNfile ]

where

options are the command-line options, described in the following section.
attribute is the name of the attribute type, followed by one of the three ways to specify its comparative value. The attribute type name and value string should be enclosed in single quotes (") for the shell.
targetDN is the distinguished name (DN) or list of DNs in which to search for the given attribute and compare its value.
DNfile is a file with a list of DNs, one per line, to search for the given attribute and compare its value.

A.4.1.3 Options

The ldapcompare command accepts an option in either its short form (for example, -D bindDN) or its long form equivalent (for example, --bindDN bindDN).

A.4.1.4 Command Options

--assertionFilter filter

Perform a search using the LDAP assertion control (as defined in RFC 4528) to indicate that the operation should only be processed if the assertion contained in the provided filter is true.

-c, --continueOnError

Continue processing even if an error occurs. This applies when multiple entry DNs have been given either as trailing options or in a file specified with the --filename option. If an error occurs while processing a compare request, then the client will continue with the next entry DN if the --continueOnError option has been provided, or it will exit with an error if it was not provided.

-f, --filename filename

Specify the path to a file that contains one or more filters to use when processing the search operation. If there are to be multiple entry DNs, then the file should be structured with one DN per line. All comparisons will be performed using the same connection to the directory server in the order that they appear in the file. If this option is not provided, at least one entry DN must follow the attribute-value assertion. If this option is used, the only trailing option required is the attribute-value assertion. The --filename option takes precedence over any DNs provided as additional command-line options. Additional DNs are simply ignored.

-J, --control controloid[criticality[:value|::b64value|:<fileurl]]

Perform a search with the specified control in search requests sent to the directory server. This option makes it possible to include arbitrary request controls that the client cannot directly support. The value for this option must be in the form:

oid[:criticality[:value|::b64value|:<fileurl]]

The elements of this value include:

oid Use the OID for the control. For certain types of controls, a text name may be used instead of the numeric OID (for search operations, this includes managedsait for the manage DSA IT control). This element is required. Human-readable names can be used in place of the OID to reference controls that do not require values using the -J or control option. These OID names are the following:
- accountusable or accountusability Use in place of the Account Usability Request Control OID: 1.3.6.1.4.1.42.2.27.9.5.8 (no value)
- authzid or authorizationidentity Use in place of the Authorization Identity Request Control OID: 2.16.840.1.113730.3.4.16 (no value)
- effectiverights Use in place of the Get Effective Rights Control OID: 1.3.6.1.4.1.42.2.27.9.5.2 (value = authorization ID)
- managedsait Use in place of the Manage DSA IT Control OID: 2.16.840.1.113730.3.4.2 (no value)
- noop or no-op Use in place of the LDAP No-op Control OID: 1.3.6.1.4.1.4203.1.10.2 (no value)
- pwpolicy or password policy Use in place of the Password Policy Request OID: 1.3.6.1.4.1.42.2.27.8.5.1 (no value)
- subtreedelete or treedelete Use in place of the Subtree Delete Request Control OID: 1.2.840.113556.1.4.805 (no value)
criticality If true, the control should be marked critical (meaning that the directory server should not process the operation unless it can meet the requirements of this control). If false, the control should not be marked critical. If this subcommand is not provided, then the control is not marked critical.
value Specifies the value for the control. This form should only be used if the value can be expressed as a string. It must not be used in conjunction with either the ::b64value or :< fileurl forms. If none of these subcommands is present, then the control will not have a value.
b64value Specifies the value for the control in base64-encoded form. This subcommand must not be used in conjunction with either the :value or :< fileurl forms. If none of these subcommands is present, then the control will not have a value.
fileurl Specifies a URL that references a file from which the value of the control should be taken. It must not be used in conjunction with either the :value or ::b64value forms. If none of these subcommands is present, then the control will not have a value.

For example, the value 1.3.6.1.4.1.42.2.27.9.5.2:true:dn:uid=dmiller,ou=people,dc=example,dc=com will include a critical control with an OID of 1.3.6.1.4.1.42.2.27.9.5.2, marked as critical (true), and with a string value for the authorization ID dn:uid=dmiller,ou=people,dc=example,dc=com. Or, you can use the OID names: effectiverights:true:dn:uid=dmiller,ou=people,dc=example,dc=com.

-n, --dry-run

Run in no-op mode. That is, report what should happen but do not actually perform any searches or communicate with the server in any way.

A.4.1.5 LDAP Connection Options

-D, --bindDN bindDN

Use the bind DN to authenticate to the directory server. This option is used when performing simple authentication and is not required if SASL authentication is to be used. The default value for this option is cn=Directory Manager.

-h, --hostname address

Contact the directory server on the specified host name or IP address. If it is not provided, then a default address of localhost will be used.

-j, --bindPasswordFile bindPasswordFile

Use the bind password in the specified file when authenticating to the directory server. The option is used for simple authentication, as well as for password-based SASL mechanisms such as CRAM-MD5, DIGEST-MD5, and PLAIN. It is not required if no authentication is to be performed. This option must not be used in conjunction with --bindPassword.

SASL is not supported for a proxy server instance.

-K, --keyStorePath keyStorePath

Use the client keystore certificate in the specified path for secure communication when using the SSL or the StartTLS extended operation. This option should only be necessary if the client needs to present a certificate to the directory server, for example, when using SASL EXTERNAL authentication.

SASL is not supported for a proxy server instance.

-N, --certNickName certNickName

Use the specified certificate for certificate-based client authentication.

-o, --saslOption name=value

Use the specified option when performing SASL authentication. Multiple SASL options can be provided by using this option multiple times, once for each option.

SASL is not supported for a proxy server instance.

-p, --port port

Contact the directory server at the specified port. If this option is not provided, then a default port of 389 will be used.

-P, --trustStorePath trustStorePath

Use the client trust store certificate in the specified path for secure communication when using the SSL or the StartTLS extended operation. This option is not needed if --trustAll is used, although a trust store should be used when working in a production environment.

-q, --useStartTLS

Use the StartTLS Extended Operation when communicating with the directory server. This option must not be used in conjunction with --useSSL.

-r, --useSASLExternal

Use the SASL EXTERNAL mechanism for authentication, which attempts to identify the client by using an SSL certificate that it presents to the directory server. If this option is used, then the --keyStorePath option must also be provided to specify the path to the client keystore and either the --useSSL or the --useStartTLS option must be used to establish a secure communication channel with the server.

SASL is not supported for a proxy server instance.

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

-U, --trustStorePasswordFile trustStorePasswordFile

-V, --ldapVersion version

Set the LDAP protocol version that the client should use when communicating with the directory server. The value must be either 2 (for LDAPv2 communication) or 3 (for LDAPv3). If this option is not provided, then the client will use LDAPv3.

-w, --bindPassword bindPassword

Use the bind password when authenticating to the directory server. This option can be used for simple authentication as well as password-based SASL mechanisms. This option must not be used in conjunction with --bindPasswordFile. To prompt for the password, type -w -.

SASL is not supported for a proxy server instance.

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

-X, --trustAll

Trust any certificate that the directory 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.

-Z, --useSSL

Use Secure Sockets Layer when communicating with the directory server. If SSL is to be used, then the --port option should be used to specify the server's secure port.

A.4.1.6 Command Input/Output Options

--noPropertiesFile: Indicate that a properties file will not be used to get the default command-line options.
--propertiesFilePath propertiesFilePath: Specify the path to the properties file that contains the default command-line options.
-v, --verbose: Run in verbose mode, displaying process and diagnostic information on standard output.

A.4.1.7 General Options

-?, -H, --help: Display command-line usage information for the command and exit without making any attempt to run the command.
-V, --version: Display the version information for the directory server.

A.4.1.8 Examples

The following examples show how to use the ldapcompare command.

Example A-119 Comparing an Entity for Group Membership

The following command specifies the host name (-h) that is connected to port 1389 (-p) and verifies if an employee (uid=scarter) is a member of a group (cn=Accounting Managers).

$ ldapcompare -h hostname -p 1389 \
"uniquemember:uid=scarter,ou=People,dc=example,dc=com" \
"cn=Accounting Managers,ou=groups,dc=example,dc=com"

Comparing type uniquemember with value uid=scarter,ou=People,dc=example,dc=com 
in entry cn=Accounting Managers,ou=groups,dc=example,dc=com 
Compare operation returned true for entry
cn=Accounting Managers,ou=groups,dc=example,dc=com

Example A-120 Comparing an Attribute Value to an Entry

The following command specifies the hostname (-h) that is connected to port 1389 (-p) and verifies if an attribute (ou=Accounting) is present in an entity's (cn=Sam Carter) record.

$ ldapcompare -h hostname -p 1389 "ou:Accounting" \
"uid=scarter,ou=People,dc=example,dc=com"

Comparing type ou with value Accounting in entry uid=scarter,ou=People,dc=example,dc=com
Compare operation returned true for entry uid=scarter,ou=People,dc=example,dc=com

Example A-121 Using ldapcompare with Server Authentication

The following command uses server authentication, specifies the host name (-h), SSL port (-p), base DN (-b), the bind DN (-D), the bind password (-w), trust store file path (-P), and checks if the attribute is present in the entry. For Windows platforms, use the path where your trust store file resides (for example, -P \temp\certs\cert.db).

$ ldapcompare -h hostname -p 1636 -D "cn=Directory Manager" \
-j pwd-file -P /home/kwinters/certs/cert.db \
'givenname:Sam' "uid=scarter,ou=People,dc=example,dc=com"

Comparing type givenname with value Sam in entry uid=scarter,ou=People,dc=example,dc=com
Compare operation returned true for entry uid=scarter,ou=People,dc=example,dc=com

Example A-122 Using ldapcompare with Client Authentication

The following command uses client authentication with the compare. The command uses SSL (-Z) with the SSL port (-p), specifies the trust store file path (-P), the certificate nickname (-N), the keystore file path (-K), the keystore password (-W) and checks if the entity's given name givenname=Sam is present in the entry. For Windows platforms, use the path where your trust store file resides (for example, -P \temp\certs\cert.db) and where the path where your keystore file resides (-K \temp\security\key.db).

$ ldapcompare -h hostname -p 1636 -Z \
-P /home/kwinters/security/cert.db -N "kwcert" \
-K /home/kwinters/security/key.db -W KeyPassword \
'givenname:Sam' "uid=scarter,ou=People,dc=example,dc=com"

Comparing type givenname with value Sam in entry uid=scarter,ou=People,dc=example,dc=com
Compare operation returned true for entry uid=scarter,ou=People,dc=example,dc=com

A.4.1.9 Exit Codes

An exit code of 6 indicates that the comparison is successful. An exit code of 5 indicates that the comparison is unsuccessful. Any other exit code indicates that an error occurred during processing.

A.4.1.10 Using a CLI Properties File

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

The following options can be stored in a properties file:

assertionFilter
bindDN
bindPassword
bindPasswordFile
certNickname
continueOnError
control
dry-run
filename
hostname
keyStorePassword
keyStorePasswordFile
keyStorePath
ldapVersion
port
saslOption
trustAll
trustStorePassword
trustStorePasswordFile
trustStorePath
useSASLExternal
useSSL
useStartTLS
verbose

Entries in the properties file have the following format:

toolname.propertyname=propertyvalue

For example:

ldapcompare.ldapport=12345

A.4.1.11 Location

UNIX and Linux: INSTANCE_DIR/OUD/bin/ldapcompare
Windows: INSTANCE_DIR\OUD\bat\ldapcompare.bat

A.4.1.12 Related Commands

Section A.4.2, "ldapdelete"
Section A.4.3, "ldapmodify"
Section A.4.4, "ldappasswordmodify"
Section A.4.5, "ldapsearch"

A.4.2 ldapdelete

The ldapdelete command issues LDAP delete requests to the directory server in order to remove entries.

A.4.2.1 Synopsis

ldapdelete [option] [DN]

A.4.2.2 Description

The ldapdelete command issues LDAP delete requests to the directory server in order to remove entries. Unless the --filename option is given, an entry DN must be given as the only trailing option to specify which entry should be removed.

A.4.2.3 Before You Begin

Many UNIX or Linux operating systems provide an installed version of common LDAP client commands, such as ldapsearch, ldapmodify, and ldapdelete in the /usr/bin directory. You can check if a version is on your system by entering the command: which ldapdelete. If the command returns a value (seen below), you will need to update your $PATH to the INSTANCE_DIR/OUD/bin directory or create an alias to the directory server instance.

$ which ldapdelete (UNIX/Linux)
/usr/bin/ldapdelete

A.4.2.4 Options

The ldapdelete command accepts an option in either its short form (for example, -D bindDN) or its long form equivalent (for example, --bindDN bindDN).

A.4.2.5 Command Options

-c, --continueOnError

Continue processing even if an error occurs. This operation applies when multiple entry DNs have been given either as trailing options or in a file specified with the --filename option. If an error occurs while processing a compare request, then the client will continue with the next entry DN if the --continueOnError option has been provided, or it will exit with an error if that option was not provided.

-f, --filename filename

Specify the path to a file that contains one or more filters to use when processing the search operation. If there are multiple entry DNs, then the file should be structured with one DN per line. If this option is used, then do not add any trailing options. The DN of the entry to remove should be the only trailing option.

-J, --control controloid[:criticality[:value|::b64value|:<fileurl]]

oid[:criticality[:value|::b64value|:<fileurl]]

The elements of this value include:

oid. Use the OID for the control. For certain types of controls, a text name may be used instead of the numeric OID (for search operations, this includes managedsait for the manage DSA IT control). This element is required. Human-readable names can be used in place of the OID to reference controls that do not require values using the -J or control option. These OID names are the following:

accountusable or accountusability — Use in place of the Account Usability Request Control OID:1.3.6.1.4.1.42.2.27.9.5.8 (no value).

authzid or authorizationidentity — Use in place of the Authorization Identity Request Control OID: 2.16.840.1.113730.3.4.16 (no value).

effectiverights — Use in place of the Get Effective Rights Control OID: 1.3.6.1.4.1.42.2.27.9.5.2 (value = authorization ID).

managedsait — Use in place of the Manage DSA IT Control OID: 2.16.840.1.113730.3.4.2 (no value).

noop or no-op — Use in place of the LDAP No-op Control OID: 1.3.6.1.4.1.4203.1.10.2 (no value).

pwpolicy or password policy — Use in place of the Password Policy Request Control OID: 1.3.6.1.4.1.42.2.27.8.5.1 (no value).

subtreedelete or treedelete — Use in place of the Subtree Delete Request Control OID: 1.2.840.113556.1.4.805 (no value).
criticality. If true, the control should be marked critical (meaning that the directory server should not process the operation unless it can meet the requirements of this control). If false, the control should not be marked critical. If this subcommand is not provided, then the control is not marked critical.
value. Specifies the value for the control. This form should only be used if the value can be expressed as a string. It must not be used in conjunction with either the::b64value or :< fileurl forms. If none of these subcommands is present, then the control will not have a value.
b64value. Specifies the value for the control in base64-encoded form. This subcommand must not be used in conjunction with either the :value or :< fileurl forms. If none of these subcommands is present, then the control will not have a value.
fileurl. Specifies a URL that references a file from which the value of the control should be taken. It must not be used in conjunction with either the :value or ::b64value forms. If none of these subcommands is present, then the control will not have a value.

For example, the value 1.3.6.1.4.1.42.2.27.9.5.2:true:dn:uid=dmiller,ou=people,dc=example,dc=com will include a critical control with an OID of 1.3.6.1.4.1.42.2.27.9.5.2, marked as critical (true), and with a string value for the authorization ID dn:uid=dmiller,ou=people,dc=example,dc=com. Or, you can use the OID names: effectiverights:true:dn:uid=dmiller,ou=people,dc=example,dc=com.

-n, --dry-run

Run in no-op mode. That is, report what should happen but do not actually perform any searches or communicate with the server in any way.

-x, --deleteSubtree

Delete the specified entry and all entries below it.

A.4.2.6 LDAP Connection Options

-D, --bindDN bindDN

-h, --hostname address

Contact the directory server on the specified host name or IP address. If it is not provided, then a default address of localhost will be used.

-j, --bindPasswordFile bindPasswordFile

SASL is not supported for a proxy server instance.

-K, --keyStorePath keyStorePath

SASL is not supported for a proxy server instance.

-N, --certNickName certNickName

Use the specified certificate for certificate-based client authentication.

-o, --saslOption name = value

Use the specified option when performing SASL authentication. Multiple SASL options can be provided by using this option multiple times, once for each option. See Section 19.6, "Using SASL Authentication" for more information.

SASL is not supported for a proxy server instance.

-p, --port port

Contact the directory server at the specified port. If this option is not provided, then a default port of 389 will be used.

-P, --trustStorePath trustStorePath

-q, --useStartTLS

Use the StartTLS Extended Operation when communicating with the directory server. This option must not be used in conjunction with --useSSL.

-r, --useSASLExternal

SASL is not supported for a proxy server instance.

--trustStorePassword trustStorePassword

-u, --keyStorePasswordFile keyStorePasswordFile

-U, --trustStorePasswordFile trustStorePasswordFile

-V, --ldapVersion version

-w, --bindPassword bindPassword

SASL is not supported for a proxy server instance.

-W, --keyStorePassword keyStorePassword

-X, --trustAll

-Z, --useSSL

Use Secure Sockets Layer when communicating with the directory server. If SSL is to be used, then the --port option should be used to specify the server's secure port.

A.4.2.7 Command Input/Output Options

--noPropertiesFile: Indicate that a properties file will not be used to get the default command-line options.
--propertiesFilePath propertiesFilePath: Specify the path to the properties file that contains the default command-line options.
-v, --verbose: Run in verbose mode, displaying process and diagnostic information on standard output.

A.4.2.8 General Options

-?, -H, --help: Display command-line usage information for the command and exit without making any attempt to run the command.
-V, --version: Display the version information for the directory server.

A.4.2.9 Examples

The following examples show how to use the ldapdelete command.

Example A-123 Deleting an Entry from the Command Line

The following command specifies the host name (-h), the port (-p), the bind DN (-D), the bind password (-w), and deletes a single entry:

$ ldapdelete -h hostname -p 1389 -D "cn=Directory Manager" -j pwd-file \
"uid=mgarza,ou=People,dc=example,dc=com"

Example A-124 Deleting Multiple Entries by Using a DN File

The following file contains a list of DN's for deletion. The file must list each DN on a separate line.

uid=mgarza,ou=People,dc=example,dc=com
uid=wsmith,ou=People,dc=example,dc=com
uid=jarrow,ou=People,dc=example,dc=com
uid=mbean,ou=People,dc=example,dc=com

The following command specifies the host name (-h), the port (-p), the bind DN (-D), and the bind password (-w), and reads the entries in a file for deletion. If an error occurs, the command continues (-c) to the next search item. For Windows platforms, use the path where the deletion file resides (for example, -f \temp\delete.ldif):

$ ldapdelete -h hostname -p 1389 -D "cn=Directory Manager" -j pwd-file \
-c -f /usr/local/delete.ldif

Example A-125 Deleting Entries by Using Server Authentication

The following command uses server authentication to delete an entry. The command specifies the host name (-h), SSL port (-p), bind DN (-D), the bind password (-w), trust store file path (-P), and LDIF file (-f) that contains the deletes. If an error occurs, the command continues (-c) to the next search item. For Windows platforms, use the path where the deletion file resides (for example, -f \temp\delete.ldif) and the file where the trust store password resides (for example, -P \temp\certs\cert.db):

$ ldapdelete -h hostname -p 1636 -c -f /usr/local/delete.ldif \
-D "cn=Directory Manager" -j pwd-file \
-P /home/kwinters/certs/cert.db

Example A-126 Deleting Entries by Using Client Authentication

The following command uses client authentication to perform a delete option. The command uses SSL (-Z) with the SSL port (-p), specifies the trust store file path (-P), the certificate nickname (-N), the keystore file path (-K), the keystore password (-W) and the LDIF file (-f) that contains the deletions. If an error occurs, the command continues (-c) to the next search item. For Windows platforms, use the path where the deletion file resides (for example, -f \temp\delete.ldif), the file where the trust store password resides (for example, -P \temp\certs\cert.db), and the file where the keystore password resides (for example, -K \temp\security\key.db).

$ ldapdelete -h hostname -p 1636 -c -f /usr/local/delete.ldif \
-Z -P /home/kwinters/security/cert.db -N "kwcert" \
-K /home/kwinters/security/key.db -W keypassword

A.4.2.10 Exit Codes

An exit code of 0 indicates that the operation completed successfully. A nonzero exit code indicates that an error occurred during processing.

A.4.2.11 Using a CLI Properties File

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

The following options can be stored in a properties file:

bindDN
bindPassword
bindPasswordFile
certNickname
continueOnError
control
deleteSubtree
dry-run
filename
hostname
keyStorePassword
keyStorePasswordFile
keyStorePath
ldapVersion
port
saslOption

SASL is not supported for a proxy server instance
trustAll
trustStorePassword
trustStorePasswordFile
trustStorePath
useSASLExternal

SASL is not supported for a proxy server instance.
useSSL
useStartTLS
verbose

Entries in the properties file have the following format:

toolname.propertyname=propertyvalue

For example:

ldapdelete.ldapport=12345

A.4.2.12 Location

UNIX and Linux: INSTANCE_DIR/OUD/bin/ldapdelete
Windows: INSTANCE_DIR\OUD\bat\ldapdelete.bat

A.4.2.13 Related Commands

Section A.4.1, "ldapcompare"
Section A.4.3, "ldapmodify"
Section A.4.4, "ldappasswordmodify"
Section A.4.5, "ldapsearch"

A.4.3 ldapmodify

The ldapmodify command modifies directory entries.

A.4.3.1 Synopsis

ldapmodify [options] [filter] [attributes]

A.4.3.2 Description

The ldapmodify command can be used to perform LDAP modify, add, delete, and modify DN operations in the directory server. The operations to perform in the directory server should be specified in LDIF change format, as described in RFC 2849 (http://www.ietf.org/rfc/rfc2849.txt). This change syntax uses the changetype keyword to indicate the type of change.

An add change record is straightforward, because it is a complete entry in LDIF form with a changetype value of add. For example:

dn: uid=john.doe,ou=People,dc=example,dc=com
changetype: add
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
uid: john.doe
givenName: John
sn: Doe
cn: John Doe
mail: john.doe@example.com
userPassword: password

A delete change record is even simpler than an add change record. The add record consists of a line with the entry DN followed by another line with a changetype of delete. For example:

dn: uid=john.doe,ou=People,dc=example,dc=com
changetype: delete

The modify change record is the most complex operation, because of the number of variants. The modify change records all start with the entry DN followed by a changetype of modify. The next line consists of either add, delete, or replace followed by an attribute name indicating what modification will be and to which attribute. The change record may optionally be followed by one or more lines containing the attribute name followed by a value to use for the modification (that is, a value to add to that attribute, remove from that attribute, or use to replace the existing set of values). Multiple attribute changes can be made to an entry in the same modify operation by separating changes with a line containing only a dash, starting the next line with a new add, delete, or replace tag followed by a colon and the next attribute name, and then setting of values for that attribute. For example:

dn: uid=john.doe,ou=People,dc=example,dc=com
changetype: modify
replace: description
description: This is the new description for John Doe
-
add: mailAlternateAddress
mailAlternateAddress: jdoe@example.com

Modify DN change records should always contain the newRDN and deleteOldRDN elements and can optionally contain the newSuperior component to specify a new parent for the target entry. For example:

dn: uid=john.doe,ou=People,dc=example,dc=com
changetype: moddn
newRDN: uid=jdoe
deleteOldRDN: 1

If no arguments are provided to the ldapmodify command, it attempts to interact with a Directory Server instance using an unauthenticated connection using the loopback address on port 389, and information about the changes to request will be read from standard input. This is unlikely to succeed, as it will almost certainly be necessary to at least provide arguments that will be used to specify how to authenticate to the server.

A.4.3.3 Before You Begin

Many UNIX and Linux operating systems provide an installed version of common LDAP client commands, such as ldapsearch, ldapmodify, and ldapdelete in the /usr/bin directory. You can check if a version is on your system by entering the command: which ldapmodify. If the command returns a value (seen below), you will need to update your $PATH to INSTANCE_DIR/OUD/bin or create an alias to the directory server instance.

$ which ldapmodify (Unix/Linux)
/usr/bin/ldapmodify

A.4.3.4 Options

The ldapmodify command accepts an option in either its short form (for example, -D bindDN) or its long form equivalent (for example, --bindDN bindDN).

A.4.3.5 Command Options

-a, --defaultAdd

Add entries. Treat records with no changetype element as an add request. This option can be used to add entries from a standard LDIF file that does not contain information in the LDIF change format.

--assertionFilter filter

Perform a search using the LDAP assertion control (as defined in RFC 4528 (http://www.ietf.org/rfc/rfc4528.txt)) to indicate that the operation should only be processed if the assertion contained in the provided filter is true.

-c, --continueOnError

Continue processing even if an error occurs. Use this option when using multiple search filters in a file --filename. If an error occurs during processing, the directory server will continue processing the next search filter. Otherwise the command will exit before all searches have been completed.

-f, --filename filename

Read modifications from the specified file containing one or more filters to use during the modify operation. The records in the LDIF file should be in the LDIF change format (that is, including the changetype element). If the LDIF file only contains entries that should be added to the directory server, then the file can be used with the --defaultAdd option even if the entries do not have a changetype element. The provided file can contain multiple changes as long as there is at least one blank line between change records.

If this option is not provided, then the ldapmodify command will attempt to read change information from standard input. This makes it possible to have the change records either provided interactively by the target user on the command line or piped into the command from some other source.

-J, --control controloid[:criticality[:value|::b64value|:<fileurl]]

oid[: criticality[:value|::b64value|:<fileurl]]

The elements of this value include:

oid. Use the OID for the control. For certain types of controls, a text name may be used instead of the numeric OID (for search operations, this includes managedsait for the manage DSA IT control). This element is required. Human-readable names can be used in place of the OID to reference controls that do not require values using the -J or control option. These OID names are the following:

accountusable or accountusability — Use in place of the Account Usability Request Control OID: 1.3.6.1.4.1.42.2.27.9.5.8 (no value).

authzid or authorizationidentity — Use in place of the Authorization Identity Request Control OID: 2.16.840.1.113730.3.4.16 (no value).

effectiverights — Use in place of the Get Effective Rights Control OID: 1.3.6.1.4.1.42.2.27.9.5.2 (value = authorization ID).

managedsait — Use in place of the Manage DSA IT Control OID: 2.16.840.1.113730.3.4.2 (no value).

noop or no-op — Use in place of the LDAP No-op Control OID: 1.3.6.1.4.1.4203.1.10.2 (no value).

pwpolicy or password policy — Use in place of the Password Policy Request Control OID: 1.3.6.1.4.1.42.2.27.8.5.1 (no value).

subtreedelete or treedelete — Use in place of the Subtree Delete Request Control OID: 1.2.840.113556.1.4.805 (no value).
criticality. If true, the control should be marked critical (meaning that the directory server should not process the operation unless it can meet the requirements of this control). If false, the control should not be marked critical. If this subcommand is not provided, then the control is not marked critical.
value. Specifies the value for the control. This form should only be used if the value can be expressed as a string. It must not be used in conjunction with either the::b64value or :< fileurl forms. If none of these subcommands is present, then the control will not have a value.
b64value. Specifies the value for the control in base64-encoded form. This subcommand must not be used in conjunction with either the :value or :< fileurl forms. If none of these subcommands is present, then the control will not have a value.
fileurl. Specifies a URL that references a file from which the value of the control should be taken. It must not be used in conjunction with either the :value or ::b64value forms. If none of these subcommands is present, then the control will not have a value.

For example, the value 1.3.6.1.4.1.42.2.27.9.5.2:true:dn:uid=dmiller,ou=people,dc=example,dc=com will include a critical control with an OID of 1.3.6.1.4.1.42.2.27.9.5.2, marked as critical (true), and with a string value for the authorization ID dn:uid=dmiller,ou=people,dc=example,dc=com. Or, you can use the OID names: effectiverights:true:dn:uid=dmiller,ou=people,dc=example,dc=com.

-n, --dry-run

Run in no-op mode. That is, report what should happen but do not actually perform any searches or communicate with the server in any way.

--postReadAttributes attrList

Use the LDAP ReadEntry Post-read Control (as defined in RFC 4527 (http://www.ietf.org/rfc/rfc4527.txt)) to indicate that the directory server should return a copy of the target entry as it was immediately after the update. This is only applicable for add, modify, and modify DN operations. The value for this option should be a comma-separated list of the attributes to include in the representation of the pre-read entry. The same conventions apply to this list as for the list of attributes to return in the ldapsearch command (that is, it is possible to use * for all user attributes, + for all operational attributes, @ocname for all attributes in the specified objectclass, and so on). If no attributes are specified (signified with empty quotes), then all user attributes will be returned.

--preReadAttributes attrList

Use the LDAP ReadEntry Pre-read Control (as defined in RFC 4527 (http://www.ietf.org/rfc/rfc4527.txt)) to indicate that the directory server should return a copy of the target entry as it was immediately before the update. This is only applicable for delete, modify, and modify DN operations. The value for this option should be a comma-separated list of the attributes to include in the representation of the pre-read entry. The same conventions apply to this list as for the list of attributes to return in the ldapsearch command (that is, it is possible to use * for all user attributes, + for all operational attributes, @ocname for all attributes in the specified objectclass, and so on). If no attributes are specified (signified with empty quotes), then all user attributes will be returned.

-Y, --proxyAs authzID

Use the Proxied Authorization Control to specify the identity of the user for whom the operations should be performed. This will use version 2 of the Proxied Authorization Control as defined in RFC 4370 (http://www.ietf.org/rfc/rfc4370.txt). The value of the option should be an authorization ID in the form dn: followed by the DN of the target user (for example, dn:uid=john.doe,ou=People,dc=example,dc=com), or u: followed by the user name (for example, u:john.doe). If this option is not provided, then proxied authorization will not be used.

A.4.3.6 LDAP Connection Options

-D, --bindDN bindDN

Use the bind DN to authenticate to the directory server. This option is used when performing simple authentication. The default value for this option is cn=Directory Manager. It is not required when using SASL authentication or if no authentication is to be performed.

-E, --reportAuthzID

Use the authorization identity request control (as defined in RFC 3829 (http://www.ietf.org/rfc/rfc3829.txt)) in the bind request so that the directory server returns the corresponding authorization ID to the client when authentication has completed. (The line containing the authorization ID will be prefixed with a # character, making it a comment if the output is to be interpreted as an LDIF.)

-h, --hostname address

Contact the directory server on the specified host name or IP address. If it is not provided, then a default address of localhost will be used.

-j, --bindPasswordFile bindPasswordFile

SASL is not supported for a proxy server instance.

-K, --keyStorePath keyStorePath

SASL is not supported for a proxy server instance.

-N, --certNickName certNickName

Use the specified certificate for certificate-based client authentication.

-o, --saslOption name = value

Use the specified option when performing SASL authentication. Multiple SASL options can be provided by using this option multiple times, once for each option. For information about using SASL authentication in clients, see Section 19.7, "Configuring SASL Authentication."

SASL is not supported for a proxy server instance.

-p, --port port

Contact the directory server at the specified port. If this option is not provided, then a default port of 389 will be used.

-P, --trustStorePath trustStorePath

-q, --useStartTLS

Use the StartTLS extended operation when communicating with the directory server. This option must not be used in conjunction with --useSSL.

-r, --useSASLExternal

SASL is not supported for a proxy server instance.

--trustStorePassword trustStorePassword

-u, --keyStorePasswordFile keyStorePasswordFile

-U, --trustStorePasswordFile trustStorePasswordFile

-V, --ldapVersion version

-w, --bindPassword bindPassword

SASL is not supported for a proxy server instance.

-W, --keyStorePassword keyStorePassword

-X, --trustAll

-Z, --useSSL

Use SSL when communicating with the directory server. If SSL is to be used, then the --port option should be used to specify the server's secure port.

A.4.3.7 Command Input/Output Options

--noPropertiesFile: Indicate that a properties file will not be used to get the default command-line options.
--propertiesFilePath propertiesFilePath: Specify the path to the properties file that contains the default command-line options.
-v, --verbose: Run in verbose mode, displaying process and diagnostic information on standard output.

A.4.3.8 General Options

-?, -H, --help: Display command-line usage information for the command and exit without making any attempt to run the command.
-V, --version: Display the version information for the directory server.

A.4.3.9 Examples

The following examples show how to use the ldapmodify command.

Example A-127 Adding an Entry

The following LDIF file contains an entry for an employee:

dn: uid=Marcia Garza,ou=People,dc=example,dc=com
cn: Marcia Garza
sn: Garza
givenName: Marcia
objectClass: person
objectClass: inetOrgPerson
objectClass: top
objectClass: organizationalPerson
ou: Accounting
ou: People

The following command specifies the host name (-h), port (-p), bind DN (-D), bind password (-w), reads the modifications from the file (-f) and adds the entry (-a) to the database. For Windows platforms, specify the path to your LDIF file (for example, -f \temp\add_entry.ldif).

$ ldapmodify -h hostname -p 1389 -D "cn=Directory Manager" -j pwd-file \
-a -f /usr/local/add_entry.ldif

Example A-128 Adding an Attribute to an Entry

The following LDIF file modifies an entry by adding a telephonenumber attribute:

dn: uid=Marcia Garza,ou=People,dc=example,dc=com
changetype: modify
add: telephonenumber
telephonenumber: +1 408 555 8283

The following command specifies the host name (-h), port (-p), bind DN (-D), bind password (-w), reads the modifications from the file (-f) and adds an attribute to the entry. For Windows platforms, specify the path to your LDIF file (for example,

-f \temp\add_attribute.ldif).

$ ldapmodify -h hostname -p 1389 -D "cn=Directory Manager" -j pwd-file \
-f /usr/local/add_attribute.ldif

Example A-129 Modifying the Value of an Attribute

The following LDIF file modifies the value of the telephonenumber attribute:

dn: uid=Marcia Garza,ou=People,dc=example,dc=com
changetype: modify
replace: telephonenumber
telephonenumber: +1 408 555 6456

The following command specifies the hostname (-h), port (-p), bind DN (-D), bind password (-w), reads the modifications from the file (-f) and modifies the attribute's value. For Windows-platforms, specify the path to your LDIF file (for example, -f \temp\modify_attribute.ldif).

$ ldapmodify -h hostname -p 1389 -D "cn=Directory Manager" -j pwd-file \
-f /usr/local/modify_attribute.ldif

Example A-130 Modifying Multiple Attributes

The following LDIF file contains multiple modifications to an entry:

dn: uid=Marcia Garza,ou=People,dc=example,dc=com
changetype: modify
replace: telephonenumber
telephonenumber: +1 408 555 6465
-
add: facsimiletelephonenumber
facsimiletelephonenumber: +1 408 222 4444
-
add: l
l: Sunnyvale

The following command specifies the host name (-h), port (-p), bind DN (-D), bind password (-w), reads the modifications from the file (-f) and processes the changes to the database. For Windows platforms, specify the path to your LDIF file (for example,-f \temp\mod_attribute.ldif):

$ ldapmodify -h hostname -p 1389 -D "cn=Directory Manager" -j pwd-file \
-f /usr/local/mod_attribute.ldif

Example A-131 Deleting an Attribute from the Command Line

The following command specifies the host name (-h), port (-p), bind DN (-D), bind password (-w), and deletes the facsimiletelephonenumber attribute for an entry. Because the command is run from the command line, enter the dn, changetype, modification operation, and then press Control-D (UNIX, Linux) or Control-Z (Windows) to process it:

$ ldapmodify -h hostname -p 1389 -D "cn=Directory Manager" -j pwd-file
dn: uid=Marcia Garza,ou=People,dc=example,dc=com
changetype: modify
delete: facsimiletelephonenumber
(Press Control-D for Unix, Linux)
(Press Control-Z for Windows)

Example A-132 Deleting an Entry from the Command Line

The following command specifies the hostname (-h), port (-p), bind DN (-D), bind password (-w), and deletes the entry. Because the command is run from the command line, enter the dn, changetype, and then press Control-D (UNIX, Linux) or Control-Z (Windows) to process it:

$ ldapmodify -h hostname -p 1389 -D "cn=Directory Manager" -j pwd-file
dn: uid=Marcia Garza,ou=People,dc=example,dc=com
changetype: delete
(Press Control-D for Unix, Linux)
(Press Control-Z for Windows)

Example A-133 Using ldapmodify with Server Authentication

The following command uses the -P SSL option to perform a modify with server authentication. The command specifies the host name (-h), SSL port (-p), base DN (-b), the bind DN (-D), the bind password (-w), trust store file path (-P), and LDIF file (-f) that contains the changes. For Windows platforms, specify the paths for the modification file (for example, -f \temp\myldif.ldif) and trust store file (for example, -P \temp\certs\cert.db):

$ ldapmodify -h hostname -p 1636 -f /home/local/myldif.ldif \
-D "cn=Directory Manager" -j pwd-file \
-P /home/scarter/certs/cert.db

Example A-134 Using ldapmodify with Client Authentication

The following command uses the -P SSL option to perform a modify using client authentication. The command uses SSL (-Z) with the SSL port (-p) and specifies the trust store file path (-P), the certificate nickname (-N), the keystore file path (-K), the keystore password (-W) and the LDIF file (-f) that contains the changes. For Windows platforms, specify the paths for the modification file (for example, -f \temp\myldif.ldif), trust store file (for example, -P \certs\cert.db), and the keystore file (for example, -K \security\key.db):

$ ldapmodify -h hostname -p 1636 -f /home/local/myldif.ldif \
-Z -P /home/scarter/security/cert.db -N "sccert" \
-K /home/scarter/security/key.db -W keypassword

A.4.3.10 Exit Codes

An exit code of 0 indicates that the operation completed successfully. A nonzero exit code indicates that an error occurred during processing.

A.4.3.11 Using a CLI Properties File

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

The following options can be stored in a properties file:

assertionFilter
bindDN
bindPassword
bindPasswordFile
certNickname
continueOnError
control
dry-run
filename
hostname
keyStorePassword
keyStorePasswordFile
keyStorePath
ldapVersion
port
postReadAttributes
preReadAttributes
proxyAs
reportAuthzID
saslOption

SASL is not supported for a proxy server instance.
trustAll
trustStorePassword
trustStorePasswordFile
trustStorePath
useSASLExternal

SASL is not supported for a proxy server instance.
useSSL
useStartTLS
verbose

Entries in the properties file have the following format:

toolname.propertyname=propertyvalue

For example:

ldapmodify.ldapport=12345

A.4.3.12 Location

UNIX and Linux: INSTANCE_DIR/OUD/bin/ldapmodify
Windows: INSTANCE_DIR\OUD\bat\ldapmodify.bat

A.4.3.13 Related Commands

Section A.4.1, "ldapcompare"
Section A.4.2, "ldapdelete"
Section A.4.4, "ldappasswordmodify"
Section A.4.5, "ldapsearch"

A.4.4 ldappasswordmodify

The ldappasswordmodify command modifies LDAP passwords.

A.4.4.1 Synopsis

ldappasswordmodify options

A.4.4.2 Description

The ldappasswordmodify command can be used to change or reset user passwords with the LDAP password modify extended operation as defined in RFC 3062 (http://www.ietf.org/rfc/rfc3062.txt).

Using this mechanism for changing user passwords offers a number of benefits over a simple LDAP modify operation targeted at the password attribute, including the following:

Changing one's own password. The command allows a user to change his own password even after it has expired, provided that this capability is allowed in that user's password policy.
Supplying clear-text password. The command provides a mechanism for supplying the clear-text version of the current password for further validation of the user's identity.
Using authorization ID. When changing a user's password, the user can be specified by using an authorization ID (prefixed by dn: or u:) in addition to a full DN.
Generating passwords. If a new password is not provided, then the server can generate one for the user, provided that this capability is allowed in that user's password policy.

A.4.4.3 Options

The ldappasswordmodify command accepts an option in either its short form (for example, -D bindDN) or its long form equivalent (for example, --bindDN bindDN).

A.4.4.4 Command Options

-a, --authzID authzID

Specify an authorization ID for the user whose password is to be changed. The authorization ID can be in the form dn: followed by the DN of the target user, or u: followed by the user name of the target user. If this option is not provided, then no authorization ID will be included in the request and the password for the authenticated user will be changed. This option must not be used in conjunction with the --provideDNForAuthzID option.

-A, --provideDNForAuthzID

Indicate that the bind DN should be used as the authorization ID for the password modify operation. This option must not be used in conjunction with the --authzID option.

-c, --currentPassword currentPassword

Specify the current password for the user. It must not be used in conjunction with --currentPasswordFile. The user's current password must be provided in cases in which no authentication is performed, for example, if a user is trying to change his password after it has already expired. The password might also be required by the server based on the password policy configuration even if a bind password was provided.

-C, --currentPasswordFile currentPasswordFile

Read the current password from the specified file. It must not be used in conjunction with --currentPassword. The user's current password must be provided in cases in which no authentication is performed, for example, if a user is trying to change his password after it has already expired. The password might also be required by the server based on the password policy configuration even if a bind password was provided.

-J, --control controloid[:criticality[:value|::b64value|:<fileurl]]

oid[:criticality[:value|::b64value|:<fileurl]]

The elements of this value include:

oid. Use the OID for the control. For certain types of controls, a text name may be used instead of the numeric OID (for search operations, this includes managedsait for the manage DSA IT control). This element is required. Human-readable names can be used in place of the OID to reference controls that do not require values using the -J or control option. These OID names are the following:

accountusable or accountusability — Use in place of the Account Usability Request Control OID: 1.3.6.1.4.1.42.2.27.9.5.8 (no value).

authzid or authorizationidentity — Use in place of the Authorization Identity Request Control OID: 2.16.840.1.113730.3.4.16 (no value).

effectiverights — Use in place of the Get Effective Rights Control OID: 1.3.6.1.4.1.42.2.27.9.5.2 (value = authorization ID).

managedsait — Use in place of the Manage DSA IT Control OID: 2.16.840.1.113730.3.4.2 (no value).

noop or no-op — Use in place of the LDAP No-op Control OID: 1.3.6.1.4.1.4203.1.10.2 (no value).

pwpolicy or password policy — Use in place of the Password Policy Request Control OID: 1.3.6.1.4.1.42.2.27.8.5.1 (no value).

subtreedelete or treedelete — Use in place of the Subtree Delete Request Control OID: 1.2.840.113556.1.4.805 (no value).
criticality. If true, the control should be marked critical (meaning that the directory server should not process the operation unless it can meet the requirements of this control). If false, the control should not be marked critical. If this subcommand is not provided, then the control is not marked critical.
value. Specifies the value for the control. This form should only be used if the value can be expressed as a string. It must not be used in conjunction with either the ::b64value or :< fileurl forms. If none of these subcommands is present, then the control will not have a value.
b64value. Specifies the value for the control in base64-encoded form. This subcommand must not be used in conjunction with either the :value or :< fileurl forms. If none of these subcommands is present, then the control will not have a value.
fileurl. Specifies a URL that references a file from which the value of the control should be taken. It must not be used in conjunction with either the :value or ::b64value forms. If none of these subcommands is present, then the control will not have a value.

-n, --newPassword newPassword

Specify the new password that should be assigned to the target user. This option must not be used in conjunction with --newPasswordFile. If neither of these options is provided, then the server will automatically generate a new password for the user, provided that a password generator is configured in the user's password policy.

-N, --newPasswordFile newPasswordFile

Read the new password from the specified file that should be assigned to the target user. This option must not be used in conjunction with --newPassword. If neither of these options is provided, then the server will automatically generate a new password for the user, provided that a password generator is configured in the user's password policy.

A.4.4.5 LDAP Connection Options

--certNickname nickname

Use the certificate for certificate-based client authentication.

-D, --bindDN bindDN

Use the DN when binding to the directory server through simple authentication. If this option is not provided, then the --authzID option must be used to specify the authorization ID for the target user, and either the --currentPassword or --currentPasswordFile option must be provided to specify the current password for the user. (This mode of use will be required for users to change their passwords after the passwords have expired.)

-h, --hostname address

Contact the directory server on the specified host name or IP address. If it is not provided, then a default address of localhost will be used.

-j, --bindPasswordFile bindPasswordFile

SASL is not supported for a proxy server instance.

-K, --keyStorePath keyStorePath

SASL is not supported for a proxy server instance.

-o, --saslOption name=value

-p, --port port

Contact the directory server at the specified port. If this option is not provided, then a default port of 389 will be used.

-P, --trustStorePath trustStorePath

-q, --useStartTLS

Use the StartTLS extended operation when communicating with the directory server. This option must not be used in conjunction with --useSSL.

--trustStorePassword trustStorePassword

-u, --keyStorePasswordFile keyStorePasswordFile

-U, --trustStorePasswordFile trustStorePasswordFile

-w, --bindPassword bindPassword

SASL is not supported for a proxy server instance.

-W, --keyStorePassword keyStorePassword

-X, --trustAll

-Z, --useSSL

Use the Secure Sockets Layer when communicating with the directory server. If SSL is to be used, then the --port option should be used to specify the server's secure port.

A.4.4.6 Command Input/Output Options

--noPropertiesFile: Indicate that a properties file will not be used to get the default command-line options.
--propertiesFilePath propertiesFilePath: Specify the path to the properties file that contains the default command-line options.

A.4.4.7 General Options

-?, -H, --help: Display command-line usage information for the command and exit without making any attempt to run the command.
-V, --version: Display the version information for the directory server.

A.4.4.8 Examples

The following examples show how to use the ldappasswordmodify command.

Example A-135 Modifying Your User Password

The following command connects to the host (-h) using port 1389 (-p), specifies the authorization ID uid=abergin (-a) of an administrator, specifies the user's current password file (-C), and changes it with a new one specified in a new password file (-N). For Windows platforms, use the file paths where your current and new passwords exist, respectively. For example, use -C \temp\currentPasswordFile and -N \temp\newPasswordFile.

$ ldappasswordmodify -h hostname -p 1389 \
-a "dn:uid=abergin,ou=People,dc=example,dc=com" \
-C /tmp/currentPasswordFile -N /tmp/newPasswordFile

The LDAP password modify operation was successful

Example A-136 Modifying and Generating a Password for Another User

The following command connects to the host (-h) using port 1389 (-p), specifies the bind DN (-D), specifies the bind password file (-j), and modifies and generates a password for another user (-a) connecting over simple authentication. For Windows platforms, specify the file where the bind password file resides, for example, -j \temp\bindPasswordFile.

$ ldappasswordmodify -h hostname -p 1389 \
-D "cn=Directory Manager" -j /tmp/bindPasswordFile \
-a "dn:uid=abergin,ou=People,dc=example,dc=com"

The LDAP password modify operation was successful
Generated Password:  blb44hjm

Example A-137 Modifying a Password for Another User

The following command connects to the host (-h) using port 1389 (-p), specifies the bind DN (-D), specifies the bind password file (-j), and modifies the password with a new one (-N) for another user (-a) connecting over simple authentication. For Windows platforms, specify the bind password file (for example, -j \temp\bindPasswordFile) and the new password file (for example, -N \temp\newPassword).

$ ldappasswordmodify -h hostname -p 1389 \
-D "cn=Directory Manager" -j /tmp/bindPasswordFile \
-a "dn:uid=abergin,ou=People,dc=example,dc=com" -N /tmp/newPassword

The LDAP password modify operation was successful

A.4.4.9 Exit Codes

An exit code of 0 indicates that the operation completed successfully. A nonzero exit code indicates that an error occurred during processing.

A.4.4.10 Using a CLI Properties File

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

The following options can be stored in a properties file:

authzID
bindDN
bindPassword
bindPasswordFile
currentPassword
currentPasswordFile
control
hostname
keyStorePassword
keyStorePasswordFile
keyStorePath
newPassword
newPasswordFile
port
provideDNForAuthzID
trustAll
trustStorePassword
trustStorePasswordFile
trustStorePath
useSSL
useStartTLS

Entries in the properties file have the following format:

toolname.propertyname=propertyvalue

For example:

ldappasswordmodify.ldapport=12345

A.4.4.11 Location

UNIX and Linux: INSTANCE_DIR/OUD/bin/ldappasswordmodify
Windows: INSTANCE_DIR\OUD\bat\ldappasswordmodify.bat

A.4.4.12 Related Commands

Section A.4.1, "ldapcompare"
Section A.4.2, "ldapdelete"
Section A.4.3, "ldapmodify"
Section A.4.5, "ldapsearch"

A.4.5 ldapsearch

The ldapsearch command searches directory server entries.

A.4.5.1 Synopsis

ldapsearch [options] [filter] [attributes]

A.4.5.2 Description

The ldapsearch command can be used to enter a search request to the directory server. The command opens a connection to the directory server, binds to it, and returns all entries that meet the search filter and scope requirements starting from the specified base DN. It can also be used to test other components of the directory server, such as authentication, control, and secure communication mechanisms.

If the --filename option is used to specify a file containing one or more search filters, then the search filter should not be included as an option. All trailing options will be interpreted as requested attributes.

If an entry has non-ASCII characters for its name and attributes, such as sn, givenName, uid, and title, the non-ASCII characters returned by running the ldapsearch command are suppressed while printing. You have to run the base64 command to decode the Base64-encoded string.

If no specific attributes are requested, then all user attributes (that is, all non-operational attributes) are returned. If one or more attribute names are listed, then only those attributes are included in the entries that are returned.

A.4.5.3 Before You Begin

Many UNIX and Linux operating systems provide an installed version of common LDAP client commands, such as ldapsearch, ldapmodify, and ldapdelete in the /usr/bin directory. You can check if a version is on your system by entering the command: which ldapsearch. If the command returns a value (seen below), you will need to update your $PATH to directory server installation directory or create an alias to the directory server instance.

$ which ldapsearch (Unix/Linux)
/usr/bin/ldapsearch

A.4.5.4 Options

The ldapsearch command accepts an option in either its short form (for example, -b baseDN) or its long form equivalent (for example, --baseDN baseDN).

A.4.5.5 Command Options

-a, --dereferencePolicy dereferencePolicy

Specify the dereference alias policy during a search. Dereference alias allows you to set an entry to point to another object. If this option is not provided, then a default of never will be used. Possible values are the following:

always — Dereference aliases both when finding the base DN and when searching below it.
find — Dereference alias when finding the base DN.
never — Never dereference aliases (default).
search — Dereference aliases when searching below the base DN but not when finding the base DN.

-A, --typesOnly

Perform a search to include attribute names in matching entries but not the attribute values. If this option is not provided, then both attribute names and values will be included in the matching entries.

--assertionFilter filter

-b, --baseDN baseDN

Specify the base DN to use for the search operation. If a file containing multiple filters is provided using the --filename option, then this base DN will be used for all of the searches. This is a required option. If a base DN with a null value ("") is specified, the server returns the root DSE entry.

-c, --continueOnError

Continue processing even if an error occurs. Use this option when you use multiple search filters in a file (--filename). If an error occurs during processing, the server will continue processing the next search filter. Otherwise the command will exit before all searches have been completed.

-C, --persistentSearch ps[:changetype[:changesonly[:entrychangecontrols]]]

Use the persistent search control (as defined in draft-ietf-ldapext-psearch.txt (https://opends.dev.java.net/public/standards/draft-ietf-ldapext-psearch.txt)) in the search request to obtain information about changes that are made to entries that match the provided search criteria. The value for this option must be in the form:

ps[:changetype[:changesonly [:entrychangecontrols]]]

The elements of this value include:

ps — Required operator.
changetype — Indicates the types of changes for which the client wants to receive notification. It can be any of add, del, mod, or moddn, or it can be all to register for all change types, or it can be a comma-separated list to register for multiple specific change types. If this element is not provided, then it will default to including all change types.
changesonly — If true, the client is only notified of changes that occur to matching entries after the search is registered. If false, the directory server sends all existing entries in the directory server that match the provided search criteria. If this element is not provided, then it will default to only returning entries for updates that occurred since the search was registered.
entrychangecontrols — If true, the directory server includes the entry change notification control in entries sent to the client as a result of changes. If false, the entry change notification control is not included. If this element is not provided, then it will default to including the entry change notification controls.

For example, the value ps:add,del:true:true returns only entries matching the search criteria that have been added or deleted since the time that the persistent search was registered, and those entries will include entry change notification controls.

--countEntries

Display the total number of matching entries returned by the directory server. If the --filename option is used to specify the path to a file containing multiple search filters, the total number of matching entries for all searches is displayed.

-e, --getEffectiveRightsAttribute attribute

Return the effective rights on the specified attribute. This option can be used to specify attributes that would not normally appear in the search results for the entry. For example, use this option to determine if a user has permission to add an attribute that does not currently exist in the entry. The -e option requires the --getEffectiveRightsAuthzid or -g option.

-f, --filename filename

Specify the path to a file that contains one or more filters to use when processing the search operation. If the file contains multiple filters, the file should be structured with one filter per line. The searches will be performed using the same connection to the directory server in the order that they appear in the filter file. If this option is used, any trailing options will be treated as separate attributes. Otherwise the first trailing option must be the search filter.

-g, --getEffectiveRightsAuthzid authzid

Display the effective rights of the user binding with the given authzid. This option can be used with the -e option but cannot be used with the -J option.

-G, --virtualListView before:after:index:count|before:after:value

Retrieve the virtual list view displaying a portion of the total search results. Use one of two patterns to specify the size of the virtual list view:

before:after:index:count — Return the target entry and the specified number of entries before the target entry and after the target entry. The target entry depends on the index and the count options. The count option can take the following values:

count=0. The target entry is the entry at the specified index position, starting from 1 and relative to the entire list of sorted results.

count=1. The target entry is the first entry in the list of sorted results.

count>1. The target entry is the first entry in the portion of the list represented by the fraction index/count. To target the last result in the list, use an index option greater than the count option.

For example, -G 5:10:2:4 specifies the index closest to the beginning of the second quarter of the entire list. If the search yielded 100 entries, the target index would be 26, and this pattern would return entries 21 through 36.
before:after:value — Return the target entry and specified number of entries before and after the target entry. The target entry is the first entry in the sorted results whose sort attribute is greater than or equal to the specified value.

For example, -G 5:10:johnson -S sn returns 16 entries in alphabetical order from the surname attribute: 5 less than johnson, the entry equal to or following johnson, and the 10 entries after johnson.

-J, --control controloid[:criticality[:value|::b64value |:<filePath]]

oid[:criticality[:value|::b64value|:<filePath]]

The elements of this value include:

oid. Use the OID for the control. For certain types of controls, a text name may be used instead of the numeric OID (for search operations, this includes managedsait for the manage DSA IT control). This element is required. Human-readable names can be used in place of the OID to reference controls that do not require values using the -J or control option. These OID names are the following:

accountusable or accountusability — Use in place of the Account Usability Request Control OID: 1.3.6.1.4.1.42.2.27.9.5.8 (no value).

authzid or authorizationidentity — Use in place of the Authorization Identity Request Control OID: 2.16.840.1.113730.3.4.16 (no value).

effectiverights — Use in place of the Get Effective Rights Control OID: 1.3.6.1.4.1.42.2.27.9.5.2 (value = authorization ID).

managedsait — Use in place of the Manage DSA IT Control OID: 2.16.840.1.113730.3.4.2 (no value).

noop or no-op — Use in place of the LDAP No-op Control OID: 1.3.6.1.4.1.4203.1.10.2 (no value).

pwpolicy or password policy — Use in place of the Password Policy Request Control OID: 1.3.6.1.4.1.42.2.27.8.5.1 (no value).

subtreedelete or treedelete — Use in place of the Subtree Delete Request Control OID: 1.2.840.113556.1.4.805 (no value).
criticality. If true, the control should be marked critical (meaning that the directory server should not process the operation unless it can meet the requirements of this control). If false, the control should not be marked critical. If this subcommand is not provided, then the control is not marked critical.
value. Specifies the value for the control. This form should only be used if the value can be expressed as a string. It must not be used in conjunction with either the ::b64value or :< fileurl forms. If none of these subcommands is present, then the control will not have a value.
b64value. Specifies the value for the control in base64-encoded form. This subcommand must not be used in conjunction with either the :value or :< fileurl forms. If none of these subcommands is present, then the control will not have a value.
fileurl. Specifies a URL that references a file from which the value of the control should be taken. It must not be used in conjunction with either the :value or ::b64value forms. If none of these subcommands is present, then the control will not have a value.

-l, --timeLimit numSeconds

Set the maximum length of time, in seconds, that the directory server should spend processing any search request. If this option is not provided, no time limit is requested by the client. Note that the directory server can enforce a lower time limit than the one that is requested by the client.

--matchedValuesFilter filter

Use the LDAP matched values control (as defined in RFC 3876 (http://www.ietf.org/rfc/rfc3876.txt)) to indicate that only attribute values matching the specified filter should be included in the search results. This option can be provided multiple times to specify multiple matched values filters.

-n, --dry-run

Run in no-op mode. That is, report what should happen but do not actually perform any searches or communicate with the server in any way.

-s, --searchScope scope

Set the scope for the search operation. The scope value must be one of the following:

base — Search only the entry specified by the --baseDN or -b option.
one — Search only the entry specified by the --baseDN or -b option and its immediate children.
sub or subordinate — Search the subtree whose base is the entry specified by the --baseDN or -b option. This is the default option when the --searchScope is not provided.

-S, --sortOrder sortOrder

Sort the results before returning them to the client. The sort order is a comma-delimited list of sort keys, where each sort key consists of the following elements:

+/- (plus or minus sign) — Indicates that the sort should be in ascending (+) or descending (-) order. If this element is omitted, then the sort will be in ascending order.
attribute name — The name of the attribute to use when sorting the data. This element must always be provided.
name or OID Matching Rule — An optional colon followed by the name or OID of the matching rule to use to perform the sort. If this element is not provided, then the default ordering matching rule for the specified attribute type will be used. For example, the sort order string sn,givenName sorts entries in ascending order first by sn and then by givenName. Alternately, the value --modifyTimestamp will cause the results to be sorted with the most recent values first.

--simplePageSize numEntries

Use the Simple Paged Results control with the given page size.

--subEntries

Use the subentries control to specify that subentries are visible, and normal entries are not.

-Y, --proxyAsauthzID

-z, --sizeLimit numEntries

Set the maximum number of matching entries that the directory server should return to the client. If this option is not provided, then there will be no maximum requested by the client. Note that the directory server can enforce a lower size limit than the one requested by the client.

A.4.5.6 LDAP Connection Options

-D, --bindDN bindDN

-E, --reportAuthzID

-h, --hostname address

Contact the directory server on the specified host name or IP address. If it is not provided, then a default address of localhost will be used.

-j, --bindPasswordFile bindPasswordFile

SASL is not supported for a proxy server instance.

-K, --keyStorePath keyStorePath

SASL is not supported for a proxy server instance.

-N, --certNickName certNickName

Use the specified certificate for certificate-based client authentication.

-o, --saslOption name=value

Use the specified option when performing SASL authentication. Multiple SASL options can be provided by using this option multiple times, once for each option. See Section 19.7, "Configuring SASL Authentication" for more information on using SASL authentication in clients.

SASL is not supported for a proxy server instance.

-p, --port port

Contact the directory server at the specified port. If this option is not provided, then a default port of 389 will be used.

-P, --trustStorePath trustStorePath

-q, --useStartTLS

Use the StartTLS Extended Operation extended operation when communicating with the directory server. This option must not be used in conjunction with --useSSL.

-r, --useSASLExternal

SASL is not supported for a proxy server instance.

--trustStorePassword trustStorePassword

-u, --keyStorePasswordFile keyStorePasswordFile

--usePasswordPolicyControl

Use the Password Policy Request Control in the bind request so that the directory server returns the corresponding result control in the bind response. This can be used to obtain information about any warnings or errors with regard to the state of the client's account.

-U, --trustStorePasswordFile trustStorePasswordFile

-V, --ldapVersion version

-w, --bindPassword bindPassword

SASL is not supported for a proxy server instance.

-W, --keyStorePassword keyStorePassword

-X, --trustAll

-Z, --useSSL

Use SSL when communicating with the directory server. If SSL is to be used, then the --port option should be used to specify the server's secure port.

A.4.5.7 Command Input/Output Options

--noPropertiesFile: Indicate that a properties file will not be used to get the default command-line options.
--propertiesFilePath propertiesFilePath: Specify the path to the properties file that contains the default command-line options.
-T, --dontWrap: Do not wrap long lines when displaying matching entries. If this option is not provided, then long lines will be wrapped (in a manner compatible with the LDIF specification) to fit on an 80-column terminal.
-v, --verbose: Run in verbose mode, displaying process and diagnostic information on standard output.

A.4.5.8 General Options

-?, -H, --help: Display command-line usage information for the command and exit without making any attempt to run the command.
-V, --version: Display the version information for the directory server.

A.4.5.9 Examples

The following examples show how to use the ldapsearch command. For additional examples, see Section 16.4, "Searching Directory Data."

Example A-138 Returning All Entries

The following command returns all entries on the directory server. The command connects to the default port 1389 (-p) on the host (-h), specifies the base DN as example.com (-b), and returns all entries by using the search filter (objectclass=*). Because the scope (-s) is not specified, the scope is set to the default value of sub, the full subtree of the base DN. Because no attributes are specified, the command returns all attributes and values.

$ ldapsearch -h hostname -p 1389 -b dc=example,dc=com "(objectclass=*)"

dn: dc=example,dc=com
objectClass: domain
objectClass: top
dc: example

dn: ou=Groups,dc=example,dc=com
objectClass: organizationalunit
objectClass: top
ou: Groups

dn: cn=Directory Administrators,ou=Groups,dc=example,dc=com
objectClass: groupofuniquenames
objectClass: top
ou: Groups
cn: Directory Administrators
uniquemember: uid=kvaughan, ou=People, dc=example,dc=com
uniquemember: uid=rdaugherty, ou=People, dc=example,dc=com
uniquemember: uid=hmiller, ou=People, dc=example,dc=com

Example A-139 Returning Attributes Names but No Values

The following command returns the attribute names (-A) but no values. The command connects to the default port 1389 (-p) on the host (-h), specifies the base DN as dc=example,dc=com (-b), matches all entries by using the search filter objectclass=*, and returns three (-z) entries. Using the -A option is a convenient way to check if an attribute is present in the database.

$ ldapsearch -h hostname -p 1389 -b dc=example,dc=com -A -z 3 "(objectclass=*)"

dn: dc=example,dc=com
objectClass
dc

dn: ou=Groups,dc=example,dc=com
objectClass
ou

dn: cn=Directory Administrators,ou=Groups,dc=example,dc=com
objectClass
ou
cn
uniquemember

Example A-140 Returning Specific Attribute Values

The following command returns a specific attribute and its value. The command connects to the port 1389 (-p) on the host (-h), specifies the base DN as dc=example,dc=com (-b), matches all entries by using the search filter cn=Sam Carter, and returns the value of the attribute, telephonenumber.

$ ldapsearch -h hostname -p 1389 -b dc=example,dc=com "(cn=Sam Carter)" telephoneNumber

dn: uid=scarter,ou=People,dc=example,dc=com
telephonenumber: +1 408 555 4798

Example A-141 Returning the Root DSE

The root DSE is a special entry that provides information about the directory server's name, version, naming contexts, and supported features. You specify the root DSE by using a base DN with a null value (for example, -b "") from which the directory server searches below all public naming contexts by default. You can override the null base DN default by specifying specific sets of base DNs with the subordinate-base-dn property by using the dsconfig command. The following example connects to the default port 1389 (-p) on the host (-h), specifies the root DSE as an empty base entry (-b), specifies the scope of the search to base (-s), matches all entries by using the search filter objectclass=*, and returns the directory server's root DSE information for supported controls:

$ ldapsearch -h hostname -p 1389 -b "" -s base "(objectclass=*)" supportedControl

dn:
supportedControl: 1.2.826.0.1.3344810.2.3
supportedControl: 1.2.840.113556.1.4.319
supportedControl: 1.2.840.113556.1.4.473
supportedControl: 1.2.840.113556.1.4.805
...

Example A-142 Searching by Using Server Authentication

The following command uses the SSL option to run a search with server authentication. The command specifies the host name (-h), SSL port 1636 (-p), base DN (-b), the bind DN (-D), the bind password (-w), trust store file path (-P), and the entity's given name. For Windows platforms, specify the paths for trust store file (for example, -P \certs\cert.db).

$ ldapsearch -h hostname -p 1636 -b "dc=example,dc=com" \
-D "uid=scarter,ou=people,dc=example,dc=com" -w bindPassword \
-P /home/scarter/certs/cert.db "(givenname=Sam)"

Example A-143 Searching by Using Client Authentication

The following command uses the SSL option to perform a search by using client authentication. The command uses SSL (-Z) with the SSL port (-p) and specifies the trust store file path (-P), the certificate nickname (-N), the keystore file path (-K), the keystore password (-W) and the entity's given name (givenname=Sam). For Windows platforms, specify the paths for the trust store file (for example, -P \certs\cert.db), and the keystore file (for example, -K \security\key.db):

$ ldapsearch -h hostname -p 1636 -b "dc=example,dc=com" \
-Z -P /home/scarter/security/cert.db -N "sccert" \
-K /home/scarter/security/key.db -W KeyPassword \
"(givenname=Sam)"

Example A-144 Returning the Effective Rights of a User

The following command returns the effective rights granted to a user, in addition to the user's attribute entries. Only a directory administrator can access this information for another user. The command specifies the host name (-h), port 1389 (-p), bindDN (-D), bindDN password (-w), base DN (-b), control spec option that includes the OID name effectiverights (alternately, you can enter the OID equivalent: 1.3.6.1.4.1.42.2.27.9.5.2), search filter objectclass=*, and the aclRights attribute.

$ ldapsearch -h hostname -p 1389 -D "cn=Directory Manager" -j pwd-file \
-b dc=example,dc=com -J "1.3.6.1.4.1.42.2.27.9.5.2"  "(objectclass=*)" \
aclRights

dn: dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0

dn: ou=Groups, dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0

dn: ou=People, dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0

dn: cn=Accounting Managers,ou=groups,dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0

dn: cn=HR Managers,ou=groups,dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0

dn: uid=bjensen,ou=People, dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0

dn: uid=cfuente, ou=People, dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:1,proxy:0

Example A-145 Returning the Schema

The following command searches the cn=schema entry for the object classes and attributes defined on the directory instance. The command connects to the port 1389 (-p) on the host (-h), sets the scope of the search to base (-s), matches all entries by using the search filter (objectclass=\*) and returns the objectClass definitions in the schema entry, cn=schema. You can also use the + symbol to view the schema. Place it after the search filter.

$ ldapsearch -h hostname -p 1389 -b cn=schema -s base "(objectclass=*)" objectClasses

dn: cn=schema
objectClasses: ( 2.5.6.0 NAME 'top' ABSTRACT MUST objectClass X-ORIGIN 'RFC 4512
' )
objectClasses: ( 2.5.6.1 NAME 'alias' SUP top STRUCTURAL MUST aliasedObjectName
X-ORIGIN 'RFC 4512' )
objectClasses: ( 2.5.6.2 NAME 'country' SUP top STRUCTURAL MUST c MAY ( searchGu
ide $ description ) X-ORIGIN 'RFC 4519' )
objectClasses: ( 2.5.6.3 NAME 'locality' SUP top STRUCTURAL MAY ( street $ seeAl
so $ searchGuide $ st $ l $ description ) X-ORIGIN 'RFC 4519' )
...

Example A-146 Performing a Persistent Search

The ldapsearch command provides an option to run a persistent search (-C) that keeps the connection open and displays the entries that matching the scope and filter whenever any changes (add, delete, mod, or all) occur. The command connects to the port 1389 (-p), sets the scope of the search to base (-s), and matches all entries by using the search filter (objectclass=\*). You can quit out of the search by pressing Control-C.

$ ldapsearch -b dc=example,dc=com -p 1389 -D "cn=Directory Manager" \
-j pwd-file -C ps:add:true:true "(objectclass=*)"

Example A-147 Viewing ACI Attributes

The following command displays the access control instruction (ACI) attributes from the specified base DN. The command connects to the port 1389 (-p), sets the scope of the search to base (-s), matches all entries using the search filter (objectclass=\*) and specifies the aci attribute.

$ ldapsearch -p 1389 -D "cn=Directory Manager" -j pwd-file -b dc=example,dc=com \
-s base "(objectclass=*)" aci

dn: dc=example,dc=com
aci: (target ="ldap:///dc=example,dc=com")(targetattr h3.="userPassword")(version
3.0;acl "Anonymous read-search access";allow (read, search, compare)(userdn = "
ldap:///anyone");)
aci: (target="ldap:///dc=example,dc=com") (targetattr = "*")(version 3.0; acl "a
llow all Admin group"; allow(all) groupdn = "ldap:///cn=Directory Administrator
s,ou=Groups,dc=example,dc=com";)

Example A-148 Viewing Monitoring Information

The following command searches the cn=monitor entry for information on the activity on the directory server. The command specifies the host name (-h), port (-p), base DN (-b) for cn=monitor, authenticates using the bind DN (-D) and bind password (-w) and specifies the filter (objectclass=\*).

$ ldapsearch --useSSL -X -h hostname -p 4444 -b cn=monitor -D "cn=Directory Manager" \
-j pwd-file "(objectclass=*)"

dn: cn=monitor
objectClass: top
objectClass: extensibleObject
objectClass: ds-monitor-entry
currentTime: 20070803161832Z
startTime: 20070803132044Z
productName: Oracle Unified Directory
...

Example A-149 Searching by Using a Properties File

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

The following options can be stored in a properties file:

assertionFilter
bindDN
bindPassword
bindPasswordFile
certNickname
continueOnError
control
countEntries
dereferencePolicy
dry-run
dontWrap
filename
getEffectiveRightsAttribute
getEffectiveRightsAuthzid
hostname
keyStorePassword
keyStorePasswordFile
keyStorePath
ldapVersion
matchedValuesFilter
persistentSearch
port
proxyAs
reportAuthzID
saslOption

SASL is not supported for a proxy server instance.
searchScope
simplePageSize
sizeLimit
sortOrder
timeLimit
trustAll
trustStorePassword
trustStorePasswordFile
trustStorePath
typesOnly
usePasswordPolicyControl
useSASLExternal

SASL is not supported for a proxy server instance.
useSSL
useStartTLS
verbose
virtualListView

A.4.5.10 To Search by Using a Properties File

Create a properties file in any text editor. Here, save the file as tools.properties.

hostname=host
port=1389
bindDN=cn=Directory Manager
bindPassword=password
baseDN=dc=example,dc=com
searchScope=sub
sortOrder=givenName
virtualListView=0:2:1:0

Use ldapsearch with the --propertiesFilePath option. $ldapsearch --propertiesFilePath tools.properties "(objectclass=*)"

A.4.5.11 Search Attributes

A number of special search attributes can also be used for various purposes, including the following:

*This symbol indicates that all user attributes should be included in the entries returned by the directory server.

$ ldapsearch -h hostname -p 1389 -b dc=example,dc=com "(objectclass=*)" *

+This symbol indicates that all operational attributes are to be included in the entries returned by the directory server. By default, no operational attributes will be returned. Note that even if this is specified, there might be some operational attributes that are not returned automatically for some reason for example, if an expensive computation is required to construct the value). On some systems, you might need to escape the + symbol by enclosing it in quotation marks, "+" or by using a backslash, \+.

$ ldapsearch -h hostname -p 1389 -b dc=example,dc=com "(objectclass=*)" "+"

1.1This indicates that no attribute values should be included in the matching entries. On some systems, you might need to escape the 1.1 character by enclosing it in quotation marks, "1.1", or by using a backslash, \1.1.

$ ldapsearch -h hostname -p 1389 -b dc=example,dc=com "(objectclass=*)" "1.1"

@_objectclass_This indicates that all attributes associated with the specified object class should be included in the entries returned by the server. For example, @person indicates that the server should include all attributes associated with the person object class.

$ ldapsearch -h hostname -p 1389 -b dc=example,dc=com "(objectclass=*)" @person

A.4.5.12 Exit Codes

An exit code of 0 indicates that the operation completed successfully. A nonzero exit code indicates that an error occurred during processing.

A.4.5.13 Location

UNIX and Linux: INSTANCE_DIR/OUD/bin/ldapsearch
Windows: INSTANCE_DIR\OUD\bat\ldapsearch.bat

A.4.5.14 Related Commands

Section A.4.1, "ldapcompare"
Section A.4.2, "ldapdelete"
Section A.4.3, "ldapmodify"
Section A.4.4, "ldappasswordmodify"

A Oracle Unified Directory Command Line Interface

A.1 General Command-Line Usage Information

A.1.1 Summary of Server Commands and Their Use

A.1.2 Using a Properties File With Server Commands

A.1.2.1 Locating the Properties File

A.1.2.2 Order of Precedence of Options and Properties

A.2 Server Administration Commands

A.2.1 create-rc-script

A.2.1.1 Synopsis

A.2.1.2 Description

A.2.1.3 Options

A.2.1.4 General Options

A.2.1.5 Examples

A.2.1.6 Code Generated by the create-rc-script Command

A.2.1.7 Exit Codes

A.2.1.8 Location

A.2.1.9 Related Commands

A.2.2 dps2oud

A.2.2.1 Synopsis

A.2.2.2 Description

A.2.2.3 Options

A.2.2.4 LDAP Connection Options

A.2.2.5 General Options

A.2.2.6 Examples

A.2.2.7 Exit Codes

A.2.2.8 Location

A.2.2.9 Related Commands

A.2.3 ds2oud

A.2.3.1 Synopsis

A.2.3.2 Description

A.2.3.3 Options

A.2.3.4 Oracle Directory Server Enterprise Edition LDAP Connection Options

A.2.3.5 Oracle Unified Directory LDAP Connection Options

A.2.3.6 Command Input/Output Options

A.2.3.7 General Options

A.2.3.8 Examples

A.2.3.9 Exit Codes

A.2.3.10 Location

A.2.3.11 Related Commands

A.2.4 dsconfig

A.2.4.1 Synopsis

A.2.4.2 Description

A.2.4.3 Help Subcommands

A.2.4.4 General Subcommands

A.2.4.5 Core Server Subcommands

A.2.4.6 Database Subcommands

A.2.4.7 Logging Subcommands

A.2.4.8 Replication Subcommands

A.2.4.9 Security Subcommands

A.2.4.10 User Management Subcommands

A.2.4.11 Options

A.2.4.12 LDAP Connection Options

A.2.4.13 Command Input/Output Options

A.2.4.14 General Options

A.2.4.15 Examples

A.2.4.16 Exit Codes

A.2.4.17 Using a Properties File

A.2.4.18 Location

A.2.4.19 Related Commands

A.2.5 dsjavaproperties

A.2.5.1 Synopsis

A.2.5.2 Description

A.2.5.3 Options

A.2.5.4 Example

A.2.5.5 Exit Codes

A.2.5.6 Location

A.2.6 dsreplication

A.2.6.1 Synopsis

A.2.6.2 Description

A.2.6.3 Server Subcommands

A.2.6.4 Options

A.2.6.5 Configuration Options

A.2.6.6 LDAP Connection Options

A.2.6.7 Command Input/Output Options

A.2.6.8 General Options

A.2.6.9 Examples

A.2.6.10 Exit Codes

A.2.6.11 Using a Properties File

A.2.6.12 Location

A.2.6.13 Related Commands

A.2.1.6 Code Generated by the `create-rc-script` Command