RHQ Agent Installation

The RHQ Agent can run on either a Windows or UNIX platform and does not require the execution of a special installer program. You only need to install one agent per machine, regardless of the number or types of resources running on that machine that you want to manage. For example, if you have one or ten JBossAS app servers running on your machine, you only need to run one RHQ Agent to manage them all; similarly, if you have one or more JBossAS app servers and one or more Apache Web Servers running on your machine, you only need to run one RHQ Agent to manage them all.

By default, the agent is not fully configured out-of-the-box (unless you've preconfigured it). The first time you start the agent, or anytime that the agent's configuration has been cleaned, you must answer a series of setup questions. This can be done via a console window or by specifying a valid configuration file. After the agent has been configured you can run it as a Windows service, from a console, or run it as a daemon or init.d script in a UNIX environment.

1. You first should install one or more RHQ Servers.
2. If you already have agents installed and you need to upgrade them, see Manually Upgrading the Agent.
3. If you plan to install many RHQ Agents and would like to preconfigure them for easily automated installs, please see Preconfiguring the Agent.
4. To install a new RHQ Agent, follow the steps in the next sections.
5. After the agent has been installed and configured, you can run it as a Windows service, from a console, or run it as a daemon or init.d script in a UNIX environment. Go to Running the RHQ Agent for more information.
6. If you would like to be able to have your agent auto-updated in the future, you must make sure you follow the guidelines specified below.

Download The Agent Update Binary

The RHQ Server comes with a bundled RHQ Agent inside of it - this agent bundle is called the "agent update binary" (it is called this because it is used to not only install a new agent but will also be used to upgrade the agent in the future).

In order to obtain an agent update binary, you can download it directly from any running RHQ Server. You can do this by accessing the URL "http://<server-hostname>:<server-port>/agentupdate/download" and storing the agent update binary file on your local machine. Alternatively, you can use command line tools such as "wget" to do the same thing: wget http://<server-hostname>:<server-port>/agentupdate/download. The name of the downloaded agent update binary is typically something like "rhq-enterprise-agent-#.#.#.jar". where "#.#.#" is the version of the agent. You can download the agent update binary from the RHQ Server GUI by navigating to the Administration>Downloads page.

Extract The RHQ Agent from the Agent Update Binary

Copy the agent update binary .jar file into your chosen directory where you want the agent to be installed and run the following command:

java -jar <agent-update-binary.jar> --install

This will tell the agent update binary to extract the RHQ Agent distribution and install a fresh copy of it in the "rhq-agent" subdirectory. At this point, you will have a fully installed RHQ Agent located in a "rhq-agent" directory where your agent update binary is located.

From here on, the instructions will refer to this "rhq-agent" directory as <agent-install-dir>.

Configure the RHQ Agent

If your agent was already preconfigured, there is nothing left to do. You can go to Running the RHQ Agent to learn more about running the agent.

If your agent was not preconfigured, then you need to configure the agent by following one of the options below. Note that the rhq-agent.sh,bat script is located in the <agent-install-dir>/bin directory.

• Run the rhq-agent.sh,bat script in a console and follow the prompts, entering the appropriate values. If you need help on a particular preference setting, enter !? at the setup prompt for a description of that preference.

or

• Edit the agent-configuration.xml file located at <agent-install-dir>/conf and ensure to edit it with the correct settings. You are essentially doing the same thing as if you were preconfiguring the agent, so read Preconfiguring the Agent for more information. After you edit and save the agent-configuration.xml, you can run the rhq-agent.sh,bat script and the agent will start and not have to ask you any setup questions. This is useful if you want to initially start the agent as a background service or daemon.

Once the agent is configured, it persists its configuration in the Java Preferences backing store. Once this happens, agent-configuration.xml is no longer needed or used. Editing agent-configuration.xml will no longer have any effect on the agent, even if you restart the agent. If you want the agent to pick up changes you make to agent-configuration.xml, you must either restart the agent with the "--cleanconfig" command line option or use the "config --import" agent prompt command.

Here are the basic settings the setup questions will ask:

If the agent fails to register with the server, seems to hang after outputting the message "The agent does not have plugins - it will now wait for them to be downloaded..." or otherwise does not work property after configuring it, please check the agent log file for error messages (<agent-install-dir>/logs/agent.log). The agent log will normally tell you what the problem is. Typically, problems occur when you bind your agent to an IP address or hostname that is not resolvable by the RHQ Servers or is otherwise not reachable by the RHQ Servers. Make sure your agents are bound to IP addresses or hostnames that are recognizable and reachable by all your RHQ Servers. Similarly, make sure all of your RHQ Servers' public endpoint addresses are resolvable by your RHQ Agent. Even if you entered a valid server endpoint in the agent setup question, the agent may attempt to switch to another RHQ Server immediately after startup registration (read about failover lists for why that would be), and if one or more RHQ Servers are installed with unresolvable hostnames or IPs (as seen by this agent), the agent will fail to start properly

.

Reconfiguring the RHQ Agent

If you have previously installed a RHQ Agent on a machine and need to wipe all of its old persistent configuration data, start with a clean RHQ Agent by passing in the command line option --cleanconfig. This forces the agent to wipe its persisted configuration and enter setup mode. If at any time, you need to start the RHQ Agent in setup mode, specify the --setup command line option.

If you only want to reconfigure one or a few agent settings, you have a couple of options:

1. Assuming the agent is imported in inventory, you can reconfigure the agent using RHQ itself. Go to the agent's "Configuration tab" in the UI and you can change the agent's configuration there.
2. Use the "setconfig" agent prompt command. This will set the new configuration setting and persisted it so it survives agent restarts.

Remember! Just changing agent-configuration.xml will not affect the agent. A fully configured agent will ignore agent-configuration.xml; only if you restart an agent with --cleanconfig will the agent reload agent-configuration.xml.

Configuring the RHQ Agent Runtime Environment

The agent has an environment script that is read when the agent is started up. This file is called "rhq-agent-env.bat" on Windows and "rhq-agent-env.sh" on UNIX. Edit this file to change the environment of the agent. The comments in that file document the different settings. Some of the settings are also explained in the Running the RHQ Agent pages.

Preparing Your Agent To Be Auto-Updatable

With the introduction of High Availability (HA), your environment can now support many hundreds of agents. How you manage those agents now becomes very important. The agent auto-update feature introduced in RHQ 2.2 allows your agents to automatically update themselves, without the need for an administrator to manually log onto every agent box and do it by hand.

In order for your agent to be auto-updateable, you must keep a few rules in mind. If you following these recommendations, you should be able to update your agents to new versions easily, without any additional manual configuration necessary. If you do not follow these recommendations, you will still be able to have your agent update itself, but you will most likely need to perform some additional manual administration tasks in order for your agent to start back up in the same configuration it was in before the update.

Agent auto-updates are only available when going from RHQ version 2.2 to a later version. You cannot auto-update agents from any previous RHQ version.

Start The Agent Using The Wrapper Service

On any platform (Windows or UNIX), the agent can be started in two basic ways: 1) in a console or 2) as a background daemon. To run the agent in a console, you use rhq-agent.sh,bat directly - this provides you with a command prompt allowing you to type commands to the agent from your keyboard. To run the agent as a background daemon process, you use rhq-agent-wrapper.sh,bat. The rhq-agent-wrapper.sh,bat is called the "wrapper" script and it runs the agent as a service with no console input (just like any other service such as "sshd"). On Windows platforms, this wrapper script installs and runs the agent as an actual Windows Service.

