3 Oracle Internet Directory Data Management Tools

This chapter describes the following command-line tools used to administer the entries and data stored in Oracle Internet Directory:

3.1 bulkdelete

The bulkdelete command-line tool enables you to delete one or more subtrees efficiently. It can be used when both an Oracle Internet Directory server and Oracle Directory Replication servers are in operation. It uses a SQL interface to benefit performance. For this release, the bulkdelete tool runs on only one node at a time.

This tool does not support filter-based deletion. That is, it deletes an entire subtree below the root of the subtree. If the base DN is a user-added DN, rather than a DN created as part of the installation of the directory, it is included in the delete. You must restrict LDAP activity against the subtree during deletion.

Note:

The bulkdelete command requires that the environment variable ORACLE_INSTANCE be set.

3.1.1 Syntax for bulkdelete

bulkdelete connect=connect_string {[basedn=Base_DN]|[file=file_name]}
[cleandb="TRUE"|"FALSE"] [size=transaction_size] [encode=character_set]
[debug="TRUE"|"FALSE"] [threads=num_of_threads] [verbose="TRUE"|"FALSE"]

3.1.2 Arguments for bulkdelete

connect

Required. The directory database connect string. If you already have a tnsnames.ora file configured, then this is the net service name specified in that file, which is located by default in ORACLE_INSTANCE/config. (You can set the TNS_ADMIN environment variable if you want to use a different location.)

basedn | file

Required. The base DN of the subtree to be deleted, for example, "dc=company, dc=com". Enclose the DN in quotation marks. You can also specify multiple base DNs by putting them in a file and specifying the file name and path with the file argument.

cleandb

Optional. This is used to specify whether the deleted entries would be tomb stoned or deleted completely from the database. The default (cleandb="TRUE") is to delete the entries completely.

size

Optional. The number of entries to be committed as a part of one transaction.

encode

Optional. The native character set encoding. Defaults to the character set of the user's terminal. Each supported character set has a unique acronym, for example, WE8MSWIN1252, JA16SJIS, or AL32UTF8.

debug

Optional. The debug option reports the logging level. This is useful in case the command runs into errors. The output is logged to the bulkdelete.log file. This file can be found under ORACLE_INSTANCE/diagnostics/logs/OID/tools.

threads

Optional. The number of threads to create. The default value is the number of CPUs on the machine plus one.

verbose

Optional. This is used to run the command in verbose mode.

3.1.3 Tasks and Examples for bulkdelete

The following examples show how to delete one or more subtrees from the directory:

3.1.3.1 Deleting All Entries in a Naming Context and Making Them Tombstone Entries

Example:

bulkdelete connect="dbs1" basedn="cn=OracleContext" cleandb="FALSE"

3.1.3.2 Completely Deleting All Entries in a Naming Context

Example:

bulkdelete connect="dbs1" basedn="cn=OracleContext"

3.1.3.3 Deleting Entries in Multiple Naming Contexts

This example uses a file that contains a list of DNs to delete.

Example:

bulkdelete connect="dbs1" file="~/myfiles/dn.txt"

3.1.4 Related Command-Line Tools for bulkdelete

3.2 bulkload

The bulkload command-line tool is useful for loading large number of entries into a directory server. It uses Oracle SQL*Loader to load the directory entries. The bulkload tool expects the input file to be in LDAP Data Interchange Format (LDIF). See Appendix A, "LDIF File Format" for the correct format and syntax of an LDIF file.

Intermediate files used by bulkload are stored in ORACLE_INSTANCE/OID/load by default.

Note:

The bulkload command requires that the environment variable ORACLE_INSTANCE be set.

Using bulkload with Replication

When you add data to a node that is part of a Directory Replication Group (DRG), you can use either bulk tools or LDAP tools, depending on the circumstances. The following rules apply:

  • When you add new entries to all nodes in the DRG, you can use either bulk tools or LDAP tools. For more than 20K entries, bulk tools are significantly faster. If you use LDAP tools, add the entries to only one node in the DRG and let replication propagate the entries. If you use bulk tools, generate the intermediate file only once from the LDIF file and use that intermediate file to load the entries onto all the nodes in the DRG.

  • When you copy existing entries from one node to another in the same replication group, use bulk tools. Use the bulkload option restore=true when you upload the data.

  • If the LDIF file contains operational attributes, which it does when created with ldifwrite, use bulkload to add the entries.

  • If the replication agreement is a partial replication agreement, use ldifwrite with the base DN as the replication agreement DN to write the entries to the LDIF file. Then use bulkload with the restore=true option to load the data.

Overview of the Bulk Loading Tool Operations

The Bulk Loading Tool performs its operations in the following phases:

  1. Check

    In the check phase, all entries of LDIF files are verified for valid LDAP schema and duplicate entries. The Bulk Loading Tool reports any errors, which must be corrected before proceeding.

  2. Generate

    In the generate phase, the LDIF input is converted into intermediate files that can be used by SQL*Loader to load the data into the Oracle Internet Directory directory store.

  3. Load

    The Intermediate files generated in generate phase are loaded into the Oracle Internet Directory directory store. The Bulk Loading Tool supports two types of loading of data:

    • Incremental Mode Loading

      Incremental mode enables you to append data to existing directory data. Loading in this mode is faster than other add methods, but slower than bulk mode loading.

      Use this mode when you want to append a small amount of data. Here, small amount is a relative number. It depends upon existing data in directory, the amount of data to be loaded, and the hardware capabilities to handle the load.

      In this mode, the Bulk Loading Tool does not drop and rebuild catalog indexes. Instead, it uses SQL*Loader in insert mode to add data to the database and update indexes through inserts.

    • Bulk Mode Loading

      In bulk mode, you must be able to add or append large number of entries to a directory. By default, the Bulk Loading Tool runs in bulk mode. Bulk mode is faster than incremental mode.

      In bulk mode, all Oracle Internet Directory server instances should be stopped. In this mode, the Bulk Loading Tool drops existing indexes and re-creates them after loading of data. For data loading, it uses SQL*Loader direct-path mode.

      Notes:

      • Running the bulkload -load operation sets the server mode to read-write. If you require a different mode, reset it after performing the load operation.

      • At the start of the load operation, bulkload determines the current configured value of orclRIenabled, then disables referential integrity. At the end of load phase, bulkload returns orclRIenabled to its original value. If is any referential integrity violations occurred, however, referential integrity is disabled, and you see the message:

        There is a violation of Referential Integrity and hence it is Disabled now. Run the OIDDIAG tool with diagnostic option to collect the Entries which have dangling DN attribute values and Fix the violation
        

        Fix the violation and then set orclRIenabled to the desired value.

  4. Index Creation

    After the load is complete, the indexes are re-created if the load was done in bulk mode. Also, the Bulk Loading Tool provides an option just to re-create all indexes. This is useful in case if previous index creation was unsuccessful for some reason.

  5. Directory Data Recovery

    A failure in the load phase can leave directory data in an inconsistent state. The Bulk Loading Tool can revert back to original state that existed prior to the invocation of bulkload.

Before Using the bulkload Tool

Before running the bulkload tool:

  1. Stop your Oracle Internet Directory server instance(s) before loading data in bulk mode.

  2. Take a cold backup of the Oracle Internet Directory database.

  3. If loading data in incremental mode, you do not need to stop the directory server, although you must put the directory server in read-modify mode. Read-modify mode restricts add, delete, and modify DN operations.

  4. If loading an LDIF file with data from an older version of Oracle Internet Directory, see the Oracle Fusion Middleware Upgrade Planning Guide for any special instructions about upgrading orclguids before you begin.

3.2.1 Syntax for bulkload

bulkload [connect=connect_string]
{[check="TRUE"|"FALSE"  [file=ldif_file]] [generate="TRUE"|"FALSE"
[append="TRUE"|"FALSE"] [restore="TRUE"|"FALSE"] [thread=num_of_threads]
file=ldif_file]
[load="TRUE"|"FALSE"  [append="TRUE"|"FALSE"] [threads=num_of_threads]]
[index="TRUE"|"FALSE"] [missing="TRUE"|"FALSE"] [recover="TRUE"|"FALSE"]}
[encode=character_set] [debug="TRUE"|"FALSE"] [verbose="TRUE"|"FALSE"]

3.2.2 Arguments for bulkload

connect

Optional. The directory database connect string. If you already have a tnsnames.ora file configured, then this is the net service name specified in that file, which is located by default in ORACLE_INSTANCE/config. (You can set the TNS_ADMIN environment variable if you want to use a different location.) For loading data in single node, specify its connect string—for example orcl. For loading data in multiple nodes, specify connect strings of all nodes—for example:

bulkload connect="orcl1,orcl2,orcl3"

check | generate | load | recover | index | missing

Required. The operation to perform. The operations are:

  • check - Checks the LDIF file provided for schema inconsistencies and for duplicate entry DNs. You must provide the full path or relative path and file name of an LDIF file. You can optionally specify the number of threads. The check and generate operations can be issued at the same time.

  • generate - Creates intermediate files suitable for loading entries into Oracle Internet Directory using SQL*Loader. You must provide the full path or relative path and file name of an LDIF file from which to generate entries. You can optionally specify the number of threads. The check and generate operations can be issued at the same time.

    Note:

    • After the generate operation, the directory is left in the read-modify mode until you perform the load operation.

    • bulkload updates the mode to read-only when performing a load operation.

  • load - Loads the files generated in the generate operation into the database. You can use the append option to specify if the data needs to be appended to the existing directory data. For load to succeed, the LDAP server must be stopped. You can optionally specify the number of threads. If you set the ldplonly option to "TRUE", then the data is loaded in parallel but index creation takes place in serial mode. You must run a generate operation before a load operation.

  • recover - In case of a failure during a load operation, recovers the directory with the original data. You cannot use any other option when using the recover option.

  • index - Recreates indexes on all catalog tables.

  • missing - Creates only missing indexes on catalog tables.

file

Required for the check and generate operations. The fully qualified path or relative path and file name of the LDIF file that contains the entries you want to load.

threads

Optional for the check,generate, and load operations. The number of threads to create. The default value is the number of CPUs on the machine plus one.

restore

Optional with the check and generate operations. Assumes operational attributes, such as orclguid, creatorsname, and createtimestamp, are already present in the specified LDIF file. Duplicate operational attribute values are not created in the output SQL*Loader files.

When the restore option is set to TRUE, then the operational attributes specified in the LDIF file are honored. If restore option is not specified or it is set to FALSE, then the operational attributes might not be retained, depending on the type of attribute. Best practice is to avoid having operational attributes in the LDIF file when the restore option value is FALSE.

append

Optional with the generate and load operations. Loads entries in incremental mode rather than bulk mode, which is the default. Incremental mode appends data to existing directory data, and is intended for loading small amounts of data.

encode

Optional. The native character set encoding. Defaults to the character set of the user's terminal. Each supported character set has a unique acronym, for example, WE8MSWIN1252, JA16SJIS, or AL32UTF8.

debug

Optional. The debug option turns debugging on or off. Turning debugging on (debug="TRUE") is useful when the command runs into errors. The output is logged to the bulkload.log file. This file can be found under ORACLE_INSTANCE/diagnostics/logs/OID/tools.

verbose

This is used to run the command in verbose mode.

3.2.3 Tasks and Examples for bulkload

Using the bulkload tool, you can perform the following tasks:

3.2.3.1 Loading Data in Bulk Mode

The typical usage scenario is to load directory data after Oracle Internet Directory installation. First check the LDIF file for schema errors and generate the intermediate files. Next, load the data into the Oracle Internet Directory store.

The following example shows how to run the bulkload tool. The tool is first run with the check and generate options. The check option checks the input for schema and data consistency violations. The generate option generates the input files for SQL*Loader. Next, the command is run with the load option to load the data into the directory.

