Configuration file
OS agents use a configuration file t that is read by the agent when it starts. The file contains configuration options and filters. You must create this configuration file and configure the agent instance to use it.
The configuration file is monitored for changes to its time stamp every 60 seconds thereafter. If the time stamp of the file changes, the agent reinitializes its configuration dynamically, without requiring a restart. For more information, see Changing the agent configuration and format files.
- codepage
- This parameter is the code page of the monitored file. Use this parameter in the configuration file when the code page of the monitored file is different from the code page of the system. Specify the code page of the monitored file, for example, ibm-5348_P100-1997, UTF-16, or UTF-8.
- ConfigFilesAreUTF8=Y
- This parameter specifies that the configuration file and format file are in UTF-8. Use this parameter if the encoding of the configuration files is UTF-8 and the system code page is not. The default is that the agent assumes the system encoding.
- DupDetectionKeyAttributes
- A comma-separated list of Cloud
APM
attributes that is used to determine which events are duplicates. If all the named attributes are
the same in two events, then those two events are considered duplicates. This option applies only to
events. For more information, see Event filtering and summarization. Note:
- The attribute names are case-sensitive, so you must enter the names exactly as described.
- If you do not provide a list of attributes, the values default to
Class
andLogname
.
- ENFORCE_STRICT_TEC_COMPATIBILITY
- This parameter refers to all white space characters in the log data to ensure that the
characters are respected. For example, when you use a format such as
"%s %s"
to extract information from log messages, the OS agent matches not only a literal space but also any other white space characters that are present such as tabs and carriage returns.When this parameter is not set, the default behavior of the OS agent when it matches a Tivoli Enterprise Console® style format string is to match as much of the input text as it can, while it processes the format from left to right.
For example, for the
%s:%s
format string and theone:two:three
input string, the OS agent default assignsone.two
to the first parameter (corresponding to the first%s
) and it assignsthree
to the second parameter.Note:- This parameter does not apply to format statements that use the regular expression syntax.
- Setting this parameter has a performance impact. To give greater control over the behavior and performance of matching, avoid setting this parameter and use regular expressions instead.
- EventSummaryInterval
- Specifies the number of seconds during which the agent searches for duplicate events to suppress. Set this parameter to a positive integer. This option applies only to events. For more information, see Event filtering and summarization.
- EventFloodThreshold
- Specifies which events are sent when duplicate events are detected. Set this parameter to
send_none
,send_all
,send_first
, or a positive integer. This option applies only to events. For more information, see Event filtering and summarization. - EventMaxSize
- Specifies in bytes, the maximum size of a generated event. If specified, this parameter is used
in two places:
- The parameter can be used by the agent to set the size of a buffer that is used to process events. If not set, this buffer defaults to a size of 16384 bytes. If the buffer is set too small, events are truncated and can be discarded.
- The parameter can be used by the EIF sender to set the size of a buffer that is used to send events to an EIF receiver, such as the OMNIbus EIF probe. If not set, this buffer defaults to a size of 4096 bytes. If the buffer is set too small, events are discarded.
- FileComparisonMode
- Specifies which log files are monitored when more than one file matches a wildcard pattern. The
following values are available:
- CompareByAllMatches
- This value is the default behavior. All files that match the wildcard pattern that is specified
in
LogSources
are monitored. - CompareByLastUpdate
- Of the files that match the wildcard pattern that is specified in
LogSources
, the file with the most recently updated time stamp is monitored. - CompareBySize
- Of the two or more files that match the file name pattern criteria, the larger file is selected
for monitoring. Do not use
CompareBySize
with multiple matching files that are being updated at the same time and increasing their file sizes. If the largest file is subject to frequent change, monitoring might continually restart at the beginning of the newly selected file. Instead, useCompareBySize
for a set of matching files where only one is active and being updated at any specific time. - CompareByCreationTime
- Of the files that match the wildcard pattern that is specified in
LogSources
, the file with the most recently created time stamp is monitored. This value has the following restrictions:- The value is applicable only to Windows operating systems because UNIX and Linux® operating systems do not store a true creation time for files.
- The value is not supported for remote files that you monitor by using the Secure Shell (SSH) File Transfer Protocol.
Tip: TheCompareByLastUpdate
,CompareBySize
, andCompareByCreationTime
values can all be used for rolling log files.CompareByLastUpdate
is typically used for these files. - FQDomain
- Specifies how and if the agent sets a domain name:
- If set to
yes
, the agent determines the system domain name. - If set to
no
, the agent does not set a domain name. Thefqhostname
attribute is assigned a blank string. - If set so that it does not contain a
yes
orno
value, the domain name is accepted as the value and it is appended to the host name.
For more information, see Format file.
- If set to
- IncludeEIFEventAttr
- The agent includes a large attribute that is called EIFEvent, which is a
representation of the event that is sent through the Event Integration Facility if that feature is
enabled. The information that is contained in the EIFEvent attribute can also be
found in other attributes. Its large size made it problematic, thus it was disabled by default.
Setting this value to
y
, reenables the EIFEvent attribute.Note: Using this attribute might cause thresholds to fail if you have large events. A large event in this context is an event where the total number of bytes that is required to contain all values for all attributes and their names results in a string longer than 3600 bytes. - LognameIsBasename
- When set to
y
, the value of theLogname
attribute is the base name of the log file in which the event was found. This option applies only to Performance Management events. The path is removed. For example,/data/logs/mylog.log
becomesmylog.log
. If this value is set ton
, then you get the full path. However, because the attribute is limited to 64 characters, setting it ton
means that the name is truncated if it is longer. For this reason, the default value isy
. To see the full path name in a longer attribute, you can specify it in the mappings section of a format in the .fmt file, for example,filename FILENAME CustomSlot1
. The mapping completes the slot that is namedfilename
with the full path of the file in which the event was found and maps it intoCustomSlot1
, which is 256 characters. - LogSources
- Specifies the text log files to poll for messages. The complete path to each file must be
specified, and file names must be separated by commas. Within each file name, you can also use an
asterisk (
*
) to represent any sequence of characters, or a question mark (?
) to represent any single character. For example,mylog*
results in polling all log files whose names begin withmylog
, whereasmylog???
results in polling all log files whose names consist ofmylog
followed by exactly 3 characters. These wildcard characters are supported only within the file name; the path must be explicitly specified.If you want to use regular expressions or pattern matching in the path, see the RegexLogSources description.
A log file source is not required to exist when the agent is started; the log file is polled when it is created.
- NewFilePollInterval
- Specifies the frequency, in seconds, that the agent checks for new files to monitor. For example, if a file name specified by the LogSources or RegexLogSources configuration file settings does not yet exist when the agent starts, it checks again for the existence of the files after this interval.
- NumEventsToCatchUp
- Specifies the event in the log that the agent starts with. This option provides some flexibility
if the source that is being monitored is new or the agent is stopped for an extended time. The
following values are valid: Note: For text files, values
0
and-1
apply. For Windows Event Log, values0
,-1
, andn
apply.0
- Start with the next event in the logs. This value is the default.
-1
- When set to
-1
, the agent saves its place in the file that is being monitored. It saves its place so that when the agent is stopped and later restarted, it can process any events that are written to the log while it was stopped. The agent otherwise ignores events that arrived while it was stopped and restarts from the end of the file. This setting does not apply to pipes, or syslog monitoring on UNIX and Linux systems. n
- Set to a positive integer. Starts with the nth event from the most current
event in the logs; that is, start n events back from the most current event in
the logs. If n is greater than the number of events that are available, all the
events that are available are processed. Note: You can use the
n
value only for Windows Event Log. Then
value is ignored whenUseNewEventLogAPI
is set to y.
- PollInterval
- Specifies the frequency, in seconds, to poll each log file that is listed in the
LogSources
option for new messages. The default value is5
seconds.If you upgraded a Windows Event Log adapter from a previous release and you have a value that is set for
PollingInterval
in the Windows registry, you must specify thePollInterval
option in the agent configuration file with the same value that is used in the Windows registry. This rule applies only if you are replacing a Tivoli Enterprise Console OS agent that had values in the registry. - ProcessPriorityClass
- Specifies the process priority for the agent. You can adjust this value to improve system
performance if the agent processes large volumes of events and is using too many processor
resources. The possible values are:
- A - Very low priority
- B - Low priority
- C - Typical priority
- D - Above typical priority
- E - High priority
- F - Very high priority
- USE_CONF_FILE_VALUE - Use the value that is specified in the configuration file. This value is the default.
- RegexLogSources
- Specifies the text log files to poll for messages. It differs from the LogSources option in that
regular expression meta characters can be used in the base name portion of the file name and in one
subdirectory of the file name. This difference provides greater flexibility than the LogSources
option in describing multiple files to monitor in multiple directories.
For example, specifying
/var/log/mylog*
for the LogSources statement is identical to using the dot(.)
meta character followed by an asterisk(*)
meta character to form/var/log/mylog.*
in the RegexLogSources statement. This type of qualifier results in polling all log files in the/var/log
directory whose base names begin with mylog and are followed by zero or more characters. A/var/log/mylog.+
qualifier results in polling all log files in the/var/log
directory whose names begin with mylog and are followed by one or more characters.Similar to LogSources, the complete path to each file must be specified and the file names must be separated by commas. However, the comma is also a valid character inside a regular expression. To distinguish between a comma that is used as part of a regular expression and one that is used to separate file names, commas that are used as part of a regular expression must be escaped with the backslash
(\)
character.For example, if you want to search for logs that match either of the following regular expressions,
/logs/.*\.log
and/other/logs/[a-z]{0,3}\.log
, you must escape the comma in the{0,3}
clause of the second expression so the agent does not mistake it for the beginning of a new expression:RegexLogSources=/logs/.*\.log,/other/logs/[a-z]{0\,3}\.log
If meta characters are used in the path name, the meta characters can be used in only one subdirectory of the path. For example, you can specify
/var/log/[0-9\.]*/mylog.*
to have meta characters in one subdirectory. The[0-9\.]*
results in matching any subdirectory of/var/log
that consists solely of numbers and dots(.)
. Themylog.*
results in matching any file names in those/var/log
subdirectories that begin withmylog
and are followed by zero or more characters.Because some operating systems use the backslash
(\)
as a directory separator it can be confused with a regular expression escape meta character. Because of this confusion, forward slashes must always be used to indicate directories. For example, Windows files that are specified as C:\temp\mylog.* might mean the\t
is a shorthand tab character. Therefore, always use forward slashes(/)
for all operating systems directory separators. For example, C:/temp/mylog.* represents all files in the C:/temp directory that start with mylog.If more than one subdirectory contains meta characters, a trace message is also issued. For example,
c:/[0-9\.]*/temp.files/mylog.*
has two subdirectories with meta characters.[0-9\.]*
is the first subdirectory with meta characters andtemp.files
is the second subdirectory that used a dot(.)
meta character. In this case, the agent assumes that the first subdirectory with the meta character is used and the subsequent directories with meta characters are ignored. - SubnodeName
- A string value that can be used to override the default name that is assigned to a monitoring profile subnode. By default the subnode name that is assigned to a monitoring profile corresponds to the base name of the configuration file that is used for that profile. By using this setting, a different subnode name can be assigned.
- SubnodeDescription
- A string value that can be used to assign a value to the Subnode Description attribute of LFAProfiles.
- UnmatchLog
- Specifies a file to log discarded events that cannot be parsed into an event class by the agent.
The discarded events can then be analyzed to determine whether modifications to the agent format
file are required. Events that match a pattern that uses *DISCARD* do not appear in the unmatch log
because they did match a pattern.
This option is used in a test environment to validate the filters in the format file. This option fills up your file system if you leave it on for extended periods.
Options for remote log file monitoring by using SSH
Other than SshHostList, which is a list, all options can have only one value, which is applied to all remote hosts that are specified in SshHostList.
- SshAuthType
- Must be set to either PASSWORD or PUBLICKEY. If set to PASSWORD, the value of SshPassword is treated as the password to be used for SSH authentication with all remote systems. If set to PUBLICKEY, the value of SshPassword is treated as the pass phrase that controls access to the private key file. If set to PUBLICKEY, SshPrivKeyfile and SshPubKeyfile must also be specified.
- SshHostList
- A comma-separated list of remote hosts to monitor. All log files that are specified in the LogSources or RegexLogSources statements are monitored on each host that is listed here. If localhost is one of the specified host names, the agent monitors the same set of files directly on the local system. When you specify localhost, SSH is not used to access the files on the local system; the log files are read directly.
- SshPassword
- When the value of SshAuthType is
PASSWORD, this value is the account password of the user that is specified in
SshUserid. You can supply the account password in clear text, or you can supply
a password that is encrypted with the IBM®
Tivoli® Monitoring CLI
itmpwdsnmp command. For more information about how to encrypt a password by using
the itmpwdsnmp command, see Remote log file monitoring: Encrypting a password or pass phrase.When the value of SshAuthType is PUBLICKEY, this value is the pass phrase that decrypts the private key that is specified by the SshPrivKeyfile parameter. You can supply the pass phrase in clear text, or you can supply a pass phrase that is encrypted with the IBM Tivoli Monitoring CLI itmpwdsnmp command. For more information about how to encrypt a password by using the itmpwdsnmp command, see Remote log file monitoring: Encrypting a password or pass phrase.Note: If the value of SshAuthType is PUBLICKEY, and you configured SSH not to require a pass phrase, SshPassword must be set to null. To set SshPassword to null, the entry in the configuration file is:
SshPassword=
- SshPort
- A TCP port to connect to for SSH. If not set, defaults to 22.
- SshPrivKeyfile
- If SshAuthType is set to PUBLICKEY, this value must be the full path to the file that contains the private key of the user that is specified in SshUserid, and SshPubKeyfile must also be set. If SshAuthType is not set to PUBLICKEY, this value is not required and is ignored.
- SshPubKeyfile
- If SshAuthType is set to PUBLICKEY, this value must be the full path to the file that contains the public key of the user that is specified in SshUserid, and SshPrivKeyfile must also be set. If SshAuthType is not set to PUBLICKEY, this value is not required and is ignored.
- SshUserid
- The user name on the remote systems, which the agent uses for SSH authentication.
Option that is supported on UNIX and Linux systems only
- AutoInitSyslog
- If this option is set to Yes, the agent automatically configures the
syslog facility to write a standard set of events to a pipe that the agent monitors. By enabling
this setting, you can monitor syslog events without maintaining and rolling over log files. If this
option is not set in the configuration file, it is the same as being set to
No.Restriction: This option is not supported for remote log file monitoring.
Options that are supported on Windows systems only
- NTEventLogMaxReadBytes
- If you are using the older NT Event Log interface (
UseNewEventLogAPI
is not set toy
) to read event log data on a Windows system, the agent reads up to this number of bytes each time it checks the event log for new data. Setting the value to0
causes the agent to attempt to read all new data, as it did in earlier releases. This activity can occupy the agent for a considerable amount of time on a system with many events. The default value is655360
. When set, the agent might not stop at exactly the value that is specified, but rather at the nearest multiple of an internal buffer size to this value. - PreFilter
- Specifies how events in a Windows Event Log are
filtered before agent processing.
PreFilter
statements are used byPreFilterMode
when the filters determine which events are sent from an event log to the agent. An event matches aPreFilter
statement when each attribute=value specification in thePreFilter
statement matches an event in the event log. A PreFilter statement must contain at least the log specification and can contain up to three more specifications, which are all optional: event ID, event type, and event source. The order of the attributes in the statement does not matter.ThePreFilter
statement has the following basic format:PreFilter:Log=log_name;EventId=value; EventType=value;Source=value;
You can specify multiple values for each attribute by separating each value with a comma.
Each
PreFilter
statement must be on a single line.PreFilter
is not mandatory. All Windows log events are sent to the agent if prefilters are not specified andPreFilterMode=OUT
. - PreFilterMode
- This option applies only to Windows Event Log. The
option specifies whether Windows systems log events that
match a
PreFilter
statement are sent (PreFilterMode=IN
) or ignored (PreFilterMode=OUT
). Valid values areIN
,in
,OUT
, orout
. The default value isOUT
.PreFilterMode
is optional; ifPreFilterMode
is not specified, only events that do not match anyPreFilter
statements are sent to the agent.Note: If you setPreFilterMode=IN
, you must also define thePreFilter
statements. - SpaceReplacement
- Set to
TRUE
by default for Windows Event Log (Windows Server 2008 only) but not for previous versions of Event Log. WhenSpaceReplacement
isTRUE
, any spaces in the security ID, subsource, Level, and keywords fields of the event log messages are replaced with underscores (_). WhenSpaceReplacement
isFALSE
, any spaces in the security ID, subsource, Level, and keywords fields of the event log messages remain unchanged. For more information about this option, see Windows Event Log. - UseNewEventLogAPI
- When set to
y
on Windows systems, uses the new Windows Event Log interface for event logs. The option is supported only on Windows 2008 and later. The option is needed to access many of the new event logs that debuted in Windows 2008 and the applications that run on it. The option is ignored on earlier versions of Windows and on UNIX and Linux. For more information about this option, see Windows Event Log. - WINEVENTLOGS
- Controls which Windows event logs are monitored.
The WINEVENTLOGS statement is a comma-delimited list with no spaces. For more information, see Windows Event Log.
Note: Any carriage returns, tabs, or new lines in Windows events are replaced by spaces.
Option that is supported on AIX systems only
- AIXErrptCmd
- An
errpt
(error report) command string that the agent runs can be supplied here. The command output is fed into the stream of log data that is being monitored.For example, the following command causes the agent to search for the mmddhhmmyy string and replace it with the actual date and time on startup. Only the first occurrence of the string is replaced.AIXErrptCmd=errpt -c -smmddhhmmyy
Although you can supply your own
The data stream is the standard output from theerrpt
command, you must use the-c
(concurrent mode) option so that the command runs continuously. You cannot use the-t
option or the following options that result in detailed output:-a
,-A
, or-g
.errpt
command, so regular expressions in the.fmt file must be written to match. For example, the data output might be:
A sample format that picks up the data rows, but not the header, is:IDENTIFIER TIMESTAMP T C RESOURCE_NAME DESCRIPTION F7FA22C9 0723182911 I O SYSJ2 UNABLE TO ALLOCATE SPACE IN FILE SYSTEM 2B4F5CAB 1006152710 U U ffdc UNDETERMINED ERROR 2B4F5CAB 1006152610 U U ffdc UNDETERMINED ERROR
For more information, see Monitoring an AIX Binary Log.REGEX GenericErrpt ^([A-F0-9]{8}) +([0-9]{10}) ([A-Z]) ([A-Z]) (\S+) +(.*)$ Identifier $1 CustomSlot1 Timestamp $2 CustomSlot2 T $3 CustomSlot3 C $4 CustomSlot4 Resource $5 CustomSlot5 msg $6 END
Options that apply only when events are being forwarded to EIF
- BufferEvents
- Specifies how event buffering is enabled. The possible values
are:
- YES - Stores events in the file that is specified by the BufEvtPath option (This value is the default).
- MEMORY_ONLY - Buffers events in memory.
- NO - Does not store or buffer events.
- BufEvtPath
- Specifies the full path name of the agent cache file. If this path is not rectified the default
is:
- /etc/Tivoli/tec/cache
- \etc\Tivoli\tec\cache
Note: If events are being forwarded to more than one server, a BufEvtPath value must be specified for each forwarding channel. An index number is appended to the BufEvtPath name for each additional entry. For example, use BufEvtPath1 to indicate the path name of the agent cache file for forwarding to the first extra server. The value that is set in each BufEvtPath must be unique. - BufEvtMaxSize
- Specifies the maximum size, in KB, of the agent cache file. The default value is 64. The cache
file stores events on disk when the BufferEvents option is set to Yes. The
minimum size for the file is 8 KB. File sizes specified less than this level are ignored, and 8 KB
is used. The value that you specify for the maximum file size does not have an upper limit. Note: If the cache file exists, you must delete the file for option changes to take effect.
- NO_UTF8_CONVERSION
- Specifies whether the Event Integration Facility encodes event data in UTF-8. When this option
is set to
YES
, the EIF does not encode event data in UTF-8. The data is assumed to already be in UTF-8 encoding when passed to the EIF. However, a prefix is added to the flag to indicate that the data is in UTF-8 encoding (if the flag does not exist at the beginning of the event data). The default value isNO
. - MaxEventQueueDepth
- This value indicates the maximum number of events that can be queued for forwarding. When the limit is reached, each new event that is placed in the queue bumps the oldest event from the queue. If not specified, the default value is 1000. This setting applies to all forwarding channels if NumAdditionalServers is used.
- NumAdditionalServers
- This entry is required if you want to forward events to more than one Netcool/OMNIbus ObjectServer. Its value is used to indicate the number of servers that events are forwarded to. Valid values are 1 - 8.
- ServerLocation
- Specifies the name of the host on which the event server is installed. Specify host name or IP
address. Use the dotted format for IP address. You can specify failover values such as
ServerLocation1=2.3.4.5,2.3.4.6. for the server locations if you want to. If
you specify failover values for ServerLocation, you must also specify an extra
ServerPort value for each ServerLocation.Note: If events are being forwarded to more than one server, a ServerLocation value must be specified for each server. An index number is appended to the ServerLocation name for each additional entry. For example, use ServerLocation1 to specify the name of the host on which the first extra server is installed.
- ServerPort
- Specifies the port number on which the EIF receiver listens for events. The
ServerPort option can contain up to eight values, which are separated by commas.
If failover values are specified for ServerLocation, you must set an equivalent
ServerPort value. The ServerPort is not used when the
TransportList option is specified.Note: If events are being forwarded to more than one server, a ServerPort value must be specified for each server. An index number is appended to the ServerPort name for each additional entry. For example, use ServerPort1 to specify the port number on which the EIF receiver listens for events for the first extra server.
- TransportList
- Specifies the user-supplied names of the transport mechanisms, which are separated by commas.
When a transport mechanism fails for sender applications, the API uses the following transport
mechanisms in the order that is specified in the list. For receiving applications, the API creates
and uses all the transport mechanisms. The transport type and channel for each
type_name must be specified by using the Type and Channels keywords:
- type_nameType
-
Specifies the transport type for the transport mechanism that is specified by the TransportList option. SOCKET is the only supported transport type.
The server and port for each channel_name are specified by the ServerLocation and ServerPort options.
- type_nameChannels
-
- channel_namePort
- Specifies the port number on which the transport mechanisms server listens for the specified channel (set by the Channel option). When this keyword is set to zero, the portmapper is used. This keyword is required.
- channel_namePortMapper
- Enables the portmapper for the specified channel.
- channel_namePortMapperName
- Specifies the name of the portmapper if the portmapper is enabled.
- channel_namePortMapperNumber
- Specifies the ID that is registered by the remote procedure call.
- channel_namePortMapperVersion
- Specifies the version of the portmapper if the portmapper is enabled.
- channel_nameServerLocation
- Specifies the name of the event server and the region where the server for transport mechanisms is located for the specified channel. The channel is set by the Channel option. This keyword is required.
The configuration file accepts generic EIF options when used directly with OMNIbus. These options operate only over an EIF connection to OMNIbus. They do not affect events that are sent to the Cloud APM server. For more information about these EIF options, see EIF keywords.