Sun Java System Message Queue 3 2005Q4 Administration Guide |
Chapter 13
Command Line ReferenceThis chapter provides reference information on the use of the Message Queue command line administration utilities. It consists of the following sections:
Command Line SyntaxMessage Queue command line utilities are shell commands. The name of the utility is a command and its subcommands or options are arguments passed to that command. There is no need for separate commands to start or quit the utility.
All the command line utilities share the following command syntax:
utilityName [subcommand] [commandArgument] [[-optionName [-optionArgument]]…]
where utilityName is one of the following:
Subcommands and command-level arguments, if any, must precede all options and their arguments; the options themselves may appear in any order. All subcommands, command arguments, options, and option arguments are separated with spaces. If the value of an option argument contains a space, the entire value must be enclosed in quotation marks. (It is generally safest to enclose any attribute-value pair in quotation marks.)
The following command, which starts the default broker, is an example of a command line with no subcommand clause:
imqbrokerd
Here is a fuller example:
imqcmd destroy dst -t q -n myQueue -u admin -f -s
This command destroys a queue destination (destination type q) named myQueue. Authentication is performed on the user name admin; the command will prompt for a password. The command will be performed without prompting for confirmation (-f option) and in silent mode, without displaying any output (-s option).
Broker UtilityThe Broker utility (imqbrokerd) starts a broker. Command line options override values in the broker configuration files, but only for the current broker session.
Table 13-1 shows the options to the imqbrokerd command and the configuration properties, if any, overridden by each option.
Table 13-1 Broker Utility Options
Option
Properties Overridden
Description
-name instanceName
imq.instancename
Instance name of broker
Multiple broker instances running on the same host must have different instance names.
Default value: imqbroker
-port portNumber
imq.portmapper.port
Port number for broker’s Port Mapper
Message Queue clients use this port number to connect to the broker. Multiple broker instances running on the same host must have different Port Mapper port numbers.
Default value: 7676
-cluster broker1 [ [,broker2 ] … ]
imq.cluster.brokerlist
Connect brokers into cluster1
The specified brokers are merged with the list in the imq.cluster.brokerlist property. Each broker argument has one of the forms
hostName:portNumber
hostName
:portNumberIf hostName is omitted, the default value is localhost; if portNumber is omitted, the default value is 7676.
-Dproperty=value
Corresponding property in instance configuration file
Set configuration property
See Chapter 14, "Broker Properties Reference," for information about broker configuration properties.
Caution: Be careful to check the spelling and formatting of properties set with this option. Incorrect values will be ignored without notification or warning.
-reset props
None
Reset configuration properties
Replaces the broker’s existing instance configuration file (config.properties) with an empty file; all properties assume their default values.
-reset store
None
Reset persistent data store
Clears all persistent data from the data store (including persistent messages, durable subscriptions, and transaction information), allowing you to start the broker instance with a clean slate. To prevent the persistent store from being reset on subsequent restarts, restart the broker instance without the -reset option.
To clear only persistent messages or durable subscriptions, use -reset messages or -reset durables instead.
-reset messages
None
Clear persistent messages from data store
-reset durables
None
Clear durable subscriptions from data store
-backup fileName
None
Back up configuration change record to file1
See Managing the Configuration Change Record for more information.
-restore fileName
None
Restore configuration change record from backup file1
The backup file must have been previously created using the -backup option.
See Managing the Configuration Change Record for more information.
-remove instance
None
Remove broker instance2
Deletes the instance configuration file, log files, persistent store, and other files and directories associated with the instance.
-password keyPassword
imq.keystore.password
Password for SSL certificate key store3
-dbuser userName
imq.persist.jdbc.user
User name for JDBC-based persistent data store
-dbpassword dbPassword
imq.persist.jdbc.password
Password for JDBC-based persistent data store3
-ldappassword ldapPassword
imq.user_repository.ldap.password
Password for LDAP user repository3
-passfile filePath
imq.passfile.enabled
imq.passfile.dirpath
imq.passfile.nameLocation of password file
Sets the broker’s imq.passfile.enabled property to true, imq.passfile.dirpath to the path containing the password file, and imq.passfile.name to the file name itself.
See Using a Password File for more information.
-shared
imq.jms.threadpool_model
Use shared thread pool model to implement jms connection service
Execution threads will be shared among connections to increase the number of connections supported.
Sets the broker’s imq.jms.threadpool_model property to shared.
-javahome path
None
Location of alternative Java runtime
Default: Use runtime installed on system or bundled with Message Queue.
-vmargs arg1 [ [ arg2 ] … ]
None
Pass arguments to Java virtual machine
Arguments are separated with spaces. To pass more than one argument, or an argument containing a space, enclose the argument list in quotation marks.
VM arguments can be passed only from the command line; there is no associated configuration property in the instance configuration file.
-license [ licenseName ]
None
License to load, if different from default for installed edition of Message Queue product:
pe Platform Edition with basic
featurestry Platform Edition with enterprise
features (90-day trial)unl Enterprise Edition
If no license name is specified, this option lists all licenses installed on the system.
-upgrade-store-nobackup
None
Automatically remove old data store on upgrade to Message Queue 3.5 or 3.5 SPx from an incompatible version2
See the Message Queue Installation Guide for more information.
-force
None
Perform action without user confirmation
This option applies only to the -remove instance and -upgrade-store-nobackup options, which normally require confirmation.
-loglevel level
imq.broker.log.level
Logging level:
NONE
ERROR
WARNING
INFODefault value: INFO
-metrics interval
imq.metrics.interval
Logging interval for broker metrics, in seconds
-tty
imq.log.console.output
Log all messages to console
Sets the broker’s imq.log.console.output property to ALL.
If not specified, only error and warning messages will be logged.
-s | -silent
imq.log.console.output
Silent mode (no logging to console)
Sets the broker’s imq.log.console.output property to NONE.
-version
None
Display version information4
-h | -help
None
Display usage help4
1This option applies only to broker clusters.
2This option requires user confirmation unless -force is also specified.
3This option is being deprecated and will eventually be removed. Instead, either omit the password entirely (so that the command will prompt for it interactively) or use the -passfile option to specify a password file containing the password.
4Any other options specified on the command line are ignored .
Command UtilityThe 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). The possible subcommands are listed here and described in detail in the corresponding sections below. In all cases, if the 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.
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 13-2 to manage and control it.
Table 13-2 Command Utility Subcommands for Broker Management
Syntax
Description
shutdown bkr [-b hostName:portNumber]
Shut down broker
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 a Broker for more information.
resume bkr [-b hostName:portNumber]
Resume broker
update bkr [-b hostName:portNumber]
-o property1=value1
[ [-o property2=value2] … ]Set broker properties
See Chapter 14, "Broker Properties Reference," for information on broker properties.
reload cls
Reload cluster configuration1
Forces all persistent information to be brought up to date.
query bkr -b hostName:portNumber
List broker property values
Also lists all running brokers connected to the specified broker in a 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 brokerrts Rate of flow of messages and packets into
and out of the broker per secondcxn Connections, virtual memory heap, and
threadsDefault 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).
1This option applies only to broker clusters.
Connection Service Management
Table 13-3 lists the imqcmd subcommands for managing connection services.
Table 13-3 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 servicerts Rate of flow of messages and packets into
and out of the broker per second by way of
the specified connection servicecxn Connections, virtual memory heap, and
threadsDefault 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 13-4 lists the imqcmd subcommands for managing connections.
Physical Destination Management
Table 13-5 lists the imqcmd subcommands for managing physical destinations. In all cases, the -t (destination type) option can take either of two values:
q Queue destination
t Topic destination
Table 13-5 Command Utility Subcommands for Physical Destination Management
Syntax
Description
create dst -t destType -n destName
[-o property1=value1]
[ [-o property2=value2] … ]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 -t destType -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:
CONSUMERS Pause delivery to message
consumersPRODUCERS Pause delivery to message producers
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.
update dst -t destType -n destName
-o property1=value1
[ [-o property2=value2] … ]Set physical destination properties
See Chapter 15, "Physical Destination Property Reference," for information on physical destination properties.
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.
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 memoryrts Rate of flow of messages and packets into
and out of the broker per second, along with
other rate informationcon 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).
1This operation cannot be performed in a broker cluster whose master broker is temporarily unavailable.
Durable Subscription Management
Table 13-6 lists the imqcmd subcommands for managing durable subscriptions.
Table 13-6 Command Utility Subcommands for Durable Subscription Management
Syntax
Description
destroy dur -c clientID
-n subscriberNameDestroy durable subscription1
purge dur -c clientID
-n subscriberNamePurge all messages for durable subscription
list dur -d topicName
List durable subscriptions for topic
1This operation cannot be performed in a broker cluster whose master broker is temporarily unavailable.
Transaction Management
Table 13-7 lists the imqcmd subcommands for managing transactions.
General Command Utility Options
The additional options listed in Table 13-8 can be applied to any subcommand of the imqcmd command.
Table 13-8 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.
-p password
Password for authentication1
-passfile path
Location of password file
See Using a Password File for more information.
-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: Use runtime installed on system or bundled with Message Queue.
-f
Perform action without user confirmation
-s
Silent mode (no output displayed)
-v
-h
-H
Display expanded usage help, including attribute list and examples2,3
1This option is being deprecated and will eventually be removed. Instead, either omit the password entirely (so that the command will prompt for it interactively) or use the -passfile option to specify a password file containing the password.
2Any other options specified on the command line are ignored .
3A user name and password are not needed with this option.
Object Manager UtilityThe Object Manager utility (imqobjmgr) creates and manages Message Queue administered objects. Table 13-9 lists the available subcommands.
Table 13-10 lists the options to the imqobjmgr command.
Table 13-10 Object Manager Options
Option
Description
-l lookupName
JNDI lookup name of administered object
-j attribute=value
Attributes of JNDI object store (see Object Stores)
-t objectType
Type of administered object:
q Queue destination
t Topic destination
cf Connection factory
qf Queue connection factory
tf Topic connection factory
xcf Connection factory for distributed transactions
xqf Queue connection factory for distributed transactions
xtf Topic connection factory for distributed transactions
e SOAP endpoint (see Message Queue Developer’s Guide for Java Clients)
-o attribute=value
Attributes of administered object (see Administered Object Attributes and Chapter 16, "Administered Object Attribute Reference")
-r readOnlyState
Is administered object read-only?
If true, client cannot modify object’s attributes. Default value: false.
-i fileName
Name of command file containing all or part of subcommand clause
-pre
Preview results without performing command
This option is useful for checking the values of default attributes.
-javahome path
Location of alternative Java runtime
Default: 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
-h
Display usage help1
-H
Display expanded usage help, including attribute list and examples1
1Any other options specified on the command line are ignored .
Database Manager UtilityThe Database Manager utility (imqdbmgr) sets up the database schema for a JDBC-based persistent data store. You can also use it to delete Message Queue database tables that have become corrupted or to change the data store. Table 13-11 lists the available subcommands.
Table 13-12 lists the options to the imqdbmgr command.
Table 13-12 Database Manager Options
Option
Description
-b instanceName
Instance name of broker
-Dproperty=value
Set broker configuration property
See Persistence Properties for information about persistence-related broker configuration properties.
Caution: Be careful to check the spelling and formatting of properties set with this option. Incorrect values will be ignored without notification or warning.
-u name
User name for authentication
-p password
Password for authentication1
-passfile path
Location of password file
See Using a Password File for more information.
-v
Display version information2
-h
Display usage help2
1This option is being deprecated and will eventually be removed. Instead, either omit the password entirely (so that the command will prompt for it interactively) or use the -passfile option to specify a password file containing the password.
2Any other options specified on the command line are ignored .
User Manager UtilityThe User Manager utility (imqusermgr) is used for populating or editing a flat-file user repository. The utility must be run on the same host where the broker is installed; if a broker-specific user repository does not yet exist, you must first start up the corresponding broker instance in order to create it. You will also need the appropriate permissions to write to the repository: on the Solaris or Linux platforms, this means you must be either the root user or the user who originally created the broker instance.
Table 13-13 lists the subcommands available with the imqusermgr command. In all cases, the -i option specifies the instance name of the broker to whose user repository the command applies; if not specified, the default name imqbroker is assumed.
In addition, the options listed in Table 13-14 can be applied to any subcommand of the imqusermgr command.
Table 13-14 General User Manager Options
Option
Description
-f
Performs action without user Perform action without user confirmation.
-s
Silent mode (no output displayed)
-v
Display version information1
-h
Display usage help1
1Any other options specified on the command line are ignored .
Service Administrator UtilityThe Service Administrator utility (imqsvcadmin) utility installs a broker as a Windows service. Table 13-15 lists the available subcommands.
Table 13-16 lists the options to the imqsvcadmin command.
Table 13-16 Service Administrator Options
Option
Description
-javahome path
Location of alternative Java runtime
Default: Use runtime installed on system or bundled with Message Queue.
-jrehome path
Location of alternative Java Runtime Environment (JRE)
-vmargs arg1 [ [arg2] … ]
Additional arguments to pass to Java Virtual Machine running broker service1
Example:
imqsvcadmin install -vmargs "-Xms16m -Xmx128m"
-args arg1 [ [arg2] … ]
Additional command line arguments to pass to broker service1
Example:
imqsvcadmin install -args "-passfile d:\imqpassfile"
See Broker Utility for information about broker command line arguments.
-h
Display usage help2
1These arguments can also be specified in the Start Parameters field under the General tab in the service’s Properties window (reached via the Services tool in the Windows Administrative Tools control panel).
2Any other options specified on the command line are ignored .
Any information you specify using the -javahome, -vmargs, and -args options is stored in the Windows registry under the keys JREHome, JVMArgs, and ServiceArgs in the path
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\iMQ_Broker\Paramet ers
Key Tool UtilityThe Key Tool utility (imqkeytool) generates a self-signed certificate for the broker, which can be used for the ssljms, ssladmin, or cluster connection service. The syntax is
imqkeytool -broker
On UNIX systems, you may need to run the utility from the superuser (root) account.