This page will describe how an agent registers with its server and what an "agent name" and "security token" is and what they are used for.
The "agent name" is the "key" to uniquely identify any agent. It is given to the agent either at setup time or in its configuration file. If not defined, the default is the fully qualified domain name but an agent name can be any string and doesn't have to be related in any way to the agent's hostname or IP address (although it can be if you want).
Every time the agent starts up, it will re-register with the server. Agent registration on the server means the agent will attempt to associate its agent name with its agent endpoint IP address and port. In our examples following, let's assume our agent is named "foo" with an IP address of 1.2.3.4 and port 16163.
When the agent registers its agent name for the very first time, the server will say, "OK, your agent name "foo" is now associated with agent IP 1.2.3.4 and port 16163". The server will also create a "security token" for the agent and send that security token down to the agent. A "security token" is just a randomly generated string created by the server that is unique to an agent.
The security token and agent name then both get persisted in the agent's preferences (they get stored in your user's Java Preferences location, which is, by default, $HOME/.java on UNIX machines). If you restart the agent, or even if you re-install the agent, those persisted values remain intact assuming the same user is installing/running the agent (i.e. the security token and agent name assignments survive agent restarts/reinstallations). This security token will be used from here on out to identify this agent's registration. If this token is ever lost, the agent will not be able to re-register with its name "foo".
The security token is sent as part of the agent-to-server messaging and used by the server as a kind of pseudo-authentication mechanism (however, it is not to be considered true security - you would need to configure the server-agent communications to use secure SSL communications for that).
If you delete that security token (e.g. restarting the agent with --fullcleanconfig), that agent will attempt to register as a new, unidentified agent but it will not be able to register under the same name "foo" as before nor can it register with the same IP/port combination. This is because that security token is now associated with agent "foo" on IP 1.2.3.4 listening to port 16163 - no other agent can register using that name or IP/port combination without the proper security token. Any agent that wants to identify itself with the name "foo" must have the associated security token. If you wish to re-register that agent with the same name "foo", you must re-install the security token. One way you can do this is:
Stop the agent
Log into the GUI as a user with MANAGE_SECURITY permissions (such as "rhqadmin") and go to Administration>Agents and find your agent. View its details and copy down its security token - let's call it "security-token-foo".
Start the agent with command line option "-Drhq.agent.security-token=security-token-foo"
At this point, the agent should be able to re-register with the same name "foo" as before, now that its security token has been reinstalled. You no longer need to start the agent with that -D option, you only needed to do it once to get that new security token stored in the agent's configuration.
Note that changing the IP of an agent box or the port an agent is listening to, assuming the agent still has its security token, is supported. This is a common occurrence - needing to change the hostname or IP of a box - so the agent supports the ability to maintain its identity while changing its IP/port combination. However, if you do change the IP of the agent box, you are required to restart the agent so it knows to bind to the new address. If you had previously configured the agent to explicitly bind to the old IP address, you must reconfigure the agent to bind to the new IP address (in other words, you must ensure the agent preference "rhq.communications.connector.bind-address" is set). If your agent had previously left that value unset, the agent should be able to automatically detect the new IP address upon restart without you having to reconfigure the agent.