.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "PFLOGSUMM 1" .TH PFLOGSUMM 1 2026-04-22 1.2.0 "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME pflogsumm \- Produce Postfix MTA logfile summary .PP Copyright (C) 1998\-2026 by James S. Seymour, Release 1.2.0 .SH "SYNOPSIS pflogsumm [\-\-config ] [\-\-bounce\-detail ] [\-\-colwidth ] [\-d|\-\-date\-range ] [\-\-deferral\-detail ] [\-\-detail ] [\-\-dow0mon] [\-e|\-\-extended\-detail] [\-\-expired\-detail ] [\-h|\-\-host\-cnt ] [\-i|\-\-ignore\-case] [\-\-iso\-date\-time] [\-m|\-\-uucp\-mung] [\-\-mailq] [\-\-no\-no\-msg\-size] [\-\-problems\-first] [\-\-pscrn\-detail ] [\-\-pscrn\-stats] [\-q|\-\-quiet] [\-\-rej\-add\-from] [\-\-rej\-add\-to] [\-\-reject\-detail ] [\-\-smtpd\-stats] [\-\-srs\-mung] [\-\-ssl\-tls\-stats] [\-\-syslog\-name ] [\-u|\-\-user\-cnt ] [\-\-unprocd\-file ] [\-\-use\-orig\-to] [\-\-verbose\-msg\-detail] [\-\-verp\-mung [n]] [\-\-warning\-detail ] [\-x|\-\-debug ] [\-\-zero\-fill] [file1 [filen]]" .IX Header "SYNOPSIS pflogsumm [--config ] [--bounce-detail ] [--colwidth ] [-d|--date-range ] [--deferral-detail ] [--detail ] [--dow0mon] [-e|--extended-detail] [--expired-detail ] [-h|--host-cnt ] [-i|--ignore-case] [--iso-date-time] [-m|--uucp-mung] [--mailq] [--no-no-msg-size] [--problems-first] [--pscrn-detail ] [--pscrn-stats] [-q|--quiet] [--rej-add-from] [--rej-add-to] [--reject-detail ] [--smtpd-stats] [--srs-mung] [--ssl-tls-stats] [--syslog-name ] [-u|--user-cnt ] [--unprocd-file ] [--use-orig-to] [--verbose-msg-detail] [--verp-mung [n]] [--warning-detail ] [-x|--debug ] [--zero-fill] [file1 [filen]]" .Vb 1 \& pflogsumm \-\-[dump\-config|help|version] \& \& Note: Where both long\- and short\-form options exist only the \& latter are shown above. See man page for long\-form equivalents. \& \& If no file(s) specified, reads from stdin. Output is to stdout. Errors \& to stderr. .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" .Vb 4 \& 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. .Ve .SH OPTIONS .IX Header "OPTIONS" .Vb 1 \& \-\-bounce\-detail \& \& Limit detailed bounce reports to the top . 0 \& to suppress entirely. \& \& \-\-config \& \& Path to a configuration file containing pflogsumm \& options. \& \& Supports all standard command\-line options (without the \& leading "\-" or "\-\-"). Options like "config", "dump\-config", \& "help", and "version" technically work here, too, though \& they\*(Aqre not particularly useful in this context. \& \& Command\-line arguments override config file values except \& for boolean options. \& \& \-\-colwidth \& Maximum report output width. Default is 80 columns. \& 0 = unlimited. \& \& N.B.: \-\-verbose\-msg\-detail overrides \& \& \-d \& \-\-date\-range \& \& Limits the report to the specified date or range. \& \& Accepted values: \& \& today \& yesterday \& "this week" / "last week" \& "this month" / "last month" \& YYYY\-MM[\-DD] \& "YYYY\-MM[\-DD] YYYY\-MM[\-DD]" \& \& These options do what they suggest, with one \& important caveat: \& \& ISO 8601 / RFC 3339\-style dates and ranges may \& not yield accurate results when used with \& traditional log formats lacking year information \& ("month day\-of\-month"). \& \& In such cases, pflogsumm assumes log entries \& are from the current year. For example, if the \& current month is April and a log contains "Apr \& NN" entries from the previous year, they will \& be interpreted as from the *current* April. \& \& As such, date\-based filtering is only reliable \& for entries less than ~365 days old for \& old\-/traditional\-style logfiles. \& \& Arguments containing spaces must be quoted! \& \& This/last week/month arguments can take underscores, \& rather than spaces, to avoid quoting: E.g.: \& \& \-\-date\-range last_week \& \& ISO 8601/RFC 3339 date ranges may optionally use a \& hyphen or the word "to" for readability. E.g.: \& \& "2025\-08\-01 to 2025\-08\-08" \& \& If an optional day (DD) is omitted, the range becomes \& the full month. E.g.: \& \& 2025\-08 == 2025\-08\-01 through 2025\-08\-31 \& \& "2025\-07 \- 2025\-08" == 2025\-07\-01 \- 2025\-08\-31 \& \& \-\-debug \& Enable debugging to \& \& See Also: \-x \& \& \-\-dow0mon \& First day of the week is Monday, rather than Sunday. \& \& (Used only for this/last week calculations.) \& \& \-\-deferral\-detail \& \& Limit detailed deferral reports to the top . 0 \& to suppress entirely. \& \& \-\-detail \& Sets all \-\-*\-detail, \-h and \-u to . Is \& over\-ridden by individual settings. \-\-detail 0 \& suppresses *all* detail. \& \& \-\-dump\-config \& Dump the config to STDOUT and exit. \& \& This can be used as both a debugging aid and as a way \& to develop your first config file. For the latter: \& Simply run your usual pflogsumm command line, adding \& \-\-dump\-config to it, and redirect STDOUT to a file. \& \& To make it cleaner: Remove unset configs: \& \& pflogsumm \-\-dump\-config |grep \-v \*(Aq = $\*(Aq \& \& \-\-expired\-detail \& \& Limit detailed message queue time expired reports to \& the top . 0 to suppress entirely. \& \& \-e \& \-\-extended\-detail \& \& 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 \& \-\-host\-cnt \& \& top 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 \& \& 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 \& "foo!username@somehost.dom". This also affects the \& extended detail report (\-e), to help ensure that by\- \& domain\-by\-name sorting is more accurate. \& \& See also: \-\-uucp\-mung \& \& \-\-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\-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." \& \& \-\-problems\-first \& \& Emit "problems" reports (bounces, defers, warnings, \& etc.) before "normal" stats. \& \& \-\-pscrn\-detail \& \& Limit postscreen detail reporting to top lines of \& each event. 0 to suppress entirely. \& \& Note: Postscreen rejects are collected and reported \& in any event. \& \& \-\-pscrn\-stats \& Collect and emit postscreen summary stats. \& \& Note: Postscreen rejects are collected and reported \& in any event. \& \& \-\-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 \& quiet \- don\*(Aqt print headings for empty reports \& \& note: headings for warning, fatal, and "master" \& messages will always be printed. \& \& \-\-rej\-add\-to \& For sender reject reports: Add the intended recipient \& address. \& \& \-\-reject\-detail \& \& Limit detailed smtpd reject, warn, hold and discard \& reports to the top . 0 to suppress entirely. \& \& \-\-smtp\-detail \& \& Deprecated \& \& \-\-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 \& \& Deprecated. Use \-\-warning\-detail instead. \& \& Limit detailed smtpd warnings reports to the top . \& 0 to suppress entirely. \& \& \-\-srs\-mung \& Undo SRS address munging. \& \& If your postfix install has an SRS plugin running, many \& addresses in the report will contain the SRS\-formatted \& email addresses, also for non\-local addresses (f.i. \& senders). This option will try to undo the "damage". \& \& Addresses of the form: \& \& SRS0=A6cv=PT=sender.example.com=support@srs.example.net \& \& will be reformatted to their original value: \& \& support@sender.example.com \& \& \-\-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\*(Aqve 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. \& \& \-\-ssl\-tls\-stats \& \& Report SMTP TLS statistics and SMTPD SSL/TLS errors. \& \& \-u \& \-\-user\-cnt \& \& top to display in user reports. 0 == none. \& \& See also: "\-h" and "\-\-*\-detail" options for further \& report\-limiting options. \& \& \-\-unprocd\-file \& \& Emit unprocessed logfile lines to file \& \& \-\-use\-orig\-to \& \& Where "orig_to" fields are found, report that in place \& of the "to" address. \& \& \-\-uucp\-mung \& modify (mung?) UUCP\-style bang\-paths \& \& See also: \-m \& \& \-\-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 [n] \& \& If n = 1 or is not provided, perform basic "VERP" \& address munging, converting sender addresses of the form \& \& "list\-return\-NN\-someuser=some.dom@host.sender.dom" \& \& to \& \& "list\-return\-ID\-someuser=some.dom@host.sender.dom" \& \& In other words: replace the numeric value with "ID". \& \& If n = 2, the munging is more "aggressive", converting the \& address to something like: \& \& "list\-return@host.sender.dom" \& \& See "NOTES" regarding this option. \& \& \-\-version Print program name and version and bail out. \& \& \-\-warning\-detail \& \& Limit detailed warnings reports to the top . \& 0 to suppress entirely. \& \& \-x Enable debugging to \& \& See Also: \-\-debug \& \& \-\-zero\-fill "Zero\-fill" certain arrays so reports come out with \& data in columns that that might otherwise be blank. .Ve .SH "RETURN VALUE" .IX Header "RETURN VALUE" .Vb 1 \& Pflogsumm doesn\*(Aqt return anything of interest to the shell. .Ve .SH ERRORS .IX Header "ERRORS" .Vb 1 \& Error messages are emitted to stderr. .Ve .SH EXAMPLES .IX Header "EXAMPLES" .Vb 1 \& Produce a report of previous day\*(Aqs activities: \& \& pflogsumm \-d yesterday /var/log/maillog \& \& A report of prior week\*(Aqs activities: \& \& pflogsumm \-d last_week /var/log/maillog.0 \& \& What\*(Aqs happened so far today: \& \& pflogsumm \-d today /var/log/maillog \& \& Crontab entry to generate a report of the previous day\*(Aqs 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\*(Aqs activity. \& \& 10 4 * * 0 /usr/local/sbin/pflogsumm \-d "last week" /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\*(Aqre broken\-up into two\-or\-more lines due to page \& formatting issues.) \& \& Using a config file: \& \& pflogsumm \-\-config /usr/local/etc/pflogusmm/daily.conf \& \& Using a config file, overriding a config file options on the command \& line: \& \& pflogsumm \-\-config /usr/local/etc/pflogsumm/daily.conf \& \-\-detail 30 \& \& This would override *all* detail settings in the config \& file, setting them all to 30. \& \& pflogsumm \-\-config /usr/local/etc/pflogsumm/daily.conf \& \-\-detail 30 \-\-host\-cnt 10 \& \& This would override all detail settings in the config \& file, setting them all to 30, with the global detail \& setting in turn being overridden to 10 for host count. .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" .Vb 1 \& pffrombyto, pftobyfrom \& \& The pflogsumm FAQ: pflogsumm\-faq.txt. .Ve .SH NOTES .IX Header "NOTES" .Vb 4 \& Some options, such as date range, have both short\-form and \& long\-form names. In the interest of brevity, only the \& short\-form options are shown in the SYNOPSIS and in \& pflogsumm\*(Aqs "help" output. \& \& Pflogsumm makes no attempt to catch/parse non\-Postfix log \& entries. Unless it has "postfix/" in the log entry, it will be \& ignored. \& \& It\*(Aqs 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\*(Aq $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\*(Aqs described in \& sample\-misc.cf will be reported under "postfix", so that if \& you\*(Aqre 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 .Ve .SH REQUIREMENTS .IX Header "REQUIREMENTS" .Vb 1 \& Requires Perl 5.10, minimum, and Date::Calc \& \& For \-\-config, Pflogsumm requires the Config::Simple module. \& \& Both of the above can be obtained from CPAN at http://www.perl.com \& or from your distro\*(Aqs repository. \& \& Pflogsumm is currently written and tested under Perl 5.38. \& As of version 19990413\-02, pflogsumm worked with Perl 5.003, but \& future compatibility is not guaranteed. .Ve .SH LICENSE .IX Header "LICENSE" .Vb 4 \& 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. .Ve