7 Logging Webgate Event Messages

Each Webgate instance (both 10g and 11g Webgates) can write information about its processes and states to a log file. The logs can be configured to provide information at various levels of granularity. For example, you can record errors, errors plus state information, or errors, states, and other information to the level of a debug trace. You can also eliminate sensitive information from the logs.

Note:

Unless explicitly stated, all information in this section applies equally to 10g and 11g Webgates. For instance, the location of the log configuration, oblog_config_wg.xml, has changed for 11g while the content of the file and most other specifics have not changed.

This chapter provides the following sections:

7.1 About Logging, Log Levels, and Log Output

The logging feature enables you to analyze system performance and health, and to troubleshoot issues.

You can configure logging for individual Webgate instances of the following components:

  • 10g Webgates

  • 11g Webgates

  • Custom Access Clients (Access Manager SDK)

You can configure different logging levels for different functional areas of a component instance. For example, you can capture debug data for LDAP activity while recording only error-level data for all other component activity. You can also record the time taken for each request that a component processes, and you can send different levels of log data to different destinations. For example, you can send error information to a file and all other log data to the system log.

Securing Sensitive Information: Access Manager handles sensitive information about users. On some sites, this includes user password, date of birth, a social security number, security questions and answers for lost password requests. Sensitive data on your site might include a security number or other information you want to secure. At certain logging levels, sensitive information might be captured. Today, you can filter sensitive information out of log files, as described in "Filtering Sensitive Attributes".

Configuring Logging: You configure logging by editing a configuration file that is stored with the Webgate. See "About Log Configuration File Paths and Contents".

Logging Levels: You can request logging at various levels. The highest level is Fatal and the lowest level is Trace. See "About Log Levels" for details.

Logging Destinations: In the log configuration file, a parameter known as a log writer determines the destination for log output. See "About Directing Log Output to a File or the System File" for details. You create a complete definition for your log output by identifying a log writer and a log level. This complete definition is known as a log-handler. See "The Second Compound List and Log Handlers" for details.

The rest of this section discusses the following topics:

7.1.1 About Log Levels

A logging level determines the amount of data that is written to the log data file. Each logging level is cumulative, that is, each level contains all the data generated by the higher levels. For example, Error logs contain all the data generated by the Fatal logs, plus the events that are specific to the Error category.

Table 7-5 describes the levels. The default log level is Warning: LOGLEVEL_ WARNING.

Table 7-1 Logging Levels

Level Number of Events Reported Description

LOGLEVEL_ FATAL

> 60

Records critical errors. Generally, these events can cause the component to exit.

In the event of a system failure, Fatal-level messages are always flushed to the log file.

LOGLEVEL_ ERROR

> 960

Records events that may require corrective action, for example, a component is unavailable. Error logs can also be generated for transient or self-correcting problems, for example, failure to connect to another component.

LOGLEVEL_ WARNING

> 1200

Records issues that may lead to an error or require corrective action in the future.

LOGLEVEL_ INFO

> 400

Records completed actions or the current state of a component, for example, the component is initializing.

LOGLEVEL_ DEBUG1

> 400

Records debugging information. Typically, the information at this level is only meaningful to a developer.

LOGLEVEL_ DEBUG2

> 100

Records advanced debugging information. This level augments the Debug1 log level. Typically, the information at this level is only meaningful to a developer.

LOGLEVEL_ DEBUG3

> 900

Records a large amount of debugging information or data pertaining to an expensive section of the code. This level is useful for debugging a tight loop or a performance-sensitive function. Typically, the information at this log level is only meaningful to a developer.

These logs can contain sensitive information.

LOGLEVEL_ TRACE

> 900 Access Manager API

> 150 third-party API

This log level is used to trace code path execution or to capture performance metrics. This information is captured at the entry and exit points for each component function. Typically, the information at this log level is only meaningful to a developer.

These logs can contain sensitive information.

LOGLEVEL_ ALL

> 5000

This level includes all the events and states from all other levels.


Compound Lists: You can collect log data from non-adjacent levels and send different levels of log data to different destinations. For example, you can send the Fatal logs to the system log, and write Error logs to a file. See "The Second Compound List and Log Handlers" for details.

Threshold: You configure a global cutoff, or threshold, for logging on the LOG_THRESHOLD_LEVEL parameter in the log configuration file. By default, if a configured level for a log-handler exceeds the cutoff, the log data is not collected. Note that logs can fail to be written despite the configured level because the LOG_THRESHOLD_LEVEL parameter takes precedence over the level configured in the log-handler. Only the MODULE_CONFIG section of the log configuration file overrides the global threshold. See "The Simple List and Logging Threshold" for details.

Overrides: You specify function- or module-specific overrides for the global logging threshold on the MODULE_CONFIG parameter. See "Configuring Different Threshold Levels for Different Types of Data" for details.

Note:

The Trace and Debug3 level logs can contain sensitive information. For more information about sensitive information, see "Filtering Sensitive Attributes".

7.1.2 About Log Output

Each line of the log output file follows a particular structure. A line starts with a date and time stamp, followed by the thread that is processing the request, the name of the function or module being logged, and the log level.

The following is a snapshot of the left-most columns of the log output file:

2007/06/01@00:50:56.859000    5932  2672  DB_RUNTIME     DEBUG3
2007/06/01@00:50:56.859000    5932  2672  DB_RUNTIME     TRACE
2007/06/01@00:50:56.859000    5932  2672  LDAP           DEBUG1
2007/06/01@00:50:56.859000    5932  2672  LDAP           TRACE
2007/06/01@00:50:56.859000    5932  2672  LDAP           TRACE

The two columns to the right of the log level are internal code references, and can be ignored. The following is an example of these columns:

0x00000205   ldap_connection_mngr.cpp:212

To the right of the internal code reference columns, you see the log message that is associated with this log level, for example, "Function called" or "Function returned," followed by the name of the function, as illustrated in the following example:

"Function called"   _CallName^ldap_init

The log message and function name can be followed by additional information, for example, the duration of the process, the address space where the function is running, or state information, as illustrated in the following examples:

"Connection health check result"   Server^dlsun4072   Port^389   Server Priority^1     Connection available^true

"Function entered"    _TraceName^ConnectionWatcherThread::CheckPrimaries  

"Function exited"     _TraceName^ConnectionWatcherThread::CheckPrimaries TraceDuration^0.000028

