postfix-logwatch and amavis-logwatch log reporters FAQ

My reports have Unmatched entries. How can I suppress them?

Without code modifications, unmatched entries are always output. Consider them as either annoying reminders or friendly encouragement to send me samples of the entries so that I can continue to improve the utilities for the benefit of all. Sanitize email addresses, domains or IPs if you feel it necessary (I will keep your information confidential), but please do not change anything else in the log lines. Ideally, send a gzipped text file containing the unmatched log lines.

Email: lists-logreporters (at) cappella (dot) us.

Why does the detailed section start at detail level 5?

Both amavis-logwatch and postfix-logwatch started as improvements to the existing amavis and postfix service scripts in logwatch (since then, they have both been entirely rewritten, and enhanced substantially). Logwatch has three mnemonics (low, medium, and high) assigned to the numerically equivalent detail levels of 0, 5 and 10, respectively. Filters in logwatch are expected to produce only summary or essential information at the default (low = 0) detail level, additional information at medium (5) detail, and maximum information when detail is high (10). To conform to the logwatch standards, only summary information is produced by amavis-logwatch and postfix-logwatch at details less than 5. I chose to increase the granularity of information disclosed as the detail level is increased above level 5, and to conform to logwatch's maximum output when detail is 10 (or more). Of course, detail goes up to 11; report lines are not cropped to fit within the current report width.

What is the relationship between command line options and configuration file variables?

The configuration file variables are prefixed with $postfix_ for postfix-logwatch, and $amavis_ for amavis-logwatch. This is done for the benefit of logwatch, which passes variables to a service script via environment. In addition logwatch .conf variables are case insensitive; camel-case is used in the configuration files to enhance readability. For example, the amavis-logwatch configuration file variable $amavis_Line_Style is equivalent to the command line option --line_style. Internally, postfix-logwatch and amavis-logwatch strip the $postfix_ and $amavis_ prefixes, and lowercase the variables.

In standalone mode, the default configuration file is read first (if it exists), or any configuration file(s) specified via command line are read. Subsequent command line options override any earlier settings, in a left to right fashion.

How can I determine which section is controlled by which configuration variable/command line option?

Run postfix-logwatch (>= v1.36.12) with the --sect_vars option. Each section's title will include the limiter name at the end of the line. For example:

   27220   Reject relay denied ---------------------------------------------------- [ rejectrelay ] -

How do I disable a section that I consider noise?

The amount (levels) of data presented under each section in the detailed report is controlled by setting that section's level limiter. A section's level limiter can be set in the configuration file or by command line option. Setting a section's detail level to 0 prevents that section from being output in the detail report:

   $ amavis-logwatch --limit bayes=0 /var/log/amavisd.log

How do I turn a section into a top 10 list?

Set a section's level variable to "1.10" or "1:10:". For instance, to see a top 10 list of domains for postfix delivered messages, set the postfix-logwatch option --limit delivered=1.10 (or the configuration file variable $postfix_Delivered = 1.10).


   $ postfix-logwatch --limit delivered=1.10 /var/log/maillog
       1276   Delivered -------------------------------------------------------------------------------
        229      bcc.local

The 1 in 1.10 means only show level 1 details, the .10 means only show 10 level 1 items. But this form of level limiter is less useful, as only level 1 items may be limited. To limit any or all levels, use the l:n:t form of level limiting.

There are so many options! How can I quickly get a report for just one or two sections?

You can use the --nodetail and --nosummary options followed by the level variable(s) for the detail section(s) of choice. The --nodetail option internally sets the value of all level limiters to 0. For instance, if you only want a list of TLS server connections and SASL authenticated messages, you would execute:

   $ postfix-logwatch --nosummary --nodetail -l tlsserverconnect=1 -l saslauth=1 /var/log/maillog 
   ****** Detail **************************************************************************************

         42   TLS connections (server) ----------------------------------------------------------------
          9    unknown
         42   SASL authenticated messages -------------------------------------------------------------

