Skip Headers
Oracle GlassFish Server Message Queue Administration Guide
Release 4.5.2

Part Number E24943-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

16 Command Line Reference

This chapter provides reference information on the use of the Message Queue 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:

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:

imqcmddestroy 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 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 Description
-name instanceName

Instance name of broker

Multiple broker instances running on the same host must have different instance names.

Default value: imqbroker

Properties overridden: imq.instancename

-port portNumber

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

Properties overridden: imq.portmapper.port

-cluster broker1 [,broker2]...

Connect brokers into clusterFoot 1 

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.

Literal IP addresses as host names: You can use a literal IPv4 or IPv6 address as a host name. If you use a literal IPv6 address, its format must conform to RFC2732, Format for Literal IPv6 Addresses in URL's.

Properties overridden: imq.cluster.brokerlist

-Dproperty=value

Set configuration property

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

Properties overridden: Corresponding property in instance configuration file

-reset props

Reset configuration properties

Replaces the broker's existing instance configuration file config.properties with an empty file; all properties assume their default values.

Properties overridden: None

-reset store

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.

Properties overridden: None

-reset messages

Clear persistent messages from data store

Properties overridden: None

-reset durables

Clear durable subscriptions from data store

Properties overridden: None

-reset takeover-then-exit

Clear any takeover locks and then exit.

If a broker fails before completing the takeover of another broker's store, the failed broker retains a takeover lock even though it is not running. Use -reset takeover-then-exit to cause the failed broker to initiate startup, release the takeover lock, and then exit without actually starting up.

Properties overridden: None

-backup fileName

Back up configuration change record to fileFootref 1

See Managing a Conventional Cluster's Configuration Change Record for more information.

Properties overridden: None

-restore fileName

Restore configuration change record from backup fileFootref 1

The backup file must have been previously created using the -backup option.

See Managing a Conventional Cluster's Configuration Change Record for more information.

Properties overridden: None

-remove instance

Remove broker instanceFoot 2 

Deletes the instance configuration file, log files, persistent store, and other files and directories associated with the instance.

Properties overridden: None

-dbuser userName

User name for JDBC-based persistent data store

Properties overridden: imq.persist.jdbc.user

-passfile filePath

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.

Properties overridden: imq.passfile.enabledimq.passfile.dirpathimq.passfile.name

-shared

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.

Properties overridden: imq.jms.threadpool_model

-javahome path

Location of alternative Java runtime

Default behavior: Use runtime installed on system or bundled with Message Queue.

Properties overridden: None

-vmargs arg1 [arg2] ...

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.

Properties overridden: None

-startRmiRegistry

Start RMI registry at broker startup

Properties overridden: imq.jmx.rmiregistry.start

-useRmiRegistry

Use external RMI registry

Properties overridden: imq.jmx.rmiregistry.use

-rmiRegistryPort

Port number of RMI registry

Properties overridden: imq.jmx.rmiregistry.port

-upgrade-store-nobackup

Automatically remove old data store on upgrade to Message Queue 3.5 or 3.5 SPx from an incompatible versionFootref 2

Properties overridden: None

-force

Perform action without user confirmation

This option applies only to the -remove instance and -upgrade-store-nobackup options, which normally require confirmation.

Properties overridden: None

-loglevel level

Logging level: NONE, ERROR, WARNING or INFO.

Default value: INFO

Properties overridden: imq.broker.log.level

-metrics interval

Logging interval for broker metrics, in seconds

Properties overridden: imq.metrics.interval

-tty

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.

Properties overridden: imq.log.console.output

-s | -silent

Silent mode (no logging to console)

Sets the broker's imq.log.console.output property to NONE.

Properties overridden: imq.log.console.output

-version

Display version informationFoot 3 

Properties overridden: None

-h | -help

Display usage helpFootref 3

Properties overridden: None


Footnote 1 Applies only to broker clusters

Footnote 2 Requires user confirmation unless -force is also specified

Footnote 3 Any other options specified on the command line are ignored.

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

Note:

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.

Table 16-2 Command Utility Subcommands

