Complete Contents
Chapter 1 Getting Started With Netscape Messaging Server
Chapter 2 Configuring IMAP and POP Services
Chapter 3 Configuring SMTP Services
Chapter 4 Managing Mail Users and Mailing Lists
Chapter 5 Managing the Message Store
Chapter 6 Security and Access Control
Chapter 7 Working With SMTP Plugins
Chapter 8 Filtering Unsolicited Bulk Email
Chapter 9 Message Routing
Chapter 10 Monitoring and Maintaining Your Server
Chapter 11 Logging and Log Analysis
Appendix A Command Line Utilities
Appendix B Program Delivery
Appendix C sendmail Migration and Compatibility
Appendix D SNMP MIB
Glossary
Messaging Server Administrator's Guide: Logging and Log Analysis
Previous Next Contents Index Bookshelf


Chapter 11 Logging and Log Analysis

Netscape Messaging Server 4.0 can create log files that record events related to its administration, to communications using any of the protocols (IMAP, POP, and SMTP) that the server supports, and to other processes employed by the server. By examining the log files, you can monitor many aspects of the server's operation.

You can customize the policies for creating and managing the Messaging Server log files. This chapter describes the types and structure of log files, and discusses how to administer and how to view the log files.

This chapter has the following sections:


Log Characteristics
Messaging Server logging is flexible and customizable. You can specify settings that affect which and how many events are logged, and you can use those settings and other characteristics to refine searches for logged events when you are analyzing log files.

Services That Are Logged

Messaging Server creates a separate set of log files for each of the major protocols, or services, it supports. You can customize and view each type of log file individually. Table 11.1 lists the services that can be logged.

Table 11.1 Logged Services

Service
Log-file description
Admin
Contains logged events related to communication between Netscape Console and Messaging Server (mostly through several CGI processes), by way of its Administration Server
SMTP
Contains logged events related to SMTP activity of this server
IMAP
Contains logged events related to IMAP4 activity of this server
POP
Contains logged events related to POP3 activity of this server
Default
Contains logged events related to other activity of this server, such as command-line utilities and other processes

Levels of Logging

The level, or priority, of logging defines how detailed, or verbose, the logging activity is to be. A higher priority level means less detail, because only events of high priority (high severity) are logged. A lower level means greater detail because more kinds of events are recorded in the log file.

You can set the logging level separately for each service (see Log Files Option Tab), and you can use logging level to filter searches for log events (see Log Viewer Window). Table 11.2 describes the available levels.

Table 11.2 Levels of Logging

Level
Description
Critical
The minimum logging detail. An event is written to the log whenever a severe problem or critical condition occurs--such as when the server cannot access a mailbox or a library needed for it to run.
Error
An event is written to the log whenever an error condition occurs--such as when a connection attempt to a client or another server fails.
Warning
An event is written to the log whenever a warning condition occurs--such as when the server cannot understand a communication sent to it by a client.
Notice
An event is written to the log whenever a notice (a normal but significant condition) occurs--such as when a user login fails or when a session closes.
Informational
An event is written to the log with every significant action that takes place--such as when a user successfully logs on or off or creates or renames a mailbox.
Debugging
The most verbose logging. Useful only for debugging purposes. Events are written to the log at individual steps within each process or task, to pinpoint problems.

Note: These Messaging-Server logging levels are a subset of those defined by the Unix syslog facility.

IMPORTANT: The more verbose the logging you specify, the more disk space your log files will occupy; for guidelines, see Defining Log Rotation, Expiration, and Backup Policies.

When you select a particular logging level, events corresponding to that level and to all higher (less verbose) levels are logged. The default level of logging is Notice.

Facility Categories

Within each supported service or protocol, Messaging Server further categorizes logged events by the facility, or functional area, in which they occur. Every logged event contains the name of the facility that generated it. These categories aid in filtering events during searches (see Log Viewer Window). Table 11.3 lists the facilities that Messaging Server recognizes for logging purposes.

Table 11.3 Facilities for log files

Facility
Description
General
Undifferentiated actions related to this protocol or service
LDAP
Actions related to Messaging Server accessing the LDAP directory database
Network
Actions related to network connections (socket errors fall into this category)
Account
Actions related to user accounts (user logins fall into this category)
Protocol
Protocol-level actions related to protocol-specific commands (errors returned by IMAP or POP functions fall into this category)
Stats
Actions related to the gathering of server statistics
Store
Low-level actions related to accessing the message store (read/write errors fall into this category)

