24
Managing the Oracle Directory Integration Server

This chapter discusses the Oracle directory integration server and tells you how to configure and manage it. It contains these topics:

• About the Oracle Directory Integration Server

• Registering the Oracle Directory Integration Server

• Managing Configuration Set Entries

• Managing the Oracle Directory Integration Server

• Viewing Oracle Directory Integration Server Information

About the Oracle Directory Integration Server

The Oracle directory integration server is the central component of the Oracle Directory Integration platform. It is a daemon server process that does the following:

Schedules agents	The directory integration server controls the execution of agents, invoking them at specified times. The scheduling information is stored in the integration profile associated with the agent. When it invokes agents, the directory integration server also passes agent configuration information to them.
Imports and exports data	The directory integration server imports and exports changes into and out of Oracle Internet Directory. The directory integration server and the agents exchange change information by using import files and export files.
Maps attributes	The directory integration server includes a generic mapping facility for performing attribute mappings. It maps attributes based on a set of rules that you specify in Oracle Internet Directory. The directory integration server maps attributes either when generating an export file during an export operation, or when interpreting an import file during an import operation.

You can run multiple directory integration server instances.

Only partner agents use the directory integration server. External agents do not use it.

This section contains these topics:

• The Oracle Directory Integration Server and Configuration Set Entries

• Configuration Data Refresh

• LDAP Connections Used by the Oracle Directory Integration Server

• Registering the Oracle Directory Integration Server

The Oracle Directory Integration Server and Configuration Set Entries

When you start the directory integration server by using the OID Control Utility, the start message you send refers to a configuration set entry containing server parameters. That configuration set is, in turn, associated with one or many agents. The directory integration server runs the agents associated with the particular configuration set.

The server has four types of threads of execution in the process:

Controller thread	Monitors all the other threads
Configuration reader thread	Periodically polls for changes in the directory integration profiles in the directory, then refreshes the directory integration profiles in its cache with that information. The default polling interval, in minutes, is 2.
Agent threads	Spawn the agent executable and mapping service as subprograms. These threads are created only for executing the agents. They terminate when the synchronization cycle for the agent is over.
Scheduler thread	Schedules the agents for execution. Every time a timer is triggered, it spawns an agent thread.

If there are no agents configured for the configuration set, or if all the configured agents are disabled, then the Oracle Directory Integration server does not initiate synchronization. Instead, it waits indefinitely for agents to be added to that configuration set. If the configuration set specified at the command line does not exist in the directory, then the Oracle Directory Integration server logs this information in the log file and exits.

Configuration Data Refresh

Agent configuration data is checked every 2 minutes for changes by the configuration reader thread, and the entire configuration data cache is refreshed in memory as required. The server, if started with the proper debug level, can give the appropriate messages.

See Also: "Managing Server Configuration Set Entries" for more information on configuration set entries "Managing Partner Agents by Using Oracle Directory Manager" for instructions on enabling and disabling directory integration agents "Setting the Debug Level" for more information about debug levels

LDAP Connections Used by the Oracle Directory Integration Server

Whenever it executes an agent at synchronization time, the directory integration server starts an agent thread. This thread opens an LDAP connection to the directory server, then closes the connection before exiting.

In addition, the configuration reader thread uses one LDAP connection for periodically refreshing its cache with configuration information from Oracle Internet Directory.

Registering the Oracle Directory Integration Server

After installing the directory integration server, you must register it with Oracle Internet Directory. You must separately register each directory integration server installed on a different host. You do this by using the Oracle directory integration server registration tool (odisrvreg).

To run this tool, you need the privileges of an Oracle Internet Directory administrator. Run the tool from the machine on which the directory integration server is installed.

The tool creates an entry in the directory as part of the registration. It sets the password for the directory integration server and stores it as an encrypted value in the registration entry. If the registration entry already exists, then you can use the tool to reset the existing password. You must supply the correct password to run the tool.

In addition to generating the registration entry in the directory, the tool also creates a local file, called odisrvwallet, that acts as a private wallet for the directory integration server. The directory integration server, when it starts, uses this file to bind to the directory. It creates this file in the $ORACLE_HOME/ldap/odi/conf directory.

