This chapter provides reference information on the use of the Message Queue command line administration utilities. It consists of the following sections:
Message Queue command line utilities are shell commands. The name of the utility is a command and its subcommands or options are arguments passed to that command. There is no need for separate commands to start or quit the utility.
All the command line utilities share the following command syntax:
utilityName [subcommand] [commandArgument] [ [-optionName [optionArgument] ] … ]
where utilityName is one of the following:
imqbrokerd (Broker utility)
imqcmd (Command utility)
imqobjmgr (Object Manager utility)
imqdbmgr (Database Manager utility)
imqusermgr (User Manager utility)
imqbridgemgr (Bridge Manager utility)
imqsvcadmin (Service Administrator utility)
imqkeytool (Key Tool utility)
Subcommands and command-level arguments, if any, must precede all options and their arguments; the options themselves may appear in any order. All subcommands, command arguments, options, and option arguments are separated with spaces. If the value of an option argument contains a space, the entire value must be enclosed in quotation marks. (It is generally safest to enclose any attribute-value pair in quotation marks.)
The following command, which starts the default broker, is an example of a command line with no subcommand clause:
imqbrokerd
Here is a fuller example:
imqcmd destroy dst -t q -n myQueue -u admin -f -s
This command destroys a queue destination (destination type q) named myQueue. Authentication is performed on the user name admin; the command will prompt for a password. The command will be performed without prompting for confirmation (-f option) and in silent mode, without displaying any output (-s option).
The Broker utility (imqbrokerd) starts a broker. Command line options override values in the broker configuration files, but only for the current broker session.
Table 16–1 shows the options to the imqbrokerd command and the configuration properties, if any, overridden by each option.
Table 16–1 Broker Utility Options
Option |
Properties Overridden |
Description |
---|---|---|
-name instanceName |
imq.instancename |
Multiple broker instances running on the same host must have different instance names. Default value: imqbroker |
-port portNumber |
imq.portmapper.port |
Port number for broker’s Port Mapper Message Queue clients use this port number to connect to the broker. Multiple broker instances running on the same host must have different Port Mapper port numbers. Default value: 7676 |
-cluster broker1 [ [ ,broker2 ] … ] |
imq.cluster.brokerlist |
Connect brokers into cluster [Applies only to broker clusters] The specified brokers are merged with the list in the imq.cluster.brokerlist property. Each broker argument has one of the forms hostName:portNumber hostName :portNumber If hostName is omitted, the default value is localhost; if portNumber is omitted, the default value is 7676. |
-Dproperty=value |
Corresponding property in instance configuration file |
Set configuration property See Chapter 17, Broker Properties Reference for information about broker configuration properties. Caution: Be careful to check the spelling and formatting of properties set with this option. Incorrect values will be ignored without notification or warning. |
-reset props |
None |
Reset configuration properties Replaces the broker’s existing instance configuration file config.properties with an empty file; all properties assume their default values. |
-reset store |
None |
Clears all persistent data from the data store (including persistent messages, durable subscriptions, and transaction information), allowing you to start the broker instance with a clean slate. To prevent the persistent store from being reset on subsequent restarts, restart the broker instance without the -reset option. To clear only persistent messages or durable subscriptions, use -reset messages or -reset durables instead. |
-reset messages |
None |
Clear persistent messages from data store |
-reset durables |
None |
Clear durable subscriptions from data store |
-backup fileName |
None |
Back up configuration change record to file See Managing a Conventional Cluster's Configuration Change Record for more information. |
-restore fileName |
None |
Restore configuration change record from backup file The backup file must have been previously created using the -backup option. See Managing a Conventional Cluster's Configuration Change Record for more information. |
-remove instance |
None |
Remove broker instance [Requires user confirmation unless -force is also specified] Deletes the instance configuration file, log files, persistent store, and other files and directories associated with the instance. |
-dbuser userName |
imq.persist.jdbc.user |
User name for JDBC-based persistent data store |
-passfile filePath |
imq.passfile.enabledimq.passfile.dirpathimq.passfile.name |
Sets the broker’s imq.passfile.enabled property to true, imq.passfile.dirpath to the path containing the password file, and imq.passfile.name to the file name itself. See Password Files for more information. |
-shared |
imq.jms.threadpool_model |
Use shared thread pool model to implement jms connection service Execution threads will be shared among connections to increase the number of connections supported. Sets the broker’s imq.jms.threadpool_model property to shared. |
-javahome path |
None |
Location of alternative Java runtime Default behavior: Use runtime installed on system or bundled with Message Queue. |
-vmargs arg1 [ [ arg2 ] … ] |
None |
Pass arguments to Java virtual machine Arguments are separated with spaces. To pass more than one argument, or an argument containing a space, enclose the argument list in quotation marks. VM arguments can be passed only from the command line; there is no associated configuration property in the instance configuration file. |
-startRmiRegistry |
imq.jmx.rmiregistry.start |
Start RMI registry at broker startup |
-useRmiRegistry |
imq.jmx.rmiregistry.use |
Use external RMI registry |
-rmiRegistryPort |
imq.jmx.rmiregistry.port |
Port number of RMI registry |
-upgrade-store-nobackup |
None |
Automatically remove old data store on upgrade to Message Queue 3.5 or 3.5 SPx from an incompatible version See the Message Queue Installation Guide for more information. |
-force |
None |
Perform action without user confirmation This option applies only to the -remove instance and -upgrade-store-nobackup options, which normally require confirmation. |
-loglevel level |
imq.broker.log.level |
NONE ERROR WARNING INFO Default value: INFO |
-metrics interval |
imq.metrics.interval | |
-tty |
imq.log.console.output |
Log all messages to console Sets the broker’s imq.log.console.output property to ALL. If not specified, only error and warning messages will be logged. |
-s | -silent |
imq.log.console.output |
Silent mode (no logging to console) Sets the broker’s imq.log.console.output property to NONE. |
-version |
None |
Display version information [Any other options specified on the command line are ignored. ] |
-h | -help |
None |
Display usage help |
The Command utility (imqcmd) is used for managing brokers, connection services, connections, physical destinations, durable subscriptions, and transactions.
All imqcmd commands must include a subcommand (except those using the -v or -h option to display product version information or usage help, respectively). The possible subcommands are listed in Table 16–2 and described in detail in the corresponding sections below. In addition, each imqcmd subcommand supports the general options shown in General Command Utility Options.
The -u userName option (and corresponding password) is required except when using the -v or -h option. Also if a subcommand accepts a broker address (-b option) and no host name or port number is specified, the values localhost and 7676 are assumed by default.
shutdown bkr |
Shut down broker |
restart bkr |
Restart broker |
pause bkr |
Pause broker |
quiesce bkr |
Quiesce broker |
unquiesce bkr |
Unquiesce broker |
resume bkr |
Resume broker |
takeover bkr |
Initiate broker takeover |
update bkr |
Set broker properties |
reload cls |
Reload cluster configuration |
query bkr |
List broker property values |
list bkr |
List brokers in cluster |
metrics bkr |
Display broker metrics |
pause svc |
Pause connection service |
resume svc |
Resume connection service |
update svc |
Set connection service properties |
list svc |
List connection services available on broker |
query svc |
List connection service property values |
metrics svc |
Display connection service metrics |
list cxn |
List connections on broker |
query cxn |
Display connection information |
destroy cxn |
Destroy connection |
create dst |
Create physical destination |
destroy dst |
Destroy physical destination |
pause dst |
Pause message delivery for physical destination |
resume dst |
Resume message delivery for physical destination |
purge dst |
Purge all messages from physical destination |
compact dst |
Compact physical destination |
update dst |
Set physical destination properties |
list dst |
List physical destinations |
query dst |
List physical destination property values |
metrics dst |
Display physical destination metrics |
destroy dur |
Destroy durable subscription |
purge dur |
Purge all messages for durable subscription |
list dur |
List durable subscriptions for topics |
commit txn |
Commit transaction |
rollback txn |
Roll back transaction |
list txn |
List transactions being tracked by broker |
query txn |
Display transaction information |
list dur |
List durable subscriptions for topic |
list jmx |
List JMX service URLs of JMX connectors |
The additional options listed in Table 16–3 can be applied to any subcommand of the imqcmd command.
Table 16–3 General Command Utility Options
Option |
Description |
---|---|
-secure |
Use secure connection to broker with ssladmin connection service |
-u userName |
User name for authentication If this option is omitted, the Command utility will prompt for it interactively. |
-passfile path |
Location of password file See Password Files for more information. |
-D |
Set connection-related system property that affects how imqcomd creates a connection to the broker. Not used to set broker configuration properties. Usually overrides connection factory attributes for imqcmd client runtime. For example, the option in the following command changes the default value of imqSSLIsTrusted: imqcmd list svc -secure -DimqSSLIsTrusted=true |
-rtm timeoutInterval |
Initial timeout interval, in seconds This is the initial length of time that the Command utility will wait for a reply from the broker before retrying a request. Each subsequent retry will use a timeout interval that is a multiple of this initial interval. Default value: 10. |
-rtr numRetries |
Number of retries to attempt after a broker request times out Default value: 5. |
-javahome path |
Location of alternative Java runtime Default behavior: Use runtime installed on system or bundled with Message Queue. |
-f |
Perform action without user confirmation |
-s |
Silent mode (no output displayed) |
-v |
Display version information [Any other options specified on the command line are ignored. ] , [User name and password not needed] |
-h | |
-H |
Display expanded usage help, including attribute list and examples, |
The Command utility cannot be used to start a broker; use the Broker utility (imqbrokerd) instead. Once the broker is started, you can use the imqcmd subcommands listed in Table 16–4 to manage and control it.
Table 16–4 Command Utility Subcommands for Broker Management
Syntax |
Description |
---|---|
shutdown bkr [-b hostName:portNumber] [-time nSeconds] [-nofailover] |
The -time option specifies the interval, in seconds, to wait before shutting down the broker. (The broker will not block, but will return immediately from the delayed shutdown request.) During the shutdown interval, the broker will not accept any new jms connections; admin connections will be accepted, and existing jms connections will continue to operate. A broker belonging to an enhanced cluster will not attempt to take over for any other broker during the shutdown interval. The -nofailover option indicates that no other broker is to take over the persistent data of the one being shut down. [Applies only to broker clusters] |
restart bkr [-b hostName:portNumber] |
Shuts down the broker and then restarts it using the same options specified when it was originally started. |
pause bkr [-b hostName:portNumber] |
See Pausing and Resuming a Broker for more information. |
quiesce bkr [-b hostName:portNumber] |
The broker will stop accepting new connections; existing connections will continue to operate. |
unquiesce bkr [-b hostName:portNumber] |
The broker will resume accepting new connections, returning to normal operation. |
resume bkr [-b hostName:portNumber] | |
takeover bkr -n brokerID [-f] |
Before taking over a broker, you should first shut it down manually using the shutdown bkr subcommand with the -nofailover option. If the specified broker appears to be still running, takeover bkr will display a confirmation message (Do you want to take over for this broker?). The -f option suppresses this message and initiates the takeover unconditionally. Note – The takeover bkr subcommand is intended only for use in failed-takeover situations. You should use it only as a last resort, and not as a general way of forcibly taking over a running broker. |
update bkr [-b hostName:portNumber] -o property1=value1 [ [-o property2=value2] … ] |
See Chapter 17, Broker Properties Reference for information on broker properties. |
reload cls |
Forces all persistent information to be brought up to date. |
query bkr -b hostName:portNumber |
For brokers belonging to a cluster, also lists cluster properties such as broker list, master broker (for conventional clusters), and cluster identifier (for enhanced clusters). |
list bkr | |
metrics bkr [-b hostName:portNumber] [-m metricType] [-int interval] [-msp numSamples] |
The -m option specifies the type of metrics to display: ttl: Messages and packets flowing into and out of the broker rts: Rate of flow of messages and packets into and out of the broker per second cxn: Connections, virtual memory heap, and threads Default value: ttl. The -int option specifies the interval, in seconds, at which to display metrics. Default value: 5. The -msp option specifies the number of samples to display. Default value: Unlimited (infinite). |
Table 16–5 lists the imqcmd subcommands for managing connection services.
Table 16–5 Command Utility Subcommands for Connection Service Management
Syntax |
Description |
---|---|
pause svc -n serviceName [-b hostName:portNumber] |
The admin connection service cannot be paused. |
resume svc -n serviceName [-b hostName:portNumber] | |
update svc -n serviceName [-b hostName:portNumber] -o property1=value1 [ [-o property2=value2] … ] |
Set connection service properties See Connection Properties for information on connection service properties. |
list svc [-b hostName:portNumber] | |
query svc -n serviceName [-b hostName:portNumber] | |
metrics svc -n serviceName [-b hostName:portNumber] [-m metricType] [-int interval] [-msp numSamples] |
Display connection service metrics The -m option specifies the type of metrics to display: ttl: Messages and packets flowing into and out of the broker by way of the specified connection service rts: Rate of flow of messages and packets into and out of the broker per second by way of the specified connection service cxn: Connections, virtual memory heap, and threads Default value: ttl. The -int option specifies the interval, in seconds, at which to display metrics. Default value: 5. The -msp option specifies the number of samples to display. Default value: Unlimited (infinite). |
Table 16–6 lists the imqcmd subcommands for managing connections.
Table 16–6 Command Utility Subcommands for Connection Service Management
Table 16–7 lists the imqcmd subcommands for managing physical destinations. In all cases, the -t (destination type) option can take either of two values:
q: Queue destination
t: Topic destination
Syntax |
Description |
---|---|
create dst -t destType -n destName [ [-o property=value] … ] |
Create physical destination [Cannot be performed in a broker cluster whose master broker is temporarily unavailable] The destination name destName may contain only alphanumeric characters (no spaces) and must begin with an alphabetic character or the underscore (_) or dollar sign ($) character. It may not begin with the characters mq. |
destroy dst -tdestType -n destName |
This operation cannot be applied to a system-created destination, such as a dead message queue. |
pause dst [-t destType -n destName] [-pst pauseType] |
Pause message delivery for physical destination Pauses message delivery for the physical destination specified by the -t and -n options. If these options are not specified, all destinations are paused. The -pst option specifies the type of message delivery to be paused: PRODUCERS: Pause delivery from message producers CONSUMERS: Pause delivery to message consumers ALL: Pause all message delivery Default value: ALL |
resume dst [-t destType -n destName] |
Resume message delivery for physical destination Resumes message delivery for the physical destination specified by the -t and -n options. If these options are not specified, all destinations are resumed. |
purge dst -t destType -n destName | |
compact dst [-t destType -n destName] |
Compacts the file-based persistent data store for the physical destination specified by the -t and -n options. If these options are not specified, all destinations are compacted. A destination must be paused before it can be compacted. |
update dst -t destType -n destName -o property1=value1 [ [ -o property2=value2] … ] |
Set physical destination properties See Chapter 18, Physical Destination Property Reference for information on physical destination properties. |
list dst [-t destType] [-tmp] |
Lists all physical destinations of the type specified by the -t option. If no destination type is specified, both queue and topic destinations are listed. If the -tmp option is specified, temporary destinations are listed as well. |
query dst -t destType -n destName | |
metrics dst -t destType -n destName [-m metricType] [-int interval] [-msp numSamples] |
Display physical destination metrics The -m option specifies the type of metrics to display: ttl: Messages and packets flowing into and out of the destination and residing in memory rts: Rate of flow of messages and packets into and out of the destination per second, along with other rate information con: Metrics related to message consumers dsk: Disk usage Default value: ttl. The -int option specifies the interval, in seconds, at which to display metrics. Default value: 5. The -msp option specifies the number of samples to display. Default value: Unlimited (infinite). |
Table 16–8 lists the imqcmd subcommands for managing durable subscriptions.
Table 16–8 Command Utility Subcommands for Durable Subscription Management
Table 16–9 lists the imqcmd subcommands for managing local (non-distributed) Message Queue transactions. Distributed transactions are managed by a distributed transaction manager rather than imqcmd.
Table 16–9 Command Utility Subcommands for Transaction Management
Syntax |
Description |
---|---|
commit txn -n transactionID |
Commit transaction |
rollback txn -n transactionID |
Roll back transaction |
list txn |
List transactions being tracked by broker |
query txn -n transactionID |
The imqcmd subcommand shown in Table 16–10 is used for administrative support of Java applications using the Java Management Extensions (JMX) application programming interface to configure and monitor Message Queue resources. See Appendix D, JMX Support for further information on the broker's JMX support.
Table 16–10 Command Utility Subcommand for JMX Management
Syntax |
Description |
---|---|
list jmx |
The Object Manager utility (imqobjmgr) creates and manages Message Queue administered objects. Table 16–11 lists the available subcommands.
Table 16–11 Object Manager Subcommands
Subcommand |
Description |
---|---|
add |
Add administered object to object store |
delete |
Delete administered object from object store |
list |
List administered objects in object store |
query |
Display administered object information |
update |
Modify administered object |
Table 16–12 lists the options to the imqobjmgr command.
Table 16–12 Object Manager Options
Option |
Description |
---|---|
-l lookupName |
JNDI lookup name of administered object |
-j attribute=value |
Attributes of JNDI object store (see Object Stores) |
-t objectType |
Type of administered object: q: Queue destination t: Topic destination cf: Connection factory qf: Queue connection factory tf: Topic connection factory xcf: Connection factory for distributed transactions xqf: Queue connection factory for distributed transactions xtf: Topic connection factory for distributed transactions |
-o attribute=value |
Attributes of administered object (see Administered Object Attributes and Chapter 19, Administered Object Attribute Reference) |
-r readOnlyState |
Is administered object read-only? If true, client cannot modify object’s attributes. Default value: false. |
-i fileName |
Name of command file containing all or part of subcommand clause |
-pre |
Preview results without performing command This option is useful for checking the values of default attributes. |
-javahome path |
Location of alternative Java runtime Default behavior: Use runtime installed on system or bundled with Message Queue. |
-f |
Perform action without user confirmation |
-s |
Silent mode (no output displayed) |
-v |
Display version information [Any other options specified on the command line are ignored. ] |
-h |
Display usage help |
-H |
Display expanded usage help, including attribute list and examples |
The Database Manager utility (imqdbmgr) sets up the database schema for a JDBC-based data store. You can also use it to delete Message Queue database tables that have become corrupted, change the database, display information about the database, convert a standalone database for use in an enhanced broker cluster, or back up and restore a highly-available database. Table 16–13 lists the imqdbmgr subcommands.
Table 16–13 Database Manager Subcommands
Table 16–14 lists the options to the imqdbmgr command.
Table 16–14 Database Manager Options
Option |
Description |
---|---|
-b instanceName |
Instance name of broker |
-Dproperty=value |
Set broker configuration property See Persistence Properties for information about persistence-related broker configuration properties. Caution: Be careful to check the spelling and formatting of properties set with this option. Incorrect values will be ignored without notification or warning. |
-u userName |
User name for authentication against the database |
-passfile filePath |
Location of password file See Password Files for more information. |
-n brokerID |
(Used with the remove bkr subcommand) Broker identifier of broker to be removed from shared data store |
-n bridgeName |
(Used with the remove jmsbridge subcommand) Bridge name of the JMS bridge to be removed from shared data store |
-dir dirPath |
Backup directory for backing up or restoring JDBC-based data store |
-v |
Display version information [Any other options specified on the command line are ignored. ] |
-h |
Display usage help |
The User Manager utility (imqusermgr) is used for populating or editing a flat-file user repository. The utility must be run on the same host where the broker is installed; if a broker-specific user repository does not yet exist, you must first start up the corresponding broker instance in order to create it. You will also need the appropriate permissions to write to the repository: on the Solaris or Linux platforms, this means you must be either the root user or the user who originally created the broker instance.
Table 16–15 lists the subcommands available with the imqusermgr command. In all cases, the -i option specifies the instance name of the broker to whose user repository the command applies; if not specified, the default name imqbroker is assumed.
Table 16–15 User Manager Subcommands
In addition, the options listed in Table 16–16 can be applied to any subcommand of the imqusermgr command.
Table 16–16 General User Manager Options
The Bridge Manager utility (imqbridgemgr) is used to manage the bridges configured for a broker, including the links within bridge types that support links. The basic syntax of imqbridgemgr is:
imqbridgemgr subcommand commandArgument [ options ] imqbridgemgr -h | -help imqbridgemgr -H | -Help imqbridgemgr -v | -version
Table 16–17 lists the imqbridgemgr subcommands for general bridge management, Table 16–18 lists the imqbridgemgr subcommands for link management, which are applicable only to bridge types that support links, and Table 16–19 lists the imqbridgemgr options.
Table 16–17 Bridge Manager Subcommands for Bridge Management
Subcommand |
Description |
---|---|
list bridge |
Lists the bridges specified by the command options provided. For each bridge, the bridge name, type and state are displayed. |
pause bridge |
Pauses the bridges specified by the command options provided if the bridge type supports this subcommand. Attempting to pause a bridge that is stopped generates an error, and attempting to pause a bridge that is already paused has no effect. |
resume bridge |
Resumes the bridges specified by the command options provided if the bridge type supports this subcommand. Attempting to resume a bridge that is stopped generates an error, and attempting to resume a bridge that is already started has no effect. |
start bridge |
Starts the bridges specified by the command options provided. Attempting to start a bridge that is paused causes the bridge to resume, and attempting to start a bridge that is already started has no effect. |
stop bridge |
Stops the bridges specified by the command options provided. Attempting to stop a bridge that is paused causes the bridge to stop, and attempting to stop a bridge that is already stopped has no effect. |
Table 16–18 Bridge Manager Subcommands for Link Management
Subcommand |
Description |
---|---|
list link |
Lists the links specified by the command options provided. For each link, the link name, state, source, target, and transaction status are displayed. |
pause link |
Pauses the link specified by the command options provided. Attempting to pause a link that is stopped, in the process of stopping, or has never been started generates an error. Attempting to pause a link that is already paused or in the process of pausing has no effect. |
resume link |
Resumes the link specified by the command options provided. Attempting to resume a link that is stopped, in the process of stopping, or has never been started generates an error. Attempting to resume a link that is already started or in the process of starting has no effect. |
start link |
Starts the link specified by the command options provided. Attempting to start a link that is paused causes the link to resume. Attempting to start a link that is in the process of pausing causes the link to complete pausing and then to resume. Attempting to start a link that is already started or in the process of starting has no effect. |
stop link |
Stops the link specified by the command options provided. Attempting to stop a link that has never been started generates an error. Attempting to stop a link that is in the process of starting causes the link to complete starting and then to stop. Attempting to stop a link that is paused causes the link to stop. Attempting to stop a link that is in the process of pausing causes the link to complete pausing and then to stop. Attempting to stop a link that is already stopped or in the process of stopping has no effect. |
Table 16–19 lists the options to the imqbridgemgr command.
Table 16–19 Bridge Manager Options
Option |
Description |
---|---|
-b hostName:portNumber |
The broker housing the bridge. Default value: localhost:7676 |
-bn bridgeName |
The name of the bridge. |
-f |
Perform the action without user confirmation |
-javahome path |
Location of an alternative Java runtime. Default behavior: Use the runtime installed with Message Queue. |
-ln linkName |
The name of the link. |
-passfile path |
Location of password file |
-rtm timeoutInterval |
Initial timeout interval, in seconds This is the initial length of time that the Command utility will wait for a reply from the broker before retrying a request. Each subsequent retry will use a timeout interval that is a multiple of this initial interval. Default value: 10 |
-rtr numRetries |
Number of retries to attempt after a broker request times out Default value: 5 |
-s |
Silent mode (no output displayed) |
-secure |
Use secure connection to broker with ssladmin connection service |
-t bridgeType |
The type of the bridge: JMS or STOMP |
-u userName |
User name for authentication |
The Service Administrator utility (imqsvcadmin) installs a broker as a Windows service. Table 16–20 lists the available subcommands.
Table 16–20 Service Administrator Subcommands
Subcommand |
Description |
---|---|
install |
Install service |
remove |
Remove service |
query |
Display startup options Startup options can include whether the service is started manually or automatically, its location, the location of the Java runtime, and the values of arguments passed to the broker on startup (see Table 16–21). |
Table 16–21 lists the options to the imqsvcadmin command.
Table 16–21 Service Administrator Options
Option |
Description |
---|---|
-javahome path |
Location of alternative Java runtime Default behavior: Use runtime installed on system or bundled with Message Queue. |
-jrehome path | |
-vmargs arg1 [ [arg2] … ] |
Additional arguments to pass to Java Virtual Machine (JVM) running broker service [These arguments can also be specified in the Start Parameters field under the General tab in the service’s Properties window (reached by way of the Services tool in the Windows Administrative Tools control panel). ] Example: imqsvcadmin install -vmargs "-Xms16m -Xmx128m" |
-args arg1 [ [arg2] … ] |
Additional command line arguments to pass to broker service Example: imqsvcadmin install -args "-passfile d:\\imqpassfile" See Broker Utility for information about broker command line arguments. |
-h |
Display usage help [Any other options specified on the command line are ignored. ] |
Any information you specify using the -javahome, -vmargs, and -args options is stored in the Windows registry under the keys JREHome, JVMArgs, and ServiceArgs in the path
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\iMQ_Broker\Parameters
The Key Tool utility (imqkeytool) generates a self-signed certificate for the broker, which can be used for the ssljms, ssladmin, or cluster connection service. The syntax is
imqkeytool -broker
On UNIX systems, you might need to run the utility from the root user account.
This chapter provides reference information about configuration properties for a message broker. It consists of the following sections:
Table 17–1 lists the broker properties related to connection services.
Table 17–1 Broker Connection Properties
Property |
Type |
Default Value |
Description |
---|---|---|---|
String |
None |
Broker identifier For brokers using a shared JDBC-based data store, this string is appended to the names of all database tables to identify each table with a particular broker. Must be a unique alphanumeric string of no more than n - 13 characters, where n is the maximum table name length allowed by the database. This property is unnecessary for an embedded database or a standalone database which stores data for only one broker instance. Note – For enhanced broker clusters (imq.cluster.ha = true), database table names also use the imq.cluster.clusterid property (see Table 17–12). |
|
imq.service.activelist [Must have the same value for all brokers in an enhanced cluster. ] |
String |
jms,admin |
List of connection services to be activated at broker startup, separated by commas See Table 6–1 under Configuring Connection Services for the names of the available connection services. |
String |
All available IP addresses |
Default host name or IP address for all connection services |
|
String |
None |
Host name or IP address of Port Mapper If specified, overrides imq.hostname. This might be necessary, for instance, if the broker’s host computer has more than one network interface card installed. |
|
imq.portmapper.port [Can be used with imqcmd update bkr command] |
Integer |
7676 |
Port number of Port Mapper Note – If multiple broker instances are running on the same host, each must be assigned a unique Port Mapper port. |
imq.serviceName.protocolType.hostname [jms, ssljms, admin, and ssladmin services only; see Appendix C, HTTP/HTTPS Support for information on configuring the httpjms and httpsjms services] |
String |
None |
Host name or IP address for connection service If specified, overrides imq.hostname for the designated connection service. This might be necessary, for instance, if the broker’s host computer has more than one network interface card installed. |
Integer |
0 |
Port number for connection service A value of 0 specifies that the port number should be allocated dynamically by the Port Mapper. You might need to set a different value, for instance, to specify a static port number for connecting to the broker through a firewall. |
|
Integer |
50 |
Maximum number of pending Port Mapper requests in operating system backlog |
|
imq.serviceName.threadpool_model [jms and admin services only] |
String |
dedicated |
Threading model for thread pool management: dedicated: Two dedicated threads per connection, one for incoming and one for outgoing messages shared: Connections processed by shared thread when sending or receiving messages |
The dedicated model limits the number of connections that can be supported, but provides higher performance; the shared model increases the number of possible connections, but at the cost of lower performance because of the additional overhead needed for thread management. |
|||
Integer |
jms: 10ssljms: 10httpjms: 10 httpsjms: 10 admin: 4ssladmin: 4 |
Minimum number of threads maintained in connection service’s thread pool When the number of available threads exceeds this threshold, threads will be shut down as they become free until the minimum is reached. The default value varies by connection service, as shown. |
|
Integer |
jms: 1000ssljms: 500httpjms: 500httpsjms : 500admin: 10ssladmin: 10 |
Number of threads beyond which no new threads are added to the thread pool for use by the named connection service Must be greater than 0 and greater than the value of imq.serviceName.min_threads. The default value varies by connection service, as shown. |
|
imq.shared.connectionMonitor_limit [Shared threading model only] |
Integer |
Solaris: 512Linux: 512Windows: 64 |
Maximum number of connections monitored by a distributor thread The system allocates enough distributor threads to monitor all connections. The smaller the value of this property, the faster threads can be assigned to active connections. A value of -1 denotes an unlimited number of connections per thread. The default value varies by operating-system platform, as shown. |
Integer |
120 |
Interval, in seconds, at which to test connection between client and broker A value of 0 or -1 disables periodic testing of the connection. |
Table 17–2 lists the broker properties related to routing and delivery services. Properties that configure the automatic creation of destinations are listed in Table 17–3.
Table 17–2 Broker Routing and Delivery PropertiesTable 17–3 Broker Properties for Auto-Created Destinations
Message Queue supports both file-based and JDBC-based persistence modules. The broker property imq.persist.store (Table 17–4) specifies which module to use. The following sections describe the broker configuration properties for the two modules.
Table 17–4 Global Broker Persistence Property
Table 17–5 lists the broker properties related to file-based persistence.
Table 17–5 Broker Properties for File-Based Persistence
Table 17–6 lists the file-based persistence properties for the transaction logging mechanism introduced in Message Queue 4.4 Update 1.
Table 17–6 Broker Properties for File-Based Persistence Using the Transaction Logging Mechanism
Property |
Type |
Default Value |
Description |
---|---|---|---|
Boolean |
false |
Enables the transaction logging mechanism introduced in Message Queue 4.4 Update 1. For information about this mechanism, see Optimizing File-Based Transaction Persistence. |
|
Boolean |
false |
This property is applicable only if imq.persist.file.newTxnLog.enabled is true. Can improve performance if imq.persist.file.sync.enabled is true and the number of concurrent transactions being processed is high:
|
|
Boolean |
false |
This property is applicable only if imq.persist.file.newTxnLog.enabled is true. Overrides the behavior for persisting non-transacted messages (as defined by the imq.persist.file.sync.enabled property):
|
|
Boolean |
false |
This property is applicable only if imq.persist.file.newTxnLog.enabled is true. Overrides the behavior for persisting non-transacted message acknowledgements (as defined by the imq.persist.file.sync.enabled property):
|
Table 17–7 lists the broker properties related to JDBC-based persistence. The first of these properties, imq.persist.jdbc.dbVendor, identifies the database vendor being used for the broker’s persistent data store; all of the remaining properties are qualified by this vendor name.
Table 17–7 Broker Properties for JDBC-Based Persistence
Table 17–8 lists broker properties related to security services: authentication, authorization, and encryption. Table 17–9 lists broker properties related specifically to LDAP-based authentication, and Table 17–10 lists broker properties related specifically to JAAS-based authentication.
Table 17–8 Broker Security Properties
Property |
Type |
Default Value |
Description |
---|---|---|---|
String |
file |
Type of user authentication: file: File-based ldap: Lightweight Directory Access Protocol jaas: Java Authentication and Authorization Service |
|
String |
digest |
digest: MD5 (for file-based authentication) basic: Base-64 (for LDAP or JAAS authentication) |
|
String |
None |
Password encoding method for connection service serviceName: digest: MD5 (for file-based authentication) basic: Base-64 (for LDAP or JAAS authentication) If specified, overrides imq.authentication.type for the designated connection service. |
|
Integer |
180 |
Interval, in seconds, to wait for client response to authentication requests |
|
Boolean |
true |
If true, the system will check the access control file to verify that an authenticated user is authorized to use a connection service or to perform specific operations with respect to specific destinations. |
|
String |
file |
Specifies the access control type |
|
Boolean |
None |
Use access control for connection service? If specified, overrides imq.accesscontrol.enabled for the designated connection service. If true, the system will check the access control file to verify that an authenticated user is authorized to use the designated connection service or to perform specific operations with respect to specific destinations. |
|
String |
accesscontrol.properties |
Name of access control file The file name specifies a path relative to the access control directory (see Appendix A, Distribution-Specific Locations of Message Queue Data). |
|
String |
None |
Name of access control file for connection service If specified, overrides imq.accesscontrol.file.filename for the designated connection service. The file name specifies a path relative to the access control directory (see Appendix A, Distribution-Specific Locations of Message Queue Data). |
|
String |
Not set |
The location, as a URL, of the access control file. |
|
String |
None |
The location, as a URL, of the access control file for connection service If specified, overrides imq.accesscontrol.file.url for the designated connection service. |
|
String |
See Appendix A, Distribution-Specific Locations of Message Queue Data |
Path to directory containing key store file |
|
String |
keystore |
Name of key store file |
|
String |
None |
Password for key store file |
|
Boolean |
false |
Obtain passwords from password file? |
|
String |
See Appendix A, Distribution-Specific Locations of Message Queue Data |
Path to directory containing password file |
|
String |
passfile | ||
String |
None |
Password for administrative user The Command utility (imqcmd) uses this password to authenticate the user before executing a command. |
|
Boolean |
false |
Is audit logging to broker log file enabled? |
|
Boolean |
true |
Is audit logging to the Solaris BSM audit log disabled? |
Table 17–9 lists broker properties related to LDAP-based user authentication.
Table 17–9 Broker Security Properties for LDAP Authentication
Table 17–10 lists broker properties related to JAAS-based user authentication.
Table 17–10 Broker Security Properties for JAAS Authentication
Property |
Type |
Default Value |
Description |
---|---|---|---|
String |
None |
Set to the name of the desired entry (in the JAAS configuration file) that references the login modules you want to use as the authentication service. This is the name you noted in Step 3. |
|
String |
None |
This property, used by Message Queue access control, specifies the java.security.Principal implementation class in the login module(s) that the broker uses to extract the Principal name to represent the user entity in the Message Queue access control file. If, it is not specified, the user name passed from the Message Queue client when a connection was requested is used instead. |
|
String |
None |
This property, used by Message Queue access control, specifies the java.security.Principal implementation class in the login module(s) that the broker uses to extract the Principal name to represent the group entity in the Message Queue access control file. If, it is not specified, the user name passed from the Message Queue client when a connection was requested is used instead. |
Table 17–11 lists the broker properties related to monitoring services.
Table 17–11 Broker Monitoring Properties
Property |
Type |
Default Value |
Description |
|
---|---|---|---|---|
String |
INFO |
Logging level Specifies the categories of logging information that can be written to an output channel. Possible values, from high to low: ERROR WARNING INFO Each level includes those above it (for example, WARNING includes ERROR). |
||
Boolean |
false |
Log information about dead messages? If true, the following events will be logged:
|
||
String |
ERR |
Destination for console output: OUT: stdout ERR: stderr |
||
String |
ERROR|WARNING |
Categories of logging information to write to console: NONE ERROR WARNING INFO ALL The ERROR, WARNING, and INFO categories do not include those above them, so each must be specified explicitly if desired. Any combination of categories can be specified, separated by vertical bars (|). |
||
String |
See Appendix A, Distribution-Specific Locations of Message Queue Data |
Path to directory containing log file |
||
String |
log.txt |
Name of log file |
||
String |
ALL |
Categories of logging information to write to log file: NONE ERROR WARNING INFO ALL The ERROR, WARNING, and INFO categories do not include those above them, so each must be specified explicitly if desired. Any combination of categories can be specified, separated by vertical bars (|). |
||
Integer |
-1 |
File length, in bytes, at which output rolls over to a new log file A value of -1 denotes an unlimited number of bytes (no rollover based on file length). |
||
Integer |
604800 (one week) |
Age of file, in seconds, at which output rolls over to a new log file A value of -1 denotes an unlimited number of seconds (no rollover based on file age). |
||
String |
ERROR |
Categories of logging information to write to syslogd(1M): NONE ERROR WARNING INFO ALL The ERROR, WARNING, and INFO categories do not include those above them, so each must be specified explicitly if desired. Any combination of categories can be specified, separated by vertical bars (|). |
||
String |
LOG_DAEMON |
syslog facility for logging messages Possible values mirror those listed on the syslog(3C) man page. Appropriate values for use with Message Queue include: LOG_USER LOG_DAEMON LOG_LOCAL0 LOG_LOCAL1 LOG_LOCAL2 LOG_LOCAL3 LOG_LOCAL4 LOG_LOCAL5 LOG_LOCAL6 LOG_LOCAL7 |
||
String |
imqbrokerd_${imq.instanceName} |
Identity string to be prefixed to all messages logged to syslog |
||
Boolean |
true |
Log broker process ID with message? |
||
Boolean |
false |
Write messages to system console if they cannot be sent to syslog? |
||
String |
Local time zone |
Time zone for log time stamps Possible values are the same as those used by the method java.util.TimeZone.getTimeZone. Examples: GMT GMT-8:00 America/LosAngeles Europe/Rome Asia/Tokyo |
||
Boolean |
true |
Enable writing of metrics information to Logger? Does not affect the production of metrics messages (controlled by imq.metrics.topic.enabled). |
||
Integer |
-1 |
Time interval, in seconds, at which to write metrics information to Logger Does not affect the time interval for production of metrics messages (controlled by imq.metrics.topic.interval). A value of -1 denotes an indefinite interval (never write metrics information to Logger). |
||
Boolean |
true |
Enable production of metrics messages to metric topic destinations? If false, an attempt to subscribe to a metric topic destination will throw a client-side exception. |
||
Integer |
60 |
Time interval, in seconds, at which to produce metrics messages to metric topic destinations |
||
Boolean |
false |
Are metrics messages sent to metric topic destinations persistent? |
||
Integer |
300 |
Lifetime, in seconds, of metrics messages sent to metric topic destinations |
||
String |
System property user.name (user who started the broker) |
Name of primary system owner |
||
String |
System property user.name (user who started the broker) |
Contact information for primary system owner |
||
Integer |
None |
Number of defined roles |
||
String |
Broker instance name |
Name of defined role N (where N ranges from 0 to .count-1) Example:
|
Table 17–12 lists the configuration properties related to broker clusters.
Table 17–12 Broker Properties for Cluster Configuration
Property |
Type |
Default Value |
Description |
---|---|---|---|
imq.cluster.url [Must have the same value for all brokers in a cluster] , [Can be used with imqcmd update bkr command] |
String |
None |
URL of cluster configuration file, if any Examples: http://webserver/imq/cluster.properties (for a file on a Web server) file:/net/mfsserver/imq/cluster.properties (for a file on a shared drive) |
Boolean |
false |
Is broker part of a high-availability cluster? |
|
String |
None |
List of broker addresses belonging to cluster The list consists of one or more addresses, separated by commas. Each address specifies the host name and Port Mapper port number of a broker in the cluster, in the form hostName:portNumber. Example: host1:3000,host2:8000,ctrlhost Note – If set, this property is ignored (and a warning logged) for high-availability clusters; all brokers configured to use the cluster’s shared persistent store are automatically recognized as members of the cluster. |
|
imq.cluster.hostname [Can be specified independently for each broker in a cluster] |
String |
None |
Host name or IP address for cluster connection service If specified, overrides imq.hostname (see Table 17–1) for the cluster connection service. This might be necessary, for instance, if the broker’s host computer has more than one interface card installed. |
Integer |
0 |
Port number for cluster connection service A value of 0 specifies that the port number should be allocated dynamically by the Port Mapper. You might need to set a different value, for instance, to specify a static port number for connecting to the broker through a firewall. |
|
String |
tcp |
Network transport protocol for cluster connection service For secure, encrypted message delivery between brokers, set this property to ssl. |
|
String |
None |
Host name and Port Mapper port number of host on which cluster’s master broker (if any) is running The value has the form hostName:portNumber, where hostName is the host name of the master broker’s host and portNumber is its Port Mapper port number. Example: ctrlhost:7676 Note – enhanced clusters cannot have a master broker. If this property is set for a broker belonging to an enhanced cluster, the broker will log a warning message and ignore the property. |
|
String |
None |
Must be a unique alphanumeric string of no more than n–13 characters, where n is the maximum table name length allowed by the database. No two running clusters may have the same cluster identifier. This string is appended to the names of all database tables in the cluster’s shared persistent store. Note – For brokers belonging to a high-availability cluster, this property is used in database table names in place of imq.brokerid (see Table 17–1). |
|
String |
None |
Host name or IP address for heartbeat service If specified, overrides imq.hostname (see Table 17–1) for the heartbeat service. |
|
Integer |
7676 |
Port number for heartbeat service A value of 0 specifies that the port number should be allocated dynamically by the Port Mapper. |
|
Integer |
2 |
Interval between heartbeats, in seconds |
|
Integer |
3 |
Number of missed heartbeat intervals after which to invoke monitor service |
|
Integer |
30 |
Interval, in seconds, at which to update monitor time stamp Note – Larger values for this property will reduce the frequency of database access and thus improve overall system performance, but at the cost of slower detection and takeover in the event of broker failure. |
|
Integer |
2 |
Number of missed monitor intervals after which to initiate broker takeover |
Table 17–13 lists broker properties related to the bridge service manager. Table 17–14 lists broker properties related specifically to the JMS bridge service, and Table 17–15 lists broker properties related specifically to the STOMP bridge service.
Table 17–13 Broker Properties for the Bridge Service Manager
Property |
Type |
Default Value |
Description |
---|---|---|---|
imq.bridge.enabled |
Boolean |
false |
Is the bridge service enabled on this broker? |
imq.bridge.activelist |
String |
None |
List of bridges that will be loaded on broker startup. The list consists of one or more bridge names, separated by commas. All bridge names for a broker must be unique. |
imq.bridge.admin.user |
String |
None |
The Message Queue broker administrative user to be used by the bridge service manager and individual bridges to create ADMIN connections to the broker. For JMS bridges, this user is also used to access the JMS bridge's built-in DMQ destination. |
imq.bridge.admin.password |
String |
None |
The password for the imq.bridge.admin.user user. |
Table 17–14 Broker Properties for a JMS Bridge Service
Table 17–15 Broker Properties for the STOMP Bridge Service
Property |
Type |
Default Value |
Description |
---|---|---|---|
imq.bridge.stomp.tcp.enabled |
Boolean |
true |
Does the STOMP bridge accept TCP connections? |
imq.bridge.stomp.tcp.port |
Integer |
7672 |
The port on which the STOMP bridge listens for TCP connections, provided that imq.bridge.stomp.tcp.enabled is true. |
imq.bridge.stomp.tls.enabled |
Boolean |
false |
Does the STOMP bridge accept SSL/TLS connections? If true, a keystore must be created using the imqkeytool utility before starting the broker. |
imq.bridge.stomp.tls.port |
Integer |
7673 |
The port on which the STOMP bridge listens for SSL/TLS connections, provided that imq.bridge.stomp.tls.enabled is true. |
imq.bridge.stomp.tls.requireClientAuth |
Boolean |
false |
Do SSL/TLS connections require client authentication? |
imq.bridge.stomp.consumerFlowLimit |
Integer |
1000 |
The maximum number of unacknowledged messages that the STOMP bridge will deliver on a transacted STOMP subscription. The STOMP client must then acknowledge the messages and commit the transaction. |
imq.bridge.stomp.messageTransformer |
String |
None |
The fully qualified class name of a class that extends the Message Queue bridge MessageTransformer abstract class by implementing the transform() method. Place this class under the IMQ_HOME/lib/ext. directory |
imq.bridge.stomp.logfile.limit |
Integer |
0 |
The approximate maximum number of bytes the STOMP bridge writes to any one log file. A value of 0 (zero) indicates that there is no maximum limit. |
imq.bridge.stomp.logfile.count |
Integer |
1 |
The number of log files the STOMP bridge cycles through. |
The broker properties listed in Table 17–16 support the use of the Java Management Extensions (JMX) application programming interface by Java applications. The JMX API is used to configure and monitor broker resources.
These JMX-related properties can be set in the broker's instance configuration file (config.properties) or at broker startup with the -D option of the Broker utility (imqbrokerd). None of these properties can be set dynamically with the Command utility (imqcmd).
In addition, some of these properties (imq.jmx.rmiregistry.start, imq.jmx.rmiregistry.use, imq.jmx.rmiregistry.port) can be set with corresponding Broker utilityimqbrokerd options described in Table 16–1.
See Appendix D, JMX Support for further information on administrative support of JMX clients.
Table 17–16 Broker Properties for JMX Support
Property |
Type |
Default Value |
Description |
---|---|---|---|
String |
jmxrmi |
Names of JMX connectors to be activated at broker startup, separated by commas |
|
String |
Shown in next column |
urlpath component of JMX service URL for connector connectorName Useful in cases where an RMI registry is being used and the JMX service URL path must be set explicitly (such as when a shared external RMI registry is used). See The JMX Service URL. Default: /jndi/rmi://brokerHost:rmiPort /brokerHost/brokerPort/connectorName |
|
Integer |
None: the port is dynamically allocated |
Port number of JMX connector Used to specify a static/known JMX connector port, typically in cases where a JMX client is accessing the broker's MBean server through a firewall. See JMX Connections Through a Firewall. |
|
Boolean |
false |
Use Secure Socket Layer (SSL) for connector connectorName? This property is set to true for the ssljmxrmi connector. |
|
Boolean |
false |
Trust any certificate presented by broker for connector connectorName? Applies only when imq.jmx.connector.connectorName.useSSL is true. If false, the JMX client runtime will validate all certificates presented to it. Validation will fail if the signer of the certificate is not in the client's trust store. If true, validation of certificates is skipped. This can be useful, for instance, during software testing when a self-signed certificate is used. |
|
Boolean |
false |
Start RMI registry at broker startup? If true, the broker will start an RMI registry at the port specified by imq.jmx.rmiregistry.port and use the regsitry to store the JMX connector stub. (The value of imq.jmx.rmiregistry.use is ignored in this case.) For convenience, this property can also be set at broker startup with the -startRmiRegistry option ofimqbrokerd. |
|
Boolean |
false |
Use an existing RMI registry? Applies only if imq.jmx.rmiregistry.start is false. If true, the broker will use an existing RMI registry on the local host at the port specified by imq.jmx.rmiregistry.port to store the JMX connector stub. The existing RMI registry must already be running at broker startup. For convenience, this property can also be set at broker startup with the -useRmiRegistry option ofimqbrokerd. |
|
Integer |
1099 |
Port number of RMI registry Applies only if imq.jmx.rmiregistry.start is true or imq.jmx.rmiregistry.use is true. This port number will be included in the URL path of the JMX service URL. For convenience, this property can also be set at broker startup with the -rmiRegistryPort option of imqbrokerd. |
Alphabetical List of Broker Properties is an alphabetical list of broker configuration properties, with cross-references to the relevant tables in this chapter.
Table 17–17 Alphabetical List of Broker Properties
Property |
Table |
---|---|
imq.accesscontrol.enabled | |
imq.accesscontrol.type | |
imq.accesscontrol.file.filename | |
imq.audit.bsm.disabled | |
imq.audit.enabled | |
imq.authentication.basic.user_repository | |
imq.authentication.client.response.timeout | |
imq.authentication.type | |
imq.autocreate.destination.isLocalOnly | |
imq.autocreate.destination.limitBehavior | |
imq.autocreate.destination.maxBytesPerMsg | |
imq.autocreate.destination.maxNumMsgs | |
imq.autocreate.destination.maxNumProducers | |
imq.autocreate.destination.maxTotalMsgBytes | |
imq.autocreate.destination.useDMQ | |
imq.autocreate.queue | |
imq.autocreate.queue.consumerFlowLimit | |
imq.autocreate.queue.localDeliveryPreferred | |
imq.autocreate.queue.maxNumActiveConsumers | |
imq.autocreate.queue.maxNumBackupConsumers | |
imq.autocreate.reaptime | |
imq.autocreate.topic | |
imq.autocreate.topic.consumerFlowLimit | |
imq.brokerid | |
imq.bridge.activelist | |
imq.bridge.admin.password | |
imq.bridge.admin.user | |
imq.bridge.enabled | |
imq.bridge.name.autostart | |
imq.bridge.name.logfile.count | |
imq.bridge.name.logfile.limit | |
imq.bridge.name.tm.props | |
imq.bridge.name.type | |
imq.bridge.name.xmlurl | |
imq.bridge.stomp.consumerFlowLimit | |
imq.bridge.stomp.logfile.count | |
imq.bridge.stomp.logfile.limit | |
imq.bridge.stomp.messageTransformer | |
imq.bridge.stomp.tcp.enabled | |
imq.bridge.stomp.tcp.port | |
imq.bridge.stomp.tls.enabled | |
imq.bridge.stomp.tls.port | |
imq.bridge.stomp.tls.requireClientAuth | |
imq.bridge.tm.props | |
imq.cluster.brokerlist | |
imq.cluster.clusterid | |
imq.cluster.ha | |
imq.cluster.heartbeat.hostname | |
imq.cluster.heartbeat.interval | |
imq.cluster.heartbeat.port | |
imq.cluster.heartbeat.threshold | |
imq.cluster.hostname | |
imq.cluster.masterbroker | |
imq.cluster.monitor.interval | |
imq.cluster.monitor.threshold | |
imq.cluster.port | |
imq.cluster.transport | |
imq.cluster.url | |
imq.destination.DMQ.truncateBody | |
imq.destination.logDeadMsgs | |
imq.hostname | |
imq.imqcmd.password | |
imq.jmx.connector.activelist | |
imq.jmx.connector.RMIconnectorName.brokerHostTrusted | |
imq.jmx.connector.RMIconnectorName.port | |
imq.jmx.connector.RMIconnectorName.urlpath | |
imq.jmx.connector.RMIconnectorName.useSSL | |
imq.jmx.rmiregistry.port | |
imq.jmx.rmiregistry.start | |
imq.jmx.rmiregistry.use | |
imq.keystore.file.dirpath | |
imq.keystore.file.name | |
imq.keystore.password | |
imq.keystore.propertyName | |
imq.log.console.output | |
imq.log.console.stream | |
imq.log.file.dirpath | |
imq.log.file.filename | |
imq.log.file.output | |
imq.log.file.rolloverbytes | |
imq.log.file.rolloversecs | |
imq.log.level | |
imq.log.syslog.facility | |
imq.log.syslog.identity | |
imq.log.syslog.logconsole | |
imq.log.syslog.logpid | |
imq.log.syslog.output | |
imq.log.timezone | |
imq.message.expiration.interval | |
imq.message.max_size | |
imq.metrics.enabled | |
imq.metrics.interval | |
imq.metrics.topic.enabled | |
imq.metrics.topic.interval | |
imq.metrics.topic.persist | |
imq.metrics.topic.timetolive | |
imq.passfile.dirpath | |
imq.passfile.enabled | |
imq.passfile.name | |
imq.persist.file.destination.message.filepool.limit | |
imq.persist.file.message.cleanup | |
imq.persist.file.message.filepool.cleanratio | |
imq.persist.file.message.max_record_size | |
imq.persist.file.sync.enabled | |
imq.persist.file.transaction.memorymappedfile.enabled | |
imq.persist.jdbc.dbVendor | |
imq.persist.jdbc.vendorName.closedburl | |
imq.persist.jdbc.vendorName.createdburl | |
imq.persist.jdbc.vendorName.driver | |
imq.persist.jdbc.vendorName.needpassword | |
imq.persist.jdbc.vendorName.opendburl | |
imq.persist.jdbc.vendorName.password | |
imq.persist.jdbc.vendorName.property.propName | |
imq.persist.jdbc.vendorName.user | |
imq.persist.store | |
imq.ping.interval | |
imq.portmapper.backlog | |
imq.portmapper.hostname | |
imq.portmapper.port | |
imq.resourceState.count | |
imq.resourceState.threshold | |
imq.service.activelist | |
imq.serviceName.accesscontrol.enabled | |
imq.serviceName.accesscontrol.file.filename | |
imq.serviceName.authentication.type | |
imq.serviceName.max_threads | |
imq.serviceName.min_threads | |
imq.serviceName.protocolType.hostname | |
imq.serviceName.protocolType.port | |
imq.serviceName.threadpool_model | |
imq.shared.connectionMonitor_limit | |
imq.system.max_count | |
imq.system.max_size | |
imq.transaction.autorollback | |
imq.user_repository.ldap.base | |
imq.user_repository.ldap.gidattr | |
imq.user_repository.ldap.grpbase | |
imq.user_repository.ldap.grpfilter | |
imq.user_repository.ldap.grpsearch | |
imq.user_repository.ldap.memattr | |
imq.user_repository.ldap.password | |
imq.user_repository.ldap.principal | |
imq.user_repository.ldap.propertyName | |
imq.user_repository.ldap.server | |
imq.user_repository.ldap.ssl.enabled | |
imq.user_repository.ldap.timeout | |
imq.user_repository.ldap.uidattr | |
imq.user_repository.ldap.usrfilter | |
imq.user_repository.jaas.name | |
imq.user_repository.jaas.userPrincipalClass | |
imq.user_repository.jaas.groupPrincipalClass |
This chapter provides reference information about configuration properties for physical destinations.
Table 18–1 lists the configuration properties for physical destinations. These properties can be set when creating or updating a physical destination. For auto-created destinations, you set default values in the broker’s instance configuration file (see Table 17–3).
Table 18–1 Physical Destination Properties
This chapter provides reference information about the attributes of administered objects. It consists of the following sections:
The attributes of a connection factory object are grouped into categories described in the following sections below:
Table 19–1 lists the connection factory attributes for connection handling.
Table 19–1 Connection Factory Attributes for Connection Handling
Attribute |
Type |
Default Value |
Description |
---|---|---|---|
String |
An existing Message Queue 3.0 address, if any; if none, the first entry in Table 19–2 |
List of broker addresses The list consists of one or more addresses, separated by commas. Each address specifies (or implies) the host name, port number, and connection service for a broker instance to which the client can connect. Address syntax varies depending on the connection service and port assignment method; see below for details. Note – In an enhanced broker cluster, the value of this attribute is updated dynamically as brokers enter and leave the cluster, so that it always reflects the cluster’s current membership. |
|
String |
PRIORITY |
Order in which to attempt connection to broker addresses: PRIORITY: Order specified in address list RANDOM: Random order Note – If many clients share the same connection factory, specify random connection order to prevent them from all attempting to connect to the same address. |
|
Integer |
1 |
Number of times to iterate through address list attempting to establish or reestablish a connection A value of -1 denotes an unlimited number of iterations. Note – In the event of broker failure in an enhanced broker cluster, this attribute is ignored and the Message Queue client runtime iterates through the address list indefinitely until it succeeds in reconnecting to a takeover broker. The effect is equivalent to an imqAddressListIterations value of -1, overriding any other explicit or default setting of this attribute. The only way for a client application to avoid this behavior is to close the connection explicitly on broker failure. |
|
imqPingInterval |
Integer |
30 |
Interval, in seconds, at which to test connection between client and broker A value of 0 or -1 disables periodic testing of the connection. |
Boolean |
false |
Attempt to reestablish a lost connection? Note – In the event of broker failure in an enhanced broker cluster, this attribute is ignored and automatic reconnection is always attempted. The effect is equivalent to an imqReconnectEnabled value of true, overriding any other explicit or default setting of this attribute. The only way for a client application to avoid this behavior is to close the connection explicitly on broker failure. |
|
Integer |
0 |
Number of times to attempt connection (or reconnection) to each address in address list before moving on to next A value of -1 denotes an unlimited number of connection attempts: attempt repeatedly to connect to first address until successful. For example, in an enhanced broker cluster, this value will allow for connection to the failover broker. |
|
Long integer |
3000 |
Interval, in milliseconds, between reconnection attempts This value applies both for successive attempts on a given address and for successive addresses in the list. Note – Too small a value may give the broker insufficient recovery time; too large a value may cause unacceptable connection delays. |
|
Boolean |
false |
Trust any certificate presented by broker? If false, the Message Queue client runtime will validate all certificates presented to it. Validation will fail if the signer of the certificate is not in the client's trust store. If true, validation of certificates is skipped. This can be useful, for instance, during software testing when a self-signed certificate is used. NOTE: To use signed certificates from a certification authority, set this attribute to false. |
The value of the imqAddressList attribute is a comma-separated string specifying one or more broker addresses to which to connect. The general syntax for each address is as follows:
scheme://address
where scheme identifies one of the addressing schemes shown in the first column of Table 19–2 and address denotes the broker address itself. The exact syntax for specifying the address depends on the addressing scheme, as shown in the last column of the table.
Table 19–2 Message Broker Addressing SchemesTable 19–3 Message Broker Address Examples
Service |
Broker Host |
Port |
Example Address |
---|---|---|---|
Not specified |
Not specified |
Not specified |
No address (mq://localHost:7676/jms) |
Not specified |
Specified host |
Not specified |
myBkrHost (mq://myBkrHost:7676/jms) |
Not specified |
Not specified |
Specified Port Mapper port |
1012 (mq://localHost:1012/jms) |
ssljms |
Local host |
Standard Port Mapper port |
mq://localHost:7676/ssljms |
ssljms |
Specified host |
Standard Port Mapper port |
mq://myBkrHost:7676/ssljms |
ssljms |
Specified host |
Specified Port Mapper port |
mq://myBkrHost:1012/ssljms |
jms |
Local host |
Specified service port |
mqtcp://localhost:1032/jms |
ssljms |
Specified host |
Specified service port |
mqssl://myBkrHost:1034/ssljms |
httpjms |
Not applicable |
Not applicable |
http://websrvr1:8085/imq/tunnel |
httpsjms |
Not applicable |
Not applicable |
https://websrvr2:8090/imq/tunnel |
Table 19–4 lists the connection factory attributes for client identification.
Table 19–4 Connection Factory Attributes for Client Identification
Attribute |
Type |
Default Value |
Description |
---|---|---|---|
String |
guest |
Default user name for authenticating with broker |
|
String |
guest |
Default password for authenticating with broker |
|
String |
null |
Administratively configured client identifier |
|
Boolean |
false |
Prevent client from changing client identifier using setClientID method? |
Table 19–5 lists the connection factory attributes for reliability and flow control.
Table 19–5 Connection Factory Attributes for Reliability and Flow Control
Attribute |
Type |
Default Value |
Description |
---|---|---|---|
String |
0 |
Maximum time, in milliseconds, to wait for broker acknowledgment before throwing an exception A value of 0 denotes no timeout (wait indefinitely). Note – In some situations, too low a value can cause premature timeout: for example, initial authentication of a user against an LDAP user repository using a secure (SSL) connection can take more than 30 seconds. |
|
Integer |
100 |
Number of payload messages in a metered batch Delivery of payload messages to the client is temporarily suspended after this number of messages, allowing any accumulated control messages to be delivered. Payload message delivery is resumed on notification by the client runtime, and continues until the count is again reached. A value of 0 disables metering of message delivery and may cause Message Queue control messages to be blocked by heavy payload message traffic. |
|
Boolean |
false |
Limit message flow at connection level? |
|
Integer |
1000 |
Maximum number of messages per connection to deliver and buffer for consumption Message delivery on a connection stops when the number of unconsumed payload messages pending (subject to flow metering governed by imqConnectionFlowCount) exceeds this limit. Delivery resumes only when the number of pending messages falls below the limit. This prevents the client from being overwhelmed with pending messages that might cause it to run out of memory. This attribute is ignored if imqConnectionFlowLimitEnabled is false. |
|
Integer |
1000 |
Maximum number of messages per consumer to deliver and buffer for consumption Message delivery to a given consumer stops when the number of unconsumed payload messages pending for that consumer exceeds this limit. Delivery resumes only when the number of pending messages for the consumer falls below the percentage specified by imqConsumerFlowThreshold. This can be used to improve load balancing among multiple consumers and prevent any single consumer from starving others on the same connection. This limit can be overridden by a lower value set for a queue’s own consumerFlowLimit attribute (see Chapter 18, Physical Destination Property Reference). Note also that message delivery to all consumers on a connection is subject to the overall limit specified by imqConnectionFlowLimit. |
|
Integer |
50 |
Number of messages per consumer buffered in the client runtime, as a percentage of imqConsumerFlowLimit, below which to resume message delivery |
Table 19–6 lists the connection factory attributes for queue browsing and server sessions.
Table 19–6 Connection Factory Attributes for Queue Browser and Server Sessions
The connection factory attributes listed in Table 19–7 control whether the Message Queue client runtime sets certain standard message properties defined in the Java Message Service Specification.
Table 19–7 Connection Factory Attributes for Standard Message Properties
Property |
Type |
Default Value |
Description |
---|---|---|---|
Boolean |
false |
Set JMSXUserID property (identity of user sending message) for produced messages? |
|
Boolean |
false |
Set JMSXAppID property (identity of application sending message) for produced messages? |
|
Boolean |
false |
Set JMSXProducerTXID property (transaction identifier of transaction within which message was produced) for produced messages? |
|
Boolean |
false |
Set JMSXConsumerTXID property (transaction identifier of transaction within which message was consumed) for consumed messages? |
|
Boolean |
false |
Set JMSXRcvTimestamp property (time message delivered to consumer) for consumed messages? |
Table 19–8 lists the connection factory attributes for overriding JMS message header fields.
Table 19–8 Connection Factory Attributes for Message Header Overrides
Attribute |
Type |
Default Value |
Description |
---|---|---|---|
Boolean |
false |
Allow client-set delivery mode to be overridden? |
|
Integer |
2 |
Overriding value of delivery mode: 1 Nonpersistent 2 Persistent |
|
Boolean |
false |
Allow client-set expiration time to be overridden? |
|
Long integer |
0 |
Overriding value of expiration time, in milliseconds A value of 0 denotes an unlimited expiration time (message never expires). |
|
Boolean |
false |
Allow client-set priority level to be overridden? |
|
Integer |
4 (normal) |
Overriding value of priority level (0 to 9) |
|
Boolean |
false |
Apply overrides to temporary destinations? |
Table 19–9 lists the attributes that can be set for a destination administered object.
Table 19–9 Destination Attributes
Attribute |
Type |
Default Value |
Description |
---|---|---|---|
String |
Untitled_Destination_Object |
Name of physical destination The destination name may contain only alphanumeric characters (no spaces) and must begin with an alphabetic character or the underscore (_) or dollar sign ($) character. It may not begin with the characters mq. |
|
String |
None |
Descriptive string for destination |
This chapter describes the configuration properties of the Message Queue JMS Resource Adapter (JMS RA), which enables you to integrate Sun GlassFish Message Queue with any J2EE 1.4 application server by means of the standard J2EE connector architecture (JCA). When plugged into an application server, the Resource Adapter allows applications deployed in that application server to use Message Queue to send and receive JMS messages.
The Message Queue JMS Resource Adapter exposes its configuration properties through three JavaBean components:
The ResourceAdapter JavaBean (ResourceAdapter JavaBean) affects the behavior of the Resource Adapter as a whole.
The ManagedConnectionFactory JavaBean (ManagedConnectionFactory JavaBean) affects connections created by the Resource Adapter for use by message-driven beans (MDBs).
The ActivationSpec JavaBean (ActivationSpec JavaBean) affects message endpoints that represent MDBs in their interactions with the messaging system.
To set property values for these entities, you use the tools provided by your application server for configuration and deployment of the Resource Adapter and for deployment of MDBs.
This chapter lists and describes the configuration properties of the Message Queue JMS Resource Adapter. It contains the following sections:
The Message Queue JMS Resource Adapter provides a special feature called shared subscriptions for containers that support clustering, such as Sun Java System GlassFish Enterprise Server. This feature enables clustered containers to share the load of processing messages for topic subscriptions across the instances of a cluster.
When this feature is enabled, the following behaviors apply:
A client id must be set when creating any subscription, even a nondurable subscription (which does not normally require a client id). Attempting to create a subscription without a client id throws an exception.
Attempts by multiple connections to use the same client id do not result in an exception, provided that the connections are from different instances in the cluster.
Two or more subscriptions on the same topic with the same client id and the same durable subscription name (if the subscription is durable) are considered “shared”; that is, they are treated as a single subscription, with each message being sent to only one of the participating subscriptions.
By default, the shared subscriptions feature is enabled. In some applications that use nondurable subscriptions, however, the shared behavior is not desired. In such cases, the useSharedSubscriptionInClusteredContainer property can be set to false to disable the feature.
The ResourceAdapter configuration configures the default JMS Resource Adapter behavior. Table 20–1 lists and describes the properties with which you can configure this JavaBean.
Table 20–1 Resource Adapter Properties
A managed connection factory defines the connections that the Resource Adapter provides to a message-driven bean. Table 20–2 shows the properties of the ManagedConnectionFactory JavaBean; if set, these properties override the corresponding properties of the ResourceAdapter JavaBean.
Table 20–2 Managed Connection Factory Properties
Property |
Type |
Default Value |
Description |
||
---|---|---|---|---|---|
String |
Inherited from ResourceAdapter JavaBean (see Table 20–1) |
List of message service addresses for connecting to Message Queue service |
|||
String |
guest |
User name for connecting to Message Queue service |
|||
String |
guest |
Password for connecting to Message Queue service |
|||
String |
None |
Client identifier for connections to Message Queue service |
|||
String |
PRIORITY |
Order in which to attempt connection to Message Queue service: PRIORITY: Order specified in address list RANDOM: Random order Note – Reconnection attempts after a connection failure start with the broker whose connection failed and proceed sequentially through the address list, regardless of the value set for this property. |
|||
Integer |
1 |
Number of times to iterate through address list attempting to establish or reestablish a connection |
|||
Boolean |
false | ||||
Integer |
6 |
Number of times to attempt reconnection to each address in address list before moving on to next |
|||
Long integer |
30000 |
Interval, in milliseconds, between reconnection attempts |
|||
String |
None |
A list of additional connection factory properties to be used when creating connections to a Message Queue broker. When specified, the value of options must be a comma-separated list of connection factory properties and their values, in the form:
If value contains a comma or an equals sign, precede the symbol with a backslash (\) or enclose the entire value in quotes; for example:
The options property cannot specify properties that are configured internally or that have their own setter methods, specifically: imqReconnectEnabled, imqReconnectAttempts, imqReconnectInterval, imqDefaultUsername, imqDefaultPassword, imqAddressList, imqAddressListIterations. Any values specified in options for these properties are ignored. |
|||
Boolean |
true |
Controls whether topic subscriptions created using this ManagedConnectionFactory will be shared when running in a clustered container, as described in About Shared Topic Subscriptions for Clustered Containers. Set to true (the default) to share subscriptions. The clientID property must also be set, even if the subscription is nondurable. Set to false to not share subscriptions. This setting should only be used for nondurable subscriptions. The clientID property does not need to be set. |
Table 20–3 shows the configurable properties of the ActivationSpec JavaBean. These properties are used by the application server when instructing the Resource Adapter to activate a message endpoint and associate it with a message-driven bean.
Table 20–3 ActivationSpec Properties
Property |
Type |
Default Value |
Description |
||
---|---|---|---|---|---|
addressList [Optional] , [Property specific to Message Queue JMS Resource Adapter] |
String |
Inherited from ResourceAdapter JavaBean |
Message service address for connecting to Message Queue service |
||
destination [Standard Enterprise JavaBean (EJB) and J2EE Connector Architecture (CA) property] |
String |
None |
Name of destination from which to consume messages The value must be that of the destinationName property for a Message Queue destination administered object. |
||
String |
None |
Type of destination specified by destination property: javax.jms.Queue: Queue destination javax.jms.Topic: Topic destination |
|||
String |
None |
Message selector for filtering messages delivered to consumer |
|||
String |
None |
Name for durable subscriptions This property must be set if subscriptionDurability is set to Durable. |
|||
String |
NonDurable |
Durability of consumer for topic destination: Durable: Durable consumer NonDurable: Nondurable consumer This property is valid only if destinationType is set to javax.jms.Topic, and is optional for nondurable subscriptions and required for durable ones. If set to Durable, the clientID and subscriptionName properties must also be set. |
|||
String |
None |
Client ID for connections to Message Queue service This property must be set if subscriptionDurability is set to Durable. |
|||
String |
Auto-acknowledge |
Acknowledgment mode: Auto-acknowledge: Auto-acknowledge mode Dups-ok-acknowledge: Dups-OK-acknowledge mode |
|||
String |
None |
Acknowledgment mode for MDB message consumption Valid values are No_acknowledge or null. You can use no-acknowledge mode only for a nontransacted, nondurable topic subscription; if you use this setting with a transacted subscription or a durable subscription, subscription activation will fail. |
|||
Integer |
6 |
Number of times to redeliver a message when MDB throws an exception during message delivery |
|||
Boolean |
true |
Place message in dead message queue when MDB throws a runtime exception and number of redelivery attempts exceeds the value of endpointExceptionRedeliveryAttempts? If false, the Message Queue broker will attempt redelivery of the message to any valid consumer, including the same MDB. |
|||
String |
None |
A list of additional connection factory properties to be used when creating connections to a Message Queue broker. When specified, the value of options must be a comma-separated list of connection factory properties and their values, in the form:
If value contains a comma or an equals sign, precede the symbol with a backslash (\) or enclose the entire value in quotes; for example:
The options property cannot be used to specify properties that are configured internally or that have their own setter methods, specifically: imqReconnectEnabled, imqReconnectAttempts, imqReconnectInterval, imqDefaultUsername, imqDefaultPassword, imqAddressList, imqAddressListIterations. Any values specified in options for these properties are ignored. |
|||
Boolean |
true |
Controls whether topic subscriptions created using this ActivationSpec will be shared when running in a clustered container, as described in About Shared Topic Subscriptions for Clustered Containers. Set to true (the default) to share subscriptions. The clientID property must also be set, even if the subscription is nondurable. Set to false to not share subscriptions. This setting should only be used for nondurable subscriptions. The clientID property does not need to be set. |
This chapter describes the metrics information that a Message Queue broker can provide for monitoring, tuning, and diagnostic purposes. This information can be made available in a variety of ways:
In a log file (see Sending Metrics Data to Log Files)
Interactively with the Command utility’s imqcmd metrics subcommand (see Using the Command Utility)
In metrics messages sent to a metrics topic destination (see Using the Message-Based Monitoring API )
Through JMX MBeans that can be accessed programmatically by Java applications using the JMX Administration API.
The tables in this chapter list the kinds of metrics information available and the forms in which it can be provided. For metrics provided through the Command utility’s imqcmd metrics subcommand, the tables list the metric type with which they can be requested; for those provided in metrics messages, the tables list the metrics topic destination to which they are delivered. All the metrics information in this chapter can be accessed progamatically using the JMX Administration API as described in the Message Queue Developer’s Guide for JMX Clients
The chapter consists of the following sections:
Table 21–1 shows the metrics information that the broker reports for the broker process JVM (Java Virtual Machine) heap.
Table 21–1 JVM Metrics
Metrics Quantity |
Description |
Log File? |
metrics bkrMetric Type |
Metrics Topic |
---|---|---|---|---|
JVM heap: total memory |
Current total memory, in bytes |
Yes |
cxn |
mq.metrics.jvm |
JVM heap: free memory |
Amount of memory currently available for use, in bytes |
Yes |
cxn |
mq.metrics.jvm |
JVM heap: max memory |
Maximum allowable heap size, in bytes |
Yes |
None |
mq.metrics.jvm |
Table 21–2 shows the brokerwide metrics information that the broker reports.
Table 21–2 Brokerwide Metrics
Metrics Quantity |
Description |
Log File? |
metrics bkrMetric Type |
Metrics Topic |
---|---|---|---|---|
Connections |
||||
Num connections |
Total current number of connections for all connection services |
Yes |
cxn |
mq.metrics.broker |
Num threads |
Total current number of threads for all connection services |
Yes |
cxn |
None |
Min threads |
Total minimum number of threads for all connection services |
Yes |
cxn |
None |
Max threads |
Total maximum number of threads for all connection services |
Yes |
cxn |
None |
Stored Messages |
||||
Num messages |
Current number of payload messages stored in memory and persistent store |
No |
mq.metrics.broker |
|
Total message bytes |
Total size in bytes of payload messages currently stored in memory and persistent store |
No |
None |
mq.metrics.broker |
Message Flow |
||||
Num messages in |
Cumulative number of payload messages received since broker started |
Yes |
ttl |
mq.metrics.broker |
Num messages out |
Cumulative number of payload messages sent since broker started |
Yes |
ttl |
mq.metrics.broker |
Rate messages in |
Current rate of flow of payload messages into broker |
Yes |
rts |
None |
Rate messages out |
Current rate of flow of payload messages out of broker |
Yes |
rts |
None |
Message bytes in |
Cumulative size in bytes of payload messages received since broker started |
Yes |
ttl |
mq.metrics.broker |
Message bytes out |
Cumulative size in bytes of payload messages sent since broker started |
Yes |
ttl |
mq.metrics.broker |
Rate message bytes in |
Current rate of flow of payload message bytes into broker |
Yes |
rts |
None |
Rate message bytes out |
Current rate of flow of payload message bytes out of broker |
Yes |
rts |
None |
Num packets in |
Cumulative number of payload and control packets received since broker started |
Yes |
ttl |
mq.metrics.broker |
Num packets out |
Cumulative number of payload and control packets sent since broker started |
Yes |
ttl |
mq.metrics.broker |
Rate packets in |
Current rate of flow of payload and control packets into broker |
Yes |
rts |
None |
Rate packets out |
Current rate of flow of payload and control packets out of broker |
Yes |
rts |
None |
Packet bytes in |
Cumulative size in bytes of payload and control packets received since broker started |
Yes |
ttl |
mq.metrics.broker |
Packet bytes out |
Cumulative size in bytes of payload and control packets sent since broker started |
Yes |
ttl |
mq.metrics.broker |
Rate packet bytes in |
Current rate of flow of payload and control packet bytes into broker |
Yes |
rts |
None |
Rate packet bytes out |
Current rate of flow of payload and control packet bytes out of broker |
Yes |
rts |
None |
Destinations |
||||
Num destinations |
Current number of physical destinations |
No |
None |
mq.metrics.broker |
Table 21–3 shows the metrics information that the broker reports for individual connection services.
Table 21–3 Connection Service Metrics
Metrics Quantity |
Description |
Log File? |
metrics svcMetric Type |
Metrics Topic |
---|---|---|---|---|
Connections |
||||
Num connections |
Current number of connections |
No |
None |
|
Num threads |
Current number of threads |
No |
cxn |
None |
Min threads |
Minimum number of threads assigned to service |
No |
cxn |
None |
Max threads |
Maximum number of threads assigned to service |
No |
cxn |
None |
Message Flow |
||||
Num messages in |
Cumulative number of payload messages received through connection service since broker started |
No |
ttl |
None |
Num messages out |
Cumulative number of payload messages sent through connection service since broker started |
No |
ttl |
None |
Rate messages in |
Current rate of flow of payload messages into broker through connection service |
No |
rts |
None |
Rate messages out |
Current rate of flow of payload messages out of broker through connection service |
No |
rts |
None |
Message bytes in |
Cumulative size in bytes of payload messages received through connection service since broker started |
No |
ttl |
None |
Message bytes out |
Cumulative size in bytes of payload messages sent through connection service since broker started |
No |
ttl |
None |
Rate message bytes in |
Current rate of flow of payload message bytes into broker through connection service |
No |
rts |
None |
Rate message bytes out |
Current rate of flow of payload message bytes out of broker through connection service |
No |
rts |
None |
Num packets in |
Cumulative number of payload and control packets received through connection service since broker started |
No |
ttl |
None |
Num packets out |
Cumulative number of payload and control packets sent through connection service since broker started |
No |
ttl |
None |
Rate packets in |
Current rate of flow of payload and control packets into broker through connection service |
No |
rts |
None |
Rate packets out |
Current rate of flow of payload and control packets out of broker through connection service |
No |
rts |
None |
Packet bytes in |
Cumulative size in bytes of payload and control packets received through connection service since broker started |
No |
ttl |
None |
Packet bytes out |
Cumulative size in bytes of payload and control packets sent through connection service since broker started |
No |
ttl |
None |
Rate packet bytes in |
Current rate of flow of payload and control packet bytes into broker through connection service |
No |
rts |
None |
Rate packet bytes out |
Current rate of flow of payload and control packet bytes out of broker through connection service |
No |
rts |
None |
Table 21–4 shows the metrics information that the broker reports for individual destinations.
Table 21–4 Physical Destination Metrics
This chapter describes the monitoring information items that Message Queue exposes through the Sun JavaTM Enterprise System Monitoring Framework (JESMF), using the Monitoring Framework’s Common Monitoring Model (CMM). It contains the following sections:
The attributes listed in Table 22–1 are common to all (or almost all) CMM objects.
Table 22–1 JESMF Common Object Attributes
Attribute |
Description |
---|---|
Name |
Object name |
Caption |
Short description |
Description |
Full description |
LastUpdateTime |
Time last updated |
OperationalStatus |
Current status (for example, OK or DORMANT) |
StatusDescriptions |
Description of status |
OperationalStatusLastChange |
Time of last change in operational status |
Table 22–2 shows attributes of the Message Queue product itself that can be accessed with JESMF.
Table 22–2 JESMF-Accessible Message Queue Product Attributes
Table 22–3 shows the JESMF-accessible attributes pertaining to each broker instance.
Table 22–3 JESMF-Accessible Message Queue Broker Attributes
Attribute |
Description |
---|---|
PrimaryOwnerName |
Name of primary system owner (broker property imq.primaryowner.name; see Table 17–11) |
PrimaryOwnerContact |
Contact information for primary system owner (broker property imq.primaryowner.contact; see Table 17–11) |
Roles |
Array of strings denoting broker’s roles (taken from broker properties imq.broker.adminDefinedRoles.namen; see Table 17–11) |
StartupTime |
Time of last startup (date and time in milliseconds) |
URL |
URL of Port Mapper |
ConfigurationDirectory |
Broker instance directory (for example, /var/imq/instances/mybroker) |
DirectoryName |
Distinguished name of directory (for example, LDAP) entry where static information about application is stored An empty string indicates that no information about the application is available in the directory. |
The attributes shown in Table 22–4 provide information about a broker’s Port Mapper.
Table 22–4 JESMF-Accessible Message Queue Port Mapper Attributes
Attribute |
Description |
---|---|
LabeledURI |
URI for accessing Port Mapper, in the form mq://hostName:portNumber |
Secured |
Is Port Mapper access secure (SSL/TLS)? |
Table 22–5 shows the JESMF-accessible attributes pertaining to each connection service.
Table 22–5 JESMF-Accessible Message Queue Connection Service Attributes
Attribute |
Description |
---|---|
LabeledURI |
URI for accessing connection service, in the form mq://hostName:portNumber/serviceName if dynamically allocated, or mqtcp://hostName:servicePort/serviceName or mqssl://hostName:servicePort/serviceName if statically assigned |
Secured |
Is connection service access secure (SSL/TLS)? |
ConnectionsCount |
Current number of connections |
NumConnectionsCreated |
Cumulative number of connections created since broker started |
FailedConnectionsCount |
Cumulative number of connections rejected since broker started |
CurrentNumberOfThreads |
Current number of threads actively handling connections |
MinThreadPoolSize |
Minimum number of threads maintained in connection service’s thread pool (broker property imq.serviceName.min_threads; see Table 17–1) |
MaxThreadPoolSize |
Number of threads beyond which no new threads are added to thread pool for use by connection service (broker property imq.serviceName.max_threads; see Table 17–1) |
NumProducers |
Current number of message producers |
NumConsumers |
Current number of message consumers |
NumMsgsIn |
Cumulative number of messages received since broker started |
NumMsgsOut |
Cumulative number of messages sent since broker started |
InBytesCount |
Cumulative size in bytes of messages received since broker started |
OutBytesCount |
Cumulative size in bytes of messages sent since broker started |
NumPktsIn |
Cumulative number of packets received since broker started |
NumPktsOut |
Cumulative number of packets sent since broker started |
PktBytesIn |
Cumulative size in bytes of packets received since broker started |
PktBytesOut |
Cumulative size in bytes of packets sent since broker started |
Table 22–6 shows the JESMF-accessible attributes pertaining to each destination. Each of these attributes corresponds to a Message Queue physical destination property; see Table 18–1 for further information.
Table 22–6 JESMF-Accessible Message Queue Destination Attributes
Attribute |
Corresponding Property |
Description |
---|---|---|
Type |
Destination type (q = queue, t = topic) |
|
MaxNumMsgs |
Maximum number of unconsumed messages |
|
MaxBytesPerMsg |
Maximum size, in bytes, of any single message |
|
MaxTotalMsgBytes |
Maximum total memory, in bytes, for unconsumed messages |
|
LimitBehavior |
Broker behavior when memory-limit threshold reached |
|
Maximum number of associated message producers |
||
Maximum number of associated active message consumers in load-balanced delivery |
||
MaxNumBackupConsumers |
Maximum number of associated backup message consumers in load-balanced delivery |
|
ConsumerFlowLimit |
Maximum number of messages delivered to consumer in a single batch |
|
LocalOnly |
Local delivery only? |
|
LocalDeliveryPreferred , |
Local delivery preferred? |
|
UseDMQ |
The attributes shown in Table 22–7 pertain to the persistent data store.
Table 22–7 JESMF-Accessible Message Queue Persistent Store Attributes
Attribute |
Description |
---|---|
AccessInfo |
URL for accessing JDBC database |
InfoFormat |
Format of AccessInfo attribute (URL) |
JDBCDriver |
JDBC driver |
UserName |
User name for authentication |
The attributes shown in Table 22–8 pertain to the LDAP user repository.
Table 22–8 JESMF-Accessible Message Queue User Repository Attributes
Attribute |
Description |
---|---|
AccessInfo |
URL for accessing LDAP server |
InfoFormat |
Format of AccessInfo attribute (URL) |
Base |
Root or base node for user lookup |
GroupBase |
Root or base node for group lookup |
UserName |
User name for authentication |