imqcmd(1M) System Administration Commands imqcmd(1M)NAMEimqcmd - manage Message Queue brokers
SYNOPSIS
/usr/bin/imqcmd subcommand argument [option...]
/usr/bin/imqcmd [-h | -H]
/usr/bin/imqcmd -v
DESCRIPTIONimqcmd manages the Message Queue broker, including resources such as
connection services, physical destinations, durable subscriptions, and
transactions. The utility provides a number of subcommands for managing
these resources.
imqcmd supports many subcommands. Basic connection and authentication
is required for the execution of every imqcmd subcommand. Use the
-secure option to specify secure connections. Subcommands and their
corresponding arguments and options follow the imqcmd command on the
command line. See USAGE and OPTIONS.
OPTIONS
The following options are supported:
-b hostName:port Specify the name of the host on which the broker
instance is running and the port number it is
using.
The default value is localhost:7676. If you do
not specify the -b option, imqcmd uses the
default.
To specify port only, use: -b :7878. This is
equivalent to -b localhost:7878
To specify name only, use: -b somehost. This is
equivalent to -b somehost:7676.
-c clientID Specify the ID of the durable subscriber to a
topic.
-d topicName Specify the name of the topic.
Use this option with the list dur and destroy dur
subcommands.
-f Perform action without user confirmation.
Use this option with any subcommand.
-h Display usage help. Execute nothing else on the
command line.
-H Display usage help, attribute list, and examples.
Execute nothing else on the command line.
-int interval Specify the interval, in seconds, at which the
metrics bkr, metrics dst, and metrics svc subcom‐
mands display metrics output.
Use this option with the metrics subcommand.
-javahome Specify an alternate Java 2 compatible runtime to
use.
-m metricType Specify the type of metric information to diplay.
Use this option with the metrics bkr, metrics
dst, and metrics svc subcommands. The value of
metricType depends on whether the metrics are
generated for a destination, a service, or a bro‐
ker.
Use one of the following values to specify met‐
ricType:
ttl Total of messages in and out of the broker
(default)
rts Provides the same information as ttl, but
specifies the number of messages per sec‐
ond
cxn Connections, virtual memory heap, threads
The following command displays connection, VM
heap, and threads metric information for the
default broker instance (localhost:7676) every
five seconds:
imqcmd metrics bkr -m cxn -int 5
-msp numSamples Specify the number of samples the metrics bkr,
metrics dst, and metrics svc subcommands display
in the metrics output.
-n argumentName Specify the name of the subcommand argument.
Depending on the subcommand, this might be the
name of a service, a physical destination, a
durable subscription, or a transaction ID.
-o attribute=value Specify the value of an attribute. Depending on
the subcommand argument, this might be the
attribute of a broker, service, or destination.
-p password Specify the administrator password.
This option is deprecated. Use the -passfile
option instead.
-passfile Specify the administrator password.
-pst pauseType Specify whether producers, consumers, or both are
paused when pausing a destination.
Use this option with the pause dst subcommand.
Use one of the following values:
CONSUMERS Pause delivery of messages to con‐
sumers.
PRODUCERS Pause delivery of messages from pro‐
ducers.
ALL Pause delivery of messages to con‐
sumers and from producers.
If the -pst option is not specified, pauses both
consumers and producers (the equivalent of -pst
ALL).
-rtm timeout Specify the timeout period in seconds of an
imqcmd subcommand. The default value is 10.
-rtr numRetries Specify the number of retries attempted after an
imqcmd subcommand times out.
The default value is 5.
-s Silent mode. No output is displayed.
Use this option with any subcommand.
-secure Specify a secure administration connection to the
broker instance. You must first configure the
broker to enable a secure connection service.
Use this option whenever you want a secure commu‐
nication with the broker.
-svn serviceName Specify the service for which the connections are
listed.
Use this option with the list cxn subcommand.
-t destinationType Specify the type of a destination: t (topic) or q
(queue).
-tmp Include temporary destinations when listing des‐
tinations using the list dst subcommand.
-u name Specify the administrator user name.
If you omit this value, you are prompted for it.
-v Display version information. Execute nothing else
on the command line.
USAGE
Subcommands and Options
The following subcommands and associated arguments and options are sup‐
ported:
compact dst [-t type -n destName]
Compact the flat-file data store for the destination of the speci‐
fied type and name. If no type and name are specified, all destina‐
tions are compacted. Destinations must be paused before they can be
compacted.
commit txn -n transaction_id
Commit the specified transaction
create dst -t destinationType -n destName [-o attribute=value] [-o
attribute=value1]...
Create a destination of the specified type, with the specified
name, and the specified attributes. Destination names must contain
only alphanumeric characters (no spaces) and can begin with an
alphabetic character or the underscore character (_).
destroy dst -t destinationType -n destName
Destroy the destination of the specified type and name.
destroy dur -n subscrName -c client_id
Destroy the specified durable subscription for the specified Client
Identifier.
list cxn [-svn serviceName] [-b hostName:port]
List all connections of the specified service name on the default
broker or on a broker at the specified host and port. If the ser‐
vice name is not specified, all connections are listed.
list dst [-tmp]
List all destinations, with option of listing temporary destina‐
tions as well .
list dur -d destination
List all durable subscriptions for the specified destination.
list svc
List all connection services on the broker instance.
list txn
List all transactions, being tracked by the broker.
metrics bkr [-m metricType] [-int interval] [-msp numSamples]
Display broker metrics for the broker instance.
Use the -m option to specify the type of metric to display. Use one
of the following values to specify metricType:
ttl Specifies the total of messages in and out of the broker
(default) .
rts Provides the same information as ttl, but specifies the num‐
ber of messages per second.
cxn Connections, virtual memory heap, threads.
Use the -int option to specify the interval (in seconds) at which
to display the metrics. The default is 5 seconds.
Use the -msp option to specify the number of samples displayed in
the output. A value of -1 means an unlimited number. The default
value is -1.
metrics dst -t type -n destName [-m metricType] [-int interval] [-msp
numSamples]
Displays metrics information for the destination of the specified
type and name.
Use the -m option to specify the type of metrics to display. Use
one of the following values to specify metricType:
ttl Specifies the number of messages flowing in and out of the
broker and residing in memory.
rts Provides the same information as ttl, but specifies the num‐
ber of messages per second.
con Displays consumer related metrics.
dsk Displays disk usage metrics.
Use the -int option to specify the interval (in seconds) at which
to display the metrics. The default is 5 seconds.
Use the -msp option to specify the number of samples displayed in
the output. A value of -1 means an unlimited number. The default
value is 5.
metrics svc -n serviceName [-m metricType] [-int interval] [-msp num‐
Samples]
List metrics for the specified service on the broker instance. Use
the -m option to specify the type of metric to display. Use one of
the following values to specify metricType:
ttl Total of messages in and out of the broker (default)
rts Provides the same information as ttl, but specifies the num‐
ber of messages per second
cxn Connections, virtual memory heap, threads
Use the -int option to specify the interval (in seconds) at which
to display the metrics. The default is 5 seconds.
Use the -msp option to specify the number of samples displayed in
the output. A value of -1 means an unlimited number. The default
value is -1.
pause bkr
Pause the broker instance.
pause dst [-t type -n destName] [-pst pauseType]
Pause the delivery of messages to consumers (-pst CONSUMERS), or
from producers (-pst PRODUCERS), or both (-pst ALL), for the desti‐
nation of the specified type and name. If no destination type or
name are specified, all destinations are paused.
pause svc -n serviceName
Pause the specified service running on the broker instance. You
cannot pause the administative service.
purge dst -t destinationType -n destName
Purge messages at the destination with the specified type and name.
purge dur -n subscrName -c client_id
Purge all messages for the specified client identifier.
query bkr
List the current settings of properties of the broker instance.
Show the list of running brokers (in a multi-broker cluster) that
are connected to the specified broker.
query dst -t destinationType -n destName
List information about the destination of the specified type and
name.
query svc -n serviceName
Display information about the specified service running on the bro‐
ker instance.
query txn -n transaction_id
List information about the specified transaction.
reload cls
Forces all the brokers in a cluster to reload the imq.cluster.bro‐
kerlist property and update cluster information. This subcommand
only applies to broker clusters.
restart bkr
Shut down and restart the broker instance. This command restarts
the broker using the options specified when the broker was first
started. If you want different options to be in effect, you must
shut down the broker and then start it again, specifying the
options you want.
resume bkr
Resume the broker instance.
resume dst [-t type] [-n -destName]
Resumes the delivery of messages for the paused destination of the
specified type and name. If no destination type and name are speci‐
fied, all destinations are resumed.
resume svc -n serviceName
Resume the specified service running on the broker instance.
rollback txn -n transaction_id
Roll back the specified transaction.
shutdown bkr
Shut down the broker instance
update bkr -o attribute=value [-o attribute=value]...
Change the specified attributes for the broker instance.
update dst -t destinationType -n destName -o attribute=value [-o
attribute=value1]...
Update the value of the specified attributes at the specified des‐
tination..
update svc -n serviceName -o attribute=value [-o attribute=value1]...
Update the specified attribute of the specified service running on
the broker instance.
Attribute Value Pairs
You can specify attributes with the create and update subcommands.
Applicable attributes depend on the subcommand arguments.
The following attributes are supported:
Queue (dst):
maxTotalMsgBytes Value: Integer (maximum total size of mes‐
sages, in bytes)
Default: 0 (unlimited)
maxBytesPerMsg Value: Integer (maximum size of a single mes‐
sage, in bytes)
Default: 0 (unlimited)
maxNumMsgs Value: Integer (maximum total number of mes‐
sages)
Default: 0 (unlimited)
consumerFlowLimit Value: Integer Initial number of queued mes‐
sages sent to active consumers before load-
balancing starts A value of -1 means an
unlimited number.
Default: 1000
isLocalOnly Value: Boolean (destination limited to deliv‐
ering messages to local consumers only)
Default: false
limitBehavior Value: Specify how broker responds when mem‐
ory-limit is reached. Use one of the follow‐
ing values:
FLOW_CONTROL Slows down producers
REMOVE_OLDEST Purges oldest messages
REJECT_NEWEST Rejects the newest messages
Default: REJECT_NEWEST
localDeliveryPreferred Value: Boolean Specify messages be delivered
to remote consumers only if there are no con‐
sumers on the local broker. Requires that the
destination not be restricted to local-only
delivery (isLocalOnly = false)
Default: false
maxNumActiveConsumers Value: Integer (maximum number of active con‐
sumers in load-balanced delivery) A value of
-1 means an unlimited number.
Default: 1
maxNumBackupConsumers Value: Integer (maximum number of backup con‐
sumers in load-balanced delivery) A value of
-1 means an unlimited number.
Default: 0
maxNumProducers Value: (maximum total number of producers) A
value of -1 means an unlimited number.
Default: -1
useDMQ Specify whether a destination's dead messages
are discarded or put on the dead message
queue.
Default: true
Topic (dst):
consumerFlowLimit Value: Integer Maximum number of messages deliv‐
ered to a consumer in a single batch. A value of
-1 means an unlimited number.
Default: 1000
isLocalOnly Value: Boolean (destination limited to delivering
messages to local consumers only)
Default: false
limitBehavior Value: Specify how broker responds when memory-
limit is reached. Use one of the following values:
FLOW_CONTROL Slows down producers
REMOVE_OLDEST Purges the oldest messages
REJECT_NEWEST Rejects the newest messages
Default: REJECT_NEWEST
maxBytesPerMsg Value: Integer (maximum size of a single message,
in bytes)
Default: 0 (unlimited)
maxNumMsgs Value: Integer (maximum total number of messages)
A value of -1 means an unlimited number.
Default: -1
maxNumProducers Value: (maximum total number of producers)
Default: 0 (unlimited)
maxTotalMsgBytes Value: Integer (maximum total size of messages, in
bytes) A value of -1 means an unlimited number.
Default: -1
useDMQ Specify whether a destination's dead messages are
discarded or put on the dead message queue.
Default: true
Broker (bkr):
imq.autocreate.destination.useDMQ
Value: Boolean. Set the useDMQ attribute to true to enable all
autocreated physical destinations on a broker to use the dead mes‐
sage queue. Set the useDMQ attribute to false to disable all
autocreated physical destinations on a broker from using the dead
message queue.
Default: true
imq.autocreate.queue
Value: Boolean
Default: true
imq.autocreate.queue.maxNumActiveConsumers
Value: Integer (maximum number of consumers that can be active in
load-balanced delivery from an autocreated queue destination) A
value of -1 means an unlimited number.
Default: 1
imq.autocreate.queue.maxNumBackupConsumers
Value: Integer (maximum number of backup consumers that can take
the place of active consumers) A value of -1 means an unlimited
number.
Default: 0
imq.autocreate.topic
Value: Boolean
Default: true
imq.cluster.url
Value: String (location of cluster configuration file)
Default: none
imq.log.file.rolloverbytes
Value: Integer (maximum size of a log file, in bytes)
Default: 0 (no rollover based on size)
imq.log.file.rolloversecs
Value: Integer (maximum age of a log file, in seconds)
Default: 0 (no rollover based on age)
imq.log.level
Value: String (NONE, ERROR, WARNING, INFO)
Default: INFO
imq.message.max_size
Value: Integer (maximum size of a single message, in bytes)
Default: 70m
imq.portmapper.port
Value: Integer
Default: 7676
imq.system.max_count
Value: Integer (maximum total number of messages)
Default: 0 (no limit)
imq.system.max_size
Value: Integer (maximum total size of messages, in bytes)
Default: 0 (no limit)
Service (svc):
maxThreads Value: Integer (maximum threads assigned)
Default: Depends on service
minThreads Value: Integer (minimum threads assigned)
Default: Depends on service
port Value: Integer
Default: 0 (dynamically allocated)
EXAMPLES
Example 1 Shutting Down a Broker
The following command shuts down a broker for hostname myserver on port
7676:
mqcmd shutdown bkr -b myserver:7676
Example 2 Restarting a Broker
The following command restarts a broker for hostname myserver:
imqcmd restart bkr -b myserver
Example 3 Pausing a Service
The following command pauses a broker for hostname localhost on port
7676, with a serviceName of jms:
imqcmd pause svc -n jms -b :7676
Example 4 Resuming a Service
The following command resumes a service for hostname localhost on port
7676, with a serviceName of jms:
imqcmd resume svc -n jms -b myserver:7676
Example 5 Creating a Queue Destination
The following command creates a queue destination for hostname myserver
on port 7676, with a destName of myFQ, a queueDeliveryPolicy of
Failover, and a maxBytesPerMsg of 10000:
imqcmd create dst -n myFQ -t q -o "queueDeliveryPolicy=f" \
-o "maxBytesPerMsg=10000" -b myserver:7676
Example 6 Purging a Queue Destination
The following command purges a queue destination for hostname myserver
on port 7676, with a destName of myFQ:
imqcmd purge dst -n myFQ -t q -b myserver:7676
Example 7 Listing Destinations on a Broker
The following command lists destinations for hostname myserver on port
7676:
imqcmd list dst -b myserver:7676
Example 8 Updating a Portmapper Port
The following command updates a portmapper port on hostname myserver
from port 7676 to 7878:
imqcmd update bkr -o "imq.portmapper.port=7878"
Example 9 Updating the Maximum Number of Messages in the Queue
The following command updates the maximum number of messages in the
queue to 2000 for myserver on port 8080 with a destName of TestQueue:
imqcmd update dst -b myserver:8080 -n TestQueue -t q -o "maxNumMsgs=2000"
Example 10 Updating the Maximum Threads
The following command updates the maximum threads jms connection ser‐
vice to 200 for hostname localhost on port 7676:
imqcmd update svc -n jms -o "minThreads=200"
Example 11 Listing Durable Subscriptions
The following command lists durable subscriptions for a topic with
hostname localhost on port 7676 with a destName of myTopic:
imqcmd list dur -d myTopic
Example 12 Destroying Durable Subscriptions
The following command destroys subscriptions for hostname localhost on
port 7676 with a dursubName of myDurSub and a client_ID of
111.222.333.444:
imqcmd destroy dur -n myDurSub -c "111.222.333.444"
Example 13 Listing All Transactions
The following command lists all transactions on a broker with hostname
localhost on port 7676:
imqcmd list txn
Example 14 Displaying Information About a Transaction
The following command displays information about a transaction with
hostname localhost on port 7676, and a transactionID of 1234567890
imqcmd query txn -n 1234567890
Example 15 Committing a Transaction
The following command commits a transaction with hostname localhost on
port 7676, and a transactionID of 1234567890:
imqcmd commit txn -n 1234567890
ENVIRONMENT VARIABLES
The following environment variables affect the execution of this com‐
mand:
IMQ_JAVAHOME Specify the Java 2 compatible runtime. When this envi‐
ronment variable is not set it defaults to /usr/j2se.
EXIT STATUS
The following exit values are returned:
0 Successful completion.
>0 An error occurred.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Availability │SUNWiq │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOimqadmin(1M), imqbrokerd(1M), imqdbmgr(1M), imqkeytool(1M), imqob‐
jmgr(1M), imqusermgr(1M), attributes(5)
Sun Java System Message Queue Administrator's Guide
SunOS 5.11 7 Aug 2007 imqcmd(1M)