You can run the tool in SSL mode to make communication between the tool and the directory fully secure.

To register the directory integration server, enter this command:

odisrvreg -h hostname -p port -D binddn  -w bindpasswd

Table 24-1 Descriptions of ODISRVREG arguments

Argument	Description
-h hostname	Oracle directory server host name
-p port_number	Port number on which the directory server is running
-W binddn	Bind DN. The bind DN must have authorization to create the registration entry for the directory integration server.
-W bindpasswd	Bind password

To run the Oracle directory integration server registration tool in the SSL mode, enter the following:

odisrvreg -h hostname -p port -D binddn  -w bindpasswd -U ssl_mode -W wallet -P 
wallet_password

Table 24-2 Descriptions of ODISRVREG arguments

Argument	Description
-h hostname	Oracle directory server host name
-p port_number	Port number on which the directory server is running
-W binddn	Bind DN. The bind DN must have authorization to create the registration entry for the directory integration server.
-W bindpasswd	Bind password
-U ssl mode	SSL mode. For no authorization, specify 0. For one-way authorization, specify 1.
-W wallet	SSL wallet. Enter the full path. For example, on Solaris, you could set this parameter as follows: file:/home/my_dir/my_wallet On Windows NT, you could set this parameter as follows: file:C:\my_dir\my_wallet
-P wallet password	Password for opening the SSL wallet

Managing Configuration Set Entries

When it starts, the directory integration server needs a list of all the agents that the directory integration server is to control. A configuration set entry holds this information for the directory integration server. You can create, modify, and view configuration set entries by using either Oracle Directory Manager or the appropriate command line tools.

When an agent is registered, an integration profile is created in the directory for that agent. The integration profile is always associated with a configuration set entry. In this way, the association between an agent and the Directory Integration Server is established.

When you start the directory integration server, a configuration set entry is supplied as part of the argument list. This configuration set entry determines the behavior of the directory integration server.

You can control the runtime behavior of the directory integration server by using a different configuration set entry when you start it. For example, you can start instance 1 of the directory integration server on host H1 with configset1, and instance 2 of the directory integration server on host H1 with configset2. The behavior of instance 1 of the directory integration server depends on configset 1, and that of instance 2 depends on configset2. By dividing different agents on host H1 between the two configuration set entries, you are distributing the load of running the agents on host H1 between the two directory integration server instances.

Managing the Oracle Directory Integration Server

This section contains these topics:

• Starting the Oracle Directory Integration Server

• Stopping the Oracle Directory Integration Server

• Using the Restart Command

• Using the Oracle Directory Integration Server in SSL Mode

• Finding the Log File

• Setting the Debug Level

• Changing the Synchronization Status Attribute

Starting the Oracle Directory Integration Server

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

The way you start the directory integration server depends on whether your installation includes the OID Monitor and the OID Control Utility. These tools--along with other server and client components--are parts of a typical installation. In such installations, you start the directory integration server by using these tools.

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

Client-only installations do not include the OID Monitor and the OID Control Utility. In such installations, you start the directory integration server from the command line.

Starting the Oracle Directory Integration Server by Using OID Monitor and the OID Control Utility

To start the directory integration server:

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

   ps -ef | grp oidmon
   
   

   If OID Monitor is not running, then start it by following the instructions in "Task 1: Start the OID Monitor".

2. Start the directory integration server by using the OID Control utility by entering:

   oidctl [connect=net_service_name] server=odisrv [instance=instance_number]  
   config=configuration_set_number [flags="[host=hostname] [port=port_number] 
   [debug=debug_level]"] start
   
   

   The arguments in this command are described in the following table.

   Table 24-3 Description of Arguments for Starting Oracle Directory Integration Server

   Argument	Description
   connect=net_service_name	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 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=configuration_set_number	Specifies the number of the configuration set that the the directory integration server is to execute. This argument is mandatory.
   host=hostname	Oracle directory server host name
   port=port_number	Oracle directory server port number
   debug=debug_level	The required debugging level of the directory integration server See Also: Table 24-6 for a description of the various debug levels

Starting the Oracle Directory Integration Server Without Using OID Monitor and the OID Control Utility

To start the directory integration 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]

Stopping the Oracle Directory Integration Server

