Chapter 5 Starting and Configuring a Broker

Previous Contents Index Next
Sun Java System Message Queue 3.5 SP1 Administration Guide

Chapter 5
Starting and Configuring a Broker

After 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:

edit a broker instance configuration file

work with broker clusters

control logging for the broker

For a description of how to start and use the broker as a Windows service, see "Using a Broker as a Windows Service".

Configuration Files

Installed 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

Note

The …/instances/instanceName directory (and the instance configuration file) is owned by whoever created the corresponding broker instance. All subsequent start-ups of the broker instance must be by that same user.

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.

Table 5-1  Broker Instance Configuration Properties

Property Name

Type

Default Value

Reference

imq.accesscontrol.enabled

boolean

true

Table 2-6

imq.accesscontrol.file.
filename

string

accesscontrol.
properties

Table 2-6

imq.authentication.basic.
user_repository

string

file

Table 2-6

imq.authentication.
client.response.timeout

integer
(seconds)

180

Table 2-6

imq.authentication.type

string

digest

Table 2-6

imq.autocreate.destination.
isLocalOnly

boolean

false

Table 2-10

imq.autocreate.destination.
limitBehavior

string

REJECT_NEWEST

Table 2-10

imq.autocreate.destination.
maxBytesPerMsg

byte string¹

10k

Table 2-10

imq.autocreate.destination.
maxNumMsgs

integer

100,000

Table 2-10

imq.autocreate.destination.
maxNumProducers

integer

100

Table 2-10

imq.autocreate.destination.
maxTotalMsgBytes

byte string¹

10m

Table 2-10

imq.autocreate.queue

boolean

true

Table 2-10

imq.autocreate.queue.
consumerFlowLimit

integer

1000

Table 2-10

imq.autocreate.queue.
localDeliveryPreferred

boolean

false

Table 2-10

imq.autocreate.queue.
maxNumActiveConsumers

integer

1

Table 2-10

imq.autocreate.queue.
maxNumBackupConsumers

integer

0

Table 2-10

imq.autocreate.topic

boolean

true

Table 2-10

imq.autocreate.topic.
consumerFlowLimit

integer

1,000

Table 2-10

imq.cluster.property_name

Table 5-3

imq.hostname

string

all available IP addresses

Table 2-3

imq.httpjms.http.property_name

Table C-1

imq.httpsjms.https.
property_name

Table C-3

imq.keystore.property_name

Table 8-8

imq.log.console.output

string

ERROR|WARNING

Table 2-9

imq.log.console.stream

string

ERR

Table 2-9

imq.log.file.dirpath

string

See Appendix A, "Location of Message Queue Data"

Table 2-9

imq.log.file.filename

string

log.txt

Table 2-9

imq.log.file.output

string

ALL

Table 2-9

imq.log.file.rolloverbytes

integer
(bytes)

-1
(no rollover)

Table 2-9

imq.log.file.rolloversecs

integer
(seconds)

604800

Table 2-9

imq.log.level

string

INFO

Table 2-9

imq.log.syslog.facility

string

LOG_DAEMON

Table 2-9

imq.log.syslog.identity

string

imqbrokerd_${imq.
instanceName}

Table 2-9

imq.log.syslog.logconsole

boolean

false

Table 2-9

imq.log.syslog.logpid

boolean

true

Table 2-9

imq.log.syslog.output

string

ERROR

Table 2-9

imq.log.timezone

string

local time zone

Table 2-9

imq.message.expiration.
interval

integer
(seconds)

60

Table 2-4

imq.message.max_size

byte string¹

70m

Table 2-4

imq.metrics.enabled

boolean

true

Table 2-9

imq.metrics.interval

integer
(seconds)

-1
(never)

Table 2-9

imq.metrics.topic.enabled

boolean

true

Table 2-9

imq.metrics.topic.interval

integer
(seconds)

60

Table 2-9

imq.metrics.topic.persist

boolean

false

Table 2-9

imq.metrics.topic.timetolive

integer
(seconds)

300

