java -jar <agent-update-binary.jar> --install
These instructions are for installing and upgrading an RHQ agent on a managed machine. Do not use these instructions for installing or upgrading agents that are on the same machine as RHQ Server or RHQ Storage Node installations. Use rhqctl to install and upgrade agents when co-locating agents with RHQ Servers and/or RHQ Storage Nodes.
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 application 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 any time 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.
You first should install one or more RHQ Servers.
If you already have agents installed and you need to upgrade them, see Manually Upgrading the Agent.
If you plan to install many RHQ Agents and would like to preconfigure them for easily automated installs, please see Preconfiguring the Agent.
To install a new RHQ Agent, follow the steps in the next sections.
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.
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.
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.
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>.
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:
|
Parameter |
Description |
|
Agent Name |
A unique name for the agent. The default is the fully qualified domain name (FQDN) of the host system. However, you can specify any name you want, as long as it is unique among all other agents in the system. |
|
Agent Hostname or IP Address |
The IP address the agent will bind to in order to listen for incoming messages. This must be resolvable by all RHQ Servers since all RHQ Servers have the potential to need to talk to this RHQ Agent. |
|
Agent Port |
The port that the agent listens to for incoming messages. All RHQ Servers must be able to tunnel to this port. |
|
RHQ Server Hostname or IP Address |
The hostname or IP address the RHQ Server is listening to for incoming messages from agents - this is the value you set as the server's public endpoint address in the RHQ Server installer. Note that this address you enter here is used by the agent to perform its initial registration request. If you are running in a High Availability (HA) environment (that is, you have multiple RHQ Servers running), this will not necessarily be this agent's primary server that it will talk to immediately after registration completes. |
|
RHQ Server Port |
The port that the RHQ Server listens to for the incoming messages from the agent. |
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
.
The agent uses a built-in feature of the Java platform called "Java Preferences" to store its configuration settings. The Java Preferences subsystem has a "backing store" where all configuration settings (aka preferences) are stored. (side note: for those familiar with the Java Preferences API, RHQ only stores user preferences under the backing store's user preferences root node).
Depending on your Java vendor's implementation, this backing store can be in different places. For example, SUN's Java implementation on Windows uses the Windows Registry for the backing store; on Linux platforms, SUN's Java Preferences backing store is the user's $HOME directory - specifically $HOME/.java.
If you are running on a non-Windows platform, this is a very important point to understand - the agent's configuration is determined by what user is running the agent. If you run the agent as one user but later run it a second time as another user, the agent will have a different configuration that second time because it will use a different backing store for its configuration settings. For example, suppose you log in as a non-root user called "john" and start up a newly installed agent in a console window in order to answer its initial setup questions - the agent's new configuration settings will be stored in ~john/.java. Then suppose you set up that agent to run in the background as an init.d boot time service and reboot your machine. The agent will start up at boot time, but it will probably run as root and thus the agent will look for its configuration in ~root/.java - a totally different backing store location compared to when running as user "john". Thus, your agent will not be configured the same as it was when you ran it under the user "john". Therefore, you must ensure the agent runs as the same user as the user that configured the agent previously.
The agent determines what its configuration should be by reading the values it finds in the Java Preferences backing store. In other words, the agent really doesn't get the authoritative values of its configuration settings from the agent-configuration.xml - it gets its true configuration values from the Java Preferences backing store. If the Java Preferences backing store is missing its RHQ settings, only then will the agent read agent-configuration.xml - the values found in that XML file will be used as default values which initialize the backing store (i.e. the agent will read the default values it finds in agent-configuration.xml and store them in the Java Preferences backing store). From then on, the backing store will have RHQ settings and agent-configuration.xml is no longer needed or read. The only time agent-configuration.xml is used again is if you delete the RHQ settings from the backing store (which happens, for example, when you pass the command line option "--cleanconfig" to the agent).
You can override the values found in agent-configuration.xml by passing -D options to the agent. For example, if you pass the command line option "-Drhq.agent.wait-for-server-at-startup-msecs=90000" to the agent, the preference setting "rhq.agent.wait-for-server-at-startup-msecs" will be set to "90000" regardless of what value is found in agent-configuration.xml. In fact, -D even overrides values found in the Java Preferences backing store - so in this example, even if a value for "rhq.agent.wait-for-server-at-startup-msecs" was already set in the Java Preferences backing store, it doesn't matter because the -D option overrides it and the agent will consider its value to be "90000".
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:
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.
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.
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.
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.
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).
Configure the agent.
Edit the rhq-agent-wrapper.bat script and set the environment variable to define the system user as whom the init script will run. There are two options:
RHQ_AGENT_RUN_AS explicitly sets the user account name. This must match the format of a Windows user account name, DOMAIN\username.
RHQ_AGENT_RUN_AS_ME forces the agent to run as whoever the current user is; this uses the format . \ %USERNAME %. If both environment variables are defined, this variable overrides RHQ_AGENT_RUN_AS.
Before setting RHQ_AGENT_RUN_AS_ME or RHQ_AGENT_RUN_AS, make sure that the given user actually has permission to start services. If necessary, assign the user the appropriate rights.
If neither variable is set, the agent init script runs as the System user. Other available environment variables are listed and defined in the comments in the rhq-agent-wrapper.bat script.# Run the rhq-agent-wrapper.bat script to install the init script as a service. Use the install command to install the init script.
When prompted, fill in the password for the system user as whom the service will run.
The agent service starts automatically when the Windows system boots. The service can be started or stopped through the Windows Services Administrative Tools.
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:
|
rhq-agent.sh |
Launcher script to start the agent in a console window on UNIX |
|
rhq-agent.bat |
Launcher script to start the agent in a console window on Windows |
|
rhq-agent-wrapper.sh |
Launcher script to start the agent as a background daemon on UNIX |
|
rhq-agent-wrapper.bat |
Launcher script to start the agent as a Windows Service on Windows |
|
rhq-agent-env.sh |
Script to setup the agent environment on UNIX |
|
rhq-agent-env.bat |
Script to setup the agent environment on Windows |
|
wrapper/rhq-agent-wrapper.conf |
Configuration for the agent's Windows Service on Windows |
|
wrapper/rhq-agent-wrapper.env * |
Sets up additional environment variables for the Windows Service on Windows |
|
wrapper/rhq-agent-wrapper.inc * |
Overrides or adds Windows Service configuration settings on Windows |
* These do not exist out of the box when you install an agent but you can create and configure them when appropriate. Most people, however, will not need these.
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.
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).
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:
The keystore files must have the word "keystore" in their filenames. For example, "my-agent-keystore.dat".
The truststore files must have the word "truststore" in their filenames. For example, "my-agent-truststore.dat"
You must have your keystore and truststore files in the agent's <agent-install-dir>/conf 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.
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.
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:
|
rhq.agent.agent-update.version-url |
The URL the agent uses when it needs to retrieve information about the latest available agent update binary. |
|
rhq.agent.agent-update.download-url |
The URL the agent uses when it needs to download the latest available agent update binary distribution file. |
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.
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.