1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.13)
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
9 .de Vb \" Begin verbatim text
14 .de Ve \" End verbatim text
18 .\" Set up some character translations and predefined strings. \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
21 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
29 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
43 .\" Escape single quotes in literal strings from groff's Unicode transform.
47 .\" If the F register is turned on, we'll generate index entries on stderr for
48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
49 .\" entries marked with X<> in POD. Of course, you'll have to process the
50 .\" output yourself in some meaningful fashion.
53 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64 .\" Fear. Run. Save yourself. No user-serviceable parts.
65 . \" fudge factors for nroff and troff
74 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80 . \" simple accents for nroff and troff
90 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
97 . \" troff and (daisy-wheel) nroff accents
98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105 .ds ae a\h'-(\w'a'u*4/10)'e
106 .ds Ae A\h'-(\w'A'u*4/10)'E
107 . \" corrections for vroff
108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
110 . \" for low resolution devices (crt and lpr)
111 .if \n(.H>23 .if \n(.V>19 \
124 .\" ========================================================================
126 .IX Title "PFLOGSUMM 1"
127 .TH PFLOGSUMM 1 "2010-03-20" "1.1.3" "User Contributed Perl Documentation"
128 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
129 .\" way too many mistakes in technical documents.
133 pflogsumm.pl \- Produce Postfix MTA logfile summary
135 Copyright (C) 1998\-2010 by James S. Seymour, Release 1.1.3.
137 .IX Header "SYNOPSIS"
139 \& pflogsumm.pl \-[eq] [\-d <today|yesterday>] [\-\-detail <cnt>]
140 \& [\-\-bounce_detail <cnt>] [\-\-deferral_detail <cnt>]
141 \& [\-h <cnt>] [\-i|\-\-ignore_case] [\-\-iso_date_time] [\-\-mailq]
142 \& [\-m|\-\-uucp_mung] [\-\-no_bounce_detail] [\-\-no_deferral_detail]
143 \& [\-\-no_no_msg_size] [\-\-no_reject_detail] [\-\-no_smtpd_warnings]
144 \& [\-\-problems_first] [\-\-rej_add_from] [\-\-reject_detail <cnt>]
145 \& [\-\-smtp_detail <cnt>] [\-\-smtpd_stats]
146 \& [\-\-smtpd_warning_detail <cnt>] [\-\-syslog_name=string]
147 \& [\-u <cnt>] [\-\-verbose_msg_detail] [\-\-verp_mung[=<n>]]
148 \& [\-\-zero_fill] [file1 [filen]]
150 \& pflogsumm.pl \-[help|version]
152 \& If no file(s) specified, reads from stdin. Output is to stdout.
155 .IX Header "DESCRIPTION"
157 \& Pflogsumm is a log analyzer/summarizer for the Postfix MTA. It is
158 \& designed to provide an over\-view of Postfix activity, with just enough
159 \& detail to give the administrator a "heads up" for potential trouble
162 \& Pflogsumm generates summaries and, in some cases, detailed reports of
163 \& mail server traffic volumes, rejected and bounced email, and server
164 \& warnings, errors and panics.
169 \& \-\-bounce_detail <cnt>
171 \& Limit detailed bounce reports to the top <cnt>. 0
172 \& to suppress entirely.
174 \& \-d today generate report for just today
175 \& \-d yesterday generate report for just "yesterday"
177 \& \-\-deferral_detail <cnt>
179 \& Limit detailed deferral reports to the top <cnt>. 0
180 \& to suppress entirely.
184 \& Sets all \-\-*_detail, \-h and \-u to <cnt>. Is
185 \& over\-ridden by individual settings. \-\-detail 0
186 \& suppresses *all* detail.
188 \& \-e extended (extreme? excessive?) detail
190 \& Emit detailed reports. At present, this includes
191 \& only a per\-message report, sorted by sender domain,
192 \& then user\-in\-domain, then by queue i.d.
194 \& WARNING: the data built to generate this report can
195 \& quickly consume very large amounts of memory if a
196 \& lot of log entries are processed!
198 \& \-h <cnt> top <cnt> to display in host/domain reports.
202 \& See also: "\-u" and "\-\-*_detail" options for further
203 \& report\-limiting options.
205 \& \-\-help Emit short usage message and bail out.
207 \& (By happy coincidence, "\-h" alone does much the same,
208 \& being as it requires a numeric argument :\-). Yeah, I
212 \& \-\-ignore_case Handle complete email address in a case\-insensitive
215 \& Normally pflogsumm lower\-cases only the host and
216 \& domain parts, leaving the user part alone. This
217 \& option causes the entire email address to be lower\-
222 \& For summaries that contain date or time information,
223 \& use ISO 8601 standard formats (CCYY\-MM\-DD and HH:MM),
224 \& rather than "Mon DD CCYY" and "HHMM".
226 \& \-m modify (mung?) UUCP\-style bang\-paths
229 \& This is for use when you have a mix of Internet\-style
230 \& domain addresses and UUCP\-style bang\-paths in the log.
231 \& Upstream UUCP feeds sometimes mung Internet domain
232 \& style address into bang\-paths. This option can
233 \& sometimes undo the "damage". For example:
234 \& "somehost.dom!username@foo" (where "foo" is the next
235 \& host upstream and "somehost.dom" was whence the email
236 \& originated) will get converted to
237 \& "foo!username@somehost.dom". This also affects the
238 \& extended detail report (\-e), to help ensure that by\-
239 \& domain\-by\-name sorting is more accurate.
241 \& \-\-mailq Run "mailq" command at end of report.
243 \& Merely a convenience feature. (Assumes that "mailq"
244 \& is in $PATH. See "$mailqCmd" variable to path thisi
247 \& \-\-no_bounce_detail
248 \& \-\-no_deferral_detail
249 \& \-\-no_reject_detail
251 \& These switches are depreciated in favour of
252 \& \-\-bounce_detail, \-\-deferral_detail and
253 \& \-\-reject_detail, respectively.
255 \& Suppresses the printing of the following detailed
256 \& reports, respectively:
258 \& message bounce detail (by relay)
259 \& message deferral detail
260 \& message reject detail
262 \& See also: "\-u" and "\-h" for further report\-limiting
265 \& \-\-no_no_msg_size
267 \& Do not emit report on "Messages with no size data".
269 \& Message size is reported only by the queue manager.
270 \& The message may be delivered long\-enough after the
271 \& (last) qmgr log entry that the information is not in
272 \& the log(s) processed by a particular run of
273 \& pflogsumm.pl. This throws off "Recipients by message
274 \& size" and the total for "bytes delivered." These are
275 \& normally reported by pflogsumm as "Messages with no
278 \& \-\-no_smtpd_warnings
280 \& This switch is depreciated in favour of
281 \& smtpd_warning_detail
283 \& On a busy mail server, say at an ISP, SMTPD warnings
284 \& can result in a rather sizeable report. This option
285 \& turns reporting them off.
287 \& \-\-problems_first
289 \& Emit "problems" reports (bounces, defers, warnings,
290 \& etc.) before "normal" stats.
293 \& For those reject reports that list IP addresses or
294 \& host/domain names: append the email from address to
295 \& each listing. (Does not apply to "Improper use of
296 \& SMTP command pipelining" report.)
298 \& \-q quiet \- don\*(Aqt print headings for empty reports
300 \& note: headings for warning, fatal, and "master"
301 \& messages will always be printed.
303 \& \-\-reject_detail <cnt>
305 \& Limit detailed smtpd reject, warn, hold and discard
306 \& reports to the top <cnt>. 0 to suppress entirely.
308 \& \-\-smtp_detail <cnt>
310 \& Limit detailed smtp delivery reports to the top <cnt>.
311 \& 0 to suppress entirely.
315 \& Generate smtpd connection statistics.
317 \& The "per\-day" report is not generated for single\-day
318 \& reports. For multiple\-day reports: "per\-hour" numbers
319 \& are daily averages (reflected in the report heading).
321 \& \-\-smtpd_warning_detail <cnt>
323 \& Limit detailed smtpd warnings reports to the top <cnt>.
324 \& 0 to suppress entirely.
326 \& \-\-syslog_name=name
328 \& Set syslog_name to look for for Postfix log entries.
330 \& By default, pflogsumm looks for entries in logfiles
331 \& with a syslog name of "postfix," the default.
332 \& If you\*(Aqve set a non\-default "syslog_name" parameter
333 \& in your Postfix configuration, use this option to
334 \& tell pflogsumm what that is.
336 \& See the discussion about the use of this option under
339 \& \-u <cnt> top <cnt> to display in user reports. 0 == none.
341 \& See also: "\-h" and "\-\-*_detail" options for further
342 \& report\-limiting options.
344 \& \-\-verbose_msg_detail
346 \& For the message deferral, bounce and reject summaries:
347 \& display the full "reason", rather than a truncated one.
349 \& Note: this can result in quite long lines in the report.
351 \& \-\-verp_mung do "VERP" generated address (?) munging. Convert
352 \& \-\-verp_mung=2 sender addresses of the form
353 \& "list\-return\-NN\-someuser=some.dom@host.sender.dom"
355 \& "list\-return\-ID\-someuser=some.dom@host.sender.dom"
357 \& In other words: replace the numeric value with "ID".
359 \& By specifying the optional "=2" (second form), the
360 \& munging is more "aggressive", converting the address
361 \& to something like:
363 \& "list\-return@host.sender.dom"
365 \& Actually: specifying anything less than 2 does the
366 \& "simple" munging and anything greater than 1 results
367 \& in the more "aggressive" hack being applied.
369 \& See "NOTES" regarding this option.
371 \& \-\-version Print program name and version and bail out.
373 \& \-\-zero_fill "Zero\-fill" certain arrays so reports come out with
374 \& data in columns that that might otherwise be blank.
377 .IX Header "RETURN VALUE"
379 \& Pflogsumm doesn\*(Aqt return anything of interest to the shell.
384 \& Error messages are emitted to stderr.
387 .IX Header "EXAMPLES"
389 \& Produce a report of previous day\*(Aqs activities:
391 \& pflogsumm.pl \-d yesterday /var/log/maillog
393 \& A report of prior week\*(Aqs activities (after logs rotated):
395 \& pflogsumm.pl /var/log/maillog.0
397 \& What\*(Aqs happened so far today:
399 \& pflogsumm.pl \-d today /var/log/maillog
401 \& Crontab entry to generate a report of the previous day\*(Aqs activity
402 \& at 10 minutes after midnight.
404 \& 10 0 * * * /usr/local/sbin/pflogsumm \-d yesterday /var/log/maillog
405 \& 2>&1 |/usr/bin/mailx \-s "\`uname \-n\` daily mail stats" postmaster
407 \& Crontab entry to generate a report for the prior week\*(Aqs activity.
408 \& (This example assumes one rotates ones mail logs weekly, some time
409 \& before 4:10 a.m. on Sunday.)
411 \& 10 4 * * 0 /usr/local/sbin/pflogsumm /var/log/maillog.0
412 \& 2>&1 |/usr/bin/mailx \-s "\`uname \-n\` weekly mail stats" postmaster
414 \& The two crontab examples, above, must actually be a single line
415 \& each. They\*(Aqre broken\-up into two\-or\-more lines due to page
416 \& formatting issues.
419 .IX Header "SEE ALSO"
421 \& The pflogsumm FAQ: pflogsumm\-faq.txt.
426 \& Pflogsumm makes no attempt to catch/parse non\-Postfix log
427 \& entries. Unless it has "postfix/" in the log entry, it will be
430 \& It\*(Aqs important that the logs are presented to pflogsumm in
431 \& chronological order so that message sizes are available when
434 \& For display purposes: integer values are munged into "kilo" and
435 \& "mega" notation as they exceed certain values. I chose the
436 \& admittedly arbitrary boundaries of 512k and 512m as the points at
437 \& which to do this\-\-my thinking being 512x was the largest number
438 \& (of digits) that most folks can comfortably grok at\-a\-glance.
439 \& These are "computer" "k" and "m", not 1000 and 1,000,000. You
440 \& can easily change all of this with some constants near the
441 \& beginning of the program.
443 \& "Items\-per\-day" reports are not generated for single\-day
444 \& reports. For multiple\-day reports: "Items\-per\-hour" numbers are
445 \& daily averages (reflected in the report headings).
447 \& Message rejects, reject warnings, holds and discards are all
448 \& reported under the "rejects" column for the Per\-Hour and Per\-Day
449 \& traffic summaries.
451 \& Verp munging may not always result in correct address and
452 \& address\-count reduction.
454 \& Verp munging is always in a state of experimentation. The use
455 \& of this option may result in inaccurate statistics with regards
456 \& to the "senders" count.
458 \& UUCP\-style bang\-path handling needs more work. Particularly if
459 \& Postfix is not being run with "swap_bangpath = yes" and/or *is* being
460 \& run with "append_dot_mydomain = yes", the detailed by\-message report
461 \& may not be sorted correctly by\-domain\-by\-user. (Also depends on
462 \& upstream MTA, I suspect.)
464 \& The "percent rejected" and "percent discarded" figures are only
465 \& approximations. They are calculated as follows (example is for
466 \& "percent rejected"):
468 \& percent rejected =
470 \& (rejected / (delivered + rejected + discarded)) * 100
472 \& There are some issues with the use of \-\-syslog_name. The problem is
473 \& that, even with $syslog_name set, Postfix will sometimes still log
474 \& things with "postfix" as the syslog_name. This is noted in
475 \& /etc/postfix/sample\-misc.cf:
477 \& # Beware: a non\-default syslog_name setting takes effect only
478 \& # after process initialization. Some initialization errors will be
479 \& # logged with the default name, especially errors while parsing
480 \& # the command line and errors while accessing the Postfix main.cf
481 \& # configuration file.
483 \& As a consequence, pflogsumm must always look for "postfix," in logs,
484 \& as well as whatever is supplied for syslog_name.
486 \& Where this becomes an issue is where people are running two or more
487 \& instances of Postfix, logging to the same file. In such a case:
489 \& . Neither instance may use the default "postfix" syslog name
492 \& . Log entries that fall victim to what\*(Aqs described in
493 \& sample\-misc.cf will be reported under "postfix", so that if
494 \& you\*(Aqre running pflogsumm twice, once for each syslog_name, such
495 \& log entries will show up in each report.
497 \& The Pflogsumm Home Page is at:
499 \& http://jimsun.LinxNet.com/postfix_contrib.html
502 .IX Header "REQUIREMENTS"
504 \& For certain options (e.g.: \-\-smtpd_stats), Pflogsumm requires the
505 \& Date::Calc module, which can be obtained from CPAN at
506 \& http://www.perl.com.
508 \& Pflogsumm is currently written and tested under Perl 5.8.3.
509 \& As of version 19990413\-02, pflogsumm worked with Perl 5.003, but
510 \& future compatibility is not guaranteed.
515 \& This program is free software; you can redistribute it and/or
516 \& modify it under the terms of the GNU General Public License
517 \& as published by the Free Software Foundation; either version 2
518 \& of the License, or (at your option) any later version.
520 \& This program is distributed in the hope that it will be useful,
521 \& but WITHOUT ANY WARRANTY; without even the implied warranty of
522 \& MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
523 \& GNU General Public License for more details.
525 \& You may have received a copy of the GNU General Public License
526 \& along with this program; if not, write to the Free Software
527 \& Foundation, Inc., 59 Temple Place \- Suite 330, Boston, MA 02111\-1307,
530 \& An on\-line copy of the GNU General Public License can be found
531 \& http://www.fsf.org/copyleft/gpl.html.