Table 2-9

imq.passfile.dirpath

string

See Appendix A, "Location of Message Queue Data"

Table 2-6

imq.passfile.enabled

boolean

false

Table 2-6

imq.passfile.name

string

passfile

Table 2-6

imq.persist.file.
destination.message.
filepool.limit

integer

100

Table 2-5

imq.persist.file.message.
cleanup

boolean

false

Table 2-5

imq.persist.file.message.
filepool.cleanratio

integer

0

Table 2-5

imq.persist.file.message.
max_record_size

byte string ¹

1m

Table 2-5

imq.persist.file.sync.
enabled

boolean

false

Table 2-5

imq.persist.jdbc.property_name

Table B-1

imq.persist.store

string

file

Table 2-5

imq.ping.interval

integer

120

Table 2-3

imq.portmapper.backlog

integer

50

Table 2-3

imq.portmapper.hostname

string

inherited from imq.hostname

Table 2-3

imq.portmapper.port

integer

7676

Table 2-3

imq.resource_state.count

integer
(percent)

5000 (green)
500 (yellow)
50(orange)
0 (red)

Table 2-4

imq.resource_state.
threshold

integer
(percent)

0 (green)
80 (yellow)
90(orange)
98 (red)

Table 2-4

imq.service.activelist

list

jms,admin

Table 2-3

imq.service_name.
accesscontrol.enabled

boolean

inherits value from system-wide property

Table 2-6

imq.service_name.
accesscontrol.file.filename

string

inherits value from system-wide property

Table 2-6

imq.service_name.
authentication.type

string

inherits value from system-wide property

Table 2-6

imq.service_name.max_threads

integer

1000 (jms)
500 (ssljms)
500 (httpjms)
500 (httpsjms)
10 (admin)
10 (ssladmin)

Table 2-3

imq.service_name.min_threads

integer

10 (jms)
10 (ssljms)
10 (httpjms)
10 (httpsjms)
4 (admin)
4 (ssladmin)

Table 2-3

imq.service_name.protocol_type.
hostname

string

inherited from imq.hostname

Table 2-3

imq.service_name.protocol_type.
port

integer

0
(dynamically allocated)

Table 2-3

imq.service_name.
threadpool_model

string

dedicated (jms)
dedicated (ssljms)
dedicated (httpjms)
dedicated (httpsjms)
dedicated (admin)
dedicated (ssladmin)

Table 2-3

imq.shared.
connectionMonitor_limit

integer

512 (Solaris & Linux)
64 (Windows)

Table 2-3

imq.system.max_count

integer,
0 (no limit)

-1

Table 2-4

imq.system.max_size

byte string¹,
0 (no limit)

-1

Table 2-4

imq.transaction.autorollback

boolean

false

Table 2-4

imq.user_repository.ldap.
property_name

Table 8-5

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.

Note

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 Message Queue 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.

Syntax of the imqbrokerd Command

The syntax of the imqbrokerd command is as follows (options and arguments are separated by a space):

