Environment variables

These environment variables control the behavior of the agent at runtime. They can be built into the agent using the Environment Variables page, for more see Environment variables. 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. XX is the two-letter 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 running C Shell. Use an alternative shell if you need to make use of environment variables.

Table 45. Environment variables
Environment variable	Default value	Valid values	Description
CDP_ATTRIBUTE_GROUP _REFRESH_INTERVAL	Not Applicable	Any non-negative integer	The interval in seconds at which a particular specified attribute group is updated in the background. 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 upper case, even if the actual attribute group name is not.
CDP_DP_CACHE_TTL	60	Any integer greater than or equal to 1.	Data 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. (You cannot set different values for each attribute group.)
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 to happen before timing out and returning cached data, even if the cached data is stale (older than CDP_DP_CACHE_TTL seconds). If this variable is not set, the agent waits as long as the data collection takes, which at times can make the Tivoli Enterprise Portal time out and give up on it. If no thread pool is configured, this variable is ignored and data collection is performed synchronously.
CDP_DP_REFRESH_INTERVAL	60 if subnodes are defined, otherwise not set	Any non-negative integer	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. 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. This is logically equivalent to a thread pool size of 1.
CDP_DP_THREAD_POOL_SIZE	15 if subnodes are defined, otherwise not set	Any non-negative integer	The number of threads created to perform background data collections at an interval defined by CDP_DP_REFRESH_INTERVAL. If this variable is not set or is set to 0, there is no thread pool. The Thread Pool Status attribute group shows how it is performing, and helps you 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. If you have not included it in a custom workspace for the agent, you can easily view it by assigning the Thread Pool Status query to a base agent level workspace view.
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.	The 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 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 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 launched 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 launched 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 retry sending the SNMP request. The total number of requests 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 time out. Each row in an attribute group is a separate request. Each request can be retried based on the value defined by CDP_SNMP_MAX_RETRIES. This timeout value is the number of seconds for which a response is waited before a retry is attempted. 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 hostname	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. This is used by the SNMP data provider.
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_SAMPLE_FACTOR	5	Any non-negative integer	For a Log File data provider, sets the sampling factor when the Process all records when the file is sampled option is selected on the Agent Builder. This wait time ensures that patterns that span multiple records are completely written before logging scans 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	Specifies 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 being used.
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 briefly to allow the previous updates to be processed. Use this environment variable only if the monitored file receives high-volume bursts of new records and there is a concern 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 launched 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 the location on the remote system to which to upload the script files provided with the agent. A relative location is relative to the user's home directory. The default of . (period) refers to the user's home directory itself.
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 invoked to delete the uploaded script files 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 being monitored has trouble responding when multiple requests are received at once.
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 consume too much time, there is always a delay of at least CDP_PING_MIN_INTERVAL_DELAY seconds before beginning the pings again. Data is refreshed no more frequently than this setting, but 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 pinging the devices in a device list file, 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 will be sent before pausing for the amount of time 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 sending a set number of pings 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. Three ping attempts are made 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. You should 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 should 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 the CDP_DP_EVENT_LOG_MAX_BACKLOG_ EVENTS variable has not been set to 1 or any integer greater than 1, does not process events generated while the agent is shutdown. 0 is the default. If set to 1, and the CDP_DP_EVENT_LOG_MAX_BACKLOG _EVENTS variable has not been set to an integer greater than 1, processes all events generated while the agent is shutdown. If set to a value greater than 1, and the CDP_DP_EVENT_LOG_MAX_BACKLOG _EVENTS variable has not been set to an integer greater than 1, processes events 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 generated within 300 seconds of the current computer time. Where a value greater than 1 is entered for both the CDP_DP_EVENT_LOG_MAX_BACKLOG_ TIME and the CDP_DP_EVENT_LOG_MAX_BACKLOG_ EVENTS variables, either that time interval of events or that number of events is processed, depending on which is matched first.
CDP_DP_EVENT_LOG_MAX_ BACKLOG_EVENTS	0 events	0, 1, or any integer greater than 1	If set to 0, and the CDP_DP_EVENT_LOG_MAX_BACKLOG_ TIME variable has not been set to 1 or any integer greater than 1, does not process events generated while the agent is shutdown. 0 is the default. If set to 1, and the CDP_DP_EVENT_LOG_MAX_BACKLOG _TIME variable has not been set to an integer greater than 1, processes all events generated while the agent is shutdown. If set to a value greater than 1, and the CDP_DP_EVENT_LOG_MAX_BACKLOG _TIME variable has not been set to an integer greater than 1, processes a maximum of that number of events generated while the agent is shutdown. For example, if the value is set to 200, then at startup of the agent the 200 events generated directly before startup are processed. Where a value greater than 1 is entered for both the CDP_DP_EVENT_LOG_MAX_BACKLOG_ EVENTS and CDP_DP_EVENT_LOG_MAX_BACKLOG_ TIME variables, either that number of events or that time interval of events is processed, depending on which is matched first.
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 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.