'\" t
.\"
.\"
.\" Title: couriertcpd
.\" Author: Sam Varshavchik
.\" Generator: DocBook XSL Stylesheets v1.75.2
.\" Date: 04/04/2011
.\" Manual: Double Precision, Inc.
.\" Source: Courier Mail Server
.\" Language: English
.\"
.TH "COURIERTCPD" "1" "04/04/2011" "Courier Mail Server" "Double Precision, Inc."
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
couriertcpd \- the Courier mail server TCP server daemon
.SH "SYNOPSIS"
.HP \w'\fBcouriertcpd\fR\ 'u
\fBcouriertcpd\fR [\-pid=\fIpidfile\fR] [\fIoption\fR...] {\fIlist\fR} {\fIprogram\fR} {\fIarg\fR...}
.HP \w'\fBcouriertcpd\fR\ 'u
\fBcouriertcpd\fR {\-pid=\fIpidfile\fR} {\-stop}
.HP \w'\fBcouriertcpd\fR\ 'u
\fBcouriertcpd\fR {\-pid=\fIpidfile\fR} {\-restart}
.SH "DESCRIPTION"
.PP
\fBcouriertcpd\fR
accepts incoming network connections, and runs
\fBprogram\fR
after establishing each network connection\&. The
\fBprogram\fR\'s standard input and output are set to the network connection\&.
.PP
\fIlist\fR
is a comma\-separated list of TCP port numbers where incoming connections are created\&.
\fBprogram\fR
is the program to run\&. If
\fBprogram\fR
requires any arguments, they are specified on the command line, after
\fBprogram\fR
itself\&.
.PP
Before running
\fBprogram\fR,
\fBcouriertcpd\fR
initializes several environment variables that describe the network connection\&. The environment inherited by
\fBprogram\fR
will be the environment inherited by
\fBcouriertcpd\fR, plus any additional environment variables initialized by
\fBcouriertcpd\fR\&. It is also possible to reject certain network connections\&. Several options are available to specify which network connections will be rejected\&.
.SH "OPTIONS"
.PP
\-access=\fIfilename\fR
.RS 4
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\&.
\fIfilename\fR
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\&.
.RE
.PP
\-accesslocal
.RS 4
Lookup the local interface IP and port in the access file, in addition to looking up the remote IP\&. This gives a mechanism for setting environment variables depending on which IP address and/or port the client connected to\&. In the access file, "1\&.2\&.3\&.4\&.25" matches connections to IP address 1\&.2\&.3\&.4 port 25; "1\&.2\&.3\&.4" matches connections to IP address 1\&.2\&.3\&.4 on any port; and "*\&.25" matches connections to port 25 on any IP address\&.
.RE
.PP
\-address=\fIn\&.n\&.n\&.n\fR
.RS 4
Accept network connections only to IP address
\fIn\&.n\&.n\&.n\fR\&. If not specified,
\fBcouriertcpd\fR
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
\fBcouriertcpd\fR
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\&. When multiple port numbers are specified, it is also possible to selectively bind different network addresses to each port number when
\fIlist\fR
specifies more than one port number\&. See "\m[blue]\fBMultiple port list\fR\m[]\&\s-2\u[1]\d\s+2" below for more information\&.
.RE
.PP
\-block=\fIzone\fR[,\fIvar\fR[/\fIn\&.n\&.n\&.n\fR][,\fImsg\fR]]
.RS 4
Initialize the environment variable
\fIvar\fR
if both of the following conditions are true:
\fIvar\fR
is not already initialized; the connecting IP address can be found in a DNS\-based list\&. See DNS ACCESS LISTS, below\&. Multiple
\fB\-block\fR
options can be used\&.
.RE
.PP
\-denymsg=\fItext\fR
.RS 4
Specifies an optional message to be returned to the client if the
\fI\-access\fR
option rejects them\&. The default is to drop the TCP connection without sending back any messages\&.
.RE
.PP
\-drop=\fIvar\fR
.RS 4
If the environment variable
\fIvar\fR
is set to a nonempty value, terminate immediately\&. Do not run the
\fBprogram\fR
to handle the connection\&. See DNS ACCESS LISTS, below, for more information\&.
\fIvar\fR
defaults to
\(lqBLOCK\(rq, if not specified\&.
.RE
.PP
\-group=\fIgroup\fR
.RS 4
Set
\fBcouriertcpd\fR\'s its group ID\&.
\fIgroup\fR
may be specified numerically, or by its name\&. Only the superuser may use
\fB\-group\fR\&.
.RE
.PP
\-listen=\fIn\fR
.RS 4
Length of the queue which holds pending connections\&.
\fIn\fR
is a number\&. If not specified, the system default is used\&.
.RE
.PP
\-maxperc=\fIn\fR
.RS 4
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\&.
.RE
.PP
\-maxperip=\fIn\fR
.RS 4
Maximum number of connections accepted from the same IP address\&. Use both the
\fB\-maxperc\fR
and
\fB\-maxperip\fR
options to fine tune connection limits\&. For example, when
\fBcouriertcpd\fR
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
\fBcouriertcpd\fR
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\&.
.RE
.PP
\-maxprocs=\fIn\fR
.RS 4
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,
\fBcouriertcpd\fR
waits for an existing connection to close, before accepting any more connections\&.
.RE
.PP
\-warn=\fIn\fR
.RS 4
Log a
\fBLOG_WARNING\fR
message to syslog when the number of active processes exceeds
\fIn\fR\&. The default is 90% of
\fImaxprocs\fR\&.
\fBcouriertcpd\fR
logs a
\fBLOG_ALERT\fR
syslog message when the number of active processes reaches the maximum\&.
.RE
.PP
\-nodnslookup
.RS 4
Do not look up the hostname associated with connecting IP address and the local addres, do not initialize the
\fBTCPREMOTEHOST\fR
or
\fBTCPLOCALHOST\fR
environment variables (see below)\&.
.RE
.PP
\-noidentlookup
.RS 4
Do not perform an
\fIident\fR
lookup, and do not initialize the
\fBTCPREMOTEINFO\fR
environment variable\&.
.RE
.PP
\-pid=\fIfilename\fR
.RS 4
If given,
\fBcouriertcpd\fR
puts itself into the background and saves its process ID in this file, usually somewhere in
/var/run\&.
.sp
This option must also be present when using the
\fB\-restart\fR
and
\fB\-stop\fR
options\&.
.RE
.PP
\-restart
.RS 4
Send a SIGHUP to an existing
\fBcouriertcpd\fR
process\&. Specify the same
\fB\-pid\fR
argument as the one that was used to start
\fBcouriertcpd\fR\&. The process ID is read from the
\fB\-pid\fR
file, and the
\fBcouriertcpd\fR
receives a SIGHUP signal\&.
.RE
.PP
\-stderr=socket
.RS 4
Set
\fBprogram\fR\'s standard error to the network connection, just like its standard input and output\&.
.RE
.PP
\-stderr=\fIlogfile\fR
.RS 4
Set
\fBprogram\fR\'s standard error to the specified file,
logfile\&. The file is created, if necessary, and is opened in append mode\&.
.RE
.PP
\-stderrlogger=\fIlogprogram\fR
.RS 4
Set
\fBprogram\fR\'s standard error to a pipe, which is read by
\fBlogprogram\fR\&. Only one instance of
\fIlogger\fR
is started, which receives standard error from every instance of
\fBprogram\fR\&. The specified
\fIlogger\fR
is executed with the output end of the stderr pipe connected as standard input\&.
\fIlogprogram\fR
is executed with one argument \-
\fBprogram\fR\'s name\&.
.RE
.PP
\-stderrloggername=name
.RS 4
Use
\fIname\fR
as the argument to
\fIlogprogram\fR, instead of the
\fBprogram\fR\'s name\&.
.RE
.PP
\-stop
.RS 4
Stop (kill) an existing
\fBcouriertcpd\fR
process\&. Specify the same
\fB\-pid\fR
argument as the one that was used to start
\fBcouriertcpd\fR\&. The process ID is read from the
\fB\-pid\fR
file, and the
\fBcouriertcpd\fR
process is killed\&. All child processes of
\fBcouriertcpd\fR
will receive a SIGTERM signal\&.
.RE
.PP
\-user=\fIuser\fR
.RS 4
Set
\fBcouriertcpd\fR\'s user ID\&. Also, the group ID is set to the user\'s group ID\&. Using both
\fB\-group\fR
and
\fB\-user\fR
is not necessary\&. Only the superuser can specify
\fB\-user\fR\&.
.RE
.SH "MULTIPLE PORT LIST"
.PP
The
\fIlist\fR
argument can be a comma\-separated list of multiple port numbers\&.
\fBcouriertcpd\fR
will create network connections on any listed port\&. Each port number can be optionally specified as "address\&.port", for example:
.sp
.if n \{\
.RS 4
.\}
.nf
couriertcpd \-pid=/var/run/smtp\&.pid 127\&.0\&.0\&.1\&.25,999 \fIprogram\fR
.fi
.if n \{\
.RE
.\}
.PP
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\&.
.PP
Whenever an IP address is not specified, network connections are accepted to any IP address (called "wildcarding")\&. On IPv6\-capable systems,
\fBcouriertcpd\fR
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\&.
\fBcouriertcpd\fR
quietly ignores a failure to create an IPv4 wildcard port, as long as an IPv6 wildcard was succesfully created\&.
.PP
The
\fB\-address\fR
option can be used to default a specific IP address for every listed port number\&. For example:
.sp
.if n \{\
.RS 4
.\}
.nf
couriertcpd \-pid=/var/run/smtp\&.pid 127\&.0\&.0\&.1\&.25,127\&.0\&.0\&.1\&.999 \fIprogram\fR
.fi
.if n \{\
.RE
.\}
.PP
and
.sp
.if n \{\
.RS 4
.\}
.nf
couriertcpd \-pid=/var/run/smtp\&.pid \-address=127\&.0\&.0\&.1 25,999 \fIprogram\fR
.fi
.if n \{\
.RE
.\}
.PP
will create network connections on ports 25 and 999 of the IP address 127\&.0\&.0\&.1\&.
.SH "ACCESS FILE"
.PP
The access file lists IP addresses that
\fBcouriertcpd\fR
will accept or reject connections from\&. An access file is optional\&. Without an access file
\fBcouriertcpd\fR
accepts a connection from any IP address\&.
.PP
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\&.
.PP
The access file is a binary database file that\'s usually created by a script, such as
\m[blue]\fB\fBmakesmtpaccess\fR(8)\fR\m[]\&\s-2\u[2]\d\s+2, from one or more plain text files\&. Blank lines in the text file are ignored\&. Lines that start with the # character are also ignored\&.
.SS "Rejecting and accepting connections by IP address"
.PP
The following line instructs
\fBcouriertcpd\fR
to reject all connections from an IP address range:
.sp
.if n \{\
.RS 4
.\}
.nf
netblockdeny
.fi
.if n \{\
.RE
.\}
.PP
\fInetblock\fR
is an IP address, such as
192\&.68\&.0\&.2\&.
is the ASCII tab character\&. There MUST be exactly one tab character after the IP address and the word "deny"\&.
.PP
You can also block connections from an entire network C block:
.sp
.if n \{\
.RS 4
.\}
.nf
192\&.68\&.0deny
.fi
.if n \{\
.RE
.\}
.PP
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\&.
.PP
Use the word "allow" instead of "deny" to explicitly allow connections from that IP address or netblock\&. For example:
.sp
.if n \{\
.RS 4
.\}
.nf
192\&.68\&.0deny
192\&.68\&.0\&.10allow
.fi
.if n \{\
.RE
.\}
.PP
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\&.
\fBcouriertcpd\fR
always uses the line with the most specific IP address\&.
.PP
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:
.sp
.if n \{\
.RS 4
.\}
.nf
*deny
.fi
.if n \{\
.RE
.\}
.SS "IPv6 addresses"
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
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\&.
.sp .5v
.RE
.PP
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:
.sp
.if n \{\
.RS 4
.\}
.nf
:hhhh:hhhh:hhhh:hhhh:hhhh:hhhh:hhhh:hhhh\fIaction\fR
.fi
.if n \{\
.RE
.\}
.PP
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
\fIusing zero\-padded lowercase hexadecimal digits\fR\&. For example:
.sp
.if n \{\
.RS 4
.\}
.nf
:0000:0000:0000:0000:0000:f643:00a2:9354deny
.fi
.if n \{\
.RE
.\}
.PP
Netblocks must be specified using even\-word boundaries only:
.sp
.if n \{\
.RS 4
.\}
.nf
:3ffedeny
.fi
.if n \{\
.RE
.\}
.PP
This will deny entire 3ffe::/16 (6bone network, which is phased out)\&.
.sp
.if n \{\
.RS 4
.\}
.nf
:2002:c0a8deny
.fi
.if n \{\
.RE
.\}
.PP
This will deny 2002:c0a8::/32 (6to4 addresses derived from private address space)\&.
.SS "Setting environment variables"
.PP
allow
can be optionally followed by a list of environment variable assignments, separated by commas\&. The environment variables are set before executing
\fBprogram\fR
or checking access lists (see below)\&. For example:
.sp
.if n \{\
.RS 4
.\}
.nf
192\&.68\&.0allow,RELAYCLIENT
192\&.68\&.0\&.10allow,RELAYCLIENT,SIZELIMIT=1000000
.fi
.if n \{\
.RE
.\}
.PP
This sets
\fBRELAYCLIENT\fR
environment variable for connections from the
192\&.68\&.0
block\&. In addition to that, the
\fBSIZELIMIT\fR
environment variable is set to
1000000
if the connection comes from the IP address
192\&.68\&.0\&.10\&.
.PP
Note that
\fBRELAYCLIENT\fR
must be explicitly specified for the IP address
192\&.68\&.0\&.10\&. The first line is NOT used for connections from this IP address\&.
\fBcouriertcpd\fR
only reads one entry from the access file, the entry for the most specific IP address\&.
.SS "DNS ACCESS LISTS"
.PP
An alternative to listing banned IP addresses is to use an external DNS\-based IP access list\&.
.PP
There is no provision to support IPv6\-based lists, because none yet exist\&. IPv6\-based access list support will be added in the future\&.
.PP
\fBcouriertcpd\fR\'s default configuration does not automatically reject connections from any IP address listed on a DNS\-based list\&. If the connecting IP address is listed couriertcpd simply sets an environment variable\&. It\'s up to the
\fBprogram\fR, run by
\fBcouriertcpd\fR, to read the environment variable and choose what to do if the environment variable is set\&.
.PP
Please note that if the environment variable is already set,
\fBcouriertcpd\fR
will NOT search the access list\&. This can be used to override the access list where
\fBprogram\fR
only recognizes the access list 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 access lists for selected IP addresses\&.
.PP
The
\fB\-block\fR
option queries a DNS list for each connecting IP address\&. The only required argument to
\fB\-block\fR
is the DNS zone that is used to publish thelist\&. The name of the zone can optionally be followed by a comma and the name of the environment variable to set if the DNS list includes the IP address\&.
\fBcouriertcpd\fR
sets the environment variable
\fBBLOCK\fR
if you do not specify the name yourself\&.
.PP
The name of the environment variable can be optionally followed by a slash and an IP address\&. Normally
\fBcouriertcpd\fR
sets the environment variable if the access list includes any A record entry for the specified IP address\&. Some access lists 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 access list includes an A record containing the indicated IP address\&.
.PP
The contents of the environment variable will be the contents of any TXT record for the listed IP address\&.
\fIvar\fR[/\fIn\&.n\&.n\&.n\fR] 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 listed IP address\&.
.PP
When the
\fB\-drop\fR
option is given in addition to
\fB\-block\fR,
\fBcouriertcpd\fR
drops the connection, rather than running the
\fBprogram\fR\&. First, all
\fB\-block\fR
options are processed and the environment variables are set, based on the results of any matching DNS lookups\&. The
\fB\-drop\fR
gets processed after all DNS lookups\&.
\fB\-drop\fR
takes a list of comma\-separated environment variables (if not specified,
\fBBLOCK\fR
is the default list)\&. If any environment variable named by the
\fB\-drop\fR
option is set to a non\-empty string,
\fBcouriertcpd\fR
drops the connection instead of executing the
\fBprogram\fR\&.
.SS "MULTIPLE DNS LISTS"
.PP
Multiple
\fB\-block\fR
options can be used\&. The connecting IP address gets looked up in multiple access lists\&. This is implemented as follows\&.
.PP
\fBcouriertcpd\fR
processes all
\fB\-block\fR
options one at a time\&. If the indicated environment variable is already set,
\fBcouriertcpd\fR
skips the DNS list lookup (this is also true if only one
\fB\-block\fR
option is specified)\&. Therefore, if multiple
\fB\-block\fR
options are used, and an IP address is found in the first access list, the remaining lists that use the same environment variable will not be checked\&. But other lists that use a different environment variable WILL be checked\&.
.PP
The same
\fIzone\fR
can be specified more than once, with different environment variables and different IP addresses\&. For example:
.sp
.if n \{\
.RS 4
.\}
.nf
couriertcpd \-block=block\&.example\&.org,BLOCK1/127\&.0\&.0\&.2 \e
\-block=block\&.example\&.org,BLOCK2/127\&.0\&.0\&.3
.fi
.if n \{\
.RE
.\}
.PP
If the specified access list contains an A record for the listed address, and the A record contains the IP address 127\&.0\&.0\&.2,
\fBcouriertcpd\fR
initializes the
\fBBLOCK1\fR
environment variable\&. If the A record contains the IP address 127\&.0\&.0\&.3,
\fBcouriertcpd\fR
initializes
\fBBLOCK2\fR\&. If both records are present, both variables are initialized\&.
.PP
\fBcouriertcpd\fR
uses the following logic to determine what kind of DNS query to issue:
.PP
If neither the IP address, nor
\fImsg\fR
is specified,
\fBcouriertcpd\fR
will query for existence of TXT records, for the IP address\&.
.PP
If only
\fImsg\fR
is specified,
\fBcouriertcpd\fR
looks up the existence of A records, for the IP address\&.
.PP
If
\fI/n\&.n\&.n\&.n\fR
is used, and
\fImsg\fR
is not specified for at least one
\fB\-block\fR
option for this same zone,
\fBcouriertcpd\fR
will query for existence of ANY records, which should return both TXT and all the A records for this IP address\&.
.PP
If
\fI/n\&.n\&.n\&.n\fR
is used, and
\fImsg\fR
is specified for every
\fB\-block\fR
option for this same zone,
\fBcouriertcpd\fR
will query for existence of A records only\&.
.SH "ENVIRONMENT VARIABLES"
.PP
\fBcouriertcpd\fR
also initializes the following environment variables prior to running
\fBprogram\fR:
.PP
TCPLOCALHOST
.RS 4
The name of the host on the local end of the network connection, looked up in DNS\&.
\fBTCPLOCALHOST\fR
will not be set if the IP address of the network connection\'s local end cannot be found in DNS, or if
\fB\-nodnslookup\fR
option is specified\&.
\fBTCPLOCALHOST\fR
will be set to the string
\fBsoftdnserr\fR
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\&.
\fBTCPLOCALHOST\fR
will not be set if the reverse DNS lookup fails completely\&.
.RE
.PP
TCPLOCALIP
.RS 4
The IP address of the local end of the network connection\&.
.RE
.PP
TCPLOCALPORT
.RS 4
Rhe number of the port of the local end of the network connection\&.
.RE
.PP
TCPREMOTEHOST
.RS 4
The hostname of the connecting host\&. Like
\fBTCPLOCALHOST\fR, but for the connecting IP address\&.
.RE
.PP
TCPREMOTEIP
.RS 4
Connecting IP address\&.
.RE
.PP
TCPREMOTEINFO
.RS 4
Identification string received from the IDENT server on the remote IP address\&. Not set if the IDENT server returned an error, or if the
\fB\-noidentlookup\fR
option was specified\&.
.RE
.PP
TCPREMOTEPORT
.RS 4
TCP port of the remote end of the network connection\&.
.RE
.SH "SEE ALSO"
.PP
\m[blue]\fB\fBcourier\fR(8)\fR\m[]\&\s-2\u[3]\d\s+2\&.
.SH "AUTHOR"
.PP
\fBSam Varshavchik\fR
.RS 4
Author
.RE
.SH "NOTES"
.IP " 1." 4
Multiple port list
.RS 4
\%[set $man.base.url.for.relative.links]/#list
.RE
.IP " 2." 4
\fBmakesmtpaccess\fR(8)
.RS 4
\%[set $man.base.url.for.relative.links]/makesmtpaccess.html
.RE
.IP " 3." 4
\fBcourier\fR(8)
.RS 4
\%[set $man.base.url.for.relative.links]/courier.html
.RE