|
| |
| Sun Java System Message Queue 3 2005Q1 Administration Guide | |
Chapter 3
Starting Brokers and ClientsAfter installing Sun Java™ System Message Queue and performing some preparatory steps, you can start brokers and clients.
The chapter contains the following sections:
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. For information about broker configuration, see Chapter 4, "Configuring a Broker".
Preparing System ResourcesBefore you start a broker, there are two system-level tasks to perform: synchronizing the system clocks, and, on Solaris or Linux, setting the file descriptor limits. The next sections describe these tasks.
Synchronizing System Clocks
Before starting any brokers or clients, it is important to synchronize the clocks on all hosts that will interact with the Message Queue system. Synchronization is particularly crucial if you are using message expiration (TimeToLive). Timestamps from clocks that are not synchronized could prevent the TimeToLive feature from working as expected and prevent the delivery of messages. Synchronization is also crucial for broker clusters.
Configure your systems to run a time synchronization protocol, such as Simple Network Time Protocol (SNTP). Time synchronization is generally supported by the xntpd daemon on Solaris and Linux, and by the W32Time Time service on Windows. See your operating system documentation for information about configuring this service.
After the broker is running, avoid setting the system clock backward.
Setting the File Descriptor Limits (Solaris or Linux)
On the Solaris and Linux platforms, the shell in which the client or broker is running places a soft limit on the number of file descriptors that a process can use. In the Message Queue system, each connection a client makes, or each connection a broker accepts, uses one of these file descriptors. Each physical destination that has persistent messages also uses a file descriptor.
As a result, the number of connections is limited by these factors. You cannot have a broker or client running with more than 256 connections on Solaris or 1024 on Linux without changing the file descriptor limit. (The connection limit is actually lower than that due to the use of file descriptors for persistence.)
To change the file descriptor limit, see the ulimit man page. The limit needs to be changed in each shell in which a client or broker will be executing.
Starting Brokers InteractivelyYou can start brokers interactively from the command line, using the imqbrokerd command. (Alternatively, on Windows, you can start a broker from the Start menu.) You cannot use the Administration Console (imqadmin) or the Command Utility (imqcmd) to start a broker; the broker must already be running before you can use these tools.
On the Solaris and Linux platforms, a broker instance must always be started by the user who initially started it. When the broker instance first starts, Message Queue uses that user’s umask to set permissions on broker instance directories containing configuration information and persistent data. Each broker instance has its own set of configuration properties and file-based message store.
A broker instance has the instance name imqbroker by default. To start a broker from the command line with this name and the default configuration, simply use the command
imqbrokerd
This starts a broker instance named imqbroker on the local machine, with the Port Mapper at the default port of 7676.
To specify an instance name other than the default, use the -name option to the imqbrokerd command. The following command starts a broker with the instance name myBroker:
imqbrokerd -name myBroker
Other options are available on the imqbrokerd command line to control various aspects of the broker’s operation. The following example uses the -tty option to send errors and warnings to the command window (standard output):
imqbrokerd -name myBroker -tty
You can also use the -D option on the command line to override the values of properties specified in the broker’s instance configuration file (config.properties). This example sets the imq.jms. max_threads property, raising the maximum number of threads available to the jms connection service to 2000:
imqbrokerd -name myBroker -Dimq.jms. max_threads=2000
See Chapter 13, "Command Reference," for complete information on the syntax, subcommands, and options of the imqbrokerd command. For a quick summary of this information, enter the command
imqbrokerd -help
Starting Brokers AutomaticallyInstead of starting a broker explicitly from the command line, you can set it up to start automatically at system startup. How you do this depends on the platform you’re running the broker on (Solaris, Linux, or Windows).
Automatic Startup on Solaris and Linux
On Solaris and Linux systems, scripts that enable automatic startup are placed in the /etc/rc* directory tree during Message Queue installation. To enable the use of these scripts, you must edit the configuration file /etc/imq/imqbrokerd.conf (Solaris) or /etc/opt/sun/mq/imqbrokerd.conf (Linux) as follows:
Automatic Startup on Windows
To start a broker automatically at Windows system startup, you must define the broker as a Windows service. You can install a broker as a service when you install Message Queue on a Windows system. After installation, you can use the Service Administrator utility, imqsvcadmin, to perform the following operations:
For reference information about the syntax, subcommands, and options of the imqsvcadmin command, see Chapter 13, "Command Reference."
Installing a broker as a Windows service means that it will start at system startup time and run in the background until you shut down. Consequently, you do not use the imqbrokerd command to start the broker unless you want to start an additional instance.
To pass startup options to the broker, use the -args argument to the imqsvcadmin command. This works the same way as the imqbrokerd command’s -D option, as described under Starting Brokers Interactively. Use the imqcmd command to control broker operations as usual.
When a broker runs as a Windows service, Task Manager lists the broker as two executable processes:
A system can have only one broker that is running as a Windows service.
Reconfiguring the Broker Service
The sequence for reconfiguring the Windows service is as follows:
Using an Alternative Java Runtime
You can use either the -javahome or -jrehome options to specify the location of an alternative Java runtime. You can also specify these options in the Windows Services Control Panel Startup Parameters field.
The Startup Parameters field treats the back slash (\) as an escape character, so you must type it twice when using it as a path delimiter; for example,
-javahome d:\\jdk1.3.Displaying the Broker Service Startup Options
To determine the startup options for the broker service, use the query option to the imqsvcadmin command.
Troubleshooting Service Startup Problems
If you get an error when you try to start the service, you can view error events that were logged.
To See Logged Service Error Events
Removing a Broker That Is Running as a Windows Service
To remove a broker that is running as a service, do one of the following:
Restart your computer when you are done.
Starting Message Queue ClientsBefore starting a client application, obtain information from the application developer about how to set up the system. If you are starting Java client applications, you must set the CLASSPATH variable and ensure you have the correct jar files installed. The Message Queue Developer’s Guide for Java Clients contains information about generic steps for setting up the system, but your developers might have additional information to provide.
To start a Java client application, use the following command line format:
java clientAppName
To start a C client application, use the format supplied by the application developer.
The application developer or application documentation should provide information on attribute values that the application sets. You might want to override some attributes that the application sets. You do so by specifying those attributes on the command line.
You might also want to specify attributes on the command line for any Java client that uses a JNDI lookup to find its connection factory. If the lookup returns a connection factory that is older than the application, the connection factory might lack support for more recent attributes. In such a case, Message Queue sets those attributes to default values. By specifying the attributes on the command line, you can set them to nondefault values.
To provide attribute values on the command line, use the following command line syntax for a Java application:
java [[-Dattribute=value ]...] clientAppName
The value for attribute must be a connection factory administered object attribute, as described in Chapter 16, "Administered Object Attribute Reference." If there is a space in the value, put quotation marks around the attribute=value part of the command line.
The following example starts the client application MyMQClient. The application connects to a broker on the host OtherHost at port 7677, overriding any host name and port set by the application.
java -DimqAddressList=mq://OherHost:7677/jms MyMQClient
In some cases, you cannot use the command line to specify attribute values. An administrator can set an administered object to allow read access only, or an application developer can code the client to do so. Communication with the application developer is necessary to understand the best way to start the client program.
Removing a Broker InstanceThis section contains information on removing a broker instance on Solaris or Linux. For information about removing a Windows service, see Removing a Broker That Is Running as a Windows Service.
To remove a broker instance, use the imqbrokerd command with the -remove option. The command format for removing a broker instance is as follows:
imqbrokerd [options..] -remove instance
For example, if the name of the broker is myBroker, this is the command:
imqbrokerd -name myBroker -remove instance
The command deletes the entire instance directory for the specified broker.
For a list of options that you can use to remove a broker, see the imqbrokerd reference information in Command Reference.
On Solaris or Linux, if the broker is set up to start automatically at system startup, edit the configuration file /etc/imq/imqbrokerd.conf (Solaris) or /etc/opt/sun/mq/imqbrokerd.conf (Linux) and set the AUTOSTART property to NO.