6 Process Control of Oracle Internet Directory Components

This chapter describes the concepts behind the process control model in Oracle Internet Directory. The process control model applies to the Oracle Internet Directory LDAP server, the Replication server, and the Directory Integration Server.

This section contains these topics:

• Tools and Daemons Important to Oracle Internet Directory Process Control

• Oracle Internet Directory Integration with OPMN

• Oracle Internet Directory Process Control–Best Practices

• OIDMON and the ODS_PROCESS Table

• OIDCTL Process Control Semantics

For information on starting and stopping the Oracle Directory Integration Platform server, see the chapter on managing the Oracle Directory Integration Platform server in Oracle Identity Management Integration Guide.

6.1 Tools and Daemons Important to Oracle Internet Directory Process Control

The Oracle Process Manager and Notification Server (OPMN) is a daemon process that monitors the components in an installation of Oracle Application Server. It is installed and configured in every middle-tier and Oracle Application Server Infrastructure installation and is essential for running Oracle Application Server. Because Oracle Internet Directory is part of the Oracle Application Server Infrastructure, OPMN is responsible for monitoring Oracle Internet Directory as an Oracle Application Server component. The command-line interface to OPMN is $ORACLE_HOME/opmn/bin/opmnctl. You use OPMNCTL to stop or start Oracle Internet Directory as a component.

See Also: The chapter entitled "Configuring Oracle Internet Directory" in Oracle Process Manager and Notification Server Administrator's Guide

OIDMON ($ORACLE_HOME/bin/oidmon) is a daemon process responsible for the process control of all Oracle Internet Directory Server instances.

OIDCTL ($ORACLE_HOME/bin/oidctl) is a command line tool that lets you configure additional Oracle Internet Directory Server Instances or perform process control at the instance level.

6.2 Oracle Internet Directory Integration with OPMN

This section describes Oracle Internet Directory interaction with OPMN. It includes the following sections:

• Semantics of OPMN Monitoring Oracle Internet Directory

• Oracle Internet Directory Snippet in OPMN.XML

• Semantics of OPMN Starting Oracle Internet Directory

• Semantics of OPMN Stopping Oracle Internet Directory

• Semantics of OPMN Monitoring OIDMON

6.2.1 Semantics of OPMN Monitoring Oracle Internet Directory

Monitoring rules are as follows:

• OPMN is responsible for monitoring Oracle Internet Directory as an Oracle Application Server component.

• OPMN integration with Oracle Internet Directory is such that OPMN knows only about OIDMON and is unaware of the Oracle Internet Directory Server Instances.

• OPMN is responsible for the direct start, stop, restart and monitoring of OIDMON only. OIDMON continues to be responsible for the direct start, stop, restart and monitoring of all Oracle Internet Directory Server Instances.

6.2.2 Oracle Internet Directory Snippet in OPMN.XML

Oracle Internet Directory component-specific directives are located as follows:

• Oracle Internet Directory component-specific directives for OPMN are located under the tag <ias-component id="OID" status="enabled> in $ORACLE_HOME/opmn/conf/opmn.xml.

• OPMN uses the directives in the OID component snippet in opmn.xml and invokes OIDMON and OIDCTL as required.

• OIDCTL related requirements are located under the tag <category id="oidctl parameters">.

• OIDMON related requirements are located under the tag <category id="oidmon parameters">. There should be only one such directive.

• The default value of OID Snippet in opmn.xml has one entry for OIDMON and one for OIDCTL.

See Also: The chapter entitled "Configuring Oracle Internet Directory" in Oracle Process Manager and Notification Server Administrator's Guide

6.2.3 Semantics of OPMN Starting Oracle Internet Directory

OPMN startup of an Oracle Internet Directory component proceeds as follows:

• You can indicate to OPMN the intent to start an Oracle Internet Directory component with one of the following commands:

  opmnctl startall
  
  opmnctl startproc ias-component=OID
  
  

• OPMN issues an oidmon start command with appropriate arguments to OIDMON as specified in the contents of "oidmon parameters" in the OID Snippet in opmn.xml.

• OPMN issues oidctl start commands if the OID Snippet in opmn.xml has entries that require this.

Note that when you use opmnctl startproc ias-component=OID, the opmn.xml parameters are not reloaded as they are when you use when you use opmnctl startall.

6.2.4 Semantics of OPMN Stopping Oracle Internet Directory

OPMN stopping of an Oracle Internet Directory component proceeds as follows:

• You can indicate to OPMN the intent to stop an Oracle Internet Directory component with one of the following commands:

  opmnctl stopall
  
  opmnctl stopproc ias-component=OID
  
  

• OPMN issues an oidmon stop.

