A Oracle Unified Directory Command-Line Interface

This appendix describes the command-line utilities used by Oracle Unified Directory to create, configure, and manage directory server, proxy server and replication gateway instances.

This appendix includes the following sections:

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

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

Administration Port Only

The command must use the administration connector to access the server (on port 4444 by default)

Note:

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

Table A-1 Server Administration Commands

Command Remote Offline Online Administration Connector

create-rc-script

        

dsconfig

X

  

X

X

dsjavaproperties

  

X

    

dsreplication

X

  

X

X

gicadm

X

  

X

X

oudExtractMovePlan

  

X

X

  

oudCopyConfig

  

X

X

  

oudPasteConfig

  

X

    

start-ds

  

X

    

status

X

X

X

X

stop-ds

X

  

X

X

uninstall

  

X

X

X

upgrade

  

X

    

windows-service

  

X

    

Table A-2 Data Administration Commands

Command Remote Offline Online Administration Connector

backup

X *

X

X

X

base64

  

X

    

dbtest

  

X

    

encode-password

  

X

    

export-ldif

X *

X

X

X

import-ldif

X *

X

X

X

ldapcompare

X

  

X

  

ldapdelete

X

  

X

  

ldapmodify

X

  

X

  

ldappasswordmodify

X

  

X

  

ldapsearch

X

  

X

  

ldif-diff

  

X

    

ldifmodify

  

X

    

ldifsearch

  

X

    

list-backends

  

X

    

make-ldif

  

X

    

manage-account

X

  

X

X

manage-tasks

X

  

X

X

rebuild-index

  

X

    

restore

X *

X

X

X

split-ldif

  

X

X

  

verify-index

  

X

    

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

A.1.2 Using a Properties File With Server Commands

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

  • The host name and port number of the server

  • Whether to use SSL or StartTLS to communicate with the server

  • The bind DN to use when connecting to the server

The following utilities can use a properties file:

  • backup

  • dsconfig

  • dsreplication

  • export-ldif

  • gicadm

  • import-ldif

  • split-ldif

  • ldapcompare

  • ldapdelete

  • ldapmodify

  • ldappasswordmodify

  • ldapsearch

  • manage-tasks

  • oud-setup

  • oud-proxy-setup

  • oud-replication-gateway-setup

  • restore

  • status

  • stop-ds

  • uninstall

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

--propertiesFilePath path

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

--noPropertiesFile

Indicates that the properties file is not used to obtain default values for command-line options.

A.1.2.1 Locating the Properties File

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

  • If the --noPropertiesFile option is specified, the command-line interface does not try to locate a properties file. Only options specified on the command line are evaluated.

  • If the --propertiesFilePath option is specified, property values are read from this file.

  • If neither --propertiesFilePath nor --noPropertiesFile is specified, the command-line interface attempts to find a properties file in the following locations:

    • USERDIRECTORY/.opends/tools.properties

    • INSTANCE_DIR/OUD/config/tools.properties

  • If no properties file is found in either of these locations, the default behavior is applied (only arguments specified on the command line are evaluated).

A.1.2.2 Order of Precedence of Options and Properties

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

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

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

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

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

Note:

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

A.2 Server Administration Commands

The following sections describe the server administration commands:

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

-A, --adaptDseeData {file}

Adapts an Oracle Directory Server Enterprise Edition 6.3 LDIF data file to ease import on Oracle Unified Directory, producing a result file, {file}_result.ldif

-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 the user schema and global configuration parameters
4)  Migrate the user schema only
5)  Migrate global configuration parameters only
6)  Adapt DSEE 6.3 LDIF data file to ease import on OUD

c)  cancel

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

Example A-10 Running ds2oud for Diagnosing Data

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

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

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

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

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

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

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

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

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

A.2.3.9 Exit Codes

0

Successful.

1

Unable to initialize arguments.

2

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

3

At least one step into the migration process has failed.

4

The user canceled the operation in interactive mode.

A.2.3.10 Location

  • UNIX and Linux: INSTANCE_DIR/OUD/bin/ds2oud

  • Windows: INSTANCE_DIR\OUD\bat\ds2oud.bat

A.2.3.11 Related Commands

A.2.4 dsconfig

The dsconfig command allows you to define a base configuration for the Directory Server.

A.2.4.1 Synopsis

dsconfig [subcommands] [Options]

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 17.4, "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 17.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 base configuration.

--help-distribution

Display subcommands relating to distribution.

--help-general-configuration

Display subcommands relating to general configuration.

--help-integration

Display subcommands relating to integration.

--help-load-balancing

Display subcommands relating to load balancing.

--help-local-datasource

Display subcommands relating to local data source.

--help-remote-datasource

Display subcommands relating to remote data source.

--help-replication

Display subcommands relating to replication.

--help-schema

Display subcommands relating to schema.

--help-security

Display subcommands relating to authentication and authorization.

--help-virtualization

Display subcommands relating to virtualization.

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

The following subcommands allow you to define the base configuration for the directory server.

create-distribution-algorithm

Creates distribution algorithms. 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.

-t,--type type. The type of Distribution Algorithm that should be created. The value for type can be one of capacity, dnpattern, generic, lexico, or numeric.

create-distribution-partition

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. The type of Distribution Partition that should be created. The value for type can be one of capacity, dnpattern, generic, lexico, or numeric.

create-workflow-element --type distribution

Creates Workflow Elements. Suboptions are as follows:

--element-name name. The name of the new 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. The type of Workflow Element that should be created. The value for type can be one of ad-paging, backup-local-backend, db-local-backend,distribution, dn-renaming, eus, eus-context, fa, global-index-local-backend, global-index-replication-changes-local-backend, kerberos-auth-provider, ldif-local-backend, load-balancing, memory-local-backend, monitor-local-backend, null-local-backend, pass-through-authentication, plugin, proxy-ldap, rdn-changing, transformations, trust-store-local-backend.

create-global-index

Creates global indexes. Suboptions are as follows:

--extension-name name. The name of the Global Index Catalog Extension.

--index-name name. The name of the new 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.

create-extension --type global-index-catalog

Creates Extensions. Suboptions are as follows:

--extension-name name. The name of the Global Index Catalog 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. The type of Extension that should be created. The value for type can be one of global-index-catalog, global-index-catalogs-shared-cache, ldap-server.

create-global-index-catalog-replication-domain

Creates global index catalog replication domains. Suboptions are as follows:

--extension-name name. The name of the Global Index Catalog 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.

create-extension --type global-index-catalogs-shared-cache

Creates Extensions. Suboptions are as follows:

--extension-name name. The 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. The type of Extension that should be created. The value for type can be one of global-index-catalog, global-index-catalogs-shared-cache, ldap-server.

create-workflow-element --type global-index-local-backend

Creates Workflow Elements. Suboptions are as follows:

--element-name name. The name of the new 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. The type of Workflow Element that should be created. The value for type can be one of ad-paging, backup-local-backend, db-local-backend, distribution, dn-renaming, eus, eus-context, fa, global-index-local-backend, global-index-replication-changes-local-backend, kerberos-auth-provider, ldif-local-backend, load-balancing, memory-local-backend, monitor-local-backend, null-local-backend, pass-through-authentication, plugin, proxy-ldap, rdn-changing, transformations, trust-store-local-backend.

create-workflow-element --type global-index-replication-changes-local-backend

Creates Workflow Elements. Suboptions are as follows:

--element-name name. The name of the new 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. The type of Workflow Element that should be created. The value for type can be one of ad-paging, backup-local-backend, db-local-backend, distribution, dn-renaming, eus, eus-context, fa, global-index-local-backend, global-index-replication-changes-local-backend, kerberos-auth-provider, ldif-local-backend, load-balancing, memory-local-backend, monitor-local-backend, null-local-backend, pass-through-authentication, plugin, proxy-ldap, rdn-changing, transformations, trust-store-local-backend.

delete-distribution-algorithm

Deletes distribution algorithms. Suboptions are as follows:

--element-name name. The name of the Distribution Workflow Element.

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

delete-distribution-partition

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

Deletes Extensions. Suboptions are as follows:

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

-f,--force. Ignore nonexistent extensions.

delete-global-index

Deletes global indexes. Suboptions are as follows:

--extension-name name. The name of the Global Index Catalog Extension.

--index-name name. The name of the Global Index.

-f,--force. Ignore nonexistent global indexes.

delete-global-index-catalog-replication-domain

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

Deletes global index catalog replication domains. Suboptions are as follows:

--extension-name name. The name of the Global Index Catalog Extension.

-f,--force. Ignore nonexistent global index catalog replication domains.

delete-workflow-element

Deletes Workflow Elements. Suboptions are as follows:

--element-name name. The name of the Workflow Element.

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

get-data-encryption-prop

Shows data encryption properties. Suboptions are as follows:

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

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

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-global-index-catalog-replication-domain-prop

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

Shows global index catalog replication domain properties. Suboptions are as follows:

--extension-name name. The name of the Global Index Catalog 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-index-prop

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

Shows Global index properties. Suboptions are as follows:

--extension-name name. The name of the Global Index Catalog Extension.

--index-name name. The name of the Global 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-distribution-algorithm

This command is supported for only proxy.

Lists existing distribution algorithm. 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-extensions

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-catalog-replication-domain

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

Lists existing global index catalog replication domain. Suboptions are as follows:

--extension-name name. The name of the Global Index Catalog Extension.

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

Lists existing global indexes. Suboptions are as follows:

--extension-name name. The name of the Global Index Catalog Extension.

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

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

set-data-encryption-prop

Modifies Data Encryption 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-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-extension-prop

Modifies Extension properties. Suboptions are as follows:

--extension-name name. The name of the 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.

--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-catalog-replication-domain-prop

This command is supported only for the proxy.

Modifies global index catalog replication domain properties. Suboptions are as follows:

--extension-name name. The name of the Global Index Catalog 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.

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

Modifies global index properties. Suboptions are as follows:

--extension-name name. The name of the Global Index Catalog Extension.

--index-name name. The name of 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.

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

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.

A.2.4.6 General Configuration Subcommands

The following subcommands configure the core server.

create-alert-handler

Creates alert handlers. Suboptions are as follows:

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

--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 Alert Handler that should be created. The value for type can be one of custom, jmx, or smtp.

create-certificate-mapper

Creates certificate mappers. Suboptions are as follows:

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

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

Creates connection handlers. Suboptions are as follows:

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

--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 Connection Handler that should be created. The value for type can be one of custom, jmx, ldap, snmp, or ldif.

create-debug-target

Creates debug targets. Suboptions are as follows:

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

--target-name java-name. The name of the new debug target, which will also be used as the value for 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-extended-operation-handler

This command is not supported for the proxy.

Creates extended operation handlers. Suboptions are as follows:

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

--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 Extended Operation handler that should be created. The value for 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-identity-mapper

Creates identity mappers. Suboptions are as follows:

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

--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 custom,exact-match, or match-and-replace.

create-log-publisher

Creates log publishers. Suboptions are as follows:

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

--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 custom-access, custom-debug, custom-error, 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. The name of the new log retention 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.

-t,--type type. The type of Log Retention Policy that should be created. The value for type can be one of custom,file-count, free-disk-space, or size-limit.

create-log-rotation-policy

Creates log rotation policies. Suboptions are as follows:

--policy-name name. The name of the new log rotation 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.

-t,--type type. The type of Log Rotation Policy that should be created. The value for type can be one of custom, fixed-time, size-limit, or time-limit.

create-workflow-element --type monitor-local-backend

Creates Workflow Elements. Suboptions are as follows:

--element-name name. The name of the new 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. The type of Workflow Element that should be created. The value for type can be one of ad-paging, backup-local-backend, db-local-backend, distribution, dn-renaming, eus, eus-context, fa, global-index-local-backend, global-index-replication-changes-local-backend, kerberos-auth-provider, ldif-local-backend, load-balancing, memory-local-backend, monitor-local-backend, null-local-backend, pass-through-authentication, plugin, proxy-ldap, rdn-changing, transformations, trust-store-local-backend.

create-network-group

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

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, --type type. 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-workflow

Creates workflows. Suboptions are as follows:

--workflow-name name. The name of the new workflow. This name will also be used as The value for the workflow-id property.

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

Deletes alert handlers. Suboptions are as follows:

--handler-name name. The name of the alert handler.

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

delete-certificate-mapper

Deletes certificate mappers. Suboptions are as follows:

--mapper-name name. The name of the certificate mapper.

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

delete-connection-handler

Deletes connection handlers. Suboptions are as follows:

--handler-name name. The name of the connection handler.

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

delete-debug-target

Deletes debug targets. Suboptions are as follows:

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

--target-name name. The name of the debug target.

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

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

Deletes identity mappers. Suboptions are as follows:

--mapper-name name. The name of the identity mapper.

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

delete-log-publisher

Deletes log publishers. Suboptions are as follows:

--publisher-name name. The 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. The 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. The name of the log rotation policy.

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

delete-network-group

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

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

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

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

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

delete-workflow

Deletes workflow. Suboptions are as follows:

-f,--force. Ignore nonexistent workflow.

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

delete-workflow-element

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:

--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-alert-handler-prop

Shows alert handler properties. Suboptions are as follows:

--handler-name name. The 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-certificate-mapper-prop

Shows certificate mapper properties. Suboptions are as follows:

--mapper-name name. The name 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-connection-handler-prop

Shows connection handler properties. Suboptions are as follows:

--handler-name name. The name of the connection 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-debug-target-prop

Shows debug target properties. Suboptions are as follows:

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

--target-name name. The 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-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-global-configuration-prop

Shows global configuration properties. Suboptions are as follows:

--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. The name 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-log-publisher-prop

Shows log publisher properties. Suboptions are as follows:

--publisher-name name. The name 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. The name 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. The name 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).

get-network-group-prop

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

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

Shows plugin root properties.

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

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

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

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

Lists existing debug targets. Suboptions are as follows:

--publisher-name name. The 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-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-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-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).

list-network-group-qos-policies

Lists existing network group QOS 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

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

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

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

Modifies 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. The name of the alert handler.

--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. The name of the certificate mapper.

--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. The name of the connection handler.

--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-debug-target-prop

Modifies debug target properties. Suboptions are as follows:

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

--target-name name. The name of the debug target.

--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. The name of the extended operation handler.

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

--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. The name of the identity mapper.

--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. The name of the log publisher.

--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. The name of the log retention 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-log-rotation-policy-prop

Modifies log rotation policy properties. Suboptions are as follows:

--policy-name name. The name of the log rotation 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-network-group-prop

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

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

Modifies plugin root 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-root-dse-backend-prop

Modifies root DSE back end 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-work-queue-prop

Modifies work queue 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-workflow-element-prop

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

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.7 Load Balancing Subcommands

The following subcommands configure load balancing for the proxy server.

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. The type of Load Balancing Algorithm that should be created. The value for 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. The type of Load Balancing Route that should be created. The value for type can be failover, generic, optimal, proportional, saturation, or searchfilter. The default value is generic.

