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 subscriber to a topic.
-d topicName
Specify the name of the topic.
Use this option with the list dur and destroy dur sub-
commands.
-f Perform action without user confirmation.
Use this option with any subcommand.
-h Display usage help. Execute nothing else on the com-
mand line.
-H Display usage help, attribute list, and examples. Exe-
cute nothing else on the command line.
-int interval
Specify the interval, in seconds, at which imqcmd
displays broker metrics.
Use this option with the the metrics subcommand.
-javahome
Specify an alternate Java 2 compatible runtime to use.
-m metricType
Specify the type of metric information 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 number of messages per second
cxn Connections, virtual memory heap, threads
Use this option with the either the metrics bkr or metrics
svc subcommand. 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
-n argumentName
Specify the name of the subcommand argument. Depending
on the subcommand, this might be the name of a ser-
vice, 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.
If you omit this value, you are prompted for it.
-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 communica-
tion with the broker.
-t destinationType
Specify the type of a destination: t (topic) or q
(queue).
-tmp Include temporary destinations when listing destina-
tions 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:
commit txn -n transaction_id
Commit the specified transaction
[-o attribute= value1]...
create dst -t destinationType -n destName [-
o attribute=value]
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.
destroy dur -n subscrName -c client_id
Destroy the specified durable subscription for the
specified Client Identifier.
list dst [-tmp]
List all destinations, with option of listing tem-
porary destinations as well .
list dur -d destination
List all durable subscriptions for the specified des-
tination.
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]
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 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
metrics svc -n serviceName [-m metricType] [-int interval]
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 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.
pause bkr
Pause the broker instance.
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 identif-
ier.
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 speci-
fied broker.
query dst -t destinationType -n destName
List information about the destination of the speci-
fied type and name.
query svc -n serviceName
Display information about the specified service run-
ning 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 com-
mand restarts the broker using the options specified
when the broker was first started. If you want dif-
ferent 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 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.
attribute= value1]...
update dst -t destinationType -n destName -
o attribute=value [-o
Update the value of the specified attributes at the
specified destination..
attribute=value1]...
update svc -n serviceName -
o attribute=value [-o
Update the specified attribute of the specified ser-
vice 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):
queueDeliveryPolicy
Value: String (f = Failover, r = Round Robin, s = Sin-
gle)
Default: s
maxTotalMsgBytes
Value: Integer (maximum total size of messages, in
bytes)
Default: 0 (unlimited)
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)
Topic (dst):
maxBytesPerMsg
Value: Integer (maximum size of a single message, in
bytes)
Default: 0 (unlimited)
Broker (bkr):
imq.autocreate.queue
Value: Boolean
Default: true
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.queue.deliverypolicy
Value: String (f = Failover, r = Round Robin, s = Sin-
gle)
Default: s
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 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:
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
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 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:
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.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWiqu |
|_____________________________|_____________________________|
SEE ALSO
imqadmin(1M), imqbrokerd(1M), imqdbmgr(1M), imqkeytool(1M),
imqobjmgr(1M), imqusermgr(1M), attributes(5)
Sun ONE Message Queue Administrator's Guide
Man(1) output converted with
man2html