Example:

bulkload connect="orcl" check="TRUE" generate="TRUE" file="~/myfiles/data.ldif"
bulkload connect="orcl" load="TRUE"

3.2.3.2 Loading Data for Multiple Nodes in a Replicated Environment

When you load the same data into multiple nodes in a replicated network, ensure that the orclGUID parameter (global ID) is consistent across all the nodes. You can accomplish this by generating the bulk load data file once only (using the generate argument), and then using the same data file to load the other nodes (using the load argument).

3.2.3.3 Loading Data in Incremental Mode

If you must add directory entries to an Oracle Internet Directory store already containing some user LDIF data, use the append argument to denote incremental mode. This mode is normally faster than other methods of adding entries to the directory. However, be sure that the directory server instances are in read-modify mode before you begin. The following example shows how to run bulkload in incremental mode.

Example:

bulkload connect="orcl" check="TRUE" generate="TRUE" load="TRUE" append="TRUE" file="~/myfiles/data.ldif"

3.2.3.4 Verifying Indexes

You can verify existing indexes in the directory using the check option along with the index option.

Example:

bulkload connect="orcl" check="TRUE" index="TRUE"

3.2.3.5 Recreating Indexes

The load operation either updates or creates the indexes. However, due to issues like improper sizing, the indexes may not be updated or created properly. For this reason, the bulkload tool enables you to re-create all the indexes.

Example:

bulkload connect="orcl" index="TRUE"

3.2.3.6 Recovering Data After a Load Error

Due to issues like improper disk sizing, the load operation may fail. If this happens, then directory data can be inconsistent. For this reason, bulkload enables you to recover the directory data to the state that existed prior to the invocation of bulkload.

Example:

bulkload connect="orcl" recover="TRUE"

3.2.4 Related Command-Line Tools for bulkload

3.3 bulkmodify

The bulkmodify command-line tool enables you to modify a large number of existing entries in an efficient way.

Note:

The bulkmodify command requires that the environment variable ORACLE_INSTANCE be set.

The bulkmodify tool supports the following:

  • Subtree based modification

  • LDAP search filter. For example, the filter could be objectclass=*, objectclass=oneclass, or '(&(sn=Baileys)(cn=Kalid Baileys))'.

  • Attribute value addition and replacement. It modifies all matched entries in bulk.

The bulkmodify tool performs schema checking on the specified attribute name and value pair during initialization. All entries that meet the following criteria are modified:

  • They are under the specified subtree.

  • They meet the LDAP filter condition.

  • They contain the attribute to be modified as either mandatory or optional.

The directory server and directory replication server may be running concurrently while bulk modification is in progress, but the bulk modification does not affect the replication server. You must perform bulk modification against all replicas.

Note:

LDIF file based modification is not supported by bulkmodify. This type of modification requires per-entry-based schema checking, and therefore the performance gain over the existing ldapmodify tool is insignificant.

Make sure that when bulkmodify is invoked, server side entry cache is disabled.

You must restrict user access to the subtree during bulk modification. If necessary, access control item (ACI) restriction can be applied to the subtree being updated by bulkmodify.

You cannot use bulkmodify to add a value to single-valued attributes that already contain one value. If a second value is added, you must alter the directory schema to make that attribute multi-valued.

You cannot use bulkmodify to update the following attributes:

3.3.1 Syntax for bulkmodify

bulkmodify connect=connect_string basedn=Base_DN
{[add="TRUE"|"FALSE"]|[replace="TRUE"|"FALSE"]} attribute=attribute_name
value=attribute_value [filter=filter_string] [size=transaction_size]
[threads=num_of_threads] [debug="TRUE"|"FALSE"] [encode=character_set]
[verbose="TRUE"|"FALSE"]

3.3.2 Arguments for bulkmodify

connect

Required. The directory database connect string. If you already have a tnsnames.ora file configured, then this is the net service name specified in that file, which is located by default in ORACLE_INSTANCE/config. (You can set the TNS_ADMIN environment variable if you want to use a different location.)

basedn

Required. The DN of the subtree to be modified. Enclose the DN in quotes.

add | replace

Required. The operation to be performed on the attribute. Specifies whether you want to add an attribute value or replace an attribute value.

attribute

Required. The name of a single attribute for which a value needs to be added or replaced.

value

Required. The single attribute value to add or replace. If the value contains spaces, enclose it in quotes.

filter

Optional. A filter string that contains a single attribute. Defaults to objectclass=*.

size

Optional. The number of entries to be committed as part of one transaction. Defaults to 100.

threads

Optional. The number of threads to create. The default value is the number of CPUs on the machine plus one.

debug

Optional. The debug option reports the logging level. This is useful in case the command runs into errors. The output is logged to the bulkmodify.log file. This file can be found under ORACLE_INSTANCE/diagnostics/logs/OID/tools.

encode

Optional. The native character set encoding. Defaults to the character set of the user's terminal. Each supported character set has a unique acronym, for example, WE8MSWIN1252, JA16SJIS, or AL32UTF8.

verbose

This is used to run the command in verbose mode.

3.3.3 Tasks and Examples for bulkmodify

Using the bulkmodify tool, you can perform the following task:

3.3.3.1 Updating an Attribute for Multiple Entries at Once

The following example shows how to modify an attribute for several entries using a filter. This command adds the telephone number 408-123-4567 to the entries of all employees who have Anne Smith as their manager.

Example:

bulkmodify connect="orcl" basedn="c=US" add="TRUE" attribute="telephoneNumber" value="408-123-4567" filter="manager=Anne Smith"

3.3.4 Limitations of bulkmodify

bulkmodify has the following limitations:

  • bulkmodify does not distinguish between attributes with or without subtypes, when performing the replace operation. bulkmodify replaces the attribute value irrespective of whether the attribute contains subtypes.

  • bulkmodify allows the RDN to be modified without modifying the DN. If an attribute is part of a DN, then the attribute value is modified but the DN entry in the directory is not modified.

  • bulkmodify does not perform an object class check when performing an add operation. When adding a new attribute to a directory entry, bulkmodify does not verify if the entry has the required object class to support the attribute.

3.3.5 Related Command-Line Tools for bulkmodify

3.4 catalog

Oracle Internet Directory uses indexes to make attributes available for searches. When Oracle Internet Directory is installed, the cn=catalogs entry lists available attributes that can be used in a search. You can index only those attributes that have:

  • An equality matching rule

  • Matching rules supported by Oracle Internet Directory (see "Matching Rules")

If you want to use additional attributes in search filters, then you must add them to the catalog entry. You can do this at the time you create the attribute by using Oracle Directory Services Manager. However, if the attribute already exists, then you can index it only by using the Catalog Management Tool (catalog).

Note:

The catalog command requires that the environment variable ORACLE_INSTANCE be set.

Before running catalog, be sure that the directory server is either stopped or in read-only mode.

Caution:

Do not use the catalog delete="TRUE" argument on indexes created by the Oracle Internet Directory base schema. Removing indexes from base schema attributes can adversely impact the operation of Oracle Internet Directory.

3.4.1 Syntax for catalog

catalog connect=connect_string {[add="TRUE"|"FALSE"]|[delete="TRUE"|"FALSE"]}
{[attribute=attribute_name]|[file=file_name]} [logging="TRUE"|"FALSE"]
[threads=num_of_threads] [debug="TRUE"|"FALSE"] [verbose="TRUE"|"FALSE"]

3.4.2 Arguments for catalog

connect

Required. The directory database connect string. If you already have a tnsnames.ora file configured, then this is the net service name specified in that file, which is located by default in ORACLE_INSTANCE/config. (You can set the TNS_ADMIN environment variable if you want to use a different location.)

add | delete

Required. The operation to perform. The add argument indexes the specified attribute. The delete argument drops the index for the specified attribute.

attribute | file

Required. The attribute or attributes to catalog. Use the attribute argument to specify a single attribute name on the command-line. Use the file argument to provide the full path and file name of a file that contains a list of several attribute names.

logging

Optional. This option is used to decide if redo logs are generated when a catalog is created.

threads

Optional. The number of threads to create. The default value is the number of CPUs on the machine plus one.

debug

Optional. The debug option reports the logging level. This is useful in case the command runs into errors. The output is logged to the catalog.log file. This file can be found under ORACLE_INSTANCE/diagnostics/logs/OID/tools.

verbose

Optional. This option specifies whether the command should be run in verbose mode.

3.4.3 Tasks and Examples for catalog

Using the catalog tool, you can perform the following tasks:

3.4.3.1 Indexing a Single Attribute

The following example shows how to index a single attribute. The catalog tool prompts you for the Oracle Internet Directory superuser password.

Example:

catalog connect="orcl" add="TRUE" attribute="orclGender"

3.4.3.2 Indexing Multiple Attributes

The following example shows how to index multiple values at once by supplying a file that contains a list of attribute names. The catalog tool prompts you for the Oracle Internet Directory superuser password.

Example:

catalog connect="orcl" add="TRUE" file="~/myfiles/attrs.txt"

3.4.3.3 Removing an Attribute from the List of Indexed Attributes

The following example shows how to remove a single attribute from the list of indexed attributes. The catalog tool prompts you for the Oracle Internet Directory superuser password.

Example:

catalog connect="orcl" delete="TRUE" attribute="orclGender"

3.4.4 Related Command-Line Tools for catalog

  • N/A

3.5 ldapadd

The ldapadd command-line tool enables you to add entries, their object classes, attributes, and values to the directory. To add attributes to an existing entry, use the ldapmodify command, explained in "ldapmodify".

See Also:

For information on using attribute aliases with ldapadd refer to the "Attribute Aliases In the Directory" section in Oracle Fusion Middleware Administrator's Guide for Oracle Internet Directory

3.5.1 Syntax for ldapadd

ldapadd -h oid_hostname -D "binddn" -q | -w password [-Y "proxy_dn"] 
[-p ldap_port]  [-V ldap_version] {-f ldif_filename | -X dsml_filename} 
[-b] [-n] [-c [-o log_file_name]] [-M] [-v] [-O ref_hop_limit] [-i 1|0] 
[-k|-K] [-U SSL_auth_mode {-W wallet_location -Q | -P wallet_password}] 
[-d debug_level] [-E character_set]

3.5.2 Arguments for ldapadd

-h oid_hostname

Required. The host name or IP address of the Oracle Internet Directory server.

-D "binddn"

Required. The DN of the Oracle Internet Directory user needed to bind to the directory (for example, cn=orcladmin).

-q

Required unless -w is used. Causes the command to prompt for the user password needed to bind to the directory. A password supplied at the command prompt is not visible on the screen.

-w password

Required unless -q is used. The user password needed to bind to the directory. Avoid supplying a password on the command line whenever possible. A password typed on the command line is visible on your screen. The -w password option is disabled when LDAP_PASSWORD_PROMPTONLY is set to true. See "Using Passwords with Command-Line Tools".

-Y "proxy_dn"

Optional. The DN of a proxy user. After binding to the directory, the add operation is performed as this user.

-p ldap_port

Optional. The port number used to connect to the Oracle Internet Directory server. Defaults to port 3060.

-V ldap_version

Optional. The version of the LDAP protocol to use. Allowed values are 2 or 3. Defaults to 3 (LDAP v3).

-f ldif_filename | -X dsml_filename

Required. The full path and file name of the input file that contains the data you want to import.

Use the -f argument to supply an LDIF file. See Appendix A, "LDIF File Format" for information on formatting an LDIF file.

Use the -X argument to supply a Directory Service Markup Language (DSML) file. See "Adding Data to the Directory Using a DSML File" for more information about formatting a DSML file.

-b

Optional. Use this option if your input file has binary file names in it, which are preceded by the forward slash character. The tool retrieves the actual values from the file referenced.

-n

