Agent Properties

The properties supported in the agent.properties file are defined below. Note that not all supported properties appear in the default agent.properties file. To use a property that is not defined in agent.properties, you must add it explicitly.

For more information, see Understanding Agent Configuration.

Looking for a property that is not listed on this page? If your agent.properties file contains a property not listed here, please add a comment to this page. One explanation, although uncommon, is the use of special agent properties to override the descriptor-defined value for a <property> for resource instances on a particular platform. Such properties have names that reflect a resource type attribute and value. See Overriding the Value of a Resource property at Platform Level.

agent.eventReportBatchSize

Description

The maximum number of events that an HQ Agent will send per contact with the HQ Server.

When the agent detects an event, it puts it in a queue of events to report to the server. As long as there are events in the queue, the agent continuously creates and sends batches of events to the HQ Server. The agent.eventReportBatchSize sets the (maximum) number of events the agent will put in a batch.

What's an Event? Events that the HQ Agent can track include: log messages — Log messages are tracked for a resource if log tracking is configured for the resource on its Configuration Properties page. configuration file changes — Changes to configuration files for a resource are tracked if configuration tracking is configured for the resource on its Configuration Properties page. resource control actions — control actions performed (on resources that support control actions) are automatically tracked. alerts — Alerts fired on any resource are automatically tracked.

About Metric Batch Size You can also configure the maximum number of metrics that the agent will send per contact with the HQ Server, with the Agent.maxBatchSize property

Default

As installed, agent.properties does not contain a line that defines the value of this property. The default behavior of the agent is to send a maximum of 100 events per contact with the server.

agent.listenIp

Description

The IP address to which the agent binds at startup. The default value allows the agent to listen on all IP addresses on the the agent host.

Default

As installed, agent.properties does not contain a line that defines the value of this property. The default behavior of the agent is to listen on all IP addresses on its host. This behavior is equivalent to to setting this property to an asterisk, like this:

*

agent.listenPort

Description

The port on the agent's listen address to which the agent binds at startup.

Default

As installed, agent.properties does not contain a line that defines the value of this property. The default behavior of the agent is to listen on port 2144.

agent.logDir

Description

You can add this property to the agent.properties file to specify the directory where the HQ Agent will write its log file. Unless you specify a fully qualified path, agent.logDir is evaluated relative to the agent installation directory.

This property does not exist in agent.properties unless you explicitly add it.  To change the location for the agent log file, add agent.logDir  to agent.properties and enter a path relative to the agent installation directory, or if desired, a fully qualified path.

Note that the name of the agent log file is configured with the agent.logFile property.

Default

agent.logDir does not exist in agent.properties unless you explicitly add it.  The default behavior is equivalent to this setting:

agent.logDir=log

resulting in the agent log file being written to the AgentHome/log directory.

agent.logFile

Description

Specifies the path and name of the agent log file.

Default

Note that in agent.properties, the default setting for agent.LogFile is made up of a variable and a string.

agent.logFile=${agent.logDir}\agent.log

• agent.logDir is a variable - it supplies the value of an identically named agent property. By default, the value of agent.logDir is log, interpreted relative to the agent installation directory.

• agent.log is the name for the agent log file.

So, by default, the agent log file is named agent.log, and is written to the AgentHome/log directory.

If you want the agent to the log to a different directory, you must explicitly add the agent.logDir property to agent.properties.

agent.logLevel

Description
Specifies the level of detail of the messages the Agent writes to the log file. Allowable values are: INFO and DEBUG.
Default
INFO

agent.logLevel.SystemErr

Description

Redirects System.err to agent.log. Commenting out this setting will cause System.err to be directed to agent.log.startup.

Default

ERROR

agent.logLevel.SystemOut

Description

Redirects System.out to agent.log. Commenting out this setting will cause System.out to be directed to agent.log.startup.

Default

INFO

agent.maxBatchSize

Description

The maximum number of metrics that the HQ Agent will send per contact with the HQ Server.

An HQ Agent puts the metrics it collects into a queue of metrics to report to the server. As long as there are metrics in the queue, the agent continuously creates and sends batches of metrics to the HQ Server. The agent.maxBatchSize property sets the (maximum) number of metrics the agent will put in a batch.

About Event Batch Size You can also configure the maximum number of events that the agent will send per contact with the HQ Server, with the Agent.eventReportBatchSize property

Default

As installed, agent.properties does not contain a line that defines the value of this property. The default behavior of the agent is to send a maximum of 500 metrics per contact with the server.

agent.proxyHost

Description

