The table in this section lists the common agent environment variables that are used by all IBM Tivoli Monitoring agents.
| Variable | Purpose |
|---|---|
| CMS_MSGBASE | Applies only to the IBM® i platform. Specifies the MSG2 message file for agent framework messages. |
| CT_CMSDIRECT | Obsolete. Replaced by IBM Tivoli Monitoring V6 firewall communications services. Specify the full NAT firewall address of the monitoring server to connect to, including protocol:address[port#]. |
| CT_CMSLIST | Required variable that specifies the primary or secondary Tivoli Enterprise Monitoring Server the agent must connect with. Takes a list of monitoring server names in the form network_protocol:hostname or network_protocol:address and delimited by semicolons. |
| CTIRA_CELL_NAME | Obsolete. Replaced by the CT_CMSLIST agent configuration variable. |
| CTIRA_HEARTBEAT | The interval, in minutes, of the agent-to-monitoring server heartbeat data sample. The default value is 10 minutes. Shorter heartbeat intervals increase network traffic between the agent and the Tivoli Enterprise Monitoring Server. |
| CTIRA_HIST_DIR | Required variable that specifies the directory where agent-based short-term history data files are stored. Does not apply to the Tivoli Enterprise Monitoring Server's short-term history data files. The directory must already exist. |
| CTIRA_HOSTNAME | Used by many, but not all, agents to provide an alternate host name qualifier (subsystem:hostname:nodetype) for the published agent managed system name. Used to remove a long network domain name (such as acme.us.com) from the default agent hostname. Not honored by all agents. For some agents, CTIRA_HOSTNAME might cause unpredictable results in the Tivoli Enterprise Portal navigation tree. |
| CTIRA_IP_PORT | Applies to z/OS® agents only. Do not modify. Set this variable to 0 so the operating system can provide the agent RPC listen port, which prevents a port conflict for some z/OS configurations. |
| CTIRA_LOG_PATH | Required variable that specifies the directory where the agent's Operations Log file is stored. The file names themselves use the suffixes .LG0 and .LG1. This variable does not apply to agents running on a z/OS system. |
CTIRA_MAX_RECONNECT_ |
Obsolete. Number of consecutive unsuccessful attempts the agent makes to connect to a Tivoli Enterprise Monitoring Server before giving up and exiting. The default value of 0 means that the agent remains started regardless of its connection status with the monitoring server. |
| CTIRA_NCSLISTEN | Number of RPC listen server threads to create for the agent. The default value is 10. |
| CTIRA_NODETYPE | Supplies the agent node type qualifier (subsystem:hostname:nodetype) of the agent managed system name (msn). Provide the agent product indicator in this name. This value is set by the application and should not be set by the user. |
| CTIRA_OS_INFO | Overrides the default value for agent entries in the Tivoli Enterprise Monitoring Server's “ManagedSystem.Host_Info” column. This variable is used to build the navigation tree for the Tivoli® Enterprise Portal Server. The value must match an existing entry in the CNPS/osnames file. This variable is not applicable to subnode type records in the monitoring server's ManagedSystem table. |
CTIRA_PRIMARY_FALLBACK_ |
Forces the agent to switch from the primary Tivoli Enterprise Monitoring Server to one of the defined secondary monitoring servers, because the primary monitoring server is offline or due to network connectivity issues. You want the agent to switch back to the primary monitoring server as soon as possible when it becomes available. This parameter controls the frequency with which the agent performs a lookup of the primary monitoring server. If the primary monitoring server is found, the agent disconnects from the secondary monitoring server and reconnects to the primary monitoring server. A value of zero disables this feature. The minimum value must be 2.5 times CTIRA_RECONNECT_WAIT value. The default value is 4500 seconds, or 75 minutes. |
| CTIRA_PRODUCT_SEP | Supplies an alternate qualifier for the agent's managed system name (msn). The default value is a colon (:). |
| CTIRA_RECONNECT_WAIT | Time interval, in seconds, that the agent waits between attempts to register with a Tivoli Enterprise Monitoring Server. The default value is 600 seconds. |
| CTIRA_REFLEX_ATOMIC | For subnode targets only. Evaluates the situation state by any existing specified display item column name when deciding which reflex situation automation command the agent should execute. Not applicable to reflex situation commands executed or evaluated by the Tivoli Enterprise Monitoring Server. Disable by setting to N. The default value is Y. |
| CTIRA_REFLEX_TARGET | For subnode targets only. Evaluates situation state by subnode name value in the ORIGINNODE column when deciding which reflex situation automation command the agent should execute. Not applicable to reflex situation commands executed or evaluated by the Tivoli Enterprise Monitoring Server. Disable by setting to N. The default value is Y. |
| CTIRA_SIT_CLEAN | Number of seconds between garbage cleanup of stale entries in the agent persistent situation file. The default value is 900 seconds. |
| CTIRA_SIT_FILE | Specifies an alternate name for the default agent-based persistent situation file. This variable should be used only in exceptional conditions because the file name reflects the agent’s managed system name. Unsupported for z/OS-based agents. |
| CTIRA_SIT_MGR | Specifies whether or not to use the agent's persistent situation file when registering with the Tivoli Enterprise Monitoring Server. Using this file improves performance of the monitoring server. Set this variable to N to disable usage. For a z/OS agent, the value must be N, because this feature is not implemented for a z/OS-based monitoring server. For all other platforms, the default value is Y. |
| CTIRA_SIT_PATH | Required variable that specifies the directory where the agent-based persistent situation file is stored. This agent-only file contains a copy of the Tivoli Enterprise Monitoring Server monitoring situations for the agent's use while registering with the monitoring server. The file is named psit_msn.str, where msn is the managed system name of the agent process. Unsupported for z/OS-based agents. |
| CTIRA_SUBSYSTEM_ID | Optional variable that overrides the subsystem ID qualifier (subsystem:hostname:nodetype) of the agent managed system name (msn). Describes a monitored resource instance to help make this name unique. Value may also be set by the agent itself. |
| CTIRA_SYSTEM_NAME | Sets an alternate system name for agent entries in the Tivoli Enterprise Monitoring Server's ManagedSystem.Host_Address column within the <NM>mysystem</NM> tags. Used to build the Tivoli Enterprise Portal Server's navigation tree. Not applicable to subnode type records in the monitoring server's ManagedSystem table. The maximum allowable length of the value used for this variable is 31 characters. |
| CTIRA_THRESHOLDS | Specifies the fully qualified name of the XML-based adaptive (dynamic) threshold override file. The default file is located in $CANDLE_HOME/localconfig/pc/pc_thresholds.xml, where pc is the agent product code. On z/OS systems, the default file name is pc THRES. |
IRA_ADAPTIVE_THRESHOLD_ |
Specifies the adaptive (dynamic) threshold operation
mode, either CENTRAL or LOCAL.
In CENTRAL mode, threshold overrides are
centrally created and distributed to the agent. Do not modify the
override XML file, which is the default mode. In LOCAL mode, central distribution to the agent is inhibited, and threshold overrides are locally created and managed. Use LOCAL mode to specify that the agent should ignore enterprise distribution; its affinity will not be registered, so the Tivoli Enterprise Portal cannot override the agent's managed system node. Use this mode cautiously because it causes the Tivoli Enterprise Monitoring Server's thresholds and the agent's thresholds to be out of sync. You must create and manually write override definitions in the same file that is created in CENTRAL mode: managed-system-name_product-code_thresholds.xml. For instance, on Windows, this file is named Primary_myagent_NT_thresholds.xml; on Linux, myagent_LZ_thresholds.xml; on UNIX, myagent_UX_thresholds.xml. On Windows, the file is stored in the %CANDLEHOME%\TMAITM6 directory; on Linux and UNIX, the file is stored in $CANDLEHOME/interp/product-code/bin. The names of the columns to be used when specifying overrides is taken from the attributes file. The override name and objectId must be unique in the XML file. Timestamp is not required. If later you switch back from LOCAL mode to CENTRAL mode, centrally located overrides will again override the local definitions. |
| IRA_AUTONOMOUS_LIMIT | Sets the saved event limit for autonomous operation. If the specified value is a number (for example, 500), then it is the maximum number of situation event records to be saved by the agent. If the specification is in common disk space units such as KB, MB, or GB (for example, 5 MB), then it is the total amount of disk space to be used by the agent for saving situation event data. The default value is 2 MB. |
| IRA_AUTONOMOUS_MODE | Turns on (YES) or off (NO) agent autonomous mode. While in autonomous mode, the agent continues to run Enterprise situations. The situation event data persists on disk even after agent restart. On reconnection to the Tivoli Enterprise Monitoring Server, the agent uploads saved situation event data to the monitoring server. The default value is Y. |
| IRA_DEBUG_AUTONOMOUS | Turns on (Y) or off (N) debug trace for agent autonomous operation. This variable is used for diagnosing problems in this area. The default value is N. |
| IRA_DEBUG_EVENTEXPORT | Turns on (Y) or off (N) agent event export operations, such as SNMP trap and debug trace. The default value is N. |
IRA_DEBUG_PRIVATE_ |
Turns on (Y) or off (N) debug trace when processing the private situations of an agent. The default value is N. |
| IRA_DEBUG_SERVICEAPI | Turns on (Y) or off (N) debug trace for agent service interface processing. The default value is N. |
| IRA_DEBUG_TRANSCON | Turns on (Y) or off (N) debug trace for agent transport conduit processing. This variable is used for diagnosing problems in this area. The default value is N. |
| IRA_DEBUG_EIF | Turns on (Y) or off (N) debug trace for the EIF event emitting feature in this agent. |
| IRA_DUMP_DATA | Used by both agents and the Tivoli Enterprise Monitoring Server for debugging. Set to Y to do a hexadecimal dump of RPC transaction content data contents into the RAS1 log. The default value is N. Can produce voluminous RAS1 message output if enabled. |
IRA_EVENT_EXPORT_ |
Specifies the frequency with which the agent checks and calculates the autonomous operation saved event usage limit that is defined by the IRA_AUTONOMOUS_LIMIT parameter. The default value is 90 seconds; the agent enforces the minimum setting of 30 seconds. |
| IRA_EIF_ENABLE_LOG | Enables logging of EIF events sent for private situations directly from the Tivoli Enterprise Monitoring Agent to the agent's *.LG0 operational log if set to "Y". |
| IRA_EVENT_EXPORT_EIF | Enables (Y) or disables (N) the EIF event emitting feature for any private situations configured for this agent. |
IRA_EVENT_EXPORT_ |
Defines the frequency with which the agent outputs collected situation statistics to the debug trace log. The default value is 900 seconds, or 15 minutes. |
IRA_EVENT_EXPORT_ |
Enables (Y) or disables (N) periodic output of situation operation statistics data to the trace log. The default is N. |
IRA_EVENT_EXPORT_ |
Enables (Y) or disables (N) basic situation operation statistics data collection. The basic situation data includes situation first start time, situation first event time, situation last start time, situation last stop time, situation last true event time, situation last false event time, number of times situation recycles, number of times situation enters autonomous operation. The default value is Y. |
IRA_EVENT_EXPORT_SIT_ |
Enables (Y) or disables (N) details situation operation statistics data collection. The detail data collected includes 8 days' situation operation profile such as hourly true event count, hourly false event count, hourly data row count, hourly true event ratio, and hourly false event ratio. The default value is N. |
IRA_EVENT_EXPORT_ |
Enables (Y) or disables (N) the SNMP trap emitter capability. When enabled, the SNMP trap configuration file is required and must exist for the agent to emit SNMP V1, V2, or V3 trap to configured SNMP trap managers. The default value is Y. |
IRA_EVENT_EXPORT_ |
Specifies the fully qualified SNMP trap configuration file name. The default file is located in $CANDLE_HOME/localconfig/pc/pc_trapcnfg.xml (member pcTRAPS on z/OS systems), where pc is the agent product code. |
| IRA_LOCALCONFIG_DIR | Specifies the local configuration directory path that contains locally customized configuration files such as threshold overrides, private situations, and SNMP trap configuration file. The default directory is the localconfig subdirectory of the directory specified by the CANDLE_HOME environment variable, which is the RKANDATV DD name on z/OS systems. |
IRA_PRIVATE_SITUATION_ |
Specifies the fully qualified autonomous Private Situation configuration file name. The default file on distributed systems is located in $CANDLE_HOME/localconfig/pc/pc_situations.xml, where pc is the agent product code. The default file on z/OS systems is the SICNFG member in the RKANDATV data set. |
IRA_SERVICE_INTERFACE_ |
Instructs the agent to open the named product-specific
HTML page instead of the default navigator.htm page
when logging on to the agent service interface. By default, the agent
looks for the product-specific file in CANDLE_HOME/localconfig on
distributed systems and the RKANDATV dataset on z/OS systems. However, if the IRA_SERVICE_INTERFACE_DIR environment
variable has been set, the agent looks in the directory specified
by that environment variable. If you set IRA_SERVICE_INTERFACE_DEFAULT_PAGE (but not IRA_SERVICE_INTERFACE_DIR), you should put any product-specific HTML pages in the CANDLE_HOME/localconfig/html directory on distributed systems. Therefore, if you create myPage.htm and put it in CANDLE_HOME/localconfig/html set IRA_SERVICE_INTERFACE_DEFAULT_PAGE=/html/myPage.htm. |
IRA_SERVICE_INTERFACE_ |
Defines the path specification of the agent
service interface HTML directory. In conjunction with the IRA_SERVICE_INTERFACE_DEFAULT_PAGE parameter,
the agent constructs the file path to a specific, requested HTTP GET
object. The default filepath is CANDLE_HOME/localconfig on
distributed systems and the RKANDATV dataset on z/OS systems. The parameter is equivalent to
the IRA_HTML_PATH parameter. Example: If IRA_SERVICE_INTERFACE_DIR="\mypath\private" and you enter http://localhost:1920///kuxagent/kuxagent/html/myPage.htm in your browser, myPage.htm is retrieved from \mypath\private\html\ instead of %CANDLE_HOME%\localconfig\html\. |
IRA_SERVICE_INTERFACE_ |
Specifies a unique agent interface name to represent this agent. The default agent service interface name is pc agent, where pc is the application product code. In the scenario where multiple instances of the same agent are running in the system, this parameter enables customization of a unique service interface name to correspond to this agent. |
| ITM_MANIFEST_PATH=file_loc | The location of the self-describing agent's
manifest and JAR files. Normally this parameter is set during agent
installation and needs to be changed only if the files are moved to
a network file system. File locations:
This parameter is an internal parameter that is set and used by the agent installers only. You should not change this variable. |
| KBB_RAS1 | Sets the level of agent tracing:
|
| KCA_CACHE_LIMIT | Maximum time (in hours) that an alert is cached
and seen in the Alerts view of the Agent Managent Service (AMS)
workspace. Possible values: Greater than 0. Default value: 24. |
| KCA_CAP_DIR | Directories looking for CAP files. Possible values: Any valid PATH. Default value:
|
KCA_CAP_DISCOVERY_ |
Time interval (in seconds) for discovering new
or changed CAP files. Possible values: Greater than 0. Default value: 30. |
| KCA_CMD_TIMEOUT | Timeout (in seconds) for external commands created
by PAS. Possible values: Greater than or equal to 90. Default value: 90. |
| KCA_DISCOVERY_INTERVAL | How frequently the watchdog polls for new, running
instances of agents managed by Agent Management Services. Possible values: Greater than 0. Default value:
|
| KCA_IP_DIR | Only for Linux and UNIX; directory for creating sockets
to accept external commands. Possible values: Any valid existing PATH. Default value: $CANDLEHOME$/$BINARCH$/$PRODUCTCODE$/bin/pasipc Note:
|
KCA_ITM_DISCOVERY_ |
Time interval (in seconds) for discovering new
unmanaged agent instances of IBM Tivoli Monitoring agents
(cinfo command). Possible values: Greater than KCA_DISCOVERY_INTERVAL. Default value: 600. |
| KCA_MAX_RETRIES_ON_PIPE | Maximum number of consecutive failed attempts
to check the availability of the OS agent through the PAS internal
socket (pipe). When KCA_MAX_RETRIES_ON_PIPE is reached, the OS agent
is restarted. An undefined variable, or less than 0, means an infinite
number of retries (no restart). Possible values: Greater than 5. Default value: Not defined. |
| KCAWD_WRITE_DIR | Writable directory for kcawd (WatchDog agent). Possible values: Any valid directory. Default value: The installation directory of the OS agent binary. |
KHD_HISTSIZE_EVAL_ |
Controls how often (in seconds) the Warehouse Proxy Agent client code checks the size of the historical files. For more information, see the IBM Tivoli Monitoring Administrator's Guide. |
| KHD_HISTRETENTION | Specifies the default retention period in hours for the short-term history files (default is 24 hours). This value can be used to reduce the amount of data kept on disk after a successful upload to the warehouse is performed. |
| KHD_STATUSTIMEOUT | The time in seconds set by default to 900s = 15 minutes. An export request on the application agent is resent if a status is not received from the Warehouse Proxy agent before the timeout expires. It is advisable not to change this variable. |
| KHD_TOTAL_HIST_MAXSIZE | Controls the threshold that the Warehouse Proxy Agent client code uses when checking the size of the historical files. When their combined size is over the specified value in MB, writing to them is suspended until the threshold is no longer exceeded. A value of 0 disables the periodic checking. For more information, see the IBM Tivoli Monitoring Administrator's Guide. |
| TIMEOUT | Specifies the time in seconds that Agent Deployment tool has to complete a task. If the tool does not complete in the task in the time specified by the TIMEOUT value, the task is terminated. The default value is 600 seconds. |
| TEMA_SDA | N disables the self-describing agent capability
at the agent, whereas Y enables it. A value of N blocks the Tivoli Enterprise Monitoring
Server from retrieving any product support files from this agent and
provides you with control on a per agent basis without stopping the
self-describing agent feature on the Tivoli Enterprise Monitoring Server for
other products. Note: Do not specify YES or NO;
instead, always specify Y or N.
|
| TEMA_SDA_ACK_WAIT | Time interval in seconds for the agent to wait
on a response from the Tivoli Enterprise Monitoring Server for
the completion status of an actual self-describing agent installation.
A valid value is a number in seconds greater than or equal to 60.
The default value is 300 seconds. This parameter is an internal parameter that you might use, in a rare situation, to fine-tune the self-describing agent capability. In general, accept the default value of this variable. |
| TEMA_SDA_RETRY_WAIT | Time interval in seconds for the agent to wait
before attempting another self-describing agent installation request.
Not all failed self-describing agent registration or installation
responses from the Tivoli Enterprise
Monitoring Server are retried. A valid value is a number in seconds
greater than or equal to 60. The default value is 600 seconds. This parameter is an internal parameter that you might use, in a rare situation, to fine-tune the self-describing agent capability. In general, accept the default value of this variable. |
| TEMA_SDA_MAX_ATTEMPTS | The maximum number of times the agent tries
to register a request to initiate a self-describing agent product
installation with the Tivoli Enterprise
Monitoring Server. The agent will continue to try its self-describing
agent registration until the Tivoli Enterprise
Monitoring Server self-describing agent manager has completed the
installation of this agent's product support. The minimum value is
1. The agent must always try its self-describing agent registration
once (unless the TEMA_SDA value is N). This maximum attempt count
should only be modified with direction from IBM Software Support. If the value is set too
low, your self-describing agent product installation might not complete
as expected. The agent must be able to retry its self-describing agent
registration until the product installation has completed. In the
event of an agent attempting excessive self-describing agent product
install retry attempts, it might generate excessive or unwanted audit
or error messages that you want to stop. Decreasing this number can
help in such a case. This parameter is an internal parameter that you might use, in a rare situation, to fine-tune the self-describing agent capability. In general, accept the default value of this variable. |