Chapter 4 Configuring a Broker

When a broker instance starts, its configuration is governed by a set of configuration files and by the options passed to the imqbrokerd command. This chapter explains how configuration files and command line options interact to configure a broker instance, describes the functions of each broker component and lists its configuration properties, and then explains how to set up the configuration.

About Configurable Broker Components

Message delivery in a Message Queue messaging system—from producing clients to destinations, and then from destinations to one or more consuming clients—is performed by a broker, or by a cluster of broker instances working in tandem.

To perform message delivery, a broker must set up communication channels with clients, perform authentication and authorization, route messages appropriately, guarantee reliable delivery, and provide data for monitoring system performance.

To perform its functions, a broker uses a number of internal components, each with a specific role in the delivery process. These broker components are illustrated in Figure 4-1.

The Message Router component performs the key message routing and delivery service, and the others provide important support services. Table 4-1 briefly describes each component.

Table 4-1 Main Broker Service Components and Functions
Component	Description/Function	For Property Descriptions...
Connection Services	Manages the physical connections between a broker and clients, providing transport for incoming and outgoing messages.	Connection Service Properties
Message Router	Manages the routing and delivery of messages: These include JMS messages as well as control messages used by the Message Queue messaging system to support JMS message delivery.	Message Router Properties
Persistence Manager	Manages the writing of data to persistent storage and the retrieval of data from persistent storage.	Persistence Manager Properties
Security Manager	Provides authentication services for users requesting connections to a broker and authorization services (access control) for authenticated users.	Security Manager Properties
Monitoring Service	Generates metrics and diagnostic information that can be written to a number of output channels that an administrator can use to monitor and manage a broker.	Monitoring and Logging Properties

You can configure these components to optimize broker performance, depending on load conditions, application complexity, and so on. The following sections explore the functions that each component performs and the properties that you can set to affect its behavior.

Connection Services

A Message Queue broker supports communication with both Message Queue application clients and Message Queue administration clients. Each connection service is specified by its service type and protocol type, as follows:

The service type specifies whether the service provides JMS message delivery (NORMAL) or Message Queue administration (ADMIN) services

The protocol type specifies the underlying transport protocol layer that supports the service.

Table 4-2 Connection Services Supported by a Broker
Service Name	Service Type	Protocol Type
jms	NORMAL	tcp
ssljms (Enterprise Edition)	NORMAL	tls (SSL-based security)
httpjms (Enterprise Edition)	NORMAL	http
httpsjms (Enterprise Edition)	NORMAL	https (SSL-based security)
admin	ADMIN	tcp
ssladmin	ADMIN	tls (SSL-based security)

You can configure a broker to run any or all of these connection services. Each connection service is available at a particular port, specified by the broker’s host name and a port number. The jms and admin services are enabled by default.

Message Queue can dynamically map a connection service to a port number, or you can explicitly assign a port. Each service registers itself with a common Port Mapper but has its own Thread Pool Manager, as shown in Figure 4-2.

The next sections describe the relationship between a connection service and the Port Mapper and Thread Pool Manager.

Port Mapper

Message Queue provides a Port Mapper that assigns ports to connection services. The Port Mapper resides at a standard port number, 7676. When a client sets up a connection with the broker, it first contacts the Port Mapper, requesting the port number of a specified connection service.

The port numbers for the jms, ssljms, admin and ssladmin connection services can be dynamic or static. By default, a connection service dynamically configures its port when it starts up. Alternatively, you can specify a static port for the service, but static port numbers are not generally recommended. Static port numbers are typically used only for special situations, such as connections that traverse a firewall.

Thread Pool Manager

Each connection service is multi-threaded, supporting multiple connections. The threads needed for these connections are maintained in a thread pool managed by a Thread Pool Manager component.

You can configure the Thread Pool Manager to set a minimum number and maximum number of threads maintained in the thread pool. As threads are needed by connections, they are added to the thread pool. When the minimum number of threads is exceeded, the system shuts down threads as they become free, until the minimum number threshold is reached, to save memory resources. This number should be large enough so that new threads do not have to be continually created. Under heavy connection loads, the number of threads might increase until the thread pool’s maximum number is reached, after which connections must wait until a thread becomes available.

The threads in a thread pool can be dedicated to a single connection (dedicated model) or assigned to multiple connections, as needed (shared model).

Dedicated model Each connection to the broker requires two dedicated threads: one handles incoming messages for the connection and one handles outgoing messages for the connection. This limits the number of connections to half the maximum number of threads in the thread pool, but it provides for high performance.