The host name or IP address of the proxy server that the agent must connect to first when establishing a connection to the HQ server.

Default

none

agent.proxyPort

Description

The port number of the proxy server that the agent must connect to first when establishing a connection to the HQ server.

Default

none

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

agent.startupTimeOut

Description

The number of seconds that the agent startup script will wait before determining that the agent did not startup successfully. If the agent is not determined to be listening for requests within this period of time, an error is logged, and the startup script times out.

Default

As installed, agent.properties does not contain a line that defines the value of this property. The default behavior of the agent is to timeout after 300 seconds.

agent.storageProvider.info

Description

Configuration for data storage on the Agent side

Default

As installed, agent.properties does not contain a line that defines the value of this property. The default setting of the agent is

agent.storageProvider.info=$\{agent.dataDir\}|m|100|20|50

Which means, use the data directory to store the disklists, max size 100MB. The 20 and 50 numbers are used for purging data; check to see if the list can be shortened when the size is greater than 20MB and the list is 50% empty

autoinventory.defaultScan.interval.millis

Description

Specifies how frequently the agent performs a default autoinventory scan.

The default scan detects servers and platform services, typically using the process table or the Windows registry. Default scans are less resource-intensive than runtime scans.

Default

Commented out, set to 86,400,000 milliseconds, or 1 day

autoinventory.runtimeScan.interval.millis

Description

Specifies how frequently the agent performs a runtime scan.

A runtime scans may use more resource-intensive methods to detect services than a default scan. For instance, a runtime scan may involve issuing an SQL query or looking up an MBean.

Default

86,400,000 milliseconds, or 1 day

http.useragent

Describes HQ 4.3 feature

Description

The http.useragent property defines the value for the User-Agent request header in HTTP requests issued by the HQ Agent. By default, the User-Agent in agent requests includes  the HQ Agent version - and so change upon agent upgrade. If a target HTTP server is configured to block requests with an unknown User-Agent, agent requests will fail after agent upgrade.

You can use http.useragent to define a User-Agent value that will be consistent across upgrades.

Note: agent.properties does not contain this property by default. You must explicitly add it to the file.

Default

Hyperic-HQ-Agent/Version

For example:

Hyperic-HQ-Agent/4.1.2-EE

jboss.installpath

Description

To enable the agent to monitor JBoss, specify the location of the JBoss root directory.

Default

/usr/local/jboss-4.0.0

log4j Properties

log4j.rootLogger=${agent.logLevel}, R
log4j.appender.R.File=${agent.logFile}
log4j.appender.R.MaxBackupIndex=1
log4j.appender.R.MaxFileSize=5000KB
log4j.appender.R.layout.ConversionPattern=%d %-5p [%t] [%c{1}] %m%n
log4j.appender.R.layout=org.apache.log4j.PatternLayout
log4j.appender.R=org.apache.log4j.RollingFileAppender
##
## Disable overly verbose logging
##
log4j.logger.httpclient.wire=ERROR
log4j.logger.org.apache.commons.httpclient=WARN
log4j.logger.org.hyperic.hq.measurement.agent.server.SenderThread=INFO
log4j.logger.org.hyperic.hq.agent.server.AgentDListProvider=INFO
log4j.logger.org.hyperic.hq.agent.server.MeasurementSchedule=INFO
log4j.logger.org.hyperic.hq.measurement.agent.server.ScheduleThreadTrace=INFO
log4j.logger.org.hyperic.util.schedule.ScheduleTrace=INFO
##
## Only log errors from naming context
##
log4j.category.org.jnp.interfaces.NamingContext=ERROR
log4j.category.org.apache.axis=ERROR

platform.log_track.eventfmt

Describes HQ 4.3 feature

Description

Specifies the content and format of the Windows event attributes that an HQ Agent includes when logging a Windows event as an event in HQ. agent.properties does not contain the platform.log_track.eventfmt property, you must explicitly add it if you want to tailor the data logged for Windows events.

Default Behavior

When Windows log tracking is enabled, an entry of this form is logged for events that match the criteria you specified on the resource's Configuration Properties page:

[Timestamp] Log Message (EventLogName):EventLogName:EventAttributes

where:

• Timestamp - is when the event occurred
• Log Message - is an text string
• EventLogName - is the Windows event log type, "System", "Security", or "Application".
• EventAttributes - a colon delimited string made of the Windows event Source and Message attributes.

For example, this log entry: 

 04/19/2010 06:06 AM Log Message (SYSTEM): SYSTEM: Print: Printer HP LaserJet 6P was paused.

