NAME

courier-analog - Courier log analyzer

SYNOPSIS

courier-analog [--smtpinet] [--smtpitime] [--smtpierr] [--smtpos] [--smtpod] [--smtpof] [--imapnet] [--imaptime] [--imapbyuser] [--imapbylength] [--imapbyxfer] [--pop3net] [--pop3time] [--pop3byuser] [--pop3bylength] [--pop3byxfer] [--html=directory] [--noise=count] [--noisy] [--title="text"] {logfile}

DESCRIPTION

courier-analog reads the syslog(3)logfile with log messages generated by Courier mail server, and generates a useful report. courier-analog can also be used with the Courier-IMAP package subset, the SMTP-related report sections will be empty.

courier-analog expects each line in logfile to follow the generic syslog format: “Mmm dd hh:mm:ss hostname process: message”; the first fifteen character specify the time of the log message, which is followed by the server's hostname, the name of the process logging the message, then the message itself.

courier-analog should be invoked as part of the scheduled job that rotates the system log files. For example: all messages are logged to /var/log/maillog and once a week (or once a day) /var/log/maillog gets rotated to /var/log/maillog.1, after which the command “courier-analog [options] /var/log/maillog.1” is executed.

The name of the syslog(3) file with Courier messages is specified as logfile, following courier-analog's command line options. logfile may be “-”, which reads standard input. This can be used if log files are compressed after rotation. Example:

gunzip -cd </var/log/maillog.1.gz | courier-analog [options] -

The log file can contain messages from other applications besides Courier; they will be ignored.

Note

courier-analog reads the entire log file in memory, before indexing and generating reports, and sufficient memory must be available. A rule of thumb is that the amount of required RAM should be twice the size of logfile.

A sensible system log rotation policy should be established in advance, before deploying courier-analog. The level of system activity should be used to establish a log rotation policy that generates log files of reasonable size, when compared with system resources. An alternative is to copy the log file to another server, with available resources, and run courier-analog on the other server.

If possible, system log files should not be rotated more than once a day. The “Connections by time” report will not be meaningful with more frequent rotation frequencies.

OPTIONS

--smtpinet

Generate the “Incoming SMTP connections by network” report to standard output. The report is sorted by the number of total connections from each network, largest first. This report summarizes incoming SMTP connections, by the connecting /24 IPv4 network or a /64 IPv6 network.

--smtpitime

Generate the “Incoming SMTP connections by time” report to standard output. The report is sorted by the number of total connections per hour, largest first. This report summarizes incoming SMTP connections, on an hourly basis.

--smtpierr

Generate the “Incoming SMTP connections by error message” report to standard output. This report summarizes the error messages in incoming SMTP connections. A single SMTP connection may have multiple delivery attempts, and generate multiple errors. This report identifies the largest sources of rejected E-mail messages without regard to the actual number of connections. This report consists of three parts:

1.Summary of errors per each /24 IPv4 network or a /64 IPv6 network, sorted by the number of total errors from each network.

2.Summary of errors per each return address, sorted by the number of total errors for each return address.

3.Summary of errors per each recipient address, sorted by the number of total errors for each recipient address.

--smtpos

Generate the “Successful outbound SMTP connections” report to standard output. This report consists of two parts: summary sorted by the return address, and summary sorted by the destination address, sorted by the E-mail domain, largest number of addresses first. This report summarizes E-mail messages that were successfully sent.

--smtpof

Generate the “Failed outbound SMTP connections” report to standard output. This report consists of two parts: summary sorted by the return address, and summary sorted by the destination address, sorted by the E-mail domain, largest number of addresses first. This report summarizes E-mail messages that were not delivered.

--smtpod

Generate the “Deferred outbound SMTP connections” report to standard output. This report consists of two parts: summary sorted by the return address, and summary sorted by the destination address, sorted by the E-mail domain, largest number of addresses first. This report summarizes SMTP delivery attempts that resulted in a temporary error due to the destination E-mail server being down or temporarily unable to receive mail.

--html=directory

This option generates all reports in HTML format. “directory” should be an empty directory (which will be created, if necessary). courier-analog generates all reports, in HTML format, with a navigation index.html file.

--imapnet

Generate the “IMAP connections by network” report to standard output. The report is sorted by the number of total connections from each network, largest first. This report summarizes IMAP connections, by the connecting /24 IPv4 network or a /64 IPv6 network.

--imaptime

Generate the “IMAP connections by time” report to standard output. The report is sorted by the number of total connections per hour, largest first. This report summarizes IMAP connections, on an hourly basis.

--imapbyuser

Generate the “IMAP logins” report to standard output. The report is sorted by the number of total connections for each login ID, in decreasing order. This report summarizes IMAP connections, on a per-login basis.

--imapbyxfer

Generate the “IMAP data transfers” report to standard output. This is the same report as the “IMAP logins” report, except that the report is sorted by the total number of downloaded bytes in decreasing order. This report summarizes IMAP connections that download the most amount of mail.

--imapbylength

Generate the “IMAP session lengths” report to standard output. This is the same report as the “IMAP logins” report, except that the report is sorted by the total login time, in decreasing order. This report summarizes the longest IMAP connections.

--pop3net

Generate the “POP3 connections by network” report to standard output. The report is sorted by the number of total connections from each network, largest first. This report summarizes POP3 connections, by the connecting /24 IPv4 network or a /64 IPv6 network.

--pop3time

Generate the “POP3 connections by time” report to standard output. The report is sorted by the number of total connections per hour, largest first. This report summarizes POP3 connections, on an hourly basis.

--pop3byuser

Generate the “POP3 logins” report to standard output. The report is sorted by the number of total connections for each login ID, in decreasing order. This report summarizes POP3 connections, on a per-login basis.

--pop3byxfer

Generate the “POP3 data transfers” report to standard output. This is the same report as the “POP3 logins” report, except that the report is sorted by the total number of downloaded bytes in decreasing order. This report summarizes POP3 connections that download the most amount of mail.

--pop3bylength

Generate the “POP3 session lengths” report to standard output. This is the same report as the “POP3 logins” report, except that the report is sorted by the total login time, in decreasing order. This report summarizes the longest POP3 connections.

The --smtpinet option will be used by default if none are specified. Multiple options concate the reports to standard output. The --html option does not generate anything on standard output.

The IMAP/POP3 connections by network and time reports may not show the same connection total as the rest of the IMAP/POP3 reports. The “IMAP/POP3 connections by network and time” reports include all connections, whether they logged in or not. The other reports only include connections that succesfully logged in.

OTHER OPTIONS

--noise=N

Generate a report only for connections, or error messages, that occur more than N times. The rest is background noise that should not be paid attention to. The default is 10.

--noisy

Generate a separate report for the background noise, all lumped together. Alternatively, use --noise to set a lower noise threshold (perhaps even --noise=0).

--title="text"

Use “text” for the report's title.

BUGS

courier-analog eats memory even if only one, small, report is requested. None of the options have a major impact on its memory demands. courier-analog always eats the entire log file and chews it. The options only determine what gets spit out.

When the local time is set back due a transition to/from an alternate time zone (such as the return to standard time from daylight savings time in Northern America), the default syslog(3) format repeats the local timestamps, for an hour. This will have a minor impact on some of the time-based based reports.

courier-analog understands multi-line SMTP messages. During times of excessive system activity multi-line log entries could be interspersed with other messages. courier-analog may not be able to combine multi-line messages in that case, and report on each line of the message separately.

AUTHORS

Double Precision, Inc.