Red Hat Training

A Red Hat training course is available for Red Hat JBoss Operations Network

6.12. 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 6.10, “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

6.12.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.
  1. Edit the agent-configuration.xml file to use the new node name: 
    [rhquser@server ~]$ vim agentRoot/rhq-agent/conf/agent-configuration.xml

<node name="agent01-node">
  2. Then, start the agent with the --config option to load the edited configuration file and the --prefs option 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.