is for an Windows event written to the Windows System event log at 6:06 AM on 04/19/2010. The Windows event Source and Message attributes, are "Print" and "Printer HP LaserJet 6P was paused.", respectively.

Configuration

In HQ 4.3 and later, you can use the parameters below to configure the Windows event attributes that the agent writes for a Windows event. Each parameter maps to Windows event attribute of the same name.

• %user% - The name of the user on whose behalf the event occurred.
• %computer% - The name of the computer on which the event occurred.
• %source% - The software that logged the Windows event.
• %event% - A number identifying the particular event type.
• %message% - The event message.
• %category% - An application-specific value used for grouping events.

For example, with this property setting:

platform.log_track.eventfmt=%user%@%computer% %source%:%event%:%message%

the HQ Agent will write the following data when logging Windows event:

This entry is for as for an Windows event written to the Windows System event log at 6:06 AM on 04/19/2010. The software associated with the event was running as "HP_Administrator" on the host "Office". The Windows event's Source, Event, and Message attributes, are "Print", "7", and "Printer HP LaserJet 6P was paused.", respectively.

After you configure the content of the log entry written for a Windows event, when you configure an alert definition for a Windows resource, you can create an alert condition based on the message content, including the custom fields you have configured. For more information, see Define Alert Condition Set.

plugins.exclude

Description

Use this property to specify plugins that you do not wish the HQ Agent to load at startup. This is useful for reducing the agents memory footprint.

Usage

Supply a comma-separated list of plugins to exclude, for example:

{{plugins.exclude=jboss,apache,mysql}}

plugins.include

Description

Use this property to specify plugins that you do wish the HQ Agent to load at startup. This is useful for reducing the agents memory footprint.

Usage

Supply a comma-separated list of plugins to include, for example:

plugins.include=weblogic,apache

sigar.mirror.procnet

Description

mirror /proc/net/tcp on linux

Default

true

snmpTrapReceiver.listenAddress

Description
Use this property to specify the port on which the HQ Agent listens for SNMP traps. By default, the agent is not configured to listen for SNMP traps. You must add this property to agent.properties to enable the agent to receive traps.

Typically SNMP uses the UDP port 162 for trap messages. This port is in the privileged range, so an agent listening for trap messages on it must run as root (or as an Administrative user on Windows).

If you prefer to run the the agent under the context of a non-administrative user, you can configure it to listen for trap messages on an unprivileged port.

Usage
Specify an IP address (or 0.0.0.0 to specify all interfaces on the platform) and the port for UDP communications in this format:

snmpTrapReceiver.listenAddress=udp:IP_address/port

To enable the HQ Agent to receive SNMP traps on an unprivileged port, specify port 1024 or above. The following setting allows the agent to receive traps on any interface on the platform, on UDP port 1620.

snmpTrapReceiver.listenAddress=udp:0.0.0.0/1620

weblogic.auth.method

View Source

Describes HQ 4.3 feature

Description

weblogic.auth.method is one of four properties you define to enable an HQ Agent to communicate with a WebLogic Administration Server using Two-Way-SSL.

Add the following line to the agent.properties file to specify that the agent will use Two-Way-SSL for communications with the Administration Server.

weblogic.auth.method=ssl2ways

Default

None.

Agent Properties for Two-Way-SSL with WLS Admin Server In Two-Way SSL, each side presents an SSL certificate to the other - the client must trust the server cert and the server must trust the client cert. The process is: HQ Agent initiates a connection with the Administration Server. The Administration server presents its certificate and asks the HQ Agent for its certificate. The HQ Agent presents its certificate (client2certs.pem), using the private key (clientkey.pem and clientkey) to encrypt the communication. To enable the HQ Agent to use Two-Way-SSL with a Weblogic Administration Server, you specify the client cert the HQ Agent presents to the Administration Server by adding these properties to agent.properties. weblogic.auth.method=ssl2ways weblogic.ssl2ways.key=ClientKey.pem (client private key) weblogic.ssl2ways.key.pass=ClientKey (passphrase for client private key) weblogic.ssl2ways.cert=Client2Certs.pem (client certificate) Weblogic docs: Using Two-Way SSL Authentication

weblogic.installpath

Description

To enable the agent to monitor WebLogic 8.1, specify the location server/lib/weblogic.jar

Default

/usr/local/bea/weblogic-8.1

weblogic.ssl2ways.cert

Describes HQ 4.3 feature

Description

weblogic.ssl2ways.cert is one of four properties you define to enable an HQ Agent to communicate with a WebLogic Administration Server using Two-Way-SSL.

