2 Oracle Internet Directory Administration Tools

This chapter describes the following command-line tools used to administer Oracle Internet Directory:

Note:

The term "instance" refers to an Oracle instance in opmnctl documentation. The term "instance" refers to an Oracle Internet Directory instance in oidctl documentation.

2.1 oidpasswd

The Oracle Internet Directory Database Password Utility (oidpasswd) is used to:

  • Change the password to the Oracle Internet Directory database.

    Oracle Internet Directory uses a password when connecting to an Oracle database. The default for this password matches the value you specified during installation for the Oracle Fusion Middleware administrator's password. You can change this password by using the OID Database Password Utility.

  • Create wallets for the Oracle Internet Directory database password and the Oracle directory replication server password.

  • Unlock or reset the directory superuser account, namely, cn=orcladmin.

  • Reset an access control point (ACP) so that the subtree is accessible by the Oracle Internet Directory superuser.

  • Manage the restricted superuser ACL.

2.1.1 Syntax for oidpasswd

oidpasswd [connect=connect_string] [change_oiddb_pwd=true | create_wallet=true | unlock_su_acct=true| reset_su_password=true | manage_su_acl=true]

2.1.2 Arguments for oidpasswd

connect=connect_string

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

change_oiddb_pwd=true | unlock_su_acct=true | reset_su_password=true | manage_su_password=true

Required. The operation you want to perform. Depending on the operation you choose, the Oracle Internet Directory Database Password Utility prompts you for additional information. The following choices are available:

  • change_oiddb_pwd=true - Changes the password to the Oracle Internet Directory database. You are prompted to provide the current database password, enter a new database password, and confirm the new password.

    Note:

    In an Oracle Real Application Clusters (Oracle RAC) environment, if you update the password on one Oracle RAC node, then you must update the wallet on the other Oracle RAC nodes. Refer to "About Changing the ODS Password on an Oracle RAC System" in the Oracle Application Server High Availability Guide for more information.

  • create_wallet=true - Create a wallet named oidpwdlldap1 for the Oracle Internet Directory database password, and a wallet, named oidpwdrsid, for the Oracle directory replication server password.

    The sid is obtained from the connected database.

    You must provide the ODS password to authenticate yourself to the ODS database before the ODS wallet can be generated. Note that the default ODS password is the same as that for the Oracle Fusion Middleware administrator.

  • unlock_su_acct=true - Unlocks a superuser account that has been locked.

  • reset_su_password=true - Resets the password for the Oracle Internet Directory superuser account. You are prompted to provide the Oracle Internet Directory database password, enter a new superuser password, and confirm the new superuser password.

  • manage_su_acl=true - Manages the restricted superuser ACL.

2.1.3 Tasks and Examples for oidpasswd

Using Oracle Internet Directory Database Password Utility, you can perform the following tasks:

2.1.3.1 Changing the Password to the Oracle Internet Directory Database

The following example shows how to change the Oracle Internet Directory database password, assuming the database in on the same machine.

Example:

oidpasswd
current password: oldpassword
new password: newpassword
confirm password: newpassword
password set.

The Oracle Internet Directory Database Password Utility prompts you for the current password. Type the current password, then the new password, then a confirmation of the new password.

Notes:

  • User responses are not echoed to the screen when you enter a password.

  • Whenever you change the password to the Oracle Internet Directory database by using the OID Database Password Utility, you should also run the oidemdpasswd utility. This enables the Oracle Enterprise Manager Daemon (a component of Oracle Enterprise Manager) to properly cache that password and contact the ODS schema upon starting up. Once you have run the oidemdpasswd utility, you can monitor Oracle Internet Directory processes from the Oracle Enterprise Manager.

2.1.3.2 Creating Wallets for Directory Database and Replication Server Passwords

The following example shows how to create wallets for the Oracle Internet Directory database password and the Directory Replication server password.

Example:

oidpasswd connect=dbs1 create_wallet=true 

The argument create_wallet=true is mandatory in this case. Except for the connect string, no other option can be specified.

2.1.3.3 Unlocking the Superuser Account

The following example shows how to unlock the Oracle Internet Directory superuser account, cn=orcladmin.

Example:

oidpasswd connect=dbs1 unlock_su_acct=true

The argument unlock_su_acct is mandatory. Except for connect string, no other option can be specified.

2.1.3.4 Resetting the Superuser Password

If you forget the Oracle Internet Directory superuser password, you can use the oidpasswd tool to reset it. You must provide the Oracle Internet Directory database password. When you first install Oracle Internet Directory, the superuser password and Oracle Internet Directory database password are the same. After installation, however, you can change the Oracle Internet Directory superuser password using ldapmodify. You can change the Oracle Internet Directory superuser password using the oidpasswd tool separately.

The following example shows how to reset the Oracle Internet Directory superuser password. The oidpasswd tool prompts you for the Oracle Internet Directory database password.

Example:

oidpasswd connect=dbs1 reset_su_password=true
OID DB user password: oid_db_password
                password: new_su_password
confirm password: new_su_password
OID super user password reset successfully

2.1.3.5 Managing Superuser Access Control Points

When an access control point (ACP) is set with an access control item (ACI) that has the keyword DenyGroupOverride, neither the Oracle Internet Directory superuser nor members of DirectoryAdminGroup can access the subtree under that ACP. If necessary, you can use the oidpasswd tool to reset that ACP so that the subtree is accessible by the Oracle Internet Directory superuser.