create-workflow-element --type load-balancing

Creates Workflow Elements. Suboptions are as follows:

--element-name name. The name of the new 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. The type of Workflow Element that should be created. The value for type can be one of ad-paging, backup-local-backend,db-local-backend, distribution, dn-renaming,eus,eus-context, fa, global-index-local-backend, global-index-replication-changes-local-backend, kerberos-auth-provider,ldif-local-backend,load-balancing, memory-local-backend,monitor-local-backend,null-local-backend, pass-through-authentication,plugin,proxy-ldap, rdn-changing,transformations,trust-store-local-backend.

delete-load-balancing-algorithm

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-load-balancing-route

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

delete-workflow-element

Deletes Workflow Elements. Suboptions are as follows:

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

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

get-load-balancing-algorithm-prop

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

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

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

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

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

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.

A.2.4.8 Local Data Source Subcommands

create-account-status-notification-handler

Creates account status notification handlers. Suboptions are as follows:

--handler-name name. The name of the new account status notification handler.

--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. The value for type can be one of custom, error-log, or smtp.

create-workflow-element --type backup-local-backend

Creates Workflow Elements. Suboptions are as follows:

--element-name name. The name of the new 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. The type of Workflow Element that should be created. The value for type can be one of ad-paging, backup-local-backend, db-local-backend, distribution, dn-renaming, eus, eus-context, fa, global-index-local-backend, global-index-replication-changes-local-backend, kerberos-auth-provider, ldif-local-backend, load-balancing, memory-local-backend, monitor-local-backend, null-local-backend, pass-through-authentication, plugin, proxy-ldap, rdn-changing, transformations, trust-store-local-backend.

create-workflow-element --type db-local-backend

Creates Workflow Elements. Suboptions are as follows:

--element-name name. The name of the new 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. The type of Workflow Element that should be created. The value for type can be one of ad-paging, backup-local-backend, db-local-backend, distribution, dn-renaming, eus, eus-context, fa, global-index-local-backend, global-index-replication-changes-local-backend, kerberos-auth-provider, ldif-local-backend, load-balancing, memory-local-backend, monitor-local-backend, null-local-backend, pass-through-authentication, plugin, proxy-ldap, rdn-changing, transformations, trust-store-local-backend.

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

This command is not supported for the proxy.

Creates group implementations. Suboptions are as follows:

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

--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 Group Implementation that should be created. The value for type can be one of dynamic, static, or virtual-static.

create-workflow-element --type ldif-local-backend

Creates Workflow Elements. Suboptions are as follows:

--element-name name. The name of the new 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. The type of Workflow Element that should be created. The value for type can be one of ad-paging, backup-local-backend, db-local-backend, distribution, dn-renaming, eus, eus-context, fa, global-index-local-backend, global-index-replication-changes-local-backend, kerberos-auth-provider, ldif-local-backend, load-balancing, memory-local-backend, monitor-local-backend, null-local-backend, pass-through-authentication, plugin, proxy-ldap, rdn-changing, transformations, trust-store-local-backend.

create-local-db-index

Creates local DB indexes. Suboptions are as follows:

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

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

--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. The name of the local DB back end workflow element.

--index-name name. The 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.

--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 --type memory-local-backend

Creates Workflow Elements. Suboptions are as follows:

--element-name name. The name of the new 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. The type of Workflow Element that should be created. The value for type can be one of ad-paging, backup-local-backend, db-local-backend, distribution, dn-renaming, eus, eus-context, fa, global-index-local-backend, global-index-replication-changes-local-backend, kerberos-auth-provider, ldif-local-backend, load-balancing, memory-local-backend, monitor-local-backend, null-local-backend, pass-through-authentication, plugin, proxy-ldap, rdn-changing, transformations, trust-store-local-backend.

create-workflow-element --type null-local-backend

Creates Workflow Elements. Suboptions are as follows:

--element-name name. The name of the new 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. The type of Workflow Element that should be created. The value for type can be one of ad-paging, backup-local-backend, db-local-backend, distribution, dn-renaming, eus, eus-context, fa, global-index-local-backend, global-index-replication-changes-local-backend, kerberos-auth-provider, ldif-local-backend, load-balancing, memory-local-backend, monitor-local-backend, null-local-backend, pass-through-authentication, plugin, proxy-ldap, rdn-changing, transformations, trust-store-local-backend.

create-password-generator

Creates password generators. Suboptions are as follows:

--generator-name name. The name of the new password generator.

--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. The value for type can be one of custom or random.

create-password-policy

Creates Password Policies. Suboptions are as follows:

--policy-name name. The name of the new Password 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.

create-plugin --type password-policy-import

Creates Plugins. Suboptions are as follows:

--plugin-name name. The name of the new Plugin.

--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 Plugin that should be created. The value for type can be one of dsee-gateway, password-policy-import, referential-integrity, seven-bit-clean, unique-attribute.

create-password-storage-scheme

Creates password storage schemes. Suboptions are as follows:

--scheme-name name. The name of the new password storage scheme.

--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. The value for type can be one of aes, base64, blowfish, clear, crypt, custom, md5, rc4, salted-md5, salted-sha1, salted-sha256, sha256, salted-sha384, salted-sha512, sha512, sha1, or triple-des.

create-password-validator

Creates password validators. Suboptions are as follows:

--validator-name name. The name of the new password validator.

--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. The value for type can be one of attribute-value, character-set, custom, dictionary, length-based, repeated-characters, similarity-based, or unique-characters.

create-plugin --type referential-integrity

Creates Plugins. Suboptions are as follows:

--plugin-name name. The name of the new Plugin.

--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 Plugin that should be created. The value for type can be one of dsee-gateway, password-policy-import, referential-integrity,seven-bit-clean,unique-attribute.

create-plugin --type seven-bit-clean

Creates Plugins. Suboptions are as follows:

--plugin-name name. The name of the new Plugin.

--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 Plugin that should be created. The value for type can be one of dsee-gateway, password-policy-import, referential-integrity,seven-bit-clean,unique-attribute.

create-plugin --type unique-attribute

Creates Plugins. Suboptions are as follows:

--plugin-name name. The name of the new Plugin.

--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 Plugin that should be created. The value for type can be one of dsee-gateway, password-policy-import, referential-integrity,seven-bit-clean,unique-attribute.

create-virtual-attribute

This command is not supported for the proxy.

Creates virtual attributes. Suboptions are as follows:

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

--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 Virtual Attribute that should be created. The value for type can be one of collective-attribute-subentries, custom, entry-dn,entry-uuid, governing-structure-rule, has-subordinates, is-member-of, member, nsuniqueid, num-subordinates, orclguid, password-policy-subentry, proximity, structural-object-class, subschema-subentry, user-defined.

delete-account-status-notification-handler

Deletes account status notification handlers. Suboptions are as follows:

--handler-name name. The name of the account status notification handler.

-f,--force. Ignore nonexistent account status notification handlers.

delete-entry-cache

Deletes entry caches. Suboptions are as follows:

--cache-name name. The name of the Entry Cache.

-f,--force. Ignore nonexistent entry cache.

delete-group-implementation

This command is not supported for the proxy.

Deletes group implementations. Suboptions are as follows:

--implementation-name name. The name of the group implementation.

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

delete-local-db-index

Deletes local DB indexes. Suboptions are as follows:

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

--index-name name. The 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. The name of the local DB back end workflow element.

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

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

delete-password-generator

Deletes password generators. Suboptions are as follows:

--generator-name name. The name of the password generator.

-f,--force. Ignore nonexistent password generators.

delete-password-policy

Deletes password policies. Suboptions are as follows:

--policy-name name. The 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. The 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. The name of the password validator.

-f,--force. Ignore nonexistent password validators.

delete-plugin

Deletes Plugins. Suboptions are as follows:

--plugin-name name. The name of the Plugin.

-f,--force. Ignore nonexistent Plugins.

delete-virtual-attribute

This command is not supported for the proxy.

Deletes virtual attributes. Suboptions are as follows:

--name name. The name of the virtual attribute.

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

delete-workflow-element

Deletes Workflow Elements. Suboptions are as follows:

--element-name name. The name of the Workflow Element.

-f,--force. Ignore nonexistent Workflow Elements.

get-account-status-notification-handler-prop

Shows account status notification handler properties. Suboptions are as follows:

--handler-name name. The name 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-entry-cache-prop

Shows entry cache properties. Suboptions are as follows:

--cache-name name. The name 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-group-implementation-prop

This command is not supported for the proxy.

Shows group implementation properties. Suboptions are as follows:

--implementation-name name. The name 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-local-db-index-prop

Shows local DB index properties. Suboptions are as follows:

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

--index-name name. The name 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-local-db-vlv-index-prop

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

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

--index-name name. The name 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).

get-password-generator-prop

Shows password generator properties. Suboptions are as follows:

--generator-name name. The name 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. The name 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. The name 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. The name 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).

get-virtual-attribute-prop

This command is not supported for the proxy.

Shows virtual attribute properties. Suboptions are as follows:

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

list-account-status-notification-handlers

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

Lists existing entry caches. 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-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-local-db-indexes

Lists existing local DB indexes. Suboptions are as follows:

--element-name name. The name of the DB Local Backend 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-local-db-vlv-indexes

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

--element-name name. The name of the DB Local Backend 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-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).

list-plugins

Lists existing Plugins. 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

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

set-account-status-notification-handler-prop

Modifies account status notification handler properties. Suboptions are as follows:

--handler-name name. The name of the account status notification handler.

--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-entry-cache-prop

Modifies Entry Cache properties. Suboptions are as follows:

--cache-name name. The name of the 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.

--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-group-implementation-prop

This command is not supported for the proxy.

Modifies group implementation properties. Suboptions are as follows:

--implementation-name name. The name of the group implementation.

--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. The name of the local DB back end workflow element.

--index-name name. The name of the local DB 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.

--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. The name of the local DB back end workflow element.

--index-name name. The name of the local DB VLV 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.

--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. The name of the password generator.

--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. The name of the password 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-password-storage-scheme-prop

Modifies password storage scheme properties. Suboptions are as follows:

--scheme-name name. The name of the password storage scheme.

--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. The name of the password validator.

--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 Plugin properties. Suboptions are as follows:

--plugin-name name. The name of the Plugin.

--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. The name of the virtual attribute.

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

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.

A.2.4.9 Integration Subcommands

This section describes the subcommands for various workflow operations.

create-workflow-element --type ad-paging

This command creates Ad Paging Workflow Elements. Suboptions are as follows:

--element-name name. The name of the new 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. The type of Workflow Element that should be created. The value for type can be one of ad-paging, ad-password, backup-local-backend, db-local-backend,distribution, dn-renaming, eus, eus-context, fa, global-index-local-backend, global-index-replication-changes-local-backend, kerberos-auth-provider, ldif-local-backend, load-balancing, memory-local-backend, monitor-local-backend, null-local-backend, pass-through-authentication, plugin, proxy-ldap, rdn-changing, transformations, trust-store-local-backend.

create-workflow-element --type ad-password

This command creates Password Workflow Elements. 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.

-t, --type type. The type of Workflow Element that should be created. The value for type can be one of ad-paging, ad-password,backup-local-backend, db-local-backend,distribution, dn-renaming, eus, eus-context, fa, global-index-local-backend, global-index-replication-changes-local-backend, kerberos-auth-provider, ldif-local-backend, load-balancing, memory-local-backend, monitor-local-backend, null-local-backend, pass-through-authentication, plugin, proxy-ldap, rdn-changing, transformations, trust-store-local-backend.

create-workflow-element --type eus-context

This command creates Eus Context Workflow Elements. Suboptions are as follows:

--element-name name. The name of the new 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. The type of Workflow Element that should be created. The value for type can be one of ad-paging,ad-password, backup-local-backend,db-local-backend,distribution, dn-renaming,eus,eus-context,fa,global-index-local-backend,global-index-replication-changes-local-backend, kerberos-auth-provider, ldif-local-backend, load-balancing, memory-local-backend, monitor-local-backend, null-local-backend, pass-through-authentication, plugin, proxy-ldap, rdn-changing, transformations, trust-store-local-backend.

create-workflow-element --type eus

This command creates Eus Workflow Elements. Suboptions are as follows:

--element-name name. The name of the new 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. The type of Workflow Element that should be created. The value for type can be one of ad-paging, ad-password, backup-local-backend, db-local-backend, distribution, dn-renaming, eus, eus-context, fa, global-index-local-backend, global-index-replication-changes-local-backend, kerberos-auth-provider, ldif-local-backend, load-balancing, memory-local-backend, monitor-local-backend, null-local-backend, pass-through-authentication, plugin, proxy-ldap, rdn-changing, transformations, trust-store-local-backend.

create-workflow-element --type fa

This command creates Fa Workflow Elements. Suboptions are as follows:

--element-name name. The name of the new 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. The type of Workflow Element that should be created. The value for type can be one of ad-paging, ad-password, backup-local-backend, db-local-backend,distribution, dn-renaming, eus, eus-context, fa, global-index-local-backend, global-index-replication-changes-local-backend, kerberos-auth-provider, ldif-local-backend, load-balancing, memory-local-backend, monitor-local-backend, null-local-backend, pass-through-authentication, plugin, proxy-ldap, rdn-changing, transformations, trust-store-local-backend.

create-workflow-element --type kerberos-auth-provider

This command creates Kerberos Auth Provider Workflow Elements. Suboptions are as follows:

--element-name name. The name of the new 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. The type of Workflow Element that should be created. The value for type can be one of ad-paging, ad-password, backup-local-backend, db-local-backend, distribution, dn-renaming, eus, eus-context, fa, global-index-local-backend, global-index-replication-changes-local-backend, kerberos-auth-provider, ldif-local-backend, load-balancing, memory-local-backend, monitor-local-backend, null-local-backend, pass-through-authentication, plugin, proxy-ldap, rdn-changing, transformations, trust-store-local-backend.

create-workflow-element --type pass-through-authentication

This command creates Pass Through Authentication Workflow Elements. Suboptions are as follows:

--element-name name. The name of the new 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. The type of Workflow Element that should be created. The value for type can be one of ad-paging, ad-password, backup-local-backend, db-local-backend, distribution, dn-renaming, eus, eus-context, fa, global-index-local-backend, global-index-replication-changes-local-backend, kerberos-auth-provider, ldif-local-backend, load-balancing, memory-local-backend, monitor-local-backend, null-local-backend, pass-through-authentication, plugin, proxy-ldap, rdn-changing, transformations, trust-store-local-backend.

create-workflow-element --type plugin

This command creates Plugin Workflow Elements. Suboptions are as follows:

--element-name name. The name of the new 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. The type of Workflow Element that should be created. The value for type can be one of ad-paging, ad-password, backup-local-backend, db-local-backend, distribution, dn-renaming, eus, eus-context, fa, global-index-local-backend, global-index-replication-changes-local-backend, kerberos-auth-provider, ldif-local-backend, load-balancing, memory-local-backend, monitor-local-backend, null-local-backend, pass-through-authentication, plugin, proxy-ldap, rdn-changing, transformations, trust-store-local-backend.