See Searching and Viewing Logs for examples of using facility categories as filters in log searches.

Filename Conventions for Log Files

All log files created by Messaging Server use identical naming conventions. Each log file has a filename of the form

service.sequenceNum.timeStamp

where the components of the filename have these meanings:

service
The protocol or service being logged (see Table 11.1)
sequenceNum
An integer that specifies the order of creation of this log file compared to others in the log-file directory. Log files with higher sequence numbers are more recent than those with lower numbers. Sequence numbers do not roll over; they increase monotonically for the life of the server (beginning at server installation).
timeStamp
A large integer that specifies the date and time of file creation. (Its value is expressed in standard Unix time: the number of seconds since midnight January 1, 1970.)

For example, a log file named imap.63.915107696 would be the 63rd log file created in the directory of IMAP log files, created at 12:34:56 PM on December 31, 1998.

The combination of open-ended sequence numbering with a timestamp gives you more flexibility in rotating, expiring, and selecting files for analyzing. See Defining Log Rotation, Expiration, and Backup Policies for more specific suggestions.

Content Format for Log Files

All log files created by Messaging Server have identical content formats. Log files are multiline text files, in which each line describes one logged event. All event descriptions, for each of the supported services, have the general format

dateTime hostName processName[pid]: facility logLevel: eventMessage

in which the components of the event description have these meanings:

dateTime
The date and time at which the event was logged, expressed in dd/mon/yyyy hh:mm:ss format, with a time-zone field expressed as +/-hhmm from GMT. For example:
:02/Jan/1999:13:08:21 -0700
hostName
The name of the host machine on which the server is running: for example, showshoe.
Note: If there is more than one instance of Messaging Server on the host, you can use the process ID component to separate logged events of one instance from another.
processName
The name of the process that generated the event: for example, cgi_store
pid
The process ID of the process that generated the event: for example, 18753
facility
The facility category that the event belongs to: for example, General (see Table 11.3)
logLevel
The level of logging that the event represents: for example, Notice (see Table 11.2)
eventMessage
An event-specific explanatory message that may be of any length: for example, Log created (894305624). For descriptions of the formats of some event messages, see Selected Event-Message Formats.

Note: This logging format is identical to the logging format defined by the Unix syslog facility, except that the date/time format is different and the format includes two additional components (facility and logLevel).

Here are three examples of logged events as viewed using Netscape Console (see Log Viewer Window).

02/May/1998:17:37:32 -0700 showshoe cgi_store[18753]: General Notice: 
Log created (894155852)

04/May/1998:11:07:44 -0400 xyzmail cgi_service[343]: General Error: 
function=getserverhello|port=2500|error=failed to connect

03/Dec/1998:06:54:32 +0200 AiriusPost imapd[232]: Account Notice: 
close [127.0.0.1] [unauthenticated] 1998/12/3 6:54:32 0:00:00 0 115 0

When viewing a log file in the Log Viewer window, you can limit the events displayed by searching for any specific component in an event, such as a specific logging level or facility, or a specific process ID. See Searching and Viewing Logs.

Log-File Directories

Every logged service is assigned a single directory, in which its log files are stored. All IMAP log files are stored together, as are all POP log files, and likewise for the other services. You define the location of each directory, and you also define how many log files of what maximum size are permitted to exist in the directory. (See Log Files Option Tab.)

Make sure that your storage capacity is sufficient for all your log files. Log data can be voluminous, especially at lower (more verbose) logging levels.

It is important also to define your logging level, log rotation, log expiration, and server-backup policies appropriately so that all of your log-file directories are backed up and none of them become overloaded; otherwise, you may lose information. See Defining Log Rotation, Expiration, and Backup Policies (next).


Defining Log Rotation, Expiration, and Backup Policies
You can define the logging configurations for Messaging Server that best serve your administration needs. This section discusses issues that may help you decide on the best configurations and policies, and it explains how to implement them.

Flexible Logging Architecture

The naming scheme for log files (service.sequenceNum.timeStamp) helps you to design a flexible log-rotation and backup policy. The fact that events for different services are written to different files makes it easier for you to isolate problems quickly. Also, because the sequence number in a filename is ever-increasing and the timestamp is always unique, later log files do not simply overwrite earlier ones after a limited set of sequence numbers is exhausted. Instead, older log files are overwritten or deleted only when more flexible limits of age, number of files, or total storage are reached.

Messaging Server supports automatic rotation of log files, which simplifies administration and facilitates backups. You are not required to manually retire the current log file and create a new one to hold subsequent logged events. You can back up all but the current log file in a directory at any time, without stopping the server or manually notifying the server to start a new log file.

In setting up your logging policies, you can set options (for each service) that control limits on total log storage, maximum number of log files, individual file size, maximum file age, and rate of log-file rotation.

Setting Logging Options

You can use Netscape Console to set options that control the logging configuration for each Messaging Server service.

The optimal settings for these options depend on the rate at which log data accumulates. It may take between 4,000 and 10,000 log entries to occupy 1 MB of storage. At the more verbose levels of logging (such as Notice), a moderately busy server may generate hundreds of megabytes of log data per week. Here is one approach you can follow:

  1. In Netscape Console, open the Messaging Server whose log file options you want to set.
  2. Click the Configuration tab, open the Log Files folder in the left pane, and select the log files of a service (such as IMAP, SMTP, or Admin).
  3. Click the Option tab in the right pane. The Option form for that logged service is displayed.
  4. Pick a total storage limit that is within your hardware capacity and that coordinates with the backup schedule you have planned for the server. Estimate the rate at which you anticipate that log data will accumulate, add a factor of safety, and define your total storage limit so that it is not exceeded over the period between server backups.
  5. Example: If you expect to accumulate an average of 3 MB of IMAP log-file data per day, and server backups are weekly, you might specify on the order of 25 - 30 MB as the storage limit for IMAP logs (assuming that your disk storage capacity is sufficient).

    Put the value you choose into the "When total log size exceeds" field of the Log Files Option form.

  6. Define your maximum number of log files, maximum age, and log-rotation schedule to coordinate with your backup schedule.
  7. Example: If server backups are weekly and you rotate IMAP log files daily, you might specify a maximum number of IMAP log files of about 10 (to account for faster rotation if the individual log-size limit is exceeded), and a maximum age of 7 or 8 days.

    Put the values you choose into the "Number of logs per directory", "When a log is older than", and "Create new log every" fields of the Log Files Option form.

  8. Define your maximum log-file size so that searching performance is not impacted. Also, coordinate it with your rotation schedule and your total storage limit. Given the rate at which log entries accumulate, you might set a maximum that is slightly larger that what you expect to accumulate by the time a rotation automatically occurs. And your maximum file size times your maximum number of files might be roughly equivalent to your total storage limit.
  9. Example: If your IMAP log rotation is daily, your expected accumulation of IMAP log data is 3 MB per day, and your total storage limit for IMAP logs is 25 MB, you might set a maximum IMAP log-file size of 3.5 MB. (In this example, you could still lose some log data if it accumulated so rapidly that all log files hit maximum size and the maximum number of log files were reached.)

    Put the value you choose into the "File size for each log" field of the Log Files Option form.

  10. For safety, pick a minimum amount free disk space that you will permit on the volume that holds the log files. That way, if factors other than log-file size cause the volume to fill up, old log files will be deleted before a failure occurs from attempting to write log data to a full disk.
  11. Put this value into the "When free disk space is less than" field of the Log Files Option form.

  12. Assign a directory to hold your log files. Put this value into the "Directory path for log files" field of the Log Files Option form.
  13. Set a level of logging that is consistent with your storage limits--that is, a level that you estimate will cause log-data accumulation at approximately the rate you used to estimate the storage limit. Put this value into the "Levels of detail" field of the Log Files Option form.
See Log Files Option Tab for a detailed description of the contents of that form.

Note that you must set several limits, more than one of which might cause the rotation or deletion of a log file. Whichever limit is reached first is the controlling one. For example, if your maximum log-file size is 3.5 MB, and you specify that a new log be created every day, you may actually get log files created faster than one per day if log data builds up faster than 3.5 MB every 24 hours. Then, if your maximum number of log files is 10 and your maximum age is 8 days, you may never reach the age limit on log files because the faster log rotation may mean that 10 files will have been created in less than 8 days.

