Chapter 5 Broker Management
This chapter explains how to use the Message Queue Command utility (imqcmd) to manage a broker and its services. The chapter has the following sections:
This chapter does not cover all topics related to managing a broker. Additional topics are covered in the following separate chapters:
-
For information on managing physical destinations on the broker, such as how to create, display, update, and destroy physical destinations and how to use the dead message queue, see Chapter 6, Physical Destinations.
-
For information about setting up security for the broker, such as user authentication, access control, encryption, and password files, see Chapter 9, Security.
Command Utility Preliminaries
Before using the Command utility to manage a broker, you must do the following:
-
Start the broker using the imqbrokerd command. You cannot use the other command line utilities 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 administrative 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 Command utility.
If you are setting up a production system, you must set up authentication and authorization for administrative users. See Chapter 9, 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 Message Encryption.
Using the Command Utility
The Message Queue Command utility (imqcmd) enables you to manage the broker and its services interactively from the command line. See Command Utility for general reference information about the syntax, subcommands, and options of the imqcmd command, and Chapter 14, Broker Properties Reference for specific information on the configuration properties used to specify broker behavior.
Specifying the User Name and Password
Because each imqcmd subcommand is authenticated against the user repository, it requires a user name and password. The only exceptions are commands that use the -h or -H option to display help, and those that use the -v option to display the product version.
Use the -u option to specify an administrative user name. For example, the following command displays information about the default broker:
imqcmd query bkr -u admin
If you omit the user name, the command will prompt you for it.
Note –
For simplicity, the examples in this chapter use the default user name admin as the argument to the -u option. In a real-life production environment, you would use a custom user name.
Specify the password using one of the following methods:
-
Create a password file and enter the password into that file as the value of the imq.imqcmd.password property. On the command line, use the -passfile option to provide the name of the password file.
-
Let the imqcmd command prompt you for the password.
Note –
In previous versions of Message Queue, you could use the -p option to specify a password on the imqcmd command line. As of Message Queue 4.0, this option is deprecated and is no longer supported; you must instead use one of the methods listed above.
Specifying the Broker Name and Port
Most imqcmd subcommands use the -b option to specify the host name and port number of the broker to which the command applies:
-b hostName:portNumber
If no broker is specified, the command applies by default to a broker running on the local host (localhost) at port number 7676. To issue a command to a broker that is running on a remote host, listening on a nondefault port, or both, you must use the -b option to specify the host and port explicitly.
Displaying the Product Version
To display the Message Queue product version, use the -v option. For example:
imqcmd -v
If you enter an imqcmd command line containing 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 Help
To display help on the imqcmd command, 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 an imqcmd command line containing 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.
Examples
The examples in this section illustrate how to use the imqcmd command.
The following example lists the properties of the broker running on host localhost at port 7676, so the -b option is unnecessary:
imqcmd query bkr -u admin
The command uses the default administrative user name (admin) and omits the password, so that the command will prompt for it.
The following example lists the properties of the broker running on the host myserver at port 1564. The user name is aladdin:
imqcmd query bkr -b myserver:1564 -u aladdin
(For this command to work, the user repository would need to be updated to add the user name aladdin to the admin group.)
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. This option causes the Command utility to use the ssladmin service if that service has been configured and started.
Managing Brokers
This section describes how to use Command utility subcommands to perform the following broker management tasks:
In addition to using the subcommands described in the following sections, imqcmd allows you to set system properties using the –D option. This is useful for setting or overriding connection factory properties or connection-related Java system properties. The following command changes the default value of imqSSLIsHostTrusted.
imqcmd list svc -secure -DimqSSLIsHostTrusted=true
The following command specifies the password file and the password.
imqcmd list svc -secure -DJavax.net.ssl.trustStore=/tmp/MyTruststore
-Djavax.net.ssl.trustStorePassword=MyTrustword
Shutting Down and Restarting a Broker
The subcommand imqcmd shutdown bkr shuts down a broker:
imqcmd shutdown bkr [-b hostName:portNumber]
[-time nSeconds]
[-nofailover]The broker stops accepting new connections and messages, completes delivery of existing messages, and terminates the broker process.
The -time option, if present, specifies the interval, in seconds, to wait before shutting down the broker. For example, the following command delays 90 seconds and then shuts down the broker running on host wolfgang at port 1756:
imqcmd shutdown bkr -b wolfgang:1756 -time 90 -u admin
The broker will not block, but will return immediately from the delayed shutdown request. During the shutdown interval, the broker will not accept any new jms connections; admin connections will be accepted, and existing jms connections will continue to operate. If the broker belongs to a high-availability cluster, it will not attempt to take over for any other broker during the shutdown interval.
If the broker is part of a high-availability cluster (see High-Availability Clusters), another broker in the cluster will ordinarily attempt to take over its persistent data on shutdown; the -nofailover option to the imqcmd shutdown bkr subcommand suppresses this behavior. Conversely, you can use the imqcmd takeover bkr subcommand to force such a takeover manually (for instance, if the takeover broker were to fail before completing the takeover process); see Preventing or Forcing Takeover of a Broker for more information.
Note –
The imqcmd takeover bkr subcommand is intended only for use in failed-takeover situations. You should use it only as a last resort, and not as a general way of forcibly taking over a running broker.
To shut down and restart a broker, use the subcommand imqcmd restart bkr:
imqcmd restart bkr [-b hostName:portNumber]
This shuts down the broker and then restarts it using the same options that were specified when it was first started. To choose different options, shut down the broker with imqcmd shutdown bkr and then start it again with the Broker utility (imqbrokerd), specifying the options you want.
Quiescing a Broker
The subcommand imqcmd quiesce bkr quiesces a broker, causing it to refuse any new client connections while continuing to service old ones:
imqcmd quiesce bkr [-b hostName:portNumber]
If the broker is part of a high-availability cluster, this allows its operations to wind down normally without triggering a takeover by another broker, for instance in preparation for shutting it down administratively for upgrade or similar purposes. For example, the following command quiesces the broker running on host hastings at port 1066:
imqcmd quiesce bkr -b hastings:1066 -u admin
To reverse the process and return the broker to normal operation, use the imqcmd unquiesce bkr subcommand:
imqcmd unquiesce bkr [-b hostName:portNumber]
For example, the following command unquiesces the broker that was quiesced in the preceding example:
imqcmd unquiesce bkr -b hastings:1066 -u admin
Pausing and Resuming a Broker
The subcommand imqcmd pause bkr pauses a broker, suspending its connection service threads and causing it to stop listening on the connection ports:
imqcmd pause bkr [-b hostName:portNumber]
For example, the following command pauses the broker running on host myhost at port 1588:
imqcmd pause bkr -b myhost:1588 -u admin
Because its connection service threads are suspended, a paused broker is unable to accept new connections, receive messages, or dispatch messages. The admin connection service is not suspended, allowing you to continue performing administrative tasks needed to regulate the flow of messages to the broker. Pausing a broker also does not suspend the cluster connection service; however, since message delivery within a cluster depends on the delivery functions performed by the different brokers in the cluster, pausing a broker in a cluster may result in a slowing of some message traffic.
You can also pause individual connection services and physical destinations. For more information, see Pausing and Resuming a Connection Service and Pausing and Resuming a Physical Destination.
The subcommand imqcmd resume bkr reactivates a broker’s service threads, causing it to resume listening on the ports:
imqcmd resume bkr [-b hostName:portNumber]
For example, the following command resumes the default broker (host localhost at port 7676):
imqcmd resume bkr -u admin
Updating Broker Properties
The subcommand imqcmd update bkr changes the values of specified properties for the default broker (or for the broker at a specified host and port):
imqcmd update bkr [-b hostName:portNumber]
-o property1=value1 [ [-o property2=value2] … ]For example, the following command turns off the auto-creation of queue destinations for the default broker:
imqcmd update bkr -o imq.autocreate.queue=false -u admin
You can use imqcmd update bkr to update any of the following broker properties:
imq.autocreate.queue.maxNumActiveConsumers
imq.autocreate.queue.maxNumBackupConsumers
imq.destination.DMQ.truncateBody
See Chapter 14, Broker Properties Reference for detailed information about these properties.
Viewing Broker Information
To display information about a single broker, use the imqcmd query bkr subcommand:
imqcmd query bkr -b hostName:portNumber
This lists the current settings of the broker’s properties, as shown in Example 5–1.
Example 5–1 Broker Information Listing
|
The imqcmd metrics bkr subcommand displays detailed metric information about a broker’s operation:
imqcmd metrics bkr [-b hostName:portNumber]
[-m metricType]
[-int interval]
[-msp numSamples]The -m option specifies the type of metric information to display:
-
ttl (default): Messages and packets flowing into and out of the broker
-
rts: Rate of flow of messages and packets into and out of the broker per second
-
cxn: Connections, virtual memory heap, and threads
The -int and -msp options specify, respectively, the interval (in seconds) at which to display the metrics and the number of samples to display in the output. The default values are 5 seconds and an unlimited number of samples.
For example, the following command displays the rate of message flow into and out of the default broker (host localhost at port 7676) at 10-second intervals:
imqcmd metrics bkr -m rts -int 10 -u admin
Example 5–2 shows an example of the resulting output.
Example 5–2 Broker Metrics Listing
|
For a more detailed description of the data gathered and reported by the broker, see Brokerwide Metrics.
For brokers belonging to a broker cluster, the imqcmd list bkr subcommand displays information about the configuration of the cluster; see Displaying the Cluster Configuration for more information.
Managing Connection Services
Message Queue brokers support connections from both application clients and administrative clients. See Connection Services for a description of the available connection services. The Command utility provides subcommands that you can use for managing both connection services as a whole and individual services; to apply a subcommand to a particular service, use the -n option to specify one of the names listed in the “Service Name” column of Table 4–1. Subcommands are available for the following connection service management tasks:
Pausing and Resuming a Connection Service
Pausing a connection 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 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.)
The admin connection service can never be paused; to pause and resume any other service, use the subcommands imqcmd pause svc and imqcmd resume svc. The syntax of the imqcmd pause svc subcommand is as follows:
imqcmd pause svc -n serviceName
[-b hostName:portNumber]For example, the following command pauses the httpjms service running on the default broker (host localhost at port 7676):
imqcmd pause svc -n httpjms -u admin
The imqcmd resume svc subcommand resumes operation of a connection service following a pause:
imqcmd resume svc -n serviceName
[-b hostName:portNumber]Updating Connection Service Properties
You can use the imqcmd update svc subcommand to change the value of one or more of the service properties listed in Table 5–1. See Connection Properties for a description of these properties.
Table 5–1 Connection Service Properties Updated by Command Utility|
Property |
Description |
|---|---|
|
port |
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 | |
|
maxThreads |
Maximum number of threads assigned to the service |
The imqcmd update svc subcommand has the following syntax:
imqcmd update svc -n serviceName
[-b hostName:portNumber]
-o property1=value1 [[-o property2=value2]…]For example, the following command changes the minimum number of threads assigned to the jms connection service on the default broker (host localhost at port 7676) to 20:
imqcmd update svc -o minThreads=20 -u admin
Viewing Connection Service Information
To list the connection services available on a broker, use the imqcmd list svc subcommand:
imqcmd list svc [-b hostName:portNumber]
For example, the following command lists all services on the default broker (host localhost at port 7676):
imqcmd list svc -u admin
Example 5–3 shows an example of the resulting output.
Example 5–3 Connection Services Listing
|
The imqcmd query svc subcommand displays information about a single connection service:
imqcmd query svc -n serviceName
[-b hostName:portNumber]For example, the following command displays information about the jms connection service on the default broker (host localhost at port 7676):
imqcmd query svc -n jms -u admin
Example 5–4 shows an example of the resulting output.
Example 5–4 Connection Service Information Listing
|
To display metric information about a connection service, use the imqcmd metrics svc subcommand:
imqcmd metrics svc -n serviceName
[-b hostName:portNumber]
[-m metricType]
[-int interval]
[-msp numSamples]The -m option specifies the type of metric information to display:
-
ttl (default): Messages and packets flowing into and out of the broker by way of the specified connection service
-
rts: Rate of flow of messages and packets into and out of the broker per second by way of the specified connection service
-
cxn: Connections, virtual memory heap, and threads
The -int and -msp options specify, respectively, the interval (in seconds) at which to display the metrics and the number of samples to display in the output. The default values are 5 seconds and an unlimited number of samples.
For example, the following command displays cumulative totals for messages and packets handled by the default broker (host localhost at port 7676) by way of the jms connection service:
imqcmd metrics svc -n jms -m ttl -u admin
Example 5–5 shows an example of the resulting output.
Example 5–5 Connection Service Metrics Listing
|
For a more detailed description of the use of the Command utility to report connection service metrics, see Connection Service Metrics.
Managing Connections
The Command utility’s list cxn and query cxn subcommands display information about individual connections. The subcommand imqcmd list cxn lists all connections for a specified connection service:
imqcmd list cxn [-svn serviceName]
[-b hostName:portNumber]If no service name is specified, all connections are listed. For example, the following command lists all connections on the default broker (host localhost at port 7676):
imqcmd list cxn -u admin
Example 5–6 shows an example of the resulting output.
Example 5–6 Broker Connections Listing
|
To display detailed information about a single connection, obtain the connection identifier from imqcmd list cxn and pass it to the imqcmd query cxn subcommand:
imqcmd query cxn -n connectionID
[-b hostName:portNumber]For example, the command
imqcmd query cxn -n 421085509902214374 -u admin
produces output like that shown in Example 5–7.
Example 5–7 Connection Information Listing
|
The imqcmd destroy cxn subcommand destroys a connection:
imqcmd destroy cxn -n connectionID
[-b hostName:portNumber]For example, the command
imqcmd destroy cxn -n 421085509902214374 -u admin
destroys the connection shown in Example 5–7.
Managing Durable Subscriptions
Message Queue clients subscribing to a topic destination can register the subscription as durable. A durable subscription has a unique, persistent identity and requires the broker to retain messages addressed to it even when its message consumer becomes inactive. Ordinarily, the broker may delete a message held for a durable subscriber only when the message expires.
The Message Queue Command utility provides subcommands for managing a broker’s durable subscriptions in the following ways:
-
Listing durable subscriptions
-
Purging all messages for a durable subscription
-
Destroying a durable subscription
To list durable subscriptions for a specified physical destination, use the imqcmd list dur subcommand:
imqcmd list dur -d topicName
For example, the following command lists all durable subscriptions to the topic SPQuotes on the default broker (host localhost at port 7676):
imqcmd list dur -d SPQuotes
The resulting output lists the name of each durable subscription to the topic, the client identifier to which it belongs, its current state (active or inactive), and the number of messages currently queued to it. Example 5–8 shows an example.
Example 5–8 Durable Subscription Information Listing
|
The imqcmd purge dur subcommand purges all messages for a specified durable subscriber and client identifier:
imqcmd purge dur -n subscriberName
-c clientID
For example, the following command purges all messages for the durable subscription listed in Example 5–8:
imqcmd purge dur -n myCurable -c myClientID
The imqcmd destroy dur subcommand destroys a durable subscription, specified by its subscriber name and client identifier:
imqcmd destroy dur -n subscriberName
-c clientID
For example, the following command destroys the durable subscription listed in Example 5–8:
imqcmd destroy dur -n myCurable -c myClientID
Managing Transactions
All 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 is identified by a unique 64-bit Message Queue transaction identifier. Distributed transactions also have a distributed transaction identifier (XID), up to 128 bytes long, assigned by the distributed transaction manager. Message Queue maintains the association between its own transaction identifiers and the corresponding XIDs.
The imqcmd list txn subcommand lists the transactions being tracked by a broker:
imqcmd list txn
This lists all transactions on the broker, both local and distributed. For each transaction, it shows the transaction ID, state, user name, number of messages and acknowledgments, and creation time. Example 5–9 shows an example of the resulting output.
Example 5–9 Broker Transactions Listing
|
To display detailed information about a single transaction, obtain the transaction identifier from imqcmd list txn and pass it to the imqcmd query txn subcommand:
imqcmd query txn -n transactionID
This displays the same information as imqcmd list txn, along with the client identifier, connection identification, and distributed transaction identifier (XID). For example, the command
imqcmd query txn -n 64248349708800
produces output like that shown in Example 5–10.
Example 5–10 Transaction Information Listing
|
In case of broker failure, it is possible that a distributed transaction could be left in the prepared state without ever being committed. Until such a transaction is committed, its messages will not be delivered and its acknowledgments will not be processed. Hence, as an administrator, you may need to monitor such transactions and commit them or roll them back manually. For example, if the broker’s imq.transaction.autorollback property (see Table 14–2) is set to false, you must manually commit or roll back transactions found in the prepared state at broker startup, using the Command utility’s commit txn or rollback txn subcommand:
imqcmd commit txn -n transactionID
imqcmd rollback txn -n transactionID
For example, the following command commits the transaction listed in Example 5–10:
imqcmd commit txn -n64248349708800
Note –
Only transactions in the prepared state can be committed or rolled back. You should do so only 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.
- © 2010, Oracle Corporation and/or its affiliates