• OPMN does not issue oidctl stop commands; instead, the OIDMON stop semantics ensure that the Oracle Internet Directory Server Instances are stopped as required. For more information, see "OIDMON and the ODS_PROCESS Table" .

Note that when you use opmnctl stopproc ias-component=OID, the opmn.xml parameters are not reloaded as they are when you use when you use opmnctl stopall.

6.2.5 Semantics of OPMN Monitoring OIDMON

OPMN monitors OIDMON as follows:

• Once you start OIDMON through OPMN, OPMN ensures that OIDMON is up and running. If OIDMON goes down for some reason, OPMN will bring it back up.

• If you issue oidmon stop on the command line, OIDMON will be stopped but OPMN will immediately bring it back up.

6.3 Oracle Internet Directory Process Control–Best Practices

The recommended approach for using OPMNCTL and OIDCTL is as follows:

• Use OPMNCTL to stop or start Oracle Internet Directory as a component. That is, use it to stop or start all Oracle Internet Directory LDAP, replication, and Oracle Directory Integration Platform server instances.

  • Using OPMNCTL to stop Oracle Internet Directory causes OPMN to issue an oidmon stop, which results in OIDMON shutting down all configured LDAP, replication, and Oracle Directory Integration Platform server instances.

  • Using OPMNCTL to start Oracle Internet Directory causes OPMN to issue an oidmon start, which results in OIDMON starting up all configured LDAP, replication, and Oracle Directory Integration Platform server instances.

• Use OIDCTL to configure required additional Oracle Internet Directory Server Instances.

  • To configure an Oracle Internet Directory LDAP, replication, or Oracle Directory Integration Platform server that is not part of the default configuration, use the OIDCTL command to start such an instance.

  • Issue the oidctl start command only once for each instance for the duration of the deployment of that configuration. The OIDMON start and stop semantics ensure that configured servers start and stop appropriately.

• Use OIDCTL to perform process control at the instance level only.

  • Use oidctl stop to stop a particular instance of the Oracle Internet Directory LDAP, replication, or Oracle Directory Integration Platform server. Do not use it to stop all the configured instances of the servers.

  • Use oidctl start to start an additional instance of the Oracle Internet DirectoryLDAP, replication, or Oracle Directory Integration Platform server that is not already configured.

  • If, for some reason, a server instance is stopped using oidctl stop, then it is removed from the process table and will not be known to OIDMON any longer. To restart an instance that was stopped this way, use oidctl start.

The following sections provide examples of the recommended approach. The examples are:

• Changing the Configuration of the Default OID LDAP Server Instance

• Configuring Additional Oracle Internet Directory LDAP Server Instances

• Deconfiguring the Default Oracle Internet Directory LDAP Server Instance

• Configuring an Instance of the Oracle Internet Directory Replication Server

• Configuring an Oracle Directory Integration Platform Server Instance

See Also: "Oracle Internet Directory Server Administration Tools" in Oracle Identity Management User Reference for more information on the syntax of the commands used in the examples

6.3.1 Changing the Configuration of the Default OID LDAP Server Instance

A default Oracle Internet Directory installation uses the default configuration set (configset0), which provides a single server instance with one server process and two database connections configured. This configuration might be inadequate to handle the production LDAP load in your environment. If so, you need to increase the number of server processes or database connections or both. You change these by changing the orclserverprocs and orclmaxcc attributes values, respectively, in configset0.You change the default configset using Oracle Directory Manager, as follows:

1. Launch Oracle Directory Manager.

2. Log in as orcladmin.

3. Expand Server Management.

4. Click Default Configuration.

5. Change Max Number of DB Connections to the desired value. A typical recommendation is 10.

6. Change Number of Child Process if required. A typical value is 1 or the number of CPUs on the system.

7. Click Apply.

8. Restart the Oracle Internet Directory servers, as follows:

   opmnctl stopproc ias-component=OID 
   opmnctl startproc ias-component=OID
   
   

   Oracle recommends that you not change other parameters in the default configuration set.

6.3.2 Configuring Additional Oracle Internet Directory LDAP Server Instances

To start additional Oracle Internet Directory LDAP server instances, add additional configuration sets with the required configuration values and use these additional configuration sets to start additional server instances. (Do not use the default configuration set and override the default values.) You add a configuration set and to use it to start an Oracle Internet Directory LDAP Server Instance as follows:

1. Launch Oracle Directory Manager.

2. Expand Server Management.

3. Expand Directory Server.

4. Right click Default Configuration Set.

5. Click Create Like.

6. Change the required parameters in the new configuration set. Ensure that the port numbers do not overlap with those of the default configuration set or any other configuration set.

7. Click OK.

To start an LDAP server instance using a new configuration set called configset2, type:

oidctl connect=connStr server=oidldapd instance=2 configset=2 start

6.3.3 Deconfiguring the Default Oracle Internet Directory LDAP Server Instance

To replace the Oracle Internet Directory LDAP server instance with one or more Oracle Internet Directory LDAP Server Instances, you must edit opmn.xml to deconfigure the default LDAP instance. By default, opmn.xml contains an XML snippet that attempts to start the default Oracle Internet Directory LDAP server instance when you type opmnctl start. To deconfigure the default Oracle Internet Directory LDAP server instance, perform the following steps:

1. Type:

   oidctl connect=connStr server=oidldapd instance=1 stop
   
   

2. Edit the file $ORACLE_HOME/opmn/conf/opmn.xml and remove the following lines:

   <category id="oidctl-parameters">
   <data id="connect" value="iasdb"/>
   <data id="startoidldapd" value="true"/>
   </category>
   
   

6.3.4 Configuring an Instance of the Oracle Internet Directory Replication Server

To configure an instance of OID Replication Server, use the oidctl start command. For example:

oidctl connect=connStr server=oidrepld instance=1 \
 flags="-h LdapHost -p LdapPort" start

Do not start more than one instance of oidrepld.

6.3.5 Configuring an Oracle Directory Integration Platform Server Instance

To configure an instance of the Oracle Directory Integration Platform Server, use the oidctl start command. For example:

oidctl connect=connStr server=odisrv instance=1 \
 flags="-h LdapHost -p LdapPort" start

6.4 OIDMON and the ODS_PROCESS Table

OIDMON It is responsible for starting, stopping, restarting, and monitoring of all the Oracle Internet Directory Server instances including Oracle Internet Directory LDAP, Replication, and Directory Server instances.

OIDMON reads the contents of the ods_process table in the ODS database user schema once every periodicity and acts upon the intent conveyed by the contents of that table. The periodicity is controlled by the value of the sleep command line argument used at oidmon startup, and the default value is 10 seconds.

Table 6-1 describes the information in the ODS_PROCESS table that is relevant to process control:

Table 6-1 Process Control Items in the ODS_PROCESS Table

Item	Meaning
Instance	Unique instance number for a given server ID on a given host
PID	Process ID of the server that is up and running
ServerID	Server ID (2=OIDLDAPD, 3=OIDREPLD, 7=ODISRV)
Flags	Command line arguments that need to be passed to the server instance
Hostname	Name of the host on which this server must be present
Configset	Configset information
State	State of the Server Instance (0=stop, 1=start, 2=running, 3=restart, 4=shutdown)
RetryCount	Number of attempts to start the server instance before it could be started successfully

Notes: There is a uniqueness constraint on (Instance,ServerID,Hostname). Details are provided here about ods_process only to convey the concepts. Any updates to the table by a user, other than by using OIDCTL, are inappropriate and are not supported by Oracle.

OIDMON takes the following actions with respect to Oracle Internet Directory server instances:

• When OIDMON is stopped, it performs the following tasks before shutting down:

  • OIDMON stops all the server instances active (up and running) on its node, that is, all instances active on the same host as OIDMON.

  • OIDMON updates the value of the "state" column of rows in the ods_process table with matching hostname to 4.

• When OIDMON is started, it starts all Oracle Internet Directory Server instances whose information in the ods_process table has state value 1 or 4 and hostname value matching the host on which OIDMON is active.

6.5 OIDCTL Process Control Semantics

This section explains the semantics of starting and stopping Oracle Internet Directory server instances by using OIDCTL.

OIDCTL communicates the intent to start, stop, or restart a particular Oracle Internet Directory Server instance by updating the ods_process table in the ODS database user schema.

When you start an Oracle Internet Directory server instance:

• You use the OIDCTL command line utility to indicate the intent to start a particular Oracle Internet Directory server instance.

• OIDCTL inserts a row into the ods_process table to convey the intent to OIDMON

• If the uniqueness constraint on the ods_process table is violated, then OIDCTL reports the error "Instance number already in use".

• OIDMON reads this information, starts the server instance, and updates the state and PID columns of the ods_process table as appropriate.

When you stop an Oracle Internet Directory server instance by using OIDCTL:

• You use the OIDCTL command line utility to indicate the intent to stop a particular Oracle Internet Directory server instance.

• OIDCTL updates the corresponding row in the ods_process table to convey the intent to OIDMON.

• If the corresponding row is not found, that is, the given instance is not configured, then OIDCTL reports the error "Cannot Stop an Instance that is not running".

• OIDCTL updates the state value to 0.

• OIDMON reads this information, stops the server instance, and deletes the row representing this server instance from the ods_process table.