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.
Note
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_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.
Warning
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.
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 .sh or .bat extension found in the agent's /bin directory will be copied to the new agent's /bin directory.
6.6.4. Upgrading Custom log4j Settings
Any edits to the Java settings in the
rhq-agent-env.sh file 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.xml differs at all from the newly installed agent-configuration.xml, both files are preserved. The current agent-configuration.xml file is retained with the same name. The newly installed agent-configuration.xml is 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 agent-configuration.xml.
Note
If the current
agent-configuration.xml and the newly installed agent-configuration.xml are exactly the same, then an agent-configuration.xml.new file 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,
my-agent-keystore.dat. - The truststore files must have the word truststore in their filenames. For example,
my-agent-truststore.dat. - Both the keystore and truststore files should be located in the agent's
agentRoot/rhq-agent/conf/directory. Any trust files in the agent'sconf/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 /opt/rhq directory.
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
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.
