7.13. Installing Multiple Agents with a Shared Directory or Account
Multiple agents, running on multiple systems, can share the same system user accounts. If the same user is used for a JBoss ON agent on different systems and those system users all use the same shared home directory, then they all share the same agent configuration location and preference node by default. Because of the way the agent uses Java preferences, this requires special agent configuration to prevent the agents from overwriting each other's preferences.
A similar situation can occur on Windows systems if the same domain user is used for the JBoss ON agent. In that case, the Java preferences are stored in a registry key which is used by the domain user and is loaded into the local user's profile. If there are multiple agents using the same domain user, then they will overwrite each other's registry keys.
All of the agent configuration, after setup, is stored in a Java preferences node, as described in Section 7.11, “Managing the Agent's Persisted Configuration”. With the default configuration, the node name is default, and the node location is agentUserHomeDir
/.java/.userPrefs/rhq-agent/default.
If multiple agents are installed using the same file share, then all of them attempt to use the same default node and location.
When multiple agents attempt to use the same Java preferences node, each new agent overwrites the previous agent's configuration as it is set up. This means that only the newest agent's configuration is saved, so only the newest agent can be started. Starting any of the previous agents fails because they cannot find their own configuration.
The preferences node is uniquely identified by two settings:
- Its name, which is defined as an agent configuration setting
- Its location, which is itself a Java option
To run multiple agents with the same home directory, the preferences node has to be uniquely identified for each agent. There are a couple of different ways to do that:
- Editing the agent configuration files directly
- Setting an explicit Java option
7.13.1. Editing the Configuration Files
When the agent is first set up, the name of the agent preferences node is set in the
agent-configuration.xml file and is loaded from there. The node location is derived from the node name setting.
- Edit the
agent-configuration.xmlfile to use the new node name:[rhquser@server ~]$ vim agentRoot/rhq-agent/conf/agent-configuration.xml <node name="agent01-node">
- Then, start the agent with the
--configoption to load the edited configuration file and the--prefsoption to point to the specific node location:[rhquser@server ~]$ agentRoot/rhq-agent/bin/rhq-agent.sh --prefs=agent01-node --config=agent-configuration.xml
Important
If the custom Java preferences node is specified by editing the
agent-configuration.xml file, then every time the agent restarts, the node location has to be passed to the agent using the --prefs option.
7.13.2. Setting a Java Option
Editing the
agent-configuration.xml file only sets the node name; the node location still has to be passed every time the agent is started.
By setting a Java option in the
rhq-agent-env.sh file, the Java preferences node information is set once and then persisted, so you can restart the agent as a service, without having to pass --prefs options or edit and reload the configuration.
- Open the agent prompt. For example, if the agent process is already running, the prompt can be opened by re-running the
rhq-agent.shscript with the-noption.[rhquser@server ~]$ agentRoot/rhq-agent/bin/rhq-agent.sh -n
- Use the setconfig command to set the
RHQ_AGENT_ADDITIONAL_JAVA_OPTSvalue with the preference node. For example:> setconfig RHQ_AGENT_ADDITIONAL_JAVA_OPTS="-Djava.util.prefs.userRoot=agentUserHomeDir/.java/.userPrefs/rhq-agent/agent01-node"
The preference node can be in the user preferences directory with a different name, such as agent01-node, or it can be in an entirely different location, such as/etc/agent-preferences, which is not a shared or filesystem-mounted location. - Restart the agent process to load the new configuration. For example, if the agent is running as a service:
[rhquser@server ~]$ service rhq-agent-wrapper.sh stop [rhquser@server ~]$ service rhq-agent-wrapper.sh start
Note
It is also possible to stop the agent, edit the
rhq-agent-env.sh file directly, and then restart the agent.
Important
Do not set the Java option within the rhq-agent runtime directory because this file is overwritten during JBoss ON agent updates. The default location for the rhq-agent runtime is
$USERHOME/.java/.userPrefs/rhq-agent/default.
