4
Configuring Oracle Message Broker

This chapter describes tasks that you need to complete following the Oracle Message Broker installation. Some of these tasks are optional, since installations can use different drivers.

• Update Path for the JRE

• Directory Installation and Configuration

• Oracle Advanced Queuing Configuration (Optional)

• MQSeries Installation Tasks (Optional)

• TIBCO Installation Tasks (Optional)

• Asynchronous Component Invocation Installation Tasks (Optional)

• Creating an OMB Instance and Using Oracle Message Broker

• Migrating Directory Data between Releases

Update Path for the JRE

Assure that the proper version of the JRE is installed on your system, and that PATH is set appropriately. If you have several versions of the JRE on your system, make sure that first one found in your path is the version that corresponds to the version installed with Oracle Message Broker.

Oracle Message Broker Installer installs JRE in the directory, $OMB_HOME/jdk for Sun SPARC Solaris, and it sets the path in the ombenv environment scripts in the directory $OMB_HOME/bin to use the supplied JRE.

Directory Installation and Configuration

The LDAP Directory needs to be installed on a system available to, and configured for use with Oracle Message Broker. You can install the LDAP Directory on the same system as Oracle Message Broker, or on a separate system. This section covers directory installation and configuration.

Oracle Message Broker requires an LDAP Directory to handle administrative functions. Oracle Message Broker supports two LDAP Directory products:

• Oracle Internet Directory (OID) Release 2.0.6

• Netscape Directory Server (running on a Windows NT system)

Install Oracle Internet Directory before Oracle Message Broker if you are using the same $ORACLE_HOME for both Oracle Internet Directory and Oracle Message Broker.

Note: When you install Oracle Internet Directory, do not use any upper case letters in the ORACLE_HOME path since upper case letters can cause the installer to fail.

Oracle Internet Directory is available from Oracle. Refer to the following web page for information on Oracle Internet Directory,

http://www.oracle.com/database/oid

See Also: Refer to Oracle8i Installation Guide for Sun SPARC Solaris Release 3 (8.1.7) and Oracle Internet Directory Release Notes for more information on installing Oracle Internet Directory: Refer to the Oracle Message Broker Installation Guide for information on installing the Netscape Directory Server.

Supplying the Directory Bind DN

All of the Oracle Message Broker commands that access the LDAP Directory, including those used during the installation process require that a bind DN and a password be supplied.

For Oracle Internet Directory, the default bind DN is cn=orcladmin and the default password welcome. The bind DN cn=orcladmin is the default superuser bind DN, and has superuser privileges. Only the LDAPSchema command and possibly the InitDir command, depending on the directory setup, require super user privileges.

It is recommended that users create user and group entries in the directory and use the bind DN and password corresponding to non-superuser entries. Setting up user and group entries requires knowledge of LDAP and the LDAP server specific tools such as oidadmin.

See Also: For details on the types of users needed for Oracle Message Broker, see the Oracle Message Broker Administration Guide.

There are three ways to supply the bind DN and the password:

• At the prompt, when running a command, such as InitDir.

• By using the command-line options -D and -w.

• By directly setting JNDI properties. If you set JNDI properties and want to use values set when running an Oracle Message Broker command, either use the command line option -noauth or supply no values at the supplied authentication prompt.

  The JNDI Java properties for setting security options are:

  java.naming.security.principal
  java.naming.security.credentials
  java.naming.security.authentication=simple
  

Directory Configuration

After the LDAP Directory and Oracle Message Broker are both installed, you need to perform several configuration tasks on the directory. The tasks use tools installed with Oracle Message Broker. These tools modify the directory and require an active directory server. The directory modifications support the Oracle Message Broker administrative functions.

1. Start the LDAP Directory after the Oracle 8i database server is up and running.
   1. Use the OID command oidmon to start the OID monitor.

      % oidmon connect=connect_string start
      
      

      where connect_string specifies the Net8 connect descriptor for connecting to the database server.

   2. Use the OID command oidctl to start the OID instance.

      % oidctl connect=connect_string server=oidldapd instance=1 start
      
      

      where connect_string specifies the Net8 connect descriptor for connecting to the database server.

2. Assure that the proper version of the JDK is installed on your system. If you have several versions of the JDK on your system, make sure that first one found in your path is the version required by Oracle Message Broker.

