This chapter explains how yo use the imqcmd utility to manage the broker and its services. This 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:
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
You use the imqcmd and imqusermgr command line utilities to manage the broker. Before managing the broker, you must do the following:
Start the broker using the imqbrokerd utility command. You cannot use the other command line utilities until a broker is running.
Determine whether you want to set up a Message QueueTM 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 Message Encryption.
The imqcmd 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 Line Reference. Reference information for managing physical destinations is in a separate chapter, Chapter 15, Physical Destination Property Reference.
To display help on the imqcmd 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 imqcmd utility processes only the -h or -H option. All other items on the command line are ignored.
To 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 imqcmd utility processes only the -v option. All other items on the command line are ignored.
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 commands that use the -v option to display the product version.
Use the -u option to specify an administrative user name. If you omit the user name, the command prompts you for it. For example, the following command displays information about the default broker:
imqcmd query bkr -u admin
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.
Specify the password using 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 password file.
Let the command prompt you for the password.
In previous versions of Message Queue, you could use the -p option to specify a password on the imqcmd command line. This option is being deprecated and will be removed in a future version.
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 listening on a nondefault port, or both, you must use the -b option to specify the broker’s host and port.
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 the host myserver at port 1564. The user name is aladdin . (For this command to work, the user repository would need to be updated to add the user name aladdin 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.
To 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: portNumber
This subcommand lists the current settings of properties for the default broker or a broker at the specified host and port. It also shows the list of running brokers (in a multiple-broker cluster) that are connected to the specified broker.
imqcmd query bkr -u admin
After prompting you for the password, the command produces output like the following:
Version 3.6 Instance Name imqbroker Primary Port 7676 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 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) |
You can use the update bkr subcommand to update the following broker properties:
This is the syntax of the update bkr subcommand:
imqcmd update bkr [-b hostName: portNumb er]-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. For example, the following command turns off the auto-creation of queue destinations:
imqcmd update bkr -o "imq.autocreate.queue=false" -u admin
The properties are described in Chapter 14, Broker Properties Reference
After you start the broker, you can use imqcmd subcommands to control the state of the 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, or 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. Pausing a broker also does not suspend the cluster connection service. However message delivery within a cluster depends on the delivery functions performed by the different brokers in the cluster. Therefore, pausing a broker in a cluster might result in a slowing of some message traffic.
This is the syntax of the pause bkr subcommand:
imqcmd pause bkr [-b hostName: portNumber]
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 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: portNumber]
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 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: portNumber]
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
Use the restart bkr subcommand to shut down and restart the broker. This is the syntax of the restart bkr subcommand:
imqcmd restart bkr [-b hostName: portNumber]
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.
To 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: portNumber] [-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:
ttl Displays metrics about the messages and packets flowing into and out of the broker (default metric type).
rts Displays metrics about the rate of flow of messages and packets into and out of the broker (per second).
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 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 about the data gathered and reported by the broker, see Brokerwide Metrics.
The imqcmd 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. As shown in the table, each service is associated with the service type it uses (NORMAL for application clients or ADMIN for administration clients) and with an underlying transport protocol.
Table 5–1 Message Queue Connection Services
Service Name |
Service Type | |
---|---|---|
NORMAL | ||
NORMAL | ||
NORMAL | ||
NORMAL | ||
ADMIN |
TCP |
|
ADMIN |
TLS (SSL-based security) |
You can use imqcmd subcommands to manage connection services as a whole or to manage a particular connection service. If the target of a subcommand is a particular service, use the -n option to specify one of the names listed in the Service Name column of Table 5–1.
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: portNumber]
The subcommand lists all connection services on the default broker or on a broker at the specified host and port.
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 |
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:portNumber]
The query svc subcommand displays 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 |
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 | |
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:portNumber] -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 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
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:portNumber] [-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.
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:portNumber]
The subcommand pauses the specified service running on the default broker or on a broker at the specified host and port. For example, the following command pauses the httpjms service running on the default broker.
imqcmd pause svc -n httpjms -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:portNumber]
The subcommand resumes the specified service running on the default broker or on a broker at the specified host and port.
The imqcmd 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:portNumber]
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, the following command lists all connections on the default broker:
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:portNumber]
The subcommand displays information about the specified connection on the default broker or on a broker at the specified host and port.
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 |
Using imqcmd subcommands you can manage a broker’s durable subscriptions by doing one or more of the following:
Listing durable subscriptions
Purging all messages for a durable subscription
Destroying a durable subscription
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 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 clientID
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 clientID
For example, the following command destroys the durable subscription myDurable and clientID, myClientID.
imqcmd destroy dur -n myDurable -c myClientID
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 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), up to 128 bytes long, assigned by the distributed transaction manager. 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–2), 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 transactionID
For example, the following example produces the output shown below:
imqcmd query txn -n 64248349708800
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 |
Use the commit and rollback subcommands 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 transactionID
For example:
imqcmd commit txn -n 64248349708800
This is the syntax of the rollback. subcommand:
imqcmd rollback txn -n transactionID
See the imq.transaction.autorollback property in Table 14–2 for more information.
It is also possible to configure the broker to automatically roll back transactions in the PREPARED state at broker startup.