Oracle Message Broker Adminstration Guide
Release 2.0.1.0

Part Number A65435-01

Library

Product

Contents

Index

Go to previous page Go to next page

4
Administration

The Oracle Message Broker supports two means of specifying configuration information for administration: using an LDAP Directory, and using lightweight configuration. With lightweight configuration, the Oracle Message Broker reads configuration information from a file or from Java properties when it begins its execution. This chapter describes using an LDAP Directory for configuration information. Refer to Chapter 13, "Lightweight Configuration" for details on using a configuration file or Java properties to specify configuration information.

When administrative information is stored in an LDAP Directory, directory entries contain the names and configuration options for Oracle Message Broker administrative objects such as JMS destinations (topics or queues). This chapter introduces the LDAP Directory and describes the directory entries. The chapter also covers the administrative utilities that modify and check directory entries.

When the Oracle Message Broker starts, and it is using the directory, it writes an address into a directory entry. Clients use this address to contact the Oracle Message Broker. In addition, while the Oracle Message Broker is running, the administrative utilities notify it of configuration changes. For example, Oracle Message Broker is notified when administrators change configuration parameters.

This chapter includes the following sections:

What is the Oracle Internet Directory?

Oracle Internet Directory is a directory service implemented as an application on the Oracle 8i database. It enables retrieval of information about dispersed users and network resources. It combines Lightweight Directory Access Protocol (LDAP) Version 3, the open Internet standard directory access protocol, with the high performance, scalability, robustness, and availability of the Oracle8i Server.

What is a Directory?

A directory is a way of organizing information so that it can be found easily. It lists objects--for example, people, books in a library, merchandise in a department store--and gives details about each one. Information in the directory is stored in a hierarchy of directory entries. A directory entry consists of attributes and their values. The directory contains administrative objects that store Oracle Message Broker configuration options.

What is LDAP?

LDAP (Lightweight Directory Access Protocol) is the emerging Internet standard for directory services. It is based on the earlier ISO X.500 Directory Access Protocol (DAP) standard, but simplifies that standard considerably, allowing LDAP to be more efficient, straightforward, and easier to implement.

Oracle Internet Directory implements Version 3 of LDAP, which was approved as a proposed Internet Standard by the Internet Engineering Task Force (IETF) in December 1997.

The LDAP specification is contained in a number of public documents of the Internet Engineering Task Force called RFCs (Requests for Comments). In particular, LDAP Version 3 is defined in RFCs 2251-2256. These are available on the worldwide web at:

http://www.ietf.org/rfc

The building blocks of an LDAP Directory service are called directory entries. Each entry has a unique name, called a distinguished name. Each entry contains information items, called attributes. Attributes are grouped into categories, called object classes.

Directory Entries

In a directory, each collection of information about an object is called an entry. For example, a typical telephone directory includes entries for people, and a library card catalog contains entries for books. Similarly, the Oracle Message Broker directory includes entries containing configuration information for Oracle Message Broker components.

Each entry in a directory is uniquely identified by a distinguished name (DN). The distinguished name tells you exactly where the entry resides in the directory's hierarchy represented by the Directory Information Tree (DIT).

To understand the relation between a distinguished name and a DIT, look at Figure 4-1.

Figure 4-1 A Directory Information Tree


The DIT shown in Figure 4-1 is structured along geographical and organizational lines. It diagrammatically represents entries for two employees who have the same common name (cn), namely, Anne Smith.

The DIT branch on the right represents the entry for the Anne Smith who works in an organizational unit (ou) named Server Development, in the organization (o) Oracle, in the country (c) of Switzerland (ch).

The DN for this "Anne Smith" entry is:

cn=Anne Smith,ou=Server Development,o=Oracle,c=ch

Note that the conventional format of a distinguished name places the lowest DIT component at the left, then follows it with the next highest component, and thus moving progressively up to the root.

Within a distinguished name, the lowest component is called the relative distinguished name (RDN). For example, in the above entry for Anne Smith, the RDN is cn=Anne Smith. Similarly, the RDN for the entry immediately above Anne Smith's RDN is ou=Server Development, the RDN for the entry immediately above ou=Server Development is o=Oracle, and so on. A DN is made up of a sequence of RDNs separated by commas.

To locate a particular entry within the overall DIT, a client uniquely identifies that entry by using the entry's full DN--not simply the RDN. For example, within the global organization in Figure 4-1, there are two employees with the same RDN, namely, Anne Smith. To avoid confusion between these two entries, you would use each one's full DN. If there are potentially two employees with the same name in the same organizational unit, you could use additional mechanisms, such as uniquely identifying each employee with an identification number.

Distinguished Name Format

When you use a DN with the Oracle Message Broker utilities, or in an Oracle Message Broker client program, be aware of the following:

  1. A DN is case-insensitive.

  2. The RDN portion of a DN can be separated by either a comma, ',' or a semi-colon, ';'.

  3. White spaces between the components of a DN are ignored.

    For example, the following DNs are equivalent:

    cn=sales,cn=oracle,c=us
    cn=sales;cn=oracle;c=us
    cn  = sales; cN=oRacLE;C=US
    
    
  4. In a DN, you can escape the following characters using a backslash (\).

     

    Quote 

     

    Comma 

     

    Colon 

     

    Plus 

     

    Equals 

     

    Semi-colon 

     

    Backslash 

     

    Pound 

     

    Less than 

     

    Greater than 

Attributes

In a typical telephone directory, an entry for a person contains such information items as an address and phone number. In an online directory, such information items are called attributes. Attributes in a typical employee entry could include a job title, e-mail address, and phone number.

In Figure 4-1, the entry for Anne Smith in Switzerland has several attributes, each providing specific information about her. These are listed in the balloon to the right of the tree, and they include emailaddrs=, printername=, jpegPhoto=, and app preferences=. Moreover, each bullet in Figure 4-1 is also an entry with attributes, although the attributes for each are not shown.

Each attribute consists of an attribute type and one or more attribute values. The attribute type identifies the kind of information that the attribute contains--for example, job title. The attribute value is the particular instance of information appearing in that entry. For example, in the entry for Anne Smith, the value for the job title attribute could be manager.

Kinds of Attribute Information

Attributes contain two kinds of information.

Application Information 

This information is maintained and retrieved by the directory clients and is unimportant to the operation of the directory. A telephone number, for example, is application information. 

Operational Information 

This information pertains to the operation of the directory itself. Some operational information is specified by the directory to control the server--for example, the time stamp for an entry. Other operational information, such as access information, is defined by administrators and is used by the directory program in its processing. 

Any given attribute can hold either application information, or operational information, but not both.

Single-Valued and Multiple-Valued Attributes

Attributes can be either single-valued or multiple-valued. Single-valued attributes carry only one value in the attribute, whereas multiple-valued attributes can have more than one value. An example of a multiple-valued attribute is a group membership list that includes the names of all the members of a given group, such as an e-mail list.

Object Classes

The Oracle Message Broker defines several directory entries, and assigns object classes to the entries. These object classes define groups of attributes. An object class is a category of objects, and it provides both mandatory and optional attributes for particular objects.

For example, the organizationalPerson object class includes the mandatory attributes commonName (cn) and surname (sn). The Oracle Internet Directory provides standard LDAP object classes, several proprietary object classes, as well as object classes that are added to support the Oracle Message Broker.

Schemas

All information about how data is organized in the DIT--that is, metadata such as object classes, attributes, matching rules, and syntaxes--is contained in the directory schema. This information is contained in a special class of entry called a subentry. Oracle Internet Directory holds schema definitions in the subentry called cn=subSchemaSubentry. To provide directory support for the Oracle Message Broker the installation includes scripts that add object classes and attributes to the directory entry cn=subSchemaSubentry.

Accessing LDAP with the Administrative Framework

The Oracle Message Broker and the administrative utilities use the LDAP Directory to read or modify administrative objects. To facilitate use of the directory, the Oracle Message Broker includes a support layer called the administrative framework. The administrative framework provides methods to access entries in the directory, validate DNs, map LDAP attributes to Oracle Message Broker options, and perform a number of other functions. The Oracle Message Broker administrative framework hides LDAP from the administrator and provides significant error checking for directory modifications. Using the administrative framework and the administrative utilities, an administrator only needs to use a few commands and understand distinguished names to perform Oracle Message Broker administration.

The administrative framework uses JNDI to access the directory. Figure 4-2 shows the Oracle Message Broker components and shows how these components use the administrative framework to access the directory.

Figure 4-2 Directory Access with the Administrative Framework


Oracle Message Broker Directory Information Tree

This section describes the structure and the organization of Oracle Message Broker administrative information. This structure is defined when the directory is modified to support the Oracle Message Broker. The steps required to modify the directory are installation tasks (see the Oracle Message Broker Installation Guide for details). After the directory is modified, an administrator can use the Oracle Message Broker administrative utilities to create, delete, or modify Oracle Message Broker entries.

Figure 4-3 shows a DIT containing several Oracle Message Broker instance entries, and the entries that are created to support the Oracle Message Broker security service (for information on the security service, see Chapter 12, "Security"). An Oracle Message Broker instance, OMB Instance, contains the administrative objects needed to start or modify the Oracle Message Broker. These entries also allow a JMS client to contact the Oracle Message Broker. Figure 4-4 shows the contents of an OMB Instance. Table 4-1 describes the OMB Instance entries in more detail.

An administrator creates an OMB Instance for each active Oracle Message Broker (Local Mode allows for sharing of OMB Instances. See Chapter 5, "Oracle Message Broker Features" for information on running in Local Mode). An administrator creates multiple OMB Instances to support different working groups in an organization, for improved performance, or to support multiple networks of communicating Oracle Message Brokers using one or more directories.

Figure 4-3, Table 4-1, and Figure 4-4 show fixed container entries in bold; the administrator uses the Oracle Message Broker administration utilities to create these entries in the directory with the name exactly as shown. User defined container entries, such as topic1, are shown in italics; these entries can have any name that an Oracle Message Broker Administrator chooses, and multiple entries are allowed.

Figure 4-3 Top Level Directory Organization


Figure 4-4 OMB Instance Directory Organization



Table 4-1  OMB Instance Entries
Entry  Description 

OMB_instance1 

This is the top-level of an Oracle Message Broker directory instance. A complete OMB Instance contains all the entries required to use an Oracle Message Broker, or for a JMS client to contact an active Oracle Message Broker. 

ACI 

A fixed container defining asynchronous component invocation 

queuetrigger1 

An entry defining an ACI queue trigger 

topictrigger1 

An entry defining an ACI topic trigger 

aq_driver 

A driver entry for an Oracle AQ Driver 

aq_server 

An entry for Oracle AQ Server information. An instance may have 0 or 1 aq_server entries. 

aqlite_driver 

A driver entry for an Oracle AQ Lite Driver. 

aqlite_server 

An entry for Oracle AQ Lite Server information. An instance may have 0 or 1 aqlite_server entries. 

ConnectionFactories 

A fixed container defining the instance connection factories 

connection_factory1 

A connection factory entry. At least one connection factory must be defined per driver. 

DurableSubscribers 

A fixed container defining durable subscribers 

durable_sub1 

A durable subscriber entry. All attributes for a durable subscriber are read-only-after-create. This means that you can only view the durable subscriber attributes. To modify a durable subscriber, delete the entry and then recreate it.

 

prop_http 

Specifies the HTTP propagation listener options 

mcast_driver 

A driver entry for an Oracle Multicast Driver 

mcast_server 

An entry for Oracle Multicast Server information. An instance may have 0 or 1 mcast_server entries. 

mq_driver 

A driver entry for an MQSeries Driver 

mq_server 

An entry for MQSeries Server information. An instance may have 0 or 1 mq_server entries. 

msg_broker 

A fixed name container for Oracle Message Broker configuration parameters.

