Running the RHQ Server

The RHQ Server is actually a customized JBossAS server located in the jbossas directory where the RHQ Server distribution is installed. When you start the RHQ Server, you are actually starting that JBossAS server instance.

Running in Debug Mode

Sometimes you need the server launcher scripts (i.e. rhq-server.sh/.bat) to emit debug messages. To run the scripts in debug mode, define the environment variable RHQ_SERVER_DEBUG to 'true'. To disable this debug mode, unset that environment variable, or set it to 'false'.

To run the RQH Server itself in debug mode, you need to modify the jboss-log4j.xml file, located in the jbossas/server/default/conf directory, appropriately. You would do this if you need the RHQ Server itself to log debug messages. Note that the RHQ_SERVER_DEBUG setting does not affect whether or not the RHQ Server itself emits debug messages - that environment variable effects only the server launcher scripts.

We do not recommend modifying anything else under the jbossas directory unless explicitly mentioned in the documentation; modifying any internal files could adversely affect the performance of the RHQ Server.

Running on Windows

The RHQ Server can be run from within a console window or it can be installed as a Windows Service and run as a service.

Running in a Windows Console

The rhq-server.bat script is found in the <install-dir>/bin/ directory of the distribution. To run the RHQ Server in a console, execute the command rhq-server.bat console. Alternatively, open Windows Explorer and locate the <install-dir>/bin/rhq-server-console.bat file. Double click on the file to start the RHQ Server.

The rhq-server.bat script looks for specific environment variables during its execution. These variables can be modified to suit your system requirements. For example, you can point the RHQ Server at a new JVM. The comments at the top of the rhq-server.bat file contain a detailed list of these environment variables. You do not have to set any specific variables to get the RHQ Server to run; sensible defaults are used.

Installing and Running as a Windows Service

When the RHQ Server runs as a Windows service, it runs as a particular user. This user is specified by the RHQ_SERVER_RUN_AS environment variable. The RHQ_SERVER_RUN_AS_ME variable overrides the RHQ_SERVER_RUN_AS variable and allows the RHQ Server to run as the current user. If neither of these two variables are set, the RHQ Server Windows Service runs as the System account. Both variables are explicitly mentioned here because of their security implications. All environment variables can be defined in the rhq-server.bat script. To run the RHQ Server Windows service as a specific user, define the RHQ_SERVER_RUN_AS variable with a value conforming to the strict Microsoft Windows format of: DOMAIN\username, for example, MYDOMAIN\john. Alternatively, define the RHQ_SERVER_RUN_AS_ME variable; no value is required. The RHQ Server runs as the username defined in the USERNAME environment variable. Execute the rhq-server.bat script with one of the following command line options:

• install - This installs the RHQ Server as a Windows service. At the prompt, enter the password of the user designated to run the server. The Windows service now starts the server during the system boot. You can change this behavior by modifying the wrapper configuration file described below.
• start - This starts the Windows service, effectively starting the RHQ Server. Ensure that you have run the rhq-install.bat install command first. Alternatively, start the RHQ Server by using the Windows Services Administrative Tool.
• stop - This stops the Windows Service, effectively stopping the RHQ Server. You must have installed and started the Windows Service first in order to stop it. Alternatively, stop the RHQ Server by using the Windows Services Administrative Tool instead.
• remove - This removes the Windows Service from your Windows operating system. If the service is running, it is first stopped. Once the service is removed, it is no longer started at boot time and you can no longer start it with the start option.
• status - If the service is installed, this option informs you if the server is currently running or not.

Optional Wrapper Configuration Files

The RHQ Server Windows Service can also be modified by the service wrapper configuration file, located at <server-install-dir>\bin\wrapper\rhq-server-wrapper.conf. This file sets some of the Java Service Wrapper configuration settings. The rhq-server.bat script uses the Java Service Wrapper utility to install and control the Windows Service. Before editing this file, refer to the Java Service Wrapper's property configuration documentation located at http://wrapper.tanukisoftware.org/doc/english/properties.html. A few common settings you might be interested in modifying are:

• wrapper.app.parameter.# - these command line options are passed to the RHQ Server. Because the RHQ Server runs inside a JBossAS container, the options are passed on to this container. Each individual option and its value must be given its own wrapper configuration property, and must be placed in numerical order. Do not change any of the five default properties, wrapper.app.parameter.1 thru .5; to add a new property, start with wrapper.app.parameter.6. You should not need to add or modify these properties for a standard configuration.
• wrapper.java.additional.# - these additional VM options are passed directly to the VM (such as -Xmx or -D). As with the wrapper.app.parameter.# properties, you must increment each option in numerical order. Do not edit the existing wrapper.java.additional.# properties unless, for example, you want to adjust the memory requirements of the RHQ Server or you want to point to your own log configuration file. You can add, remove, and modify other properties. For example: wrapper.java.additional.12=-XX:+DisableExplicitGC
• wrapper.ntservice.starttype - by default, this is set to AUTO_START. This starts the RHQ Server automatically at boot time. To manually start the service, change the value to DEMAND_START.