Command Description

Broker Management

 

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

query bkr

List broker property values

list bkr

List brokers in cluster

metrics bkr

Display broker metrics

reload cls

Reload cluster configuration

changemaster cls

Change the master broker in a conventional cluster with master broker

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

destroy cxn

Destroy connection

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

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

Durable Subscription Management

 

destroy dur

Destroy durable subscription

purge dur

Purge all messages for durable subscription

list dur

List durable subscriptions for topics

Transaction Management

 

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

JMX Management

 

list jmx

List JMX service URLs of JMX connectors


General Command Utility Options

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 imqcmd 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 informationFoot 1 ,Foot 2 

-h

Display usage helpFootref 1,Footref 2

-H

Display expanded usage help, including attribute list and examplesFootref 1,Footref 2


Footnote 1 Any other options specified on the command line are ignored.

Footnote 2 User name and password not needed

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 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]

Shut down broker

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. Foot 1 

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 and Resuming a Broker for more information.

quiesce bkr [-b hostName:portNumber]

Quiesce broker

The broker will stop accepting new connections; existing connections will continue to operate.

unquiesce bkr [-b hostName:portNumber]

Unquiesce broker

The broker will resume accepting new connections, returning to normal operation.

resume bkr [-b hostName:portNumber]

Resume broker

takeover bkr 
 -n brokerID
 [-f]

Initiate broker takeover Footref 1

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

Set broker properties

See Broker Properties Reference for information on broker properties.

query bkr
 -b hostName:portNumber

List broker property values

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

List brokers in 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).

reload cls

Reload cluster configurationFootref 1

Forces all persistent information to be brought up to date.

changemaster cls
 -o imq.cluster.masterbroker=newMaster

Change the master broker in a conventional cluster with master broker.

This command must be run on the current master broker.

The value newMaster has the form hostName:portNumber, where hostName and portNumber are is its Port Mapper host name and port number, respectively.

Literal IP addresses as host names: You can use a literal IPv4 or IPv6 address as a host name. If you use a literal IPv6 address, its format must conform to RFC2732, Format for Literal IPv6 Addresses in URL's.


Footnote 1 Applies only to broker clusters