How do I interpret a percentiles reports?

The percentile reports show what percentage of data falls below a certain value. It is easier to explain by way of example. Postfix logs a breakdown of the length of time taken for message delivery activities. This is reported in log entries as delays=a/b/c/d, where a, b, c, and d are defined as:

    a = time before queue manager, including message transmission
    b = time in queue manager
    c = connection setup including DNS, HELO and TLS;
    d = message transmission time.

Here is a sample percentiles table for postfix message delays ("a" is row 1, "b" is row 2, etc.):

   Delays Percentiles            0%       25%       50%       75%       90%       95%       98%      100%
1  Before qmgr                 0.00      0.02      0.03      0.19      0.69      1.14      4.10    611.00
2  In qmgr                     0.00      0.00      0.01      0.01      0.03      0.07      0.12     19.00
3  Connection setup            0.00      0.00      0.00      0.00      0.39      1.20      3.50     65.00
4  Transmission                0.00      0.00      0.83      4.40      8.08     12.00     22.00    104.00
5  Total                       0.01      0.04      1.90      5.10     10.80     20.00     41.68    612.00

Looking at row (1), the 90% column indicates that 90% of the samples, before qmgr activities took less than .69 seconds. And transmission time from row 4 took less than 10.80 seconds for 90% of the samples. The 100% column indicates the largest value found in the data, and the 0% column indicates the smallest.

You can specify the percentiles (columns) to display via command line (or configuration file variable). For some measurements, evenly spaced quadrilles (eg. 25%, 50%, 75%, 100%) may be sufficient; for others, favoring the high-end may prove more useful (eg. 0%, 25%, 50%, 90%, 95%, 98%, 100%).

My configuration file is setup for nightly reports. How can I override those settings for a one-shot report?

Add the appropriate command line option(s). Variables are set when they are read, and they are read first from the default configuration file (or any configuration file(s) specified via --config_file), and then from the command line (left to right). Command line options will override previously set variables. Later options override earlier ones.

It may be useful to specify low-detail values in the configuration file for nightly emailed reports, and override those values via command line option(s) for additional information as needed.

Can I have more than one configuration file?

Sure. The --config_file option allows specifying an alternate configuration file. This option can be used multiple times. Later settings override earlier ones.

I have multiple postfix instances. How do I get separate reports for each instance?

This depends on how you have configured your postfix instances. If you use separate log files, one for each instance, specify the appropriate log file on the command line. If you have specified a unique per-instance syslog_name in postfix -- see postconf(5) -- specify that name with the postfix-logwatch command line option --syslog_name (configuration variable $postfix_Syslog_Name). This will cause postfix-logwatch to select only postfix log lines that match that name. The default value for syslog_name is "postfix".

How can I tell postfix-logwatch to ignore certain postfix service lines?

Postfix log lines are generally identified by pairing the configured syslog name with the service name, as in "postfix/smtpd". There may be some services which are not yet handled by postfix-logwatch, and they result in Unmatched entries appearing in reports. The --ignore_service option (configuration file variable: $postfix_Ignore_Service) will cause postfix-logwatch to ignore specified log lines. The argument to --ignore_service is a regular expression pattern, which will cause postfix-logwatch to ignore any lines with the postfix service "postfix/pattern". See the man page or configuration file comments for more details.

What's the difference between the service scripts that come with logwatch and amavis-logwatch/postfix-logwatch?

The amavis-logwatch and postfix-logwatch utilities on this site will always have the latest code, containing new features and bug fixes.

Note: 2012-11-01: postfix-logwatch and amavis-logwatch now use the MIT/X11 license, and may be included into the logwatch project. Historic Note: 2008-05-24: due to licensing discrepancies, the logwatch project and I have agreed it is necessary to revert both of the amavis and postfix service scripts to very old versions. Logwatch will no longer be including postfix-logwatch and amavis-logwatch in their distribution. The postfix-logwatch and amavis-logwatch code falls under GPL2, whereas the logwatch project under the MIT/X11 license.