"Connection Pool Status in ValidateConnections()    "NumLivePrimaryConnections^1 Maximum Connections^1     UpConnections^1     Failover Threshold^1     Max Session Time^0    SleepFor^60

To secure sensitive information and ensure that it is not included in the output of the logging operation, see "Filtering Sensitive Attributes".

7.2 About Log Configuration File Paths and Contents

The log configuration file, oblog_config_wg.xml, is used to specify configuration details for Webgate logging (oblogs).

You configure parameters that control Webgate log output in XML-based log files that you edit with a plain text editor. Changes that you make to these files are effective immediately.

The rest of this section discusses the following topics:

7.2.1 Log Configuration File Paths and Names

By default, Webgate logging is enabled and oblogs are generated in the Oracle HTTP Server (OHS) instance diagnostics directory: instance1/diagnostics/logs/OHS/ohs1/.

Each Webgate instance includes a log configuration file (oblog_config_wg.xml) where you can define what type of data is recorded in the log output. A log configuration file is distinct from the log output file. For details on log output files, see "About Log Output".

The oblog_config_wg.xml file is updated when you edit to configure Webgate logging. For example, by setting a new log threshold level, changing a log file name, or filtering logs related to some modules and so on.

Log configuration, oblog_config_wg.xml, files reside in the following locations depending upon your Webgate version:

10g Webgates: Webgate_install_dir\oblix\config

11g Webgates: Webgate/Oracle_Home under webgate/ohs/config and Instance_Home/webgate/config. The later is to be used when configuring logging.

The same oblog_config_wg.xml file is copied to the Webgate instance directory when the Webgate instance is created. Within Instance_Home, this file is located at webgate/config.

Note:

Do not change the path to this file. If you install more than one instance, a log configuration file is installed for each instance. When configuring logging, use oblog_config_wg.xml under Instance_Home should be updated.

After installation, oblog_config_wg.xml and oblog_config_wg_original.xml both contain comments to help guide your editing.

Table 7-2 lists the names of the log configuration files. Do not change the names.

Table 7-2 Log Configuration File Names for Components

Component Log Configuration FIle Name

Webgate

oblog_config_wg.xml

Access Manager SDK (custom Access Client)

oblog_config.xml


Important:

Do not change the default path or name for any logging configuration file.

The oblog_config_wg.xml file can be edited using any text editor as long as you ensure that after the update the file is still valid XML. After updates to the file, changes will take affect in about 60 seconds.

7.2.2 Log Configuration File Contents

The log configuration file controls items such as the following:

  • What is logged for that component

  • Where the data is sent

  • In certain cases, the size of the write buffer used for the log

  • Log file rotation intervals

The configuration file contains XML statements that you can edit in a text editor.

7.2.2.1 When Changes to the File Take Effect

A watcher thread picks up changes to the log configuration file every 60 seconds and ensures that changes take effect. It is unnecessary to restart the server

7.2.2.2 About Comments in the Log File

Each default log configuration file contains comments that are intended to assist with editing the file.

See Also:

The log configuration file on your system.

The commented default configuration file is shown here:

Comments can span one or multiple lines. Comments look similar to the following:

<!--NetPoint Logging Configuration File                            -->
<!--                                                               -->
<!--Changes to this file will be automatically taken into  effect  -->
<!--in one minute. This does not require any server restart.       -->

Example 7-1 shows a typical log configuration file with comments. Example 7-8 shows an example of a log file without comments.

Example 7-1 The Default Log Configuration File with Comments

<?xml version="1.0" encoding="ISO-8859-1" ?>
<!--============================================================   -->
<!--============================================================   -->
<!--NetPoint Logging Configuration File                            -->
<!--                                                               -->
<!--Changes to this file will be automatically taken into  effect  -->
<!--in one minute. This does not require any server restart.       -->
<!--                                                               -->
<!--============================================================   -->
<!--============================================================   -->
<!--Set the Log Threshold                                          -->
<!---->
<!--The log Threshold determines the amount of information to log. -->
<!--Selecting a lower level of logging includes the information    -->
<!--logged at the higher levels. For example, LOGLEVEL_ERROR       -->
<!--includes the information collected at LOGLEVEL_FATAL.          -->
<!---->
<!--Choices are:                                                   -->
<!--LOGLEVEL_FATAL - serious error, possibly a program halt.       -->
<!--LOGLEVEL_ERROR - a transient or self-correcting problem.       -->
<!--LOGLEVEL_WARNING - a problem that does not cause an error.     -->
<!--LOGLEVEL_INFO - reports the current state of the component.    -->
<!--LOGLEVEL_DEBUG1 - basic debugging information.                 -->
<!--LOGLEVEL_DEBUG2 - advanced debugging information.              -->
<!--LOGLEVEL_DEBUG3 - logs performance-sensitive code.             -->
<!--LOGLEVEL_TRACE - used when you need to trace the code path     -->
<!--execution or capture metrics. Includes all previous levels.    -->
<!--                                                               -->
<!--If you do not specify a threshold, the default is WARNING.     -->
<!--                                                               -->
<!--In addition to specifying a threshold, you need to specify     -->
<!--if changes that you make to the logging configuration in       -->
<!--the NetPoint GUI overwrite the settings in this file. The      -->
<!--AutoSync parameter accomplishes this. This parameter takes a   -->
<!--value of True or False. If set to True, changes made in the    -->
<!--GUI overwrite changes in this config file. If False, changes   -->
<!--made in the GUI are only in effect until the server is         -->
<!--stopped or restarted, after which the settings in this file    -->
<!--overwrite the GUI settings. The default is True.               -->
<!--                                                               --> 
<!--                                                               --> 
<CompoundList xmlns="http://www.oblix.com" ListName="logframework.xml.staging"> 
  <SimpleList> 
   <NameValPair ParamName="LOG_THRESHOLD_LEVEL" Value="LOGLEVEL_WARNING" /> 
   <NameValPair ParamName="AUTOSYNC" Value="True" /> 
   <!-- SECURE_LOGGING flag can be used to turn on/off Secure Logging -->   <!-- feature. By defalut this feature is tunred on.                --> 
   <NameValPair ParamName="SECURE_LOGGING" Value="On" /> 
   <!-- In addition to specifying a log threshold, you need to       --> 
   <!-- configure log level for which Secure Logging should be       --> 
   <!-- applicable.Choices for this can be used same as that of      --> 
   <!-- LOG_THRESHOLD_LEVEL. Secure log threshold can be set using   --> 
   <!-- LOG_SECURITY_THRESHOLD_LEVEL flag. Default value for Secure  --> 
   <!-- log threshold is TRACE.                                    --> 
   <NameValPair ParamName="LOG_SECURITY_THRESHOLD_LEVEL" 
    Value="LOGLEVEL_TRACE" /> 
   <!-- LOG_SECURITY_ESCAPE_CHARS is used to configure escape sequence --> 
   <!-- characters. This can be used to avoid additional information   --> 
   <!-- getting overwritten due to Secure Logging mechanism. Currently --> 
   <!-- following characters have been identified as escape sequence.  --> 
   <!-- Configuring inappropriate characters may lead to sensitive     --> 
   <!-- information being unmasked.                                    --> 
   <NameValPair ParamName="LOG_SECURITY_ESCAPE_CHARS" Value="),]" /> 
   <!-- LOG_SECURITY_MASK_LENGTH is used to specify default masking    --> 
   <!-- length if none is specified in FILTER_LIST.                    --> 
   <!-- Default value for LOG_SECURITY_MASK_LENGTH is 300.             --> 
   <NameValPair ParamName="LOG_SECURITY_MASK_LENGTH" Value="300" /   >
  </SimpleList>