The following example shows how to reset a restricted ACP. The oidpasswd utility prompts you to enter the Oracle Internet Directory database password and to choose which superuser restricted ACPs to reset.

Example:

oidpasswd conn=dbs1 manage_su_acl=true
OID DB user password: oid_db_password

The super user restricted ACP list
[1] o=oracle,c=us
[2] ou=personnel,o=oracle,c=us

Enter 'resetall' or the number(s) of the ACP to be reset separated by [,]
resetall

Once you have reset some ACPs so that the superuser can access them, you can use ldapmodify to make the subtrees inaccessible to the superuser again.

2.1.4 Related Command-Line Tools for oidpasswd

2.2 oidctl

Oracle Internet Directory Control Utility (oidctl) is a command-line tool for starting and stopping Oracle Identity Management server instances. In 11g Release 1 (11.1.1), it is typically used only to configure, start, and stop the Oracle Directory Replication Server.

Notes:

  • You must set the environment variables ORACLE_INSTANCE, ORACLE_HOME, INSTANCE_NAME and COMPONENT_NAME before you run the oidctl command. Alternatively, you can pass the instance name and component name in the command line as name=instanceName, componentname=componentName.

  • Best practice is to create new Oracle Internet Directory instances by creating new Oracle Internet Directory components with opmnctl createcomponent. See "opmnctl". You should only use oidctl to create an instance if you plan to run Oracle Internet Directory in standalone mode and never use Oracle Enterprise Manager Fusion Middleware Control.

  • The term "instance" refers to an Oracle Internet Directory instance in oidctl command documentation.

The commands issued by Oracle Internet Directory Control Utility are interpreted and executed by the Oracle Internet Directory Monitor process. Before starting a server instance with this utility, make sure that the Monitor process is running. See "oidmon".

2.2.1 Syntax for oidctl

