A Syntax for LDIF and Command-Line Tools

This appendix provides syntax, usage notes, and examples for LDIF and LDAP command-line tools. It contains these topics:

• LDAP Data Interchange Format (LDIF) Syntax

• Starting, Stopping, Restarting, and Monitoring Oracle Internet Directory Servers

• Entry and Attribute Management Command-Line Tools Syntax

• Oracle Directory Integration and Provisioning Platform Command-Line Tools Syntax

A.1 LDAP Data Interchange Format (LDIF) Syntax

The standardized file format for directory entries is as follows:

dn: distinguished_name
attribute_type: attribute_value
.
.
.
objectClass: object_class_value
.
.
.

Property	Value	Description
dn:	RDN,RDN,RDN,...	Separate RDNs with commas.
attribute_type	attribute_value	This line repeats for every attribute in the entry, and for every attribute value in multi-valued attributes.
objectClass	object_class_value	This line repeats for every object class.

The following example shows a file entry for an employee. The first line contains the DN. The lines that follow the DN begin with the mnemonic for an attribute, followed by the value to be associated with that attribute. Note that each entry ends with lines defining the object classes for the entry.

dn: cn=Suzie Smith,ou=Server Technology,o=Acme, c=US
cn: Suzie Smith
cn: SuzieS
sn: Smith
mail: [e-mail]
telephoneNumber: 69332
photo: /ORACLE_HOME/empdir/photog/ssmith.jpg
objectClass: organizationalPerson
objectClass: person
objectClass: top

The next example shows a file entry for an organization:

dn: o=Acme,c=US
o: Acme
ou: Financial Applications
objectClass: organization 
objectClass: top

LDIF Formatting Notes

A list of formatting rules follows. This list is not exhaustive.

• All mandatory attributes belonging to an entry being added must be included with non-null values in the LDIF file.

  
  

  Tip: To see the mandatory and optional attribute types for an object class, use Oracle Directory Manager. See Oracle Internet Directory Administrator's Guide.

  
  

• Non-printing characters and tabs are represented in attribute values by base-64 encoding.

• The entries in your file must be separated from each other by a blank line.

• A file must contain at least one entry.

• Lines can be continued to the next line by beginning the continuation line with a space or a tab.

• Add a blank line between separate entries.

• Reference binary files, such as photographs, with the absolute address of the file, preceded by two forward slashes.

• The DN contains the full, unique directory address for the object.

• The lines listed after the DN contain both the attributes and their values. DNs and attributes used in the input file must match the existing structure of the DIT. Do not use attributes in the input file that you have not implemented in your DIT.

• Sequence the entries in an LDIF file so that the DIT is created from the top down. If an entry relies on an earlier entry for its DN, make sure that the earlier entry is added before its child entry.

• When you define schema within an LDIF file, insert a white space between the opening parenthesis and the beginning of the text, and between the end of the text and the ending parenthesis.

  
  

  See Also: The various resources listed in "Related Documents" for a complete list of LDIF formatting rules The section "Using Globalization Support with LDIF Files" in Oracle Internet Directory Administrator's Guide

  
  

A.2 Starting, Stopping, Restarting, and Monitoring Oracle Internet Directory Servers

This section tells how to use command-line tools for starting, stopping, restarting, and monitoring Oracle Internet Directory servers. It contains these topics:

• The OID Monitor (oidmon) Syntax

• The OID Control Utility (oidctl) Syntax

A.2.1 The OID Monitor (oidmon) Syntax

Use the OID Monitor to initiate, monitor, and terminate directory server processes. If you elect to install a replication server, OID Monitor controls it. When you use oidctl to start or stop directory server instances, OID Monitor interprets your commands.

A.2.1.1 Starting the OID Monitor

Starting OID Monitor restarts any Oracle Internet Directory processes that were previously stopped.

To start the OID Monitor:

1. Set the following environment variables:

   • ORACLE_HOME

   • ORACLE_SID or a proper TNS CONNECT string

   • NLS_LANG (APPROPRIATE_LANGUAGE.AL32UTF8). The default language set at installation is AMERICAN_AMERICA.

   • PATH. In the PATH environment variable, specify the Oracle LDAP binary—that is, ORACLE_HOME/bin—before the UNIX binary directory.

2. At the system prompt, type:

   oidmon [connect=connect_string] [host=virtual/host_name][sleep=seconds] start
   

Table A-1 Arguments for Starting OID Monitor

Argument	Description
connect=connect_string	Specifies the connect string for the database to which you want to connect. This is the network service name set in the tnsnames.ora file. This argument is optional.
host=virtual/host_name	Specifies the virtual host or rack nodes on which to start OID Monitor
sleep=seconds	Specifies number of seconds after which the OID Monitor should check for new requests from OID Control and for requests to restart any servers that may have stopped. The default sleep time is 10 seconds. This argument is optional.
start	Starts the OID Monitor process

For example:

oidmon connect=dbs1 sleep=15 start

To start OID Monitor on a virtual host:

oidmon connect=dbsl host=virtual_host start

A.2.1.2 Stopping the OID Monitor

Stopping the OID Monitor also stops all other Oracle Internet Directory processes.

To stop the OID Monitor daemon, at the system prompt, type:

oidmon [connect=connect_string] [host=virtual/host_name] stop

Table A-2 Arguments for Stopping OID Monitor

Argument	Description
connect=connect_string	Specifies the connect string for the database to which you want to connect. This is the connect string set in the tnsnames.ora file.
host=virtual/host_name	Specifies the virtual host or rack nodes on which to start OID Monitor
stop	Stops the OID Monitor process

For example:

oidmon connect=dbs1 stop

A.2.1.3 Starting and Stopping OID Monitor in a Cold Failover Cluster Configuration

While starting and stopping OID Monitor, use the host parameter to specify the virtual host name. The syntax is:

oidmon [connect=connect_string] host=virtual_host start|stop

Note: If you are going to start Oracle Internet Directory servers on a virtual host, then, when using both oidmon and oidctl, be sure to specify the host argument as the virtual host. If the OID Monitor is started with the host=host name argument, and the host name does not match the name of the physical host, then the OID Monitor assumes that the intended host is the logical host. You must use the same host name when using oidmon to stop or start any servers, otherwise the OID Monitor does not start or stop the servers. To determine the physical host name, execute the uname command.

A.2.2 The OID Control Utility (oidctl) Syntax

OID Control Utility is a command-line tool for starting and stopping the directory server. The commands are interpreted and executed by the OID Monitor process.

Note: Although you can start the directory server without using OID Monitor and the OID Control Utility, Oracle Corporation recommends that you use them. This way, if the directory server unexpectedly terminates, then OID Monitor automatically restarts it.

This section contains these topics:

• Starting and Stopping an Oracle Directory Server Instance

• Troubleshooting Directory Server Instance Startup

• Starting and Stopping an Oracle Directory Replication Server Instance

• Starting the Oracle Directory Integration and Provisioning Server

• Stopping the Oracle Directory Integration and Provisioning Server

• Restarting Oracle Internet Directory Server Instances

• Starting and Stopping Directory Servers on a Virtual Host or an Oracle Application Server Cluster (Identity Management)

A.2.2.1 Starting and Stopping an Oracle Directory Server Instance

Use the object class to start and stop Oracle directory server instances.

A.2.2.1.1 Starting an Oracle Directory Server Instance

The syntax for starting an Oracle directory server instance is:

oidctl connect=connect_string server=oidldapd instance=server_instance_number  
-server number_of_server_processes [configset=configset_number]
[host=virtual/host_name] [flags=' -p port_number -work 
maximum_number_of_worker_threads_per_server -debug debug_level 
-l change_logging'] start

Table A-3 Arguments for Starting a Directory Server by Using OIDCTL

Argument	Description
-debug debug_level	Specifies a debug level during Oracle directory server instance startup
-l change_logging	Turns replication change logging on and off. To turn it off, enter -l false. To turn it on, do any one of the following: omit the -l flag enter simply -l enter -l true Turning off change logging for a given node by specifying -l false has two drawbacks: it prevents replication of updates on that node to other nodes in the DRG, and it prevents application provisioning and synchronization of connected directories, because those two services require an active change log. The default, TRUE, permits replication, provisioning, and synchronization.
-p port_number	Specifies a port number during server instance startup. The default port number is 389.
-server server_processes	Specifies the number of server processes to start on this port
-sport	Specifies the SSL port number during server instance startup. Default port if not set is 636. See Also: The information about orclsslenable attribute in the section "Configuration Set Entry Schema Elements" in Oracle Internet Directory Administrator's Guide "Configuring SSL Parameters"in Oracle Internet Directory Administrator's Guide
-work threads_per_server	Specifies the maximum number of worker threads for this server
configset=configset_number	Configset number used to start the server. This defaults to configset0 if not set. This should be a number between 0 and 1000.
connect=connect_string	If you already have a tnsnames.ora file configured, then this is the net service name specified in that file, located in ORACLE_HOME/network/admin.
host=virtual/host_name	Specifies the virtual host or rack nodes on which to start the directory server
instance=instance_number	Instance number of the server to start. Should be a number between 1 and 1000.
server=oidldapd	Type of server to start (valid values are OIDLDAPD and OIDREPLD). This is not case-sensitive.
start	Starts the server specified in the server argument.

For example, to start a directory server instance whose net service name is dbs1, using configset5 at port 12000, with a debug level of 1024, an instance number 3, and in which change logging is turned off, type at the system prompt:

oidctl connect=dbs1 server=oidldapd instance=3 configset=5 flags='-p 12000  -debug 1024 -l ' start

When starting and stopping an Oracle directory server instance, the server name and instance number are mandatory, as are the commands start or stop. All other arguments are optional.

All keyword value pairs within the flags arguments must be separated by a single space.

Single quotes are mandatory around the flags.

The configset identifier defaults to zero (configset0) if not set.

Note: If you choose to use a port other than the default port (389 for non-secure usage or 636 for secure usage), you must tell the clients which port to use to locate the Oracle Internet Directory. If you use the default ports, clients can connect to the Oracle Internet Directory without referencing a port in their connect requests.

A.2.2.1.2 Stopping an Oracle Directory Server Instance

At the system prompt, type:

oidctl connect=connect_string server=oidldapd instance=server_instance_number stop

For example:

oidctl connect=dbs1 server=oidldapd instance=3 stop

A.2.2.2 Troubleshooting Directory Server Instance Startup

If the directory server fails to start, you can override all user-specified configuration parameters to start the directory server and then return the configuration sets to a workable state by using the ldapmodify operation.

To start the directory server by using its hard-coded default parameters instead of the configuration parameters stored in the directory, type at the system prompt:

oidctl connect=connect_string flags='-p port_number -f'

The -f option in the flags starts the server with hard-coded configuration values, overriding any defined configuration sets except for the values in configset0.

To see debug log files generated by the OID Control Utility, navigate to ORACLE_HOME/ldap/log.

A.2.2.3 Starting and Stopping an Oracle Directory Replication Server Instance

Use the OID Control Utility to start and stop Oracle directory replication server instances.

A.2.2.3.1 Starting an Oracle Directory Replication Server Instance

The syntax for starting the Oracle directory replication server is:

oidctl connect=connect_string server=oidrepld instance=server_instance_number
[configset=configset_number] flags= ' -p directory_server_port_number 
-d debug_level -h directory_server_host_name -m [true | false]  
-z transaction_size ' start

Table A-4 Arguments for Starting a Directory Replication Server by Using OIDCTL

Argument	Description
connect=connect_string	If you already have a tnsnames.ora file configured, then this is the name specified in that file, which is located in ORACLE_HOME/network/admin.
server=oidrepld	Type of server to start (valid values are OIDLDAPD and OIDREPLD). This is not case-sensitive.
instance=instance_number	Instance number of the server to start. Should be a number between 1 and 1000.
configset=configset_number	Configset number used to start the server. The default is configset0. This should be a number between 0 and 1000.
-p directory__port	Port number that the replication server uses to connect to the directory on TCP port directory_server_port_number. If you do not specify this option, the tool connects to the default port (389).
-d debug_level	Specifies a debug level during replication server instance startup
-h directory_host_name	Specifies the directory_server_host_name to which the replication server connects, rather than to the default host, that is, your local computer. directory_server_host_name can be a computer name or an IP address. (Replication server only)
-m [true|false]	Turns conflict resolution on and off. Valid values are true and false. The default is true. (Replication server only)
-z transaction_size	Specifies the number of changes applied in each replication update cycle. If you do not specify this, the number is determined by the Oracle directory server sizelimit parameter, which has a default setting of 1024. You can configure this latter setting.
start	Starts the server specified in the server argument.

For example, to start the replication server with an instance=1, at port 12000, with debugging set to 1024, type at the system prompt:

oidctl connect=dbs1 server=oidrepld instance=1 flags='-p 12000 -h eastsun11 -d 1024' start

When starting and stopping an Oracle directory replication server, the -h flag, which specifies the host name, is mandatory. All other flags are optional.

All keyword value pairs within the flags arguments must be separated by a single space.

Single quotes are mandatory around the flags.

The configset identifier defaults to zero (configset0) if not set.

Note: If you choose to use a port other than the default port (389 for non-secure usage or 636 for secure usage), you must tell the clients which port to use to locate the Oracle Internet Directory. If you use the default ports, clients can connect to the Oracle Internet Directory without referencing a port in their connect requests.

A.2.2.3.2 Stopping an Oracle Directory Replication Server Instance

At the system prompt, type:

oidctl connect=connect_string server=OIDREPLD instance=server_instance_number stop

For example:

oidctl connect=dbs1 server=oidrepld instance=1 stop

A.2.2.4 Starting the Oracle Directory Integration and Provisioning Server

The Oracle directory integration and provisioning server executable, odisrv, resides in the ORACLE_HOME/bin directory.

The way you start the directory integration and provisioning server depends on whether your installation is:

• A typical Oracle Internet Directory installation

  In this case, your installation includes, among other server and client components, the OID Monitor and the OID Control Utility. In such installations, you start and stop the directory integration and provisioning server by using these tools.

  
  

  Note: Although you can start the directory integration and provisioning server without using the OID Monitor and the OID Control Utility, Oracle Corporation recommends that you use them. This way, if the directory integration and provisioning server unexpectedly terminates, the OID Monitor automatically restarts it.

  
  

• An Oracle Directory Integration and Provisioning platform-only installation

  In this case, the way you start the directory integration and provisioning server depends on whether you are using the Oracle Directory Integration and Provisioning platform for high availability.

  • If you are using Oracle Directory Integration and Provisioning platform for high availability, then Oracle Corporation recommends that you start the directory integration and provisioning server by using the OID Monitor and the OID Control Utility. This requires configuring the tnsnames.ora file with the right host and SID to which the OID Monitor must connect.

  • If you are not using Oracle Directory Integration and Provisioning platform for high availability, then Oracle Corporation recommends that you start the directory integration and provisioning server without using the OID Monitor.

You can start the directory integration and provisioning server in either SSL mode for tighter security, or non-SSL mode. You need to use a connect string to connect to the database.

Note: When the Oracle directory integration and provisioning server is invoked in the default mode, it supports only the Oracle Directory Provisioning Integration Service, and not the Oracle Directory Synchronization Service.

A.2.2.4.1 Starting the Oracle Directory Integration and Provisioning Server by Using the OID Monitor and Control Utilities

To start the directory integration and provisioning server in non-SSL mode:

1. Be sure that OID Monitor is running. To verify this on UNIX, enter the following at the command line:

   ps -ef | grep oidmon
   
   

   If OID Monitor is not running, then start it by following the instructions in "The OID Monitor (oidmon) Syntax".

2. Start the directory integration and provisioning server by using the OID Control Utility. Do this by entering:

   oidctl [connect=connect_string] server=odisrv [instance=instance_number]
   [config=configuration_set_number] [flags="[host=hostname] [port=port_number]
   [grpID=group_identifier_of_provisioning_profile] [debug=debug_level] 
   [refresh=interval_between_refresh] [maxprofiles=number_of_profiles]
   [sslauth=ssl_mode ]"] start
   
   

   Table A-5 describes the arguments in this command.

Table A-5 Description of Arguments for Starting the Oracle Directory Integration and Provisioning Server

Argument	Description
connect=connect_string	If you already have a tnsnames.ora file configured, then this is the net service name specified in that file, located in ORACLE_HOME/network/admin
server=odisrv	Type of server to start. In this case, the server you are starting is odisrv. This is not case-sensitive. This argument is mandatory.
instance=instance_number	Specifies the instance number to assign to the directory integration and provisioning server. This instance number must be unique. OID Monitor verifies that the instance number is not already associated with a currently running instance of this server. If it is associated with a currently running instance, then OID Monitor returns an error message.
config=set_number	Specifies the number of the configuration set that the directory integration and provisioning server is to execute. This argument is mandatory.
host=host_name	Oracle directory server host name
port=port_number	Oracle directory server port number
debug=debug_level	The required debugging level of the directory integration and provisioning server. See the chapter about logging, auditing, and monitoring in Oracle Internet Directory Administrator's Guide.
refresh=refresh_interval	Specifies the interval, in minutes, between server refreshes for any changes in the integration profiles. The default is 2 minutes (Refresh=2).
grpID=profile_identifier	Specifies the group of profiles to be scheduled.
maxprofiles=number_of_profiles	Specifies the maximum number of profiles that can be executed concurrently for this server instance.
sslauth=ssl_mode	SSL modes: 0: SSL is not used—that is, non-SSL mode 1: SSL used for encryption only—that is, with no PKI authentication. A wallet is not used in this case. 2: SSL is used with one-way authentication. This mode requires you to specify a complete path name of an Oracle Wallet, including the file name itself, unlike other directory tools that expect only the wallet location. For example, in a server-only installation, or in a complete installation, you would enter something like this: oidctl server=odisrv [instance=instance_number] [configset=configset_number] [grpID=group_identifier_of_provisioning_profile] flags="host=myhost port=myport sslauth=2 In a client-only installation, you would enter something like this: odisrv [host=host_name] [port=port_number] config=configuration_set_number [instance=instance_number] [debug=debug_level] [refresh=interval_between_refresh] [maxprofiles=number_of_profiles] [refresh=interval_between_refresh] [maxprofiles=number_of_profiles] [sslauth=ssl_mode]

A.2.2.4.2 Starting the Oracle Directory Integration and Provisioning Server Without Using the OID Monitor and the OID Control Utility

In a client-only installation, where the OID Monitor and OID Control tools are not available, the Oracle directory integration and provisioning server can be started without OID Monitor or OID Control Utility, either in non-SSL mode or, for tighter security, in SSL mode. The parameters described in Table A-5 remain the parameters for each type of invocation.

To start the directory integration and provisioning server, enter the following at the command line:

odisrv [host=host_name] [port=port_number] config=configuration_set_number 
[instance=instance_number] [debug=debug_level] [refresh=interval_between_refresh]
[maxprofiles=number_of_profiles] [sslauth=ssl_mode]

A.2.2.5 Stopping the Oracle Directory Integration and Provisioning Server

You can use the OID Monitor and the OID Control utility to stop the directory integration and provisioning server:

1. Before you stop the directory integration and provisioning server, be sure that the OID Monitor is running. To verify this, enter the following at the command line:

   ps -ef | grep oidmon
   
   

   If OID Monitor is not running, then start it by following the instructions in "The OID Monitor (oidmon) Syntax".

2. Stop the directory integration and provisioning server, by entering:

   oidctl [connect=connect_string] server=odisrv instance=instance stop
   

Note: To run shell script tools on the Windows operating system, you need one of the following UNIX emulation utilities: Cygwin 1.3.2.2-1 or later. Visit this site: http://sources.redhat.com MKS Toolkit 6.1. Visit this site: http://www.datafocus.com/

A.2.2.6 Restarting Oracle Internet Directory Server Instances

When you want to refresh the server cache immediately, rather than at the next scheduled time, use the RESTART command. When the Oracle Internet Directory server restarts, it maintains the same parameters it had before it stopped.

To restart an Oracle Internet Directory server instance, at the system prompt, type:

oidctl connect=connect_string server={oidldapd|oidrepld|odisrv}  instance=server_instance_number  restart

OID Monitor must be running whenever you restart directory server instances.

If you try to contact a server that is not running, you receive from the SDK the error message 81—LDAP_SERVER_DOWN.

If you change a configuration set entry that is referenced by an active server instance, you must stop that instance and restart it to effect the changed value in the configuration set entry on that server instance. You can either issue the STOP command followed by the START command, or you can use the RESTART command. RESTART both stops and restarts the server instance.

For example, suppose that Oracle directory server instance1 is started, using configset3, and with the net service name dbs1. Further, suppose that, while instance1 is running, you change one of the attributes in configset3. To enable the change in configset3 to take effect on instance1, you enter the following command:

oidctl connect=dbs1 server=oidldapd instance=1 restart

If there are more than one instance of the Oracle directory server running on that node using configset3, then you can restart all the instances at once by using the following command syntax:

oidctl connect=dbs1 server=oidldapd restart

Note that this command restarts all the instances running on the node, whether they are using configset3 or not.

Important Note: During the restart process, clients cannot access the Oracle directory server instance. However, the process takes only a few seconds to execute.

A.2.2.7 Starting and Stopping Directory Servers on a Virtual Host or an Oracle Application Server Cluster (Identity Management)

When starting a directory server, a directory replication server, or a directory integration and provisioning server, use the host parameter to specify the virtual host name.

Starting and Stopping a Directory Server

To start a directory server on a virtual host:

oidctl [connect=connect_string] host=virtual_host_name server=oidldapd 
instance=instance_number configset=configset_number flags= "..." start

To stop a directory server on a virtual host:

oidctl host=virtual_host_name server=oidldapd instance=instance_number stop

Starting and Stopping a Directory Replication Server

To start a directory replication server on a virtual host:

oidctl [connect=connect_string] host=virtual_host_name server=oidrepld instance=instance_number flags= "..." start

To stop a directory replication server on a virtual host:

oidctl host=virtual_host_name server=oidrepld instance=instance_number stop

Starting and Stopping a Directory Integration and Provisioning Server

To start a directory integration and provisioning server on a virtual host:

oidctl [connect=connect_string] host=virtual_host_name server=odisrv
instance=instance_number configset=configset_number flags= "..." start

To stop a directory integration and provisioning server on a virtual host:

oidctl host=virtual/host_name server=odisrv instance=instance_number stop

When the directory server is started to run on the virtual host, it binds and listens to requests on the specified LDAP port on the IP address or IP addresses that correspond to the virtual host only.

When communicating with the directory server, the directory replication server uses the virtual host name. Further, the replicaID attribute that represents the unique replication identification for the Oracle Internet Directory node is generated once. It is independent of the host name and hence requires no special treatment in an Oracle Application Server Cold Failover Cluster.

When communicating with the directory server, the directory integration and provisioning server uses the virtual host name.

A.3 Entry and Attribute Management Command-Line Tools Syntax

This section tells you how to use the following tools:

• The Catalog Management Tool (catalog.sh) Syntax

• ldapadd Syntax

• ldapbind Syntax

• ldapcompare Syntax

• ldapdelete Syntax

• ldapmoddn Syntax

• ldapmodify Syntax

• ldapmodifymt Syntax

• ldapsearch Syntax

  
  

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

  
  

A.3.1 The Catalog Management Tool (catalog.sh) Syntax

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

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 Manager. However, if the attribute already exists, then you can index it only by using the Catalog Management tool.

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

Caution: Do not use the catalog.sh -delete option 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.

Note: To run shell script tools on the Windows operating system, you need one of the following UNIX emulation utilities: Cygwin 1.3.2.2-1 or later. Visit this site: http://sources.redhat.com MKS Toolkit 6.1. Visit this site: http://www.datafocus.com

The Catalog Management tool uses this syntax:

catalog.sh -connect connect_string {-add|-delete} {-attr attr_name|-file file_name}

Table A-6 Arguments for the Catalog Management Tool (catalog.sh)

Argument	Description
-connect connect_string	Specifies the connect string to connect to the directory database. This argument is mandatory. See Also: Oracle9i Net Services Administrator's Guide in the Oracle Database Documentation Library
-add -attr attr_name	Indexes the specified attribute
-delete -attr attr_name	Drops the index from the specified attribute
-add -file file_name	Indexes attributes (one for each line) in the specified file
-delete -file file_name	Drops the indexes from the attributes in the specified file

When you enter the catalog.sh command, the following message appears:

This tool can only be executed if you know the OiD user password.
Enter OiD password:

If you enter the correct password, the command is executed. If you give an incorrect password, the following message is displayed:

Cannot execute this tool

To effect the changes after running the Catalog Management tool, stop, then restart, the Oracle directory server.

See Also: "The OID Control Utility (oidctl) Syntax" and for instructions on starting and restarting directory servers. Note that OID Monitor must be running before you start a directory server. "The OID Monitor (oidmon) Syntax" for information about starting OID Monitor The section about matching rules in the schema appendix of Oracle Internet Directory Administrator's Guide

A.3.2 ldapadd Syntax

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

See Also: "Adding Configuration Set Entries by Using ldapadd" in Oracle Internet Directory Administrator's Guide for an explanation of using ldapadd to configure a server with an input file

ldapadd uses this syntax:

ldapadd [arguments] -f file_name

where file_name is the name of an LDIF file written with the specifications explained in the section "LDAP Data Interchange Format (LDIF) Syntax".

The following example adds the entry specified in the LDIF file my_ldif_file.ldi:

ldapadd -p 389 -h myhost -f my_ldif_file.ldi

Table A-7 Arguments for ldapadd

Optional Arguments	Description
-b	Specifies that you have included binary file names in the file, which are preceded by a forward slash character. The tool retrieves the actual values from the file referenced.
-c	Tells ldapadd to proceed in spite of errors. The errors will be reported. (If you do not use this option, ldapadd stops when it encounters an error.)
-D binddn	When authenticating to the directory, specifies doing so as the entry specified in binddn. This is the DN of the user seeking authentication. Use this with the -w password option.
-E character_set	Specifies native character set encoding. See the appendix about globalization support in Oracle Internet Directory Administrator's Guide.
-f file_name	Specifies the input name of the LDIF format import data file. For a detailed explanation of how to format an LDIF file, see "LDAP Data Interchange Format (LDIF) Syntax".
-h ldaphost	Connects to ldaphost, rather than to the default host, that is, your local computer. ldaphost can be a computer name or an IP address.
-K	Same as -k, but performs only the first step of the Kerberos bind
-k	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.
-M	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	Shows what would occur without actually performing the operation
-O ref_hop_limit	Specifies the number of referral hops that a client should process. The default value is 5.
-p directory_port	Connects to the directory on TCP port directory_port. If you do not specify this option, the tool connects to the default port (389).
-P wallet_password	Specifies wallet password required for one-way or two-way SSL connections
-U SSLAuth	Specifies SSL authentication mode: 1 for no authentication required 2 for one way authentication required 3 for two way authentication required
-v	Specifies verbose mode
-V ldap_version	Specifies the version of the LDAP protocol to use. The default value is 3, which causes the tool to use the LDAP v3 protocol. A value of 2 causes the tool to use the LDAP v2 protocol.
-w password	Provides the password required to connect
-W wallet_location	Specifies wallet location required for one-way or two-way SSL connections. For example, on UNIX, you could set this parameter as follows: -W "file://home/my_dir/my_wallet". On Windows NT, you could set this parameter as follows: -W "file:C:\my_dir\my_wallet".
-X dsml_file	Specifies the input name of the DSML format import data file.

A.3.3 ldapaddmt Syntax

ldapaddmt is like ldapadd: It enables you to add entries, their object classes, attributes, and values to the directory. It is unlike ldapadd in that it supports multiple threads for adding entries concurrently.

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

ldapaddmt uses this syntax:

ldapaddmt -T number_of_threads -h host -p port -f file_name

where file_name is the name of an LDIF file written with the specifications explained in the section "LDAP Data Interchange Format (LDIF) Syntax".

The following example uses five concurrent threads to process the entries in the file myentries.ldif.

ldapaddmt -T 5 -h node1 -p 3000 -f myentries.ldif

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

Table A-8 Arguments for ldapaddmt

Optional Arguments	Description
-b	Specifies that you have included binary file names in the data file, which are preceded by a forward slash character. The tool retrieves the actual values from the file referenced.
-c	Tells the tool to proceed in spite of errors. The errors will be reported. (If you do not use this option, the tool stops when it encounters an error.)
-D binddn	When authenticating to the directory, specifies doing so as the entry is specified in binddn—that is, the DN of the user seeking authentication. Use this with the -w password option.
-E character_set	Specifies native character set encoding. See the appendix about globalization support in Oracle Internet Directory Administrator's Guide.
-h ldap_host	Connects to ldaphost, rather than to the default host, that is, your local computer. ldaphost can be a computer name or an IP address.
-K	Same as -k, but performs only the first step of the kerberos bind
-k	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.
-M	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	Shows what would occur without actually performing the operation.
-O ref_hop_limit	Specifies the number of referral hops that a client should process. The default value is 5.
-p ldapport	Connects to the directory on TCP port ldapport. If you do not specify this option, the tool connects to the default port (389).
-P wallet_password	Specifies wallet password required for one-way or two-way SSL connections
-T	Sets the number of threads for concurrently processing entries
-U SSLAuth	Specifies SSL Authentication Mode: 1 for no authentication required 2 for one way authentication required 3 for two way authentication required
-v	Specifies verbose mode
-V ldap_version	Specifies the version of the LDAP protocol to use. The default value is 3, which causes the tool to use the LDAP v3 protocol. A value of 2 causes the tool to use the LDAP v2 protocol.
-w password	Provides the password required to connect
-W wallet_location	Specifies wallet location required for one-way or two-way SSL connections. For example, on UNIX, you could set this parameter as follows: -W "file://home/my_dir/my_wallet". On Windows NT, you could set this parameter as follows: -W "file:C:\my_dir\my_wallet".
-X dsml_file	Specifies the input name of the DSML format import data file.

A.3.4 ldapbind Syntax

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

ldapbind uses this syntax:

ldapbind [arguments]

Table A-9 Arguments for ldapbind

Optional Arguments	Description
-D binddn	When authenticating to the directory, specifies doing so as the entry specified in binddn—that is, the DN of the user seeking authentication. Use this with the -w password option.
-E character_set	Specifies native character set encoding. See the appendix about globalization support in Oracle Internet Directory Administrator's Guide.
-h ldaphost	Connects to ldaphost, rather than to the default host, that is, your local computer. ldaphost can be a computer name or an IP address.
-n	Shows what would occur without actually performing the operation.
-p ldapport	Connects to the directory on TCP port ldapport. If you do not specify this option, the tool connects to the default port (389).
-P wallet_password	Specifies the wallet password required for one-way or two-way SSL connections.
-U SSLAuth	Specifies SSL authentication mode: 1 for no authentication required 2 for one way authentication required 3 for two way authentication required.
-V ldap_version	Specifies the version of the LDAP protocol to use. The default value is 3, which causes the tool to use the LDAP v3 protocol. A value of 2 causes the tool to use the LDAP v2 protocol.
-w password	Provides the password required to connect.
-W wallet_location	Specifies wallet location required for one-way or two-way SSL connections. For example, on UNIX, you could set this parameter as follows: -W file://home/my_dir/my_wallet. On Windows NT, you could set this parameter as follows: -W "file:C:\my_dir\my_wallet".
-O sasl_properties	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 sasl_mechanism	Specifies a SASL mechanism. These mechanisms are supported: Y "DIGEST-MD5" Y "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	Specifies a SASL realm.

Table A-10 Optional Arguments

Optional Arguments	Description
-O sasl_properties	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 sasl_mechanism	Specifies a SASL mechanism. These mechanisms are supported: Y "DIGEST-MD5" Y "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	Specifies a SASL Realm.

A.3.5 ldapcompare Syntax

The ldapcompare command-line tool enables you to match attribute values you specify in the command line with the attribute values in the directory entry.

ldapcompare uses this syntax:

ldapcompare [arguments] 

The following example tells you whether Person Nine's title is associate.

ldapcompare -p 389 -h myhost -b "cn=Person Nine,ou=EuroSInet Suite,o=IMC,c=US" -a title -v associate

Table A-11 Arguments for ldapcompare

Optional Arguments	Description
-a attribute_name	Specifies the attribute on which to perform the compare. This argument is mandatory.
-b basedn	Specifies the distinguished name of the entry on which to perform the compare. This argument is mandatory.
-v attribute_value	Specifies the attribute value to compare. This argument is mandatory.
-D binddn	When authenticating to the directory, specifies doing so as the entry is specified in binddn—that is, the DN of the user seeking authentication. Use this with the -w password option.
-d debug_level	Sets the debugging level. See the chapter about logging, auditing, and monitoring in Oracle Internet Directory Administrator's Guide.
-E character_set	Specifies native character set encoding. See the appendix about globalization support in Oracle Internet Directory Administrator's Guide.
-f file_name	Specifies the input file name
-h ldaphost	Connects to ldaphost, rather than to the default host, that is, your local computer. ldaphost can be a computer name or an IP address.
-M	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	Specifies the number of referral hops that a client should process. The default value is 5.
-p ldapport	Connects to the directory on TCP port ldapport. If you do not specify this option, the tool connects to the default port (389).
-P wallet_password	Specifies wallet password required for one-way or two-way SSL connections
-U SSLAuth	Specifies SSL authentication mode: 1 for no authentication required 2 for one way authentication required 3 for two way authentication required
-V ldap_version	Specifies the version of the LDAP protocol to use. The default value is 3, which causes the tool to use the LDAP v3 protocol. A value of 2 causes the tool to use the LDAP v2 protocol.
-w password	Provides the password required to connect
-W wallet_location	Specifies wallet location required for one-way or two-way SSL connections. For example, on UNIX, you could set this parameter as follows: -W "file://home/my_dir/my_wallet". On Windows NT, you could set this parameter as follows: -W "file:C:\my_dir\my_wallet".

A.3.6 ldapdelete Syntax

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

ldapdelete uses this syntax:

ldapdelete [arguments] ["entry_DN" | -f input_file_name]

Note: If you specify the entry DN, then do not use the -f option.

The following example uses port 389 on a host named myhost.

ldapdelete -p 389 -h myhost "ou=EuroSInet Suite, o=IMC, c=US"

Table A-12 Arguments for ldapdelete

Optional Argument	Description
-D binddn	When authenticating to the directory, uses a full DN for the binddn parameter—that is, the DN of the user seeking authentication; typically used with the -w password option.
-d debug_level	Sets the debugging level. See "Setting Debug Logging Levels by Using the OID Control Utility" in Oracle Internet Directory Administrator's Guide.
-E character_set	Specifies native character set encoding. See the appendix about globalization support in Oracle Internet Directory Administrator's Guide.
-f input_file_name	Specifies the input file name
-h ldaphost	Connects to ldaphost, rather than to the default host, that is, your local computer. ldaphost can be a computer name or an IP address.
-k	Authenticates using authentication instead of simple authentication. To enable this option, you must compile with Kerberos defined. You must already have a valid ticket granting ticket.
-M	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	Shows what would be done, but doesn't actually delete
-O ref_hop_limit	Specifies the number of referral hops that a client should process. The default value is 5.
-p ldapport	Connects to the directory on TCP port ldapport. If you do not specify this option, the tool connects to the default port (389).
-P wallet_password	Specifies wallet password required for one-way or two-way SSL connections
-U SSLAuth	Specifies SSL authentication mode: 1 for no authentication required 2 for one way authentication required 3 for two way authentication required
-v	Specifies verbose mode
-V ldap_version	Specifies the version of the LDAP protocol to use. The default value is 3, which causes the tool to use the LDAP v3 protocol. A value of 2 causes the tool to use the LDAP v2 protocol.
-w password	Provides the password required to connect.
-W wallet_location	Specifies wallet location required for one-way or two-way SSL connections. For example, on UNIX, you could set this parameter as follows: -W "file://home/my_dir/my_wallet". On Windows NT, you could set this parameter as follows: -W "file:C:\my_dir\my_wallet".

A.3.7 ldapmoddn Syntax

The ldapmoddn command-line tool enables you to modify the DN or RDN of an entry.

ldapmoddn uses this syntax:

ldapmoddn [arguments]

The following example uses ldapmoddn to modify the RDN component of a DN from cn=mary smith to cn=mary jones. It uses port 389, and a host named myhost.

ldapmoddn -p 389 -h myhost -b "cn=mary smith,dc=Americas,dc=imc,dc=com" -R "cn=mary jones"

Table A-13 Arguments for ldapmoddn

Argument	Description
-b basedn	Specifies DN of the entry to be moved. This argument is mandatory.
-D binddn	When authenticating to the directory, do so as the entry is specified in binddn. This is the DN of the user seeking authentication. Use this with the -w password option.
-E character_set	Specifies native character set encoding. See the appendix about globalization support in Oracle Internet Directory Administrator's Guide.
-f file_name	Specifies the input file name
-h ldaphost	Connects to ldaphost, rather than to the default host, that is, your local computer. ldaphost can be a computer name or an IP address.
-M	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 newparent	Specifies new parent of the RDN. Either this argument or the -R argument must be specified.
-O ref_hop_limit	Specifies the number of referral hops that a client should process. The default value is 5.
-p ldapport	Connects to the directory on TCP port ldapport. If you do not specify this option, the tool connects to the default port (389).
-P wallet_password	Specifies wallet password required for one-way or two-way SSL connections
-r	Specifies that the old RDN is not retained as a value in the modified entry. If this argument is not included, the old RDN is retained as an attribute in the modified entry.
-R newrdn	Specifies new RDN. Either this argument or the -N argument must be specified.
-U SSLAuth	Specifies SSL authentication mode: 1 for no authentication required 2 for one way authentication required 3 for two way authentication required
-V ldap_version	Specifies the version of the LDAP protocol to use. The default value is 3, which causes the tool to use the LDAP v3 protocol. A value of 2 causes the tool to use the LDAP v2 protocol.
-w password	Provides the password required to connect.
-W wallet_location	Specifies wallet location required for one-way or two-way SSL connections. For example, on UNIX, you could set this parameter as follows: -W "file://home/my_dir/my_wallet". On Windows NT, you could set this parameter as follows: -W "file:C:\my_dir\my_wallet".

A.3.8 ldapmodify Syntax

The ldapmodify tool enables you to act on attributes.

ldapmodify uses this syntax:

ldapmodify [arguments] -f file_name

where file_name is the name of an LDIF file written with the specifications explained the section "LDAP Data Interchange Format (LDIF) Syntax".

The list of arguments in the following table is not exhaustive. These arguments are all optional.

Table A-14 Arguments for ldapmodify

Argument	Description
-a	Denotes that entries are to be added, and that the input file is in LDIF format.
-b	Specifies that you have included binary file names in the data file, which are preceded by a forward slash character.
-c	Tells ldapmodify to proceed in spite of errors. The errors will be reported. (If you do not use this option, ldapmodify stops when it encounters an error.)
-D binddn	When authenticating to the directory, specifies doing so as the entry is specified in binddn—that is, the DN of the user seeking authentication. Use this with the -w password option.
-E character_set	Specifies native character set encoding. See the appendix about globalization support in Oracle Internet Directory Administrator's Guide.
-h ldaphost	Connects to ldaphost, rather than to the default host, that is, your local computer. ldaphost can be a computer name or an IP address.
-M	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	Shows what would occur without actually performing the operation.
-o log_file_name	Can be used with the -c option to write the erroneous LDIF entries in the logfile. You must specify the absolute path for the log file name.
-O ref_hop_limit	Specifies the number of referral hops that a client should process. The default value is 5.
-p ldapport	Connects to the directory on TCP port ldapport. If you do not specify this option, the tool connects to the default port (389).
-P wallet_password	Specifies wallet password required for one-way or two-way SSL connections
-U SSLAuth	Specifies SSL authentication mode: 1 for no authentication required 2 for one way authentication required 3 for two way authentication required
-v	Specifies verbose mode
-V ldap_version	Specifies the version of the LDAP protocol to use. The default value is 3, which causes the tool to use the LDAP v3 protocol. A value of 2 causes the tool to use the LDAP v2 protocol.
-w password	Overrides the default, unauthenticated, null bind. To force authentication, use this option with the -D option.
-W wallet_location	Specifies wallet location required for one-way or two-way SSL connections. For example, on UNIX, you could set this parameter as follows: -W "file://home/my_dir/my_wallet". On Windows NT, you could set this parameter as follows: -W "file:C:\my_dir\my_wallet".

To run modify, delete, and modifyrdn operations using the -f flag, use LDIF for the input file format (see "LDAP Data Interchange Format (LDIF) Syntax") with the specifications noted in this section:

If you are making several modifications, then, between each modification you enter, add a line that contains a hyphen (-) only. For example:

dn: cn=Barbara Fritchy,ou=Sales,o=Oracle,c=US
changetype: modify
add: work-phone
work-phone: [phone]
work-phone: [phone]
-
delete: home-fax

Unnecessary space characters in the LDIF input file, such as a space at the end of an attribute value, will cause the LDAP operations to fail.

Line 1: Every change record has, as its first line, the literal dn: followed by the DN value for the entry, for example:

dn:cn=Barbara Fritchy,ou=Sales,o=Oracle,c=US

Line 2: Every change record has, as its second line, the literal changetype: followed by the type of change (add, delete, modify, modrdn), for example:

changetype: modify

or

changetype: modrdn

Format the remainder of each record according to the following requirements for each type of change:

• changetype: add

  Uses LDIF format (see "LDAP Data Interchange Format (LDIF) Syntax").

• changetype: modify

  The lines that follow this changetype consist of changes to attributes belonging to the entry that you identified previously in Line 1. You can specify three different types of attribute modifications—add, delete, and replace—which are explained next:

  • Add attribute values. This option to changetype modify adds more values to an existing multi-valued attribute. If the attribute does not exist, it adds the new attribute with the specified values:

    add: attribute name
    attribute name: value1
    attribute name: value2...
    
    

    For example:

    dn:cn=Barbara Fritchy,ou=Sales,o=Oracle,c=US
    changetype: modify
    add: work-phone
    work-phone: [phone]
    work-phone: [phone]
    

  • Delete values. If you supply only the delete line, all the values for the specified attribute are deleted. Otherwise, if you specify an attribute line, you can delete specific values from the attribute:

    delete: attribute name
    [attribute name: value1]
    dn: cn=Barbara Fritchy,ou=Sales,o=Oracle,c=US
    changetype: modify
    delete: home-fax
    
    

  • Replace values. Use this option to replace all the values belonging to an attribute with the new specified set:

    replace: attribute name
    [attribute name: value1 ...]
    
    

    If you do not provide any attributes with replace, the directory adds an empty set. It then interprets the empty set as a delete request, and complies by deleting the attribute from the entry. This is useful if you want to delete attributes that may or may not exist. For example:

    dn: cn=Barbara Fritchy,ou=Sales,o=Oracle,c=US 
    changetype: modify
    replace: work-phone
    work-phone: [phone]
    

• changetype:delete

  This change type deletes entries. It requires no further input, since you identified the entry in Line 1 and specified a changetype of delete in Line 2.

  For example:

  dn: cn=Barbara Fritchy,ou=Sales,o=Oracle,c=US 
  changetype: delete
  

• changetype:modrdn

  The line following the change type provides the new relative distinguished name using this format:

  newrdn: RDN
  

  For example:

  dn: cn=Barbara Fritchy,ou=Sales,o=Oracle,c=US
  changetype: modrdn
  newrdn: cn=Barbara Fritchy-Blomberg
  
  

To specify an attribute as single-valued, include the keyword SINGLE-VALUE in the attribute definition entry in the LDIF file. Surround it with white space.

Example: Using ldapmodify to Add an Attribute

This example adds a new attribute called myAttr. The LDIF file for this operation is:

dn: cn=subschemasubentry 
changetype: modify 
add: attributetypes 
attributetypes: (1.2.3.4.5.6.7 NAME 'myAttr' DESC 'New attribute definition' EQUALITY caseIgnoreMatch SYNTAX
'1.3.6.1.4.1.1466.115.121.1.15' ) 

On the first line, enter the DN specifying where this new attribute is to be located. All attributes and object classes they are stored in cn=subschemasubentry.

The second and third lines show the proper format for adding a new attribute.

The last line is the attribute definition itself. The first part of this is the object identifier number: 1.2.3.4.5.6.7. It must be unique among all other object classes and attributes. Next is the NAME of the attribute. In this case the attribute NAME is myAttr. It must be surrounded by single quotes. Next is a description of the attribute. Enter whatever description you want between single quotes. At the end of this attribute definition in this example are optional formatting rules to the attribute. In this case we are adding a matching rule of EQUALITY caseIgnoreMatch and a SYNTAX of Directory String. This example uses the object ID number of 1.3.6.1.4.1.1466.115.121.1.15 instead of the SYNTAXES name which is Directory String.

Put your attribute information in a file formatted like this example. Then run the following command to add the attribute to the schema of your Oracle directory server.

ldapmodify -h yourhostname -p 389 -D "orcladmin" -w "welcome" -v -f /tmp/newattr.ldif 

This ldapmodify command assumes that your Oracle directory server is running on port 389, that your super user account name is orcladmin, that your super user password is welcome and that the name of your LDIF file is newattr.ldif. Substitute the host name of your computer where you see yourhostname.

If you are not in the directory where the LDIF file is located, then you must enter the full directory path to the file at the end of your command. This example assumes that your LDIF file is located in the /tmp directory.

A.3.9 ldapmodifymt Syntax

The ldapmodifymt command-line tool enables you to modify several entries concurrently.

ldapmodifymt uses this syntax:

ldapmodifymt -T number_of_threads [arguments] -f file_name

where file_name is the name of an LDIF file written with the specifications explained the section "LDAP Data Interchange Format (LDIF) Syntax".

See Also: "ldapmodify Syntax" for additional formatting specifications used by ldapmodifymt

The following example uses five concurrent threads to modify the entries in the file myentries.ldif.

ldapmodifymt -T 5 -h node1 -p 3000 -f myentries.ldif

Note: The ldapmodifymt tool logs error messages in the file add.log, which is located in the directory where you are running the command.

The arguments in the following table are all optional.

Table A-15 Arguments for ldapmodifymt

Argument	Description
-a	Denotes that entries are to be added, and that the input file is in LDIF format. (If you are running ldapadd, this flag is not required.)
-b	Specifies that you have included binary file names in the data file, which are preceded by a forward slash character.
-c	Tells ldapmodify to proceed in spite of errors. The errors will be reported. (If you do not use this option, ldapmodify stops when it encounters an error.)
-D binddn	When authenticating to the directory, specifies doing so as the entry is specified in binddn—that is, the DN of the user seeking authentication. Use this with the -w password option.
-E character_set	Specifies native character set encoding. See the appendix about globalization support in Oracle Internet Directory Administrator's Guide.
-h ldaphost	Connects to ldaphost, rather than to the default host, that is, your local computer. ldaphost can be a computer name or an IP address.
-M	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	Shows what would occur without actually performing the operation.
-O ref_hop_limit	Specifies the number of referral hops that a client should process. The default value is 5.
-p ldapport	Connects to the directory on TCP port ldapport. If you do not specify this option, the tool connects to the default port (389).
-P wallet_password	Specifies wallet password required for one-way or two-way SSL connections
-T	Sets the number of threads for concurrently processing entries
-U SSLAuth	Specifies SSL authentication mode: 1 for no authentication required 2 for one way authentication required 3 for two way authentication required
-v	Specifies verbose mode
-V ldap_version	Specifies the version of the LDAP protocol to use. The default value is 3, which causes the tool to use the LDAP v3 protocol. A value of 2 causes the tool to use the LDAP v2 protocol.
-w password	Overrides the default, unauthenticated, null bind. To force authentication, use this option with the -D option.
-W wallet_location	Specifies wallet location required for one-way or two-way SSL connections. For example, on UNIX, you could set this parameter as follows: -W "file://home/my_dir/my_wallet". On Windows NT, you could set this parameter as follows: -W "file:C:\my_dir\my_wallet".

A.3.10 ldapsearch Syntax

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

The ldapsearch tool uses this syntax:

ldapsearch [arguments] filter [attributes]

The filter format must be compliant with RFC-2254.

See Also: RFC-2254 available at http://www.ietf.org for further information about the standard for the filter format

Separate attributes with a space. If you do not list any attributes, all attributes are retrieved.

Note: The ldapsearch tool does not generate LDIF output by default. To generate LDIF output from the ldapsearch command-line tool, use the -L flag. Various UNIX shells interpret some characters—for example, asterisks (*)—as special characters. Depending on the shell you are using, you may need to escape these characters.

Table A-16 Arguments for ldapsearch

Argument	Description
-b basedn	Specifies the base DN for the search. This argument is mandatory.
-s scope	This argument is mandatory. Specifies search scope: base, one, or sub 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 Level: Limits your search to all entries beginning one level down from the root of your search Subtree: Searches entries within the entire subtree, including the root of your search
-A	Retrieves attribute names only (no values)
-a deref	Specifies alias dereferencing: never, always, search, or find
-B	Allows printing of non-ASCII values
-D binddn	When authenticating to the directory, specifies doing so as the entry specified in binddn—that is, the DN of the user seeking authentication. Use this with the -w password option.
-d debug_level	Sets debugging level to the level specified (see the chapter about logging, monitoring, and auditing in Oracle Internet Directory Administrator's Guide).
-E character_set	Specifies native character set encoding. See the appendix about globalization support inOracle Internet Directory Administrator's Guide.
-f file	Performs sequence of searches listed in file.
-F sep	Printssep instead of = between attribute names and values
-h ldaphost	Connects to ldaphost, rather than to the default host, that is, your local computer. ldaphost can be a computer name or an IP address.
-L	Prints entries in LDIF format (-B is implied).
-l timelimit	Specifies maximum time (in seconds) to wait for ldapsearch command to complete
-M	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	Shows what would be done without actually searching
-O ref_hop_limit	Specifies the number of referral hops that a client should process. The default value is 5.
-p ldapport	Connects to the directory on TCP port ldapport. If you do not specify this option, the tool connects to the default port (389).
-P wallet_password	Specifies wallet password required for one-way or two-way SSL connections
-S attr	Sorts the results by attribute attr.
-t	Writes to files in /tmp.
-u	Includes user friendly entry names in the output
-U SSLAuth	Specifies the SSL authentication mode: 1 for no authentication required 2 for one way authentication required 3 for two way authentication required
-v	Specifies verbose mode
-w passwd	Specifies bind passwd for simple authentication
-W wallet_location	Specifies wallet location required for one-way or two-way SSL connections. For example, on UNIX, you could set this parameter as follows: -W "file://home/my_dir/my_wallet". On Windows NT, you could set this parameter as follows: -W "file:C:\my_dir\my_wallet".
-z sizelimit	Specifies maximum number of entries to retrieve
-X	Prints the entries in DSML v1 format.

A.3.10.1 Examples of ldapsearch Filters

Study the following examples to see how to build your own search commands.

A.3.10.1.1 Example 1: Base Object Search

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

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

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

A.3.10.1.2 Example 2: One-Level Search

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

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

A.3.10.1.3 Example 3: Subtree Search

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

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

A.3.10.1.4 Example 4: Search Using Size Limit

The following example actually retrieves only two entries, even if there are more than two matches.

ldapsearch -h myhost -p 389 -z 2 -b "ou=Benefits,ou=HR,ou=Americas,o=IMC,c=US" -s one "objectclass=*"

A.3.10.1.5 Example 5: Search with Required Attributes

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

ldapsearch -p 389 -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:

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

A.3.10.1.6 Example 6: Search 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.

ldapsearch -p 389 -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:

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

A.3.10.1.7 Example 7: Searching for All User Attributes and Specified Operational Attributes

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

ldapsearch -p 389 -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:

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

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

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

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

A.3.10.1.8 Other Examples:

Each of the following examples searches on port 389 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 389 -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 389 -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 389 -h sun1 -b "ou=hr, o=acme, c=us" -s subtree "(&(objectclass=orcl*)(cn=foo*))"

The following example searches for entries in which the common name (cn) is not foo.

ldapsearch -p 389 -h sun1 -b "ou=hr, o=acme, c=us" -s subtree "(!(cn=foo))"

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

ldapsearch -p 389 -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 389 -h sun1 -b "ou=hr, o=acme, c=us" -s subtree "employeenumber<=10000"

A.4 Oracle Directory Integration and Provisioning Platform Command-Line Tools Syntax

This section contains these topics:

• The Directory Integration and Provisioning Assistant (dipassistant) Syntax

• The schemasync Tool Syntax

• The Oracle Directory Integration and Provisioning Server Registration Tool (odisrvreg)

• Syntax for Provisioning Subscription Tool (oidprovtool)

A.4.1 The Directory Integration and Provisioning Assistant (dipassistant) Syntax

The Directory Integration and Provisioning Assistant (dipassistant) is a command-line tool for administering the Oracle directory integration and provisioning server. The syntax for the Directory Integration and Provisioning Assistant is:

dipassistant [-gui | command] [-help]

command := createprofile [cp] 
| createprofilelike [cpl]
| modifyprofile [mp]
| deleteprofile [dp]
| listprofiles[lp | lsprof]
| showprofile[sp]
| expressconfig[ec]
| bootstrap [bs]
| wpasswd [wp]
| chgpasswd [cpw]
| reassociate [rs]
 

For help on a particular command, enter:

dipassistant command -help
 

Table A-17 lists the tasks you can perform with the Directory Integration and Provisioning Assistant. It also points you to instructions for performing each task.

Table A-17 Summary of Functionality of the Directory Integration and Provisioning Assistant

Tasks	Commands	More Information
Use the Oracle Directory Integration and Provisioning Server Administration tool, which is the graphical version of the Directory Integration and Provisioning Assistant	-gui	The chapter about tools in Oracle Identity Management Integration Guide.
Create, modify, or delete a synchronization profile	createprofile createprofilelike modifyprofile deleteprofile	"Creating, Modifying, and Deleting Synchronization Profiles"
See all the profile names in Oracle Internet Directory	listprofiles	"Listing All Synchronization Profiles in Oracle Internet Directory"
See the details of a specific profile	showprofile	"Viewing the Details of a Specific Synchronization Profile"
Creates and configures import and export profiles for synchronization with Microsoft Active Directory	expressconfig	"Performing an Express Configuration of the Active Directory Connector Profiles"
Make Oracle Internet Directory and the connected directory identical before beginning synchronization	bootstrap	"Bootstrapping a Directory by Using the Directory Integration and Provisioning Assistant"
Set the wallet password that the Oracle directory integration and provisioning server later uses to connect to Oracle Internet Directory	wpasswd	"Setting the Wallet Password for the Oracle Directory Integration and Provisioning Server"
Reset the password of the administrator of the Oracle Directory Integration Platform	chgpasswd	"Changing the Password of the Administrator of Oracle Directory Integration and Provisioning Platform"
Move integration profiles from one identity management node to another	reassociate	"Moving an Integration Profile to a Different Identity Management Node"

A.4.1.1 Creating, Modifying, and Deleting Synchronization Profiles

The syntax for creating, modifying, or deleting synchronization profiles by using the Directory Integration and Provisioning Assistant is:

dipassistant createprofile [-h hostName] [-p port] [-D bindDn] [-w password] -f fileName -configset Configset Number

dipassistant createprofilelike [-h hostName] [-p port] [-D bindDn] [-w password] -profile origProfName -newprofile newProfName

dipassistant modifyprofile [-h hostName] [-p port] [-D bindDn] [-w password] 
{-f fileName | -profile profName [-updlcn] } [propName1=value] [propName2=value]...

dipassistant deleteprofile -profile profName [-h hostName] [-p port] [-D bindDn] [-w password] [-configset Configset Number]

Table A-18 describes the parameters for creating, modifying, and deleting synchronization profiles by using the Directory Integration and Provisioning Assistant.

Table A-18 Parameters for Creating, Modifying, and Deleting Synchronization Profiles by Using the Directory Integration and Provisioning Assistant

Parameter	Description
-h | -host	Host where Oracle Internet Directory is running. The default value is the name of the local host.
-p | -port	Port at which Oracle Internet Directory was started. The default is 389.
-D | -dn	The bind DN to be used in identifying to the directory. The default value is the DN of the Oracle Directory Integration and Provisioning platform administrator.
-w | -passwd	The password of the bind DN to be used while binding to the directory.
-f | -file	The configuration file containing the profile parameters. See Also: Table A-19 for a list of parameters and their description
-configset	An integer greater than 0 that represents the configuration set with which to associate the profile.
-profile	A text string representing the name of profile to be modified, deleted, or used as a template for creating a new profile.
-newProfile | -name	A text string representing the name of profile to be created in Oracle Internet Directory.
-updlcn	Updates the last applied changed number in the specified profile

The following example uses a configuration file named import.profile to create a new profile and associate the new profile with configuration set 1:

dipassistant createprofile -h myhost -p 3060 -D cn=dipadmin -w welcome1 
-f import.profile -configset 1 

The following example creates a new profile named iPlImport with values copied from a profile named iPllmportTemplate.

dipassistant createprofilelike -h myhost -p 3060 -D cn=dipadmin -w welcome1 -profile iPlImportTemplate -newProfile iPlImport

The following example uses a configuration file named changes.profile to modify a profile named myprofile.

dipassistant modifyprofile -profile myprofile -h myhost -p 3060 -D cn=dipadmin 
-w welcome1 -f changes.profile

The following example deletes the myprofile profile.

dipassistant deleteprofile -profile myprofile -h myhost -p 3060 -D cn=dipadmin 
-w welcome1 -configset 1

For the createprofile, createprofilelike, and modifyprofile commands, you specify a configuration file containing the properties listed in Table A-19. When modifying an already existing profile, no defaults are assumed. Only those attributes specified in the file are changed. When using Directory Integration and Provisioning Assistant, you reference a property name in the format odip.profile.property_name. However, in Oracle Internet Directory, the property name is stored in the format orclodipproperty_name. Both property name formats are listed in Table A-19.

Table A-19 Properties Expected by createprofile and modifyprofile Commands

Property	Description	Default
odip.profile.agentexecommand / orclodipagentexecommand	In the case of a non-LDAP interface, the command to produce the information in LDIF format	-
odip.profile.condiraccount / orclodipcondiraccessaccount	DN or user name used to connect to the third party directory.	-
odip.profile.condirfilter / orclodipcondirmatchingfilter	Filter that needs to be applied to the changes read from the connected directory before importing to Oracle Internet Directory	-
odip.profile.condirpassword / orclodipcondiraccesspassword	Password used for identification to the third-party directory.	-
odip.profile.condirurl / orclodipcondirurl	Location of third-party directory [hostname:port]	-
odip.profile.configfile	Name of the file that contains the additional profile-specific information to be used for execution	-
odip.profile.configinfo / orclodipadditionalconfiginfo	Contains additional profile-specific information to be used for execution	-
odip.profile.debuglevel / orclodipprofiledebuglevel	Specifies the profile debug level	-
odip.profile.interface / orclodipinterfacetype	Indicator as to whether the LDAP or LDIF or DB or TAGGED format is to be used for data exchange	LDAP
odip.profile.lastchgnum / orclodipcondirlastappliedchangenumber	Last applied change number. In the case of an export profile this number refers to Oracle Internet Directory's last applied change number However, n the case of the import profile, this number refers to the last applied change number in the connected directory	-
odip.profile.mapfile / orclodipattributemappingrules	Name of the file that contains the mapping rules	-
odip.profile.name / orclodipagentname	Name of the profile	-
odip.profile.oidfilter / orclodipoidmatchingfilter	Filter that needs to be applied to the changes that are read from the Oracle Internet Directory before exporting to the connected directory	-
odip.profile.password / orclODIPAgentPassword	Password for accessing this profile	-
odip.profile.retry / orclodipsyncretrycount	Maximum number of times the Oracle directory integration and provisioning server should attempt to execute an entry	4
odip.profile.schedinterval/ orclodipschedulinginterval	Interval between successive executions of this profile by the integration server. If the previous execution has not completed then the next execution will not resume until it completes.	One minute
odip.profile.status / orclodipagentcontrol	Either DISABLE or ENABLE	DISABLE
odip.profile.syncmode / orclodipasynchronizationmode	Direction of synchronization. When the changes are propagated from the third party to Oracle Internet Directory, the synchronization mode is IMPORT. When the changes are propagated to the third party directory, the synchronization mode is EXPORT.	IMPORT

A.4.1.2 Listing All Synchronization Profiles in Oracle Internet Directory

The listprofiles command prints a list of all the synchronization profiles in Oracle Internet Directory. The syntax for this command is:

dipassistant listprofiles [-h hostName] [-p port] [-D bindDn] [-w password] [-configset Configset Number]
 

Table A-20 describes the parameters of the listprofiles command.

Table A-20 Parameters of the listprofiles Command

Parameter	Description
-h | -host	Host where Oracle Internet Directory is running. The default value is the name of the local host.
-p | -port	Port at which Oracle Internet Directory was started. The default is 389.
-D | -dn	The bind DN to be used in identifying to the directory. The default value is the DN of the Oracle Directory Integration and Provisioning platform administrator.
-w | -passwd	The password of the bind DN to be used while binding to the directory.
-configset	An integer greater than 0 that represents the configuration set with which to associate the profile.

The following example prints a list of all the synchronization profiles in Oracle Internet Directory:

dipassistant listprofiles -h myhost -p 3060 -D cn=dipadmin -w welcome1

By default, the preceding command prints the following list of sample profiles created during installation. However, your deployment of Oracle Internet Directory may contain additional synchronization profiles.

IplanetExport 
IplanetImport 
ActiveImport 
ActiveExport 
LdifExport 
LdifImport 
TaggedExport 
TaggedImport 
OracleHRAgent 
ActiveChgImp 

A.4.1.3 Viewing the Details of a Specific Synchronization Profile

The showprofile command prints the details of a specific synchronization profile. The syntax for this command is:

dipassistant showprofile -profile profName [-h hostName] [-p port] [-D bindDn] 
[-w password]
 

Table A-21 describes the parameters of the showprofile command.

Table A-21 Parameters of the showprofile Command

Parameter	Description
-h | -host	Host where Oracle Internet Directory is running. The default value is the name of the local host.
-p | -port	Port at which Oracle Internet Directory was started. The default is 389.
-D | -dn	The bind DN to be used in identifying to the directory. The default value is the DN of the Oracle Directory Integration and Provisioning platform administrator.
-w | -passwd	The password of the bind DN to be used while binding to the directory.
-profile	A text string representing the name of profile to show.

For example, the following showprofile command prints the details for the ActiveImport sample profile that is created during installation:

dipassistant showprofile -h myhost -p 3060 -D cn=dipadmin -w welcome1 
-profile ActiveImport

The preceding command prints the following details of the ActiveImport sample profile:

odip.profile.version = 2.0
odip.profile.lastchgnum = 0
odip.profile.interface = LDAP
odip.profile.oidfilter = orclObjectGUID
odip.profile.schedinterval = 60
odip.profile.name = ActiveImport
odip.profile.syncmode = IMPORT
odip.profile.condirfilter = "searchfilter=(|(objectclass=group)(objectclass=organizationalunit)
(&(objectclass=user)(!(objectclass=computer))))"
odip.profile.retry = 5
odip.profile.debuglevel = 0
odip.profile.status = DISABLE

A.4.1.4 Performing an Express Configuration of the Active Directory Connector Profiles

The expressconfig command performs an express configuration of the Active Directory connector. When you run this command, it performs all required configurations outlined in Table A-17, "Summary of Functionality of the Directory Integration and Provisioning Assistant". This command also creates two profiles, an import profile and an export profile. The syntax for performing an express configuration is as follows:

dipassistant expressconfig [-h hostName] [-p port] [-3rdpartyds 3rd party ds] [-configset Configset Number]
 

Table A-22 describes the parameters of the expressconfig command.

Table A-22 Parameters of the expressconfig Command

Parameter	Description
-h | -host| -oidhost	Host where Oracle Internet Directory is running. The default value is the name of the local host.
-p |-port | -oidport	Port at which Oracle Internet Directory was started. The default is 389.
-3rdpartyds	The third-party directory service to configure.
-configset	An integer greater than 0 that represents the configuration set with which to associate the profile.

A.4.1.5 Bootstrapping a Directory by Using the Directory Integration and Provisioning Assistant

The bootstrap command performs the initial migration of data between a connected directory and Oracle Internet Directory. The syntax for this command is as follows:

dipassistant bootstrap { -profile profName [-h hostName] [-p port] [-D bindDn] [-w  
password] [-log logFile] [-logseverity severity] [-trace traceFile] [-tracelevel
level] [-loadparallelism #nThrs] [-loadretry retryCnt] | -f filename } 

Table A-23 describes the parameters of the bootstrap command.

Table A-23 Parameters of the bootstrap Command

Parameter	Description
-f | cfg	A configuration file containing all the parameters required for performing the bootstrapping. See Also: Table A-24 for a list of parameters and their description.
-h | -host	Host where Oracle Internet Directory is running. The default value is the name of the local host.
-p | -port	Port at which Oracle Internet Directory was started. The default is 389.
-D | -dn	The bind DN to be used in identifying to the directory. The default value is the DN of the Oracle Directory Integration and Provisioning platform administrator.
-w | -passwd	The password of the bind DN to be used while binding to the directory.
-profile	A text string representing the name of profile to use when performing the bootstrapping.
-log	Log file. If this parameter is not specified, then, by default, the log information is written to ORACLE_HOME/ldap/odi/bootstrap.log
-logseverity	Log severity 1 - 15. 1 – INFO, 2 – WARNING, 3 – DEBUG, 4 – ERROR. Or any combination of these. If not specified, then INFO and ERROR messages alone will be logged.
-trace	Trace file for debugging purposes.
-tracelevel	Trace level.
-loadparallelism	Indicator that loading to Oracle Internet Directory is to take place in parallel by using multiple threads. For example, -loadparallelism 5 means that five threads are to be created, each of which tries to load the entries in parallel to Oracle Internet Directory.
-loadretry	When loading to the destination fails, the number of times to retry before marking the entry bad.

When you use the bootstrap command, you can use either the -profile parameter to specify a synchronization profile or the -f parameter to a configuration file. The following example uses a synchronization profile named iPlanetProfile to perform bootstrapping:

dipassistant bootstrap –profile iPlanetProfile -h myhost –port 3060 -D cn=dipadmin -w welcome1
 

The following example uses a configuration file named bootstrap.cfg to perform bootstrapping:

dipassistant bootstrap –f bootstrap.cfg
 

When you use the -f parameter with the bootstrap command, you must specify a configuration file containing the properties listed in Table A-24.

A.4.1.6 Properties Expected by the Bootstrapping Command

Table A-24 Bootstrapping Configuration File Properties

Property	Description	Mandatory	Default
odip.bootstrap.srctype	Indicator of whether source of the bootstrapping is LDAP or LDIF. Valid values are either LDAP or LDIF.	Yes	-
odip.bootstrap.desttype	Indicator of whether destination of the bootstrapping is LDAP or LDIF. Valid values are either LDAP or LDIF.	Yes	-
odip.bootstrap.srcurl	In the case of LDAP source type, location of the source directory. In the case of LDIF, the location of the LDIF file. Note: For LDAP, the expected format is host[:port]. For LDIF, the expected format is the absolute path of the file.	Yes	-
odip.bootstrap.desturl	In the case of LDAP, location of the destination directory. In the case of LDIF, the location of the LDIF file. Note: For LDAP, the expected format is host[:port]. For LDIF, the expected format is the absolute path of the file.	Yes	-
odip.bootstrap.srcsslmode	Indicator of whether SSL-based authentication must be used to connect to the source of the bootstrapping. A value of TRUE indicates that SSL-based authentication must be used.	No	FALSE
odip.bootstrap.destsslmode	Indicator of whether SSL-based authentication must be used to connect to the destination of the bootstrapping. TRUE indicates that SSL-based authentication must be used. Note: In the case of LDIF, this parameter is meaningless.	No	FALSE
odip.bootstrap.srcdn	Supplement to the source URL. In the case of LDIF binding, this parameter is meaningless. However in the case of LDAP, this parameter specifies the Bind DN.	Only in the case of LDAP	-
odip.bootstrap.destdn	Supplement to the destination URL. In the case of LDIF binding, this parameter is meaningless. However in the case of LDAP, this parameter specifies the Bind DN.	Only in the case of LDAP	-
odip.bootstrap.srcpasswd	Bind password to the source. In the case of LDAP binding, this is used as security. Oracle Corporation recommends that you not specify the password in this file.	No	-
odip.bootstrap.destpasswd	Bind password. In the case of LDAP binding, this is used as security credential. Oracle Corporation recommends that you not specify the password in this file.	No	-
odip.bootstrap.mapfile	Location of the map file that contains the attribute and domain mappings.	No	-
odip.bootstrap.logfile	Location of the log file. If this file already exists then it will be appended. The default log file is bootstrap.log created under $ORACLE_HOME/ldap/odi/log directory.	No	The file bootstrap.log created under the directory ORACLE_HOME/ldap/odi/
odip.bootstrap.logseverity	Type of log messages that needs to be logged. INFO – 1 WARNING - 2 DEBUG – 4 ERROR - 8 Note: A combination of these types can also be given. For example, if you are interested only in WARNING and ERROR message, then specify a value of 8+2—that is, 10. Similarly, for all types of message, use 1 + 2 + 4 + 8 = 15	No	1 + 8 = 9
odip.bootstrap.loadparallelism	Numeric value indicating the number of writer threads used to load the processed data to the destination	No	1-
odip.bootstrap.loadretry	In the event of a failure to load an entry, indicator of how many times to retry	No	5
odip.bootstrap.trcfile	Location of the trace file. If this file already exists, then it is overwritten.	No	The default location is ORACLE_HOME/ldap/odi/log/bootstrap.trc
odip.bootstrap.trclevel	The tracing level	No	3
odip.bootstrap.srcencode	The encoding used by the LDIF file if the file: Is generated by using a utility of a third-party directory Contains NLS data Is processed on a different platform By default, the Directory Integration and Provisioning Assistant assumes that the file is processed on the system on which it was generated.	Yes	-

A.4.1.7 Setting the Wallet Password for the Oracle Directory Integration and Provisioning Server

The wp command enables you to set the wallet password that the Oracle directory integration and provisioning server later uses to connect to Oracle Internet Directory. To use this command, enter:

dipassistant wp

The Directory Integration and Provisioning Assistant prompts you to enter, and then confirm, the password.

A.4.1.8 Changing the Password of the Administrator of Oracle Directory Integration and Provisioning Platform

This chgpasswd command resets the password of dipadmin account. The default password for the dipadmin account is same as ias_admin password chosen during installation. To reset the password, you must provide the security credentials of the orcladmin account. The syntax for resetting the password is as follows:

dipassistant chgpasswd [-h hostName] [-p port] [-D bindDn] [-w password] 
 

Table A-25 describes the parameters of the chgpasswd command.

Table A-25 Parameters of the chgpasswd Command

Parameter	Description
-h | -host	Host where Oracle Internet Directory is running. The default value is the name of the local host.
-p | -port	Port at which Oracle Internet Directory was started. The default is 389.
-D | -dn	The bind DN to be used in identifying to the directory. The default value is the DN of the Oracle Directory Integration and Provisioning platform administrator.
-w | -passwd	The password of the bind DN to be used while binding to the directory.

The following is an example of the chgpasswd command:

dipassistant chgpasswd -h myhost -p 3060 -D cn=dipadmin -w welcome1

The Directory Integration and Provisioning Assistant then prompts for the new password as follows:

New Password: 
Confirm Password: 

A.4.1.9 Moving an Integration Profile to a Different Identity Management Node

You can use the reassociate command of the Directory Integration and Provisioning Assistant to move directory integration profiles to another node and to reassociate them with it. For example, if the middle-tier components are associated with a particular Oracle Identity Management infrastructure, then all the integration profiles existing in that infrastructure node can be moved to a new infrastructure node and reassociated with it.

Table A-26 describes the reassociation rules.

Table A-26 Scenarios for Reassociating Directory Integration Profiles

Scenario	Actions Taken
Integration profile does not exist on the second Oracle Internet Directory node	The integration profile is copied to the second Oracle Internet Directory node and is disabled after copying. It must be enabled by the application. The lastchangenumber attribute in the integration profile is modified to the current last change number on the second Oracle Internet Directory node.
Integration profile exists on the second Oracle Internet Directorynode	Both integration profiles are reconciled in the following manner: Any new attribute in the profile on node 1 is added to the profile on node 2 For existing same attributes, the values in profile on node 1 override the attributes in the profile on node 2 The profile is disabled after copying. It needs to be enabled by the application. The lastchangenumber attribute in the integration profile is modified to the current last change number on the second Oracle Internet Directory node

The syntax for the reassociate command is as follows:

dipassistant reassociate [-src_ldap_host hostName] [-src_ldap_port port] [-src_ 
ldap_dn bindDn] [-src_ldap_passwd password] -dst_ldap_host hostName [-dst_ldap_ 
port port [-dst_ldap_dn bindDn] [-dst_ldap_passwd password] [-log logfile]

Table A-27 describes the parameters of the reassociate command.

Table A-27 Parameters of the reassociate Command

Parameter	Description
-src_ldap_host host_name	Host where Oracle Internet Directory-1 runs
-src_ldap_port port_number	Port where Oracle Internet Directory-1 runs
-src_ldap_dn bind_DN	Bind DN for connecting to Oracle Internet Directory-1
-src_ldap_passwd password	Bind DN password for connecting to Oracle Internet Directory-1
-dst_ldap_host host_name	Host where Oracle Internet Directory-2 runs
-dst_ldap_portport_number	Port where Oracle Internet Directory-2 runs
-dst_ldap_dn bind_DN	Bind DN for connecting to Oracle Internet Directory-2
-dst_ldap_passwd password	Bind DN password for connecting to Oracle Internet Directory-2
-log log_file	Log file

The reassociate command defaults are as follows:

src_ldap_host - localhost, src_ldap_port & dst_ldap_port - 389
src_ldap_dn & dst_ldap_dn - cn=orcladmin account

The following is an example of the reassociate command:

dipassistant reassociate -src_ldap_host oid1.mycorp.com \
-dst_ldap_host oid2.mycorp.com -src_ldap_passwd srcpassword \
-dst_ldap_passwd dstpassword

Note if the location of the log file is not specified then by default it will be created as ORACLE_HOME/ldap/odi/log/reassociate.log.

A.4.1.10 Limitations of the Directory Integration and Provisioning Assistant in Oracle Internet Directory 10g Release 2 (10.1.2)

In this release, the Directory Integration and Provisioning Assistant does not support the following:

• SSL-based authentications to Oracle Internet Directory

• Schema synchronization

• Automatic profile creation at the end of the bootstrapping process when used with the -cfg option

• Mapping file validation

• Creation of a failed entries file

The following elements of the Directory Integration and Provisioning Assistant are untested:

• Bootstrapping of the connected directory over the SSL connection

• The use of the modifyprofile command while synchronization is happening for that profile

The bootstrapping command of the Directory Integration and Provisioning Assistant has the limitations described in Table A-28.

Table A-28 Limitations of Bootstrapping in the Directory Integration and Provisioning Assistant

Type of Bootstrapping	Limitation
LDIF-to-LDIF	None
LDAP-to-LDIF	For a large number of entries, bootstrapping can fail with an error of size limit exceeded. To resolve this, the connected directory server from which you are bootstrapping should: Support paged results control (OID 1.2.840.113556.1.4.319). Currently, Microsoft Active Directory is the only LDAP directory that supports this control. Have an adequate value for the server side search size limit parameter. Use a proprietary tool on the connected directory server to dump all entries to an LDIF file, and then bootstrap by using either the LDIF-to-LDIF or the LDIF-to-LDAP approach.
LDIF -to-LDAP	None
LDAP-to-LDAP	Same as LDAP-to-LDIF

For initial bootstrapping, you should perform the following steps:

1. Generate a dump of the entries in the connected directory to an LDIF file using a proprietary tool on the connected directory server.

2. Configure the properties file so that entries are created in Oracle Internet Directory using the LDIF-to-LDAP approach.

A.4.2 The schemasync Tool Syntax

The schemasync tool enables you to synchronize schema elements—namely attributes and object classes—between an Oracle directory server and third-party LDAP directories.

The usage for schemasync is as follows:

ORACLE_HOME/bin/schemasync -srchost source_LDAP_directory -srcport

source_LDAP_port_number -srcdn privileged_DN_in_source_directory_to_access_schema
-srcpwd password -dsthost destination_directory -dstport destination_port
-dstdn privileged_dn_in_destination_directory -dstpwdpassword [-ldap]

Note: the -ldap parameter is optional. If it is specified, then the schema changes are applied directly from the source LDAP directory to the destination LDAP directory. If it is not specified, then the schema changes are placed in the following LDIF files: ORACLE_HOME/ldap/odi/data/attributetypes.ldif This file has the new attribute definitions. ORACLE_HOME/ldap/odi/data/objectclasses.ldif This file has the new object class definitions. if you do not specify -ldap, then you must use ldapmodify to upload the definitions from these two files, first attribute types and then object classes.

The errors that occur during schema synchronization are logged in the following log files:

• ORACLE_HOME/ldap/odi/log/attributetypes.log

• ORACLE_HOME/ldap/odi/log/objectclasses.log

A.4.3 The Oracle Directory Integration and Provisioning Server Registration Tool (odisrvreg)

To register an Oracle directory integration and provisioning server with the directory, this tool creates an entry in the directory and sets the password for the directory integration and provisioning server. If the registration entry already exists, then you can use the tool to reset the existing password. The odisrvreg tool also creates a local file called odisrvwallet_hostname, at ORACLE_HOME/ldap/odi/conf. This file acts as a private wallet for the directory integration and provisioning server, which uses it on startup to bind to the directory.

Table A-29 describes the parameters that you use with the Oracle Directory Integration and Provisioning Server Registration Tool. You can also run odisrvreg in SSL mode to make communication between the tool and the directory fully secure, using the -U, -W, and -P parameters that are also described in Table A-29.

To register the directory integration and provisioning server, enter this command:

odisrvreg -h host_name -p port -D binddn -w bindpasswd –I passwd [-U ssl_mode -W wallet –P wallet_password]

Table A-29 Descriptions of ODISRVREG Arguments

Argument	Description
-h host_name	Oracle directory server host name
-p port_number	Port number on which the directory server is running
-D binddn	Bind DN. The bind DN must have authorization to create the registration entry for the directory integration and provisioning server
-l host	In a cold failover cluster configuration, the virtual hostname
-w bindpasswd	Bind password
-U ssl_mode	For no authorization, specify 0. For one-way authorization, specify 1.
-W wallet_location	Location of the Oracle Wallet containing the SSL certificate
-P wallet_password	Wallet password to open the Oracle wallet

A.4.4 Syntax for Provisioning Subscription Tool (oidprovtool)

Use the Provisioning Subscription Tool (oidprovtool) to administer directory entries for provisioning profiles. You can perform these tasks:

• Create a profile (create)

• Disable a profile (disable)

• Reenable a profile (enable)

• Modify a profile (modify)

• Delete a profile (delete)

• Get the current status of a profile (status)

• Clear all of the errors in a profile (reset)

oidprovtool hides the location of profile entries from callers of the tool. It also hides schema details. From the caller's perspective, the combination of an application identity and an identity management realm uniquely identify a provisioning profile. There can be only one provisioning profile per application per identity management realm.

Note: To run oidprovtool and other shell scripts on Windows platforms, use one of these UNIX emulation utilities: Cygwin 1.0: http://sources.redhat.com MKS Toolkit 5.1 or 6.0: http://www.datafocus.com/products

The name of the executable is oidProvTool. It is found at ORACLE_HOME/bin. To invoke the tool, issue this command:

oidprovtool param1=param1_value  param2=param2_value param3=param3_value ...

oidprovtool accepts the following parameters:

Table A-30 Provisioning Subscription Tool Parameters

Name	Description	Operations	Mandatory/Optional
operation	The subscription operation performed. Only one operation can be performed for each invocation of the tool.	All	M
ldap_host	Host name of the directory server on which the operation is performed. If not specified, the default value of localhost is assumed.	All	O
profile_status	The status of the profile. This value can be either enabled or disabled. The default is enabled.	Create	O
profile_mode	The values possible are inbound, outbound, or both. The default is outbound.	Create	O
profile_debug	The debug level at which the DIP server executes the profile.	All	O
sslmode	A value of 0 indicates non-SSL. A value of 1 indicates SSL.	All	O
ldap_port	The TCP/IP port on which the directory server is listening for requests. Defaults to 389 if no value is specified.	All	O
ldap_user_dn	The distinguished name of the user on whose behalf the operation is performed. The default is cn=orcladmin. Not all users may have the permissions necessary to perform provisioning subscription operations. See the administration guide to learn how to grant or deny permissions.	All	O
ldap_user_password	The password of the user on whose behalf the operation is performed. The default is welcome.	All	O
application_dn	The distinguished name of the application for which the operation is performed. Used together, application_dn and organization_dn help the subscription tool identify a provisioning profile.	All	M
organization_dn	The distinguished name of the organization for which the operation is performed. The default is the default identity management realm. Used together, application_dn and organization_dn help oidprovtool identify a provisioning profile.	All	O
interface_name	Database schema name for the PL/SQL package. The format of this value should be [Schema].[PACKAGE_NAME]	Create or modify	M
interface_type	The type of the interface to which events have to be propagated. The default is PLSQL if no value is specified.	Create or modify	O
interface_connect_info	The database connect string. The format is host:port:database_sid:user_id:password.	Create or modify	M
interface_version	The version of the interface protocol. Valid Values are 1.0, 1.1, or 2.0. Version 1.0 and 1.1 are old interfaces. Version 2.0 is the default.	Create	O
interface_additional_info	Additional information about the interface. This parameter is not used currently.	Create or modify	O
schedule	The length of time, in seconds, that must elapse before DIP processes the profile. Defaults to 3600 if no value is specified.	Create or modify	O
max_retries	The number of times the provisioning service should try to deliver an event if delivery has failed. Defaults to 5 if no value is specified.	Create or modify	O
max_events_per_schedule	The maximum number of events that should be propagated in one schedule. The default is 100. Useful for controlling load situations.	Create or modify	O
profile_group	The group of the profile. The Default is 0. Use this parameter to address scalability issues that arise when different DIP server instances execute different groups.	Create or modify	O
lastchangenumber	The change number at which events are propagated to the application. Used only in outbound mode. The default for the create operation is the current number.	Create or modify	O
event_subscription	Events that DIP should notify the application about. The string must have this format: [USER | GROUP]:[domain_of_interest]:[DELETE | MODIFY(list of attributes separated by commas)] You can specify multiple values by including more than one event_subscription parameter in a run of oidprovtool.	create only	M (for outbound mode only)
event_mapping_rules	For multivalued inbound events only. This parameter maps the type of object received from an application and a qualifying filter condition to determine the domain of interest for events indicated in event_subscription. The parameter takes this format: OBJECT_TYPE:filter_condition:domain_of_interest Multiple rules are allowed. You might, for example, enter these two rules: EMP::cn=users,dc=acme,dc=com EMP:1=AMERICA:1=AMER,cn=users,dc=acme,dc=com In the first case, if the object type received is EMP, the event is meant for the domain cn=users,dc=acme,dc=com. In the second case, the object received is again EMP, but the rule contains the attribute l (locality). The value of this attribute is AMERICA. Accordingly, the events specified are meant for the domain l=AMER,cn=users,dc=acme,dc=com.	Create or modify	M (for inbound mode only)
event_permitted_operations	For multivalued inbound events only. This parameter is used to define the types of events an application is privileged to send to the Provisioning Integration Service. The parameter takes this format: EVENT_OBJECT:affected_domain:operation(attributes) Here are two examples: IDENTITY:cn=users,dc=acme,dc=com:ADD(*) IDENTITY:cn=users,dc=acme,dc=com:MODIFY(cn,sn,mail,telephonenumber) In the first example, the IDENTITY_ADD event is allowed for the domain specified as well as all of its attributes. In the second example, IDENTITY_ADD is allowed for the same domain, but only for certain attributes. Other attributes are ignored.	Create or modify	M (for inbound mode only)