<!--                                                               -->
<!--                                                               -->
<!--============================================================   -->
<!--============================================================   -->
<!--Configure the Log Level                                        -->
<!--                                                               -->
<!--                                                               -->
<!--To configure a log level, you specify a name for the           -->
<!--configuration (for instance, MyErrorLog1) and                  -->
<!--the log level that you are configuring. You can create         -->
<!--more than one configuration per log level if you want          -->
<!--to output to more than one destination. You can output to      -->
<!--the system log or to a file, as specified on                   -->
<!--the LOG_WRITER parameter. The value for the LOG_WRITER         -->
<!--parameter may only be SysLogWriter, FileLogWriter or           -->
<!--MPFileLogWriter. The MPFileLogWriter is a multi-process safe   -->
<!--FileLogWriter. It should be used to log in webcomponents i.e   -->
<!--Webgate loaded on multiprocess     -->
<!--webservers like Apache and IPlanet(UNIX)                       -->
<!--                                                               -->
<!--If you do not specify an output destination, the default is    -->
<!--SysLogWriter.                                                  -->
<!--                                                               -->
<!--If outputting to a file, you also specify a file name and      -->
<!--other parameters. Default parameter values are:                -->
<!--FILE_NAME: <installdir>/oblix/log/oblog.log                    -->
<!--BUFFER_SIZE: 32767 (number of bytes)                           -->
<!--MAX_ROTATION_SIZE: 5242880 (bytes, equivalent to 5MB)          -->
<!--MAX_ROTATION_TIME: 86400 (seconds, equivalent to one day)      -->
<!--                                                               -->
<!--Configuring the log level does not ensure that the data is     -->
<!--actually collected. Data collection for a log is               -->
<!--determined by the LOG_THRESHOLD_LEVEL parameter, above,        -->
<!--and the LOG_STATUS parameter in the log configuration.         -->
<!--                                                               -->
<!--If you do not provide a LOG_STATUS, the default for            -->
<!--LOGLEVEL_FATAL, LOGLEVEL_ERROR, and LOGLEVEL_WARNING,          -->
<!--is On.                                                         -->
<!---->
<!--This file contains several sample configurations that are      -->
<!--enclosed in comments. To use them, remove the comments.        -->
<!--                                                               --> 
   <CompoundList xmlns="http://www.oblix.com" ListName="LOG_CONFIG">
    <!--Write all FATAL logs to the system logger. --> 
    <ValNameList xmlns="http://www.oblix.com" ListName="LogFatal2Sys"> 
      <NameValPair ParamName="LOG_LEVEL" Value="LOGLEVEL_FATAL" /> 
      <NameValPair ParamName="LOG_WRITER" Value="SysLogWriter" /> 
      <NameValPair ParamName="LOG_STATUS" Value="On" /> 
    </ValNameList>
    <!--Write all logs to the Oracle log file.                     --> 
    <ValNameList xmlns="http://www.oblix.com" ListName="LogAll2File"> 
      <NameValPair ParamName="LOG_LEVEL" Value="LOGLEVEL_ALL" /> 
      <NameValPair ParamName="LOG_WRITER" Value="FileLogWriter" /> 
      <NameValPair ParamName="FILE_NAME" Value="oblog.log" /> 
      <!-- Buffer up to 64 KB (expressed in bytes) of log entries before         flushing to the file.     --> 
      <NameValPair ParamName="BUFFER_SIZE" Value="65535" />
      <!--Rotate the log file once it exceeds 50 MB (expressed in bytes). --> 
      <NameValPair ParamName="MAX_ROTATION_SIZE" Value="52428800" />
      <!--Rotate the log file after 24 hours (expressed in seconds). --> 
      <NameValPair ParamName="MAX_ROTATION_TIME" Value="86400" /> 
      <NameValPair ParamName="LOG_STATUS" Value="On" /> 
    </ValNameList> 
  </CompoundList> 
<!--  List of values that can be specified in the module config      -->
<!--                                                                 -->
<!--  On - Uses loglevel set in the loglevel threshold               -->
<!--  Off - No information is logged                                 -->
<!--  LOGLEVEL_FATAL - serious error, possibly a program halt.       -->
<!--  LOGLEVEL_ERROR - a transient or self-correcting problem.       -->
<!--  LOGLEVEL_WARNING - a problem that does not cause an error.     -->
<!--  LOGLEVEL_INFO - reports the current state of the component.    -->
<!--  LOGLEVEL_DEBUG1 - basic debugging information.                 -->
<!--  LOGLEVEL_DEBUG2 - advanced debugging information.              -->
<!--  LOGLEVEL_DEBUG3 - logs performance-sensitive code.             -->
<!--  LOGLEVEL_TRACE - used when you need to trace the code path     -->
<!--  execution or capture metrics. Includes all previous levels.    -->
<!--                                                                 -->
<!--  List of modules that can be specified in the module config     -->
<!--                                                                 -->
<!--  ALL_MODULES - Applies to all log modules                       -->
<!--  Specific module name - Applies to specific module              -->
<!--                                                                 -->
<!--                                                                 -->
<!--    <ValNameList                                                 -->
<!--        xmlns="http://www.oblix.com"                             -->
<!--        ListName="MODULE_CONFIG">                                -->
<!--        <NameValPair                                             -->
<!--            ParamName="CONNECTIVITY"                             -->
<!--            Value="LOGLEVEL_TRACE"></NameValPair>                -->
<!--    </ValNameList>                                               --><!--   <!--FILTER_LIST is used to maintain list of attributes which need         --> 
<!-- to be treated as sensitive and hence will be filtered out from   --> 
<!-- from logs. FILTER_LIST consist of all attribute names along      --> 
<!-- with corresponding masking lengths.There should be separate      --> 
<!-- entry in the list for the display name of the attribute          --> 
<!-- identified as sensitive. All attributes configured are case      -->
<!-- sensitive i.e. if we configured sensitive attribute homePhone    --> 
<!-- as HomePhone then it will not get filtered out from logs.        --> 
<!-- By default four attributes (password, Password, response and     --> 
<!-- Response) are configured as sensitive                            --> 
<!-- A sample configuration is shown below                            --> 