3. Modify the directory schema to support the Oracle Message Broker.
   1. Set the environment for your system:

      For the Bourne or Korn shell:

      $ . $ORACLE_HOME/omb/2.0/bin/ombenv.sh
      

      For the C shell:

      % source $ORACLE_HOME/omb/2.0/bin/ombenv.csh
      

      The Oracle Message Broker installation creates the startup scripts ombenv.sh or ombenv.csh.

   2. Update the directory schema using the LDAPSchema command found in the $ORACLE_HOME/omb/2.0/bin directory.

      % LDAPSchema [options]
      
      

      Options are shown in Table 4-1.

      The LDAPSchema command creates an LDAP Directory entry, cn=OracleSchemaVersion at the root. This entry contains the attribute, orclProductVersion, defining the version number of the Oracle Message Broker LDAP schema. LDAPSchema updates the LDAP schema only if the entry cn=OracleSchemaVersion does not exist, or, if the value for orclProductVersion is lower than the current version for the LDAPSchema command.

      Table 4-1  LDAPSchema Command Line Options

      Option	Description
      -D auth_dn	The auth_dn supplies the DN to use for user name authentication.
      -errorlevel level	Set the error reporting level. The parameter level is set to an integer value in the range 1-4: 1 - print error message for the top exception 2 - print error messages for all linked exceptions 3 - print stack trace for the top exception 4 - print stack trace for all linked exceptions The default value for errorlevel is 2.
      -h host-name	The host-name is the host where the directory is installed. Default value: localhost
      -noauth	Specifies that LDAP authentication is not required on the LDAP server.
      -p port	The port is the port used to access the directory on the specified host. Default value: 389
      -P wallet_password	Specifies the wallet password. This is ignored if the value of -U is 0 or 1.
      -ldapv2	Use this option when the LDAP Directory only supports LDAP version 2. Default value: LDAPSchema defaults to support for LDAP version 3.
      -U value	Specifies if SSL is used, and the authentication level. Valid values are: 0, 1, 2, and 3. 0 - no SSL. This is the default if -U is not specified. 1 - SSL with no authentication. 2 - SSL with server-side authentication. 3 - SSL with server-side and client-side authentication.
      -version	Provides version information. Use -fullVersion for detailed version information.
      -w auth_passwd	Supplies a password, auth_passwd, for authentication on the LDAP server.
      -W wallet_path	Specifies the path to an exported wallet file. This is ignored if the value of -U is 0 or 1.

      If the security options -D, -noauth, or -w are not used, LDAPSchema prompts for an authentication DN and a password.

      If the LDAP Directory has authentication enabled, enter the directory administrator's entry DN and password.

      For example, to modify the LDAP schema for the LDAP Directory running on the host named system1, and the default port number, 389, use the command:

      % LDAPSchema -h system1 
      
      

      If LDAPSchema prints the following message, you need to run catalog.sh, as described in step 4, :

      ### ATTENTION: The attribute "orcloasentrytype" is not searchable. 
      Please run "catalog.sh" on OiD to make this attribute searchable
      

3. Modify the directory for the Oracle Message Broker suffix with the InitDir command found in the $ORACLE_HOME/omb/2.0/bin directory. Use InitDir as follows:

   % InitDir [options]
   
   

Table 4-2 shows the available options.

Table 4-2  InitDir Command Line Options

Option	Description
-b base_dn	Create all entries under the specified base_dn. The DN specified for the base_dn must exist in the directory.
-c country	Specifies the country to use for the root naming context
-D auth_dn	The auth_dn supplies the DN to use for user name authentication.
-errorlevel level	Set the error reporting level. The parameter level is set to an integer value in the range 1-4: 1 - print error message for the top exception 2 - print error messages for all linked exceptions 3 - print stack trace for the top exception 4 - print stack trace for all linked exceptions The default value for errorlevel is 2.
-h host-name	The host-name is the host where the directory is installed. Default value: localhost
-noauth	Specifies that LDAP authentication is not required on the LDAP server.
-o org	Specifies the organization to use for the root naming context.
-ou org-unit	Specifies the organizational unit to use for the root naming context.
-p port	The port is the port used to access the directory on the specified host. Default value: 389
-P wallet_password	Specifies the wallet password. This is ignored if the value of -U is 0 or 1.
-U value	Specifies if SSL is used, and the authentication level. Valid values are: 0, 1, 2, and 3. 0 - no SSL. This is the default if -U is not specified. 1 - SSL with no authentication. 2 - SSL with server-side authentication. 3 - SSL with server-side and client-side authentication.
-ldapv2	Use this option when the LDAP Directory only supports LDAP version 2. The default, without this option is support for LDAP version 3.
-version	Provides version information. Use -fullVersion for detailed version information.
-w auth_passwd	Supplies a password, auth_passwd, for authentication on the LDAP server.
-W wallet_path	Specifies the path to an exported wallet file. This is ignored if the value of -U is 0 or 1.

