On Unix-based systems, use this command and a supported command switch to invoke agent operations from a command shell:

$AGENT_HOME%/bin/hq-agent.sh

Command switches are shown below.

                               start---starts the agent as a daemon process

                               stop---stops the agent process

                               restart---stops and then starts the agent's JVM process

                               status---indicates whether there exists a running agent process

                               dump---sends a kill -3 signal to the agent JVM process in order to obtain a full thread dump

                               ping---pings the agent process for availability

                               setup---prompts for setup configuration for the agent process

 

 

 

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

                   Where Agent Startup Configuration Data is Stored

                   Supported Locations for agent.properties

                   What Happens when an Agent Starts Up

                   How to Change Agent Setup Configuration Properties

                   Understanding Agent - Server Communications

                   HQ 4.0 Agent Installation Directory Structure

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.

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.

On Unix-based platforms, 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. 

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 Up

If 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:

                               .hq subdirectory in the home directory of the user that runs the agent (on Unix-based systems only)

                               AgentHome/conf directory---the installation location for the properties file

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 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. 

Understanding Agent - Server Communications

By default, communications between an HQ Agent and an HQ Server is bidirectional.

                               Agents initiates a communications channel to send measurement data, auto-inventory information, and event log data to the HQ Server. All of the agent-to-server data flows over HTTPS via a byte encrypted XML protocol called Lather.

                               The HQ Server initiates communications related to: 1) creation and update of the metric scheduling, 2) verification of metric scheduling, 3) initiation of auto-inventory requests, 4) control actions, and 5) the live data plug-in framework data. These data flows use a simple protocol directly on top of TCP.

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 Structure

In 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