<!-- <ValNameList                                                    --> 
<!--    xmlns="http://www.oblix.com"                                 --> 
<!--    ListName="FILTER_LIST">                                      -->
<!--    <NameValPair                                                 -->
<!--      ParamName="password"                                       -->
<!--      Value="40"></NameValPair>                                  -->
<!--    <NameValPair                                                 -->
<!--      ParamName="Password"                                       -->
<!--      Value="40"></NameValPair>                                  -->
<!--    <NameValPair                                                 -->
<!--      ParamName="response"                                       -->
<!--      Value="40"></NameValPair>                                  -->
<!--     <NameValPair                                                -->
<!--      ParamName="Response"                                       -->
<!--      Value="40"></NameValPair>                                  -->
<!--    <NameValPair                                                 -->
<!--      ParamName="homePhone"                                      -->
<!--      Value="40"></NameValPair>                                  -->
<!--  </ValNameList>                                                 --> 
  <ValNameList xmlns="http://www.oblix.com" ListName="FILTER_LIST">
    <NameValPair ParamName="password" Value="40" />
    <NameValPair ParamName="Password" Value="40" />
    <NameValPair ParamName="passwd" Value="40" />
    <NameValPair ParamName="Passwd" Value="40" />
    <NameValPair ParamName="response" Value="40" />
    <NameValPair ParamName="Response" Value="40" />
  </ValNameList>
</CompoundList>

7.3 About Directing Log Output to a File or the System File

To send log output to a destination, you configure a log writer. A log writer can send log output to one, none, or both of the following:

  • A log file.

    This file resides under the root installation directory of the component.

  • The system file of the host for the component.

    If more than one component resides on the same host, all components send data to the system log file on that host.

You can send logs of a particular level, or logs of different levels, to more than one type of log writer. For instance, you can send Fatal data to the system log, and send Trace data to a file. Or, you can send Fatal data to both the system log and a file.

You define log writers in the log configuration file using the LOG_WRITER parameter in a log-handler definition. See "The Second Compound List and Log Handlers" for details.

The log writers are described in Table 7-3.

Table 7-3 Log Writers

Writer Description

SysLogWriter

Sends data to the system log file for the computer that hosts the component being logged. Typically, the system log file contains event information from multiple applications and the host operating system.

For Windows, this is the application log file located at My Computer, Manage, Event Viewer, Application.

For UNIX platforms, the name and location of the system log file can vary according to the computer and the preferences of the system Administrator. Consult the Administrator of the computer for the file location.

The default log configuration file sends Fatal, Error, and Warning messages to the system log file.

FileLogWriter

This writer is recommended when you want to save log data for an OAM Server or other single-process application on a disk file.

The FileLogWriter opens the log file and holds it open for disk writes until the approximate file size limit or file rotation interval has been reached. Oracle does not recommend this log writer for situations where more than one process needs to write to the same log file. For these situations, use the MPFileLogWriter.

MPFileLogWriter

This writer resembles the FileLogWriter, except that it opens and closes the log file each time it writes data to the file. This enables multiple processes to write to the file in turn. However, this practice can slow performance substantially.

Oracle recommends using MPFileLogWriter only when FileLogWriter fails to record logging data from some of the processes associated with a multi-process application, for example, an Access Client installed on a multi-process Web server (such as Apache) or the Solaris version of the iPlanet Web server.


7.4 Structure and Parameters of the Log Configuration File

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.

See Example 7-1 or Example 7-8 for a listing of the default log configuration file.

The rest of this section discusses the following topics:

7.4.1 The Log Configuration File Header

At the beginning of the log configuration file there is an XML file header:

<?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.

7.4.2 The Initial Compound List

The header is followed by an initial compound list that 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.

7.4.3 The Simple List and Logging Threshold

After the start-tag for the first compound list, a simple list sets the global defaults for logging, as follows:

<SimpleList>
. . .
</SimpleList>

Between the start and end tags of the simple list, you configure the following:

Table 7-4 Global Parameters in the First Compound List

Parameter Description

LOG_LEVEL_THRESHOLD

Sets the default logging threshold.

Default value: LOGLEVEL_WARNING

Possible Values: Refer to log levels in "About 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.

SECURE_LOGGING

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

LOG_SECURITY_THRESHOLD_LEVEL

Indicates the log threshold for which secure logging is effective.

Default value: LOGLEVEL_TRACE

Possible Values: Refer to log levels in "About Log Levels"

Note: Ensure that LOG_THRESHOLD_LEVEL and LOG_SECURITY_THRESHOLD_LEVEL are the same or are consistent with one another. For example, if LOG_THRESHOLD_LEVEL is set to LOGLEVEL_TRACE while LOG_SECURITY_THRESHOLD_LEVEL is set at LOGLEVEL_WARNING, then secure logging applies to LOGLEVEL_WARNING and above but does not apply to LOGLEVEL_TRACE.

LOG_SECURITY_ESCAPE_CHARS

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.

LOG_SECURITY_MASK_LENGTH

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".


Example 7-2 shows the simple lists containing global settings, which appear in the first compound list in the oblog_config_wg.xml file.

Example 7-2 Simple Lists with Global Settings (First Compound List in oblog_config_wg.xml)

<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>

7.4.4 The Second Compound List and Log Handlers

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 7-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 7-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 7-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" />
    

7.4.5 The List for Per-Module Logging

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.

7.4.6 The Filter List

After the per-module logging parameters a filter list identifies sensitive information that you might want to filter out of the log file. For example, passwords and responses for lost password management are sensitive information that you might want to filter out of the log file.

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 Example 7-3.

