Set Up Agent in Properties File

Topics marked with * relate to features available only in vFabric Hyperic.

About this page...

This page has instructions for configuring a newly installed Hyperic Agent to communicate with the Hyperic Server in its properties file. It corresponds to the Configure Hyperic Agent in properties file step of the Hyperic Installation and Startup Process.

Note that if you start an agent without previously configuring required data in the properties file, you will be prompted to supply connection-related data in the shell, as described in Set Up Agent Interactively.

If you have multiple Hyperic Agents to deploy, it is more efficient to configure agent behaviors in the properties files. Install Hyperic Agents in Volume describes options for remote agent installation and configuration using a standard agent.properties file that you can use for all agents in your environment.

Agent Properties Location

The Hyperic Agent looks for its properties file in two locations, in this order:

  • HqUserHome/.hq — If this directory exists and contains agent.properties, the Hyperic Agent will use the property values defined there. (Hyperic honors this location for historical reasons. In pre-4.2 versions of Hyperic, storing the properties file in a location external to the agent installation directory was a method of ensuring that agent configuration settings survived an agent upgrade. This precaution is not necessary in Hyperic 4.2 — you can update the agent bundle from the Hyperic user interface without risk of overwriting the properties settings.)

  • AgentHome/conf — This is the default location of agent.properties.

If the agent does not find the the properties it needs to establish communications with the Hyperic Server in either of these locations, it prompts for the property values at startup.

Procedure: Configure Agent-Server Communication Properties

Step 1 - Open or create agent.properties

Make a copy of the agent.properties file from the agent installation.

Step 2 - Uncomment Agent-Server Communication Properties