Shared model (Enterprise Edition) Connections are processed by a shared thread whenever sending or receiving messages. Because each connection does not require dedicated threads, this model increases the number of connections that a connection service (and therefore, a broker) can support. However there is some performance overhead involved in the sharing of threads. The Thread Pool Manager uses a set of distributor threads that monitor connection activity and assign connections to threads as needed. The performance overhead involved in this activity can be minimized by limiting the number of connections monitored by each such distributor thread.

Security

Each connection service supports specific authentication and authorization (access control) features (see Security Manager).

Connection Service Properties

imq.service.activelist. List of connection services to be started at broker startup.

imq.hostname. Specifies the host to which all connection services bind if there is more than one host available (for example, if there is more than one network interface card in a computer).

imq.portmapper.port. Specifies the broker’s primary port—the port at which the Port Mapper resides.

imq.portmapper.hostname. Specifies the host to which the Port Mapper binds if there is more than one host available.

imq.portmapper.backlog. Specifies the maximum number of concurrent requests that the Port Mapper can handle before rejecting requests. The property sets the number of requests that can be stored in the operating system backlog waiting to be handled by the Port Mapper.

imq.service_name.protocol_type.port. For jms, ssljms, admin, and ssladmin services only, specifies the port number for the named connection service.

imq.service_name.protocol_type.hostname. For jms, ssljms, admin, and ssladmin services only, specifies the host to which the named connection service binds if there is more than one host available.

imq.service_name.min_threads. Specifies the number of threads, which once reached, are maintained in the thread pool for use by the named connection service.

imq.service_name. max_threads. Specifies the number of threads beyond which no new threads are added to the thread pool for use by the named connection service.

imq.service_name.threadpool_model. Specifies whether threads are dedicated to connections or shared by connections as needed for the named connection service.

imq.shared.connectionMonitor_limit. For shared thread pool model only, specifies the maximum number of connections that can be monitored by a distributor thread.

Message Router

Once connections have been established between clients and a broker using the supported connection services, message routing and delivery can proceed.

Basic Delivery Mechanisms

JMS payload messages that are sent by producer clients and destined for consumer clients

Control messages that are sent to and from clients to support the delivery of the JMS messages

If an incoming message is a JMS message, the broker routes it to consumer clients, based on whether the destination is a queue or topic:

If the destination is a topic, the JMS message is immediately routed to all active subscribers to the topic. If a durable subscriber is inactive, the Message Router holds the message until the subscriber becomes active, and then delivers the message.

If the destination is a queue, the JMS message is placed in the corresponding queue, and delivered to the appropriate consumer when the message reaches the front of the queue. The order in which messages reach the front of the queue depends on the order of their arrival and on their priority.

Once the Message Router has delivered a message to all its intended consumers, it clears the message from memory. If the message is persistent, the Message Router removes it from the broker’s persistent data store.

Reliable Delivery: Acknowledgments and Transactions

The delivery mechanism just described becomes more complicated when adding requirements for reliable delivery. There are two aspects involved in reliable delivery:

Assuring that delivery of messages to and from a broker is successful

Assuring that the broker does not lose messages or delivery information before messages are actually delivered

To ensure that messages are successfully delivered to and from a broker, Message Queue uses a number of response control messages.

For example, when a producer sends a JMS message (a payload message) to a destination, the broker responds that it received the JMS message. (By default, Message Queue does this only if the producer specifies the JMS message as persistent.) The producing client uses the broker response to guarantee delivery to the destination.

Similarly, when a broker delivers a JMS message to a consumer, the consuming client sends back an acknowledgment that it has received and processed the message. A client specifies how automatically or how frequently to send these acknowledgments when creating session objects, but the Message Router does not delete a JMS message from memory until it receives an acknowledgment from each consumer to which it has delivered the message—for example, from each of the multiple subscribers to a topic.

If there are durable subscriptions to a topic, the Message Router retains each JMS message in that destination, delivering it as each durable subscriber becomes an active consumer.

The Message Router records client acknowledgments as they are received, and deletes the JMS message only after all the acknowledgments have been received, unless the JMS message expires before then.

Furthermore, the Message Router confirms receipt of the client acknowledgment by sending a broker response back to the client. The consuming client uses the broker response to make sure that the broker will not deliver a JMS message more than once. This could happen if the broker fails to receive the client acknowledgment.

If the broker does not receive a client acknowledgment and delivers a JMS message a second time, the message is marked with a Redeliver flag. The broker generally redelivers a JMS message under the following circumstances:

The client connection closes before the broker receives a client acknowledgment, and a new connection is subsequently opened.

The client application recovers a session.

The client application recovers a rolled back transaction.

For example, if a message consumer of a queue goes off line before acknowledging a message, and another consumer subsequently registers with the queue, the broker redelivers the unacknowledged message to the new consumer.