Optional. Enables you to preview what would occur in an operation without actually performing the operation.

-c

Optional. Proceeds in spite of errors. All errors are reported. If the -c argument is not used, the tool stops when an error occurs.

-o log_file_name

Optional. Used with the -c argument. Writes the LDIF entries with errors to a log file. Specify the full path and name of the log file.

-M

Optional. Instructs the tool to send the ManageDSAIT control to the server. The ManageDSAIT control instructs the server not to send referrals to clients. Instead a referral entry is returned as a regular entry.

-v

Optional. Runs the tool in verbose mode.

-O ref_hop_limit

Optional. The number of referral hops that a client should process. Defaults to 5.

-i 1 | 0

Optional. Specifies whether to bind as the current user when following referrals. 1 means bind as the current user, 0 means bind anonymously. The default is 0 (zero).

-k | -K

Optional. The -k argument authenticates using Kerberos authentication instead of simple authentication. To enable this option, you must compile with KERBEROS defined.You must already have a valid ticket granting ticket. Use the -K argument if you want to only perform the first step of the Kerberos bind.

-U SSL_auth_mode

Optional. The SSL authentication mode:

  • 1 for no authentication required.

  • 2 for one way authentication required. You must also supply a wallet location and wallet password.

  • 3 for two way authentication required. You must also supply a wallet location and wallet password.

-W wallet_location

Required if using one way or two way SSL authentication (-U 2|3). The location of the wallet file that contains the server's SSL certificates.

Example for UNIX:

-W "file:/home/my_dir/my_wallet"

Example for Microsoft Windows:

-W "file:C:\my_dir\my_wallet"

-Q

Required, unless -P is used, if using one way or two way SSL authentication (-U 2|3). Causes the command to prompt for the wallet password for the wallet specified in the -W argument. A password supplied at the command prompt is not visible on the screen.

-P wallet_password

Required, unless -Q is used, if using one way or two way SSL authentication (-U 2|3). The wallet password for the wallet specified in the -W argument. Avoid supplying a password on the command line whenever possible. A password typed on the command line is visible on your screen. The -P wallet_password option is disabled when LDAP_PASSWORD_PROMPTONLY is set to true. See "Using Passwords with Command-Line Tools".

-d debug_level

Optional. If not specified the default of 0 (not enabled) is used. Debug levels are additive. Add the numbers representing the functions that you want to activate, and use the sum of those in the command-line option. For example, to trace search filter processing (512) and active connection management (256), enter 768 as the debug level (512 + 256 = 768). Debug levels are as follows:

  • 1 — Heavy trace debugging

  • 128 — Debug packet handling

  • 256 — Connection management, related to network activities

  • 512 — Search filter processing

  • 1024 — Entry parsing

  • 2048 — Configuration file processing

  • 8192 — Access control list processing

  • 491520 — Log of communication with the database

  • 524288 — Schema related operations

  • 4194304 — Replication specific operations

  • 8388608 — Log of entries, operations and results for each connection

  • 16777216 — Trace function call arguments

  • 67108864 — Number and identity of clients connected to this server

  • 117440511 — All possible operations and data

-E character_set

Optional. The native character set encoding. Defaults to the character set of the user's terminal. Each supported character set has a unique acronym, for example, WE8MSWIN1252, JA16SJIS, or AL32UTF8.

3.5.3 Tasks and Examples for ldapadd

Using the ldapadd tool, you can perform the following tasks:

3.5.3.1 Adding Data to the Directory Using an LDIF File

You can use ldapadd to add entries or schema information to the directory from an LDIF file. The file must be correctly formatted. See Appendix A, "LDIF File Format" for information about formatting an LDIF file.

Example:

ldapadd -h myhost.company.com -D "cn=orcladmin" -q -p 3060 \
   -f ~/myfiles/input.ldif -v

3.5.3.2 Adding Data to the Directory Using a DSML File

You can use ldapadd to add entries or schema information to the directory from a Directory Service Markup Language (DSML) file that contains <addRequest> elements. For more information about the formatting DSML files, visit the OASIS Web site at http://www.oasis-open.org. The following example shows a sample DSML entry for a user.

Example:

<addRequest dn="CN=Alice,OU=HR,DC=Example,DC=COM">
     <attr name="objectclass"><value>top</value></attr>
     <attr name="objectclass"><value>person</value></attr>
     <attr name="objectclass"><value>organizationalPerson</value></attr>
     <attr name="sn"><value>Johnson</value></attr>
     <attr name="givenName"><value>Alice</value></attr>
     <attr name="title"><value>Software Design Engineer</value></attr>
</addRequest>

Once you have a correctly formatted DSML file, you can add data to the directory using ldapadd and supplying the DSML file as the input file.

Example:

ldapadd -h myhost.company.com -D "cn=orcladmin" -q -p 3060 \
    -X ~/myfiles/input.xml -v

3.5.3.3 Previewing an Add Operation

Use the -n argument with an ldapadd command to preview the results of an add operation before actually adding any data to the directory.

Example:

ldapadd -h myhost.company.com -D "cn=orcladmin" -q -p 3060 \
    -X ~/myfiles/input.xml -v -n

3.5.4 Related Command-Line Tools for ldapadd

3.6 ldapaddmt

The ldapaddmt tool performs the same functionality as the ldapadd command. It enables you to add entries, their object classes, attributes, and values to the directory. However, it also supports multiple threads for adding entries concurrently.

While it is processing entries, ldapaddmt logs errors in the add.log file within the current directory.

Note:

Increasing the number of concurrent threads improves the rate at which entries are created, but consumes more system resources.

3.6.1 Syntax for ldapaddmt

ldapaddmt -h oid_hostname -D "binddn" -q | -w password -T number_threads 
[-p ldap_port] [-V ldap_version] {-f ldif_filename | -X dsml_filename}  [-b] [-c]
[-M] [-O ref_hop_limit] [-k|-K] [-U SSL_auth_mode {-W wallet_location -Q | -P
wallet_password}] [-d debug_level] [-E character_set]

3.6.2 Arguments for ldapaddmt

-h oid_hostname

Required. The host name or IP address of the Oracle Internet Directory server.

-D "binddn"

Required. The DN of the Oracle Internet Directory user needed to bind to the directory (for example, cn=orcladmin).

-q

Required unless -w is used. Causes the command to prompt for the user password needed to bind to the directory. A password supplied at the command prompt is not visible on the screen.

-w password

Required unless -q is used. The user password needed to bind to the directory. Avoid supplying a password on the command line whenever possible. A password typed on the command line is visible on your screen. The -w password option is disabled when LDAP_PASSWORD_PROMPTONLY is set to true. See "Using Passwords with Command-Line Tools".

-T number_threads

Required. The number of threads for concurrently processing entries.

-p ldap_port

Optional. The port number used to connect to the Oracle Internet Directory server. Defaults to port 3060.

-V ldap_version

Optional. The version of the LDAP protocol to use. Allowed values are 2 or 3. Defaults to 3 (LDAP v3).

-f ldif_filename | -X dsml_filename

Required. The full path and file name of the input file that contains the data you want to import.

Use the -f argument to supply an LDIF file. See Appendix A, "LDIF File Format" for information on formatting an LDIF file.

Use the -X argument to supply a Directory Service Markup Language (DSML) file. See "Adding Data to the Directory Using a DSML File" for more information about formatting a DSML file.

-b

Optional. Use this option if your input file has binary file names in it, which are preceded by the forward slash character. The tool retrieves the actual values from the file referenced.

-c

Optional. Proceeds in spite of errors. All errors are reported. If the -c argument is not used, the tool stops when an error occurs.

-M

Optional. Instructs the tool to send the ManageDSAIT control to the server. The ManageDSAIT control instructs the server not to send referrals to clients. Instead a referral entry is returned as a regular entry.

-O ref_hop_limit

Optional. The number of referral hops that a client should process. Defaults to 5.

-k | -K

Optional. The -k argument authenticates using Kerberos authentication instead of simple authentication. To enable this option, you must compile with KERBEROS defined.You must already have a valid ticket granting ticket. Use the -K argument if you want to only perform the first step of the Kerberos bind.

-U SSL_auth_mode

Optional. The SSL authentication mode:

  • 1 for no authentication required.

  • 2 for one way authentication required. You must also supply a wallet location and wallet password.

  • 3 for two way authentication required. You must also supply a wallet location and wallet password.

-W wallet_location

Required if using one way or two way SSL authentication (-U 2|3). The location of the wallet file that contains the server's SSL certificates.

Example for UNIX:

-W "file:/home/my_dir/my_wallet"

Example for Microsoft Windows:

-W "file:C:\my_dir\my_wallet"

-Q

Required, unless -P is used, if using one way or two way SSL authentication (-U 2|3). Causes the command to prompt for the wallet password for the wallet specified in the -W argument. A password supplied at the command prompt is not visible on the screen.

-P wallet_password

Required, unless -Q is used, if using one way or two way SSL authentication (-U 2|3). The wallet password for the wallet specified in the -W argument. Avoid supplying a password on the command line whenever possible. A password typed on the command line is visible on your screen. The -P wallet_password option is disabled when LDAP_PASSWORD_PROMPTONLY is set to true. See "Using Passwords with Command-Line Tools".

-d debug_level

Optional. If not specified the default of 0 (not enabled) is used. Debug levels are additive. Add the numbers representing the functions that you want to activate, and use the sum of those in the command-line option. For example, to trace search filter processing (512) and active connection management (256), enter 768 as the debug level (512 + 256 = 768). Debug levels are as follows:

  • 1 — Heavy trace debugging

  • 128 — Debug packet handling

  • 256 — Connection management, related to network activities

  • 512 — Search filter processing

  • 1024 — Entry parsing

  • 2048 — Configuration file processing

  • 8192 — Access control list processing

  • 491520 — Log of communication with the database

  • 524288 — Schema related operations

  • 4194304 — Replication specific operations

  • 8388608 — Log of entries, operations and results for each connection

  • 16777216 — Trace function call arguments

  • 67108864 — Number and identity of clients connected to this server

  • 117440511 — All possible operations and data

-E character_set

Optional. The native character set encoding. Defaults to the character set of the user's terminal. Each supported character set has a unique acronym, for example, WE8MSWIN1252, JA16SJIS, or AL32UTF8.

3.6.3 Tasks and Examples for ldapaddmt

Using the ldapaddmt tool, you can perform the following task:

3.6.3.1 Adding Concurrent Entries to the Directory Using an LDIF File

You can use ldapaddmt to add concurrent entries or schema information to the directory from an LDIF file. The file must be correctly formatted. See Appendix A, "LDIF File Format" for information about formatting an LDIF file.

Example:

ldapaddmt -h myhost.company.com -D "cn=orcladmin" -q -T 5 -p 3060 \
    -f ~/myfiles/input.ldif -v

3.6.4 Related Command-Line Tools for ldapaddmt

3.7 ldapbind

The ldapbind command-line tool enables you to see whether you can authenticate a client to a server.

3.7.1 Syntax for ldapbind

ldapbind -h oid_hostname -D "binddn" -q | -w password [-p ldap_port] 
[-V ldap_version] [-n] [-O "auth"] [-Y "DIGEST-MD5|EXTERNAL"] 
[-R SASL_realm] [-U SSL_auth_mode {-W wallet_location -Q | -P wallet_password}]
[-E character_set]

3.7.2 Arguments for ldapbind

-h oid_hostname

Required. The host name or IP address of the Oracle Internet Directory server.

-D "binddn"

Required. The DN of the Oracle Internet Directory user needed to bind to the directory (for example, cn=orcladmin).

-q

Required unless -w is used. Causes the command to prompt for the user password needed to bind to the directory. A password supplied at the command prompt is not visible on the screen.

-w password

