1 <!doctype html public
"-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html4/loose.dtd">
4 <meta http-equiv=
"Content-Type" content=
"text/html; charset=us-ascii">
5 <title> Man page: postfix-logwatch(
1)
</title>
7 POSTFIX-LOGWATCH(
1) General Commands Manual POSTFIX-LOGWATCH(
1)
12 postfix-logwatch - A Postfix log parser and analysis utility
15 <b>postfix-logwatch
</b> [
<i>options
</i>] [
<i>logfile ...
</i>]
18 The
<b>postfix-logwatch
</b>(
1) utility is a Postfix MTA log parser that pro-
19 duces summaries, details, and statistics regarding the operation of
22 This utility can be used as a standalone program, or as a Logwatch fil-
23 ter module to produce Postfix summary and detailed reports from within
26 <b>Postfix-logwatch
</b> is able to produce a wide range of reports with data
27 grouped and sorted as much as possible to reduce noise and highlight
28 patterns. Brief summary reports provide a quick overview of general
29 Postfix operations and message delivery, calling out warnings that may
30 require attention. Detailed reports provide easy to scan, hierarchi-
31 cally-arranged and organized information, with as much or little detail
34 <b>Postfix-logwatch
</b> outputs two principal sections: a
<b>Summary
</b> section and
35 a
<b>Detailed
</b> section. For readability and quick scanning, all event or
36 hit counts appear in the left column, followed by brief description of
37 the event type, and finally additional statistics or count representa-
38 tions may appear in the rightmost column.
40 The following segment from a sample Summary report illustrates:
42 ****** Summary ********************************************
44 81 *Warning: Connection rate limit reached (anvil)
47 68.310M Bytes accepted
71,
628,
177
48 97.645M Bytes delivered
102,
388,
245
49 ======== ================================================
53 -------- ------------------------------------------------
55 ======== ================================================
57 The report warns that anvil's connection rate was hit
81 times, a Post-
58 fix access check WARN action was logged
146 times, and a total of
59 68.310 megabytes (
71,
628,
177 bytes) were accepted into the Postfix sys-
60 tem, delivering
97.645 megabytes of data (due to multiple recipients).
61 The Accepted and Rejected lines show that Postfix accepted
3464 (
41.44%
62 of the total messages) and rejected
4895 (the remaining
58.56%) of the
63 8359 total messages (temporary rejects show up elsewhere).
65 There are dozens of sub-sections available in the
<b>Detailed
</b> report, each
66 of whose output can be controlled in various ways. Each sub-section
67 attempts to group and present the most meaningful data at superior lev-
68 els, while pushing less useful or
<i>noisy
</i> data towards inferior levels.
69 The goal is to provide as much benefit as possible from smart grouping
70 of data, to allow faster report scanning, pattern identification, and
71 problem solving. Data is always sorted in descending order by count,
72 and then numerically by IP address or alphabetically as appropriate.
74 The following MX errors segment from a sample
<b>Detailed
</b> report illus-
75 trates the basic hierarchical level structure of
<b>postfix-logwatch
</b>:
77 ****** Detailed *******************************************
79 261 MX errors --------------------------------------
80 261 Unable to look up MX host
82 73 foolishspammer.local
83 60 completely.bogus.domain.example
85 39 No address associated with hostname
87 16 pushn.spam.sample.com
90 The
<b>postfix-logwatch
</b> utility reads from STDIN or from the named Postfix
91 <i>logfile
</i>. Multiple
<i>logfile
</i> arguments may be specified, each processed
92 in order. The user running
<b>postfix-logwatch
</b> must have read permission
93 on each named log file.
96 The options listed below affect the operation of
<b>postfix-logwatch
</b>.
97 Options specified later on the command line override earlier ones. Any
98 option may be abbreviated to an unambiguous length.
101 <b>-f
</b> <i>config
</i><b>_
</b><i>file
</i>
102 <b>--config_file
</b> <i>config
</i><b>_
</b><i>file
</i>
103 Use an alternate configuration file
<i>config
</i><b>_
</b><i>file
</i> instead of the
104 default. This option may be used more than once. Multiple con-
105 figuration files will be processed in the order presented on the
106 command line. See
<b>CONFIGURATION FILE
</b> below.
108 <b>--debug
</b> <i>keywords
</i>
109 Output debug information during the operation of
<b>postfix-log-
</b>
110 <b>watch
</b>. The parameter
<i>keywords
</i> is one or more comma or space
111 separated keywords. To obtain the list of valid keywords, use
112 --debug xxx where xxx is any invalid keyword.
115 Enables (disables) output of the message delays percentiles
116 report. The delays percentiles report shows percentiles for
117 each of the
4 delivery latency times reported by Postfix (avail-
118 able in version
2.3 and later) in the form
<b>delays=
</b><i>a
</i>/
<i>b
</i>/
<i>c
</i>/
<i>d
</i>, where
119 <i>a
</i> is the amount of time before the active queue (includes time
120 for previous delivery attempts and time in the deferred queue),
121 <i>b
</i> is the amount of time in the active queue up to delivery agent
122 handoff,
<i>c
</i> is the amount of time spent making connections
123 (including DNS, HELO and TLS) and
<i>d
</i> is the amount of time spent
124 delivering the message. The total delay shown comes from the
125 <b>delay=
</b> field in a message delivery log line.
127 <b>Note:
</b> This report may consume a large amount of memory; if you
128 have no use for it, disable the delays report.
131 <b>--delays_percentiles
</b> <i>p1 [p2 ...]
</i>
132 Specifies the percentiles to be used in the message delays per-
133 centiles report. The percentiles
<i>p1
</i>,
<i>p2
</i>,
<i>...
</i> range from
0 to
134 100, inclusively. The order of the list is not sorted - the
135 report will output the percentiles columns in the order you
138 <b>--detail
</b> <i>level
</i>
139 Sets the maximum detail level for
<b>postfix-logwatch
</b> to
<i>level
</i>.
140 This option is global, overriding any other output limiters
143 The
<b>postfix-logwatch
</b> utility produces a
<b>Summary
</b> section, a
144 <b>Detailed
</b> section, and additional report sections. With
<i>level
</i>
145 less than
5,
<b>postfix-logwatch
</b> will produce only the
<b>Summary
</b> sec-
146 tion. At
<i>level
</i> 5 and above, the
<b>Detailed
</b> section, and any addi-
147 tional report sections are candidates for output. Each incre-
148 mental increase in
<i>level
</i> generates one additional hierarchical
149 sub-level of output in the
<b>Detailed
</b> section of the report. At
150 <i>level
</i> 10, all levels are output. Lines that exceed the maximum
151 report width (specified with
<b>max_report_width
</b>) will be cut.
152 Setting
<i>level
</i> to
11 will prevent lines in the report from being
153 cut (see also
<b>--line_style
</b>).
155 <b>--help
</b> Print usage information and a brief description about command
158 <b>--ignore_service
</b> <i>pattern
</i>
159 Ignore log lines that contain the postfix service name
<b>post-
</b>
160 <b>fix/
</b><i>service
</i>. The parameter
<i>service
</i> is a regular expression.
162 <b>Note:
</b> if you use parenthesis in your regular expression, be sure
163 they are cloistering and not capturing: use
<b>(?:
</b><i>pattern
</i><b>)
</b> instead
164 of
<b>(
</b><i>pattern
</i><b>)
</b>.
166 <b>--ipaddr_width
</b> <i>width
</i>
167 Specifies that IP addresses in address/hostname pairs should be
168 printed with a field width of
<i>width
</i> characters. Increasing the
169 default may be useful for systems using long IPv6 addresses.
171 <b>-l limiter=levelspec
</b>
172 <b>--limit limiter=levelspec
</b>
173 Sets the level limiter
<i>limiter
</i> with the specification
<i>levelspec
</i>.
175 <b>--line_style
</b> <i>style
</i>
176 Specifies how to handle long report lines. Three styles are
177 available:
<b>full
</b>,
<b>truncate
</b>, and
<b>wrap
</b>. Setting
<i>style
</i> to
<b>full
</b> will
178 prevent cutting lines to
<b>max_report_width
</b>; this is what occurs
179 when
<b>detail
</b> is
11 or higher. When
<i>style
</i> is
<b>truncate
</b> (the
180 default), long lines will be truncated according to
181 <b>max_report_width
</b>. Setting
<i>style
</i> to
<b>wrap
</b> will wrap lines longer
182 than
<b>max_report_width
</b> such that left column hit counts are not
183 obscured. This option takes precedence over the line style
184 implied by the
<b>detail
</b> level. The options
<b>--full
</b>,
<b>--truncate
</b>,
185 and
<b>--wrap
</b> are synonyms.
187 <b>--[no]long_queue_ids
</b>
188 Enables (disables) interpretation of long queue IDs in Postfix
192 Disables the
<b>Detailed
</b> section of the report, and all supplemen-
193 tal reports. This option provides a convenient mechanism to
194 quickly disable all sections under the
<b>Detailed
</b> report, where
195 subsequent command line options may re-enable one or more sec-
196 tions to create specific reports.
200 <b>--show_summary
</b>
201 Enables (disables) displaying of the the
<b>Summary
</b> section of the
202 report. The variable Posfix_Show_Summary in used in a configu-
205 <b>--recipient_delimiter
</b> <i>delimiter
</i>
206 Split email delivery addresses using the recipient delimiter
207 character
<i>delimiter
</i>. This should generally match the
<b>recipi-
</b>
208 <b>ent_delimiter
</b> specified in the Postfix parameter file
<b>main.cf
</b>,
209 or the default value indicated in
<b>postconf -d recipient_delim-
</b>
210 <b>iter
</b>. This is very useful for obtaining per-alias statistics
211 when a recipient delimeter is used for mail delivery.
213 <b>--reject_reply_patterns
</b> <i>r1 [r2 ...]
</i>
214 Specifies the list of reject reply patterns used to create
215 reject groups. Each entry in the list
<i>r1 [r2 ...]
</i> must be
216 either a three character regular expression reply code of the
217 form [
45][
0-
9.][
0-
9.], or the word "Warn". The "." in the regu-
218 lar expression is a literal dot which matches any reject reply
219 subcode; this wildcarding allows creation of broad rejects
220 groups. List order is preserved, in that reject reports will be
221 output in the same order as the entries in the list. Specific
222 reject reply codes will take priority over wildcard patterns,
223 regardless of the list order.
225 The default list is "
5..
4.. Warn", which creates three groups
226 of rejects: permanent rejects, temporary reject failures, and
227 reject warnings (as in warn_if_reject).
229 This feature allows, for example, distinguishing
421 transmis-
230 sion channel closures from
45x errors (eg.
450 mailbox unavail-
231 able,
451 local processing errors,
452 insufficient storage).
232 Such a grouping would be configured with the list: "
421 4..
5..
233 Warn". See RFC
2821 for more information about reply codes.
235 See also
<b>CONFIGURATION FILE
</b> regarding using
<b>reject_reply_pat-
</b>
236 <b>terns
</b> within a configuration file.
238 <b>--[no]sect_vars
</b>
239 <b>--show_sect_vars
</b> <i>boolean
</i>
240 Enables (disables) supplementing each
<b>Detailed
</b> section title
241 with the name of that section's level limiter. The name dis-
242 played is the command line option (or configuration file vari-
243 able) used to limit that section's output. With the large num-
244 ber of level limiters available in
<b>postfix-logwatch
</b>, this a con-
245 venient mechanism for determining exactly which level limiter
248 <b>--syslog_name
</b> <i>namepat
</i>
249 Specifies the syslog service name that
<b>postfix-logwatch
</b> uses to
250 match syslog lines. Only log lines whose service name matches
251 the perl regular expression
<i>namepat
</i> will be used by
<b>postfix-log-
</b>
252 <b>watch
</b>; all non-matching lines are silently ignored. This is
253 useful when a pre-installed Postfix package uses a name other
254 than the default (
<b>postfix
</b>), or when multiple Postfix instances
255 are in use and per-instance reporting is desired.
257 The pattern
<i>namepat
</i> should match the
<b>syslog_name
</b> configuration
258 parameter specified in the Postfix parameter file
<b>main.cf
</b>, the
259 master control file
<b>master.cf
</b>, or the default value as indicated
260 by the output of
<b>postconf -d syslog_name
</b>.
262 <b>Note:
</b> if you use parenthesis in your regular expression, be sure
263 they are cloistering and not capturing: use
<b>(?:
</b><i>pattern
</i><b>)
</b> instead
264 of
<b>(
</b><i>pattern
</i><b>)
</b>.
267 <b>--show_unknown
</b> <i>boolean
</i>
268 Enables (disables) display of the postfix-generated name of
269 'unknown' in formated IP/hostname pairs in
<b>Detailed
</b> reports.
273 Print
<b>postfix-logwatch
</b> version information.
275 <b>Level Limiters
</b>
276 The output of every section in the
<b>Detailed
</b> report is controlled by a
277 level limiter. The name of the level limiter variable will be output
278 when the
<b>sect_vars
</b> option is set. Level limiters are set either via
279 command line in standalone mode with
<b>--limit
</b> <i>limiter
</i><b>=
</b><i>levelspec
</i> option,
280 or via configuration file variable
<b>$postfix_
</b><i>limiter
</i><b>=
</b><i>levelspec
</i>. Each
281 limiter requires a
<i>levelspec
</i> argument, which is described below in
282 <b>LEVEL CONTROL
</b>.
284 The list of level limiters is shown below.
286 There are several level limiters that control reject sub-sections (eg.
287 <b>rejectbody
</b>,
<b>rejectsender
</b>, etc.). Because the list of reject variants
288 is not known until runtime after
<b>reject_reply_patterns
</b> is seen, these
289 reject limiters are shown below generically, with the prefix
<b>###
</b>. To
290 use one of these reject limiters, substitute
<b>###
</b> with one of the reject
291 reply codes in effect, replacing each dot with an
<b>x
</b> character. For
292 example, using the default
<b>reject_reply_patterns
</b> list of "
5..
4..
293 Warn", three
<b>rejectbody
</b> variants are valid:
<b>--limit
5xxrejectbody
</b>,
294 <b>--limit
4xxrejectbody
</b> and
<b>--limit warnrejectbody
</b>. As a convenience,
295 you may entirely eliminate the
<b>###
</b> prefix, and instead use the bare
296 <b>reject
</b><i>XXX
</i> option, and all reject level limiter variations will be auto-
297 generated based on the
<b>reject_reply_patterns
</b> list. For example, the
298 command line segment:
300 ... --reject_reply_patterns "
421 5.." \
301 --limit
rejectrbl="
1:
10:"
303 would automatically become:
305 ... --reject_reply_patterns "
421 5.." \
306 --limit
421rejectrbl="
1:
10:" --limit
5xxrejectrbl="
1:
10:"
308 See
<b>reject_reply_patterns
</b> above, and comments in the configuration file
309 <b>postfix-logwatch.conf
</b>.
312 [ THIS SECTION IS NOT YET COMPLETE ]
315 Errors obtaining attribute data from service.
316 <b>BCCed
</b> Messages that triggered access, header_checks or body_checks BCC
317 action. (postfix
2.6 experimental branch)
320 Local and remote bounces. A bounce is considered a local bounce
321 if the relay was one of none, local, virtual, avcheck, maildrop
324 Regrouping by client host IP address of all
5xx (permanent)
326 <b>CommunicationError
</b>
327 Postfix errors talking to one of its services.
328 <b>Anvil
</b> Anvil rate or concurrency limits.
329 <b>ConnectionInbound
</b>
330 Connections made to the
<b>smtpd
</b> server.
331 <b>ConnectionLostInbound
</b>
332 Connections lost to the
<b>smtpd
</b> server.
333 <b>ConnectionLostOutbound
</b>
334 Connections lost during
<b>smtp
</b> communications with remote MTA.
335 <b>ConnectToFailure
</b>
336 Failures reported by
<b>smtp
</b> when connecting to remote MTA.
337 <b>DatabaseGeneration
</b>
338 Warnings noted when binary database map file requires
<b>postmap
</b>
339 update from newer source file.
342 Message delivery deferrals. A single
<b>deferred
</b> message will have
343 one or more
<b>deferrals
</b> many times.
345 Address verification indicates recipient address is deliverable.
347 Number of messages handed-off to a delivery agent such as local
350 Messages that triggered access, header_checks or body_checks
353 Any one of several errors encounted during DNS lookups.
354 <b>EnvelopeSenderDomains
</b>
355 List of sending domains. (
2 levels: envelope sender domain,
357 <b>EnvelopeSenders
</b>
358 List of envelope senders. (
1 level: envelope sender)
359 <b>Error
</b> Postfix general
<b>error
</b> messages.
360 <b>FatalConfigError
</b>
361 Fatal main.cf or master.cf configuration errors.
363 Postfix general
<b>fatal
</b> messages.
365 Messages that triggered access, header_checks or body_checks
368 Messages forwarded by MDA for one address class to another (eg.
369 local -
> virtual).
372 <b>Hold
</b> Messages that were placed on hold by postsuper, or triggered by
373 access, header_checks or body_checks HOLD action.
374 <b>HostnameValidationError
</b>
375 Invalid hostname detected.
376 <b>HostnameVerification
</b>
377 Lookup of hostname does not map back to the IP of the peer (ie.
378 the remote system connecting to
<b>smtpd
</b>). Also known as forward-
379 confirmed reverse DNS (FCRDNS). When the reverse name has no
380 DNS entry, the message "host not found, try again" is included;
381 otherwise, it is not (e.g. when the reverse has some IP address,
382 but not the one Postfix expects).
383 <b>IllegalAddrSyntax
</b>
384 Illegal syntax in an email address provided during the MAIL FROM
387 Any LDAP errors during LDAP lookup.
389 An MX lookup for the best mailer to use to deliver mail would
390 result in a sending to ourselves.
392 Problem with an access table map that needs correcting.
393 <b>MessageWriteError
</b>
394 Postfix encountered an error when trying to create a message
395 file somewhere in the spool directory.
396 <b>NumericHostname
</b>
397 A hostname was found that was numeric, instead of alphabetic.
399 Postfix general
<b>panic
</b> messages.
401 Workarounds were enabled to avoid remote Cisco PIX SMTP "fix-
404 Summarization of policyweight/policydweight results.
406 Summarization of PolicySPF results.
408 Summarization of Postgrey results.
410 Summarization of
2.7's postscreen and verify services.
412 Summarization of
2.7's dnsblog service.
414 Messages that triggered header_checks or body_checks PREPEND
417 Postfix services that exited unexpectedly.
419 A Postfix service has reached or exceeded the maximum number of
421 <b>QueueWriteError
</b>
422 Problems writing a Postfix queue file.
424 Lookup errors for RBLs.
426 Messages that triggered access, header_checks or body_checks RE-
429 Messages that triggered body_checks REJECT action.
430 <b>###RejectClient
</b>
431 Messages rejected by client access controls
432 (smtpd_client_restrictions).
433 <b>###RejectConfigError
</b>
434 Message rejected due to server configuration errors.
435 <b>###RejectContent
</b>
436 Messages rejected by message_reject_characters.
438 Messages rejected at DATA stage in SMTP conversation
439 (smtpd_data_restrictions).
441 Messages rejected at ETRN stage in SMTP conversation
442 (smtpd_etrn_restrictions).
443 <b>###RejectHeader
</b>
444 Messages that triggered header_checks REJECT action.
446 Messages rejected at HELO/EHLO stage in SMTP conversation
447 (smtpd_helo_restrictions).
448 <b>###RejectInsufficientSpace
</b>
449 Messages rejected due to insufficient storage space.
450 <b>###RejectLookupFailure
</b>
451 Messages rejected due to temporary DNS lookup failures.
452 <b>###RejectMilter
</b>
453 Milter rejects. No reject reply code is available for these
454 rejects, but an extended
5.7.1 DSN is provided. These rejects
455 are forced into the generic
5xx rejects group. If you redefine
456 <b>reject_reply_patterns
</b> such that it does not contain the pattern
457 <b>5..
</b>, milter rejects will not be output.
459 Messages rejected by an RBL hit.
460 <b>###RejectRecip
</b>
461 Messages rejected by recipient access controls (smtpd_recipi-
463 <b>###RejectRelay
</b>
464 Messages rejected by relay access controls.
465 <b>###RejectSender
</b>
466 Messages rejected by sender access controls
467 (smtpd_sender_restrictions).
469 Messages rejected due to excessive message size.
470 <b>###RejectUnknownClient
</b>
471 Messages rejected by unknown client access controls.
472 <b>###RejectUnknownReverseClient
</b>
473 Messages rejected by unknown reverse client access controls.
474 <b>###RejectUnknownUser
</b>
475 Messages rejected by unknown user access controls.
476 <b>###RejectUnverifiedClient
</b>
477 Messages rejected by unverified client access controls.
478 <b>###RejectVerify
</b>
479 Messages rejected dueo to address verification failures.
481 Messages that triggered header_checks or body_checks REPLACE
483 <b>ReturnedToSender
</b>
484 Messages returned to sender due to exceeding queue lifetime
485 (maximal_queue_lifetime).
487 SASL authentication successes, includes SASL method, username,
488 and sender when present.
490 SASL authentication failures.
491 <b>Sent
</b> Messages sent via the SMTP delivery agent.
493 Messages sent via the LMTP delivery agent.
494 <b>SmtpConversationError
</b>
495 Errors during the SMTP/ESMTP dialog.
496 <b>SmtpProtocolViolation
</b>
497 Protocol violation during the SMTP/ESMTP dialog.
499 Errors during Postfix server startup.
500 <b>TimeoutInbound
</b>
501 Connections to
<b>smtpd
</b> that timed out.
502 <b>TlsClientConnect
</b>
503 TLS client connections.
505 TLS communication offerred.
506 <b>TlsServerConnect
</b>
507 TLS server connections.
509 Unverified TLS connections.
511 Address verification indicates recipient address is undeliver-
513 <b>Warn
</b> Messages that triggered access, header_checks or body_checks
515 <b>WarnConfigError
</b>
516 Warnings regarding Postfix configuration errors.
518 Postfix general
<b>warning
</b> messages.
522 The
<b>Detailed
</b> section of the report consists of a number of sub-sec-
523 tions, each of which is controlled both globally and independently.
524 Two settings influence the output provided in the
<b>Detailed
</b> report: a
525 global detail level (specified with
<b>--detail
</b>) which has final (big ham-
526 mer) output-limiting control over the
<b>Detailed
</b> section, and sub-section
527 specific detail settings (small hammer), which allow further limiting
528 of the output for a sub-section. Each sub-section may be limited to a
529 specific depth level, and each sub-level may be limited with top N or
530 threshold limits. The
<i>levelspec
</i> argument to each of the level limiters
531 listed above is used to accomplish this.
533 It is probably best to continue explanation of sub-level limiting with
534 the following well-known outline-style hierarchy, and some basic exam-
556 The simplest form of output limiting suppresses all output below a
557 specified level. For example, a
<i>levelspec
</i> set to "
2" shows only data
558 in levels
0 through
2. Think of this as collapsing each sub-level
2
559 item, thus hiding all inferior levels (
3,
4, ...), to yield:
568 Sometimes the volume of output in a section is too great, and it is
569 useful to suppress any data that does not exceed a certain threshold
570 value. Consider a dictionary spam attack, which produces very lengthy
571 lists of hit-once recipient email or IP addresses. Each sub-level in
572 the hierarchy can be threshold-limited by setting the
<i>levelspec
</i> appro-
573 priately. Setting
<i>levelspec
</i> to the value "
2::
5" will suppress any data
574 at level
2 that does not exceed a hit count of
5.
576 Perhaps producing a top N list, such as top
10 senders, is desired. A
577 <i>levelspec
</i> of "
3:
10:" limits level
3 data to only the top
10 hits.
579 With those simple examples out of the way, a
<i>levelspec
</i> is defined as a
580 whitespace- or comma-separated list of one or more of the following:
582 <i>l
</i> Specifies the maximum level to be output for this sub-section,
583 with a range from
0 to
10. if
<i>l
</i> is
0, no levels will be output,
584 effectively disabling the sub-section (level
0 data is already
585 provided in the Summary report, so level
1 is considered the
586 first useful level in the
<b>Detailed
</b> report). Higher values will
587 produce output up to and including the specified level.
589 <i>l
</i><b>.
</b><i>n
</i> Same as above, with the addition that
<i>n
</i> limits this section's
590 level
1 output to the top
<i>n
</i> items. The value for
<i>n
</i> can be any
591 integer greater than
1. (This form of limiting has less utility
592 than the syntax shown below. It is provided for backwards com-
593 patibility; users are encouraged to use the syntax below).
595 <i>l
</i><b>:
</b><i>n
</i><b>:
</b><i>t
</i> This triplet specifies level
<i>l
</i>, top
<i>n
</i>, and minimum threshold
<i>t
</i>.
596 Each of the values are integers, with
<i>l
</i> being the level limiter
597 as described above,
<i>n
</i> being a top
<i>n
</i> limiter for the level
<i>l
</i>, and
598 <i>t
</i> being the threshold limiter for level
<i>l
</i>. When both
<i>n
</i> and
<i>t
</i>
599 are specified,
<i>n
</i> has priority, allowing top
<i>n
</i> lists (regardless
600 of threshold value). If the value of
<i>l
</i> is omitted, the speci-
601 fied values for
<i>n
</i> and/or
<i>t
</i> are used for all levels available in
602 the sub-section. This permits a simple form of wildcarding (eg.
603 place minimum threshold limits on all levels). However, spe-
604 cific limiters always override wildcard limiters. The first
605 form of level limiter may be included in
<i>levelspec
</i> to restrict
606 output, regardless of how many triplets are present.
608 All three forms of limiters are effective only when
<b>postfix-logwatch
</b>'s
609 detail level is
5 or greater (the
<b>Detailed
</b> section is not activated
610 until detail is at least
5).
612 See the
<b>EXAMPLES
</b> section for usage scenarios.
614 <b>CONFIGURATION FILE
</b>
615 <b>Postfix-logwatch
</b> can read configuration settings from a configuration
616 file. Essentially, any command line option can be placed into a con-
617 figuration file, and these settings are read upon startup.
619 Because
<b>postfix-logwatch
</b> can run either standalone or within Logwatch,
620 to minimize confusion,
<b>postfix-logwatch
</b> inherits Logwatch's configura-
621 tion file syntax requirements and conventions. These are:
623 <b>o
</b> White space lines are ignored.
625 <b>o
</b> Lines beginning with
<b>#
</b> are ignored
627 <b>o
</b> Settings are of the form:
629 <i>option
</i> <b>=
</b> <i>value
</i>
632 <b>o
</b> Spaces or tabs on either side of the
<b>=
</b> character are ignored.
634 <b>o
</b> Any
<i>value
</i> protected in double quotes will be case-preserved.
636 <b>o
</b> All other content is reduced to lowercase (non-preserving, case
639 <b>o
</b> All
<b>postfix-logwatch
</b> configuration settings must be prefixed with
640 "
<b>$postfix_
</b>" or <b>postfix-logwatch</b> will ignore them.
642 <b>o</b> When running under Logwatch, any values not prefixed with "<b>$post-
</b>
643 <b>fix_
</b>" are consumed by Logwatch; it only passes to <b>postfix-logwatch</b>
644 (via environment variable) settings it considers valid.
646 <b>o</b> The values <b>True</b> and <b>Yes</b> are converted to 1, and <b>False</b> and <b>No</b> are
649 <b>o</b> Order of settings is not preserved within a configuration file
650 (since settings are passed by Logwatch via environment variables,
651 which have no defined order).
653 To include a command line option in a configuration file, prefix the
654 command line option name with the word "<b>$postfix_
</b>". The following con-
655 figuration file setting and command line option are equivalent:
657 <b>$postfix_Line_Style = Truncate</b>
659 <b>--line_style Truncate</b>
661 Level limiters are also prefixed with <b>$postfix_</b>, but on the command
662 line are specified with the <b>--limit</b> option:
664 <b>$postfix_Sent = 2</b>
666 <b>--limit Sent=2</b>
670 The order of command line options and configuration file processing
671 occurs as follows: 1) The default configuration file is read if it
672 exists and no <b>--config_file</b> was specified on a command line. 2) Con-
673 figuration files are read and processed in the order found on the com-
674 mand line. 3) Command line options override any options already set
675 either via command line or from any configuration file.
677 Command line options are interpreted when they are seen on the command
678 line, and later options will override previously set options. The
679 notable exception is with limiter variables, which are interpreted in
680 the order found, but only after all other options have been processed.
681 This allows <b>--reject_reply_patterns</b> to determine the dynamic list of
682 the various reject limiters.
684 See also <b>--reject_reply_patterns</b>.
687 The <b>postfix-logwatch</b> utility exits with a status code of 0, unless an
688 error occurred, in which case a non-zero exit status is returned.
691 <b>Running Standalone</b>
692 <b>Note: postfix-logwatch</b> reads its log data from one or more named Post-
693 fix log files, or from STDIN. For brevity, where required, the exam-
694 ples below use the word <i>file</i> as the command line argument meaning
695 <i>/path/to/postfix.log</i>. Obviously you will need to substitute <i>file</i> with
696 the appropriate path.
698 To run <b>postfix-logwatch</b> in standalone mode, simply run:
700 <b>postfix-logwatch</b> <i>file</i>
702 A complete list of options and basic usage is available via:
704 <b>postfix-logwatch --help</b>
706 To print a summary only report of Postfix log data:
708 <b>postfix-logwatch --detail 1</b> <i>file</i>
710 To produce a summary report and a one-level detail report for May 25th:
712 <b>grep 'May 25'</b> <i>file</i> <b>| postfix-logwatch --detail 5</b>
714 To produce only a top 10 list of Sent email domains, the summary report
715 and detailed reports are first disabled. Since commands line options
716 are read and enabled left-to-right, the Sent section is re-enabled to
717 level 1 with a level 1 top 10 limiter:
719 <b>postfix-logwatch --nosummary --nodetail --limit sent='1 1:10:'</b> <i>file</i>
721 The following command and its sample output shows a more complex level
722 limiter example. The command gives the top 3 Sent email addresses from
723 the top 5 domains, in addition, all level 3 items with a hit count of 2
724 or less are suppressed (in the Sent sub-section, this happens to be
725 email's Original To address). Ellipses indicate top N or threshold-
728 <b>postfix-logwatch --nosummary --nodetail \</b>
729 <b>--limit sent '1:5: 2:3: 3::2'</b> <i>file</i>
731 1762 Sent via SMTP -----------------------------------
734 255 joe.bob@virtdomain.example.com
735 7 info@virtdomain.example.com
759 The next command uses both <b>reject_reply_patterns</b> and level limiters to
760 see 421 RBL rejects, threshold-limiting level 2 output to hits greater
761 than 5 (level 2 in the Reject RBL sub-section is the client's IP
762 address / hostname pair). This makes for a very nice RBL offenders
763 list, shown in the sample output (note the use of the unambiguous,
764 abbreviated command line option reject_reply_pat):
766 <b>postfix-logwatch --reject_reply_pat '421 4.. 5.. Warn' \</b>
767 <b>--nosummary --nodetail --limit 421rejectrbl='2 2::5'</b> <i>file</i>
769 300 421 Reject RBL ---------------------------------------
770 243 zen.spamhaus.org=127.0.0.2
771 106 10.0.0.129 129.0.0.example.com
772 41 192.168.10.70 hostx10.sample.net
773 40 192.168.42.39 hostz42.sample.net
774 15 10.1.1.152 dsl-10-1-1-152.example.us
775 14 10.10.10.122 mail122.sample.com
776 7 192.168.3.44 smalltime-spammer.example.com
778 48 zen.spamhaus.org=127.0.0.4
779 17 10.29.124.92 10-29-124-92.adsl-static.sample.us
781 8 zen.spamhaus.org=127.0.0.11
783 1 zen.spamhaus.org=127.0.0.10
786 <b>Running within Logwatch</b>
787 <b>Note:</b> Logwatch versions prior to 7.3.6, unless configured otherwise,
788 required the <b>--print</b> option to print to STDOUT instead of sending
789 reports via email. Since version 7.3.6, STDOUT is the default output
790 destination, and the <b>--print</b> option has been replaced by <b>--output std-</b>
791 <b>out</b>. Check your configuration to determine where report output will be
792 directed, and add the appropriate option to the commands below.
794 To print a summary report for today's Postfix log data:
796 <b>logwatch --service postfix --range today --detail 1</b>
798 To print a report for today's Postfix log data, with one level
799 of detail in the <b>Detailed</b> section:
801 <b>logwatch --service postfix --range today --detail 5</b>
803 To print a report for yesterday, with two levels of detail in the
804 <b>Detailed</b> section:
806 <b>logwatch --service postfix --range yesterday --detail 6</b>
808 To print a report from Dec 12th through Dec 14th, with four levels of
809 detail in the <b>Detailed</b> section:
811 <b>logwatch --service postfix --range \</b>
812 <b>'between 12/12 and 12/14' --detail 8</b>
814 To print a report for today, with all levels of detail:
816 <b>logwatch --service postfix --range today --detail 10</b>
818 Same as above, but leaves long lines uncut:
820 <b>logwatch --service postfix --range today --detail 11</b>
824 The <b>postfix-logwatch</b> program uses the following (automatically set)
825 environment variables when running under Logwatch:
827 <b>LOGWATCH_DETAIL_LEVEL</b>
828 This is the detail level specified with the Logwatch command
829 line argument <b>--detail</b> or the <b>Detail</b> setting in the ...conf/ser-
830 vices/postfix.conf configuration file.
832 <b>LOGWATCH_DEBUG</b>
833 This is the debug level specified with the Logwatch command line
834 argument <b>--debug</b>.
836 <b>postfix_</b><i>xxx</i>
837 The Logwatch program passes all settings <b>postfix_</b><i>xxx</i> in the con-
838 figuration file ...conf/services/postfix.conf to the <b>postfix</b>
839 filter (which is actually named .../scripts/services/postfix)
840 via environment variable.
843 <b>Standalone mode</b>
844 /usr/local/bin/postfix-logwatch
845 The <b>postfix-logwatch</b> program
847 /usr/local/etc/postfix-logwatch.conf
848 The <b>postfix-logwatch</b> configuration file in standalone mode
851 /etc/logwatch/scripts/services/postfix
852 The Logwatch <b>postfix</b> filter
854 /etc/logwatch/conf/services/postfix.conf
855 The Logwatch <b>postfix</b> filter configuration file
858 logwatch(8), system log analyzer and reporter
861 README, an overview of <b>postfix-logwatch</b>
862 Changes, the version change list history
863 Bugs, a list of the current bugs or other inadequacies
864 Makefile, the rudimentary installer
865 LICENSE, the usage and redistribution licensing terms
868 Covered under the included MIT/X-Consortium License:
869 http://www.opensource.org/licenses/mit-license.php
874 The original <b>postfix</b> Logwatch filter was written by Kenneth Porter, and
875 has had many contributors over the years. They are entirely not
876 responsible for any errors, problems or failures since the current
877 author's hands have touched the source code.
882 </pre> </body> </html>
projects / postfix-logwatch.git / blob