System Administration Commands imqcmd(1M)
NAME
imqcmd - manage Message Queue brokers
SYNOPSIS
/usr/bin/imqcmd subcommand argument [option...]
/usr/bin/imqcmd [-h | -H]
/usr/bin/imqcmd -v
DESCRIPTION
imqcmd 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 connec-
tions. Subcommands and their corresponding arguments andoptions 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:7878To specify name only, use: -b
somehost. This is equivalent to -b
somehost:7676.-c clientID Specify the ID of the durable sub-
scriber to a topic.SunOS 5.11 Last change: 7 Aug 2007 1
System Administration Commands imqcmd(1M)
-d topicName Specify the name of the topic.
Use this option with the list dur and destroy dur subcommands.-f Perform action without user confirma-
tion. 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 subcommands display metrics output.Use this option with the metrics sub-
command.-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 subcom-
mands. The value of metricType depends on whether the metrics are generated for a destination, a service, or a broker. Use one of the following values to specify metricType: ttl Total of messages in and out of the broker (default)SunOS 5.11 Last change: 7 Aug 2007 2
System Administration Commands imqcmd(1M)
rts Provides the same information as ttl, but specifies the number of messages per second cxn Connections, virtual memory heap, threadsThe following command displays connec-
tion, 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, aphysical destination, a durable sub-
scription, 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 des-
tination. Use this option with the pause dstSunOS 5.11 Last change: 7 Aug 2007 3
System Administration Commands imqcmd(1M)
subcommand. Use one of the following values:CONSUMERS Pause delivery of mes-
sages to consumers.PRODUCERS Pause delivery of mes-
sages from producers.ALL Pause delivery of mes-
sages to consumers 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 con-
nection to the broker instance. You must first configure the broker to enable a secure connection service. Use this option whenever you want a secure communication with the broker.-svn serviceName Specify the service for which the con-
nections are listed.Use this option with the list cxn sub-
command.SunOS 5.11 Last change: 7 Aug 2007 4
System Administration Commands imqcmd(1M)
-t destinationType Specify the type of a destination: t
(topic) or q (queue).-tmp Include temporary destinations when
listing destinations 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 supported:compact dst [-t type -n destName]
Compact the flat-file data store for the destination of
the specified type and name. If no type and name are specified, all destinations are compacted. Destinations must be paused before they can be compacted.commit txn -n transaction_id
Commit the specified transactioncreate dst -t destinationType -n destName [-o
attribute=value] [-o attribute=value1]...
Create a destination of the specified type, with thespecified name, and the specified attributes. Destina-
tion names must contain only alphanumeric characters (no spaces) and can begin with an alphabetic character orthe underscore character (_).
destroy dst -t destinationType -n destName
Destroy the destination of the specified type and name.SunOS 5.11 Last change: 7 Aug 2007 5
System Administration Commands imqcmd(1M)
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 hostand port. If the service name is not specified, all con-
nections are listed.list dst [-tmp]
List all destinations, with option of listing temporary destinations as well .list dur -d destination
List all durable subscriptions for the specified desti-
nation. 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 numSam-
ples] 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 speci-
fies the number of messages per second.SunOS 5.11 Last change: 7 Aug 2007 6
System Administration Commands imqcmd(1M)
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 unlim-
ited number. The default value is -1.
metrics dst -t type -n destName [-m metricType] [-int inter-
val] [-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 speci-
fies the number 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 unlim-
ited number. The default value is 5.metrics svc -n serviceName [-m metricType] [-int interval]
[-msp numSamples]
List metrics for the specified service on the brokerinstance. Use the -m option to specify the type of
metric to display. Use one of the following values to specify metricType:SunOS 5.11 Last change: 7 Aug 2007 7
System Administration Commands imqcmd(1M)
ttl Total of messages in and out of the broker (default)rts Provides the same information as ttl, but speci-
fies the number of messages per second cxn Connections, virtual memory heap, threadsUse 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 unlim-
ited 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 CONSU-
MERS), or from producers (-pst PRODUCERS), or both (-pst
ALL), for the destination 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 bkrSunOS 5.11 Last change: 7 Aug 2007 8
System Administration Commands imqcmd(1M)
List the current settings of properties of the brokerinstance. 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 broker 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.brokerlist 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 destina-
tion of the specified type and name. If no destination type and name are specified, all destinations are resumed.SunOS 5.11 Last change: 7 Aug 2007 9
System Administration Commands imqcmd(1M)
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 instanceupdate 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 destination..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 PairsYou can specify attributes with the create and update sub-
commands. Applicable attributes depend on the subcommand arguments. The following attributes are supported: Queue (dst): maxTotalMsgBytes Value: Integer (maximum total size of messages, in bytes) Default: 0 (unlimited)SunOS 5.11 Last change: 7 Aug 2007 10
System Administration Commands imqcmd(1M)
maxBytesPerMsg Value: Integer (maximum size of a single message, in bytes) Default: 0 (unlimited) maxNumMsgs Value: Integer (maximum total number of messages) Default: 0 (unlimited) consumerFlowLimit Value: Integer Initial number of queued messages sent to activeconsumers before load-balancing
starts A value of -1 means an
unlimited number. Default: 1000isLocalOnly Value: Boolean (destination lim-
ited to delivering messages to local consumers only) Default: false limitBehavior Value: Specify how broker respondswhen memory-limit is reached. Use
one of the following values:FLOW_CONTROL Slows down pro-
ducersREMOVE_OLDEST Purges oldest
messagesREJECT_NEWEST Rejects the
newest messagesDefault: REJECT_NEWEST
localDeliveryPreferred Value: Boolean Specify messages be delivered to remote consumers only if there are no consumers on the local broker. Requires that the destination not be restricted tolocal-only delivery (isLocalOnly =
false)SunOS 5.11 Last change: 7 Aug 2007 11
System Administration Commands imqcmd(1M)
Default: false maxNumActiveConsumers Value: Integer (maximum number ofactive consumers in load-balanced
delivery) A value of -1 means an
unlimited number. Default: 1 maxNumBackupConsumers Value: Integer (maximum number ofbackup consumers in load-balanced
delivery) A value of -1 means an
unlimited number. Default: 0 maxNumProducers Value: (maximum total number ofproducers) 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 mes-
sages delivered to a consumer in a sin-
gle batch. A value of -1 means an
unlimited number. Default: 1000 isLocalOnly Value: Boolean (destination limited to delivering messages to local consumers only) Default: falseSunOS 5.11 Last change: 7 Aug 2007 12
System Administration Commands imqcmd(1M)
limitBehavior Value: Specify how broker responds whenmemory-limit is reached. Use one of the
following values:FLOW_CONTROL Slows down producers
REMOVE_OLDEST Purges the oldest mes-
sagesREJECT_NEWEST Rejects the newest
messagesDefault: REJECT_NEWEST
maxBytesPerMsg Value: Integer (maximum size of a sin-
gle message, in bytes) Default: 0 (unlimited) maxNumMsgs Value: Integer (maximum total number ofmessages) A value of -1 means an unlim-
ited number.Default: -1
maxNumProducers Value: (maximum total number of produc-
ers) Default: 0 (unlimited) maxTotalMsgBytes Value: Integer (maximum total size ofmessages, 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: trueSunOS 5.11 Last change: 7 Aug 2007 13
System Administration Commands imqcmd(1M)
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 message queue. Set the useDMQ attributeto false to disable all autocreated physical destina-
tions 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 beactive 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 thatcan 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: noneSunOS 5.11 Last change: 7 Aug 2007 14
System Administration Commands imqcmd(1M)
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.levelValue: String (NONE, ERROR, WARNING, INFO)
Default: INFOimq.message.max_size
Value: Integer (maximum size of a single message, in bytes) Default: 70m imq.portmapper.port Value: Integer Default: 7676imq.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)SunOS 5.11 Last change: 7 Aug 2007 15
System Administration Commands imqcmd(1M)
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
SunOS 5.11 Last change: 7 Aug 2007 16
System Administration Commands imqcmd(1M)
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 DestinationThe following command creates a queue destination for host-
name 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 DestinationThe following command purges a queue destination for host-
name 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:SunOS 5.11 Last change: 7 Aug 2007 17
System Administration Commands imqcmd(1M)
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 messagesin the queue to 2000 for myserver on port 8080 with a dest-
Name of TestQueue:imqcmd update dst -b myserver:8080 -n TestQueue -t q -o "maxNumMsgs=2000"
Example 10 Updating the Maximum ThreadsThe following command updates the maximum threads jms con-
nection service 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 aclient_ID of 111.222.333.444:
imqcmd destroy dur -n myDurSub -c "111.222.333.444"
SunOS 5.11 Last change: 7 Aug 2007 18
System Administration Commands imqcmd(1M)
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 TransactionThe following command displays information about a transac-
tion with hostname localhost on port 7676, and a transac-
tionID of 1234567890imqcmd 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 command:IMQ_JAVAHOME Specify the Java 2 compatible runtime. When
this environment variable is not set it defaults to /usr/j2se. EXIT STATUS The following exit values are returned: 0 Successful completion. >0 An error occurred.SunOS 5.11 Last change: 7 Aug 2007 19
System Administration Commands imqcmd(1M)
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWiq ||_____________________________|_____________________________|
SEE ALSO
imqadmin(1M), imqbrokerd(1M), imqdbmgr(1M), imqkeytool(1M), imqobjmgr(1M), imqusermgr(1M), attributes(5) Sun Java System Message Queue Administrator's GuideSunOS 5.11 Last change: 7 Aug 2007 20