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.

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).

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.

badfrom user@domain

badfrom @domain

badfrom @.domain

badfrom user@.domain

badmx N

freemail domain [domain2] [domain3]...

spamtrap user@domain

maxrcpts N [hard]

opt BOFHCHECKHELO=1

opt BOFHCHECKHELO=2

opt BOFHHEADERLIMIT=n

opt BOFHNOBASE64TEXT=1

opt BOFHSPFHELO=keywords

opt BOFHSPFMAILFROM=keywords

opt BOFHSPFFROM=keywords

opt BOFHSPFHARDERROR=keywords

opt BOFHSPFTRUSTME=1

opt BOFHSPFNOVERBOSE=1

opt BOFHSUPPRESSBACKSCATTER=list

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.

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.

esmtp

local

uucp

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.

See the section called “Hostname-dependent configuration” for more information on hostname-dependent configuration in the esmtpacceptmailfor configuration file.

See the section called “Hostname-dependent configuration” for more information on hostname-dependent configuration in the esmtpacceptmailfor.dir configuration files.

relay userid password

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).

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.

esmtphelo may also be set to a special value of “*”:

echo '*' >esmtphelo

domain:relay[,port][/SECURITY=STARTTLS][/SECURITY=REQUIRED][/SECURITY=SMTPS]

relay can be another domain, or an explicit IP address inside brackets. For example, if esmtproutes contains the following:

example.com: relay.domain.com
domain.com: [192.168.0.2]

 .example.com: [192.168.0.3],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]

If relay is empty, the Courier mail server interprets it as an explicit directive to use MX and A records from DNS. For example:

example.com:
:[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.

: relay.example.com,465 /SECURITY=SMTPS

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.

/SECURITY=STARTTLS

/SECURITY=SMTPS

/SECURITY=REQUIRED

Changes to esmtproutes take effect immediately, more or less. Existing courieresmtp processes that already have an established connection will ignore any changes.

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.

faxqueuetime specifies the timeout for fax messages. This time interval is specified in the same way as queuetime (see queuetime for more information).

If the domain "example.com" appears in hosteddomains instead, the Courier mail server 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, 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.

 .domain.com

Specific hosts can be excluded from the wildcard. Example:

 !host.domain.com


 .domain.com

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.

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

Modifiers

     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

Wildcards

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.

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.

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.

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

retrybeta

retrygamma

retrymaxdelta

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.

If sizelimit does not exist, and SIZELIMIT is not set, the maximum message size defaults to 10485760 bytes.

submitdelay specifies a time interval in the same format as queuetime.

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.

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.

The Courier mail server can add up to three “Received-SPF” headers of its own, one for each SPF check. The Courier mail server renames any existing “Received-SPF” header as “Old-Received-SPF”. All “Received-SPF” headers delivered to a local mailbox will always come from the Courier mail server.

# 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

# 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"

Notwithstanding the IP address set in an ipout or an ip6out file, the server's network configuration must be able to actually establish a network connection to the destination address from the explicitly specified IP address. Specifying an explicit IP address for outgoing connections implies that the IP addresses are fully and globally routable.

# echo "relay.example.com" >/etc/courier/me.192.168.0.1
# echo "firewall.example.com" >/etc/courier/me.192.168.1.1

The IP address-specific configuration settings get used only in the context of processing messages, and have no impact on other parts of the Courier mail server that do not have a direct relationship to a specific message. One such example would be when Courier authenticates a client's username or password. This is not directly related to any message the client may or may not send after it authenticates, so this happens in exactly the same way no matter which IP address the client connected to.

# touch >/etc/courier/vhost.example.com

# echo '192.168.0.1' >/etc/courier/ipout.example.com