Example 7-3 FILTER_LIST Masks Sensitive Attributes in Log Files

<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.

7.4.7 About XML Element Order

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 Example 7-4 and Example 7-5 are equivalent:

Example 7-4 Valid Name/Value List

<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>

Example 7-5 Another Valid Name/Value List

<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 Example 7-6 and Example 7-7 are equivalent:

Example 7-6 Opening tag for a Name/Value List

<ValNameList xmlns="http://www.example.com" ListName="LogError2Sys">

Example 7-7 Opening tag for a Name/Value List

<ValNameList ListName="LogError2Sys" xmlns="http://www.example.com">

7.5 About Activating and Suppressing Logging Levels

Several factors determine if logging is active for a particular log-handler. Table 7-5 lists these factors.

Table 7-5 Factors that Determine Whether Logging Is Active

Factor Importance Description

LOG_ THRESHOLD_ LEVEL

Primary

This parameter sets a cutoff for logging. Any log level that is more detailed than the threshold is suppressed. See Table 7-1 for valid log levels.

You override this parameter for a subset of items that can be logged using the MODULE_CONFIG parameter. See "Configuring Different Threshold Levels for Different Types of Data" for details.

MODULE_CONFIG

Primary

This sets a per-module override for the global logging threshold.

See "Configuring Different Threshold Levels for Different Types of Data" for details.

LOG_STATUS

Secondary

This parameter toggles logging on or off, as long as it is not overridden by the logging threshold or a module-specific override.

The physical position of a log handler

Secondary

See "About Log Handler Precedence".


7.5.1 About Log Handler Precedence

You can configure up to three log-handler definitions for a single log level in a log configuration file. Three different log handlers are required to send output for a particular log level to each of the three log writers described in Table 7-3.

If you specify different LOG_STATUS settings in these log handlers, the setting in the log-handler definition closest to the physical end of the log configuration file sets the status for the other log-handler definitions of the same log level. For example, you can set LOG_STATUS to Off for the first two log handlers for the Error log level, but if LOG_STATUS is On for the third and final log handler in the configuration file, logging still occurs for all three handlers.

The LOG_STATUS settings are moot if that level is more fine-grained than the current LOG_THRESHOLD_LEVEL. In this case, logging cannot be activated at this level unless the threshold is overridden by a module-specific threshold. See "Configuring Different Threshold Levels for Different Types of Data" for details.

7.6 Mandatory Log-Handler Configuration Parameters

At minimum, each log-handler definition contains five parameters listed in Table 7-6.

Table 7-6 Mandatory Log Configuration File Parameters

Parameter Comment

xmlns

This parameter is specified in the opening ValNameList tag.

It specifies the relevant XML namespace for the current list and is identical for all log-handler definitions in a given logging configuration file. Example:

http://www.example.com

ListName

This parameter is specified in the opening ValNameList tag. Where possible, use the default names.

When creating a new log-handler definition, select a memorable name that you cannot confuse with other log handlers. Examples:

WarningsAndAboveToSyslog sends Fatal, Error, and Warning messages to the system log file.

WarningsOnlyToFileLog128KBuffer sends messages from just the Warning level to a 128KB buffer, and hence to a disk file.

TraceOnlyToMPRotateDaily sends messages from just the Trace level to the multi-process file writer, which opens and closes the file each time it writes to disk. This file is replaced with a fresh (empty) file every day, regardless of the size of the file at the time of replacement.

LOG_LEVEL

This specifies a log level. See Table 7-1 for details.

The default logging configuration file activates logging for three levels: Fatal, Error, and Warning.

LOG_WRITER

This specifies the destination for log output for this log-handler. See Table 7-3 for details.

The default log configuration file sends output to both the system log and the log data file for the component doing the logging.

LOG_STATUS

This parameter turns the log handler on or off.


If you specify FileLogWriter or MPFileLogWriter as the value for the LOG_WRITER parameter, the four parameters in Table 7-7 are relevant.

Table 7-7 Log Data File Configuration Parameters

Parameter Description Default

FILE_ NAME

Mandatory. Used only for the FileLogWriter or MPFileLogWriter. It is the name and location of the file where log data is written.

You can prepend an absolute path to the file name to store it somewhere other than the default location, which is:

component_install_dir\oblix\logs

Where component_install_dir is the root installation directory for the component whose system events you are logging.

When you create more than one log-handler definition that sends output to FileLogWriter or MPFileLogWriter, provide unique file names so that multiple handlers do not write to the same file. This caution does not apply to log handlers accessing the SysLogWriter.

oblog.log

BUFFER_SIZE

Optional. This is the size of the buffer, in bytes, for logged data as it is being written to the log file.

If you set the buffer value to 0 or a negative number, the default value is used. To write to the log file immediately, without buffering, set the value to a small number, for example, 5. Oracle recommends that you set a small buffer size in situations where there are system failures.

65535

(64KB)

MAX_ ROTATION_ SIZE

Optional. When the log file reaches this size (in bytes), a time stamp is appended to the file name, for example oblog.log becomes oblog.log1081303126. New data is written to the file with the original name.

52428800

(512KB)

MAX_ ROTATION_ TIME

Optional. A time interval, in seconds, when the log file is renamed, whether or not it has reached the maximum rotation size.

If the rotation time determines when the file is rotated, the numbers appended to the log files differ by the number of seconds in the rotation interval. For example, oblog.log.1081389526 and oblog.log.1081303126 differ by 84,600, which is the number of seconds in 24 hours. This is the rotation interval set in the log configuration file.

86400

(1 day, in seconds)


7.6.1 Settings in the Default Log Configuration File

As installed with each component, the log configuration file activates only the highest three levels (Fatal, Error, and Warning) and directs all log output to the system log.

On Windows, you can view the system log for the computer that hosts the component you are logging by navigating to My Computer, Manage, Event Viewer, Application. System event entries for the components being logged are interspersed among the system events for the operating system and applications other than Access Manager.

For Solaris and Linux environments, the location of the system log is recorded in a system configuration file whose particulars can vary from computer to computer. For the name and location of this system file or the system log, consult the owner of the computer that hosts the component whose system log you want to examine.

Example 7-8 shows the default log configuration file with comments removed to expose the file structure.

Example 7-8 A Default Log Configuration File Without Embedded Comments

