Bounce Processor Configuration

• Table of Contents
• Overview
• Main Configuration file
  • File Format
  • Bounce-Configuration-Object
  • Default Settings
  • Configuration Precedence
  • Example Configuration
  • Default Configuration
• bounce.concurrency
• bounce.max_gap_days
• bounce.queue_size.soft and bounce.queue_size.hard
• bounce.queue_type
• opt.treat_qsbf_bounces_as_local_server_names and opt.treat_all_qsbf_bounces_as_local

Overview

This page describes the bounce processor’s configuration files. See the Bounce Processor Concepts page for an overview of how GreenArrow’s bounce processor works, and definitions of some of the terms used on this page.

Main Configuration file

Most of the bounce processor’s configuration is contained within the following file:

/var/hvmail/control/bounce_processor.conf

To validate the syntax of this file, run:

/var/hvmail/bin/hvmail_bounce_processor --check-config

Updates to this file are automatically re-read by the bounce processor within one minute.

If there are errors in this file, bounces will not be processed and the errors will be logged to /var/hvmail/log/bounce-processor/current. Bounces will accumulate and potentially slow GreenArrow down until the error is corrected.

File Format

This file is a JSON document where the root is an object. The following keys may be defined:

Bounce-Configuration-Object

Each Bounce-Configuration-Object can have the following optional keys:

Default Settings

GreenArrow’s default settings are as follows.

Default bounce code mappings:

Configuration Precedence

The bounce processor goes through the following list when processing GreenArrow Studio bounces. The first matching entry is used:

1. The id of the Mailing List is searched for in studio_by_mailing_list_id
2. The configuration defined in the studio object, if present
3. The configuration defined in the default object, if present
4. GreenArrow’s default settings

The bounce processor goes through the following list when processing bounces from non-GreenArrow Studio sources. The first matching entry is used:

1. The ListID is searched for in by_listid
2. If the ListID has a prefix, a configuration in by_listid_prefix is searched for
3. The configuration defined in the default object, if present
4. GreenArrow’s default settings

Example Configuration

{
   "default" : {
      "hard_allow_missing" : 1,
      "hard_req_count" : 2,
      "hard_req_days" : 0
   },
   "by_listid" : {
      "bb" : {
         "soft_req_count" : 2,
         "soft_req_days" : 2,
         "soft_allow_missing" : 1
      }
   },
   "studio_by_mailing_list_id" : {
      "66" : {
         "hard_req_count" : 1,
         "hard_req_days" : 0,
         "hard_allow_missing" : 0,
         "bounce_codes" : {
            "10" : "hard",
            "20" : "soft",
            "21" : "soft",
            "22" : "soft",
            "23" : "other",
            "29" : "soft",
            "90" : "hard"
          }
      }
   }
}

Default Configuration

The configuration file is blank by the default. This implies the following settings:

{
   "default" : {
      "hard_req_count" : 1,
      "hard_req_days" : 0,
      "hard_allow_missing" : 0,
      "soft_req_count" : 2,
      "soft_req_days" : 10,
      "soft_allow_missing" : 0,
      "store_bounce_details_length" : 1024,
      "bounce_codes" : {
         "10" : "hard",
         "20" : "soft",
         "21" : "soft",
         "22" : "soft",
         "23" : "other",
         "29" : "soft",
         "90" : "hard"
      }
   }
}

bounce.concurrency

This file controls the number of concurrent processes to use for bounce processing. Valid values are 1-100.

Concurrent bounce processing was introduced in GreenArrow Engine 4.1.153-0, which was released in January 2017. This means that until this release, this setting’s effective value was 1, which was sufficient in the vast majority of installations. Having a single bounce processing process only represented a bottleneck on some installations which had exceptionally high bounce rates.

The default value is 2. To restore the default, run:

echo 2 > /var/hvmail/control/bounce.concurrency

bounce.max_gap_days

If no emails are sent to an email/ListID combination in this many days, then the repeat bounce processing system will forget about repeat bounces for this email/ListID combination. This means that you can’t have a gap in sending more than this many days.

The default value 75. To restore the default, run:

echo 75 > /var/hvmail/control/bounce.max_gap_days

bounce.queue_size.soft and bounce.queue_size.hard

These files are used to apply back pressure to the rest of the MTA if more than the configured number of bounces or FBL messages accumulate in the bounce processor’s queue. This back pressure slows down the MTA and can impact both GreenArrow’s delivery and message acceptance performance.

Back pressure is applied in the form of a queuing delay. This is done to prevent larger issues, like memory exhaustion or never catching up on bounce processing from occurring.

The soft limit is reached when the number of messages in the bounce processor’s queue exceeds the value set in the /var/hvmail/control/bounce.queue_size.soft configuration file. When this happens, a small amount of latency is added to the process of queuing new bounces.

The hard limit is reached when the number of messages in the bounce processor’s queue exceeds the value set in the /var/hvmail/control/bounce.queue_size.hard configuration file. When this happens, the queuing of new bounces is delayed until after the number of messages in the bounce processor’s queue falls below the hard limit.

The default soft limit is 3000 and the default hard limit is 5000. Commas should not be used in these values. To restore the defaults, run:

echo 3000 > /var/hvmail/control/bounce.queue_size.soft
echo 5000 > /var/hvmail/control/bounce.queue_size.hard

bounce.queue_type

This file controls the type of bounce processor queue that’s used. Valid values are redis and maildir.

This file only controls the handling of bounce messages. Spam complaints always get delivered to a maildir.

redis is recommended in most situations because it offers better performance by storing bounces in a RAM-based Redis queue instead of a disk-based maildir.

The default value is redis. To restore the default, run:

echo redis > /var/hvmail/control/bounce.queue_type

After changing this value, you’ll need to restart the bounce processor to apply changes. To restart the bounce processor, run:

svc -tu /service/hvmail-bounce-processor

After restarting the bounce processor, verify that it stays up:

hvmail_init status | grep hvmail-bounce-processor

opt.treat_qsbf_bounces_as_local_server_names and opt.treat_all_qsbf_bounces_as_local

GreenArrow has internal bounce codes for messages that aren’t delivered because they were either dumped from the queue or their queue lifetime expired while delivery was paused. These internal bounce codes normally only occur locally, so GreenArrow’s default configuration only assigns special meanings to these internal bounce codes when the bounces are synchronous.

If you have multiple GreenArrow servers and they relay mail to each other, then you may want to overwrite this default behavior, and allow the internal GreenArrow bounce codes to be processed for asynchronous bounces. This is where the opt.treat_qsbf_bounces_as_local_server_names and opt.treat_all_qsbf_bounces_as_local files come in. Neither of these files exist by default.

To configure GreenArrow to process these internal bounce codes if they originate from specific server(s), add each their Server Names, one per line to /var/hvmail/control/opt.treat_qsbf_bounces_as_local_server_names.

echo mailer.example.com >> /var/hvmail/control/opt.treat_qsbf_bounces_as_local_server_names

To configure GreenArrow to process these internal bounce codes regardless of where they originate, set /var/hvmail/control/opt.treat_all_qsbf_bounces_as_local to a TRUE value, such as 1:

echo 1 > /var/hvmail/control/opt.treat_all_qsbf_bounces_as_local

Updates to the above files are automatically read by the bounce processor without any service restarts.