X-Git-Url: http://git.sven.stormbind.net/?p=sven%2Fpflogsumm.git;a=blobdiff_plain;f=pflogsumm.1;fp=pflogsumm.1;h=33dac0e8d66d4ceb5870afa32883e18fd654ec9f;hp=0000000000000000000000000000000000000000;hb=80016b92950431352612eb3f713acd5f5a7a0e81;hpb=a2fecf41814c5657fe1b97d452ee3a2e7890a409 diff --git a/pflogsumm.1 b/pflogsumm.1 new file mode 100644 index 0000000..33dac0e --- /dev/null +++ b/pflogsumm.1 @@ -0,0 +1,532 @@ +.\" 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 ] [\-\-detail ] +\& [\-\-bounce_detail ] [\-\-deferral_detail ] +\& [\-h ] [\-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 ] +\& [\-\-smtp_detail ] [\-\-smtpd_stats] +\& [\-\-smtpd_warning_detail ] [\-\-syslog_name=string] +\& [\-u ] [\-\-verbose_msg_detail] [\-\-verp_mung[=]] +\& [\-\-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 +\& +\& Limit detailed bounce reports to the top . 0 +\& to suppress entirely. +\& +\& \-d today generate report for just today +\& \-d yesterday generate report for just "yesterday" +\& +\& \-\-deferral_detail +\& +\& Limit detailed deferral reports to the top . 0 +\& to suppress entirely. +\& +\& \-\-detail +\& +\& Sets all \-\-*_detail, \-h and \-u to . 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 top 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 +\& +\& Limit detailed smtpd reject, warn, hold and discard +\& reports to the top . 0 to suppress entirely. +\& +\& \-\-smtp_detail +\& +\& Limit detailed smtp delivery reports to the top . +\& 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 +\& +\& Limit detailed smtpd warnings reports to the top . +\& 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 top 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