| Oracle® Access Manager Identity and Common Administration Guide 10g (10.1.4.3) Part Number E12489-01 |
|
|
View PDF |
| Oracle® Access Manager Identity and Common Administration Guide 10g (10.1.4.3) Part Number E12489-01 |
|
|
View PDF |
An Oracle Access Manager component instance 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.
This chapter provides the following sections:
Note:
For an overview of other reporting features, including system event auditing, diagnostics, and SNMP monitoring, see "Reporting".The logging feature enables you to analyze system performance and health, and to troubleshoot issues.
You can configure logging for individual instances of the following components:
Access Servers
Identity Servers
Policy Managers
WebPass instances
WebGates
Custom AccessGates (Access Manager SDK)
Custom plug-ins
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: Oracle 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 component. For Identity Servers only, you can also set some parameters for logging in the Identity System Console. 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.
Logging Performance: For analysis of performance issues, the logs can capture data on the amount of time it takes to perform specific operations. See "Logging the Amount of Time to Process Requests" for details.
The rest of this section discusses the following topics:
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 10-5 describes the levels. The default log level is Warning: LOGLEVEL_ WARNING.
| Level | Number of Events Reported | Description |
|---|---|---|
|
|
> 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. |
|
|
> 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. |
|
|
> 1200 |
Records issues that may lead to an error or require corrective action in the future. |
|
|
> 400 |
Records completed actions or the current state of a component, for example, the component is initializing. |
|
|
> 400 |
Records debugging information. Typically, the information at this level is only meaningful to a developer. |
|
|
> 100 |
Records advanced debugging information. This level augments the Debug1 log level. Typically, the information at this level is only meaningful to a developer. |
|
|
> 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. |
|
|
> 900 Oracle 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. |
|
|
> 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, Logging Threshold, and Identity System Console Synchronization" 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".If you have enabled logging for a component instance and the instance crashes, Oracle Access Manager writes stack trace information to the log files. You can also generate stack traces on demand.
See "Capturing Diagnostic Information" for details.
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 leftmost 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".
See Also:
"Log Configuration File Contents"You configure parameters that control 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:
Each Oracle Access Manager component has a log configuration file where you 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".
Log configuration files reside in the following location:
component_install_dir\identity|access\oblix\config
Here component_install_dir is the directory where you installed the component, and identity|access refers to either the Identity System or Access System. Do not change the path to this file. If you install more than one instance of a component, for example, if you install multiple Identity Servers, a log configuration file is installed for each instance.
After installation, oblog_config.xml and oblog_config_original.xml both contain comments. After making logging configuration changes using the Identity System Console, data from the directory server is written to oblog_config.xml. During this process, comments in this file are lost. However, oblog_config_original.xml remains unchanged and so that you can refer to the original comments.
Table 10-2 lists the names of the log configuration files. Do not change the names.
Table 10-2 Log Configuration File Names for Components
| Component | Log Configuration FIle Name |
|---|---|
|
Access Server |
oblog_config.xml |
|
Identity Server |
oblog_config.xml |
|
Policy Manager |
oblog_config_am.xml |
|
WebGate |
oblog_config_wg.xml |
|
WebPass |
oblog_config_wp.xml |
|
Access Manager SDK (custom AccessGate) |
oblog_config.xml |
Important:
Do not change the default path or name for any logging configuration file.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.
For Identity Servers only, you can also modify configuration parameters in the log file through the Identity System console, provided that the AUTOSYNC parameter in the configuration file is set to the default value, True. See "Configuring Logs in the Identity System Console" for details.
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.
For Identity Servers, if you modify the logging settings using the Identity System Console, the changes are written to the log configuration file if the AutoSync parameter in the file is set to True. If this parameter is set to False, the old configuration file are reinstated after the server is restarted.
Each default log configuration file contains comments that are intended to assist with editing the file. The commented default configuration file is:
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 10-1 shows a typical log configuration file with comments. Example 10-8 shows an example of a log file without comments.
Example 10-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, Access Manager and WebPass 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>
Note:
If you modify logging settings in the Identity System Console, the log configuration file for the associated component instance is saved without comments. See "Configuring Logs in the Identity System Console" for details.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 10-3.
Table 10-3 Log Writers
| Writer | Description |
|---|---|
|
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. |
|
|
This writer is recommended when you want to save log data for an Access Server, Identity 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. |
|
|
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 AccessGate installed on a multi-process Web server (such as Apache) or the Solaris version of the iPlanet Web server. |
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 10-1 or Example 10-8 for a listing of the default log configuration file.
The rest of this section discusses the following topics:
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.
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.
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 10-4 Global Parameters in the First Compound List
| Parameter | Description |
|---|---|
|
Sets the default logging threshold. Default value: 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. |
|
|
Determines if logging configuration that is performed in the Identity System Console is written to the log configuration file. Default value: True Possible Values: True or False |
|
|
|
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 "About 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. 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". |
Example 10-2 shows the simple lists containing global settings, which appear in the first compound list in the oblog_config.xml file.
Example 10-2 Simple Lists with Global Settings (First Compound List in oblog_config.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>
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 10-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 10-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 10-7 for details:
A destination file name, as follows:
<NameValPair ParamName="FILE_NAME" Value="oblog.log" />
<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.
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 Oracle 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 10-3.
Example 10-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.
If you filter the user password in Identity Server or WebPass logs, you must ensure that WebGate is disabled. When you disable WebGate, Form authentication is used automatically with a pre-configured login page. In this case, you do not need to create a separate HTML login page nor configure form-based authentication. For more information, see "Filtering Sensitive Attributes".
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 10-4 and Example 10-5 are equivalent:
Example 10-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 10-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 10-6 and Example 10-7 are equivalent:
Several factors determine if logging is active for a particular log-handler. Table 10-5 lists these factors.
Table 10-5 Factors that Determine Whether Logging Is Active
| Factor | Importance | Description |
|---|---|---|
|
Primary |
This parameter sets a cutoff for logging. Any log level that is more detailed than the threshold is suppressed. See Table 10-1 for valid log levels. You override this parameter for a subset of items that can be logged using the For Identity Servers only, you can also configure the threshold in the Identity System Console. See "Configuring Logs in the Identity System Console" for details. |
|
|
|
Primary |
This sets a per-module override for the global logging threshold. See "Configuring Different Threshold Levels for Different Types of Data" for details. |
|
Secondary |
This parameter toggles logging on or off, as long as it is not overridden by the logging threshold or a module-specific override. |
|
|
Secondary |
When this parameter is set to When |
|
|
The physical position of a log handler |
Secondary |
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 10-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.
At minimum, each log-handler definition contains five parameters listed in Table 10-6.
Table 10-6 Mandatory Log Configuration File Parameters
| Parameter | Comment |
|---|---|
|
This parameter is specified in the opening 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:
|
|
|
This parameter is specified in the opening When creating a new log-handler definition, select a memorable name that you cannot confuse with other log handlers. Examples:
|
|
|
This specifies a log level. See Table 10-1 for details. The default logging configuration file activates logging for three levels: Fatal, Error, and Warning. |
|
|
This specifies the destination for log output for this log-handler. See Table 10-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. |
|
|
This parameter turns the log handler |
If you specify FileLogWriter or MPFileLogWriter as the value for the LOG_WRITER parameter, the four parameters in Table 10-7 are relevant.
Table 10-7 Log Data File Configuration Parameters
| Parameter | Description | Default |
|---|---|---|
|
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 |
|
|
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) |
|
|
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) |
|
|
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) |
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 Oracle 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 10-8 shows the default log configuration file with comments removed to expose the file structure.
Example 10-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.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>
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:
It sets the LOG_THRESHOLD_LEVEL to Warning.
The threshold suppresses logging for levels that are more fine-grained than Warning. You can override this threshold. See "Configuring Different Threshold Levels for Different Types of Data" for details.
The simple list also sets the AUTOSYNC parameter to True.
If set to True, this setting enables you to save values that you set in the Identity System console to this configuration file so that they persist after you restart the Identity Server. This parameter applies only to Identity Servers.
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.
For Identity Servers only, you can modify certain log settings through the Identity System Console. Alternatively, you can edit the log configuration file manually.
Note:
Secure logging parameters are configured only in the oblog_config.xml file. For more information, see "Filtering Sensitive Attributes".If you modify logging settings in the Identity System Console, the log configuration file for the associated component instance is saved without comments. To view the original comments, open the following read-only duplicate of the original configuration file:
IdentityServer_install_dir/oblix/config/oblog_config_original.xml
Where IdentityServer_install_dir is the root installation folder for your Identity Server.
To view or modify log-handler definitions
From the Identity System landing page, click the Identity System Console link.
If you are already logged in, click the Identity System Console tab.
From the Identity System Console, click the System Configuration sub-tab, then click the Identity Servers link in the left navigation pane.
The List of All Identity Servers page appears.
Click the link for the Identity Server whose activity you want to log.
The Details for Identity Server page appears with a list of log-handler definitions at the bottom of the page.
Examine the Log Threshold setting above the Log Handler Definitions table. This represents the current LOG_THRESHOLD_LEVEL.
To change this setting, click Modify at the bottom of the page and proceed to "To modify the log threshold from the Identity System Console". Otherwise, continue to the next step.
In the table of log-handler definitions, click the link for the log handler you want to examine or change.
The Modify the Log Handler Definition page appears. From this page, you can specify values as described in Table 10-6. If you specify File in the Output To field, you must complete the fields described in Table 10-7.
You can change the defaults for the log file name, log file maximum size, log file rotation interval, and log buffer maximum size, as listed in Table 10-7.
Click Save.
To modify the log threshold from the Identity System Console
From the Identity System Console, click the System Configuration sub-tab, then click Identity Servers in the left navigation pane.
Click the name of the Identity Server whose settings you want to examine.
Click Modify at the bottom of the Details of the Identity Server page.
Use the list to set the Log Threshold Level to the value you want.
Click Save.
The change takes effect immediately. If AUTOSYNC is True in the log configuration file, the change is written to the log configuration file so that the change persists after you restart the server.
To add or delete a log-handler definition from the Identity System Console
From the Identity System Console, click the System Configuration sub-tab, then click the Identity Server link in the left navigation pane.
Click the name of the Identity Server to which you want to add a log-handler definition.
Click Modify at the bottom of the page.
The Modify Identity Server page appears.
Under Log Handlers Definition, complete the appropriate action:
To delete a log output configuration, check the box next to the appropriate link, then click Delete.
To add a log writer, click Add.
If you click Add, the Add a New Log Writer page appears.
Supply a name and a log level for the new log writer.
Verify that the log level is the same as or higher than the current log threshold level, as described in "To view or modify log-handler definitions".
If the new log level is lower than the current threshold level, set the threshold level to the new log level or lower, as detailed in "To modify the log threshold from the Identity System Console".
If you choose to output to a file rather than the system log, you must supply a file name and path, as described in Table 10-7.
Click Save.
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 Oracle 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.xml file. The MODULE_CONFIG section 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:
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 10-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 10-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.
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.
Table 10-8 describes the a partial list of the values that you can specify for the ParamName parameter in the MODULE_CONFIG list.
Table 10-8 ParamName Values You Can Configure for Per-Module Logging Threshold
| ParamName Value | Logging Threshold That This Parameter Sets |
|---|---|
|
|
Sets a logging threshold for triggered actions that are configured as part of a policy in the Access System. <ValNameList xmlns="http://www.oblix.com"
ListName="MODULE_CONFIG">
<NameValPair Paramname="AAA_ACTIONS" Value="OFF">
</NameValPair>
See the Oracle Access Manager Access Administration Guide for details. |
|
|
Sets a logging threshold for activity performed by the Access Manager engine. See the Oracle Access Manager Access Administration Guide for details. |
|
|
Sets a logging threshold for all Access System activities related to determining if a resource operation is protected. See the Oracle Access Manager Access Administration Guide for details. |
|
|
Sets a logging threshold for operations performed by an access client, that is, an AccessGate or WebGate. See the Oracle Access Manager Access Administration Guide for details. |
|
|
Sets a logging threshold for operations performed by an AccessGate. See the Oracle Access Manager Access Administration Guide for details. |
|
|
Sets a logging threshold for operations performed by the Policy Manager. See the Oracle Access Manager Access Administration Guide for details. |
|
|
Sets a logging threshold for operations performed by the Access Manager SDK interface. See the Oracle Access Manager Developer Guide for details. |
|
|
Sets a logging threshold for operations performed in the Access Server. See the Oracle Access Manager Access Administration Guide for details. |
|
|
Sets a logging threshold for the Access Manager SDK. See the Oracle Access Manager Developer Guide for details. |
|
|
Sets a logging threshold for auditing. See "Auditing" for details. |
|
|
Sets a logging threshold for user authentication operations. See the Oracle Access Manager Access Administration Guide for details. |
|
|
Sets a logging threshold for authentication scheme management. See the Oracle Access Manager Access Administration Guide for details. |
|
|
Sets a logging threshold for operations performed by an authentication plug-in. See the Oracle Access Manager Access Administration Guide for details. |
|
|
Sets a logging threshold for user authorization operations. See the Oracle Access Manager Access Administration Guide for details. |
|
|
Sets a logging threshold for authorization scheme management. See the Oracle Access Manager Access Administration Guide for details. |
|
|
Sets a logging threshold for authorization plug-in operations. See the Oracle Access Manager Access Administration Guide for details. |
|
|
Sets a logging threshold for cache management and operations on the caches. |
|
|
Sets a logging threshold for connection management. |
|
|
Sets a logging threshold for connection run time. |
|
|
Sets a logging threshold for client-sever connectivity and messaging. |
|
|
Sets a logging threshold for the data store interface layer configuration. |
|
|
Sets a logging threshold for the data store interface layer run time. |
|
|
Sets a logging threshold for the diagnostic framework. |
|
|
Sets the threshold for logging accesses of Group Manager data in the directory. |
|
|
Sets the threshold for logging Group Manager operations. |
|
|
Sets the threshold for logging HTTP request processing. |
|
|
Sets the threshold for logging IDXML operations. See the Oracle Access Manager Developer Guide for details. |
|
|
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>
|
|
|
Sets the threshold for logging Lost Password Management. See "Lost Password Management" for details. |
|
|
Sets a logging threshold for network APIs. |
|
|
Sets a logging threshold for ObMyGroups processing. This refers to searches of groups where the person who initiated the search is a member. |
|
|
Sets a logging threshold for the Identity client. |
|
|
Sets a logging threshold for the Identity Server engine. |
|
|
Sets a logging threshold for Identity System management. |
|
|
Sets a logging threshold for operations performed by an Identity Server. |
|
|
Sets a logging threshold for operations performed in the Organization Manager. |
|
|
Sets a logging threshold for policy and policy domain management. |
|
|
Sets a logging threshold for Identity Event Plug-in API operations. See the Oracle Access Manager Developer Guide for details. |
|
|
Sets a logging threshold for Query Builder operations. |
|
|
Sets a logging threshold for the time consumed by all calls. See "Logging the Amount of Time to Process Requests" for details. |
|
|
Sets a logging threshold for the security and encryption library. |
|
|
Sets a logging threshold for Selector operations. |
|
|
Sets a logging threshold for server infrastructure. |
|
|
Sets a logging threshold for SNMP activity. See "SNMP Monitoring" for details. |
|
|
Single sign-on token management. |
|
|
Sets a logging threshold for administrative operations in the User Manager. |
|
|
Sets a logging threshold for the Uidinfo cache. |
|
|
Sets a logging threshold for operations performed in the User Manager. |
|
|
Sets a logging threshold for IDXML calls to the user service center (the User Manager). |
|
|
Sets a logging threshold for searches of user information in the directory. |
|
|
Sets a logging threshold for utility classes. |
|
|
Sets a logging threshold for the Web server plug-in interface. |
|
|
Sets a logging threshold for workflow execution. See "Chaining Identity Functions Into Workflows" for details. |
|
|
Sets a logging threshold for workflow configuration and management. See "Chaining Identity Functions Into Workflows" for details. |
|
|
Sets a logging threshold for the XML Infrastructure. |
The following procedure describes how to configure a function- or module-specific log level threshold.
Note:
The following example shows a log configuration file with extended comments regarding per-module logging thresholds. If you have installed the 10.1.4.2 patch release, these comments do not appear in this file.To configure a module-specific log threshold
Open the log configuration file in the following location:
component_install_dir\identity|access\oblix\config
Where component_install_dir is the directory where you installed the component for which you want to configure logging, and identity|access refers to the designation for either the Identity System or Access System, respectively.
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.
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 10-8 for the modules that you can supply on the ParamName parameter. See Table 10-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>
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 use only "Phone".
If you choose to filter User Password from Identity Server and WebPass logs, you must disable the WebGate as described in the following procedure. If you are not filtering User Password, you can skip the related step.
See Also:
To add sensitive attributes to the filter list
Locate the display name and attribute name to filter in the Identity System Console: Click Common Configuration, and then click Object Classes.
Modify attributes and corresponding display names as follows:
Click the configured person object (genSiteOrgPerson, for example).
Click the Modify Attributes button.
Scroll to locate the desired attributes and corresponding display names.
On the Modify Attributes page, check the lists for the attribute display names you want to add to the filter list in Step 6. For example:
Attribute: homePhone
Display Name: Home Phone
Open the appropriate log configuration file in a text editor:
component_install_dir\identity|access\oblix\config\oblog_config.xml
Where component_install_dir is the directory where you installed the component for which you want to configure secure logging.
In oblog_config.xml:
Confirm that secure logging is active. For example:
<SimpleList>
<NameValPair
ParamName="SECURE_LOGGING"
Value="On"></NameValPair>
</SimpleList>
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>
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 theLOG_THRESHOLD_LEVEL and LOG_SECURITY_THRESHOLD_LEVEL to TRACE. See Step 6a.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 10-4. For example:
<SimpleList> <NameValPair ParamName="LOG_THRESHOLD_LEVEL" Value="LOGLEVEL_WARNING" /> </SimpleList> ... <SimpleList> <NameValPair ParamName="LOG_SECURITY_THRESHOLD_LEVEL" Value="LOGLEVEL_ WARNING" /> </SimpleList>
Save the oblog_config.xml file.
Filtering User Password: Perform the following steps and see "The Filter List":
In the filter list in oblog_config.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>
Disable WebGate: From the Access System Console, click the Access System Configuration tab, click AccessGate Configuration, search for the WebGate and click the name link, locate State on the configuration page and click Disabled, then save the change.
For more information about filtering the user password, see "The Filter List". For more information about WebGate configuration, see the Oracle Access Manager Access Administration Guide.
Log in to the Identity System.
Test secure logging and filtering of sensitive information as follows:
In the oblog_config.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" />
In the user profile, confirm that the attribute to be filtered contains a value. For example:
From the Identity System Console, click User Manager.
In the User Manager, click My Profile.
In your profile, locate the attribute and confirm there is an entry.
Perform a task that involves the component for which you have configured secure logging. For example:
Access a resource, if you configured secure logging for the Access Server.
View or modify the value of the attribute in the user's profile: Home Phone (if the filtered attribute is homePhone).
Check the oblog and confirm that the filtered attribute value is masked by a string like ***********.
component_install_dir/identity|access\oblix/log/oblog.log
For example, if you implemented secure logging for the Access Server, the User Password value is masked in the Access Server log file. If you view or modify the value of the attribute in the user's profile (Home Phone, for example) the Home Phone value is masked by *********** in the Identity Server log file.
In the oblog_config.xml file, reset the LOG_THRESHOLD_LEVEL and LOG_SECURITY_THRESHOLD_LEVEL to the desired level for your enterprise.
Adjust the mask length of filtered attributes if needed in the oblog_config.xml file. For example:
<NameValPair ParamName="Home Phone" Value="340" />
<NameValPair ParamName="homePhone" Value="340"/>
Repeat Steps 1 through 6 for each component in your deployment with one or more masked attributes.
For capacity planning and performance tuning purposes, you can log the time it takes to process calls to external components. For example, when performing capacity planning, you may want to know what calls to the directory server are taking the most time. After identifying these calls, you can ask your directory administrator to set up appropriate indexes. Or, you can analyze the client IP addresses to determine what components are handling the most calls. The logs can indicate if an Identity Server is receiving calls from multiple high-traffic WebPass instances. If the calls from the IP address for internal users is much higher than the calls from the IP address for external users, you can add more Identity Servers for internal users.
When reviewing logs of request processing times, you can also determine what servers are implicated when more time is taken than expected. These logs capture the IP address of the Web component that makes the request. Additionally, these logs show the size of various request queues, which can also indicate where there are performance bottlenecks.
The rest of this section discusses the following topics:
Table 10-9 lists the calls that are captured in the request timing logs:
Table 10-9 List of Calls to External Components That Are Written to the Logs
| Component | Calls That Are Logged |
|---|---|
|
Identity Server and Access Server |
|
|
Identity Server-specific |
|
|
Access Server-specific |
|
Each request timing log consists of four lines of output, as shown in Table 10-10. Items of particular interest in this table include the following:
In the third line, if you notice that a particular WebPass or WebGate is the requesting party most of the time, this can give you insight into where you might need to redistribute the load.
The fourth line shows the time spent on different types of calls and the frequency of the call type.
The information on this line can indicate what types of requests are taking the longest.
Table 10-10 illustrates an example of a REQUEST_TIMINGS entry in the LOGLEVEL_INFO log. Note that "OIS" is a freqently-used abbreviation for the Identity Server and "PPP" is a frequently-used abbreviation for an Identity System plug-in.
Table 10-10 Annotated Example of a REQUEST_TIMINGS Call in the Log Output
| Line | Contents and Explanation |
|---|---|
|
First line |
The first line indicates the program that has initiated the request, as illustrated in the following example: 2007/06/01@01:13:50.125000 5932 4892 REQUEST_TIMINGS INFO 0x0000093A obmessagechannel.cpp:410 "Request Received" _seqno^38 _opcode^12 _program^workflowSaveCreateProfile |
|
Second line |
The second line indicates that the request was taken from the request queue for processing. This line prints a log message and shows the wait time, which is the amount of time the request spent in the request queue before being processed. If you follow the 2007/06/01@01:13:50.125000 5932 3980 REQUEST_TIMINGS INFO 0x0000093B servicethread.cpp:109 "Request started executing" Waiting time for the Request^0.000769 MessageThreadID^4892 _seqno^38 _opcode^12 |
|
Third line |
The third line shows that the request is being processed, and it provides the IP address of the WebPass or WebGate that issued the request. This line prints a log message, and may display the IP address of the requesting client, as shown in the following example: 2007/06/01@01:13:50.125000 5932 3980 REQUEST_TIMINGS INFO 0x0000093C data\module_main.cpp:614 "Request is being executed" _programName^workflowSaveCreateProfile _ClientIP^111.11.11.111 |
|
Fourth line |
The fourth line contains the frequency and time consumed by LDAP calls, audit calls, plug-in calls, and flush calls, in addition to the queue size, as shown in the following example: 2007/06/01@01:13:52.812000 5932 3980 REQUEST_TIMINGS INFO 0x0000093D servicethread.cpp:143 "Processing time for this request" queue size^0 MessageThreadID^4892 _seqno^38 _opcode^12 Total_Dura^2.687061 LdapAllCalls_Freq^55 LdapAllCalls_Dura^0.014618 LdapAddCalls_Freq^9 LdapAddCalls_Dura^0.001843 LdapDeleteCalls_Freq^0 LdapDeleteCalls_Dura^0.000000 LdapSearchCalls_Freq^28 LdapSearchCalls_Dura^0.010169 LdapModifyCalls_Freq^4 LdapModifyCalls_Dura^0.001000 LdapBindCalls_Freq^1 LdapBindCalls_Dura^0.000155 LdapGetDNCalls_Freq^13 LdapGetDNCalls_Dura^0.001452 LdapOtherCalls_Freq^0 LdapOtherCalls_Dura^0.000000 AuditDBCall_Freq^0 AuditDBCall_Dura^0.000000 PPPPluginCall_Freq^0 PPPPluginCall_Dura^0.000000 OIS2OISflush_Freq^0 OIS2OISflush_Dura^0.000000 OIS2AAACALL_Freq^0 OIS2AAACALL_Dura^0.000000 |
You capture logs of request processing times on a per-module basis. To do this, you add the REQUEST_TIMINGS parameter to the MODULE_CONFIG section of the log configuration file. The following procedure describes how to capture only request processing times in the logs.
Note:
The following example shows a log configuration file with extended comments regarding per-module logging thresholds. If you have installed the 10.1.4.2 patch release, these comments do not appear in this file.To log the time taken to process external requests
Open the following file:
component_install_dir\identity|access\oblix\config\oblog_config.xml
Where component_install_dir is the directory where you installed the component, for example, the Identity Server.
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.
To restrict the information written to the logs to only the time consumed by different types of calls, in the MODULE_CONFIG section, add a listing that contains the REQUEST_TIMINGS parameter, as illustrated in bold in the following example.
See "Configuring Different Threshold Levels for Different Types of Data" for details on the MODULE_CONFIG section.
<!-- ============================================================ --><!-- 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> -->
<!-- Write only REQUEST_TIMINGS logs when when using LOGLEVEL_INFO. -->
<ValNameList xmlns="http://www.oblix.com" ListName="MODULE_CONFIG">
<NameValPair ParamName="REQUEST_TIMINGS" Value="LOGLEVEL_INFO">
</ValNameList>
</CompoundList>
|
 Copyright © 2000, 2009, Oracle. All rights reserved. Legal Notices |
|