pflogsumm(1)

NAME

pflogsumm - Produce Postfix MTA logfile summary

SYNOPSIS pflogsumm [--config <file>] [--bounce-detail <cnt>] [--colwidth <n>] [-d|--date-range <date [range]>] [--deferral-detail <cnt>] [--detail <cnt>] [--dow0mon] [-e|--extended-detail] [--expired-detail <cnt>] [-h|--host-cnt <cnt>] [-i|--ignore-case] [--iso-date-time] [-m|--uucp-mung] [--mailq] [--no-no-msg-size] [--problems-first] [--pscrn-detail <cnt>] [--pscrn-stats] [-q|--quiet] [--rej-add-from] [--rej-add-to] [--reject-detail <cnt>] [--smtpd-stats] [--srs-mung] [--ssl-tls-stats] [--syslog-name <string>] [-u|--user-cnt <cnt>] [--unprocd-file <filename>] [--use-orig-to] [--verbose-msg-detail] [--verp-mung [n]] [--warning-detail <cnt>] [-x|--debug <file>] [--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
    to stderr.

DESCRIPTION

    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.

OPTIONS

    --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're 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
    --debug <file>
                   Enable debugging to <file>
                   See Also: -x
    --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'l args> |grep -v ' = $'
    --expired-detail <cnt>
                   Limit detailed message queue time expired reports to
                   the top <cnt>.  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 <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
                   "[email protected]".  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't 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>
                   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 <cnt>
                   Deprecated. Use --warning-detail instead.
                   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:
                     [email protected]
                   will be reformatted to their original value:
                     [email protected]
    --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.
    --ssl-tls-stats
                   Report SMTP TLS statistics and SMTPD SSL/TLS errors.
    -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 [n]
                   If n = 1 or is not provided, perform basic "VERP"
                   address munging, converting sender addresses of the form
                      "[email protected]"
                    to
                      "[email protected]"
                   In other words: replace the numeric value with "ID".
                   If n = 2, the munging is more "aggressive", converting the
                   address to something like:
                        "[email protected]"
                   See "NOTES" regarding this option.
    --version      Print program name and version and bail out.
    --warning-detail <cnt>
                   Limit detailed warnings reports to the top <cnt>.
                   0 to suppress entirely.
    -x <file>      Enable debugging to <file>
                   See Also: --debug
    --zero-fill    "Zero-fill" certain arrays so reports come out with
                   data in columns that that might otherwise be blank.

RETURN VALUE

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

ERRORS

    Error messages are emitted to stderr.

EXAMPLES

    Produce a report of previous day's activities:
        pflogsumm -d yesterday /var/log/maillog
    A report of prior week's activities:
        pflogsumm -d last_week /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.
        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're 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.

NOTES

    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's "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'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

REQUIREMENTS

    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's 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.

LICENSE

    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.

NAME

DESCRIPTION

OPTIONS

RETURN VALUE

ERRORS

EXAMPLES

SEE ALSO

NOTES

REQUIREMENTS

LICENSE

History