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)
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 15–1 shows the options to the imqbrokerd command and the configuration properties, if any, overridden by each option.
Table 15–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 16, 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 15–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 15–3 can be applied to any subcommand of the imqcmd command.
Table 15–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 15–4 to manage and control it.
Table 15–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 16, 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 15–5 lists the imqcmd subcommands for managing connection services.
Table 15–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 15–6 lists the imqcmd subcommands for managing connections.
Table 15–6 Command Utility Subcommands for Connection Service Management
Table 15–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 17, 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 15–8 lists the imqcmd subcommands for managing durable subscriptions.
Table 15–8 Command Utility Subcommands for Durable Subscription Management
Table 15–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 15–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 15–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 15–10 Command Utility Subcommand for JMX Management
Syntax |
Description |
---|---|
list jmx |
The Object Manager utility (imqobjmgr) creates and manages Message Queue administered objects. Table 15–11 lists the available subcommands.
Table 15–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 15–12 lists the options to the imqobjmgr command.
Table 15–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 18, 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 15–13 lists the imqdbmgr subcommands.
Table 15–13 Database Manager Subcommands
Table 15–14 lists the options to the imqdbmgr command.
Table 15–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 |
Broker identifier of broker 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 15–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 15–15 User Manager Subcommands
In addition, the options listed in Table 15–16 can be applied to any subcommand of the imqusermgr command.
Table 15–16 General User Manager Options
The Service Administrator utility (imqsvcadmin) installs a broker as a Windows service. Table 15–17 lists the available subcommands.
Table 15–17 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 15–18). |
Table 15–18 lists the options to the imqsvcadmin command.
Table 15–18 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.