Stop the directory integration server in one of two ways, depending on how you started it.

Stopping the Oracle Directory Integration Server by Using OID Monitor and the OID Control Utility

If you started the directory integration server by using OID Monitor and the OID Control utility, then you must stop it by using them.

To stop the directory integration server by using the OID Monitor:

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

   ps -ef | grp oidmon
   
   

   If OID Monitor is not running, then start it by following the instructions in "Task 1: Start the OID Monitor".

2. Stop the directory integration server by entering:

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

Stopping the Directory Integration Server Without Using OID Monitor and the OID Control Utility

If you started the directory integration server without using OID Monitor and the OID Control utility, then you must stop it by using the command line.

To stop the directory integration server by using the command line:

1. Enter the following at the command line to determine the PID (process identifier) of the directory integration server:

   ps -ef | grep odisrv
   
   

2. Stop the directory integration server by entering the following at the command line:

   kill PID
   

Using the Restart Command

If you use OID Monitor and the OID Control utility, then you can both stop and restart the directory integration server in one command, namely, restart. This is useful when you want to refresh the server cache immediately, rather than at the next scheduled time. When the directory integration server restarts, it maintains the same parameters it had before it stopped.

To restart the directory integration server:

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

   ps -ef | grp oidmon
   
   

   If OID Monitor is not running, then start it by following the instructions in "Task 1: Start the OID Monitor".

2. At the command line, enter:

   oidctl [connect=net_service_name] server=odisrv instance=instance_number 
   restart
   

Using the Oracle Directory Integration Server in SSL Mode

To secure the data exchanged between Oracle Internet Directory and the directory integration server, you run both the directory server and the directory integration server in SSL mode.

Starting the Oracle Directory Integration Server in SSL Mode by Using OID Monitor and OID Control

To run the directory integration server in the SSL mode by using OID Monitor and the OID Control utility, enter the following command:

oidctl [connect=net_service_name] server=odisrv [instance=instance_number] 
config=configuration_set_number [flags= [host=hostname] [port=port_number] 
[debug=debug_level] [sslauth=<ssl mode> wloc= <wallet> wpass=<wallet 
password>"]]start

Table 24-4 describes the arguments in this command.

Table 24-4 Description of Arguments for Starting Oracle Directory Integration Server in SSL Mode by Using OID Monitor and OID Control

Argument	Description
connect=net_service_name	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 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=configuration_set_number	Specifies the number of the configuration set that the the directory integration server is to execute. This argument is mandatory.
host=hostname	Oracle directory server host name
port=port_number	Oracle directory server port number
debug=debug_level	The required debugging level of the directory integration server See Also: Table 24-6 for a description of the various debug levels
sslauth ssl_mode	SSL modes (0: NO Auth, 1: One Way)
wloc wallet	SSL wallet. Enter the full path. For example, on Solaris, you could set this parameter as follows: file:/home/my_dir/my_wallet On Windows NT, you could set this parameter as follows: file:C:\my_dir\my_wallet
wpass wallet_password	Password used for opening the SSL wallet

Starting the Oracle Directory Integration Server in SSL Mode Without Using OID Monitor and OID Control

To start the directory integration server in SSL Mode without using OID Monitor and OID Control, enter this command:

odisrv [host=host_name] [port=port_number] config=configuration_set_number 
[instance=instance_number] [debug=debug_level]  [sslauth=ssl_mode wloc=wallet 
wpass=wallet_password]

Table 24-5 Description of Arguments for Starting Oracle Directory Integration Server in SSL Mode Without Using OID Monitor and OID Control

Argument	Description
instance=instance_number	Specifies the instance number to assign to the directory integration 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=configuration_set_number	Specifies the number of the configuration set that the the directory integration server is to execute. This argument is mandatory.
host=hostname	Oracle directory server host name
port=port_number	Oracle directory server port number
debug=debug_level	The required debugging level of the directory integration server See Also: Table 24-6 for a description of the various debug levels
sslauth ssl_mode	SSL modes (0: NO Auth, 1: One Way)
wloc wallet	SSL wallet. Enter the full path. For example, on Solaris, you could set this parameter as follows: file:/home/my_dir/my_wallet On Windows NT, you could set this parameter as follows: file:C:\my_dir\my_wallet
wpass wallet_password	Password used for opening the SSL wallet

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

Finding the Log File

The log file is located in
the $ORACLE_HOME/ldap/log/OidsyncServer_instance_number.log directory.

For example, if the server was started as server instance number 3, then the log file would have this path name: $ORACLE_HOME/ldap/log/oidsync03.log.

Setting the Debug Level

You can specify the kinds of events listed in a log file by using the debug flag.

To specify multiple types of debugging:

1. Add the numeric values of the individual types as indicated in Table 24-6.

2. At the command line, specify the total value. For example, the following command sets the debug level to 484:

   oidctl server=odisrv flags="debug=484" start
   
   

The various types of debug types are listed in Table 24-6.

Table 24-6 Debug Types

Debug Event Type	Numeric Value
Starting and stopping of different threads. Process related.	4
Detail level. Shows the spawned commands and the command-line arguments passed	32
Operations being performed by configuration reader thread. Configuration refresh events.	64
Actual configuration reading operations	128
Operations being performed by scheduler thread in response to configuration refresh events, and so on	256
Creation of callout lists for timers for different agents	512
Spawned agent and command names	1024
Monitoring of spawned agent processes	2048
Debugging of mapping service built into the Oracle Directory Integration server	4096
Debugging of the agent executable	8192
Detail agent level tracing	32768
Debugging of LDAP operations	65536
Detailed debugging of mapping service built into the Oracle Directory Integration server	131072

If you do not set a value for the debug flag, then the default level is 0 (zero).

Each trace statement in the log file includes:

• Timestamp

• Thread type

• Agent name

The various trace-statement types are:

OME:CTL	Messages from the controller thread
OME:CFG	Messages from the configuration reader thread
OME:SCH	Messages from the scheduler thread
OME:CONN	Messages from the thread which executes the agent and the mapping service

Changing the Synchronization Status Attribute

In an export operation, the server constantly updates the synchronization status attribute, orcllastappliedchangenumber, while synchronization is in progress. In Oracle Directory Manager, this field is called OID last applied change number.

To change this attribute manually from Oracle Directory Manager:

1. Disable the agent by using Oracle Directory Manager.

2. Make the attribute changes.

3. Re-enable the agent after the change.

Viewing Oracle Directory Integration Server Information

When the directory integration server starts, it generates specific runtime information and stores it in the directory. This information includes:

• Instance number of the directory integration server

• Host on which it is running

• Configuration set with which the directory integration server was started

• State of the configuration set refresh flag. This flag indicates to the directory integration server whenever there is a change to a directory integration profile and a refresh is required.

You can view this information for the directory integration server by using either Oracle Directory Manager or ldapsearch.

The entry containing the runtime information for the directory integration server uses the following format:

cn=instance_number,cn=odisrv,cn=subregistrysubentry

This section contains these topics:

• Viewing Oracle Directory Integration Server Runtime Information by Using Oracle Directory Manager

• Viewing Oracle Directory Integration Server Runtime Information by Using ldapsearch

Viewing Oracle Directory Integration Server Runtime Information by Using Oracle Directory Manager

To view runtime information for the directory integration server instance by using Oracle Directory Manager:

1. In the navigator pane, expand Oracle Internet Directory Servers > directory_server_instance > Server Management, then select Directory Integration Server. The Active Processes box appears in the right pane.

2. Click View Properties. The Server Process dialog box displays the information.

Viewing Oracle Directory Integration Server Runtime Information by Using ldapsearch

To view registration information for the directory integration server instance by using ldapsearch, perform a base search on its entry. For example:

ldapsearch -p 389 -h my_host -b cn=instance1,cn=odisrv,cn=subregistrysubentry -s 
base -v "objectclass=*"

This example search returns the following:

dn: cn=instance1,cn=odisrv,cn=subregistrysubentry
cn: instance1
orcldiaconfigdns: "orclDIAName=HR,cn=subscriber profile,cn=changelog subscriber, 
cn=oracle internet directory"
orcldiaconfigrefreshflag: 0
orclhostname: my_host
orclconfigsetnumber: 1     
objectclass: top
objectclass: orclDIA