Required unless -q is used. The user password needed to bind to the directory. Avoid supplying a password on the command line whenever possible. A password typed on the command line is visible on your screen. The -w password option is disabled when LDAP_PASSWORD_PROMPTONLY is set to true. See "Using Passwords with Command-Line Tools".

-p ldap_port

Optional. The port number used to connect to the Oracle Internet Directory server. Defaults to port 3060.

-V ldap_version

Optional. The version of the LDAP protocol to use. Allowed values are 2 or 3. Defaults to 3 (LDAP v3).

-O "auth"

Optional. Specifies SASL security properties. The security property supported is -O "auth". This security property is for DIGEST-MD5 SASL mechanism. It enables authentication with no data integrity or data privacy.

-Y "DIGEST-MD5 | EXTERNAL"

Optional. Specifies a Simple Authentication and Security Layer (SASL) mechanism. The following mechanisms are supported:

  • DIGEST-MD5

  • EXTERNAL - The SASL authentication in this mechanism is done on top of two-way SSL authentication. In this case the identity of the user stored in the SSL wallet is used for SASL authentication.

-R SASL_realm

Optional. A SASL realm.

-U SSL_auth_mode

Optional. The SSL authentication mode:

  • 1 for no authentication required.

  • 2 for one way authentication required. You must also supply a wallet location and wallet password.

  • 3 for two way authentication required. You must also supply a wallet location and wallet password.

-W wallet_location

Required if using one way or two way SSL authentication (-U 2|3). The location of the wallet file that contains the server's SSL certificates.

Example for UNIX:

-W "file:/home/my_dir/my_wallet"

Example for Microsoft Windows:

-W "file:C:\my_dir\my_wallet"

-Q

Required, unless -P is used, if using one way or two way SSL authentication (-U 2|3). Causes the command to prompt for the wallet password for the wallet specified in the -W argument. A password supplied at the command prompt is not visible on the screen.

-P wallet_password

Required, unless -Q is used, if using one way or two way SSL authentication (-U 2|3). The wallet password for the wallet specified in the -W argument. Avoid supplying a password on the command line whenever possible. A password typed on the command line is visible on your screen. The -P wallet_password option is disabled when LDAP_PASSWORD_PROMPTONLY is set to true. See "Using Passwords with Command-Line Tools".

-E character_set

Optional. The native character set encoding. Defaults to the character set of the user's terminal. Each supported character set has a unique acronym, for example, WE8MSWIN1252, JA16SJIS, or AL32UTF8.

3.7.3 Tasks and Examples for ldapbind

Using the ldapbind tool, you can perform the following task:

3.7.3.1 Validating Authentication Credentials

The following example shows how to validate the authentication credentials used to bind to the directory server when using SSL.

Example:

ldapbind -h myhost.company.com -D "cn-orcladmin" -q -p 3133 \
    -U 2 -W "file:/home/my_dir/my_wallet" -Q

3.7.4 Related Command-Line Tools for ldapbind

  • N/A

3.8 ldapcompare

The ldapcompare command-line tool enables you to compare an attribute value that you specify on the command line to the attribute value in a directory entry.

3.8.1 Syntax for ldapcompare

ldapcompare -h oid_hostname -D "binddn" -q | -w password [-Y "proxy_dn"] 
[-p ldap_port] -a attribute_name -b "base" -v "attribute_value" 
[-U SSL_auth_mode {-W wallet_location -Q | -P wallet_password}] 
[-d debug_level] [-E character_set]

3.8.2 Arguments for ldapcompare

-h oid_hostname

Required. The host name or IP address of the Oracle Internet Directory server.

-D "binddn"

Required. The DN of the Oracle Internet Directory user needed to bind to the directory (for example, cn=orcladmin).

-q

Required unless -w is used. Causes the command to prompt for the user password needed to bind to the directory. A password supplied at the command prompt is not visible on the screen.

-w password

Required unless -q is used. The user password needed to bind to the directory. Avoid supplying a password on the command line whenever possible. A password typed on the command line is visible on your screen. The -w password option is disabled when LDAP_PASSWORD_PROMPTONLY is set to true. See "Using Passwords with Command-Line Tools".

-Y "proxy_dn"

Optional. The DN of a proxy user. After binding to the directory, the add operation is performed as this user.

-p ldap_port

Optional. The port number used to connect to the Oracle Internet Directory server. Defaults to port 3060.

-a attribute_name

Required. The attribute for which to perform the comparison of values.

-b "base"

Required. The DN of the entry for which to perform the comparison.

-v "attribute_value"

Required. The attribute value that you want to compare to the value in the entry.

-U SSL_auth_mode

Optional. The SSL authentication mode:

  • 1 for no authentication required.

  • 2 for one way authentication required. You must also supply a wallet location and wallet password.

  • 3 for two way authentication required. You must also supply a wallet location and wallet password.

-W wallet_location

Required if using one way or two way SSL authentication (-U 2|3). The location of the wallet file that contains the server's SSL certificates.

Example for UNIX:

-W "file:/home/my_dir/my_wallet"

Example for Microsoft Windows:

-W "file:C:\my_dir\my_wallet"

-Q

Required, unless -P is used, if using one way or two way SSL authentication (-U 2|3). Causes the command to prompt for the wallet password for the wallet specified in the -W argument. A password supplied at the command prompt is not visible on the screen.

-P wallet_password

Required, unless -Q is used, if using one way or two way SSL authentication (-U 2|3). The wallet password for the wallet specified in the -W argument. Avoid supplying a password on the command line whenever possible. A password typed on the command line is visible on your screen. The -P wallet_password option is disabled when LDAP_PASSWORD_PROMPTONLY is set to true. See "Using Passwords with Command-Line Tools".

-d debug_level

Optional. If not specified the default of 0 (not enabled) is used. Debug levels are additive. Add the numbers representing the functions that you want to activate, and use the sum of those in the command-line option. For example, to trace search filter processing (512) and active connection management (256), enter 768 as the debug level (512 + 256 = 768). Debug levels are as follows:

  • 1 — Heavy trace debugging

  • 128 — Debug packet handling

  • 256 — Connection management, related to network activities

  • 512 — Search filter processing

  • 1024 — Entry parsing

  • 2048 — Configuration file processing

  • 8192 — Access control list processing

  • 491520 — Log of communication with the database

  • 524288 — Schema related operations

  • 4194304 — Replication specific operations

  • 8388608 — Log of entries, operations and results for each connection

  • 16777216 — Trace function call arguments

  • 67108864 — Number and identity of clients connected to this server

  • 117440511 — All possible operations and data

-E character_set

Optional. The native character set encoding. Defaults to the character set of the user's terminal. Each supported character set has a unique acronym, for example, WE8MSWIN1252, JA16SJIS, or AL32UTF8.

3.8.3 Tasks and Examples for ldapcompare

Using ldapcompare you can perform the following task:

3.8.3.1 Comparing Attribute Values for an Entry

The following example shows how to check an entry for a person named Anne Smith to see if her title is Manager.

Example:

ldapcompare -h myhost.company.com -D "cn=orcladmin" -q -p 3060 -a title \
    -b "cn=Anne Smith,ou=Sales,o=IMC,c=US" -v "Manager"

3.8.4 Related Command-Line Tools for ldapcompare

  • N/A

3.9 ldapdelete

The ldapdelete command-line tool enables you to remove entire entries from the directory.

See Also:

For information on using attribute aliases with ldapdelete refer to the "Attribute Aliases In the Directory" section in Oracle Fusion Middleware Administrator's Guide for Oracle Internet Directory

3.9.1 Syntax for ldapdelete

ldapdelete -h oid_hostname -D "binddn" -q | -w password [-Y proxy_dn] 
[-p ldap_port] [-V ldap_version] {-f ldif_filename | "entry_dn"} 
[-n] [-M] [-v] [-O ref_hop_limit] [-k|-K] 
[-U SSL_auth_mode {-W wallet_location -Q | -P wallet_password}] [-E character_set]

3.9.2 Arguments for ldapdelete

-h oid_hostname

Required. The host name or IP address of the Oracle Internet Directory server.

-D "binddn"

Required. The DN of the Oracle Internet Directory user needed to bind to the directory (for example, cn=orcladmin).

-q

Required unless -w is used. Causes the command to prompt for the user password needed to bind to the directory. A password supplied at the command prompt is not visible on the screen.

-w password

Required unless -q is used. The user password needed to bind to the directory. Avoid supplying a password on the command line whenever possible. A password typed on the command line is visible on your screen. The -w password option is disabled when LDAP_PASSWORD_PROMPTONLY is set to true. See "Using Passwords with Command-Line Tools".

-Y "proxy_dn"

Optional. The DN of a proxy user. After binding to the directory, the add operation is performed as this user.

-p ldap_port

Optional. The port number used to connect to the Oracle Internet Directory server. Defaults to port 3060.

-V ldap_version

Optional. The version of the LDAP protocol to use. Allowed values are 2 or 3. Defaults to 3 (LDAP v3).

-f ldif_filename | "entry_dn"

Required. The full path and file name of the input file that contains the entry DNs you want to delete, or a single entry DN supplied on the command-line.

Use the -f argument to supply an LDIF file. See Appendix A, "LDIF File Format" for information on formatting an LDIF file.

To delete one entry, supply the DN of the entry in quotes.

-n

Optional. Enables you to preview what would occur in an operation without actually performing the operation.

-M

Optional. Instructs the tool to send the ManageDSAIT control to the server. The ManageDSAIT control instructs the server not to send referrals to clients. Instead a referral entry is returned as a regular entry.

-v

Optional. Runs the tool in verbose mode.

-O ref_hop_limit

Optional. The number of referral hops that a client should process. Defaults to 5.

-k | -K

Optional. The -k argument authenticates using Kerberos authentication instead of simple authentication. To enable this option, you must compile with KERBEROS defined.You must already have a valid ticket granting ticket. Use the -K argument if you want to only perform the first step of the Kerberos bind.

-U SSL_auth_mode

Optional. The SSL authentication mode:

  • 1 for no authentication required.

  • 2 for one way authentication required. You must also supply a wallet location and wallet password.

  • 3 for two way authentication required. You must also supply a wallet location and wallet password.

-W wallet_location

Required if using one way or two way SSL authentication (-U 2|3). The location of the wallet file that contains the server's SSL certificates.

Example for UNIX:

-W "file:/home/my_dir/my_wallet"

Example for Microsoft Windows:

-W "file:C:\my_dir\my_wallet"

-Q

Required, unless -P is used, if using one way or two way SSL authentication (-U 2|3). Causes the command to prompt for the wallet password for the wallet specified in the -W argument. A password supplied at the command prompt is not visible on the screen.

-P wallet_password

Required, unless -Q is used, if using one way or two way SSL authentication (-U 2|3). The wallet password for the wallet specified in the -W argument. Avoid supplying a password on the command line whenever possible. A password typed on the command line is visible on your screen. The -P wallet_password option is disabled when LDAP_PASSWORD_PROMPTONLY is set to true. See "Using Passwords with Command-Line Tools".

-E character_set

Optional. The native character set encoding. Defaults to the character set of the user's terminal. Each supported character set has a unique acronym, for example, WE8MSWIN1252, JA16SJIS, or AL32UTF8.

3.9.3 Tasks and Examples for ldapdelete

Using ldapdelete you can perform the following tasks:

3.9.3.1 Deleting a Single Entry

The following example shows how to delete an entry for a person named Anne Smith.

Example:

ldapdelete -h myhost.company.com -D "cn=orcladmin" -q \
   -p 3060 "cn=Anne Smith,ou=Sales,o=IMC,c=US"

3.9.3.2 Deleting Multiple Entries Using an LDIF File

The following example shows how to delete many entries at once by supplying an LDIF file that contains the DNs of the entries to delete. See Appendix A, "LDIF File Format" for information about formatting an LDIF file.

