6.6. 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.
6.6.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 6.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:
- The updated server puts the updated agent packages in a directory accessible to the agent.
- 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.
- 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.
- The agent downloads the new binaries from the server.
- The agent spawns a new Java process.
- The Java process backs up the old agent configuration and applies the update.
- 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:
agentRoot/rhq-agent/bin/rhq-agent.sh > update
6.6.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_ADDITIONAL_JAVA_OPTS, should be added to the
rhq-agent-env.shfile. 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:
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.
6.6.3. Custom Scripts
JBoss ON 3.3 allows for custom scripts to be placed in the agent's
/bin. When an agent is upgraded, any files with the
.batextension found in the agent's
/bindirectory will be copied to the new agent's
6.6.4. Upgrading Custom log4j Settings
Any edits to the Java settings in the
rhq-agent-env.shfile are preserved between upgrades. Also, if any changes are made to the log4j.xml file, the entire file will be copied over.
6.6.5. Upgrading Custom agent-configuration.xml Settings
During the upgrade process, if the current
agent-configuration.xmldiffers at all from the newly installed
agent-configuration.xml, both files are preserved. The current
agent-configuration.xmlfile is retained with the same name. The newly installed
agent-configuration.xmlis renamed to
agent-configuration.xml.new. This allows for custom settings to be retained if the agent is restarted using the --cleanconfig option. Users should review both files to ensure that any new settings are added to the
If the current
agent-configuration.xmland the newly installed
agent-configuration.xmlare exactly the same, then an
agent-configuration.xml.newfile will not be created.
6.6.6. 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:
- The keystore files must have the word keystore in their filenames. For example,
- The truststore files must have the word truststore in their filenames. For example,
- Both the keystore and truststore files should be located in the agent's
agentRoot/rhq-agent/conf/directory. Any trust files in the agent's
conf/directory will be preserved when the agent configuration is cleaned or purged, including during upgrade.
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.
6.6.7. Setting Write 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 the parent directory. For example, if the agent is installed in
/opt/rhq/rhq-agent, then the agent user should have write permissions to the
If necessary, reset the permissions on the agent home directory. For example:
[root@server ~]# chown agent_user /opt/rhq
6.6.8. Starting the Agent as a Background Service
Section 6.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
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.