6. Configuring Agents
6.1. Registering and Re-registering the Agent
6.1.1. About the Security Token and Agent Registration
Figure 8. Agent Registration
Figure 9. Different Agent Connection Attempts
- 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 6.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.
--cleanconfig. This allows the agent to re-register easily.
6.1.2. Re-installing a Lost Security Token
- Stop the agent.
- Log into the web UI as a user with manage security permissions.
- Click the Administration tab and select the Agents link under the Topology section on the left.
- Select the agent from the list, and click its name to open its details page.
- Copy the security token.
- Restart the agent, and use the
-Doption to set the
rhq.agent.security-tokenproperty to the security token.
6.1.3. Reinstalling the Agent with a New Security Token
- 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 (via the platform entry) must be removed from the JON inventory.
ImportantIf the agent was configured, but the platform was never imported into the inventory, then you must import the platform from the discovery queue first, and then delete the platform. The discovery queue is a halfway point in the inventory. Even if the agent is removed, the platform could still linger in the discovery queue as a ghost entry.
- The agent's original identifying information (name, IP address, and port) can be changed.
- Make sure that the original agent instance is properly removed.
- Stop the agent process.
- Remove the platform entry from the JBoss ON server inventory.
- Restart the agent with the
--fullcleanconfigoption. This registers the agent with a new security token and fresh configuration settings.
6.1.4. Cleaning the Agent Configuration, with the Original Security Token
- 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).
--cleanconfigoption. This registers the agent with fresh configuration settings (from the
conf/agent-configuration.xmlfile) and reuses its previous security token.