Running the RHQ Server
The RHQ Server can run on either a Windows or UNIX platform. If you wish to run the launcher scripts in debug mode (where the scripts log debug messages), define the environment variable RHQ_SERVER_DEBUG to any value. When you wish to disable debug mode, unset that environment variable.
The RHQ Server is actually a customized JBossAS server (located in the jbossas directory where the RHQ Server distribution was installed). When you start the RHQ Server, you are actually starting that JBossAS server instance. Should you wish to run the RHQ Server in debug mode, you can modify the standard jboss-log4j.xml file appropriately (that file is located in the directory jbossas/server/default/conf). Typically, you do not modify anything else under this jbossas directory - you could adversely affect the performance of the RHQ Server if you do this.
 | The RHQ Server is deployed inside a JBossAS 4.2.2 application server. Because of this, you must ensure your Java environment is supported by that JBossAS version. Specifically, this means the RHQ Server will only run inside a Java 5 VM. It will not run inside a Java 6 or higher VM. |
Running on Windows
The RHQ Server can be run directly from within a console window or it can be installed as a Windows Service and run as a service.
Running in a Windows Console
To run the RHQ Server in a console, you simply execute the command rhq-server.bat console. The rhq-server.bat script file is found in the /bin directory of the distribution. There is a convenience script rhq-server-console.bat that executes that command for you; this allows you to simply "double click" it from a Windows Explorer to launch the RHQ Server.
There are a few environment variables that this rhq-server.bat script looks for to allow you to do some custom things such as explicitly pointing to a specific JVM that you want the server to run with. See the comments at the top of the rhq-server.bat for the list of these environment variables. You do not have to set any specific environment variables to get the RHQ Server to run under most circumstances; sensible defaults will be used.
Installing and Running as a Windows Service
If you wish to run the RHQ Server at boot time, you can install the RHQ Server as a Windows Service. To do so, you use the same rhq-server.bat but with one of the following command line options:
- install - this will install the RHQ Server as a Windows Service. When you do this, you will be prompted for the password of the user that the service will run as. See below for information on how to define what user the service will run as. The Windows Service will be installed to automatically start at boot time. You can change this behavior by modifying the wrapper configuration file as described below.
- start - this will start the Windows Service, effectively starting the RHQ Server. You must have installed the Windows Service first in order to be able to start it. Note that you can also start the RHQ Server by using the Windows Services Administrative Tool instead.
- stop - this will stop the Windows Service, effectively stopping the RHQ Server. You must have installed and started the Windows Service first in order to be able to stop it. Note that you can also stop the RHQ Server by using the Windows Services Administrative Tool instead.
- remove - this will remove the Windows Service from your Windows operating system. If the service was running, it will first be stopped. Once the service is removed, it will no longer be started at boot time and you can no longer start it with this script's start option.
- status - this simply tells you if the service is installed or not; if it is installed, it will tell you if it is currently running or not.
There are a few environment variables that you can set to customize your RHQ Server Windows Service. Refer to the comments at the top of the rhq-server.bat script file for the full list of variables you can set and the documentation on what they control. Two environment variables need to be explicitly mentioned here since they are important and have security implications:
- RHQ_SERVER_RUN_AS - if this variable is set, its value will be the domain\username of the user account that the RHQ Server Windows Service will be run as. The format of this variable's value must match that which Windows expects for a user account - specifically the Windows domain name followed by a backslash followed by the username. An example would be MYDOMAIN\john. This variable is used when you install the service via rhq-server.bat install.
- RHQ_SERVER_RUN_AS_ME - if this variable is defined, it forces the user account to be that of the current user (specifically ".\ %USERNAME%)". The variable's value does not have to be anything in particular; as long as it is defined to something, it will take effect. If this variable is defined, it will override the RHQ_SERVER_RUN_AS environment variable. This variable is used when you install the service via rhq-server.bat install.
Note that if neither of the above two environment variables are set, the RHQ Server Windows Service will run as the System account.
In addition to setting the script file's environment variables, you can also further configure the RHQ Server Windows Service by modifying the service wrapper configuration file - this file is located in the server's distribution, specifically at bin\wrapper\rhq-server-wrapper.conf. This configuration file sets some Java Service Wrapper configuration items (Java Service Wrapper is the utility that rhq-server.bat script uses to install and control the Windows Service). If you wish to add, remove or modify some wrapper.* settings, it is recommended that you read the Java Service Wrapper's configuration properties documentation.
A few common settings you might be interested in modifying are:
- wrapper.app.parameter.# - these are command line options you can pass to the RHQ Server itself (which is technically command line options getting sent to the JBossAS container, which is what the RHQ Server runs inside of). Note that each individual option and their values must be given their own wrapper configuration property and each property must be placed in numerical order. You cannot change the wrapper.app.parameter.1 through wrapper.app.parameter.5 properties - start with wrapper.app.parameter.6. It is rare that you would need to add or modify these properties.
- wrapper.java.additional.# - these are additional VM options you can pass directly to the VM (such as -Xmx or -D). As with the wrapper.app.parameter.# properties, you must increment each option in numerical order. You should leave wrapper.java.additiona.1 alone unless you want to point to your own log configuration file. You can add, remove or modify others, but make sure you know what you are doing. Example:
- wrapper.ntservice.starttype - by default, this is set to AUTO_START, meaning the RHQ Server's service will be started automatically at boot time. If you would rather be forced to manually start the service, you can set this to DEMAND_START.
There are many other Java Service Wrapper configuration properties you can set. If you are interested in learning more, again it is recommended that you refer to the Java Service Wrapper documentation. You can also read the comments found directly in the rhq-server-wrapper.conf file.
Running on UNIX
The RHQ Server can be run directly from a console window or it can be installed as an init.d process such that it starts up when the computer boots up.
Running in a Console
To run the RHQ Server in a console, you simply execute rhq-server.sh console where that script is found in the /bin directory of the distribution. There are a few environment variables that this rhq-server.sh script looks for to allow you to do some custom things such as explicitly pointing to a specific JVM that you want the server to run with. See the comments at the top of the rhq-server.sh for the list of these environment variables. You do not have to set any specific environment variables to get the RHQ Server to run under most circumstances; sensible defaults will be used.
Running With init.d
The RHQ Server script rhq-server.sh can also be used in conjunction with init.d such that the RHQ Server can be run at boot time. Copy this script to a location appropriate for your UNIX platform and edit this script so it points to your RHQ Server distribution directory (specifically, you need to modify the value set to the RHQ_SERVER_HOME variable). There are a few other variables that are defined (or commented out) at the top of this script file (in addition to RHQ_SERVER_HOME) - you may define these as appropriate in order to customize the RHQ Server startup parameters. Note: unlike the Windows script, this UNIX script does not utilize the Java Service Wrapper utility.
Running the Embedded RHQ Agent
You have the option to run a RHQ Agent embedded within the RHQ Server. This 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 where your RHQ Server is. To enable the embedded RHQ Agent, you must edit the bin/rhq-server.properties file and set the enabled flag to true. You can also define the name of your embedded agent (in case you have more than one RHQ Server with an embedded agent in your environment), reset the agent configuration (cleans out the java preferences, and empties its data/ directory), and you can enable or disable the native system for that agent:
