+++ /dev/null
-<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
- "http://www.w3.org/TR/html4/loose.dtd">
-<html> <head>
-<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
-<title> Man page: amavis-logwatch(1) </title>
-</head> <body> <pre>
-AMAVIS-LOGWATCH(1) General Commands Manual AMAVIS-LOGWATCH(1)
-
-
-
-<b>NAME</b>
- amavis-logwatch - An Amavisd-new log parser and analysis utility
-
-<b>SYNOPSIS</b>
- <b>amavis-logwatch</b> [<i>options</i>] [<i>logfile ...</i>]
-
-<b>DESCRIPTION</b>
- The <b>amavis-logwatch</b>(1) utility is an Amavisd-new log parser that pro-
- duces summaries, details, and statistics regarding the operation of
- Amavisd-new (henceforth, simply called Amavis).
-
- This utility can be used as a standalone program, or as a Logwatch fil-
- ter module to produce Amavisd-new summary and detailed reports from
- within Logwatch.
-
- <b>Amavis-logwatch</b> is able to produce a wide range of reports with data
- grouped and sorted as much as possible to reduce noise and highlight
- patterns. Brief summary reports provide a quick overview of general
- Amavis operations and message delivery, calling out warnings that may
- require attention. Detailed reports provide easy to scan, hierarchi-
- cally-arranged and organized information, with as much or little detail
- as desired.
-
- Much of the interesting data is available when Amavis' $log_level is
- set to at least 2. See <b>Amavis Log Level</b> below.
-
- <b>Amavis-logwatch</b> outputs two principal sections: a <b>Summary</b> section and a
- <b>Detailed</b> section. For readability and quick scanning, all event or hit
- counts appear in the left column, followed by brief description of the
- event type, and finally additional statistics or count representations
- may appear in the rightmost column.
-
- The following segment from a sample Summary report illustrates:
-
- ****** Summary ********************************************
-
- 9 Miscellaneous warnings
-
- 20313 Total messages scanned ---------------- 100.00%
- 1008.534M Total bytes scanned 1,057,524,252
- ======== ================================================
-
- 1190 Blocked ------------------------------- 5.86%
- 18 Malware blocked 0.09%
- 4 Banned name blocked 0.02%
- 416 Spam blocked 2.05%
- 752 Spam discarded (no quarantine) 3.70%
-
- 19123 Passed -------------------------------- 94.14%
- 47 Bad header passed 0.23%
- 19076 Clean passed 93.91%
- ======== ================================================
-
- 18 Malware ------------------------------- 0.09%
- 18 Malware blocked 0.09%
-
- 4 Banned -------------------------------- 0.02%
- 4 Banned file blocked 0.02%
-
- 1168 Spam ---------------------------------- 5.75%
- 416 Spam blocked 2.05%
- 752 Spam discarded (no quarantine) 3.70%
-
- 19123 Ham ----------------------------------- 94.14%
- 47 Bad header passed 0.23%
- 19076 Clean passed 93.91%
- ======== ================================================
-
- 1982 SpamAssassin bypassed
- 32 Released from quarantine
- 2 DSN notification (debug supplemental)
- 2 Bounce unverifiable
- 2369 Whitelisted
- 2 Blacklisted
- 12 MIME error
- 58 Bad header (debug supplemental)
- 40 Extra code modules loaded at runtime
-
- The report indicates there were 9 general warnings, and <b>Amavis</b> scanned
- a total of 20313 messages for a total of 1008.53 megabytes or
- 1,057,524,252 bytes. The next summary groups shows the Blocked /
- Passed overview, with 1190 Blocked messages (broken down as 18 messages
- blocked as malware, 4 messages with banned names, 416 spam messages,
- and 752 discarded messages), and 19123 Passed messages (47 messages
- with bad headers and 19076 clean messages).
-
- The next (optional) summary grouping shows message disposition by con-
- tents category. There were 18 malware messages and 4 banned file mes-
- sages (all blocked), 1168 Spam messages, of which 416 were blocked
- (quarantined) and 752 discarded. Finally, there were 19123 messages
- consdidered to be Ham (i.e. not spam), 47 of which contained bad head-
- ers.
-
- Additional count summaries for a variety of events are also listed.
-
- There are dozens of sub-sections available in the <b>Detailed</b> report, each
- of whose output can be controlled in various ways. Each sub-section
- attempts to group and present the most meaningful data at superior lev-
- els, while pushing less useful or <i>noisy</i> data towards inferior levels.
- The goal is to provide as much benefit as possible from smart grouping
- of data, to allow faster report scanning, pattern identification, and
- problem solving. Data is always sorted in descending order by count,
- and then numerically by IP address or alphabetically as appropriate.
-
- The following Spam blocked segment from a sample <b>Detailed</b> report illus-
- trates the basic hierarchical level structure of <b>amavis-logwatch</b>:
-
- ****** Detailed *******************************************
-
- 19346 Spam blocked -----------------------------------
- 756 from@example.com
- 12 10.0.0.2
- 12 <>
- 12 192.168.2.2
- 12 <>
- 5 192.168.2.1
- ...
-
-
- The <b>amavis-logwatch</b> utility reads from STDIN or from the named Amavis
- <i>logfile</i>. Multiple <i>logfile</i> arguments may be specified, each processed
- in order. The user running <b>amavis-logwatch</b> must have read permission
- on each named log file.
-
- <b>Options</b>
- The options listed below affect the operation of <b>amavis-logwatch</b>.
- Options specified later on the command line override earlier ones. Any
- option may be abbreviated to an unambiguous length.
-
-
- <b>--[no]autolearn</b>
- <b>--show_autolearn</b> <i>boolean</i>
- Enables (disables) output of the autolearn report. This report
- is only available if the default Amavis <b>$log_templ</b> has been mod-
- ified to provide autolearn results in log entries. This can be
- done by uncommenting two lines in the Amavis program itself
- (where the default log templates reside), or by correctly adding
- the <b>$log_templ</b> variable to the <b>amavisd.conf</b> file. See Amavis'
- <b>README.customize</b> and search near the end of the Amavisd program
- for "autolearn".
-
- <b>--[no]by_ccat_summary</b>
- <b>--show_by_ccat_summary</b> <i>boolean</i>
- Enables (disables) the by contents category summary in the <b>Sum-</b>
- <b>mary</b> section. Default: enabled.
-
- <b>-f</b> <i>config</i><b>_</b><i>file</i>
- <b>--config_file</b> <i>config</i><b>_</b><i>file</i>
- Use an alternate configuration file <i>config</i><b>_</b><i>file</i> instead of the
- default. This option may be used more than once. Multiple con-
- figuration files will be processed in the order presented on the
- command line. See <b>CONFIGURATION FILE</b> below.
-
- <b>--debug</b> <i>keywords</i>
- Output debug information during the operation of <b>amavis-log-</b>
- <b>watch</b>. The parameter <i>keywords</i> is one or more comma or space
- separated keywords. To obtain the list of valid keywords, use
- --debug xxx where xxx is any invalid keyword.
-
- <b>--detail</b> <i>level</i>
- Sets the maximum detail level for <b>amavis-logwatch</b> to <i>level</i>.
- This option is global, overriding any other output limiters
- described below.
-
- The <b>amavis-logwatch</b> utility produces a <b>Summary</b> section, a
- <b>Detailed</b> section, and additional report sections. With <i>level</i>
- less than 5, <b>amavis-logwatch</b> will produce only the <b>Summary</b> sec-
- tion. At <i>level</i> 5 and above, the <b>Detailed</b> section, and any addi-
- tional report sections are candidates for output. Each incre-
- mental increase in <i>level</i> generates one additional hierarchical
- sub-level of output in the <b>Detailed</b> section of the report. At
- <i>level</i> 10, all levels are output. Lines that exceed the maximum
- report width (specified with <b>max_report_width</b>) will be cut.
- Setting <i>level</i> to 11 will prevent lines in the report from being
- cut (see also <b>--line_style</b>).
-
- <b>--[no]first_recip_only</b>
- <b>--show_first_recip_only</b> <i>boolean</i>
- Specifies whether or not to sort by, and show, only the first
- recipient when a scanned messages contains multiple recipients.
-
- <b>--help</b> Print usage information and a brief description about command
- line options.
-
- <b>--ipaddr_width</b> <i>width</i>
- Specifies that IP addresses in address/hostname pairs should be
- printed with a field width of <i>width</i> characters. Increasing the
- default may be useful for systems using long IPv6 addresses.
-
- <b>-l limiter=levelspec</b>
- <b>--limit limiter=levelspec</b>
- Sets the level limiter <i>limiter</i> with the specification <i>levelspec</i>.
-
- <b>--line_style</b> <i>style</i>
- Specifies how to handle long report lines. Three styles are
- available: <b>full</b>, <b>truncate</b>, and <b>wrap</b>. Setting <i>style</i> to <b>full</b> will
- prevent cutting lines to <b>max_report_width</b>; this is what occurs
- when <b>detail</b> is 11 or higher. When <i>style</i> is <b>truncate</b> (the
- default), long lines will be truncated according to
- <b>max_report_width</b>. Setting <i>style</i> to <b>wrap</b> will wrap lines longer
- than <b>max_report_width</b> such that left column hit counts are not
- obscured. This option takes precedence over the line style
- implied by the <b>detail</b> level. The options <b>--full</b>, <b>--truncate</b>,
- and <b>--wrap</b> are synonyms.
-
-
- <b>--nodetail</b>
- Disables the <b>Detailed</b> section of the report, and all supplemen-
- tal reports. This option provides a convenient mechanism to
- quickly disable all sections under the <b>Detailed</b> report, where
- subsequent command line options may re-enable one or more sec-
- tions to create specific reports.
-
- <b>--sarules</b> `<i>S,H</i>'
- <b>--sarules default</b>
- Enables the SpamAssassin Rules Hit report. The comma-separated
- <i>S</i> and <i>H</i> arguments are top N values for the Spam and Ham reports,
- respectively, and can be any integer greater than or equal to 0,
- or the keyword <b>all</b>. The keyword <b>default</b> uses the built-in
- default values.
-
- <b>--nosarules</b>
- Disables the SpamAssassin Rules Hit report.
-
- <b>--sa_timings</b> <i>nrows</i>
- Enables the SpamAssassin Timings percentiles report. The report
- can be limited to the top N rows with the <i>nrows</i> argument. This
- report requires Amavis 2.6+ and SpamAssassin 3.3+.
-
- <b>--sa_timings_percentiles</b> `<i>P1 [P2 ...]</i>'
- Specifies the percentiles shown in the SpamAssassin Timings
- report. The arguments <i>P1 ...</i> are integers from 0 to 100 inclu-
- sive. Their order will be preserved in the report.
-
- <b>--nosa_timings</b>
- Disables the SpamAssassin Timings report.
-
- <b>--version</b>
- Print <b>amavis-logwatch</b> version information.
-
- <b>--score_frequencies</b> `<i>B1 [B2 ...]</i>'
- <b>--score_frequencies default</b>
- Enables the Spam Score Frequency report. The arguments <i>B1 ...</i>
- are frequency distribution buckets, and can be any real numbers.
- Their order will be preserved in the report. The keyword
- <b>default</b> uses the built-in default values.
-
- <b>--noscore_frequencies</b>
- Disables the Spam Score Frequency report.
-
- <b>--score_percentiles</b> `<i>P1 [P2 ...]</i>'
- <b>--score_percentiles default</b>
- Enables the Spam Score Percentiles report. The arguments <i>P1 ...</i>
- specify the percentiles shown in the report, and are integers
- from 0 to 100 inclusive. The keyword <b>default</b> uses the built-in
- default values.
-
- <b>--noscore_percentiles</b>
- Disables the Spam Score Percentiles report.
-
-
- <b>--[no]sect_vars</b>
- <b>--show_sect_vars</b> <i>boolean</i>
- Enables (disables) supplementing each <b>Detailed</b> section title
- with the name of that section's level limiter. The name dis-
- played is the command line option (or configuration file vari-
- able) used to limit that section's output. With the large num-
- ber of level limiters available in <b>amavis-logwatch</b>, this a con-
- venient mechanism for determining exactly which level limiter
- affects a section.
-
- <b>--[no]startinfo</b>
- <b>--show_startinfo</b> <i>boolean</i>
- Enables (disables) the Amavis startup report showing most recent
- Amavis startup details.
-
- <b>--[no]summary</b>
-
- <b>--show_summary</b>
- Enables (disables) displaying of the the <b>Summary</b> section of the
- report. The variable Amavis_Show_Summary in used in a configu-
- ration file.
-
- <b>--syslog_name</b> <i>namepat</i>
- Specifies the syslog service name that <b>amavis-logwatch</b> uses to
- match syslog lines. Only log lines whose service name matches
- the perl regular expression <i>namepat</i> will be used by <b>amavis-log-</b>
- <b>watch</b>; all non-matching lines are silently ignored. This is
- useful when a pre-installed Amavis package uses a name other
- than the default (<b>amavis</b>).
-
- <b>Note:</b> if you use parenthesis in your regular expression, be sure
- they are cloistering and not capturing: use <b>(?:</b><i>pattern</i><b>)</b> instead
- of <b>(</b><i>pattern</i><b>)</b>.
-
- <b>--timings</b> <i>percent</i>
- Enables the Amavis Scan Timings percentiles report. The report
- can be top N-percent limited with the <i>percent</i> argument.
-
- <b>--timings_percentiles</b> `<i>P1 [P2 ...]</i>'
- Specifies the percentiles shown in the Scan Timings report. The
- arguments <i>P1 ...</i> are integers from 0 to 100 inclusive. Their
- order will be preserved in the report.
-
- <b>--notimings</b>
- Disables the Amavis Scan Timings report.
-
- <b>--version</b>
- Print <b>amavis-logwatch</b> version information.
-
-
- <b>Level Limiters</b>
- The output of every section in the <b>Detailed</b> report is controlled by a
- level limiter. The name of the level limiter variable will be output
- when the <b>sect_vars</b> option is set. Level limiters are set either via
- command line in standalone mode with <b>--limit</b> <i>limiter</i><b>=</b><i>levelspec</i> option,
- or via configuration file variable <b>$amavis_</b><i>limiter</i><b>=</b><i>levelspec</i>. Each
- limiter requires a <i>levelspec</i> argument, which is described below in
- <b>LEVEL CONTROL</b>.
-
- The list of level limiters is shown below.
-
-
- Amavis major contents category (ccatmajor) sections, listed in order of
- priority: VIRUS, BANNED, UNCHECKED, SPAM, SPAMMY, BADH, OVERSIZED, MTA,
- CLEAN.
-
- <b>MalwareBlocked</b>
- <b>MalwarePassed</b>
- Blocked or passed messages that contain malware (ccatmajor:
- VIRUS).
-
- <b>BannedNameBlocked</b>
- <b>BannedNamePassed</b>
- Blocked or passed messages that contain banned names in MIME
- parts (ccatmajor: BANNED).
-
- <b>UncheckedBlocked</b>
- <b>UncheckedPassed</b>
- Blocked or passed messages that were not checked by a virus
- scanner or SpamAssassin (Amavis ccatmajor: UNCHECKED).
-
- <b>SpamBlocked</b>
- <b>SpamPassed</b>
- Blocked or passed messages that were considered spam that
- reached kill level (Amavis ccatmajor: SPAM)
-
- <b>SpammyBlocked</b>
- <b>SpammyPassed</b>
- Blocked or passed messages that were considered spam, but did
- not reach kill level (Amavis ccatmajor: SPAMMY)
-
- <b>BadHeaderBlocked</b>
- <b>BadHeaderPassed</b>
- Blocked or passed messages that contain bad mail headers (ccat-
- major: BAD-HEADER).
-
- <b>OversizedBlocked</b>
- <b>OversizedPassed</b>
- Blocked or passed messages that were considered oversized
- (Amavis ccatmajor: OVERSIZED).
-
- <b>MtaBlocked</b>
- <b>MtaPassed</b>
- Blocked or passed messages due to failure to re-inject to MTA
- (Amavis ccatmajor: MTA-BLOCKED). Occurrences of this event
- indicates a configuration problem. [ note: I don't believe mta-
- passed occurs, but exists for completeness.]
-
- <b>OtherBlocked</b>
- <b>OtherPassed</b>
- Blocked or passed messages that are not any of other major con-
- tents categories (Amavis ccatmajor: OTHER).
-
-
- <b>TempFailBlocked</b>
- <b>TempfailPassed</b>
- Blocked or passed messages that had a temporary failure (Amavis
- ccatmajor: TEMPFAIL)
-
- <b>CleanBlocked</b>
- <b>CleanPassed</b>
- Messages blocked or passed which were considered clean (Amavis
- ccatmajor: CLEAN; i.e. non-spam, non-viral).
-
- Other sections, arranged alphabetically:
-
- <b>AvConnectFailure</b>
- Problems connecting to Anti-Virus scanner(s).
-
- <b>AvTimeout</b>
- Timeouts awaiting responses from Anti-Virus scanner(s).
-
- <b>ArchiveExtract</b>
- Archive extraction problems.
-
- <b>BadHeaderSupp</b>
- Supplemental debug information regarding messages containing bad
- mail headers.
-
- <b>Bayes</b> Messages frequencies by Bayesian probability buckets.
-
- <b>BadAddress</b>
- Invalid mail address syntax.
-
- <b>Blacklisted</b>
- Messages that were (soft-)blacklisted. See also Whitelisted
- below.
-
- <b>BounceKilled</b>
- <b>BounceRescued</b>
- <b>BounceUnverifiable</b>
- Disposition of incoming bounce messages (DSNs).
-
- <b>ContentType</b>
- MIME attachment breakdown by type/subtype.
-
- <b>DccError</b>
- Errors encountered with or returned by DCC.
-
- <b>DefangError</b>
- Errors encountered during defang process.
-
- <b>Defanged</b>
- Messages defanged (rendered harmless).
-
- <b>DsnNotification</b>
- Errors encountered during attempt to send delivery status noti-
- fication.
-
- <b>DsnSuppressed</b>
- Delivery status notification (DSN) intentionally suppressed.
-
- <b>ExtraModules</b>
- Additional code modules Amavis loaded during runtime.
-
- <b>FakeSender</b>
- Forged sender addresses, as determimed by Amavis.
-
- <b>Fatal</b> Fatal events. These are presented at the top of the report, as
- they may require attention.
-
- <b>LocalDeliverySkipped</b>
- Failures delivering to a local address.
-
- <b>MalwareByScanner</b>
- Breakdown of malware by scanner(s) that detected the malware.
-
- <b>MimeError</b>
- Errors encountered during MIME extraction.
-
- <b>Panic</b> Panic events. These are presented at the top of the report, as
- they may require attention.
-
- <b>p0f</b> Passive fingerprint (p0f) hits, grouped by mail contents type
- (virus, unchecked, banned, spam, ham), next by operating system
- genre, and finally by IP address. Note: Windows systems are
- refined by Windows OS version, whereas versions of other operat-
- ing systems are grouped generically.
-
- <b>Released</b>
- Messages that were released from Amavis quarantine.
-
- <b>SADiags</b>
- Diagnostics as reported from SpamAssassin.
-
- <b>SmtpResponse</b>
- SMTP responses received during dialog with MTA. These log
- entries are primarly debug.
-
- <b>TmpPreserved</b>
- Temporary directories preserved by Amavis when some component
- encounters a problem or failure. Directories listed and their
- corresponding log entries should be evaluated for problems.
-
- <b>VirusScanSkipped</b>
- Messages that could not be scanned by a virus scanner.
-
- <b>Warning</b>
- Warning events not categorized in specific warnings below.
- These are presented at the top of the report, as they may
- require attention.
-
- <b>WarningAddressModified</b>
- Incomplete email addresses modified by Amavis for safety.
-
- <b>WarningNoQuarantineId</b>
- Attempts to release a quarantined message that did not contain
- an X-Quarantine-ID header.
-
- <b>WarningSecurity</b> <i>levelspec</i>
- Insecure configuration or utility used by Amavis.
-
- <b>WarningSmtpShutdown</b>
- Failures during SMTP conversation with MTA.
-
- <b>WarningSql</b>
- Failures to communicate with, or error replies from, SQL ser-
- vice.
-
- <b>Whitelisted</b>
- Messages that were (soft-)whitelisted. See also Blacklisted
- above.
-
-
-<b>LEVEL CONTROL</b>
- The <b>Detailed</b> section of the report consists of a number of sub-sec-
- tions, each of which is controlled both globally and independently.
- Two settings influence the output provided in the <b>Detailed</b> report: a
- global detail level (specified with <b>--detail</b>) which has final (big ham-
- mer) output-limiting control over the <b>Detailed</b> section, and sub-section
- specific detail settings (small hammer), which allow further limiting
- of the output for a sub-section. Each sub-section may be limited to a
- specific depth level, and each sub-level may be limited with top N or
- threshold limits. The <i>levelspec</i> argument to each of the level limiters
- listed above is used to accomplish this.
-
- It is probably best to continue explanation of sub-level limiting with
- the following well-known outline-style hierarchy, and some basic exam-
- ples:
-
- level 0
- level 1
- level 2
- level 3
- level 4
- level 4
- level 2
- level 3
- level 4
- level 4
- level 4
- level 3
- level 4
- level 3
- level 1
- level 2
- level 3
- level 4
-
- The simplest form of output limiting suppresses all output below a
- specified level. For example, a <i>levelspec</i> set to "2" shows only data
- in levels 0 through 2. Think of this as collapsing each sub-level 2
- item, thus hiding all inferior levels (3, 4, ...), to yield:
-
- level 0
- level 1
- level 2
- level 2
- level 1
- level 2
-
- 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. Consider a dictionary spam attack, which produces very lengthy
- lists of hit-once recipient email or IP addresses. Each sub-level in
- the hierarchy can be threshold-limited by setting the <i>levelspec</i> appro-
- priately. Setting <i>levelspec</i> to the value "2::5" will suppress any data
- at level 2 that does not exceed a hit count of 5.
-
- Perhaps producing a top N list, such as top 10 senders, is desired. A
- <i>levelspec</i> of "3:10:" limits level 3 data to only the top 10 hits.
-
- With those simple examples out of the way, a <i>levelspec</i> is defined as a
- whitespace- or comma-separated list of one or more of the following:
-
- <i>l</i> Specifies the maximum level to be output for this sub-section,
- with a range from 0 to 10. if <i>l</i> is 0, no levels will be output,
- effectively disabling the sub-section (level 0 data is already
- provided in the Summary report, so level 1 is considered the
- first useful level in the <b>Detailed</b> report). Higher values will
- produce output up to and including the specified level.
-
- <i>l</i><b>.</b><i>n</i> Same as above, with the addition that <i>n</i> limits this section's
- level 1 output to the top <i>n</i> items. The value for <i>n</i> can be any
- integer greater than 1. (This form of limiting has less utility
- than the syntax shown below. It is provided for backwards com-
- patibility; users are encouraged to use the syntax below).
-
- <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>.
- Each of the values are integers, with <i>l</i> being the level limiter
- as described above, <i>n</i> being a top <i>n</i> limiter for the level <i>l</i>, and
- <i>t</i> being the threshold limiter for level <i>l</i>. When both <i>n</i> and <i>t</i>
- are specified, <i>n</i> has priority, allowing top <i>n</i> lists (regardless
- of threshold value). If the value of <i>l</i> is omitted, the speci-
- fied values for <i>n</i> and/or <i>t</i> are used for all levels available in
- the sub-section. This permits a simple form of wildcarding (eg.
- place minimum threshold limits on all levels). However, spe-
- cific limiters always override wildcard limiters. The first
- form of level limiter may be included in <i>levelspec</i> to restrict
- output, regardless of how many triplets are present.
-
- All three forms of limiters are effective only when <b>amavis-logwatch</b>'s
- detail level is 5 or greater (the <b>Detailed</b> section is not activated
- until detail is at least 5).
-
- See the <b>EXAMPLES</b> section for usage scenarios.
-
-<b>CONFIGURATION FILE</b>
- <b>Amavis-logwatch</b> can read configuration settings from a configuration
- file. Essentially, any command line option can be placed into a con-
- figuration file, and these settings are read upon startup.
-
- Because <b>amavis-logwatch</b> can run either standalone or within Logwatch,
- to minimize confusion, <b>amavis-logwatch</b> inherits Logwatch's configura-
- tion file syntax requirements and conventions. These are:
-
- <b>o</b> White space lines are ignored.
-
- <b>o</b> Lines beginning with <b>#</b> are ignored
-
- <b>o</b> Settings are of the form:
-
- <i>option</i> <b>=</b> <i>value</i>
-
-
- <b>o</b> Spaces or tabs on either side of the <b>=</b> character are ignored.
-
- <b>o</b> Any <i>value</i> protected in double quotes will be case-preserved.
-
- <b>o</b> All other content is reduced to lowercase (non-preserving, case
- insensitive).
-
- <b>o</b> All <b>amavis-logwatch</b> configuration settings must be prefixed with
- "<b>$amavis_</b>" or <b>amavis-logwatch</b> will ignore them.
-
- <b>o</b> When running under Logwatch, any values not prefixed with
- "<b>$amavis_</b>" are consumed by Logwatch; it only passes to <b>amavis-log-</b>
- <b>watch</b> (via environment variable) settings it considers valid.
-
- <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
- converted to 0.
-
- <b>o</b> Order of settings is not preserved within a configuration file
- (since settings are passed by Logwatch via environment variables,
- which have no defined order).
-
- To include a command line option in a configuration file, prefix the
- command line option name with the word "<b>$amavis_</b>". The following con-
- figuration file setting and command line option are equivalent:
-
- <b>$amavis_Line_Style = Truncate</b>
-
- <b>--line_style Truncate</b>
-
- Level limiters are also prefixed with <b>$amavis_</b>, but on the command line
- are specified with the <b>--limit</b> option:
-
- <b>$amavis_SpamBlocked = 2</b>
-
- <b>--limit SpamBlocked=2</b>
-
-
-
- The order of command line options and configuration file processing
- occurs as follows: 1) The default configuration file is read if it
- exists and no <b>--config_file</b> was specified on a command line. 2) Con-
- figuration files are read and processed in the order found on the com-
- mand line. 3) Command line options override any options already set
- either via command line or from any configuration file.
-
- Command line options are interpreted when they are seen on the command
- line, and later options will override previously set options.
-
-
-
-<b>EXIT STATUS</b>
- The <b>amavis-logwatch</b> utility exits with a status code of 0, unless an
- error occurred, in which case a non-zero exit status is returned.
-
-<b>EXAMPLES</b>
- <b>Running Standalone</b>
- <b>Note: amavis-logwatch</b> reads its log data from one or more named Amavis
- log files, or from STDIN. For brevity, where required, the examples
- below use the word <i>file</i> as the command line argument meaning
- <i>/path/to/amavis.log</i>. Obviously you will need to substitute <i>file</i> with
- the appropriate path.
-
- To run <b>amavis-logwatch</b> in standalone mode, simply run:
-
- <b>amavis-logwatch</b> <i>file</i>
-
- A complete list of options and basic usage is available via:
-
- <b>amavis-logwatch --help</b>
-
- To print a summary only report of Amavis log data:
-
- <b>amavis-logwatch --detail 1</b> <i>file</i>
-
- To produce a summary report and a one-level detail report for May 25th:
-
- <b>grep 'May 25'</b> <i>file</i> <b>| amavis-logwatch --detail 5</b>
-
- To produce only a top 10 list of Sent email domains, the summary report
- and detailed reports are first disabled. Since commands line options
- are read and enabled left-to-right, the Sent section is re-enabled to
- level 1 with a level 1 top 10 limiter:
-
- <b>amavis-logwatch --nosummary --nodetail \</b>
- <b>--limit spamblocked '1 1:10:'</b> <i>file</i>
-
- The following command and its sample output shows a more complex level
- limiter example. The command gives the top 4 spam blocked recipients
- (level 1), and under with each recipient the top 2 sending IPs (level
- 2) and finally below that, only envelope from addresses (level 3) with
- hit counts greater than 6. Ellipses indicate top N or threshold-lim-
- ited data:
-
- <b>amavis-logwatch --nosummary --nodetail \</b>
- <b>--limit spamblocked '1:4: 2:2: 3::6'</b> <i>file</i>
-
- 19346 Spam blocked -----------------------------------
- 756 joe@example.com
- 12 10.0.0.1
- 12 <>
- 12 10.99.99.99
- 12 <>
- ...
- 640 fred@example.com
- 8 10.0.0.1
- 8 <>
- 8 192.168.3.19
- 8 <>
- ...
- 595 peter@sample.net
- 8 10.0.0.1
- 8 <>
- 7 192.168.3.3
- 7 <>
- ...
- 547 paul@example.us
- 8 192.168.3.19
- 8 <>
- 7 10.0.0.1
- 7 <>
- ...
- ...
-
- <b>Running within Logwatch</b>
- <b>Note:</b> Logwatch versions prior to 7.3.6, unless configured otherwise,
- required the <b>--print</b> option to print to STDOUT instead of sending
- reports via email. Since version 7.3.6, STDOUT is the default output
- destination, and the <b>--print</b> option has been replaced by <b>--output std-</b>
- <b>out</b>. Check your configuration to determine where report output will be
- directed, and add the appropriate option to the commands below.
-
- To print a summary report for today's Amavis log data:
-
- <b>logwatch --service amavis --range today --detail 1</b>
-
- To print a report for today's Amavis log data, with one level
- of detail in the <b>Detailed</b> section:
-
- <b>logwatch --service amavis --range today --detail 5</b>
-
- To print a report for yesterday, with two levels of detail in the
- <b>Detailed</b> section:
-
- <b>logwatch --service amavis --range yesterday --detail 6</b>
-
- To print a report from Dec 12th through Dec 14th, with four levels of
- detail in the <b>Detailed</b> section:
-
- <b>logwatch --service amavis --range \</b>
- <b>'between 12/12 and 12/14' --detail 8</b>
-
- To print a report for today, with all levels of detail:
-
- <b>logwatch --service amavis --range today --detail 10</b>
-
- Same as above, but leaves long lines uncropped:
-
- <b>logwatch --service amavis --range today --detail 11</b>
-
- <b>Amavis Log Level</b>
- Amavis provides additional log information when the variable <b>$log_level</b>
- is increased above the default 0 value. This information is used by
- the <b>amavis-logwatch</b> utility to provide additional reports, not avail-
- able with the default <b>$log_level</b>=0 value. A <b>$log_level</b> of 2 is sug-
- gested.
-
- If you prefer not to increase the noise level in your main mail or
- Amavis logs, you can configure syslog to log Amavis' output to multiple
- log files, where basic log entries are routed to your main mail log(s)
- and more detailed entries routed to an Amavis-specific log file used to
- feed the <b>amavis-logwatch</b> utility.
-
- A convenient way to accomplish this is to change the Amavis configura-
- tion variables in <b>amavisd.conf</b> as shown below:
-
- amavisd.conf:
- $log_level = 2;
- $syslog_facility = 'local5';
- $syslog_priority = 'debug';
-
-
- This increases <b>$log_level</b> to 2, and sends Amavis' log entries to an
- alternate syslog facility (eg. <b>local5</b>, user), which can then be routed
- to one or more log files, including your main mail log file:
-
- syslog.conf:
- #mail.info -/var/log/maillog
- mail.info;local5.notice -/var/log/maillog
-
- local5.info -/var/log/amavisd-info.log
-
-
- <b>Amavis</b>' typical <b>$log_level</b> 0 messages will be directed to both your
- maillog and to the <b>amavisd-info.log</b> file, but higher <b>$log_level</b> mes-
- sages will only be routed to the <b>amavisd-info.log</b> file. For additional
- information on Amavis' logging, search the file <b>RELEASE_NOTES</b> in the
- Amavis distribution for:
-
- "syslog priorities are now dynamically derived"
-
-
-<b>ENVIRONMENT</b>
- The <b>amavis-logwatch</b> program uses the following (automatically set)
- environment variables when running under Logwatch:
-
- <b>LOGWATCH_DETAIL_LEVEL</b>
- This is the detail level specified with the Logwatch command
- line argument <b>--detail</b> or the <b>Detail</b> setting in the ...conf/ser-
- vices/amavis.conf configuration file.
-
- <b>LOGWATCH_DEBUG</b>
- This is the debug level specified with the Logwatch command line
- argument <b>--debug</b>.
-
- <b>amavis_</b><i>xxx</i>
- The Logwatch program passes all settings <b>amavis_</b><i>xxx</i> in the con-
- figuration file ...conf/services/amavis.conf to the <b>amavis</b> fil-
- ter (which is actually named .../scripts/services/amavis) via
- environment variable.
-
-<b>FILES</b>
- <b>Standalone mode</b>
- /usr/local/bin/amavis-logwatch
- The <b>amavis-logwatch</b> program
-
- /usr/local/etc/amavis-logwatch.conf
- The <b>amavis-logwatch</b> configuration file in standalone mode
-
- <b>Logwatch mode</b>
- /etc/logwatch/scripts/services/amavis
- The Logwatch <b>amavis</b> filter
-
- /etc/logwatch/conf/services/amavis.conf
- The Logwatch <b>amavis</b> filter configuration file
-
-<b>SEE ALSO</b>
- logwatch(8), system log analyzer and reporter
-
-<b>README FILES</b>
- README, an overview of <b>amavis-logwatch</b>
- Changes, the version change list history
- Bugs, a list of the current bugs or other inadequacies
- Makefile, the rudimentary installer
- LICENSE, the usage and redistribution licensing terms
-
-<b>LICENSE</b>
- Covered under the included MIT/X-Consortium License:
- http://www.opensource.org/licenses/mit-license.php
-
-
-<b>AUTHOR(S)</b>
- Mike Cappella
-
- The original <b>amavis</b> Logwatch filter was written by Jim O'Halloran, and
- has had many contributors over the years. They are entirely not
- responsible for any errors, problems or failures since the current
- author's hands have touched the source code.
-
-
-
- AMAVIS-LOGWATCH(1)
-</pre> </body> </html>
projects / amavis-logwatch.git / commitdiff