NAME

maillogpp -- a pretty-printer for mail server logfiles

SYNOPSIS

maillogpp 'args' < /var/log/maillog > output

DESCRIPTION

Maillogpp scans through a mail server logfile and consolidates all entries that correspond to an email transmission.

The output is done in either or two formats:

pretty-printing format: Each email transmission consisting of one from address and multiple to addresses is printed in a paragraph together with its associated arguments like relay server, delay time, delivery status and so on
greppable format: Each email transmission ist printed in one long line so that it is easy for search for distict pattern. The line consists of a space separated list of key=value pairs.

The following options are available:

General Configuration

-f 'filter-expr', --filter 'filter-expr': Collect only lines with matching server names. Not fully implemented yet.

Printing Configuration

-t, --time

Print a timestamp in front of each printed line (format HH:MM:SS).

-T, --full-time

Print a datestamp and a timestamp in front of each printed line (format YYYY-MM-DD HH:MM:SS while pretty-printing, YYYY-MM-DDTHH:MM:SS while in grep-mode).

-q, --queueid

Print the queue-id in front of each printed line. You can use the queue-id to grep in the raw logfile, then.

-Q, --full-queueid

Print the 'extended' queue-id in front of each printed line. The extended queue-id consists out of server name from the logfile prepended to the real queue-id. The extended queue-id is necessary, when you collect the log output from multiple servers into one logfile.

-w, --wrap

Wrap long lines of output. Unfortunately you cannot set the maximum line length, so wrapped lines are still very long.

-o 'method', --output 'method'

Select a output method. The following output methods are available:

plain: Print the output in a nice human-readable manner (default).
grep: Print the output in one long line structured as space

separated list of key=value pairs. See FILTER SYNTAX below.

-R 'filedesc', --remaining 'filedesc'

Print all lines, that were not considered by maillogpp on filehandle filedesc. E.g. other messages, messages from a POP or IMAP server, etc.

Use it e.g. with a sh-like shell in a command like maillogpp ... -R 3 3> maillog-rest.

Help

-h, --help: Print usage information
-D, --debug: Enable debug output.

If no option is given, maillogpp waits on stdin for input.

FILTER SYNTAX

The filter syntax is used in the --filter (-f) option (not yet) and as output format in the -output grep output method.

It is a sequence of key=value pairs separated with on space and put into one long line. One 'From' line and multiple 'To' lines are expressed in one line as one 'from=' and multiple 'to=' chunks.

The following keywords are available:

begin: 'HH:DD:SS' or 'YYYY-MM-DDTHH:DD:SS' dependig on --full-time
end: 'HH:DD:SS' or 'YYYY-MM-DDTHH:DD:SS' dependig on --full-time
qid: queue-id or extended queue-id depending on --full-queue
from: sender address, '<>' if empty (= mailer-daemon)
size: in bytes
recipient: number of recipients
pickup-uid: UID of local user who has sent the mail
client: IP of sending MTA or MUA
message-id: Message-Id
user: SMTP Auth username
to: recipient address
relay: name of recipient MTA
delay: in seconds
tries: number of deliveries until success or bounce
status: see above or maillogstat -l for status codes

Output Method 'grep'

The keywords appear in the above order.

The begin and end keys are a bit special. begin contains the timestamp of the earliest line in the logfile and end the timestamp of the latest.

The begin, end, and qid are not present if --time, --full-time, --queueid or --full-queueid (or -t, -T, -q, -Q) are not given as option.

Example:

Maillogpp in plain outmut mode would print something like this:

12:34:56 From: [u@example.com] Size: 123 Bytes, Recipients: 1, Client: 127.0.0.1,
         Message-Id: [k26CDMcR022351@example.com]
12:34:57   To: [dz@426.ch] Relay: mail.426.ch, Delay: 1 Sec, Tries: 1 (sent)
12:34:57   To: [as@426.ch] Relay: mail.426.ch, Delay: 1 Sec, Tries: 1 (sent)

Grep output mode would express the same information in filter syntax like this:

begin=12:34:56 end=12:34:57 from=[user@example.com] size=123 recipients=1 cleint=127.0.0.1 message-id=[k26CDMcR022351@example.com] to=[dz@426.ch] relay=mail.426.ch delay=1 tries=1 status=sent to=[as@426.ch] relay=mail.426.ch delay=1 tries=1 status=sent

Filter syntax

not yet implemented

EXAMPLES

Pretty print a logfile

% **maillogpp** /var/log/maillog

Pretty print a logfile and grep for 'From' address

% **maillogpp** -o grep | egrep 'from=.*@example.com' XXX should be \S* instead of .*

print complete daily statistics over a months' logfiles

% zcat /var/log/mail-200601*.gz | **maillogpp** -s -r reject_reasons -n -d my_domains -i 1d

On http://426.ch/maillogpp/examples you can see how the output looks on a wide screen.

REQUIREMENTS

Perl, tested with versions > XXX

/usr/bin/env should be in place. If it is not there, replace the first line of maillogpp with the full path to your perl binary, for example #!/usr/bin/perl.

DIAGNOSTICS

Maillogpp exits 0 on success, and 1 if an error ocurrs. XXX really?

BUGS

At the moment it only works with postfix logfiles.

Be very careful, if your logfile is large and you are short of RAM, monitor the RAM usage (top(1)) the first few times you run maillogpp to get an idea of the amount of resident memory consumed.

You might need a really wide screen or terminal to enjoy maillogpp most.

maillogpp ... -R fd fd> file works only when fd is < 10, except when using bash.

see TODO

Maillogpp/maillogpp(1)