Example:

ldapdelete -h myhost.company.com -D "cn=orcladmin" -q -p 3060 \      -f /home/mydir/delete.ldif

3.9.4 Related Command-Line Tools for ldapdelete

3.10 ldapmoddn

The ldapmoddn command-line tool enables you to change the RDN of an entry, or to move an entry to a new parent node in the directory tree.

See Also:

For information on using attribute aliases with ldapmoddn refer to the "Attribute Aliases In the Directory" section in Oracle Fusion Middleware Administrator's Guide for Oracle Internet Directory

3.10.1 Syntax for ldapmoddn

ldapmoddn -h oid_hostname -D "binddn" -q | -w password [-p ldap_port] 
[-V ldap_version] -b "base_dn" {-R "new_rdn"|-N "new_parent"} 
[-r] [-M] [-O ref_hop_limit] 
[-U SSL_auth_mode {-W wallet_location -Q | -P wallet_password}] [-E character_set]

3.10.2 Arguments for ldapmoddn

-h oid_hostname

Required. The host name or IP address of the Oracle Internet Directory server.

-D "binddn"

Required. The DN of the Oracle Internet Directory user needed to bind to the directory (for example, cn=orcladmin).

-q

Required unless -w is used. Causes the command to prompt for the user password needed to bind to the directory. A password supplied at the command prompt is not visible on the screen.

-w password

Required unless -q is used. The user password needed to bind to the directory. Avoid supplying a password on the command line whenever possible. A password typed on the command line is visible on your screen. The -w password option is disabled when LDAP_PASSWORD_PROMPTONLY is set to true. See "Using Passwords with Command-Line Tools".

-p ldap_port

Optional. The port number used to connect to the Oracle Internet Directory server. Defaults to port 3060.

-V ldap_version

Optional. The version of the LDAP protocol to use. Allowed values are 2 or 3. Defaults to 3 (LDAP v3).

-b "base_dn"

Required. The DN of the entry to be moved to a new parent DN or have its RDN updated.

-R "new_rdn" | -N "new_parent"

Required. The action to perform. Use the -R argument to change the RDN of the entry. Use the -N argument to move the entry to a new parent node in the directory tree.

-r

Optional. Specifies that the old RDN is not retained as a value in the modified entry. If not included, the old RDN is retained as an attribute in the modified entry.

-M

Optional. Instructs the tool to send the ManageDSAIT control to the server. The ManageDSAIT control instructs the server not to send referrals to clients. Instead a referral entry is returned as a regular entry.

-O ref_hop_limit

Optional. The number of referral hops that a client should process. Defaults to 5.

-U SSL_auth_mode

Optional. The SSL authentication mode:

  • 1 for no authentication required.

  • 2 for one way authentication required. You must also supply a wallet location and wallet password.

  • 3 for two way authentication required. You must also supply a wallet location and wallet password.

-W wallet_location

Required if using one way or two way SSL authentication (-U 2|3). The location of the wallet file that contains the server's SSL certificates.

Example for UNIX:

-W "file:/home/my_dir/my_wallet"

Example for Microsoft Windows:

-W "file:C:\my_dir\my_wallet"

-Q

Required, unless -P is used, if using one way or two way SSL authentication (-U 2|3). Causes the command to prompt for the wallet password for the wallet specified in the -W argument. A password supplied at the command prompt is not visible on the screen.

-P wallet_password

Required, unless -Q is used, if using one way or two way SSL authentication (-U 2|3). The wallet password for the wallet specified in the -W argument. Avoid supplying a password on the command line whenever possible. A password typed on the command line is visible on your screen. The -P wallet_password option is disabled when LDAP_PASSWORD_PROMPTONLY is set to true. See "Using Passwords with Command-Line Tools".

-E character_set

Optional. The native character set encoding. Defaults to the character set of the user's terminal. Each supported character set has a unique acronym, for example, WE8MSWIN1252, JA16SJIS, or AL32UTF8.

3.10.3 Tasks and Examples for ldapmoddn

Using the ldapmoddn command-line tool, you can perform the following tasks:

3.10.3.1 Changing the RDN of an Entry

The following example shows how to change the RDN of an entry from Mary Smith to Mary Jones.

Example:

ldapmoddn -h myhost.company.com -D "cn=orcladmin" -q -p 3060 \
    -b "cn=Mary Smith,dc=Americas,dc=IMC,dc=com" -R "cn=Mary Jones" -r

3.10.3.2 Moving an Entry

The following example shows how to move an entry to another parent node in the directory subtree. The entry with the RDN of Mary Smith is moved from the dc=Americas parent node to the dc=Australia parent node.

Example:

ldapmoddn -h myhost.company.com -D "cn=orcladmin" -q -p 3060 \
    -b "cn=Mary Smith,dc=Americas,dc=IMC,dc=com" -N "dc=Australia,dc=IMC,dc=com"

3.10.4 Related Command-Line Tools for ldapmoddn

3.11 ldapmodify

The ldapmodify command-line tool enables you to add, delete, or replace attributes for entries by supplying an LDIF file as input. You can also delete or add entries using ldapmodify.

See Appendix A, "LDIF File Format" for more information about the correct formatting of LDIF files.

See Also:

For information on using attribute aliases with ldapmodify refer to the "Attribute Aliases In the Directory" section in Oracle Fusion Middleware Administrator's Guide for Oracle Internet Directory

3.11.1 Syntax for ldapmodify

ldapmodify -h oid_hostname -D "binddn" [-Y "proxy_dn"] -q | -w password 
[-p ldap_port] [-V ldap_version] {-f ldif_filename | -X dsml_filename}  
[-a] [-b] [-c [-o log_file_name]] [-n] [-v] [-M] [-O ref_hop_limit] 
[-i 1|0] [-k|-K] 
[-U SSL_auth_mode {-W wallet_location -Q | -P wallet_password}] 
[-E character_set] [-d debug_level]

3.11.2 Arguments for ldapmodify

-h oid_hostname

Required. The host name or IP address of the Oracle Internet Directory server.

-D "binddn"

Required. The DN of the Oracle Internet Directory user needed to bind to the directory (for example, cn=orcladmin).

-Y "proxy_dn"

Optional. The DN of a proxy user. After binding to the directory, the add operation is performed as this user.

-q

Required unless -w is used. Causes the command to prompt for the user password needed to bind to the directory. A password supplied at the command prompt is not visible on the screen.

-w password

Required unless -q is used. The user password needed to bind to the directory. Avoid supplying a password on the command line whenever possible. A password typed on the command line is visible on your screen. The -w password option is disabled when LDAP_PASSWORD_PROMPTONLY is set to true. See "Using Passwords with Command-Line Tools".

-p ldap_port

Optional. The port number used to connect to the Oracle Internet Directory server. Defaults to port 3060.

-V ldap_version

Optional. The version of the LDAP protocol to use. Allowed values are 2 or 3. Defaults to 3 (LDAP v3).

-f ldif_filename | -X dsml_filename

Required. The full path and file name of the input file that contains the data you want to import.

Use the -f argument to supply an LDIF file. See Appendix A, "LDIF File Format" for information on formatting an LDIF file.

Use the -X argument to supply a Directory Service Markup Language (DSML) file. See "Adding Data to the Directory Using a DSML File" for more information about formatting a DSML file.

-a

Optional. Denotes that the LDIF or DSML input file has new entries to be added.

-b

Optional. Use this option if your input file has binary file names in it, which are preceded by the forward slash character. The tool retrieves the actual values from the file referenced.

-c

Optional. Proceeds in spite of errors. All errors are reported. If the -c argument is not used, the tool stops when an error occurs.

-n

Optional. Enables you to preview what would occur in an operation without actually performing the operation.

-v

Optional. Runs the tool in verbose mode.

-o log_file_name

Optional. Used with the -c argument. Writes the LDIF entries with errors to a log file. Specify the full path and name of the log file.

-M

Optional. Instructs the tool to send the ManageDSAIT control to the server. The ManageDSAIT control instructs the server not to send referrals to clients. Instead a referral entry is returned as a regular entry.

-O ref_hop_limit

Optional. The number of referral hops that a client should process. Defaults to 5.

-i 1 | 0

Optional. Specifies whether to bind as the current user when following referrals. 1 means bind as the current user, 0 means bind anonymously. The default is 0 (zero).

-k | -K

Optional. The -k argument authenticates using Kerberos authentication instead of simple authentication. To enable this option, you must compile with KERBEROS defined.You must already have a valid ticket granting ticket. Use the -K argument if you want to only perform the first step of the Kerberos bind.

-U SSL_auth_mode

Optional. The SSL authentication mode:

  • 1 for no authentication required.

  • 2 for one way authentication required. You must also supply a wallet location and wallet password.

  • 3 for two way authentication required. You must also supply a wallet location and wallet password.

-W wallet_location

Required if using one way or two way SSL authentication (-U 2|3). The location of the wallet file that contains the server's SSL certificates.

Example for UNIX:

-W "file:/home/my_dir/my_wallet"

Example for Microsoft Windows:

-W "file:C:\my_dir\my_wallet"

-Q

Required, unless -P is used, if using one way or two way SSL authentication (-U 2|3). Causes the command to prompt for the wallet password for the wallet specified in the -W argument. A password supplied at the command prompt is not visible on the screen.

-P wallet_password

Required, unless -Q is used, if using one way or two way SSL authentication (-U 2|3). The wallet password for the wallet specified in the -W argument. Avoid supplying a password on the command line whenever possible. A password typed on the command line is visible on your screen. The -P wallet_password option is disabled when LDAP_PASSWORD_PROMPTONLY is set to true. See "Using Passwords with Command-Line Tools".

-E character_set

Optional. The native character set encoding. Defaults to the character set of the user's terminal. Each supported character set has a unique acronym, for example, WE8MSWIN1252, JA16SJIS, or AL32UTF8.

-d debug_level

Optional. If not specified the default of 0 (not enabled) is used. Debug levels are additive. Add the numbers representing the functions that you want to activate, and use the sum of those in the command-line option. For example, to trace search filter processing (512) and active connection management (256), enter 768 as the debug level (512 + 256 = 768). Debug levels are as follows:

  • 1 — Heavy trace debugging

  • 128 — Debug packet handling

  • 256 — Connection management, related to network activities

  • 512 — Search filter processing

  • 1024 — Entry parsing

  • 2048 — Configuration file processing

  • 8192 — Access control list processing

  • 491520 — Log of communication with the database

  • 524288 — Schema related operations

  • 4194304 — Replication specific operations

  • 8388608 — Log of entries, operations and results for each connection

  • 16777216 — Trace function call arguments

  • 67108864 — Number and identity of clients connected to this server

  • 117440511 — All possible operations and data

3.11.3 Tasks and Examples for ldapmodify

Using the ldapmodify command-line tool, you can perform the following tasks:

3.11.3.1 Modifying the Directory Schema

First, you must prepare your LDIF file to define the new schema elements you want to add. See "LDIF Format for Adding Schema Elements" for examples. Once you have a properly formatted LDIF file, you can use the ldapmodify tool to import the new schema definitions into the directory schema.

Example:

ldapmodify -h myhost.company.com -D "cn=orcladmin" -q -p 3060  \
    -f /home/myfiles/modify.ldif  -v

3.11.3.2 Modifying an Entry

To modify the attributes or attribute values for an entry, you must first prepare your LDIF file correctly. See "LDIF Format for Modifying Entries" for examples. Once you have a properly formatted LDIF file, you can use the ldapmodify tool to import the changes.

Example:

ldapmodify -h myhost.company.com -D "cn=orcladmin" -q \
    -p 3060 -f /home/myfiles/modify.ldif  -v

3.11.4 Related Command-Line Tools for ldapmodify