The client acknowledgments and broker responses described above apply, as well, to JMS message deliveries grouped into transactions. In such cases, these processes operate on the level of a transaction as well as on the level of individual JMS message sends or receives. When a transaction commits, a broker response is sent automatically.

The broker tracks transactions, allowing them to be committed or, if they fail, rolled back. This transaction management also supports local transactions that are part of larger, distributed transactions. The broker tracks the state of these transactions until they are committed. When a broker starts up, it inspects all uncommitted transactions, and by default, the broker rolls back all transactions except those in a PREPARED state. If you set the imq.transaction.autorollback property, the broker also rolls back transactions that are in a PREPARED state.

Reliable Delivery: Persistence

The other aspect of reliable delivery is assuring that the broker does not lose messages or delivery information before messages are actually delivered. In general, messages remain in memory until they have been delivered or they expire. However, if the broker fails, these messages are lost.

If a producer client specifies that a message is persistent, the Message Router passes the message to a Persistence Manager. The Persistence Manager stores the message in a database or file system (see Persistence Manager) so that the message can be recovered if the broker fails.

Managing Memory Resources and Message Flow

The performance and stability of a broker depends on the system resources available and how efficiently resources such as memory are utilized. In particular, the Message Router could become overwhelmed, using up all its memory resources, when production of messages is much faster than consumption. To prevent this from happening, the Message Router uses three levels of memory protection to keep the system operating as resources become scarce:

Message limits on individual destinations You can set physical destination properties that specify limits on the number of messages and the total memory consumed by messages (see Chapter 15, "Physical Destination Property Reference"). You can also specify the behavior of the Message Router when limits are reached. The four limit behaviors are:

Slowing message producers (FLOW_CONTROL)

Throwing out the oldest messages in memory (REMOVE_OLDEST)

Throwing out the lowest priority messages in memory, according to age of the messages (REMOVE_LOW_PRIORITY)

Rejecting the newest messages (REJECT_NEWEST)

System-wide message limits System-wide message limits constitute a second line of protection. You can specify system-wide limits that apply collectively to all destinations on the system: the total number of messages and the memory consumed by all messages (see Table 14-3). If any of the system-wide message limits are reached, the Message Router rejects new messages.

System memory thresholds System memory thresholds are a third line of protection. You can specify thresholds of available system memory at which the broker takes increasingly serious action to prevent memory overload. The action taken depends on the state of memory resources, as follows:

green (plenty of memory is available)

yellow (broker memory is running low)

orange (broker is low on memory)

red (broker is out of memory).

As the broker’s memory state progresses from green through yellow and orange to red, the broker takes increasingly serious actions of the following types:

Swapping messages out of active memory into persistent storage (see Persistence Manager).

Throttling back producers of non-persistent messages, eventually stopping the flow of messages into the broker. Persistent message flow is automatically limited by the requirement that the broker acknowledge each message.

If system memory thresholds are reached, destination message limits and system-wide message limits are too small. In some situations, the thresholds cannot catch all potential memory overloads in time. Therefore, do not rely on this feature to control memory resources, but instead configure destinations individually and collectively to optimize memory resources.

Message Router Properties

These are the system-wide limits and system memory thresholds for managing memory resources:

imq.destination.DMQ.truncateBody. Specifies that the dead message queue contains only a message’s header and property data. Message body contents are discarded.

imq.message.expiration.interval. Specifies how often reclamation of expired messages occurs, in seconds.

imq.system.max_count. Specifies the maximum number of messages held by the broker.

imq.system.max_size. Specifies the maximum total size of messages held by the broker.

imq.message.max_size. Specifies the maximum size of a message body.

imq.resource_state.threshold. Specifies the percent memory utilization at which each memory resource state is triggered.

imq.resource_state.count. Specifies the maximum number of incoming messages allowed in a batch as each memory resource state is triggered.

imq.transaction.autorollback. Specifies whether distributed transactions left in a PREPARED state are automatically rolled back when a broker starts up.

Persistence Manager

For a broker to recover, in case of failure, it needs to recreate the state of its message delivery operations. This requires it to save all persistent messages, as well as essential routing and delivery information, to a data store. A Persistence Manager component manages the writing and retrieval of this information.

To recover a failed broker requires more than simply restoring undelivered messages. The broker must also be able to do the following:

Re-create destinations

Restore the list of durable subscriptions for each topic

Restore the acknowledge list for each message

Reproduce the state of all committed transactions

The Persistence Manager manages the storage and retrieval of all this state information.

When a broker restarts, it recreates destinations and durable subscriptions, recovers persistent messages, restores the state of all transactions, and recreates its routing table for undelivered messages. It can then resume message delivery.

