The paragraphs that follow provide useful information about agent configuration data - how it is initially supplied, where it is saved, and how to change it.
How an Agent Obtains its Configuration at First Startup
When you install the agent, you do not supply any configuration information. The first time you start an agent, you must supply the minimum configuration data that the agent needs to communicate with the HQ Server, in one of these ways:
- Interactively - Start the agent, and it will prompt you to supply configuration values that enable it to contact the HQ Server, as described in Configuring Agent Startup Settings Interactively.
- In agent.properties - Before you start the agent, supply the configuration values in the agent.properties file, as described in Configuring Agent Startup Settings in its Properties File. This method is preferable if you have many agents to install, as it speeds the process and reduces the chance of error.
Agent Server Communications Diagram summarizes key facts about communications between the HQ Agent and the HQ Server, and how that behavior is configured and persisted.
Where Agent Startup Configuration Data is Stored
The configuration choices you must supply for the agent to start up specify where and how to communicate with the HQ Server. As described above, you can supply these setup values either interactively or in the agent's properties file.
Note that upon successful startup, the HQ Agent saves its setup configuration data it two locations: settings related to the agent-to-server connection are stored in the /data directory under the agent installation directory; settings related to server-to-agent connection are stored in the HQ database. The agent creates the /data directory upon first successful startup. On subsequent startups, the agent will look at the setup data stored in its /data directory and in the HQ database to determine where and how to connect to the HQ Server.
The agent properties that govern communications are the ones that are absolutely required for an agent to start up. In addition, there are a number of other agent properties that you can use to configure optional agent features and behaviors. Unlike the setup properties, which the agent obtains from its data directory and the HQ database, the properties that control optional agent behaviors are persisted only in agent.properties.
For a complete list of agent properties, see Agent Properties. The setup properties related to communications with the HQ server are those whose name starts with "agent.setup".
Supported Locations for agent.properties
When you install the HQ 4.0 Agent, agent.properties is placed in AgentHome/conf.
Note that the agent honors an external (from the agent installation) location for the properties file: an .hq directory under the home directory of the user under which the agent runs. If that directory does not exist, you can create it. Note that under Windows, you must use the mkdir command in a DOS window to create to create a directory with a leading period (.).
Storing agent.properties external to the agent installation directory is useful, because some upgrade scenarios will overwrite the /conf directory. Specifically, upgrading an agent by installing a full agent package will overwrite your previous agent installation. This is relevant when you first upgrade an agent from 3.2.x or 3.1.x to 4.x, or if you choose to upgrade a 4.x agent to a later version by installing a full agent package. In these cases, if you don't keep the properties file in the .hq/ directory, back it up prior to upgrade, and restore it after upgrade.
Once you have an operational 4.0 agent installation, you can upgrade it by installing an agent bundle only - you can perform this upgrade operation from the HQ user interface or using a manual procedure, if you prefer. When you upgrade the agent bundle only, the agent's /conf directory is not updated---this method preserves the agent.properties file within the agent installation through the upgrade.
How to Change Agent Setup Configuration Properties
As described in How an Agent Obtains its Configuration at First Startup, you configure an agent's setup properties - the properties that begin with "agent.setup" - the first time you start it up. The properties that relate to where and how to contact the HQ server, are saved in the agent's /data directory; those related to how the server can reach the agent are stored in the HQ database.
If you need to make changes to those configuration values for an agent at a later time, you can delete the agent's /data directory, edit the agent.setup.* properties in the agent.properties file, and restart the agent. You must use this method if you wish to change the agent's listen port---you cannot change port settings without restarting the agent.
If you prefer to change the startup configuration (other than agent listen port) without having to restart the agent, run the following command in a command shell, while the agent is running.
AgentHome/hq-agent.sh setup
This will allow you to interactively supply new values for the setup properties, as described in Configuring Agent Startup Settings Interactively at First Startup. This will this cause all properties in the properties file to be re-read, and take effect.