Skip Headers

Oracle Internet Directory Administrator's Guide
Release 9.0.2

Part Number A95192-01
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Go to previous page Go to next page

30
Oracle Directory Integration Server Administration

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

What the Oracle Directory Integration Server Is

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

You can run multiple directory integration server instances, on any host.

Registering the Oracle Directory Integration Server

After installing the directory integration server, you must register it with Oracle Internet Directory by using the Oracle directory integration server registration tool (odisrvreg). You must separately register each directory integration server installed on a different host, by running odisrvreg on that host. To run this tool, you need the privileges of an Oracle Internet Directory administrator.

As part of the registration, the tool creates an entry in the directory. 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. The odisrvreg tool also creates a local file called odisrvwallet, at $ORACLE_HOME/ldap/odi/conf. This file acts as a private wallet for the directory integration server, which uses it on startup to bind to the directory. Table 30-1 describes the parameters odisrvreg uses. You can also run odisrvreg in SSL mode to make communication between the tool and the directory fully secure, using three additional parameters that are also in Table 30-1.

To register the directory integration server in non-SSL mode, enter this command:

odisrvreg -h hostname -p port -D binddn  -w bindpasswd
Table 30-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

-D 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

To register the Oracle directory integration server in SSL mode, i.e., to run the registration tool in SSL mode, enter the following:

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

The three additional parameters, shown here on a separate line for clarity, are actually used on the same command line as the others.

Operational Information about the Oracle Directory Integration Server

This section introduces structural and operational information about the directory integration server and contains these topics:

The Oracle Directory Integration Server and Configuration Set Entries

Each directory integration server can execute a set of connections supporting data synchronization between Oracle Internet Directory and connected directories. The set of connectors enabling the server to support these connections is listed in its configuration set and passed as one of the command-line arguments to the server.

Whenever a connector is scheduled to do synchronization, the directory integration server starts up a separate thread. This thread opens an LDAP connection to the directory server, then closes the connection before exiting.

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

If no integration profiles are listed for the configuration set, the Oracle Directory Integration server waits indefinitely until integration profiles are added to that configuration set. (This wait also occurs if integration profiles are configured for the configuration set, but they are all disabled.)

If the configuration set specified in the command line does not exist in the directory, then the Oracle Directory Integration server logs this information in the log file and exits.

If the configuration set is not specified, then configuration set 0 is assumed, and all the provisioning profiles are considered for scheduling.

See Also:

Standard Sequences of Directory Integration Server Events

The Oracle directory integration server is the central component of the Oracle Directory Integration Platform. Any specific instance of the Oracle Directory Integration Server supports either provisioning or synchronization. The directory integration server runs as a multi-threaded process while handling the synchronization and provisioning event propagations.

The three threads described in the previous section work together to create these typical process flow sequences:

Main Thread Process Sequence

  1. On startup, the main thread comes up. This is the daemon thread of the server.

  2. The daemon thread starts up the scheduler.

  3. Checks of the registration of the instance in the directory. If, the instance is not registered, i.e.if the instance is not started up by OIDMON utility, it performs self-registration in Oracle Internet Directory with the config set number and the instance number details.

  4. Periodically checks for the refresh time and signals the scheduler to refresh.

  5. Periodically checks for the shutdown signal. On receipt of the shutdown signal, signals the Scheduler thread to shutdown.

  6. Once the scheduler thread dies, the main thread unregisters and dies.

Scheduler Process Sequence

  1. On having started by the Main thread, reads the config set to find the integration profiles to be scheduled.

  2. Creates a list of profiles to be scheduled and schedules them based on their scheduling interval.

  3. While creating the list of profiles, validates the attributes. If any of the profile attributes have invalid values, the profile is not considered for synchronization or provisioning.

  4. On receipt of the refresh signal, refreshes the integration profiles.

  5. On receipt of the shutdown signal, waits till all the connectors complete the synchronization /provisioning event propagation and returns to the main thread.

Connector Process Sequence

  1. As part of initialisation, the connector establishes connection with Oracle Internet Directory and the connected directory. If the 'data interface type' is LDIF or Tagged then appropriate files are opened.

  2. Reads the changes one at a time from the source.

  3. Filter the changes if applicable.

  4. Map the changes as specified by the mapping rules and create the destination change record.

  5. Write the changes to the destination.

  6. After applying all the changes, return back to the scheduler.

Managing Configuration Set Entries

As discussed above, a configuration set entry contains a list of all the integration profiles that the directory integration server is to execute. You can create, modify, and view configuration set entries by using either Oracle Directory Manager or the appropriate command line tools.

A configuration set is also a means of establishing an association between the host and the integration profile for synchronization. When a connector is registered, an integration profile is created and added to the configuration set. 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. Similarly, running different configuration sets and different instances on different hosts helps in balancing the load between the servers.

Managing the Oracle Directory Integration Server

This section contains these topics:

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

The directory server can be started in non-SSL mode, or in SSL mode for tighter security. Table 30-2 describes the parameters for each type of invocation.