oidctl [connect=connect_string] { server=OIDLDAPD | OIDREPLD } 
instance=instance_number [name=instance_name] [componentname=component_name]
[host=host_name] [flags="flagname=value ..." ] [ 
{start | stop | add | delete | status [-diag | -odiag interval]}

2.2.2 Arguments for oidctl

connect=connect_string

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

server=server

Required. The options are:

  • OIDLDAPD — Oracle Internet Directory server

  • OIDREPLD — Directory Replication server

instance=instance_number

Required. The numerical value of the instance. The value must be greater than 0 but less than 100.

host=host_name

Optional. Name of the logical host where the server is located or will be added. If you are using this argument, make sure oidmon is also started with the host=host_name parameter. If oidmon is started by opmn, then make sure the hostname parameter exists in the file ORACLE_INSTANCE/config/OPMN/opmn/opmn.xml.

name=instance_name

Optional. Name of the instance to be used. The default is inst1.

componentname=component_name

Optional. Name of the component to be used. The default is oid1.

flags="flagname=value | -flag value ..."

The flags argument is needed only while starting the server. If the flags consist of UNIX-style keywords, then the keyword-value pairs must be separated by spaces.

start | stop | restart | add | delete | status

Required. The operation to perform on the given server process.

  • start — Start the server=server instance=instance_number [name=instance_name componentName=component_name]

  • stop — Stop the server=server instance=instance_number [name=instance_name componentName=component_name]

  • add — Add the instance-specific configuration entry and start the server instance.

  • delete — Stop the server instance and delete the instance-specific configuration entry

  • status [-diag | -opdiag] — Report the status of running server instances. Use -diag with status to get diagnostic information. Use -opdiag, followed by interval, an integer value, with status to get the operation count for each operation for each Oracle Internet Directory component.

2.2.2.1 OIDLDAPD Flags

In 11g Release 1 (11.1.1), the recommended tool for creating instances and managing the LDAP server is opmnctl, not oidctl. See "opmnctl". You should only use oidctl for these purposes if you plan to run Oracle Internet Directory in standalone mode and never use Oracle Enterprise Manager Fusion Middleware Control.

-l true | false

Optional. Turns replication change logging on or off. Use true to enable change logging. Use false to disable change logging. The default is true.

-p ldap_port

Optional. Specifies the LDAP port that this Oracle Internet Directory server instance will use. If not specified the default 3060 is used.

-server number_of_processes

The number of server processes to start on this port.

-sport ssl_port

Optional. Specifies the LDAPS port that this Oracle Internet Directory server instance will use. If not specified the default 3133 is used.

-work maximum_threads

The maximum number of worker threads for this server.

2.2.2.2 OIDREPLD Flags

-p directory_port_number

Required for a start operation. Port number used to connect to Oracle Internet Directory server. The default is 3060.

-h directory_hostname

Required for a start operation. The host name of the Oracle Internet Directory server to which the replication server connects. If not specified, localhost is used.

-m true | false

Optional. Use true to enable conflict resolution. Use false to disable conflict resolution. The default value is true.

-sizelimit transaction_size

Optional. The number of changes applied in each replication update cycle. If not specified the value from the Oracle Internet Directory server size limit configuration parameter, which has a default of 1024.

2.2.3 Tasks and Examples for oidctl

In 11g Release 1 (11.1.1), oidctl is used primarily to manage the replication server. The recommended tool for creating instances and managing the LDAP server is opmnctl, not oidctl. See "opmnctl". You should only use oidctl for these purposes if you plan to run Oracle Internet Directory in standalone mode and never use Oracle Enterprise Manager Fusion Middleware Control.

Before using Oracle Internet Directory Control, make sure that Oracle Internet Directory Monitor is running. To verify this on UNIX, enter to following at the command-line:

ps -ef | grep oidmon

See "oidmon" for more information about Oracle Internet Directory Monitor.

Using Oracle Internet Directory Control, you can perform the following tasks:

2.2.3.1 Creating an Oracle Internet Directory Instance in an Existing Component

To create another Oracle Internet Directory instance within an existing component, type

oidctl connect=connect_string server=oidldapd inst=new_instance_number \
   name=instanceName componentname=componentName  \
   flags=port=non_ssl_port sport=ssl_port add 

The name and componentname arguments are required unless the environment variables INSTANCE_NAME and COMPONENT_NAME have been set. Typically, the inst value of the original instance is 1, the second instance you create is 2, and so forth.

As an example:

oidctl connect=oiddb server=oidldapd inst=2 "flags=port=5678 sport=5679" add

2.2.3.2 Deleting an Oracle Internet Directory Instance in a Component

To delete one Oracle Internet Directory instance within a component, type

oidctl connect=connect_string server=oidldapd inst=new_instance_number \
   name=instanceName componentname=componentName  \
   flags=port=non_ssl_port sport=ssl_port delete 

Typically, the inst value of the original instance is 1, the second instance you create is 2, and so forth.

2.2.3.3 Starting an Oracle Internet Directory Server Instance

When starting an Oracle Internet Directory server, you must supply the instance, server=OIDLDAPD, and start arguments. All other arguments are optional.

Before starting a new instance of OIDLDAPD, run the command:

oidctl connect=connstr status 

to make sure oidmon is running and that the instance number and ports that you intend to use are not already in use.

Example:

oidctl connect=dbs1 server=OIDLDAPD instance=2 flags="-p 3133 \
   -debug 1024  -l false" start

2.2.3.4 Stopping an Oracle Internet Directory Server Instance

Example:

oidctl connect=dbs1 server=OIDLDAPD instance=2 stop

2.2.3.5 Restarting an Oracle Internet Directory Server Instance

A restart operation is useful when you want to refresh the server cache immediately, or when you have changed a configuration set entry and want your changes to take effect on an active server instance. When the Oracle Internet Directory server restarts, it maintains the same arguments it had before it stopped.

For example, if you changed a configuration set that was being referenced by an active instance of Oracle Internet Directory server, you could update it by restarting that server instance. You do not need to supply the configset argument again, as it is maintained from the prior start operation.

Example:

oidctl connect=dbs1 server=OIDLDAPD instance=1 restart

To restart all active instances on a node, do not specify the instance argument. Note that a server is momentarily unavailable to client requests during a restart.

2.2.3.6 Starting a Directory Replication Server Instance

When starting an Oracle Directory Replication server, you must supply the information it needs to connect to the Oracle Internet Directory server. You cannot use the add option when starting a replication server.

Example:

oidctl connect=dbs1 server=OIDREPL instance=1 flags="-p 3060 \
   -h ldaphost.example.com -d 1024" start 

This command uses the same instance-specific configuration entry as instance=1.

2.2.3.7 Stopping a Directory Replication Server Instance

Example:

oidctl connect=dbs1 server=OIDREPLD instance=1 stop

2.2.3.8 Starting and Stopping a Server Instance on a Virtual Host or Cluster Node

Use the host argument to specify a virtual host name when starting an Oracle Internet Directory server or Oracle Internet Directory Replication server on a virtual host or a Oracle Application Server Identity Management Cluster Node.

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 Oracle Application Server Cold Failover Cluster (Identity Management).

When communicating with the directory server, the Directory Integration Platform server uses the virtual host name.

The following example shows how to start an Oracle Internet Directory server (OIDLDAPD) on a virtual host. The same syntax can be used to also start a directory replication server (OIDREPLD) on a virtual host.

Example:

oidctl connect=dbs1 host=vhost.company.com server=OIDLDAPD instance=1 \
   configset=2 [flags="..."] start

2.2.3.9 Reporting the Status of Each Server

The status argument is used to report the status of each server running on the node.

Example:

oidctl connect=dbs1 status

2.2.3.10 Reporting Diagnostics

Use the -diag flag with the status argument to get detailed diagnostic information that can be useful in resolving performance issues.

The -diag flag causes oidctl to print information about each LDAP operation as it executes, including the time it spends in the database layer.

For example:

oidctl connect=dbs1 status -diag 
oidctl : ORACLE_INSTANCE is not set, defaulting to /ade/rsathyan_ldmain5/oracle/ldap/
oidctl : INSTANCE_NAME   is not set, defaulting to inst1
oidctl : COMPONENT_NAME  is not set, defaulting to oid1
  +------------------------------------------------------------------------+
  | Process      |  PID   | InstName   | CompName  | Inst# | Port | Sport  |
  +------------------------------------------------------------------------+
  | oidmon       |  12838 |      inst1 |      oid1 |       |      |        |  +------------------------------------------------------------------------+
  | oidldapd disp|  12926 |      inst1 |      oid1 |      1| 8856 |      0 |
  | oidldapd serv|  12930 |      inst1 |      oid1 |      1| 8856 |      0 |
  | Config   DN  | cn=oid1,cn=osdldapd,cn=subconfigsubentry                |
  +------------------------------------------------------------------------+
  +------------------------------------------------------------------------+
  |Printing LDAP Operation in progress status ...                          |
  +------------------------------------------------------------------------+
    Search: 
      OIDLDAPD_PID: 12930 WorkerID: 8 DBSID: 162 
      ConnDN:                                            
      BaseDN:c=us                                           
      Scope=2                                           
        Filter=(|(uid=a*)(cn=b*)(objectclass=person))                                                 ReqdAttrs:                                           
      SqlText:
        SELECT /*+ FIRST_ROWS */ dn.entryid FROM ct_dn dn WHERE dn.entryi
        d IN (SELECT /*+ INDEX( at1 VA_uid ) */ entryid FROM CT_uid at1 W
        HERE attrValue  like :0 ESCAPE '\'  UNION SELECT /*+ INDEX( at1 V
        A_cn ) */ entryid FROM CT_cn at1 WHERE attrValue  like :1 ESCAPE 
        '\'  UNION SELECT /*+ INDEX( at1 VA_objectclass ) */ entryid FROM
         CT_objectclass at1 WHERE attrValue  = 'person') AND ( (dn.parent
        dn like :bdn  ESCAPE '\' OR (dn.rdn = :rdn AND dn.parentdn = :pdn
        )) ) AND dn.entryid >= :entryThreshold 
         
      Plan Hash Value :          0
      Rows Fetched    :          0
      Number of Sorts :          0
      Disk Read       :          0
      Disk Writes     :          0
      Buffer Gets     :          0
      IO Wait Time    :          0 (ms)
      CPU Time        :          0 (ms)
  +------------------------------------------------------------------------+