The values you select for the -c, -o, and -ou options to InitDir should match the LDAP base naming context information that you supplied on the Suffix Information screen while running the Oracle Message Broker installer.

If the security options -D, -noauth, or -w are not used, InitDir prompts for an authentication DN and a password.

If the LDAP Directory has authentication enabled, enter the directory administrator's entry DN and password to use the InitDir command.

For example, to initialize the LDAP Directory running on the host named system1, and the default port number, 389, use the command:

% InitDir -h system1 -c us -o oracle -ou sales

This assumes that the directory is being initialized for Oracle Message Broker from the root specified with the -c, -o, and -ou options.

4. Make the Oracle Internet Directory attributes searchable. Only perform this step when the LDAPschema command described in step 2 prints the following message:

   ### Attention: The attribute orcloasentrytype is not searchable. Please run 
   catalog.sh on OiD to make this attribute searchable.
   

   LDAPSchema prints this message when there is data in the directory which uses the attribute orcloasentrytype and orcloasentrytype was not cataloged. In this case, LDAPSchema cannot catalog the attribute and catalog.sh must be run manually.

   1. Issue the following commands on the system where Oracle Internet Directory is installed and running.

      % cd $ORACLE_HOME/ldap/bin
      % catalog.sh -connect connect_string -add -attr orcloasentrytype
      

      where connect_string specifies the Net8 connect descriptor for connecting to the database server.

   2. Enter the password when the catalog.sh command prompts you. The default password is ods, which is the default OID database server password. If you change the password using oidpasswd before running catalog.sh, use the new password, rather than the default password.

      See Also: For the OID directory, these steps require an active Net8 listener. For more information on Net8 listeners, refer to the Oracle Net8 Administrator's Guide.

Restart OID (Optional)

It is possible that Oracle Internet Directory may need to be restarted after running catalog.sh. It is also possible for step 4 in Directory Configuration to not fully complete its actions. If step 4 did not fully complete its actions, directory operations, including use of AdminUtil or ombadmin may report the following error message:

DSA unwilling to perform: operation not supported

The following steps provide a workaround for this problem:

1. Run the following commands:

   catalog.sh -connect connect_string delete -attr orcloasentrytype
   catalog.sh -connect connect_string -add -attr orcloasentrytype
   
   

   where connect_string specifies the Net8 connect descriptor for connecting to the database server.

2. Shutdown the oidldapd instance(s) using oidctl.

3. Shutdown oidmon.

   oidmon connect=connect_string stop
   
   

4. Shutdown the database server.

5. Start the database server.

6. Start oidmon using the command:

   oidmon connect=connect_string start
   
   

7. Start the oidldapd instance(s) using oidctl.

Oracle Advanced Queuing Configuration (Optional)

This section covers the configuration steps for using Oracle 8i Advanced Queuing feature with the Oracle Message Broker. Perform the steps in this section if you are using Oracle Message Broker and the Oracle AQ Driver.

Stop Oracle Internet Directory

If you are running Oracle AQ using the same Oracle 8i database server as Oracle Internet Directory, then you need to shutdown both Oracle Internet Directory and Oracle 8i database server. This section covers shutting down Oracle Internet Directory.

1. Use the OID command oidctl to stop the OID instance.

   % oidctl connect=connect_string server=oidldapd instance=1 stop
   
   

   where connect_string specifies the Net8 connect descriptor for connecting to the database server.

2. Use the OID command oidmon to stop the OID monitor.

   % oidmon connect=connect_string stop
   
   where connect_string specifies the Net8 connect descriptor for connecting 
   to the database server.
   

   See Also: For information on oidct.l and oidmon, see the Oracle Internet Directory Administrator's Guide.

Stop the Database Server and the Listeners

On the system running Oracle8i database server, perform the following steps:

1. Stop the Net8 Listeners with the lsnrctl command.

   lsnrctl 
   lsnrctl> stop
   lsnrctl> quit
   

2. Navigate to the Oracle8i database server home directory.

3. Start SQL*Plus.

   % sqlplus
   

4. Log in as INTERNAL.

5. Stop the database.

6. Shutdown the server.

   SQL> SHUTDOWN [MODE]
   
   

   where, MODE is one of the following:

   	Normal	The database server waits for all currently connected users to disconnect and disallows any new connections before shutting down. This is the default mode.
   	Immediate	The database server terminates and rolls back active transactions, disconnects clients, and shuts down.

   See Also: See the Net8 Administrator's Guide for more information on stopping listeners.

Configure Database Parameters