There are many other Java Service Wrapper configuration properties you can set. If you are interested in learning more, refer to the Java Service Wrapper documentation at http://wrapper.tanukisoftware.org/doc/english/properties.html. Also refer to the comments located in the rhq-server-wrapper.conf file. You can also configure the RHQ Server Windows Service by creating a bin\wrapper\rhq-server-wrapper.inc include file. This effectively augments the service wrapper configuration file, server-install-dir\bin\wrapper\rhq-server-wrapper.conf. If you want to add additional Java VM options, we recommend that you add your settings in here, as opposed to the rhq-server-wrapper.conf file.

Running on Unix

The RHQ Server can run from a console window or run as a service started by the init process.

Setting Environment Variables

The rhq-server.sh file, located in the <server-install-dir>/bin/ directory, contains a detailed list of the environment variables it requires to run. For most variables, sensible defaults are used and therefore do not need editing. It is important however, to set the correct path to your Java installation. Before starting the RHQ Server, edit the rhq-server.sh file and ensure that either the RHQ_SERVER_JAVA_HOME or the RHQ_SERVER_JAVA_EXE_FILE_PATH variable is set appropriately.

Running in a Console

To run the RHQ Server in a console, execute the following commands as the root user:

# cd _<server-install-dir>_/bin/
# ./rhq-server.sh console

Running with init.d

To ensure the RHQ Server is started at boot time, the rhq-server.sh script can be managed by the init process. The script must be copied to the appropriate location and the RHQ_SERVER_HOME variable must be set to the installation directory of the RHQ Server. The exact procedure on how to do this varies between different flavors of UNIX. The example procedure below describes this process on Red Hat Enterprise Linux 5.2.

Unlike the Windows script, this UNIX script does not utilize the Java Service Wrapper utility.

Service Installation on Red Hat Enterprise Linux 5.2

The rhq-server.sh script can be placed under the /etc/init.d/ directory and managed by the service and chkconfig command. To run the RHQ Server as a service on Red Hat Enterprise Linux 5.2 and ensure that it starts in run level 5, follow the procedure below as the root user:

1. Copy the rhq-server.sh script into the /etc/init.d/ directory.

   cp _<server-install-dir>_/bin/rhq-server.sh /etc/init.d/

2. Edit the /etc/init.d/rhq-server.sh script and set the RHQ_SERVER_HOME variable to the RHQ Server install directory. For example:

   RHQ_SERVER_HOME=/opt/jon-server-2.1.0.GA/

3. Edit the /etc/init.d/rhq-server.sh script and add the following lines to the top of the file, directly under #!/bin/sh. The last two parameters in the #chkconfig: 2345 95 20 line specify the start and stop priority respectively; edit these accordingly.

   #!/bin/sh
   #chkconfig: 2345 95 20
   #description: RHQ Server
   #processname: run.sh

4. Add the service to the chkconfig service management command.

   # chkconfig --add rhq-server.sh
   # chkconfig rhq-server.sh --list

5. Ensure the service will start in run level 5.

   # chkconfig --level 5 rhq-server.sh on

The RHQ Server service can now be managed by the command:

service rhq-server.sh { start | stop | status }

For example, to start the service, enter the following command:

# service rhq-server.sh start

Running the Embedded Agent in the RHQ Server

The RHQ Agent embedded within the RHQ Server allows you to manage the platform, other products and the RHQ Server itself, without having to run a separate RHQ Agent process on the same machine. This feature enables quick testing and demo'ing of RHQ without the need to install and run a standalone agent.

Use the embedded agent for demo/testing purposes only. It is not recommended to use it in a production environment. There are some known issues with managing certain resources with the embedded agent (for example, one specific issue deals with the inability to monitor some of the internal RHQ Server EJBs).

To enable the embedded RHQ Agent, edit the bin/rhq-server.properties file and set the rhq.server.embedded-agent.enabled flag to true. An example portion of the rhq-server.properties file is shown below.

# Embedded RHQ Agent
rhq.server.embedded-agent.enabled=true
rhq.server.embedded-agent.name=
rhq.server.embedded-agent.reset-configuration=true
rhq.server.embedded-agent.disable-native-system=false