In almost all production environments, you will want to start the agent as a background daemon process. On UNIX, this means you usually run the agent at boot time from init.d. On Windows, this means you install the agent as a Windows Service that automatically starts at boot time. The agent auto-update feature assumes you start your agent in this way. If you do not, and the agent auto-updates itself, the old agent running in the console will be shutdown and the new agent will be restarted as a background service if at all possible (caveat: on Windows, if the agent is not installed as a Windows Service, the agent will attempt to be restarted in a console window).

Do Not Alter The Launcher Scripts

The agent ships with several launcher scripts along with several support scripts in the /bin directory. You must not change the launcher scripts. If you need to customize the agent's configuration, you can do so by editing the support scripts that are used by the launcher scripts for their configuration. Therefore, you must not edit rhq-agent.sh,bat or rhq-agent-wrapper.sh,bat. You can edit the others. Below are the script files that are used by the agent; those listed in bold italic are the launcher scripts that must not be changed, the others are the support scripts that can be modified:

If you change the support scripts, the agent-auto-update will keep your files and reuse them in your new agent. If you change the launcher scripts, the agent-auto-update will first back them up but then overwrite them with the new scripts found in the update.

Fully Configure The Agent Using the Support Scripts

Do not rely on any shell environment variables that existed at the time you started the agent. If, for example, you started the agent from within a command line shell and prior to starting the agent you had exported the RHQ_AGENT_HOME environment variable in that shell, the agent will use that value. However, once the agent is shutdown and restarted (as what happens after an auto-update completes) that setting will be lost. If you need to customize the settings that your agent uses at startup (e.g. RHQ_AGENT_HOME or RHQ_AGENT_ADDITIONAL_JAVA_OPTS, to name a few), you should do so by editing the support scripts and setting the values in there. This persists the settings and can therefore be picked up the next time the agent restarts. This provides the added benefit of being able to configure, reconfigure and track/rollback configurations using the agent resource's Configuration tab in the GUI.

