test

Sun Java System Message Queue 4.3 Administration Guide

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.

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

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 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.

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 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

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 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.

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


Querying the broker specified by:
-------------------------
Host         Primary Port
-------------------------
localHost    7676

Version                                              4.3
Instance Name                                        imqbroker
Broker ID                                            mybroker
Primary Port                                         7676
Broker is Embedded                                   false
Instance Configuration/Data Root Directory           /var/imq

Current Number of Messages in System                 0
Current Total Message Bytes in System                0

Current Number of Messages in Dead Message Queue     0
Current Total Message Bytes in Dead Message Queue    0
Log Dead Messages                                    true
Truncate Message Body in Dead Message Queue          false

Max Number of Messages in System                     unlimited (-1)
Max Total Message Bytes in System                    unlimited (-1)
Max Message Size                                     70m

Auto Create Queues                                   true
Auto Create Topics                                   true
Auto Created Queue Max Number of Active Consumers    1
Auto Created Queue Max Number of Backup Consumers    0

Cluster ID                                           myClusterID
Cluster Is Highly Available                          true
Cluster Broker List (active)                         
Cluster Broker List (configured)                     
Cluster Master Broker                                
Cluster URL                                          

Log Level                                            INFO
Log Rollover Interval (seconds)                      604800
Log Rollover Size (bytes)                            unlimited (-1)

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:

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


--------------------------------------------------------
 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 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.