|
| Sun ONE Message Queue, Version 3.0.1 Administrator's Guide |
Chapter 6 Broker and Application Management
This chapter explains how to perform tasks related to managing the broker and the services it provides. Some of these tasks are independent of any particular client application. These include:
- controlling the broker's state: you can pause, resume, shutdown, and restart the broker.
- querying and updating broker properties
- querying and updating connection services
- allocating and managing resources
- managing connection services
Other broker tasks are performed on behalf of specific applications; these include managing physical destinations, durable subscriptions, and transactions:
- MQ messages are routed to their receivers or subscribers by way of broker destinations. You are responsible for creating these destinations on the broker.
- MQ allocates and maintains resources for durable subscribers even when clients that have durable subscriptions become inactive. You use the MQ Command tool to get information about durable subscriptions and to destroy durable subscriptions or purge their messages in order to save MQ resources.
- MQ transactions and distributed transactions are tracked by a broker. You might need to manually commit or roll back transactions if a failure takes place.
This chapter explains how you use the Command utility (imqcmd) to perform all these tasks. You can accomplish many of these same tasks by using the Administration Console, the graphical interface to the MQ message server. For more information, see Chapter 4, "Administration Console Tutorial."
Command Utility
The Command utility allows you to manage the broker and the services it provides. This section describes the basic imqcmd command syntax, provides a listing of subcommands, and summarizes imqcmd options. Subsequent sections explain how you use these commands to accomplish specific tasks.
Syntax of Command
The general syntax of the imqcmd command is as follows:
imqcmd subcommand argument [options]
imqcmd -h|H
imqcmd -vNote that if you specify the -v, -h, or -H options, no subcommands specified on the command line are executed. For example, if you enter the following command, version information is displayed but the restart subcommand is not executed.
imqcmd restart bkr -v
imqcmd Subcommands
The Command utility (imqcmd) includes the subcommands listed in Table 6-1:
Summary of imqcmd Options
Table 6-2 lists the options to the imqcmd command. For a discussion of their use, see the following task-based sections.
Table 6-2 imqcmd Options
Option
Description
-b hostName:port
Specifies the name of the broker's host and its port number. The default value is localhost:7676.
To specify port only: -b :7878
To specify name only: -b somehost-c clientID
Specifies the ID of the durable subscriber to a topic. For more information, see "Managing Durable Subscriptions".
-d topicName
Specifies the name of the topic. Used with the list dur and destroy dur subcommands. See "Managing Durable Subscriptions".
-f
Performs action without user confirmation.
-h
Displays usage help. Nothing else on the command line is executed.
-H
Displays usage help, attribute list, and examples. Nothing else on the command line is executed.
-int interval
Specifies the interval, in seconds, at which imqcmd displays broker metrics. (Used with the metrics subcommand.)
-javahome
Specifies an alternate Java 2 compatible runtime to use (default is to use the runtime bundled with the product).
-m metricType
Specifies the type of metric information to display. Type can be one of the following
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 metrics bkr or metrics svc subcommand. The following command displays cxn-type metrics for the default broker every five seconds.
imqcmd metrics bkr -m cxn -int 5
-n argumentName
Specifies 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
Specifies the value of an attribute. Depending on the subcommand argument, this might be the attribute of a broker (see "Querying and Updating Broker Properties"), service (see "Managing Connection Services"), or destination (see "Managing Destinations").
-secure
Specifies a secure administration connection to the broker using the ssladmin connection service (see "Step 4. Configuring and Running SSL-based Clients,""Command Utility (imqcmd)").
-p password
Specifies your (the administrator's) password. If you omit this value, you will be prompted for it.
-s
Silent mode. No output will be displayed.
-t destinationType
Specifies the type of a destination: t (topic) or q (queue).
-tmp
Displays temporary destinations.
-u name
Specifies your (the administrator's) name. If you omit this value, you will be prompted for it.
-v
Displays version information. Nothing else on the command line is executed.
You must specify the options for host name and port number (-b), user name (-u) password (-p), and secure connection (-secure) each time you issue a imqcmd subcommand. If you don't specify the host name and port number, it uses the default values. If you don't specify user name and password information, you will be prompted for them. If you don't specify -secure, then the connection will not be secure.
Prerequisites to Using imqcmd
In order to use imqcmd commands to manage the broker, you must do the following:
- Start the broker using the imqbrokerd command.
See "Starting a Broker". You can use the Command utility only to administer brokers that are already running; you cannot use it to start a broker.
- Specify the target broker using the -b option unless the broker is running on the local host, on port 7676.
- Specify the proper administrator user name and password. If you do not do this, you will be prompted for it. Either way, be aware that every operation you perform using imqcmd will be authenticated against a user repository.
When you install MQ, a default flat-file user repository is installed. The file is named IMQ_HOME/etc/passwd (/etc/imq/passwd on Solaris). The repository is shipped with two entries: one for an admin user and one for a guest user. These entries allow you to connect to the broker without doing any additional work. For example, if you are just testing MQ, you can run the utility using your default user name and password (admin/admin).
If you are setting up a production system, you will need to do some additional work to authenticate and authorize users. You also have the option of using an existing LDAP directory server for your user repository. For more information, see "Authenticating Users".
Examples
The following command lists the properties of the broker running on localhost at port 7676:
imqcmd query bkr -u admin -p admin
The following command lists the properties of the broker running on myserver at port 1564; the user's name is alladin, the user's password is abracadabra.
imqcmd query bkr -b myserver:1564 -u alladin -p abracadabra
Assuming that the user name alladin was assigned to the admin group, you will be connected as an admin client to the specified broker.
Controlling the Broker's State
After you start the broker, you can use the following imqcmd subcommands to control the state of the broker.
- Pausing the broker
Pausing the broker suspends the broker service threads which causes the broker to stop listening on the ports. You can then perform any administration tasks needed to regulate the flow of messages to the broker. For example, if a particular destination is bombarded with messages, you can pause the broker and take any of the following actions that might help you fix the problem: trace the source of the messages, limit the size of the destination, or destroy the destination.
The following command pauses the broker running on myhost at port 1588.
imqcmd pause bkr -b myhost:1588
- Resuming the broker
Resuming the broker reactivates the broker's service threads and the broker resumes listening on the ports. The following command resumes the broker running on localhost at port 7676.
imqcmd resume bkr
- Shutting down the broker
Shutting down the broker terminates the broker process. This is a graceful termination: the broker stops accepting new connections and messages, it completes delivery of existing messages, and it terminates the broker process. The following command shuts down the broker running on ctrlsrv at port 1572
imqcmd shutdown bkr -b ctrlsrv:1572
- Restarting the broker
Shuts down and restarts the broker. The following command restarts the broker running on localhost at port 7676:
imqcmd restart bkr
Table 6-3 summarizes the imqcmd subcommands used to control the broker. Remember that you must specify the broker host name and port number unless you are targeting the broker running on localhost at port 7676.
Querying and Updating Broker Properties
The Command utility includes subcommands that you can use to get information about the broker and to update broker properties. Table 6-4 lists these subcommands.
Table 6-4 imqcmd Subcommands Used to Get Information and to Update Broker
Subcommand Syntax
Description
query bkr -b hostName:port
Lists the current settings of properties of the default broker or a broker at the specified host and port. Also shows the list of running brokers (in a multi-broker cluster) that are connected to the specified broker.
reload cls
Applies only to broker clusters. Forces all the brokers in a cluster to reload the imq.cluster.brokerlist property and update cluster information. See "Adding Brokers to Clusters" for more information.
update bkr [-b hostName:port]
-o attribute=value
[-o attribute=value1]...
Changes the specified attributes for the default broker or a broker at the specified host and port.
metrics bkr [-b hostName:port]
[-m metricType]
[-int interval]
Displays broker metrics for the default broker or a broker at the specified host and port.
Use the -m option to specify the type of metric to display:
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,
threadsUse the -int option to specify the interval (in seconds) at which to display the metrics. The default is 5 seconds
Remember that you must specify the broker host name and port number when using any of the subcommands listed in Table 6-4 unless you are targeting the broker running on localhost at port 7676
Querying a Broker
To query and display information about a single broker, use the query subcommand. For example,
imqcmd query bkr
This produces output like the following:
%imqcmd query bkr
Querying the broker specified by:
-------------------------
Host Primary Port
-------------------------
localhost 7676
Auto Create Queues true
Auto Create Topics true
Auto Created Queue Delivery Policy Round Robin
Cluster Broker List (active) myhost/192.18.116.221:7676
Cluster Broker List (configured)
Cluster Master Broker
Cluster URL
Current Number of Messages in System 0
Current Size of Messages in System 0
Instance Name imqbroker
Log Level INFO
Log Rollover Interval (seconds) 604800
Log Rollover Size (bytes) 0 (unlimited)
Max Message Size 70m
Max Number of Messages in System 0 (unlimited)
Max Size of Messages in System 0 (unlimited)
Primary Port 7676
Version 3.0
Successfully queried the broker.
Updating a Broker
You can use the update subcommand to update any of the broker properties listed in Table 6-5. Note that updates to the broker are automatically written to the broker's instance configuration file.
Table 6-5 Broker Properties
Properties
Description
imq.autocreate.queue
Specifies whether a broker is allowed to auto-create a queue destination. True by default.
imq.autocreate.topic
Specifies whether a broker is allowed to auto-create a topic destination. True by default.
imq.queue.deliverypolicy
Specifies the default delivery policy of auto-created queues. Values are: s (single),
r (round-robin), or f (failover). Default is s.imq.cluster.url
Specifies the location of the cluster configuration file. For more information, see"Cluster Configuration Properties".
imq.log.level
Specifies the log level as one of the following: NONE, ERROR, WARNING, INFO. Default is INFO.
imq.log.file.rolloversecs
The age (in seconds) before the log file is rolled over. A value of 0 means no rollover based on the age of the file. Default is 604800 (7 days).
imq.log.file.rolloverbytes
Specifies the maximum size of the log file before it is rolled over. A value of 0 means no rollover based on file size. Default is 0.
imq.message.max_size
Specifies the maximum size of a message in bytes. Default is 70m.
imq.system.max_count
Specifies the maximum number of messages in memory and disk. A value of 0 means no limit. Default is 0.
imq.system.max_size
Specifies the maximum total size of messages in memory and disk. A value of 0 means no limit. Default is 0.
imq.portmapper.port
Specifies the number of the port mapper port. Default is 7676.
For example, the following command changes the default delivery policy for queues from single to round-robin.
imqcmd update bkr -o "imq.queue.deliverypolicy=r"
Managing Connection Services
The Command utility includes a number of subcommands that allows you to do the following
- list available connection services
- display information about a particular service
- update the attributes of a service
- pause and resume services
For an overview of MQ connection services, see "Connection Services".
Table 6-6 lists the imqcmd subcommands that control connection services. If no host name or port is specified, they are assumed to be localhost, 7676.
Table 6-6 imqcmd Subcommands Used to Manage Connection Services
Subcommand Syntax
Description
list svc [-b hostName:port]
Lists all connection services on the default broker or on a broker at the specified host and port.
metrics svc -n serviceName
[-b hostName:port]
[-m metricType] [-int interval]
Lists metrics for the specified service on the default broker or on a broker at the specified host and port.
Use the -m option to specify the type of metric to display:
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 the -int option to specify the interval (in seconds) at which to display the metrics. The default is 5 seconds.
query svc -n serviceName
[-b hostName:port]
Displays information about the specified service running on the default broker or on a broker at the specified host and port.
pause svc -n serviceName
[-b hostName:port]
Pauses the specified service running on the default broker or on a broker at the specified host and port. You cannot pause the admin service.
resume svc -n serviceName
[-b hostName:port]
Resumes the specified service running on the default broker or on a broker at the specified host and port.
update svc -n serviceName
[-b hostName:port]
-o attribute=value
[-o attribute=value1]...
Updates the specified attribute of the specified service running on the default broker or on a broker at the specified host and port. For a description of service attributes, see Table 6-8.
A broker supports communication with both application clients and administration clients. The connection services currently available from an MQ broker are shown in Table 6-7. The values in the Service Name column are the values you use to specify a service name for the -n option. (As shown in the table, each service is specified by the service type it uses—NORMAL (JMS) or ADMIN—and an underlying transport layer.)
Listing Connection Services
To list available connection services on a broker, use a command like the following:
imqcmd list svc [-b hostName:portNumber]
For example, the following command lists the services available for the broker running on the host MyServer on port 6565.
imqcmd list svc -b MyServer:6565
The following command lists all services on the broker running on localhost at port 7676:
imqcmd list svc
The command will output information like the following:
Listing all the services on the broker specified by:
Host Primary Port
localhost 7676
Service Name Port Number Service State
admin 33984 (dynamic) RUNNING
httpjms UNKNOWN
httpsjms - UNKNOWN
jms 33983 (dynamic) RUNNING
ssladmin dynamic UNKNOWN
ssljms dynamic UNKNOWN
Successfully listed services.
Querying and Updating Service Properties
To query and display information about a single service, use the query subcommand. For example,
imqcmd query svc -n jms
This produces output like the following:
Querying the service where:
Service Name
jms
On the broker specified by:
Host Primary Port
localhost 7676
Current Number of Allocated Threads 120
Current Number of Connections 20
Max Number of Threads 1000
Min Number of Threads 50
Port Number 42019 (dynamic)
Service Name jms
Service State RUNNING
Successfully queried the service.
You can use the update subcommand to change the value of one or more of the service attributes listed in Table 6-8.
The following command changes the minimum number of threads assigned to the jms service to 20.
imqcmd update svc -n jms -o "minThreads=20"
Pausing and Resuming a Service
To pause any service other than the admin service (which cannot be paused), use a command like the following:
imqcmd pause svc -n serviceName
To resume a service, use a command like the following:
imqcmd resume svc -n serviceName
Managing Destinations
All MQ messages are routed to their consumer clients by way of destinations, queues and topics, created on a particular broker. You are responsible for managing these destinations on the broker. This involves using the Command utility to create and destroy destinations, to list destinations, to display information about destinations, and to purge messages. For an introduction to destinations, see "Physical Destinations".
Table 6-9 provides a summary of the imqcmd destination subcommands. Remember to specify the host name and port of the broker if this is not the default (localhost:7676) broker.
Table 6-9 imqcmd Subcommands Used to Manage Destinations
Subcommand
Description
list dst [-tmp]
Lists all destinations, with option of listing temporary destinations as well (see "Temporary Destinations").
create dst -t type
-n destName
[-o attribute=value]
[-o attribute=value1]...
Creates 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 character "_"
destroy dst -t type
-n destName
Destroys the destination of the specified type and name.
purge dst -t type
-n destName
Purges messages at the destination with the specified type and name.
query dst -t type
-n destName
Lists information about the destination of the specified type and name.
update dst -t type
-n destName
-o attribute=value
[-o attribute=value1]...
Updates the value of the specified attributes at the specified destination.
The attribute name may be any of the attributes described in Table 6-10.
Creating Destinations
When creating a destination, you must specify its type (topic or queue) and, if needed, specify values for the destination's attributes. Default values for these attributes are set in the broker's configuration file (see "Configuration Files".)
Destroying a destination purges all messages at that destination and removes it from the broker; the operation is not reversible.
Table 6-10 describes the attributes that can be set for each type of destination when you create the destination.
- To create a queue destination, enter a command like the following:
imqcmd create dst -n myQueue -t q -o "queueDeliveryPolicy=f"
Note that a destination name must be a valid Java identifier.
- To create a topic destination, enter a command like the following:
imqcmd create dst -n myTopic -t t -o "maxBytesPerMsg=5000"
Getting Information About Destinations
To get information about the current value of a destination's attributes, use a command like the following:
imqcmd query dst -t q -n XQueue
You can then use the update imqcmd subcommand to change the values of one or more attributes.
To list all destinations on a particular broker, say the broker running on myHost at port 4545, use a command like the following:
imqcmd list dst -b myHost:4545
The list command can optionally include temporary destinations (using the -tmp option). These are destinations created by client applications that need a destination at which to receive replies to messages sent to other clients (see "Temporary Destinations"). You cannot destroy these destinations; they can only be destroyed by API calls made by the client application when there are no more active message consumers.
Updating Destinations
You can change the attributes of a destination by using the update dst subcommand and the -o option to specify the attribute to update. You can use the -o option more than once if you want to update more than one attribute. For example, the following command changes the maxBytesPerMsg attribute to 1000 and the MaxNumMsgs to 2000:
imqcmd update dst -t q -n myQueue -o "maxBytesPerMsg=1000"
-o maxNumMsgs=2000See Table 6-10 for a list of the attributes that you can update.
You cannot use the update dst subcommand to update the type of a destination or to update the queue delivery policy for a queue.
Purging Destinations
You can purge all messages currently queued at a destination. Purging a destination means that all messages queued at the physical destination are deleted. You might want to purge messages when the messages accumulated at a destination are taking up too much of the system's resources. This might happen when a queue does not have any registered consumer clients and is receiving many messages. It might also happen if inactive durable subscribers to a topic do not become active. In both cases, messages are held unnecessarily.
To purge messages at a destination, enter commands like the following:
imqcmd purge dst -n myQueue -t q
imqcmd purge dst -n myTopic -t t
In the case where you have shut down the broker and do not want old messages to be delivered when you restart it, use the reset subcommand of the imqbrokerd command to purge stale messages; for example:
imqbrokerd -reset messages
This saves you the trouble of purging destinations after restarting the broker.
Destroying Destinations
To destroy a destination, enter a command like the following:
imqcmd destroy dst -t q -n myQueue
Managing Durable Subscriptions
You might need to use imqcmd subcommands to manage a broker's durable subscriptions. A durable subscription is a subscription to a topic that is registered by a client as durable; it has a unique identity and it requires the broker to retain messages for that subscription even when its consumer becomes inactive. Normally, the broker may only delete a message held for a durable subscriber when the message expires.
Table 6-12 provides a summary of the imqcmd durable subscription subcommands. Remember to specify the host name and port of the broker if this is not the default (localhost:7676) broker.
Table 6-11 imqcmd Subcommands Used to Manage Durable Subscriptions
Subcommand
Description
list dur -d destination
Lists all durable subscriptions for the specified destination.
destroy dur -n subscrName
-c client_id
Destroys the specified durable subscription for the specified Client Identifier (see "Client Identifiers").
purge dur -n subscrName
-c client_id
Purges all messages for the specified Client Identifier (see "Client Identifiers").
For example, the following command lists all durable subscriptions to the topic SPQuotes
imqcmd list dur -d SPQuotes
For each durable subscription to a topic, the list subcommand returns the name of the durable subscription, the client ID of the user, the number of messages queued to this topic, and the state of the durable subscription (active/inactive). For example:
Listing all the durable subscriptions on the topic myTopic
on the broker specified by:
-------------------------
Host Primary Port
-------------------------
localhost 7676
Name Client ID Number of Durable Sub
Messages State
----------------------------------------------------------------
myDurable myClientID 1 INACTIVE
Successfully listed durable subscriptions.
You can use the information returned from the list command to identify a durable subscription you might want to destroy or for which you want to purge messages. Use the name of the subscription and the client ID to identify the subscription. For example:
imqcmd destroy dur -n myDurable -c myClientID
Managing Transactions
All transactions initiated by client applications are tracked by the broker. These can be simple MQ transactions or distributed transactions managed by an XA resource manager (see "Local Transactions"). All transaction have an MQ transaction ID—a 64 bit number that uniquely identifies a transaction on the broker. Distributed transactions also have a distributed transaction ID (XID) assigned by the distributed transaction manager—up to 128 bytes long. MQ maintains the association of an MQ transaction ID with an XID.
For distributed transactions, in cases of failure, it is possible that transactions could be left in a PREPARED state without ever being committed. Hence, as an administrator you might need to monitor and then roll back or commit transactions left in a prepared state.
Table 6-12 provides a summary of the imqcmd transactions subcommands. Remember to specify the host name and port of the broker if this is not the default (localhost:7676) broker.
For example, the following command lists all transactions in a broker.
imqcmd list txn
For each transaction, the list subcommand returns the transaction ID, state, user name, number of messages or acknowledgements, and creation time. For example:
Listing all the transactions on the broker specified by:
-------------------------
Host Primary Port
-------------------------
localhost 7676
---------------------------------------------------------------
Transaction ID State User name # Msgs/ Creation time
# Acks
---------------------------------------------------------------
64248349708800 PREPARED guest 4/0 1/30/02 10:08:31 AM
64248371287808 PREPARED guest 0/4 1/30/02 10:09:55 AM
Successfully listed transactions.
The command shows all transactions in the broker, both local and distributed. You can only commit or roll back transactions in the PREPARED state. You should only do so if you know that the transaction has been left in this state by a failure and is not in the process of being committed by the distributed transaction manager.
For example, if the broker's auto-rollback property is set to false (see Table 2-4), then you have to manually commit or roll back transactions found in a PREPARED state at broker startup.
The list subcommand also shows the number of messages that were produced in the transaction and the number of messages that were acknowledged in the transaction (#Msgs/#Acks). These messages will not be delivered and the acknowledgements will not be processed until the transaction is committed.
The query subcommand lets you see the same information plus a number of additional values: the Client ID, connection identification, and distributed transaction ID (XID). For example,
imqcmd query txn -n 64248349708800
produces the following output:
Querying the transaction where:
-------------------------
Transaction ID
-------------------------
64248349708800
On the broker specified by:
-------------------------
Host Primary Port
-------------------------
localhost 7676
Client ID
Connection guest@192.18.116.219:62209->jms:62195
Creation time 1/30/02 10:08:31 AM
Number of acknowledgements 0
Number of messages 4
State PREPARED
Transaction ID 64248349708800
User name guest
XID
6469706F6C7369646577696E6465723130313234313431313030373230
Successfully queried the transaction.
The commit and rollback subcommands can be used to commit or roll back a distributed transaction. As mentioned previously, only a transaction in the PREPARED state can be committed or rolled back. For example:
imqcmd commit txn -n 64248349708800
It is also possible to configure the broker to automatically roll back transactions in the PREPARED state at broker startup. See the imq.transaction.autorollback property in Table 2-4 for more information.