The Oracle8i database server needs to be configured to support the resource requirements for Oracle Message Broker. Active Oracle Message Brokers consume transactions, sessions, cursors, and processes. Other applications may also use the database server and have their own resource needs.

Table 4-3 shows the database server requirements for Oracle Message Broker. These requirements are in addition to the requirements for any other applications that will use the database server.

Keep the following points in mind when configuring an Oracle8i database server:

• The DBMS must be restarted when initSID.ora is edited

• It is better to not be too conservative when setting limits.

• The OS kernel may need to be configured to support some of these parameters and the system may need to be rebooted. Consult the platform specific Oracle8i install guide for details.

  Table 4-3  Oracle8i Database Server Parameters Required for Oracle Message Broker

  Parameter	Description
  AQ_TM_PROCESSES = num_aq	The value of num_aq must be > 1.
  LICENSE_MAX_ SESSIONS = num_license	The value of num_license must be greater than the following: num_license > num_processes See PROCESSES below for information on the value of num_processes.
  OPEN_CURSORS = num_open	The num_open must be, at a minimum: num_open = Max( (2*maxConsumers), numQueues ) * 1.2 Where: maxConsumers is the maximum number of consumers. A consumer is a QueueReceiver or a TopicSubscriber within a JMS session. numQueues is the number of AQ queues configured for the Oracle Message Broker. This equation should determine the maximum number of cursors used by any Oracle Message Broker managed database server connection. If other uses require more cursors, then OPEN_CURSORS should be set to the value required.
  PROCESSES= num_processes	The num_processes must be, at a minimum: num_processes = (maxPrivate + maxShared + aq_tm_processes) * 1.2 maxPrivate is the sum of the maxPrivateSessions attribute values for all Oracle Message Broker that concurrently use the database server. maxShared is the sum of the maxSharedSessions attribute values for all Oracle Message Brokers that concurrently use the database server. aq_tm_processes is the value of AQ_TM_PROCESSES from the init.ora file. See chapter 4, "Managing Oracle Processes," in the Oracle 8i Administrator's Guide for more information on managing processes. This assumes use of dedicated database servers. If other applications use the same database server, their resource needs also must be included.
  SESSIONS = num_sessions	The value of num_sessions where num_sessions > num_processes.
  TRANSACTIONS = num_trans	The num_trans must be, at a minimum: num_trans = (2 * maxPrivate + maxShared) * 1.2 maxPrivate is the sum of the maxPrivateSessions attribute values for all Oracle Message Broker that concurrently use the database server. maxShared is the sum of the maxSharedSessions attribute values for all Oracle Message Broker that concurrently use the database server.

Restart the Database Server and the Listeners

On the system running Oracle8i database server supporting AQ, restart the database. To start an Oracle8i database server, navigate to the Oracle8i database server home directory.

1. Start SQL*Plus at the command prompt.

   % sqlplus
   
   

2. Log in as INTERNAL.

3. Start the database.

   SQL> STARTUP
   
   

4. Exit SQL*Plus.

   SQL> EXIT
   
   

5. Restart the Net8 Listeners.

   lsnrctl
   lsnrctl> start
   lsnrctl> quit
   

See Also: For more information on starting listeners, see Net8 Administrator's Guide.

Start Oracle Internet Directory

If you are running Oracle AQ using the same Oracle 8i database server as Oracle Internet Directory, then you need to startup both the OID and the Oracle 8i database server. This section covers starting OID after the database server is up and running.

1. Start the OID monitor.

   % oidmon connect=connect_string start
   
   

   where connect_string specifies the Net8 connect descriptor for connecting to the database server.

2. Start the OID instance.

   % oidctl connect=connect_string server=oidldapd instance=1 start
   
   

   where connect_string specifies the Net8 connect descriptor for connecting to the database server.

   See Also: For information on oidct.l and oidmon, see the Oracle Internet Directory Administrator's Guide.

Initialize AQ

After installing the Oracle Message Broker and the Oracle8i database server, initialize AQ. The Oracle8i database server needs to be running to use the scripts step1.sql, step2.sql and step3.sql located in the $OMB_HOME/admin/plsql directory. These scripts initialize AQ for use with Oracle Message Broker and provide support to allow the AQ Driver to work with AQ queues and topics.