imqbrokerd     [[ -Dproperty=value]…]

    [ -backup fileName]

    [ -cluster “[broker1] [[,broker2]…]”

    [ -dbuser userName] [ -dbpassword password]

    [ -force]

    [ -h|-help]

    [ -javahome path]

    [ -ldappassword password]

    [ -license licenseName]

    [ -loglevel level]

    [ -metrics interval]

    [ -name instanceName]

    [ -password keypassword] [ -passfile fileName]

    [ -port number]

    [ -remove instance]

    [ -reset data]

    [ -restore fileName]

    [ -shared]

    [ -silent|-s] [ -tty]

    [ -upgrade-store-nobackup]

    [ -version]

    [ -vmargs arg1 [[arg2]…]

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 either

host[:port]

[host]:port

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.

-dbpassword password

Sets imq.persist.jdbc.
password to specified password

Specifies 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 name

Specifies 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
password

Sets imq.user_repository.
ldap.password to specified password

Specifies 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|
props

None 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 ALL

Specifies that all messages be displayed to the console. By default only WARNING and ERROR level messages are displayed.

-upgrade-store-
nobackup

None 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, ctrhost

imq.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.properties

imq.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

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), the network transport to use for the cluster connection service (imq.cluster.transport), and optionally, the address of the Master Broker (imq.cluster.masterbroker).

If you use this method, you must also set the imq.cluster.url property (for every broker in the cluster) to point to the location of the cluster configuration file. From the point of view of easy maintenance, this is the recommended method of cluster configuration.

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.

imq.cluster.brokerlist=host1,host2:5000,ctrlhost

imq.cluster.masterbroker=ctrlhost

The instance configuration file for each broker connected in this cluster, must then contain the URL of the cluster configuration file; for example:

imq.cluster.url=file:/home/cluster.properties

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 brokers A, B, and C were all started using the following command line, then just restarting A will not remove it from the cluster.

imqbrokerd -cluster A,B,C

Instead, you need to restart all the other brokers with the following command line:

imqbrokerd -cluster B,C

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:

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.

Logging

This 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.txt

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 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

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

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:

change the output channel (the destination of log messages)

change rollover criteria

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.

Previous      Contents      Index      Next

Copyright 2003 Sun Microsystems, Inc. All rights reserved.


Note	The …/instances/instanceName directory (and the instance configuration file) is owned by whoever created the corresponding broker instance. All subsequent start-ups of the broker instance must be by that same user.

Property Name	Type	Default Value	Reference
imq.accesscontrol.enabled	boolean	true	Table 2-6
imq.accesscontrol.file. filename	string	accesscontrol. properties	Table 2-6
imq.authentication.basic. user_repository	string	file	Table 2-6
imq.authentication. client.response.timeout	integer (seconds)	180	Table 2-6
imq.authentication.type	string	digest	Table 2-6
imq.autocreate.destination. isLocalOnly	boolean	false	Table 2-10
imq.autocreate.destination. limitBehavior	string	REJECT_NEWEST	Table 2-10
imq.autocreate.destination. maxBytesPerMsg	byte string¹	10k	Table 2-10
imq.autocreate.destination. maxNumMsgs	integer	100,000	Table 2-10
imq.autocreate.destination. maxNumProducers	integer	100	Table 2-10
imq.autocreate.destination. maxTotalMsgBytes	byte string¹	10m	Table 2-10
imq.autocreate.queue	boolean	true	Table 2-10
imq.autocreate.queue. consumerFlowLimit	integer	1000	Table 2-10
imq.autocreate.queue. localDeliveryPreferred	boolean	false	Table 2-10
imq.autocreate.queue. maxNumActiveConsumers	integer	1	Table 2-10
imq.autocreate.queue. maxNumBackupConsumers	integer	0	Table 2-10
imq.autocreate.topic	boolean	true	Table 2-10
imq.autocreate.topic. consumerFlowLimit	integer	1,000	Table 2-10
imq.cluster.property_name			Table 5-3
imq.hostname	string	all available IP addresses	Table 2-3
imq.httpjms.http.property_name			Table C-1
imq.httpsjms.https. property_name			Table C-3
imq.keystore.property_name			Table 8-8
imq.log.console.output	string	ERROR\|WARNING	Table 2-9
imq.log.console.stream	string	ERR	Table 2-9
imq.log.file.dirpath	string	See Appendix A, "Location of Message Queue Data"	Table 2-9
imq.log.file.filename	string	log.txt	Table 2-9
imq.log.file.output	string	ALL	Table 2-9
imq.log.file.rolloverbytes	integer (bytes)	-1 (no rollover)	Table 2-9
imq.log.file.rolloversecs	integer (seconds)	604800	Table 2-9
imq.log.level	string	INFO	Table 2-9
imq.log.syslog.facility	string	LOG_DAEMON	Table 2-9
imq.log.syslog.identity	string	imqbrokerd_${imq. instanceName}	Table 2-9
imq.log.syslog.logconsole	boolean	false	Table 2-9
imq.log.syslog.logpid	boolean	true	Table 2-9
imq.log.syslog.output	string	ERROR	Table 2-9
imq.log.timezone	string	local time zone	Table 2-9
imq.message.expiration. interval	integer (seconds)	60	Table 2-4
imq.message.max_size	byte string¹	70m	Table 2-4
imq.metrics.enabled	boolean	true	Table 2-9
imq.metrics.interval	integer (seconds)	-1 (never)	Table 2-9
imq.metrics.topic.enabled	boolean	true	Table 2-9
imq.metrics.topic.interval	integer (seconds)	60	Table 2-9
imq.metrics.topic.persist	boolean	false	Table 2-9
imq.metrics.topic.timetolive	integer (seconds)	300	Table 2-9
imq.passfile.dirpath	string	See Appendix A, "Location of Message Queue Data"	Table 2-6
imq.passfile.enabled	boolean	false	Table 2-6
imq.passfile.name	string	passfile	Table 2-6
imq.persist.file. destination.message. filepool.limit	integer	100	Table 2-5
imq.persist.file.message. cleanup	boolean	false	Table 2-5
imq.persist.file.message. filepool.cleanratio	integer	0	Table 2-5
imq.persist.file.message. max_record_size	byte string ¹	1m	Table 2-5
imq.persist.file.sync. enabled	boolean	false	Table 2-5
imq.persist.jdbc.property_name			Table B-1
imq.persist.store	string	file	Table 2-5
imq.ping.interval	integer	120	Table 2-3
imq.portmapper.backlog	integer	50	Table 2-3
imq.portmapper.hostname	string	inherited from imq.hostname	Table 2-3
imq.portmapper.port	integer	7676	Table 2-3
imq.resource_state.count	integer (percent)	5000 (green) 500 (yellow) 50(orange) 0 (red)	Table 2-4
imq.resource_state. threshold	integer (percent)	0 (green) 80 (yellow) 90(orange) 98 (red)	Table 2-4
imq.service.activelist	list	jms,admin	Table 2-3
imq.service_name. accesscontrol.enabled	boolean	inherits value from system-wide property	Table 2-6
imq.service_name. accesscontrol.file.filename	string	inherits value from system-wide property	Table 2-6
imq.service_name. authentication.type	string	inherits value from system-wide property	Table 2-6
imq.service_name.max_threads	integer	1000 (jms) 500 (ssljms) 500 (httpjms) 500 (httpsjms) 10 (admin) 10 (ssladmin)	Table 2-3
imq.service_name.min_threads	integer	10 (jms) 10 (ssljms) 10 (httpjms) 10 (httpsjms) 4 (admin) 4 (ssladmin)	Table 2-3
imq.service_name.protocol_type. hostname	string	inherited from imq.hostname	Table 2-3
imq.service_name.protocol_type. port	integer	0 (dynamically allocated)	Table 2-3
imq.service_name. threadpool_model	string	dedicated (jms) dedicated (ssljms) dedicated (httpjms) dedicated (httpsjms) dedicated (admin) dedicated (ssladmin)	Table 2-3
imq.shared. connectionMonitor_limit	integer	512 (Solaris & Linux) 64 (Windows)	Table 2-3
imq.system.max_count	integer, 0 (no limit)	-1	Table 2-4
imq.system.max_size	byte string¹, 0 (no limit)	-1	Table 2-4
imq.transaction.autorollback	boolean	false	Table 2-4
imq.user_repository.ldap. property_name			Table 8-5
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)


Note	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 Message Queue administration tools.


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.

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 either host[:port] [host]:port	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.
-dbpassword password	Sets imq.persist.jdbc. password to specified password	Specifies 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 name	Specifies 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 password	Sets imq.user_repository. ldap.password to specified password	Specifies 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\| props	None 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 ALL	Specifies that all messages be displayed to the console. By default only WARNING and ERROR level messages are displayed.
-upgrade-store- nobackup	None 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"

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, ctrhost
imq.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.properties
imq.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

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.


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.