You must also ensure that the agent has been fully configured prior to running it the very first time. You do this by starting the agent in a console to answer the setup questions or by preconfiguring the agent (which means you must fully configure the agent's configuration file so it can start up without needing additional input from an administrator; in other words, so it does not have to ask the initial setup questions). Once fully configured, you can start the agent as a background daemon thereafter.

You can fully configure the agent by changing the support scripts/configuration files directly. But if you have the agent imported into inventory, you can optionally use the GUI to configure the agent (in effect, we are using RHQ to manage RHQ).

Install Keystores and Truststores Properly

If you configured your old agent with SSL such that it uses your own custom keystores and truststores, you must ensure that you install those stores in the following manner:

1. The keystore files must have the word "keystore" in their filenames. For example, "my-agent-keystore.dat".
2. The truststore files must have the word "truststore" in their filenames. For example, "my-agent-truststore.dat"
3. You must have your keystore and truststore files in the agent's <agent-install-dir>/data directory.

If you follow those three simple rules, then your new, updated agent will remain fully secured just as your old agent was. This is because your keystore and truststore files will be copied directly from your old agent to your new agent.

Install The Agent In A Writable Directory

During the update process, files will need to be written in the directory where the agent is currently installed. This means that the parent directory of the agent's install directory must be writable by the user that is running the agent. As an example, if the agent's $RHQ_AGENT_HOME (i.e. where the agent is installed) is the directory called "/opt/rhq-agent-parent/rhq-agent", the agent will need to write files to the "/opt/rhq-agent-parent" directory and therefore must have write permissions there.

Use Unsecured Endpoints To The New Agent Update Binary

There is currently a limitation in the agent code that only allows the agent to download the new agent update binary distribution from an unsecured, HTTP endpoint. If your agent is using an encrypted communications transport to talk to the RHQ Server (e.g. sslservlet), then you must configure your agents (prior to upgrading the server) with a separate, unsecured endpoint where your agent update binary distribution can be found. More specifically, there are two URLs that the agent needs in order to perform auto-updates - the two agent preferences you need to explicitly set that define these URLs are:

This unsecured HTTP endpoint can still be your RHQ Server, since it has an unsecured endpoint already preconfigured (e.g. the version URL and download URL would be http://your-rhq-server:7080/agentupdate/version and http://your-rhq-server:7080/agentupdate/download). You can alternatively refer to a separate web server (like Apache) that has your agent update binary distribution accessible over http. This would require that you place a copy of the agent update binary distribution file and a copy of its information properties file on your Apache web server and make it accessible over HTTP.

Auto-Updating The Agent

There is really nothing you have to do when an agent needs to be updated and it is able to auto-update itself. As long as you have configured your server and agents to allow for auto-agent updates (they are configured this way by default), it all happens automatically at the appropriate time.

When a new agent update has been released, it is placed in the server making it available for download by the old, existing agents running in the network. The server will notify the agent that it needs to update as soon as the server detects that the agent is of an older version. Once the agent knows it needs to update itself, it will stop everything it is doing, download the agent update binary, spawn a new Java process that is responsible for applying the update and then kill itself. That new Java process will update the existing agent and then restart the now updated agent. The old, existing agent will be backed up in case it needs to be rolled back (in the event the update fails for some reason).

If you wish to immediately tell the agent to update itself (or just to see if the agent needs to update or is even allowed/enabled to update), use the prompt command "update". Execute the agent prompt command "help update" for more information on that command.

You may notice that it takes several minutes for an agent to fully complete its update. The agent has many threads running in it that need to be gracefully shutdown, it then has to download and verify the integrity of the new agent update binary and then it must actually apply the update before being able to restart. Depending on the situation, it's possible several minutes could elapse before the new agent is fully functional again.

During the upgrade process, the agent will not be collecting metrics or be available to perform management functions. Once the agent is back up and communicating with the server, you will notice your resources will not have measurement data for the time period when the upgrade was taking place.