1. Run the three AQ setup scripts:

   % sqlplus system/system_password[@service_name] @step1
   % sqlplus system/system_password[@service_name] @step2
   

   % sqlplus aq/aq[@service_name] @step3

   where system_password is the password for the system administrative user and service_name is the database service name.

   The step1.sql script is only required if this is the first time that Oracle Message Broker pl/sql support is installed. It creates the user aq with the password aq. The administrative sample script SetupAQ requires that you supply the password values for AQ. After installation, the AQ password can be changed using the database server Enterprise Manager, or using the database server ALTER USER SQL command.

   One or more of the following errors messages are expected while running the script step3.sql. You can ignore these error messages.

   ORA-00942: table or view does not exist
   ORA-04043: xx does not exist
   ORA-04043: object xx does not exist
   

   The step2 script is required and does the following:

   • It grants privileges to user aq

   • Creates the role ombadmin

   • Grants privileges to role ombadmin

   • Creates role ombuser

   • Grants privileges to role ombuser

   The step3 script is required and does the following:

   • Installs package ombaq in the aq schema

   • Installs package ombaqadm in the aq schema

   • Grants execute on ombaq to ombuser, ombadmin

   • Grants execute on ombaqadm to ombadmin

   One or more of the following errors messages may occur while running the script step3.sql. You can ignore these error messages.

   ORA-00942: table or view does not exist
   ORA-04043: xx does not exist
   ORA-04043: object xx does not exist
   

Remove AQ Queue Tables

Oracle Message Broker also provides a script to remove the tables and users that are created for AQ. If you need to remove these tables, use the following command to remove the AQ Driver support from the database server:

% sqlplus system/system_password[@service_name] @uninstall

where system_password is the password for the system administrative user and service_name is the database service name.

The uninstall script does the following:

• Drops the ombadmin and ombuser roles

• Drops the aq user (using the cascade option)

• Removes all of the queues and queue tables that exist in the AQ schema

One or more of the following types of errors may occur while running this script:

ORA-00942: table or view does not exist
ORA-04043: xx does not exist

Note: The uninstall script performs these functions only if no queue tables outside of the schema aq use Oracle Message Broker object types. If queue tables outside of the schema aq use the Oracle Message Broker object types, executing the uninstall script lists those queue tables, prints an error message, and quits.

MQSeries Installation Tasks (Optional)

This version of the Oracle Message Broker only supports IBM MQSeries V5.1. For details on installing MQSeries, refer to the MQSeries documentation available from IBM and supplied with the MQSeries product.

TIBCO Installation Tasks (Optional)

To use the Oracle Message Broker with the TIBCO Driver you need to install and start up TIB/Rendezvous Release 5.x or TIB/Rendezvous Pro Release 5.x (when using the JDK 1.2 version of Oracle Message Broker, TIB/Rendezvous Pro Release 5.x is required).

See Also: For information on TIB/Rendezvous installation and administration, see TIB/Rendezvous Administrator's Guide. For information on TIB/Rendezvous, see the web site http://www.rv.tibco.com/

Asynchronous Component Invocation Installation Tasks (Optional)

If you are using the Oracle Message Broker Asynchronous Component Invocation (ACI), you need to load Oracle Message Broker's client classes in the Oracle database server, and grant permissions to the schema in which the EJB executes using the following two commands (replace SCOTT/TIGER with your schema and password):

# grant permissions to SCOTT
sqlplus sys/sys_password @$OMB_HOME/admin/plsql/setupaci.sql SCOTT
# Loading OMB client classes
loadjava -r -g SYS -u SCOTT/TIGER ${OMB_HOME}/classes/ombclt.jar

or on Windows NT systems:

sqlplus sys/sys_password @%OMB_HOME%\admin\plsql\setupaci.sql SCOTT
loadjava -r -g SYS -u SCOTT/TIGER %OMB_HOME%\classes\ombclt.jar

where:

sys_password is the administrative sys user password.

Note: Run these commands once for each schema, prior to deploying EJBs in the schema.

Creating an OMB Instance and Using Oracle Message Broker

At this point, the installation for Oracle Message Broker, the LDAP Directory, and the required providers is complete. The next step is to configure Oracle Message Broker and to start using Oracle Message Broker. Refer to Oracle Message Broker Administration Guide for information on creating an OMB instance, working with the administrative utilities, the sample administrative scripts, and starting Oracle Message Broker.

Migrating Directory Data between Releases

Migrating from Release 2.0.0.0 to Release 2.0.1.0

If you are migrating from Oracle Message Broker Release 2.0.0.0 to Release 2.0.1.0, run the command InitDir with the same options used when installing Release 2.0.0.0, which will update the LDAP schema, as required for Release 2.0.1.0.

Migrating Between Releases 1.0 to 2.0

If you are installing Oracle Message Broker and you need to migrate existing LDAP Directory entries created for an older version of Oracle Message Broker, you can use the Migrate10To20 utility.

See Also: Refer to the Oracle Message Broker Administration Guide for information on using Migrate10To20.