Users wanting current capabilities from within logwatch should download and install the latest stable or development release of postfix-logwatch and amavis-logwatch.

Can I reorder the sections in a report?

Not currently, without code modification. If there is sufficient call for this feature, I may make this configurable. To change the presentation order, find the add_sections() function calls in build_section_table(). Both the summary and detail sections are driven a Sections table, and sections are presented in the order added to the table with add_section. Reorder it as you desire, but take note of the special table groupings begin_section_group() and end_section_group(); these control row borders and separations.

How can I determine the effectiveness of my postfix header and body checks?

Postfix header_checks(5) and body_checks(5) allow "optional text..." to be logged when a rule is hit.

   REJECT optional text...

   Reject the entire message. Reply with optional text... when the
   optional text is specified, otherwise reply with a generic error

The postfix-logwatch utility will use this "optional text" to organize header and body reject sections by the rule hit, sorted as usual, with most frequently hit rules appearing first. With appropriate use of optional text, you can group or separate your header and body check hits as desired.

For example, with the (pcre) header check rules:

    /^Subject:.*verify your account information/i  REJECT Phishing 2
    /^Subject:.*your account is suspended/i        REJECT Phishing 4
    /^Subject:.*St0ck/i                            REJECT Pump and dump
    /^Subject:.*Symbol: [A-Z]{4}/                  REJECT Pump and dump

you can see in the report below that the Phishing 4 reject rule was hit 30 times, Phishing 2 was hit 5 times, and either of the two generic "Pump and dump" rules were hit at total of 17 times.

         56   Reject header ---------------------------------------------------------------------------
         30      5.7.1 Phishing 4
         17      5.7.1 Spam: Pump and dump
          5      5.7.1 Phishing 2
          2      5.7.1 Spam: Greeting card
          1      5.7.1 Spam: Real estate
          1      5.7.1 Spam: Enhancement

What is the meaning of "*Warning: Connection overload" or "*Warning: Possible connection overload"?

Note: this entry is essentially obsolete for version 1.38.01 of postfix-logwatch, which simply merges the limiter connectionlostoverload into connectionlostinbound.

These warnings are derived from the following postfix log line:

    postfix/smtpd[20403]: connect from unknown[unknown]

which are typically followed by:

    postfix/smtpd[20403]: lost connection after CONNECT from unknown[unknown]
    postfix/smtpd[20403]: disconnect from unknown[unknown]

These indicate that the kernel received an SMTP connection from some host, but the host disconnected before postfix's smtpd daemon was able to process the incoming connection. By the time postfix serviced the queued connection, the kernel had already removed the entry, so postfix was unable to provide the IP address, let alone perform the IP to name lookup; smtpd was only able to log that the connection occurred.

This sometimes occurs in reaction to a portscan or broken bots, or when postfix is overloaded, due to excessive header_checks / body_checks content filtering, or even too few smtpd processes to service the demand. One could reduce the number of header_checks and body_checks, and possibly set smtpd_timeout to 60 (seconds). The key is that existing clients are overloading the number of smtpd daemons. The postfix-logwatch section configuration variable is postfix_ConnectionLostOverload, and the command line option is --connectionlostoverload. If you consider this sub-section to be meaningless, set the level limiter value to 0 and the sub-section will be suppressed.

Newer versions of the logwatch postfix service script or the standalone postfix-logwatch show "Possible connection overload". Earlier versions output "Connection overload". The message was changed to indicate the possibility of an overload, and not be a final diagnosis.

Why is there no output from amavis-logwatch ?

One possibility is that your installation of amavis is configured such that log entries contain the full path to the amavisd program, so amavis-logwatch needs to be configured with the correct syslog name. This can be done via the command line option --syslog_name=/usr/bin/amavisd or by setting the configuration file variable $amavis_Syslog_Name, as in:

$amavis_Syslog_Name = "/usr/bin/amavisd".

