Running the RHQ Agent

The RHQ Agent can run on either a Windows or UNIX platform. Should you wish to run the agent (and its launcher scripts) in debug mode (where the scripts and the agent itself log debug messages), define the environment variable RHQ_AGENT_DEBUG to any value. When you wish to disable debug mode, unset that environment variable.

By default, the agent is not fully configured out-of-box. The first time you start the agent (or anytime that the agent's configuration has been cleaned), it will ask you a series of setup questions. You must pass the answers to the agent via the keyboard (more technically, through stdin). Because of this, when you start the agent for the very first time, you must do so in a console (e.g. you cannot start it as a Windows Service or init.d process since background services like that do not have keyboard input). You can get around this by one of two ways:

use the --config command line option to the agent, passing in a valid configuration file that fully configures the agent.
use the --input command line option to the agent, passing in a valid file that contains all valid answers to all setup questions that will be asked by the agent.

Running on Windows

The RHQ Agent 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 Agent in a console, you simply execute the rhq-agent.bat script found in the /bin directory of the distribution. You can pass in any of the command line options that are described here. There are a few environment variables that this rhq-agent.bat script looks for to allow you to do some custom things such as explicitly pointing to a specific JVM that you want the agent to run with or defining what VM options you would like to pass in. See the comments at the top of the rhq-agent.bat for the list of these environment variables. You do not have to set any specific environment variables to get the RHQ Agent to run under most circumstances - sensible defaults will be used.

Installing and Running as a Windows Service

If you wish to run the RHQ Agent at boot time, you can install the RHQ Agent as a Windows Service. To do so, you use the rhq-agent-wrapper.bat file. This script file accepts one of the following command line options:

install - this will install the RHQ Agent 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 Agent. You must have installed the Windows Service first in order to be able to start it. Note that you can also start the RHQ Agent by using the Windows Services Administrative Tool instead.

stop - this will stop the Windows Service, effectively stopping the RHQ Agent. 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 Agent 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 wrapper script.

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 Agent Windows Service. Refer to the comments at the top of the rhq-agent-wrapper.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_AGENT_RUN_AS - if this variable is set, its value will be the domain\username of the user account that the RHQ Agent 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-agent-wrapper.bat install.

RHQ_AGENT_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_AGENT_RUN_AS environment variable. This variable is used when you install the service via rhq-agent-wrapper.bat install.

Note that if neither of the above two environment variables are set, the RHQ Agent Windows Service will run as the System account.

In addition to setting the wrapper script file's environment variables, you can also further configure the RHQ Agent Windows Service by modifying the service wrapper configuration file - this file is located in the agent's distribution, specifically at bin\wrapper\rhq-agent-wrapper.conf. This configuration file sets some Java Service Wrapper configuration items (Java Service Wrapper is the utility that rhq-agent-wrapper.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 Agent itself. 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 or wrapper.app.parameter.2 properties - start with wrapper.app.parameter.3 and increment up from there. Example:
```
wrapper.app.parameter.3=--config
wrapper.app.parameter.4=C:\my-configs\my-agent-config.xml
```

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.java.additional.2=-Xms256m
wrapper.java.additional.3=-Xmx800m
wrapper.java.additional.4=-XX:+DisableExplicitGC
```

wrapper.ntservice.starttype - by default, this is set to AUTO_START, meaning the RHQ Agent'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.

Running on UNIX

The RHQ Agent 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 Agent in a console, you simply execute the rhq-agent.sh script found in the /bin directory of the distribution. You can pass in any of the command line options that are described here. There are a few environment variables that this rhq-agent.sh script looks for to allow you to do some custom things such as explicitly pointing to a specific JVM that you want the agent to run with or defining what VM options you would like to pass in. See the comments at the top of the rhq-agent.sh for the list of these environment variables. You do not have to set any specific environment variables to get the RHQ Agent to run under most circumstances; sensible defaults will be used.

Running With init.d

There is a RHQ Agent script found in the /bin directory called rhq-agent-wrapper.sh that can be used in conjunction with init.d such that the RHQ Agent 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 Agent distribution directory (specifically, you need to modify the value set to the RHQ_AGENT_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_AGENT_HOME) - you may define these as appropriate in order to customize the RHQ Agent startup parameters. Note: unlike the wrapper script on Windows, this wrapper script does not utilize the Java Service Wrapper utility.

Running Embedded In a RHQ Server

There is actually a third way you can run the RHQ Agent, and that is embedded in a RHQ Server. For those platforms that are running your RHQ Server, you have the option to either run a standalone RHQ Agent normally (as described in the sections above) or you can run the RHQ Agent embedded in the RHQ Server itself. This allows you to manage the RHQ Server platform and all the products running on that platform (including the RHQ Server itself) by simply starting the RHQ Server and having it start a RHQ Agent for you.

The RHQ Server disables the Embedded RHQ Agent by default - you have to explicitly enable the Embedded RHQ Agent in order to run it. Please see Running the Embedded RHQ Agent for information on how you can enable and configure the Embedded RHQ Agent.

The Embedded RHQ Agent implicitly runs in daemon mode, which means it has no command line interface. Its log file is located in logs/embedded-agent.log.