releasing version 1.1.4-1
[sven/pflogsumm.git] / pflogsumm.1
1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.13)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
6 .if t .sp .5v
7 .if n .sp
8 ..
9 .de Vb \" Begin verbatim text
10 .ft CW
11 .nf
12 .ne \\$1
13 ..
14 .de Ve \" End verbatim text
15 .ft R
16 .fi
17 ..
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<>.
24 .tr \(*W-
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26 .ie n \{\
27 .    ds -- \(*W-
28 .    ds PI pi
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
31 .    ds L" ""
32 .    ds R" ""
33 .    ds C` ""
34 .    ds C' ""
35 'br\}
36 .el\{\
37 .    ds -- \|\(em\|
38 .    ds PI \(*p
39 .    ds L" ``
40 .    ds R" ''
41 'br\}
42 .\"
43 .\" Escape single quotes in literal strings from groff's Unicode transform.
44 .ie \n(.g .ds Aq \(aq
45 .el       .ds Aq '
46 .\"
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.
51 .ie \nF \{\
52 .    de IX
53 .    tm Index:\\$1\t\\n%\t"\\$2"
54 ..
55 .    nr % 0
56 .    rr F
57 .\}
58 .el \{\
59 .    de IX
60 ..
61 .\}
62 .\"
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
66 .if n \{\
67 .    ds #H 0
68 .    ds #V .8m
69 .    ds #F .3m
70 .    ds #[ \f1
71 .    ds #] \fP
72 .\}
73 .if t \{\
74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75 .    ds #V .6m
76 .    ds #F 0
77 .    ds #[ \&
78 .    ds #] \&
79 .\}
80 .    \" simple accents for nroff and troff
81 .if n \{\
82 .    ds ' \&
83 .    ds ` \&
84 .    ds ^ \&
85 .    ds , \&
86 .    ds ~ ~
87 .    ds /
88 .\}
89 .if t \{\
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'
96 .\}
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 \
112 \{\
113 .    ds : e
114 .    ds 8 ss
115 .    ds o a
116 .    ds d- d\h'-1'\(ga
117 .    ds D- D\h'-1'\(hy
118 .    ds th \o'bp'
119 .    ds Th \o'LP'
120 .    ds ae ae
121 .    ds Ae AE
122 .\}
123 .rm #[ #] #H #V #F C
124 .\" ========================================================================
125 .\"
126 .IX Title "PFLOGSUMM 1"
127 .TH PFLOGSUMM 1 "2012-02-01" "1.1.4" "User Contributed Perl Documentation"
128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
129 .\" way too many mistakes in technical documents.
130 .if n .ad l
131 .nh
132 .SH "NAME"
133 pflogsumm.pl \- Produce Postfix MTA logfile summary
134 .PP
135 Copyright (C) 1998\-2010 by James S. Seymour, Release 1.1.4
136 .SH "SYNOPSIS"
137 .IX Header "SYNOPSIS"
138 .Vb 8
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\-no\-msg\-size] [\-\-problems\-first]
143 \&        [\-\-rej\-add\-from] [\-\-reject\-detail <cnt>] [\-\-smtp\-detail <cnt>]
144 \&        [\-\-smtpd\-stats] [\-\-smtpd\-warning\-detail <cnt>]
145 \&        [\-\-syslog\-name=string] [\-u <cnt>] [\-\-verbose\-msg\-detail]
146 \&        [\-\-verp\-mung[=<n>]] [\-\-zero\-fill] [file1 [filen]]
147 \&
148 \&    pflogsumm.pl \-[help|version]
149 \&
150 \&    If no file(s) specified, reads from stdin.  Output is to stdout.
151 .Ve
152 .SH "DESCRIPTION"
153 .IX Header "DESCRIPTION"
154 .Vb 4
155 \&    Pflogsumm is a log analyzer/summarizer for the Postfix MTA.  It is
156 \&    designed to provide an over\-view of Postfix activity, with just enough
157 \&    detail to give the administrator a "heads up" for potential trouble
158 \&    spots.
159 \&    
160 \&    Pflogsumm generates summaries and, in some cases, detailed reports of
161 \&    mail server traffic volumes, rejected and bounced email, and server
162 \&    warnings, errors and panics.
163 .Ve
164 .SH "OPTIONS"
165 .IX Header "OPTIONS"
166 .Vb 1
167 \&    \-\-bounce\-detail <cnt>
168 \&
169 \&                   Limit detailed bounce reports to the top <cnt>.  0
170 \&                   to suppress entirely.
171 \&
172 \&    \-d today       generate report for just today
173 \&    \-d yesterday   generate report for just "yesterday"
174 \&
175 \&    \-\-deferral\-detail <cnt>
176 \&
177 \&                   Limit detailed deferral reports to the top <cnt>.  0
178 \&                   to suppress entirely.
179 \&
180 \&    \-\-detail <cnt>
181 \&    
182 \&                   Sets all \-\-*\-detail, \-h and \-u to <cnt>.  Is
183 \&                   over\-ridden by individual settings.  \-\-detail 0
184 \&                   suppresses *all* detail.
185 \&
186 \&    \-e             extended (extreme? excessive?) detail
187 \&
188 \&                   Emit detailed reports.  At present, this includes
189 \&                   only a per\-message report, sorted by sender domain,
190 \&                   then user\-in\-domain, then by queue i.d.
191 \&
192 \&                   WARNING: the data built to generate this report can
193 \&                   quickly consume very large amounts of memory if a
194 \&                   lot of log entries are processed!
195 \&
196 \&    \-h <cnt>       top <cnt> to display in host/domain reports.
197 \&    
198 \&                   0 = none.
199 \&
200 \&                   See also: "\-u" and "\-\-*\-detail" options for further
201 \&                             report\-limiting options.
202 \&
203 \&    \-\-help         Emit short usage message and bail out.
204 \&    
205 \&                   (By happy coincidence, "\-h" alone does much the same,
206 \&                   being as it requires a numeric argument :\-).  Yeah, I
207 \&                   know: lame.)
208 \&
209 \&    \-i
210 \&    \-\-ignore\-case  Handle complete email address in a case\-insensitive
211 \&                   manner.
212 \&                   
213 \&                   Normally pflogsumm lower\-cases only the host and
214 \&                   domain parts, leaving the user part alone.  This
215 \&                   option causes the entire email address to be lower\-
216 \&                   cased.
217 \&
218 \&    \-\-iso\-date\-time
219 \&
220 \&                   For summaries that contain date or time information,
221 \&                   use ISO 8601 standard formats (CCYY\-MM\-DD and HH:MM),
222 \&                   rather than "Mon DD CCYY" and "HHMM".
223 \&
224 \&    \-m             modify (mung?) UUCP\-style bang\-paths
225 \&    \-\-uucp\-mung
226 \&
227 \&                   This is for use when you have a mix of Internet\-style
228 \&                   domain addresses and UUCP\-style bang\-paths in the log.
229 \&                   Upstream UUCP feeds sometimes mung Internet domain
230 \&                   style address into bang\-paths.  This option can
231 \&                   sometimes undo the "damage".  For example:
232 \&                   "somehost.dom!username@foo" (where "foo" is the next
233 \&                   host upstream and "somehost.dom" was whence the email
234 \&                   originated) will get converted to
235 \&                   "foo!username@somehost.dom".  This also affects the
236 \&                   extended detail report (\-e), to help ensure that by\-
237 \&                    domain\-by\-name sorting is more accurate.
238 \&
239 \&    \-\-mailq        Run "mailq" command at end of report.
240 \&    
241 \&                   Merely a convenience feature.  (Assumes that "mailq"
242 \&                   is in $PATH.  See "$mailqCmd" variable to path thisi
243 \&                   if desired.)
244 \&
245 \&    \-\-no_bounce_detail
246 \&    \-\-no_deferral_detail
247 \&    \-\-no_reject_detail
248 \&
249 \&                   These switches are deprecated in favour of
250 \&                   \-\-bounce\-detail, \-\-deferral\-detail and
251 \&                   \-\-reject\-detail, respectively.
252 \&
253 \&                   Suppresses the printing of the following detailed
254 \&                   reports, respectively:
255 \&
256 \&                        message bounce detail (by relay)
257 \&                        message deferral detail
258 \&                        message reject detail
259 \&
260 \&                   See also: "\-u" and "\-h" for further report\-limiting
261 \&                             options.
262 \&
263 \&    \-\-no\-no\-msg\-size
264 \&
265 \&                    Do not emit report on "Messages with no size data".
266 \&
267 \&                    Message size is reported only by the queue manager.
268 \&                    The message may be delivered long\-enough after the
269 \&                    (last) qmgr log entry that the information is not in
270 \&                    the log(s) processed by a particular run of
271 \&                    pflogsumm.pl.  This throws off "Recipients by message
272 \&                    size" and the total for "bytes delivered." These are
273 \&                    normally reported by pflogsumm as "Messages with no
274 \&                    size data."
275 \&
276 \&    \-\-no\-smtpd\-warnings
277 \&
278 \&                   This switch is deprecated in favour of
279 \&                   smtpd\-warning\-detail
280 \&
281 \&                    On a busy mail server, say at an ISP, SMTPD warnings
282 \&                    can result in a rather sizeable report.  This option
283 \&                    turns reporting them off.
284 \&
285 \&    \-\-problems\-first
286 \&
287 \&                   Emit "problems" reports (bounces, defers, warnings,
288 \&                   etc.) before "normal" stats.
289 \&
290 \&    \-\-rej\-add\-from
291 \&                   For those reject reports that list IP addresses or
292 \&                   host/domain names: append the email from address to
293 \&                   each listing.  (Does not apply to "Improper use of
294 \&                   SMTP command pipelining" report.)
295 \&
296 \&    \-q             quiet \- don\*(Aqt print headings for empty reports
297 \&    
298 \&                   note: headings for warning, fatal, and "master"
299 \&                   messages will always be printed.
300 \&
301 \&    \-\-reject\-detail <cnt>
302 \&
303 \&                   Limit detailed smtpd reject, warn, hold and discard
304 \&                   reports to the top <cnt>.  0 to suppress entirely.
305 \&
306 \&    \-\-smtp\-detail <cnt>
307 \&
308 \&                   Limit detailed smtp delivery reports to the top <cnt>.
309 \&                   0 to suppress entirely.
310 \&
311 \&    \-\-smtpd\-stats
312 \&
313 \&                   Generate smtpd connection statistics.
314 \&
315 \&                   The "per\-day" report is not generated for single\-day
316 \&                   reports.  For multiple\-day reports: "per\-hour" numbers
317 \&                   are daily averages (reflected in the report heading).
318 \&
319 \&    \-\-smtpd\-warning\-detail <cnt>
320 \&
321 \&                   Limit detailed smtpd warnings reports to the top <cnt>.
322 \&                   0 to suppress entirely.
323 \&
324 \&    \-\-syslog\-name=name
325 \&
326 \&                   Set syslog\-name to look for for Postfix log entries.
327 \&
328 \&                   By default, pflogsumm looks for entries in logfiles
329 \&                   with a syslog name of "postfix," the default.
330 \&                   If you\*(Aqve set a non\-default "syslog_name" parameter
331 \&                   in your Postfix configuration, use this option to
332 \&                   tell pflogsumm what that is.
333 \&
334 \&                   See the discussion about the use of this option under
335 \&                   "NOTES," below.
336 \&
337 \&    \-u <cnt>       top <cnt> to display in user reports. 0 == none.
338 \&
339 \&                   See also: "\-h" and "\-\-*\-detail" options for further
340 \&                             report\-limiting options.
341 \&
342 \&    \-\-verbose\-msg\-detail
343 \&
344 \&                   For the message deferral, bounce and reject summaries:
345 \&                   display the full "reason", rather than a truncated one.
346 \&
347 \&                   Note: this can result in quite long lines in the report.
348 \&
349 \&    \-\-verp\-mung    do "VERP" generated address (?) munging.  Convert
350 \&    \-\-verp\-mung=2  sender addresses of the form
351 \&                   "list\-return\-NN\-someuser=some.dom@host.sender.dom"
352 \&                    to
353 \&                      "list\-return\-ID\-someuser=some.dom@host.sender.dom"
354 \&
355 \&                    In other words: replace the numeric value with "ID".
356 \&
357 \&                   By specifying the optional "=2" (second form), the
358 \&                   munging is more "aggressive", converting the address
359 \&                   to something like:
360 \&
361 \&                        "list\-return@host.sender.dom"
362 \&
363 \&                   Actually: specifying anything less than 2 does the
364 \&                   "simple" munging and anything greater than 1 results
365 \&                   in the more "aggressive" hack being applied.
366 \&
367 \&                   See "NOTES" regarding this option.
368 \&
369 \&    \-\-version      Print program name and version and bail out.
370 \&
371 \&    \-\-zero\-fill    "Zero\-fill" certain arrays so reports come out with
372 \&                   data in columns that that might otherwise be blank.
373 .Ve
374 .SH "RETURN VALUE"
375 .IX Header "RETURN VALUE"
376 .Vb 1
377 \&    Pflogsumm doesn\*(Aqt return anything of interest to the shell.
378 .Ve
379 .SH "ERRORS"
380 .IX Header "ERRORS"
381 .Vb 1
382 \&    Error messages are emitted to stderr.
383 .Ve
384 .SH "EXAMPLES"
385 .IX Header "EXAMPLES"
386 .Vb 1
387 \&    Produce a report of previous day\*(Aqs activities:
388 \&
389 \&        pflogsumm.pl \-d yesterday /var/log/maillog
390 \&
391 \&    A report of prior week\*(Aqs activities (after logs rotated):
392 \&
393 \&        pflogsumm.pl /var/log/maillog.0
394 \&
395 \&    What\*(Aqs happened so far today:
396 \&
397 \&        pflogsumm.pl \-d today /var/log/maillog
398 \&
399 \&    Crontab entry to generate a report of the previous day\*(Aqs activity
400 \&    at 10 minutes after midnight.
401 \&
402 \&        10 0 * * * /usr/local/sbin/pflogsumm \-d yesterday /var/log/maillog
403 \&        2>&1 |/usr/bin/mailx \-s "\`uname \-n\` daily mail stats" postmaster
404 \&
405 \&    Crontab entry to generate a report for the prior week\*(Aqs activity.
406 \&    (This example assumes one rotates ones mail logs weekly, some time
407 \&    before 4:10 a.m. on Sunday.)
408 \&
409 \&        10 4 * * 0   /usr/local/sbin/pflogsumm /var/log/maillog.0
410 \&        2>&1 |/usr/bin/mailx \-s "\`uname \-n\` weekly mail stats" postmaster
411 \&
412 \&    The two crontab examples, above, must actually be a single line
413 \&    each.  They\*(Aqre broken\-up into two\-or\-more lines due to page
414 \&    formatting issues.
415 .Ve
416 .SH "SEE ALSO"
417 .IX Header "SEE ALSO"
418 .Vb 1
419 \&    The pflogsumm FAQ: pflogsumm\-faq.txt.
420 .Ve
421 .SH "NOTES"
422 .IX Header "NOTES"
423 .Vb 3
424 \&    Pflogsumm makes no attempt to catch/parse non\-Postfix log
425 \&    entries.  Unless it has "postfix/" in the log entry, it will be
426 \&    ignored.
427 \&
428 \&    It\*(Aqs important that the logs are presented to pflogsumm in
429 \&    chronological order so that message sizes are available when
430 \&    needed.
431 \&
432 \&    For display purposes: integer values are munged into "kilo" and
433 \&    "mega" notation as they exceed certain values.  I chose the
434 \&    admittedly arbitrary boundaries of 512k and 512m as the points at
435 \&    which to do this\-\-my thinking being 512x was the largest number
436 \&    (of digits) that most folks can comfortably grok at\-a\-glance.
437 \&    These are "computer" "k" and "m", not 1000 and 1,000,000.  You
438 \&    can easily change all of this with some constants near the
439 \&    beginning of the program.
440 \&
441 \&    "Items\-per\-day" reports are not generated for single\-day
442 \&    reports.  For multiple\-day reports: "Items\-per\-hour" numbers are
443 \&    daily averages (reflected in the report headings).
444 \&
445 \&    Message rejects, reject warnings, holds and discards are all
446 \&    reported under the "rejects" column for the Per\-Hour and Per\-Day
447 \&    traffic summaries.
448 \&
449 \&    Verp munging may not always result in correct address and
450 \&    address\-count reduction.
451 \&
452 \&    Verp munging is always in a state of experimentation.  The use
453 \&    of this option may result in inaccurate statistics with regards
454 \&    to the "senders" count.
455 \&
456 \&    UUCP\-style bang\-path handling needs more work.  Particularly if
457 \&    Postfix is not being run with "swap_bangpath = yes" and/or *is* being
458 \&    run with "append_dot_mydomain = yes", the detailed by\-message report
459 \&    may not be sorted correctly by\-domain\-by\-user.  (Also depends on
460 \&    upstream MTA, I suspect.)
461 \&
462 \&    The "percent rejected" and "percent discarded" figures are only
463 \&    approximations.  They are calculated as follows (example is for
464 \&    "percent rejected"):
465 \&
466 \&        percent rejected =
467 \&        
468 \&            (rejected / (delivered + rejected + discarded)) * 100
469 \&
470 \&    There are some issues with the use of \-\-syslog\-name.  The problem is
471 \&    that, even with Postfix\*(Aq $syslog_name set, it will sometimes still
472 \&    log things with "postfix" as the syslog_name.  This is noted in
473 \&    /etc/postfix/sample\-misc.cf:
474 \&
475 \&        # Beware: a non\-default syslog_name setting takes effect only
476 \&        # after process initialization. Some initialization errors will be
477 \&        # logged with the default name, especially errors while parsing
478 \&        # the command line and errors while accessing the Postfix main.cf
479 \&        # configuration file.
480 \&
481 \&    As a consequence, pflogsumm must always look for "postfix," in logs,
482 \&    as well as whatever is supplied for syslog_name.
483 \&
484 \&    Where this becomes an issue is where people are running two or more
485 \&    instances of Postfix, logging to the same file.  In such a case:
486 \&
487 \&        . Neither instance may use the default "postfix" syslog name
488 \&          and...
489 \&
490 \&        . Log entries that fall victim to what\*(Aqs described in
491 \&          sample\-misc.cf will be reported under "postfix", so that if
492 \&          you\*(Aqre running pflogsumm twice, once for each syslog_name, such
493 \&          log entries will show up in each report.
494 \&
495 \&    The Pflogsumm Home Page is at:
496 \&
497 \&        http://jimsun.LinxNet.com/postfix_contrib.html
498 .Ve
499 .SH "REQUIREMENTS"
500 .IX Header "REQUIREMENTS"
501 .Vb 3
502 \&    For certain options (e.g.: \-\-smtpd\-stats), Pflogsumm requires the
503 \&    Date::Calc module, which can be obtained from CPAN at
504 \&    http://www.perl.com.
505 \&
506 \&    Pflogsumm is currently written and tested under Perl 5.8.3.
507 \&    As of version 19990413\-02, pflogsumm worked with Perl 5.003, but
508 \&    future compatibility is not guaranteed.
509 .Ve
510 .SH "LICENSE"
511 .IX Header "LICENSE"
512 .Vb 4
513 \&    This program is free software; you can redistribute it and/or
514 \&    modify it under the terms of the GNU General Public License
515 \&    as published by the Free Software Foundation; either version 2
516 \&    of the License, or (at your option) any later version.
517 \&    
518 \&    This program is distributed in the hope that it will be useful,
519 \&    but WITHOUT ANY WARRANTY; without even the implied warranty of
520 \&    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
521 \&    GNU General Public License for more details.
522 \&    
523 \&    You may have received a copy of the GNU General Public License
524 \&    along with this program; if not, write to the Free Software
525 \&    Foundation, Inc., 59 Temple Place \- Suite 330, Boston, MA  02111\-1307,
526 \&    USA.
527 \&    
528 \&    An on\-line copy of the GNU General Public License can be found
529 \&    http://www.fsf.org/copyleft/gpl.html.
530 .Ve