Add weblogic.ssl2ways.cert to the agent.properties file and set its value to the location of the client certificate that the HQ Agent will present to the Administration Server:

weblogic.ssl2ways.cert=Client2Cert.pem

where Client2Cert.pem is the path to the client certificate the HQ Agent presents to the Administration Server it manages.

Default

None.

Agent Properties for Two-Way-SSL with WLS Admin Server In Two-Way SSL, each side presents an SSL certificate to the other - the client must trust the server cert and the server must trust the client cert. The process is: HQ Agent initiates a connection with the Administration Server. The Administration server presents its certificate and asks the HQ Agent for its certificate. The HQ Agent presents its certificate (client2certs.pem), using the private key (clientkey.pem and clientkey) to encrypt the communication. To enable the HQ Agent to use Two-Way-SSL with a Weblogic Administration Server, you specify the client cert the HQ Agent presents to the Administration Server by adding these properties to agent.properties. weblogic.auth.method=ssl2ways weblogic.ssl2ways.key=ClientKey.pem (client private key) weblogic.ssl2ways.key.pass=ClientKey (passphrase for client private key) weblogic.ssl2ways.cert=Client2Certs.pem (client certificate) Weblogic docs: Using Two-Way SSL Authentication

weblogic.ssl2ways.key

Describes HQ 4.3 feature

Description

weblogic.ssl2ways.key is one of four properties you define to enable an HQ Agent to communicate with a WebLogic Administration Server using Two-Way-SSL.

weblogic.ssl2ways.key to the agent.properties file and set its value to the location of client's private key:

weblogic.ssl2ways.key=clientKey.pem

where:

clientkey.pem is the path to the private key the HQ Agent presents to the Administration Server that the agent manages.

Default

None.

Agent Properties for Two-Way-SSL with WLS Admin Server In Two-Way SSL, each side presents an SSL certificate to the other - the client must trust the server cert and the server must trust the client cert. The process is: HQ Agent initiates a connection with the Administration Server. The Administration server presents its certificate and asks the HQ Agent for its certificate. The HQ Agent presents its certificate (client2certs.pem), using the private key (clientkey.pem and clientkey) to encrypt the communication. To enable the HQ Agent to use Two-Way-SSL with a Weblogic Administration Server, you specify the client cert the HQ Agent presents to the Administration Server by adding these properties to agent.properties. weblogic.auth.method=ssl2ways weblogic.ssl2ways.key=ClientKey.pem (client private key) weblogic.ssl2ways.key.pass=ClientKey (passphrase for client private key) weblogic.ssl2ways.cert=Client2Certs.pem (client certificate) Weblogic docs: Using Two-Way SSL Authentication

weblogic.ssl2ways.key.pass

Describes HQ 4.3 feature

Description

weblogic.ssl2ways.key.pass is one of four properties you define to enable an HQ Agent to communicate with a WebLogic Administration Server using Two-Way-SSL.

Add weblogic.ssl2ways.key.pass to the agent.properties file and set its value to the passphrase for the client private key:

weblogic.ssl2ways.key.pass=ClientKey

where ClientKey is the passphrase for the client private key.

Default

None.

Agent Properties for Two-Way-SSL with WLS Admin Server In Two-Way SSL, each side presents an SSL certificate to the other - the client must trust the server cert and the server must trust the client cert. The process is: HQ Agent initiates a connection with the Administration Server. The Administration server presents its certificate and asks the HQ Agent for its certificate. The HQ Agent presents its certificate (client2certs.pem), using the private key (clientkey.pem and clientkey) to encrypt the communication. To enable the HQ Agent to use Two-Way-SSL with a Weblogic Administration Server, you specify the client cert the HQ Agent presents to the Administration Server by adding these properties to agent.properties. weblogic.auth.method=ssl2ways weblogic.ssl2ways.key=ClientKey.pem (client private key) weblogic.ssl2ways.key.pass=ClientKey (passphrase for client private key) weblogic.ssl2ways.cert=Client2Certs.pem (client certificate) Weblogic docs: Using Two-Way SSL Authentication

websphere.installpath

Description

To enable the agent to monitor WebSphere, specify the location of the WebSphere jars.

Default

/opt/WebSphere/AppServer

websphere.useext

Description

This property is required to enable management of WebSphere 6.0 and 6.1.

Do not define the websphere.useext property to monitor WebSphere 7.

Usage

Add the following property definition to the agent.properties file for an an HQ Agent that will manage WebSphere 6.0 or 6.1.

websphere.useext=true