test

Sun Java System Access Manager 7 2005Q4 Administration Guide

Chapter 13 Logging Service

Sun Java™ System Access Manager 7 2005Q4 provides a Logging Service to record information such as user activity, traffic patterns, and authorization violations. In addition, the debug files allow administrators to troubleshoot their installation.

Log Files

The log files record a number of events for each of the services it monitors. These files should be checked by the administrator on a regular basis. The default directory for the log files is /var/opt/SUNWam/logs for SPARC systems and /var/opt/sun/identity for Linux systems. The log file directory can be configured in the Logging Service by using the Access Manager console.

See How the Logging Feature Works in Sun Java System Access Manager 7 2005Q4 Technical Overview in the Sun Java System Access Manager Technical Overview for a detailed list of the default log file types, the information that is recorded, and log file formats.

For attribute definitions for the Logging Service, see the online help by clicking the Help button in the Access Manager Console.

Access Manager Service Logs

There are two different types of service log files: access and error. Access log files may contain records of action attempts and successful results. Error log files record errors that occur within the Access Manager services. Flat log files are appended with the .error or .access extension. Database column names end with _ERROR or _ACCESS for Oracle databases, or _error or _access for MySQL databases. For example, a flat file logging console events is named amConsole.access, while a database column logging the same events is named AMCONSOLE_ACCESS. The following sections describe the log files recorded by the Logging Service.

Session Logs

The Logging Service records the following events for the Session Service:

The session logs are prefixed with amSSO.

Console Logs

The Access Manager console logs record the creation, deletion and modification of identity-related objects, policies and services including, among others, organizations, organizational units, users, roles, policies and groups. It also records modifications of user attributes including passwords and the addition or removal of users to or from roles and groups. Additionally, the console logs write delegation and data store activities. The console logs are prefixed with amConsole.

Authentication Logs

Authentication component logs user logins and logouts. The authentication logs are prefixed with amAuthentication.

Federation Logs

The Federation component logs federation-related events including, but not limited to, the creation of an Authentication Domain and the creation of a Hosted Provider. The federation logs are prefixed with amFederation.

Policy Logs

The Policy component records policy-related events including, but not limited to, policy administration (policy creation, deletion and modification) and policy evaluation. The policy logs are prefixed with amPolicy.

Agent Logs

The policy agent logs are responsible for logging exceptions regarding log resources that were either allowed or denied to a user. The agent logs are prefixed with amAgent. amAgent logs reside on the agent server only. Agent events are logged on the Access Manager server in the Authentication Logs. For more information on this function, see the documentation for the policy agent in question.

SAML Logs

The SAML component records SAML-related events including, but not limited to, assertion and artifact creation or removal, response and request details, and SOAP errors. The session logs are prefixed with amSAML.

amAdmin Logs

The command line logs record event errors that occur during operations using the command line tools. These include, but are not limited to, loading a service schema, creating policy and deleting users. The command line logs are prefixed with amAdmin.

Logging Features

The Logging Service has a number of special features which can be enabled for additional functionality. They include To Enable Secure Logging, Command Line Logging and Remote Logging.

Secure Logging

This optional feature adds additional security to the logging function. Secure Logging enables detection of unauthorized changes to, or tampering of, the security logs. No special coding is required to leverage this feature. Secure Logging is accomplished by using a pre-registered certificate configured by the system administrator. This Manifest Analysis and Certification (MAC) is generated and stored for every log record. A special "signature" log record is periodically inserted that represents the signature for the contents of the log written to that point. The combination of the two records ensures that the logs have not been tampered with.