The following default values, provided for Messaging Server administration logs, may be a reasonable starting point for planning:

maximum number of log files in directory: 10
maximum log-file size: 2 MB
total maximum size permitted for all log files: 20 MB
minimum free disk space permitted: 5 MB
log rollover time: 1 day
maximum age before expiration: 7 days
level of logging: Notice

You can see that this configuration assumes that server-administration log data is predicted to accumulate at about 2 MB per day, backups are weekly, and the total space allotted for storage of admin logs is at least 25 MB.(These settings may be insufficient if the logging level is more verbose.)

For SMTP, POP, or IMAP logs, the same values might be a reasonable start. If all services have approximately the same log-storage requirements as the defaults shown here, you might expect to initially plan for about 150 MB of total log-storage capacity. (Note that this is meant only as a general indication of storage requirements; your actual requirements may be significantly different.)


Searching and Viewing Logs
Netscape Console provides a basic interface for viewing Messaging Server log data. It allows for selecting individual log files and for performing flexible filtered searches of log entries within those files.

For a given service (such as SMTP), log files are listed in chronological order. Once you have chosen a log file to search, you can narrow the search for individual events by specifying a time interval, the logging level, facility category, and a text pattern for matching.

Search Parameters

These are the search parameters you can specify for viewing log data:

Specifying a Search and Viewing Results

Follow these steps to search for logged events with specific characteristics belonging to a given service:

  1. In Netscape Console, open the Messaging Server whose log files you want to inspect.
  2. Follow either of these steps to display the Log Files Content form for a given logged service:
  3. The Content form for that logged service is displayed.
  4. In the Log filename field, select the log file you want to examine.
  5. (See Log Files Content Tab for a detailed description of the contents of that form.)

  6. Click the View selected log button to open the Log Viewer window.
  7. In the Log Viewer window, specify your desired search parameters (described the next section, Search Parameters).
  8. Click Update to perform the search and display the results in the Log entry field.
See Log Viewer Window for a detailed description of the contents of that window.


Analyzing Logs with Third-Party Tools
For log analyses and report generation beyond the display capabilities of Netscape Console, you need to use other tools. You can manipulate log files on your own with text editors, and you may also be able to modify and use existing report-generation tools that were developed to manipulate Unix syslog files.

With a scriptable text editor supporting regular-expression parsing, you can potentially search for and extract log entries based on any of the criteria discussed in this chapter, and possibly sort the results or even generate sums or other statistics.

If you wish to use a public-domain syslog manipulation tool, remember that you may need to modify it to account for the different date/time format and for the two extra components (facility and logLevel) that appear in Messaging Server log entries but not in syslog entries.


Selected Event-Message Formats
The event message of each log entry is in a format specific to the type of event being logged: that is, each service defines what content appears in any of its event messages. Many event messages are simple and self-evident; others are more complex.

To help you search for and interpret common log entries related to message transfer, this section describes the format of logged events written by three modules of the SMTP service: SMTP-Accept, SMTP-Deliver, and Mailbox-Deliver.

Note that the log-entry elements described here are all parts of the eventMessage portion of the log entry, where the entire entry has the format

dateTime hostName processName[pid]: facility logLevel: eventMessage

. See Content Format for Log Files for descriptions of the other portions.

SMTP-Accept log format

The event message for an SMTP-Accept log entry has the format

moduleName:envelopeID:mailFrom:[peerAddress]:peerHost:msgID:msgSize:
numRecipients:recipientList

Where the elements of the event message have the following meanings:

moduleName
The name of the SMTP module that logged the event (SMTP-Accept)
envelopeID
The ID assigned to the message by Messaging Server (unique to each received message)
mailFrom
The sender's address, from the message envelope
peerAddress
The IP address of the connecting server
peerHost
The host name (or IP address, if no lookup is performed) of the connecting server
msgID
The ID of the message, written by the sending client into the message header
msgSize
The size of the message, in bytes
numRecipients
The number of recipients
recipientList
The address of each recipient

Here is an example:

[08/Sep/1998:19:04:24 -0700] dizzy smtpd[8379]: General Notice:
SMTP-Accept:0EYZV320.6U1:<aswe32dasdf@netscape.com>:[127.0.0.1]:
127.0.0.1:<pkeni@netscape.com>:272:1:<dizzy2@dizzy.mcom.com>

