Courier 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 Courier processes and
aborts all current mail deliveries.
"courier restart" restarts the Courier 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) command.
Please note that courier start runs the main Courier
scheduling engine only. It does not start any other daemons that you may
have, such as the ESMTP or the IMAP daemon.
"CONFIGURATION FILES"
Courier 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.
aliasfilteracct
This 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) for more
information.
Due to technical limitations, content filtering is not available for
multiple-recipient aliases.
Changes to this file take effect immediately.
authdaemonrc
This file configures the authdaemond authentication proxy.
See
authlib(7)
for more information.
authldaprc
This file configures LDAP authentication. See
authlib(7)
for more information.
authmysqlrc
This file configures MySQL authentication. See
authlib(7)
for more information.
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:
"Cnnn" or
"Snnn" (or both strings, on the same line). Cnnn: allow up to #nnn
autoreplies to be created. Snnn: allow up to #nnn bytes as the total size of
all autoreplies, combined. If both Cnnn and Snnn 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, Courier 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 Courier checks for both MX and
A records for the machine specified in this configuration file.
batchsize
This file contains one line, containing a single number. This number
specifies the absolute maximum number of recipients for a single message. If
Courier 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
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 <anything@anything.domain>.
badfrom user@.domain
Reject all mail with the return address
of <user@anything.domain>.
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 BOFHBADMIME=action
Set default disposition of mail with invalid or corrupted MIME headers.
Possible settings for action are:
accept - accept and pass on the corrupted message,
untouched; reject - reject and return the mail as
undeliverable; wrap - "wrap" the message as an
attachment, that must be separately opened (this is the default
action).
This setting applies to mail that's generated locally, or which is sent from
IP addresses that do not have an explicit BOFHBADMIME
setting listed in the smtpaccess configuration
file.
smtpaccess can be used to set
BOFHBADMIME for specific sending IP address ranges
only.
See
makesmtpaccess(8)
for more information.
Note: BOFHMIME=accept implies MIME=none
(see
submit(8)
for more information).
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)
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) .
Alternatively, HELO/EHLO checking may be turned off by default, and enabled
for specific IP address ranges by using
makesmtpaccess(8)
to set
BOFHCHECKHELO to 1.
See
makesmtpaccess(8)
for more information.
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.
"SENDER POLICY FRAMEWORK KEYWORDS"
Courier 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'',
``pass'',
``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.
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 Courier won't bother
looking at the From: header.
Note:
A conservative policy should not reject failed SPF checks from the
From:header,
because it can be counterproductive in some situations.
This is because when a sender from a domain with a published SPF policy
sends a message to a mailing list, the message goes through the
mailing list processor's IP address, and it will fail the SPF check unless
the domain SPF explicitly authorizes the mailing list processor's IP
address.
This is very unlikely.
The end result is that domains with a published SPF record get punished,
and domains without an SPF record
get off scott free.
Mailing lists should be encouraged to publish their own SPF records for
mailing list traffic; then the ``mailfromok'' keyword can validate
the mailing list's return address, and forego checking of
the ``From:'' header from the mailing list, while still checking
the ``From:'' header from everyone else.
Another alternative is to use
opt BOFHSPFFROM=all for advisory purposes only.
Post-delivery mail filters can key off the ``Received-SPF''
header.
Note: Courier can add up to three ``Received-SPF'' headers of its own,
one for each SPF check.
Courier renames any existing ``Received-SPF'' header as
``Old-Received-SPF''.
All ``Received-SPF'' headers delivered to a local mailbox will
always come from Courier.
calendarmode
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:
echo "local" >/etc/courier/calendarmode
This configuration file must be globally readable, so make sure that your
umask is not set too tight.
courierd
This configuration file specifies several parameters relating to general
Courier 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, Courier 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, Courier uses the contents of the me control file.
The contents of defaultdomain are also appended to return
addresses to mail sent from Courier's webmail server, if they don't already
have a domain. If defaultdomain does not exist, Courier's
webmail server obtain the machine hostname, and uses that.
Note: The mail domain in defaultdomain must be
one of the local domains,
as defined by the
locals and the hosteddomains
control files.
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, Courier reads $HOME/.courier,
$HOME/.courier-foo, $HOME/.courier-default, and so
on. If this file contains the text "qmail", Courier 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 Courier puts in all delivery status notifications. This file
specifies a complete header, except for the "From: " part. If
dsnfrom is missing, then Courier uses the following
header:
"Courier 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 Courier 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
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)
will be filtered using the global mail filtering API.
uucp
Specifies that mail received from UUCP will be filtered.
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) manual page.
This is NOT the traditional user-controlled mail filtering, such as
maildrop(1) .
A global mail filter is a daemon process that selectively accepts or rejects
incoming mail, based on arbitrary criteria.
esmtpacceptmailfor
This file lists all domains that Courier accepts mail for via ESMTP. This
file is in the same format as the locals file. If this file is
missing, Courier uses the single domain specified in me (or the
system machine name).
esmtpacceptmailfor.dat
This is a binary database file that lists additional domains that Courier
accepts mail for, just like esmtpacceptmailfor. A binary
database file will be faster than a flat text file when the number of domains
is large. Courier will accept mail for domains listed in either
esmtpacceptmailfor or esmtpacceptmailfor.dat.
esmtpacceptmailfor.dat is created by the
makeacceptmailfor command. 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.
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:
relay userid password
When Courier connects to a remote ESMTP relay, Courier 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 "daemon".
ESMTP negotiation will take place, and Courier will use a SASL
authentication method supported by both Courier and the remote ESMTP server.
Currently Courier supports PLAIN, LOGIN and CRAM-MD5 authentication. CRAM-MD5
is preferred over the other two, and PLAIN is preferred over LOGIN.
Courier 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
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 Courier 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 Courier 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 Courier 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 Courier calls itself in the
EHLO or HELO command sent to a remote SMTP server.
me is used if this file does not exist.
esmtproutes
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, Courier
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 Courier 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, Courier 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:
.example.com: [192.168.0.3],26
This specifies that any address of the form
<anything@anything.example.com> 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:
example.com: relay.example.com
:[192.168.0.4]
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, Courier interprets it as an explicit directive to use
MX and A records from DNS. For example:
example.com:
:[192.168.0.4]
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 optional /SECURITY=STARTTLS flag indicates that mail to
this domain should be automatically upgraded to use the SECURITY
ESMTP extension. See the Courier installation notes for a description of
SECURITY, what it does, and how to configure it.
The /SECURITY=NONE flag prevents Courier from using the
STARTTLS ESMTP extension even if the remote server claims to
support it. Use this flag to deliver mail to misconfigured Microsoft
Exchange relays that claim to support STARTTLS, but always report a failure
to a STARTTLS request.
Changes to this file take effect immediately, more or less. Existing
courieresmtp processes that already have an established
connection will ignore any changes.
esmtptimeout
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 Courier 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. Courier 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 Courier 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
Courier 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 Courier 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
Courier 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 Courier waits
for the external SMTP server to acknowledge the QUIT command, before Courier
unilaterally tears down the connection. The default value is 10 seconds. This
must be a small value because Courier needs to be able to shut down quickly,
on very short notice.
faxqueuetime
This file specifies how long Courier 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 Courier should deliver received faxes
(if this option is enabled).
See Courier's installation notes for more information.
faxrc
This file configures Courier's outbound faxing and dialing parameters.
Consult the comments in the default file for additional information, and
the
courierfax(8)
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 user@example.com will have example.com
removed, and then Courier will look for a local mailbox named
"user".
If the domain "example.com" appears in
hosteddomains instead, Courier will look for a local mailbox
named "user@example.com" instead.
The contents of the hosteddomains configuration file is a
list of domains, one per line, in lowercase. You must run the
makehosteddomains command for any changes to take
effect.
Additionally, hosteddomains can specify simple domain
aliases.
See the complete description in the
makehosteddomains(8)
manual page.
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:
This file is used by the courierldapaliasd process. See
courierldapaliasd(8)
for more information.
locallowercase
If this file exists, Courier will not distinguish being lowercase and
uppercase local accounts, so that john@example.com and
John@example.com 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:
.domain.com
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:
!host.domain.com
.domain.com
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, Courier uses the contents of the
me control file (note that me specifies only one
domain, second and subsequent lines are ignored). Also, see
hosteddomains.
localtimeout
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 Courier'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.
Enhanced login domain listing:
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
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
"user@domain.com", "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:
domain1.com
domain3.com
domain5.com
"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
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.
maildirfilterconfig
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
Courier. 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)
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)
for more information.
maildrop
This file contains one line whose contents is a pathname to the
maildrop(1)
mail delivery agent. If Courier knows
that the delivery agent used to delivery mail locally is
maildrop(1)
then certain delivery optimizations
are possible. This configuration file does NOT actually specify that
maildrop(1)
should be used as a local mail delivery
agent, it only specifies where
maildrop(1)
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, Courier assumes that it's
maildrop(1) ,
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)
that's integrated with Courier. The integrated version of
maildrop(1)
is configured slightly differently than
the standalone version of
maildrop(1) .
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)
mail delivery filter. In addition to
being a delivery agent, maildrop can also be used as a mail filtering engine.
If this file exists, Courier will be capable of invoking recipient-specified
mail filters when a message is received. If the mail filtering rules reject
the message, Courier will not accept the message for delivery. This means
that when receiving mail via ESMTP, Courier 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)
deliveries. This configuration file is
optional, and is used by
maildrop(1)
when it
is invoked as a traditional post-delivery mail filter. See
maildropfilter(6)
for more information.
me
This file contains one line whose contents is a valid machine name. When a
single installation of Courier is shared over a network, each machine that's
running Courier must have a unique me file. If me is missing,
Courier uses the result of the gethostname() system call.
Warning: If you change the contents of this configuration file, you
must run 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 also must run
makealiases.
msgidhost
If a message does not have a Message-ID: header, Courier 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
Courier'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 Courier's mail queue processing.
Courier 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.
Courier 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,
Courier 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 Courier simultaneously tries to
clear the existing backlog, and process any new mail at the same time.
Up to Courier 0.41, all of this generally translates to Courier giving
priority to newly arrived mail, and processing the backed up mail queue
if spare resources are available.
The queuefill setting was added in Courier 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 Courier completely fills the memory queue it sets a timer.
After the interval given by queuefill Courier will go
back and re-fill the mail queue even if the number of messages did not fall
below the low watermark.
If Courier 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 Courier 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 Courier 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, Courier makes repeated delivery
attempts
for one week.
retryalpha, retrybeta, retrygamma, retrydelta
These control files specify the schedule with which Courier 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.
Courier will first make retrybeta delivery attempts, waiting
for the time interval specified by retryalpha between each
attempt. Then, Courier waits for the amount of time specified by
retrygamma, then Courier will make another
retrybeta delivery attempts, retryalpha amount of
time apart. If still undeliverable, Courier 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 Courier 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
Five minutes
retrybeta
Three times
retrygamma
Fifteen minutes
retrymaxdelta
Three
This results in Courier 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
Maximum size of the message, in bytes, that Courier accepts for delivery.
Courier rejects larger messages. If sizelimit is set to zero,
Courier 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 Courier 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)
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)
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, Courier'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 Courier 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 relay. See
courieruucp(8)
for more information.
uucpneighbors
uucpneighbors is used by the courieruucp module to
specify Courier's configuration for relaying mail via UUCP. See
courieruucp(8)
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.
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, Courier sends a warning message (a "delayed" Delivery Status
Notification) to the sender. If warntime is missing, Courier
sets warntime to four hours.
Note: The time interval specified by warntime is only
approximate. Courier sends a delayed Delivery Status Notification at the
conclusion of the first attempted delivery after warntime has
elapsed.
"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.
CHARSET
This 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.
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 Courier 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.
