Red Hat Training

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

Chapter 7. Configuring Agents

The agent can be configured and managed through the agent prompt, which is opened through the rhq-agent.sh script.
Report a bug

7.1. Registering and Re-registering the Agent

When an agent registers with the JBoss ON server, the agent name is used as a unique resource key to identify the agent. In addition, the server generates a random string which it sends to the agent to use as a registration token or security token.
Report a bug

7.1.1. About the Security Token and Agent Registration

When the JBoss ON agent starts up, it registers with the JBoss ON server and sends the server its information. The JBoss ON server creates an entry based on the given agent name, IP address, and port number.
The JBoss ON server also creates a randomly-generated string, a security token, which is also associated with the agent name and with the IP address and port number pair.

Figure 7.1. Agent Registration

Agent Registration
The agent sends its security token to the server when it restarts as a form of pseudo-authentication. The JBoss ON server uses the unique resource key (the agent's name) and its security token as a way to verify the agent identity.
The JBoss ON server associates the agent name and its security token every time the agent starts up and registers with the server. If the agent-supplied information does not match the information that the JBoss ON server has for that agent, then it rejects the agent's connection attempt.

Figure 7.2. Different Agent Connection Attempts

Different Agent Connection Attempts
That means that there are a few rules about when the JBoss ON server will accept changes to the agent's registration information:
  • An agent cannot register with an existing agent name without the corresponding security token.
    To register an agent with an existing agent name, you must first install the corresponding security token, as described in Section 7.1.2, “Re-installing a Lost Security Token”.
  • An agent cannot register with an existing IP address/port combination without having the corresponding security token and using the original agent name.
    This essentially means that you cannot rename an agent. If an agent is registered with an existing IP address/port combination, then both the original security token and the original name must also be used. This re-establishes the original identity of the agent and prevents one agent from effectively stealing the identity of another agent.
  • An agent can register with an existing name and a new IP address/port combination if it has the security token which corresponds to that agent name.
    While the agent name cannot be changed during re-registration, the agent IP address, the agent port, or both can be changed. This is a common and useful scenario in cloud, virtual, or DHCP environments where an existing agent needs to re-register with a new IP address or port.
Note
The security token is stored in the agent's Java preferences. This security token persists even if the agent is restarted, is uninstalled, or has its configuration wiped with --cleanconfig. This allows the agent to re-register easily.
Report a bug

7.1.2. Re-installing a Lost Security Token

If a security token is accidentally deleted from the agent's configuration, then the agent can no longer communicate with the server. Any attempt fails with a failure to authenticate error.
A lost security token can be re-added to the agent's configuration manually.
  1. Stop the agent.
  2. Log into the web UI as a user with manage security permissions.
  3. Click the Administration tab and select the Agents link under the Topology section on the left.
  4. Select the agent from the list, and click its name to open its details page.
  5. Copy the security token.
  6. Restart the agent, and use the -D option to set the rhq.agent.security-token property to the security token. 
    agentRoot/rhq-agent/bin/rhq-agent.sh -Drhq.agent.security-token=abcd1234
Report a bug

7.1.3. Reinstalling the Agent with a New Security Token

An agent can be re-installed and re-registered, with completely fresh configuration. There are three points of configuration for the agent: the agent's (local) persisted configuration, the agent inventory (and associated resource data), and the platform entry in the server inventory. Both the configuration on the local machine and the agent and resource configuration on the JBoss ON server need to be cleared for the agent to reinstalled successfully:
  • The agent's persisted Java configuration should be purged.
  • The agent's inventory should be purged, along with any resource history and configuration.
  • The agent must be removed from the JBoss ON inventory. This can be done by removing the agent from the JBoss ON topology (Section 7.2, “Removing an Agent”) or by deleting the platform entry.
  • The agent's original identifying information (name, IP address, and port) can be changed.
To reinstall the agent:
  1. Make sure that the original agent instance is properly removed.
    1. Stop the agent process.
    2. Remove the platform entry from the JBoss ON server inventory.
  2. Restart the agent with the --fullcleanconfig option. This registers the agent with a new security token and fresh configuration settings. 
    agentRoot/rhq-agent/bin/rhq-agent.sh --fullcleanconfig
Note
If the agent was not removed from the JBoss ON inventory, then the re-installation fails with an error that the agent has an invalid security token.
Report a bug

7.1.4. Cleaning the Agent Configuration, with the Original Security Token

An alternative re-registration path cleans the agent configuration except for its security token. The agent uses that existing security token to register with the server, so it essentially refreshes its registration instead of re-registering.
In this case, almost all of the original agent configuration is preserved:
  • The agent's persisted Java configuration is purged.
  • The agent's inventory, along with any resource history and configuration, is saved.
  • The agent (via the platform entry) remains in the JON inventory.
  • The agent's name must remain the same (though the IP address or port number can be changed).
The main action, then, is the the agent configuration is refreshed, while the agent entry itself is preserved.
To clean the agent configuration, restart the agent with the --cleanconfig option. This registers the agent with fresh configuration settings (from the conf/agent-configuration.xml file) and reuses its previous security token. 
agentRoot/rhq-agent/bin/rhq-agent.sh --fullcleanconfig
Note
If the agent name is different, then this re-registration attempt fails because the existing security token cannot be validated with the given (new) agent name.
Report a bug