4.2 Access Gateway Service Logs

The Access Gateway Service logs contain the messages sent between the Access Gateway Service and the Embedded Service Provider and between the Access Gateway Service and the Web server. They are configurable from the main configuration page. The options allow you to configure the which events are logged and which file they are sent to by using filters and profiles.

4.2.1 Managing Access Gateway Service Logging

The Logging page allows you to configure the events that are sent to the Access Gateway Service log file. You can configure the Access Gateway Service to log to multiple files and use a filter so that specific types of events go to a specific log file.

  1. In the Administration Console, click Devices > Access Gateways > Edit > Logging.

  2. Select one of the following actions:

    New: To add a new log profile, click New. Specify a name for the profile, then click OK. For more information on how to configure the profile, see Section 4.2.2, Configuring a Log Profile.

    Delete: To delete a profile, select the check box next to the profile, then click Delete.

    Copy: To copy a profile, select the check box next to the profile, then click Copy. To rename the copy and modify it, click the name of the copy. For configuration information, see Section 4.2.2, Configuring a Log Profile.

    Enable: To enable a profile, select the check box next to the profile, then click Enable.

    Disable: To disable a profile, select the check box next to the profile, then click Disable.

  3. Click OK twice, then update the Access Gateway.

4.2.2 Configuring a Log Profile

