Monitoring amavis

This article describes how to monitor amavis for fault and performance.

Monitoring Basics

If you operate an application, you have to monitor it. You want to be the first one to know when things go wrong. You also want to know how well your application performs. That is why you use a monitoring system to observe your application. This also applies to amavis.

The amavis management part tells you a lot of information about the messages and their fate. A good monitoring system will tell you if you are in trouble for example because some daemons on the mail server are dead, your deferred queue is filling up or a new wave of spam or virus mails is rushing in.

In this documentation I want to describe how to set up fault and performance monitoring for amavis.

The SNMP Subagent of amavis

The Internet standard for the transport of monitoring information is the Simple Network Monitoring Protocol aka SNMP. All good operation systems and applications offer an SNMP interface to gather the relevant information. Of course, this also applies for amavis. It comes with its own piece of monitoring software that gathers the information and integrates into the SNMP agent of the operating system.

In the default installation the subagent gets its data out of the amavis database that resides in /var/amavis/db. There also exists a version of the software that uses the zmq interface of amavis.

The subagent software of amavis connects to the AgentX interface of the system SNMP agent. The installation of the main system SNMP agent is covered in the SNMP INSTALL file. Please refer to that documentation to install the main agent.

 +--------+       +-----------------------+          +-------------------+
 |        |   ?   |                       |   SNMP   |                   |
 | amavis | <---> | amavisd-snmp-subagent | <------> | Monitoring System |
 |        |       | snmpd                 |          |                   |
 +--------+       +-----------------------+          +-------------------+

You need to tell the SNMP snmpd daemon to listen to amavis` AgentX client. Add the following options to /etc/snmpd/snmpd.conf:

agentXSocket tcp:localhost:705,tcp6:[::1]:705
master agentx

Amavis SNMP client is called amavisd-snmp-subagent. Usually it has been installed to /usr/sbin/. An init file or systemd unit should also be deployed with the operation system package manager. So after starting the system SNMP agent, you can start the subagent. It registers itself at the master agent and the master agent will forward requests for information provided by the subagent.

The SNMP Management Side

To check if the Master / Subagent setup works you can request management information from the system. Use the snmpwalk command to check if your SNMP service is able to provide system information:

snmpwalk -v3 <v3 options> 192.0.2.25 system        (1)
1 This command sequence queries the SNMP service listening on 192.0.2.25.
SNMPv3 Authentication

For a good introduction on SNMPv3 and how it authenticates users see SNMPv3.

This request will display all entries of the system table of the server like system name, contact and location. Please use SNMPv3 for security reasons and do not use SNMPv1 of v2c any more. The old versions are deprecated.

Now you can request amavis management information from your server.

snmpwalk -v3 <v3 options> 192.0.2.25 enterprises.15312

The mailserver should reply with a lot of lines that starts with

SNMPv2-SMI::enterprises.15312.2.1.1.1.1.0 = STRING: "amavisd-new-2.11.0 (20160426)"

The management server displays the OIDs of the management information as plain numbers since it does not know what they stand for. If you want to replace the OIDs with human readable output you need to deploy a MIB. A MIB maps OIDs to Terms. Once snmpd has been equipped with a suitable MIB it will print out human readable outout.

amavis has its own MIB. The package installed usually places the MIB into the documentation directory /usr/share/doc/amavisd-new. Please look for a file called AMAVIS-MIB.txt. If it has been packed unpack it until you have a plaintext file.

Copy this file to your monitoring server and place it into the MIB directory. This could be /usr/share/snmp/mibs or, on Debian, /usr/share/mibs. There’s no need to restart snmpd. The mapping will be used immediately.

If you run the following command OIDs will not be displayed numerically anymore, but as human readable interpretation.

snmpwalk -v3 <v3 options> -m+ALL 192.0.2.25 enterprises.15312    (1)
1 The enterprises.15312.2.1.1.1.1.0 from above now is AMAVIS-MIB::sysDescr.0.

Now that snmpd is able to provide you with monitoring data from amavis you can can start using them in your monitoring system.

Fault Monitoring

Besides checking if there are sufficent amavis processes (prTable of the operating system agent) the amavis subagent gives you information about log entries. Your monitoring system could watch the logEntriesEmerg counter and fire an alert if the counter rises.

If you use Postfix amavis' subagent will also tell you about Postfix' active and deferred queues. You monitoring system should have an eye on the mtaQueueEntriesActive.0 and mtaQueueEntriesDeferred.0 and trigger an alert if there are too many mails in these queues.

Please mail me if you think other management information should additional be monitored and indicate a fault of the amavis daemon.

Performance Monitoring

Every organisation has different requirements for performance monitoring. In this section I want to give some basic hints, what information you can derive from the amavis subagent.

The most prominent information is inMsgs. This is the number of messages beeing processed by amavis. To know the scan verdict check the OIDs that begin with inMsgsStatus. A monitoring system will show how many mails are accepted, bounced, discarded, rejected, or somehow other not passed on to the user.

amavis also does bookkeeping about the classification of the messages. The OIDs that start with content tell you about clean messages or somehow non-clean messages. Most interesting are, of course, spam, virus, banned, or unchecked mail.

The same logic applies for outbound messages. Check the OIDs in the outMsgs section of the management information.

A very interesting part of the information if the timeElapsed section. This part tells you about the time amavis spent in various parts of the message processing. All values are in units of 0.01 seconds. The timeElapsedTotal tells you about the total time amavis used to process messages.

In a typical setup most of the time will be used processing virus and spam checks. In a monitoring system it is interesting to watch the various parts working on the mails. Of course the monitoring system would trigger an alert if it one part suddenly consumes more time that in the average in the past.

Michael Schwartzkopff, 06 May 2019