Sun Java System Message Queue 3.7 UR1 Administration Guide

Chapter 13 Command Line Reference

This chapter provides reference information on the use of the Message Queue^TM command line administration utilities. It consists of the following sections:

Command Line Syntax

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

Broker Utility

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 13–1 shows the options to the imqbrokerd command and the configuration properties, if any, overridden by each option.

Table 13–1 Broker Utility Options


Option	Properties Overridden	Description
`-name` `instanceName`	`imq.instancename`	Instance name of broker 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 14, 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	Reset persistent data store 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 the 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 the 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.
`-password` `keyPassword`	`imq.keystore.password`	Password for SSL certificate key store [This option is deprecated and will eventually be removed. Either omit the password (so that the user will be prompted for it interactively) or use the `-passfile` option to specify a file containing the password. ]
`-dbuser` `userName`	`imq.persist.jdbc.user`	User name for JDBC-based persistent data store
`-dbpassword` `dbPassword`	`imq.persist.jdbc.password`	Password for JDBC-based persistent data store
`-ldappassword` `ldapPassword`	`imq.user_repository.ldap.password`	Password for LDAP user repository
`-passfile` `filePath`	`imq.passfile.enabledimq.passfile.dirpathimq.passfile.name`	Location of password file 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.
`-license` [ `licenseName` ]	None	License to load, if different from default for installed edition of Message Queue product: `pe`: Platform Edition with basic features `try`: Platform Edition with enterprise features (90-day trial) `unl`: Enterprise Edition If no license name is specified, all licenses installed on the system are listed.
`-upgrade-store-nobackup`	None	Automatically remove old data store on upgrade to Message Queue 3.5 or 3.5 SP`x` 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`	Logging level: `NONE` `ERROR` `WARNING` `INFO` Default value: `INFO`
`-metrics` `interval`	`imq.metrics.interval`	Logging interval for broker metrics, in seconds
`-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

Command Utility

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). The possible subcommands are listed here and described in detail in the corresponding sections below. In all cases, if the 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.

Broker Management
`shutdown bkr`	Shut down broker
`restart bkr`	Restart broker
`pause bkr`	Pause broker
`resume bkr`	Resume broker
`update bkr`	Set broker properties
`reload cls`	Reload cluster configuration
`query bkr`	List broker property values
`metrics bkr`	Display broker metrics
Connection Service Management
`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
Connection Management
`list cxn`	List connections on broker
`query cxn`	Display connection information
Physical Destination Management
`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
`update dst`	Set physical destination properties
`purge dst`	Purge all messages from physical destination
`compact dst`	Compact physical destination
`list dst`	List physical destinations
`query dst`	List physical destination property values
`metrics dst`	Display physical destination metrics
Durable Subscription Management
`destroy dur`	Destroy durable subscription
`purge dur`	Purge all messages for durable subscription
`list dur`	List durable subscriptions for topic
Transaction Management
`commit txn`	Commit transaction
`rollback txn`	Roll back transaction
`list txn`	List transactions being tracked by broker
`query txn`	Display transaction information

Broker Management

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 13–2 to manage and control it.

Table 13–2 Command Utility Subcommands for Broker Management


Syntax	Description
`shutdown bkr` [`-b` `hostName:portNumber`]	Shut down broker
`restart bkr` [`-b` `hostName:portNumber`]	Restart broker Shuts down the broker and then restarts it using the same options specified when it was originally started.
`pause bkr` [`-b` `hostName:portNumber`]	Pause broker See Pausing a Broker for more information.
`resume bkr` [`-b` `hostName:portNumber`]	Resume broker
`update bkr` [`-b` `hostName:portNumber`] `-o` `property1=value1` [ [`-o` `property2=value2`] … ]	Set broker properties See Chapter 14, Broker Properties Reference for information on broker properties.
`reload cls`	Reload cluster configuration [Applies only to broker clusters] Forces all persistent information to be brought up to date.
`query bkr` `-b` `hostName:portNumber`	List broker property values Also lists all running brokers connected to the specified broker in a cluster.
`metrics bkr` [`-b` `hostName:portNumber`] [`-m` `metricType`] [`-int` `interval`] [`-msp` `numSamples`]	Display broker metrics 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).

Connection Service Management

Table 13–3 lists the imqcmd subcommands for managing connection services.

Table 13–3 Command Utility Subcommands for Connection Service Management


Syntax	Description
`pause svc` `-n` `serviceName` [`-b` `hostName:portNumber`]	Pause connection service The `admin` connection service cannot be paused.
`resume svc` `-n` `serviceName` [`-b` `hostName:portNumber`]	Resume connection service
`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`]	List connection services available on broker
`query svc` `-n` `serviceName` [`-b` `hostName:portNumber`]	List connection service property values
`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).

Connection Management

Table 13–4 lists the imqcmd subcommands for managing connections.

Table 13–4 Command Utility Subcommands for Connection Service Management


Syntax	Description
`list cxn` [`-svn` `serviceName`] [`-b` `hostName:portNumber`]	List connections on broker Lists all connections on the broker to the specified connection service. If no connection service is specified, all connections are listed.
`query cxn` `-n` `connectionID` [`-b` `hostName:portNumber`]	Display connection information

Physical Destination Management

Table 13–5 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

Table 13–5 Command Utility Subcommands for Physical Destination Management


Syntax	Description
`create dst` `-t` `destType` `-n` `destName` [`-o` `property1=value1`] [ [ `-o` `property2=value2`] … ]	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` `-t` `destType` `-n` `destName`	Destroy physical destination 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: `CONSUMERS`: Pause delivery to message consumers `PRODUCERS`: Pause delivery to message producers `ALL`: Pause all message delivery Default value: `ALL`
`resume dst` [`-t` `destType` `-ndestName`]	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.
`update dst` `-t` `destType` `-n` `destName` `-o` `property1=value1` [ [ `-o` `property2=value2`] … ]	Set physical destination properties See Chapter 15, Physical Destination Property Reference for information on physical destination properties.
`purge dst` `-t` `destType` `-n` `destName`	Purge all messages from physical destination
`compact dst` [`-t` `destType` `-n` `destName`]	Compact physical destination 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.
`list dst` [`-t` `destType`] [`-tmp`]	List physical destinations 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`	List physical destination property values
`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 broker 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).

