|
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 StartupWhen 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:
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 StoredThe 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.propertiesWhen 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. What Happens when an Agent Starts UpIf you are having trouble starting an agent, or need to change its startup configuration, it is helpful to understand how the agent obtains its startup settings. 1. When an agent starts up, it looks in its /data directory for the information it needs to be able to connect to the HQ Server. If it finds that information, the agent connects to the HQ server and gets additional startup settings from the database. 2. If the agent doesn't find the connection information that allows it to connect to the HQ Server in its /data directory---either because it has not been started previously, or because the data directory's contents are corrupt or missing, it looks for uncommented agent.setup.* properties in the agent.properties file. The agent looks for the properties file in these locations, in this order:
If the agent finds the connection properties it needs in the agent.properties file, those property values are saved---the server connection information in the AgentHome/data directory, and the agent connection information in the HQ database. 3. If the agent fails to find any or all of the required connection and startup settings, it prompts the user to supply the missing information. If the user supplies values that enable it to connect to the HQ server, those values are persisted, as described above. How to Change Agent Setup Configuration PropertiesAs 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. Understanding Agent - Server CommunicationsBy default, communications between an HQ Agent and an HQ Server is bidirectional.
If your security policies dictate, you can configure the agent to initiate all communications with the HQ Server. You can configure unidirectional communications at first startup of a new 4.x agent, or an upgraded 4.x agent. If you want to change from bidirectional to unidirectional communications at a later time, see Changing Between Unidirectional and Bidirectional Agent Communications. HQ 4.0 Agent Installation Directory StructureIn HQ 4.0, the agent directory structure has changed. The new structure is shown below.
HQ_AGENT_HOME
bin
conf
bundles
agent-x.y.z
conf
bin
lib
pdk
product_connectors
rcfiles
tmp
log
wrapper
lib
sbin
jre
data
|
Understanding Agent Configuration
(None)