ProcedureTo Enable Secure Logging

  1. Create a certificate with the name Logger and install it in the deployment container running Access Manager. See the documentation for the deployment container for details.

  2. Turn on Secure Logging in the Logging Service configuration using the Access Manager console and save the change. The administrator can also modify the default values for the other attributes in the Logging Service.

    If the logging directory is changed from the default (/var/opt/SUMWam/logs), make sure that the permissions are set to 0700. The logging service will create the directory, if it does not exist, but it will create the directory with permissions set to 0755.

    Additionally, if you specify a different directory from the default, you must change the following parameter to the new directory in the web container's server.policy file:

    permission java.io.FilePermission “/var/opt/SUNWam/logs/*”,”delete,write”

  3. Create a file in the AccessManager-base/SUNWam/config directory that contains the certificate database password and name it .wtpass.

    Note –

    The file name and the path to it is configurable in the AMConfig.properties file. For more information see the "Certificate Database" in Appendix A, AMConfig.properties File.

    Ensure that the deployment container user is the only administrator with read permissions to this file for security reasons.

  4. Restart the server.

    The secure log directory should be cleared, as some misleading verification errors may be written to the /var/opt/SUNWam/debug/amLog file when the secure logging was started.

    To detect unauthorized changes or tampering of the security logs, look for error messages that are written by the verification process to /var/opt/SUNWam/debug/amLog. To manually check for tampering, run the VerifyArchive utility. See Chapter 19, The VerifyArchive Command Line Tool for more information.

Command Line Logging

The amadmin command line tool has the ability to create, modify and delete identity objects (organizations, users, and roles, for example) in Directory Server. This tool can also load, create, and register service templates. The Logging Service can record these actions by invoking the -t option. If the com.iplanet.am.logstatus property in AMConfig.properties is enabled (ACTIVE) then a log record will be created. (This property is enabled by default.) The command line logs are prefixed with amAdmin. See Chapter 14, The amadmin Command Line Tool for more information.

Logging Properties

There are properties in the AMConfig.properties file that affect logging output:

com.iplanet.am.logstatus=ACTIVE

This property will enable or disable logging. The default is ACTIVE.

iplanet-am-logging.service.level= level

service is the service's normal debug file name. level is one of the java.util.logging.Level values and denotes the level of detail recorded in the logs. The levels are SEVERE, WARNING, INFO, CONFIG, FINE, FINER, and FINEST. Most services do not record log levels with higher detail than INFO.

Remote Logging

Access Manager supports remote logging. This allows a client application using a host where the Access Manager SDK is installedto create log records on an instance of Access Manager deployed on a remote machine. Remote logging can be initiated in any of the following scenarios:

  1. When the logging URL in the Naming Service of one Access Manager instance points to a remote instance and there is a trust relationship configured between the two, logs will be written to the remote Access Manager instance.

  2. When the Access Manager SDK is installed against a remote Access Manager instance and a client (or a simple Java class) running on the SDK server uses the logging APIs, the logs will be written to the remote Access Manager machine.

  3. When logging APIs are used by Access Manager agents.

ProcedureTo Enable Remote Logging

  1. If using Sun Java System Web Server, the following environment variables need to be set in the server.xml configuration file:

    • java.util.logging.manager=com.sun.identity.log.LogManager

    • java.util.logging.config.file=/AccessManager-base /SUNwam/lib/LogConfig.properties

    • If the Java™ 2 Platform, Standard Edition being used is 1.4 or later, this is accomplished by invoking the following at the command line:

      java -cp /AccessManager-base /SUNWam/lib/am_logging.jar:/AccessManager-base /SUNWam/lib/xercesImpl.jar:/AccessManager-base /SUNWam/lib/xmlParserAPIs.jar:/AccessManager-base /SUNWam/lib/jaas.jar:/AccessManager-base /SUNWam/lib/xmlParserAPIs.jar:/AccessManager-base /SUNWam/lib/servlet.jar:/AccessManager-base /SUNWam/locale:/AccessManager-base/SUNWam/lib/am_services.jar:/ AccessManager-base/SUNWam/lib/am_sdk.jar:/ AccessManager-base/SUNWam/lib/jss311.jar:/ AccessManager-base/SUNWam/lib:.

      -Djava.util.logging.manager=com.sun.identity.log.LogManager

      -Djava.util.logging.config.file=/AccessManager-base /SUNwam/lib/LogConfig.properties <logTestClass>

    • If the Java 2 Platform, Standard Edition being used is earlier than 1.4, this is accomplished by invoking the following at the command line:

      java -Xbootclasspath/a:/AccessManager-base /SUNWam/lib/jdk_logging.jar -cp /AccessManager-base /SUNWam/lib/am_logging.jar:/AccessManager-base /SUNWam/lib/xercesImpl.jar:/AccessManager-base /SUNWam/lib/xmlParserAPIs.jar:/AccessManager-base /SUNWam/lib/jaas.jar:/AccessManager-base /SUNWam/lib/xmlParserAPIs.jar:/AccessManager-base /SUNWam/lib/servlet.jar:/AccessManager-base /SUNWam/locale:/AccessManager-base/SUNWam/lib/am_services.jar:/ AccessManager-base/SUNWam/lib/am_sdk.jar:/ AccessManager-base/SUNWam/lib/jss311.jar:/ AccessManager-base/SUNWam/lib:.

      -Djava.util.logging.manager=com.sun.identity.log.LogManager

      -Djava.util.logging.config.file=/AccessManager-base /SUNwam/lib/LogConfig.properties <logTestClass>

  2. Ensure that the following parameters are configured in LogConfig.properties located in AccessManager-base/SUNWam/lib :

    • iplanet-am-logging-remote-handler=com.sun.identity.

      log.handlers.RemoteHandler

    • iplanet-am-logging-remote-formatter=com.sun.

      identity.log.handlers.RemoteFormatter

    • iplanet-am-logging-remote-buffer-size=1

      Remote logging supports buffering on the basis of the number of log records. This value defines the log buffer size by the number of records. Once the buffer is full, all buffered records will be flushed to the server.

    • iplanet-am-logging-buffer-time-in-seconds=3600

      This value defines the time-out period in which to invoke the log buffer-cleaner thread.

    • iplanet-am-logging-time-buffering-status=OFF

      This value defines whether log buffering (and the buffer-cleaner thread) is enabled. By default this feature is turned off.

    Note –

    Whenever a log file is empty, secure logging may show "verification failure." This is because when the number of created files is equal to the archive size, secure logging will archive from this set and start again. It most instances, you can ignore this error. Once the number of records is equal to the archive size, the error will not be displayed.

Error and Access Logs

Two types of Access Manager log files exist: access log files and error log files.

Access log files record general auditing information concerning the Access Manager deployment. A log may contain a single record for an event such as a successful authentication. A log may contain multiple records for the same event. For example, when an administrator uses the console to change an attribute value, the Logging Service logs the attempt to change in one record. Logging Service also logs the results of the execution of the change in a second record.

Error log files record errors that occur within the application. While an operation error is recorded in the error log, the operation attempt is recorded in the access log file.

Flat log files are appended with the .error or .access extension. Database column names end with _ERROR or _ACCESS. For example, a flat file logging console events is named amConsole.access while a database column logging the same events is named AMCONSOLE_ACCESS or amConsole_access.

The following table provides a brief description of the log file produced by each Access Manager component.

Table 13–1 Access Manager Component Logs

Component  

Log Filename Prefix  

Information Logged  

Session 

amSSO

Session management attributes values such as login time, logout time, timeout limits. 

Administration Console 

amConsole

User actions performed through the administration console such as creation, deletion and modification of identity-related objects, realms, and policies. 

Authentication 

amAuthentication

User logins and logouts. 

Identity Federation 

amFederation

Federation-related events such as the creation of an Authentication Domain and the creation of a Hosted Provider. The federation logs are prefixed with amFederation.

Authorization (Policy) 

amPolicy

Policy-related events such as policy creation, deletion, or modification, and policy evaluation. 

Policy Agent 

amAgent

Exceptions regarding resources that were either accessed by a user or denied access to a user. amAgent logs reside on the server where the policy agent is installed. Agent events are logged on the Access Manager machine in the Authentication logs.

SAML 

amSAML

SAML-related events such as assertion and artifact creation or removal, response and request details, and SOAP errors. 

Command-line 

amAdmin

Event errors that occur during operations using the command line tools. Examples are: loading a service schema, creating policy, and deleting users. 

See Appendix C, Log File Reference for list and description of the Access Manager log files.

Debug Files

The debug files are not a feature of the Logging Service. They are written using different APIs which are independent of the logging APIs. Debug files are stored in /var/opt/SUNWam/debug. This location, along with the level of the debug information, is configurable in the AMConfig.properties file, located in the AccessManager-base/SUNWam/lib/ directory. For more information on the debug properties, see Appendix A, AMConfig.properties File.

Debug Levels

There are several levels of information that can be recorded to the debug files. The debug level is set using the com.iplanet.services.debug.level property in AMConfig.properties.

  1. Off—No debug information is recorded.

  2. Error—This level is used for production. During production, there should be no errors in the debug files.

  3. Warning—Currently, using this level is not recommended.

  4. Message—This level alerts to possible issues using code tracing. Most Access Manager modules use this level to send debug messages.

    Note –

    Warning and Message levels should not be used in production. They cause severe performance degradation and an abundance of debug messages.

Debug Output Files

A debug file does not get created until a module writes to it. Therefore, in the default error mode no debug files may be generated. The debug files that get created on a basic login with the debug level set to message include:

The most often used files are the amSDK, amProfile and all files pertaining to authentication. The information captured includes the date, time and message type (Error, Warning, Message).

Using Debug Files

The debug level, by default, is set to error. The debug files might be useful to an administrator when they are:

The debug files should go hand in hand with any troubleshooting guide we might have in the future. For example when SSL fails, someone might turn on debug to message and look in the amJSS debug file for any specific certificate errors.

Multiple Access Manager Instances And Debug Files

Access Manager contains the ammultiserverinstall script that can be used to configure numerous instances of the server. If the multiple server instances are configured to use different debug directories, each individual instance has to have both read and write permissions to the debug directories.