Rejecting and accepting connections by IP address

netblock<tab>deny

netblock is an IP address, such as 192.68.0.2. <tab> is the ASCII tab character. There MUST be exactly one tab character after the IP address and the word "deny".

You can also block connections from an entire network C block:

192.68.0<tab>deny

This blocks connections from IP addresses 192.68.0.0 through 192.68.0.255. Blocking connections from an entire B or A network block works the same way.

Use the word "allow" instead of "deny" to explicitly allow connections from that IP address or netblock. For example:

192.68.0<tab>deny
192.68.0.10<tab>allow

This blocks all connections from 192.68.0.0 to 192.68.0.255 except for 192.68.0.10. These two lines can occur in any order. couriertcpd always uses the line with the most specific IP address.

If the IP address of the connection is not found in the access file the connection is accepted by default. The following line causes unlisted connections to be rejected:

*<tab>deny

IPv6 addresses

The access file can also specify IPv6 addresses, if IPv6 support is available. The existing IPv4 address format is used for IPv6-mapped IPv4 addresses, and no changes are required. For all other IPv6 addresses use the following format:

:hhhh:hhhh:hhhh:hhhh:hhhh:hhhh:hhhh:hhhh<tab>action

The IPv6 address must begin with :. The initial : character is not really a part of the IPv6 address, it is only used to designate this record as an IPv6 address, allowing an access file to contain a mixture of IPv4 and IPv6 addresses. The IPv6 address follows the initial : character, and it must be spelled out using zero-padded lowercase hexadecimal digits. For example:

:0000:0000:0000:0000:0000:f643:00a2:9354<tab>deny

Netblocks must be specified using even-word boundaries only:

:3ffe<tab>deny

This will deny entire 3ffe::/16 (6bone network, which is phased out).

:2002:c0a8<tab>deny

This will deny 2002:c0a8::/32 (6to4 addresses derived from private address space).

Setting environment variables

192.68.0<tab>allow,RELAYCLIENT
192.68.0.10<tab>allow,RELAYCLIENT,SIZELIMIT=1000000

This sets RELAYCLIENT environment variable for connections from the 192.68.0 block. In addition to that, the SIZELIMIT environment variable is set to 1000000 if the connection comes from the IP address 192.68.0.10.

Note that RELAYCLIENT must be explicitly specified for the IP address 192.68.0.10. The first line is NOT used for connections from this IP address. couriertcpd only reads one entry from the access file, the entry for the most specific IP address.

192.68.0.10<tab>allow,MAXCPERIP=100

couriertcpd itself implements the MAXCPERIP environment variable setting in the access file, as an override to the -maxperip parameter, which specifies the maximum number of connections from the same IP address. If specified in the access file for an IP address, or an IP address range, the value given by MAXCPERIP overrides it.

DNS ACCESS LISTS

couriertcpd's default configuration does not automatically reject connections from banned IP address unless the -drop option is present. Instead, couriertcpd sets an environment variable if the connecting address has a hit in the DNS access list. The Courier mail server rejects all mail if the connection's environment has the environment variable BLOCK set to a non-empty string, and it just so happens that -block and -allow set the BLOCK environment variable by default.

-allow=dnswl.example.com -block=dnsbl.example.com

-allow and -block's parameter gives the DNS zone where the access list query gets performed. In this example, couriertcpd makes a DNS query for “d.c.b.a.dnswl.example.com”, then, if necessary, for “d.c.b.a.dnsbl.example.com”, for a connection from the IPv4 address a.b.c.d.

An optional “=display_zone” follows the DNS zone. This sets the contents of BLOCK_ZONE DNS access list variable (see below), which defaults to the DNS zone name. This is only useful with -allow, since -block rejects the message, so nothing gets set anyway.

For IPv6 addresses, the DNS query consists of individual hexadecimal nybbles (in reverse order, like the IPv4 query).

If the DNS query succeeds (more details below), -allow sets the environment variable to an empty string, and -block sets the environment variable from the TXT record in the DNS response, if one was requested (see below), or to a default message for regular DNS queries for A records. It should be possible to use couriertcpd with DNS access lists that use either A or TXT records.

The DNS zone parameter to -allow and -block has up to three additional components, which must be given in the following order, if more than one optional component gets specified:

-allow=dnswl.example.com,BLOCK2

The environment variable that gets set by the DNS access list query can be changed from the default of BLOCK to something else, BLOCK2 in this example. The Courier mail server pays attention only to BLOCK, this is for the benefit of local or custom hacks, which want to leverage couriertcpd's DNS access list lookup facilities, but want it for other purposes.

-block=dnsbl.example.com/127.0.0.2

couriertcpd's DNS access list lookup normally ignores the contents of the actual A record in the DNS access list, however some DNS access lists may use different A record to indicate different kinds of records. Given an explicit IP address to couriertcpd results in the environment variable getting set only if the lookup returned the matching A record. An A record must exist in the DNS access list, in addition to any TXT record. If an explicit IP address is not given, any A or TXT record sets -allow and -block's environment variable.

-block=dnsbl.example.com,BLOCK,Go away

The last component specifies a custom message that overrides the default rejection message. Note that this is a single parameter to couriertcpd, so the parameter must be quoted if it contains any spaces or special shell metacharacters. A message that's specified as “*” results in a TXT query to the DNS access list instead of the regular A query. This is for DNS access lists that provide TXT records, that gets copied into the BLOCK variable (or the custom variable). The “*” must also be quoted, since it's also a shell metacharacter, and it cannot be used together with an explicit A address query, described above.

The custom message parameter gets specified for the -block, option. -allow also allows takes this parameter, but it has a different meaning. If its set, even if it's an empty string, couriertcpd looks for TXT records in the DNS access list that's used as a whitelist, in addition to the A records (using the “any” query):

-allow=dnswl.example.com,BLOCK,

Without this parameter couriertcpd queries for A records only.

Finally, a literal IP address, if given, must always follow the variable name:

-block=dnsbl.example.com,BLOCK/127.0.0.2,Go away

-block normally searches the DNS access list for either A or TXT records using the “any” DNS query. Sometimes this can cause problems, or not work at all, with older DNS servers. Specifying a custom message results in -block executing an ordinary A DNS query. -allow always uses an A query.

MULTIPLE DNS LISTS

couriertcpd processes all -block and -allow options in list order. If each option's environment variable (BLOCK or something else) is already set, couriertcpd skips the DNS access list lookup. Therefore, when multiple options use the same environment variable, the first DNS access list it exists in will set the environment variable, and the remaining ones get ignored, but any remaining -blocks and -allows for different environment variables still get processed.

It follows that, in general, -allow options should always be listed first, before any -blocks; but it's also possible to implement a complicated policy with some -allows, then some -blocks, then more -allows and -blocks.

ADDITIONAL DNS ACCESS LIST VARIABLES

BLOCK_IP

BLOCK_TXT

BLOCK_ZONE

-block and -allow options that specify a custom environment variable name follow the same naming convention, of appending “_IP”, “_TXT”, and “_ZONE” suffix to the name of the custom environment variable.

USING DNS WHITELISTS WITH SPF