2.2.3.11 Reporting Server Manageability Information

When you run oidctl with status -opdiag interval, oidctl reads the shared memory contents for all servers in the running instances associated with the OIDMON in that environment and aggregates the operation count of each type for each OID component. It repeatedly displays current and total operation counts on the standard output at interval seconds. oidctl resets all the current values of operation count in the shared memory so that the directory server starts from zero for each type of operation for the next cycle.

For example:

$ oidctl status -opdiag 15
oidctl : ORACLE_INSTANCE is not set, defaulting to
/ade/myOID/oracle/ldap/
oidctl : INSTANCE_NAME   is not set, defaulting to inst1
oidctl : COMPONENT_NAME  is not set, defaulting to oid1
 
+--------------------------------------------------------------------------+
+--------------------------------------------------------------------------+
 |Printing completed LDAP operation counts ...                              
| +--------------------------------------------------------------------------+
  ComponentName: oid1       Current    Total
              Bind Count     : 0           0
              Add Count      : 0           0
              Delete Count   : 0           0
              Modify Count   : 0           0
              ModRdn Count   : 0           0
              Compare Count  : 0           0
              Search Count   : 0           0
              Extended Count : 0           0
. +--------------------------------------------------------------------------+
 +--------------------------------------------------------------------------+

2.2.4 Related Command-Line Tools for oidctl

2.3 oiddiag

The Oracle Internet Directory Server Diagnostic command-line tool (oiddiag) collects diagnostic information that helps triage issues reported on Oracle Internet Directory. It is available as oiddiag for use on UNIX and Linux platforms and as oiddiag.bat for Windows. The tool connects to the database used as the directory store (also called Metadata Repository) of Oracle Internet Directory and reads the information. The tool makes no recommendations on potential fixes to issues. Rather, it collects information to help Support and Development understand a problem and determine its solution. The tool can collect four types of diagnostic information:

  • Directory information tree (DIT)

  • Data consistency

  • Server manageability statistics

  • System and process information

If you use either the collect_all=true or the collect_sub=true arguments, you are prompted to supply the following information:

  • The fully domain-qualified database host name

  • The database listener port number

  • The database service name

  • The ODS database user password

  • Whether the Oracle Database connection uses SSL or not. Only NoSSL Authentication (Encryption only) is supported.

You can find the hostname, port number and service name in the file tnsnames.ora, located by default in ORACLE_INSTANCE/config. For example, in the following tnsnames.ora file, the hostname, port number and service names are, respectively, sun16.example.com, 1521, and orcl.example.com:

 ORCL =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCP)(HOST = sun16.example.com)(PORT = 1521))
    (CONNECT_DATA =
      (SERVER = DEDICATED)
      (SERVICE_NAME = orcl.example.com)
    )
  )

Note:

You must set the ORACLE_HOME environment variable before executing the OIDDIAG tool.

2.3.1 Syntax for oiddiag

oiddiag {listdiags=true [targetfile=filename]} | {collect_all=true [outfile=filename]} | {collect_sub=true [infile=filename] [outfile=filename]} | {audit_report=true [outfile=file_name]} 

2.3.2 Arguments for oiddiag

listdiags=true

Writes a list of available diagnostics that can be collected. The list is written to an output file, which is ORACLE_INSTANCE/diagnostics/logs/OID/tools/oiddiag.txt by default. You should run a listdiags command before running a collect_sub command. The collect_sub command uses the file that is output by listdiags. You can edit this file as needed to contain only the diagnostic items you want.

targetfile=filename

This is the location of the output file where the diagnostic tool writes the list of available diagnostics when listdiags=true is given. If not specified, the tool writes the list to ORACLE_INSTANCE/diagnostics/logs/OID/tools/oiddiag.txt.

collect_all=true

Collect all of the diagnostic information available and writes it to an output file. You are prompted to provide the Oracle Internet Directory database host name, listener port, net service name, and password.

