Oracle Message Broker Adminstration Guide Release 2.0.1.0 Part Number A65435-01 |
|
Oracle Message Broker provides sample administration scripts and sample programs that allow you to quickly set up and use the system. By editing the sample scripts you can customize the system for your needs.
Note: This chapter provides a quick start guide for the steps required to operate the Oracle Message Broker in Remote Mode (Non-Local Mode). For information on using the Oracle Message Broker in Local Mode, refer to "Running in Local Mode". |
This chapter assumes that you have installed the Oracle Message Broker and that you have access to an LDAP Directory that has been updated to support the Oracle Message Broker. Refer to the Oracle Message Broker Installation Guide for information on installing these components.
This chapter covers the following:
This section shows you how to use the sample administration scripts to create Oracle Message Broker administrative objects. Oracle Message Broker stores administrative objects as entries in an LDAP Directory. See Chapter 4 for detailed information on the organization of the LDAP Directory.
Note: The Oracle Message Broker also supports lightweight configuration for administration without using an LDAP Directory Refer to Chapter 13 for information on lightweight configuration. |
The Oracle Message Broker retrieves configuration information from the LDAP Directory and uses the directory to locate and set parameters for destinations, message servers, and for other administrative tasks. Client programs also use the directory to locate the Oracle Message Broker and to find destinations for messages.
If you are setting up the Oracle Message Broker, you need to create an OMB Instance and create entries for your destinations and message servers. To perform these administration tasks you can use AdminUtil
with the sample administration scripts shown in this chapter, or you can use the Oracle Message Broker Graphical User Interface. The Oracle Message Broker Graphical User Interface provides wizards for creating OMB Instances and other required entries. For information on using ombadmin
, see Chapter 11, "Administration GUI".
The Oracle Message Broker sample administration scripts allow you to quickly create required administrative entries in the directory and set up Oracle Message Broker queues and topics. You can use these scripts as they are or customize them for your needs. Before working with the sample scripts, determine which drivers you need to use for your queues or topics (see Chapter 7, for more information on drivers). The Oracle Message Broker includes the following drivers:
Table 2-1 lists the sample scripts (these are in $OMB_HOME/samples/admin or %OMB_HOME%\samples\admin on Windows NT systems.)
The sample scripts include comments that explain the entries and attributes. If you need to modify a script, copy it and then modify the copy. You can create directory entries for Oracle Message Broker by running AdminUtil
using the sample scripts.
The SetupOMB script creates an Oracle Message Broker Instance (OMB Instance) and the required top level directory entries. An OMB Instance contains the administrative objects, as directory entries, required for an administrator to start or modify an Oracle Message Broker. The SetupOMB script also sets values for several required attributes. To execute the SetupOMB script, perform the following steps (this assumes that $OMB_HOME is set to the Oracle Message Broker installation directory):
On Unix with the Bourne or Korn shell:
$ . ./$OMB_HOME/bin/ombenv.sh
or with the C-Shell environment:
% source $OMB_HOME/bin/ombenv.csh
On Windows NT run the batch file:
> C:%OMB_HOME%\bin\ombenv.bat
The Oracle Message Broker installation creates these startup scripts (ombenv.bat, ombenv.sh, and ombenv.csh).
AdminUtil
using the SetupOMB script. AdminUtil
displays its progress as it runs.
On Unix:
% cd $OMB_HOME/samples/admin % AdminUtil -f SetupOMB
On Windows NT:
> cd %OMB_HOME%\samples\admin > AdminUtil -f SetupOMB
Note:
|
To run the driver sample scripts, perform the following steps:
AdminUtil
using the selected script for the driver you want to add. Run the SetupDriver script, where Driver is one of the following: AQ, AQLite, Vol, MQSeries, Mcast, or Rv. AdminUtil
displays its progress as it executes.
For example, to setup the Oracle Volatile Driver on Unix systems:
% AdminUtil -f SetupVol
On Windows NT systems, run the command:
> AdminUtil -f SetupVol
The propagation job sample script sets up a propagation job for transferring messages between targets. See Chapter 7 for more information on propagation and propagation jobs. To run the propagation sample script, perform the following steps:
AdminUtil
using the SetupProp script for the queues or topics that you want to propagate. AdminUtil
displays its progress as it executes.
On Unix:
% AdminUtil -f SetupProp
On Windows NT:
> AdminUtil -f SetupProp
Use the Oracle Message Broker Manager to view the contents of the directory and verify that the entries you created are in the directory. The command to start the Oracle Message Broker Manager is:
% ombadmin
When you view your OMB Instance using the Oracle Message Broker Manager, you can verify your configuration entries.
You can also use AdminDirCheck
to validate entries. Refer to "Checking Directory Entries with AdminDirCheck" for information on AdminDirCheck
.
After creating the administrative entries using the setup scripts, execute the MsgBroker
command with the -start
option to start the Oracle Message Broker. Table 2-2 shows the MsgBroker
command line options. Use the MsgBroker
command as follows:
On Unix:
% MsgBroker -omb RDN [options] &
On Windows NT:
> MsgBroker -omb RDN [options]
where RDN is:
RDN |
the relative distinguished name, RDN, for the message broker entry (for more information on distinguished names and LDAP, refer to Chapter 4). |
For example, to start the Oracle Message Broker using the RDN, cn=msg_Broker,cn=your_Inst,cn=OMB
, use the following command:
On Unix:
% MsgBroker -omb cn=msg_Broker,cn=your_Inst,cn=OMB -start &
On Windows NT:
> MsgBroker -omb cn=msg_Broker,cn=your_Inst,cn=OMB -start
For more information on starting the Oracle Message Broker, see "The msg_broker Entry and Distinguished Names".
You can also start the Oracle Message Broker in Local Mode without using the MsgBroker
command. For information on starting the Oracle Message Broker in Local Mode, refer to "Running in Local Mode".
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. |
-fullVersion |
Displays the full program version information. |
-heap size |
Supplies a heap size to the specified, size, in Megabytes. This sets the size of the JVM heap used by the Oracle Message Broker process. |
-noauth |
Specifies that LDAP authentication is not required on the LDAP server. |
-omb RDN |
Specifies the relative distinguished name, RDN, for the message broker entry (for more information on distinguished names and LDAP, refer to Chapter 4). The RDN must be enclosed in quotes on Windows NT systems. |
-P wallet_password |
Specifies the wallet password. This is ignored if the value of -U is 0 or 1. |
-ping |
Displays the status of the specified Oracle Message Broker. The status message indicates if the Oracle Message Broker is running. The |
-start |
Use this option to start the specified |
-stats format |
Produces a DMS log file containing Oracle Message Broker DMS statistics. The name of the DMS log file is the same as the associated Oracle Message Broker log file, prepended with "dms-". Refer to "Collecting Runtime Metrics" for details on the format of the DMS log file. The parameter format is set to an integer value in the range 1-4:
This option is ignored when -start or -stop are also specified on the same command-line. |
-stop |
Using this option to shutdown the specified MsgBroker. |
-U value |
Specifies if SSL is used, and the authentication level. Valid values are: 0, 1, 2, and 3. |
-version |
Displays the program version number. |
-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 you do not supply the security command line options to MsgBroker
, a dialogue box prompts for a user DN and password. Enter a user DN and password. If the directory does not use authentication, or if you have set properties to indicate the user DN and password, leave these fields blank and select the Continue button. If you select the Exit button, the MsgBroker
command exits (for more information security, refer to Chapter 12, "Security").
If -w is specified without -D, then a dialogue box prompts for the user DN.
If -D is specified without -w, then a dialogue box prompts for the user password associated with the DN supplied with the -D.
If -noauth is specified, the -D and -w options are ignored. If no authentication properties are defined, the Oracle Message Broker attempts an anonymous bind to the LDAP Directory.
Authentication and authorization are delegated to the LDAP server. The credentials required to start the Oracle Message Broker are those required for updating Oracle Message Broker entries.
Starting and stopping the Oracle Message Broker using the MsgBroker
command requires that you enter a RDN for a msg_broker
entry. For example:
% MsgBroker -start -omb cn=msg_Broker,cn=your_Inst,cn=OMB
Where the RDN for the message broker entry is:
cn=msg_Broker,cn=your_Inst,cn=OMB
In this example, the full DN for the msg_Broker
entry is the relative distinguished name shown above, plus the following:
cn=Products,cn=OracleContext,ou=sales,o=oracle,c=us
The Oracle Message Broker installer writes several distinguished name components to the startup scripts, including: the country, c=, the organization, o=, and the organizational unit, ou=. These scripts set environment variables that the MsgBroker
command uses to start the Oracle Message Broker. Oracle standards specify the following entries:
cn=OMB,cn=Products,cn=OracleContext
The initial naming context is the top level component of the full message broker DN. For example, in the sample above, the initial naming context is:
cn=Products,cn=OracleContext,ou=sales,o=oracle,c=us
The OMB_IC environment variable, that the MsgBroker
command uses contains the initial context. This variable is set in the startup scripts: ombenv.bat, ombenv.csh, and ombenv.sh (see "Using the Oracle Message Broker Instance Configuration Script" for information on these scripts).
Oracle Message Broker clients, and the MsgBroker
command require the environment variables, OMB_EF, OMB_IC, OMB_LP, and OMB_OF. The ombenv scripts define the values for these environment variables (for more information on the ombenv scripts, see "Using the Oracle Message Broker Instance Configuration Script"). Table 2-3 shows the required environment variables.
Variable | Description |
---|---|
OMB_EF |
Entry Factory |
OMB_IC |
LDAP Initial Context |
OMB_LP |
LDAP Provider Properties |
OMB_OF |
Object Factory |
The Oracle Message Broker command MsgBroker
-stop
executes a shutdown of all drivers, connections, and open transactions. To shut down the Oracle Message Broker and stop the system, issue the command:
On Unix:
% MsgBroker -omb RDN -stop &
On Windows NT:
> MsgBroker -omb RDN -stop
Where the value RDN is the relative distinguished name (RDN) for the message broker entry of the active Oracle Message Broker.
For example:
% MsgBroker -omb cn=msg_broker,cn=your_Inst1,cn=OMB -stop
If you do not supply the security command line options to MsgBroker
, a dialogue box prompts for a user DN and password. Enter a user DN and password. If the directory does not use authentication, or if you have set properties to indicate the user DN and password, leave these fields blank and select the Continue button. If you select the Exit button, the MsgBroker
command exits (for more information security, refer to Chapter 12, "Security").
Authentication and authorization are delegated to the LDAP server. The credentials required to stop the Oracle Message Broker are those required for updating Oracle Message Broker entries.
You can also stop the Oracle Message Broker when it is running in Local Mode. For information on using the Oracle Message Broker in Local Mode, refer to "Running in Local Mode".
Use the -ping
option to MsgBroker to check if an Oracle Message Broker is available. Table 2-2 shows the MsgBroker
command line options, including the -ping
option. To check the status of the Oracle Message Broker, use the MsgBroker
command as follows:
On Unix:
% MsgBroker -ping -omb RDN [options]
On Windows NT:
> MsgBroker -ping -omb RDN [options]
where RDN is:
RDN |
the relative distinguished name, RDN, for the message broker entry that you want to check the status for (for more information on distinguished names and LDAP, refer to Chapter 4). |
If the specified Oracle Message Broker is available, MsgBroker
displays the following message and returns with a 0 return value:
Broker answered
If the specified Oracle Message Broker is not available, MsgBroker
displays the following message and returns with a non-zero return value:
Broker unreachable
When running on Windows NT systems with Java 1.2, the Oracle Message Broker can be installed as a service that can be started automatically when the system starts up. To start Oracle Message Broker as a service, use the command:
%OMB_HOME%\bin\Register options
Where, options are the same as available for the MsgBroker
command (Table 2-2 shows the MsgBroker
command line options). For example, the following command registers an Oracle Message Broker instance as a service:
> Register -noauth -omb cn=msg_broker,cn=testomb,cn=OMB -start
Note that only one instance of Oracle Message Broker can be started as a service per system. Before running the register command, set the default JVM for the system to the JVM installed by Oracle Message Broker. In addition, the default PATH environment variable for the system must contain %OMB_HOME%\jdk\bin, %OMB_HOME%\bin, and %OMB_HOME%\..\..\orb\bin.
To unregister a previously registered Windows NT service, use the command:
%OMB_HOME%\bin\Unregister
The $OMB_HOME/samples/client/java/queue directory contains sample programs for sending and receiving messages (on Windows NT systems, the directory is, %OMB_HOME%\samples\client\java\queue). Sample programs for publishing and subscribing using JMS topics are in the directory $OMB_HOME/samples/client/java/topic (on Windows NT systems, %OMB_HOME%\samples\client\java\topic). The Readme files in these directories provide information on compiling and running the sample programs.
All Java client programs should include the environment variables shown in Table 2-3 on the Java command line. These environment variables set values that allow the Oracle Message Broker to run.
|
![]() Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
|