List of environment variables

Use environment variables to control the behavior of the agent at run time.

Environment variables can be built into the agent by using the Environment Variables page. On Windows systems, environment variables are defined in the agent KXXENV file. On UNIX and Linux® systems, these variables can be defined in the agent $CANDLEHOME/config/XX.ini file, where XX is the two-character product code. The agent must be restarted for the new settings to take effect.

Note: Environment variables are not set correctly on a remote system that runs C Shell. Use a different shell if you want to use environment variables.

Table 1. Environment variable descriptions including their default values and valid value ranges
Environment variable	Default value	Valid values	Description
`CDP_DP_REFRESH_INTERVAL`	`60` if subnodes are defined, otherwise not set	Any positive integer (such as 3600 for a 1-hour interval)	The interval, in seconds, at which attribute groups are updated in the background. If this variable is not set or is set to 0, background updates are disabled. Use this variable to to tune behavior so that the data is fresh enough without causing undue load on the application from which data is being collected. If a thread pool is configured (see variable `CDP_DP_THREAD_POOL_SIZE`), then the attribute groups can be refreshed in parallel. If there is no thread pool, the updates happen serially, which can take a long time. Logically equivalent to a thread pool size of 1.
`CDP_ATTRIBUTE_GROUP_REFRESH_INTERVAL`	Not Applicable	Any positive integer (such as 600 for a 10-minute interval	Override the interval, in seconds, at which a particular attribute group is updated in the background when the agent is updating data in the background because `CDP_DP_REFRESH_INTERVAL` was set. This variable works in the same way as `CDP_DP_REFRESH_INTERVAL` except it targets only the specified attribute group. The attribute group name in the variable name must be in uppercase, even if the actual attribute group name is not. If the `CDP_DP_REFRESH_INTERVAL` environment variable has not been set, the attribute group override does not take effect. You can simulate background collection for a subset of attribute groups by using a large value for `CDP_DP_REFRESH_INTERVAL`, such as 86400 for once a day.
`CDP_DP_THREAD_POOL_SIZE`	`15` if subnodes are defined, otherwise not set	Any non-negative integer	The number of threads that are created to run background data collections at an interval that is defined by `CDP_DP_REFRESH_INTERVAL`. If this variable is not set or is set to 0, there is no thread pool. If `CDP_DP_THREAD_POOL_SIZE` is set to a value greater than 1 and `CDP_DP_REFRESH_INTERVAL` is set to 0, te value of `CDP_DP_THREAD_POOL_SIZE` is ignored and data collection happens on demand. The Thread Pool Status attribute group shows how the thread pool is running. Use the Thread Pool Status to adjust the thread pool size and refresh interval for best results. By default, the query for this attribute group is not displayed on the agent Navigator tree. You might not remember to include the query in a custom workspace for the agent. However, you can easily view it by assigning the Thread Pool Status query to a base agent level workspace view.
`CDP_DP_CACHE_TTL`	`55`	Any integer greater than or equal to 1.	Data that is collected for an attribute group is cached for this number of seconds. Multiple requests for the same data in this time interval receive a cached copy of the data. This value applies to all attribute groups in the agent.
`CDP_ATTRIBUTE_GROUP_CACHE_TTL`	Value of `CDP_DP_CACHE_TTL`	Any integer greater than or equal to 1.	Data that is collected for the particular specified attribute group is cached for this number of seconds. Multiple requests for the same data in this time interval receive a cached copy of the data. This value overrides `CDP_DP_CACHE_TTL` for the specified group. The attribute group name in the variable name must be in uppercase, even if the actual attribute group name is not.
`CDP_DP_IMPATIENT_COLLECTOR_TIMEOUT`	`5` if subnodes are defined, otherwise not set	Any positive integer	The number of seconds to wait for a data collection before a timeout and cached data is returned, even if the cached data is stale. (Cached data is stale if older than `CDP_DP_CACHE_TTL` seconds). If this variable is not set, the agent waits until the data collection completes. The wait at times can make the Tivoli® Enterprise Portal timeout and give up waiting. If no thread pool is configured, this variable is ignored and data collection is done synchronously.
`CDP_JDBC_MAX_ROWS`	`1000`	Any positive integer	The maximum number of rows of data that the JDBC data provider returns. A result set that contains more than this number of rows is processed only up to this maximum value. Queries can be developed to prevent too much data from being returned to IBM® Tivoli Monitoring.
`CDP_NT_EVENT_LOG_GET_ALL_ENTRIES_FIRST_TIME`	`NO`	YES, NO	If set to YES, the agent sends an event for every event in the Windows event log. If set to NO, only new events in the Windows event log are sent.
`CDP_NT_EVENT_LOG_CACHE_TIMEOUT`	`3600`	Any integer greater than or equal to 300.	The number of seconds Windows Event log events are cached by the agent. All cached events are returned when the event log attribute group is queried. Note: This variable is no longer used. Use the `CDP_PURE_EVENT_CACHE_SIZE` variable.
`CDP_PURE_EVENT_CACHE_SIZE`	`100`	Any positive integer greater than or equal to 1.	Maximum number of events to cache for a log file data source that is configured to process new records, for the Windows Event Log attribute group. And also for JMX monitors and notifications. Each new record in the log causes an event to be sent. This environment variable defines how many events are remembered in a cache by the agent. The cached values are returned when the attribute group is queried.
`CDP_DP_ACTION_TIMEOUT`	`20` seconds	Any positive integer greater than or equal to 1.	The number of seconds to wait for a Take Action that is being handled by the agent to complete.
`CDP_DP_SCRIPT_TIMEOUT`	`30` seconds	Any positive integer greater than or equal to 10.	The number of seconds to wait for the program started by a script-based attribute group to complete.
`CDP_DP_PING_TIMEOUT`	`30` seconds	Any positive integer greater than or equal to 10.	The number of seconds to wait for the program started by a command return code to complete. Note: This variable is not related to the ICMP ping data provider.
`CDP_SNMP_MAX_RETRIES`	`2`	Any positive integer	The number of times to try sending the SNMP request again. The total number of requests that are sent to the SNMP agent is this value plus one if no responses are received.
`CDP_SNMP_RESPONSE_TIMEOUT`	`2` seconds	Any positive integer	The number of seconds to wait for each SNMP request to timeout. Each row in an attribute group is a separate request. This timeout value is the number of seconds to wait for a response before you try again. The total timeout for a single row of data is (`CDP_SNMP_MAX_RETRIES` + 1) * `CDP_SNMP_RESPONSE_TIMEOUT`. The total default timeout value is (2+1) * 2 = 6 seconds.
`CDP_DP_HOSTNAME`	Name of the first installed network interface	An IP address or host name	Sets the preferred host name (network interface) on a multiple interface system. Use this environment variable if the agent binds its listening ports to a non-default network interface address. Used by the SNMP data provider. For Socket data sources, this variable applies if `CDP_DP_ALLOW_REMOTE` is also set.
`CDP_SNMP_ALLOW_DECREASING_OIDS`	`NO`	YES, NO	If set to YES, the SNMP data providers do not check whether returned OIDs are increasing. Set to YES with caution because the monitored agent might have problems that this check would normally catch.
`KUMP_DP_COPY_MODE_SAMPLE_INTERVAL`	`60`	Wait time in seconds	For a log file data provider, specifies how long to wait before it rereads the contents of a file when the agent is defined to Process all records when the file is sampled. The time is specified in seconds.
`KUMP_MAXPROCESS`	`100%`	5-100%	For a log file data provider, specifies the maximum processor usage to use to process file data. Values range from 5 to 100 percent. The default is 100 percent.
`KUMP_DP_SAMPLE_FACTOR`	`5`	Any non-negative integer	For a log file data provider, sets the sampling factor when you select Process all records when the file is sampled on the Agent Builder. This wait time ensures that patterns that span multiple records are written before scans are logged for the pattern.
`KUMP_DP_EVENT`	`5`	Any non-negative integer	For a log file data provider, sets the sampling frequency for Event data, in seconds.
`KUMP_DP_FILE_EXIST_WAIT`	`YES`	YES, NO	For a log file data provider, specifies that the file monitoring thread continues to run if it detects that the monitored file is absent or empty. The thread waits for the file to exist, rechecks every few seconds, and starts or restarts monitoring when the file becomes available.
`KUMP_DP_FILE_SWITCH_CHECK_INTERVAL`	`600`	Any non-negative integer	The frequency in seconds that the log file Data Provider searches for a different monitoring file to switch to when dynamic file name support is enabled.
`KUMP_DP_FILE_ROW_PAUSE_INCREMENT`	None	Any non-negative integer	For a log file data provider, specifies how many file records are read before the file monitoring thread pauses. The pause is so that previous updates can be processed. Use this environment variable only if the monitored file receives high-volume bursts of new records and you are concerned that some record updates might be lost.
`CDP_COLLECTION_TIMEOUT`	`60` seconds	Any positive integer	The number of seconds that the agent waits for a response from a data collector that was started in another process. JMX, JDBC, HTTP, and SOAP data collectors are examples.
`CDP_SSH_TEMP_DIRECTORY`	`.` (period)	Any valid path string on the remote system	For an SSH enabled Script data provider, specifies a location on the remote system. The script files that are provided with the agent are to be uploaded to this location. A relative lo\cation is relative to the user's home directory. The default of `.` (period) denotes the user's home directory.
`CDP_SSH_DEL_COMMAND`	`rm -Rf`	Any valid delete command string on the remote system	For an SSH enabled Script data provider, specifies the command to start to delete the uploaded script files that are provided with the agent.
`CDP_SNMP_SEND_DELAY_ FACTOR`	`0` milliseconds	Any positive integer	The initial SNMP send is delayed from 0 to the number of milliseconds specified. This variable is only enabled if the thread pool is also enabled. The delay does not apply to all sends, only to the first send made by an attribute group. This variable is useful if the device that is being monitored can sometimes fail to respond correctly if it receives multiple requests at the same time.
`CDP_ICMP_PING_REFRESH_INTERVAL`	`60` seconds	Any integer greater than or equal to 1	The systems in a device list file are pinged at this interval. If the pings use too much time, there is always a delay of at least `CDP_PING_MIN_INTERVAL_DELAY` seconds before the pings begin again. Data is refreshed no more frequently than this setting. Data can be refreshed less frequently based on the number of entries in the device list file and the time it takes to receive responses.
`CDP_ICMP_PING_MIN_INTERVAL_DELAY`	`30` seconds	Any integer greater than or equal to 1 and less than the `CDP` Ping refresh interval	After the devices in a device list file are pinged, the next ping refresh interval does not begin until at least this number of seconds elapses.
`CDP_ICMP_PING_BURST`	`10`	Any integer greater than or equal to 0	The number of pings that are sent before the agents pauses for the amount of time that is specified by the `CDP_ICMP_PING_BURST_DELAY` variable. A value of 0 disables this function.
`CDP_ICMP_PING_BURST_DELAY`	`10`	Any integer greater than or equal to 0	The amount of time in milliseconds to wait after a set number of pings are sent as defined by the `CDP_ICMP_PING_BURST` variable. A value of 0 disables this function.
`CDP_ICMP_PING_TIMEOUT`	`2000` milliseconds	Any integer greater than or equal to 1	The number of milliseconds to wait for a ping response. This setting applies to each ping attempt that is made. Ping attempts are made 3 times for each host. If no response is received from any of the 3 attempts, the total time waited for a reply is `CDP_ICMP_PING_TIMEOUT` multiplied by 3. By default, this value is 6000 milliseconds. Changing the value for `CDP_ICMP_PING_TIMEOUT` causes the default `TIMEOUT` enumeration for the Current Response Time attribute to no longer apply. Change the `TIMEOUT` enumeration to the new value of `CDP_ICMP_PING_TIMEOUT` multiplied by 3.
`CDP_JDBC_CONNECTIONLESS`	`false`	true, false	If set to true, JDBC connections are closed after each data collection attempt. That is, all attribute groups attempt to create their own connection each time data is collected. Connections are not reused if this variable is enabled. If set to false, one connection to the database is made and that connection is shared among the attribute groups.
`CDP_SSH_EXCLUDED_ ENVIRONMENT_VARIABLES`	None	A comma-separated list of environment variable names	For an SSH enabled Script data provider, specifies the set of local environment variables that must not be set in the environment of the remote system.
`CDP_DP_EVENT_LOG_MAX_BACKLOG_TIME`	`0` seconds	0, 1, or any integer greater than 1	If set to 0, and `CDP_DP_EVENT_LOG_MAX_BACKLOG_EVENTS` is not set to 1 or a greater integer, does not process events that are generated while the agent is shut down. 0 is the default. If set to 1, and `CDP_DP_EVENT_LOG_MAX_BACKLOG_EVENTS` is not set to an integer greater than 1, processes all events that are generated while the agent is shut down. If set greater than 1, and `CDP_DP_EVENT_LOG_MAX_BACKLOG_EVENTS` is not set greater than 1, processes events that are generated within that value in seconds of the current computer time. For example, if the value is set to 300, at startup, the agent processes all events that are generated within 300 seconds of the current time. Where a value greater than 1 is entered for both `CDP_DP_EVENT_LOG_MAX_BACKLOG _TIME` and `CDP_DP_EVENT_LOG_MAX _BACKLOG_EVENTS` variables, either that time interval of events or that number of events is processed. Which variable is chosen depends on which is matched first.
`CDP_DP_EVENT_LOG_ Windows_Event_Log_MAX_BACKLOG_TIME`	`0` seconds (Do not process missed events while the agent is shut down)	0, 1, or any integer greater than 1	If set to
`CDP_DP_EVENT_LOG_ MAX_BACKLOG_EVENTS`	`0` events	0, 1, or any integer greater than 1	If set to 0, and `CDP_DP_EVENT_LOG_MAX_BACKLOG _TIME` variable is not set to 1 or a greater integer, does not process events that are generated while the agent is shut down. 0 is the default. If set to 1, and the `CDP_DP_EVENT_LOG_MAX_BACKLOG _TIME` variable is not set to an integer greater than 1, processes all events that are generated while the agent is shut down. If set greater than 1, and `CDP_DP_EVENT_LOG_MAX_BACKLOG _TIME` is not set greater than 1, processes at most that number of events that are generated while the agent is shut down. For example, if the value is set to 200, then at startup of the agent the 200 events that generated directly before startup are processed. Where a value greater than 1 is entered for both `CDP_DP_EVENT_LOG_MAX_BACKLOG _EVENTS` and `CDP_DP_EVENT_LOG_MAX_BACKLOG _TIME`, either that number of events or that time interval of events is processed. Which variable is chosen depends on which is matched first.
`CDP_DP_EVENT_LOG_ Windows_Event_Log_MAX_BACKLOG_EVENTS`	`0` events (Do not process missed events while the agent is shut down)	0 or any integer greater than or equal to 1	If set to
`CDP_HTTP_READ_TIMEOUT`	`10`	Any positive integer	The number of seconds to wait for a reply to the HTTP request.
`CDP_JAT_THREAD_POOL_SIZE`	`15`	Any positive integer	The number of threads that are used by the Java™ providers for handling data collection requests. JMX, JDBC, HTTP, and SOAP data providers are the providers that can benefit from this thread pool.
`CDP_HTML_OBJECTS_THREAD_ POOL_SIZE`	`10`	Any positive integer	The number of threads that are used to download page objects that are found in URLs monitored with the HTTP data provider.
`CDP_HTTP_SOAP_MAX_ROWS`	`500`	Any positive integer	The maximum number of rows that are returned by the HTTP SOAP data provider.
`CDP_DP_ALLOW_REMOTE`	`NO`	`NO, YES`	If set to Yes, the agent allows remote socket connections. If set to No, the agent allows only socket connections from the local host. No is the default.
`CDP_DP_INITIAL_COLLECTION_ DELAY`	varies	Any positive integer	The number of seconds, after the agent starts, until the thread pool begins its scheduled data collections.