3.12 ldapmodifymt

The ldapmodifymt command-line tool is similar to ldapmodify in that it enables you to add, delete, or modify entries by supplying an LDIF file as input. However, ldapmodifymt runs in multi-threaded mode allowing you to operate on multiple entries concurrently.

See Appendix A, "LDIF File Format" for more information about the correct formatting of LDIF files.

3.12.1 Syntax for ldapmodifymt

ldapmodifymt -h oid_hostname -D "binddn" -q | -w password [-p ldap_port] 
[-V ldap_version] -T number_of_threads {-f ldif_filename | -X dsml_filename}  
[-a] [-b] [-c [-o log_file_name]] [-M] [-O ref_hop_limit] [-k|-K] 
[-U SSL_auth_mode {-W wallet_location -Q | -P wallet_password}] 
[-E character_set] [-d debug_level]

3.12.2 Arguments for ldapmodifymt

-h oid_hostname

Required. The host name or IP address of the Oracle Internet Directory server.

-D "binddn"

Required. The DN of the Oracle Internet Directory user needed to bind to the directory (for example, cn=orcladmin).

-q

Required unless -w is used. Causes the command to prompt for the user password needed to bind to the directory. A password supplied at the command prompt is not visible on the screen.

-w password

Required unless -q is used. The user password needed to bind to the directory. Avoid supplying a password on the command line whenever possible. A password typed on the command line is visible on your screen. The -w password option is disabled when LDAP_PASSWORD_PROMPTONLY is set to true. See "Using Passwords with Command-Line Tools".

-p ldap_port

Optional. The port number used to connect to the Oracle Internet Directory server. Defaults to port 3060.

-V ldap_version

Optional. The version of the LDAP protocol to use. Allowed values are 2 or 3. Defaults to 3 (LDAP v3).

-T number_threads

Required. The number of threads for concurrently processing entries.

-f ldif_filename | -X dsml_filename

Required. The full path and file name of the input file that contains the data you want to import.

Use the -f argument to supply an LDIF file. See Appendix A, "LDIF File Format" for information on formatting an LDIF file.

Use the -X argument to supply a Directory Service Markup Language (DSML) file. See "Adding Data to the Directory Using a DSML File" for more information about formatting a DSML file.

-a

Optional. Denotes that the LDIF file has entries to be added.

-b

Optional. Use this option if your input file has binary file names in it, which are preceded by the forward slash character. The tool retrieves the actual values from the file referenced.

-c

Optional. Proceeds in spite of errors. All errors are reported. If the -c argument is not used, the tool stops when an error occurs.

-o log_file_name

Optional. Used with the -c argument. Writes the LDIF entries with errors to a log file. Specify the full path and name of the log file.

-M

Optional. Instructs the tool to send the ManageDSAIT control to the server. The ManageDSAIT control instructs the server not to send referrals to clients. Instead a referral entry is returned as a regular entry.

-O ref_hop_limit

Optional. The number of referral hops that a client should process. Defaults to 5.

-k | -K

Optional. The -k argument authenticates using Kerberos authentication instead of simple authentication. To enable this option, you must compile with KERBEROS defined.You must already have a valid ticket granting ticket. Use the -K argument if you want to only perform the first step of the Kerberos bind.

-U SSL_auth_mode

Optional. The SSL authentication mode:

  • 1 for no authentication required.

  • 2 for one way authentication required. You must also supply a wallet location and wallet password.

  • 3 for two way authentication required. You must also supply a wallet location and wallet password.

-W wallet_location

Required if using one way or two way SSL authentication (-U 2|3). The location of the wallet file that contains the server's SSL certificates.

Example for UNIX:

-W "file:/home/my_dir/my_wallet"

Example for Microsoft Windows:

-W "file:C:\my_dir\my_wallet"

-Q

Required, unless -P is used, if using one way or two way SSL authentication (-U 2|3). Causes the command to prompt for the wallet password for the wallet specified in the -W argument. A password supplied at the command prompt is not visible on the screen.

-P wallet_password

Required, unless -Q is used, if using one way or two way SSL authentication (-U 2|3). The wallet password for the wallet specified in the -W argument. Avoid supplying a password on the command line whenever possible. A password typed on the command line is visible on your screen. The -P wallet_password option is disabled when LDAP_PASSWORD_PROMPTONLY is set to true. See "Using Passwords with Command-Line Tools".

-E character_set

Optional. The native character set encoding. Defaults to the character set of the user's terminal. Each supported character set has a unique acronym, for example, WE8MSWIN1252, JA16SJIS, or AL32UTF8.

-d debug_level

Optional. If not specified the default of 0 (not enabled) is used. Debug levels are additive. Add the numbers representing the functions that you want to activate, and use the sum of those in the command-line option. For example, to trace search filter processing (512) and active connection management (256), enter 768 as the debug level (512 + 256 = 768). Debug levels are as follows:

  • 1 — Heavy trace debugging

  • 128 — Debug packet handling

  • 256 — Connection management, related to network activities

  • 512 — Search filter processing

  • 1024 — Entry parsing

  • 2048 — Configuration file processing

  • 8192 — Access control list processing

  • 491520 — Log of communication with the database

  • 524288 — Schema related operations

  • 4194304 — Replication specific operations

  • 8388608 — Log of entries, operations and results for each connection

  • 16777216 — Trace function call arguments

  • 67108864 — Number and identity of clients connected to this server

  • 117440511 — All possible operations and data

3.12.3 Tasks and Examples for ldapmodifymt

Using the ldapmodifymt command-line tool, you can perform the following task:

3.12.3.1 Modifying Multiple Entries Concurrently

To modify multiple entries at once, you must first prepare your LDIF file correctly. See Appendix A, "LDIF File Format" for examples. Once you have a properly formatted LDIF file, you can use the ldapmodifymt tool to import the changes.

The following example uses five concurrent threads to modify the entries specified in the file /home/myfiles/modify.ldif.

Example:

ldapmodify -h myhost.company.com -D "cn=orcladmin" -w password -p 3060 \
    -T 5 -f /home/myfiles/modify.ldif  -v

3.12.4 Related Command-Line Tools for ldapmodifymt

3.13 ldapsearch

The ldapsearch command-line tool enables you to search for and retrieve specific entries in the directory.

The LDAP filter that you use to search for entries must be compliant with the Internet Engineering Task Force (IETF) standards as specified in RFC 2254. Refer to the IETF Web site at http://www.ietf.org for more information about the standard filter format. Oracle Internet Directory supports all elements of RFC 2254 except for extensible matching.

Note:

Various UNIX shells interpret some characters—for example, asterisks (*)—as special characters. Depending on the shell you are using, you might need to escape these characters.

See Also:

For information on using attribute aliases with ldapsearch refer to the "Attribute Aliases In the Directory" section in Oracle Fusion Middleware Administrator's Guide for Oracle Internet Directory

3.13.1 Syntax for ldapsearch

ldapsearch -h oid_hostname -D "binddn" -q | -w password [-Y "proxy_dn"] 
[-p ldap_port] [-V ldap_version] -b "basedn" {-s base|one|sub} {"filter_string"
attributes]|-f input_file} [-F separator] [-T [-]sort_attribute] [-j page_size]
[-A] [-a never|always|search|find] [-S] [-R] [-i 1|0] [-t] [-u] [-L|-X] [-B] [-M]
[-v] [-n] [-l time_limit] [-z size_limit] [-O ref_hop_limit] [-U SSL_auth_mode 
{-W wallet_location -Q | -P wallet_password}] [-d debug_level] 
[-E character_set][-c]

3.13.2 Arguments for ldapsearch

-h oid_hostname

Required. The host name or IP address of the Oracle Internet Directory server.

-D "binddn"

Required. The DN of the Oracle Internet Directory user needed to bind to the directory (for example, cn=orcladmin).

-q

Required unless -w is used. Causes the command to prompt for the user password needed to bind to the directory. A password supplied at the command prompt is not visible on the screen.

-w password

Required unless -q is used. The user password needed to bind to the directory. Avoid supplying a password on the command line whenever possible. A password typed on the command line is visible on your screen. The -w password option is disabled when LDAP_PASSWORD_PROMPTONLY is set to true. See "Using Passwords with Command-Line Tools".

-Y "proxy_dn"

Optional. The DN of a proxy user. After binding to the directory, the add operation is performed as this user.

-p ldap_port

Optional. The port number used to connect to the Oracle Internet Directory server. Defaults to port 3060.

-V ldap_version

Optional. The version of the LDAP protocol to use. Allowed values are 2 or 3. Defaults to 3 (LDAP v3).

-b "basedn"

Required. The base DN for the search.

-s base | one | sub

Required. The scope of the search within the DIT. The options are:

  • base - Retrieves a particular directory entry. Along with this search depth, you use the search criteria bar to select the attribute objectClass and the filter Present.

  • one - Limits your search to all entries beginning one level down from the root of your search.

  • sub - Searches entries within the entire subtree, including the root of your search.

"filter_string" [attributes] | -f input_file

Required. Supply a single filter on the command-line within quotes followed by the attribute names whose values you want returned. Separate attributes with a space. If you do not list any attributes, all attributes are retrieved.

You can also supply an input file with the -f argument that contains a sequence of search operations to perform.

In the output, the attribute names are shown in lower case if the attribute orclReqattrCase is 0 in the instance-specific config entry. If orclReqattrCase is set to 1, the attribute names in the output are shown in the same case in which they were entered on the commoand line. See "Attribute Case in ldapsearch Output".

-F separator

Optional. Enables you to choose a separator to use between attribute names and values in the search output. The default is = (equal sign).

-T [-]sort_attribute

Optional. Instructs the tool to send a sort request to the server. The server returns entries sorted on the attribute, sort_attribute. A dash (-) before sort_attribute instructs the tool to sort the entries in reverse order.

-j page_size

Optional. Instructs the tool to send a page request to the server. The server returns paged entries with pages of size, page_size.

-A

Optional. Retrieves attribute names only (no values).

-a never | always | search | find

Optional. Specifies alias dereferencing. An alias entry in an LDAP directory is an entry that points to another entry. Following an alias pointer is known as dereferencing an alias. The options are:

  • never - Never dereference alias entries. Choose this option to improve search performance if there are no alias entries in the directory that require dereferencing.

  • always - Always dereference aliases. This selection is the default.

  • search - Dereference alias entries subordinate to a specified search base, but do not dereference an alias search base entry.

  • find - Deference an alias entry for a specified search base, but do not dereference alias entries subordinate to the search base.

-S attr

Optional. Sorts the results by the attribute specified.

-R

Optional. Disables the automatic following of referrals.

-i 1 | 0

Optional. Specifies whether to bind as the current user when following referrals. 1 means bind as the current user, 0 means bind anonymously. The default is 0 (zero).

-t

Optional. Writes files to /tmp.

-u

Optional. Includes user-friendly names in the output.

-L | -X

Optional. Prints entries in LDIF (-L) or DSML format (-X).

With the -L option, all attributes, including binary attributes are printed in LDAP Data Interchange Format (LDIF). Binary attributes are transformed into printable characters using BASE64 encoding.

See Also:

Appendix A, "LDIF File Format" for a description of LDAP Data Interchange Format.

-B

Optional. Allows printing of non-ASCII values. Binary attributes are printed as is, without encoding. The complete value might not be printed, as it might contain non-printable characters.

-M

Optional. Instructs the tool to send the ManageDSAIT control to the server. The ManageDSAIT control instructs the server not to send referrals to clients. Instead a referral entry is returned as a regular entry.

-n

Optional. Enables you to preview what would occur in an operation without actually performing the operation.

-v

Optional. Runs the tool in verbose mode.

-l time_limit

Optional. The maximum time in seconds to wait for an ldapsearch command to complete.

-z size_limit

