couriertcpd -pid=pidfile [ options ] port program arg1 arg2 ...
couriertcpd -pid=pidfile -stop
couriertcpd -pid=pidfile -restart
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.
-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.-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
- REQUIRED OPTION: name of a
file where couriertcpd
's process ID will be saved, usually
somewhere in /var/run
.-restart
- send a SIGHUP to an existing
couriertcpd
process. Specify the same -pid
argument as the one that was used to start couriertcpd
. The
process ID is read from the -pid
file, and the
couriertcpd
receives a SIGHUP signal.-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.-stderrloggername=name
- use name as the argument to
stderrlogger, instead of the program's name.-stop
- stop (kill) an existing couriertcpd
process. Specify the same -pid
argument as the one that was
used to start couriertcpd
. The process ID is read from the
-pid
file, and the couriertcpd
process is
killed. All child processes of couriertcpd
will receive a
SIGTERM signal.-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
.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)
, 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
NOTE: IPv6 support in the access file is experimental, and is subject to change in a future release. The following syntax is subject to change at any time.
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:
:0000:0000:0000:e240<tab>deny
This puts the entire ::e240/32 IPv6 CIDR into the access file.
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.
There is no provision to support IPv6-based blacklists, because none yet exist. IPv6-based blacklist support will be added in the future.
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.
-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.
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.