Oracle® Fusion Middleware Administrator's Guide for Oracle Unified Directory
11g Release 2 (11.1.2)

Part Number E22648-02

 PDF · Mobi · ePub

# 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:

## A.1 General Command-Line Usage Information

The following sections provide general information about command usage:

### 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

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.

Command Remote Offline Online Administration Connector

create-rc-script

dsconfig

X

X

X

dsjavaproperties

X

dsreplication

X

X

X

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

X

windows-service

X

Command Remote Offline Online Administration Connector

backup

X *

X

X

X

base64

X

dbtest

X

X

export-ldif

X *

X

X

X

import-ldif

X *

X

X

X

ldapcompare

X

X

ldapdelete

X

X

ldapmodify

X

X

X

X

ldapsearch

X

X

ldif-diff

X

ldifmodify

X

ldifsearch

X

list-backends

X

make-ldif

X

manage-account

X

X

X

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
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").

The following sections describe the server administration commands:

### 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


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 ### 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. --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 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. --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 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. --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 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. --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 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. --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 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. --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 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. --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 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. --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 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-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. --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 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. --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. 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. --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. 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. --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, --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. --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 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. --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 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. --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. 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. --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. 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: --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. 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. --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. 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. --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. 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. --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. --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. --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. --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. --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. --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. --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. --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). --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. 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. --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. 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. --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. 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. --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. 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. --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. --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. --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. --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. --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. --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. --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. --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. --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. 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. --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. 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. --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. 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. --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. --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. --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. --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. --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. 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. --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. 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. --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. 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. --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. 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. --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. 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. --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. --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. --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. --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: --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. 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. --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. 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. --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. 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. --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. 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. --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. 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. --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. 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. --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. 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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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. --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.

1. Set the desired locale using the following command:

export LC_ALL=fr_FR.UTF-8

2. 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] :
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
journal
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
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
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
catalogue d'index globaux
20)  ImplÃ©mentation de groupe      45)  Fournisseur de synchronisation
21)  Mappeur d'identitÃ©s           46)  Fournisseur de gestionnaire de
22)  Fournisseur de gestionnaire    47)  Attribut virtuel
23)  Algorithme d'Ã©quilibrage de   48)  File d'attente de travaux
charge
24)  Route d'Ã©quilibrage de charge  49)  Workflow

q)   quit

Entrez votre choix :

3. 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] :
DN de liaison de l'administrateur [cn=Directory Manager] :

>>>> Menu principal de la console de configuration Oracle Unified Directory

Que voulez-vous configurer ?

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
7)   Configuration globale          32)  Index global
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
18)  Fournisseur de gestionnaire    43)  Serveur de rÃ©plication
19)  Fournisseur de surveillance    44)  StratÃ©gie de conservation de
journal
20)  Fournisseur de                 45)  StratÃ©gie de mot de passe
synchronisation
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.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.

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

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

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

-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" \
--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" \
-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. --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. 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: -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. 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. --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. 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. -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. 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. --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. 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. --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. --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. --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. 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

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

#### 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
-------------------------------------------------------
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

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.8.11 Related Commands ### 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 ### 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 ### 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 ### 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 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. -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 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). -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 ### 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.

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

--- Connection Handlers ---
-------------:-------------:---------
--           : 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

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.

-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

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.

#### 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: 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 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. -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

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

6

Error stopping the replication gateway.

7

Error unconfiguring windows service.

8

Error input limit.

9

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.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.3 Data Administration Commands The following sections describe the data administration commands: ### 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.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.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 \
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.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

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



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 ### 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 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.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 ### 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
# givenName: Quentin
# description: This is Quentin's description.
# mail: qcubbins@example.com

dn: uid=qrcubbins,ou=People,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: top
objectClass: inetOrgPerson
cn: Quentin R Cubbins
sn: Cubbins
uid: 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 ### 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
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.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.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 ### 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" \

Account Is Disabled:  false
Account Expiration Time:
Seconds Until Account Expiration:
Authentication Failure Times:
Seconds Until Authentication Failure Unlock:
Remaining Authentication Failure Count:
Seconds Until Idle Account Lockout:
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

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

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 ### 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 \
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.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.4 LDAP Client Commands

The following sections describe the LDAP client utilities:

### 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

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

-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" \
'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.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]]

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

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

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

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

-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.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" \


#### 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.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
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
uid: john.doe
givenName: John
sn: Doe
cn: John Doe
mail: john.doe@example.com


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
-


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]]

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

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

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

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

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

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 \


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" \


#### 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

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]]

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 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, --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

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.

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

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

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

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

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

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


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

$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 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. -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]] 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|:<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. 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. -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 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, proxied authorization is not used. -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 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 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. 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 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 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. --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 Use the password in the specified file to access the certificates in the client trust store. This option is only required if --trustStorePath is used and the specified trust store requires a password in order to access its contents (most trust stores do not require this). This option must not be used in conjunction with --trustStorePassword. -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 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

objectClass: groupofuniquenames
objectClass: top
ou: Groups
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" \
-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

dn: ou=Groups, dc=example,dc=com

dn: ou=People, dc=example,dc=com

dn: cn=Accounting Managers,ou=groups,dc=example,dc=com

dn: cn=HR Managers,ou=groups,dc=example,dc=com

dn: uid=bjensen,ou=People, dc=example,dc=com

dn: uid=cfuente, ou=People, dc=example,dc=com


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" \


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

1. Create a properties file in any text editor. Here, save the file as tools.properties.

hostname=host
port=1389
bindDN=cn=Directory Manager
baseDN=dc=example,dc=com
searchScope=sub
sortOrder=givenName
virtualListView=0:2:1:0

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