The log configuration file conforms to a standard format. You can edit parameters and add or subtract sections known as log-handler definitions, but do not change the underlying format of the log configuration file.
The rest of this section discusses the following topics:
The XML file header is available at the beginning of the log configuration file.
<?xml version="1.0" encoding="ISO-8859-1" ?>
The header serves the following purposes:
The header declares the relevant XML version, which is always 1.0.
It also declares the encoding format, which is always ISO-8559-1.
The header is followed by an initial compound list.
The initial compund list is delimited as follows:
<CompoundList xmlns="http://www.oblix.com" ListName="logframework.xml.staging"> . . . </CompoundList>
The first compound list is structured as follows:
The compound list start-tag shows the relevant XML name space for the log configuration file in the xmlns parameter.
The compound list start-tag also provides a name for the compound list in the ListName parameter.
The compound list end-tag occurs near the end of the file.
This compound list delimits all log configuration information.
After the start-tag for the first compound list, a simple list sets the global defaults for logging.
The start and end tags for this list are as follows:
<SimpleList> . . . </SimpleList>
Between the start and end tags of the simple list, you configure the following:
Table 9-4 Global Parameters in the First Compound List
| Parameter | Description |
|---|---|
|
|
Sets the default logging threshold. Default value: Possible Values: Refer to log levels in "Log Levels" The global threshold allows logs of a particular level and more general levels to be collected, and prevents lower-level logs from being collected. This threshold can be overridden by a per-module threshold. See "Configuring Different Threshold Levels for Different Types of Data" for details. |
|
|
Dynamically enables or disables the secure logging mechanism. This does not require a server or component restart. Default value: On Possible Values: On or Off |
|
|
Indicates the log threshold for which secure logging is effective. Default value: Possible Values: Refer to log levels in "Log Levels" Note: Ensure that |
|
|
Configure escape sequence characters used to avoid additional information being overwritten due to the secure logging mechanism. Use a comma separated list as shown here. Default value: ),] Possible Values: Characters only Note: Default values are recommended. Configuring inappropriate characters may lead to sensitive information being unmasked. |
|
|
Specifies the default masking length if none is specified in FILTER_LIST. Default value: 300 Possible Values: Positive integer Note: FILTER_LIST appears after the second compound list (log handlers). For more information, see "Filtering Sensitive Attributes". |
Following example shows the simple lists containing global settings, which appear in the first compound list in the oblog_config_wg.xml file.
<SimpleList>
<NameValPair
ParamName="LOG_THRESHOLD_LEVEL"
Value="LOGLEVEL_WARNING">
</NameValPair>
<NameValPair
ParamName="AUTOSYNC"
Value="True">
</NameValPair>
<NameValPair
ParamName="SECURE_LOGGING"
Value="On">
</NameValPair>
<NameValPair
ParamName="LOG_SECURITY_THRESHOLD_LEVEL"
Value="LOGLEVEL_TRACE">
</NameValPair>
<NameValPair
ParamName="LOG_SECURITY_ESCAPE_CHARS"
Value="),]">
</NameValPair>
<NameValPair
ParamName="LOG_SECURITY_MASK_LENGTH"
Value="300">
</NameValPair>
</SimpleList>
After the simple list containing global settings, and within the start and end tags for the initial compound list, you specify an additional compound list. This compound list contains log-handler definitions.
The start and end tags for this list are as follows:
<CompoundList xmlns="http://www.oblix.com" ListName="LOG_CONFIG"> . . . </CompoundList>
This compound list tag is configured as follows:
In the start tag for the compound list, the xmlns parameter indicates the relevant XML name space.
Also in the start tag, you specify the name of the list on the ListName parameter.
Typically, the name of this list is LOG_CONFIG.
Between the start and end tags for the compound list for the log-handler, you specify one or more ValNameList elements. Each ValNameList element contains the definition for a log-handler. Each instance of this element begins and ends as follows:
<ValNameList xmlns="http://www.oblix.com" ListName="Unique_Name">
. . .
</ValNameList>
The ValNameList elements are configured as follows:
The opening tag sets the relevant XML name space on the xmlns parameter.
The opening tag also sets a name for the log-handler on the ListName parameter.
Within the opening and closing ValNameList tags, you configure the log-handler. A log-handler definition contains three mandatory NameValPair elements:
The first mandatory NameValPair element defines the logging level for the log-handler.
This element contains the statement ParamName="LOG_LEVEL", whose value is a reserved name in Table 9-1, as follows:
<NameValPair ParamName="LOG_LEVEL" Value="LOGLEVEL_FATAL" />
The second mandatory NameValPair element defines the destination for log output.
This element contains a statement ParamName="LOG_WRITER", whose value is a reserved name in Table 9-3, as follows:
<NameValPair ParamName="LOG_WRITER" Value="SysLogWriter" />
The third mandatory NameValPair element toggles this log-handler on and off.
This element contains a statement ParamName="LOG_STATUS", with a value of On or Off, as follows:
<NameValPair ParamName="LOG_STATUS" Value="On" />
Finally, within the opening and closing ValNameList tags, if you specify FileLogWriter or MPFileLogWriter as the log writer, you can add none, some, or all of the following. See Table 9-7 for details:
A destination file name, as follows:
<NameValPair ParamName="FILE_NAME" Value="oblog.log" />
A buffer size, as follows:
<NameValPair ParamName="BUFFER_SIZE" Value="65535" />
A a file size that determines when a new log file is generated, as follows:
<NameValPair ParamName="MAX_ROTATION_SIZE" Value="52428800" />
A time in minutes that determines the interval at which a new log file is generated, as follows:
<NameValPair ParamName="MAX_ROTATION_TIME" Value="86400" />
After the end tag for the compound list that delimits the log-handlers, and before the end tag for the initial compound list, you can add per-module logging parameters.
See "Configuring Different Threshold Levels for Different Types of Data" for details.
Each name value pair associated with the FILTER_LIST parameter provides the name of a word or phrase to be checked before the log is written and the corresponding masking length for that word or phrase. During logging, the value of the word or phrase is masked and omitted from the log file.
Simply put, during logging Access Manager does not recognize whether a value to be masked is an attribute or its display name or something different (plain text). Secure Logging works by searching for words or phrases added in the FILTER_LIST and then masking out any data that is followed by the occurrence of those words or phrases. For example, in the following statement:
\csabuild\coreid1014\np_common\db\ldap\util\ldap_util3.cpp:3107 "ldap_parse_result of Simple Bind" ld handle^0x0779FA00 result^0x09FB0088 bind^cn=orcladmin LDAP bind operation status code^0 Additional error message^ freeit^0 parse_rc^0
After turning Secure Logging ON and adding "bind" in the FILTER_LIST (which is neither an attribute nor a display name), whatever follows the word in the FILTER_LIST (in this case, "bind") is masked. In this case, you would see the following in logs:
\csabuild\coreid1014\np_common\db\ldap\util\ldap_util3.cpp:3107 "ldap_parse_result of Simple Bind" ld handle^0x0779FA00 result^0x09FB0088 bind^cn=orcladmin LDAP bind********** status code^0 Additional error message^ freeit^0 parse_rc^0
All attributes are case sensitive. For example, if you enter "password" instead of "Password" as a display name for an attribute, then "Password" is not filtered. By default, four attributes are always configured in the filter list: password, Password, response, and Response.
The default masking length, 40, is specified for each of the four default attributes. The default mask length can be altered for the default attributes if needed. If you add other attributes to the filter list, you might need a larger mask length (300, for example).
The default filter list is shown in the following example:
<ValNameList>
xmlns="http://www.oblix.com"
ListName="FILTER_LIST">
<NameValPair
ParamName="password"
Value="40"></NameValPair>
<NameValPair
ParamName="Password"
Value="40"></NameValPair>
<NameValPair
ParamName="passwd"
Value="40"></NameValPair>
<NameValPair
ParamName="Passwd"
Value="40"></NameValPair>
<NameValPair
ParamName="response"
Value="40"></NameValPair>
<NameValPair
ParamName="Response"
Value="40"></NameValPair>
</SimpleList>
When you add another attribute to the filter list, you must include the display name as well as the attribute name in the directory server.
When using XML, you can specify parallel elements in a list in any order as long as the elements remain intact and within the tags that originally bracketed them.
For example, the lists in the following examples are equivalent:
<ValNameList xmlns="http://www.example.com" ListName="LogError2Sys"> <NameValPair ParamName="LOG_LEVEL" Value="LOGLEVEL_ERROR" /> <NameValPair ParamName="LOG_WRITER" Value="SysLogWriter" /> <NameValPair ParamName="LOG_STATUS" Value="On" /> </ValNameList>
<ValNameList xmlns="http://www.example.com" ListName="LogError2Sys"> <NameValPair ParamName="LOG_WRITER" Value="SysLogWriter" /> <NameValPair ParamName="LOG_LEVEL" Value="LOGLEVEL_ERROR" /> <NameValPair ParamName="LOG_STATUS" Value="On" /></ValNameList>
Similarly, within a given tag, the attributes (except for the tag name, which must always be the first element within the tag brackets) can be reordered, as long as they remain intact and within the tag elements that originally bracketed them. The opening tags for a name-value list in the following examples are equivalent:
<ValNameList xmlns="http://www.example.com" ListName="LogError2Sys">
<ValNameList ListName="LogError2Sys" xmlns="http://www.example.com">