Configuring Agent Startup Settings in its Properties File

You can configure the properties that govern communications between and HQ Agent and the HQ Server in the agent.properties file before you start it up the first time.

On Unix-based platforms, make your edits in the agent.properties in the .hq/ subdirectory in the home directory of the user that runs the agent. The properties in the home directory take preference, and unlike the copy of  agent.properties file in the agent installation directory, it will not be overwritten when you upgrade the Agent.  (If your agent runs under Windows, you must create the .hq directory using the mkdir command in a DOS shell.)

You must restart the agent for property changes to take effect, unless you run hq-agent.sh setup.

This excerpt shows the setup properties:

#agent.setup.camIP=localhost
#agent.setup.camPort=7080
#agent.setup.camSSLPort=7443
#agent.setup.camSecure=yes
#agent.setup.camLogin=hqadmin
#agent.setup.camPword=hqadmin
#agent.setup.agentIP=*default*
#agent.setup.agentPort=*default*
#agent.setup.unidirectional=no

Uncomment the properties, and as necessary, change the value.

Note that defining the agent listen address and port as *default* will cause the Agent to use the address and port that SIGAR detects on the agent host.

Definitions of the setup properties are provided below.

agent.setup.camIP

Description

You can use this property to define for the agent the IP address of the HQ server. The agent reads this value only in the event that it cannot find connection configuration in its data directory. Specifying this and other agent.setup.* properties is a way to reduce the user interaction required to configure an agent to communicate with the server.

The value can be provided as an IP address or a fully qualified domain name. To identify an server on the same host as the server, set the value to 127.0.0.1.

If there is a firewall between the agent and server, specify the address of the firewall, and configure the firewall to forward traffic on port 7080, or 7443 if you use the SSL port, to the HQ Server.

Default

Commented out, localhost.

agent.setup.camPort

Description

You can use this property to define for the agent, at first startup after installation, what server port to use for non-secure communications with the server. The agent reads this value only in the event that it cannot find connection configuration in its data directory. Specifying this and other agent.setup.* properties is a way to reduce the user interaction required to configure an agent to communicate with the server.

Default

Commented out, 7080.

agent.setup.camSSLPort

Description

You can use this property to define for the agent, at first startup after installation, what server port to use for SSL communications with the server. The agent reads this value only in the event that it cannot find connection configuration in its data directory. Specifying this and other agent.setup.* properties is a way to reduce the user interaction required to configure an agent to communicate with the server.

Default

Commented out, 7443

agent.setup.camSecure

Description

You can use this property to define for the agent, at first startup after installation, whether to communicate with the server over SSL. If you set this property to yes, all agent-server communications will be use the SSL secure port.

If acceptable in your environment, non-SSL communication offers improved performance for agent-server communications.

The agent reads this value only in the event that it cannot find connection configuration in its data directory. Specifying this and other agent.setup.* properties is a way to reduce the user interaction required to configure an agent to communicate with the server.

Default

Commented out, value of yes

agent.setup.camLogin

Description

You can use this property to define for the agent, at first startup after installation, the HQ username to use when registering itself with the server. The permission required on the server for this initialization is Create, for Platforms.

A login from the agent to the server is only required during the initial configuration of the agent.

The agent reads this value only in the event that it cannot find connection configuration in its data directory. Specifying this and other agent.setup.* properties is a way to reduce the user interaction required to configure an agent to communicate with the server.

Default

Commented out, hqadmin

agent.setup.camPword

Description

You can use this property to define for the agent, at first startup after installation, the password for the user specified by agent.setup.camLogin.

The agent reads this value only in the event that it cannot find connection configuration in its data directory. Specifying this and other agent.setup.* properties is a way to reduce the user interaction required to configure an agent to communicate with the server.

Default

Commented out, hqadmin.

agent.setup.agentIP

Description

This specifies the IP address that the HQ Server will use to contact the HQ Agent. If the agent is on the same host as the server, value of 127.0.0.1 is valid.

If there is a firewall between the server and agent, specify the IP address of the firewall, and configure the firewall to forward traffic intended for the agent to the agent's listen address, which can be configured with agent.listenIP.

The agent reads this value only in the event that it cannot find connection configuration in its data directory. Specifying this and other agent.setup.* properties is a way to reduce the user interaction required to configure an agent to communicate with the server.

Default

As installed, agent.properties contains a commented out statement that sets the value to *default*. If you use the agent.setup.* properties to supply an agent's configuration at first startup, and uncomment this property and leave the value *default*, the HQ Server will contact the agent using the IP address that SIGAR detects on the agent host.

agent.setup.agentPort

Description

This specifies the port (on the IP address configured with agent.setup.agentIP) on the agent on which the HQ Server will communication with the agent.

If there is a firewall between the agent and the server, set agent.setup.agentPort to the appropriate port on the firewall, and configure the firewall to forward traffic intended for the agent to the agent listen port, which can be configured with.

The agent reads this value only in the event that it cannot find its connection configuration in its data directory. Specifying this and other agent.setup.* properties is a way to reduce the user interaction required to configure an agent to communicate with the server.

Default

As installed, agent.properties contains a commented out statement that sets the value to *default*. If you use the agent.setup.* properties to supply an agent's configuration at first startup, and uncomment this property and leave the value *default*, the HQ Server will contact the agent on port 2144, unless SIGAR detects it is not available, in which case another default is selected.

agent.setup.resetupToken

Description

You can use this property to define for the agent, at first startup after installation, whether the agent will create a new token to use to authenticate with the server each time it starts up. Regenerating a token is useful if the Agent cannot connect to the server because the token has been deleted or corrupted.

Regardless of the value of this property, an agent will generate a token the first time it is started after installation.

The agent reads this value only in the event that it cannot find connection configuration in its data directory. Specifying this and other agent.setup.* properties is a way to reduce the user interaction required to configure an agent to communicate with the server.

Default

As installed, agent.properties contains a commented out statement that sets the value to no.

agent.setup.unidirectional*

Available only in HQ Enterprise

Description

Enables the unidirectional communications between HQ Agent and HQ Server, in HQ Enterprise. For more information, see Understanding Agent Configuration.

Default

Commented out, defaults to no.