<?xml version="1.0" encoding="utf-8"?>
<CompoundList        
   xmlns="http://www.oblix.com 
   ListName="oblog_config_wg.xml.staging">
   <SimpleList>
      <NameValPair 
         ParamName="LOG_THRESHOLD_LEVEL" 
         Value="LOGLEVEL_WARNING"></NameValPair>
   </SimpleList>
   <SimpleList>
      <NameValPair        
         ParamName="AUTOSYNC" 
         Value="True"></NameValPair>
   </SimpleList>
   <SimpleList>
      <NameValPair 
          ParamName="SECURE_LOGGING"
          Value="On"></NameValPair>  
   </SimpleList>
   <SimpleList> 
      <NameValPair 
         ParamName="LOG_SECURITY_THRESHOLD_LEVEL" 
         Value="LOGLEVEL_TRACE"></NameValPair>  
   </SimpleList>
   <SimpleList> 
      <NameValPair  
         ParamName="LOG_SECURITY_ESCAPE_CHARS"
         Value="),]"></NameValPair> 
   </SimpleList>
   <SimpleList> 
      <NameValPair 
        ParamName="LOG_SECURITY_MASK_LENGTH" 
        Value="300"></NameValPair> 
   </SimpleList>
   <CompoundList
      xmlns="http://www.oblix.com"
      ListName="LOG_CONFIG">
      <ValNameList 
         xmlns="http://www.oblix.com" 
         ListName="LogFatal2Sys">
         <NameValPair 
            ParamName="LOG_LEVEL"
            Value="LOGLEVEL_FATAL"></NameValPair>
         <NameValPair 
            ParamName="LOG_WRITER" 
            Value="SysLogWriter"></NameValPair>
         <NameValPair 
            ParamName="LOG_STATUS"
            Value="On"></NameValPair>
      </ValNameList>
      <ValNameList 
         xmlns="http://www.oblix.com" 
         ListName="LogAll2File">
         <NameValPair 
            ParamName="LOG_LEVEL" 
            Value="LOGLEVEL_ALL"></NameValPair>
         <NameValPair 
            ParamName="LOG_WRITER" 
            Value="FileLogWriter"></NameValPair>
         <NameValPair 
            ParamName="FILE_NAME" 
            Value="oblog.log"></NameValPair>
         <NameValPair 
            ParamName="BUFFER_SIZE" 
            Value="65535"></NameValPair>
         <NameValPair 
            ParamName="MAX_ROTATION_SIZE" 
            Value="52428800"></NameValPair>
         <NameValPair 
            ParamName="MAX_ROTATION_TIME" 
            Value="86400"></NameValPair>
         <NameValPair
            ParamName="LOG_STATUS" 
            Value="On"></NameValPair>
      </ValNameList>
    </CompoundList>
    <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>
    </ValNameList>
  </CompoundList>

7.6.1.1 Description of the Settings in the Default Log Configuration File

The default configuration file sends Fatal, Error, and Warning messages to both the system log and to a log data file named oblog.log.

The simple list near the top of the file sets the following parameters:

The nested compound list contains four log-handler definitions:

  • The first, named LogFatal2Sys, sets the logging level to Fatal and sets LOG_STATUS to On.

    The threshold level is Warning, which is more fine-grained than Fatal, so this definition is in effect. The log output is written to the system log, as specified by the LOG_WRITER parameter.

  • The LogError2Sys log-handler definition sends Error level messages to the system log.

    Error is located before the current threshold level (Warning), so this definition is in effect.

  • The LogWarning2Sys definition sends Warning level output to the system log.

    Like the two previous log-handler definitions, it is not overridden by the current LOG_THRESHOLD_LEVEL parameter.

  • LogAll2File, the final log-handler definition, appears to send output from all log levels to a disk file named oblog.log.

    The LOG_THRESHOLD_LEVEL parameter is set to Warning, so only the output from the Fatal, Error, and Warning levels are recorded in this log data file. Since output from LogAll2File goes to the FileLogWriter, the parameters governing file name, buffer size, rotation size, and rotation interval all take effect.

Figure 7-1 illustrates log-level activation in the default log confirmation file.

Figure 7-1 Log-Level Activation in the Default Log Configuration File

Description of Figure 7-1 follows
Description of "Figure 7-1 Log-Level Activation in the Default Log Configuration File"

7.7 Configuring Different Threshold Levels for Different Types of Data

When diagnosing a problem, you may not want detailed logs for every operation that a component performs. For example, to diagnose slow response times for requests that an Identity Server submits to its directory, you would want detailed information on LDAP operations and fewer details about other types of operations.

As of release 10.1.4.2, you can configure per-module or per-function threshold levels in the log configuration file, so that Access Manager generates detailed logs for some components while generating concise logs, or no logs, for others.

You configure per-module logging thresholds in a MODULE_CONFIG section in the oblog_config_wg.xml file. The MODULE_CONFIG section overrides the global default that you specify on the LOG_THRESHOLD_LEVEL in the simple list section of this file.

The rest of this section discusses the following topics:

7.7.1 About the MODULE_CONFIG Section

As described in "Structure and Parameters of the Log Configuration File", in the log configuration file you configure a global logging threshold. The following is an example of the global LOG_THRESHOLD_LEVEL setting:

   <SimpleList> 
      <NameValPair ParamName="LOG_THRESHOLD_LEVEL" Value="LOGLEVEL_WARNING" /> 
      . . . 
   </SimpleList>

In addition to the global threshold, the configuration file can contain a ValNameList that defines function- or module-specific log thresholds. The name of this list is always MODULE_CONFIG. Only one instance of this list is permitted in the log configuration file, and the information in the list applies to all log writers defined in the file. As of release 10.1.4.2, the default log configuration file contains a commented sample of the MODULE_CONFIG list.

Each item in the MODULE_CONFIG list sets a logging level for a module, as shown in the following example:

<ValNameList xmlns="http://www.oblix.com" ListName="MODULE_CONFIG">
    <NameValPair ParamName="LDAP" Value="LOGLEVEL_TRACE"></NameValPair>    <NameValPair ParamName="DB_RUNTIME" Value="LOGLEVEL_TRACE"></NameValPair></ValNameList>

The elements in this section are as follows:

  • The ValNameList tag delimits the list of per-module logging thresholds.

  • One NameValPair tag delimits each specific per-module logging threshold.

  • The ParamName parameter sets the name of a module or function.

    See Table 7-8 for a list of valid values.

  • The Value parameter sets the logging threshold for the module that you specify as a value for the ParamName parameter.

    Table 7-1 lists the permissible values for the Value parameter. In addition to these values, you can specify the value ON to enable logging for the module and a value of OFF to disable logging for the specific module.