Message Queue supports both built-in and plugged-in persistence modules (see Figure 4-3). Built-in persistence is a file-based data store. Plugged-in persistence uses a Java Database Connectivity (JDBC™) interface and requires a JDBC data store. The built-in persistence is generally faster than plugged-in persistence; however, some users prefer the redundancy and administrative features of using a JDBC-compliant database system.

Built-in Persistence

The default Message Queue persistent storage solution is a file-based data store. This approach uses individual files to store persistent data, such as messages, destinations, durable subscriptions, and transactions.

The file-based data store is structured so that persistent messages are stored in a directory according to the destination in which they reside. Most messages are stored in a single file consisting of variable-sized records.

To alleviate fragmentation as messages are added and removed, you can compact the variable-sized record file (see Compacting Physical Destinations). In addition, built-in persistence manager stores messages whose size exceeds a configurable threshold (imq.persist.file.message.max_record_size) in their own respective files, rather than in the variable-sized record file. For these individual files, a file pool is maintained so that files can be reused. When a message file is no longer needed, it is not deleted. Instead, the message file is added to the pool of free files in its destination directory, to be used to store new messages.

You can configure the maximum number of files in the destination file pool (imq.persist.file.destination.message.filepool.limit). You can also specify the percentage of free files in the file pool that are cleaned up by being truncated to zero and not simply tagged for reuse (imq.persist.file.message.filepool.
cleanratio). As the percentage of cleaned files increases, the amount of disk space decreases and the overhead required to maintain the file pool increases.

You can specify whether or not tagged files will be cleaned up at shutdown (imq.persist.file.message.cleanup). If the files are cleaned up, they will take up less disk space, but the broker will take longer to shut down.

All other persistent data (destinations, durable subscriptions, and transactions) are stored in separate files. All destinations are in one file, all durable subscriptions are in another file, and so on.

To maximize reliability, you can use the imq.persist.file.sync.enabled attribute to specify that persistence operations should synchronize the in-memory state with the physical storage device. This helps eliminate data loss due to system crashes, but at the expense of performance. If you are running Message Queue in a Sun Cluster environment, you must set this attribute to true for all nodes in the cluster.

Because the data store can contain messages of a sensitive or proprietary nature, you should secure the instances/instanceName/fs350/ directory against unauthorized access. For instructions, see Securing Persistent Data.

Plugged-In Persistence

You can set up a broker to access any data store accessible through a JDBC driver. This involves setting a number of JDBC-related broker configuration properties and using the database manager utility (imqdbmgr) to create a data store with the proper schema. The procedures and related configuration properties are detailed in Setting Up a Persistent Store.

Persistence Manager Properties

imq.persist.store. Specifies whether the broker is using built-in, file-based (file) persistence or plugged-in JDBC-compliant (jdbc) persistence.

imq.persist.file.sync.enabled. Specifies whether persistence operations synchronize in-memory state with the physical storage device.

imq.persist.file.message.max_record_size. Specifies the maximum size of messages that will be added to the message storage file.

imq.persist.file.destination.message.filepool.limit. Specifies the maximum number of free files available for reuse in the destination file pool.

imq.persist.file.message. filepool.cleanratio. Specifies the percentage of free files in destination file pools that are maintained in a clean state (truncated to zero).

imq.persist.file.message.cleanup. Specifies whether or not the broker cleans up free files in destination file pools when it shuts down.

imq.persist.jdbc.brokerid. Specifies a broker instance identifier to append to the names of tables in a database used by multiple broker instances.

imq.persist.jdbc.driver. Specifies the java class name of the JDBC driver to connect to the database.

imq.persist.jdbc.opendburl. Specifies the database URL for opening a connection to an existing database.

imq.persist.jdbc.createdburl. Specifies the database URL for opening a connection to create a database.

imq.persist.jdbc.closedburl. Specifies the database URL for shutting down the current database connection when the broker is shut down.

imq.persist.jdbc.user. Specifies the user name used to open a database connection, if required.

imq.persist.jdbc.needpassword. Specifies whether the database requires a password for broker access.

imq.persist.jdbc.password. Specifies the password for use in opening a database connection, if required.

imq.persist.jdbc.table.IMQSV35. SQL command used to create the version table.

imq.persist.jdbc.table.IMQCCREC35. SQL command used to create the configuration change record table.

imq.persist.jdbc.table.IMQDEST35. SQL command used to create the destination table.

imq.persist.jdbc.table.IMQINT35. SQL command used to create the interest table.

imq.persist.jdbc.table.IMQMSG35. SQL command used to create the message table.