delete-workflow-element

This command deletes Workflow Elements. Suboptions are as follows:

--element-name name. The name of the Workflow Element.

-f, --force. Ignore nonexistent Workflow Elements.

list-workflow-elements

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

set-workflow-element-prop

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.

A.2.4.10 Remote Data Source Subcommands

This section describes subcommands for various remote data source operations.

create-extension --type ldap-server

This command creates LDAP Server Extensions. Suboptions are as follows:

--extension-name name. The 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. The type of Extension that should be created. The value for type can be one of global-index-catalog, global-index-catalogs-shared-cache,ldap-server.

create-workflow-element --type proxy-ldap

This command creates Proxy LDAP Workflow Elements. Suboptions are as follows:

--element-name name. The name of the new 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. The type of Workflow Element that should be created. The value for type can be one of ad-paging, backup-local-backend, db-local-backend, distribution, dn-renaming, eus, eus-context, fa, global-index-local-backend, global-index-replication-changes-local-backend, kerberos-auth-provider, ldif-local-backend, load-balancing, memory-local-backend, monitor-local-backend, null-local-backend, pass-through-authentication, plugin, proxy-ldap, rdn-changing, transformations, trust-store-local-backend.

delete-extension

Deletes extension. Suboptions are as follows:

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

-f,--force. Ignore nonexistent extensions.

delete-workflow-element

Deletes workflow elements. Suboptions are as follows:

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

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

list-extensions

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

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

set-extension-prop

This command modifies Extension properties. Suboptions are as follows:

--extension-name name. The name of the 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.

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

A.2.4.11 Replication Subcommands

This section describes subcommands for various replication operations.

create-plugin --type dsee-gateway

Creates Plugins. Suboptions are as follows:

--plugin-name name. The name of the Plugin.

--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 Plugin that should be created. The value for type can be one of dsee-gateway,password-policy-import,referential-integrity, seven-bit-clean,unique-attribute.

create-gateway-domain

Creates gateway domains. Suboptions are as follows:

--plugin-name name. The name of the DSEE gateway plugin.

--domain-name name. The name of the gateway domain.

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

Creates replication domains. Suboptions are as follows:

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

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

--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. The name of the multi-master synchronization provider.

--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. The name of the new synchronization provider.

--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 can be one of custom,replication.

delete-gateway-domain

Deletes gateway domains. Suboptions are as follows:

--plugin-name name. The name of the DSEE gateway plugin.

--domain-name name. The name of the gateway domain.

-f, --force. Ignore nonexistent Gateway Domains.

delete-plugin

Deletes Plugins. Suboptions are as follows:

--plugin-name name. The name of the Plugin.

-f,--force. Ignore nonexistent Plugin.

delete-replication-domain

Deletes replication domains. Suboptions are as follows:

--provider-name name. The name of the synchronization provider.

--domain-name name. The name of the replication domain.

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

delete-replication-server

Deletes replication servers. Suboptions are as follows:

--provider-name name. The name of the synchronization provider.

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

delete-synchronization-provider

Deletes synchronization providers. Suboptions are as follows:

--provider-name name. The name of the synchronization provider.

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

get-external-changelog-domain-prop

Shows External Changelog Domain properties. Suboptions are as follows:

--provider-name name. The name of the Replication Synchronization Provider.

--domain-name name. The name 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-gateway-domain-prop

Shows gateway domain properties.

--plugin-name name. The name of the DSEE gateway plugin.

--domain-name name. The name of the gateway 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-domain-prop

Shows replication domain properties. Suboptions are as follows:

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

--domain-name name. The name 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. The name of the multi-master 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).

get-synchronization-provider-prop

Shows synchronization provider properties. Suboptions are as follows:

--provider-name name. The name 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-plugins

Lists existing Plugins. 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-gateway-domains

Lists existing gateway domains. Suboptions are as follows.

--plugin-name name. The name of the DSEE Gateway Plugin.

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

Lists existing replication domains. Suboptions are as follows:

--provider-name name. The 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. The 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-external-changelog-domain-prop

Modifies External Changelog Domain properties. Suboptions are as follows:

--provider-name name. The name of the Replication Synchronization Provider.

--domain-name name. The name of the Replication Domain.

--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-gateway-domain-prop

Modifies gateway domain properties. Suboptions are as follows:

--plugin-name name. The name of the DSEE Gateway Plugin.

--domain-name name. The name of the gateway domain.

--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 Plugin properties. Suboptions are as follows:

--plugin-name name. The name of the Plugin.

--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-replication-domain-prop

Modifies replication domain properties. Suboptions are as follows:

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

--domain-name name. The name of the replication domain.

--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-replication-server-prop

Modifies replication server properties. Suboptions are as follows:

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

--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. The name of the synchronization provider.

--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.12 Schema Subcommands

This section describes subcommands for various schema operations.

create-attribute-syntax

This command is not supported for the proxy.

Creates attribute syntaxes. Suboptions are as follows:

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

--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 Attribute Syntax that should be created. The value for type can be one of attribute-type-description, directory-string, generic, or telephone-number.

create-matching-rule

This command is not supported for the proxy.

Creates matching rules. Suboptions are as follows:

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

--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 Matching Rule that should be created. The value for type can be one of collation or generic.

delete-attribute-syntax

This command is not supported for the proxy.

Deletes attribute syntaxes. Suboptions are as follows:

--syntax-name name. The name of the attribute syntax.

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

delete-matching-rule

This command is not supported for the proxy.

Deletes matching rules. Suboptions are as follows:

--rule-name name. The name of the matching rule.

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

get-attribute-syntax-prop

This command is not supported for the proxy.

Shows attribute syntax properties. Suboptions are as follows:

--syntax-name name. The name of the attribute syntax.

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

--rule-name name. The 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).

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

set-attribute-syntax-prop

This command is not supported for the proxy.

Modifies attribute syntax properties. Suboptions are as follows:

--syntax-name name. The name of the attribute syntax.

--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. The name of the matching rule.

--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.13 Security Subcommands

create-access-control-group

Creates access control groups.

--group-name name. The name of the new access control 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-key-manager-provider

Creates key manager providers. Suboptions are as follows:

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

--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. The value for type can be one of file-based, custom, 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. The name of the new SASL mechanism handler.

--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. The value for type can be one of anonymous, cram-md5, digest-md5, external, custom, gssapi, or plain.

create-trust-manager-provider

Creates trust manager providers. Suboptions are as follows:

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

--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. The value for type can be one of blind, file-based, or custom.

create-workflow-element --type trust-store-local-backend

Creates Workflow Elements. Suboptions are as follows:

--element-name name. The name of the new 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. The type of Workflow Element that should be created. The value for type can be one of ad-paging, backup-local-backend, db-local-backend,distribution, dn-renaming, eus, eus-context, fa, global-index-local-backend, global-index-replication-changes-local-backend, kerberos-auth-provider, ldif-local-backend, load-balancing, memory-local-backend, monitor-local-backend, null-local-backend, pass-through-authentication, plugin, proxy-ldap, rdn-changing, transformations, trust-store-local-backend.

delete-access-control-group

Deletes access control groups. Suboptions are as follows:

--group-name name. The name of the access control group.

-f,--force. Ignore nonexistent access control groups.

delete-key-manager-provider

Deletes key manager providers. Suboptions are as follows:

--provider-name name. The 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. The 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. The name of the trust manager provider.

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

delete-workflow-element

Deletes Workflow Elements. Suboptions are as follows:

--element-name name. The name of the Workflow Element.

-f,--force. Ignore nonexistent Workflow Elements.

get-access-control-group-prop

Shows access control group properties. Suboptions are as follows:

--group-name name. The name of the access control 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-access-control-handler-prop

Shows access control handler properties. Suboptions are as follows:

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

--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. The name 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-root-dn-prop

Shows Root DN properties. Suboptions are as follows:

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

Shows SASL mechanism handler properties. Suboptions are as follows:

--handler-name name. The name 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. The name 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-access-control-groups

Lists existing access control 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-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).

list-workflow-elements

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

set-access-control-group-prop

Modifies access control group properties. Suboptions are as follows:

--group-name name. The name of the access control 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-access-control-handler-prop

Modifies access control handler 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-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-key-manager-provider-prop

Modifies key manager provider properties. Suboptions are as follows:

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

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

--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. The name of the SASL mechanism handler.

--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. The name of the trust manager provider.

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

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.

A.2.4.14 Virtualization Subcommands

This section describes subcommands for virtualization.

create-transformation --type add-inbound-attribute

Creates Add Inbound Attribute Transformations. Suboptions are as follows:

--transformation-name name. The name of the new transformation.

--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 Transformation that should be created. The value for type can be one of add-inbound-attribute,add-outbound-attribute, filter-inbound-attribute,filter-outbound-attribute, map-attribute. For more information about each transformation, see Section 24.6.2, "Configuring Transformation Using dsconfig."

create-transformation --type add-outbound-attribute

Creates Add Outbound Attribute Transformations. Suboptions are as follows:

--transformation-name name. The name of the new transformation.

--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 Transformation that should be created. The value for type can be one of add-inbound-attribute,add-outbound-attribute, filter-inbound-attribute,filter-outbound-attribute, map-attribute. For more information about each transformation, see Section 24.6.2, "Configuring Transformation Using dsconfig."

create-workflow-element --type dn-renaming

Creates DN Renaming Workflow Elements. Suboptions are as follows:

--element-name name. The name of the new 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. The type of Workflow Element that should be created. The value for type can be one of ad-paging, backup-local-backend, db-local-backend,distribution, dn-renaming, eus, eus-context, fa, global-index-local-backend, global-index-replication-changes-local-backend, kerberos-auth-provider, ldif-local-backend, load-balancing, memory-local-backend, monitor-local-backend, null-local-backend, pass-through-authentication, plugin, proxy-ldap, rdn-changing, transformations, trust-store-local-backend.

create-transformation --type filter-inbound-attribute

Creates Filter Inbound Attribute Transformations. Suboptions are as follows:

--transformation-name name. The name of the new transformation.

--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 Transformation that should be created. The value for type can be one of add-inbound-attribute,add-outbound-attribute, filter-inbound-attribute,filter-outbound-attribute, map-attribute. For more information about each transformation, see Section 24.6.2, "Configuring Transformation Using dsconfig."

create-transformation --type filter-outbound-attribute

Creates Filter Outbound Attribute Transformations. Suboptions are as follows:

--transformation-name name. The name of the new transformation.

--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 Transformation that should be created. The value for type can be one of add-inbound-attribute,add-outbound-attribute,filter-inbound-attribute,filter-outbound-attribute, map-attribute. For more information about each transformation, see Section 24.6.2, "Configuring Transformation Using dsconfig."

create-transformation --type map-attribute

Creates Map Attribute Transformations. Suboptions are as follows:

--transformation-name name. The name of the new transformation.

--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 Transformation that should be created. The value for type can be one of add-inbound-attribute,add-outbound-attribute, filter-inbound-attribute,filter-outbound-attribute, map-attribute. For more information about each transformation, see Section 24.6.2, "Configuring Transformation Using dsconfig."

create-workflow-element --type rdn-changing

Creates RDN Changing Workflow Elements. 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.

-t,--type type. The type of Workflow Element that should be created. The value for type can be one of ad-paging, backup-local-backend, db-local-backend,distribution, dn-renaming, eus, eus-context, fa, global-index-local-backend, global-index-replication-changes-local-backend, kerberos-auth-provider, ldif-local-backend, load-balancing, memory-local-backend, monitor-local-backend, null-local-backend, pass-through-authentication, plugin, proxy-ldap, rdn-changing, transformations, trust-store-local-backend.

create-transformation

Creates Transformations. Suboptions are as follows:

--transformation-name name. The name of the new transformation.

--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 Transformation that should be created. The value for type can be one of add-inbound-attribute,add-outbound-attribute, filter-inbound-attribute,filter-outbound-attribute, map-attribute.

create-workflow-element --type transformations

Creates Transformations Workflow Elements. Suboptions are as follows:

--element-name name. The name of the new 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. The type of Workflow Element that should be created. The value for type can be one of ad-paging, backup-local-backend, db-local-backend,distribution, dn-renaming, eus, eus-context, fa, global-index-local-backend, global-index-replication-changes-local-backend, kerberos-auth-provider, ldif-local-backend, load-balancing, memory-local-backend, monitor-local-backend, null-local-backend, pass-through-authentication, plugin, proxy-ldap, rdn-changing, transformations, trust-store-local-backend.

delete-transformation

Deletes Transformations. Suboptions are as follows:

--transformation-name name. The name of the transformation.

-f, --force. Ignore nonexistent transformation.

delete-workflow-element

Deletes Workflow Elements. Suboptions are as follows:

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

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

get-transformation-prop

Shows Transformation properties. Suboptions are as follows:

--transformation-name name. The name of the transformation 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).

list-transformations

Lists existing Transformations. 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

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

set-transformation-prop

Modifies Transformation properties. Suboptions are as follows:

--transformation-name name. The name of the transformation 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-element-prop

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.

A.2.4.15 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.16 LDAP Connection Options

The dsconfig command contacts the directory server over SSL through the administration connector (described in Section 17.4, "Managing Administration Traffic to the Server"). These connection options are used to contact the directory server.

-D, --bindDN bindDN

Use the bind DN to bind 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 nickname of certificate for SSL 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 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 run in the same instance, there is no certificate interaction.

--connectTimeout {timeout}

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

A.2.4.17 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.18 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.19 Examples

The following examples show how to use the dsconfig command. For additional dsconfig examples, see Section 17.1, "Managing the Server Configuration Using 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 subcommands relating to authentication and authorization:

$ dsconfig --help-security

Example A-14 Viewing Help on an Individual Subcommand

The following command displays the help information for the set-distribution-partition-prop subcommand:

$ dsconfig set-distribution-partition-prop --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

