8.7. About Agent Automatic Updates

Even for automatic upgrades for the agent, certain preparation has to be made to the JBoss ON agent to make sure that the upgrade process goes smoothly and the agent restarts successfully.

8.7.1. The Process When an Agent Autoupgrades

By default, both JBoss ON servers and agents are configured to upgrade agents automatically. As soon as the JBoss ON server is upgraded, then the agents will be upgraded.


The agent should be running in the background to upgrade properly, as in Section 8.4, “Running the JBoss ON Agent as a Service”.
The automatic upgrade process is part of the normal agent tasks of checking the server for updates:
  1. The updated server puts the updated agent packages in a directory accessible to the agent.
  2. The server notifies the agent that the agent needs to update as soon as the server detects that the agent is running an older version.
  3. As the agent prepares to update, it begins shutting down its other process. This can take several minutes, as it gracefully shuts down each thread.
  4. The agent downloads the new binaries from the server.
  5. The agent spawns a new Java process.
  6. The Java process backs up the old agent configuration and applies the update.
  7. The Java process then restarts the agent and kills itself.
It is possible to instruct an agent to initiate an update or to check if updates are available using the update through the agent command line:

> update

8.7.2. Configuring Agent Preferences

Agent preferences for settings like the Java home directory can be set in environment variables for normal use. However, the environment variables set in the shell are lost when the upgrade process stops and restarts the agent, and that means that the agent may not automatically restart after upgrade. Custom settings for the agent, such as RHQ_AGENT_HOME or RHQ_AGENT_ADDITIONAL_JAVA_OPTS, should be added to the rhq-agent-env.sh file. This file is preserved during upgrade so all of the settings are carried over.


Do not edit any of the scripts used to launch the JBoss ON agent. There are four files which should never be modified:
  • rhq-agent.sh
  • rhq-agent-wrapper.sh
  • rhq-agent.bat
  • rhq-agent-wrapper.bat
Any changes to the launcher scripts are overwritten during the automatic update. Changes to the environment files (such as rhq-agent-env.sh ) are preserved during the update.

8.7.3. Upgrading Custom log4j Settings

Any edits to the Java settings in the rhq-agent-env.sh file are preserved between upgrades. However, any changes to the log settings (log4j.xml) and other files are lost between upgrades.

8.7.4. Configuring Keystores and Truststores

If the original JBoss ON agent was configured to run over SSL using custom keystores and truststores, then make sure that those stores are configured so that the upgraded agent can still access them:
  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. Both the keystore and truststore files must be located in the agent's agentRoot/rhq-agent/data directory.
As long as the SSL files are properly set up, then they will be copied over into the new agent configuration, and the new agent will automatically run in SSL.

8.7.5. Setting Writer Permissions on the Agent Home Directory

The upgrade process will write new files to the agent's current installation directory, so the agent's system user must have write permissions to that directory.
If the agent's home directory is /opt/rhq-agent, then the agent has to be able to write to the /opt/rhq-agent directory. If necessary, reset the permissions on the agent home directory. For example:
chown agent_user /opt/rhq-agent

8.7.6. Starting the Agent as a Background Service

Section 8.4, “Running the JBoss ON Agent as a Service” describes how to configure the agent to run as a background service. On Windows, this runs as a service. On Linux and Unix systems, the agent starts at boot time from init.d.
The auto-upgrade process assumes that the agent is running in the background. If the agent is not running as a background daemon, when the agent auto-updates itself, the old agent process running in the console is shutdown, and the new agent is restarted as a background service if possible. On Windows, if the agent is not installed as a service, the agent is restarted in a console window.