imq.persist.jdbc.table.IMQPROPS35. SQL command used to create the property table.

imq.persist.jdbc.table.IMQILIST35. SQL command used to create the interest state table.

imq.persist.jdbc.table.IMQTXN35. SQL command used to create the transaction table.

imq.persist.jdbc.table.IMQTACK35. SQL command used to create the transaction acknowledgment table.

Security Manager

Message Queue provides authentication and authorization (access control) features, and also supports encryption capabilities.

The authentication and authorization features depend upon a user repository (see Figure 4-4): a file, directory, or database that contains information about the users of the messaging system—their names, passwords, and group memberships. The names and passwords are used to authenticate a user when a connection to a broker is requested. The user names and group memberships are used, in conjunction with an access control file, to authorize operations such as producing or consuming messages for destinations.

Authentication

Message Queue security supports password-based authentication. When a client requests a connection to a broker, the client must submit a user name and password.

The Security Manager compares the name and password submitted by the client to those stored in the user repository. On transmitting the password from client to broker, the passwords are encoded using either base 64 encoding or message digest (MD5). For more secure transmission, see Encryption. You can separately configure the type of encoding used by each connection service or set the encoding on a broker-wide basis.

Authorization

Once the user of a client application has been authenticated, the user can be authorized to perform various Message Queue-related activities. The Security Manager supports both user-based and group-based access control. Depending on a user’s name or the groups to which the user is assigned in the user repository, that user has permission to perform certain Message Queue operations. You specify these access controls in an access control properties file (see Figure 4-4).

When a user attempts to perform an operation, the Security Manager checks the user’s name and group membership from the user repository against those specified for access to that operation in the access control properties file. The access control properties file specifies permissions for the following operations:

Establishing a connection with a broker

Accessing destinations: creating a consumer, a producer, or a queue browser for any given destination or all destinations

Auto-creating destinations

Figure 4-4 Security Manager Support
Diagram showing that the security manager uses both a user repository and an access control properties file.

The default access control properties file explicitly references only one group: admin (see Groups). A user in the admin group has admin service connection permission. The admin service lets the user perform administrative functions such as creating destinations, and monitoring and controlling a broker. A user in any other group that you define cannot, by default, get an admin service connection.

As a Message Queue administrator you can define groups and associate users with those groups in a user repository (though groups are not fully supported in the flat-file user repository).

By editing the access control properties file, you can specify access to destinations by users and groups for the purpose of producing and consuming messages, or browsing messages in queue destinations. You can make individual destinations or all destinations accessible only to specific users or groups. If the broker is configured to allow auto-creation of destinations, you can edit the access control properties file to control the users and groups for whom the broker can auto-create destinations.

Encryption

To encrypt messages sent between clients and broker, you need to use a connection service based on the Secure Socket Layer (SSL) standard. SSL provides security at a connection level by establishing an encrypted connection between an SSL-enabled broker and an SSL-enabled client.

To use a Message Queue SSL-based connection service, you generate a private key/public key pair using the Key Tool utility (imqkeytool). This utility embeds the public key in a self-signed certificate and places it in a Message Queue keystore. The Message Queue keystore is, itself, password protected; to unlock it, you must provide a keystore password at startup time. See Working With an SSL-Based Service.

Once the keystore is unlocked, a broker can pass the certificate to any client requesting a connection. The client then uses the certificate to set up an encrypted connection to the broker.

All Security Manager properties are listed in the next section and described in detail under Security Manager Properties.

Security Manager Properties

These are the configurable properties for authentication, authorization, encryption, and other secure communications:

imq.authentication.type. Specifies whether the password should be passed in base 64 coding (basic) or as an MD5 digest (digest).

imq.service_name. authentication.type. Specifies whether the password should be passed in base 64 coding (basic) or as an MD5 digest (digest).

imq.authentication.basic.user_repository. For base 64 coding, specifies the type of user repository used for authentication, either file-based or LDAP.

imq.authentication.client.response.timeout. Specifies the time (in seconds) the system will wait for a client to respond to an authentication request from the broker.

imq.accesscontrol.enabled. Indicates whether the system will check whether an authenticated user has permission to use a connection service or to perform specific Message Queue operations with respect to specific destinations, as specified in the access control properties file.

imq.service_name.accesscontrol.enabled. Sets access control (true/false) for the named connection service, overriding the broker-wide setting.

imq.accesscontrol.file.filename. Specifies the name of an access control properties file for all connection services supported by a broker instance.

imq.service_name.accesscontrol.file.filename. Specifies the name of an access control properties file for a named connection service of a broker instance.

imq.passfile.enabled. Specifies whether user passwords (for SSL, LDAP, JDBC™) for secure communications are specified in a file.