outfile=filename

The name of the output file that the diagnostic information is written to. If not specified, the default output file is written to ORACLE_INSTANCE/diagnostics/logs/OID/tools/oiddiag/timestamp.log. The timestamp format is YYYYMMDDHHmmss.

collect_sub=true

Collects a subset of diagnostic information (based on the diagnostics specified in the input file) and writes it to an output file. You are prompted to provide the Oracle Internet Directory database host name, listener port, net service name, and password.

You should run a listdiags command before running a collect_sub command. The collect_sub command uses the file that is output by listdiags. You can edit this file as needed to contain only the diagnostic items you want.

infile=filename

A file that contains the list of diagnostic items for which you want to output information. By default, the diagnostic tool looks for this file in ORACLE_INSTANCE/diagnostics/logs/OID/tools/oiddiag.txt, which is the default target file location of the listdiags command. You can edit this file as needed to contain only the diagnostic items you want.

audit_report=true

Generates standard reports for Secure Events Tracking and writes them to an output file.

2.3.3 Tasks and Examples for oiddiag

Using the Oracle Internet Directory diagnostic tool, you can perform the following tasks:

2.3.3.1 Collecting All Diagnostic Information

The following example shows how to collect all available diagnostic information and write it to the specified output file.

Example:

oiddiag collect_all=true outfile=~/myfiles/oid.log

2.3.3.2 Collecting Selected Diagnostic Information

To collect a subset of diagnostic data, you must first run the oiddiag tool with the listdiags argument. This outputs a list of available diagnostics, which you can then edit. This list is then passed in to the collect_sub command to determine the diagnostics for which to collect output. The following example uses the default file locations of ORACLE_INSTANCE/diagnostics/logs/OID/tools/oiddiag.txt (for the list) and ORACLE_INSTANCE/diagnostics/logs/OID/tools/oiddiagtimestamp.log (for the output file).

Example:

oiddiag listdiags=true
oiddiag collect_sub=true

2.3.3.3 Collecting Stack Trace Information

An important type of information that the oiddiag tool collects is the stack trace data for Oracle Internet Directory processes. Examining the stack trace is useful if you are experiencing slow response times or if your system stops responding. Because Oracle Internet Directory is usually started as a setuid-root program, you must log in as the root user before you can use the oiddiag tool to trace the stack for any Oracle Internet Directory processes. The root user must belong to the same operating system group that the Oracle operating system user belongs to. The following example logs in as the root user and changes to the dba group before executing the oiddiag tool:

su
newgrp dba
oiddiag collect_all=true

2.4 oidmon

In 11g Release 1 (11.1.1), you typically manage Oracle Internet Directory by using Oracle Enterprise Manager Fusion Middleware Control or the command-line utility opmnctl. Both opmnctl and Fusion Middleware Control use the Oracle Process Manager and Notification Server to issue commands to the Oracle Internet Directory Monitor, oidmon, which initiates, monitors, and terminates directory server processes.

2.4.1 Syntax for oidmon

oidmon [connect=connect_string] [host=hostname] [sleep=seconds] start | stop

2.4.2 Arguments for oidmon

connect=connect_string

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

host=hostname

Optional. Enables you to specify a virtual host name for the server or the name of an Oracle Application Server Identity Management Cluster Node. If not given, the default of localhost is used.

sleep=seconds

Optional. The number of seconds after which Oracle Internet Directory Monitor should check for new requests from Oracle Internet Directory Control and for requests to restart any server instances that may have stopped. The default is 10 seconds.

start | stop

Required. The operation to perform (start or stop the Monitor process).

2.4.3 Tasks and Examples for oidmon

Using Oracle Internet Directory Monitor, you can perform the following tasks:

2.4.3.1 Starting Oracle Internet Directory Monitor

You should start Oracle Internet Directory Monitor before using Oracle Internet Directory Control.

Example:

oidmon connect=dbs1 sleep=15 start

2.4.3.2 Starting Oracle Internet Directory Monitor on a Virtual Host or Cluster Node

Use the host argument to specify a virtual host name when starting an Oracle Internet Directory Monitor on a virtual host or a Oracle Application Server Identity Management Cluster Node.

Example:

oidmon connect=dbs1 host=virtualhostname.company.com start

2.4.3.3 Stopping Oracle Internet Directory Monitor

Stopping Oracle Internet Directory Monitor also stops all other Oracle Internet Directory processes. The oidmon tool does not remove server instance information from the ODS_PROCESS table. When an oidmon start operation is executed, it starts all the server processes it had stopped previously.

Example:

oidmon connect=dbs1 stop

2.4.4 Related Command-Line Tools for oidmon

2.5 opmnctl

The Oracle Process Manager and Notification Server Control Utility (opmnctl) enables you to manage system components, such as Oracle Internet Directory, in an integrated way.

The term "instance" refers to an Oracle instance in opmnctl command descriptions.

Notes:

2.5.1 Syntax for opmnctl

opmnctl startproc ias-component=componentName

opmnctl stopproc ias-component=componentName

opmnctl createcomponent [admin_server_properties] [instance_properties] 
[opmn_properties] [component_properties] [component_configuration_properties]

opmnctl deletecomponent [admin_server_properties] [instance_properties] 
[opmn_properties] [component_properties] [component_configuration_properties]

opmnctl registerinstance [admin_server_properties] [instance_properties] [component_configuration_properties]

