JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Oracle GlassFish Server Message Queue 4.5 Administration Guide
search filter icon
search icon

Document Information

Preface

Part I Introduction to Message Queue Administration

1.  Administrative Tasks and Tools

2.  Quick-Start Tutorial

Part II Administrative Tasks

3.  Starting Brokers and Clients

4.  Configuring a Broker

5.  Managing a Broker

6.  Configuring and Managing Connection Services

7.  Managing Message Delivery

8.  Configuring Persistence Services

9.  Configuring and Managing Security Services

10.  Configuring and Managing Broker Clusters

11.  Managing Administered Objects

12.  Configuring and Managing Bridge Services

13.  Monitoring Broker Operations

14.  Analyzing and Tuning a Message Service

15.  Troubleshooting

Part III Reference

16.  Command Line Reference

Command Line Syntax

Broker Utility

Command Utility

General Command Utility Options

Broker Management

Connection Service Management

Connection Management

Physical Destination Management

Durable Subscription Management

Transaction Management

JMX Management

Object Manager Utility

Database Manager Utility

User Manager Utility

Bridge Manager Utility

Service Administrator Utility

Key Tool Utility

17.  Broker Properties Reference

18.  Physical Destination Property Reference

19.  Administered Object Attribute Reference

20.  JMS Resource Adapter Property Reference

21.  Metrics Information Reference

22.  JES Monitoring Framework Reference

Part IV Appendixes

A.  Distribution-Specific Locations of Message Queue Data

B.  Stability of Message Queue Interfaces

C.  HTTP/HTTPS Support

D.  JMX Support

E.  Frequently Used Command Utility Commands

Index

Command Utility

The Command utility (imqcmd) is used for managing brokers, connection services, connections, physical destinations, durable subscriptions, and transactions.

All imqcmd commands must include a subcommand (except those using the -v or -h option to display product version information or usage help, respectively). The possible subcommands are listed in Table 16-2 and described in detail in the corresponding sections below. In addition, each imqcmd subcommand supports the general options shown in General Command Utility Options.


Note - The -u userName option (and corresponding password) is required except when using the -v or -h option. Also if a subcommand accepts a broker address (-b option) and no host name or port number is specified, the values localhost and 7676 are assumed by default.


Table 16-2 Command Utility Subcommands

shutdown bkr
Shut down broker
restart bkr
Restart broker
pause bkr
Pause broker
quiesce bkr
Quiesce broker
unquiesce bkr
Unquiesce broker
resume bkr
Resume broker
takeover bkr
Initiate broker takeover
update bkr
Set broker properties
query bkr
List broker property values
list bkr
List brokers in cluster
metrics bkr
Display broker metrics
reload cls
Reload cluster configuration
changemaster cls
Change the master broker in a conventional cluster with master broker
pause svc
Pause connection service
resume svc
Resume connection service
update svc
Set connection service properties
list svc
List connection services available on broker
query svc
List connection service property values
metrics svc
Display connection service metrics
list cxn
List connections on broker
query cxn
Display connection information
destroy cxn
Destroy connection
create dst
Create physical destination
destroy dst
Destroy physical destination
pause dst
Pause message delivery for physical destination
resume dst
Resume message delivery for physical destination
purge dst
Purge all messages from physical destination
compact dst
Compact physical destination
update dst
Set physical destination properties
list dst
List physical destinations
query dst
List physical destination property values
metrics dst
Display physical destination metrics
destroy dur
Destroy durable subscription
purge dur
Purge all messages for durable subscription
list dur
List durable subscriptions for topics
commit txn
Commit transaction
rollback txn
Roll back transaction
list txn
List transactions being tracked by broker
query txn
Display transaction information
list dur
List durable subscriptions for topic
list jmx
List JMX service URLs of JMX connectors

General Command Utility Options

The additional options listed in Table 16-3 can be applied to any subcommand of the imqcmd command.

Table 16-3 General Command Utility Options

Option
Description
-secure
Use secure connection to broker with ssladmin connection service
-u userName
User name for authentication

If this option is omitted, the Command utility will prompt for it interactively.

-passfile path
Location of password file

See Password Files for more information.

-D
Set connection-related system property that affects how imqcomd creates a connection to the broker. Not used to set broker configuration properties.

Usually overrides connection factory attributes for imqcmd client runtime. For example, the option in the following command changes the default value of imqSSLIsTrusted:

imqcmd list svc -secure -DimqSSLIsTrusted=true

-rtm timeoutInterval
Initial timeout interval, in seconds

This is the initial length of time that the Command utility will wait for a reply from the broker before retrying a request. Each subsequent retry will use a timeout interval that is a multiple of this initial interval.

