Sun Java System Message Queue 3.5 SP1 Administration Guide |
Chapter 5
Starting and Configuring a BrokerAfter installing Sun Java System Message Queue, 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".
Configuration FilesInstalled broker configuration file templates, which are used to configure the broker, are located in a directory that varies by operating system, as shown in Appendix A, "Location of Message Queue Data."
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 Message Queue is installed. This file is called install.properties; it cannot be edited after installation.
Instance Configuration File
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. The instance configuration file is stored in a directory identified by the name of the broker instance (instanceName) with which the configuration file is associated (see Appendix A, "Location of Message Queue Data"):
…/instances/instanceName/props/config.properties
The instance configuration file is maintained by the broker instance. It is modified when you make configuration changes using administration tools. You can also edit an instance configuration file by hand to make configuration changes (see "Editing the Instance Configuration File"). To do so, you must be the owner of the …/instances/instanceName directory or log in as root to change privileges on the directory.
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 Message Queue property definition in a configuration file uses the following naming syntax:
propertyName=value[[,value1]…]
For example, the following entry specifies that the broker will hold up to 50,000 messages in memory and persistent storage before rejecting additional messages:
imq.system.max_count=50000
The following entry specifies that a new log file will be created every day (86400 seconds):
imq.log.file.rolloversecs=86400
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-4.
- 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.
Starting a BrokerTo start a broker instance use the imqbrokerd command.
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.
Syntax of the imqbrokerd Command
The syntax of the imqbrokerd command is as follows (options and arguments are separated by a space):
Note
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.
Note
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.
Startup Examples
The following examples show the use of the imqbrokerd command. For more details on the imqbrokerd command line options, see Table 5-2.
To Start a Broker Instance That Uses the Default Broker Name and Configuration
Use the following command:
imqbrokerd
This starts a default instance of a broker (named imqbroker) on the local machine with the Port Mapper at port 7676.
To Start a Broker Instance With a Trial Enterprise Edition License
If you have a Platform Edition license, but wish to try out Enterprise Edition features for a period of 90 days, you can enable a trial Enterprise Edition license, using the -license command line option and passing “try” as the license to use:
imqbrokerd -license try
You must use this option each time you start the broker instance, otherwise it defaults back to the basic Platform Edition license.
To Start a Named Broker Instance With Plugged-in Persistence
To start a broker named myBroker that uses a plugged-in data store (see Appendix B, "Setting Up Plugged-in Persistence") and which requires a username and password, use the following command:
imqbrokerd -name myBroker -dbuser myName -dbpassword myPassword
Summary of imqbrokerd Options
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
Option
Properties Affected
Description
-backup fileName
None affected.
Applies only to broker clusters. Backs up a Master Broker’s configuration change record to the specified file. See "Backing up the Configuration Change Record".
-cluster“[broker1]
[[,broker2]…]”
where broker is eitherSets 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.
-dbpassword password
Sets imq.persist.jdbc.
password to specified passwordSpecifies the password for a plugged-in JDBC-compliant data store. See Appendix B, "Setting Up Plugged-in Persistence."
-dbuser userName
Sets imq.persist.jdbc.user
to specified user nameSpecifies the user name for a plugged-in JDBC-compliant database. See Appendix B, "Setting Up Plugged-in Persistence."
-Dproperty=value
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 Message Queue will not be able to set them.
-force
None affected.
Performs action without user confirmation. This option applies only to the
-remove instance and the -upgrade-store-nobackup options, which normally require confirmation.-h|-help
None affected.
Displays help. Nothing else on the command line is executed.
-javahome path
None affected.
Specifies the path to an alternate
Java 2- compatible JDK. The default is to use the bundled runtime.-ldappassword
passwordSets imq.user_repository.
ldap.password to specified passwordSpecifies the password for accessing a LDAP user repository. See "Using an LDAP Server for a User Repository".
-license [licenseName]
None affected.
Specifies the license to load, if different from the default for your Message Queue product edition. If you don’t specify a license name, this lists all licenses installed on the system. Depending on the installed Message Queue edition, the values for licenseName are pe (Platform Edition—basic features), try (Platform Edition—90-day trial enterprise features), and unl (Enterprise Edition). See "Product Editions".
-loglevel level
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".
-metrics interval
Sets imq.metrics.
interval to the specified number of seconds.Specifies that broker metrics be written to the Logger at an interval specified in seconds.
-name instanceName
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 instance 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.-passfile fileName
Sets imq.passfile.
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 keypassword
Sets imq.keystore.
password to the specified password.Specifies the password for the SSL certificate keystore. For more information, see "Security Manager".
-port number
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. Message Queue clients connect to the broker instance using this port number.
-remove instance
None affected.
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|
durables|
propsNone affected.
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 restarts, 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.
-restore fileName
None affected.
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 Configuration Change Record".
-shared
Sets imq.jms.
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".
-silent|-s
Sets imq.log.console.
output to NONE.Turns off logging to the console.
-tty
Sets imq.log.console.
output to ALLSpecifies that all messages be displayed to the console. By default only WARNING and ERROR level messages are displayed.
-upgrade-store-
nobackupNone affected
Specifies that an upgrade to Message Queue 3.5 or Message Queue 3.5 SPx from an incompatible version automatically removes the old data store. For additional details, see the Message Queue Installation Guide.
-version
None affected.
Displays the version number of the installed product.
-vmargs arg1 [[arg2]…]
None affected
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 two methods of connecting brokers, and explains how to 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 (see "System Clock Settings").
Cluster Configuration Properties
When you connect brokers into a cluster, all the connected brokers must specify as set of cluster configuration properties. These properties describe the participation of the brokers in a cluster. Table 5-3 summarizes the cluster-related configuration properties. Properties marked with an asterisk (*) must have the same value for all brokers in a cluster.
Table 5-3 Cluster Configuration Properties
Property Name
Description
imq.cluster.brokerlist*
Specifies all the brokers in a cluster. Consists of a comma-separated list of host:port entries, where host is the host name of each broker and port is its Port Mapper port number. For example:
host1:3000, host2:8000, ctrhostimq.cluster.
masterbroker*Specifies which broker in a cluster (if any) is the Master Broker that keeps track of state changes. Property consists of host:port where host is the host name of the Master Broker and port is its Port Mapper port number. Set this property for production environments. For example, ctrhost:7676
imq.cluster.url*
Specifies the location of a cluster configuration file. Used in cases where brokers reference one central cluster configuration file rather than being individually configured. Consists of a URL string: If kept on a web server it can be accessed using a normal http:URL. If kept on a shared drive it can be accessed using a file:URL.
For example: http://webserver/imq/cluster.properties
file:/net/mfsserver/imq/cluster.propertiesimq.cluster.port
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)imq.cluster.hostname
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: inherits the value of imq.hostname (see Table 2-3)imq.cluster.transport*
Specifies the network transport used by the cluster connection service for internal communication between brokers in a cluster. For secure, encrypted message delivery between brokers, set this property to ssl for all brokers in a cluster. Default: tcp
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.
imq.cluster.brokerlist=host1, host2:5000, ctrlhost
- 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), the network transport to use for the cluster connection service (imq.cluster.transport), 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, host2, 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:
Connecting Brokers
This section describes how to connect brokers into a cluster and how to configure the cluster for secure, encrypted message delivery between brokers in the cluster.
Connection Methods
There are two general methods of connecting brokers into a cluster: connecting with or without a cluster configuration file.
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 Master Broker is started up. 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: Connecting Without a 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: Connecting With 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. If you use this method, each broker in the cluster must set the value of the imq.cluster.url property to point to the cluster configuration file.
Secure Inter-Broker Connections
In situations where you want secure, encrypted message delivery between the brokers in a cluster, you have to configure the cluster connection service to use an SSL-based transport protocol, as follows.
To Configure Secure Connections Within a Cluster
- For each broker in the cluster, set up SSL-based connection services.
See the instructions in "Setting Up an SSL-based Service Over TCP/IP".
- Set the imq.cluster.transport cluster configuration property to ssl.
If you are not using a cluster configuration file, you need to set this property for each broker in the cluster.
Managing Brokers in a Cluster
Once you have set up a broker cluster, you might need to add a new broker, restart a broker that is already part of the cluster, or remove a broker from the cluster.
Adding Brokers to a Cluster
To Add a New Broker to an Existing Cluster
- If you are using a cluster configuration file, then
- Add the new broker to the imq.cluster.brokerlist property in the cluster configuration file.
- Issue the following command to every 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.
- Start the new broker specifying the imq.cluster.url property on the command line using the -D option.
This points the broker to the cluster configuration file.
- If you are not using a cluster configuration file, then when you start the new broker, specify the imq.cluster.brokerlist,the imq.cluster.transport (if using a secure cluster connection service), and (if necessary) the imq.cluster.masterbroker properties on the command line using the -D option.
Restarting a Broker in a Cluster
If a broker in a cluster crashed or was shut down for some reason, you need to restart it as a member of the cluster.
To Restart a Broker That is Already a Member of an Existing Cluster
- If the cluster is not defined using a cluster configuration file, when you restart the 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 restart the broker.
- 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.
Removing a Broker from a Cluster
To Remove a Broker From an Existing Cluster
- If the list of brokers was specified using a cluster configuration file, then you will need to do the following:
- Remove mention of the broker from the configuration file.
- Change or remove the imq.cluster.url property for the broker that is being removed so that it no longer uses the common properties.
- Use the imqcmd reload cls command to force all the brokers to reload their cluster configuration and thereby reconfigure the cluster.
Managing 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. The state includes information about durable subscriptions and administrator-created physical destinations. All brokers consult the Master Broker during startup (which, in turn, consults its configuration change record) in order to synchronize information about these persistent objects. Consequently, the failure of the Master Broker would make such synchronization impossible. As a result, if the Master Broker fails, you cannot create or delete physical destinations or durable subscriptions.
Because of the important information it contains, it is important that you back up the Master Broker’s configuration change record regularly and restore it in case of failure.
The following sections explain how to back up and restore the configuration change record.
Backing up the Configuration Change Record
To Back Up the Configuration Change Record
Use 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 changes in physical destinations or durable subscriptions since the backup was last done will be lost.
Restoring the 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.
LoggingThis section describes the default logging configuration for the broker and explains how you can change that configuration to redirect log information to alternate output channels and change log file rollover criteria. For an introduction to logging, see "Logger". For information on using logging to report broker metrics, see "Monitoring Tools".
Default Logging Configuration
When you start the broker, it is automatically configured to save log output to a set of rolling log files located in a directory identified by the name of the broker instance (instanceName) with which the log files are associated (see Appendix A, "Location of Message Queue Data"):
…/instances/instanceName/log/
The log files are simple text files. They are named as follows, from earliest to latest:
log.txt
log_1.txt
log_2.txt
…
log_9.txtBy default, log files are rolled over once a week; the system maintains nine backup files.
The broker supports three log categories: ERROR, WARNING, INFO (see Table 2-7). Setting a logging level gathers messages for that level and all higher levels. The default log level is INFO. This means that ERROR, WARNING, and INFO messages are all logged by default.
Log Message Format
Logged messages consist of a timestamp (see Table 2-9 to change the timestamp time zone), 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-9.
To Change the Logger Configuration for a Broker
You complete these steps by setting Logger properties. You can do this in one of two ways:
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
imqbrokerd Options
Description
-metrics interval
Specifies the interval (in seconds) at which metrics information is written to the Logger.
-loglevel level
Sets the log level to one of ERROR, WARNING, INFO.
-silent
Turns off logging to the console.
-tty
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:
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,
imq.log.file.output=ERROR
- Use the imq.log.console.output property to specify which categories of logging information should be written to the console. For example,
imq.log.console.output=INFO
- On Solaris, use the imq.log.syslog.output property to specify which categories of logging information should be written to Solaris syslog. For example,
imq.log.syslog.output=NONE
Note
Before changing logger output channels, you must make sure that logging is set at a level that supports the information 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 WARNING messages.
Changing Log File 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:
imq.log.file.rolloversecs=864000
- 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
imq.log.file.rolloverbytes=500000
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.