couriertcpd

NAME

couriertcpd - the Courier mail server TCP server daemon

SYNOPSIS

DESCRIPTION

couriertcpd accepts incoming network connections, and runs program after establishing each network connection. The program's standard input and output are set to the network connection. list is a comma-separated list of TCP port numbers where incoming connections are created. program is the program to run. If program requires any arguments, they are specified on the command line, after program itself. Before running program, couriertcpd initializes several environment variables that describe the network connection. The environment inherited by program will be the environment inherited by couriertcpd, plus any additional environment variables initialized by couriertcpd. It is also possible to reject certain network connections. Several options are available to specify which network connections will be rejected.

OPTIONS

-access= filename -accesslocal -address= n.n.n.n -block= zone[=display_zone][,var[/n.n.n.n][,msg]] or -allow= zone[=display_zone][,var[/n.n.n.n[,]]] -denymsg= text -drop= var -group= group -listen= n -maxperc= n -maxperip= n -maxprocs= n -warn= n -nodnslookup -noidentlookup -pid= filename -restart -stderr=socket -stderr= logfile -stderrlogger= logprogram -stderrloggername=name -stop -user= user

MULTIPLE PORT LIST

The list argument can be a comma-separated list of multiple port numbers. couriertcpd will create network connections on any listed port. Each port number can be optionally specified as "address.port", for example: This instance accepts network connections to either port 25 or port 999, however connections on port 25 are created only on the IP address 127.0.0.1, the loopback interface. Whenever an IP address is not specified, network connections are accepted to any IP address (called "wildcarding"). On IPv6-capable systems, couriertcpd will attempt to create two incoming network connection ports, if an IP address is not specified. After creating the first port as an IPv6 wildcard port, couriertcpd will then attept to create an IPv4 wildcard port, with the same port number. Some BSD-derived systems must use separate IPv6 and IPv4 wildcard ports to create incoming network connections. Most other systems only need an IPv6 port to create both IPv6 and IPv4 incoming network connections. couriertcpd quietly ignores a failure to create an IPv4 wildcard port, as long as an IPv6 wildcard was succesfully created. The -address option can be used to default a specific IP address for every listed port number. For example: and will create network connections on ports 25 and 999 of the IP address 127.0.0.1.

ACCESS FILE

The access file lists IP addresses that couriertcpd will accept or reject connections from. An access file is optional. Without an access file couriertcpd accepts a connection from any IP address. Both IPv4 and IPv6 addresses can be specified, if IPv6 support is available. A non-standard syntax is currently used to specify IPv6 addresses. This is subject to change in the near future. IPv6 support is currently considered to be experimental. The access file is a binary database file that's usually created by a script, such as makesmtpaccess(8)[2], or makeimapaccess(8)[3], from one or more plain text files. Blank lines in the text file are ignored. Lines that start with the # character are also ignored.

Rejecting and accepting connections by IP address

The following line instructs couriertcpd to reject all connections from an IP address range: 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: 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: 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:

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: 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: Netblocks must be specified using even-word boundaries only: This will deny entire 3ffe::/16 (6bone network, which is phased out). This will deny 2002:c0a8::/32 (6to4 addresses derived from private address space).

Setting environment variables

allow can be optionally followed by a list of environment variable assignments, separated by commas. The environment variables are set before executing program or checking access lists (see below). For example: 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. 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

An alternative to listing banned IP addresses in access files is to use an external DNS-based IP access list. 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 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: 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. 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. 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): Without this parameter couriertcpd queries for A records only. Finally, a literal IP address, if given, must always follow the variable name: -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

Multiple -block and -allow options can be given. The connecting IP address gets looked up in multiple access lists. This is implemented as follows. 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

Three additional environment variables may get set in conjunction with a successful DNS access list lookup: 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

Including “allowok” keyword in an SPF setting automatically passes the SPF check for senders whose IP address is found in an -allow-ed access list. See courier(8)[4].

ENVIRONMENT VARIABLES

couriertcpd also initializes the following environment variables prior to running program: TCPLOCALHOST TCPLOCALIP TCPLOCALPORT TCPREMOTEHOST TCPREMOTEIP TCPREMOTEINFO TCPREMOTEPORT

SEE ALSO

courier(8)[4].

AUTHOR

Sam Varshavchik

NOTES

1.

Multiple port list

2.

makesmtpaccess(8)

3.

makeimapaccess(8)

4.

courier(8)