.\" 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