1PFLOGSUMM(1) User Contributed Perl Documentation PFLOGSUMM(1)
2
6 pflogsumm.pl - Produce Postfix MTA logfile summary
7 Copyright (C) 1998-2010 by James S. Seymour, Release 1.1.5
9
11 pflogsumm.pl -[eq] [-d <today|yesterday>] [--detail <cnt>]
12 [--bounce-detail <cnt>] [--deferral-detail <cnt>]
13 [-h <cnt>] [-i|--ignore-case] [--iso-date-time] [--mailq]
14 [-m|--uucp-mung] [--no-no-msg-size] [--problems-first]
15 [--rej-add-from] [--reject-detail <cnt>] [--smtp-detail <cnt>]
16 [--smtpd-stats] [--smtpd-warning-detail <cnt>]
17 [--syslog-name=string] [-u <cnt>] [--verbose-msg-detail]
18 [--verp-mung[=<n>]] [--zero-fill] [file1 [filen]]
19 pflogsumm.pl -[help|version]
21 If no file(s) specified, reads from stdin. Output is to stdout.
23
25 Pflogsumm is a log analyzer/summarizer for the Postfix MTA. It is
26 designed to provide an over-view of Postfix activity, with just enough
27 detail to give the administrator a "heads up" for potential trouble
28 spots.
29 Pflogsumm generates summaries and, in some cases, detailed reports of
31 mail server traffic volumes, rejected and bounced email, and server
32 warnings, errors and panics.
33
35 --bounce-detail <cnt>
36 Limit detailed bounce reports to the top <cnt>. 0
38 to suppress entirely.
39 -d today generate report for just today
41 -d yesterday generate report for just "yesterday"
42 --deferral-detail <cnt>
44 Limit detailed deferral reports to the top <cnt>. 0
46 to suppress entirely.
47 --detail <cnt>
49 Sets all --*-detail, -h and -u to <cnt>. Is
51 over-ridden by individual settings. --detail 0
52 suppresses *all* detail.
53 -e extended (extreme? excessive?) detail
55 Emit detailed reports. At present, this includes
57 only a per-message report, sorted by sender domain,
58 then user-in-domain, then by queue i.d.
59 WARNING: the data built to generate this report can
61 quickly consume very large amounts of memory if a
62 lot of log entries are processed!
63 -h <cnt> top <cnt> to display in host/domain reports.
65 0 = none.
67 See also: "-u" and "--*-detail" options for further
69 report-limiting options.
70 --help Emit short usage message and bail out.
72 (By happy coincidence, "-h" alone does much the same,
74 being as it requires a numeric argument :-). Yeah, I
75 know: lame.)
76 -i
78 --ignore-case Handle complete email address in a case-insensitive
79 manner.
80 Normally pflogsumm lower-cases only the host and
82 domain parts, leaving the user part alone. This
83 option causes the entire email address to be lower-
84 cased.
85 --iso-date-time
87 For summaries that contain date or time information,
89 use ISO 8601 standard formats (CCYY-MM-DD and HH:MM),
90 rather than "Mon DD CCYY" and "HHMM".
91 -m modify (mung?) UUCP-style bang-paths
93 --uucp-mung
94 This is for use when you have a mix of Internet-style
96 domain addresses and UUCP-style bang-paths in the log.
97 Upstream UUCP feeds sometimes mung Internet domain
98 style address into bang-paths. This option can
99 sometimes undo the "damage". For example:
100 "somehost.dom!username@foo" (where "foo" is the next
101 host upstream and "somehost.dom" was whence the email
102 originated) will get converted to
103 "foo!username@somehost.dom". This also affects the
104 extended detail report (-e), to help ensure that by-
105 domain-by-name sorting is more accurate.
106 --mailq Run "mailq" command at end of report.
108 Merely a convenience feature. (Assumes that "mailq"
110 is in $PATH. See "$mailqCmd" variable to path thisi
111 if desired.)
112 --no_bounce_detail
114 --no_deferral_detail
115 --no_reject_detail
116 These switches are deprecated in favour of
118 --bounce-detail, --deferral-detail and
119 --reject-detail, respectively.
120 Suppresses the printing of the following detailed
122 reports, respectively:
123 message bounce detail (by relay)
125 message deferral detail
126 message reject detail
127 See also: "-u" and "-h" for further report-limiting
129 options.
130 --no-no-msg-size
132 Do not emit report on "Messages with no size data".
134 Message size is reported only by the queue manager.
136 The message may be delivered long-enough after the
137 (last) qmgr log entry that the information is not in
138 the log(s) processed by a particular run of
139 pflogsumm.pl. This throws off "Recipients by message
140 size" and the total for "bytes delivered." These are
141 normally reported by pflogsumm as "Messages with no
142 size data."
143 --no-smtpd-warnings
145 This switch is deprecated in favour of
147 smtpd-warning-detail
148 On a busy mail server, say at an ISP, SMTPD warnings
150 can result in a rather sizeable report. This option
151 turns reporting them off.
152 --problems-first
154 Emit "problems" reports (bounces, defers, warnings,
156 etc.) before "normal" stats.
157 --rej-add-from
159 For those reject reports that list IP addresses or
160 host/domain names: append the email from address to
161 each listing. (Does not apply to "Improper use of
162 SMTP command pipelining" report.)
163 -q quiet - don't print headings for empty reports
165 note: headings for warning, fatal, and "master"
167 messages will always be printed.
168 --reject-detail <cnt>
170 Limit detailed smtpd reject, warn, hold and discard
172 reports to the top <cnt>. 0 to suppress entirely.
173 --smtp-detail <cnt>
175 Limit detailed smtp delivery reports to the top <cnt>.
177 0 to suppress entirely.
178 --smtpd-stats
180 Generate smtpd connection statistics.
182 The "per-day" report is not generated for single-day
184 reports. For multiple-day reports: "per-hour" numbers
185 are daily averages (reflected in the report heading).
186 --smtpd-warning-detail <cnt>
188 Limit detailed smtpd warnings reports to the top <cnt>.
190 0 to suppress entirely.
191 --syslog-name=name
193 Set syslog-name to look for for Postfix log entries.
195 By default, pflogsumm looks for entries in logfiles
197 with a syslog name of "postfix," the default.
198 If you've set a non-default "syslog_name" parameter
199 in your Postfix configuration, use this option to
200 tell pflogsumm what that is.
201 See the discussion about the use of this option under
203 "NOTES," below.
204 -u <cnt> top <cnt> to display in user reports. 0 == none.
206 See also: "-h" and "--*-detail" options for further
208 report-limiting options.
209 --verbose-msg-detail
211 For the message deferral, bounce and reject summaries:
213 display the full "reason", rather than a truncated one.
214 Note: this can result in quite long lines in the report.
216 --verp-mung do "VERP" generated address (?) munging. Convert
218 --verp-mung=2 sender addresses of the form
219 "list-return-NN-someuser=some.dom@host.sender.dom"
220 to
221 "list-return-ID-someuser=some.dom@host.sender.dom"
222 In other words: replace the numeric value with "ID".
224 By specifying the optional "=2" (second form), the
226 munging is more "aggressive", converting the address
227 to something like:
228 "list-return@host.sender.dom"
230 Actually: specifying anything less than 2 does the
232 "simple" munging and anything greater than 1 results
233 in the more "aggressive" hack being applied.
234 See "NOTES" regarding this option.
236 --version Print program name and version and bail out.
238 --zero-fill "Zero-fill" certain arrays so reports come out with
240 data in columns that that might otherwise be blank.
241
243 Pflogsumm doesn't return anything of interest to the shell.
244
246 Error messages are emitted to stderr.
247
249 Produce a report of previous day's activities:
250 pflogsumm.pl -d yesterday /var/log/maillog
252 A report of prior week's activities (after logs rotated):
254 pflogsumm.pl /var/log/maillog.0
256 What's happened so far today:
258 pflogsumm.pl -d today /var/log/maillog
260 Crontab entry to generate a report of the previous day's activity
262 at 10 minutes after midnight.
263 10 0 * * * /usr/local/sbin/pflogsumm -d yesterday /var/log/maillog
265 2>&1 |/usr/bin/mailx -s "`uname -n` daily mail stats" postmaster
266 Crontab entry to generate a report for the prior week's activity.
268 (This example assumes one rotates ones mail logs weekly, some time
269 before 4:10 a.m. on Sunday.)
270 10 4 * * 0 /usr/local/sbin/pflogsumm /var/log/maillog.0
272 2>&1 |/usr/bin/mailx -s "`uname -n` weekly mail stats" postmaster
273 The two crontab examples, above, must actually be a single line
275 each. They're broken-up into two-or-more lines due to page
276 formatting issues.
277
279 The pflogsumm FAQ: pflogsumm-faq.txt.
280
282 Pflogsumm makes no attempt to catch/parse non-Postfix log
283 entries. Unless it has "postfix/" in the log entry, it will be
284 ignored.
285 It's important that the logs are presented to pflogsumm in
287 chronological order so that message sizes are available when
288 needed.
289 For display purposes: integer values are munged into "kilo" and
291 "mega" notation as they exceed certain values. I chose the
292 admittedly arbitrary boundaries of 512k and 512m as the points at
293 which to do this--my thinking being 512x was the largest number
294 (of digits) that most folks can comfortably grok at-a-glance.
295 These are "computer" "k" and "m", not 1000 and 1,000,000. You
296 can easily change all of this with some constants near the
297 beginning of the program.
298 "Items-per-day" reports are not generated for single-day
300 reports. For multiple-day reports: "Items-per-hour" numbers are
301 daily averages (reflected in the report headings).
302 Message rejects, reject warnings, holds and discards are all
304 reported under the "rejects" column for the Per-Hour and Per-Day
305 traffic summaries.
306 Verp munging may not always result in correct address and
308 address-count reduction.
309 Verp munging is always in a state of experimentation. The use
311 of this option may result in inaccurate statistics with regards
312 to the "senders" count.
313 UUCP-style bang-path handling needs more work. Particularly if
315 Postfix is not being run with "swap_bangpath = yes" and/or *is* being
316 run with "append_dot_mydomain = yes", the detailed by-message report
317 may not be sorted correctly by-domain-by-user. (Also depends on
318 upstream MTA, I suspect.)
319 The "percent rejected" and "percent discarded" figures are only
321 approximations. They are calculated as follows (example is for
322 "percent rejected"):
323 percent rejected =
325 (rejected / (delivered + rejected + discarded)) * 100
327 There are some issues with the use of --syslog-name. The problem is
329 that, even with Postfix' $syslog_name set, it will sometimes still
330 log things with "postfix" as the syslog_name. This is noted in
331 /etc/postfix/sample-misc.cf:
332 # Beware: a non-default syslog_name setting takes effect only
334 # after process initialization. Some initialization errors will be
335 # logged with the default name, especially errors while parsing
336 # the command line and errors while accessing the Postfix main.cf
337 # configuration file.
338 As a consequence, pflogsumm must always look for "postfix," in logs,
340 as well as whatever is supplied for syslog_name.
341 Where this becomes an issue is where people are running two or more
343 instances of Postfix, logging to the same file. In such a case:
344 . Neither instance may use the default "postfix" syslog name
346 and...
347 . Log entries that fall victim to what's described in
349 sample-misc.cf will be reported under "postfix", so that if
350 you're running pflogsumm twice, once for each syslog_name, such
351 log entries will show up in each report.
352 The Pflogsumm Home Page is at:
354 http://jimsun.LinxNet.com/postfix_contrib.html
356
358 For certain options (e.g.: --smtpd-stats), Pflogsumm requires the
359 Date::Calc module, which can be obtained from CPAN at
360 http://www.perl.com.
361 Pflogsumm is currently written and tested under Perl 5.8.3.
363 As of version 19990413-02, pflogsumm worked with Perl 5.003, but
364 future compatibility is not guaranteed.
365
367 This program is free software; you can redistribute it and/or
368 modify it under the terms of the GNU General Public License
369 as published by the Free Software Foundation; either version 2
370 of the License, or (at your option) any later version.
371 This program is distributed in the hope that it will be useful,
373 but WITHOUT ANY WARRANTY; without even the implied warranty of
374 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
375 GNU General Public License for more details.
376 You may have received a copy of the GNU General Public License
378 along with this program; if not, write to the Free Software
379 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
380 USA.
381 An on-line copy of the GNU General Public License can be found
383 http://www.fsf.org/copyleft/gpl.html.
3841.1.5 2012-02-05 PFLOGSUMM(1)