A.2.4.20 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.21 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.22 Location

  • UNIX and Linux: INSTANCE_DIR/OUD/bin/dsconfig

  • Windows: INSTANCE_DIR\OUD\bat\dsconfig.bat

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

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 17.4, "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
12) Verify Server Configuration
13) List the Certificates Used for Replication
14) Regenerate the Certificate Used for Replication
15) Set the Certificate Used for Replication

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 32.7, "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 32.7, "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 must 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. 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. 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. (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.

list-certs

List the certificates used by the servers for replication. Suboptions are as follows:

-h, --hostname host

Directory server host name or IP address.

-p, --port port

Directory server administration port number. Default value: 4444

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.

regenerate-cert

Regenerates the certificate used by the specified server (or all servers) for replication. Suboptions are as follows:

-a, --all

Regenerates the certificate of all servers configured for replication (and not only of the server provided to connect).

-h, --hostname host

Directory server host name or IP address.

-p, --port port

Directory server administration port number. Default value: 4444

set-cert

Configures the server to use a certificate in a keystore for replication. Suboptions are as follows:

--replCertNickName nickname

Specifies the nickname of the certificate that you want to be used by the server for replication.

--replKeyStoreType type

Specifies the type of the keystore. The value can be any type of keystore, including JKS, JCEKS, PKCS12, and PKCS11. The Java Virtual Machine used by the server must support this keystore type (by default, most JVMs support the keystore types JKS, JCEKS, and PKCS12). The default value is JKS.

--replKeyStorePath path

Specifies the path of the keystore containing the certificate to be used by the server for replication. This value is not required if the certificate is stored on a hardware device such as a Java card. The server must have read access rights to this path. You can specify a path relative to the location of the server (for example, config/my-keystore).

--replKeyStorePasswordFile path

Specifies the path to the file containing the password (PIN) needed to access the keystore. The password must be stored in clear text in the file, and the server must have read access rights to the file. If you want the server to encrypt the contents of the file, the server must also have write access rights. You can specify a path relative to the location of the server (for example, config/my-keystore.pin).

--replKeyPasswordFile keyPasswordFile

Specifies the file containing the password (PIN) needed to access the private key of the certificate in the keystore. This option is required if the private key cannot be read using the keystore password specified with the --replKeyStorePasswordFile option. The password must be stored in clear text in the file, and the server must have read access rights to the file. You can specify a path relative to the location of the server (for example, config/my-key.pin).

--skipLocalChecks

Specifies that the default checks to validate the provided data should be skipped when you run the command from the same machine as the server.

--encryptKeyStorePasswordFile

Specifies that the server should overwrite the contents of the password (PIN) file you provide with the password encrypted. The password file must contain the password in clear text, and the server must have write access rights on the file specified using the --replKeyStorePasswordFile option.

-h, --hostname host

Directory server host name or IP address.

-p, --port port

Directory server administration port number. Default value: 4444

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. Default value: 4444

-D, --bindDN bindDN

DN to use to bind to the server if no global administrator has been defined. This can be used to view the external changelog status (which does not require replication between servers to be configured). Default value: cn=Directory Manager

-e, --expanded

Use expanded view of the replication status showing the replication domains (replicated data) and replication servers (change log and replication port) as separate entities.

-s, --script-friendly

Use the script-friendly mode.

-d, --dataToDisplay {dataToDisplay}

Specify the replication data information that you want to be displayed. For example, if you enter the following:

--dataToDisplay entry-number --dataToDisplay missing-changes

the number of entries and the missing changes is displayed. For more information about the different values allowed, run the following:

dsreplication status --listDataToDisplay

--listDataToDisplay

List the different values that can be used for the argument --dataToDisplay. If you want to display the full list of values, also specify --advanced argument.

verify

Verifies the replication configuration of the different replicated servers.

Oracle recommends that you run the verify subcommand in interactive mode (without the --no-prompt option). Then, if any inconsistencies are found in the replication configuration, they will be displayed and you can fix them interactively.

For example, you can use the verify subcommand:

  • To remove references to servers that are no longer reachable (for example, because they crashed and are not recoverable or they were not properly uninstalled).

  • To fix configuration problems related to the certificates used by the replication system.

  • To update the host names used by the replication configuration.

Suboptions are as follows:

-r, --replicationServer hostName:replicationPort

Specifies the host names and replication ports used in the configuration to reference the replication servers. These values are applied to all servers that are replicated. For example: replicationhost1.example.com:8989

--noReplicationDomainUpdate

If specified when you provide a list of replication servers using the --replicationServer argument, the changes are not applied to the replication domains.

-a, --serverToAdd hostName:administrationPort

Specifies servers that have been removed from the registration information by mistake and must be added again (for example, servers removed by using the --serverToRemove option by mistake). If there are several network interfaces defined in the server, use commas to separate them. For example:

host1-interface1.domain1.com,host2-interface2.domain2.com:4444

-s, --serverToRemove hostName:administrationPort

Specifies servers that are not reachable (for example, servers that have been uninstalled), but they are still referenced by the other servers and are mentioned when running dsreplication status. The references to these servers will be removed. For example: replicationhost3.example.com:4444

--updateAddress oldHostName/newHostName1,newHostName2

Specifies new addresses that the registration information should use for a given server. Use this argument when a network interface has changed or when the complete list of addresses was not provided when replication was configured, which can result in duplicate lines when running dsreplication status.

You must specify the addresses currently used for the server and the new servers that you want to use. For example: oldhost/newhost1,newhost2

--fixCertificates

Fixes any problems found with the certificates that are used by the replication to communicate between servers.

-h, --hostname host

Directory server host name or IP address.

-p, --port port

Directory server administration port number. Default value: 4444

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. Use virtual-acis if you want to replicate the virtual ACIs.

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 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. Using the interactive mode and --displayCommand option, you can get the equivalent non-interactive command to do scripting).

To illustrate which arguments are configured, these examples do not use the interactive mode.

Example A-18 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-19 Initializing Directory Server Replication

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

$ dsreplication initialize --baseDN "dc=example,dc=com" \
  --adminUID admin --adminPasswordFile /tmp/pwd-file \
  --hostSource host1 --portSource 4444 \
  --hostDestination host2 --portDestination 4444 -X -n

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

Example A-20 Obtaining the Directory Server Replication Status

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

bin/dsreplication status -X --adminPasswordFile /tmp/password.txt -n
Establishing connections .......... Done.
 
dc=example,dc=com - Replication Enabled
=======================================
Server             : Entries : M.C. [1] : A.O.M.C. [2] : Port [3] : Status [4]
-------------------:---------:----------:--------------:----------:-------------
host1:4444         : 200000  : 0        : N/A          : 8989     : Normal
host2:5444         : 200000  : 0        : N/A          : 9989     : Normal
 
