couriertcpd [ options ] port program arg1 arg2 ...
port is the TCP port where connections are accepted from. 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 will initialize several environment variables. 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.
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.
The access file is a binary database file that's usually created by a script, such as makesmtpaccess(8), from one or more plain text files. Blank lines in the text file are ignored. Lines that start with the # character are also ignored.
The following line instructs couriertcpd to reject all connections from an IP address range:
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
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 blacklists (see below). For example:
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.
An alternative to listing banned IP addresses is to use an external DNS-based blacklist.
couriertcpd does not automatically reject connections from any blacklisted IP address. If the connecting IP address is blacklisted, couriertcpd simply sets an environment variable. It's up to the program run by couriertcpd to read the environment variable and choose what to do if the environment variable is blacklisted.
Please note that if the environment variable is already set, couriertcpd will NOT search the blacklist. This can be used to override the blacklist where program only recognizes the blacklist if the environment variable is not empty. By setting the environment variable to an empty string in the access file (see above), you can override blacklists for selected IP addresses.
The -block option queries a blacklist for each connecting IP address. The only required argument to -block is the DNS zone that is used to publish the blacklist. The name of the zone can optionally be followed by a comma and the name of the environment variable to set if the blacklist lists the connecting IP address. couriertcpd sets the environment variable BLOCK if you do not specify the name yourself.
The name of the environment variable can be optionally followed by a slash and an IP address. Normally couriertcpd sets the environment variable if the blacklist includes any A record entry for the specified IP address. Some blacklists may offer additional information by returning one of several possible A records. If the name of the environment variable is followed by a slash and an IP address, the environment variable will be initialized only if the blacklist includes an A record containing the indicated IP address.
The contents of the environment variable will be the contents of any TXT record for the blacklisted IP address. var[/n.n.n.n] can be optionally followed by a comma and a text message, which will be used instead of the TXT record. The text message may include a single @ character somewhere in it, which will be replaced by the blacklisted IP address.
couriertcpd processes all -block options one at a time. If the indicated environment variable is already set, couriertcpd skips the blacklist lookup (this is also true if only one -block option is specified). Therefore, if multiple -block options are used, and an IP address is found in the first blacklist, the remaining blacklists that use the same environment variable will not be checked. But other blacklists that use a different environment variable WILL be checked.
The same zone can be specified more than once, with different environment variables and different IP addresses. For example:
couriertcpd -block=block.example.org,BLOCK1/127.0.0.2 \ -block=block.example.org,BLOCK2/127.0.0.3If the specified blacklist contains an A record for the blacklisted address, and the A record contains the IP address 127.0.0.2, couriertcpd initializes the BLOCK1 environment variable. If the A record contains the IP address 127.0.0.3, couriertcpd initializes BLOCK2. If both records are present, both variables are initialized.
NOTE: for this to work, your DNS server must be able to send a correct response to the ANY query. Although all DNS servers are supposed to implement ANY queries, some implementations are buggy.
couriertcpd uses the following logic to determine what kind of DNS query to issue:
If neither the IP address, nor msg is specified, couriertcpd will query for existence of TXT records, for the blacklisted IP address.
If only msg is specified, couriertcpd will query for existence of A records, for the blacklisted IP address.
If /n.n.n.n is used, and msg is not specified for at least one -block option for this same zone, couriertcpd will query for existence of ANY records, which should return both TXT and all the A records for this IP address.
If /n.n.n.n is used, and msg is specified for every -block option for this same zone, couriertcpd will query for existence of A records only.