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: amavis-logwatch(
1)
</title>
7 AMAVIS-LOGWATCH(
1) General Commands Manual AMAVIS-LOGWATCH(
1)
12 amavis-logwatch - An Amavisd-new log parser and analysis utility
15 <b>amavis-logwatch
</b> [
<i>options
</i>] [
<i>logfile ...
</i>]
18 The
<b>amavis-logwatch
</b>(
1) utility is an Amavisd-new log parser that pro-
19 duces summaries, details, and statistics regarding the operation of
20 Amavisd-new (henceforth, simply called Amavis).
22 This utility can be used as a standalone program, or as a Logwatch fil-
23 ter module to produce Amavisd-new summary and detailed reports from
26 <b>Amavis-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 Amavis 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 Much of the interesting data is available when Amavis' $log_level is
35 set to at least
2. See
<b>Amavis Log Level
</b> below.
37 <b>Amavis-logwatch
</b> outputs two principal sections: a
<b>Summary
</b> section and a
38 <b>Detailed
</b> section. For readability and quick scanning, all event or hit
39 counts appear in the left column, followed by brief description of the
40 event type, and finally additional statistics or count representations
41 may appear in the rightmost column.
43 The following segment from a sample Summary report illustrates:
45 ****** Summary ********************************************
47 9 Miscellaneous warnings
49 20313 Total messages scanned ----------------
100.00%
50 1008.534M Total bytes scanned
1,
057,
524,
252
51 ======== ================================================
53 1190 Blocked -------------------------------
5.86%
54 18 Malware blocked
0.09%
55 4 Banned name blocked
0.02%
56 416 Spam blocked
2.05%
57 752 Spam discarded (no quarantine)
3.70%
59 19123 Passed --------------------------------
94.14%
60 47 Bad header passed
0.23%
61 19076 Clean passed
93.91%
62 ======== ================================================
64 18 Malware -------------------------------
0.09%
65 18 Malware blocked
0.09%
67 4 Banned --------------------------------
0.02%
68 4 Banned file blocked
0.02%
70 1168 Spam ----------------------------------
5.75%
71 416 Spam blocked
2.05%
72 752 Spam discarded (no quarantine)
3.70%
74 19123 Ham -----------------------------------
94.14%
75 47 Bad header passed
0.23%
76 19076 Clean passed
93.91%
77 ======== ================================================
79 1982 SpamAssassin bypassed
80 32 Released from quarantine
81 2 DSN notification (debug supplemental)
86 58 Bad header (debug supplemental)
87 40 Extra code modules loaded at runtime
89 The report indicates there were
9 general warnings, and
<b>Amavis
</b> scanned
90 a total of
20313 messages for a total of
1008.53 megabytes or
91 1,
057,
524,
252 bytes. The next summary groups shows the Blocked /
92 Passed overview, with
1190 Blocked messages (broken down as
18 messages
93 blocked as malware,
4 messages with banned names,
416 spam messages,
94 and
752 discarded messages), and
19123 Passed messages (
47 messages
95 with bad headers and
19076 clean messages).
97 The next (optional) summary grouping shows message disposition by con-
98 tents category. There were
18 malware messages and
4 banned file mes-
99 sages (all blocked),
1168 Spam messages, of which
416 were blocked
100 (quarantined) and
752 discarded. Finally, there were
19123 messages
101 consdidered to be Ham (i.e. not spam),
47 of which contained bad head-
104 Additional count summaries for a variety of events are also listed.
106 There are dozens of sub-sections available in the
<b>Detailed
</b> report, each
107 of whose output can be controlled in various ways. Each sub-section
108 attempts to group and present the most meaningful data at superior lev-
109 els, while pushing less useful or
<i>noisy
</i> data towards inferior levels.
110 The goal is to provide as much benefit as possible from smart grouping
111 of data, to allow faster report scanning, pattern identification, and
112 problem solving. Data is always sorted in descending order by count,
113 and then numerically by IP address or alphabetically as appropriate.
115 The following Spam blocked segment from a sample
<b>Detailed
</b> report illus-
116 trates the basic hierarchical level structure of
<b>amavis-logwatch
</b>:
118 ****** Detailed *******************************************
120 19346 Spam blocked -----------------------------------
130 The
<b>amavis-logwatch
</b> utility reads from STDIN or from the named Amavis
131 <i>logfile
</i>. Multiple
<i>logfile
</i> arguments may be specified, each processed
132 in order. The user running
<b>amavis-logwatch
</b> must have read permission
133 on each named log file.
136 The options listed below affect the operation of
<b>amavis-logwatch
</b>.
137 Options specified later on the command line override earlier ones. Any
138 option may be abbreviated to an unambiguous length.
141 <b>--[no]autolearn
</b>
142 <b>--show_autolearn
</b> <i>boolean
</i>
143 Enables (disables) output of the autolearn report. This report
144 is only available if the default Amavis
<b>$log_templ
</b> has been mod-
145 ified to provide autolearn results in log entries. This can be
146 done by uncommenting two lines in the Amavis program itself
147 (where the default log templates reside), or by correctly adding
148 the
<b>$log_templ
</b> variable to the
<b>amavisd.conf
</b> file. See Amavis'
149 <b>README.customize
</b> and search near the end of the Amavisd program
152 <b>--[no]by_ccat_summary
</b>
153 <b>--show_by_ccat_summary
</b> <i>boolean
</i>
154 Enables (disables) the by contents category summary in the
<b>Sum-
</b>
155 <b>mary
</b> section. Default: enabled.
157 <b>-f
</b> <i>config
</i><b>_
</b><i>file
</i>
158 <b>--config_file
</b> <i>config
</i><b>_
</b><i>file
</i>
159 Use an alternate configuration file
<i>config
</i><b>_
</b><i>file
</i> instead of the
160 default. This option may be used more than once. Multiple con-
161 figuration files will be processed in the order presented on the
162 command line. See
<b>CONFIGURATION FILE
</b> below.
164 <b>--debug
</b> <i>keywords
</i>
165 Output debug information during the operation of
<b>amavis-log-
</b>
166 <b>watch
</b>. The parameter
<i>keywords
</i> is one or more comma or space
167 separated keywords. To obtain the list of valid keywords, use
168 --debug xxx where xxx is any invalid keyword.
170 <b>--detail
</b> <i>level
</i>
171 Sets the maximum detail level for
<b>amavis-logwatch
</b> to
<i>level
</i>.
172 This option is global, overriding any other output limiters
175 The
<b>amavis-logwatch
</b> utility produces a
<b>Summary
</b> section, a
176 <b>Detailed
</b> section, and additional report sections. With
<i>level
</i>
177 less than
5,
<b>amavis-logwatch
</b> will produce only the
<b>Summary
</b> sec-
178 tion. At
<i>level
</i> 5 and above, the
<b>Detailed
</b> section, and any addi-
179 tional report sections are candidates for output. Each incre-
180 mental increase in
<i>level
</i> generates one additional hierarchical
181 sub-level of output in the
<b>Detailed
</b> section of the report. At
182 <i>level
</i> 10, all levels are output. Lines that exceed the maximum
183 report width (specified with
<b>max_report_width
</b>) will be cut.
184 Setting
<i>level
</i> to
11 will prevent lines in the report from being
185 cut (see also
<b>--line_style
</b>).
187 <b>--[no]first_recip_only
</b>
188 <b>--show_first_recip_only
</b> <i>boolean
</i>
189 Specifies whether or not to sort by, and show, only the first
190 recipient when a scanned messages contains multiple recipients.
192 <b>--help
</b> Print usage information and a brief description about command
195 <b>--ipaddr_width
</b> <i>width
</i>
196 Specifies that IP addresses in address/hostname pairs should be
197 printed with a field width of
<i>width
</i> characters. Increasing the
198 default may be useful for systems using long IPv6 addresses.
200 <b>-l limiter=levelspec
</b>
201 <b>--limit limiter=levelspec
</b>
202 Sets the level limiter
<i>limiter
</i> with the specification
<i>levelspec
</i>.
204 <b>--line_style
</b> <i>style
</i>
205 Specifies how to handle long report lines. Three styles are
206 available:
<b>full
</b>,
<b>truncate
</b>, and
<b>wrap
</b>. Setting
<i>style
</i> to
<b>full
</b> will
207 prevent cutting lines to
<b>max_report_width
</b>; this is what occurs
208 when
<b>detail
</b> is
11 or higher. When
<i>style
</i> is
<b>truncate
</b> (the
209 default), long lines will be truncated according to
210 <b>max_report_width
</b>. Setting
<i>style
</i> to
<b>wrap
</b> will wrap lines longer
211 than
<b>max_report_width
</b> such that left column hit counts are not
212 obscured. This option takes precedence over the line style
213 implied by the
<b>detail
</b> level. The options
<b>--full
</b>,
<b>--truncate
</b>,
214 and
<b>--wrap
</b> are synonyms.
218 Disables the
<b>Detailed
</b> section of the report, and all supplemen-
219 tal reports. This option provides a convenient mechanism to
220 quickly disable all sections under the
<b>Detailed
</b> report, where
221 subsequent command line options may re-enable one or more sec-
222 tions to create specific reports.
224 <b>--sarules
</b> `
<i>S,H
</i>'
225 <b>--sarules default
</b>
226 Enables the SpamAssassin Rules Hit report. The comma-separated
227 <i>S
</i> and
<i>H
</i> arguments are top N values for the Spam and Ham reports,
228 respectively, and can be any integer greater than or equal to
0,
229 or the keyword
<b>all
</b>. The keyword
<b>default
</b> uses the built-in
233 Disables the SpamAssassin Rules Hit report.
235 <b>--sa_timings
</b> <i>nrows
</i>
236 Enables the SpamAssassin Timings percentiles report. The report
237 can be limited to the top N rows with the
<i>nrows
</i> argument. This
238 report requires Amavis
2.6+ and SpamAssassin
3.3+.
240 <b>--sa_timings_percentiles
</b> `
<i>P1 [P2 ...]
</i>'
241 Specifies the percentiles shown in the SpamAssassin Timings
242 report. The arguments
<i>P1 ...
</i> are integers from
0 to
100 inclu-
243 sive. Their order will be preserved in the report.
245 <b>--nosa_timings
</b>
246 Disables the SpamAssassin Timings report.
249 Print
<b>amavis-logwatch
</b> version information.
251 <b>--score_frequencies
</b> `
<i>B1 [B2 ...]
</i>'
252 <b>--score_frequencies default
</b>
253 Enables the Spam Score Frequency report. The arguments
<i>B1 ...
</i>
254 are frequency distribution buckets, and can be any real numbers.
255 Their order will be preserved in the report. The keyword
256 <b>default
</b> uses the built-in default values.
258 <b>--noscore_frequencies
</b>
259 Disables the Spam Score Frequency report.
261 <b>--score_percentiles
</b> `
<i>P1 [P2 ...]
</i>'
262 <b>--score_percentiles default
</b>
263 Enables the Spam Score Percentiles report. The arguments
<i>P1 ...
</i>
264 specify the percentiles shown in the report, and are integers
265 from
0 to
100 inclusive. The keyword
<b>default
</b> uses the built-in
268 <b>--noscore_percentiles
</b>
269 Disables the Spam Score Percentiles report.
272 <b>--[no]sect_vars
</b>
273 <b>--show_sect_vars
</b> <i>boolean
</i>
274 Enables (disables) supplementing each
<b>Detailed
</b> section title
275 with the name of that section's level limiter. The name dis-
276 played is the command line option (or configuration file vari-
277 able) used to limit that section's output. With the large num-
278 ber of level limiters available in
<b>amavis-logwatch
</b>, this a con-
279 venient mechanism for determining exactly which level limiter
282 <b>--[no]startinfo
</b>
283 <b>--show_startinfo
</b> <i>boolean
</i>
284 Enables (disables) the Amavis startup report showing most recent
285 Amavis startup details.
289 <b>--show_summary
</b>
290 Enables (disables) displaying of the the
<b>Summary
</b> section of the
291 report. The variable Amavis_Show_Summary in used in a configu-
294 <b>--syslog_name
</b> <i>namepat
</i>
295 Specifies the syslog service name that
<b>amavis-logwatch
</b> uses to
296 match syslog lines. Only log lines whose service name matches
297 the perl regular expression
<i>namepat
</i> will be used by
<b>amavis-log-
</b>
298 <b>watch
</b>; all non-matching lines are silently ignored. This is
299 useful when a pre-installed Amavis package uses a name other
300 than the default (
<b>amavis
</b>).
302 <b>Note:
</b> if you use parenthesis in your regular expression, be sure
303 they are cloistering and not capturing: use
<b>(?:
</b><i>pattern
</i><b>)
</b> instead
304 of
<b>(
</b><i>pattern
</i><b>)
</b>.
306 <b>--timings
</b> <i>percent
</i>
307 Enables the Amavis Scan Timings percentiles report. The report
308 can be top N-percent limited with the
<i>percent
</i> argument.
310 <b>--timings_percentiles
</b> `
<i>P1 [P2 ...]
</i>'
311 Specifies the percentiles shown in the Scan Timings report. The
312 arguments
<i>P1 ...
</i> are integers from
0 to
100 inclusive. Their
313 order will be preserved in the report.
316 Disables the Amavis Scan Timings report.
319 Print
<b>amavis-logwatch
</b> version information.
322 <b>Level Limiters
</b>
323 The output of every section in the
<b>Detailed
</b> report is controlled by a
324 level limiter. The name of the level limiter variable will be output
325 when the
<b>sect_vars
</b> option is set. Level limiters are set either via
326 command line in standalone mode with
<b>--limit
</b> <i>limiter
</i><b>=
</b><i>levelspec
</i> option,
327 or via configuration file variable
<b>$amavis_
</b><i>limiter
</i><b>=
</b><i>levelspec
</i>. Each
328 limiter requires a
<i>levelspec
</i> argument, which is described below in
329 <b>LEVEL CONTROL
</b>.
331 The list of level limiters is shown below.
334 Amavis major contents category (ccatmajor) sections, listed in order of
335 priority: VIRUS, BANNED, UNCHECKED, SPAM, SPAMMY, BADH, OVERSIZED, MTA,
338 <b>MalwareBlocked
</b>
340 Blocked or passed messages that contain malware (ccatmajor:
343 <b>BannedNameBlocked
</b>
344 <b>BannedNamePassed
</b>
345 Blocked or passed messages that contain banned names in MIME
346 parts (ccatmajor: BANNED).
348 <b>UncheckedBlocked
</b>
349 <b>UncheckedPassed
</b>
350 Blocked or passed messages that were not checked by a virus
351 scanner or SpamAssassin (Amavis ccatmajor: UNCHECKED).
355 Blocked or passed messages that were considered spam that
356 reached kill level (Amavis ccatmajor: SPAM)
360 Blocked or passed messages that were considered spam, but did
361 not reach kill level (Amavis ccatmajor: SPAMMY)
363 <b>BadHeaderBlocked
</b>
364 <b>BadHeaderPassed
</b>
365 Blocked or passed messages that contain bad mail headers (ccat-
368 <b>OversizedBlocked
</b>
369 <b>OversizedPassed
</b>
370 Blocked or passed messages that were considered oversized
371 (Amavis ccatmajor: OVERSIZED).
375 Blocked or passed messages due to failure to re-inject to MTA
376 (Amavis ccatmajor: MTA-BLOCKED). Occurrences of this event
377 indicates a configuration problem. [ note: I don't believe mta-
378 passed occurs, but exists for completeness.]
382 Blocked or passed messages that are not any of other major con-
383 tents categories (Amavis ccatmajor: OTHER).
386 <b>TempFailBlocked
</b>
387 <b>TempfailPassed
</b>
388 Blocked or passed messages that had a temporary failure (Amavis
393 Messages blocked or passed which were considered clean (Amavis
394 ccatmajor: CLEAN; i.e. non-spam, non-viral).
396 Other sections, arranged alphabetically:
398 <b>AvConnectFailure
</b>
399 Problems connecting to Anti-Virus scanner(s).
402 Timeouts awaiting responses from Anti-Virus scanner(s).
404 <b>ArchiveExtract
</b>
405 Archive extraction problems.
408 Supplemental debug information regarding messages containing bad
411 <b>Bayes
</b> Messages frequencies by Bayesian probability buckets.
414 Invalid mail address syntax.
417 Messages that were (soft-)blacklisted. See also Whitelisted
422 <b>BounceUnverifiable
</b>
423 Disposition of incoming bounce messages (DSNs).
426 MIME attachment breakdown by type/subtype.
429 Errors encountered with or returned by DCC.
432 Errors encountered during defang process.
435 Messages defanged (rendered harmless).
437 <b>DsnNotification
</b>
438 Errors encountered during attempt to send delivery status noti-
442 Delivery status notification (DSN) intentionally suppressed.
445 Additional code modules Amavis loaded during runtime.
448 Forged sender addresses, as determimed by Amavis.
450 <b>Fatal
</b> Fatal events. These are presented at the top of the report, as
451 they may require attention.
453 <b>LocalDeliverySkipped
</b>
454 Failures delivering to a local address.
456 <b>MalwareByScanner
</b>
457 Breakdown of malware by scanner(s) that detected the malware.
460 Errors encountered during MIME extraction.
462 <b>Panic
</b> Panic events. These are presented at the top of the report, as
463 they may require attention.
465 <b>p0f
</b> Passive fingerprint (p0f) hits, grouped by mail contents type
466 (virus, unchecked, banned, spam, ham), next by operating system
467 genre, and finally by IP address. Note: Windows systems are
468 refined by Windows OS version, whereas versions of other operat-
469 ing systems are grouped generically.
472 Messages that were released from Amavis quarantine.
475 Diagnostics as reported from SpamAssassin.
478 SMTP responses received during dialog with MTA. These log
479 entries are primarly debug.
482 Temporary directories preserved by Amavis when some component
483 encounters a problem or failure. Directories listed and their
484 corresponding log entries should be evaluated for problems.
486 <b>VirusScanSkipped
</b>
487 Messages that could not be scanned by a virus scanner.
490 Warning events not categorized in specific warnings below.
491 These are presented at the top of the report, as they may
494 <b>WarningAddressModified
</b>
495 Incomplete email addresses modified by Amavis for safety.
497 <b>WarningNoQuarantineId
</b>
498 Attempts to release a quarantined message that did not contain
499 an X-Quarantine-ID header.
501 <b>WarningSecurity
</b> <i>levelspec
</i>
502 Insecure configuration or utility used by Amavis.
504 <b>WarningSmtpShutdown
</b>
505 Failures during SMTP conversation with MTA.
508 Failures to communicate with, or error replies from, SQL ser-
512 Messages that were (soft-)whitelisted. See also Blacklisted
517 The
<b>Detailed
</b> section of the report consists of a number of sub-sec-
518 tions, each of which is controlled both globally and independently.
519 Two settings influence the output provided in the
<b>Detailed
</b> report: a
520 global detail level (specified with
<b>--detail
</b>) which has final (big ham-
521 mer) output-limiting control over the
<b>Detailed
</b> section, and sub-section
522 specific detail settings (small hammer), which allow further limiting
523 of the output for a sub-section. Each sub-section may be limited to a
524 specific depth level, and each sub-level may be limited with top N or
525 threshold limits. The
<i>levelspec
</i> argument to each of the level limiters
526 listed above is used to accomplish this.
528 It is probably best to continue explanation of sub-level limiting with
529 the following well-known outline-style hierarchy, and some basic exam-
551 The simplest form of output limiting suppresses all output below a
552 specified level. For example, a
<i>levelspec
</i> set to "
2" shows only data
553 in levels
0 through
2. Think of this as collapsing each sub-level
2
554 item, thus hiding all inferior levels (
3,
4, ...), to yield:
563 Sometimes the volume of output in a section is too great, and it is
564 useful to suppress any data that does not exceed a certain threshold
565 value. Consider a dictionary spam attack, which produces very lengthy
566 lists of hit-once recipient email or IP addresses. Each sub-level in
567 the hierarchy can be threshold-limited by setting the
<i>levelspec
</i> appro-
568 priately. Setting
<i>levelspec
</i> to the value "
2::
5" will suppress any data
569 at level
2 that does not exceed a hit count of
5.
571 Perhaps producing a top N list, such as top
10 senders, is desired. A
572 <i>levelspec
</i> of "
3:
10:" limits level
3 data to only the top
10 hits.
574 With those simple examples out of the way, a
<i>levelspec
</i> is defined as a
575 whitespace- or comma-separated list of one or more of the following:
577 <i>l
</i> Specifies the maximum level to be output for this sub-section,
578 with a range from
0 to
10. if
<i>l
</i> is
0, no levels will be output,
579 effectively disabling the sub-section (level
0 data is already
580 provided in the Summary report, so level
1 is considered the
581 first useful level in the
<b>Detailed
</b> report). Higher values will
582 produce output up to and including the specified level.
584 <i>l
</i><b>.
</b><i>n
</i> Same as above, with the addition that
<i>n
</i> limits this section's
585 level
1 output to the top
<i>n
</i> items. The value for
<i>n
</i> can be any
586 integer greater than
1. (This form of limiting has less utility
587 than the syntax shown below. It is provided for backwards com-
588 patibility; users are encouraged to use the syntax below).
590 <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>.
591 Each of the values are integers, with
<i>l
</i> being the level limiter
592 as described above,
<i>n
</i> being a top
<i>n
</i> limiter for the level
<i>l
</i>, and
593 <i>t
</i> being the threshold limiter for level
<i>l
</i>. When both
<i>n
</i> and
<i>t
</i>
594 are specified,
<i>n
</i> has priority, allowing top
<i>n
</i> lists (regardless
595 of threshold value). If the value of
<i>l
</i> is omitted, the speci-
596 fied values for
<i>n
</i> and/or
<i>t
</i> are used for all levels available in
597 the sub-section. This permits a simple form of wildcarding (eg.
598 place minimum threshold limits on all levels). However, spe-
599 cific limiters always override wildcard limiters. The first
600 form of level limiter may be included in
<i>levelspec
</i> to restrict
601 output, regardless of how many triplets are present.
603 All three forms of limiters are effective only when
<b>amavis-logwatch
</b>'s
604 detail level is
5 or greater (the
<b>Detailed
</b> section is not activated
605 until detail is at least
5).
607 See the
<b>EXAMPLES
</b> section for usage scenarios.
609 <b>CONFIGURATION FILE
</b>
610 <b>Amavis-logwatch
</b> can read configuration settings from a configuration
611 file. Essentially, any command line option can be placed into a con-
612 figuration file, and these settings are read upon startup.
614 Because
<b>amavis-logwatch
</b> can run either standalone or within Logwatch,
615 to minimize confusion,
<b>amavis-logwatch
</b> inherits Logwatch's configura-
616 tion file syntax requirements and conventions. These are:
618 <b>o
</b> White space lines are ignored.
620 <b>o
</b> Lines beginning with
<b>#
</b> are ignored
622 <b>o
</b> Settings are of the form:
624 <i>option
</i> <b>=
</b> <i>value
</i>
627 <b>o
</b> Spaces or tabs on either side of the
<b>=
</b> character are ignored.
629 <b>o
</b> Any
<i>value
</i> protected in double quotes will be case-preserved.
631 <b>o
</b> All other content is reduced to lowercase (non-preserving, case
634 <b>o
</b> All
<b>amavis-logwatch
</b> configuration settings must be prefixed with
635 "
<b>$amavis_
</b>" or <b>amavis-logwatch</b> will ignore them.
637 <b>o</b> When running under Logwatch, any values not prefixed with
638 "<b>$amavis_
</b>" are consumed by Logwatch; it only passes to <b>amavis-log-</b>
639 <b>watch</b> (via environment variable) settings it considers valid.
641 <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
644 <b>o</b> Order of settings is not preserved within a configuration file
645 (since settings are passed by Logwatch via environment variables,
646 which have no defined order).
648 To include a command line option in a configuration file, prefix the
649 command line option name with the word "<b>$amavis_
</b>". The following con-
650 figuration file setting and command line option are equivalent:
652 <b>$amavis_Line_Style = Truncate</b>
654 <b>--line_style Truncate</b>
656 Level limiters are also prefixed with <b>$amavis_</b>, but on the command line
657 are specified with the <b>--limit</b> option:
659 <b>$amavis_SpamBlocked = 2</b>
661 <b>--limit SpamBlocked=2</b>
665 The order of command line options and configuration file processing
666 occurs as follows: 1) The default configuration file is read if it
667 exists and no <b>--config_file</b> was specified on a command line. 2) Con-
668 figuration files are read and processed in the order found on the com-
669 mand line. 3) Command line options override any options already set
670 either via command line or from any configuration file.
672 Command line options are interpreted when they are seen on the command
673 line, and later options will override previously set options.
678 The <b>amavis-logwatch</b> utility exits with a status code of 0, unless an
679 error occurred, in which case a non-zero exit status is returned.
682 <b>Running Standalone</b>
683 <b>Note: amavis-logwatch</b> reads its log data from one or more named Amavis
684 log files, or from STDIN. For brevity, where required, the examples
685 below use the word <i>file</i> as the command line argument meaning
686 <i>/path/to/amavis.log</i>. Obviously you will need to substitute <i>file</i> with
687 the appropriate path.
689 To run <b>amavis-logwatch</b> in standalone mode, simply run:
691 <b>amavis-logwatch</b> <i>file</i>
693 A complete list of options and basic usage is available via:
695 <b>amavis-logwatch --help</b>
697 To print a summary only report of Amavis log data:
699 <b>amavis-logwatch --detail 1</b> <i>file</i>
701 To produce a summary report and a one-level detail report for May 25th:
703 <b>grep 'May 25'</b> <i>file</i> <b>| amavis-logwatch --detail 5</b>
705 To produce only a top 10 list of Sent email domains, the summary report
706 and detailed reports are first disabled. Since commands line options
707 are read and enabled left-to-right, the Sent section is re-enabled to
708 level 1 with a level 1 top 10 limiter:
710 <b>amavis-logwatch --nosummary --nodetail \</b>
711 <b>--limit spamblocked '1 1:10:'</b> <i>file</i>
713 The following command and its sample output shows a more complex level
714 limiter example. The command gives the top 4 spam blocked recipients
715 (level 1), and under with each recipient the top 2 sending IPs (level
716 2) and finally below that, only envelope from addresses (level 3) with
717 hit counts greater than 6. Ellipses indicate top N or threshold-lim-
720 <b>amavis-logwatch --nosummary --nodetail \</b>
721 <b>--limit spamblocked '1:4: 2:2: 3::6'</b> <i>file</i>
723 19346 Spam blocked -----------------------------------
750 <b>Running within Logwatch</b>
751 <b>Note:</b> Logwatch versions prior to 7.3.6, unless configured otherwise,
752 required the <b>--print</b> option to print to STDOUT instead of sending
753 reports via email. Since version 7.3.6, STDOUT is the default output
754 destination, and the <b>--print</b> option has been replaced by <b>--output std-</b>
755 <b>out</b>. Check your configuration to determine where report output will be
756 directed, and add the appropriate option to the commands below.
758 To print a summary report for today's Amavis log data:
760 <b>logwatch --service amavis --range today --detail 1</b>
762 To print a report for today's Amavis log data, with one level
763 of detail in the <b>Detailed</b> section:
765 <b>logwatch --service amavis --range today --detail 5</b>
767 To print a report for yesterday, with two levels of detail in the
768 <b>Detailed</b> section:
770 <b>logwatch --service amavis --range yesterday --detail 6</b>
772 To print a report from Dec 12th through Dec 14th, with four levels of
773 detail in the <b>Detailed</b> section:
775 <b>logwatch --service amavis --range \</b>
776 <b>'between 12/12 and 12/14' --detail 8</b>
778 To print a report for today, with all levels of detail:
780 <b>logwatch --service amavis --range today --detail 10</b>
782 Same as above, but leaves long lines uncropped:
784 <b>logwatch --service amavis --range today --detail 11</b>
786 <b>Amavis Log Level</b>
787 Amavis provides additional log information when the variable <b>$log_level</b>
788 is increased above the default 0 value. This information is used by
789 the <b>amavis-logwatch</b> utility to provide additional reports, not avail-
790 able with the default <b>$log_level</b>=0 value. A <b>$log_level</b> of 2 is sug-
793 If you prefer not to increase the noise level in your main mail or
794 Amavis logs, you can configure syslog to log Amavis' output to multiple
795 log files, where basic log entries are routed to your main mail log(s)
796 and more detailed entries routed to an Amavis-specific log file used to
797 feed the <b>amavis-logwatch</b> utility.
799 A convenient way to accomplish this is to change the Amavis configura-
800 tion variables in <b>amavisd.conf</b> as shown below:
804 $syslog_facility = 'local5';
805 $syslog_priority = 'debug';
808 This increases <b>$log_level</b> to 2, and sends Amavis' log entries to an
809 alternate syslog facility (eg. <b>local5</b>, user), which can then be routed
810 to one or more log files, including your main mail log file:
813 #mail.info -/var/log/maillog
814 mail.info;local5.notice -/var/log/maillog
816 local5.info -/var/log/amavisd-info.log
819 <b>Amavis</b>' typical <b>$log_level</b> 0 messages will be directed to both your
820 maillog and to the <b>amavisd-info.log</b> file, but higher <b>$log_level</b> mes-
821 sages will only be routed to the <b>amavisd-info.log</b> file. For additional
822 information on Amavis' logging, search the file <b>RELEASE_NOTES</b> in the
823 Amavis distribution for:
825 "syslog priorities are now dynamically derived"
829 The
<b>amavis-logwatch
</b> program uses the following (automatically set)
830 environment variables when running under Logwatch:
832 <b>LOGWATCH_DETAIL_LEVEL
</b>
833 This is the detail level specified with the Logwatch command
834 line argument
<b>--detail
</b> or the
<b>Detail
</b> setting in the ...conf/ser-
835 vices/amavis.conf configuration file.
837 <b>LOGWATCH_DEBUG
</b>
838 This is the debug level specified with the Logwatch command line
839 argument
<b>--debug
</b>.
841 <b>amavis_
</b><i>xxx
</i>
842 The Logwatch program passes all settings
<b>amavis_
</b><i>xxx
</i> in the con-
843 figuration file ...conf/services/amavis.conf to the
<b>amavis
</b> fil-
844 ter (which is actually named .../scripts/services/amavis) via
845 environment variable.
848 <b>Standalone mode
</b>
849 /usr/local/bin/amavis-logwatch
850 The
<b>amavis-logwatch
</b> program
852 /usr/local/etc/amavis-logwatch.conf
853 The
<b>amavis-logwatch
</b> configuration file in standalone mode
856 /etc/logwatch/scripts/services/amavis
857 The Logwatch
<b>amavis
</b> filter
859 /etc/logwatch/conf/services/amavis.conf
860 The Logwatch
<b>amavis
</b> filter configuration file
863 logwatch(
8), system log analyzer and reporter
866 README, an overview of
<b>amavis-logwatch
</b>
867 Changes, the version change list history
868 Bugs, a list of the current bugs or other inadequacies
869 Makefile, the rudimentary installer
870 LICENSE, the usage and redistribution licensing terms
873 Covered under the included MIT/X-Consortium License:
874 http://www.opensource.org/licenses/mit-license.php
880 The original
<b>amavis
</b> Logwatch filter was written by Jim O'Halloran, and
881 has had many contributors over the years. They are entirely not
882 responsible for any errors, problems or failures since the current
883 author's hands have touched the source code.
888 </pre> </body> </html>
projects / amavis-logwatch.git / blob