Default value: 10.

-rtr numRetries
Number of retries to attempt after a broker request times out

Default value: 5.

-javahome path
Location of alternative Java runtime

Default behavior: Use runtime installed on system or bundled with Message Queue.

-f
Perform action without user confirmation
-s
Silent mode (no output displayed)
-v
Display version information1,2
-h
Display usage help1,2
-H
Display expanded usage help, including attribute list and examples1,2

1Any other options specified on the command line are ignored.

2User name and password not needed

Broker Management

The Command utility cannot be used to start a broker; use the Broker utility (imqbrokerd) instead. Once the broker is started, you can use the imqcmd subcommands listed in Table 16-4 to manage and control it.

Table 16-4 Command Utility Subcommands for Broker Management

Syntax
Description
shutdown bkr [-b hostName:portNumber]
  • [-time nSeconds]

  • [-nofailover]

Shut down broker

The -time option specifies the interval, in seconds, to wait before shutting down the broker. (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. A broker belonging to an enhanced cluster will not attempt to take over for any other broker during the shutdown interval.

The -nofailover option indicates that no other broker is to take over the persistent data of the one being shut down. 1

restart bkr [-b hostName:portNumber]
Restart broker

Shuts down the broker and then restarts it using the same options specified when it was originally started.

pause bkr [-b hostName:portNumber]
Pause broker

See Pausing and Resuming a Broker for more information.

quiesce bkr [-b hostName:portNumber]
Quiesce broker

The broker will stop accepting new connections; existing connections will continue to operate.

unquiesce bkr [-b hostName:portNumber]
Unquiesce broker

The broker will resume accepting new connections, returning to normal operation.

resume bkr [-b hostName:portNumber]
Resume broker
takeover bkr -n brokerID
  • [-f]

Initiate broker takeover 1

Before taking over a broker, you should first shut it down manually using the shutdown bkr subcommand with the -nofailover option. If the specified broker appears to be still running, takeover bkr will display a confirmation message (Do you want to take over for this broker?). The -f option suppresses this message and initiates the takeover unconditionally.


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


update bkr [-b hostName:portNumber]
  • -o property1=value1

  • [ [-o property2=value2] … ]

Set broker properties

See Chapter 17, Broker Properties Reference for information on broker properties.

query bkr -b hostName:portNumber
List broker property values

For brokers belonging to a cluster, also lists cluster properties such as broker list, master broker (for conventional clusters), and cluster identifier (for enhanced clusters).

list bkr
List brokers in cluster
metrics bkr [-b hostName:portNumber]
  • [-m metricType]

  • [-int interval]

  • [-msp numSamples]

Display broker metrics

The -m option specifies the type of metrics to display:

  • ttl: 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

Default value: ttl.

The -int option specifies the interval, in seconds, at which to display metrics. Default value: 5.

The -msp option specifies the number of samples to display. Default value: Unlimited (infinite).

reload cls
Reload cluster configuration1

Forces all persistent information to be brought up to date.

changemaster cls -o imq.cluster.masterbroker=newMaster
Change the master broker in a conventional cluster with master broker.

This command must be run on the current master broker.

The value newMaster has the form hostName:portNumber, where hostName and portNumber are is its Port Mapper host name and port number, respectively.

Literal IP addresses as host names: You can use a literal IPv4 or IPv6 address as a host name. If you use a literal IPv6 address, its format must conform to RFC2732, Format for Literal IPv6 Addresses in URL's.

1Applies only to broker clusters

Connection Service Management

Table 16-5 lists the imqcmd subcommands for managing connection services.

Table 16-5 Command Utility Subcommands for Connection Service Management

Syntax
Description
pause svc -n serviceName
  • [-b hostName:portNumber]

Pause connection service

The admin connection service cannot be paused.

resume svc -n serviceName
  • [-b hostName:portNumber]

Resume connection service
update svc -n serviceName
  • [-b hostName:portNumber]

  • -o property1=value1

  • [ [-o property2=value2] … ]

Set connection service properties

See Connection Properties for information on connection service properties.

list svc [-b hostName:portNumber]
List connection services available on broker
query svc -n serviceName
  • [-b hostName:portNumber]

List connection service property values
metrics svc -n serviceName
  • [-b hostName:portNumber]

  • [-m metricType]

  • [-int interval]

  • [-msp numSamples]

Display connection service metrics

The -m option specifies the type of metrics to display:

  • ttl: 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

Default value: ttl.

The -int option specifies the interval, in seconds, at which to display metrics. Default value: 5.

The -msp option specifies the number of samples to display. Default value: Unlimited (infinite).

Connection Management

Table 16-6 lists the imqcmd subcommands for managing connections.

Table 16-6 Command Utility Subcommands for Connection Service Management

Syntax
Description
list cxn [-svn serviceName]
  • [-b hostName:portNumber]

List connections on broker

Lists all connections on the broker to the specified connection service. If no connection service is specified, all connections are listed.

query cxn -n connectionID
  • [-b hostName:portNumber]

Display connection information
destroy cxn -n connectionID
  • [-b hostName:portNumber]

Destroy connection

Physical Destination Management

Table 16-7 lists the imqcmd subcommands for managing physical destinations. In all cases, the -t (destination type) option can take either of two values:

Table 16-7 Command Utility Subcommands for Physical Destination Management

Syntax
Description
create dst -t destType -n destName
  • [ [-o property=value] … ]

Create physical destination1

The destination name destName may contain only alphanumeric characters (no spaces) and must begin with an alphabetic character or the underscore (_) or dollar sign ($) character. It may not begin with the characters mq.

destroy dst -tdestType -n destName
Destroy physical destination1

This operation cannot be applied to a system-created destination, such as a dead message queue.

pause dst [-t destType -n destName]
  • [-pst pauseType]

Pause message delivery for physical destination

Pauses message delivery for the physical destination specified by the -t and -n options. If these options are not specified, all destinations are paused.

The -pst option specifies the type of message delivery to be paused:

  • PRODUCERS: Pause delivery from message producers

  • CONSUMERS: Pause delivery to message consumers

  • ALL: Pause all message delivery

Default value: ALL

resume dst [-t destType -n destName]
Resume message delivery for physical destination

Resumes message delivery for the physical destination specified by the -t and -n options. If these options are not specified, all destinations are resumed.

purge dst -t destType -n destName
Purge all messages from physical destination
compact dst [-t destType -n destName]
Compact physical destination

Compacts the file-based persistent data store for the physical destination specified by the -t and -n options. If these options are not specified, all destinations are compacted.

A destination must be paused before it can be compacted.

update dst -t destType -n destName
  • -o property1=value1

  • [ [ -o property2=value2] … ]

Set physical destination properties

See Chapter 18, Physical Destination Property Reference for information on physical destination properties.

list dst [-t destType]
  • [-tmp]

List physical destinations

Lists all physical destinations of the type specified by the -t option. If no destination type is specified, both queue and topic destinations are listed. If the -tmp option is specified, temporary destinations are listed as well.

query dst -t destType -n destName
List physical destination property values
metrics dst -t destType -n destName
  • [-m metricType]

  • [-int interval]

  • [-msp numSamples]

Display physical destination metrics

The -m option specifies the type of metrics to display:

  • ttl: Messages and packets flowing into and out of the destination and residing in memory

  • rts: Rate of flow of messages and packets into and out of the destination per second, along with other rate information

  • con: Metrics related to message consumers

  • dsk: Disk usage

Default value: ttl.

The -int option specifies the interval, in seconds, at which to display metrics. Default value: 5.

The -msp option specifies the number of samples to display. Default value: Unlimited (infinite).

1Cannot be performed in a broker cluster whose master broker is temporarily unavailable

Durable Subscription Management

Table 16-8 lists the imqcmd subcommands for managing durable subscriptions.

Table 16-8 Command Utility Subcommands for Durable Subscription Management

Syntax
Description
destroy dur -n subscriberName -c clientID
Destroy durable subscription1
purge dur -n subscriberName -c clientID
Purge all messages for durable subscription
list dur -[d topicName]
List durable subscriptions for the specified topic. If -d option is omitted then the command lists all durable subscriptions for all topics.

1Cannot be performed in a conventional broker cluster whose master broker is temporarily unavailable

Transaction Management

Table 16-9 lists the imqcmd subcommands for managing local (non-distributed) Message Queue transactions. Distributed transactions are managed by a distributed transaction manager rather than imqcmd.

Table 16-9 Command Utility Subcommands for Transaction Management

Syntax
Description
commit txn -n transactionID
Commit transaction
rollback txn -n transactionID
Roll back transaction
list txn
List transactions being tracked by broker
query txn -n transactionID
Display transaction information

JMX Management

The imqcmd subcommand shown in Table 16-10 is used for administrative support of Java applications using the Java Management Extensions (JMX) application programming interface to configure and monitor Message Queue resources. See Appendix D, JMX Support for further information on the broker's JMX support.

Table 16-10 Command Utility Subcommand for JMX Management

Syntax
Description
list jmx
List JMX service URLs of JMX connectors