--- /dev/null
+.\" 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
projects / sven / pflogsumm.git / blobdiff