SMTP-Deliver log format

The event message for an SMTP-Deliver log entry has the format

moduleName:envelopeID:mailFrom:status:destHost:msgID:msgSize:
numRecipients:recipientList

in which the elements of the event message have the following meanings:

moduleName
The name of the SMTP module that logged the event (SMTP-Deliver)
envelopeID
The ID assigned to the message by Messaging Server (unique to each received message)
mailFrom
The sender's address, from the message envelope
status
The delivery status of the message (Delivered or Deferred)
destHost
The host name of the destination server
msgID
The ID of the message, written by the sending client into the message header
msgSize
The size of the message, in bytes
numRecipients
The number of recipients
recipientList
The address of each recipient

Here is an example:

[08/Sep/1998:19:04:02 -0700] dizzy smtpd[8379]: General Notice:
SMTP-Deliver:0EYZV2Q0.8C0:<aasdfasdfds@netscape.com>:Delivered:
c3po.netscape.com:<pkeni@netscape.com>:337:1:<pkeni@netscape.com>

Mailbox-Deliver log format

The event message for a Mailbox-Deliver log entry has the format

moduleName:envelopeID:msgSize:msgID:userID

Where the elements of the event message have the following meanings:

moduleName
The name of the SMTP module that logged the event (Mailbox-Deliver)
envelopeID
The ID assigned to the message by Messaging Server (unique to each received message)
msgSize
The size of the message, in bytes
msgID
The ID of the message, written by the sending client into the message header
userID
The account name of the recipient to whom the message was delivered

Here is an example:

[31/Jul/1998:16:50:56 -0700] slug smtpd[19530]: General Notice: 
Mailbox-Deliver:0EWZGWV0.02Z:17943:<12345678.123@nowhere>:slug464


Interface Reference: Logging and Log Files
This section describes the Netscape Console interface elements that allow you to set logging options and view logs. See Managing Servers With Netscape Console for information on using Netscape Console to manage Messaging Server and other servers.


Log Files Option Tab
You use the form accessed through this tab to set logging characteristics for each type of service that Messaging Server logs.

For more information, see also Defining Log Rotation, Expiration, and Backup Policies.

The Option form has these elements:

Levels of detail. Use this menu to select the level of detail (verbosity) you want for this service's logging, in terms of what events are to be logged. These are the available levels:

Critical
Critical conditions are logged
Error
Error conditions are logged
Warning
Warning conditions are logged
Notice
Notices are logged
Informational
All significant actions are logged
Debugging
The most verbose logging (for debugging only)

When you select a specific level, events for that level and for all less verbose levels are logged. The default level of logging is Notice. For more information on logging levels, see Levels of Logging.

Directory path for log files. In this field, enter the location at which log files for this service are to be kept. Default is instanceDirectory/log/service, where instanceDirectory is the directory in which the files for this instance of Messaging Server reside.

Note: Log data can be voluminous. Choose a directory that has adequate disk storage space and in which your log files will not overwhelm other files.

Log File Rotation Policy

File size for each log. In this field, specify the maximum size (in KB or MB) permitted for a log file of this type. When the file currently being written to exceeds that size, subsequent events are written into a new file, named according to the conventions are described in Filename Conventions for Log Files.

Create new log every. In this field, specify the maximum age (in hours or days) permitted for the log file currently being written to.When the current log file exceeds that age, subsequent events are written into a new file, named according to the conventions are described in Filename Conventions for Log Files.

IMPORTANT: If you do not want to lose log data, make sure you adjust your log-rotation parameters and backup schedule (see Defining Log Rotation, Expiration, and Backup Policies) so that files are not deleted before they have been backed up.

Log File Expiration policy

Number of logs per directory. In this field, specify the maximum number of log files permitted in the directory specified in the Directory path for log files field. When this number of files is exceeded, the oldest log file in the directory is deleted.

When total log size exceeds. In this field, specify the maximum size (in KB or MB) permitted for the sum of all log files of this service. When this maximum is exceeded, the oldest log file in the directory is deleted.

When free disk space is less than. In this field, specify the minimum free disk space (in KB or MB) permitted on the storage volume to which the log files are written. If this minimum is surpassed, the oldest log file in the directory is deleted.

When a log is older than. In this field, specify the maximum age (in hours or days) permitted for any log file. When a file exceeds that age, it is deleted.

