|Sun ONE Message Queue, Version 3.0.1 Administrator's Guide|
Chapter 5 Starting and Configuring a Broker
After installing Sun ONE Message Queue (MQ), you use the imqbrokerd command to start a broker. The configuration of the broker instance is governed by a set of configuration files and by options passed with the imqbrokerd command, which override corresponding properties in the configuration files.
This chapter explains the syntax of the imqbrokerd command and how you use command line options and configuration files to configure the broker instance. In addition, it also describes how you do the following:
For a description of how to start and use the broker as a Windows service, see "Using a Broker as a Windows Service".
Installed configuration files, which are used to configure the broker, are located in the following directory.
(/usr/share/lib/imq/props/broker on Solaris)
This directory stores the following files:
- A default configuration file that is loaded on startup. This file is called default.properties and is not editable. You might need to read this file to determine default settings and to find the exact names of properties you want to change.
- An installation configuration file that contains any properties specified when MQ is installed. This file is called install.properties; it cannot be edited after installation.
In addition, the first time you run a broker, an instance configuration file is created that you can use to specify configuration properties for that instance of the broker. This file is maintained by the broker instance in response to administrative commands and can also be edited directly if you're careful. The instance configuration file is stored in the following location:
(/var/imq/instances/brokerName/props/config.properties on Solaris)
Where brokerName is the name of the broker instance (imqbroker by default). You can edit an instance configuration file to make configuration changes (see "Editing the Instance Configuration File").
If you connect broker instances in a cluster (see "Multi-Broker Clusters (Enterprise Edition)") you may also need to use a cluster configuration file to specify cluster configuration information. For more information, see "Cluster Configuration Properties".
Merging Property Values
At startup, the system merges property values in the different configuration files. It uses values set in the installation and instance configuration files to override values specified in the default configuration file. You can override the resulting values by using imqbrokerd command options. This scheme is illustrated in Figure 5-1.
Figure 5-1    Broker Configuration Files
Property Naming Syntax
Any MQ property definition in a configuration file uses the following naming syntax:
For example, the following entry defines the queue type for an auto-create queue:
The following entry defines the message expiration timeout value:
Table 5-1 lists the broker configuration properties (and their default values) in alphabetical order.
Editing the Instance Configuration File
The first time a broker instance is run, a config.properties file is automatically created. You can edit this instance configuration file to customize the behavior and resource use of the corresponding broker instance.
The broker instance reads the config.properties file only at startup. To make permanent changes to the config.properties file, you can either
- use administration tools. For information about properties you can set using imqcmd, see Table 6-5.
- edit the config.properties file while the broker instance is shut down; then restart the instance. (On Solaris and Linux platforms, only the user that first started the broker instance has permission to edit the config.properties file.)
Table 5-1 lists the broker instance configuration properties (and their default values) in alphabetical order. For more information about the meaning and use of each property, please consult the specified cross-referenced section.
Table 5-1    Broker Instance Configuration Properties
byte string 1
0 (no limit)
(/etc/imq on Solaris)
byte string 1
25 (Solaris & Linux)
inherits value from system-wide property
inherits value from system-wide property
inherits value from system-wide property
512 (Solaris & Linux)
0 (no limit)
0 (no limit)
1 Values that are typed as a byte string, can be expressed in bytes, Kbytes, and Mbytes: For example: 1000 means 1000 bytes; 7500b means 7500 bytes; 77k means 77 kilobytes (77 x 1024 = 78848 bytes); 17m means 17 megabytes (17 x 1024 x 1024 = 17825792 bytes)
Starting a Broker
To start a broker instance use the imqbrokerd command.
You cannot start a broker instance using the Administration Console (imqadmin) or the Command Utility (imqcmd). The broker instance must already be running to use these MQ administration tools.
To override one or more property values, specify a valid imqbrokerd command-line option. Command-line options override values in the broker configuration files, but only for the current broker session: command line options are not written to the instance configuration file.
The syntax of the imqbrokerd command is as follows (options and arguments are separated by a space):
imqbrokerd [[ -Dproperty=value]...]
[ -backup fileName]
[ -cluster "[broker] [[,broker]...]"
[ -dbuser userName] [ -dbpassword password]
[ -javahome path | -jrehome path]
[ -ldappassword password]
[ -license name]
[ -loglevel level]
[ -metrics number]
[ -name brokerName ] [ -port number]
[ -password keypassword] [ -passfile fileName]
[ -remove instance]
[ -reset data]
[ -restore fileName]
[ -silent] [ -tty]
[ -version] [ -vmargs arg [[arg]...]
For example, to start a broker that uses the default broker name and configuration, use the following command:
This starts a default instance of a broker (named imqbroker) on the local machine with the Port Mapper at port 7676.
On Solaris, you can configure the broker to automatically restart after an abnormally exit, by setting the RESTART property in the /etc/imq/imqborkerd.conf configuration file to YES.
On Solaris and Linux platforms, permissions on the directories containing configuration information and persistent data depend on the umask of the user that starts the broker instance the first time. Hence, for the broker instance to function properly, it must be started subsequently only by the original user.
Table 5-2 describes the options to the imqbrokerd command and describes the configuration properties, if any, affected by each option.
Table 5-2    imqbrokerd Options
Applies only to broker clusters. Backs up a Master Broker's configuration change record to the specified file. See "Backing up the Master Broker's Configuration Change Record".
broker is either
Sets imq.cluster.brokerlist to the list of brokers to which to connect.
Applies only to broker clusters. Connects to all the brokers on the specified hosts and ports. This list is merged with the list in the imq.cluster.brokerlist property. If you don't specify a value for host, localhost is used. If you don't specify a value for port, the value 7676 is used. See "Working With Clusters (Enterprise Edition)" for more information on how to use this option to connect multiple brokers.
password to specified password
Specifies the password for a plugged-in JDBC-compliant data store. See Appendix A, "Setting Up Plugged-in Persistence."
to specified user name
Specifies the user name for a plugged-in JDBC-compliant database. See Appendix A, "Setting Up Plugged-in Persistence."
Sets system properties. Overrides corresponding property value in instance configuration file.
Sets the specified property to the specified value. See Table 5-1 for broker configuration properties.
Caution: Be careful to check the spelling and formatting of properties set with the D option. If you pass incorrect values, the system will not warn you, and MQ will not be able to set them.
Performs action without user confirmation. This option applies only to the -remove instance option, which normally requires confirmation.
Displays help. Nothing else on the command line is executed.
Specifies the path to an alternate
Java 2- compatible JDK. The default is to use the bundled runtime.
Specifies the path to a Java 2 JRE.
ldap.password to specified password
Specifies the password for accessing a LDAP user repository. See "Using an LDAP Server for a User Repository".
Specifies the license to load, if different from the default for your MQ product edition. If you don't specify a license name, this lists all licenses installed on the system. Depending on the installed MQ edition, the values for name are pe (Platform Editionbasic features), try (Platform Edition90-day trial enterprise features), and unl (Enterprise Edition). See "Product Editions".
Sets imq.broker.log.level to the specified level.
Specifies the logging level as being one of NONE, ERROR, WARNING, or INFO. The default value is INFO. For more information, see "Logger".
interval to the specified number of seconds.
Specifies that metrics be reported at an interval specified in seconds.
Sets imq.instancename to the specified name.
Specifies the instance name of this broker and uses the corresponding instance configuration file. If you do not specify a broker name, the name of the file is set to imqbroker.
Note: If you run more than one instance of a broker on the same host, each must have a unique name.
enabled to true. Sets jmq.
passfile.dirpath to the path that contains the file.
Sets imq.passfile.name to the name of the file.
Specifies the name of the file from which to read the passwords for the SSL keystore, LDAP user repository, or JDBC-compliant database. For more information, see "Using a Passfile".
password to the specified password.
Specifies the password for the SSL certificate keystore. For more information, see "Security Manager".
Sets imq.portmapper.port to the specified number.
Specifies the broker's Port Mapper port number. By default, this is set to 7676. To run two instances of a broker on the same server, each broker's Port Mapper must have a different port number. JMS clients connect to the broker instance using this port number.
Causes the broker instance to be removed: deletes the instance configuration file, log files, persistent store, and other files and directories associated with the instance. Requires user confirmation unless -force option is also specified.
-reset store| messages|
Resets the data store (or a subset of the data store) or the configuration properties of a broker instance, depending on the argument given.
Resetting the data store clears out all persistent data, including persistent messages, durable subscriptions, and transaction information. This allows you to start the broker instance with a clean slate. You can also clear only all persistent messages or only all durable subscriptions. (If you do not want the persistent store to be reset on subsequent starts, then re-start the broker instance without using the -reset option.) For more information, see "Persistence Manager".
Resetting the broker's properties, replaces the existing instance configuration file (config.properties) with an empty file: all properties assume default values.
Applies only to broker clusters. Replaces the Master Broker's configuration change record with the specified backup file. This file must have been previously created using the -backup option. See "Restoring the Master Broker's Configuration Change Record".
threadpool_model to shared.
Specifies that the jms connection service be implemented using the shared threadpool model, in which threads are shared among connections to increase the number of connections supported by a broker instance. For more information, see "Connection Services".
output to NONE.
Turns off logging to the console.
output to ALL
Specifies that all messages be displayed to the console. By default only WARNING and ERROR level messages are displayed.
Displays the version number of the installed product.
-vmargs arg [[arg]...]
Specifies arguments to pass to the Java VM. Separate arguments with spaces. If you want to pass more than one argument or if an argument contains a space, use enclosing quotation marks. For example:
imqbrokerd -tty -vmargs "-Xmx128m -Xincgc"
Working With Clusters (Enterprise Edition)
This section describes the properties you use to configure multi-broker clusters, describes a couple of methods of connecting brokers, and explains how you manage clusters. For an introduction to clusters, see "Multi-Broker Clusters (Enterprise Edition)".
When working with clusters, make sure that you synchronize clocks among the hosts of all brokers in a cluster.
Cluster Configuration Properties
When you connect brokers into a cluster, all the connected brokers must specify the same values for cluster configuration properties. These properties describe the participation of the brokers in a cluster. Table 5-3 summarizes the cluster-related configuration properties.
Table 5-3    Cluster Configuration Properties
Specifies all brokers in a cluster in a comma-separated list; each item specifies the host and port of a broker.
For example: host1:3000, host2:8000, ctrhost
Specifies the host and port of the Master Broker.
Set this value for production environments.
For example, ctrhost:7676
Specifies the location of the cluster configuration file.
For example: http://webserver/imq/cluster.properties
For each broker within a cluster, can be used to specify the port number for the cluster connection service. The cluster connection service is used for internal communication between brokers in a cluster.
Default: 0 (port is dynamically allocated)
For each broker within a cluster, can be used to specify the host (hostname or IP address) to which the cluster connection service binds if there is more than one host available (for example, if there is more than one network interface card in a computer). The cluster connection service is used for internal communication between brokers in a cluster.
Default: null (all available hosts)
You can use one of two methods to set cluster properties:
- You set the cluster-related configuration properties in each broker's instance configuration file (or in the command line that starts each broker). For example, to connect broker A (on host1, port 7676), broker B (on host2, port 5000) and broker C (on ctrlhost, port 7676), the instance configuration file for brokers A, B, and C would need to set the following property.
If you decide to change a cluster configuration, this method requires you to update cluster-related properties in all the brokers
- You set cluster configuration properties in one central cluster configuration file. These properties might include the list of brokers to be connected (imq.cluster.brokerlist) and optionally, the address of the Master Broker (imq.cluster.masterbroker).
The following code sample shows the contents of a cluster configuration file. Both host1 and ctrlhost are running on the default port. These properties specify that host1 and ctrlhost are connected in a cluster and that ctrlhost is the Master Broker.
The instance configuration file for each broker connected in this cluster, must then contain the url of the cluster configuration file; for example:
This section describes two methods of connecting brokers into a clusters. No matter which method you use, each broker that you start attempts to connect to the other brokers every five seconds; that attempt will succeed once the other brokers in the cluster are started up.
If you connect brokers into a cluster, it is not necessary to start the Master Broker first. If a broker in the cluster starts before the Master Broker, it will remain in a suspended state, rejecting client connections. When the Master Broker starts, the suspended broker will automatically become fully functional.
Method 1: No Cluster Configuration File
To connect brokers into a cluster
- Use the -cluster option to the imqbrokerd command that starts a broker, and specify the complete list of brokers (to connect to) as an argument to the -cluster option.
- Do this for each broker you want to connect to the cluster when you start that broker.
For example, the following command starts a new broker and connects it to the broker running on the default port on host1, the broker running on port 7677 on host2 and the broker running on port 7678 on localhost.
imqbrokerd -cluster host1,host2:7677,:7678
Method 2: Using a Cluster Configuration File
It is also possible to create a cluster configuration file that specifies the list of brokers to be connected (and optionally, the address of the Master Broker). This method of defining clusters is better suited for production systems. Remember, that each broker in the cluster must set the value of the imq.cluster.url property to point to the cluster configuration file.
Adding Brokers to Clusters
Once you have set up a broker cluster, you might need to add a new broker or restart a broker that is already part of the cluster.
To add a new broker to an existing cluster, you can do one of the following:
If you are not using a cluster configuration file, when you start the new broker, specify the imq.cluster.brokerlist and (if necessary) the imq.cluster.masterbroker properties on the command line using the -D option.
To add a broker to a cluster if you are using a cluster configuration file
- Add the new broker to the imq.cluster.brokerlist property in the cluster configuration file.
- Issue the following command to any broker in the cluster.
imqcmd reload cls
This forces all the brokers to reload the imq.cluster.brokerlist property and to make sure that all persistent information for brokers in the cluster is up to date.
Restarting a Broker in a Cluster
To restart a broker that is already a member of a cluster, you can do one of the following:
- If the cluster is defined using a cluster configuration file, use the -D option to specify the imq.cluster.url property on the command line used to start the broker.
- If the cluster is not defined using a cluster configuration file, when you start the new broker, specify the imq.cluster.brokerlist (and if necessary the imq.cluster.masterbroker) properties on the command line using the -D option. If the cluster does not include a Master Broker, you can simply use the -cluster option to specify the list of brokers in the cluster when you start the new broker.
Removing a Broker from a Cluster
Take note of the following when removing a broker from a cluster:
- If the brokers A, B, and C were all started using the following command line, then just restarting A will not remove it from the cluster.
Instead, you need to restart all the other brokers with the following command line:
Then, you need to start broker A without specifying the -cluster option.
- If the list of brokers was specified using a cluster configuration file, then you will need to do the following:
Use the imqcmd reload cls command to force all the brokers to reload their cluster configuration and thereby reconfigure the cluster.
Backing up the Master Broker's Configuration Change Record
Each cluster can have one Master Broker that keeps track of any changes in the persistent state of the cluster: this includes durable subscriptions and physical destinations created by the administrator. All brokers consult the Master Broker during startup in order to synchronize information about these persistent objects. Consequently, the failure of the Master Broker can cripple the entire cluster. For this reason, it is important to backup the Master Broker's change record periodically by using the -backup option of the imqbrokerd command. For example,
imqbrokerd -backup mybackuplog
It is important you do this in a timely manner. Restoring a very old backup can result in loss of information: any persistent objects created since the backup was last done will be lost.
Restoring the Master Broker's Configuration Change Record
To restore the Master Broker in case of failure
- Shut down all the brokers in the cluster.
- Restore the Master Broker's configuration change record using the following command:
imqbrokerd -restore mybackuplog
- If you assign a new name or port number to the Master Broker, you must update the cluster configuration file to specify that the Master Broker is part of the cluster and to specify its new name (using the property imq.cluster.masterbroker).
- Restart all the brokers.
The restoration of the broker will inevitably result in some stale data being reloaded into the broker's configuration change record; however, doing frequent periodic backups, as described in the previous section, should minimize this problem.
Because the Master Broker keeps track of the entire history of changes to persistent objects, its database can grow significantly over a period of time. The backup and restore operations have the positive effect of compressing and optimizing this database.
This section describes the default logging configuration for the broker and explains how you can change that configuration in order to redirect log information to alternate output channels, to change rollover criteria, and to report broker metrics. For an introduction to logging, see "Logger".
Default Logging Configuration
When you start the broker, it is automatically configured to save log output to a set of rolling log files located at
(/var/imq/instances/brokerName/log/ on Solaris)
The log files are simple text files. They are named as follows, from earliest to latest:
By default, log files are rolled over once a week; the system maintains nine backup files.
- To change the directory in which the log files are kept, set the property imq.log.file.dirpath to the desired path.
- To change the root name of the log files from log to something else, set the imq.log.file.filename property.
The broker supports three log categories: ERROR, WARNING, INFO (see Table 2-7). Setting a logging level gathers messages for all levels up to and including that level. The default log level is INFO. This means that ERROR, WARNING, and INFO messages are logged.
Log Message Format
Logged messages consist of a timestamp, message code, and the message itself. The volume of information varies with the log level you have set. The following is an example of an INFO message.
[13/Sep/2000:16:13:36 PDT] B1004 Starting the broker service using tcp [ 25374,100] with min threads 50 and max threads of 500
Changing the Logger Configuration
All Logger properties are described in Table 2-8.
To change the Logger configuration for a broker
- Set the log level.
- Set the output channel (file, console, or both) for one or more logging categories.
- If you log output to a file, configure the rollover criteria for the file.
You complete these steps by setting Logger properties. You can do this in one of two ways:
- Change or add Logger properties in the config.properties file for a broker before you start the broker.
- Specify Logger command line options in the imqbrokerd command that starts the broker. You can also use the broker option -D to change Logger properties (or any broker property).
Options passed on the command line override properties specified in the broker instance configuration files. Table 5-4 lists the imqbrokerd options that affect logging.
Table 5-4    imqbrokerd Logger Options and Corresponding Properties
Specifies the interval (in seconds) at which metrics information is gathered.
Sets the log level to one of ERROR, WARNING, INFO.
Turns off logging to the console
Sends all messages to the console. By default only WARNING and ERROR level messages are displayed.
The following sections describe how you can change the default configuration in order to do the following:
- change the output channel (the destination of log messages)
- change rollover criteria
- log broker metrics information
Changing the Output Channel
By default, error and warning messages are displayed on the terminal as well as being logged to a log file. (On Solaris error messages are also written to the system's syslog daemon.)
You can change the output channel for log messages in the following ways:
- To have all log categories (for a given level) output displayed on the screen, use the -tty option to the imqbrokerd command.
- To prevent log output from being displayed on the screen, use the -silent option to the imqbrokerd command.
- Use the imq.log.file.output property to specify which categories of logging information should be written to the log file. For example,
- Use the imq.log.console.output property to specify which categories of logging information should be written to the console. For example,
- On Solaris, use the imq.log.syslog.output property to specify which categories of logging information should be written to Solaris syslog. For example,
Before changing the destination of log messages, you must make sure that logging is set at the level that corresponds to the log category you are mapping to the output channel. For example, if you set the log level to ERROR and then set the imq.log.console.output property to WARNING, no messages will be logged because you have not enabled the logging of those level messages.
Changing Rollover Criteria
There are two criteria for rolling over log files: time and size. The default is to use a time criteria and roll over files every seven days.
- To change the time interval, you need to change the property imq.log.file.rolloversecs. For example, the following property definition changes the time interval to ten days:
- To change the rollover criteria to depend on file size, you need to set the imq.log.file.rolloverbytes property. For example, the following definition directs the broker to rollover files after they reach a limit of 500,000 bytes
If you set both the time-related and the size-related rollover properties, the first limit reached will trigger the rollover. As noted before, the broker maintains up to nine rollover files.
Logging Broker Performance Metrics
The broker's default configuration, includes the following settings:
As a result of these settings, the broker gathers performance metrics for the broker as well as for active connection services, but it does not generate metrics reports.
You can have the broker generate metrics reports in one of two ways:
- Use the -metrics option to the imqbrokerd command and specify the interval (in seconds) at which the broker generates reports.
- Set the imq.metrics.interval property to the interval (in seconds) at which you want the broker to generate reports.
Because metrics reports are included in the INFO category, metric reports, by default, are written to the log file output channel.
The following shows sample metrics information:
Connections: 0 JVM Heap: 6291456 bytes (5186320 free)
In: 0 mesgs (0bytes) 0 pkts (0 bytes)
Out: 0 mesgs (0bytes) 0 pkts (0 bytes)
Rate In: 0 msgs/sec (0 bytes/sec) 0 pkts/sec (0 bytes/sec)
Rate Out: 0 msgs/sec (0 bytes/sec) 0 pkts/sec (0 bytes/sec)
Table 5-5 describes the meaning of the metrics generated for each connection service.
Table 5-5    Metrics Gathered for Connection Services
Pkts in (total)
Total number of packets read by the broker since the last reset. This includes MQ protocol packets, not just JMS messages.
Pkts out (total)
Total number of packets written by the broker since the last reset.
JMS Messages in (total)
Total number of JMS messages read by the broker since last reset.
JMS Messages out (total)
Total number of JMS messages written by the Broker since last reset.
Message Bytes in (total)
Total number of message bytes read by the Broker since last reset.
Message Bytes out (total)
Total number of message bytes written.
Current # connections
Current number of open connections.
Table 5-6 describes the metrics gathered and reported for each broker.
Table 5-6    Metrics Gathered for Each Broker
VM heap size (bytes)
Maximum size of the Java VM heap.
VM heap free space (bytes)
Amount of free space left in the Java VM heap.
This information is also available via the imqcmd metrics command.