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.
For example, 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 used for the SSL trust store that is used by the imqcmd command:
imqcmd list svc -secure -DJavax.net.ssl.trustStore=/tmp/MyTruststore -Djavax.net.ssl.trustStorePassword=MyTrustword
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 an enhanced broker cluster, it will not attempt to take over for any other broker during the shutdown interval.
If the broker is part of an enhanced broker cluster (see High-Availability Clusters in Sun Java System Message Queue 4.3 Technical Overview), 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 Broker Failover for more information.
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.
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.
imqcmd quiesce bkr [-b hostName:portNumber]
If the broker is part of an enhanced broker 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
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
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.
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
The subcommand imqcmd update bkr can be used to change the values of a subset of broker 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:
See Chapter 16, Broker Properties Reference for detailed information about these properties.
imqcmd query bkr -b hostName:portNumber
This lists the current settings of the broker’s properties, as shown in Example 5–1.
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.
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 a Cluster Configuration for more information.