pflogsumm (1)

    pflogsumm -[eq] [-d <today|yesterday>] [--detail <cnt>]
        [--bounce-detail <cnt>] [--deferral-detail <cnt>]
        [-h <cnt>] [-i|--ignore-case] [--iso-date-time] [--mailq]
        [-m|--uucp-mung] [--no-no-msg-size] [--problems-first]
        [--rej-add-from] [--reject-detail <cnt>] [--smtp-detail <cnt>]
        [--smtpd-stats] [--smtpd-warning-detail <cnt>]
        [--syslog-name=string] [-u <cnt>] [--verbose-msg-detail]
        [--verp-mung[=<n>]] [--zero-fill] [file1 [filen]]

    pflogsumm -[help|version]

    If no file(s) specified, reads from stdin.  Output is to stdout.

Pflogsumm is a log analyzer/summarizer for the Postfix MTA. It is designed to provide an over-view of Postfix activity, with just enough detail to give the administrator a "heads up" for potential trouble spots.

Pflogsumm generates summaries and, in some cases, detailed reports of mail server traffic volumes, rejected and bounced email, and server warnings, errors and panics.

--bounce-detail <cnt>

Limit detailed bounce reports to the top <cnt>. 0 to suppress entirely.

-d today generate report for just today -d yesterday generate report for just "yesterday"

--deferral-detail <cnt>

Limit detailed deferral reports to the top <cnt>. 0 to suppress entirely.

--detail <cnt>

Sets all --*-detail, -h and -u to <cnt>. Is over-ridden by individual settings. --detail 0 suppresses *all* detail.

-e extended (extreme? excessive?) detail

Emit detailed reports. At present, this includes only a per-message report, sorted by sender domain, then user-in-domain, then by queue i.d.

WARNING: the data built to generate this report can quickly consume very large amounts of memory if a lot of log entries are processed!

-h <cnt> top <cnt> to display in host/domain reports.

0 = none.

See also: "-u" and "--*-detail" options for further report-limiting options.

--help Emit short usage message and bail out.

(By happy coincidence, "-h" alone does much the same, being as it requires a numeric argument :-). Yeah, I know: lame.)

-i --ignore-case Handle complete email address in a case-insensitive manner.

Normally pflogsumm lower-cases only the host and domain parts, leaving the user part alone. This option causes the entire email address to be lower- cased.

--iso-date-time

For summaries that contain date or time information, use ISO 8601 standard formats (CCYY-MM-DD and HH:MM), rather than "Mon DD CCYY" and "HHMM".

-m modify (mung?) UUCP-style bang-paths --uucp-mung

This is for use when you have a mix of Internet-style domain addresses and UUCP-style bang-paths in the log. Upstream UUCP feeds sometimes mung Internet domain style address into bang-paths. This option can sometimes undo the "damage". For example: "somehost.dom!username@foo" (where "foo" is the next host upstream and "somehost.dom" was whence the email originated) will get converted to "[email protected]". This also affects the extended detail report (-e), to help ensure that by- domain-by-name sorting is more accurate.

--mailq Run "mailq" command at end of report.

Merely a convenience feature. (Assumes that "mailq" is in $PATH. See "$mailqCmd" variable to path thisi if desired.)

--no_bounce_detail --no_deferral_detail --no_reject_detail

These switches are deprecated in favour of --bounce-detail, --deferral-detail and --reject-detail, respectively.

Suppresses the printing of the following detailed reports, respectively:

message bounce detail (by relay) message deferral detail message reject detail

See also: "-u" and "-h" for further report-limiting options.

--no-no-msg-size

Do not emit report on "Messages with no size data".

Message size is reported only by the queue manager. The message may be delivered long-enough after the (last) qmgr log entry that the information is not in the log(s) processed by a particular run of pflogsumm. This throws off "Recipients by message size" and the total for "bytes delivered." These are normally reported by pflogsumm as "Messages with no size data."

--no-smtpd-warnings

This switch is deprecated in favour of smtpd-warning-detail

On a busy mail server, say at an ISP, SMTPD warnings can result in a rather sizeable report. This option turns reporting them off.

--problems-first

Emit "problems" reports (bounces, defers, warnings, etc.) before "normal" stats.

--rej-add-from For those reject reports that list IP addresses or host/domain names: append the email from address to each listing. (Does not apply to "Improper use of SMTP command pipelining" report.)

-q quiet - don't print headings for empty reports

note: headings for warning, fatal, and "master" messages will always be printed.

--reject-detail <cnt>

Limit detailed smtpd reject, warn, hold and discard reports to the top <cnt>. 0 to suppress entirely.

--smtp-detail <cnt>

Limit detailed smtp delivery reports to the top <cnt>. 0 to suppress entirely.

--smtpd-stats

Generate smtpd connection statistics.

The "per-day" report is not generated for single-day reports. For multiple-day reports: "per-hour" numbers are daily averages (reflected in the report heading).

--smtpd-warning-detail <cnt>

Limit detailed smtpd warnings reports to the top <cnt>. 0 to suppress entirely.

--syslog-name=name

Set syslog-name to look for for Postfix log entries.

