Delivery Attempt Log (Deprecated)

Table of Contents
Deprecation Notice
Overview
Alternatives
Configuration
Format
Log Rotation

Deprecation Notice

The Delivery Attempt Log has been deprecated as of GreenArrow v4.285.0. Please see the event_delivery_logfile and event_delivery_pipe_command configuration directives instead.

Overview

GreenArrow can be configured to log delivery attempts to a logfile. There are a number of configuration options available, including whether to enable this logging and what format to log the data in.

Alternatives

There are two alternative ways to monitor delivery attempts:

Use hvmail_report to request data for a particular time period.
Use the Event Notification System’s delivery_attempt event type.

Configuration

Delivery attempt logging is disabled by default. To enable it, and optionally adjust other settings, edit the /var/hvmail/control/delivery_attempt_logfile.json configuration file.

This file is written in JSON. You can verify that there are no syntax errors in your edits by running:

hvmail_logwriter --check-config-file

The configuration file is automatically re-read every few seconds, so no services need to be restarted to apply changes.

Here are the default settings:

{
  "enabled": false,
  "filename": "",
  "filename_append_date": false,
  "pipe_command": "",
  "format": "json",
  "include_status": {
    "success":         true,
    "deferral":        true,
    "failure":         true,
    "failure_toolong": true,
    "connmaxout":      false
  },
  "include_first_attempt_regardless_of_status": true,
  "include_local_channel": true
}

Here’s the meaning of each setting:

enabled boolean	If `true`, then delivery attempt logging is enabled.
filename string	The filename to write to. Either this setting or `pipe_command` is required if `enabled` is `true`. The file will be opened for appending by the `root` user.
filename_append_date boolean	If `true`, then a period and the date in `YYYY-MM-DD` format will be appended to the filename. For example `/tmp/file` becomes `/tmp/file.2017-03-21`. When the first delivery attempt is logged for the next day, it will be written to `/tmp/file.2017-03-22`.
pipe_command string	An optional command to which to open and write the log. Either this setting or `filename` is required if `enabled` is `true`. This command is executed and closed for each batch (approximately every 3 seconds). The program must exit successfuly (return status 0) or else it will be retried. If the program exits non-success (a return status other than 0, or if it is killed by a signal), there may be some duplicate delivery log lines and writing to `filename` will be prevented or delayed. This program is run by the `root` user. The log data is written to the program’s STDIN. The program should read all of STDIN and encounter an EOF before exiting.
format string	The format of logfile data to write. Options are: `json` - use JSON formatting with one JSON object per line. This is the default. `processed` - use the same format as `hvmail_report --processed-logfile` `human` - use the same format as `hvmail_report --processed-logfile --human`
include_status object	A JSON object containing a series of boolean keys that specify which types of delivery attempts should be logged. With the default settings, each message will either have a single `success`, `failure` or `failure_toolong` log entry.
include_first_attempt_regardless_of_status boolean	If `true` then the first delivery attempt for a message (where `is_retry` is `0`) should always have a log entry created regardless of the status. This is useful because the first delivery informs that a new message has been created.
include_local_channel boolean	If `true` then delivery attempts to local domain names (incoming email domains) will have events created. If `false`, they will be excluded. Most of the deliveries to local domains are bounce messages received through SMTP and internally created bounce messages.

Format

Here’s an example log entry that uses json formatting:

{"timestamp":1641480948.07533,"channel":"remote","status":"success","is_retry":0,"msguid":"1641480947.54314359","recipient":"[email protected]","sender":"[email protected]@[]","mtaid":"2","sendid":"default220106","listid":"t1","injected_time":1641480947,"message":"173.194.175.27 accepted message./Remote host said: 250 2.0.0 OK  1641480948 bi10si877913qkb.210 - gsmtp/","outmtaid":"2","outmtaid_ip":"127.0.0.1","outmtaid_hostname":"localhost","sendsliceid":"","throttleid":null,"clicktrackingid":"","mx_hostname":"aspmx.l.google.com","mx_ip":"173.194.175.27","from_address":"[email protected]","headers":{"Subject":["This is a test of the subject"]}}

Here’s an example log entry that uses human formatting:

timestamp=<1641481093.03894> channel=<remote> status=<success> is_retry=<0> msguid=<1641481092.90011942> recipient=<[email protected]> sender=<[email protected]@[]> MTAid=<2> SendID=<default220106> ListID=<t1> injected_time=<1641481092> message=<173.194.175.27 accepted message./Remote host said: 250 2.0.0 OK  1641481093 x16si812070qko.519 - gsmtp/> outmtaid=<2> SendSliceID=<> throttleid=<> clicktrackingid=<> mx_hostname=<aspmx.l.google.com> mx_ip=<173.194.175.27> from_address=<[email protected]> headers=<{"Subject":["This is a test of the subject"]}>

The following keys are populated in the json format, but not the processed or human format:

outmtaid_ip - the IP address GreenArrow used while attempting to deliver the message.
outmtaid_hostname - the hostname of the IP address that GreenArrow used while attempting to deliver the message.

All other keys in the above example are also in the Delivery Event Processed Logfile Format and described in its documentation.

Log Rotation

GreenArrow does not rotate delivery attempt logs. If you enable delivery attempt logging, then you must set up your own log file rotation system in order to avoid running out of disk space.

The logfile is re-opened for appending every few seconds, so no services need to be restarted for the logfile to be re-created after being moved or deleted.