COURIER-ANALOG(8)

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"] {[--journal=n] | [logfile]}

DESCRIPTION

courier-analog reads the syslog(3) logfile or the system journal 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.

Either the --journal option or the logfile must be specified, otherwise courier-analog reads the log file from standard input. --journal reads the mail logs from the system journal, the parameter specifies the number of days to retrieve from the system journal. The mail log entries with timestamps from midnight n days ago to today's midnight get included in the report (mail log entries after midnight are not included).

courier-analog expects each line in the logfile or the system journal 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.

With discrete files 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.

When reading directly from the system journal it's sufficient to run courier-analog at the same frequency, in days, as what's specified by --journal.

    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.