Connection Service Management

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
 [-bhostName: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
 [-bhostName:portNumber]

List connection service property values

metrics svc -n serviceName
 [-bhostName:portNumber]
 [-mmetricType]
 [-intinterval]
 [-mspnumSamples]

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 16-6 lists the imqcmd subcommands for managing connections.

Table 16-6 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

destroy cxn -n connectionID
 [-b hostName:portNumber]

Destroy connection


Physical Destination 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

Table 16-7 Command Utility Subcommands for Physical Destination Management

Syntax Description
create dst -t destType -n destName
 [-o property=value]...

Create physical destinationFoot 1 

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 destinationFootref 1

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

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.

update dst -t destType -n destName
 -o property1=value1
 [-o property2=value2]...

Set physical destination properties

See Physical Destination Property Reference for information on physical destination properties.

list dst [-tdestType]
 [-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 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).


Footnote 1 Cannot be performed in a broker cluster whose master broker is temporarily unavailable

Durable Subscription Management

Table 16-8 lists the imqcmd subcommands for managing durable subscriptions.

Table 16-8 Command Utility Subcommands for Durable Subscription Management

Syntax Description
destroy dur -n subscriberName -c clientID

Destroy durable subscriptionFoot 1 

purge dur -n subscriberName -c clientID

Purge all messages for durable subscription

list dur [-d topicName]

List durable subscriptions for the specified topic. If -d option is omitted then the command lists all durable subscriptions for all topics.


Footnote 1 Cannot be performed in a conventional broker cluster whose master broker is temporarily unavailable

Transaction 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

Display transaction information


JMX Management

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 JMX Support for further information on the broker's JMX support.

Table 16-10 Command Utility Subcommand for JMX Management

Syntax Description
list jmx

List JMX service URLs of JMX connectors


Object Manager Utility

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 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 informationFoot 1 

-h

Display usage helpFootref 1

-H

Display expanded usage help, including attribute list and examplesFootref 1


Footnote 1 Any other options specified on the command line are ignored.

Database Manager Utility

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.

Note:

When using a cluster configuration file to simplify management of the properties for a cluster of brokers, make sure to run imqdbmgr with the -D option to specify the location of the cluster configuration file; for example:

imqdbmgr -Dimq.cluster.url=location-of-cluster-configuration-file ...

Table 16-13 Database Manager Subcommands

Subcommand Description
create all

Create new database and persistent data store schema

Used on embedded database systems. The broker property imq.persist.jdbc.vendorName.createdburl must be specified.

create tbl

Create persistent data store schema for existing database

Used on external database systems.

For brokers belonging to an enhanced broker cluster (imq.cluster.ha = true), the schema created is for the cluster's shared data store, in accordance with the database vendor identified by the broker's imq.persist.jdbc.dbVendor property. If imq.cluster.ha = false, the schema is for the individual broker's standalone data store. Since the two types of data store can coexist in the same database, they are distinguished by appending a suffix to all table names:

  • C clusterID: Shared data store

  • S brokerID: Standalone data store

delete tbl

Delete Message Queue database tables from current data store

delete oldtbl

Delete Message Queue database tables from earlier-version data store

Used after the data 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.

query

Display information about the data store

upgrade hastore

Upgrade standalone data store to shared data store

backup

Back up JDBC-based data store to backup files

restore

Restore JDBC-based data store from backup files

remove bkr

Remove broker from shared data store

The broker must not be running.

remove jmsbridge

Remove JMS bridge from the shared data store

The broker hosting the JMS bridge must not be running.

reset lck

Reset data store lock

Resets the lock so that the database can be used by other processes.

Subcommands for a Cluster's Shared Configuration Change Table

 
create sharecc_tbl

Create the shared database table for the cluster configuration change record

delete sharecc_tbl

Delete the shared database table for the cluster configuration change record

recreate sharecc_tbl

Re-create the shared database table for the cluster configuration change record.

Deletes existing shared database table and then re-creates it.

backup sharecc_tbl-file filePath

Back up the shared database table for the cluster configuration change record to a backup file

restore sharecc_tbl-file filePath

Restore the shared database table for the cluster configuration change record from a backup file. The table must already exist.


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 informationFoot 1 

-h

Display usage helpFootref 1


Footnote 1 Any other options specified on the command line are ignored.

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

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

update [-i instanceName]
 -u userName -a activeStatus

update [-i instanceName]
 -u userName -p password
 -a activeStatus

Set user's password or active status (or both)

The -a option takes a boolean value specifying whether to make the user active (true) or inactive (false). An inactive status means that the user entry remains in the user repository, but the user will not be authenticated, even if using the correct password.

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 16-16 can be applied to any subcommand of the imqusermgr command.

Table 16-16 General User Manager Options

Option Description
-DbrokerProperty=value

Specify a broker property value when starting imqusermgr.

-f

Perform action without user confirmation

-s

Silent mode (no output displayed)

-v

Display version informationFoot 1 

-h

Display usage helpFootref 1


Footnote 1 Any other options specified on the command line are ignored.

Bridge Manager Utility

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.

Literal IP addresses as host names: You can use a literal IPv4 or IPv6 address as a host name. If you use a literal IPv6 address, its format must conform to RFC2732, Format for Literal IPv6 Addresses in URL's.

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


Service Administrator Utility

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

Location of alternative Java Runtime Environment (JRE)

-vmargs arg1 [arg2]…

Additional arguments to pass to Java Virtual Machine (JVM) running broker serviceFoot 1 

Example:

imqsvcadmin install vmargs "-Xms16m -Xmx128m"

-args arg1 [arg2]…

Additional command line arguments to pass to broker serviceFootref 1

Example:

imqsvcadmin install args "passfile d:\\imqpassfile"

See Broker Utility for information about broker command line arguments.

-h

Display usage helpFoot 2 


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

Footnote 2 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 might need to run the utility from the root user account.