Use the Log Profile page to configure where the log file is located, how much disk space the log file can consume, and what types of events are logged.

  1. In the Administration Console, click Devices > Access Gateways > Edit > Logging > [Profile Name].

    To create a new profile, click New, specify a name, then click OK.

  2. To control where the events are logged, configure the following fields:

    Log Profile Name: Displays the current name of the profile.

    Log File Path: (Not configurable) Displays the location of the log files.

    Log File: Specifies the name and extension for the log file. If you are creating multiple profiles, select a name that indicates the purpose of the profile. For example, you could create a log file for Form Fill policy entries and name the file form_fill.log.

    If this name includes a subdirectory, the subdirectory is created relative to the displayed Log File Path.

    Echo To Console: Causes the events to be logged in the catalina.out (Linux) file or the stdout.log (Windows) file.

  3. Configure the following rollover options to control how much disk space can be used for logging before a new log file is created and old log files are deleted.

    You can enable both options, and the event that occurs first causes the log file to roll. For example, you can configure the log file to roll over at 50 MB and daily. On weekdays, the log file reaches 50 MB by noon and is rolled over. On weekends, it does not reach 50 MB by the end of day so the daily option causes it to roll over.

    Size-Based: To roll over log files based on the size of the log file, select Size-Based, then specify a maximum file size in megabytes.

    Date-Based: To roll over log files based on a date or time, select Date-Based, then select whether you want the file rolled over hourly, daily, weekly, or monthly.

    Maximum Backup Files: Specify the maximum number of log files you want saved before older files are deleted. If you leave the field blank, one backup file is created. If you specify 0, no backup files are created. When the log file reaches its rollover limit, a new log file is created and the old log file is deleted.

  4. To specify the information included in a log entry and the order in which it is included, click Advanced Options, then specify one or more of the formats listed in the table below.

    Each log entry can be followed by a bracketed string that labels the component or formats the component. The format strings are printf-style format strings. If you do not specify a format for the component, the default format is used. The space at the beginning of the format string is significant and supplies a space between the components in the log entry.

    Component

    Default Format

    Description

    ^BT

    [amLogEntry]

    Include the beginning tag. This tag marks the beginning of a log entry, and the format string is just a label.

    ^DT

    [yyyy-MM-dd'T'HH:mm:ss'Z']

    Include the date and time tag. The format string has the following order: year, month, day, T (marks the beginning of the time entries), hour, minute, seconds, time zone.

    ^LV

    [ %1$-5s]

    Include the logging level string such as Error or Informational.

    ^PR

    [ %1$-5s]

    Include the log preamble information.

    ^EC

    [ AM#%s:]

    Include the event code assigned to the message.

    ^DV

    [ AMDEVICEID#%s:]

    Include the device ID of the Access Manager component.

    ^AI

    [ AMAUTHID#%S:]

    Include the authentication ID assigned to the user. The authentication ID allows you to identify other log entries that are generated by the same user.

    ^EI

    [ AMEVENTID#%s:]

    Include the event identifier. The event identifier allows you to identify other log entries that are generated by the same event.

    ^CD

    [ %s]

    Include any correlation data.

    ^LD

    [ %s]

    Include any log description strings or data.

    ^ET

    [amLogEntry]

    Include the end tag for the log entry. This tag marks the end of the log entry, and the format string is just a label.

    T he logging system uses the following as the default format string:

    ^BT[amLogEntry]  ^DT[yyyy-MM-dd'T'HH:mm:ss'Z']  ^LV[ %1$-5s]  ^PR[ %1$-5s]  ^EC[ AM#%s:]  ^DV[ AMDEVICEID#%s:]  ^AI[ AMAUTHID#%S:]  ^EI[ AMEVENTID#%s:]  ^CD[ %s]  ^LD[ %s]  ^ET[amLogEntry]
    

    The space between the components in the default string is not significant. It is included to make the string more readable. This format produce log entries similar to the following:

    <amLogEntry> 2010-03-27T16:05:58Z INFO AGM:  AM#504650001: AMDEVICEID#ag-9859848722920601: ApacheGatewayManager: doSystemCommand(), (/opt/novell/ag/bin/novell-agctl restart,Apache Reconfigure) </amLogEntry>
    
  5. To specify the events that are logged, select one or more of the following actions:

    • Select a filter, then click Enable.

    • Select a filter, then click Disable.

    • Create a filter. Click Manage Filters, specify a name, then configure the events. For configuration information, see Section 4.2.4, Configuring a Log Filter.

  6. Click OK.

  7. Select the profile, click Enable, then click OK.

  8. Click Servers, then update the Access Gateway.

4.2.3 Managing Log Filters

Use this page to create and manage log filters. The log filter determines the type of events that are logged when the filter is enabled for a log profile.

  1. In the Administration Console, click Devices > Access Gateways > Edit > Logging > Log Filters.

  2. Select one of the following actions:

    New: To add a new log filter, click New. Specify a name for the filter, then click OK. For more information on how to configure the filter, see Section 4.2.4, Configuring a Log Filter.

    Delete: To delete a filter, select the check box next to the filter, then click Delete. A filter cannot be deleted when a log profile is using it.

    Copy: To copy a filter, select the check box next to the filter, then click Copy. To rename the copy and modify it, click the name of the copy. For configuration information, see Section 4.2.4, Configuring a Log Filter.

  3. Click OK twice, then update the Access Gateway.

4.2.4 Configuring a Log Filter

Use this procedure to specify the type of data that should be logged. You can restrict the information in the following ways:

  1. In the Administration Console, click Devices > Access Gateways > Edit > Logging > Log Filters > [Name of Filter].

  2. To change the name of the filter, specify a new name in the Log Filter Name text box.

  3. To restrict events to specified IDs, event codes, or strings, click Advanced Options, then specify a value for one or more of the following fields.

    Use these options when you have been viewing log files, you have identified the information you want to view, and you want to restrict the log entries to this information. When you enter multiple values, use a comma to separate the values.

    For information on the various tags used in the log files, see Understanding the Log Format in the Novell Access Manager 3.1 SP2 Administration Console Guide.

    Device IDs: The AMDEVICEID# value identifies the device that performed the action. To correlate the ID with the device, click Auditing > General Logging.

    Authentication IDs: The AMAUTHID# value identifies the user for a specific session. Specify one or more values.

    Preamble (Match Any): The preamble is an optional string that usually identifies the component generating the log, such as AGM or NIDS. Specify one or more values to match. The entry is included whenever a string matches one of the listed values.

    Preamble (Match All): The preamble is an optional string that usually identifies the component generating the log, such as AGM or NIDS. Specify multiple values only if you want the entry to include all the listed strings before it is logged.

    Correlation Data (Match Any): The correlation data consists of correlation tags and data unique to a specific type of trace. Specify one or more values to match. The entry is included whenever a string matches one of the listed values.

    Correlation Data (Match All): The correlation data consists of correlation tags and data unique to a specific type of trace. Specify multiple values only if you want the entry to include all the strings before it is logged.

    Log Data (Match Any): The log data is the additional information that is included in the log entry, such as Apache Service is not responding in a timely manner. Specify one or more values to match. The entry is included whenever a string matches one of the listed values.

    Log Data (Match All): The log data is the additional information that is included in the log entry, such as Apache Service is not responding in a timely manner. Specify multiple values only if you want the entry to include all the listed strings before it is logged.

    Always Log Event Codes: The AM# value identifies the event code. Specify one or more values to match.

  4. To specify the information level, select one or more of the following Log Levels. These levels are independent of each other. If you want both Error messages and Warning messages, you need to select both levels.

    Select All: Logs all levels of event information.

    Warning: Logs events that might cause system processing to fail.

    Info: Logs informational events such as configuration changes, startups, and shutdowns that complete successfully. If the event generates any type of error, warning, or severe message, these messages are not logged.

    Debug: Logs messages that include additional information useful to Novell Support and Engineering.

    Error: Logs events that error conditions generate.

    Trace: Logs messages that are useful to Novell Engineering.

    Severe: Logs serious failures that can cause system processing to fail.

  5. To specify the event types to include and the information level, click Advanced Log Level Options, then select one or more of the following. To view and select specific events for a category, use the arrow icons to expand the lists. For a description of a specific event, mouse over the event.

    URL Request Processing: Logs information about how the requested URL was processed.

    Authorization Processing: Logs information about the authorization processing. Error events need to be resolved for the system to operate properly.

    Identity Injection Processing: Logs information about the processing of Identity Injection policies. Error events need to be resolved for the system to operate properly.

    Form Fill Processing: Logs information about the processing of Form Fill policies. Error events need to be resolved for the system to operate properly.

    Web Server Communication: Logs information about the Identity Injection parameters and Form Fill parameters sent to the Web servers.

    Administration Request Processing: Logs information about commands. Error events need to be resolved for the system to operate properly.

    Statistics: Logs information about the processing of statistic requests. Error events need to be resolved for the system to operate properly.

    Health: Logs information about the health checks that the Access Gateway Service performs. Error events need to be resolved for the system to operate properly.

    Alerts Processing: Logs information about the alerts that the Access Gateway Service generates.

    Configuration Processing: Logs information about configuration changes. Error events need to be resolved for the system to operate properly.

    Initialization/Termination Processing: Logs information about the startup and shutdown procedures of the Access Gateway. Error events need to be resolved for the system to operate properly.

  6. Click OK.

  7. Click Servers, then update the Access Gateway.

4.2.5 Configuring a Log File for Troubleshooting Form Fill

The following procedure explains how to use the logging feature of the Access Gateway Service to troubleshoot a single feature, such as Form Fill. The filter is configured to log the Form Fill information that is generated as the Access Gateway Service processes Form Fill policies. These entries are logged to a single file.

  1. In the Administration Console, click Devices > Access Gateways > Edit > Logging.

  2. On the Log Profiles page, click New, specify a name for the profile such as Form Fill, then click OK.

  3. Specify a name for the log file, such as formfill.

  4. In the Filter List section, click Manage Filters.

  5. Click New, specify a name for the filter such as Form Fill Filter, then click OK.

  6. Expand the Advanced Log Level Options section.

  7. Select Form Fill Processing, then click the expand/collapse icon on the left.

  8. To view the events you have selected, expand the Error, Info, and Debug options.

    Notice that the selected events allow you to determine if the Access Gateway found a page that matches the Form Fill policy and whether the policy was evaluated without errors.

  9. Select Web Server Communication, then click the expand/collapse icon on the left.

  10. Expand the info level of events, then make sure that the Web Server Request with Form Fill Parameters event is select and that the Web Server Request With Identity Injection Parameters event is deselected.

  11. Click OK.

  12. Select the profile, click Enable, then click OK.

  13. Click the Access Gateways link, then update the Access Gateway.

  14. Log in as a user and access a resource that has been assigned a Form Fill policy.

  15. View the entries in log file.

    Linux: /var/opt/novell/amlogging/logs

    Windows: \Program Files\Novell\amlogging\logs

  16. (Optional) To view how the Embedded Service Provider evaluates the Form Fill policy, see Form Fill Traces in the Novell Access Manager 3.1 SP2 Policy Guide.

  17. (Optional) To add more information about Form Fill policies to the Apache error_log file, enable the DebugFormFill option. For more information, see Section 5.7, Advanced Access Gateway Service Options.