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