[1] The number of changes that are still missing on this element (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 element.
[3] The replication port used to communicate between the servers whose contents are being replicated.
[4] The status of the replication on this element.
 

 
 
To have the same output as in previous versions, the user must use the --dataToDisplay argument with the 'compat-view' value:
 
bin/dsreplication status -X --adminPasswordFile /tmp/password.txt -n --dataToDisplay compat-view
Establishing connections ......... Done.
 
dc=example,dc=com - Replication Enabled
=======================================
Server     : Entries : M.C. [1] : A.O.M.C. [2] : Port [3] : SSL [4]  : Trust [5] : U.C. [6] : Status [7]   : ChangeLog [8] : Group ID [9] : Connected To [10]
-----------:---------:----------:--------------:----------:----------:-----------:----------:--------------:---------------:--------------:---------------------------
host1:4444 : 200000  : 0        : N/A          : 8989     : Disabled : Trusted   : --       : Normal       : Enabled       : 1            : host1:8989 (GID=1)
host2:5444 : 200000  : 0        : N/A          : 9989     : Disabled : Trusted   : --       : Normal       : Enabled       : 1            : host2:9989 (GID=1)
 
[1] The number of changes that are still missing on this element (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 element.
[3] The replication port used to communicate between the servers whose contents are being replicated.
[4] Whether the replication communication initiated by this element is encrypted or not. 
[5] Whether the 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 on this element.
[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 server this element is connected to with its group ID between brackets.

Example A-21 Disabling Directory Server Replication

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

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

Example A-22 Configuring the External Change Log on a Non-replicated Server

The following example illustrates the replication status before enabling the change log:

 
bin/dsreplication status -X --adminPasswordFile /tmp/password.txt -n --bindDN "cn=directory manager" --port 4444
Establishing connections ..... Done.
 
dc=example,dc=com - Replication Disabled
========================================
Server        : Entries   : ChangeLog [1]
--------------:-----------:--------------
host1:4444    : 200000    : Disabled

The following command enables the external change log on a non-replicated server.

bin/dsreplication enable-changelog -X --adminPasswordFile /tmp/password.txt -n --bindDN "cn=directory manager" -b dc=example,dc=com
Establishing connections ..... Done.
 
Configuring Replication port on server host1:4444 ..... Done.
Enabling Changelog on base DN dc=example,dc=com ..... Done

The following example illustrates the replication status after changelog has been enabled:

bin/dsreplication status -X --adminPasswordFile /tmp/password.txt -n --bindDN "cn=directory manager" --port 4444
Establishing connections ...... Done.
 
dc=example,dc=com - Replication Disabled
========================================
Server        : Entries   : ChangeLog [1]
--------------:-----------:--------------
host1:4444    : 200000    : Enabled
 
[1] Whether the external change log is enabled for the base DN on this server or not.

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.

39

No base DN available to enable replication. This occurs when you request to enable replication between two servers, and the two servers do not have common base DNs to configure replication. It may be that they are already replicated, or that simply they are not defined).

40

No base DNs replicated. The server does not contain any replicated base DN. Thus the operations requiring replicated base DNs, for example initialize, cannot be applied to the server.

41

A source for the initialization has been specified, but no destination server could be found. None of the other servers are replicating a base DN with the server chosen as source).

42

There are replication servers or replication domains with the same replication ID. This occurs, for instance, when you try to merge two replication topologies.

43

An unidentified error.

44

Error configuring crypto manager (updating the secure connection configuration for replication).

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 dstune

The dstune utility allows you to tune the Oracle Unified Directory server.

A.2.7.1 Synopsis

dstune [subcommand] [options]

A.2.7.2 Description

The dstune utility can be used to help you tuning the Oracle Unified Directory server based on criteria such as a memory limitation or the data that it will contain. To tune the server, you must use a Java Virtual Machine that uses Java HotSpot(TM), such as the Oracle Java Standard Edition.

A.2.7.3 Subcommands

The dstune utility provides the subcommands described in this section.

Note:

The dstune automatic subcommand is no longer available (automatic subcommand usage is still available for backward compatibility).

To specify automatic tuning similar to previous versions of Oracle Unified Directory, use the dstune set-runtime-options subcommand with the --value autotune suboption.

data-based

Tunes the server using information describing the data that the directory server will contain. Use --ldifFile to do the tuning based in the contents of an LDIF file. Use --entryNumber and --entrySize to do the tuning based on the number of entries and size.

If you do not specify any of these options, the server will be tuned using the data that the server currently contains.

Suboptions are as follows:

-l, --ldifFile path

Specifies the path of the LDIF file whose contents will be used to tune the server.

--entryNumber entrynumber

Specifies the number of entries that the Oracle Unified Directory server will contain. This value and the value provided for --entrySize will be used to tune the server. The default value is 100000.

--entrySize entrysize

Specifies the average size in kilobytes of the entries that the Oracle Unified Directory server will contain. This value and the value provided for --entryNumber will be used to tune the server. The default value is 4.

list

Lists the tuning settings for the server.

mem-based

Specifies the memory to be used for the tools you want to tune.

Suboptions are as follows:

--memory { heap-size | system memory | system memory percentage }

Specifies the memory to be used for the tools to be tuned.

To tune the tools based on the heap size of their respective Java process, provide a value for the memory (for example, 768m). For gigabytes, use g after the value (for example, 2.5g). If you do not specify a unit after the value, megabytes will be used.

If you are tuning the server, you can specify the system memory (systemMemory) as either an amount or percentage:

  • Amount: For example, to use 2 GB, specify systemMemory:2g. The dstune utility then splits the value you provide into two parts: the heap size that the Java Virtual Machine of the server will use and an estimation of the required file-system cache.

  • Percentage: For example, to dedicate 50 percent of system memory to the server, specify systemMemory:50.0%. To fully dedicate a machine to the server, specify systemMemory:100%.

The default value for the memory will be calculated based on your specific configuration and the free memory available on the system where dstune is running.

--targetTool { server | import-ldif | export-ldif | rebuild-index | verify-index | all }

Specifies the tools that should be tuned. The default is server.

set-runtime-options

Tunes the tools using the provided runtime settings. Use --value to provide the value of the runtime settings and --targetTool to provide the tools the value should be applied to.

Suboptions are as follows:

--value { autotune | jvm-default | JVM arguments }

Specifies the tuning parameters for the tools. The tools can be automatically tuned each time they are launched based on the available memory in the machine (provide the value autotune), the tools can use the default Java Virtual Machine on your system to choose the runtime settings (provide the value jvm-default), or you can provide directly the Java arguments that the tools must use (for instance '-server -Xmx1024m'). The default is autotune.

--targetTool { server | import-ldif | export-ldif | rebuild-index | verify-index | all }

Specifies the tools that should be tuned. The default is server.

A.2.7.4 Utility Input/Output Options

-Q, --quiet

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

-n, --no-prompt

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

-v, --verbose

Use verbose mode.

--displayCommand

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

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

--propertiesFilePath propertiesFilePath

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

--noPropertiesFile

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

A.2.7.5 General Options

-V, --version

Displays the version information for the directory server.

-?, -H, --help

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

A.2.7.6 Examples

The examples in this section show how to use the dstune utility to tune the Oracle Unified Directory server and tools (import-ldif, export-ldif, verify-index, and rebuild-index).

Note:

Beginning with Oracle Unified Directory 11g Release 2 (11.1.2.3), the dstune automatic subcommand is no longer available (automatic subcommand usage is still available for backward compatibility).

To specify automatic tuning similar to previous versions of Oracle Unified Directory, use the dstune set-runtime-options subcommand with the --value autotune suboption.

See Example A-25, "Runtime Tuning" and Section A.2.7, "dstune."

Example A-23 Memory-Based Tuning

The following subcommand tunes the server and all tools specifying 2 GB for the heap size.

$ dstune mem-based --memory 2g --targetTool all

Calculating Tuning Settings ..... Done.
Updating the tuning properties ..... Done.
Updating scripts ..... Done.

Example A-24 Data-Based Tuning

The following subcommand tunes the server based on the assumption that the server contains 10000000 entries with an average size of 20 KB each.

$ dstune data-based --entryNumber 10000000 --entrySize 20

Calculating Tuning Settings ..... Done.
Updating the tuning properties ..... Done.
Updating scripts ..... Done.

Example A-25 Runtime Tuning

The following subcommand tunes only the server and import-ldif tool to use automatic tuning. Each time you run the server and the import-ldif tool, tuning is done based on the system resources.

$ dstune set-runtime-options --targetTool server --targetTool import-ldif \
--value autotune

Updating the tuning properties ..... Done.

The server will be automatically tuned the next time it will be restarted.

Example A-26 Displaying the Current Tuning Mode

The following subcommand displays the current tuning settings for an Oracle Unified Directory server instance.

$ dstune list

Tool          : Tuning Value
--------------:------------------
server        : -server
import-ldif   : -Xmx2048m -server
export-ldif   : Automatic Tuning
rebuild-index : Automatic Tuning
verify-index  : -Xmx2048m -server

A.2.7.7 Exit Codes

0

The operation was completed successfully, this includes the cases where no operation is performed with no errors (for instance, the usage was displayed).

1

Unable to initialize the arguments.

2

The data provided by the user was not correct (for instance, invalid values or conflicting attributes).

3

The user canceled the operation during interaction.

4

Error writing the java.properties file.

5

Error executing the dsjavaproperties command-line to update the tuning settings.

6

An error occurred retrieving the JVM tuning settings. This occurs when the algorithms used by dstune of are not able to find some valid settings.

7

An error occurred reading the java.properties file while displaying the current tuning settings.

8

An unidentified error.

A.2.7.8 Location

  • UNIX and Linux: INSTANCE_DIR/OUD/bin/dstune

  • Windows: INSTANCE_DIR\OUD\bat\dstune.bat

A.2.7.9 Related Commands

Section A.2.5, "dsjavaproperties"

A.2.8 gicadm

The gicadm command manages global indexes and global index catalogs.

This command is supported only for the proxy.

A.2.8.1 Synopsis

gicadm [subcommand] [options]

A.2.8.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.8.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. The 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. The 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 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 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.8.4 LDAP Connection Options

The gicadm command contacts the directory server over SSL through the administration connector (described in Section 17.4, "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.8.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.8.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.8.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-27 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-28 Viewing Help on an Individual Subcommand

The following command displays the help information for the create-catalog subcommand:

$ gicadm create-catalog --help

Example A-29 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-30 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-31 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.8.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.8.9 Location

  • UNIX and Linux: INSTANCE_DIR/OUD/bin/gicadm

  • Windows: INSTANCE_DIR\OUD\bat\gicadm.bat

A.2.8.10 Related Commands

  • dsconfig

  • split-ldif

A.2.9 manage-tasks

The manage-tasks command manages and monitors tasks that have been scheduled to run on the directory server.

This command is not supported for the proxy.

A.2.9.1 Synopsis

manage-tasks [options]

A.2.9.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 17.5, "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 17.4, "Managing Administration Traffic to the Server").

A.2.9.3 Options

The manage-tasks command accepts an option in either its short form (for example, -c taskID) or its long form equivalent (for example, --cancel taskID).

-c, --cancel taskID

Specify a particular task to cancel.

-i, --info taskID

Display information for a particular task.

-s, --summary

Print a summary of tasks.

A.2.9.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 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.9.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.9.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.9.7 Examples

The following examples show how to use the manage-tasks command.

Example A-32 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-33 Obtaining Task Information

The following command returns information about a specific task:

$ manage-tasks -h localhost -p 4444 -D "cn=directory manager" -j /path/pwd-file \
  -X -i 2008101610442610
  Task Details
  -------------------------------------------------------
  ID                        2008101610442610
  Type                      Restore
  Status                    Waiting on start time
  Scheduled Start Time      Jan 25, 2009 12:15:00 PM SAST
  Actual Start Time
  Completion Time
  Dependencies              None
  Failed Dependency Action  None
  Email Upon Completion     admin@example.com
  Email Upon Error          admin@example.com

  Restore Options
  ----------------------------------
  Backup Directory  /backup/userRoot

Example A-34 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.9.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.9.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.9.10 Location

  • UNIX and Linux: OUD_ORACLE_HOME/bin/manage-tasks

  • Windows: OUD_ORACLE_HOME\bat\manage-tasks.bat

A.2.10 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 34, "Moving From a Test to a Production Environment."

A.2.10.1 Synopsis

oudCopyConfig [options]

A.2.10.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.10.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.10.4 Examples

The following examples show how to use the oudCopyConfig command.

Example A-35 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-36 Running the Help Command Option

$ OUD_ORACLE_HOME/bin/oudCopyConfig -javaHome /usr/jdk -help

A.2.10.5 Location

  • UNIX and Linux: OUD_ORACLE_HOME/bin/oudCopyConfig

  • Windows: OUD_ORACLE_HOME\bat\oudCopyConfig.bat

A.2.11 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 34, "Moving From a Test to a Production Environment."

A.2.11.1 Synopsis

oudExtractMovePlan [options]

A.2.11.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.11.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.11.4 Examples

The following examples show how to use the oudExtractMovePlan command.

Example A-37 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-38 Running the Help Command Option

$ OUD_ORACLE_HOME/bin/oudExtractMovePlan -javaHome /usr/jdk -help

A.2.11.5 Location

  • UNIX and Linux: OUD_ORACLE_HOME/bin/oudExtractMovePlan

  • Windows: OUD_ORACLE_HOME\bat\oudExtractMovePlan.bat

A.2.12 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 34, "Moving From a Test to a Production Environment."

A.2.12.1 Synopsis

oudPasteConfig [options]

A.2.12.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.12.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.12.4 Examples

The following examples show how to use the oudPasteConfig command.

Example A-39 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-40 Running the Help Command Option

$ OUD_ORACLE_HOME/bin/oudPasteConfig -javaHome /usr/jdk -help

A.2.12.5 Location

  • UNIX and Linux: OUD_ORACLE_HOME/bin/oudPasteConfig

  • Windows: OUD_ORACLE_HOME\bat\oudPasteConfig.bat

A.2.13 oud-replication-gateway-setup

The oud-replication-gateway-setup command is used to setup the replication gateway instance.

A.2.13.1 Synopsis

oud-replication-gateway-setup [options]

A.2.13.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:

No options are allowed if the command is run in GUI mode.

A.2.13.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.13.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 17.4, "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.13.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.13.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.13.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 must specify this option only if you have not configured replication for the provided Oracle Unified Directory server.

--secureReplicationNg

Specifies whether the replication communication established by the replication gateway to the Oracle Unified Directory servers is encrypted. If the replication port of the Oracle Unified Directory was not configured, the communication through it will be encrypted depending on whether this option is set.

-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.13.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 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.13.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.13.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.13.11 Examples

The following examples show how to use the replication server commands.

Example A-41 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-42 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.13.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.13.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.13.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.13.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.14 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.15, "oud-proxy-setup."

A.2.14.1 Synopsis

oud-setup [options]

A.2.14.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:

No options are allowed if the command is run in GUI mode.

A.2.14.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. Do not use this option 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. You generate the entries by using the MakeLDIF facility of the import command and they are based on the default example.template template. Do not use this option 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 17.4, "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

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

--serverTuning { jvm-default | heap-size | system-memory | system-memory-percentage | JVM arguments }

Specifies runtime tuning options for the server.

Note:

In Oracle Unified Directory 11g Release 2 (11.1.2.3), the autotune option has been removed. However, autotune usage is still available for backward compatibility.

To use the default (or configured) Java Virtual Machine with no extra arguments on your system when running the server, provide the value jvm-default.

To tune the server based on the heap size of its Java process, provide the memory to be used (for example: 768m). For gigabytes, use g (for example: 2.5g). If neither a unit nor a % is specified after the value, megabytes will be used.

The server requires memory not only for its Java process but also memory in the file-system cache. The memory for the server is the sum of the Java Heap and an estimation of the required file-system cache.

You can specify the system memory as either an amount or percentage:

  • Amount: For example:

    Specify --serverTuning systemMemory:3g to use 3.0 gigabytes.

    Specify --serverTuning systemMemory:1g to use one gigabyte.

    Specify --serverTuning systemMemory:512 to use 512 megabytes.

    The oud-setup script then splits the value you provide into two parts: the heap size that the Java Virtual Machine of the server will use and an estimation of the required file-system cache.

  • Percentage: For example:

    Specify --serverTuning systemMemory:50.0% to dedicate 50 percent of system memory to the server.

    Specify --serverTuning systemMemory:25% to dedicate 25 percent of system memory to the server.

    Specify --serverTuning systemMemory:100% to fully dedicate a machine to the server.

    The oud-setup script then splits the percentage you provide into two parts: the heap size that the Java Virtual Machine of the server will use and an estimation of the required file-system cache.

You can also directly specify the JVM arguments that the server must use. For example:

--serverTuning -server -Xmx1024m

The default value for the server will be calculated based on the free memory available on the system and will depend on the machine where the setup is running and how much memory is being used on that machine.

--offlineToolsTuning { autotune | jvm-default | JVM arguments }

Specifies tuning for the off-line tools (import-ldif, export-ldif, verify-index, and rebuild-index).

Note:

In Oracle Unified Directory 11g Release 2 (11.1.2.3), the --importTuning option has been renamed to --offlineToolsTuning. However, --importTuning usage is still available for backward compatibility.

The tools can be automatically tuned each time they are launched based on the available memory in the machine (provide the value autotune), or they can use the default Java Virtual Machine on your system for the run-time settings (provide the value jvm-default).

You can also directly provide the Java arguments that the tools should use. For example, the following command uses the -server argument:

--offlineToolsTuning  -server -Xmx1024m

The default value for the tools will be calculated based on the free memory available on the system and will depend on the machine where the setup is running and how much memory is being used on that machine.

A.2.14.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.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 directory server commands.

Example A-43 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-44 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-45 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-46 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-47 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-48 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

Example A-49 Running oud-setup in Interactive Mode To Tune the Server

The following command allows you to tune the Oracle Unified Directory server.

C:\OUD\OracleUnifiedDirectory> oud-setup.bat --cli
OUD Instance location successfully created - C:\OUD\OracleUnifiedDirectory\..\asinst_1"
 
Oracle Unified Directory 11.1.2.3.0
Please wait while the setup program initializes...
 
What would you like to use as the initial root user DN for the Directory
Server? [cn=Directory Manager]:
Please provide the password to use for the initial root user: password
Please re-enter the password for confirmation: password
 
On which port would you like the Directory Server to accept connections from
LDAP clients? [389]:
 
On which port would you like the Administration Connector to accept
connections? [4444]:
 
Do you want to create base DNs in the server? (yes / no) [yes]:
 
Provide the base DN for the directory data: [dc=example,dc=com]:
Options for populating the database:
 
    1)  Only create the base entry
    2)  Leave the database empty
    3)  Import data from an LDIF file
    4)  Load automatically-generated sample data
 
Enter choice [1]: 4
Please specify the number of user entries to generate: [2000]:
 
Do you want to enable SSL? (yes / no) [no]:
 
Do you want to enable Start TLS? (yes / no) [no]:
 
Enable the server to run as a Windows Service? (yes / no) [no]:
 
Specify the Oracle components with which the server integrates.  It is
recommended to choose the option covering only your requirements.
 
    1)  No Integration
    2)  DIP (Directory Integration Platform)
    3)  Generic: Database Net Services, EBS and DIP
    4)  EUS (Enterprise User Security), Database Net Services, EBS and DIP
 
    c)  cancel
 
Enter choice [1]:
 
How do you want the OUD server to be tuned?
 
    1)  Use specific Java Virtual Machine arguments
    2)  Use the default Java Virtual Machine settings
    3)  Provide the Java heap size to be used by the server
    4)  Provide the percentage of system memory to be used by the server
    5)  Provide the size of system memory to be used by the server
 
Enter choice [2]: 2
 
How do you want the off-line tools (import-ldif, export-ldif, verify-index and
rebuild-index) to be tuned?
 
    1)  Use specific Java Virtual Machine arguments
    2)  Use the default Java Virtual Machine settings
    3)  Automatic Tuning
    4)  Provide the Java heap size to be used by the off-line tools
 
Enter choice [2]: 3
 
Do you want to start the server when the configuration is completed? (yes /
no) [yes]:
 
 
Setup Summary
=============
LDAP Listener Port:                  389
Administration Connector Port:       4444
LDAP Secure Access:                  disabled
Root User DN:                        cn=Directory Manager
Directory Data:                      Create New Base DN dc=example,dc=com
                                     Base DN Data: Import Automatically-Generated
                                     Data (2000 Entries)
Integration with Oracle components:  No Integration
Server Runtime Settings:             Use the default Java Virtual Machine settings
Off-line Tools Runtime Settings:     Use Automatic Tuning
 
Start Server when the configuration is completed
Do not enable the server to run as a Windows Service
 
 
What would you like to do?
 
    1)  Set up the server with the parameters above
    2)  Provide the setup parameters again
    3)  Print equivalent non-interactive command-line
    4)  Cancel and exit
 
Enter choice [1]:
 
See C:\OUD\asinst_1\OUD\logs\oud-setup for a detailed
log of this operation.
 
Configuring Directory Server ..... Done.
Importing Automatically-Generated Data (2000 Entries) ........ Done.
Starting Directory Server ....... Done.
 
To see basic server configuration status and configuration you can launch
C:\OUD\asinst_1\OUD\bat\status.bat
...

A.2.14.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.14.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.14.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.14.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.15 oud-proxy-setup

The oud-proxy-setup command manages the setup and configuration of a proxy server instance.

A.2.15.1 Synopsis

oud-proxy-setup [options]

A.2.15.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.15.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.15.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.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 directory server and exit rather than attempting to run this command.

A.2.15.6 Examples

The following examples show how to use the oud-proxy-setup command.

Example A-50 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-51 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.15.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.15.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.15.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.16 start-ds

The start-ds command starts an installed server instance.

A.2.16.1 Synopsis

start-ds [options]

A.2.16.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.16.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.16.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.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 start—ds command.

Example A-52 Starting the Server

The following command starts the server:

$ start-ds

Example A-53 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.16.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.16.8 Location

  • UNIX and Linux: INSTANCE_DIR/OUD/bin/start-ds

  • Windows: INSTANCE_DIR\OUD\bat\start-ds.bat

A.2.16.9 Related Commands

A.2.17 status

The status command displays basic server status information.

A.2.17.1 Synopsis

status [options]

A.2.17.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 17.4, "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.17.3 LDAP Connection Options