A msg_broker entry contains 1 (one) or more driver entries. 

PropagationJobs 

A fixed container defining propagation jobs 

propagation_job1 

A propagation job entry 

Queues 

A fixed container defining queues 

queue1 

A queue entry 

RemoteDirectories 

A fixed container defining remote directories 

remote_dir1 

A remote directory entry 

RemoteHttpListeners 

A fixed container defining remote HTTP listeners 

remotehttp1 

An HTTP remote listener entry 

rv_driver 

A driver entry for a TIBCO Driver 

rv_server 

An entry for TIBCO Server information. An instance may have 0 or 1 rv_server entries. 

Topics 

A fixed container defining topics 

topic1 

A topic entry 

volatile_driver 

A driver entry for an Oracle Volatile Driver 

Oracle Message Broker Configuration

This section covers the options for configuring the Oracle Message Broker and provides tables listing the Oracle Message Broker directory entries and attributes. Refer to "Working with the Administration Utilities" for configuration examples.

To configure an OMB Instance, you perform two types of actions, creating directory entries and modifying attributes. This section provides information on these actions.

Oracle Message Broker Configuration Roadmap

After the LDAP Directory and the Oracle Message Broker are installed, you can add and configure OMB Instances. Using the Oracle Message Broker AdminUtil command, the following checklist shows the Oracle Message Broker configuration steps:

Reserved Internal Attributes

The reserved, internal attributes are common to all Oracle Message Broker entries. These attributes are reserved for internal use or for future use and should never be used, or modified with the Oracle Message Broker administration utilities, or with any other utilities that modify Oracle Message Broker entries. The list of attributes in Table 4-2 applies to all of the following tables: Table 4-3 through Table 4-22.

Table 4-2  Reserved Attributes (for internal use only)
Attribute  Description 

binary 

Reserved for internal use only 

internal 

Reserved for internal use only 

xml 

Reserved for internal use only 

Creating an Oracle Message Broker Instance

A valid OMB Instance contains all the directory entries required for an administrator to run an Oracle Message Broker. Each OMB Instance is created with a user defined container name. The OMB Instance container name is supplied when the OMB Instance is created. Refer to Figure 4-4 for a view of the contents of an OMB Instance.

Use the AdminUtil createombinstance command to create an Oracle Message Broker instance. The following sections show how to add entries and set attribute values for the entries in the OMB Instance. Refer to "Command-line Administration Utility - AdminUtil" for information on using AdminUtil.

For example, to create the OMB Instance named TestOMB using the createombinstance command (the Oracle Message Broker installation tasks create the required Oracle Message Broker directory entry named OMB, as well as other required directory entries).

% AdminUtil
> createombinstance TestOMB cn=OMB ;

Creating and Configuring Message Servers

Oracle Message Broker server entries provide information about message servers. Message server entries contain configuration options and access information for a supported message storage facility. The Oracle Message Broker supports the following message server types:

The Oracle Message Broker only supports 0 or 1 server entries of a given type within an OMB Instance. The administration utilities do not prevent you from creating multiple server entries. The Oracle Message Broker, at startup, reports the following error if it finds multiple server entries of the same kind in an OMB Instance:

Error starting broker, caught BadStateException: Entry defined twice

Setting AQ Server Options

An aq_server contains the attributes listed in Table 4-3. To configure the AQ Server, create the aq_server entry and then set the appropriate attributes.

Table 4-3  AQ Server Attributes
Attribute  Description 

aq_password 

Stores the password required to use AQ on the Oracle 8i Database Server. The value stored is encrypted in the directory. 

aq_service_name 

Specifies the service name for the AQ Oracle 8i Database Server 

prop_recv_log_queue 

(Optional) Specifies the propagation receive log queue 

prop_send_log_queue 

(Optional) Specifies the propagation send log queue 

aq_username 

Stores the user name required to use Oracle AQ on the Oracle 8i Database Server 


Note:

After installation, the AQ password can be changed using the Database Server Enterprise Manager, or using the Database Server ALTER USER command. 


Setting AQ Lite Server Options

This entry specifies the AQ Lite database that is associated with a given AQ Lite Driver, and the password that is needed to access the database.

An aqlite_server contains the attributes listed in Table 4-4. To configure the AQ Lite Server, create the aqlite_server entry and then set the appropriate attributes.

Table 4-4  AQ Lite Server Attributes
Attribute  Description 

aqlite_database_name 

The AQ Lite database name. When the aqlite_database_name is null the default database is used. 

aqlite_database_password 

Stores the password required to use AQ Lite in the Oracle 8i Lite Database. The value stored is encrypted in the directory. 

prop_recv_log_queue 

(Optional) The propagation receive log queue 

prop_send_log_queue 

(Optional) The propagation send log queue 

Setting MQSeries Server Options

The mq_server entry contains the attributes listed in Table 4-5. To configure the MQSeries Server, create the mq_server entry and then set the appropriate attributes.

Table 4-5  MQSeries Server Attributes
Attribute  Description 

connection_type 

Defines the connection type. Standard is the only connection type supported. A standard connection is established with the MQSeries Queue manager. 

prop_recv_log_queue 

(Optional) The propagation receive log queue 

prop_send_log_queue 

(Optional) The propagation send log queue 

queue_mgr 

MQSeries queue manager 

Setting Multicast Server Options

The mcast_server entry contains the attributes listed in Table 4-6. To configure the Multicast Server, create the mcast_server entry and then set the appropriate attributes.

Table 4-6  Multicast Server Attributes
Attribute  Description 

ip 

IP multicast address used by the Oracle Multicast protocol. The value must be between 225.0.0.0 and 239.255.255.255. 

port 

IP multicast port number used by the Oracle Multicast protocol. This is an integer with a lower limit of 1024 (inclusive) and an upper limit of 65535 (0xFFFF) (inclusive). 

Setting TIBCO Server Options

The rv_server entry contains the attributes listed in Table 4-7. To configure the TIBCO Server, create the rv_server entry and then set the appropriate attributes.

Table 4-7  TIBCO Server Attributes
Attribute  Description 

service 

The name of the Rendezvous service (see the Rendezvous Administration Guide, for more information). 

Configuring the Message Broker Entry and Drivers

The message broker entry contains attributes that set general parameters for an Oracle Message Broker instance. Also, when you add drivers or HTTP propagation entries, they are added beneath the message broker entry. A HTTP propagation entry (prop_http) contains configuration information for the HTTP propagation.

Only one message broker entry is allowed per OMB Instance. The message broker entry, named msg_broker, contains the attributes shown in Table 4-8.

This section covers the following Oracle Message Broker directory entries:

Oracle Message Broker Memory Management

The Oracle Message Broker uses the JVM heap to maintain its state, to store Volatile Driver messages, control consumers, and to manage producers, sessions, and connections. Any operation that uses resources can cause an exception when there is not enough heap memory available.

The max_memory attribute determines the amount of heap memory to use in the JVM where the Oracle Message Broker runs. However, setting this value is just one factor in JVM memory management. Keep the following points in mind when running the Oracle Message Broker:

The Oracle Message Broker forces garbage collection prior to throwing memory exceptions. It is also possible for the JVM to throw an exception or fail if attempts to use more memory than is currently available in the JVM.

For example, an application that creates 10,000 Sessions may cause the Oracle Message Broker to throw an exception after creating 5,689 sessions, if no additional heap memory is available and garbage collection does not free sufficient memory.

Adding an Oracle AQ Driver

An aq_driver entry contains configuration information for the AQ Driver, including the DN for the AQ Server. Table 4-9 describes the Oracle AQ Driver attributes. To add an AQ Driver, set up the AQ Server entry and then the AQ Driver attributes.

Table 4-9  AQ Driver Administrative Attributes
Attribute  Description 

max_private_sessions 

This is the maximum number of concurrent JMS sessions that the driver allows to be created. The Database Server should be configured to support more than max_private_sessions connections.

The value must be an integer. The lower limit is 1. 

max_shared_sessions 

The number of JDBC connections that are created in a pool and used internally for administrative purposes. Administrative uses include creating and destroying AQ queues and subscriptions. The AQ Driver in the OCI mode creates one connection per JMS session to provide operational access to AQ queues. The AQ Driver in the JDBC mode creates one JDBC connection per JMS session to provide operational access to AQ queues.

The value must be an integer. The lower limit is 1. 

propagation_recv_sessions 

The number of receive sessions started for propagation. The sum of propagation_recv_sessions + propagation_send_sessions must be less than max_private_sessions.

Default value: 2 

propagation_send_sessions 

The number of send sessions started for propagation. The sum of propagation_recv_sessions + propagation_send_sessions must be less than max_private_sessions.

Default value: 2 

push_sessions 

The number of threads which will push messages to message listeners.

The value must be an integer. The lower limit is 1. 

query_interval 

The number of milliseconds at which AQ is queried, polled, to determine if messages are available for message listeners.

The value must be an integer. The lower limit is 1. 

server_dns 

The DN pointing to the server that supports the AQ Driver.

The type of the DN that this references must be aq_server. 

thin_jdbc 

If true, use the thin JDBC based AQ driver. If false, use the OCI based JDBC AQ Driver.

Default value: false 

thin_jdbc_conn_string 

The URL suffix to use for the JDBC thin connection to AQ. 

use_jdbc 

If true, use JDBC based AQ Driver. If false, use the OCI based AQ Driver. See "JDBC Mode" and "OCI Mode" for details on AQ Driver Modes.

Default value: false 

Adding an Oracle AQ Lite Driver

A aqlite_driver entry contains configuration information for the Oracle AQ Lite Driver. Table 4-10 describes the driver entry attributes.

Table 4-10 AQ Lite Driver Administrative Attributes
Attribute  Description 

max_private_sessions 

The AQLite Driver ignores this value.

The value must be an integer. The lower limit is 1. 

max_shared_sessions 

The AQLite Driver ignores this value.

The value must be an integer. The lower limit is 1. 

query_interval 

The interval, in milliseconds, at which the AQ Lite Driver is polled to determine if messages are available for message listeners.

The value must be an integer. The lower limit for this is 1. 

push_sessions 

The number of threads which will push messages to message listeners.

The value must be an integer. The lower limit is 1. 

server_dns 

The dn pointing to the server that supports the AQ Lite Driver.

The type of the dn that this references must be aqlite_server. 

Adding A Volatile Driver

A volatile_driver entry contains configuration information for the Oracle Volatile Driver. Table 4-11 describes the driver entry attributes.

When using a Volatile Driver, set the msg_broker entry attribute max_memory to an appropriate value to support both the Oracle Message Broker, and the Volatile Driver. This attribute determines the total memory available to the JVM running the Oracle Message Broker. Messages stored using the Volatile Driver consume memory in the active Oracle Message Broker. The amount of memory consumed per message depends on the message type, and the size of the message. When a message is consumed, the memory associated with the message is freed. The Volatile Driver stops accepting messages when the JVM running the Oracle Message Broker does not have enough free memory.

Since the Oracle Message Broker stores messages for the Volatile Driver internally, the Oracle Volatile Driver does not use an external message server for storing messages and the volatile_driver entry does not contain a server_dns attribute (all other driver entries use the server_dns attribute to point to the message server).

Table 4-11  Volatile Driver Administrative Attributes
Attribute  Description 

max_private_sessions 

The Volatile Driver ignores this value.

The value must be an integer. The lower limit is 1. 

max_shared_sessions 

The Volatile Driver ignores this value.

The value must be an integer. The lower limit is 1. 

propagation_recv_sessions 

The number of receive sessions started for propagation.

Default value: 2 

propagation_send_sessions 

The number of send sessions started for propagation.

Default value: 2 

push_sessions 

The number of threads which will push messages to message listeners.

The value must be an integer. The lower limit for this is 1. 

query_interval 

The number of milliseconds at which the Volatile Driver is polled to determine if messages are available for message listeners.

