Release 2.0.1.0
Part Number A65435-01
 Library |
 Product |
 Contents |
 Index |
| Oracle Message Broker Adminstration Guide Release 2.0.1.0 Part Number A65435-01 |
|
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:
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.
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.
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.
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.
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.
When you use a DN with the Oracle Message Broker utilities, or in an Oracle Message Broker client program, be aware of the following:
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
|
|
" |
Quote |
|
|
, |
Comma |
|
|
: |
Colon |
|
|
+ |
Plus |
|
|
= |
Equals |
|
|
; |
Semi-colon |
|
|
\ |
Backslash |
|
|
# |
Pound |
|
|
< |
Less than |
|
|
> |
Greater than |
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.
Attributes contain two kinds of information.
Any given attribute can hold either application information, or operational information, but not both.
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.
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.
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.
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.
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.
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.
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:
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.
| Attribute | Description |
|---|---|
|
|
Reserved for internal use only |
|
|
Reserved for internal use only |
|
|
Reserved for internal use only |
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 ;
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
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.
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.
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.
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.
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.
| Attribute | Description |
|---|---|
|
|
The name of the Rendezvous service (see the Rendezvous Administration Guide, for more information). |
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:
Table 4-8 Message Broker Attributes
| Attribute | Description |
|---|---|
|
|
Specifies that the client and server run as a single JVM process. For more information, see "Running in Local Mode", in Chapter 5. The value is a boolean. Default value: false |
|
|
Limits the number of concurrent blocking receives to the specified value. The Oracle Message Broker throws a BusyException when a blocking receive request exceeds this limit. A blocking receive is a receive that blocks for at least one (1) second. The JMS specification provides three types of receive methods: blocking, timeout, and non-blocking. Therefore, a BusyException is thrown for blocking receives and timeout receives, when the timeout is 1 second or more and receives are attempted after the specified limit is reached. This option also sets the number of threads that the ORB uses to handle execute method invocations. The value must be an integer. The lower limit is 10. Default value: 10. |
|
|
Heap memory allocated in Megabytes. For more information see, "Oracle Message Broker Memory Management". The value must be an integer. The lower limit is 1. Default value: 16. |
|
|
Specifies the number of HTTP propagation handler threads to start. The value must be an integer. Default value: 1 |
|
|
Number of receive threads for propagation. Increasing the number of receive threads allows the propagation manager to handle more propagation receives concurrently. See Chapter 8 for information on propagation. The lower limit is 0 and the upper limit is 100. Default value: 1. |
|
|
Number of send threads for propagation. Increasing the number of send threads allows the propagation manager to handle more propagation sends concurrently. See Chapter 8 for information on propagation. The lower limit is 0 and the upper limit is 100. Default value: 1. |
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:
MsgBroker command, the value set on the command line with the -heap option specifies the maximum heap size.
max_memory to be updated to a value that is less than the amount of memory currently in use (as set with the -heap option on the MsgBroker command line).
MsgBroker command sets a property when starting the JVM. This property holds the value of the maximum heap size. The Oracle Message Broker uses the property to determine if new values for max_memory are valid.
max_memory attribute is equal to the value of the -heap option in the MsgBroker command, the max_memory attribute cannot be increased at run-time, unless it is first decreased.
MsgBroker command, make sure the following relationships are maintained between the JVM's initial heap size, the maximum heap size, and the Oracle Message Broker's message broker max_memory attribute:
max_memory attribute for the Oracle Message Broker must be set to a value less than or equal to the JVM maximum heap size.
max_memory to be changed to a value greater than the maximum heap size for the JVM.
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.
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.
| Attribute | Description |
|---|---|
|
|
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. |
|
|
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. |
|
|
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 |
|
|
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 |
|
|
The number of threads which will push messages to message listeners. The value must be an integer. The lower limit is 1. |
|
|
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. |
|
|
The DN pointing to the server that supports the AQ Driver. The type of the DN that this references must be aq_server. |
|
|
If true, use the thin JDBC based AQ driver. If false, use the OCI based JDBC AQ Driver. Default value: false |
|
|
The URL suffix to use for the JDBC thin connection to AQ. |
|
|
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 |
A aqlite_driver entry contains configuration information for the Oracle AQ Lite Driver. Table 4-10 describes the driver entry attributes.
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).
An mq_driver entry contains configuration information for the MQSeries Driver. Table 4-12 describes the MQSeries Driver attributes.
The mcast_driver entry contains configuration information for the Oracle Multicast Driver. Table 4-13 describes the Multicast Driver attributes.
The rv_driver entry contains configuration information for the TIBCO Driver. Table 4-14 describes the driver entry attributes.
A prop_http entry contains configuration information for the HTTP propagation. Table 4-15 describes the HTTP propagation entry attributes.
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.
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.
| Attribute | Description |
|---|---|
|
|
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 |
|
|
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. |
|
|
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. |
|
|
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 |
|
|
This attribute applies only if the queue is an AQ Queue. This specifies the schema in which the AQ queue resides. |
|
|
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 |
|
|
A DN pointing to an Acl entry. Refer to Chapter 12, "Security" for more details. |
|
|
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.
Default value: conditional. |
|
|
This is only used for MQSeries queues. Determines if the queue is managed. |
|
|
Determines if the queue stores JMS messages or native messages. The value is a boolean. |
|
|
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 |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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.
Default value: conditional. |
|
|
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. |
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).
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.
| Attribute | Description |
|---|---|
|
|
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 |
|
|
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. |
|
|
This attribute applies only if the topic uses an AQ Lite server. Specifies the storage clause used to create the AQ Lite queue table. |
|
|
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 |
|
|
This attribute applies only if the topic uses an AQ server. Specifies the schema in which the AQ queue resides. |
|
|
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 |
|
|
A DN pointing to an Acl entry. Refer to Chapter 12, "Security" for more details. |
|
|
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.
Default value: conditional. |
|
|
This is reserved for future use. |
|
|
Determines if the topic stores JMS messages or native messages |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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.
Default value: conditional. |
|
|
DN of the server that handles this topic. |
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.
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.
reThe 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.
reThe 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.
| Attribute | Description |
|---|---|
|
|
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 |
|
|
This is reserved for internal use only. |
|
|
Contains the propagation message selector string. See Propagation Message Selector "Propagation Job Configuration" for details. |
|
|
Contains the password to use for the specified username. The value stored is encrypted in the directory. |
|
|
DN of the source queue or topic. |
|
|
DN of the target queue or topic. |
|
|
Default value: 120 |
|
|
DN of the remote entry. This is used when the propagation_target is specified in a remote directory or using a remote_http_entry. |
|
|
Contains the username DN to use to access the remote Oracle Message Broker when the security service authentication is enabled. |
|
|
This is reserved for internal use. |
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.
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.
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".
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:
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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The following list shows the entries that cannot be updated in any way when the Oracle Message Broker is active.
|
|
|
|
|
|
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-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.
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.
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:
quit or exit command.
AdminUtil commands.
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 |
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
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.
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"
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.
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.
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.
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.
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.
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:
The expansion and parsing rules for step four are as follows:
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;
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
Table 4-28 provides a description of the AdminUtil commands in alphabetical order.
Table 4-29 provides examples of the 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 |
|
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. |
|
[{* | 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. |
|
entry |
Builds a distinguished name from an entry reference. This is similar to the entry is a reference from which a DN is constructed -set var saves the built reference to the named variable 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. |
|
[parentEntry] |
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
-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 -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. |
|
[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. |
|
[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 -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
|
|
[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. |
|
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
The option, |
|
|
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
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 |
|
set [{-u | -s} [args] ] |
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 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, 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. |
|
[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
-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 -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. 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 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 |
|
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 |
|
[{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. |
|
[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. |
|
[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 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. |
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:
Table 4-30 shows several sample object references.
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.
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.
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.
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.
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:
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 determines to be an Oracle Message Broker entry with invalid or missing data.
AdminDirCheck uses the OMB_IC environment variable to determine the LDAP server to connect to.
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).
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:
Migrate10To20 is in use, there should be no other directory operations in progress.
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 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
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.
|
 Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
|