7 An Amavisd-new log parser and analysis utility
12 \fBamavis-logwatch\fR [\fIoptions\fR] [\fIlogfile ...\fR]
16 The \fBamavis-logwatch\fR(1) utility is an Amavisd-new log parser
17 that produces summaries, details, and statistics regarding
18 the operation of Amavisd-new (henceforth, simply called Amavis).
20 This utility can be used as a
21 standalone program, or as a Logwatch filter module to produce
22 Amavisd-new summary and detailed reports from within Logwatch.
24 \fBAmavis-logwatch\fR is able to produce
25 a wide range of reports with data grouped and sorted as much as possible
26 to reduce noise and highlight patterns.
27 Brief summary reports provide a
28 quick overview of general Amavis operations and message
29 delivery, calling out warnings that may require attention.
30 Detailed reports provide easy to scan, hierarchically-arranged
31 and organized information, with as much or little detail as
34 Much of the interesting data is available when Amavis'
35 $log_level is set to at least 2.
36 See \fBAmavis Log Level\fR below.
38 \fBAmavis-logwatch\fR outputs two principal sections: a \fBSummary\fR section
39 and a \fBDetailed\fR section.
40 For readability and quick scanning, all event or hit counts appear in the left column,
41 followed by brief description of the event type, and finally additional
42 statistics or count representations may appear in the rightmost column.
44 The following segment from a sample Summary report illustrates:
48 ****** Summary ********************************************
50 9 Miscellaneous warnings
52 20313 Total messages scanned ---------------- 100.00%
53 1008.534M Total bytes scanned 1,057,524,252
54 ======== ================================================
56 1190 Blocked ------------------------------- 5.86%
57 18 Malware blocked 0.09%
58 4 Banned name blocked 0.02%
59 416 Spam blocked 2.05%
60 752 Spam discarded (no quarantine) 3.70%
62 19123 Passed -------------------------------- 94.14%
63 47 Bad header passed 0.23%
64 19076 Clean passed 93.91%
65 ======== ================================================
67 18 Malware ------------------------------- 0.09%
68 18 Malware blocked 0.09%
70 4 Banned -------------------------------- 0.02%
71 4 Banned file blocked 0.02%
73 1168 Spam ---------------------------------- 5.75%
74 416 Spam blocked 2.05%
75 752 Spam discarded (no quarantine) 3.70%
77 19123 Ham ----------------------------------- 94.14%
78 47 Bad header passed 0.23%
79 19076 Clean passed 93.91%
80 ======== ================================================
82 1982 SpamAssassin bypassed
83 32 Released from quarantine
84 2 DSN notification (debug supplemental)
89 58 Bad header (debug supplemental)
90 40 Extra code modules loaded at runtime
94 The report indicates there were 9 general warnings, and
95 \fBAmavis\fR scanned a total of 20313 messages
96 for a total of 1008.53 megabytes or 1,057,524,252 bytes.
97 The next summary groups shows the Blocked / Passed overview,
98 with 1190 Blocked messages (broken down as 18 messages blocked as malware,
99 4 messages with banned names, 416 spam messages, and 752 discarded
100 messages), and 19123 Passed messages (47 messages with bad headers
101 and 19076 clean messages).
103 The next (optional) summary grouping shows message disposition by contents category.
104 There were 18 malware messages and 4 banned file messages (all blocked),
105 1168 Spam messages, of which 416 were blocked (quarantined) and 752 discarded.
106 Finally, there were 19123 messages consdidered to be Ham (i.e. not spam), 47
107 of which contained bad headers.
109 Additional count summaries for a variety of events are also listed.
111 There are dozens of sub-sections available in the \fBDetailed\fR report, each of
112 whose output can be controlled in various ways.
113 Each sub-section attempts to group and present the most meaningful data at superior levels,
114 while pushing less useful or \fInoisy\fR data towards inferior levels.
115 The goal is to provide as much benefit as possible from smart grouping of
116 data, to allow faster report scanning, pattern identification, and problem solving.
117 Data is always sorted in descending order by count, and then numerically by IP address
118 or alphabetically as appropriate.
120 The following Spam blocked segment from a sample \fBDetailed\fR report
121 illustrates the basic hierarchical level structure of \fBamavis-logwatch\fR:
125 ****** Detailed *******************************************
127 19346 Spam blocked -----------------------------------
139 The \fBamavis-logwatch\fR utility reads from STDIN or from the named Amavis
141 Multiple \fIlogfile\fR arguments may be specified, each processed
143 The user running \fBamavis-logwatch\fR must have read permission on
147 The options listed below affect the operation of \fBamavis-logwatch\fR.
148 Options specified later on the command line override earlier ones.
149 Any option may be abbreviated to an unambiguous length.
151 .IP "\fB--[no]autolearn\fR"
153 .IP "\fB--show_autolearn \fIboolean\fR"
155 Enables (disables) output of the autolearn report.
156 This report is only available if the default Amavis \fB$log_templ\fR
157 has been modified to provide autolearn results in log entries.
158 This can be done by uncommenting two lines in the Amavis program itself (where the
159 default log templates reside), or by correctly adding the \fB$log_templ\fR
160 variable to the \fBamavisd.conf\fR file.
161 See Amavis' \fBREADME.customize\fR and search near the end
162 of the Amavisd program for "autolearn".
163 .IP "\fB--[no]by_ccat_summary\fR"
165 .IP "\fB--show_by_ccat_summary \fIboolean\fR"
167 Enables (disables) the by contents category summary in the \fBSummary\fR section.
169 .IP "\fB-f \fIconfig_file\fR"
171 .IP "\fB--config_file \fIconfig_file\fR"
173 Use an alternate configuration file \fIconfig_file\fR instead of
175 This option may be used more than once.
176 Multiple configuration files will be processed in the order presented on the command line.
177 See \fBCONFIGURATION FILE\fR below.
178 .IP "\fB--debug \fIkeywords\fR"
179 Output debug information during the operation of \fBamavis-logwatch\fR.
180 The parameter \fIkeywords\fR is one or more comma or space separated keywords.
181 To obtain the list of valid keywords, use --debug xxx where xxx is any invalid keyword.
182 .IP "\fB--detail \fIlevel\fR"
183 Sets the maximum detail level for \fBamavis-logwatch\fR to \fIlevel\fR.
184 This option is global, overriding any other output limiters described below.
186 The \fBamavis-logwatch\fR utility
187 produces a \fBSummary\fR section, a \fBDetailed\fR section, and
188 additional report sections.
189 With \fIlevel\fR less than 5, \fBamavis-logwatch\fR will produce
190 only the \fBSummary\fR section.
191 At \fIlevel\fR 5 and above, the \fBDetailed\fR section, and any
192 additional report sections are candidates for output.
193 Each incremental increase in \fIlevel\fR generates one additional
194 hierarchical sub-level of output in the \fBDetailed\fR section of the report.
195 At \fIlevel\fR 10, all levels are output.
196 Lines that exceed the maximum report width (specified with
197 \fBmax_report_width\fR) will be cut.
198 Setting \fIlevel\fR to 11 will prevent lines in the report from being cut (see also \fB--line_style\fR).
199 .IP "\fB--[no]first_recip_only\fR"
201 .IP "\fB--show_first_recip_only \fIboolean\fR"
203 Specifies whether or not to sort by, and show, only the first
204 recipient when a scanned messages contains multiple recipients.
206 Print usage information and a brief description about command line options.
207 .IP "\fB--ipaddr_width \fIwidth\fR"
208 Specifies that IP addresses in address/hostname pairs should be printed
209 with a field width of \fIwidth\fR characters.
210 Increasing the default may be useful for systems using long IPv6 addresses.
211 .IP "\fB-l limiter=levelspec\fR"
213 .IP "\fB--limit limiter=levelspec\fR"
215 Sets the level limiter \fIlimiter\fR with the specification \fIlevelspec\fR.
216 .IP "\fB--line_style \fIstyle\fR"
217 Specifies how to handle long report lines.
218 Three styles are available: \fBfull\fR, \fBtruncate\fR, and \fBwrap\fR.
219 Setting \fIstyle\fR to \fBfull\fR will prevent cutting lines to \fBmax_report_width\fR;
220 this is what occurs when \fBdetail\fR is 11 or higher.
221 When \fIstyle\fR is \fBtruncate\fR (the default),
222 long lines will be truncated according to \fBmax_report_width\fR.
223 Setting \fIstyle\fR to \fBwrap\fR will wrap lines longer than \fBmax_report_width\fR such that
224 left column hit counts are not obscured.
225 This option takes precedence over the line style implied by the \fBdetail\fR level.
226 The options \fB--full\fR, \fB--truncate\fR, and \fB--wrap\fR are synonyms.
228 .IP "\fB--nodetail\fR"
229 Disables the \fBDetailed\fR section of the report, and all supplemental reports.
230 This option provides a convenient mechanism to quickly disable all sections
231 under the \fBDetailed\fR report, where subsequent command line
232 options may re-enable one or more sections to create specific reports.
235 .IP "\fB--sarules \fR\`\fIS,H\fR\'"
236 .IP "\fB--sarules default"
238 Enables the SpamAssassin Rules Hit report.
239 The comma-separated \fIS\fR and \fIH\fR arguments are top N values for the Spam and Ham
240 reports, respectively, and can be any integer greater than or equal to 0, or the keyword \fBall\fR.
241 The keyword \fBdefault\fR uses the built-in default values.
242 .IP "\fB--nosarules\fR"
243 Disables the SpamAssassin Rules Hit report.
246 .IP "\fB--sa_timings \fR\fInrows\fR"
247 Enables the SpamAssassin Timings percentiles report.
248 The report can be limited to the top N rows with the \fInrows\fR argument.
249 This report requires Amavis 2.6+ and SpamAssassin 3.3+.
251 .IP "\fB--sa_timings_percentiles \fR\`\fIP1 [P2 ...]\fR\'"
252 Specifies the percentiles shown in the SpamAssassin Timings report.
253 The arguments \fIP1 ...\fR are integers from 0 to 100 inclusive.
254 Their order will be preserved in the report.
255 .IP "\fB--nosa_timings\fR"
256 Disables the SpamAssassin Timings report.
257 .IP "\fB--version\fR"
258 Print \fBamavis-logwatch\fR version information.
261 .IP "\fB--score_frequencies \fR\`\fIB1 [B2 ...]\fR\'"
262 .IP "\fB--score_frequencies default"
264 Enables the Spam Score Frequency report.
265 The arguments \fIB1 ...\fR are frequency distribution buckets, and can be any real numbers.
266 Their order will be preserved in the report.
267 The keyword \fBdefault\fR uses the built-in default values.
268 .IP "\fB--noscore_frequencies\fR"
269 Disables the Spam Score Frequency report.
272 .IP "\fB--score_percentiles \fR\`\fIP1 [P2 ...]\fR\'"
273 .IP "\fB--score_percentiles default"
275 Enables the Spam Score Percentiles report.
276 The arguments \fIP1 ...\fR specify the percentiles shown in the report,
277 and are integers from 0 to 100 inclusive.
278 The keyword \fBdefault\fR uses the built-in default values.
279 .IP "\fB--noscore_percentiles\fR"
280 Disables the Spam Score Percentiles report.
282 .IP "\fB--[no]sect_vars\fR"
284 .IP "\fB--show_sect_vars \fIboolean\fR"
286 Enables (disables) supplementing each \fBDetailed\fR section title
287 with the name of that section's level limiter.
288 The name displayed is the command line option (or configuration
289 file variable) used to limit that section's output.
291 With the large number of level limiters available in \fBamavis-logwatch\fR,
292 this a convenient mechanism for determining exactly which level limiter
294 .IP "\fB--[no]startinfo\fR"
296 .IP "\fB--show_startinfo \fIboolean\fR"
298 Enables (disables) the Amavis startup report showing most recent Amavis startup details.
299 .IP "\fB--[no]summary\fR"
300 .IP "\fB--show_summary\fR"
301 Enables (disables) displaying of the the \fBSummary\fR section of the report.
302 The variable Amavis_Show_Summary in used in a configuration file.
303 .IP "\fB--syslog_name \fInamepat\fR"
304 Specifies the syslog service name that \fBamavis-logwatch\fR uses
305 to match syslog lines.
306 Only log lines whose service name matches
307 the perl regular expression \fInamepat\fR will be used by
308 \fBamavis-logwatch\fR; all non-matching lines are silently ignored.
309 This is useful when a pre-installed Amavis package uses a name
310 other than the default (\fBamavis\fR).
312 \fBNote:\fR if you use parenthesis in your regular expression, be sure they are cloistering
313 and not capturing: use \fB(?:\fIpattern\fB)\fR instead of \fB(\fIpattern\fB)\fR.
316 .IP "\fB--timings \fR\fIpercent\fR"
317 Enables the Amavis Scan Timings percentiles report.
318 The report can be top N-percent limited with the \fIpercent\fR argument.
320 .IP "\fB--timings_percentiles \fR\`\fIP1 [P2 ...]\fR\'"
321 Specifies the percentiles shown in the Scan Timings report.
322 The arguments \fIP1 ...\fR are integers from 0 to 100 inclusive.
323 Their order will be preserved in the report.
324 .IP "\fB--notimings\fR"
325 Disables the Amavis Scan Timings report.
326 .IP "\fB--version\fR"
327 Print \fBamavis-logwatch\fR version information.
331 The output of every section in the \fBDetailed\fR report is controlled by a level limiter.
332 The name of the level limiter variable will be output when the \fBsect_vars\fR option is set.
333 Level limiters are set either via command line in standalone mode with \fB--limit \fIlimiter\fB=\fIlevelspec\fR option,
334 or via configuration file variable \fB$amavis_\fIlimiter\fB=\fIlevelspec\fR.
335 Each limiter requires a \fIlevelspec\fR argument, which is described below in \fBLEVEL CONTROL\fR.
337 The list of level limiters is shown below.
347 Amavis major contents category (ccatmajor) sections, listed in order of priority:
348 VIRUS, BANNED, UNCHECKED, SPAM, SPAMMY, BADH, OVERSIZED, MTA, CLEAN.
350 .IP "\fBMalwareBlocked"
351 .IP "\fBMalwarePassed"
352 Blocked or passed messages that contain malware (ccatmajor: VIRUS).
354 .IP "\fBBannedNameBlocked"
355 .IP "\fBBannedNamePassed"
356 Blocked or passed messages that contain banned names in MIME parts (ccatmajor: BANNED).
358 .IP "\fBUncheckedBlocked"
359 .IP "\fBUncheckedPassed"
360 Blocked or passed messages that were not checked by a virus scanner or SpamAssassin (Amavis ccatmajor: UNCHECKED).
364 Blocked or passed messages that were considered spam that reached kill level (Amavis ccatmajor: SPAM)
366 .IP "\fBSpammyBlocked"
367 .IP "\fBSpammyPassed"
368 Blocked or passed messages that were considered spam, but did not reach kill level (Amavis ccatmajor: SPAMMY)
370 .IP "\fBBadHeaderBlocked"
371 .IP "\fBBadHeaderPassed"
372 Blocked or passed messages that contain bad mail headers (ccatmajor: BAD-HEADER).
374 .IP "\fBOversizedBlocked"
375 .IP "\fBOversizedPassed"
376 Blocked or passed messages that were considered oversized (Amavis ccatmajor: OVERSIZED).
380 Blocked or passed messages due to failure to re-inject to MTA (Amavis ccatmajor: MTA-BLOCKED).
381 Occurrences of this event indicates a configuration problem.
382 [ note: I don't believe mtapassed occurs, but exists for completeness.]
384 .IP "\fBOtherBlocked"
386 Blocked or passed messages that are not any of other major contents categories (Amavis ccatmajor: OTHER).
389 .IP "\fBTempFailBlocked"
390 .IP "\fBTempfailPassed"
391 Blocked or passed messages that had a temporary failure (Amavis ccatmajor: TEMPFAIL)
393 .IP "\fBCleanBlocked"
394 .IP "\fBCleanPassed "
395 Messages blocked or passed which were considered clean (Amavis ccatmajor: CLEAN; i.e. non-spam, non-viral).
398 Other sections, arranged alphabetically:
400 .IP "\fBAvConnectFailure"
401 Problems connecting to Anti-Virus scanner(s).
404 Timeouts awaiting responses from Anti-Virus scanner(s).
406 .IP "\fBArchiveExtract"
407 Archive extraction problems.
409 .IP "\fBBadHeaderSupp"
410 Supplemental debug information regarding messages containing bad mail headers.
413 Messages frequencies by Bayesian probability buckets.
416 Invalid mail address syntax.
419 Messages that were (soft-)blacklisted. See also Whitelisted below.
421 .IP "\fBBounceKilled"
422 .IP "\fBBounceRescued"
423 .IP "\fBBounceUnverifiable"
424 Disposition of incoming bounce messages (DSNs).
427 MIME attachment breakdown by type/subtype.
430 Errors encountered with or returned by DCC.
433 Errors encountered during defang process.
436 Messages defanged (rendered harmless).
438 .IP "\fBDsnNotification"
439 Errors encountered during attempt to send delivery status notification.
441 .IP "\fBDsnSuppressed"
442 Delivery status notification (DSN) intentionally suppressed.
444 .IP "\fBExtraModules"
445 Additional code modules Amavis loaded during runtime.
448 Forged sender addresses, as determimed by Amavis.
451 Fatal events. These are presented at the top of the report, as they may require attention.
453 .IP "\fBLocalDeliverySkipped"
454 Failures delivering to a local address.
456 .IP "\fBMalwareByScanner"
457 Breakdown of malware by scanner(s) that detected the malware.
460 Errors encountered during MIME extraction.
463 Panic events. These are presented at the top of the report, as they may require attention.
466 Passive fingerprint (p0f) hits, grouped by mail contents type (virus, unchecked, banned, spam, ham),
467 next by operating system genre, and finally by IP address.
468 Note: Windows systems are refined by Windows OS version, whereas versions of other operating systems
469 are grouped generically.
472 Messages that were released from Amavis quarantine.
475 Diagnostics as reported from SpamAssassin.
477 .IP "\fBSmtpResponse"
478 SMTP responses received during dialog with MTA. These log entries are primarly debug.
480 .IP "\fBTmpPreserved"
481 Temporary directories preserved by Amavis when some component encounters a problem or failure.
482 Directories listed and their corresponding log entries should be evaluated for problems.
484 .IP "\fBVirusScanSkipped"
485 Messages that could not be scanned by a virus scanner.
488 Warning events not categorized in specific warnings below.
489 These are presented at the top of the report, as they may require attention.
491 .IP "\fBWarningAddressModified"
492 Incomplete email addresses modified by Amavis for safety.
494 .IP "\fBWarningNoQuarantineId"
495 Attempts to release a quarantined message that did not contain an X-Quarantine-ID header.
497 .IP "\fBWarningSecurity \fIlevelspec\fR"
498 Insecure configuration or utility used by Amavis.
500 .IP "\fBWarningSmtpShutdown"
501 Failures during SMTP conversation with MTA.
504 Failures to communicate with, or error replies from, SQL service.
507 Messages that were (soft-)whitelisted. See also Blacklisted above.
513 The \fBDetailed\fR section of the report consists of a number of sub-sections,
514 each of which is controlled both globally and independently.
515 Two settings influence the output provided in the \fBDetailed\fR report:
516 a global detail level (specified with \fB--detail\fR) which has final (big hammer)
517 output-limiting control over the \fBDetailed\fR section,
518 and sub-section specific detail settings (small hammer), which allow further limiting
519 of the output for a sub-section.
520 Each sub-section may be limited to a specific depth level, and each sub-level may be limited with top N or threshold limits.
521 The \fIlevelspec\fR argument to each of the level limiters listed above is used to accomplish this.
523 It is probably best to continue explanation of sub-level limiting with the following well-known outline-style hierarchy, and
547 The simplest form of output limiting suppresses all output below a specified level.
548 For example, a \fIlevelspec\fR set to "2" shows only data in levels 0 through 2.
549 Think of this as collapsing each sub-level 2 item, thus hiding all inferior levels (3, 4, ...),
561 Sometimes the volume of output in a section is too great, and it is useful to suppress any data that does not exceed a certain threshold value.
562 Consider a dictionary spam attack, which produces very lengthy lists of hit-once recipient email or IP addresses.
563 Each sub-level in the hierarchy can be threshold-limited by setting the \fIlevelspec\fR appropriately.
564 Setting \fIlevelspec\fR to the value "2::5" will suppress any data at level 2 that does not exceed a hit count of 5.
566 Perhaps producing a top N list, such as top 10 senders, is desired.
567 A \fIlevelspec\fR of "3:10:" limits level 3 data to only the top 10 hits.
569 With those simple examples out of the way, a \fIlevelspec\fR is defined as a whitespace- or comma-separated list of one or more of the following:
571 Specifies the maximum level to be output for this sub-section, with a range from 0 to 10.
572 if \fIl\fR is 0, no levels will be output, effectively disabling the sub-section
573 (level 0 data is already provided in the Summary report, so level 1 is considered the first useful level in the \fBDetailed\fR report).
574 Higher values will produce output up to and including the specified level.
575 .IP "\fIl\fB.\fIn\fR"
576 Same as above, with the addition that \fIn\fR limits this section's level 1 output to
577 the top \fIn\fR items.
578 The value for \fIn\fR can be any integer greater than 1.
579 (This form of limiting has less utility than the syntax shown below. It is provided for
580 backwards compatibility; users are encouraged to use the syntax below).
581 .IP "\fIl\fB:\fIn\fB:\fIt\fR"
582 This triplet specifies level \fIl\fR, top \fIn\fR, and minimum threshold \fIt\fR.
583 Each of the values are integers, with \fIl\fR being the level limiter as described above, \fIn\fR being
584 a top \fIn\fR limiter for the level \fIl\fR, and \fIt\fR being the threshold limiter for level \fIl\fR.
585 When both \fIn\fR and \fIt\fR are specified, \fIn\fR has priority, allowing top \fIn\fR lists (regardless of
587 If the value of \fIl\fR is omitted, the specified values for \fIn\fR and/or \fIt\fR are used for
588 all levels available in the sub-section.
589 This permits a simple form of wildcarding (eg. place minimum threshold limits on all levels).
590 However, specific limiters always override wildcard limiters.
591 The first form of level limiter may be included in \fIlevelspec\fR to restrict output, regardless of how many triplets are present.
593 All three forms of limiters are effective only when \fBamavis-logwatch\fR's detail level is 5
594 or greater (the \fBDetailed\fR section is not activated until detail is at least 5).
596 See the \fBEXAMPLES\fR section for usage scenarios.
597 .SH CONFIGURATION FILE
599 \fBAmavis-logwatch\fR can read configuration settings from a configuration file.
600 Essentially, any command line option can be placed into a configuration file, and
601 these settings are read upon startup.
603 Because \fBamavis-logwatch\fR can run either standalone or within Logwatch,
604 to minimize confusion, \fBamavis-logwatch\fR inherits Logwatch's configuration
605 file syntax requirements and conventions.
608 White space lines are ignored.
610 Lines beginning with \fB#\fR are ignored
612 Settings are of the form:
615 \fIoption\fB = \fIvalue\fR
619 Spaces or tabs on either side of the \fB=\fR character are ignored.
621 Any \fIvalue\fR protected in double quotes will be case-preserved.
623 All other content is reduced to lowercase (non-preserving, case insensitive).
625 All \fBamavis-logwatch\fR configuration settings must be prefixed with "\fB$amavis_\fR" or
626 \fBamavis-logwatch\fR will ignore them.
628 When running under Logwatch, any values not prefixed with "\fB$amavis_\fR" are
629 consumed by Logwatch; it only passes to \fBamavis-logwatch\fR (via environment variable)
630 settings it considers valid.
632 The values \fBTrue\fR and \fBYes\fR are converted to 1, and \fBFalse\fR and \fBNo\fR are converted to 0.
634 Order of settings is not preserved within a configuration file (since settings are passed
635 by Logwatch via environment variables, which have no defined order).
637 To include a command line option in a configuration file,
638 prefix the command line option name with the word "\fB$amavis_\fR".
639 The following configuration file setting and command line option are equivalent:
642 \fB$amavis_Line_Style = Truncate\fR
644 \fB--line_style Truncate\fR
647 Level limiters are also prefixed with \fB$amavis_\fR, but on the command line are specified with the \fB--limit\fR option:
650 \fB$amavis_SpamBlocked = 2\fR
652 \fB--limit SpamBlocked=2\fR
657 The order of command line options and configuration file processing occurs as follows:
658 1) The default configuration file is read if it exists and no \fB--config_file\fR was specified on a command line.
659 2) Configuration files are read and processed in the order found on the command line.
660 3) Command line options override any options already set either via command line or from any configuration file.
662 Command line options are interpreted when they are seen on the command line, and later options will override previously set options.
670 The \fBamavis-logwatch\fR utility exits with a status code of 0, unless an error
671 occurred, in which case a non-zero exit status is returned.
677 .SS Running Standalone
678 \fBNote:\fR \fBamavis-logwatch\fR reads its log data from one or more named Amavis log files, or from STDIN.
679 For brevity, where required, the examples below use the word \fIfile\fR as the command line
680 argument meaning \fI/path/to/amavis.log\fR.
681 Obviously you will need to substitute \fIfile\fR with the appropriate path.
684 To run \fBamavis-logwatch\fR in standalone mode, simply run:
688 \fBamavis-logwatch \fIfile\fR
692 A complete list of options and basic usage is available via:
696 \fBamavis-logwatch --help\fR
700 To print a summary only report of Amavis log data:
704 \fBamavis-logwatch --detail 1 \fIfile\fR
708 To produce a summary report and a one-level detail report for May 25th:
712 \fBgrep 'May 25' \fIfile\fB | amavis-logwatch --detail 5\fR
716 To produce only a top 10 list of Sent email domains, the summary report and detailed reports
717 are first disabled. Since commands line options are read and enabled left-to-right,
718 the Sent section is re-enabled to level 1 with a level 1 top 10 limiter:
722 \fBamavis-logwatch --nosummary --nodetail \\
723 --limit spamblocked '1 1:10:' \fIfile\fR
727 The following command and its sample output shows a more complex level limiter example.
728 The command gives the top 4 spam blocked recipients (level 1), and under with each recipient
729 the top 2 sending IPs (level 2) and finally below that, only envelope from addresses (level 3) with hit counts
731 Ellipses indicate top N or threshold-limited data:
735 \fBamavis-logwatch --nosummary --nodetail \\
736 --limit spamblocked '1:4: 2:2: 3::6' \fIfile\fR
739 19346 Spam blocked -----------------------------------
768 .SS Running within Logwatch
769 \fBNote:\fR Logwatch versions prior to 7.3.6, unless configured otherwise, required the \fB--print\fR option to print to STDOUT instead of sending reports via email.
770 Since version 7.3.6, STDOUT is the default output destination, and the \fB--print\fR option has been replaced
771 by \fB--output stdout\fR. Check your configuration to determine where report output will be directed, and add the appropriate option to the commands below.
773 To print a summary report for today's Amavis log data:
777 \fBlogwatch --service amavis --range today --detail 1\fR
781 To print a report for today's Amavis log data, with one level
782 of detail in the \fBDetailed\fR section:
786 \fBlogwatch --service amavis --range today --detail 5\fR
790 To print a report for yesterday, with two levels of detail in the \fBDetailed\fR section:
794 \fBlogwatch --service amavis --range yesterday --detail 6\fR
798 To print a report from Dec 12th through Dec 14th, with four levels of detail in the \fBDetailed\fR section:
802 \fBlogwatch --service amavis --range \\
803 'between 12/12 and 12/14' --detail 8\fR
806 To print a report for today, with all levels of detail:
810 \fBlogwatch --service amavis --range today --detail 10\fR
813 Same as above, but leaves long lines uncropped:
817 \fBlogwatch --service amavis --range today --detail 11\fR
819 .SS "Amavis Log Level"
821 Amavis provides additional log information when the variable
822 \fB$log_level\fR is increased above the default 0 value.
823 This information is used by the \fBamavis-logwatch\fR utility to provide additional reports,
824 not available with the default \fB$log_level\fR=0 value.
825 A \fB$log_level\fR of 2 is suggested.
827 If you prefer not to increase the noise level in your main mail or Amavis logs,
828 you can configure syslog to log Amavis' output to multiple log files,
829 where basic log entries are routed to your main mail log(s) and more detailed
830 entries routed to an Amavis-specific log file used to feed the \fBamavis-logwatch\fR utility.
832 A convenient way to accomplish this is to change the Amavis
833 configuration variables in \fBamavisd.conf\fR as shown below:
838 $syslog_facility = 'local5';
839 $syslog_priority = 'debug';
843 This increases \fB$log_level\fR to 2, and sends Amavis' log entries to
844 an alternate syslog facility (eg. \fBlocal5\fR, user), which can then be
845 routed to one or more log files, including your main mail log file:
849 #mail.info -/var/log/maillog
850 mail.info;local5.notice -/var/log/maillog
852 local5.info -/var/log/amavisd-info.log
856 \fBAmavis\fR' typical \fB$log_level\fR 0 messages will be directed to both your maillog
857 and to the \fBamavisd-info.log\fR file, but higher \fB$log_level\fR messages
858 will only be routed to the \fBamavisd-info.log\fR file.
859 For additional information on Amavis' logging, search the
860 file \fBRELEASE_NOTES\fR in the Amavis distribution for:
863 "syslog priorities are now dynamically derived"
871 The \fBamavis-logwatch\fR program uses the following (automatically set) environment
872 variables when running under Logwatch:
873 .IP \fBLOGWATCH_DETAIL_LEVEL\fR
874 This is the detail level specified with the Logwatch command line argument \fB--detail\fR
875 or the \fBDetail\fR setting in the ...conf/services/amavis.conf configuration file.
876 .IP \fBLOGWATCH_DEBUG\fR
877 This is the debug level specified with the Logwatch command line argument \fB--debug\fR.
878 .IP \fBamavis_\fIxxx\fR
879 The Logwatch program passes all settings \fBamavis_\fIxxx\fR in the configuration file ...conf/services/amavis.conf
880 to the \fBamavis\fR filter (which is actually named .../scripts/services/amavis) via environment variable.
885 .IP "/usr/local/bin/amavis-logwatch"
886 The \fBamavis-logwatch\fR program
887 .IP "/usr/local/etc/amavis-logwatch.conf"
888 The \fBamavis-logwatch\fR configuration file in standalone mode
890 .IP "/etc/logwatch/scripts/services/amavis"
891 The Logwatch \fBamavis\fR filter
892 .IP "/etc/logwatch/conf/services/amavis.conf"
893 The Logwatch \fBamavis\fR filter configuration file
897 logwatch(8), system log analyzer and reporter
902 README, an overview of \fBamavis-logwatch\fR
903 Changes, the version change list history
904 Bugs, a list of the current bugs or other inadequacies
905 Makefile, the rudimentary installer
906 LICENSE, the usage and redistribution licensing terms
911 Covered under the included MIT/X-Consortium License:
912 http://www.opensource.org/licenses/mit-license.php
920 The original \fBamavis\fR Logwatch filter was written by
921 Jim O'Halloran, and has had many contributors over the years.
922 They are entirely not responsible for any errors, problems or failures since the current author's
923 hands have touched the source code.