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.


Note The API can reside on the same server as the service or on a remote one. If the Logging interfaces are remote, the Communication Component (PLL) is used to send the request to 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

  • Number of History Files

  • Log Location

  • Logging Type

  • Database User Name

  • Database User Password

  • Database Driver Name

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.

    Code Example 6-1    File Formatted Log Record Sample
    &&TIME=2002/04/25 13:24:47
    PDT&&DOMAIN=o=iplanet.com&&LOGINID=uid=amAdmin,ou=People,o=iplan et.com&&

    TYPE=amConsole&&DATA=Registered service iPlanetAMAuthService


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: Code Example 6-2    Database Message Format
TIME

VARCHAR(200)

Date (yyyy/mm/dd hh:mm:ss)

DOMAIN

VARCHAR(100)

User's DSAME Organization

LOGINID

VARCHAR(50)

Login User's ID.

TYPE

VARACHAR(20)

Application type.

DATA

VARCHAR(300)

Message to be logged.



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:

  • ConnectionException—This exception is thrown when the connection to the database fails.

  • DriverLoadException—This exception is thrown when the JDBC driver load fails.

  • InvalidLogNameException—This exception is thrown when the log name is invalid.

  • LogAlreadyExistException—This exception is thrown when the log already exists.

  • LogCreateException—This exception is thrown when log creation fails.

  • LogDeleteException—This exception is thrown when the log deletion fails.

  • LogException—A LogException is thrown when applications are denied log access because they don't have the privileges or a valid session.

  • LogFatalException—This exception is thrown when a fatal error occurs.

  • LogHandlerException—A LogException is thrown when a log handler error is encountered.

  • LogInactiveException—A LogException is thrown when the log is in inactive status. (Inactive/active status is not currently supported.)

  • LogInvalidSessionException—This exception is thrown when an application accesses a log which does not exist.

  • LogNotFoundException—This exception is thrown when an application accesses a log which does not exist.

  • LogPrivDeniedException—A LogException is thrown when the access privilege is denied.

  • LogProfileException—A LogException is thrown when access privilege is denied.

  • LogReadExceedsMaxException—A LogException is thrown when the log size exceeds the maximum size defined in the Logging service.

  • LogReadException—A LogException is thrown when an error is encountered in retrieving the log information.

  • LogTypeException—This exception is thrown when a log type error occurs.

  • LogWriteException—This exception is thrown when the log record submission fails.

  • NullLocationException—This 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.

Code Example 6-3    Logging API Sample
LogManager lm = new LogManager(SampleSSOSession);

try {
lm.create("SampleLog");
}
} catch (Exception e) {
System.out.println("Error: " + e.getMessage();
}

try {
LogRecord lr = new LogRecord("SampleType", "SampleData");
log.write(lr, "SampleLog");
} catch(Exception e) {
System.out.println("Error: " + e.getMessage());
}



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

  • Logout

  • Session Idle TimeOut

  • Session Max TimeOut

  • Failed To Login

  • Session Reactivation

  • Session Destroy

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