Previous Contents Index Next |
Directory Server Access Management Edition Programmer's Guide |
Chapter 6 Logging
The iPlanet Directory Server Access Management Edition (DSAME) provides a logging module as a means of recording information such as user activity, traffic patterns, and authorization violations. In addition, DSAME includes a Logging API so that applications can take advantage of the logging function. This chapter explains the component and the API. It contains the following sections:
Overview
The Logging component enables all DSAME services to record information that might be useful to an administrator. This allows tracking of who is accessing what resources in one centralized location. It accepts requests to provide logging operations which include writing messages to logs, reading logs, listing log files and deleting log files. Examples of information logged might include user access denials and approvals, traffic patterns, authorization violations and code exceptions. The component allows logs to be written to either a relational database or flat files. It contains the following modules:
A Logging service which contains the configuration parameters for the logging function and accepts and processes logging requests.
Java API which can be integrated into Java applications in order to allow them to access the Logging service.
Logging Architecture
An application accesses the Logging service by calling the Logging API. Upon receiving a request, the Logging service loads the configuration data stored in the LDAP DS using the DSAME SDK. (This information might include the log format, the log's maximum size and the log's location.) Any exception message will be logged, based on these configuration values. On an error, a LoginException is thrown by the Logging service.
Logging Service
The Logging service holds the attributes and values for the DSAME logging function. The values are applied across the configuration and are inherited by every configured organization. The Logging Attributes are:
Max Log Size
More information on these attributes and the Logging service can be found in the iPlanet Directory Server Access Management Edition Administration Guide.
Log Message Formats
DSAME supports both flat-file based logging and JDBC logging. Log records can be stored in either a flat file or in a table of a relational database. The following sections explain the formats of both record types.
File Format
The Logging service uses DATE/TIME&&Domain&&LoginID&&Type&&DATA to log messages. This format is explained below. Code Example 6-1 below illustrates how a log record formatted for a file would look.
TIME is the date (yyyy/mm/dd) and time (hh:mm:ss) at which the log message was recorded.
DOMAIN is the DSAME organization to which the user belongs.
LOGINID is the ID of the user attempting to access the application.
TYPE is the application writing the log.
DATA is the description of the user activity, errors or other useful information which the application wants to log.
Database Format
For applications using a relational database to log messages, the message is stored in a database table.
Note There is a limitation in the log name length for Oracle JDBC logging: the length of the log name cannot exceed 30 characters. Oracle does not support names longer than 30 characters.
The database schema is as follows:
Logging API
The Logging API provides log management tools for DSAME services as well as providing a set of Java classes for applications to create, retrieve, submit, or delete log information. The API can be used, for instance, to develop log auditing capabilities. The main classes are LogManager and LogRecord. They are contained in the package com.iplanet.log.
Note The Overview page for the complete set of public Javadocs can be accessed at Install_Directory/SUNWam/docs/index.html.
LogManager Class
This LogManager class provides the methods for applications to use in creating, retrieving, submitting, and deleting log information. It also provides a method to access a list of log names that have been created by all the applications. This class provides methods and must be instantiated in order to use the LogRecord class.
The Create() method creates a log in the designated logging location.
The Write() method records a single piece of log information or a LogRecord. It allows an application to submit a logging message to a predetermined log.
LogRecord Class
The class LogRecord class provides the means to represent the information that needs to be logged. Each instantiation represents a single piece of log information or LogRecord. This information comes from the application. This class provides two methods and must be instantiated in order to use the LogRecord class.
The getRecType() method retrieves the log type or key of a single log record.
The getRecMsg() method retrieves the log data or value of a single log record.
Logging Exceptions
There are a number of exceptions that can be thrown using the Logging APIs. The generic LogException is probably the most common. It signals an error condition while logging a message. Other exceptions include:
ConnectionExceptionThis exception is thrown when the connection to the database fails.
DriverLoadExceptionThis exception is thrown when the JDBC driver load fails.
InvalidLogNameExceptionThis exception is thrown when the log name is invalid.
LogAlreadyExistExceptionThis exception is thrown when the log already exists.
LogCreateExceptionThis exception is thrown when log creation fails.
LogDeleteExceptionThis exception is thrown when the log deletion fails.
LogExceptionA LogException is thrown when applications are denied log access because they don't have the privileges or a valid session.
LogFatalExceptionThis exception is thrown when a fatal error occurs.
LogHandlerExceptionA LogException is thrown when a log handler error is encountered.
LogInactiveExceptionA LogException is thrown when the log is in inactive status. (Inactive/active status is not currently supported.)
LogInvalidSessionExceptionThis exception is thrown when an application accesses a log which does not exist.
LogNotFoundExceptionThis exception is thrown when an application accesses a log which does not exist.
LogPrivDeniedExceptionA LogException is thrown when the access privilege is denied.
LogProfileExceptionA LogException is thrown when access privilege is denied.
LogReadExceedsMaxExceptionA LogException is thrown when the log size exceeds the maximum size defined in the Logging service.
LogReadExceptionA LogException is thrown when an error is encountered in retrieving the log information.
LogTypeExceptionThis exception is thrown when a log type error occurs.
LogWriteExceptionThis exception is thrown when the log record submission fails.
NullLocationExceptionThis exception is thrown when the location is null.
Sample Logging Code
Code Example 6-3 below provides sample code that shows how to use the DSAME logging classes discussed above.
Recorded Events
By default, DSAME currently logs events in three logs:
SSO-related Logs
The Logging component logs the following events for the SSO component:
Login
The log is called amSSO.
Console-related Logs
The Logging component records the creation, deletion and modification of identity-related objects, policies and service including, among others, Organization, Organizational Unit, User, Role, Policy and Group. It also records modification of all user attributes including password and the addition or removal of users to or from roles and groups, respectively. The log is called am Console.
Note The Web Agents are responsible for logging exceptions related to resource access or denial; in other words, policy. For more information, see the Web Agent documentation.
Authentication-related Logs
The Logging component logs the events for the Authentication component. The log is called am Authentication.
Previous Contents Index Next
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.
Last Updated May 14, 2002