imq.passfile.dirpath. Specifies the path to the directory containing the passfile.

imq.passfile.name. Specifies the name of the passfile.

imq.keystore.property_name. For SSL-based services: specifies security properties relating to the SSL keystore. See Table 14-9.

Monitoring Service

The broker includes a number of components for monitoring and diagnosing its operation. Among these are the following:

Components that generate data (broker code that logs events and a metrics generator)

A logger component (see Logger) that writes out information through a number of output channels

A message producer that sends JMS messages containing metrics information to topic destinations for consumption by JMS monitoring clients.

Metrics Generator

The metrics generator provides information about broker activity, such as message flow in and out of the broker, the number of messages in broker memory and the memory they consume, the number of connections open, and the number of threads being used.

You can turn the generation of metrics data on and off, and specify how frequently metrics reports are generated.

Logger

The Message Queue logger takes information generated by broker code and a metrics generator and writes that information to a number of output channels: to standard output (the console), to a log file, and, on the Solaris™ operating system, to the syslog daemon process.

You can specify the type of information gathered by the logger as well as the type written to each of the output channels.

For example, you can specify the logger level to determine the type of information that the logger gathers: errors (ERROR); errors and warnings (WARNING); or errors, warnings, and information (INFO).

For each output channel, you can specify which of the categories set for the logger will be written to that channel. For example, if the logger level is set to INFO, you can specify that you want only errors and warnings written to the console, and only info (metrics data) written to the log file.

If you are using a log file, you can specify the point at which the log file is closed and output is rolled over to a new file. An archive of the nine most recent log files is retained as new rollover log files are created.

For information on configuring the logger, see Configuring and Using Broker Logging. For information on configuring and using the Solaris syslog, see the syslog(1M), syslog.conf(4) and syslog(3C) man pages.

Metrics Message Producer (Enterprise Edition)

The Message Producer component receives information from the Metrics Generator component at regular intervals. It writes the information into messages, which it then sends to metric topic destinations. The destination to which a metrics message is sent depends on the type of information it contains.

There are five metrics topic destinations, whose names are shown in Table 4-3, along with the type of metrics messages delivered to each destination.

Table 4-3 Metrics Topic Destinations
Topic Destination Name	Type of Metrics Messages
mq.metrics.broker	Broker metrics
mq.metrics.jvm	Java Virtual Machine metrics
mq.metrics.destination_list	List of destinations and their types
mq.metrics.destination.queue. monitoredDestinationName	Destination metrics for queue of specified name
mq.metrics.destination.topic. monitoredDestinationName	Destination metrics for topic of specified name

Message Queue clients that subscribe to these metric topic destinations consume the messages in the destinations and process the metrics information. For example, a client can subscribe to the mq.metrics.broker destination to receive and process information such as the total number of messages in the broker.

The Metrics Message Producer is an internal Message Queue client that creates messages (of type MapMessage) that contain name-value pairs corresponding to metrics data. These messages are produced only if there are one or more subscribers to the corresponding metrics topic destination.

The messages produced by the Metrics Message Producer are of type MapMessage. They consist of a number of name/value pairs, depending on the type of metrics they contain. Each name/value pair corresponds to a metric quantity and its value.

As an example, broker metrics messages contain values for the number of messages that have flowed into and out of the broker, the size of these messages, the number and size of messages currently in memory, and so forth. For details of the metrics quantities reported in each type of metrics message, see the Message Queue Developer’s Guide for Java Clients. That manual explains how to write a Message Queue client for consuming metrics messages.

In addition to the metrics information contained in the body of a metrics message, the header of each message has properties that provide the following information:

Message type

Host, port, and address of the broker that sent the message

Time that the metric sample was taken

These properties are useful to Message Queue client applications that process metric messages of different types or from different brokers.

Monitoring Service Properties

These are the configurable properties for setting the generation, logging, and metrics message production of information by the broker:

imq.metrics.enabled. Specifies whether metrics information is being written to the logger.

imq.metrics.interval. If metrics logging is enabled, specifies the time interval, in seconds, at which metrics information is written to the logger.

imq.log.level. Specifies the logger level: the categories of output that can be written to an output channel.

imq.log.file.output. Specifies which categories of logging information are written to the log file.

imq.log.file.dirpath. Specifies the path to the directory containing the log file.

imq.log.file.filename. Specifies the name of the log file.

imq.log.file.rolloverbytes. Specifies the size, in bytes, of the log file at which output rolls over to a new log file.

imq.log.file.rolloversecs. Specifies the age, in seconds, of log file at which output rolls over to a new log file.

imq.log.console.output. Specifies which categories of logging information are written to the console.

