'\" 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