Why is there no output from when running under logwatch ?

First, be sure to read the FAQ question above: Why is there no output from amavis-logwatch?

Second, if your amavis installation outputs its log entries into a log file other than the default maillog, you will need to create a log group configuration file for the logwatch amavis service script. Logwatch must be properly configured to know which log files to use for passing log lines to a service script. The mechanism that accomplishes this requires abiding by logwatch's naming rules, and there is an unfortunate name overloading which makes configuration a bit confusing. There are three related components that must be located and configured properly:

  1. the service script,
  2. the service script configuration file, and
  3. the log group file

When you install amavis-logwatch (or postfix-logwatch; I will only refer to amavis-logwatch henceforth), the service script amavis-logwatch is renamed and installed as /etc/logwatch/scripts/services/amavis. The service script configuration file amavis-logwatch.conf file is renamed amavis.conf, and installed as /etc/logwatch/conf/services/amavis.conf. The latter contains a LogFile variable, which is set to the default value of maillog:

    # Which logfile group...
    LogFile = maillog

Unfortunately, the variable name LogFile in the file above is a misnomer, as this variable actually determines a log group, not a log file name! The name LogFile is overloaded (i.e. it has two different meanings); the same variable name is used in another configuration file to specify the name of a log file. It is important to keep these concepts clear and distinct, so I will reiterate. The variable LogFile used within files under /etc/logwatch/conf/services specifies the name of a log group, but the same variable name use within files under /etc/logwatch/conf/logfiles specifies the name of a log file.

The value of the log group setting LogFile associates a configuration file: it is the value of LogFile appended with the .conf suffix. From the example above, the LogFile variable specifies that the log group maillog is to be used, and this refers to the log group configuration file maillog.conf (this file already exists in the logwatch installation directory).

If your system's amavis daemon logs its output to a file other than the default maillog, say amavisd.log, then you must:

  1. create and configure a log group file in /etc/logwatch/conf/logfiles, named for example, amavislog.conf, and
  2. set the value of LogFile in the service script /etc/logwatch/conf/services/amavis to refer to the group file created in (1) above.

Example, assuming amavis logs its output to /var/log/amavisd.log:


    LogFile = amavislog


    LogFile = 
    Archive = 

    LogFile = amavisd.log
    Archive = amavisd.log.*

The initial empty assignments of LogFile and Archive are required to clear out existing settings. The second set of LogFile and Archive variables define the name of the log file and its archives in the system log directory.

Do the reporters run on Mac OS X ?

I have confirmed that amavis-logwatch runs on OS X. The OS X log entries contain the full path to the amavisd program, so amavis-logwatch needs to be told amavisd's name.

See: Why is there no output from amavis-logwatch?

I have not confirmed postfix-logwatch on OS X, but suspect it should run as well, possibly requiring setting --syslog_name as well. Once I have some log entries, I will update this FAQ.

How do I disable the postfix report in logwatch ?

If you run postfix-logwatch or amavis-logwatch in standalone mode, you may want to configure logwatch to suppress postfix or amavis report output. Report sections in logwatch can be suppressed by disabling their service in the logwatch.conf file. The logwatch Service variable specifies the list of services for which logwatch should create reports. This variable is cummulative; setting the variable to empty clears the variable. The special service All means all available services. To remove a service, prefix the service with a dash. The following configuration file entries first clear the Service list, then sets it to All services, and then finally disables the postfix service.

    Service =
    Service = All
    Service = -postfix

You can add these lines to your system's logwatch.conf file, which would typically be located at /etc/logwatch/conf/logwatch.conf. The file may not yet exist, or it may reside in another location on your system. See the "HOWTO-Customize-LogWatch" file in the logwatch distribution for more information.

I have a suggestion, patch, or improvement - can I send them to you?

Sign up and post your request on the mailing list. Please be prepared to send any log lines in a gzip/bzip2 archive, so that mailers do not interfere with log lines.