IMPORTANT: If you do not want to lose log data, make sure you adjust your log-expiration parameters and backup schedule (see Defining Log Rotation, Expiration, and Backup Policies) so that files are not deleted before they have been backed up.

Action Buttons

Save. Click this button to commit any settings you have made in the Log Files Option form.

Reset. Click this button to return the form to the settings it displayed when you opened it (unless you have previously clicked Save, in which case the form returns the settings it had when you last clicked Save).

Help. Click this button to display online help (this document) describing the Log Files Option form.


Log Files Content Tab
You use the form accessed through this tab to view and search the contents of a given service's log files.

For more information, see also Searching and Viewing Logs.

The Content form has these elements:

Log file info. This table displays the following characteristics of the log file currently selected in the Log filename list: file type, file size, number of lines, date and time last modified.

Log filename. This list displays the names of all log files for this service. Select a log file in the list to display its characteristics or view its content. Log-file naming conventions are described in Filename Conventions for Log Files. Note that the current log file (the one being written to) has no numerical suffixes in its name.

View selected log. Click this button to open the Log Viewer (see Log Viewer Window), a window that allows you to search and view selected contents of the log file currently selected in the Log filename list.

Action Buttons

Help. Click this button to display online help (this document) describing the Log Files Content form.


Log Viewer Window
You use this window to configure searches on the contents of any Messaging Server log file, and to display the results of those searches.

For more information, see also Searching and Viewing Logs.

The Log Viewer window has these elements:

Filter

Specify time period. Click this radio button to enter a starting and ending date and time for searching. If the button is selected, only events that occurred between the times you specify in the From and To fields are displayed.

From. In this field, enter the start of the period for filtering log events. Enter a slash-separated date followed by a space and a colon-separated time (format = yyyy/mm/dd hh:mm:ss). This field applies only if the "Specify time period" radio button is selected.

To. In this field, enter the end of the period for filtering log events. Enter a slash-separated date followed by a space and a colon-separated time (format = yyyy/mm/dd hh:mm:ss). This field applies only if the "Specify time period" radio button is selected.

For the past n Day(s). Click this radio button to specify a number of days, rather than a starting and ending date and time, for filtering log events. If this radio button is selected, you can enter an integer number in the field, in which case all log events since that number of days before the present day will be displayed.

Facility. Use this menu to specify that only log events of a specific server facility, or functional area (such as General, LDAP, or Network), are to be displayed. (Logged facilities are described in Facility Categories.) You can select a single facility or all facilities.

Levels of detail. Use this menu to specify that only log events of a given level (such as Critical, Error, or Notice) are to be displayed. (Logging levels are described in Levels of Logging). You can select all levels or a single level; if you select a single level, events at that and all higher (less verbose) levels are included in the display.

Pattern. Use this field to enter a text pattern and specify that only log events that contain a match to that pattern are to be displayed. You can use these wildcard and special characters in the search pattern:

* Any set of characters (example: *.com)
? Any single character (example: 199?)
[nnn] Any character in the set nnn (example: [aeiou])
[^nnn] Any character not in the set nnn (example: [^aeiou])
[n-m] Any character in the range n-m (example: [A-Z])
[^n-m] Any character not in the range n-m (example: [^0-9])
\ Escape character: place before *, ?, [, or ] to use them as literals

Note: Searches are case-sensitive.

Update. Click this button to apply the currently entered filter criteria to the specified log file. Events that match the criteria are displayed in the Log entry field.

Log Entry

Log entry. This field displays (in two panes) logged events from the current log file. (The file whose contents are displayed here has been selected through the Content form for a specific logged service; see Log Files Content Tab.)

Only entries that match the filter criteria specified by the other fields in this window are displayed. Each logged event occupies one line in the upper pane of the field and has the following format:

dateTime hostName processName[pid]: facility logLevel: eventMessage

For more information on log-entry format, see Content Format for Log Files.

Entries in the upper pane of the Log entry field may be truncated by the right edge of the field. However, the full text of any entry selected in the upper pane is displayed in the lower pane, wrapped to the width of the window.

Action Buttons

Close. Click this button to close the Log Viewer window.

Help. Click this button to display online help (this document) describing the Log Viewer window.

 

© Copyright 1998 Netscape Communications Corporation