NAME
courier - The Courier mail serverSYNOPSIS
courier
{start | stop | restart | flush | flush qid |
clear user@domain | clear all | show all }
DESCRIPTION
The Courier mail server is a modular multi-protocol E-mail transport agent. The courier command is an administrative command, and most of its options are only available to the superuser. " courier start" starts the server by running /usr/lib/courier/courierctl.start in the background. " courier stop" immediately stops all the Courier mail server processes and aborts all current mail deliveries. " courier restart" restarts the Courier mail server server. A restart is often needed for certain configuration changes to take effect. " courier restart" waits for all current deliveries to complete before restarting. This is the "nice" way to restart the mail server. " courier flush" takes all undelivered messages in the queue and attempts to deliver them immediately, instead of waiting until their next scheduled attempted delivery time. " courier flush" can be optionally followed by a message queue ID in order to schedule an immediate delivery attempt for only a single message. Message queue IDs are displayed by the mailq(1)[1] command. Please note that courier start runs the main Courier mail server scheduling engine only. It does not start any other daemons that you may have, such as the ESMTP or the IMAP daemon. " courier show all" lists all E-mail addresses currently blacklisted for backscatter. " courier clear user@domain" manually clears <user@domain> from the backscatter blacklist. " courier clear all" removes all addresses from the backscatter blacklist. When the Courier mail server encounters a delivery failure to an E-mail address the Courier mail server may stop accepting any more messages to the same address in order to minimize generation of so-called "backscatter bounces". This does not occur in all cases, see "Backscatter suppression" in the Courier mail server's installation instructions for more information. The Courier mail server will resume accepting messages to the blacklisted address if the delivery attempt originally encountered a temporary failure, and a subsequent retry succesfully delivered the message, or if more than two hours elapsed since the delivery failure. Use the "clear" command to manually clear the E-mail address from the backscatter blacklist. This may be useful if the undeliverable message is manually removed from the Courier mail server's mail queue, using the "cancel" command. Even if the message is cancelled, the Courier mail server will continue to refuse accepting mail for this address for up to two hours. The "clear" command can be use to reenable mail acceptance before then.CONFIGURATION FILES
The Courier mail server uses several configuration files which are located in /etc/courier. These configuration files are plain text files that can be modified with any text editor. In certain instances a subdirectory is used, and all plain text files in the subdirectory are concatenated and are considered to be a single, consolidated, configuration file. Unless otherwise specified, you must run courier restart for any changes to these files to take effect. International domain names should be listed in UTF-8 lowercase. For example, the hosteddomains file may list “пример.испытание” as a domain. aliasfilteracctThis file contains one line, containing the
home directory of the account that's used for filtering mail addressed to
local alias lists.
When mail filtering is enabled, local recipients have the ability to define mail
filters which can selectively reject unwanted mail. /etc/courier/aliases may
define local mail aliases that contain one or more recipients. If it is
desired to use local mail filtering for mail addressed to an alias address,
designate a local account that will be used to specify filtering instructions,
and put its home directory into this control file. The filtering argument will
be "alias- address" where address is the name of the
alias. See localmailfilter(7)[2] for more information.
Due to technical limitations, content filtering is not available for
multiple-recipient aliases.
Changes to this file take effect immediately.
autoresponsesquota
This file sets the systemwide quota on
autoreplies, if autoreplies and mail filtering are enabled. Note that this can
only really be effective if there is no login access to the mail account,
since this autoreply quota can be trivially overriden.
The autoresponsesquota file contains one line: "C nnn" or
"S nnn" (or both strings, on the same line). C nnn:
allow up to #nnn autoreplies to be created. S nnn: allow up to #nnn
bytes as the total size of all autoreplies, combined. If both C nnn and
S nnn are specified, both quotas apply. If this file does not exist,
there is no limit on autoreplies. This quota setting applies systemwide. To
override the quota setting for a particular Maildir, create the
autoresponsesquota file in that Maildir (which takes precedence).
backuprelay
This file contains one line, containing a name
of a machine where mail will be rerouted if it cannot be immediately
delivered. Spaces are not allowed in this file.
Mail gets rerouted if it cannot be delivered after the time interval specified
by the warntime configuration file. When backuprelay is provided a delayed
delivery status notification will NOT be generated. The message will be
rerouted even if the recipient's delivery status notification setting does not
include a delayed notification request.
This feature is intended for use by relays that handle large quantities of mail,
where you don't want to accumulate a large mail queue for unreachable mail
servers. Please note that ALL undeliverable mail will be rerouted in this
fashion. Even if the recipient of a message is a local recipient - and the
recipient's mail filter is rejecting the message with a temporary error code -
the message will still be rerouted if it's undeliverable after the specified
amount of time.
Although currently SMTP is the only meaningful application for this feature, the
Courier mail server is a protocol-independent mail server, and the backup
relay function can be extended to other protocols, as they become available.
Multiple backup relays can be used by simply assigning multiple IP addresses to
the same machine name. Note that the Courier mail server checks for both MX
and A records for the machine specified in this configuration file.
It's important to note that when this setting is specified, warning messages get
turned off for all messages, including messages addressed to local recipients.
If a temporary delivery error prevents a message from being delivered to a
local mailbox, it remains in the queue until the temporary error condition
gets cleared. Normally, if the message remains in the queue beyond the warning
interval, the warning message gets generated. When this setting is specified,
the warning message gets replaced with a forward to the backup relay, but this
occurs only for messages that are delivered via SMTP.
batchsize
This file contains one line, containing a
single number. This number specifies the absolute maximum number of recipients
for a single message. If the Courier mail server receives a message with more
recipients, the message is duplicated as often as necessary until each copy of
the message has no more than batchsize recipients. If batchsize is missing, it
defaults to 100 recipients per message.
bofh
This configuration file configures
domain-based junk mail filters. Lines in this configuration files that begin
with the # character are considered comments, and are ignored. The remaining
lines contain the following directives, in any order:
badfrom user@domain
calendarmode
Reject all mail with the return address of
<user@domain>.
badfrom @domain
Reject all mail with the return address of
<anything@domain>.
badfrom @.domain
Reject all mail with the return address of
<[email protected]>.
badfrom [email protected]
Reject all mail with the return address of
<[email protected]>.
badmx N
Reject all mail with a return address in any
mail domain whose listed mail servers include server " N".
" N" is an IP address. The BOFHCHECKDNS option in the
esmtp configuration file must also be enabled (this is the default setting) in
order for this additional checking to take place. Note that this is "best
effort" check. A DNS failure to look up A records for hostnames returned
in the MX record may hide the blacklisted server from view.
freemail domain [domain2] [domain3]...
Reject all mail with a return address
<anything@domain> unless the mail is received from a mail relay
whose hostname is in the same domain. " domain2" and
"domain3" are optional, and specifies other domains that the
mail relay's hostname may belong to. For example: " freemail
example.com domain.com" specifies that mail with a return address
@example.com will be accepted only from a mail relay with a hostname in
the example.com or domain.com domain. Note that this setting
requires that DNS lookup be enabled for incoming ESMTP connections (which is
the default setting).
spamtrap user@domain
Reject all mail that has
<user@domain> listed as one of its recipients.
Note
For local mailboxes, 'domain' must be set to the contents of the me
configuration file, or the server's hostname. Also, this check is made after
any alias processing takes place. Suggested usage: create a single local
spamtrap account, then create aliases in the alias file that point to the
spamtrap account.
maxrcpts N [hard]
Accept the first N recipient addresses
per message, maximum. The remaining recipients are rejected. An optional
verbatim token "hard" specifies that the remaining recipients will
immediately be returned as undeliverable (otherwise the remaining recipients
are rejected as "temporary unavailable", and may be accepted on a
later delivery attempt). If not specified, the first 100 recipients are
accepted.
opt BOFHCHECKHELO=1
Verify the hostname provided in the ESMTP
HELO/EHLO statement. “opt BOFHCHECKHELO=1” is a global default,
which may be overridden by setting the BOFHCHECKHELO environment
variable in the SMTP access file. See makesmtpaccess(8)[3] for
more information. “opt BOFHCHECKHELO=1” enables ESMTP HELO/EHLO
checking by default, and ESMTP HELO/EHLO checking may be turned off for
individual IP address ranges by setting BOFHCHECKHELO to 0 using
makesmtpaccess(8)[3]. Alternatively, HELO/EHLO checking may be
turned off by default, and enabled for specific IP address ranges by using
makesmtpaccess(8)[3] to set BOFHCHECKHELO to 1. See
makesmtpaccess(8)[3] for more information.
opt BOFHCHECKHELO=2
Setting to BOFHCHECKHELO 2 has the
effect of returning a temporary SMTP error code, instead of a permanent SMTP
error code, for a failed HELO/EHLO SPF check.
opt BOFHHEADERLIMIT= n
Reject messages whose headers exceed n
bytes in size (minimum 1,000 bytes, default 100,000 bytes).
opt BOFHNOBASE64TEXT=1
Reject messages with base64-encoded text/plain
or text/html content.
opt BOFHSPFHELO= keywords
Use Sender Policy Framework to verify the HELO
or EHLO domain sent by the connecting SMTP client. See Sender Policy Framework
Keywords below for a list of possible keywords.
SPF checking is not used for HELO or EHLO commands that specify an IP address
instead of a domain name.
Note
This setting may be used in combination with opt BOFHCHECKHELO=1. The
BOFHCHECKHELO=1 check is disabled if SPF verification of the HELO/EHLO results
in the SPF status of “pass”. This makes sense: if the HELO/EHLO
domains complies with the domain's SPF, it is not necessary to check it
further.
opt BOFHSPFMAILFROM= keywords
Use Sender Policy Framework to verify the
return address in the MAIL FROM command sent by the connecting SMTP client.
See Sender Policy Framework Keywords below for a list of possible keywords.
Note
No SPF checking is done for if the MAIL FROM command specifies an empty return
address (a bounce). There's nothing to check.
opt BOFHSPFFROM= keywords
Use Sender Policy Framework to verify the
return address in the From: header. See Sender Policy Framework Keywords below
for important information, and a list of possible keywords.
opt BOFHSPFHARDERROR= keywords
This setting lists the unacceptable SPF
results that should result in a permanent error. All other unacceptable SPF
results are kicked back with a temporary error indication, inviting the sender
to try again later.
The default setting for BOFHSPFHARDERROR is fail,softfail.
opt BOFHSPFTRUSTME=1
Disable all SPF checks for any connecting
client that has relaying privileges ( RELAYCLIENT is explicitly set, or
inherited after a successful SMTP authentication).
opt BOFHSPFNOVERBOSE=1
This setting disables custom SPF rejection
messages. Any SPF rejection message specified by the SPF policy is replaced by
a stock, bland message. The author of this SPF implementation believes that
there's a minor security issue with letting an external site control the error
messages issued by your mail server. The same author does not believe that
this is such a big deal, but security-sensitive minds may choose to enable
this setting, and sleep easy at night.
opt BOFHSUPPRESSBACKSCATTER= list
This is one of the two settings that controls
which messages are subject to backscatter suppression. The other setting,
ESMTP_BLOCKBACKSCATTER is set in the courierd configuration file, which
contains further documentation.
“list” is a comma-separated list of message sources. The possible
message sources are:
authsmtp
The default setting is “opt BOFHSUPPRESSBACKSCATTER=smtp”. The
other possible values are “opt
BOFHSUPPRESSBACKSCATTER=smtp,authsmtp” (which suppresses backscatter
from all SMTP mail), and “opt
BOFHSUPPRESSBACKSCATTER=none”.
Messages received via SMTP from clients with
relaying privileges (authenticated SMTP, or IP addresses that always have
relaying privileges.
smtp
All other messages received via SMTP.
none
Do not suppress backscatter messages from any
source.
This configuration file enables basic
calendaring features in the webmail server. Calendaring is currently
considered experimental in nature, and the current implementation provides
basic calendaring services. If this file does not exist, calendaring options
are disabled. If this file exists it should contain a single word:
"local". For example:
This configuration file must be globally readable, so make sure that your umask
is not set too tight.
courierd
echo "local" >/etc/courier/calendarmode
This configuration file specifies several
parameters relating to general the Courier mail server configuration. A
default configuration file will be installed, and you should consult its
contents for additional information.
defaultdomain
This file contains one line whose contents is
a valid mail domain. Most header rewriting functions will append
@defaultdomain to all E-mail addresses that do not specify a domain. If
defaultdomain is missing, the Courier mail server uses the contents of the me
control file.
When the ESMTP server receives a “RCPT TO” command containing the
address <user@[ ip.address]>, and the IP address is the same as
the IP address of the socket it's listening on, the ESMTP server replaces the
IP address with the contents of the defaultdomain control file. If
defaultdomain is missing, the Courier mail server uses the contents of the me
control file.
The contents of defaultdomain are also appended to return addresses to mail sent
from the Courier mail server's webmail server, if they don't already have a
domain. If defaultdomain does not exist, the Courier mail server's webmail
server obtain the machine hostname, and uses that.
Note
The mail domain in defaultdomain should be one of the local domains, as defined
by the locals and the hosteddomains control files.
Otherwise, if a domain-less address in mail headers gets augmented with
defaultdomain and the recipient replies to the message, upon receipt Courier
won't recognize the recipient address as a local mailbox. This might not
necessarily be wrong, but the consequences of such an action must be clearly
understood.
Warning
If you change the contents of this configuration file, it may be necessary to
rerun the makealiases command again, else your mail will promptly begin
to bounce. If you don't have this configuration file defined, and you change
the system's network host name, you may also need to run makealiases.
dotextension
This file contains one line whose contents
specify the name of dot-files in users' home directories which contain
delivery instructions. If this file does not exist, the Courier mail server
reads $HOME/.courier, $HOME/.courier-foo, $HOME/.courier-default, and so on.
If this file contains the text "qmail", the Courier mail server will
instead read $HOME/.qmail, $HOME/.qmail-foo, $HOME/.qmail-default, and so
on.
dsnfrom
This file contains one line specifying the
contents of the From: header that the Courier mail server puts in all delivery
status notifications. This file specifies a complete header, except for the
"From: " part. If dsnfrom is missing, then the Courier mail server
uses the following header: "Courier mail server mail server at me"
<@>
dsnlimit
Maximum size, in bytes, of a message whose
contents are included in delivery status notifications. By default, the entire
message is only included in non-delivery notices (failures). Only the headers
will be returned for delay notifications (warnings) and return receipts; or
for failures if the original message is larger than dsnlimit. If missing,
dsnlimit is set to 32K.
The sender can request that the entire message be returned even on delayed
notices or return receipts, however the Courier mail server will ignore this
request if the message size exceeds this limit.
enablefiltering
This configuration file enables the global
mail filtering API for selected mail sources. This file, if it exists,
contains a single line of text that specifies which kind of mail will be
filtered. The possible values are:
esmtp
If you want to specify more than one source of mail, such as ESMTP and local
mail, specify both esmtp and local, separated by a space character.
Note
The global mail filtering API is described, in detail, in the
courierfilter(8)[5] manual page. This is NOT the traditional
user-controlled mail filtering, such as maildrop(1)[6]. A global
mail filter is a daemon process that selectively accepts or rejects incoming
mail, based on arbitrary criteria.
esmtpacceptmailfor
Enables global mail filtering for mail
received via ESMTP.
local
Specifies that mail received from logged on
users, via sendmail, and mail forwarded from dot-courier(5)[4]
will be filtered using the global mail filtering API.
uucp
Specifies that mail received from UUCP will be
filtered.
This file lists all domains that the Courier
mail server accepts mail for via ESMTP. This file is in the same format as the
locals file. If this file is missing, the Courier mail server uses the single
domain specified in me (or the system machine name).
See the section called “Hostname-dependent configuration” for more
information on hostname-dependent configuration in the esmtpacceptmailfor
configuration file.
esmtpacceptmailfor.dat and esmtpacceptmailfor.dir
esmtpacceptmailfor.dat is a binary database
file that lists additional domains that the Courier mail server accepts mail
for, just like esmtpacceptmailfor. The binary database file will be faster
than a flat text file with a large number of domains. The Courier mail server
accepts mail for domains listed in either esmtpacceptmailfor or
esmtpacceptmailfor.dat. esmtpacceptmailfor.dat is created by the
makeacceptmailfor command from the contents of the
esmtpacceptmailfor.dir directory. You can use both esmtpacceptmailfor.dat and
esmtpacceptmailfor at the same time. Put your most popular domains in
esmtpacceptmailfor, and put the rest of them into esmtpacceptmailfor.dat.
See the section called “Hostname-dependent configuration” for more
information on hostname-dependent configuration in the esmtpacceptmailfor.dir
configuration files.
esmtpauthclient
This configuration file configures ESMTP
authentication for the ESMTP client. This is a text file of zero or more lines
that contain the following fields:
When the Courier mail server connects to a remote ESMTP relay, the Courier mail
server will authenticate itself using userid and password. These fields are
separated by one or more whitespace characters. Because this file contains
passwords, it must not be world or group readable, and owned by the user
"courier".
ESMTP negotiation will take place, and the Courier mail server will use a SASL
authentication method supported by both the Courier mail server and the remote
ESMTP server. Currently the Courier mail server supports PLAIN, LOGIN and
CRAM-MD5 authentication. CRAM-MD5 is preferred over the other two, and PLAIN
is preferred over LOGIN.
The Courier mail server also supports ESMTP over SSL (the ESMTP STARTTLS
extension). If ESMTP STARTTLS is enabled, STARTTLS will be used to establish a
secure link first. The authentication will take place afterwards, over a
secure channel.
Changes to this file take effect, more or less, immediately (existing
connections are not affected, but new connections will read the updated
data).
esmtpd
relay userid password
This file is used to initialize the
environment and parameters for courieresmtpd. A default file will be
provided during installation. See the comments in the file for more
information. For changes to this file to take effect you run the esmtpd
stop command followed by esmtpd start.
esmtpdelay
This file contains one line of text that
specifies how long courieresmtp waits after a failure to contact the
remote mail server before another attempt is made. courieresmtp (not to
be confused with courieresmtpd) delivers outgoing mail to remote mail
servers. The timeout is specified as an integral number, optionally followed
by m - minutes, or h - hours. Otherwise it is specified in seconds.
The courieresmtp process delivers mail that's routed to external mail
relays, via ESMTP. When attempting to initally contact a mail server
courieresmtp waits for the amount of time specified by
esmtptimeoutconnect (see below). esmtptimeoutconnect is usually set to a
relatively long period of time, in order to accomodate slow mail servers. A
large number of messages queued up for an unreachable mail server can tie up
delivery slots that can be put to a better use by reassigning them for mail to
another domain. Although the Courier mail server does not usually assign all
delivery slots for messages to the same domain (this is a tuneable parameter),
it is still not very healthy to have a bunch of courieresmtp daemons
spinning their wheels, doing nothing.
The situation worsens when there is a large number of mail relays that accept
mail for the same domain, and all of them are unreachable due to a network
failure. That's because the esmtptimeout waiting period is used for each
individual mail relay. Multiply esmtptimeout by the number of servers to see
how large the delay really will be.
esmtpdelay is implemented internally in the courieresmtp module. The main
the Courier mail server scheduling daemon is not aware of what's happening
internally in courieresmtp. When courieresmtp fails to contact
any mail relay for the domain, the message is postponed, and the esmtpdelay
timer is set. Any additional messages received by the same courieresmtp
daemon (for the same domain), are immediately postponed without any attempt to
contact a remote mail relay. When the amount of time set by esmtpdelay
expires, courieresmtp will attempt to make another delivery attempt as
usual.
If esmtpdelay does not exist, the default delay is five minutes. Any messages
that are postponed look like any other temporary failure to courierd.
Delivery attempts are rescheduled as if a real temporary failure took place.
Therefore it does not make sense to set esmtpdelay to be greater than
retryalpha (see below). When retryalpha is smaller is esmtpdelay, you'll just
messages spinning through the mail queue, with useless delivery attempts being
attempted because esmtpdelay still hasn't expired.
Occasionally you might observe somewhat strange behavior on systems with heavy
mail traffic. esmtpdelay applies separately to each individual instance of
courieresmtp. When a remote mail server keeps going up and down, it is
possible to end up with multiple courieresmtp daemons handling mail for
the same domain, but only some of them will encounter a network failure,
purely by the luck of the draw. The remaining daemons will be able to
establish a connection. So you'll end up with some courieresmtp daemons
being able to deliver mail immediately, while the rest are still waiting
patiently for esmtpdelay to expire, postponing all messages in the meantime.
Some messages - but not all - will be immediately postponed without a delivery
attempt, becauses they ended up getting to a daemon which is waiting for
esmtpdelay to expire.
Another anomalous situation may happen when a courieresmtp daemon gets
reassigned to another domain, and then receives more mail for the previous
domain. This can happen when you have a lot of mail going through. Although
the Courier mail server tries to shuffle all mail for same domain into one
pile, the scheduler still tries to dispatch mail on "first-come,
first-serve" basis, as much as possible. When that happens another
delivery attempt will be made immediately, because the previous esmtpdelay was
cancelled when the daemon got reassigned to another domain.
There can also be occasional abnormalities that affect systems with light
traffic. When there is a domain with several mail relays of equal priority,
one mail relay is chosen at random for the connection attempt. If some of the
equal-priority mail relays are unreachable and a courieresmtp daemon
picks it, it will start the esmtpdelay timer and refuse to deliver any more
mail until it expires, even if most of the mail servers are functional. This
will happen only with mail relays of the lowest priority. Otherwise,
courieresmtp will always try to contact another mail relay of a still
lower priority, before giving up and setting the esmtpdelay timer. Another
courieresmtp daemon will not be started for the same domain if there's
already an existing one, so all delivery attempts will be turned away until
esmtpdelay expires. Another courieresmtp daemon will be started only in
the event of multiple simultaneous delivery attempts that happen to coincide
at the same time.
This is somewhat mitigated by the fact that all courieresmtp daemons are
killed after a short period of total inactivity (currently one minute), so
that longer intervals specified by esmtpdelay are ignored. Note, however, that
receiving a message to deliver, and then postponing it immediately, does count
as some activity.
esmtpdelay can be turned off by setting it to 0 seconds. esmtpdelay is designed
for servers that handle heavy amount of mail that wish to avoid having
outbound delivery slots tied up due to network failures, at an expense of an
occasional anomalous behavior due to harmless paranoia. esmtpdelay may prove
to actually make things worse for systems that carry only light mail traffic,
if they are burdened with a task of exchanging mail primarily with external
systems that are not properly maintained.
esmtpgreeting
The complete greeting banner displayed by
courieresmtpd. Changes to this file take effect immediately.
esmtphelo
This file contains one line of text, what the
Courier mail server calls itself in the EHLO or HELO command sent to a remote
SMTP server. me is used if this file does not exist.
esmtphelo may also be set to a special value of “*”:
(Note the single quotes, to prevent “*” from being expanded by the
shell). The Courier mail server will take the IP address of the local side of
the connection to the remote SMTP server, look up the IP address in DNS, and
use the hostname from the reverse DNS lookup. This might be useful when the
Courier mail server server is multihomed. The Courier mail server will look up
the local IP address of each individual connection, and use that in its EHLO
or HELO command.
Note
Functioning DNS is required. Using the hosts file, or an equivalent, won't work.
This function uses the Courier mail server's native DNS resolver, which reads
/etc/resolv.conf and queries the listed DNS servers directly.
Note
See the section called “Servers with multiple IP addresses” for a
better way of accomplishing the same results.
esmtproutes
echo '*' >esmtphelo
This file is used by the ESMTP module, and it
contains one or more lines in the following form:
domain is any SMTP domain. relay specifies a fixed mail relay for
this domain. relay is optionally followed by a comma and a port number,
to specify a port other than the default port 25. If an address's domain is
not found in esmtproutes, the Courier mail server looks for MX and A records
as usual (and always delivers to port 25). If the domain is found in
esmtproutes, however, any MX or A records for the domain are ignored; instead
the Courier mail server delivers the message to the specified relay.
relay can be another domain, or an explicit IP address inside brackets.
For example, if esmtproutes contains the following:
Mail for example.com is delivered to relay.domain.com, ignoring any MX records
for example.com. Mail for domain.com will be delivered to the machine at IP
address 192.168.0.2. All other domains will have their MX and A records looked
up.
Note
Unlike Qmail, the Courier mail server looks up MX and A records for
relay.example.com (Qmail only looks up A records).
esmtproutes may contain comments, any line that starts with the # character is
ignored. Also, wildcards are allowed:
This specifies that any address of the form
<[email protected]> will be delivered to the mail server at
this IP address, but on port 26.
esmtproutes is read from top to bottom, stopping as soon as a first match is
found.
domain may be empty, this specifies a smarthost for all domains. For example, if
esmtproutes contains the following text:
This specifies that all mail to example.com is rerouted to relay.example.com.
All other mail is routed to the IP address 192.168.0.4.
If relay is empty, the Courier mail server interprets it as an explicit
directive to use MX and A records from DNS. For example:
This uses MX and A records for all messages to example.com. All other mail is
rerouted to the IP address 192.168.0.4.
The /SECURITY=STARTTLS flag indicates that mail to this domain will use the
SECURITY ESMTP extension. See the Courier mail server installation notes for a
description of SECURITY, what it does, and how to configure it.
Note
/SECURITY=STARTTLS does not refer to the standard implementation of SMTP
over TLS, but a Courier-specific extension. Courier automatically sends mail
using encryption if it's enabled and the remote server advertises STARTTLS.
/SECURITY=SMTPS uses an encrypted SMTP connection. This is an alternative to
STARTTLS. Encrypted SMTP uses a different port, port 465, which must be
specified explicitly:
This example forwards all mail to relay.example.com on port 465 using encrypted
SMTP.
Note
If you intend to use /SECURITY=SMTPS to forward all your mail to your provider's
mail server over smtps additional you should also set
ESMTP_TLS_VERIFY_DOMAIN=1, TLS_VERIFYPEER=PEER, and TLS_TRUSTCERTS to a list
of trusted certificate authorities (Courier's configuration script should
provide a default value for TLS_TRUSTCERTS on most platforms), in the courierd
configuration file.
Otherwise, TLS still gets used to send mail, but the smarthost's certificate
does not get validated. Properly-managed Internet providers should install a
valid certificate, signed by a trusted authority, if they require SMTPS.
Poorly-managed Internet providers will just install a self-signed certificate,
and will not be able to explain why they require SMTPS, if it's trivially
compromised with a man-in-the-middle attack that a non-validated certificate
enables, so either find a more competent provider, or use /SECURITY=SMTPS
without actually enabling all the extra validation that's actually needed to
gain any kind of a secure mail transmission channel.
A combination of broken mail servers written by incompetent programmers, and
poorly-managed Internet providers will result in a mail server that advertises
the ability to use an encrypted connection to receive mail, but either
disconnect immediately, or return an error message when the sender takes up
the receiver's offer to do so.
When the Courier mail server connects to another server that claims to support
an encrypted connection, tries to enable it, then fails because the other mail
server drops the connection or returns an error message, all subsequent
connection attempts to the same mail server will ignore the server's false
advertising, and proceed to send mail without attempting to enable encryption.
The Courier mail server remembers not to use the encryption with this server
for the next 2-4 hours (depending on an internal log file's rotation
schedule). Once the remote mail server emerges from the penalty box, the next
connection attempt will try again, and see if it's still doesn't work.
The /SECURITY=REQUIRED flag blocks the Courier mail server from sending mail to
the remote server unless a standard encryped connection can get established.
If it's known that the given mail server should only receive encrypted mail,
/SECURITY=REQUIRED prevents a man-in-the-middle attack where the remote mail
server's advertisement of is STARTTLS capability gets suppressed, and the mail
gets sent in the clear.
Note
ESMTP_TLS_VERIFY_DOMAIN=1, TLS_VERIFYPEER=PEER, and TLS_TRUSTCERTS should also
be set, in the courierd configuration file, as described above, for the same
reasons, in this case.
To summarize:
/SECURITY=STARTTLS
Changes to esmtproutes take effect immediately, more or less. Existing
courieresmtp processes that already have an established connection will
ignore any changes.
esmtptimeout
domain:relay[,port][/SECURITY=STARTTLS][/SECURITY=REQUIRED][/SECURITY=SMTPS]
example.com: relay.domain.com domain.com: [192.168.0.2]
.example.com: [192.168.0.3],26
example.com: relay.example.com
:[192.168.0.4]
example.com: :[192.168.0.4]
: relay.example.com,465 /SECURITY=SMTPS
Courier-specific extension, use a private
certificate authority to set up a secure mail network, while supporting
regular encrypted TLS with the rest of the world.
/SECURITY=SMTPS
Use regular encrypted SSL/TLS with this mail
server. Use this flag with an esmtproutes entry to a server on port 465
(smtps).
/SECURITY=REQUIRED
Must use the STARTTLS extension to open a
regular encrypted TLS connection with this server on the regular SMTP port
25.
This file contains one line of text that
specifies the timeout for an SMTP command. The timeout is specified as an
integral number, optionally followed by m - minutes, or h - hours. Otherwise
it is specified in seconds. This timeout is used for all SMTP commands, unless
the SMTP command has a dedicated timeout defined by a different configuration
file. The default timeout is ten minutes.
esmtptimeoutconnect
This file contains one line of text that
specifies the timeout for an SMTP connection attempt. Most TCP/IP stacks wait
an extraordinary long period of time for SMTP connections to go through. This
configuration setting limits the amount of time the Courier mail server waits
for the SMTP connection to complete. The default timeout is one minute. Set
esmtptimeoutconnect to 0 in order to use whatever default timeout your TCP/IP
stack uses.
esmtptimeoutdata
This file contains one line of text that
specifies the timeout for transferring the message contents or individual
replies. The default timeout is five minutes. You WILL HAVE TO bump this up if
you're on a slow link, and you want to send large messages. A 28.8Kbps link
can be optimistically expected to push 3,000 bytes per second. With a five
minute cutoff, you will not be able to send or receive anything larger than
about 870 Kb. You have no business sending or receiving 870 Kb messagesl, if
all you have is an analog 28.8Kbps connection.
esmtptimeouthelo
This file contains one line of text that
specifies the timeout for the initial EHLO or HELO command. The Courier mail
server will wait this amount of time to receive the initial greeting banner
from the remote SMTP server, and a response to the subsequent EHLO/HELO
command. The default value is 5 minutes.
esmtptimeoutkeepalive
This file contains one line of text that
specifies how often outbound SMTP sessions are kept idle after delivering a
message. After the Courier mail server connects to an SMTP server and
completes the attempt to deliver the message, the SMTP session is kept idle
for this time interval before being shut down. If the Courier mail server
receives another message for the same domain, it will be delivered using the
existing SMTP session, instead of establishing a new one. Note that some SMTP
servers have a very short idle timeout, Qmail's is only two minutes. The
default value is 60 seconds.
Note that there's also a separate limit to the maximum number of simultaneous
SMTP sessions to the same domain. That limit is currently four, which is
adequate for nearly every situation, so for now it will be set by an
undocumented configuration file.
esmtptimeoutkeepaliveping
This file contains one line of text that
specifies how often the Courier mail server will issue a useless RSET command
when the connection is idle (see esmtptimeoutkeepalive). While waiting for any
more messages to deliver to the same domain, or for the esmtptimeoutkeepalive
interval to expire, courieresmtp will transmit RSET commands at regular
intervals specified by this configuration file. The default value is 0
seconds, which turns off the keepalive ping altogether. This configuration
settings must be for a shorter time interval than esmtptimeoutkeepalive for it
to make any sense. Note that other system administrators may consider this to
be a very rude thing to do. Also keep in mind that this may generate quite a
bit of idle traffic. If you have the Courier mail server configured for a
maximum number of 200 outbound SMTP sessions and a 30 second
esmtptimeoutkeepaliveping setting, then you can have as much as an average of
around seven pings every second!
esmtptimeoutquit
This file contains one line of text that
specifies how long the Courier mail server waits for the external SMTP server
to acknowledge the QUIT command, before the Courier mail server unilaterally
tears down the connection. The default value is 10 seconds. This must be a
small value because the Courier mail server needs to be able to shut down
quickly, on very short notice.
faxqueuetime
This file specifies how long the Courier mail
server normally tries to repeatedly resend a fax message (if the courierfax
module is enabled). The default E-mail message retry timeout (the queuetime
setting) is one week, which is a reasonable timeout value for E-mail messages
(taking into account downed circuits, or crashed servers). However, it doesn't
make sense to keep trying to redeliver fax messages for a whole week.
faxqueuetime specifies the timeout for fax messages. This time interval is
specified in the same way as queuetime (see queuetime for more
information).
faxnotifyrc
This file specifies which mailbox the Courier
mail server should deliver received faxes (if this option is enabled). See the
Courier mail server's installation notes for more information.
faxrc
This file configures the Courier mail server's
outbound faxing and dialing parameters. Consult the comments in the default
file for additional information, and the courierfax(8)[7] manual
page for more information.
hosteddomains
This file lists locally-hosted domains. It is
very similar in function to the locals control file. Any address with a domain
listed in hosteddomains is considered to be a local address. The difference
between hosteddomains and locals is that domains listed in hosteddomains are
not removed from individual addresses before looking up the location of their
mailboxes. For example, if the domain "example.com" appears in
locals, the address [email protected] will have example.com removed, and then
the Courier mail server will look for a local mailbox named "user".
If the domain "example.com" appears in hosteddomains instead, the
Courier mail server will look for a local mailbox named
"[email protected]" instead.
The contents of the hosteddomains configuration file is a list of domains, one
per line, in lowercase. You must run the makehosteddomains command,
followed by courier restart (this restarts the server) for any changes
to take effect.
Additionally, hosteddomains can specify simple domain aliases. See the complete
description in the makehosteddomains(8)[8] manual page.
See the section called “Hostname-dependent configuration” for more
information on hostname-dependent configuration in the locals configuration
file.
ipout, ip6out
Non-default IP addresses to send outgoing
ESMTP messages from. See the section called “Servers with multiple IP
addresses” and the section called “Simulating a server with
multiple IP addresses”, below, for more information.
ldapaddressbook
This file is used by the webmail server. It
contain a default systemwide list of accessible LDAP address books. A default
file will be installed, listing some common Internet address books. Each line
in this file contains the following information:
"<tab>" is the ASCII tab character. “name” is the
unique name for this LDAP server. “host” and
“port” specify the connection parameters. “suffix”
specifies the root LDAP entry whose subtree gets searched. The
“binddn” and “bindpw” fields are not presently
used (they were used in earlier version of the webmail server, before the LDAP
search interface was rewritten and simplified).
ldapaliasrc
name<tab>host<tab>port<tab>suffix<tab>binddn<tab>bindpw
This file is used by the courierldapaliasd
process. See courierldapaliasd(8)[9] for more information.
locallowercase
If this file exists, the Courier mail server
will not distinguish being lowercase and uppercase local accounts, so that
[email protected] and [email protected] will refer to the same local mailbox
(where example.com is your domain). Postmaster, postmaster, and POSTMASTER
always refer to the same account, even if locallowercase does not exist.
Note
If locallowercase exists you cannot have any system accounts that contain
uppercase letters. locallowercase applies only to local mail. Mail addressed
to external domains will always have the case of the addresses preserved.
locals
This file contains one or more lines of text,
where each line contains a valid mail domain. Any E-mail address without
@domain, or with a domain that can be found in locals will be considered to be
an address of a local mailbox. A domain can be specified with a leading dot:
This is called a "wildcard". Any domain ending in domain.com, such as
a.domain.com, b.domain.com, a.b.c.domain.com - but NOT somedomain.com - will
be considered local. Note that domain.com is NOT included in this wildcard.
Both "domain.com" and ".domain.com" should be listed.
Specific hosts can be excluded from the wildcard. Example:
anything.domain.com is considered to be a local domain, except for
host.domain.com. Note that "!host.domain.com" must appear in locals
before the .domain.com wildcard.
The "!hostname" syntax is also valid in the esmtpacceptmailfor control
file.
If locals does not exist, the Courier mail server uses the contents of the me
control file (note that me specifies only one domain, second and subsequent
lines are ignored). Also, see hosteddomains.
See the section called “Hostname-dependent configuration” for more
information on hostname-dependent configuration in the locals configuration
file.
localtimeout
.domain.com
!host.domain.com .domain.com
This file specifies the watchdog timer for
local mail deliveries. If a local mail delivery attempt does not complete in
the proscribed time interval, the delivering process ID is killed. The time
interval in localtimeout is specified in the same way as queuetime (see
queuetime for more information).
logindomainlist
If this file exists then the webmail login
screen will have a drop-down list whose contents will be read from this file.
This file should contain a list of E-mail domains, one per line. It should be
created if the Courier mail server's webmail server is used to provide mail
access for more than one domain. Instead of typing "user@domain" to
log in, it will only be necessary to enter "user", and select the
domain from the drop-down list. If this file does not exist it will be
necessary to enter the full E-mail address into the webmail login screen. The
enhanced logindomainlist makes it possible to specify a separate list of
domain for each virtual web site, and more control over the defaults.
What if you don't want to display a drop down menu? Administrators can now
specify records that generate a hidden field in login.html, or an editable
text field, allowing sqwebmail to show only one mail login domain to each user
per access URL or IP address. This functionality can greatly reduce confusion
for first time webmail users, and greatly speed the login process for frequent
webmail users.
Finally, the new logindomainlist file offers a new tool to ease maintenance.
Administrators can now use wildcards to "rewrite" the domain portion
of the access URL to the mail domain equivalent. For example, the following
record can rewrite the URL "mail.*.com" to the mail domain
"*.com"
*.com:mail.*.com:@
This powerful wildcard functionality can ease the login process for most of your
server's mail domains with just one or two logindomainlist records.
File Format
maildirfilterconfig
Let's take a look at the NEW logindomainlist
file format:
firstfield:secondfield:thirdfield
Above, we can see that the new logindomainlist records are made up of three
fields delimited by colons. But what does each field do?
First Field - the first field contains the "mail domain" for which we
would like the user to log in under. The mail domain is the part of an email
address after the @ symbol. For example, in the email address
"[email protected]", "domain.com" is the mail domain.
Second Field - the second field contains the "access domain". The
access domain contains an URL or IP address that is used to figure out which
mail domain to use by default. For example, in the following logindomainlist
record:
domain1.com:domain2.com
"domain2.com" is the "access domain" and
"domain1.com" is the "mail domain". If the user logs into
the following URL:
http://domain2.com/cgi-bin/sqwebmail
His default "mail domain" will be "domain1.com".
Third Field - the third field may contain a modifier. The modifier may be either
a single character modifier, or a group identification string. The single
character modifiers and the group modifier are described in detail below.
Finally, the logindomainlist file may also contain comments and empty lines.
Empty lines can be used to group records visually, and comments can be used to
explain why a certain record or group of records look the way they do.
If the first character of a line is a '#', then the entire line is considered a
comment and is ignored. If the first character of a line contains whitespace,
the entire line is assumed to be an empty line and is ignored.
Modifiers
@ - the '@' modifier can be used to create a
hidden field on the login.html page which contains the default mail domain. In
addition, this field will automatically display the default mail domain in
plain text to the right of the userid text box.
Note
The '@' modifier ALLOWS the use of wildcards to automate the relationship
between "access domains" and "mail domains". See the
heading " Wildcards" below for more information about
wildcarding.
- - the '-' modifier can be used to create an editable text field on the
login.html page which contains the default mail domain.
Note
The '-' modifier ALLOWS the use of wildcards to automate the relationship
between "access domains" and "mail domains". See the
heading " Wildcards" below for more information about
wildcarding.
group string - If no modifier is specified in the third field, or if the third
field modifier is a group identifier string, then a drop down menu will be
displayed on the login.html page. Records with the SAME group string will be
displayed together in the drop down. For example, if your logindomainlist file
contains the following records:
And the user logs into sqwebmail with the following URL:
http://domain4.com/cgi-bin/sqwebmail
He will see a drop down containing ONLY the following domains:
"domain3.com" will be automatically selected, or defaulted. Only the
records in the firstgroup will be visible to the user. This functionality is
great for organizations with more than one mail domain.
Note
The group string modifier does NOT allow the use of wildcards to automate the
relationship between "access domains" and "mail domains".
This is because drop down menus are fundamentally incompatible with wildcards.
Wildcards
domain1.com:domain2.com:firstgroup
domain3.com:domain4.com:firstgroup
domain5.com:domain6.com:firstgroup
domain7.com:domain8.com:secondgroup
domain9.com:domain10.com:secondgroup
domain1.com
domain3.com
domain5.com
If a record's modifier allows wildcarding (See
" Modifiers" above for information about which modifiers
allow wildcarding and which do not.) then the first and second fields of that
record _MAY_ contain wildcards. Wildcards match against the HTTP_HOST CGI
environment variable only. IP addresses can NOT be used if either the first or
second fields contain the wildcard character. However, if neither the first
nor second fields contain the wildcard character, then the second field can
contain an IP address.
In the logindomainlist file, an asterisk (*) character in either the first
and/or second field represents a wildcard. Any asterisk in the second field
will be used to match an access domain. If an asterisk exists in the first
field then any characters which the asterisk in the second field represents
will replace the asterisk in the first field when sqwebmail determines the
default mail domain. However, asterisks are not required in either the first
or second fields. They are totally optional. For example, given the following
logindomainlist record:
*.com:mail.*.com:@
If the user logs into sqwebmail with the following URL:
http://mail.mydomain.com/cgi-bin/sqwebmail
The asterisk in the second field will represent the string "mydomain".
This string will then replace the asterisk in the first field to give the
following default mail domain: mydomain.com
Similarly, if the following record exists in the logindomainlist file:
*:*:@
Then ANY URL the user uses to access sqwebmail will be automatically used for
the default mail domain.
But the first field doesn't _HAVE_ to contain an asterisk. The following will
work just fine:
mydomain.com:mydomain.*:@
The above example will allow the user to access the "mydomain.com"
mail domain from any of the following URLs: "mydomain.org",
"mydomain.net", "mydomain.us", etc...
And finally, the first field doesn't have to contain anything at all! If the
first field is empty, that record will serve as an explicit no-default mail
domain. No default mail domain will be specified if the second field matches
the user's login URL. This is useful because the logindomainlist is searched
from the top down. Any wildcard records at the bottom of the list will be
overridden by records closer to the top. An "explicit no-default"
record can be used to specify certain domains as "system account"
domains so that no default mail domain is specified.
This file, if exists, sets the global defaults
for mail filtering in the webmail server. Mail filtering in the webmail server
is a subject worthy of special mention. A full description of how to install
and configure webmail-based mail filtering is included in the installation
notes for the Courier mail server. Refer to the installlation instructions for
additional information.
maildirshared
This file, if exists, specifies the location
of shared maildirs for the webmail and IMAP server. Normally, each mailbox
must be separately configured to access every shared maildir, by the
maildirmake(1)[10] command. This file allows shared maildirs to
be set globally for everyone. Everyone's webmail and IMAP server will pick up
the shared maildirs specified in this file. See
maildirmake(1)[10] for more information.
maildrop
This file contains one line whose contents is
a pathname to the maildrop(1)[6] mail delivery agent. If the
Courier mail server knows that the delivery agent used to delivery mail
locally is maildrop(1)[6] then certain delivery optimizations
are possible. This configuration file does NOT actually specify that
maildrop(1)[6] should be used as a local mail delivery agent, it
only specifies where maildrop(1)[6] is installed. The default
local mail delivery instructions are specified in the courierd configuration
file. If the specified delivery instruction specify running an external
program whose pathname matches the one specified by this configuration file,
the Courier mail server assumes that it's maildrop(1)[6], and
will use maildrop-specific options to optimize mail delivery.
This configuration file is initialized, by default, to point to the version of
maildrop(1)[6] that's integrated with the Courier mail server.
The integrated version of maildrop(1)[6] is configured slightly
differently than the standalone version of maildrop(1)[6].
Although you can set the maildrop configuration file to point to some other
version of the maildrop mail filter, you MUST set the maildropfilter
configuration file (see below), to point to the integrated version of
maildrop.
maildropfilter
This file contains one line whose contents is
a pathname to the maildrop(1)[6] mail delivery filter. In
addition to being a delivery agent, maildrop can also be used as a mail
filtering engine. If this file exists, the Courier mail server will be capable
of invoking recipient-specified mail filters when a message is received. If
the mail filtering rules reject the message, the Courier mail server will not
accept the message for delivery. This means that when receiving mail via
ESMTP, the Courier mail server will reject the ESMTP transaction without even
accepting the message from the remote mail server.
This file is not installed by default. To activate mail filtering for local
recipients, simply copy the contents of the maildrop configuration file to
maildropfilter.
maildroprc
This file contains systemwide mail filtering
instructions for maildrop(1)[6] deliveries. This configuration
file is optional, and is used by maildrop(1)[6] when it is
invoked as a traditional post-delivery mail filter. See
maildropfilter(6)[11] for more information.
me
This file contains one line whose contents is
a fully-qualified domain name. When a single installation of the Courier mail
server is shared over a network, each machine that's running the Courier mail
server must have a unique me file. A missing me defaults to the
gethostname() system call (see the section called
“Hostname-dependent configuration” for more information on
hostname-dependent configuration).
Warning
Changing me requires rerunning the makealiases command again, else mail
can bounce. Without this configuration file defined changing the system's
hostname also requires rerunning makealiases.
msgidhost
If a message does not have a Message-ID:
header, the Courier mail server may decide to create one. The host portion of
the new header will be set to the contents of msgidhost, which contains one
line of text. If msgidhost does not exist, me will be used in its place.
Changes to this file take effect immediately.
nochangingfrom
The Courier mail server's webmail server lets
the contents of the From: header be set for mailed messages. If this
configuration file exists, the ability to set the contents of the From: header
is disabled.
queuelo, queuehi, queuefill
These configuration settings tune the Courier
mail server's mail queue processing. The Courier mail server does not load the
entire mail queue metadata in memory. queuelo contains a number that specifies
the queue “low watermark” message count. queuehi contains a
number that specifies the queue “high watermark” message count.
queuefill specifies a time interval, “queue refill” in seconds.
The number in queuefill may optionally be followed by "m",
indicating that the queue refill is specified in minutes.
queuehi specifies the maximum number of messages that are loaded into memory.
The Courier mail server reads the mail queue on disk until either it reads all
of it, or it reads the number of messages specified by queuehi. As messages
are delivered they are removed from the memory and disk. Messages that are
deferred for another delivery attempt are removed from memory, but kept on the
disk.
When the number of messages in memory falls below queuelo, The Courier mail
server goes back to disk and attempts to fill the memory queue to the top,
again.
This is, basically, a capsule summary of the mail queue processing logic. Many
small, low level details are omitted; this is just an executive overview. When
new messages arrive during a large mail backlog, the new messages are also
loaded into the memory queue, if there's room for them. Therefore, during a
large mail backlog the Courier mail server simultaneously tries to clear the
existing backlog, and process any new mail at the same time. Up to the Courier
mail server 0.41, all of this generally translates to the Courier mail server
giving priority to newly arrived mail, and processing the backed up mail queue
if spare resources are available.
The queuefill setting was added in the Courier mail server 0.42, in an attempt
to keep new mail from excessively delaying existing mail during a major queue
backup. queuefill specifies a time interval. When the Courier mail server
completely fills the memory queue it sets a timer. After the interval given by
queuefill The Courier mail server will go back and re-fill the mail queue even
if the number of messages did not fall below the low watermark. If the Courier
mail server finds older messages in the mail queue they will be pushed to the
top of the scheduling queue, and given priority.
Smaller queuefill time intervals means more frequent trips to the disk, and more
overhead. But, in exchange for that, during a mail backlog the Courier mail
server will spend more time handling a greater number of delayed messages.
Larger queuefill time intervals means less frequent trips to the disk, and
less overhead, in exchange for less "fairness" during large mail
backlogs.
queuefill defaults to five minutes, if not specified. Explicitly setting it to 0
seconds turns off the queue re-filling completely, essentially reverting to
pre-0.42 behavior. The default queuelo and queuehi values are computed at run
time. queuelo defaults to the larger of 200, and the sum total of configured
mail delivery slots, both local and remote. queuehi, if not explicitly set,
defaults to the smaller of twice the queuelo, or queuelo plus 1000.
queuetime
This file specifies how long the Courier mail
server normally tries to repeatedly deliver a message, before giving up and
returning it as undeliverable. Messages are immediately returned as
undeliverable when a permanent failure is encountered (such as the recipient
address not being valid). Attempts to deliver the message when there's a
temporary, transient, error (such as the network being down) will be
repeatedly made for the duration of time specified by this configuration file.
This file contains a number followed by the letter 'w' for weeks, or 'd' for
days. It is also possible to use 'h' for hours, 'm' for minutes, or 's' for
seconds. Only integers are allowed, fractions are prohibited. However, you can
use '1w2d' to specify one week and two days. If queuetime is missing, the
Courier mail server makes repeated delivery attempts for one week.
retryalpha, retrybeta, retrygamma, retrymaxdelta
These control files specify the schedule with
which the Courier mail server tries to deliver each message that has a
temporary, transient, delivery failure. retryalpha and retrygamma contain a
time interval, specified in the same way as queuetime. retrybeta and
retrymaxdelta contain small integral numbers only.
The Courier mail server will first make retrybeta delivery attempts, waiting for
the time interval specified by retryalpha between each attempt. Then, the
Courier mail server waits for the amount of time specified by retrygamma, then
the Courier mail server will make another retrybeta delivery attempts,
retryalpha amount of time apart. If still undeliverable, the Courier mail
server waits retrygamma*2 amount of time before another retrybeta delivery
attempts, with retryalpha amount of time apart. The next delay will be
retrygamma*4 amount of time long, the next one retrygamma*8, and so on.
retrymaxdelta sets the upper limit on the exponential backoff. Eventually the
Courier mail server will keep waiting retrygamma*(2^retrymaxdelta) amount of
time before making retrybeta delivery attempts retryalpha amount of time
apart, until the queuetime interval expires.
The default values are:
retryalpha
This results in the Courier mail server delivering each message according to the
following schedule, in minutes: 5, 5, 5, 15, 5, 5, 30, 5, 5, 60, 5, 5, then
repeating 120, 5, 5, until the message expires.
sizelimit
Five minutes
retrybeta
Three times
retrygamma
Fifteen minutes
retrymaxdelta
Three
Maximum size of the message, in bytes, that
the Courier mail server accepts for delivery. The Courier mail server rejects
larger messages. If sizelimit is set to zero, The Courier mail server accepts
as large message as available disk space permits. If the environment variable
SIZELIMIT is set at the time a new message is received, it takes
precedence and the Courier mail server uses the contents of the environment
variable instead. Changes to this file take effect immediately. The
SIZELIMIT environment variable is for use by individual mail submission
agents. For example, it can be set by the smtpaccess configuration file (see
makesmtpaccess(8)[3] for more information) for mail from certain
IP addresses.
If sizelimit does not exist, and SIZELIMIT is not set, the maximum
message size defaults to 10485760 bytes.
submitdelay
submitdelay specifies the delay before the
first delivery attempt for a message that has been entered into the mail
queue. Normally, the first delivery attempt is made as soon as possible. This
setting delays the initial delivery attempt. It is normally used when you have
a mail filter installed that detects duplicate messages arriving in a short
period of time. If the mail filter detects this situation it can use the
cancelmsg(1)[12] command to reject duplicate messages in the
queue (and return them back to the envelope sender).
submitdelay specifies a time interval in the same format as queuetime.
usexsender
If this configuration file exists, the Courier
mail server's webmail server will set the X-Sender: header on all outgoing
messages. This is a good idea if the webmail server allows the user to set the
contents of the From: header. Note that the Courier mail server records the
system userid of the sender in all locally-sent messages (which includes
messages mailed by the webmail server), which is sufficient in most cases. In
cases where you have many virtual accounts that share the same system userid,
this configuration file provides a way to positively identify the sender of
the outgoing message.
uucpme
uucpme sets the UUCP nodename of the Courier
mail server mail relay. See courieruucp(8)[13] for more
information.
uucpneighbors
uucpneighbors is used by the
courieruucp module to specify the Courier mail server's configuration
for relaying mail via UUCP. See courieruucp(8)[13] for more
information.
uucprewriteheaders
If this file exists, headers of messages sent
to/from UUCP addresses will be rewritten. Normally, only the message envelope
sender and recipients are rewritten, the existence of this file causes the
headers to be rewritten as well.
vhost. ip-address, vhost.domain
Enable per-message virtual configuration
settings described in the section called “Servers with multiple IP
addresses” and the section called “Simulating a server with
multiple IP addresses”, below, for more information.
warntime
warntime specifies an amount of time in the
same format as queuetime. If a message still has not been delivered after this
period of time, the Courier mail server sends a warning message (a
"delayed" Delivery Status Notification) to the sender. If warntime
is missing, the Courier mail server sets warntime to four hours.
Note
The time interval specified by warntime is only approximate. The Courier mail
server sends a delayed Delivery Status Notification at the conclusion of the
first attempted delivery after warntime has elapsed.
Hostname-dependent configuration
This section describes how to set the various domain-related parameters incorporating the server's system-specified hostname. This makes it possible to create a canned, boilerplate set of Courier configuration files. The configuration files then get replicated, as is, to multiple servers. These servers have their system hostname externally managed, often via DHCP. The server's assigned hostname gets automatically incorporated into Courier's configuration. meWhen the contents of the me configuration file
begin with “*.”, the asterisk gets replaced by the system's
hostname. For example:
Note
A fully-qualified system hostname does not require an explicit me configuration
file. If me configuration file doesn't exist it defaults to the entire (fully
qualified) system hostname.
locals, esmtpacceptmailfor/esmtpacceptmailfor.dir and hosteddomains
•me contains:
*.example.com
•The system's assigned hostname is
“mx1”.
•The effective contents of the me
configuration file is “mx1.example.com”
When a line in these configuration files is
“*” or begins with “*.”, the asterisk gets
replaced by the system's hostname. For example:
•A line in locals contains:
*.example.com
•The system's assigned hostname is
“mx1”.
•This line in the locals configuration
file is effectively equivalent to “mx1.example.com”
•A line in hosteddomains contains:
*
•The system's assigned hostname is
“mx1.example.com”.
•This line in the hosteddomains
configuration file is effectively equivalent to
“mx1.example.com”
Webmail template files
HTML output from the webmail server is generated from the template files in /usr/lib/courier/sqwebmail/html/en-us. It is possible to translate the webmail interface into another language simply by creating another subdirectory underneath /usr/lib/courier/sqwebmail/html, then meticulously translating each .html file. Each template file contains well-formed HTML, with dynamic content marked off by tags. Note that the large comment blocks in each HTML file need to be translated too, since they are inserted as dynamic content, elsewhere. The directory /usr/lib/courier/sqwebmail/html/en-us also contains several configuration files, in addition to the HTML template files. Doing so allows this configuration information to be defined for each available language. CHARSETThis file consists of a single line of text,
which names the character set used by the HTML template files. It is possible
to specify multiple character set, by separating them with commas, provided
that HTML templates use only the common portions of all listed character set.
The default English HTML templates use strictly the “us-ascii”
subset, and the CHARSET contains utf-8,iso-8859-1. When multiple character
sets are listed, the first character set that's supported by the browser is
picked, so with UTF-8 capable browsers the default webmail interface will use
UTF-8, falling back to ISO-8859-1 for browsers that do not support
UTF-8.
footer
The contents of this file, if it exists, are
appended to all messages sent by the webmail server.
ISPELLDICT
This file consists of a single line of text,
which contains the name of the dictionary used for spell-checking. It is
passed as an argument to ispell, or aspell.
LANGUAGE
This file consists of a single line of text,
which should always be the same as the name of its directory (en-us).
LANGUAGE_PREF
This file is not needed at runtime, its
contents are used during installation. See webmail/html/README_LANG in the
source distribution for more information.
LOCALE
The corresponding C locale for these
templates.
TIMEZONELIST
This file lists the available timezones on the
login screen. See the comments in this file for more information.
Sender Policy Framework Keywords
The Courier mail server can perform “Sender Policy Framework” checks on up to three addresses for each message. This is controlled by setting the following variables: BOFHSPFHELO, BOFHSPFMAILFROM, and BOFHSPFFROM. Each variable is set to a comma-separated list of the following keywords: “off” - SPF verification disabled (default); “none”, “neutral”, “pass”, “fail”, “softfail”, “error”, “unknown” - these keywords correspond to the possible results of an SPF check, the message is accepted for the listed SPF results only, any other SPF result is rejected; “all” - shorthand for all possible SPF results, use “all” to run SPF in informational mode only, recording the SPF status in the Received-SPF: header; “allowok” - automatically pass the SPF verification if the sender's IP address is found in a DNS access whitelist, any whitelist given in the -allow option to couriertcpd, see the “DNS ACCESS LISTS” section in couriertcpd(1)[14]. A rejected SPF result gets kicked back with a permanent error indication if the SPF result is listed in BOFHSPFHARDERROR, and a temporary error indication otherwise. When enabling SPF checking, the keyword list should always include “pass” (it makes no sense to do otherwise) and “none”. The keyword list should also include “softfail”, “neutral”, and “unknown”. See the SPF draft for a description of these status results. At some distant future, the keyword list will only include “pass”, rejecting all senders without a stated policy. This might be desirable at some point in the future, but not right now. The BOFHSPFFROM list may also include an additional keyword, “mailfromok”. BOFHSPFMAILFROM and BOFHSPFFROM are trade-offs. Using BOFHSPFMAILFROM is faster, and it does not require the entire message to be received, before running the SPF check. BOFHSPFFROM checking can only occur after the entire message is received, but it's more reliable. If “mailfromok” is listed, the From: is not checked if the MAIL FROM command was checked with the “pass” result. In other words: the From: header is checked if MAIL FROM was empty, or did not pass the SPF checks. If MAIL FROM passed the SPF check the Courier mail server won't bother looking at the From: header.Servers with multiple IP addresses
The Courier mail server's default configuration listens on port 25 on all IP addresses. If the server has more than one IP address, Courier accepts connections on any IP address. Adjust the settings in the esmtpd configuration file to explicitly list which IP addresses Courier should listenson. This also applies to the ESMTP over SSL server on port 465 configured by esmtpd-ssl, and the MSA server on port 587, configured by esmtpd-msa. That's for incoming EMSTP. For outgoing ESMTP connections, the Courier mail server does not specify an IP address by default, and lets the server select one. The server selects a default IP address based on a server's network configuration. The selection criteria is platform specific, and is typically based on the system's IP routing tables. The ipout and ip6out configuration files set an explicit IP address for Courier's outgoing connections:# echo "192.168.0.1" >/etc/courier/ipout # echo "fec0::230:48ff:fec4:429c" >/etc/courier/ip6out
# touch >/etc/courier/vhost.192.168.0.1 # touch >"/etc/courier/vhost.fec0::230:48ff:fec4:429c"
# echo "192.168.0.1" >/etc/courier/ipout.192.168.0.1 # echo "192.168.1.1" >/etc/courier/ipout.192.168.1.1
# touch /etc/courier/ipout.192.168.0.1 # touch /etc/courier/ipout.192.168.1.1
•The IPv4 address and the IPv6 address
for outgoing ESMTP connections get specified by the contents of
/etc/courier/ipout. address and /etc/courier/ip6out. address,
respectively.
•If the file exists, but is empty, the
same address becomes the IP address for the outgoing connection.
•The above rules are in effect only if
/etc/courier/vhost. address exists,
•If the file does not exist, or if
/etc/courier/vhost. address does not exist, the contents of
/etc/courier/ipout, for IPv4 connections, and /etc/courier/ip6out, for IPv6
connections set the IP address.
•Otherwise, the Courier mail server
uses the default IP address determined by the system's network
configuration.
•In /etc/courier/ipout. address
and /etc/courier/ip6out. address, an address of "0" also
specifies the system's default IP address.
It is possible for the Courier mail server to receive a message from an IPv6
connection, and forward it to an IPv4 address, or vice versa. The
address portion of /etc/courier/ipout. address and
/etc/courier/ip6out. address, specifies the IP address the client used
to connect to Courier and may be either an IPv4 or an IPv6 address, in both
cases! For example:
# echo "192.168.0.1" >/etc/courier/ipout.192.168.0.1 # echo "fec0::230:48ff:fec4:429c" >/etc/courier/ip6out.192.168.0.1
# echo "192.168.0.1" >"/etc/courier/ipout.fec0::230:48ff:fec4:429c" # echo "fec0::230:48ff:fec4:429c" >"/etc/courier/ipout.fec0::230:48ff:fec4:429c"
# echo "relay.example.com" >/etc/courier/me.192.168.0.1 # echo "firewall.example.com" >/etc/courier/me.192.168.1.1
Simulating a server with multiple IP addresses
As described in the previous section, the existence of vhost. ip-address enables configuration settings only for messages that were received at one of the IP addresses that the Courier mail server accepts connections on. It's possible to partially achieve the same end results by creating vhost. domain:# touch >/etc/courier/vhost.example.com
# echo '192.168.0.1' >/etc/courier/ipout.example.com
•The Courier authentication library
(see installation instructions) must be configured with accounts and mailboxes
that follow the “user@domain” format.
•Not all configuration settings can be
customized in a setting.domain. The trivial example would be the
ESMTP server banner. The mail server emits the banner before it's ready to
receive the first message, so no return address-based customization is
possible, of course, to select an ESMTP server banner. Additionally, the
“me” configuration setting gets set before the return address is
received, so the contents of a domain-specific “me” may not be
in effect in all contexts.
•Anyone can use any return address they
wish. Some mitigation is possible, of course, using measures such as SPF, but
it would be mistake to believe that this is much more than just eye
candy.
•Both an IP address and domain-based
“vhost”s are allowed. An IP address-based vhost takes
precedence.
BUGS
Flushing a single message will not work if the message queue is backed up. When that happens, your only available option is to flush the entire queue. courier start fails if the Courier mail server has detected a fatal operational error. In this situation the top-level courierd daemon sleeps for a minute, before automatically restarting. During this sleep interval courier stop does not work.SEE ALSO
cancelmsg(1)[12], maildirmake(1)[10], maildrop(1)[6], preline(1)[15], sendmail(1)[16], testmxlookup(1)[17], dot-courier(5)[4], authlib(7)[18], courierfax(8)[7], courierfilter(8)[5], filterctl(8)[5], courierldapaliasd(8)[9], courierpop3d(8)[19], courierpop3d(8)[19], couriertcpd(8)[14], courieruucp(8)[13], esmtpd(8)[20], imapd(8)[21], localmailfilter(7)[2], mailq(1)[1], makeacceptmailfor(8)[22], makealiases(8)[23], makehosteddomains(8)[8], makepercentrelay(8)[24], makesmtpaccess(8)[3], makeuserdb(8)[25], pw2userdb(8)[25], mkdhparams(8)[26], mkesmtpdcert(8)[27], mkimapdcert(8)[28], pop3d(8)[29], submit(8)[30], userdb(8)[31].AUTHOR
Sam VarshavchikAuthor
NOTES
- 1.
- mailq(1)
- 6.
- maildrop(1)
- 10.
- maildirmake(1)
- 12.
- cancelmsg(1)
- 13.
- courieruucp(8)
- 14.
- couriertcpd(1)
- 15.
- preline(1)
- 16.
- sendmail(1)
- 17.
- testmxlookup(1)
- 18.
- authlib(7)
- 19.
- courierpop3d(8)
- 20.
- esmtpd(8)
- 21.
- imapd(8)
- 23.
- makealiases(8)
- 25.
- makeuserdb(8)
- 26.
- mkdhparams(8)
- 27.
- mkesmtpdcert(8)
- 28.
- mkimapdcert(8)
- 29.
- pop3d(8)
- 30.
- submit(8)
- 31.
- userdb(8)
| 12/18/2020 | Courier Mail Server |