The status command contacts the server over SSL through the administration connector (described in Section 17.4, "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 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.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.17.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.17.6 Examples

The following examples show how to use the status command.

Example A-54 Displaying the Server Status

The following example displays the current status of a standalone server that is currently online:

$ status -D "cn=directory manager" -j /path/pwd-file -X -n

          --- Server Status ---
Server Run Status:        Started
Open Connections:         1

          --- Server Details ---
Host Name:                hostname
Administrative Users:     cn=Directory Manager
Installation Path:        /path/OracleUnifiedDirectory
Instance Path:            /path/asinst_1/OUD
Version:                  Oracle Unified Directory 11.1.2.3.0
Java Version:             1.7.0_67
Administration Connector: Port 4444 (LDAPS)

          --- Connection Handlers ---
Address:Port : Protocol    : State
-------------:-------------:---------
--           : LDIF        : Disabled
8989         : Replication : Enabled
0.0.0.0:161  : SNMP        : Disabled
0.0.0.0:636  : LDAPS       : Disabled
0.0.0.0:1389 : LDAP        : Enabled
0.0.0.0:1689 : JMX         : Disabled

          --- Data Sources ---
Base DN:                      dc=example,dc=com
Backend ID:                   userRoot
Entries:                      7
Replication:                  Enabled
Missing Changes:              0
Age Of Oldest Missing Change: not available

A.2.17.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.17.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.17.9 Location

  • UNIX and Linux: INSTANCE_DIR/OUD/bin/status

  • Windows: INSTANCE_DIR\OUD\bat\status.bat

A.2.18 stop-ds

The stop-ds command stops a server instance.

A.2.18.1 Synopsis

stop-ds [options]

A.2.18.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 17.4, "Managing Administration Traffic to the Server."

A.2.18.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 plugins 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.18.4 LDAP Connection Options

The stop-ds command contacts the server over SSL through the administration connector (described in Section 17.4, "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 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.18.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.18.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.18.7 Examples

The following examples show how to use the stop-ds command.

Example A-55 Stopping a Server Locally

The following command stops the server:

$ stop-ds

Example A-56 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-57 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.18.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.18.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.18.10 Location

  • UNIX and Linux: INSTANCE_DIR/OUD/bin/stop-ds

  • Windows: INSTANCE_DIR\OUD\bat\stop-ds.bat

A.2.18.11 Related Commands

Section A.2.16, "start-ds"

A.2.19 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.19.1 Synopsis

uninstall [options]

A.2.19.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.19.3 Removing a Directory Server

This section describes the options to remove a directory server instance.

A.2.19.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.19.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.19.4 Removing a Proxy Server

This section describes the options to remove a proxy server instance.

A.2.19.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.19.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.19.5 Removing a Replication Gateway Server

This section describes the options for removing an instance of the replication gateway server.

A.2.19.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.19.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.19.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.19.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.19.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 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.19.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.19.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.19.8 Examples

The following examples show how to use the server commands.

Example A-58 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-59 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-60 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.19.9 Exit Codes

The following exit codes are applicable for a directory server and a proxy server:

0

Successful.

1

User canceled the operation.

2

User provided invalid data.

3

Error accessing file system (reading/writing).

5

Error during the configuration of the Directory Server.

7

Error starting the Oracle Unified Directory server.

8

Error stopping the Oracle Unified Directory server.

9

Error disabling the Windows service.

10

Application specific error.

11

Error invoking an Oracle Unified Directory tool.

12

Bug.

13

Java version non-compatible.

14

User provided invalid input.

50

Print Version.

51

Print Usage.

100

Return code for errors that are non-specified.

The following exit codes are applicable for a gateway server:

0

Successful uninstall.

1

Unexpected error (potential bug).

2

Cannot parse arguments or data provided by user is not valid.

3

The user canceled the uninstall.

4

Incompatible Java version.

5

Error initializing the replication gateway configuration (loading the admin framework classes, and so on).

6

Error stopping the replication gateway.

7

Error unconfiguring windows service.

8

Error input limit.

9

Error updating ADS Contents.

10

An error with the configuration of the legacy server. The base DN specified in the replica configuration is not a valid DN.

11

One of the specified legacy (Oracle Directory Server Enterprise Edition) servers is not compatible.

12

One of the specified new generation (Oracle Unified Directory based) servers is not compatible.

13

The user does not accept the certificate.

14

The user does not want to continue because there were issues loading the configuration of some servers.

15

An error with the configuration of the replication gateway.

16

The user overcame the maximum number of tries in interactive mode.

17

The user aborted the uninstall.

18

Error accessing file system (for instance deleting installation files).

A.2.19.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.19.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.19.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.20 windows-service

The windows-service command manually enables or disables the server as a Windows service.

A.2.20.1 Synopsis

windows-service [options]

A.2.20.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.20.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.20.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.20.5 Examples

The following examples show how to use the windows-service command.

Example A-61 Enabling the Server as a Windows Service

The following command enables the server as a Windows service:

$ windows-service -e

Example A-62 Disabling the Server as a Windows Service

The following command disables the server as a Windows service:

$ windows-service -d

Example A-63 Displaying a Status

The following command displays a status of the server as a Windows service:

$ windows-service -s

A.2.20.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.20.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 17.5, "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 17.4, "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. Do not use this option 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. 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. 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 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-64 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-65 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-66 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-67 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-68 Running an Incremental Backup Against an Existing Backup

Assume that you have created two archived incremental backup files by using the -I or --backupID option and assigned the IDs 1234 and 4898 to the two files, respectively:

/tmp/backup/userRoot> ls
./     backup-userRoot-1234   backup.info
../    backup-userRoot-4898   backup.info.save

The following command runs an incremental backup (-i) on all configured back ends (-a) based on the backup ID 1234 (-B), assigns a backup ID of 5438 to the incremental backup, and saves the data to a directory (-d).

$ backup -a -i -B 1234 -I 5438 -d /tmp/backup

The contents of backup.info show that the latest incremental backup (backup_id=5438) has a dependency on backup_id=1234:

$ backend_dn=ds-cfg-backend-id=userRoot,cn=Backends,cn=config

backup_id=4898
backup_date=20070727202906Z
incremental=false
compressed=false
encrypted=false
signed_hash=VmBG/VkfMAMMPnR6M8b5kZil7FQ=
property.last_logfile_name=00000000.jdb
property.archive_file=backup-userRoot-4898
property.cipher_algorithm=AES/CBC/PKCS5Padding
property.mac_algorithm=HmacSHA1
property.last_logfile_size=490554

backup_id=1234
backup_date=20070727202934Z
incremental=false
compressed=false
encrypted=false
signed_hash=VmBG/VkfMAMMPnR6M8b5kZil7FQ=
property.last_logfile_name=00000000.jdb
property.archive_file=backup-userRoot-1234
property.cipher_algorithm=AES/CBC/PKCS5Padding
property.mac_algorithm=HmacSHA1
property.last_logfile_size=490554

backup_id=5438
backup_date=20070727203107Z
incremental=true
compressed=false
encrypted=false
dependency=1234
property.last_logfile_name=00000000.jdb
property.archive_file=backup-userRoot-5438
property.last_logfile_size=490554

Example A-69 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-70 Scheduling a Backup

Scheduling a backup requires online access to the tasks back end. Access to this back end is provided over SSL through the administration connector. When you schedule a backup, you must therefore specify the connection details, including the host, administration port, bind DN and bind password file. You must also specify the certificate details for the SSL connection.

The following command schedules a backup of all components (-a) and writes it to the /tmp/backups directory (-d). The start time is specified with the --start option. The backup sends a completion notification and error notification to admin@example.com. The self signed certificate is trusted using the -X (--trustAll) option.

$ backup -h localhost -D "cn=Directory Manager" -j /path/pwd-file -p 4444 -X \
  -a -d /tmp/backups --start 20090124121500 --completionNotify admin@example.com \
  --errorNotify admin@example.com
Backup task 2007102914530410 scheduled to start Jan 24, 2009 12:15:00 PM SAST

You can view this scheduled task by using the manage-tasks command. For more information, see Section 17.5, "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-71 Base64 Encoding a String

The following command base64-encodes the string opends.

$ base64 encode -d opends
b3BlbmRz

Example A-72 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-73 Decoding a Base64-Encoded String

The following command decodes a base64-encoded string.

$ base64 decode -d b3BlbmRz
opends

Example A-74 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-75 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. The 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-76 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-77 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-78 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-79 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.4 encode-password

The encode-password command encodes and compares user passwords.

This command is not supported for the proxy.

A.3.4.1 Synopsis

encode-password options

A.3.4.2 Description

The encode-password command can be used to interact with the password storage schemes defined in the directory server. It has three modes of operation:

  • List schemes mode. List the password storage schemes that are available in the directory server. In this mode, only the --listSchemes option is required.

  • Encode clear-text mode. Encode a clear-text password using a provided password storage scheme. In this mode, the --storageScheme option is required, along with a clear-text password that is read from a file (--clearPasswordFile).

  • Validate password mode. Determine whether a given clear-text password is correct for a provided encoded password. In this mode, a clear-text password (from --clearPasswordFile) and an encoded password (from --encodedPasswordFile) are required.

The set of authentication passwords available for use in the directory server can be retrieved from the supportedAuthPasswordSchemes attribute of the root DSE entry. You can use ldapsearch to view this information.

A.3.4.3 Options

The encode-password command accepts an option in either its short form (for example, -f filename) or its long form equivalent (for example, --clearPasswordFile filename).

-a, --authPasswordSyntax

Use the Authentication Password Syntax (as defined in RFC 3112 (http://www.ietf.org/rfc/rfc3112.txt)), which encodes values in a form scheme$authInfo$authValue. If this option is not provided, then the user password syntax (which encodes values in a form scheme$value will be used.

-E, --encodedPasswordFile filename

Use the encoded password from the specified file to compare against a given clear-text password. If the --authPasswordSyntax option is also provided, then this password must be encoded using the authentication password syntax. Otherwise, it should be encoded using the user password syntax.

-f, --clearPasswordFile filename

Use the clear-text password from the specified file when either encoding a clear-text password or comparing a clear-text password against an encoded password.

-i, --interactivePassword

The password to encode or to compare against an encoded password is interactively requested from the user.

-l, --listSchemes

Display a list of the password storage schemes that are available for use in the directory server. If the option is used by itself, it displays the names of the password storage schemes that support the user password syntax. If the option used with --authPasswordSyntax, then 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-80 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-81 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-82 Encoding a Clear-Text Password to Another Scheme

The following command encodes a clear-text password in a file (-f) using the specified scheme (-s).

$ encode-password -f /path/clear-pwd-file -s MD5

Encoded Password:  "{MD5}AjxHKRFkRwxx3j9lM2HMow=="

Example A-83 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-84 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-85 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-86 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 17.5, "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 17.4, "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. 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.

-d, --decrypt

Decrypt the LDIF data as it is exported. The default value is not to decrypt.

If -d option is not used, then an encrypted attribute is exported encrypted and the presence of {ENC} header in the attribute value states that it is an encrypted value. The values that follows the {ENC} header is base64 encoded format. Consider the following example, an LDIF entry with some encrypted attributes:

dn: uid=user87633,ou=Accounting,dc=example,dc=com objectClass: person
objectClass: organizationalperson
objectClass: inetorgperson
objectClass: top uid: user87633 description: An employee of the company
userPassword: {SSHA512}VYWWH4FxWtL7xez9Bz3n12Qvr9nnR1rwZa9tSjVk1EbZ8WgX0ay0ywPggQj2KnfABTdl9zYI/gjo+/Z1ODbKVkKoharGfvfP
employeeNumber: 87633
pager: {ENC}AQ8F/ppNg0MArph6C+5upN9woi8A7+kPxvISoI+GqDUw
mobile: {ENC}AQ8F/ppNg0MArph6C+5upN+D113xXHRk5SPy2smCNyAn
mobile: {ENC}AQ8F/ppNg0MArph6C+5upN8RMqemKLxYPG09bkPUjBSk

Every string value following the {ENC} header is base64 encrypted format of the original value that is encrypted by the CryptoManager.

If -d option is used, then an encrypted attribute is exported in clear.

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

-g, --algorithm algorithm

The specified algorithm used in the export. This option is optional and you can enter one of the following values:

  • diskOrder: This option causes data to be read from an Oracle Berkeley DB Java Edition (JE) back end in the order that it is stored on the disk.

    Oracle recommends using the diskOrder option if the database does not fit entirely in the database cache. With this option, an export operation temporarily uses 20% of the database cache to run and then releases the memory. Thus, the database cache memory is decreased by 20% during the operation.

    Note:

    This algorithm uses a feature called Disk Ordered from the JE back end and can cause an error if the server is running and you access it for modifications during the export operation. You can perform read operations.

  • entryIdOrder: This option causes the data to be read from an Oracle Berkeley DB Java Edition (JE) back end in the order that it is logically stored on the disk.

    The entryIdOrder option provides better performance than the diskOrder option algorithm if the database fits entirely into the database cache.

    This option does not temporarily extract any memory from the database cache. Thus, you can use this option when the server is running and you want to access it for modifications during the export operation.

  • auto: This option automatically selects diskOrder in an offline mode when the server is down or entryIdOrder in an online mode when the server is running.

-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 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-87 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-88 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-89 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 17.5, "Configuring Commands As Tasks."

A.3.5.9 Exit Codes

  • Offline mode. An exit code of 0 indicates that the operation completed successfully. A nonzero 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.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. 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 17.5, "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 17.4, "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. 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:

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. 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. Do not use this option 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 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-90 Running an Offline Import

This example imports an LDIF file to the userRoot back end. The LDIF file path supports both absolute and relative paths 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-91 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 supports both absolute and relative paths 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-92 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-93 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 supports both absolute and relative paths 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-94 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 supports both absolute and relative paths 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-95 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 supports both absolute and relative paths 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-96 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 supports both absolute and relative paths 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-97 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-98 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 17.5, "Configuring Commands As Tasks."

A.3.6.9 Exit Codes

  • Offline mode. An exit code of 0 indicates that the operation completed successfully. A nonzero 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.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.

Note:

The ldif-diff command is not intended for large files. Running the ldif-diff command on LDIF files over a certain size (around 600 Kbytes on Windows systems, larger on UNIX systems) might result in a memory error similar to the following:

Exception in thread "main" java.lang.OutOfMemoryError: Java heap space.

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-99 Comparing Two LDIF files and Sending the Differences to Standard Output

The following command compares a source file (-s) with a target file (-t) and outputs the differences. For Windows platforms, specify the paths for the source file (for example, -s \temp\quentin.ldif) and the target file (for example, -t \temp\quentin.ldif):

$ ldif-diff -s /usr/local/quentin.ldif -t /usr/local/quentinr.ldif

dn: uid=qcubbins,ou=People,dc=example,dc=com
changetype: delete
# objectClass: person
# objectClass: organizationalPerson
# objectClass: top
# objectClass: inetOrgPerson
# cn: Quentin Cubbins
# sn: Cubbins
# uid: qcubbins
# userPassword: qcubbins
# givenName: Quentin
# description: This is Quentin's description.
# mail: qcubbins@example.com

dn: uid=qrcubbins,ou=People,dc=example,dc=com
changetype: add
objectClass: person
objectClass: organizationalPerson
objectClass: top
objectClass: inetOrgPerson
cn: Quentin R Cubbins
sn: Cubbins
uid: qrcubbins
userPassword: qrcubbins
givenName: Quentin
description: This is Quentin R's description.
mail: qrcubbins@example.com

Example A-100 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.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 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-101 Modifying an LDIF File

Suppose that the source file is as follows:

dn: uid=qcubbins,ou=People,dc=example,dc=com
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
uid: qcubbins
givenName: Quentin
sn: Cubbins
cn: Quentin Cubbins
mail: qcubbins@example.com
userPassword: qcubbins
description: This is Quentin's description.

And suppose that the update (change) file is as follows:

## Add new telephone number for Quentin Cubbins
dn: uid=qcubbins,ou=People,dc=example,dc=com
changetype: modify
add: telephoneNumber
telephoneNumber: 512-401-1241

The following command updates a source file (-s) with changes listed in a modify file (-m) and outputs to a target file (-t). For Windows platforms, use the file paths for the modify file (for example, -m \temp\update.ldif), the source file (for example, -s \temp\quentin.ldif), and the target file (for example, -s \temp\quentin_updated.ldif):

$ ldifmodify -m /usr/local/update.ldif -s /usr/local/quentin.ldif \
-t /usr/local/quentin_updated.ldif

The updated file is as follows:

dn: uid=qcubbins,ou=People,dc=example,dc=com
objectClass: inetOrgPerson
objectClass: person
objectClass: top
objectClass: organizationalPerson
sn: Cubbins
userPassword: qcubbins
description: This is Quentin's description.
cn: Quentin Cubbins
telephoneNumber: 512-401-1241
givenName: Quentin
uid: qcubbins
mail: qcubbins@example.com

A.3.8.5 Exit Codes

An exit code of 0 indicates that the operation completed successfully. An exit code of 1 or greater indicates that an error occurred during processing.

A.3.8.6 Location

  • UNIX and Linux: INSTANCE_DIR/OUD/bin/ldifmodify

  • Windows: INSTANCE_DIR\OUD\bat\ldifmodify.bat

A.3.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:

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-102 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-103 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-104 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-105 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-106 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-107 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-108 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.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:

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 17.4, "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 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-109 Viewing All Password Policy State Information for a User

The following command returns the password policy state information for a user:

$ manage-account get-all -h localhost -p 4444 -D "cn=Directory Manager" \
  -j /path/pwd-file -X -b "uid=scarter,ou=People,dc=example,dc=com" \

Password Policy DN:  cn=Default Password Policy,cn=Password Policies,cn=config
Account Is Disabled:  false
Account Expiration Time:
Seconds Until Account Expiration:
Password Changed Time:  19700101000000.000Z
Password Expiration Warned Time:
Seconds Until Password Expiration:
Seconds Until Password Expiration Warning:
Authentication Failure Times:
Seconds Until Authentication Failure Unlock:
Remaining Authentication Failure Count:
Last Login Time:
Seconds Until Idle Account Lockout:
Password Is Reset:  false
Seconds Until Password Reset Lockout:
Grace Login Use Times:
Remaining Grace Login Count:  0
Password Changed by Required Time:
Seconds Until Required Change Time:

Example A-110 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-111 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 back-end database is unavailable while rebuild-index is running.

Note:

Online option is useful when there are multiple back-ends.

With online option, rebuild-index can be executed separately for different back-ends without bringing down all the back-ends.

Also, the rebuild-index command usually runs faster with the server offline, especially if the --rebuildAll option is specified.

Note:

As time progresses, the list of entry identifiers becomes unordered. As this happens, the performance of the rebuild-index command gradually decreases.

If you can avoid reindexing large databases, you should do so. Otherwise, if the performance of the rebuild-index command is severely compromised, reimport the database, to start with a fresh, ordered list of entry identifiers.

A.3.13.3 Options

The rebuild-index command accepts an option in either its short form (for example, -b baseDN) or its long form equivalent (for example, --baseDN baseDN).

A.3.13.4 Command Options

-b, --baseDN baseDN

Specify the base DN of a back end that supports indexing. The rebuild operation is performed on indexes within the scope of the given base DN.

-i, --index index

Specify the name of the indexes to rebuild. For an attribute index, this is simply an attribute name. At least one index must be specified for rebuild.

--rebuildAll

Rebuild all indexes that are contained in the back end that is specified by the base DN. This option not only re-indexes all attribute indexes but also the dn2id system index, any extensible and VLV indexes, and the dn2uri index. The rebuildAll option cannot be used with the -i option.

--tmpDirectory

Specify the location of a temporary work directory for scratch index files. The default temporary work directory is INSTANCE_DIR/OUD/import-tmp.

A.3.13.5 Task Back End Connection Options

Rebuilding an index online requires access to the tasks back end. Access to the tasks back end is provided over SSL through the administration connector. These connection options are used when the rebuild runs online.

-D, --bindDN bindDN

Use the bind DN to authenticate to the directory server. This option is used when performing simple authentication and is not required if SASL authentication is used. The default value for this option is cn=Directory Manager.

-h, --hostname hostname

Contact the directory server on the specified hostname or IP address. If this option is not provided, a default of localhost is used.

-j, --bindPasswordFile filename

Use the bind password in the specified file when authenticating to the directory server.

-K, --keyStorePath path

Use the client keystore certificate in the specified path.

-N, --certNickname nickname

Use the specified certificate for client authentication.

-o, --saslOption name=value

Use the specified options for SASL authentication.

-p, --port port

Contact the directory server at the specified administration port. If this option is not provided, the default administration port of 4444 is used.

-P, --trustStorePath path

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

-u, --keyStorePasswordFile filename

Use the password in the specified file to access the certificates in the client keystore. This option is only required if --keyStorePath is used.

-U, --trustStorePasswordFile filename

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

-X, --trustAll

Trust all server SSL certificates that the directory server presents. This option can be used for convenience and testing purposes, but for security reasons a trust store should be used to determine whether the client should accept the server certificate.

A.3.13.6 Task Scheduling Options

These options are used when you specify that the index should be rebuilt as a scheduled task.

--completionNotify emailAddress

Specify the email address of a recipient to be notified when the task completes. This option can be specified more than once in a single command.

--dependency taskId

Specify the ID of a task upon which this task depends. A task does not start executing until all of its dependencies have completed execution.

--errorNotify emailAddress

Specify the email address of a recipient to be notified if an error occurs when this task executes. This option can be specified more than once in a single command.

--failedDependencyAction action

Specify the action that this task will take if one of its dependent tasks fails. The value must be one of PROCESS, CANCEL, or DISABLE. If no value is specified, the default action is CANCEL.

--recurringTask schedulePattern

Indicates that the task is recurring and will be scheduled according to the schedulePattern, expressed as a crontab(5) compatible time and date pattern.

-t, --start startTime

Indicates the date and time at which the operation starts when scheduled as a directory server task expressed in the format YYYYMMDDhhmmss. A value of 0 schedules the task for immediate execution. When this option is specified, the operation is scheduled to start at the specified time after which the command exits immediately.

A.3.13.7 Utility Input/Output Options

--propertiesFilePath propertiesFilePath

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

--noPropertiesFile

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

-v, --verbose

Use verbose mode.

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-112 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-113 Rebuilding All Indexes

This example uses the --rebuildAll option to rebuild all indexes.

$ rebuild-index -b "dc=example,dc=com" --rebuildAll

Example A-114 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.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 17.5, "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 17.4, "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 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-115 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-116 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-117 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-118 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 17.5, "Configuring Commands As Tasks." You must ensure that the server is running prior to the scheduled restore date and time.

$ restore -h localhost -p 4444 -D "cn=directory manager" -j /path/pwd-file -X \
  -d /backup/userRoot --start 20081025121500 --completionNotify admin@example.com \
  --errorNotify admin@example.com
Restore task 2008101610442610 scheduled to start Oct 25, 2008 12:15:00 PM SAST

A.3.14.9 Exit Codes

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

A.3.14.10 Using a Properties File

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

A.3.14.11 Location

  • UNIX and Linux: INSTANCE_DIR/OUD/bin/restore

  • Windows: INSTANCE_DIR\OUD\bat\restore.bat

A.3.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.8, "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

The 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

The 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-119 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-120 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

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

-v, --verbose

Use verbose mode.

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-121 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-122 Verifying an Index and Counting Errors

The following command counts the number of discrepancies (--countErrors) in the sn (surname) index (-i sn) under the dc=example,dc=com base DN (-b dc=example,dc=com):

$ verify-index -b dc=example,dc=com -c -i sn --countErrors

[31/Jul/2007:02:23:52 -0500] category=BACKEND severity=NOTICE msgID=8388709 msg=
Checked 466 records and found 0 error(s) in 0 seconds (average rate 1298.1/sec)
[31/Jul/2007:02:23:52 -0500] category=BACKEND severity=NOTICE msgID=8388710 msg=
Number of records referencing more than one entry: 225
[31/Jul/2007:02:23:52 -0500] category=BACKEND severity=NOTICE msgID=8388711 msg=
Number of records that exceed the entry limit: 0
[31/Jul/2007:02:23:52 -0500] category=BACKEND severity=NOTICE msgID=8388712 msg=
Average number of entries referenced is 2.59/record
[31/Jul/2007:02:23:52 -0500] category=BACKEND severity=NOTICE msgID=8388713 msg=
Maximum number of entries referenced by any record is 150

A.3.16.7 Exit Codes

An exit code of 0 indicates that the operation completed successfully. An exit code of 1 or greater indicates that an error occurred during processing.

A.3.16.8 Location

  • UNIX and Linux: INSTANCE_DIR/OUD/bin/verify-index

  • Windows: INSTANCE_DIR\OUD\bat\verify-index.bat

A.3.16.9 Related Commands

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 issues 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 about 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. Use this form only if the value can be expressed as a string. Do not use this form 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. Do not use this subcommand 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. Do not use 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. Do not use this option 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. Do not use this option 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 to access its contents (which most trust stores do not require). Do not use this option 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. Do not use this option 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 to access its contents (most trust stores do not require this). Do not use this option 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. Do not use this option 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. Do not use this option 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-123 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-124 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-125 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-126 Using ldapcompare with Client Authentication

The following command uses client authentication with the compare. The command uses SSL (-Z) with the SSL port (-p), specifies the trust store file path (-P), the certificate nickname (-N), the keystore file path (-K), the keystore password (-W) and checks if the entity's given name givenname=Sam is present in the entry. For Windows platforms, use the path where your trust store file resides (for example, -P \temp\certs\cert.db) and where the path where your keystore file resides (-K \temp\security\key.db).

$ ldapcompare -h hostname -p 1636 -Z \
-P /home/kwinters/security/cert.db -N "kwcert" \
-K /home/kwinters/security/key.db -W KeyPassword \
'givenname:Sam' "uid=scarter,ou=People,dc=example,dc=com"

Comparing type givenname with value Sam in entry uid=scarter,ou=People,dc=example,dc=com
Compare operation returned true for entry uid=scarter,ou=People,dc=example,dc=com

A.4.1.9 Exit Codes

An exit code of 6 indicates that the comparison is successful. An exit code of 5 indicates that the comparison is unsuccessful. Any other exit code indicates that an error occurred during processing.

A.4.1.10 Using a CLI Properties File

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

The following options can be stored in a properties file:

  • assertionFilter

  • bindDN

  • bindPassword

  • bindPasswordFile

  • certNickname

  • continueOnError

  • control

  • dry-run

  • filename

  • hostname

  • keyStorePassword

  • keyStorePasswordFile

  • keyStorePath

  • ldapVersion

  • port

  • saslOption

  • trustAll

  • trustStorePassword

  • trustStorePasswordFile

  • trustStorePath

  • useSASLExternal

  • useSSL

  • useStartTLS

  • verbose

Entries in the properties file have the following format:

toolname.propertyname=propertyvalue

For example:

ldapcompare.ldapport=12345

A.4.1.11 Location

  • UNIX and Linux: INSTANCE_DIR/OUD/bin/ldapcompare

  • Windows: INSTANCE_DIR\OUD\bat\ldapcompare.bat

A.4.2 ldapdelete

The ldapdelete command issues LDAP delete requests to the directory server 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 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 must 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. Do not use this form 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. Do not use this subcommand 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. Do not use 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. Do not use this option 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 26.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. Do not use this option 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 to access its contents (which most trust stores do not require). Do not use this option 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. Do not use this option 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 to access its contents (most trust stores do not require this). Do not use this option 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. Do not use this option 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. Do not use this option 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-127 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-128 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-129 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-130 Deleting Entries by Using Client Authentication

The following command uses client authentication to perform a delete option. The command uses SSL (-Z) with the SSL port (-p), specifies the trust store file path (-P), the certificate nickname (-N), the keystore file path (-K), the keystore password (-W) and the LDIF file (-f) that contains the deletions. If an error occurs, the command continues (-c) to the next search item. For Windows platforms, use the path where the deletion file resides (for example, -f \temp\delete.ldif), the file where the trust store password resides (for example, -P \temp\certs\cert.db), and the file where the keystore password resides (for example, -K \temp\security\key.db).

$ ldapdelete -h hostname -p 1636 -c -f /usr/local/delete.ldif \
-Z -P /home/kwinters/security/cert.db -N "kwcert" \
-K /home/kwinters/security/key.db -W keypassword

A.4.2.10 Exit Codes

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

A.4.2.11 Using a CLI Properties File

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

The following options can be stored in a properties file:

  • bindDN

  • bindPassword

  • bindPasswordFile

  • certNickname

  • continueOnError

  • control

  • deleteSubtree

  • dry-run

  • filename

  • hostname

  • keyStorePassword

  • keyStorePasswordFile

  • keyStorePath

  • ldapVersion

  • port

  • saslOption

    SASL is not supported for a proxy server instance

  • trustAll

  • trustStorePassword

  • trustStorePasswordFile

  • trustStorePath

  • useSASLExternal

    SASL is not supported for a proxy server instance.

  • useSSL

  • useStartTLS

  • verbose

Entries in the properties file have the following format:

toolname.propertyname=propertyvalue

For example:

ldapdelete.ldapport=12345

A.4.2.12 Location

  • UNIX and Linux: INSTANCE_DIR/OUD/bin/ldapdelete

  • Windows: INSTANCE_DIR\OUD\bat\ldapdelete.bat

A.4.3 ldapmodify

The ldapmodify command modifies directory entries.

A.4.3.1 Synopsis

ldapmodify [options] [filter] [attributes]

A.4.3.2 Description

The ldapmodify command can be used to perform LDAP modify, add, delete, and modify DN operations in the directory server. The operations to perform in the directory server should be specified in LDIF change format, as described in RFC 2849 (http://www.ietf.org/rfc/rfc2849.txt). This change syntax uses the changetype keyword to indicate the type of change.

An add change record is straightforward, because it is a complete entry in LDIF form with a changetype value of add. For example:

dn: uid=john.doe,ou=People,dc=example,dc=com
changetype: add
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
uid: john.doe
givenName: John
sn: Doe
cn: John Doe
mail: john.doe@example.com
userPassword: password

A delete change record is even simpler than an add change record. The add record consists of a line with the entry DN followed by another line with a changetype of delete. For example:

dn: uid=john.doe,ou=People,dc=example,dc=com
changetype: delete

The modify change record is the most complex operation, because of the number of variants. The modify change records all start with the entry DN followed by a changetype of modify. The next line consists of either add, delete, or replace followed by an attribute name indicating what modification will be and to which attribute. The change record may optionally be followed by one or more lines containing the attribute name followed by a value to use for the modification (that is, a value to add to that attribute, remove from that attribute, or use to replace the existing set of values). Multiple attribute changes can be made to an entry in the same modify operation by separating changes with a line containing only a dash, starting the next line with a new add, delete, or replace tag followed by a colon and the next attribute name, and then setting of values for that attribute. For example:

dn: uid=john.doe,ou=People,dc=example,dc=com
changetype: modify
replace: description
description: This is the new description for John Doe
-
add: mailAlternateAddress
mailAlternateAddress: jdoe@example.com

Modify DN change records should always contain the newRDN and deleteOldRDN elements and can optionally contain the newSuperior component to specify a new parent for the target entry. For example:

dn: uid=john.doe,ou=People,dc=example,dc=com
changetype: moddn
newRDN: uid=jdoe
deleteOldRDN: 1

If no arguments are provided to the ldapmodify command, it attempts to interact with a Directory Server instance using an unauthenticated connection using the loopback address on port 389, and information about the changes to request will be read from standard input. This is unlikely to succeed, as it will almost certainly be necessary to at least provide arguments that will be used to specify how to authenticate to the server.

A.4.3.3 Before You Begin

Many UNIX and Linux operating systems provide an installed version of common LDAP client commands, such as ldapsearch, ldapmodify, and ldapdelete in the /usr/bin directory. You can check if a version is on your system by entering the command: which ldapmodify. If the command returns a value (seen below), you must 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 if 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. Use this form only if the value can be expressed as a string. Do not use this form 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. Do not use this subcommand 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. Do not use 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. Do not use this option 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 26.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. Do not use this option 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 to access its contents (which most trust stores do not require). Do not use this option 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. Do not use this option 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 to access its contents (most trust stores do not require this). Do not use this option 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. Do not use this option 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. Do not use this option 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.

Example A-131 Adding an Entry

The following LDIF file contains an entry for an employee:

dn: uid=Marcia Garza,ou=People,dc=example,dc=com
cn: Marcia Garza
sn: Garza
givenName: Marcia
objectClass: person
objectClass: inetOrgPerson
objectClass: top
objectClass: organizationalPerson
ou: Accounting
ou: People

The following command specifies the host name (-h), port (-p), bind DN (-D), bind password (-w), reads the modifications from the file (-f) and adds the entry (-a) to the database. For Windows platforms, specify the path to your LDIF file (for example, -f \temp\add_entry.ldif).

$ ldapmodify -h hostname -p 1389 -D "cn=Directory Manager" -j pwd-file \
-a -f /usr/local/add_entry.ldif

Example A-132 Adding an Attribute to an Entry

The following LDIF file modifies an entry by adding a telephonenumber attribute:

dn: uid=Marcia Garza,ou=People,dc=example,dc=com
changetype: modify
add: telephonenumber
telephonenumber: +1 408 555 8283

The following command specifies the host name (-h), port (-p), bind DN (-D), bind password (-w), reads the modifications from the file (-f) and adds an attribute to the entry. For Windows platforms, specify the path to your LDIF file (for example,

-f \temp\add_attribute.ldif).

$ ldapmodify -h hostname -p 1389 -D "cn=Directory Manager" -j pwd-file \
-f /usr/local/add_attribute.ldif

Example A-133 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-134 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-135 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-136 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-137 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-138 Using ldapmodify with Client Authentication

The following command uses the -P SSL option to perform a modify using client authentication. The command uses SSL (-Z) with the SSL port (-p) and specifies the trust store file path (-P), the certificate nickname (-N), the keystore file path (-K), the keystore password (-W) and the LDIF file (-f) that contains the changes. For Windows platforms, specify the paths for the modification file (for example, -f \temp\myldif.ldif), trust store file (for example, -P \certs\cert.db), and the keystore file (for example, -K \security\key.db):

$ ldapmodify -h hostname -p 1636 -f /home/local/myldif.ldif \
-Z -P /home/scarter/security/cert.db -N "sccert" \
-K /home/scarter/security/key.db -W keypassword

A.4.3.10 Exit Codes

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

A.4.3.11 Using a CLI Properties File

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

The following options can be stored in a properties file:

  • assertionFilter

  • bindDN

  • bindPassword

  • bindPasswordFile

  • certNickname

  • continueOnError

  • control

  • dry-run

  • filename

  • hostname

  • keyStorePassword

  • keyStorePasswordFile

  • keyStorePath

  • ldapVersion

  • port

  • postReadAttributes

  • preReadAttributes

  • proxyAs

  • reportAuthzID

  • saslOption

    SASL is not supported for a proxy server instance.

  • trustAll

  • trustStorePassword

  • trustStorePasswordFile

  • trustStorePath

  • useSASLExternal

    SASL is not supported for a proxy server instance.

  • useSSL

  • useStartTLS

  • verbose

Entries in the properties file have the following format:

toolname.propertyname=propertyvalue

For example:

ldapmodify.ldapport=12345

A.4.3.12 Location

  • UNIX and Linux: INSTANCE_DIR/OUD/bin/ldapmodify

  • Windows: INSTANCE_DIR\OUD\bat\ldapmodify.bat

A.4.4 ldappasswordmodify

The ldappasswordmodify command modifies LDAP passwords.

A.4.4.1 Synopsis

ldappasswordmodify options

A.4.4.2 Description

The ldappasswordmodify command can be used to change or reset user passwords with the LDAP password modify extended operation as defined in RFC 3062 (http://www.ietf.org/rfc/rfc3062.txt).

Using this mechanism for changing user passwords offers several benefits over a simple LDAP modify operation targeted at the password attribute, including the following:

  • Changing one's own password. The command allows users to change their own password even after it has expired, if this capability is allowed in their 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 if this capability is allowed in their 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. Do not use this option with the --provideDNForAuthzID option.

-A, --provideDNForAuthzID

Indicate that the bind DN should be used as the authorization ID for the password modify operation. Do not use this option with the --authzID option.

-c, --currentPassword currentPassword

Specify the current password for the user. Do not use 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. Do not use 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. Use this form only if the value can be expressed as a string. Do not use 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. Do not use this subcommand 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. Do not use 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. Do not use this option with --newPasswordFile. If neither of these options is provided, then the server will automatically generate a new password for the user if 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. Do not use this option with --newPassword. If neither of these options is provided, then the server automatically generates a new password for the user, if 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. Do not use this option 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 26.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. Do not use this option 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 to access its contents (which most trust stores do not require). Do not use this option 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. Do not use this option 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 to access its contents (most trust stores do not require this). Do not use this option 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. Do not use this option 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. Do not use this option 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.

Example A-139 Modifying Your User Password

The following command connects to the host (-h) using port 1389 (-p), specifies the authorization ID uid=abergin (-a) of an administrator, specifies the user's current password file (-C), and changes it with a new one specified in a new password file (-N). For Windows platforms, use the file paths where your current and new passwords exist, respectively. For example, use -C \temp\currentPasswordFile and -N \temp\newPasswordFile.

$ ldappasswordmodify -h hostname -p 1389 \
-a "dn:uid=abergin,ou=People,dc=example,dc=com" \
-C /tmp/currentPasswordFile -N /tmp/newPasswordFile

The LDAP password modify operation was successful

Example A-140 Modifying and Generating a Password for Another User

The following command connects to the host (-h) using port 1389 (-p), specifies the bind DN (-D), specifies the bind password file (-j), and modifies and generates a password for another user (-a) connecting over simple authentication. For Windows platforms, specify the file where the bind password file resides, for example, -j \temp\bindPasswordFile.

$ ldappasswordmodify -h hostname -p 1389 \
-D "cn=Directory Manager" -j /tmp/bindPasswordFile \
-a "dn:uid=abergin,ou=People,dc=example,dc=com"

The LDAP password modify operation was successful
Generated Password:  blb44hjm

Example A-141 Modifying a Password for Another User

The following command connects to the host (-h) using port 1389 (-p), specifies the bind DN (-D), specifies the bind password file (-j), and modifies the password with a new one (-N) for another user (-a) connecting over simple authentication. For Windows platforms, specify the bind password file (for example, -j \temp\bindPasswordFile) and the new password file (for example, -N \temp\newPassword).

$ ldappasswordmodify -h hostname -p 1389 \
-D "cn=Directory Manager" -j /tmp/bindPasswordFile \
-a "dn:uid=abergin,ou=People,dc=example,dc=com" -N /tmp/newPassword

The LDAP password modify operation was successful

A.4.4.9 Exit Codes

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

A.4.4.10 Using a CLI Properties File

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

The following options can be stored in a properties file:

  • authzID

  • bindDN

  • bindPassword

  • bindPasswordFile

  • currentPassword

  • currentPasswordFile

  • control

  • hostname

  • keyStorePassword

  • keyStorePasswordFile

  • keyStorePath

  • newPassword

  • newPasswordFile

  • port

  • provideDNForAuthzID

  • trustAll

  • trustStorePassword

  • trustStorePasswordFile

  • trustStorePath

  • useSSL

  • useStartTLS

Entries in the properties file have the following format:

toolname.propertyname=propertyvalue

For example:

ldappasswordmodify.ldapport=12345

A.4.4.11 Location

  • UNIX and Linux: INSTANCE_DIR/OUD/bin/ldappasswordmodify

  • Windows: INSTANCE_DIR\OUD\bat\ldappasswordmodify.bat

A.4.5 ldapsearch

The ldapsearch command searches directory server entries.

A.4.5.1 Synopsis

ldapsearch [options] [filter] [attributes]

A.4.5.2 Description

The ldapsearch command can be used to enter a search request to the directory server. The command opens a connection to the directory server, binds to it, and returns all entries that meet the search filter and scope requirements starting from the specified base DN. It can also be used to test other components of the directory server, such as authentication, control, and secure communication mechanisms.

If the --filename option is used to specify a file containing one or more search filters, then the search filter should not be included as an option. All trailing options will be interpreted as requested attributes.

If an entry has non-ASCII characters for its name and attributes, such as sn, givenName, uid, and title, the non-ASCII characters returned by running the ldapsearch command are suppressed while printing. You must run the base64 command to decode the Base64-encoded string.

If no specific attributes are requested, then all user attributes (that is, all non-operational attributes) are returned. If one or more attribute names are listed, then only those attributes are included in the entries that are returned.

A.4.5.3 Before You Begin

Many UNIX and Linux operating systems provide an installed version of common LDAP client commands, such as ldapsearch, ldapmodify, and ldapdelete in the /usr/bin directory. You can check if a version is on your system by entering the command: which ldapsearch. If the command returns a value (seen below), you will need to update your $PATH to directory server installation directory or create an alias to the directory server instance.

$ which ldapsearch (Unix/Linux)
/usr/bin/ldapsearch

A.4.5.4 Options

The ldapsearch command accepts an option in either its short form (for example, -b baseDN) or its long form equivalent (for example, --baseDN baseDN).

A.4.5.5 Command Options

-a, --dereferencePolicy dereferencePolicy

Specify the dereference alias policy during a search. Dereference alias allows you to set an entry to point to another object. If this option is not provided, then a default of never will be used. Possible values are the following:

  • always — Dereference aliases both when finding the base DN and when searching below it.

  • find — Dereference alias when finding the base DN.

  • never — Never dereference aliases (default).

  • search — Dereference aliases when searching below the base DN but not when finding the base DN.

-A, --typesOnly

Perform a search to include attribute names in matching entries but not the attribute values. If this option is not provided, then both attribute names and values will be included in the matching entries.

--assertionFilter filter

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 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. Use this form only if the value can be expressed as a string. Do not use 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. Do not use this subcommand 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. Do not use 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:

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:

The directory server can enforce a lower size limit than the one that is 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. Do not use this option 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 26.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. Do not use this option 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 you use this option, then you must also provide the --keyStorePath option to specify the path to the client keystore and you must use either the --useSSL or the --useStartTLS option 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 to access its contents (which most trust stores do not require). Do not use this option 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. Do not use this option 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. Use this option to obtain information about any warnings or errors regarding 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 to access its contents (most trust stores do not require this). Do not use this option 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. Do not use this option 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. Do not use this option 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 use the --port option 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 18.4, "Searching Directory Data."

Example A-142 Returning All Entries

The following command returns all entries on the directory server. The command connects to the default port 1389 (-p) on the host (-h), specifies the base DN as example.com (-b), and returns all entries by using the search filter (objectclass=*). Because the scope (-s) is not specified, the scope is set to the default value of sub, the full subtree of the base DN. Because no attributes are specified, the command returns all attributes and values.

$ ldapsearch -h hostname -p 1389 -b dc=example,dc=com "(objectclass=*)"

dn: dc=example,dc=com
objectClass: domain
objectClass: top
dc: example

dn: ou=Groups,dc=example,dc=com
objectClass: organizationalunit
objectClass: top
ou: Groups

dn: cn=Directory Administrators,ou=Groups,dc=example,dc=com
objectClass: groupofuniquenames
objectClass: top
ou: Groups
cn: Directory Administrators
uniquemember: uid=kvaughan, ou=People, dc=example,dc=com
uniquemember: uid=rdaugherty, ou=People, dc=example,dc=com
uniquemember: uid=hmiller, ou=People, dc=example,dc=com

Example A-143 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-144 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-145 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-146 Searching by Using Server Authentication

The following command uses the SSL option to run a search with server authentication. The command specifies the host name (-h), SSL port 1636 (-p), base DN (-b), the bind DN (-D), the bind password (-w), trust store file path (-P), and the entity's given name. For Windows platforms, specify the paths for trust store file (for example, -P \certs\cert.db).

$ ldapsearch -h hostname -p 1636 -b "dc=example,dc=com" \
-D "uid=scarter,ou=people,dc=example,dc=com" -w bindPassword \
-P /home/scarter/certs/cert.db "(givenname=Sam)"

Example A-147 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-148 Returning the Effective Rights of a User

The following command returns the effective rights granted to a user, in addition to the user's attribute entries. Only a directory administrator can access this information for another user. The command specifies the host name (-h), port 1389 (-p), bindDN (-D), bindDN password (-w), base DN (-b), control spec option that includes the OID name effectiverights (alternately, you can enter the OID equivalent: 1.3.6.1.4.1.42.2.27.9.5.2), search filter objectclass=*, and the aclRights attribute.

$ ldapsearch -h hostname -p 1389 -D "cn=Directory Manager" -j pwd-file \
-b dc=example,dc=com -J "1.3.6.1.4.1.42.2.27.9.5.2"  "(objectclass=*)" \
aclRights

dn: dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0

dn: ou=Groups, dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0

dn: ou=People, dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0

dn: cn=Accounting Managers,ou=groups,dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0

dn: cn=HR Managers,ou=groups,dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0

dn: uid=bjensen,ou=People, dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0

dn: uid=cfuente, ou=People, dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:1,proxy:0

Example A-149 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-150 Performing a Persistent Search

The ldapsearch command provides an option to run a persistent search (-C) that keeps the connection open and displays the entries that matching the scope and filter whenever any changes (add, delete, mod, or all) occur. The command connects to the port 1389 (-p), sets the scope of the search to base (-s), and matches all entries by using the search filter (objectclass=\*). You can quit out of the search by pressing Control-C.

$ ldapsearch -b dc=example,dc=com -p 1389 -D "cn=Directory Manager" \
-j pwd-file -C ps:add:true:true "(objectclass=*)"

Example A-151 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-152 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-153 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
bindPassword=password
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. However, even if this is specified, there might be some operational attributes that are not returned automatically for some reason, such as 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