By default, pflogsumm looks for entries in logfiles with a syslog name of "postfix," the default. If you've set a non-default "syslog_name" parameter in your Postfix configuration, use this option to tell pflogsumm what that is.

See the discussion about the use of this option under "NOTES," below.

-u <cnt> top <cnt> to display in user reports. 0 == none.

See also: "-h" and "--*-detail" options for further report-limiting options.

--verbose-msg-detail

For the message deferral, bounce and reject summaries: display the full "reason", rather than a truncated one.

Note: this can result in quite long lines in the report.

--verp-mung do "VERP" generated address (?) munging. Convert --verp-mung=2 sender addresses of the form "[email protected]" to "[email protected]"

In other words: replace the numeric value with "ID".

By specifying the optional "=2" (second form), the munging is more "aggressive", converting the address to something like:

"[email protected]"

Actually: specifying anything less than 2 does the "simple" munging and anything greater than 1 results in the more "aggressive" hack being applied.

See "NOTES" regarding this option.

--version Print program name and version and bail out.

--zero-fill "Zero-fill" certain arrays so reports come out with data in columns that that might otherwise be blank.

Pflogsumm doesn't return anything of interest to the shell.

Error messages are emitted to stderr.

Produce a report of previous day's activities:

pflogsumm -d yesterday /var/log/maillog

A report of prior week's activities (after logs rotated):

pflogsumm /var/log/maillog.0

What's happened so far today:

pflogsumm -d today /var/log/maillog

Crontab entry to generate a report of the previous day's activity at 10 minutes after midnight.

10 0 * * * /usr/local/sbin/pflogsumm -d yesterday /var/log/maillog 2>&1 |/usr/bin/mailx -s "`uname -n` daily mail stats" postmaster

Crontab entry to generate a report for the prior week's activity. (This example assumes one rotates ones mail logs weekly, some time before 4:10 a.m. on Sunday.)

10 4 * * 0 /usr/local/sbin/pflogsumm /var/log/maillog.0 2>&1 |/usr/bin/mailx -s "`uname -n` weekly mail stats" postmaster

The two crontab examples, above, must actually be a single line each. They're broken-up into two-or-more lines due to page formatting issues.

The pflogsumm FAQ: pflogsumm-faq.txt.

Pflogsumm makes no attempt to catch/parse non-Postfix log entries. Unless it has "postfix/" in the log entry, it will be ignored.

It's important that the logs are presented to pflogsumm in chronological order so that message sizes are available when needed.

For display purposes: integer values are munged into "kilo" and "mega" notation as they exceed certain values. I chose the admittedly arbitrary boundaries of 512k and 512m as the points at which to do this--my thinking being 512x was the largest number (of digits) that most folks can comfortably grok at-a-glance. These are "computer" "k" and "m", not 1000 and 1,000,000. You can easily change all of this with some constants near the beginning of the program.

"Items-per-day" reports are not generated for single-day reports. For multiple-day reports: "Items-per-hour" numbers are daily averages (reflected in the report headings).

Message rejects, reject warnings, holds and discards are all reported under the "rejects" column for the Per-Hour and Per-Day traffic summaries.

Verp munging may not always result in correct address and address-count reduction.

Verp munging is always in a state of experimentation. The use of this option may result in inaccurate statistics with regards to the "senders" count.

UUCP-style bang-path handling needs more work. Particularly if Postfix is not being run with "swap_bangpath = yes" and/or *is* being run with "append_dot_mydomain = yes", the detailed by-message report may not be sorted correctly by-domain-by-user. (Also depends on upstream MTA, I suspect.)

The "percent rejected" and "percent discarded" figures are only approximations. They are calculated as follows (example is for "percent rejected"):

percent rejected =

(rejected / (delivered + rejected + discarded)) * 100

There are some issues with the use of --syslog-name. The problem is that, even with Postfix' $syslog_name set, it will sometimes still log things with "postfix" as the syslog_name. This is noted in /etc/postfix/sample-misc.cf:

# Beware: a non-default syslog_name setting takes effect only # after process initialization. Some initialization errors will be # logged with the default name, especially errors while parsing # the command line and errors while accessing the Postfix main.cf # configuration file.

As a consequence, pflogsumm must always look for "postfix," in logs, as well as whatever is supplied for syslog_name.

Where this becomes an issue is where people are running two or more instances of Postfix, logging to the same file. In such a case:

. Neither instance may use the default "postfix" syslog name and...

. Log entries that fall victim to what's described in sample-misc.cf will be reported under "postfix", so that if you're running pflogsumm twice, once for each syslog_name, such log entries will show up in each report.

The Pflogsumm Home Page is at:

http://jimsun.LinxNet.com/postfix_contrib.html

For certain options (e.g.: --smtpd-stats), Pflogsumm requires the Date::Calc module, which can be obtained from CPAN at http://www.perl.com.

Pflogsumm is currently written and tested under Perl 5.8.3. As of version 19990413-02, pflogsumm worked with Perl 5.003, but future compatibility is not guaranteed.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You may have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

An on-line copy of the GNU General Public License can be found http://www.fsf.org/copyleft/gpl.html.