home | help 
COURIER-ANALOG(8)		 courier-analog 	       COURIER-ANALOG(8)

NAME
     courier-analog - Courier log analyzer

SYNOPSIS
     courier-analog  [--smtpinet]  [--smtpitime] [--smtpierr] [--smtpos] [--smt-
		    pod]  [--smtpof]  [--imapnet]  [--imaptime]   [--imapbyuser]
		    [--imapbylength]   [--imapbyxfer]  [--pop3net]  [--pop3time]
		    [--pop3byuser] [--pop3bylength]  [--pop3byxfer]  [--html=di-
		    rectory]	[--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 time-
     stamps from midnight n days ago to today's midnight get included in the re-
     port (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: mes-
     sage"; 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 sched-
     uled 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 log-
     file, 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  con-
	 nections, 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  ac-
	 tual 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  summa-
	 rizes E-mail messages that were successfully sent.

     --smtpof
	 Generate the "Failed outbound SMTP connections" report to standard out-
	 put.  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 summa-
	 rizes 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  summa-
	 rizes	SMTP delivery attempts that resulted in a temporary error due to
	 the destination E-mail server being down or temporarily unable  to  re-
	 ceive 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  net-
	 work,	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 de-
	 creasing 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 summa-
	 rizes 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 net-
	 work, 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  de-
	 creasing 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 summa-
	 rizes the longest POP3 connections.

     The --smtpinet option will be used by default if none are specified. Multi-
     ple  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  con-
     nections by network and time" reports include all connections, whether they
     logged  in  or not. The other reports only include connections that succes-
     fully 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 to-
	 gether. Alternatively, use --noise to set a lower noise threshold (per-
	 haps 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 time-
     stamps, 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 exces-
     sive  system  activity  multi-line  log  entries could be interspersed with
     other messages.  courier-analog may not be able to combine multi-line  mes-
     sages in that case, and report on each line of the message separately.

AUTHORS
     Double Precision, Inc.

Courier Mail Server		   04/07/2022		       COURIER-ANALOG(8)
home | help