The value must be an integer. The lower limit for this is 1. 

Adding An MQSeries Driver

An mq_driver entry contains configuration information for the MQSeries Driver. Table 4-12 describes the MQSeries Driver attributes.

Table 4-12  MQSeries Driver Administrative Attributes
Attribute  Description 

max_private_sessions 

The maximum number of connections to the queue manager for the driver. Each JMS session consumes one connection. If the Oracle Message Broker is running, and this attribute is updated, a new value that is less than the old value causes the following behavior. If the current number of sessions in use exceeds the new maximum value, all existing sessions are allowed to continue but no new sessions can be created until the number in use drops below the new maximum value.

The value must be an integer. The lower limit is 1. 

max_shared_sessions 

The maximum number of shared sessions for the driver.

The value must be an integer. The lower limit is 1. 

query_interval 

The number of milliseconds at which the MQSeries Driver is polled to determine if messages are available for message listeners.

The value must be an integer. The lower limit is 1. 

propagation_recv_sessions 

The number of receive sessions started for propagation. The sum of propagation_recv_sessions + propagation_send_sessions must be less than max_private_sessions.

Default value: 2 

propagation_send_sessions 

The number of send sessions started for propagation. The sum of propagation_recv_sessions + propagation_send_sessions must be less than max_private_sessions.

Default value: 2 

push_sessions 

The number of threads which will push messages to message listeners.

The value must be an integer. The lower limit is 1. 

server_dns 

The DN pointing to the server that supports the MQSeries Driver.

The value must be a DN that points to an entry of the type mq_server.  

Adding A Multicast Driver

The mcast_driver entry contains configuration information for the Oracle Multicast Driver. Table 4-13 describes the Multicast Driver attributes.

Table 4-13  Multicast Driver Administrative Attributes
Attribute  Description 

max_private_sessions 

The Multicast Driver ignores this value.

The value must be an integer. The lower limit is 1. 

max_shared_sessions 

The Multicast Driver ignores this value.

The value must be an integer. The lower limit is 1. 

network 

The Multicast network interface 

propagation_recv_sessions 

The number of receive sessions started for propagation.

Default value: 2 

propagation_send_sessions 

The number of send sessions started for propagation.

Default value: 2 

push_sessions 

The number of threads which will push messages to message listeners.

The value must be an integer. The lower limit is 1. 

query_interval 

The number of milliseconds at which the Multicast Driver is polled to determine if messages are available for message listeners.

The value must be an integer. The lower limit is 1. 

server_dns 

The DN pointing to the server that supports the Multicast Driver.

The value must be a valid DN that points to an entry of type mcast_server. 

Adding A TIBCO Driver

The rv_driver entry contains configuration information for the TIBCO Driver. Table 4-14 describes the driver entry attributes.

Table 4-14  TIBCO Driver Administrative Attributes
Attribute  Description 

daemon 

Rendezvous daemon used by the Oracle Message Broker (see the Rendezvous Administration Guide, for more information). 

max_private_sessions 

The maximum number of JMS sessions for the driver.

The value must be an integer. The lower limit is 1. 

max_shared_sessions 

The TIBCO Driver ignores this value.

The value must be an integer. The lower limit is 1. 

network 

Network interface used by Rendezvous (see the Rendezvous Administration Guide, for more information). 

propagation_recv_sessions 

The number of receive sessions started for propagation. The sum of propagation_recv_sessions + propagation_send_sessions must be less than max_private_sessions.

Default value: 2 

propagation_send_sessions 

The number of send sessions started for propagation. The sum of propagation_recv_sessions + propagation_send_sessions must be less than max_private_sessions.

Default value: 2 

push_sessions 

The number of threads which will push messages to message listeners.

The value must be an integer. The lower limit is 1. 

query_interval 

The number of milliseconds at which the TIBCO Driver is polled to determine if messages are available for message listeners.

The value must be an integer. The lower limit is 1. 

server_dns 

The DN pointing to the server that supports the TIBCO Driver.

The value must be a valid DN of type rv_server. 

Configuring Message Broker HTTP Propagation Options

A prop_http entry contains configuration information for the HTTP propagation. Table 4-15 describes the HTTP propagation entry attributes.

Table 4-15  Propagation with HTTP Administrative Attributes
Attribute  Description 

http_host 

Specifies the name of the system that the listener runs on. This needs to be set if the system is a multi-homed system (a system with multiple domain names).

The value is a String. Default value: null 

http_port 

Specifies the port that the HTTP listener to listen on.

The value must be an integer. Default value: none 

http_ssl_level 

Specifies the SSL level used to secure the HTTP connections.

The value must be an integer. Valid values are: 0, 1, 2, or 3. Default value: 0 

wallet_location 

Specifies the wallet location. This is the full path name of the wallet file. Note: this requires exported wallets.

The value is a String. Default value: null 

wallet_password 

Specifies the wallet password to be applied to the specified wallet file. The value stored is encrypted in the directory.

The value is a String. Default value: null 

Creating and Configuring Connection Factories

