.\" -*- 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 2025-10-22 1.1.13 "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\-2025 by James S. Seymour, Release 1.1.13
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 10
\&    pflogsumm [\-\-config <file>] [\-\-bounce\-detail <cnt>]
\&      [\-\-colwidth <n>] [\-\-deferral\-detail <cnt>] [\-\-detail <cnt>]
\&      [\-d <date [range]>] [\-\-dow0mon] [\-e] [\-h <cnt>] [\-i]
\&      [\-\-iso\-date\-time] [\-\-mailq] [\-m] [\-\-no\-no\-msg\-size]
\&      [\-\-problems\-first] [\-\-pscrn\-detail <cnt>] [\-\-pscrn\-stats]
\&      [\-q] [\-\-rej\-add\-from] [\-\-rej\-add\-to] [\-\-reject\-detail <cnt>]
\&      [\-\-smtp\-detail <cnt>] [\-\-smtpd\-stats] [\-\-smtpd\-warning\-detail <cnt>]
\&      [\-\-srs\-mung] [\-\-syslog\-name=string] [\-u <cnt>]
\&      [\-\-unprocd\-file <filename> ] [\-\-use\-orig\-to] [\-\-verbose\-msg\-detail]
\&      [\-\-verp\-mung[=<n>]] [\-x] [\-\-zero\-fill] [file1 [filen]]
\&
\&    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
\&    and debug 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 <cnt>
\&
\&                   Limit detailed bounce reports to the top <cnt>.  0
\&                   to suppress entirely.
\&
\&    \-\-config <config file>
\&
\&                   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 <n>
\&                    Maximum report output width.  Default is 80 columns.
\&                    0 = unlimited.
\&
\&                    N.B.: \-\-verbose\-msg\-detail overrides
\&
\&    \-d <arg>
\&    \-\-date\-range <arg>
\&
\&                    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
\&
\&    \-\-dow0mon
\&                   First day of the week is Monday, rather than Sunday.
\&
\&                   (Used only for this/last week calculations.)
\&
\&    \-\-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.
\&
\&    \-\-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 <add\*(Aql args> |grep \-v \*(Aq = $\*(Aq
\&
\&    \-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 <cnt>
\&    \-\-host\-cnt <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
\&
\&                   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 <cnt>
\&
\&                   Limit postscreen detail reporting to top <cnt> 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 <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.
\&
\&    \-\-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.
\&
\&    \-u <cnt>
\&    \-\-user\-cnt <cnt>
\&
\&                  top <cnt> to display in user reports. 0 == none.
\&
\&                  See also: "\-h" and "\-\-*\-detail" options for further
\&                  report\-limiting options.
\&
\&    \-\-unprocd\-file <filename>
\&
\&                  Emit unprocessed logfile lines to file <filename>
\&
\&    \-\-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
\&    \-\-verp\-mung=2
\&                   Do "VERP" generated address (?) munging.  Convert
\&                   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".
\&
\&                   By specifying the optional "=2" (second form), the
\&                   munging is more "aggressive", converting the address
\&                   to something like:
\&
\&                        "list\-return@host.sender.dom"
\&
\&                   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.
\&
\&    \-x             Enable debugging to STDERR
\&
\&    \-\-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