Optional. The maximum number of entries to return.

-O ref_hop_limit

Optional. The number of referral hops that a client should process. Defaults to 5.

-U SSL_auth_mode

Optional. The SSL authentication mode:

  • 1 for no authentication required.

  • 2 for one way authentication required. You must also supply a wallet location and wallet password.

  • 3 for two way authentication required. You must also supply a wallet location and wallet password.

-W wallet_location

Required if using one way or two way SSL authentication (-U 2|3). The location of the wallet file that contains the server's SSL certificates.

Example for UNIX:

-W "file:/home/my_dir/my_wallet"

Example for Microsoft Windows:

-W "file:C:\my_dir\my_wallet"

-Q

Required, unless -P is used, if using one way or two way SSL authentication (-U 2|3). Causes the command to prompt for the wallet password for the wallet specified in the -W argument. A password supplied at the command prompt is not visible on the screen.

-P wallet_password

Required, unless -Q is used, if using one way or two way SSL authentication (-U 2|3). The wallet password for the wallet specified in the -W argument. Avoid supplying a password on the command line whenever possible. A password typed on the command line is visible on your screen. The -P wallet_password option is disabled when LDAP_PASSWORD_PROMPTONLY is set to true. See "Using Passwords with Command-Line Tools".

-d debug_level

Optional. If not specified the default of 0 (not enabled) is used. Debug levels are additive. Add the numbers representing the functions that you want to activate, and use the sum of those in the command-line option. For example, to trace search filter processing (512) and active connection management (256), enter 768 as the debug level (512 + 256 = 768). Debug levels are as follows:

  • 1 — Heavy trace debugging

  • 128 — Debug packet handling

  • 256 — Connection management, related to network activities

  • 512 — Search filter processing

  • 1024 — Entry parsing

  • 2048 — Configuration file processing

  • 8192 — Access control list processing

  • 491520 — Log of communication with the database

  • 524288 — Schema related operations

  • 4194304 — Replication specific operations

  • 8388608 — Log of entries, operations and results for each connection

  • 16777216 — Trace function call arguments

  • 67108864 — Number and identity of clients connected to this server

  • 117440511 — All possible operations and data

-E character_set

Optional. The native character set encoding. Defaults to the character set of the user's terminal. Each supported character set has a unique acronym, for example, WE8MSWIN1252, JA16SJIS, or AL32UTF8.

-C

Optional. ldapsearch -C option causes ldapsearch to traverse a hierarchy and report direct memberships. The ldapsearch -C option essentially includes the CONNECT_BY control (2.16.840.1.113894.1.8.3) in the request sent to the client. ldapsearch doesn't have any means to pass values with a control. So, it sends the CONNECT_BY control without values. In this case the default values are assumed, that is, the hierarchy-establishing attribute name is obtained from the filter, and the number of levels is 0. Thus, the -C option can only be used to fetch all containers of a containee queries, for example, fetch all groups of a user, fetch all employees of a manager and so forth. Also, all levels of the hierarchy are traversed. For more information refer to Table 6-2, "Request Controls Supported by Oracle Internet Directory".

3.13.3 Tasks and Examples for ldapsearch

Using the ldapsearch command-line tool, you can perform the following tasks:

3.13.3.1 Performing a Base Object Search

The following example performs a base-level search on the directory from the root.

  • -b specifies base DN for the search, root in this case.

  • -s specifies whether the search is a base search (base), one level search (one) or subtree search (sub).

  • "objectclass=*" specifies the filter for search.

Example:

ldapsearch -p 3060 -h myhost -b "" -s base -v "objectclass=*"

3.13.3.2 Performing a One-Level Search

The following example performs a one level search starting at "ou=HR, ou=Americas, o=IMC, c=US".

Example:

ldapsearch -p 3060 -h myhost -b "ou=HR, ou=Americas, o=IMC, c=US" -s one \
           -v "objectclass=*"

3.13.3.3 Performing a Subtree Search

The following example performs a subtree search and returns all entries having a DN starting with "cn=us".

Example:

ldapsearch -p 3060 -h myhost -b "c=US" -s sub -v "cn=Person*"

3.13.3.4 Searching for Attribute Values of Entries

The following example returns only the DN attribute values of the matching entries:

Example:

ldapsearch -p 3060 -h myhost -b "c=US" -s sub -v "objectclass=*" dn

The following example retrieves only the distinguished name along with the surname (sn) and description (description) attribute values:

Example:

ldapsearch -p 3060 -h myhost -b "c=US" -s sub -v "cn=Person*" dn sn description

The following example retrieves the distinguished name (dn), surname (sn), and description (description) attribute values. The entries are sorted by surname (sn). There are 10 entries returned per page.

Example:

ldapsearch -p 3060 -h myhost -b "c=US" -s sub -v "cn=Person*" dn sn description \
    -T sn -j 10

3.13.3.5 Searching for Entries with Attribute Options

The following example retrieves entries with common name (cn) attributes that have an option specifying a language code attribute option. This particular example retrieves entries in which the common names are in French and begin with the letter R.

Example:

ldapsearch -p 3060 -h myhost -b "c=US" -s sub "cn;lang-fr=R*"

Suppose that, in the entry for John, no value is set for the cn;lang-it language code attribute option. In this case, the following example does not return John's entry:

Example:

ldapsearch -p 3060 -h myhost -b "c=us" -s sub "cn;lang-it=Giovanni"

3.13.3.6 Searching for All User Attributes and Specified Operational Attributes

The following example retrieves all user attributes and the createtimestamp and orclguid operational attributes:

Example:

ldapsearch -p 3060 -h myhost -b "ou=Benefits,ou=HR,ou=Americas,o=IMC,c=US" \
           -s sub "cn=Person*" "*" createtimestamp orclguid

The following example retrieves entries modified by Anne Smith:

Example:

ldapsearch -h sun1 \
    -b "" "(&(objectclass=*)(modifiersname=cn=Anne Smith))"

The following example retrieves entries modified between 01 April 2001 and 06 April 2001:

Example:

ldapsearch -h sun1 -b "" \
     "(&(objectclass=*)(modifytimestamp >= 20000401000000) \
     (modifytimestamp <= 20000406235959))"

Note:

Because modifiersname and modifytimestamp are not indexed attributes, use catalog to index these two attributes. Then, restart the Oracle directory server before issuing the two previous ldapsearch commands.

3.13.3.7 Searching for Entries (More Examples)

Each of the following examples searches on port 3060 of host sun1, and searches the whole subtree starting from the DN "ou=hr,o=acme,c=us".

The following example searches for all entries with any value for the objectclass attribute.

ldapsearch -p 3060 -h sun1 -b "ou=hr, o=acme, c=us" -s subtree "objectclass=*"

The following example searches for all entries that have orcl at the beginning of the value for the objectclass attribute.

ldapsearch -p 3060 -h sun1 -b "ou=hr, o=acme, c=us" -s subtree "objectclass=orcl*"

The following example searches for entries where the objectclass attribute begins with orcl and cn begins with foo.

ldapsearch -p 3060 -h sun1 -b "ou=hr, o=acme, c=us" \
          -s subtree "(&(objectclass=orcl*)(cn=foo*))"

The following example searches for entries in which cn begins with foo or sn begins with bar.

ldapsearch -p 3060 -h sun1 -b "ou=hr, o=acme, c=us" \
          -s subtree "(|(cn=foo*)(sn=bar*))"

The following example searches for entries in which employeenumber is less than or equal to 10000.

ldapsearch -p 3060 -h sun1 -b "ou=hr, o=acme, c=us" \
           -s subtree "employeenumber<=10000"

3.13.3.8 Attribute Case in ldapsearch Output

In the output from the ldapsearch command, the attribute names are shown in lower case if the attribute orclReqattrCasein the instance-specific configuration entry is 0. If orclReqattrCase is set to 1, the attribute names in the output are shown in the same case in which they were entered on the commoand line.

Example:

ldapsearch -h localhost -p 389 -b "dc=oracle,dc=com" -s base -L "objectclass=*" DC

If orclReqattrCase is 0 the output looks like this:

dn: dc=oracle,dc=comdc: oracle

If orclReqattrCase is 1, the output looks like this:

dn: dc=oracle,dc=comDC: oracle

3.13.4 Related Command-Line Tools for ldapsearch

3.14 ldifmigrator

The Oracle Internet Directory Data Migration Tool (ldifmigrator) is used to convert LDIF files output from other directories or application-specific repositories into a format recognized by Oracle Internet Directory. The Data Migration Tool takes as input an LDIF file containing substitution variables, and outputs an LDIF file suitable for loading into Oracle Internet Directory.

See "LDIF Format for Migrating Entries" for the correct format of the LDIF input file for this tool.

3.14.1 Syntax for ldifmigrator

ldifmigrator "input_file=filename" "output_file=filename"
[-lookup -h oid_hostname -D "binddn" -w password [-p ldap_port]
[subscriber=subscriberDN]] ["s_VariableName1=replacement_value" 
"s_VariableName2=replacement_value"...] 
[-load -reconcile SAFE|SAFE_EXTENDED|NORMAL]

3.14.2 Arguments for ldifmigrator

"input_file=filename"

The full path and file name of the LDIF file that contains directory entry data and one or more substitution variables.

"output_file=filename"

The full path and file name of the output file produced by the ldifmigrator tool.

-lookup

If this flag is specified, then values of certain substitution variables are obtained by looking up the correct values in the directory server. See "Substitution Variables for Migration Input Files" for a list of substitution variables that can be looked up.

-h oid_hostname

Required if the -lookup flag is used. The host name or IP address of the Oracle Internet Directory server.

-D "binddn"

Required if the -lookup flag is used. The DN of the Oracle Internet Directory user needed to bind to the directory (for example, cn=orcladmin).

-q

Required unless -w is used. Causes the command to prompt for the user password needed to bind to the directory. A password supplied at the command prompt is not visible on the screen.

-w password

Required unless -q is used. The user password needed to bind to the directory. Avoid supplying a password on the command line whenever possible. A password typed on the command line is visible on your screen. The -w password option is disabled when LDAP_PASSWORD_PROMPTONLY is set to true. See "Using Passwords with Command-Line Tools".

subscriber=subscriberDN

Optional. The subscriber whose attribute values is used in place of the substitution variables. If not specified, then the default identity management realm specified in the Root Oracle Context is used.

"s_VariableName=replacement_value"

Optional. You can specify a value for a substitution variable on the command-line. See "Substitution Variables for Migration Input Files" for instructions on adding a substitution variable to the input LDIF file. The ldifmigrator tool replaces all occurrences of the variable with the value you specify.

-load

Optional. Loads the data output by the ldifmigrator tool directly into Oracle Internet Directory. If an entry is already present in the directory then that directory entry is logged to the file. The addition of the directory entries could fail for other reasons as well, for instance not enough permission to add or parent entry not being present.

-reconcile SAFE | SAFE_EXTENDED | NORMAL

Optional. The -reconcile option enables you to specify different modes if the tool tries to load data for entries that already exist, or modify attributes of entries that may have conflicts. The following modes are available:

  • SAFE - This mode only adds new entries that don't exist or appends new attributes to existing entries.

  • SAFE-EXTENDED - This mode only adds new entries that don't exist or appends new attributes to existing entries. If you try to add a new value for existing attributes, then it adds it to the existing set of values.

  • NORMAL - This mode applies all directives as intended, overwriting any conflicting attributes or entries with the data specified in the ldifmigrator output.

See "Reconcile Options for Migrated Entries" for more information about LDIF directives supported by the -reconcile option.

3.14.3 Tasks and Examples for ldifmigrator

Using the ldifmigrator command-line tool, you can perform the following tasks:

3.14.3.1 Using the Data Migration Tool in Lookup Mode