In the agent.properties file, find the section excerpted below, and remove the hash mark (#) in front of each the properties shown at the end of the excerpt.

 
## Use the following if you'd like to have the agent setup 
## automatically from these properties. The values for these 
## properties are used to answer the setup questions 
## 
## If any of these properties are left undefined, the setup 
## process will prompt for their values 
## 
## If the value that should be used is the default when interactive 
## setup is done, use the string *default* as the value for the option 

#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.resetupTokens=no 

Step 3 - Define Communication Properties in agent.properties File

See Communication Properties Reference below for property definitions.

The agent.properties file contains properties you can configure to govern both agent-initiated and server-initiated communication.

  • Specify the location and credentials the agent should use to contact the Hyperic Server with these properties:

    • agent.setup.camIP — Specify the address or hostname of the Hyperic Server.

    • agent.setup.camPort — The default value is the standard plaintext Hyperic Server listen port. If your server is configured for a different listen port, supply the port number.

    • agent.setup.camSSLPort — The default value is the standard SSL Hyperic Server listen port. If your server is configured for a different listen port, supply the port number.

    • agent.setup.camSecure — The default value is "yes" (use SSL). SSL configuration is strongly recommended, and required if you are going to configure the agent for unidirectional communications. Change to "no" if you do not require the agent to use secure communications when contacting the Hyperic Server.

    • agent.setup.camLogin — Specify the username the agent should use when connecting to the server. If you change the value from the default value ("hqadmin"), make sure that that user account is properly configured on the Hyperic Server.

    • agent.setup.camPword — Specify the password the agent should use, along with the username above, when connecting to the server. Make sure that the password is the one configured in Hyperic for the user account.

      About Password Encryption

      The first time you start the Hyperic Agent, if agent.setup.camPword is uncommented, and has a plain text value, the agent will encrypt the value. Note that you can encrypt this and other agent property values yourself, as described in Encrypt an Agent Property Value.

  • You may specify the address or hostname and the listen port the Hyperic Server should use to contact the Hyperic Agent with the following properties. Note however, that if you are creating a standard agent.properties file that can be used for all agents (as described in Install Hyperic Agents in Volume), uncomment these properties, but do not change the value of either:

    • agent.setup.agentIP — If you leave the default setting — "default" — the Hyperic Agent will detect an IP address on the platform and choose it as its listen address.

    • agent.setup.agentPort — If you leave the default setting — "default" — the Hyperic Agent will use the default listen port (2144 for plaintext or 2443 for SSL) as its listen address. If that port is unavailable, the agent will detect a free port and choose it as its listen port.

These are the minimum properties required for agent-server communication.

Step 4 - Configure Unidirectional Communications (Optional)

By default, agent-server communication is bidirectional. If your policies dictate that all communication between agent and server are agent-initiated, you can uncomment the agent.setup.unidirectional property and set it to "yes". For more information, see Unidirectional Agent-Server Communication.

If you configure unidirectional communication, and the agent will contact the Hyperic Server via a proxy server, define the proxy server host in the following properties, which you must add to the properties file:

  • agent.proxyHost

  • agent.proxyPort

See agent.setup.unidirectional, agent.proxyHost and agent.proxyPort below for property definitions.

Step 5 - Configure Agent Keystore (Optional)

Perform this step if you want the agent to use a keystore you configure, rather than have it generate and use a self-signed certificate for SSL communication with the Hyperic Server.

Hyperic and SSL Communication

Read About SSL in Hyperic for information about SSL certificates and certificate verification in Hyperic 4.6 and later.

  1. Uncomment the following properties in agent.properties. Define the full path to the keystore with agent.keystore.path and the keystore password with agent.keystore.password. For more information, see agent.keystore.path and gent.keystore.password below.

     
    # agent.keystore.path= 
    # agent.keystore.password= 

  2. If you configured the agent for unidirectional communication as described in step 4 above, add [agent.keystore.alias to the properties file, and set it to the alias for the keystore's primary certificate/private key entry.

  3. Verify that agent.setup.acceptUnverifiedCertificate is "false".

See Communication Properties Reference below for property definitions.

Step 6 - Configure Additional Agent Behaviors (Optional)

As desired, you can configure additional agent behaviors in the agent.properties file. For information about configurable agent behaviors, see:

Step 7 - Save Changes

After completing your edits, save your changes and start the agent.

For instruction on how to start the agent for the first time, see Start the Hyperic Agent for the first time on the Hyperic Installation and Startup Process page.

Encrypt an Agent Property Value

Starting in Hyperic 4.6.6, the agent.properties file supports encrypted property values.

If, prior to first agent startup, you uncomment and assign a plain text value to agent.setup.camPword or agent.keystore.password, the agent will automatically encrypt the property value, as described in Hyperic Security Features and Recommendations.

If you prefer, you can encrypt these (and other, if desired) property values yourself.

About Where the Agent Finds Server Connection Data

Note that upon first successful connection to the Hyperic Server, a Hyperic Agent saves the credentials it used in its /data directory. Upon each restart, the agent looks first in that directory for server connection details. Hence, edits to the username and password (agent.setup.cam.Login and agent.setup.camPword) configured in agent.properties have no effect, if the agent has valid connection data its /data directory.

To add an encrypted entry to agent.properties, run the agent start script (AgentHome/bin/hq-agent.sh or AgentHome/bin/hq-agent.bat with the new set-property option, and supply the name of the property and the value you wish to encrypt.

Do not use set-property option on an agent upgraded to v4.6.6

The set-property option is only supported for newly installed agents. You cannot manually encrypt properties for an agent that you upgraded to 4.6.6 by pushing the 4.6.6 bundle from the Hyperic Server. Note however that if an upgraded agent's agent.properties file contains uncommented password properties with plaintext values, they will be automatically encrypted.

The command syntax is:

 
./hq-agent.sh set-property PropertyKey PropertyValue 

For example, to set the agent.setup.camPword to "hqadmin":

 
./bin/ hq-agent.sh set-property agent.setup.camPword hqadmin 

If the properties file does not already define the property, the property definition is added at the end of the agent.properties file; the encrypted value (not plain text) is shown. For example:

 
agent.setup.camPword=ENC(gaSh3I8gg1olL1EDHHJo/g==) 

The key that was used to encrypt the value is saved in AgentHome/conf/agent.scu.

If you encrypt another property value, the key in AgentHome/conf/agent.scu will be used.

Note that after you encrypt agent.setup.camPword (or any property that the agent uses to connect to the server) the agent must be able to access AgentHome/conf/agent.scu or it will fail to start up. Do not delete agent.scu.

If your agent deployment strategy involves distributed a standard agent.properties file to all agents, you must also distribute agent.scu. For more information, see Install Hyperic Agents in Volume.

If agent.scu is missing...

Iff a Hyperic Agent's AgentHome/conf/agent.scu file is missing, subsequent attempts to run the agent start script (hq-agent.sh or hq-agent.bat) with the setup option will fail. To resolve this problem, you must either:

  • Reinstall the agent, or

  • Perform these steps:

    1. Stop the agent.

    2. Delete its /data directory.

    3. Set agent.setup.camPword in AgentHome/conf/agent.properties to a plain text value.

    4. Start the agent.

Communication Properties Reference

See Agent Properties for definitions of all agent properties.

agent.setup.camIP

Description

You can use this property to define for the agent the IP address of the Hyperic Server. The Hyperic 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 Hyperic Server.

Default

Commented out, localhost.

agent.setup.camPort

Description

You can use this property to define for a Hyperic 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 Hyperic Agent, at first startup after installation, what server port to use for SSL communications with the Hyperic 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 Hyperic Agent, at first startup after installation, the Hyperic 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 the password that the Hyperic Agent will use when connecting to the Hyperic Server, so that the agent will not prompt for the user to supply the password interactively at first startup. (This is 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.

Starting in Hyper 4.6.6, the first time you start the Hyperic Agent after installation, if agent.keystore.password is uncommented and has a plain text value, the agent will automatically encrypt the property value. If you prefer, you can encrypt these (and other, if desired) property values yourself prior to starting the agent. For more information, see Encrypt Agent Property Value.

Default

Commented out, hqadmin

agent.setup.agentIP

Description

This specifies the IP address that the Hyperic Server will use to contact the Hyperic 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 Hyperic 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 Hyperic Agent on which the Hyperic Server will communicate 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 Hyperic 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 configure a Hyperic Agent to create a new token to use to authenticate with the server at startup. The agent reads this value only in the event that it cannot find connection configuration in its data directory. 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.

Default

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

agent.setup.unidirectional

Available only in vFabric Hyperic

Description

Enables the unidirectional communications between the Hyperic Agent and Hyperic Server in vFabric Hyperic. For more information, see Configure Unidirectional Agent - Server Communication.

Note that a for a unidirectional agent with a user-managed keystore, you must configure the keystore name in agent.properties. See agent.keystore.alias.

About unidirectional communication

If you configure an agent for unidirectional communication, all communication with the server is initiated by the agent. You can configure unidirectional communication at first agent startup, or with the agent.setup.unidirectional property in agent.properties. Related topics:

Default

Commented out, defaults to no.

agent.proxyHost

Description

The host name or IP address of the proxy server that the Hyperic Agent must connect to first when establishing a connection to the Hyperic Server. Supported in vFabric Hyperic only, for agents configured for unidirectional communication.

Use in conjunction with agent.proxyPort and agent.setup.unidirectional.

Default

none

agent.proxyPort

Description

The port number of the proxy server that the Hyperic Agent must connect to first when establishing a connection to the Hyperic Server. Supported in vFabric Hyperic only, for agents configured for unidirectional communication.

Use in conjunction with agent.proxyHost and agent.setup.unidirectional.

Default

none