|
| |
| Sun Java System Message Queue 3 2005Q1 Administration Guide | |
Chapter 5
Managing a BrokerThis chapter explains how to perform basic tasks related to managing the broker and its services. This chapter has the following sections:
This chapter does not cover all topics related to managing a broker. Additional large topics are covered in the following separate chapters:
- Management of physical destinations on the broker. For information about topics such as how to create, display, update and destroy physical destinations, and how to use the dead message queue, see Chapter 6, "Managing Physical Destinations."
- Setting up security for the broker. For information about topics such as user authentication, access control, encryption, password files, and audit logging, see Chapter 7, "Managing Security."
PrerequisitesYou use the imqcmd and imqusermgr commands to manage the broker. Before managing the broker, you must do the following:
- Start the broker using the imqbrokerd command. You cannot use the other commands until a broker is running.
- Determine whether you want to set up a Message Queue administrative user or use the default account. You must specify a user name and password to use management commands.
When you install Message Queue, a default flat-file user repository is installed. The repository is shipped with two default entries: an admin user and a guest user. If you are testing Message Queue, you can use the default user name and password (admin/admin) to run the imqcmd utility.
If you are setting up a production system, you must set up authentication and authorization for administrative users. See Chapter 7, "Managing Security" for information on setting up a file-based user repository or configuring the use of an LDAP directory server. In a production environment, it is a good security practice to use a nondefault user name and password.
- Set up and enable the ssladmin service on the target broker instance, if you want to use a secure connection to the broker. For more information, see Working With an SSL-Based Service.
Using the imqcmd Command UtilityThe imqcmd command utility enables you to manage the broker and its services.
Reference information about the syntax, subcommands, and options of the imqcmd command is in Chapter 13, "Command Reference". Reference information for use in managing physical destinations is in a separate chapter, Chapter 15, "Physical Destination Property Reference".
Specifying the User Name and Password
Because each imqcmd command is authenticated against the user repository, it requires a user name and password. The only exceptions are as follows:
Specifying the User Name
Use the -u option to specify an administrative user name. If you omit the user name, the command prompts you for it.
To make the examples in this chapter easy to read, the default user name admin is shown as the argument to the -u option. In a production environment, you would use a custom user name.
Specifying the Password
Specify the password by one of the following methods:
- Create a password file (passfile) and enter the password into that file. On the command line, use the -passfile option to provide the name of the passfile.
- Let the command prompt you for the password. This is the most secure method of specifying a password, unless other people can see what you are typing.
In previous versions of Message Queue, you could use the -p option to specify a password on the command line. This option is being deprecated and will be removed in a future version.
Specifying the Broker Name and Port
The default broker for imqcmd is one that is running on the local host, and the default port is 7676.
If you are issuing a command to a broker running on a remote host or to a nondefault port, or both, you must use the -b option to specify the broker’s host and port.
Examples
The examples in this section illustrate how to use imqcmd.
The first example lists the properties of the broker running on localhost at port 7676, so the -b option is unnecessary. The command uses the default administrative user name (admin) and omits the password, so that the command prompts for it.
imqcmd query bkr -u admin
The following example lists the properties of the broker running on myserver at port 1564. The user name is aladdin. This command requires that the user repository is updated so that the user name aladdin is assigned to the admin group.
imqcmd query bkr -b myserver:1564 -u aladdin
The following example lists the properties of the broker running on localhost at port 7676. The initial timeout for the command is set to 20 seconds and the number of retries after timeout is set to 7. The user’s password is in a password file called myPassfile, located in the current directory at the time the command is invoked.
imqcmd query bkr -u admin -passfile myPassfile -rtm 20 -rtr 7
For a secure connection to the broker, these examples could include the -secure option. The -secure option causes imqcmd to use the ssladmin service, if the service has been configured and started.
Displaying HelpTo display help on the imqcmd command utility, use the -h or -H option, and do not use a subcommand. You cannot get help about specific subcommands.
For example, the following command displays help about imqcmd:
imqcmd -H
If you enter a command line that contains the -h or -H option in addition to a subcommand or other options, the command utility processes only the -h or -H option. All other items on the command line are ignored.
Displaying the Product VersionTo display the Message Queue product version, use the -v option. For example:
imqcmd -v
If you enter a command line that contains the -v option in addition to a subcommand or other options, the command utility processes only the -v option. All other items on the command line are ignored.
Displaying Broker InformationTo query and display information about a single broker, use the query bkr subcommand.
This is the syntax of the query bkr subcommand:
imqcmd query bkr -b hostName:port
This subcommand lists the current settings of properties of the default broker or a broker at the specified host and port. It also shows the list of running brokers (in a multi-broker cluster) that are connected to the specified broker.
For example:
imqcmd query bkr -u admin
After prompting you for the password, the command produces output like the following:
Updating Broker PropertiesYou can use the update bkr subcommand to update the following broker properties:
- imq.autocreate.queue
- imq.autocreate.topic
- imq.autocreate.queue.maxNumActiveConsumers
- imq.autocreate.queue.maxNumBackupConsumers
- imq.cluster.url
- imq.destination.DMQ.truncateBody
- imq.destination.logDeadMsgs
- imq.log.level
- imq.log.file.rolloversecs
- imq.log.file.rolloverbytes
- imq.system.max_count
- imq.system.max_size
- imq.message.max_size
- imq.portmapper.port
This is the syntax of the update bkr subcommand:
imqcmd update bkr [-b hostName:port]-o attribute=value [-o attribute=value1]…
The subcommand changes the specified attributes for the default broker or a broker at the specified host and port.
The properties are described in Chapter 14, "Broker Properties Reference."
For example, the following command turns off the auto-creation of queue destinations:
imqcmd update bkr -o “imq.autocreate.queue=false” -u admin
Pausing and Resuming a BrokerAfter you start the broker, you can use imqcmd subcommands to control the state of the broker.
Pausing a Broker
Pausing a broker suspends the broker’s connection service threads, which causes the broker to stop listening on the connection ports. As a result, the broker will no longer be able to accept new connections, receive messages, dispatch messages.
However, pausing a broker does not suspend the admin connection service, letting you perform administration tasks needed to regulate the flow of messages to the broker. For example, if a particular physical destination is bombarded with messages, you can pause the broker and take actions that might help you fix the problem, such as:
Pausing a broker also does not suspend the cluster connection service. However message delivery within a cluster depend on the delivery functions performed by the different brokers in the cluster.
This is the syntax of the pause bkr subcommand:
imqcmd pause bkr [-b hostName:port]
The command pauses the default broker or a broker at the specified host and port.
The following command pauses the broker running on myhost at port 1588.
imqcmd pause bkr -b myhost:1588 -u admin
You can also pause individual connection services and individual physical destinations. For more information, see Pausing and Resuming a Connection Service and Pausing and Resuming Physical Destinations.
Resuming a Broker
Resuming a broker reactivates the broker’s service threads and the broker resumes listening on the ports.
This is the syntax of the resume bkr subcommand:
imqcmd resume bkr [-b hostName:port]
The subcommand resumes the default broker or a broker at the specified host and port.
The following command resumes the broker running on localhost at port 7676.
imqcmd resume bkr -u admin
Shutting Down and Restarting a BrokerShutting down the broker gracefully terminates the broker process. The broker stops accepting new connections and messages, completes delivery of existing messages, and terminates the broker process.
This is the syntax of the shutdown bkr subcommand:
imqcmd shutdown bkr [-b hostName:port]
The subcommand shuts down the default broker or a broker at the specified host and port.
The following command shuts down the broker running on ctrlsrv at port 1572:
imqcmd shutdown bkr -b ctrlsrv:1572 -u admin
You can shut down and restart the broker. This is the syntax of the restart bkr subcommand:
imqcmd restart bkr [-b hostName:port]
The subcommand shuts down and restarts the default broker or a broker at the specified host and port, using the options specified when the broker first started. To choose different options, shut down the broker and then restart it, specifying the options you want.
The following command restarts the broker running on localhost at port 7676:
imqcmd restart bkr -u admin
Displaying Broker MetricsTo display metrics information about a broker, use the metrics bkr subcommand.
This is the syntax of the metrics bkr subcommand:
imqcmd metrics bkr [-b hostName:port]
[-m metricType] [-int interval] [-msp numSamples]The subcommand displays broker metrics for the default broker or a broker at the specified host and port.
Use the -m option to specify one of the following metric types to display:
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. The default is an unlimited number (infinite).
For example, to get the rate of message flow into and out of the broker at ten second intervals:
imqcmd metrics bkr -m rts -int 10 -u admin
This command produces output like the following:
--------------------------------------------------------
Msgs/sec Msg Bytes/sec Pkts/sec Pkt Bytes/sec
In Out In Out In Out In Out
--------------------------------------------------------
0 0 27 56 0 0 38 66
10 0 7365 56 10 10 7457 1132
0 0 27 56 0 0 38 73
0 10 27 7402 10 20 1400 8459
0 0 27 56 0 0 38 73
For a more detailed description of the use of imqcmd to report broker metrics, see Broker-wide Metrics.
Managing Connection ServicesThe Command utility includes subcommands that allow you to perform the following connection service management tasks:
A broker supports connections from both application clients and administration clients. The connection services currently available from a Message Queue broker are shown in Table 5-1. 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 associated with a service type it uses (NORMAL for application clients or ADMIN for administration clients) and an underlying transport protocol.
Table 5-1 Connection Services Supported by a Broker
Service Name
Service Type
Protocol Type
jms
NORMAL
tcp
ssljms (Enterprise Edition)
NORMAL
tls (SSL-based security)
httpjms (Enterprise Edition)
NORMAL
http
httpsjms (Enterprise Edition)
NORMAL
https (SSL-based security)
admin
ADMIN
tcp
ssladmin (Enterprise Edition)
ADMIN
tls (SSL-based security)
Listing Connection Services
To list available connection services on a broker, use the list svc subcommand.
This is the syntax of the list svc subcommand:
imqcmd list svc [-b hostName:port]
The subcommand lists all connection services on the default broker or on a broker at the specified host and port.
Use the subcommand in a command line like the following:
imqcmd list svc [-b hostName:portNumber] -u admin
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 -u admin
The following command lists all services on the broker running on localhost at port 7676:
imqcmd list svc -u admin
The command will output information like the following:
------------------------------------------------
Service Name Port Number Service State
------------------------------------------------
admin 41844 (dynamic) RUNNING
httpjms - UNKNOWN
httpsjms - UNKNOWN
jms 41843 (dynamic) RUNNING
ssladmin dynamic UNKNOWN
ssljms dynamic UNKNOWN
Displaying Connection Service Information
To query and display information about a single service, use the query subcommand.
This is the syntax for the query svc subcommand:
imqcmd query svc -n serviceName [-b hostName:port]
The subcommand information about the specified service running on the default broker or on a broker at the specified host and port.
For example:
imqcmd query svc -n jms -u admin
After prompting for the password, the command produces output like the following:
Service Name jms
Service State RUNNING
Port Number 60920 (dynamic)
Current Number of Allocated Threads 0
Current Number of Connections 0
Min Number of Threads 10
Max Number of Threads 1000
Updating Connection Service Properties
You can use the update subcommand to change the value of one or more of the service properties listed in Table 5-2.
Table 5-2 Connection Service Properties Updated by imqcmd
Property
Description
port
The port assigned to the service to be updated (does not apply to httpjms or httpsjms). A value of 0 means the port is dynamically allocated by the Port Mapper.
minThreads
The minimum number of threads assigned to the service.
maxThreads
The maximum number of threads assigned to the service.
This is the syntax of the update subcommand:
imqcmd update svc -n serviceName [-b hostName:port]
-o attribute=value [-o attribute=value1]…This subcommand 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 Connection Service Properties.
The following command changes the minimum number of threads assigned to the jms service to 20.
imqcmd update svc -n jms -o “minThreads=20” -u admin
Displaying Connection Service Metrics
To display metrics information about a single service, use the metrics subcommand.
This is the syntax of the metrics subcommand:
imqcmd metrics svc -n serviceName [-b hostName:port] [-m metricType]
[-int interval] [-msp numSamples]The subcommand displays 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 Displays metrics on messages and packets flowing into and out of the broker by way of the specified connection service. (default metric type)
- rts Displays metrics on rate of flow of messages and packets into and out of the broker (per second) by way of the specified connection service.
- cxn Displays connections, virtual memory heap, and 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. The default is an unlimited number (infinite).
For example, to get cumulative totals for messages and packets handled by the jms connection service:
imqcmd metrics svc -n jms -m ttl -u admin
After prompting for the password, the command produces output like the following:
-------------------------------------------------
Msgs Msg Bytes Pkts Pkt Bytes
In Out In Out In Out In Out
-------------------------------------------------
164 100 120704 73600 282 383 135967 102127
657 100 483552 73600 775 876 498815 149948
For a more detailed description of the use of imqcmd to report connection service metrics, see Connection Service Metrics.
Pausing and Resuming a Connection Service
To pause any service other than the admin service (which cannot be paused), use the pause svc and resume svc subcommands.
This is the syntax of the pause svc subcommand:
imqcmd pause svc -n serviceName [-b hostName:port]
The subcommand 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.
Use a command line like the following:
imqcmd pause svc -n serviceName -u admin
Pausing a service has the following effects:
- The broker stops accepting new client connections on the paused service. If a Message Queue client attempts to open a new connection, it will get an exception.
- All the existing connections on the paused service are kept alive, but the broker suspends all message processing on such connections until the service is resumed. (For example, if a client attempts to send a message, the send() method will block until the service is resumed.)
- The message delivery state of any messages already received by the broker is maintained. (For example, transactions are not disrupted and message delivery will resume when the service is resumed.)
To resume a service, use the resume svc subcommand.
This is the syntax of the resume svc subcommand:
imqcmd resume svc -n serviceName[-b hostName:port]
The subcommand resumes the specified service running on the default broker or on a broker at the specified host and port.
Use a command line like the following:
imqcmd resume svc -n serviceName -u admin
Getting Information About ConnectionsThe Command utility includes subcommands that allow you to list and get information about connections.
The list cxn subcommand lists all connections of a specified service name. This is the syntax of the list cxn subcommand:
imqcmd list cxn [-svn serviceName] [-b hostName:port]
The subcommand lists 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 connections are listed.
For example:
imqcmd list cxn -u admin
After prompting for the password, the command produces output like the following:
Listing all the connections on the broker specified by:
-----------------------------------
Host Primary Port
------------------------------------
localhost 7676
---------------------------------------------------------------------------
Connection ID User Service Producers Consumers Host
---------------------------------------------------------------------------
1964412264455443200 guest jms 0 1 127.0.0.1
1964412264493829311 admin admin 1 1 127.0.0.1
Successfully listed connections.
To query and display information about a single connection service, use the query subcommand.
query cxn -n connectionID [-b hostName:port]
The subcommand displays information about the specified connection on the default broker or on a broker at the specified host and port.
For example:
imqcmd query cxn -n 421085509902214374 -u admin
After prompting for the password, the command produces output like the following:
Connection ID 421085509902214374
User guest
Service jms
Producers 0
Consumers 1
Host 111.22.333.444
Port 60953
Client ID
Client Platform
Managing Durable SubscriptionsYou 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.
To list durable subscriptions for a specified physical destination, use the list dur subcommand. This is the syntax for the list dur subcommand:
imqcmd list dur -d destName
For example, the following command lists all durable subscriptions to the topic SPQuotes, using the broker at the default port on the local host:
imqcmd list dur -d SPQuotes
For each durable subscription to a topic, the list dur 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:
Name Client ID Number of Durable Sub
Messages State
----------------------------------------------------------------
myDurable myClientID 1 INACTIVE
You can use the information returned from the list dur subcommand to identify a durable subscription you might want to destroy or for which you want to purge messages.
The destroy dur subcommand destroys a specified durable subscription with the specified client identifier. This is the syntax for the destroy dur subcommand:
imqcmd destroy dur -n subscrName -c client_id
Use the name of the subscription and the client ID to identify the subscription. For example:
imqcmd destroy dur -n myDurable -c myClientID
The purge dur subcommand purges all messages for the specified durable subscription with the specified Client Identifier. This is the syntax for the purge dur subcommand:
imqcmd purge dur -n subscrName -c client_id
Managing TransactionsAll transactions initiated by client applications are tracked by the broker. These can be simple Message Queue transactions or distributed transactions managed by a distributed transaction (XA resource) manager.
Each transaction has a Message Queue 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. Message Queue maintains the association of an Message Queue 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.
To list all transactions, being tracked by the broker, use the list txn command. This is the syntax for the list tx subcommand:
imqcmd list txn
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 acknowledgments, and creation time. For example:
---------------------------------------------------------------
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
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 14-3), you must 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 acknowledgments 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). This is the syntax of the query txn subcommand:
imqcmd query txn -n transaction_id
For example, the following example produces the output shown below:
imqcmd query txn -n 64248349708800
This is the output produced by the command:
Client ID
Connection guest@192.18.116.219:62209->jms:62195
Creation time 1/30/02 10:08:31 AM
Number of acknowledgments 0
Number of messages 4
State PREPARED
Transaction ID 64248349708800
User name guest
XID
6469706F6C7369646577696E6465723130313234313431313030373230
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.
This is the syntax of the commit subcommand:
imqcmd commit txn -n transaction_id
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.
This is the syntax of the rollback. subcommand:
imqcmd rollback txn -n transaction_id
See the imq.transaction.autorollback property in Table 14-3 for more information.