Durable Subscription Management

Table 13–6 lists the imqcmd subcommands for managing durable subscriptions.

Table 13–6 Command Utility Subcommands for Durable Subscription Management


Syntax	Description
`destroy dur` `-c` `clientID` `-n` `subscriberName`	Destroy durable subscription [Cannot be performed in a broker cluster whose master broker is temporarily unavailable]
`purge dur` `-c` `clientID` `-n` `subscriberName`	Purge all messages for durable subscription
`list dur` `-d` `topicName`	List durable subscriptions for topic

Transaction Management

Table 13–7 lists the imqcmd subcommands for managing transactions.

Table 13–7 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`	Display transaction information

General Command Utility Options

The additional options listed in Table 13–8 can be applied to any subcommand of the imqcmd command.

Table 13–8 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.
`-p` `password`	Password for authentication [This option is deprecated and will eventually be removed. Either omit the password (so that the user will be prompted for it interactively) or use the `-passfile` option to specify a file containing the password. ]
`-passfile` `path`	Location of password file See Password Files for more information.
`-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`	Display usage help^,
`-H`	Display expanded usage help, including attribute list and examples^,

Object Manager Utility

The Object Manager utility (imqobjmgr) creates and manages Message Queue administered objects. Table 13–9 lists the available subcommands.

Table 13–9 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 13–10 lists the options to the imqobjmgr command.

Table 13–10 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 `e`: SOAP endpoint (see Message Queue Developer's Guide for Java Clients)
`-o` `attribute=value`	Attributes of administered object (see Administered Object Attributes and Chapter 16, 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

Database Manager Utility

The Database Manager utility (imqdbmgr) sets up the database schema for a JDBC-based persistent data store. You can also use it to delete Message Queue database tables that have become corrupted or to change the data store. Table 13–11 lists the available subcommands.

Table 13–11 Database Manager Subcommands


Subcommand	Description
`create all`	Create new database and persistent store schema Used on embedded database systems. The broker property `imq.persist.jdbc.createdburl` must be specified.
`create tbl`	Create persistent store schema for existing database Used on external database systems.
`delete tbl`	Delete Message Queue database tables from current persistent store
`delete oldtbl`	Delete Message Queue database tables from earlier-version persistent store Used after the persistent store has been automatically migrated to the current version of Message Queue.
`recreate tbl`	Re-create persistent store schema Deletes all existing Message Queue database tables from the current persistent store and then re-creates the schema.
`reset lck`	Reset persistent store lock Resets the lock so that the persistent store database can be used by other processes.

Table 13–12 lists the options to the imqdbmgr command.

Table 13–12 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` `name`	User name for authentication
`-p` `password`	Password for authentication [This option is deprecated and will eventually be removed. Either omit the password (so that the user will be prompted for it interactively) or use the `-passfile` option to specify a file containing the password. ]
`-passfile` `path`	Location of password file See Password Files for more information.
`-v`	Display version information [Any other options specified on the command line are ignored. ]
`-h`	Display usage help

User Manager Utility

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 13–13 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 13–13 User Manager Subcommands


Syntax	Description
`add` [`-i` `instanceName`] `-u` `userName` `-p` `password` [`-g` `group`]	Add user and password to repository The optional `-g` option specifies a group to which to assign this user: `admin` `user` `anonymous`
`delete` [`-i` `instanceName`] `-u` `userName`	Delete user from repository
`update` [`-i` `instanceName`] `-u` `userName` `-p` `password` [`-a` `activeState`] `update` [`-i` `instanceName`] `-u` `userName` `-a` `activeState` [`-p` `password`]	Set user’s password or active state (or both) The `-a` option takes a boolean value specifying whether to make the user active (`true`) or inactive (`false`). Default value: `true`.
`list` [`-i` `instanceName`] [`-u` `userName`]	Display user information If no user name is specified, all users in the repository are listed.

In addition, the options listed in Table 13–14 can be applied to any subcommand of the imqusermgr command.

Table 13–14 General User Manager Options


Option	Description
`-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

Service Administrator Utility

The Service Administrator utility (imqsvcadmin) installs a broker as a Windows service. Table 13–15 lists the available subcommands.

Table 13–15 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 13–16).

Table 13–16 lists the options to the imqsvcadmin command.

Table 13–16 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`	Location of alternative Java Runtime Environment (JRE)
`-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 via 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

Key Tool Utility

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 may need to run the utility from the superuser (root) account.