7.7.1.1 Location of the Per-Module Logging Section in the Log Configuration File

You add the per-module logging threshold section near the end of the log configuration file, after the closing tag for the compound list for the log-handlers and before the closing tag for the first compound list in the file.

This section contains an example of the per-module logging section. See "To configure a module-specific log threshold" for details.

7.7.1.2 List of Modules That Can Be Logged

Table 7-8 describes the a partial list of the values that you can specify for the ParamName parameter in the MODULE_CONFIG list.

Table 7-8 ParamName Values You Can Configure for Per-Module Logging Threshold

ParamName Value Logging Threshold That This Parameter Sets

AAA_ACTIONS

Sets a logging threshold for triggered actions that are configured as part of a policy in the OAM Server.

<ValNameList xmlns="http://www.oblix.com"  
       ListName="MODULE_CONFIG">
<NameValPair Paramname="AAA_ACTIONS" Value="OFF">
</NameValPair>

AAA_AMENGINE

Sets a logging threshold for activity performed by the Access Manager engine.

AAA_ISRESRCOPPROT

Sets a logging threshold for all OAM Server activities related to determining if a resource operation is protected.

ACCESS_CLIENT

Sets a logging threshold for operations performed by an access client, that is, an Access Client or Webgate.

ACCESS_GATE

Sets a logging threshold for operations performed by an Access Client.

ACCESS_SDK

Sets a logging threshold for operations performed by the Access Manager SDK interface.

See the Oracle Fusion Middleware Developer's Guide for Oracle Access Management for details.

ACCESS_SERVER

Sets a logging threshold for operations performed in the OAM Server.

AM_SDK

Sets a logging threshold for the Access Manager SDK.

See the Oracle Fusion Middleware Developer's Guide for Oracle Access Management for details.

AUDIT

Sets a logging threshold for auditing.

See Chapter 8 for details.

AUTHENTICATION

Sets a logging threshold for user authentication operations.

AUTHN_MGMT

Sets a logging threshold for authentication scheme management.

AUTHN_PLUGIN

Sets a logging threshold for operations performed by an authentication plug-in.

AUTHORIZATION

Sets a logging threshold for user authorization operations.

AUTHZ_MGMT

Sets a logging threshold for authorization scheme management.

AUTHZ_PLUGIN

Sets a logging threshold for authorization plug-in operations.

CACHE

Sets a logging threshold for cache management and operations on the caches.

CONN_MGMT

Sets a logging threshold for connection management.

CONN_RUNTIME

Sets a logging threshold for connection run time.

CONNECTIVITY

Sets a logging threshold for client-sever connectivity and messaging.

DB_CONFIGURATION

Sets a logging threshold for the data store interface layer configuration.

DB_RUNTIME

Sets a logging threshold for the data store interface layer run time.

DIAGNOSTIC_FRAMEWORK

Sets a logging threshold for the diagnostic framework.

GROUPDB

Sets the threshold for logging accesses of Group Manager data in the directory.

GROUP_MGR

Sets the threshold for logging Group Manager operations.

HTTP_REQ

Sets the threshold for logging HTTP request processing.

IDXML

Sets the threshold for logging IDXML operations.

See the Oracle Fusion Middleware Developer's Guide for Oracle Access Management for details.

LDAP

Sets a logging threshold for LDAP SDK, for example:

<ValNameList xmlns="http://www.oblix.com" 
        ListName="MODULE_CONFIG">
<NameValPair Paramname="LDAP" Value="LOGLEVEL_TRACE">
</NameValPair>

NET

Sets a logging threshold for network APIs.

OBMYGROUPS

Sets a logging threshold for ObMyGroups processing. This refers to searches of groups where the person who initiated the search is a member.

OIS_CLIENT

Sets a logging threshold for the Identity client.

POLICY_MGMT

Sets a logging threshold for policy and policy domain management.

PPP

Sets a logging threshold for Identity Event Plug-in API operations.

See the Oracle Fusion Middleware Developer's Guide for Oracle Access Management for details.

QUERY_BUILDER

Sets a logging threshold for Query Builder operations.

SECURITY

Sets a logging threshold for the security and encryption library.

SELECTOR

Sets a logging threshold for Selector operations.

SERVER

Sets a logging threshold for server infrastructure.

SSOTOKEN

Single sign-on token management.

UTILS

Sets a logging threshold for utility classes.

WEB

Sets a logging threshold for the Web server plug-in interface.

XML

Sets a logging threshold for the XML Infrastructure.


7.7.2 Configuring a Log Level Threshold for a Function or Module

The following procedure describes how to configure a function- or module-specific log level threshold.