Using the OID Monitor and Control Utilities to Start the Oracle Directory Integration Server

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

  1. Be sure that 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 "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] [refresh=interval-between-refresh] 
    [maxprofiles=number-of-profiles] "] start

    Table 30-2 describes the arguments in this command.

    Table 30-2 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 30-4 for a description of the various debug levels

    refresh=interval-between-refresh

    Specifies the interval, in minutes, between server refresh for any changes in the integration profiles.
    Default is 2 minutes (Refresh=2).

    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: 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

To start the directory server in SSL mode, use 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] [refresh=interval-between-refresh] [maxprofiles=number-of-profiles]
[ sslauth=ssl_mode ] [ wloc=wallet ] [ wpass=wallet_password] "] start

As you can see, the only difference is the use of the SSL-related flags:
sslauth=ssl_mode, wloc=wallet, and wpass=wallet_password

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

The directory server can also 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 30-2 remain the parameters for each type of invocation.

To start the directory integration server in non-SSL mode, 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]

To start the directory integration server in SSL mode, 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 ] [ wloc=wallet ] 
[
wpass=wallet_password]

Again you can see that the only difference is the use of the SSL-related flags:
sslauth=ssl_mode, wloc=wallet, and wpass=wallet_password

Stopping the Oracle Directory Integration Server

You stop the directory integration server using the same tool that you used to start it: by using OID Monitor and the OID Control Utility, or by using odisrv.

Using OID Monitor and the OID Control Utility to Stop the Server

If you started the directory integration server by using OID Monitor and the OID Control utility, then you use them to stop it, as follows:

  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 | grep oidmon
    
    

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

  2. You then can 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

In a client-only installation where the monitor and OIDCTL tools are not available, the Oracle directory integration server can be started without the OIDCTL tool. To stop the server without these tools, use the stopOdiServer.sh tool, which is located at
$ORACLE_HOME/ldap/admin/stopodiserver.sh.


Note:

To run shell script tools on the Windows operating system, you need one of the following UNIX emulation utilities:


The stopOdiServer.sh tool is used as follows:

$ORACLE_HOME/ldap/admin/stopodiserver.sh \
[-LDAPhost <LDAP server host> ] [ -LDAPport <LDAP server port> ] \
[-binddn SuperUserDN (default cn=orcladmin ) ]\
[-bindpass Bindpassword (default=welcome) ]\
-instance <Instance NUmber to STOP>

where the arguments are explained in Table 30-3.

Table 30-3 Arguments for stopping DIP server tool
Argument

Description

LDAPhost

The LDAP Server host. The default is the current host.

LDAPport

The LDAP server port The default is port 389.

Binddn

The BIND DN of the Directory user which has the privileges to create Integration profile. The default is `cn=orcladmin'

Bindpass

The BIND password. The default is welcome

Instance

The instance number of the DIP server to stop.


Note:

If the Oracle directory integration server is stopped by using any means other than the methods mentioned above, the server cannot be started from the same host. In that case, the footprint of the previous execution in the directory needs to be removed by the following command:

$ORACLE_HOME/ldap/admin/stopodiserver.sh [-LDAPhost LDAP_Server_Host] [-LDAPhost LDAP_Server_Port] [ -binddn Super_User_DN (default is cn=orcladmin)] [ -bindpass Super_User_Password (default is welcome)] -instance number_of_the_instance_to_stop -clean


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 | grep 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
    

Setting the Debug Level

You can specify the kinds of server and profile events to be 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 30-4.

  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=7" start
    
    

The various types of debug events are listed in Table 30-4 and Table 30-5.

Table 30-4 Debug Types for Server Debugging
Debug Event Type (Server debugging) Numeric Value

Starting and stopping of different threads.

1

Detail level - shows the refresh details

2

Table 30-5 Debug Types for Profile Debugging
Debug Event Type (Profiles) Numeric Value

Start and Stop of the thread

1

Initialization, execution, and end details

2

Details during execution

4

Change Record

8

Mapping Details

16

If you do not set a value for the debug flag, then the default level is 0 (zero), and none of the debug events in the tables above are logged. (However, errors and exceptions are always logged.)

When a non-zero debug level is specified, each trace statement in the server log file includes:

The various trace-statement types are:

Finding the Log Files

The log file is located in
the $ORACLE_HOME/ldap/log/odisrv_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/odisrv03.log.

All the profile-specific debug events are stored in the profile-specific trace file in $ORACLE_HOME\ldap\odi\log\profile_name.trc.

Changing the Synchronization Status Attribute

While synchronization is in progress for an export operation, the server constantly updates the synchronization status attribute, orcllastappliedchangenumber. 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:

You can view this information for the directory integration server by using either Oracle Directory Manager or 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

Managing the Oracle Directory Integration Platform in a Replicated Environment

If you use the Oracle Directory Integration platform in a replicated environment with more than one node, then set the orcldiprepository attribute in DSE root to 1. This makes the OID server generate change log entries for changes from the other Oracle Internet Directory nodes. (By default, the directory server does not generate these change log entries.) The change log entries are required for directory data to be synchronized with third-party directories and metadirectories.


Go to previous page Go to next page
Oracle
Copyright © 1999, 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index