opmnctl unregisterinstance [admin_server_properties] [instance_properties] [component_configuration_properties]

opmnctl updatecomponentregistration  [admin_server_properties] [instance_properties] [component_configuration_properties]

opmnctl status [-l]

2.5.2 Arguments for opmnctl

Arguments for opmnctl consist of commands and several types of properties. This section describes the following types of arguments:

Note:

Arguments to opmnctl are case-sensitive. Be sure to type them exactly as shown. For example, -adminUsername must have only the letter U in upper case.

2.5.2.1 Commands

The command indicates the operation to perform. The following commands are relevant to Oracle Internet Directory:

startproc

Starts server process

stopproc

Stops server process

createcomponent

Creates a component and automatically registers the component with a WebLogic domain, as long as the instance is in a registered state.

deletecomponent

Deletes a component

registerinstance

Registers an Oracle instance that was not previously registered with a domain. This scenario occurs if you chose Configure Without a Domain during installation of Oracle Internet Directory or if you created an Oracle instance from the command line and did not register the instance.

unregisterinstance

Unregisters an Oracle instance that was previously registered with a domain.

status [-l]

Shows the status of components. Add the -l option for detailed information.

updatecomponentregistration

Registers an existing Oracle Internet Directory component that was not previously registered with a domain. This scenario occurs if you created a new component in an Oracle instance using opmnctl createcomponent and did not register the component.

2.5.2.2 WebLogic Administration Server Properties

The following administration server properties are relevant to Oracle Internet Directory:

-adminHost

The WebLogic Administration Server host name

-adminPort

The WebLogic Administration Server port. The default is 7001.

-adminUsername

The WebLogic administrator user name.

-adminPasswordFile

A text file containing the WebLogic administrator password. You are prompted for the administrator password if this parameter is missing. Best security practice is to provide the password in response to a prompt. If you must use a file containing the password in clear text, protect it with file permissions and delete it when it is no longer needed.

2.5.2.3 Instance Properties

You do not need to specify instance properties with the opmnctl command, as long as you invoke the command as ORACLE_INSTANCE/bin/opmnctl.

2.5.2.4 OPMN Configuration Properties

No OPMN configuration properties are required with the opmnctl commands shown in this chapter.

2.5.2.5 Component Properties for Oracle Internet Directory

The following component properties are relevant to Oracle Internet Directory.

-componentType

For Oracle Internet Directory, this is always OID. This is required for createcomponent.

-componentName

The name of an Oracle Internet Directory component, such as oid1. The component name must be unique within the Oracle instance.

2.5.2.6 Oracle Internet Directory Component Configuration Properties

These arguments are specific to Oracle Internet Directory

-Db_info

Specifies the name, TNS port, and service name of the Oracle Database associated with this Oracle Internet Directory component, in the format:

DBHostName:TNSPORT:DBSERVICENAME

For example:

linux12.example.com:1521:orcl.example.com

When you are using the createcomponent command, the DBHostName:Port:DBSvcName argument to the -DB_info parameter must be the same as that provided during installation. If it is not, the command fails. You can find this value in the file ORACLE_INSTANCE/config/tnsnames_copy.ora.

If the Oracle Database is based on Real Application Clusters, the argument to the -DB_info parameter is of the form:

DBHostName1:Port1^DBHostName2:Port2@DBSvcName

-Ods_Password_File

Optional. The file that contains the ODS password in cleartext.You are prompted for the ODS password if this parameter is missing. Best security practice is to provide the password in response to a prompt. If you must use a file containing the password in clear text, protect it with file permissions and delete it when it is no longer needed.

-Sm_Password_File

Optional. The file that contains the ODSSM password in cleartext.You are prompted for the ODSSM password if this parameter is missing. Best security practice is to provide the password in response to a prompt. If you must use a file containing the password in clear text, protect it with file permissions and delete it when it is no longer needed.

-Namespace

Required only for the first Oracle Internet Directory component in an instance. The Oracle Internet Directory namespace. For example: "dc=us,dc=example,dc=com".

-Admin_Password_File

Optional. The file that contains the password for the Oracle Internet Directory superuser account cn=orcladmin.You are prompted for the Oracle Internet Directory superuser password if this parameter is missing.

-Port

Optional. The non-SSL port for this Oracle Internet Directory component. The command uses a default available port if this parameter is missing.

-Sport

Optional. The SSL port for this Oracle Internet Directory component. The command uses a default available port if this parameter is missing.

2.5.3 Tasks and Examples for opmnctl

Using the OPMN Control Utility, you can perform the following Oracle Internet Directory server management tasks:

2.5.3.1 Creating an Oracle Internet Directory Component

This command creates a component and registers it with a WebLogic domain, as long as the instance is in a registered state:

opmnctl createcomponent 
   -componentType OID 
   -componentName oid2 
   -adminHost myhost   
   -adminPort 7001
   -Db_info "linux12.example.com:1521:orcl.example.com"
   -Namespace "dc=domain_component1,dc=domain_component2..."

The DBHostName:Port:DBSvcName argument to the -DB_info parameter must be the same as that provided during installation. If it is not, the command fails. You can find this value in the file ORACLE_INSTANCE/config/tnsnames_copy.ora

If the Oracle Database is based on Real Application Clusters, the argument to the -DB_info parameter is of the form:

DBHostName1:Port1^DBHostName2:Port2@DBSvcName