To configure a module-specific log threshold

  1. Open the log configuration file in the following location:

    Webgate_install_dir\identity|access\oblix\config

  2. If a ValNameList section with a ListName of MODULE_CONFIG does not already exist in this file, create one that is similar to the following:

    <ValNameList xmlns="http://www.oblix.com" ListName="MODULE_CONFIG">
    </ValNameList>
    

    Place this list after the end tag for the compound list that contains the log handler definitions. If there are comments immediately after this end tag, place the list after the comments.

  3. Between the opening and closing tags of the new ValNameList element, configure one or more NameValPair elements.

    This element contains a ParamName parameter and a Value parameter. See Table 7-8 for the modules that you can supply on the ParamName parameter. See Table 7-1 for values, or you can specify a value of On or Off. The following is an example:

    <NameValPair ParamName="LDAP" Value="LOGLEVEL_TRACE"></NameValPair>
    

    You can specify multiple ValNamePair elements within the ValNameList.

    A complete per-module logging threshold section is illustrated in bold in the following example:

    <!--  ============================================================   --><!--  Configure the Log Level                                        -->
    . . .
    <CompoundList xmlns="http://www.oblix.com" ListName="LOG_CONFIG">
     
    <!-- Write all FATAL logs to the system logger. -->
    <ValNameList xmlns="http://www.oblix.com" ListName="LogFatal2Sys">
         <NameValPair ParamName="LOG_LEVEL" Value="LOGLEVEL_FATAL">
         </NameValPair>
         <NameValPair ParamName="LOG_WRITER" Value="SysLogWriter">
         </NameValPair>
         <NameValPair ParamName="LOG_STATUS" Value="On">
         </NameValPair>
    </ValNameList>
    . . .
    </CompoundList>
    <!--  List of values that can be specified in the module config      -->
    <!--                                                                 -->
    <!--  On - Uses loglevel set in the loglevel threshold               -->
    <!--  Off - No information is logged                                 -->
    <!--  LOGLEVEL_FATAL - serious error, possibly a program halt.       -->
    <!--  LOGLEVEL_ERROR - a transient or self-correcting problem.       -->
    <!--  LOGLEVEL_WARNING - a problem that does not cause an error.     -->
    <!--  LOGLEVEL_INFO - reports the current state of the component.    -->
    <!--  LOGLEVEL_DEBUG1 - basic debugging information.                 -->
    <!--  LOGLEVEL_DEBUG2 - advanced debugging information.              -->
    <!--  LOGLEVEL_DEBUG3 - logs performance-sensitive code.             -->
    <!--  LOGLEVEL_TRACE - used when you need to trace the code path     -->
    <!--  execution or capture metrics. Includes all previous levels.    -->
    <!--                                                                 -->
    <!--  List of modules that can be specified in the module config     -->
    <!--                                                                 -->
    <!--  ALL_MODULES - Applies to all log modules                       -->
    <!--  Specific module name - Applies to specific module              -->
    <!--                                                                 -->
    <!--                                                                 -->
    <!--    <ValNameList                                                 -->
    <!--        xmlns="http://www.oblix.com"                             -->
    <!--        ListName="MODULE_CONFIG">                                -->
    <!--        <NameValPair                                             -->
    <!--            ParamName="CONNECTIVITY"                             -->
    <!--            Value="LOGLEVEL_TRACE"></NameValPair>                -->
    <!--    </ValNameList>                                               -->
     
        <ValNameList xmlns="http://www.oblix.com" ListName="MODULE_CONFIG">
            <NameValPair ParamName="LDAP" Value="LOGLEVEL_TRACE"></NameValPair>
            <NameValPair ParamName="DB_RUNTIME" Value="LOGLEVEL_TRACE">
            </NameValPair>
        </ValNameList>
     
    </CompoundList>
    

7.8 Filtering Sensitive Attributes

As described earlier, you can activate secure logging and expand the default filter list to mask sensitive information from the log file.

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. The following procedure describes how to perform this task. In this example, you are instructed to filter the user's home phone number: display name Home Phone; attribute name homePhone. However, you can filter the attribute of your choice.

Note:

Each value added to FILTER_LIST increases the runtime cost of using Secure Logging.

Oracle recommends that you optimize the use of FILTER_LIST to reduce the runtime cost. For example, rather than adding two ParamName variations (User Password and userPassword), you could use only one. Using Password as the ParamName masks values for User Password, userPassword, and other words that end with Password. Also, instead of including both Home Phone and homePhone in FILTER_LIST, you could simply use Phone.

To add sensitive attributes to the filter list

  1. Open the log configuration file in a text editor:

    Webgate_install_dir\identity|access\oblix\config\oblog_config_wg.xml

  2. In oblog_config_wg.xml:

    1. Confirm that secure logging is active. For example:

      <SimpleList> 
         <NameValPair  
            ParamName="SECURE_LOGGING"
            Value="On"></NameValPair> 
      </SimpleList>
      
    2. Locate the FILTER_LIST parameter at the end of the file. For example:

          <ValNameList xmlns="http://www.oblix.com" ListName="FILTER_LIST">
             <NameValPair ParamName="password" Value="40" />
             <NameValPair ParamName="Password" Value="40" />
             <NameValPair ParamName="response" Value="40" />
             <NameValPair ParamName="Response" Value="40" />
          </ValNameList>
      
    3. Add the display name to mask and the value for the mask length, then add the attribute and the value for the mask length. For example:

             <NameValPair ParamName="Home Phone" Value="300" />
             <NameValPair ParamName="homePhone" Value="300" />
      

      Note:

      For testing, set the LOG_THRESHOLD_LEVEL and LOG_SECURITY_THRESHOLD_LEVEL to TRACE. See Step 6a.
    4. Confirm that LOG_THRESHOLD_LEVEL and LOG_SECURITY_THRESHOLD_LEVEL are at the same level or are consistent with each other, as described in Table 7-4. For example:

      <SimpleList> 
         <NameValPair ParamName="LOG_THRESHOLD_LEVEL" Value="LOGLEVEL_WARNING" /> 
      </SimpleList>
      ...
      <SimpleList> 
         <NameValPair ParamName="LOG_SECURITY_THRESHOLD_LEVEL" Value="LOGLEVEL_
         WARNING" />
      </SimpleList>
      
    5. Save the oblog_config_wg.xml file.

  3. Filtering User Password: Perform the following steps and see "The Filter List":

    In the filter list in oblog_config_wg.xml, add the User Password display name and the corresponding attribute, and set the mask length for each. For example:

        <ValNameList xmlns="http://www.oblix.com" ListName="FILTER_LIST">
          ...
           <NameValPair ParamName="User Password" Value="40" />
           <NameValPair ParamName="userPassword" Value="40" />
        </ValNameList>
    
  4. Test secure logging and filtering of sensitive information as follows:

    1. In the oblog_config_wg.xml file, set the LOG_THRESHOLD_LEVEL and LOG_SECURITY_THRESHOLD_LEVEL to TRACE:

         <NameValPair ParamName="LOG_THRESHOLD_LEVEL" Value="LOGLEVEL_TRACE" /> 
      ...
         <NameValPair ParamName="LOG_SECURITY_THRESHOLD_LEVEL" Value="LOGLEVEL_
         TRACE" />
      
    2. Perform a task that involves the component for which you have configured secure logging. For example:

      Access a resource

      View or modify the value of the attribute in the user's profile: Home Phone (if the filtered attribute is homePhone).

    3. Check the oblog and confirm that the filtered attribute value is masked by a string like ***********.

      Webgate_install_dir/access/oblix/log/oblog.log

    4. In the oblog_config_wg.xml file, reset the LOG_THRESHOLD_LEVEL and LOG_SECURITY_THRESHOLD_LEVEL to the desired level for your enterprise.

    5. Adjust the mask length of filtered attributes if needed in the oblog_config_wg.xml file. For example:

          <NameValPair ParamName="Home Phone" Value="340" />
          <NameValPair ParamName="homePhone" Value="340"/>
      
  5. Repeat Steps 1 through 6 for each component in your deployment with one or more masked attributes.