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 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 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, threads
The 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, a
physical 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 dst
SunOS 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.
AL 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 AL).
-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 transactionid
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. Destina-
tion 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.
SunOS 5.11 Last change: 7 Aug 2007 5
System Administration Commands imqcmd(1M)
destroy dur -n subscrName -c clientid
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 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 broker
instance. 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, 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.
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
AL), 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 clientid
Purge all messages for the specified client identifier.
query bkr
SunOS 5.11 Last change: 7 Aug 2007 8
System Administration Commands imqcmd(1M)
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 broker instance.
query txn -n transactionid
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 transactionid
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 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 Pairs
You 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 active
consumers before load-balancing
starts A value of -1 means an
unlimited number.
Default: 1000
isLocalOnly Value: Boolean (destination lim-
ited 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:
FLOWCONTROL Slows down pro-
ducers
REMOVEOLDEST Purges oldest
messages
REJECTNEWEST Rejects the
newest messages
Default: REJECTNEWEST
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 to
local-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 of
active consumers in load-balanced
delivery) A value of -1 means an
unlimited number.
Default: 1
maxNumBackupConsumers Value: Integer (maximum number of
backup consumers 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 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: false
SunOS 5.11 Last change: 7 Aug 2007 12
System Administration Commands imqcmd(1M)
limitBehavior Value: Specify how broker responds when
memory-limit is reached. Use one of the
following values:
FLOWCONTROL Slows down producers
REMOVEOLDEST Purges the oldest mes-
sages
REJECTNEWEST Rejects the newest
messages
Default: REJECTNEWEST
maxBytesPerMsg Value: Integer (maximum size of a sin-
gle message, in bytes)
Default: 0 (unlimited)
maxNumMsgs Value: Integer (maximum total number of
messages) 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 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
SunOS 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 attribute
to 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 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
SunOS 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.level
Value: String (NONE, EROR, WARNING, INFO)
Default: INFO
imq.message.maxsize
Value: Integer (maximum size of a single message, in
bytes)
Default: 70m
imq.portmapper.port
Value: Integer
Default: 7676
imq.system.maxcount
Value: Integer (maximum total number of messages)
Default: 0 (no limit)
imq.system.maxsize
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 Destination
The 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 Destination
The 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 messages
in 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 Threads
The 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 a
clientID 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 Transaction
The following command displays information about a transac-
tion with hostname localhost on port 7676, and a transac-
tionID 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 command:
IMQJAVAHOME 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)
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWiqu
SEE ALSO
imqadmin(1M), imqbrokerd(1M), imqdbmgr(1M), imqkeytool(1M),
imqobjmgr(1M), imqusermgr(1M), attributes(5)
Sun Java System Message Queue Administrator's Guide
SunOS 5.11 Last change: 7 Aug 2007 20
|
