1PFLOGSUMM(1)          User Contributed Perl Documentation         PFLOGSUMM(1)
2
3
4

NAME

6       pflogsumm.pl - Produce Postfix MTA logfile summary
7
8       Copyright (C) 1998-2010 by James S. Seymour, Release 1.1.5
9

SYNOPSIS

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
20           pflogsumm.pl -[help|version]
21
22           If no file(s) specified, reads from stdin.  Output is to stdout.
23

DESCRIPTION

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
30           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

OPTIONS

35           --bounce-detail <cnt>
36
37                          Limit detailed bounce reports to the top <cnt>.  0
38                          to suppress entirely.
39
40           -d today       generate report for just today
41           -d yesterday   generate report for just "yesterday"
42
43           --deferral-detail <cnt>
44
45                          Limit detailed deferral reports to the top <cnt>.  0
46                          to suppress entirely.
47
48           --detail <cnt>
49
50                          Sets all --*-detail, -h and -u to <cnt>.  Is
51                          over-ridden by individual settings.  --detail 0
52                          suppresses *all* detail.
53
54           -e             extended (extreme? excessive?) detail
55
56                          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
60                          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
64           -h <cnt>       top <cnt> to display in host/domain reports.
65
66                          0 = none.
67
68                          See also: "-u" and "--*-detail" options for further
69                                    report-limiting options.
70
71           --help         Emit short usage message and bail out.
72
73                          (By happy coincidence, "-h" alone does much the same,
74                          being as it requires a numeric argument :-).  Yeah, I
75                          know: lame.)
76
77           -i
78           --ignore-case  Handle complete email address in a case-insensitive
79                          manner.
80
81                          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
86           --iso-date-time
87
88                          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
92           -m             modify (mung?) UUCP-style bang-paths
93           --uucp-mung
94
95                          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
107           --mailq        Run "mailq" command at end of report.
108
109                          Merely a convenience feature.  (Assumes that "mailq"
110                          is in $PATH.  See "$mailqCmd" variable to path thisi
111                          if desired.)
112
113           --no_bounce_detail
114           --no_deferral_detail
115           --no_reject_detail
116
117                          These switches are deprecated in favour of
118                          --bounce-detail, --deferral-detail and
119                          --reject-detail, respectively.
120
121                          Suppresses the printing of the following detailed
122                          reports, respectively:
123
124                               message bounce detail (by relay)
125                               message deferral detail
126                               message reject detail
127
128                          See also: "-u" and "-h" for further report-limiting
129                                    options.
130
131           --no-no-msg-size
132
133                           Do not emit report on "Messages with no size data".
134
135                           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
144           --no-smtpd-warnings
145
146                          This switch is deprecated in favour of
147                          smtpd-warning-detail
148
149                           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
153           --problems-first
154
155                          Emit "problems" reports (bounces, defers, warnings,
156                          etc.) before "normal" stats.
157
158           --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
164           -q             quiet - don't print headings for empty reports
165
166                          note: headings for warning, fatal, and "master"
167                          messages will always be printed.
168
169           --reject-detail <cnt>
170
171                          Limit detailed smtpd reject, warn, hold and discard
172                          reports to the top <cnt>.  0 to suppress entirely.
173
174           --smtp-detail <cnt>
175
176                          Limit detailed smtp delivery reports to the top <cnt>.
177                          0 to suppress entirely.
178
179           --smtpd-stats
180
181                          Generate smtpd connection statistics.
182
183                          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
187           --smtpd-warning-detail <cnt>
188
189                          Limit detailed smtpd warnings reports to the top <cnt>.
190                          0 to suppress entirely.
191
192           --syslog-name=name
193
194                          Set syslog-name to look for for Postfix log entries.
195
196                          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
202                          See the discussion about the use of this option under
203                          "NOTES," below.
204
205           -u <cnt>       top <cnt> to display in user reports. 0 == none.
206
207                          See also: "-h" and "--*-detail" options for further
208                                    report-limiting options.
209
210           --verbose-msg-detail
211
212                          For the message deferral, bounce and reject summaries:
213                          display the full "reason", rather than a truncated one.
214
215                          Note: this can result in quite long lines in the report.
216
217           --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
223                           In other words: replace the numeric value with "ID".
224
225                          By specifying the optional "=2" (second form), the
226                          munging is more "aggressive", converting the address
227                          to something like:
228
229                               "list-return@host.sender.dom"
230
231                          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
235                          See "NOTES" regarding this option.
236
237           --version      Print program name and version and bail out.
238
239           --zero-fill    "Zero-fill" certain arrays so reports come out with
240                          data in columns that that might otherwise be blank.
241

RETURN VALUE

243           Pflogsumm doesn't return anything of interest to the shell.
244

ERRORS

246           Error messages are emitted to stderr.
247

EXAMPLES

249           Produce a report of previous day's activities:
250
251               pflogsumm.pl -d yesterday /var/log/maillog
252
253           A report of prior week's activities (after logs rotated):
254
255               pflogsumm.pl /var/log/maillog.0
256
257           What's happened so far today:
258
259               pflogsumm.pl -d today /var/log/maillog
260
261           Crontab entry to generate a report of the previous day's activity
262           at 10 minutes after midnight.
263
264               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
267           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
271               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
274           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

SEE ALSO

279           The pflogsumm FAQ: pflogsumm-faq.txt.
280

NOTES

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
286           It's important that the logs are presented to pflogsumm in
287           chronological order so that message sizes are available when
288           needed.
289
290           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
299           "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
303           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
307           Verp munging may not always result in correct address and
308           address-count reduction.
309
310           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
314           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
320           The "percent rejected" and "percent discarded" figures are only
321           approximations.  They are calculated as follows (example is for
322           "percent rejected"):
323
324               percent rejected =
325
326                   (rejected / (delivered + rejected + discarded)) * 100
327
328           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
333               # 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
339           As a consequence, pflogsumm must always look for "postfix," in logs,
340           as well as whatever is supplied for syslog_name.
341
342           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
345               . Neither instance may use the default "postfix" syslog name
346                 and...
347
348               . 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
353           The Pflogsumm Home Page is at:
354
355               http://jimsun.LinxNet.com/postfix_contrib.html
356

REQUIREMENTS

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
362           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

LICENSE

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
372           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
377           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
382           An on-line copy of the GNU General Public License can be found
383           http://www.fsf.org/copyleft/gpl.html.
384
385
386
3871.1.5                             2012-02-05                      PFLOGSUMM(1)
Impressum