.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.13)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "PFLOGSUMM 1"
.TH PFLOGSUMM 1 "2010-03-20" "1.1.3" "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.pl \- Produce Postfix MTA logfile summary
.PP
Copyright (C) 1998\-2010 by James S. Seymour, Release 1.1.3.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\&    pflogsumm.pl \-[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_bounce_detail] [\-\-no_deferral_detail]
\&        [\-\-no_no_msg_size] [\-\-no_reject_detail] [\-\-no_smtpd_warnings]
\&        [\-\-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.pl \-[help|version]
\&
\&    If no file(s) specified, reads from stdin.  Output is to stdout.
.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.
\&
\&    \-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
\&                   "foo!username@somehost.dom".  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 depreciated 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.pl.  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 depreciated 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\*(Aqt 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\*(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>       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
\&                   "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.
\&
\&    \-\-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.pl \-d yesterday /var/log/maillog
\&
\&    A report of prior week\*(Aqs activities (after logs rotated):
\&
\&        pflogsumm.pl /var/log/maillog.0
\&
\&    What\*(Aqs happened so far today:
\&
\&        pflogsumm.pl \-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.
\&    (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\*(Aqre broken\-up into two\-or\-more lines due to page
\&    formatting issues.
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.Vb 1
\&    The pflogsumm FAQ: pflogsumm\-faq.txt.
.Ve
.SH "NOTES"
.IX Header "NOTES"
.Vb 3
\&    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 $syslog_name set, Postfix 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 3
\&    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.
.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