The opmnctl command prompts for the WebLogic administrator's user name if you do not supply it. It also prompts for the passwords if you do not supply password file names on the command line. The opmnctl command also uses available ports if you do not specify -Port or -Sport

2.5.3.2 Registering an Oracle Instance

This example registers an Oracle instance with a WebLogic server:

ORACLE_INSTANCE/bin/opmnctl registerinstance \
 -adminHost myhost \
 -adminPort 7001 \
 -adminUsername weblogic 

You are prompted for the WebLogic administrator's user name and password.

2.5.3.3 Unregistering an Oracle Instance

This example unregisters an Oracle instance with a WebLogic server:

ORACLE_INSTANCE/bin/opmnctl unregisterinstance \
 -adminHost myhost \
 -adminPort 7001 \
 -adminUsername weblogic 

You are prompted for the WebLogic administrator's user name and password if you do not supply them.

2.5.3.4 Updating the Component Registration of an Oracle Instance

You must update the registration of an Oracle Internet Directory component in a registered Oracle instance whenever you change any of the configuration attributes orclhostname, orclsslport, or orclnonsslport in the instance-specific configuration entry, or if you change the password for the EMD administrator. If you do not update the component registration, you will be unable to use Fusion Middleware Control or wlst to manage that component.

This example updates the component registration of an Oracle instance that has been registered.

ORACLE_INSTANCE/bin/opmnctl updatecomponentregistration \
   -adminHost myhost \
   -adminPort 7001 \
   -adminUsername weblogic 
   -componentType OID  \
   -componentName oid2 \
   -Port 6589 \
   -Sport 3032

You are prompted for the WebLogic administrator's user name and password if you do not supply them.

The default administrative port on the WebLogic Administration Server is 7001.

You must supply both a non-SSL port and an SSL port.

2.5.3.5 Deleting an Oracle Internet Directory Component

This example deletes an Oracle Internet Directory component that has been registered with a WebLogic server:

ORACLE_INSTANCE/bin/opmnctl deletecomponent \
   -adminHost myhost \
   -adminPort 7001 \
   -adminUsername weblogic \
   -componentType OID  \
   -compnentName oid2

You are prompted for the WebLogic administrator's user name and password if you do not supply them.

2.5.3.6 Stopping All Oracle Internet Directory Server Components

The following example shows how to stop all running directory server processes (Oracle Internet Directory and Oracle Directory Replication server).

ORACLE_INSTANCE/bin/opmnctl process-type=OID stop

2.5.3.7 Starting All Oracle Internet Directory Server Components

The following example shows how to start all directory server components.

$ORACLE_INSTANCE/bin/opmnctl startproc componentType=OID

2.5.3.8 Stopping a Specific Oracle Internet Directory Server Component

The following example shows how to stop a specific Oracle Internet Directory component.

ORACLE_INSTANCE/bin/opmnctl stopproc componentName=oid1

2.5.3.9 Starting a Specific Oracle Internet Directory Server Component

The following example shows how to start a specific Oracle Internet Directory component.

ORACLE_INSTANCE/bin/opmnctl startproc componentName=oid1

2.5.3.10 Getting Status Information

The following example shows the status information provided by opmnctl.

$ opmnctl status -l

Processes in Instance: asinst_2
---------------------------------+--------------------+---------+----------+------------+----------+-----------+------
ias-component                    | process-type       |     pid | status   |        uid |  memused |    uptime | ports
---------------------------------+--------------------+---------+----------+------------+----------+-----------+------
oid2                             | oidldapd           |   24760 | Alive    |  988238800 |   102744 |   0:01:12 | N/A
oid2                             | oidldapd           |   24756 | Alive    |  988238799 |    55052 |   0:01:12 | N/A
oid2                             | oidmon             |   24745 | Alive    |  988238796 |    48168 |   0:01:14 | LDAPS:6789,LDAP:6788

oid1                             | oidldapd           |   21590 | Alive    |  988238048 |   103716 |  19:51:48 | N/A
oid1                             | oidldapd           |   21586 | Alive    |  988238047 |    54420 |  19:51:49 | N/A
oid1                             | oidmon             |   21577 | Alive    |  988238046 |    48168 |  19:51:49 | LDAPS:3133,LDAP:3060

2.5.4 Related Command-Line Tools for opmnctl

2.6 oidstats.sql

Use the Oracle Internet Directory Database Statistics Collection Tool (oidstats.sql) to analyze the various database ods (Oracle Directory Server) schema objects to estimate the statistics. It is located in the following directory: ORACLE_HOME/ldap/admin/. You must run this utility whenever there are significant changes in directory data—including the initial load of data into the directory.

If you load data into the directory by any means other than the bulk load tool (bulkload), then you must run the Oracle Internet Directory Database Statistics Collection tool after loading. Statistics collection is essential for the Oracle Optimizer to choose an optimal plan in executing the queries corresponding to the LDAP operations. You can run Oracle Internet Directory Database Statistics Collection tool at any time, without shutting down any of the Oracle Internet Directory processes.

Note:

If you do not use the bulkload utility to populate the directory, then you must run the oidstats.sql tool to avoid significant search performance degradation.

2.6.1 Syntax for oidstats.sql

sqlplus ods/ods_password@connect_string @oidstats.sql

2.6.2 Arguments for oidstats.sql

If you do not supply the ODS password on the command line, sqlplus prompts for it. Note that the default ODS password is the same as that for the Oracle Application Server administrator. (For security reasons, avoid supplying a password on the command line whenever possible. A password typed on the command line is visible on your screen. When you supply a password at a prompt, it is not visible on the screen.)

