couriertcpd(8)

NAME

couriertcpd - Courier TCP server daemon

SYNOPSIS

   couriertcpd [ options ] port program arg1 arg2 ...

DESCRIPTION

couriertcpd listens for connections on a network port, and runs program in response to each connection to the network port. The program's standard input and output are set to the network connection.

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.

OPTIONS

-access=filename: specifies an optional access file. The access file lists the IP addresses from which connections should be accepted or rejected. The access file is also used to initialize environment variables based on the IP address of the connection. filename is a GDBM or DB database file that's usually created by a script from one or more text files. See ACCESS FILE below for more information.

-address=n.n.n.n: specifies the IP address where connections are accepted. If not specified, couriertcpd accepts connections to any IP address that the system accepts connections on. If the system has multiple network interfaces with separate IP addresses, this option makes couriertcpd accept connections only to one specific IP address. Most systems have multiple network interfaces: the loopback interface, plus the local network interface, so that -address=127.0.0.1 accepts connections only from the local system. -address is an all-or-nothing proposition. To accept connections to some, but not all, IP addresses assigned to the system you will have to run multiple instances of couriertcpd, one for each IP address.

-block=zone[,var[/n.n.n.n][,msg]] -: initialize the environment variable var if both of the following conditions are true: var is not already initialized; the connecting IP address can be found in a DNS-based blacklist. See BLACKLISTS, below. Multiple -block options can be used.

-forcebind: If couriertcpd cannot bind the socket immediately, couriertcpd waits 60 seconds and tries again. Some TCP/IP stacks do not allow a port to be bound immediately after a connection from the same port is closed. If this options is specified and couriertcpd gets an EADDRINUSE error, it will try to connect to the same port. If the connection goes through, there's an active listener on the same port already, and couriertcp quietly terminates. Otherwise, it waits 60 seconds and tries again. This option is very convenient for scripts that want to shut down couriertcpd and immediately restart it.

-group=group: set couriertcpd's its group ID. group may be specified numerically, or by its name. Only the superuser may use -group.

-listen=n: length of the queue which holds pending connections. n is a number. If not specified, the system default is used.

-maxperc=n: maximum number of connections accepted from the same C network block. Using this option is recommended, because connection slots are limited. Without this option, the same C network block can potentially use up all available connection slots.

-maxperip=n: maximum number of connections accepted from the same IP address. Use both the -maxperc and -maxperip options to fine tune connection limits. For example, when couriertcpd is listening on the SMTP port it makes sense to set an upper limit on the number of connections from the same C block. Domains that send a large amount of mail often have multiple servers sending outbound mail from the same C block, so it makes sense to set limits on individual C blocks. On the other hand, if couriertcpd is listening on the POP3 port it makes more sense to set limits on individual IP addresses. If a C block of addresses is assigned to a dialup modem pool, it is certainly possible to have many IP addresses within the same C block have connections to the POP3 server at the same time.

-maxprocs=n: maximum number of connection slots, or the maximum number of processes started. This effectively specifies the maximum number of connections accepted at the same time. After the maximum number of connections has been opened, couriertcpd waits for an existing connection to close, before accepting any more connections.

-nodnslookup: do not look up the hostname associated with connecting IP address and the local addres, do not initialize the TCPREMOTEHOST or TCPLOCALHOST environment variables (see below).

-noidentlookup: do not perform an ident lookup, and do not initialize the TCPREMOTEINFO environment variable.

-pid=filename: name of a file where couriertcpd's process ID will be saved, usually somewhere in /var/run.

-stderr=socket: set program's standard error to the network connection, just like its standard input and output.

-stderr=/path/to/logfile: set program's standard error to the specified file. The file is created, if necessary, and is opened in append mode.

-stderrlogger=/path/to/logger: set program's standard error to a pipe, which is read by logger. Only one instance of logger is started, which will read standard error from every instance of program. The specified logger is executed with the output end of the pipe connected as standard input. logger is executed with one argument - program's name.

-user=user: set couriertcpd's user ID. Also, the group ID is set to the user's group ID. Using both -group and -user is not necessary. Only the superuser can specify -user.

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.

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.

Rejecting and accepting connections by IP address

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

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 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.

BLACKLISTS

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.

MULTIPLE BLACKLISTS

Multiple -block options can be used. The connecting IP address will be looked up in multiple blacklists. This is implemented as follows.

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.3

If 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.

ENVIRONMENT VARIABLES

couriertcpd also initialized the following environment variables prior to running program:

TCPLOCALHOST: the name of the host on the local end of the network connection, looked up in DNS. TCPLOCALHOST will not be set if the IP address of the network connection's local end cannot be found in DNS, or if -nodnslookup option is specified. TCPLOCALHOST will be set to the string softdnserr if the DNS lookup fails with a temporary error (so you cannot tell if the IP address has a valid host name associated with it), or if the reverse and forward DNS lookups do not match. TCPLOCALHOST will not be set if the reverse DNS lookup fails completely.

TCPLOCALIP: the IP address of the local end of the network connection.

TCPLOCALPORT: the number of the port of the local end of the network connection.

TCPREMOTEHOST: the name of the connecting host. Like TCPLOCALHOST, but for the connecting IP address.

TCPREMOTEIP: connecting IP address.

TCPREMOTEINFO: identification string received from the IDENT server on the remote IP address. Not set if the IDENT server returned an error, or if the -noidentlookup option was specified.

TCPREMOTEPORT: TCP port of the remote end of the network connection.