imq.log.console.stream. Specifies whether console output is written to stdout (OUT) or stderr (ERR).

imq.log.syslog.facility. (Solaris only) Specifies what syslog facility the Message Queue broker should log as.

imq.log.syslog.logpid. (Solaris only) Specifies whether to log the broker process ID with the message.

imq.log.syslog.logconsole. (Solaris only) Specifies whether to write messages to the system console if they cannot be sent to syslog.

imq.log.syslog.identity. (Solaris only) Specifies the identity string that should be prepended to every message logged to syslog.

imq.log.syslog.output. (Solaris only) Specifies which categories of logging information are written to syslogd(1M).

imq.log.timezone. Specifies the time zone for log time stamps.

imq.metrics.topic.enabled. Specifies whether metrics message production is enabled.

imq.metrics.topic.interval. Specifies the time interval, in seconds, at which metrics messages are produced.

imq.metrics.topic.persist. Specifies whether or not metrics messages are persistent.

imq.metrics.topic.timetolive. Specifies the lifetime, in seconds, of metrics messages sent to metric topic destinations.

imq.destination.logDeadMsgs. Specifies whether the broker writes a message to the log each time it discards a dead message or puts a dead message on the dead message queue.

About Configuration Files

A default configuration file that is loaded on startup. This file is called default.properties and is not editable. You can read this file to determine default settings and find the exact names of properties you want to change.

An installation configuration file that contains any properties specified when Message Queue is installed. This file is called install.properties; it cannot be edited after installation.

Instance Configuration File

The first time you run a broker, an instance configuration file is created. Use the instance configuration file to specify configuration properties for that instance of the broker.

The instance configuration file is stored in a directory that is identified by the name of the broker instance (instanceName) with which the configuration file is associated:


Note	The …/instances/instanceName directory and the instance configuration file are owned by the user who created the corresponding broker instance. The broker instance must always be restarted by that same user.

The instance configuration file is maintained by the broker instance. It is modified when you make configuration changes using administration tools. You can also edit an instance configuration file by hand to make configuration changes (see Editing the Instance Configuration File). To do so, you must be the owner of the …/instances/instanceName directory or log in as root to change privileges on the directory.

If you connect broker instances in a cluster, you may also need to use a cluster configuration file to specify cluster configuration information. For more information, see Cluster Configuration Properties.

Merging Property Values

At startup, the broker merges property values in the different configuration files. It uses values in the installation and instance configuration files to override values specified in the default configuration file.

You can override the resulting values by using imqbrokerd command options. This scheme is illustrated in Figure 4-6.

Property Naming Syntax

Any Message Queue property definition in a configuration file uses the following naming syntax:

For example, the following entry specifies that the broker will hold up to 50,000 messages in memory and persistent storage before rejecting additional messages:

The following entry specifies that a new log file will be created every day (86400 seconds):

Editing the Instance Configuration File

The first time a broker instance is run, a config.properties file is automatically created. You can edit this instance configuration file to customize the behavior and resource use of the corresponding broker instance.

The broker instance reads the config.properties file only at startup. To make permanent changes to the config.properties file, you can do one of the following:

Use administration tools. For information about properties you can set using imqcmd, see Table 14-1.

Edit the config.properties file while the broker instance is shut down; then restart the instance. (On Solaris and Linux operating systems, only the user that first started the broker instance has permission to edit the config.properties file.)

Table 14-1 lists the broker instance configuration properties in alphabetical order, with their default values. For more information about the meaning and use of each property, please consult the specified cross-referenced section.

Entering Configuration Options on the Command Line

You can enter broker configuration options on the command line when you start a broker, or afterward.

At startup time, you use the imqbrokerd command to start a broker instance. Using the command’s -D option, you can specify any broker configuration property and its value. If you start the broker as a Windows service, using the imqsvcadmin command, you use the -args option to specify startup configuration properties.

You can also set certain broker properties when a broker instance is running. To modify the configuration of a running broker, you use the imqcmd update bkr command.

Setting Up a Persistent Store

Message Queue brokers include a Persistence Manager component that manages the writing and retrieval of persistent information. The Persistence Manager is configured by default to access a built-in, file-based data store, but you can reconfigure it to plug in any data store accessible through a JDBC-compliant driver.

The Message Queue data store contains information about transactions, messages, durable subscriptions, and physical destinations. It also contains information about the state of messages with respect to acknowledgments.

This chapter explains how to set up a broker to use a persistent store. It includes the following topics:

Configuring a File System Store

Configuring a JDBC Store

Securing Persistent Data

Configuring a File System Store