connect_string

Required. The connect string for the ODS database. This is the network service name set in the tnsnames.ora file, which is located by default in $ORACLE_INSTANCE/config. (You can set the TNS_ADMIN environment variable if you want to use a different location.)

2.6.3 Tasks and Examples for oidstats.sql

You can perform the following task using the oidstats.sql tool:

2.6.3.1 Running the Oracle Internet Directory Database Statistics Collection Tool

Example:

sqlplus ods@dbs1 @oidstats.sql

2.6.4 Related Command-Line Tools for oidstats.sql

2.7 oidcred

The Oracle Internet Directory Credential Management Tool is used to add, update, or delete a credential that has been created in the Credential Store Framework. It determines the instance name from the opmn.xml file

2.7.1 Syntax for oidcred

oidcred user_name option [InstancePath]

2.7.2 Arguments for oidcred

The oidcred command takes the following arguments:

user_name

Required. Value can be odssm or emd.

option

Required. Value can be update or delete.The update option adds the credential if it does not exists or updates it if it exists.

InstancePath

Required if ORACLE_INSTANCE environment is not set. Path of Oracle Instance directory.

If not specified on the command line, oidcred uses ORACLE_INSTANCE environment variable if set.

2.7.3 Tasks and Examples for oidcred

Update the password for user odssm in the Credential Store Framework.

oidcred odssm update /scratch/mydir/fmw_home/asinst_1
Enter password:
Confirm password:
Password set in CSF

2.8 oidrealm

The Oracle Internet Directory realm tool is used to create multiple realms in Oracle Internet Directory. The individual realms can be managed separately, so you can use oidrealm as a replacement for Delegated Administration Services.

The oidrealm tool supports creation, but not deletion, of a realm. A procedure for deleting a realm is provided in Note 604884.1, which is available on My Oracle Support at https://support.oracle.com/

2.8.1 Syntax for oidrealm

On UNIX or Linux:

oidrealm oid_host oid_port DN [-SSL]

On Windows:

oidrealm.bat oid_host oid_port DN [-SSL]

Note:

If you specify an SSL port, that port must be configured in SSL No Authentication Mode, that is, orclsslauthentication must be 1. For more information, see the section on SSL authentication modes in Oracle Fusion Middleware Administrator's Guide for Oracle Internet Directory.

2.8.2 Arguments for oidrealm

oid_host

Name of host where Oracle Internet Directory is running.

oid_port

Specifies the port number to use, which can be either SSL or non-SSL

DN

DN of realm to add

[-SSL]

Specifies that the port is an SSL port. Only no-auth mode is supported.

2.8.3 Example for oidrealm

$ oidrealm myhost.example.com 3133 'dc=newrealm,dc=com' -SSL
Enter OID Admin Password: password

[info] ->> /scratch/mydir/mwhome/idm3/ldap/schema/oid/oidSubscriberCreateCommon.lst *
Feb 2, 2009 9:22:57 PM oracle.ldap.util.LDIFLoader recursiveLoad
INFO: ->> /scratch/mydir/mwhome/idm3/ldap/schema/oid/oidSubscriberCreateCommon.lst *
[info]    ->> /scratch/mydir/mwhome/idm3/ldap/schema/oid/oidContextCreate.lst *
Feb 2, 2009 9:22:57 PM oracle.ldap.util.LDIFLoader recursiveLoad
INFO:    ->> /scratch/mydir/mwhome/idm3/ldap/schema/oid/oidContextCreate.lst *
[info]       -> LOADING:  /scratch/mydir/mwhome/idm3/ldap/schema/oid/oidContextCreateCommon.sbs
Feb 2, 2009 9:22:57 PM oracle.ldap.util.LDIFLoader loadOneLdifFile
INFO:       -> LOADING:  /scratch/mydir/mwhome/idm3/ldap/schema/oid/oidContextCreateCommon.sbs
[info]       ->> /scratch/mydir/mwhome/idm3/ldap/schema/oid/oidContextUpgradeFrom81600.lst *Feb 2, 2009 9:22:58 PM oracle.ldap.util.LDIFLoader recursiveLoad
INFO:       ->> /scratch/mydir/mwhome/idm3/ldap/schema/oid/oidContextUpgradeFrom81600.lst*
[info]          -> LOADING:  /scratch/mydir/mwhome/idm3/ldap/schema/oid/oidContextUpgradeFrom81600Common.sbs
Feb 2, 2009 9:22:58 PM oracle.ldap.util.LDIFLoader loadOneLdifFile
INFO:          -> LOADING:  /scratch/mydir/mwhome/idm3/ldap/schema/oid/oidContextUpgradeFrom81600Common.sbs
[info]       ->> /scratch/mydir/mwhome/idm3/ldap/schema/oid/oidContextCreate90100Changes.lst *
Feb 2, 2009 9:23:00 PM oracle.ldap.util.LDIFLoader recursiveLoad
INFO:       ->> /scratch/mydir/mwhome/idm3/ldap/schema/oid/oidContextCreate90100Changes.lst *
[info]          -> LOADING:  /scratch/mydir/mwhome/idm3/ldap/schema/oid/oidContextUpgradeFrom90000Common.sbs
Feb 2, 2009 9:23:00 PM oracle.ldap.util.LDIFLoader loadOneLdifFile
...
...
...
...