In this example, Oracle Internet Directory server is present in the environment, and the migration tool looks up the directory server to figure out certain substitution variables specified in the LDIF input file.

Example:

$ldifmigrator "input_file=sample.dat" "output_file=sample.ldif" \
               -lookup "host=ldap.acme.com" "subscriber=acme" \
               "s_UserOrganization=Development"

3.14.3.2 Overriding Data Migration Values in Lookup Mode

In some cases, you want to use the lookup mode but would also like to override the values of one or more of the pre-defined substitution variables. This can be done by specifying the override value in the command-line. The following command line shows how one can set the UserNickNameAttribute to cn overriding the default of uid:

Example:

$ldifmigrator "input_file=sample.dat" "output_file=sample.ldif" \
              -lookup "host=ldap.acme.com" "subscriber=acme" \
             "s_UserOrganization=Development" "s_UserNicknameAttribute=cn"

3.14.3.3 Using the Data Migration Tool by Supplying Your Own Values

The following example shows how you can specify your own values for substitution variables found in the LDIF input file, rather than using lookup mode.

Example:

$ldifmigrator "input_file=sample.dat" "output_file=sample.ldif"  \
              "s_UserContainerDN=cn=Users,o=Acme,dc=com" \
              "s_UserNicknameAttribute=uid" "s_UserOrganization=Development"

3.14.3.4 Loading and Reconciling Data Using the Data Migration Tool

The Data Migration Tool gives your the option of loading the data directly into Oracle Internet Directory. Use the -load and -reconcile options to load data and safely reconcile any conflicts.

Example:

$ldifmigrator "input_file=sample.dat" "output_file=sample.ldif" \
               -lookup "host=ldap.acme.com" "subscriber=acme" \
               "s_UserOrganization=Development"
               -load -reconcile SAFE

3.14.4 Related Command-Line Tools for ldifmigrator

3.14.5 Error Messages for ldifmigrator

The Data Migration Tool can display these error messages:

Table 3-1 Error Messages of the Data Migration Tool

Message Reason Remedial Action

Environment variable ORACLE_HOME not defined

ORACLE_HOME is not defined.

Set the environment variable ORACLE_HOME

Environment variable ORACLE_INSTANCE not defined

ORACLE_INSTANCE is not defined.

Set the environment variable ORACLE_INSTANCE

Error while parsing the input parameters. Please verify

Not all the required parameters are provided. The required parameters are Input_File, Output_File and at least one substitution variable

Specify the input parameters properly. Use the -help option to print the usage.

Input_File parameter not specified. Please specify

Input_File parameter is a mandatory parameter.

Specify the input parameters properly. Use the -help option to print the usage.

Output_File parameter not specified. Please specify

Output_File parameter is a mandatory parameter.

Specify the input parameters properly. Use the -help option to print the usage.

The specified input file does not exist

The specified file location is invalid.

Check the input file path

Check the input file. Zero byte input file

The input file does not contain any entries.

Provide a valid file with pseudo LDIF entries

Cannot create the output file. Output file already exists

The output file already exists

Check the Output_File flag

Access denied, cannot read from the input file

The specified input file does not have read permission

Check the read permission of the input file.

Access denied, cannot create the output file

You do not have permission to create the output file.

Check the permission of the directory under which the output file needs to be created.

Directory server name not specified. When -lookup option is used the host parameter should be specified

When the -lookup option is specified, the host parameter is mandatory.

Specify the host parameter.

Bind Dn parameter name not specified. When -lookup option is used the dn parameter should be specified

When the -lookup option is specified, the DN parameter is mandatory.

Specify the DN parameter.

The port number specified is invalid

The port number should be a numeric value.

Check the port number parameter

Unable to establish connection to directory. Please verify the input parameters: host, port, dn & password

The directory server may not be running on the specified host and port, or credentials may be invalid.

Check the host, port, DN and password parameters. Check ORACLE_INSTANCE/diagnostics/logs/OID/tools/.

Naming exception occurred while retrieving the subscriber information from the directory. Please verify the input parameters

The specified identity management realm does not exist in the directory

Check the realm parameter

Not all the substitution variables are defined in the directory server specified

If the identity management realm entry does not contain the required attributes, then this error occurs.

Check the realm entry in the directory

Error occurred while migrating LDIF data to Oracle Internet Directory

This might occur if something goes wrong in the middle of a process—for example, a failure of the directory server or disk.

Report the error message to the administrator


When an error condition occurs, the log messages are logged to this file:

ORACLE_INSTANCE/ldap/install/LDIFMig_YYYY_MM_DD_HH_SS.log.

3.15 ldifwrite

The ldifwrite command-line tool enables you to convert to LDIF all or part of the information residing in an Oracle Internet Directory. Once you have converted the information, you can load it into a new node in a replicated directory or another node for backup storage.

Note:

The ldifwrite command requires that the environment variable ORACLE_INSTANCE be set.

Note:

The ldifwrite tool output does not include operational data of the directory itself—for example, cn=subschemasubentry, cn=catalogs, and cn=changelog entries. To export these entries into LDIF format, use ldapsearch with the -L flag.

The ldifwrite tool performs a subtree search, including all entries below the specified DN, including the DN itself.

Using ldifwrite with Replication

When you add data to a node that is part of a Directory Replication Group (DRG), you can use either bulk tools or LDAP tools, depending on the circumstances. The following rules apply:

  • When you add new entries to all nodes in the DRG, you can use either bulk tools or LDAP tools. For more than 20K entries, bulk tools are significantly faster. If you use LDAP tools, add the entries to only one node in the DRG and let replication propagate the entries. If you use bulk tools, generate the intermediate file only once from the LDIF file and use that intermediate file to load the entries onto all the nodes in the DRG.

  • When you copy existing entries from one node to another in the same replication group, use bulk tools. Use the bulkload option restore=true when you upload the data.

  • If the LDIF file contains operational attributes, which it does when created with ldifwrite, use bulkload to add the entries.

  • If the replication agreement is a partial replication agreement, use ldifwrite with the base DN as the replication agreement DN to write the entries to the LDIF file. Then use bulkload with the restore=true option to load the data.

3.15.1 Syntax for ldifwrite

ldifwrite connect=connect_string basedn=Base_DN ldiffile=LDIF_Filename [filter=LDAP_Filter] [threads=num_of_threads] [debug="TRUE"|"FALSE"] [encode=character_set] [verbose="TRUE"|"FALSE"]

3.15.2 Arguments for ldifwrite

connect

Required. The directory database connect string. If you already have a tnsnames.ora file configured, then this is the net service name specified in that file, which is located by default in ORACLE_INSTANCE/config. (You can set the TNS_ADMIN environment variable if you want to use a different location.)

basedn

Required. The base DN of the subtree to be written out in LDIF format.

If the base DN is a replication agreement entry, then you can back up part of the naming context based on the LDAP naming context configuration. Specify the replication agreement DN in this case.

ldiffile

Required. The full path and file name of the output LDIF file.

filter

Optional. This is the LDAP filter to be used. You can specify a filter to select entries that match a particular criteria. Only these entries would be written to the LDIF file.

threads

Optional. The number of threads used to read from the directory store and write to the LDIF output file. The default is the number of CPUs plus one.

debug

Optional. The debug option reports the logging level. This is useful in case the command runs into errors. The output is logged to the ldifwrite.log file. This file can be found under ORACLE_INSTANCE/diagnostics/logs/OID/tools.

encode

Optional. The native character set encoding. Defaults to the character set of the user's terminal. Each supported character set has a unique acronym, for example, WE8MSWIN1252, JA16SJIS, or AL32UTF8.

verbose

3.15.3 Tasks and Examples for ldifwrite

Using the ldifwrite command-line tool, you can perform the following tasks

3.15.3.1 Converting All Entries under a Naming Context to an LDIF File

The following example writes all the entries under ou=Europe,o=imc,c=us into the output1.ldif file.

The LDIF file and the intermediate file are always written to the current directory.

The ldifwrite tool includes the operational attributes of each entry in the directory, including createtimestamp, creatorsname, and orclguid.

When prompted for the Oracle Internet Directory password, enter the password of the ODS database user account.

Example:

ldifwrite connect="nldap" basedn="ou=Europe, o=imc, c=us" ldiffile="output1.ldif"

3.15.3.2 Converting a Partial Naming Context to an LDIF File

The following example uses the following naming context objects defined in partial replication:

dn: cn=includednamingcontext000001,  cn=replication namecontext,  orclagreementid=000001,  orclreplicaid=node replica identifier,  cn=replication configuration
orclincludednamingcontexts: c=us
orclexcludednamingcontexts: ou=Americas, c=us
orclexcludedattributes: userpassword
objectclass: top
objectclass: orclreplnamectxconfig

In this example, all entries under c=us are backed up except ou=Americas,c=us. The userpassword attribute is also excluded.

Example:

ldifwrite connect="nldap" basedn="cn=includednamingcontext000001, \
          cn=replication namecontext,orclagreementid=000001, \
          orclreplicaid=node replica identifier,cn=replication configuration" \
          ldiffile="output2.ldif"

3.15.3.3 Converting Entries that Match Criteria to an LDIF File

The following example writes entries under ou=users,o=test,c=us that have sn="Stuart" to an output LDIF file, output3.ldif.

Example:

ldifwrite connect="nldap" basedn="ou=users, o= test, c=us" filter="sn=xyz" ldiffile="output3.ldif"

3.15.4 Related Command-Line Tools for ldifwrite

3.16 upgradecert.pl

Starting with Release 10.1.2, a certificate hash value can be used to bind to Oracle Internet Directory. The introduction of this hash value requires that user certificates issued before Release 10.1.2 be updated in the directory. This is a post-upgrade step and it is required only if user certificates are provisioned in the directory. The upgradecert.pl tool is used for this purpose.

Before running the upgradecert.pl tool:

  1. Make sure that the Oracle Internet Directory server instance is up and running.

  2. Check that you are running Perl 5.6 or later. Run this command:

    perl -version
    
  3. Make sure that the environment variable PERL5LIB is set to the proper PERL library location.

  4. Check that you can run ldapmodify and ldapsearch from your command prompt.

  5. Determine whether you have enough disk space to run the tool. The amount of disk space required depends upon the number of certificates stored.

3.16.1 Syntax for upgradecert.pl

perl ORACLE_HOME/ldap/bin/upgradecert.pl -h oid_hostname -D "binddn"
-w password [-p ldap_port] [-t temp_dir]

3.16.2 Arguments for upgradecert.pl

-h oid_hostname

Required. The host name or IP address of the Oracle Internet Directory server.

-D "binddn"

Required. The DN of the Oracle Internet Directory user needed to bind to the directory (for example, cn=orcladmin).

-q

Required unless -w is used. Causes the command to prompt for the user password needed to bind to the directory. A password supplied at the command prompt is not visible on the screen.

-w password

Required unless -q is used. The user password needed to bind to the directory. Avoid supplying a password on the command line whenever possible. A password typed on the command line is visible on your screen. The -w password option is disabled when LDAP_PASSWORD_PROMPTONLY is set to true. See "Using Passwords with Command-Line Tools".

-t temp_dir

Optional. The location of the temporary working directory. This is where the log file is found. The default is $ORACLE_INSTANCE/diagnostics/logs/OID/tools if the ORACLE_INSTANCE environment variable is set. If this variable is not set, the default is the current directory.

3.16.3 Tasks and Examples for upgradecert.pl

Using the upgradecert.pl tool, you can perform the following task:

3.16.3.1 Upgrading User Certificates Stored in the Directory from Releases Prior to 10.1.2

Example:

perl ORACLE_HOME/ldap/bin/upgradecert.pl -h myhost.company.com \
     -D "cn=orcladmin" -w password

3.16.4 Related Command-Line Tools for upgradecert.pl

  • N/A