A file system data store is automatically created when you create a broker instance. The store is located under the instance directory for that broker. The location is operating system-specific; for the exact location of the persistent store, see Appendix A, "Operating System-Specific Locations of Message Queue Data."

By default, Message Queue performs non-synchronous write operations to disk. The operating system can buffer these operations to provide for good performance. However, if an unexpected system failure occurs between write operations, messages could be lost. To improve reliability, you can cause Message Queue to perform synchronous writes to disk, but be aware that this option causes reduced performance. To specify synchronous writes to disk, set the broker property imq.persist.file.sync. For details about this property, see Table 14-6.

When you start a broker instance, you can use the imqbrokerd -reset option to clear the file system store. For more information about this option and its suboptions, see Table 13-2

Configuring a JDBC Store

To configure a broker to use JDBC-based persistence, you set JDBC-related properties in the broker instance configuration file and create the appropriate database schema. The Message Queue Database Manager utility (imqdbmgr) uses your JDBC driver and the broker configuration properties to create and manage the database.

The procedure described in this chapter is illustrated using, as an example, the PointBase DBMS bundled with the Java 2 Platform, Enterprise Edition (J2EE) SDK. Version 1.4 is available for download from java.sun.com. The example uses PointBase's embedded version (instead of the client/server version). In the procedures, instructions are illustrated using path names and property names from the PointBase example. They are identified by the word “Example:”

Example configurations for Oracle and PointBase are available. To find the example files, see Appendix A, "Operating System-Specific Locations of Message Queue Data." In the table that lists information for your operating system, look for the location of “Example applications and configurations.”

In addition, examples for PointBase embedded version, PointBase server version, and Oracle are provided as commented-out values in the instance configuration file, config.properties.

Plugging In a JDBC-Accessible Data Store

To Plug in a JDBC-Accessible Data Store

Set JDBC-related properties in the broker’s configuration file.

See the properties documented in JDBC-Based Persistence

Place a copy or a symbolic link to your JDBC driver jar file located in the following path:

/usr/share/lib/imq/ext/ (Solaris)

/opt/sun/mq/share/lib/ (Linux)

IMQ_VARHOME\lib\ext (Windows)

Copy Example (Solaris):

% cp j2eeSDK_install_directory/pointbase/lib/pointbase.jar /usr/share/lib/imq/ext

Symbolic Link Example (Solaris):

% ln -s j2eeSDK_install_directory/lib/pointbase/pointbase.jar /usr/share/lib/imq/ext

Create the database schema needed for Message Queue persistence.

Use the imqdbmgr create all command (for an embedded database) or the imqdbmgr create tbl command (for an external database). See Database Manager Utility (imqdbmgr).

Example:

Change to directory where imqdbmgr resides.

cd /usr/bin (Solaris)

cd /opt/sun/mq/bin (Linux)

cd IMQ_HOME/bin (Windows)

Enter the imqdbmgr command.

imqdbmgr create all



Note	If you use an embedded database, it is best to create it under the following directory: …/instances/instanceName/dbstore/dabatabseName. If an embedded database is not protected by a user name and password, it is probably protected by file system permissions. To ensure that the database is readable and writable by the broker, the user who runs the broker should be the same user who created the embedded database using the imqdbmgr command (see Database Manager Utility (imqdbmgr)).

JDBC-Related Broker Properties

If the file does not yet exist, you must start the broker by using the -name instanceName option, so that Message Queue can create the file.

JDBC-Based Persistence presents the configuration properties that you need to set when plugging in a JDBC- accessible data store. There is a summary of these properties at the end of this section. You set these properties in the instance configuration file (config.properties) of each broker instance that uses plugged-in persistence.

The instance configuration properties enable you to customize the SQL code that creates the Message Queue database schema: there is a configurable property that specifies the SQL code that creates each database table. These properties are needed to properly specify the data types used by the plugged-in database.

Since there are incompatibilities between database vendors with respect to the exact SQL syntax, be sure to check the corresponding documentation from your database vendor and adjust the properties in Table 14-7 accordingly. For example, for the PointBase database, you may need to adjust the maximum length allowed for the MSG column (see the imq.persist.jdbc.table.IMQMSG35 property) in the IMQMSG35 table.

As with all broker configuration properties, values can be set using the -D command line option. If a database requires certain database specific properties to be set, these also can be set using the -D command line option when starting the broker (imqbrokerd) or the Database Manager utility (imqdbmgr).

For the PointBase embedded database example, instead of specifying the absolute path of a database in database connection URLs, you can use the -D command line option to define the PointBase system directory:

imq.persist.store. Specifies a file-based or JDBC-based data store.

imq.persist.jdbc.brokerid. Specifies a broker instance identifier that is appended to database table names to make them unique.