The ConnectionFactories entry should contain at least one connection factory for each driver. A connection factory entry specifies the driver type, the provider (this is the DN of the associated message broker entry, and other information that allows a client to connect to the OMB Instance. Table 4-16 describes connection factory attributes.

Table 4-16  Connection Factory Administrative Attributes
Attribute  Description 

client_id 

Used to set the client ID for JMS connection. 

driver_type 

Type of driver associated with the connection factory.

Valid types are: aq, aqlite, vol, mq, mcast, rv

priority 

The value must be an integer. The lower limit is 0 and the upper limit is 9. 

provider_dns 

This is reserved for future use. Do not set this attribute. If you do set this attribute, results are unpredictable. 

transaction_timeout 

Transaction timeout in milliseconds.

The value must be an integer. The lower limit is 1. 

Adding Queues

The Queues entry contains all of the OMB Instance queue attributes. Queue attributes define a queue's name and the queue's configuration information. Table 4-17 describes the queue attributes.

Table 4-17  Queue Administrative Attributes
Attribute  Description 

aqlite_message_grouping 

This attribute applies only if the queue is an AQ Lite queue.

This specifies the message grouping for the AQ Lite queue.

The valid values are: NONE, or TRANSACTIONAL. Default value: NONE 

aqlite_owner 

This attribute applies only if the queue is an AQ Lite queue.

This specifies the owner of the AQLite queue. If left blank, the default is used.  

aqlite_storage_clause 

This attribute applies only if the queue is an AQ Lite queue.

This specifies the storage clause used to create the AQ Lite queue table. 

aq_adt 

This attribute applies only if the queue is an AQ Queue. This determines the JMS ADT to use for storing messages to AQ queues. See "AQ Messages" for more information.

The valid values are: text, bytes, map, stream, object, all, queriable, raw

Default value: raw 

aq_schema 

This attribute applies only if the queue is an AQ Queue.

This specifies the schema in which the AQ queue resides.  

aq_rules 

This attribute applies only if the queue is an AQ Queue.

If true, use AQ message selection, if false, use Oracle Message Broker message selection.

The value is a boolean. Default value: false 

acl_dn 

A DN pointing to an Acl entry. Refer to Chapter 12, "Security" for more details.  

create_provider_q 

This attribute is only used for Oracle AQ queues or Oracle AQ Lite queues.

Possible values are yes, no, or conditional. This attribute affects how Oracle AQ queues or Oracle AQ Lite queues are created when the administrator creates an LDAP Directory entry corresponding to the AQ queue or the AQ Lite queue using the administrative utility.

  • yes: the administrative utility creates underlying queue.

  • no: the administrative utility does not access the provider.

  • conditional: if the underlying queue already exists in AQ or AQLite, it is used, otherwise the queue is created.

Default value: conditional. 

is_managed 

This is only used for MQSeries queues.

Determines if the queue is managed.  

is_native 

Determines if the queue stores JMS messages or native messages.

The value is a boolean. 

is_queriable 

This is only used for Oracle AQ queues. Determines if the queue is queriable.

Note: use of this attribute has been deprecated. Please do not use this attribute. Equivalent functionality is provided with the aq_adt attribute.

Default value: false 

max_messages 

Sets the maximum number of messages in the queue. Note: the AQ Driver and the MQSeries Driver do not support this attribute.

The value must be an integer. The lower limit for this attribute is 1.  

provider_queue_name 

This is only used for Oracle AQ and MQSeries queues.

Determines the provider's name for the queue, if different from the cn. If not defined, the default provider_queue_name is the same as the topic or queue name (the cn). See "Notes and Limitations for Configuring Queues" for additional information on this attribute. 

provider_q_created 

This attribute is only used for Oracle AQ or Oracle AQ Lite queues. This is a read only attribute. If the administrative utility creates the Oracle AQ queue or the Oracle AQ Lite queue, this is set to true otherwise this is set to false.

The value is a boolean. 

rm_provider_q 

This attribute is only used for Oracle AQ queues or Oracle AQ Lite queues.

Possible values are yes, no, or conditional. This attribute affects how the underlying AQ or AQ Lite queues are removed when the administrator removes an LDAP Directory entry corresponding to the queue using the administrative utility.

  • yes: the queue is removed from when the entry is removed from the LDAP Directory.

  • no: the administrative utility does not access the provider and the underlying AQ or AQ Lite queue is not removed.

  • conditional: the queue is only removed if the Oracle Message Broker administrative utilities created the queue.

Default value: conditional. 

server_dn 

DN of the server that handles this queue.

The value must be a valid DN. The DN supplied must point to an entry of one of the following types: msg_broker, aq_server, aqlite_server, mq_server, mcast_server, or rv_server. 

Notes and Limitations for Configuring Queues

Normally, when setting up Queues, destinations should use unique underlying queues on the message store. Thus, the administrator should make sure that the value supplied for the provider_queue_name is unique across all OMB Instances configured to use the Oracle Message Broker or that queue names are unique.

However, the following configuration example provides a case where the previous comment is not applicable. An application could require that an AQ single-consumer queue be accessed as a JMS queue, and the deployment options could demand that several Oracle Message Broker applications accessing the same underlying queue use different Database Server credentials (including the username and password). In the Oracle Message Broker, the Database Server credentials are associated with an OMB Instance's AQ Server Entry, when using the OCI based AQ Driver (see Table 4-3). In this case, the administrator needs to create several separate OMB Instances to access the underlying AQ queue using the Oracle Message Broker, and the administrator needs to configure the multiple OMB Instances using a different username and password in the AQ Server entry. With this configuration, the different OMB Instances have at least one queue entry in the directory that points to the same underlying provider queue (AQ single-consumer queue).

Adding Topics

The Topics entry contains all of the OMB Instance topic entries. Each topic entry specifies attributes defining a topic name and the topic configuration information. Table 4-18 describes the topic attributes.

Table 4-18  Topic Administrative Attributes
Attribute  Description 

aqlite_message_grouping 

This attribute applies only if the topic uses an AQ Lite server.

Specifies the message grouping for the AQ Lite queue.

The valid values are: NONE, or TRANSACTIONAL. Default value: NONE 

aqlite_owner 

This attribute applies only if the topic uses an AQ Lite server.

Specifies the owner of the AQLite queue. If left blank, the default is used.  

aqlite_storage_clause 

This attribute applies only if the topic uses an AQ Lite server.

Specifies the storage clause used to create the AQ Lite queue table.  

aq_adt 

This attribute applies only if the topic uses an AQ server. This determines the JMS ADT to use for storing messages to AQ queues. See "AQ Messages" for more information.

The valid values are: text, bytes, map, stream, object, all, queriable, raw

Default value: raw 

aq_schema 

This attribute applies only if the topic uses an AQ server.

Specifies the schema in which the AQ queue resides.  

aq_rules 

This attribute applies only if the topic uses an AQ server.

If true, use AQ message selection, if false, use Oracle Message Broker message selection.

The value is a boolean. Default value: false 

acl_dn 

A DN pointing to an Acl entry. Refer to Chapter 12, "Security" for more details.  

create_provider_q 

This is only used for Oracle AQ or AQ Lite topics.

Possible values are yes, no, or conditional. This attribute affects how Oracle AQ or AQ Lite queues are created when the administrator creates an LDAP Directory entry corresponding to the AQ or AQ Lite topic using the administrative utility.

  • yes: the administrative utility creates the underlying queue.

  • no: the administrative utility does not access the underlying queue.

  • conditional: if the queue already exists, it is used, otherwise, it is created.

Default value: conditional. 

is_managed 

This is reserved for future use.  

is_native 

Determines if the topic stores JMS messages or native messages 

is_queriable 

This is only used for Oracle AQ topics.

Determines if the topic is queriable.

The value is a boolean. Default value: false

Note: use of this attribute has been deprecated. Please do not use this attribute. Equivalent functionality is provided with the aq_adt attribute. 

max_messages 

Sets the maximum number of messages in the topic. Note: the AQ Driver and the MQSeries Driver do not support this attribute.

The value supplied must be an integer. The lower limit for this attribute is 1. 

provider_queue_name 

Determines the provider's name for the queue that stores messages for the topic. For Oracle AQ topics, if this attribute is not defined, the default provider_queue_name is the same as the supplied cn for the topic.

See "Notes and Limitations for Configuring Topics" for additional information on this attribute. 

provider_q_created 

This attribute is only used for Oracle AQ or AQ Lite topics. This is a read only attribute. If the administrative utility creates the Oracle AQ or AQ Lite topic this is set to true otherwise this is set to false.

The value is a boolean. 

rm_provider_q 

This attribute is only used for Oracle AQ or AQ Lite topics.

Possible values are yes, no, or conditional. This attribute affects how Oracle AQ or AQ Lite queues are removed when the administrator removes an LDAP Directory entry corresponding to the topic using the administrative utility.

  • yes: the queue is removed from Oracle AQ or AQ Lite when the topic is removed from the LDAP Directory.

  • no: the administrative utility does not access Oracle AQ or AQ Lite.

  • conditional: the queue is only removed if it was created by the Oracle Message Broker administrative utilities.

Default value: conditional. 

server_dn 

DN of the server that handles this topic. 

Notes and Limitations for Configuring Topics

Normally, when setting up topics, destinations should use unique underlying queues (or topics) on the message store. Thus, the administrator should make sure that the value supplied for the provider_queue_name is unique across all OMB Instances configured to use the Oracle Message Broker, or that topic names are unique.

However, the following configuration example provides a case where the previous comment is not applicable. An application could require that an AQ multi-consumer queue be accessed as a JMS topic. This topic could be required by the application to use an AQ rules engine to specify a message selector. The application could also require access to the topic that does not use the AQ rules engine to specify a message selector. The configuration property that determines whether the AQ rules engine is used for durable subscriber message selectors is associated with the topic entry in the directory. In this case, the administrator would set up two directory entries within the OMB Instance that point to the same underlying AQ multi-consumer queue. One entry would have the aq_rules attribute set to true, and the other would have the aq_rules attribute set to false.

Creating and Configuring Remote Directories

The RemoteDirectories entry contains remote directory entries. Table 4-19 describes the remote directory entry attributes. Refer to Chapter 8 for more information on remote directories and their use with propagation.

re
Table 4-19  Remote Directories Administrative Attributes
Attribute  Description 

remote_directory_host 

Specifies the name of the host where the LDAP server runs. 

remote_directory_password 

Specifies the password used for authentication on the LDAP Directory. The value stored is encrypted in the directory. 

remote_directory_port 

Specifies the port used to connect to the LDAP Directory.

The value must be an integer. Default value: 389. 

remote_directory_username 

Specifies the DN of the user entry that is used for authentication on the LDAP Directory. 

Creating and Configuring Remote HTTP Listeners

The RemoteHTTPListener entry contains remote HTTP entries. Table 4-20 describes the remote HTTP entry attributes. Refer to Chapter 8 for more information on remote HTTP listeners and their use with propagation.

re
Table 4-20  RemoteHTTPListener Administrative Attributes
Attribute  Description 

proxy_host 

Specifies the hostname for the proxy server (on the sending side).

The value is a String. Default value: null 

proxy_port 

Specifies the port for the proxy server (on the sending side).

The value must be an integer. Default value: null 

remote_http_host 

Specifies the hostname of the system that the remote HTTP listener runs on.

The value is a String. Default value: none 

remote_http_port 

Specifies port number that the HTTP listener on the remote system listens on.

The value must be an integer. Default value: no default 

remote_http_path 

Specifies the path of the propagation servlet when using servlet based HTTP propagation. This is the path component of the URL of the HTTP propagation servlet. For example, the attribute remote_http_path should be set to /servlet/PropHttpServlet, if the servlet's URL is:

    http://company.com/servlet/PropHttpServlet

The value is a String. Default value: null 

remote_http_ssl_level 

Specifies the SSL level of the remote HTTP listener. The valid values are: 0, 1, 2, or 3.

The value must be an integer. Default value: 0 

remote_wallet_location 

The full pathname of the wallet file on the sending site. The wallet file must be in "exported file" format.

The value is a String. Default value: null 

remote_wallet_password 

The password applied to the specified wallet file. The value stored is encrypted in the directory.

The value is a String. Default value: null 

Creating and Configuring Propagation Jobs

The PropagationJobs entry contains propagation job configuration information, including the specification of the destinations, source and target, for the propagation job. Table 4-21 describes the propagation job attributes. Refer to Chapter 8 for more information on propagation, and for information on setting attributes in a PropagationJobs entry.

Table 4-21  Propagation Jobs Administrative Attributes
Attribute  Description 

activation_state 

Specifies the activation state of the propagation job. This attribute specifies whether the propagation job is activated or deactivated. See Activation State in "Propagation Job Configuration" for details.

When the value is true, the propagation job is activated.

When the value is false, the propagation job is deactivated.

The value is a boolean. Default value: false 

create_timestamp 

This is reserved for internal use only. 

propagation_msg_selector 

Contains the propagation message selector string. See Propagation Message Selector "Propagation Job Configuration" for details. 

propagation_password 

Contains the password to use for the specified username. The value stored is encrypted in the directory. 

propagation_source 

DN of the source queue or topic. 

propagation_target 

DN of the target queue or topic. 

propagation_timeout 

The timeout value in seconds.

Default value: 120 

remote_dn 

DN of the remote entry. This is used when the propagation_target is specified in a remote directory or using a remote_http_entry. 

propagation_username 

Contains the username DN to use to access the remote Oracle Message Broker when the security service authentication is enabled. 

valid_status 

This is reserved for internal use. 

Creating and Configuring Durable Subscribers

The DurableSubscribers entry contains durable subscribers. Table 4-22 describes durable subscriber attributes.

When you create or delete a durable subscriber entry for an AQ topic, the create or delete results in the creation or deletion of a subscriber in AQ. This allows durable subscribers to be created and messages accumulated for the AQ topic before the durable subscriber is available.

Table 4-22  Durable Subscriber Administrative Attributes
Attribute  Description 

aqlite_address 

This attribute applies only if the topic uses an AQ Lite server. Address of the AQ Lite subscriber. 

aqlite_protocol 

This attribute applies only if the topic uses an AQ Lite server. Protocol used by the AQ Lite subscriber. 

aqlite_rule 

This attribute applies only if the topic uses an AQ Lite server. Rule use to filter messages to the AQ Lite subscriber. 

client_id 

This attribute contains the client identifier of the client that registered the durable subscription (see [JMS 4.3.2] for more information on client identifiers.) 

jms_user 

JMS user 

msg_selector 

Message selector for the user 

topic_dn 

The DN for the topic. The value must be a valid DN. 

Creating and Configuring Asynchronous Component Invocation Triggers

The ACI container contains entries for ACI topic triggers and ACI queue triggers. An ACI trigger entry defines the condition under which a notification is sent to an EJB. Each trigger acts on one and only one destination (queue or topic). It is not possible to set triggers that involve multiple destinations. There are two types of triggers, Queue Triggers and Topic Triggers. Table 4-23 and Table 4-24 describe the attributes for these two types of triggers.

Table 4-23  ACI Queue Trigger Administrative Attributes
Attribute  Description 

authentication 

Specifies the database connection authentication method. 

cf 

The JNDI name of the connection factory.

The value is a String. 

component 

The JNDI name of the EJB component to invoke.

The value is a String. 

concurrency 

The number of ACIs that can execute concurrently for the same event.

The value must be an integer. Default value: 0 

dest 

The JNDI name of the destination. 

enabled 

Activates or deactivates the ACI trigger.

The value is a boolean. Default value: false 

password 

The database schema password. 

retries 

The number of retries to perform when the ACI does not complete normally.

The value must be an integer. Default value: 0 

selector 

The message selector associated with the trigger.

The value is a String. 

threshold 

The trigger is generated when messages reach a multiple of the threshold.

The value must be an integer. Default value: 1 

username 

The database schema name. 

Table 4-24  ACI Topic Trigger Administrative Attributes
Attribute  Description 

authentication 

Specifies the database connection authentication method. 

cf 

The JNDI name of the connection factory.

The value is a String. 

component 

The JNDI name of the EJB component to invoke.

The value is a String. 

enabled 

Activates or deactivates the ACI trigger.

The value is a boolean. Default value: false 

password 

The database schema password 

retries 

The number of retries to perform when the ACI does not complete normally.

The value must be an integer. Default value: 0 

subscription 

The subscription name for topics.

The value is a String. 

threshold 

The trigger is generated when messages reach a multiple of the threshold.

The value must be an integer. Default value: 1 

username 

The database schema name. 

Showing Directory Attributes and Entries

You can use either AdminUtil, or 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 Manager is:

% ombadmin

When you navigate to your OMB Instance, you should verify the entries you created in the previous steps.

To use AdminUtil to view directory entries, refer to the show command in the section, "Command-line Administration Utility - AdminUtil".

Dynamic Configuration

When the Oracle Message Broker is running, the set of valid administration operations is restricted. This section describes the operations allowed, and the restrictions on dynamic configuration.

This section covers the following:

Create Entry Restrictions

The following list contains the entries that cannot be created when the Oracle Message Broker is active. All other types of entries can be created when the Oracle Message Broker is active.

aqlite_driver 

mcast_server 

aqlite_server 

mq_driver 

aq_driver 

mq_server 

aq_server 

rv_driver 

prop_http 

rv_server 

mcast_driver 

volatile_driver 

Update Entry Restrictions

The following list shows the entries that cannot be updated in any way when the Oracle Message Broker is active.

aq_server 

mq_server 

mcast_server 

rv_server 


Table 4-25 lists the attributes for the specified entries that can be updated when the Oracle Message Broker is running. Other attributes for these entries are not allowed to be updated while the Oracle Message Broker is active.

Table 4-25  Allowed Update Operations for an Active Oracle Message Broker
Entry  Attributes that can be updated 

aq_driver 

query_interval, max_push_sessions 

mcast_driver 

query_interval, max_push_sessions  

mq_driver 

query_interval, max_push_sessions,
max_private_sessions
 

msg_broker 

max_memory, max_concurrent_reqs 

propagation_job 

activation_state, remote_dn, propagation_timeout, propagation_username, propagation_password 

prop_http 

http_sll_level, wallet_location, wallet_password 

queues 

max_messages

Note: With the Oracle Message Broker active, max_messages can only be updated for a queue using the Volatile Driver. 

queue_trigger 

concurrency, enabled, retries, threshold 

remote_dir 

all attributes 

remote_http 

all attributes 

rv_driver 

query_interval, max_push_sessions,
max_private_sessions
 

topics 

max_messages

Note: With the Oracle Message Broker active, max_messages can only be updated for a topic using the Volatile Driver. 

topic_trigger 

enabled, retries, threshold 

volatile_driver 

query_interval, max_push_sessions 

Delete Entry Restrictions

Table 4-26 contains the entries that cannot be deleted when the Oracle Message Broker is active. All other types of entries can be deleted when the Oracle Message Broker is active.

Table 4-26  Delete Entry Restrictions
Entry  Comment 

aqlite_driver 

 

aqlite_server 

 

aq_driver 

 

aq_server 

 

durable_subscriber 

Allowed only if the durable subscriber is not in use 

mcast_driver 

 

mcast_server 

 

mq_driver 

 

mq_server 

 

msg_broker 

 

prop_http 

 

queue 

Allowed only if the queue is not in use 

remote_dir 

 

remote_http 

 

rv_driver 

 

rv_server 

 

topic 

Allowed only if the topic is not in use 

volatile_driver 

 

Deleting a Propagation Job Entry

Deleting an activated propagation job is disallowed when the Oracle Message Broker is running (an activated propagation job is one with the activation_state attribute set to true).

To delete a propagation job entry when the Oracle Message Broker is running, first deactivate the propagation job. Refer to "Activating and Deactivating a Propagation Jobs" for more information.

Command-line Administration Utility - AdminUtil

The AdminUtil command-line utility modifies entries in the LDAP Directory and allows the administrator to create, delete, and manage Oracle Message Broker configuration information.

The AdminUtil command operates in two modes: interactive and batch:

By default, AdminUtil starts in interactive mode and assumes that simple authentication is required. You are prompted for a user DN and a password if these are not specified on the command line (using the -noauth option you are not prompted for a user DN or a password).


Note:

The LDAP Directory specified using the OMB_IC environment variable must be running before using AdminUtil (see "Required Environment Variables" for details). 


Enter a user DN and password and select the Continue button if your directory is set up for authentication. 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, AdminUtil exits (for more information on setting properties for security, refer to the section, "Enabling SSL and Authentication for the LDAP Directory").

This section uses the following abbreviations:

cwo 

the current working object 

DN 

an LDAP distinguished name 

RDN 

an LDAP relative distinguished name 

To run AdminUtil, use the following syntax:

AdminUtil [options] [--] [arguments]

Table 4-27 shows AdminUtil options. The command line options are case sensitive.

The optional arguments can be specified on the command line. If optional arguments are present, named variables are set for each of the arguments. The variables have hardwired names of ARGVn where n is the argument number 0..n-1 (for example, ARGV0, ARGV1, ...). The variable can be used as any other named variables and managed using the set command.

The following examples illustrate the variables that would be set for the given command line.

AdminUtil myOmb myQueue
ARGV0:  myOmb
ARGV1:  myQueue

AdminUtil -f myFile myOmb myQueue
ARGV0:   myOmb
ARGV1:   myQueue

AdminUtil -f myFile --  -dashArg abc xyz
ARGV0:   -dashArg
ARGV1:   abc
ARGV2:   xyz


Note:

AdminUtil does not remove JNDI related Java authentication properties. It does set JNDI properties based on command line options. You can modify the OMB_LP variable to set security properties, then run AdminUtil with the -noauth option to access a secured LDAP server. 


Table 4-27  Command-line Options for AdminUtil
Option  Description 

-- 

Marks the end of the command line options. Use -- when the first optional argument starts with a dash. 

-b LDAP_basedn 

The LDAP_basedn supplies a base DN to use for the initial context. If you use the -b option, -h is required. 

-D auth_DN 

The auth_DN supplies the DN to use for user name authentication. 

-echo 

Echoes each input line.

By default, the echo feature is disabled. 

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

-f inputFile 

Process a batch file. The file, inputFile, contains AdminUtil commands. Multiple -f options specify a sequence of files to be processed. Multiple files are processed in the order they appear on the command line. 

-fullversion 

Displays the full program version information. 

-h LDAP_host 

Specifies an LDAP server. The host, LDAP_host, must be a host available on the network. 

-help 

Displays the program usage. 

-ign 

Causes the program to ignore errors when processing a batch file. If this option is not specified, processing ends if a batch command fails. This option is ignored for interactive mode. 

-infolevel level 

Set the information reporting level. The parameter level is set to an integer value in the range 1-3:

    1 - print the minimum amount of informational messages

    2 - print the standard amount of informational messages

    3 - print the verbose informational messages.

When a command fails, using infolevel 3 causes the command tokens to be shown after the error. The default value for infolevel is 2. 

-int 

Causes the program to continue in interactive mode after processing any batch files that may have been listed. Interactive mode is the default if the -f option is not specified. 

-n 

Causes most commands to operate in a "no execute" mode. When a command string is processed, a certain degree of validation may be performed but the command is not executed. AdminUtil may display a text message indicating command status. This option is useful for checking batch files for command syntax problems.

Using AdminUtil, most commands honor the "no execute" flag while some general commands, including: echo, exit, help, run, set, and setopt behave normally; that is, they ignore the -n flag. 

-noauth 

Specifies that LDAP authentication is not required on the LDAP server. 

-p LDAP_port 

TCP port to use for the LDAP connection on the LDAP server. If you use the -p option, -h is required. 

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

 

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

Command Line Syntax

Each AdminUtil command is terminated with a semi-colon ';'. If a literal semi-colon is required in an input line, it must be escaped or quoted.

A single command can be split over multiple input lines. However, individual tokens must be fully specified on a given input line, including quoted strings. Quoted strings are not allowed to start on one input line and continue to the next. The beginning and ending quote characters must be on the same input line and an error will occur for unmatched quote characters.

AdminUtil processes commands until a quit or exit command is encountered, or the end of file is read in batch mode.

AdminUtil is not case sensitive for command names.

Quotation

AdminUtil provides three types of quotation:

A non-quoted backslash (\) is used as the escape character. It preserves the literal value of the following character.

Single quotes preserve the literal value of each character within the quotes. No escaping is allowed for single quotes so a single quote literal can not occur between single quotes.

Double quotes provide a weaker form of quotation than single quotes. All enclosed characters are preserved with the exception of $ and \. The $ character retains its special meaning within double quotes. The backslash (\) is used as an escape character only when followed by a $, \, or " (dollar, backslash and double quote). For any other character, the \ is treated as a literal character.

A double quote can be part of a quoted string by escaping the double quote with a backslash (\"). For example,

 "embedded\"quote" 
 "embedded\\backslash"

Comments and Echo Mode

An input line may contain comments. The '#' character marks the beginning of a comment. A comment starts when a word begins with '#' and extends to the end of the line. A '#' in the middle of a word or within a quoted string does not start a comment.

If a line begins with "#!" the remainder of the line is printed to the screen when echo mode is disabled. When echo mode is enabled, the entire line is echoed just like any other input line. This feature is useful for displaying user comments when processing a batch file.

LDAP Directory Interaction

Many AdminUtil commands result in an LDAP Directory operation. Other AdminUtil commands provide information for commands and set internal options to make the program easier to use. For example, attrl allows you to build a list of attributes for the create or setattr commands. Also, the builddn command allows you to construct a DN for an entry.

Object Binding

Commands are applied to a specific object reference or to the current bound object. The cd command sets the current bound object (or the -bind option of the lookup and create commands). See "Object References", for more information on object references.

Named Variables

The named variable feature allows user-defined variable names to be associated with a string.

The set command associates a string with a named variable. The -set option also associates a string with a named variable for commands such as cd, pwd, lookup, create and builddn.

A named variable is a word consisting of only alphanumeric characters and the underscore, and must begin with an alphabetic character or underscore ([a-zA-Z_][a-zA-Z0-9_]*).

There are two forms used to reference a variable: $name and ${name}. Use the second form when the characters following the name are themselves valid identifier characters.

Variable expansion is done for any variable reference within a non-quoted string and double quotes. The $ is treated as a literal character if it occurs within single quotes. A literal $ can be obtained by escaping it with a backslash (`\$'). A $ followed by a whitespace is taken as literal whether or not it is escaped.

A undefined variable expands to the empty string.

Concatenation of Named Variables

A named variable, referenced as $name or ${name}, can occur at any position in a command string. The parameter is expanded if it occurs in a non-quoted token or is within double quotes.

Evaluation Rules

Input is evaluated, expanded and parsed into a command and list of arguments in a consistent manner. The following outlines the basic steps of the evaluation process:

  1. Get an input line.

  2. Remove comments.

  3. Look for a command terminator (;) at the end of the line. If not found, repeat 1-3 until one is found.

  4. Expand and parse the command string (see below).

  5. Process the command.

The expansion and parsing rules for step four are as follows:

  1. Split the initial command string on word boundaries. Steps 2-4 are applied to each token.

  2. Expand variables. An empty string will be used for any undefined variables.

  3. Split the token on word boundaries. This may produce additional arguments if a variable is not within a quoted string and its value has whitespace characters.

  4. Remove quotation. This includes escaped characters in a non-quoted word or double quotes and the quote characters used to enclose a quoted string.

Be careful when including quotes with variables. Explicit null, empty string, arguments are retained as arguments, including those that surround undefined variables (explicit null arguments are sequences of "" or `'). However, implicit null arguments that result from the expansion of non-quoted parameters are removed.

For example, if you use variables as follows:

>set OPTION "-set name" ;
>cd $OPTION ~/path ;

This could create an invalid command, as in the following case when $OPTION is undefined:

>cd "$OPTION" ~/path;

The following example shows that when $OPTION is undefined, the command is valid when quotes do not enclose the undefined argument, since the implicit null arguments are removed:

>cd $OPTION ~/path;

Error Reporting

When AdminUtil processes a script file, and an error occurs, the last command string is printed after the error information. Printing this information can help identify the command that failed. The last command string is not printed when an error occurs in interactive mode.

If an error occurs when the infolevel is set to level 3 (verbose), the command token strings are printed after the error information. This information shows the actual command, and the command arguments after expansion is performed on a command string. The command tokens are printed for both interactive and file mode.

For example, the following set and cd command sequence causes an error because the value `-opt' is not a valid option for cd. The last command helps identify the command that failed. The command tokens show the command and arguments after the expansion. When the infolevel is set to 3, AdminUtil displays the following:

set A "-opt abc"; 
cd $A;

LAST COMMAND: 
cd $A

COMMAND TOKENS: 
[0]: cd 
[1]: -opt 
[2]: abc

Command List

Table 4-28 provides a description of the AdminUtil commands in alphabetical order.

Command Examples

Table 4-29 provides examples of the AdminUtil commands.

Table 4-28  AdminUtil Commands
Command  Description 

activate [entry]  

Reserved for future use. 

attrl {-a | -r | -s} [args]  

Manages an attribute list. Builds a set of attributes for commands such as create and setattr. There is one unnamed internal attribute list. 

attrl -a attrName

attrValue . . . 

Adds one or more values for an attribute to the attribute list. If the list already contains an attribute with the name attrName, the values are added to the existing values.

attrName specifies the attribute name.

attrValue specifies the value(s) to be added for the attribute.  

attrl -r

[{* | attrName} [attrValue] ] 

Removes all attributes from the attribute list or values for a specific attribute.

attrName specifies the name of the attribute for which values are to be removed. If this is not specified, or it is "*", all attributes are removed from the list.

attrValue specifies the value(s) to be removed for the attribute.  

attrl [-s {* | attrName}]  

Shows the values for all attributes in the list or values for a specific attribute.

attrName specifies the name of the attribute to show. If this is not specified, or it is "*", the command shows all attributes. 

builddn [-set var]

entry  

Builds a distinguished name from an entry reference. This is similar to the lookup command except it does not check whether or not such an entry exists. This is useful for constructing a full DN and saving it to a named variable for later use as an attribute value.

entry is a reference from which a DN is constructed

-set var saves the built reference to the named variable var.  

cd [-set var]

[entry]  

Binds the cwo to the specified entry.

entry is a reference to the object to be bound as the cwo. If entry is not included, the cwo is bound to the initial context used to access the LDAP Directory.

-set var saves an entry reference to the named variable var.

See "Object References", for more details on entry references. 

create [-bind]

[-set var]

[-al]

[{-av "name value"} ]

[{-avpasswd name} ]

entryType

entryName

[parentEntry

Creates a new OMB entity.

The attribute values are a combination of those specified and the default values for all mandatory attributes not specified. Create fails if the object has mandatory attributes that are not supplied, that is, the user did not specify a value and the attribute is mandatory and does not have a default value.

entryType specifies the type of object to create.

entryName specifies the name of the object.

parentEntry specifies a reference to the parent of the object being created. If not specified, use the cwo as the parent.

-bind causes the cwo to be bound to the object that was created.

-set var saves the object reference to the named variable var.

-al causes attributes from an internal attribute list to be used for object creation. The attrl command is used to manage the attribute list.

-av explicitly specifies an attribute value. Multiple -av options are allowed. The -av argument must be a quoted string with two or more words. The first word is the attribute name, and the subsequent word(s) specify the attribute value(s). Do not use the -av option when the name or the value contains whitespace or quote characters. If you need to include whitespace or quote characters, use the attrl command to set the value in the attribute list, and then use the -al option with the create command.

-avpasswd displays a dialog that prompts the user for an attribute value. The text input field shows an echo character rather than the entered text. The dialog is displayed for both interactive and batch modes. A named variable can be used for the attribute name.  

createombinstance

[-bind]

[-set var]

[-repair]

entryName

[parentEntry]  

Constructs an OMB Instance container and other containers that are commonly found under the instance container. This command can also be used to repair an OMB Instance container by creating any entries that might be missing. This command is provided solely for ease of use.

entryName specifies the name of the omb_instance_container to create.

parentEntry specifies a reference to the parent entry. If not specified, use the cwo.

-bind causes the cwo to be bound to the object that was created.

-set var saves the object reference to the named variable var.

-repair allows an existing omb_instance_container to be repaired by only creating those entries that currently do not exist. If -repair is not specified, the command fails if the container already exists.  

deactivate [entry]  

Reserved for future use. 

delete [-subonly]

[-ign]

[-recurse]

[entry]  

Deletes a specific entry, or deletes entries of a subtree.

Note: Use extreme caution when using this command. Depending on the options used, this command deletes a single object or deletes all entries in the subtree. An attempt to delete an object might fail even when that object has no children. This might occur if there is some dependency on that object by another object. The delete might fail with a notification error.

entry specifies a reference for the target object or without an entry, the cwo.

-ign option tells delete to silently ignore errors if the entry to be deleted does not exist.

-subonly deletes only entries in the subtree of the target object. The target object is not deleted, even if -recurse is specified.

-recurse deletes all objects in a subtree.  

dir [entry

Lists the contents (children) of an entry.

entry is a reference to the object whose children are listed, or the cwo. 

echo [arguments

Writes the arguments to output. This is useful for diagnostic purposes and displaying variables. The arguments are separated by a blank and terminated with a newline. If no arguments are supplied, only a newline is output. 

exit [all] 

Exits the current command reader. This is the same as quit.

The option, all for the exit command quits all command readers and terminates the program. If all is not specified, only the current command reader stops. If the reader was nested, started using the run command, processing continues using the previous reader. 

help [command]

[-out file]

[command

Displays usage information, or information for a specific command.

-out file sends the output to the specified file.

command displays help information for a specific command. 

lookup [-bind]

[-set var]

entry  

Looks up a reference to retrieve such information as the entry name, entry type and distinguished name.

entry is a reference to the object that is the target of the lookup, or the cwo if not specified.

-bind causes the cwo to be bound to that object.

-set var saves a reference to the named variable var.  

pwd [-set var]  

Displays information for the current working object.

-set var saves a reference for the current bound object to the named variable var.  

quit [all] 

Exits the current command reader. This is the same as the exit command.

The option, all, for the quit command quits all command readers and terminates the program. If all is not specified, only the current command reader terminates. If the reader was nested (started using the run command) processing continues using the previous reader. 

run [filename] 

Run suspends the current command reader, creates a new command reader and begins processing commands using the new reader. The current reader is resumed once the new reader has finished. An interactive reader is started if no filename is specified, otherwise a file reader is started. This command is useful for nesting batch files, running a batch file from interactive mode or switching to interactive mode from a batch file.

When a series of readers have been started (that is, nested run commands) and an error occurs when processing a command from a file reader, that reader will be cancelled as well as all preceding file readers, up to the most recent interactive reader. If no interactive reader was started, the program terminates.

The reader is not cancelled if the "ignore error" flag has been enabled and an error occurs. The "ignore error" can be enabled using the -ign command line option or the setopt ignoreerror command. 

set [{-u | -s} [args] ] 

Manages named variables.

There are two ways to assign a value to a variable. The set command associates a string to a named variable. The -set option for cd, pwd, lookup, create and builddn associates an entry DN to a named variable.

A $varName or ${varName} syntax references the value associated with a named variable.  

set name value 

Saves an arbitrary string to a named variable. This variable can then be referenced by other commands (for example, attrl) as $name or ${name} when the value is needed.

name specifies the variable name.

value specifies the value. 

set [ -s {* | name}]  

Shows the value of a specific variable or all variables.

name specifies the named variable to show. If not specified, all named variables are shown.  

set -u [{* | name}]  

Removes (unsets) a specific variable or removes all variables.

name specifies the named variable to clear. If not specified, all named variables are cleared. 

setattr {[-al]

[{-av "name value "} ]

[{-avpasswd name} ]}

[entry]  

Modifies attributes for an object. The attributes being changed are a combination of those from an internal attribute list (-al option) and/or those explicitly specified (-av and -avpasswd option).

entry specifies a reference for the target object. If not specified, use the cwo.

-al causes attributes from an internal attribute list to be used. The attrl command is used to manage the internal attribute list.

-av allows the user to explicitly specify an attribute value. Multiple -av options are allowed. The -av argument must be a quoted string which consists of two or more words. The first word is the attribute name, and the subsequent word(s) specify the attribute value(s). Do not use the -av option when the name or the value contains whitespace or quote characters. If you need to include whitespace or quote characters, use the attrl command to set the value in the attribute list, and then use the -al option with setattr.

-avpasswd displays a dialog that prompts the user for an attribute value. The text input field shows an echo character rather than the entered text. The dialog will be displayed for both interactive and batch modes. A named variable can be used for the attribute name. 

setopt [option [value] ] 

Sets or displays program options.

option specifies the option.

value specifies the new value. If not specified, the current value of the option is shown.  

setopt errorlevel [level

Sets 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 -errorlevel command-line option can be used to set the errorlevel when AdminUtil is first started.

The default value for errorlevel is 2. 

setopt infolevel [level]  

Displays or sets the information level. This gives the user a certain degree of control over how much information is output. Level should be in the range 0 to 3, from least to most verbose.

The -infolevel command-line option can be used to set the infolevel when AdminUtil is first started. 

setopt ignoreerror [true|false] 

If enabled (true), ignore errors when processing commands from a batch file and continue processing the file. If disabled (false), cancel processing the commands if an error occurs.

The -ign command-line option can be used to enable the ignore error mode when AdminUtil is first started. 

setopt echo

[{true | false}]  

Sets the mode for echoing input lines. When echo mode is enabled, each input line is displayed. When echo is disabled, the input line is not echoed. 

show ameta

[-long | -short]

[-type]

[entry [attrName]]  

Shows attribute metadata for an existing entry or an entry type.

entry specifies a entry reference or entry type for which attribute metadata is displayed. This can be "." to reference the cwo.

attrName specifies the name of the attribute. If not specified, metadata for all attributes is displayed.

-long, provides detailed information (the default for a single attribute).

-short, provides abbreviated information (the default for multiple attributes).

-type, the entry argument specifies an entry type rather than an entry reference.  

show attrs [entry]  

Shows attribute values for an object reference.

entry specifies a object reference whose attributes are displayed or without an entry, the attributes of the cwo. 

show emeta

[-long | -short]

[-type]

[entry

Shows entry metadata for an existing entry, a specific type of entry or all entry types.

entry specifies a entry reference or entry type for which entry metadata is displayed. This can be "." to reference the cwo.

-long, provides detailed information (the default for a single entry).

-short, provides abbreviated information (the default for multiple types).

-type, the entry argument specifies an entry type rather than an entry reference. If -type is specified and entry is not specified, entry metadata for all entry types is displayed.  

show lasterror [elevel

Shows information about the last error, at the specified error level. When using interactive mode, this command is useful for displaying information at a specific level for a specific command. See setopt errorlevel for information on setting the error level.

elevel specifies the error level setting, and is set to an integer value in the range 1-4. 

unsetattr { { -a { name | *}} ... } [entry

Unsets the value for an optional attribute or the values for all optional attributes of an entry. Only optional attributes that are not read-only after creation can be unset.

-a specifies the name of the attribute to unset. Multiple -a options are allowed. Using -a with * for the name unsets all optional attributes for the entry.

entry specifies a reference for the target object or without an entry, the cwo. 

Table 4-29  AdminUtil Examples
Example  Description 

activate; 

Sends an activate command to the object referenced by the currently bound object. 

attrl -a provider_queue_name "queue1";

attrl -a server_dn "$MYBRK_DN";

attrl -a max_messages 250; 

Adds the value queue1 to provider_queue_name.

Adds the value of MYBRK_DN to server_dn.

Adds the value 250 to max_messages. 

attrl -r max_memory;

attrl -r *; 

Removes all values for an attribute.

Removes all attributes from list. 

attrl -s max_memory;

attrl -s;  

Shows value for max_memory.

Shows all attributes in list. 

builddn -set MYBASE1 "/c=us/o=C1/cn=OracleContext/cn=Products/cn=OMB";

builddn -set MYBASE2 "/$CO/$FIXEDDIT";

builddn -set MYOMB_DN "~/cn=myomb"; 

Builds a DN for an entry reference that is relative to the root and made up of atomic names. The DN is saved to the variable MYBASE1.

Builds a DN for an entry reference that is relative to the root and made up of named variables. The DN is saved to MYBASE2.

Builds a DN for an entry reference that is relative to the initial context. The DN is saved to the variable MYOMB_DN. 

cd;

cd ~;

cd ..;  

Binds the cwo to the initial context.

Binds the cwo to the initial context.

Binds the cwo to the parent of the current cwo.  

cd $BRK_DN;  

Binds the cwo to the entry referenced by the named variable BRK_DN that is a child of the current cwo. 

cd -set BRK_DN "~/$OMB_DN/msg_broker";  

Binds the cwo to an entry having the entry name msg_broker that is a child of an entry referenced by the named variable OMB_DN which is relative to the initial context. The reference is saved to BRK_DN.  

cd -set BRK_DN "./omb1/msg_broker";  

Binds the cwo to the entry referenced by an entry path made up of simple names. The entry reference is saved to BRK_DN.  

cd ~/cn=omb1/cn=Queues/queue1;  

Binds the cwo to an entry referenced by a path that is relative to the initial context and made up of simple and atomic name components. 

create msg_broker msg_broker "~/$OMB_DN";  

Creates a new object under the entry referenced by the named variable OMB_DN. Use default values for the attributes.  

create -al topic topictest;  

Creates a new object under the cwo. The object is created using values from the internal attribute list and defaults for all others.  

create -bind -set MYTOPIC -al topic topicTest "~/$TOPICS";  

Creates a new object under the entry referenced by the named variable TOPICS. Uses attributes from the internal attribute list and default value for all other attributes. Binds the newly created object as the cwo and saves an object reference to the named variable MYTOPIC.  

create -set BRK_DN -al -av "max_memory 5" -av "max_concurrent_reqs $MAXREQ" msg_broker msg_broker "~/cn=myomb";  

Creates a new object under an entry named cn=myomb that is relative to the initial context. The creation attributes are a combination of those from the internal attribute list, those explicitly given via the -av options and defaults for all others. The value for the max_concurrent_reqs attribute is the value of the named variable MAXREQ. The reference to the new entry is saved to BRK_DN. 

create -set AQSVR -av
"aq_service_name $SVCNAME" -avpasswd aq_password aq_server aqsvTest ~/cn=myomb ;
 

Creates a new object under an entry named cn=myomb that is relative to the initial context. The aq_service_name attribute is set to the value of the SVCNAME variable. A dialog prompts for the value of the aq_password attribute. The reference to the new entry is saved to the named variable AQSVR.  

createombinstance -set OMB_DN
ombtest ~;
 

Creates a new OMB Instance container named ombtest and its associated sub-containers. It is created at the initial context and the reference saved to the named variable OMB_DN. This fails if ombtest already exists.  

createombinstance -set OMB_DN -repair ombtest "/$MYBASE";  

Repairs, or creates, an OMB Instance container whose parent is the entry referenced by the named variable MYBASE. This creates any entries that do not exist, including the OMB Instance container itself. The reference is saved to the named variable OMB_DN. 

deactivate "$BRK_DN"; 

Sends a deactivate command to the object reference by the named variable BRK_DN. 

delete; 

Deletes the cwo. This will fail if any objects exist under the target object, cwo in this example.  

delete "~/$OMB/Queues/$QUEUE1"; 

Deletes the referenced entry. 

delete -subonly; 

Deletes only the immediate children (one level) of the target object, the cwo. The target object is not deleted. Since the recurse option is not specified, any object which has children of its own is not deleted.  

delete -subonly "~/$OMB_DN/Queues"; 

Deletes the immediate children of the referenced entry. 

delete -recurse "~/$OMB_DN"; 

Deletes all objects in the subtree of the object referenced by the named variable OMB_DN, including the target object. 

delete -subonly -recurse "~/$OMB_DN";  

Deletes all objects in the subtree of the object referenced by the named variable OMB_DN. The target object is not deleted. 

dir .;  

Lists the contents of the current bound object.  

dir "~/$OMB_DN";  

Lists the contents of the entry referenced by the named variable OMB_DN.  

echo A=$A ;  

Display the resulting string after the standard expansion and parsing has taken place. 

echo /$MYOMB_DN/cn=queues/cn=$MYQUEUE ; 

Display the resulting string after the standard expansion and parsing has taken place. 

help;  

Displays help for all commands.  

help set;  

Displays help for the set command.  

help -out cmd.hlp -all ; 

Writes help information for all commands to a file named cmd.hlp. 

lookup -bind -set OMB_DN ~/cn=ombtest; 

Looks up an atomic name that is relative to the initial context, binds the cwo to that object and saves an object reference to the named variable OMB_DN.  

lookup -var MYTOPIC
~/cn=topic1,cn=Topics,cn=ombtest;
 

Looks up an object that is relative to the initial context and saves the entry DN to the named variable MYTOPIC.  

lookup msg_broker; 

Looks up an object which is a child of the cwo and has an entry name of msg_broker. 

lookup "~/$BRK_DN";  

Looks up the object that is relative to the initial context and referenced by the named variable BRK_DN. 

lookup -set BRK_DN ~/ombtest/msg_broker; 

Looks up the object which from the initial context, there is an object that has an entry name of ombtest which has a child whose name is msg_broker. The entry DN is saved to BRK_DN. 

pwd; 

Displays information for the current bound object.  

pwd -set BRK_DN; 

Displays information for the current bound object and saves its reference to the named variable BRK_DN.  

run myfile ; 

Starts a new command reader for a file. 

run ; 

Starts a new interactive reader. 

set MYROOT "cn=OMB,cn=Products,cn=OracleContext,o=Comp,c=us"; 

Sets a distinguished name value for the named variable MYROOT. 

set MAXMEM 5;  

Sets the value of MAXMEM to 5. 

set -s MYROOT;  

Shows value for MYROOT. 

set -s *; 

Shows all named variables. 

set -u MYROOT; 

Clears variable MYROOT. 

set -u *; 

Clears all named variables. 

set FIXEDDIT cn=OMB,cn=Products,cn=OracleContext; 

Sets the value for the named variable FIXEDDIT. 

set COMP1 o=Comp1,c=us;  

Sets COMP1 to the specified value. 

setattr -al;  

Modifies attributes for the cwo using values from the internal attribute list. 

setattr -av "max_memory 6";  

Modifies a specific attribute for the cwo. 

setattr -al -av "max_memory 5"
-av "max_concurrent_reqs $MAXREQ"
~/cn=myOmb ;
 

Modifies attributes for an object having atomic name of cn=myOmb that is relative to the initial context. The attributes being set are a combination of those from the internal attribute list and those explicitly given via the -av options. The value for the max_concurrent_reqs attribute comes from MAXREQ. 

setAttr -av "aq_service_name $SVCNAME" -avpasswd aq_password ~/cn=myOmb ; 

Modifies attributes for an object having atomic name of cn=myOmb that is relative to the initial context. The value for the aq_service_name attribute comes from the named variable SVCNAME. A dialog prompts for the value of the aq_password attribute. 

setopt infolevel ; 

Show current information level. 

setopt infolevel 3 ; 

Sets a new information output level setopt. 

setopt ignoreerror ; 

Display the current ingore error setting. 

setopt ignoreerror true; 

Enable ignore error mode. 

setopt errorlevel 3; 

Set a new error information level. 

setopt errorlevel ; 

Display the current error information level. 

setopt echo; 

Shows the current echo mode. 

setopt echo true; 

Enables the input line echo mode. 

show lasterror 4;  

Display error information for the last error. A stack trace for all linked exceptions is displayed. 

show emeta . ; 

Shows entry metadata for the current cwo. 

show emeta ~/ombtest/msg_broker ; 

Shows entry metadata for a referenced entry. 

show emeta -type ; 

Shows entry metadata for all entry types.  

show emeta -type msg_broker; 

Shows entry metadata for a specific entry type. 

show ameta . ; 

Shows attribute metadata for the current cwo. 

show ameta . max_memory; 

Shows attribute metadata for a specific attribute of the cwo. By default, detailed information is displayed. 

show ameta ~/ombtest/bkrtst max_memory; 

Shows attribute metadata for a specific attribute of a referenced entry. 

show ameta -type msg_broker;  

Shows attribute metadata for all attributes of a specific entry type. 

show ameta -type msg_broker max_memory; 

Show attribute metadata for a specific attribute of a specific entry type. 

show attrs . ; 

Shows attributes for the current cwo. 

show attrs ~/cn=ombtest/cn=msg_broker ; 

Shows attributes for the referenced entry. 

unsetattr -a max_memory ; 

Unsets the max_memory attribute for the cwo. 

unsetattr -a propagation_send_threads
-a propagation_recv_threads;
 

Unsets two attributes for the cwo. 

unsetattr -a * ~/cn=myOmb/cn=msg_broker; 

Unsets all optional attributes for a msg_broker entry. 

Object References

Using AdminUtil, an object can be referenced using its LDAP distinguished name. This can be a full DN or an DN relative to an initial context. References use a most-significant to least-significant naming convention. For example, the following is a full DN for cn=myOmb:

cn=myOmb,cn=OMB,cn=Products,cn=OracleContext,ou=sales,o=oracle,c=us

If the initial context were set to the following: cn=Products,cn=OracleContext, ou=sales,o=oracle,c=us, the DN specified would be:

cn=myOmb,cn=OMB

AdminUtil supports a path syntax for entry references. The syntax uses a least-significant to most-significant naming convention (right to left). Each path component is separated by a '/' character. An absolute or relative path may be specified. A path reference that starts with "/" is interpreted as an absolute path. A path that starts with "~/" is interpreted as relative to the initial context. Anything else is interpreted as relative to the currently bound object.

For example, AdminUtil resolves the following reference to a full DN:

/c=us/o=oracle/ou=sales/cn=OracleContext/cn=Products/cn=OMB/cn=myOmb

For the initial context, cn=Products,cn=OracleContext,ou=sales,o=oracle,c=us, a path reference could be:

~/cn=OMB/cn=myOmb

Using AdminUtil, do not use any paths that place the current working object above the initial context set in OMB_IC. For example, if the initial context is set to the following:

ldap://system1/cn=inst1,cn=OMB,cn=Products,cn=OracleContext,ou=dept,o=comp,c=us


Then, if the current working object is inst1, you cannot use the command cd.. to the change the current working object to cn=OMB. The upper limit in this example is:

cn=inst1

However, the buildDn command can use a path referring to an entry above the initial context. For example, if the current working object is inst1, then the command below sets the BROKER variable to the distinguished name of a broker under a different omb_instance_container:

buildDn -set BROKER ../cn=inst2/cn=abroker;

Valid path components include the following:

~ 

The initial context currently being used. This is similar to the Unix home reference. 

. 

The current working object (cwo). 

.. 

The parent of the cwo.  

DN 

An LDAP distinguished name. 

RDN 

An LDAP relative distinguished name.  

name 

The simple name (for example, the Products part of cn=Products).  

atomic 

An LDAP atomic name (for example, o=oracle or cn=OracleContext). 

$varName 

A reference associated with the named variable varName. 

Table 4-30 shows several sample object references.

Table 4-30  Sample Object References
Reference  Description 

~ 

The initial context. 

.  

The cwo. 

..  

Parent of the cwo. 

~/ombtest  

An object named ombtest, a child of the initial context. 

msg_broker  

An object having an entry name of msg_broker that is a child of the cwo. 

cn=msg_broker 

An object using an atomic name that is a child of the cwo. 

$BRK_DN 

An object referenced by the named variable BRK_DN, a child of the cwo. 

$OMB_DN/msg_broker 

An object having the entry name msg_broker that is a child of the object referenced by the named variable OMB_DN which in turn is a child of the cwo. 

../msg_broker  

An object named msg_broker that is a child of the parent of the cwo. The msg_broker object is a sibling of the cwo (hierarchical-wise). 

../msg_broker/aq_driver  

An object named aq_driver which is a child of an object named msg_broker which in turn is a child of the parent of the cwo. 

~/cn=ombtest/msg_broker  

An object path relative to the initial context that has atomic and entry name components. 

~/cn=ombtest/$QUEUES/qtest 

An object path relative to the initial context that has atomic, named variable and entry name components. 

/cn=OMB,cn=Products,
cn=OracleContext,o=oracle,
c=us/ombtest/msg_broker
 

An absolute object path which has RDN, atomic, and entry name components. 

/c=us/o=oracle/
cn=OracleContext/cn=Products/
cn=OMB/ombtest/msg_broker
 

An absolute object path which has RDN, atomic, and entry name components. 

Entry Attributes

Each entry type has attributes that define the type of data associated with the entry. Metadata exists for both the entry types and the attributes associated with the entries. Using show emeta displays the entry metadata for an existing entry or an entry type. Using show ameta displays attribute meta information for attributes of an existing entry or an entry type.

The attribute metadata details various information that might prove useful to the user. It indicates whether the attribute is single-valued or multi-valued. It indicates whether the attribute value can be set by the user when the entry is first created and if it can be modified once the entry has been created. It also indicates the syntax or format of the value.

The attribute syntax can be one of the following types.

Table 4-31  Entry Attribute Syntax
Value Type  Description 

String 

The value is a string. 

Integer 

The value is a string representing a numeric integer value. 

Float 

The value is a string representing a numeric float value. 

Boolean 

The value is a string that should be either "true" or "false". 

Distinguished Name 

The value is a string representing an LDAP distinguished name (DN). The DN string should be the full DN versus a DN relative to the initial context.

For example, the full distinguished name of an entry that is relative the following initial context would be:

Initial Context:

cn=OMB,cn=Products,cn=OracleContext,o=oracle,c=us

Given DN:

cn=msg_broker,cn=testOmb

Resulting DN:

cn=msg_broker,cn=testOmb,cn=OMB,cn=Products, cn=OracleContext,o=oracle,c=us 

Octet String 

The value is an octet (byte) array. No value is displayed. This attribute type is used for binary data. The value stored is the UTF-8 encoding of the user-specified string.  

Name Value Pair 

The value is a string that represents a set of name value pairs. The value for such an attribute has a required syntax of name=value

AdminUtil Limitations

  1. The set command assigns an arbitrary string to a named variable. When used for a path component, a named variable will usually be the entry's simple name, atomic name or an RDN. If a simple name is specified but is not unique at the hierarchical level for which it is being used, it is arbitrary as to which object would actually be referenced. In that case, an atomic name must be used for that particular component to guarantee that the desired object is referenced.

  2. It is recommended that double quotes be added to object references for a named variable. The double quotes are required if the variable value contains an embedded blank.

  3. It is possible to delete the initial context from within an interactive session of AdminUtil. However, AdminUtil cannot perform any other actions if the initial context is deleted. To perform other actions, exit AdminUtil and set the initial context to an existing entry, and then restart AdminUtil.

  4. Be careful when modifying the server_dn or provider_queue_name attributes for an existing Oracle AQ topic entry or Oracle AQ queue entry. Refer to the create_provider_q, rm_provider_q, and provider_q_created attribute information for queues and topics to determine the actions that are taken to create or remove a corresponding AQ queue when the Oracle Message Broker administrative tools modify queues or topics in the LDAP Directory.

  5. The LDAP Directory server should not be shutdown when running AdminUtil.

Directory Utilities

This section covers the Oracle Message Broker utilities that allow you to check directory entries and migrate directory entries from previous Oracle Message Broker releases.

This section covers the following:

Checking Directory Entries with AdminDirCheck

The AdminDirCheck command performs basic validation for Oracle Message Broker configuration data. It identifies problems with Oracle Message Broker entries in an LDAP Directory. The command uses Java Naming and Directory Interface (JNDI) to access the directory and then it checks either a single entry or all entries in a subtree. Starting at a given entry relative to the initial context, AdminDirCheck checks:

AdminDirCheck only accesses the LDAP Directory to check entries, it does not connect to an active Oracle Message Broker or validate any other Oracle Message Broker components.

You can use AdminDirCheck whenever the Oracle Message Broker is having unexpected problems or throwing unexpected exceptions. Such problems might range from problems a JMS client is having as it tries to use a queue, topic or connection factory obtained using JNDI to problems starting Oracle Message Broker.

If AdminDirCheck reports a problem, it does not attempt to fix the problem. You need to take the appropriate action based on the report to fix the problem. This may involve either modifying an entry or deleting and recreating an entry. An entry that contains a bad DN reference or a value out-of-range can be updated and the problem will be fixed by assigning a new, valid value.

AdminDirCheck classifies LDAP entries into three categories:

AdminDirCheck uses the OMB_IC environment variable to determine the LDAP server to connect to.

AdminDirCheck Options

AdminDirCheck uses the following syntax:

AdminDirCheck [initial_DN] [options]

By default, the program uses the following options: +all, -def, -unk. By default simple authentication is required. You are prompted for the user and password if these are not specified on the command line (using the -noauth option you are not prompted for a user and password).

Table 4-32  AdminDirCheck Options
Option  Description 

initial_DN 

Specifies the LDAP entry that is the starting point for the validation. This is the DN of the entry, relative to the initial context used to connect to the LDAP Directory. By default, the validation includes all entries in the entire subtree. Use -nosubtree to limit validation to a single entry. 

{+|-}all 

Enables or disables all validation options. This is generally used in combination with other options to enable or disable a set of options. For example, +all -dit enables all validation options except DIT checking; -all +ref enables only reference checking.

+all enables all validation options

-all disables all validation options 

-b LDAP_baseDN 

The LDAP_baseDN supplies a base DN to use for the initial context. If you use the -b option, -h is required. 

-D auth_DN 

The auth_DN supplies the DN to use for authentication. 

{+|-}def 

Enables or disables default value checking. Some attributes have a default value that is used if a value is not explicitly assigned for that attribute.

+def searches for attributes that do not have an assigned value but have a default

-def disables default value checking 

{+|-}dit 

Enables or disables DIT validation. Checks the hierarchy of the entries to insure the correct parent and child relationship exists. AdminDirCheck does not validate the topmost entry if the topmost entry has the same DN as the initial context.

+dit enables DIT hierarchy checking

-dit disables DIT hierarchy checking 

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

-help 

Displays the program usage 

-h LDAP_host 

Specifies an LDAP server. The host, LDAP_host must be a host available on the network. 

-fullversion 

Displays the full program version information. 

-noauth 

Specifies that LDAP authentication is not required on the LDAP server 

-nosubtree 

Limits the validation to a single entry specified by the initial_DN parameter. If this option is not specified, all entries in the subtree are checked. 

{+|-}omb 

Enables or disables corrupt Oracle Message Broker entry checking. This option attempts to distinguish corrupt Oracle Message Broker entries from non-Oracle Message Broker entries.

+omb searches for unknown entries that are likely to be corrupt Oracle Message Broker entries

-omb disables corrupt Oracle Message Broker entry checking 

-p LDAP_port 

TCP port to use for the LDAP connection on the LDAP server. If you use the -p option, -h is required. 

-P wallet_password 

Specifies the wallet password. This is ignored if the value of -U is 0 or 1. 

{+|-}ref 

Enables or disables reference validation. Checks certain types of attributes that reference other entries. For example, a DN attribute is checked to see whether the referenced entry exists, and if possible, that the referenced entry is of the correct type.

+ref enables reference checking

-ref disables reference checking

For reference validation, it is possible for an entry referenced by a DN attribute to be reported as not existing, when, in fact, it does exist. This might occur for a variety of reasons. For example in the following cases:

  • If the referenced entry is not accessible by the initial context

  • If the user does not have access rights to the referenced entry

  • If the reference is to an entry on another LDAP server

For an entry that contains an attribute that is a DN, using the +ref option AdminDirCheck does not check whether the DN is within the same OMB Instance. It only tries to verify that the entry exists and that the referenced entry is the correct Oracle Message Broker entry type (if applicable). 

{+|-}rng 

Enables or disables range validation. Checks the attributes of an Oracle Message Broker entry for range violations such as being outside the lower or upper limits or a value not from a set of valid values. Many attributes have no value limitations.

+rng enables range checking

-rng disables range checking 

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

 

{+|-}unk 

Enables or disables unknown entry checking. The subtree being scanned may have both Oracle Message Broker (known) and non-Oracle Message Broker (unknown) entries. This option can be used to search for non-Oracle Message Broker entries. An attempt is made to distinguish between a corrupt Oracle Message Broker entry and a non-Oracle Message Broker entry and report only a non-Oracle Message Broker entry.

+unk reports any unknown (non-Oracle Message Broker) entries

-unk disables unknown entry reporting 

-version 

Displays the program version number. 

-w auth_password 

Supplies a password, auth_password, 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. 


Note:

AdminDirCheck does not remove JNDI related Java authentication properties. It does set certain JNDI properties based on command line options. Thus, you could modify the OMB_LP environment variable to set the JNDI security properties and run AdminDirCheck with the -noauth option, and still access a secured LDAP server based on the properties defined in OMB_LP. 


Migrating Directory Entries Between Releases

The Oracle Message Broker provides a migration utility for migrating directory entries from release 1.0 to release 2.0. The migration utility performs the following actions:

Use this utility with caution. Some LDAP Directories, for example the Netscape Directory, do not allow renaming of an entry which is not a leaf entry. The change from cn=oraclesoftware to cn=oraclecontext requires to migration utility to delete all of the entries underneath cn=oraclesoftware and then recreate them.

Partial failures or cancelling the command before it completes can lead to problems. Before deleting any entries, the utility saves the Oracle Message Broker directory data in a file named OMB10DATA.ldif, LDIF format, in the current directory.

Take the following precautions while running the Migrate10To20:

  1. While Migrate10To20 is in use, there should be no other directory operations in progress.

  2. The base DN (-b option) should be carefully selected. Make the base DN match the initial context set in the environment variable OMB_IC (and remove the leading components, cn=Products,cn=OracleSoftware,).

  3. The Migrate10To20 does not work correctly if an entry, cn=OracleSoftware, which is of type container exists underneath an entry, cn=OracleSoftware, which is also of type container.

    That is, if both of the following entries exist in the same LDAP Directory, and both entries are of type container:

    cn=OracleSoftware,ou=bizzare,o=acme,c=us, 
    cn=OracleSoftware,cn=foo,cn=foo,cn=OMB,cn=Products,cn=OracleSoftware,ou=bizz
    are,o=acme,c=us
    

Migrate10To20 Options

Migrate10To20 uses the following syntax:

Migrate10To20 [options]

Table 4-33 shows the available options. By default, the program uses no options, and assumes that simple authentication is required. You are prompted for the user and password if these are not specified on the command line (using the -noauth option you are not prompted for a user and password).

For example:

% Migrate10To20 -h hal -p 389 -b ou=bizarre,o=acme,c=us

Table 4-33  Migrate10To20 Options
Option  Description 

-b LDAP_baseDN 

The LDAP_baseDN , or the initial context supplies a base DN to use for the initial context. 

-D auth_DN 

The auth_DN supplies the DN to use for authentication. 

-h LDAP_host 

Specifies an LDAP server. The host, LDAP_host must be a host available on the network. 

-fullversion 

Displays the full program version information. 

-ldapv2 

Use this option when the LDAP Directory only supports LDAP version 2. The default, without this option is support for LDAP version 3. 

-noauth 

Specifies that LDAP authentication is not required on the LDAP server 

-p LDAP_port 

TCP port to use for the LDAP connection on the LDAP server. 

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

 

-version 

Displays the program version number. 

-w auth_password 

Supplies a password, auth_password, 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. 

Authorization for Running Migrate10To20

The LDAP Directory username and password associated with the Migrate10To20 are supplied on the command-line using the -D and -w options (or provided from the values supplied in the pop-up window if command-line options are not supplied). Migrate10To20 uses the supplied username and password when it accesses the LDAP Directory.

The username provided needs to have create and delete permissions in the subtree rooted at the supplied base DN or initial context (supplied with the -b option). It is recommended that the username should be the superuser (or equivalent, such as administrator).

If there are user entries underneath cn=oraclesoftware, they are migrated and any password associated with the entry is not changed. However, the username, which is the DN of the entry, does change due to replacing cn=oraclesoftware with cn=oraclecontext.

For example, if the following two entries show the old, and the new username, before, and after running Migrate10To20:

cn=akarmark,cn=users,cn=omb,cn=products,cn=oraclesoftware,<initial-context>
cn=akarmark,cn=users,cn=omb,cn=products,cn=oraclecontext,<initial-context>

All encrypted attributes, such as the AQ password stored in the aq_password are migrated without changes.

ACIs that are set on an LDAP Directory entry are migrated without changes. However, if the ACIs grant/refuse permission to a user/group which is directly underneath the container, cn=oraclesoftware, that was migrated, then the ACIs are invalid, since the DN is not longer valid.


Go to previous page Go to next page
Oracle
Copyright © 1996-2000, Oracle Corporation.

All Rights Reserved.

Library

Product

Contents

Index