access - ACLs

This plugin applies Access Control Lists during the connect, helo, mail, and rcpt phases of the SMTP conversation. It has a split personality, supporting two somewhat different modes, any -vs- precise.


The any check is premised on blocking a domain name no matter where in the SMTP conversation it appears. That’s possible using several regex lists in the precise checks, but it’s also much slower.

With any, just drop the offending domain name into the file and it gets blocked for the rDNS hostname, the HELO hostname, the MAIL FROM domain name, and the RCPT TO domain name.

The any blacklist matches only on the Organizational Domain name (see NOTES below). Entries placed in the file are automatically reduced to the OD. Examples:

       ENTRY                  O.D.  ->       ->

In case the O.D. match is too broad, whitelist entries are placed in the same file with a ! prefix. Whitelist entries can be email addresses (for the MAIL FROM and RCPT TO tests) or hostnames for the rDNS and HELO hostnames. To block anything from but not

To block everything (supposedly) from, except messages from that one person you know that still uses it:

ANY results

When a whitelisted email or domain matches, a pass result will be saved with the hook name (ex: connect:any). When a blacklisted email or domain matches, a fail result of the same syntax is stored. If neither match, a msg result is saved (ex: unlisted(connect:any)).

ANY data

In addition to checking for a domain in the envelope, ANY can also check in the message headers as well. Settings ‘data=true’ in the [checks] section of config/access.ini enables this. At present this only checks the From header.


The precise ACLs share a common file format with each phase having a set of 4 files (whitelist, whitelist_regex, blacklist, and blacklist_regex) which are simple lists.

The ACLs for each phase apply their tests in the order listed. The whitelist is primarily to counter blacklist entries that match too much, so the the flow of control is: if whitelisted, stop processing. Then apply the blacklist.

Entries in ACL files are one per line.

Regex entries are anchored, meaning ‘^’ + regex + ‘$’ are added automatically. To bypass that, use a ‘.*’ at the start or the end of the regex. This should help avoid overly permissive rules.


To enable the access plugin, add an entry (access) to config/plugins. Then add entries to the config files for the addresses or patterns to block.


When upgrading from the rdns_access, mail_from.access, and rcpt_to.access plugins, be sure to remove the plugins from config/plugins, upon pain of wasted CPU cycles.

There is no need to modify your black/white lists in any way.

If you just want the new plugin to work exactly like the old trio it replaces, add this section to config/access.ini:


Checking ACL results

To check access results from other plugins, use the standard results methods.

var ar = connection.results.get('access');
if (ar.pass.length > 2) {
    // they passed the connection and helo checks
var ar = connection.transaction.results.get('access');
if (ar.pass.length > 2) {
    // they passed the mail and rcpt checks

To determine which file(s) had matching entries, inspect the contents of the pass/fail elements in the result object.

Config Files


Each check can be enabled or disabled in the [check] section of access.ini:

any=true    (see below)

A custom deny message can be configured for each SMTP phase:

conn=You are not allowed to connect
helo=That HELO is not allowed to connect
mail=That sender cannot send mail here
rcpt=That recipient is not allowed



The connect ACLs are evaluated against the IP address and the rDNS hostname (if any) of the remote.

  • connect.rdns_access.whitelist (pass)
  • connect.rdns_access.whitelist_regex (pass)
  • connect.rdns_access.blacklist (block)
  • connect.rdns_access.blacklist_regex (block)


  • mail_from.access.whitelist (pass)
  • mail_from.access.whitelist_regex (pass)
  • mail_from.access.blacklist (block)
  • mail_from.access.blacklist_regex (block)


  • rcpt_to.access.whitelist (pass)
  • rcpt_to.access.whitelist_regex (pass)
  • rcpt_to.access.blacklist (block)
  • rcpt_to.access.blacklist_regex (block)


ANY performance

I did some performance testing of indexOf -vs- precompiled regex. In a list of 3 items, where the matches were at the front of the list, regex matches are 2x as slow. When the list grows to 30 entries, the regex matches are 3x times as slow. When the matches are moved to the end of the 30 member list, the regex searches are over 100x slower than indexOf.

Based on this observation, reducing the domain name and doing an indexOf search of an (even much longer) blacklist is much faster than adding lists of .* entries to the *_regex files.

Organizational Domain

The OD is a term that describes the highest level portion of domain name that is under the control of a private organization. I’ll explain, but first, lets clarify a few terms:


Top Level Domains. Domain labels at the apex of a domain name.


Public Suffix

The portion of a domain name that is operated by a registry. These are often synonymous with TLDs but frequently also include second and third level domains as well:


The Organizational Domain is the next level higher than the Public Suffix. So if a hostname is, and com is the Public Suffix, the OD is If the hostname is, the PS is and the OD is