/usr/share/doc/courier-doc/html/courier.html

<?xml version="1.0"?>
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/><title>courier</title><link rel="stylesheet" type="text/css" href="style.css"/><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"/><link rel="home" href="#idm139938117728656" title="courier"/><link xmlns="" rel="stylesheet" type="text/css" href="manpage.css"/><meta xmlns="" name="MSSmartTagsPreventParsing" content="TRUE"/><link xmlns="" rel="icon" href="icon.gif" type="image/gif"/><!--

Copyright 1998 - 2009 Double Precision, Inc.  See COPYING for distribution
information.

--></head><body><div class="refentry"><a id="idm139938117728656" shape="rect"> </a><div class="titlepage"/><div class="refnamediv"><h2>Name</h2><p>courier — The <span class="application">Courier</span> mail server</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">courier</code>  { start  |   stop  |   restart  |   flush  |   
	   flush 
	    <em class="replaceable"><code>qid</code></em> 
          |   
	   clear 
	    <em class="replaceable"><code>user@domain</code></em> 
          |   
	   clear 
            all 
          |   
	   show 
            all 
         }</p></div></div><div class="refsect1"><a id="idm139938122128384" shape="rect"> </a><h2>DESCRIPTION</h2><p>
The <span class="application">Courier</span> mail server is a modular multi-protocol E-mail transport agent. The
<span class="command"><strong>courier</strong></span> command is an administrative command, and most of
its options are only available to the superuser.</p><p>
"<span class="command"><strong>courier start</strong></span>" starts the server by running
<span class="command"><strong>/usr/lib/courier/courierctl.start</strong></span> in the background.
"<span class="command"><strong>courier stop</strong></span>" immediately stops all the <span class="application">Courier</span> mail server processes and
aborts all current mail deliveries.
"<span class="command"><strong>courier restart</strong></span>" restarts the <span class="application">Courier</span> mail server server.
A restart is often needed for certain configuration changes to take effect.
"<span class="command"><strong>courier restart</strong></span>" waits for all current deliveries to
complete
before restarting. This is the "nice" way to restart the mail server.
"<span class="command"><strong>courier flush</strong></span>" takes all undelivered messages in the
queue and
attempts to deliver them immediately, instead of waiting until their next
scheduled attempted delivery time. "<span class="command"><strong>courier flush</strong></span>" 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
<a class="ulink" href="mailq.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">mailq</span>(1)</span>
</a> command.</p><p>
Please note that <span class="command"><strong>courier start</strong></span> runs the main
<span class="application">Courier</span> mail server
scheduling engine only. It does not start any other daemons that you may
have, such as the ESMTP or the IMAP daemon.</p><p>
"<span class="command"><strong>courier show all</strong></span>" lists all E-mail addresses currently
blacklisted for backscatter.
"<span class="command"><strong>courier clear user@domain</strong></span>" manually clears
&lt;user@domain&gt; from the backscatter blacklist.
"<span class="command"><strong>courier clear all</strong></span>" removes all addresses from the
backscatter blacklist.
When the <span class="application">Courier</span> mail server encounters a delivery failure to an E-mail address the <span class="application">Courier</span> 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 <span class="application">Courier</span> mail server's
installation instructions for more information.</p><p>
The <span class="application">Courier</span> 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 <span class="application">Courier</span> mail server's mail queue, using the "cancel" command.
Even if the message is cancelled, the
<span class="application">Courier</span> 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.</p><div class="refsect2"><a id="idm139938122242480" shape="rect"> </a><h3>CONFIGURATION FILES</h3><p>
The <span class="application">Courier</span> mail server uses several configuration files which are located in
<code class="filename">/etc/courier</code>.
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
<span class="command"><strong>courier restart</strong></span>
for any changes to these files to take effect.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">aliasfilteracct</code></span></dt><dd><p>
This file contains one line, containing the home directory of the account
that's used for filtering mail addressed to local alias lists.</p><p>
When mail filtering is enabled, local recipients have the ability to
define mail filters which can selectively reject unwanted mail.
<code class="filename">/etc/courier/aliases</code> 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
"<code class="filename">alias-<em class="replaceable"><code>address</code></em></code>"
where <em class="replaceable"><code>address</code></em> is the name of the
alias.  See
<a class="ulink" href="localmailfilter.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">localmailfilter</span>(7)</span></a> for more
information.</p><p>
Due to technical limitations, content filtering is not available for
multiple-recipient aliases.</p><p>
Changes to this file take effect immediately.</p></dd><dt><span class="term"><code class="filename">autoresponsesquota</code></span></dt><dd><p>
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.</p><p>
The <code class="filename">autoresponsesquota</code> file contains one line:
"<code class="literal">C<em class="replaceable"><code>nnn</code></em></code>" or
"<code class="literal">S<em class="replaceable"><code>nnn</code></em></code>" (or both strings, on the same line). <code class="literal">C<em class="replaceable"><code>nnn</code></em></code>: allow up to #nnn
autoreplies to be created. <code class="literal">S<em class="replaceable"><code>nnn</code></em></code>: allow up to #nnn bytes as the total size of
all autoreplies, combined.  If both <code class="literal">C<em class="replaceable"><code>nnn</code></em></code> and <code class="literal">S<em class="replaceable"><code>nnn</code></em></code> 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 <code class="filename">autoresponsesquota</code> file in that
Maildir (which takes precedence).</p></dd><dt><span class="term"><code class="filename">backuprelay</code></span></dt><dd><p>
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.</p><p>
Mail gets rerouted if it cannot be delivered after the time interval
specified by the <code class="filename">warntime</code> configuration file. When
<code class="filename">backuprelay</code> 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.</p><p>
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.</p><p>
Although currently SMTP is the only meaningful application for this
feature, the <span class="application">Courier</span> mail server is a protocol-independent mail server, and the backup relay
function can be extended to other protocols, as they become available.</p><p>
Multiple backup relays can be used by simply assigning multiple <acronym class="acronym">IP</acronym>
addresses to the same machine name. Note that the <span class="application">Courier</span> mail server checks for both MX and
A records for the machine specified in this configuration file.</p><p>
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.</p></dd><dt><span class="term"><code class="filename">batchsize</code></span></dt><dd><p>
This file contains one line, containing a single number. This number
specifies the absolute maximum number of recipients for a single message. If
the <span class="application">Courier</span> 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
<code class="filename">batchsize</code> recipients. If <code class="filename">batchsize</code> is missing, it
defaults to 100 recipients per message.</p></dd><dt><span class="term"><code class="filename">bofh</code></span></dt><dd><p>
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:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">badfrom <em class="replaceable"><code>user@domain</code></em></code></span></dt><dd><p>
Reject all mail with the return
address of <code class="literal">&lt;user@domain&gt;</code>.</p></dd><dt><span class="term"><code class="literal">badfrom <em class="replaceable"><code>@domain</code></em></code></span></dt><dd><p>
Reject all mail with the return address
of <code class="literal">&lt;anything@domain&gt;</code>.</p></dd><dt><span class="term"><code class="literal">badfrom <em class="replaceable"><code>@.domain</code></em></code></span></dt><dd><p>
Reject all mail with the return address
of <code class="literal">&lt;anything@anything.domain&gt;</code>.</p></dd><dt><span class="term"><code class="literal">badfrom <em class="replaceable"><code>user@.domain</code></em></code></span></dt><dd><p>
Reject all mail with the return address
of <code class="literal">&lt;user@anything.domain&gt;</code>.</p></dd><dt><span class="term"><code class="literal">badmx <em class="replaceable"><code>N</code></em></code></span></dt><dd><p>
Reject all mail with a return address in any
mail domain whose listed mail servers include server "<em class="replaceable"><code>N</code></em>". "<em class="replaceable"><code>N</code></em>" is an <acronym class="acronym">IP</acronym>
address.  The <code class="envar">BOFHCHECKDNS</code> option in the <code class="filename">esmtp</code> 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 <acronym class="acronym">DNS</acronym> failure to look up A records for hostnames returned in the MX
record may hide the blacklisted server from view.</p></dd><dt><span class="term"><code class="literal">freemail <em class="replaceable"><code>domain</code></em> [<em class="replaceable"><code>domain2</code></em>] [<em class="replaceable"><code>domain3</code></em>]...</code></span></dt><dd><p>
Reject all mail with a return address
<em class="replaceable"><code>&lt;anything@domain&gt;</code></em> unless the
mail is received from a mail relay whose hostname is in the same domain.
"<em class="replaceable"><code>domain2</code></em>" and "<em class="replaceable"><code>domain3</code></em>" are optional, and specifies other domains that
the mail relay's hostname may belong to.  For example: "<em class="replaceable"><code>freemail
example.com domain.com</code></em>" specifies that mail with a return address
<em class="replaceable"><code>@example.com</code></em> will be accepted only from a mail relay with a hostname in
the <em class="replaceable"><code>example.com</code></em> or <em class="replaceable"><code>domain.com</code></em> domain. Note that this setting requires
that <acronym class="acronym">DNS</acronym> lookup be enabled for incoming ESMTP connections (which is the
default setting).</p></dd><dt><span class="term"><code class="literal">spamtrap <em class="replaceable"><code>user@domain</code></em></code></span></dt><dd><p>
Reject all mail that has
<em class="replaceable"><code>&lt;user@domain&gt;</code></em> listed as one of its recipients.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
For local mailboxes, '<code class="literal">domain</code>' must be set to the
contents of the <code class="filename">me</code>
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.</p></div></dd><dt><span class="term"><code class="literal">maxrcpts <em class="replaceable"><code>N</code></em> [hard]</code></span></dt><dd><p>
Accept the first <em class="replaceable"><code>N</code></em> 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.</p></dd><dt><span class="term"><code class="literal">opt BOFHCHECKHELO=1</code></span></dt><dd><p>
Verify the hostname provided in the ESMTP HELO/EHLO statement.
<span class="quote">“<span class="quote">opt BOFHCHECKHELO=1</span>”</span> is a global default, which may be
overridden by setting the <code class="envar">BOFHCHECKHELO</code> environment
variable in the SMTP access file.
See
<a class="ulink" href="makesmtpaccess.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">makesmtpaccess</span>(8)</span></a>
for more information.
<span class="quote">“<span class="quote">opt BOFHCHECKHELO=1</span>”</span> enables ESMTP HELO/EHLO checking by
default, and ESMTP HELO/EHLO checking may be turned off for individual <acronym class="acronym">IP</acronym>
address ranges by setting
<code class="envar">BOFHCHECKHELO</code> to <code class="literal">0</code>
using
<a class="ulink" href="makesmtpaccess.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">makesmtpaccess</span>(8)</span></a>.
Alternatively, HELO/EHLO checking may be turned off by default, and enabled
for specific <acronym class="acronym">IP</acronym> address ranges by using
<a class="ulink" href="makesmtpaccess.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">makesmtpaccess</span>(8)</span></a>
to set
<code class="envar">BOFHCHECKHELO</code> to <code class="literal">1</code>.
See
<a class="ulink" href="makesmtpaccess.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">makesmtpaccess</span>(8)</span></a>
for more information.</p></dd><dt><span class="term"><code class="literal">opt BOFHCHECKHELO=2</code></span></dt><dd><p>
		    Setting to <code class="envar">BOFHCHECKHELO</code>
		    <code class="literal">2</code> has the effect of returning a
		    temporary SMTP error code, instead of a permanent SMTP
		    error code, for a failed HELO/EHLO SPF check.
		  </p></dd><dt><span class="term"><code class="literal">opt BOFHHEADERLIMIT=<em class="replaceable"><code>n</code></em></code></span></dt><dd><p>
Reject messages whose headers exceed <em class="replaceable"><code>n</code></em> bytes in
size (minimum 1,000 bytes, default 100,000 bytes).</p></dd><dt><span class="term"><code class="literal">opt BOFHNOBASE64TEXT=1</code></span></dt><dd><p>
Reject messages with base64-encoded <code class="literal">text/plain</code> or
<code class="literal">text/html</code> content.</p></dd><dt><span class="term"><code class="literal">opt BOFHSPFHELO=</code><em class="replaceable"><code>keywords</code></em></span></dt><dd><p>
Use Sender Policy Framework to verify the <code class="literal">HELO</code> or
<code class="literal">EHLO</code> domain sent by the connecting SMTP client.
See <a class="link" href="#SPF" title="Sender Policy Framework Keywords" shape="rect">Sender Policy Framework Keywords</a> below for
a list of possible keywords.</p><p>
SPF checking is not used for
<code class="literal">HELO</code> or
<code class="literal">EHLO</code> commands that specify an <acronym class="acronym">IP</acronym> address instead of
a domain name.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
This setting may be used in combination with
<code class="literal">opt BOFHCHECKHELO=1</code>.
The <code class="literal">BOFHCHECKHELO=1</code> check is disabled
if SPF verification of the <code class="literal">HELO</code>/<code class="literal">EHLO</code>
results in the SPF status of <span class="quote">“<span class="quote">pass</span>”</span>.
This makes sense: if the <code class="literal">HELO</code>/<code class="literal">EHLO</code>
domains complies with the domain's SPF, it is not necessary to check it
further.</p></div></dd><dt><span class="term"><code class="literal">opt BOFHSPFMAILFROM=</code><em class="replaceable"><code>keywords</code></em></span></dt><dd><p>
Use Sender Policy Framework to verify the return address in the
<code class="literal">MAIL FROM</code> command sent by the connecting SMTP client.
See <a class="link" href="#SPF" title="Sender Policy Framework Keywords" shape="rect">Sender Policy Framework Keywords</a> below for
a list of possible keywords.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
No SPF checking is done for if the <code class="literal">MAIL FROM</code> command
specifies an empty return address (a bounce).
There's nothing to check.</p></div></dd><dt><span class="term"><code class="literal">opt BOFHSPFFROM=</code><em class="replaceable"><code>keywords</code></em></span></dt><dd><p>
Use Sender Policy Framework to verify the return address in the
<code class="literal">From:</code> header.
See <a class="link" href="#SPF" title="Sender Policy Framework Keywords" shape="rect">Sender Policy Framework Keywords</a> below for
important information, and a list of possible keywords.</p></dd><dt><span class="term"><code class="literal">opt BOFHSPFHARDERROR=</code><em class="replaceable"><code>keywords</code></em></span></dt><dd><p>
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.</p><p>
The default setting for <code class="envar">BOFHSPFHARDERROR</code> is
<code class="literal">fail,softfail</code>.</p></dd><dt><span class="term"><code class="literal">opt BOFHSPFTRUSTME=1</code></span></dt><dd><p>
Disable all SPF checks for any connecting client that has relaying privileges
(<code class="envar">RELAYCLIENT</code> is explicitly set, or inherited after a successful
SMTP authentication).</p></dd><dt><span class="term"><code class="literal">opt BOFHSPFNOVERBOSE=1</code></span></dt><dd><p>
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.</p></dd><dt><span class="term"><code class="literal">opt BOFHSUPPRESSBACKSCATTER=</code><em class="replaceable"><code>list</code></em></span></dt><dd><p>
This is one of the two settings that controls which messages are subject to
backscatter suppression.
The other setting, <code class="literal">ESMTP_BLOCKBACKSCATTER</code> is set in the
<code class="filename">courierd</code> configuration file, which contains further
documentation.</p><p>
<span class="quote">“<span class="quote">list</span>”</span> is a comma-separated list of message sources.
The possible message sources are:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">authsmtp</code></span></dt><dd><p>
Messages received via <acronym class="acronym">SMTP</acronym> from clients with relaying
privileges (authenticated <acronym class="acronym">SMTP</acronym>, or <acronym class="acronym">IP</acronym> addresses that always
have relaying privileges.</p></dd><dt><span class="term"><code class="literal">smtp</code></span></dt><dd><p>
All other messages received via <acronym class="acronym">SMTP</acronym>.</p></dd><dt><span class="term"><code class="literal">none</code></span></dt><dd><p>
Do not suppress backscatter messages from any source.</p></dd></dl></div><p>
The default setting is <span class="quote">“<span class="quote">opt BOFHSUPPRESSBACKSCATTER=smtp</span>”</span>.
The other possible values are
<span class="quote">“<span class="quote">opt BOFHSUPPRESSBACKSCATTER=smtp,authsmtp</span>”</span>
(which suppresses backscatter from all <acronym class="acronym">SMTP</acronym> mail), and
<span class="quote">“<span class="quote">opt BOFHSUPPRESSBACKSCATTER=none</span>”</span>.</p></dd></dl></div></dd><dt><span class="term"><code class="filename">calendarmode</code></span></dt><dd><p>
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:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
echo "local" &gt;/etc/courier/calendarmode
</pre></div><p>
This configuration file must be globally readable, so make sure that your
umask is not set too tight.</p></dd><dt><span class="term"><code class="filename">courierd</code></span></dt><dd><p>
This configuration file specifies several parameters relating to general
the <span class="application">Courier</span> mail server configuration. A default configuration file will be installed, and
you should consult its contents for additional information.</p></dd><dt><span class="term"><code class="filename">defaultdomain</code></span></dt><dd><p>
This file contains one line whose contents is a valid mail domain. Most
header rewriting functions will append <code class="filename">@defaultdomain</code> to all
E-mail addresses that do not specify a domain. If <code class="filename">defaultdomain</code>
is missing, the <span class="application">Courier</span> mail server uses the contents of the <code class="filename">me</code> control file.</p><p>
When the ESMTP server receives a <span class="quote">“<span class="quote">RCPT TO</span>”</span> command containing
the address <code class="literal">&lt;user@[<em class="replaceable"><code>ip.address</code></em>]&gt;</code>,
and the <acronym class="acronym">IP</acronym> address is the same as the <acronym class="acronym">IP</acronym> address of the socket it's listening
on, the ESMTP server replaces the <acronym class="acronym">IP</acronym> address with the contents of the
<code class="filename">defaultdomain</code> control file.
If <code class="filename">defaultdomain</code>
is missing, the <span class="application">Courier</span> mail server uses the contents of the <code class="filename">me</code> control file.
</p><p>
The contents of <code class="filename">defaultdomain</code> are also appended to return
addresses to mail sent from the <span class="application">Courier</span> mail server's webmail server, if they don't already
have a domain. If <code class="filename">defaultdomain</code> does not exist,
the <span class="application">Courier</span> mail server's
webmail server obtain the machine hostname, and uses that.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
The mail domain in <code class="filename">defaultdomain</code> should be
one of the local domains,
as defined by the
<code class="filename">locals</code> and the <code class="filename">hosteddomains</code>
control files.</p><p>
Otherwise, if a domain-less address in mail headers gets
augmented with <code class="filename">defaultdomain</code> 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.</p></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>
If you change the contents of this configuration file, it may be necessary
to rerun the <span class="command"><strong>makealiases</strong></span> 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
<span class="command"><strong>makealiases</strong></span>.</p></div></dd><dt><span class="term"><code class="filename">dotextension</code></span></dt><dd><p>
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 <span class="application">Courier</span> mail server reads <code class="filename">$HOME/.courier</code>,
<code class="filename">$HOME/.courier-foo</code>, <code class="filename">$HOME/.courier-default</code>, and so
on. If this file contains the text "qmail",
the <span class="application">Courier</span> mail server will instead read
<code class="filename">$HOME/.qmail</code>, $<code class="filename">HOME/.qmail-foo</code>,
<code class="filename">$HOME/.qmail-default</code>, and so on.</p></dd><dt><span class="term"><code class="filename">dsnfrom</code></span></dt><dd><p>
This file contains one line specifying the contents of the
<code class="literal">From:</code>
header that the <span class="application">Courier</span> mail server puts in all delivery status notifications. This file
specifies a complete header, except for the "From: " part. If
<code class="filename">dsnfrom</code> is missing, then the <span class="application">Courier</span> mail server uses the following
header:
<code class="literal">"<span class="application">Courier</span> mail server mail server at <code class="filename">me</code>" &lt;@&gt;</code></p></dd><dt><span class="term"><code class="filename">dsnlimit</code></span></dt><dd><p>
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 <code class="filename">dsnlimit</code>.
If missing, <code class="filename">dsnlimit</code> is set to 32K.</p><p>
The sender can request that the entire message be returned even on delayed
notices or return receipts, however the <span class="application">Courier</span> mail server will ignore this request if the
message size exceeds this limit.</p></dd><dt><span class="term"><code class="filename">enablefiltering</code></span></dt><dd><p>
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:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">esmtp</code></span></dt><dd><p>
Enables global mail filtering for
mail received via ESMTP.</p></dd><dt><span class="term"><code class="literal">local</code></span></dt><dd><p>
Specifies that mail received from logged on users,
via sendmail, and mail forwarded from
<a class="ulink" href="dot-courier.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">dot-courier</span>(5)</span></a>
will be filtered using the global mail filtering API.</p></dd><dt><span class="term"><code class="literal">uucp</code></span></dt><dd><p>
Specifies that mail received from UUCP will be filtered.</p></dd></dl></div><p>
If you want to specify more than one source of mail, such as ESMTP and
local mail, specify both <code class="filename">esmtp</code> and
<code class="filename">local</code>, separated by a space character.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
The global mail filtering API is described, in detail, in the
<a class="ulink" href="courierfilter.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">courierfilter</span>(8)</span>
</a> manual page.
This is NOT the traditional user-controlled mail filtering, such as
<a class="ulink" href="maildrop.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">maildrop</span>(1)</span>
</a>.
A global mail filter is a daemon process that selectively accepts or rejects
incoming mail, based on arbitrary criteria.</p></div></dd><dt><span class="term"><code class="filename">esmtpacceptmailfor</code></span></dt><dd><p>
This file lists all domains that the <span class="application">Courier</span> mail server accepts mail for via ESMTP. This
file is in the same format as the <code class="filename">locals</code> file. If this file is
missing, the <span class="application">Courier</span> mail server uses the
single domain specified in <code class="filename">me</code> (or the
system machine name).</p></dd><dt><span class="term"><code class="filename">esmtpacceptmailfor.dat</code></span></dt><dd><p>
This is a binary database file that lists additional domains that the <span class="application">Courier</span> mail server
accepts mail for, just like <code class="filename">esmtpacceptmailfor</code>. A binary
database file will be faster than a flat text file when the number of domains
is large. The <span class="application">Courier</span> mail server will accept mail for domains listed in either
<code class="filename">esmtpacceptmailfor</code> or <code class="filename">esmtpacceptmailfor.dat</code>.
<code class="filename">esmtpacceptmailfor.dat</code> is created by the
<span class="command"><strong>makeacceptmailfor</strong></span> command.  You can use both
<code class="filename">esmtpacceptmailfor.dat</code> and <code class="filename">esmtpacceptmailfor</code> at
the same time.  Put your most popular domains in
<code class="filename">esmtpacceptmailfor</code>, and put the rest of them into
<code class="filename">esmtpacceptmailfor.dat</code>.</p></dd><dt><span class="term"><code class="filename">esmtpauthclient</code></span></dt><dd><p>
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:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
relay userid password
</pre></div><p>
When the <span class="application">Courier</span> mail server connects to a remote ESMTP <code class="literal">relay</code>,
the <span class="application">Courier</span> mail server will
authenticate itself using <code class="literal">userid</code> and <code class="literal">password</code>.  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 "<code class="literal">courier</code>".</p><p>
ESMTP negotiation will take place, and the <span class="application">Courier</span> mail server will use a SASL
authentication method supported by both the <span class="application">Courier</span> mail server and the remote ESMTP server.
Currently the <span class="application">Courier</span> mail server supports PLAIN, LOGIN and CRAM-MD5 authentication. CRAM-MD5
is preferred over the other two, and PLAIN is preferred over LOGIN.</p><p>
The <span class="application">Courier</span> 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.</p><p>
Changes to this file take effect, more or less, immediately (existing
connections are not affected, but new connections will read the updated
data).</p></dd><dt><span class="term"><code class="filename">esmtpd</code></span></dt><dd><p>
This file is used to initialize the environment and parameters for
<span class="command"><strong>courieresmtpd</strong></span>. 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 <span class="command"><strong>esmtpd stop</strong></span> command
followed by <span class="command"><strong>esmtpd start</strong></span>.</p></dd><dt><span class="term"><code class="filename">esmtpdelay</code></span></dt><dd><p>
This file contains one line of text that specifies how long
<span class="command"><strong>courieresmtp</strong></span> waits after a failure to contact the remote mail
server before another attempt is made. <span class="command"><strong>courieresmtp</strong></span> (not to be
confused with <span class="command"><strong>courieresmtpd</strong></span>) 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.</p><p>
The <span class="command"><strong>courieresmtp</strong></span> process delivers mail that's routed to
external mail relays, via ESMTP. When attempting to initally contact a mail
server <span class="command"><strong>courieresmtp</strong></span> waits for the amount of time specified by
<code class="filename">esmtptimeoutconnect</code> (see below).
<code class="filename">esmtptimeoutconnect</code> 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 <span class="application">Courier</span> 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 <span class="command"><strong>courieresmtp</strong></span> daemons spinning their wheels,
doing nothing.</p><p>
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 <code class="filename">esmtptimeout</code> waiting period
is used for each individual mail relay.  Multiply <code class="filename">esmtptimeout</code>
by the number of servers to see how large the delay really will be.</p><p>
<code class="filename">esmtpdelay</code> is implemented internally in the
<span class="command"><strong>courieresmtp</strong></span> module. The main the <span class="application">Courier</span> mail server scheduling daemon is not
aware of what's happening internally in <span class="command"><strong>courieresmtp</strong></span>. When
<span class="command"><strong>courieresmtp</strong></span> fails to contact any mail relay for the domain, the
message is postponed, and the <code class="filename">esmtpdelay</code> timer is set. Any
additional messages received by the same <span class="command"><strong>courieresmtp</strong></span> daemon
(for the same domain), are immediately postponed without any attempt to
contact a remote mail relay. When the amount of time set by
<code class="filename">esmtpdelay</code> expires, <span class="command"><strong>courieresmtp</strong></span> will attempt to
make another delivery attempt as usual.</p><p>
If <code class="filename">esmtpdelay</code> does not exist, the default delay is five
minutes. Any messages that are postponed look like any other temporary
failure to <span class="command"><strong>courierd</strong></span>. Delivery attempts are rescheduled as if a
real temporary failure took place. Therefore it does not make sense to set
<code class="filename">esmtpdelay</code> to be greater than <code class="filename">retryalpha</code> (see
below). When <code class="filename">retryalpha</code> is smaller is <code class="filename">esmtpdelay</code>,
you'll just messages spinning through the mail queue, with useless delivery
attempts being attempted because <code class="filename">esmtpdelay</code> still hasn't
expired.</p><p>
Occasionally you might observe somewhat strange behavior on systems with
heavy mail traffic. <code class="filename">esmtpdelay</code> applies separately to each
individual instance of <span class="command"><strong>courieresmtp</strong></span>. When a remote mail server
keeps going up and down, it is possible to end up with multiple
<span class="command"><strong>courieresmtp</strong></span> 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 <span class="command"><strong>courieresmtp</strong></span> daemons being able to deliver mail
immediately, while the rest are still waiting patiently for
<code class="filename">esmtpdelay</code> 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 <code class="filename">esmtpdelay</code> to expire.</p><p>
Another anomalous situation may happen when a <span class="command"><strong>courieresmtp</strong></span>
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 <span class="application">Courier</span> 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 <code class="filename">esmtpdelay</code> was cancelled when
the daemon got reassigned to another domain.</p><p>
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 <span class="command"><strong>courieresmtp</strong></span>
daemon picks it, it will start the <code class="filename">esmtpdelay</code> 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, <span class="command"><strong>courieresmtp</strong></span> will always try to contact
another mail relay of a still lower priority, before giving up and setting
the <code class="filename">esmtpdelay</code> timer. Another <span class="command"><strong>courieresmtp</strong></span> 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 <code class="filename">esmtpdelay</code>
expires. Another <span class="command"><strong>courieresmtp</strong></span> daemon will be started only in the
event of multiple simultaneous delivery attempts that happen to coincide at
the same time.</p><p>
This is somewhat mitigated by the fact that all <span class="command"><strong>courieresmtp</strong></span>
daemons are killed after a short period of total inactivity (currently one
minute), so that longer intervals specified by <code class="filename">esmtpdelay</code> are
ignored. Note, however, that receiving a message to deliver, and then
postponing it immediately, does count as some activity.</p><p>
<code class="filename">esmtpdelay</code> can be turned off by setting it to 0 seconds.
<code class="filename">esmtpdelay</code> 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. <code class="filename">esmtpdelay</code> 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.</p></dd><dt><span class="term"><code class="filename">esmtpgreeting</code></span></dt><dd><p>
The complete greeting banner displayed by <span class="command"><strong>courieresmtpd</strong></span>.
Changes to this file take effect immediately.</p></dd><dt><span class="term"><code class="filename">esmtphelo</code></span></dt><dd><p>
This file contains one line of text, what the <span class="application">Courier</span> mail server calls itself in the
<code class="literal">EHLO</code> or <code class="literal">HELO</code> command sent to a remote SMTP server.
<code class="filename">me</code> is used if this file does not exist.</p><p>
<code class="filename">esmtphelo</code> may also be set to a special value of
<span class="quote">“<span class="quote">*</span>”</span>:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
echo '*' &gt;esmtphelo
</pre></div><p>
(Note the single quotes, to prevent <span class="quote">“<span class="quote">*</span>”</span> from being expanded
by the shell).
The <span class="application">Courier</span> mail server will take the <acronym class="acronym">IP</acronym> address of the local side of the connection to
the remote SMTP server, look up the <acronym class="acronym">IP</acronym> address in <acronym class="acronym">DNS</acronym>,
and use the hostname from the reverse <acronym class="acronym">DNS</acronym> lookup.
This might be useful when the <span class="application">Courier</span> mail server server is multihomed.
The <span class="application">Courier</span> mail server will look up the local <acronym class="acronym">IP</acronym> address of each individual connection,
and use that in its <code class="literal">EHLO</code> or <code class="literal">HELO</code>
command.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
Functioning <acronym class="acronym">DNS</acronym> is required.
Using the <code class="filename">hosts</code> file, or an equivalent, won't work.
This function uses the <span class="application">Courier</span> mail server's native <acronym class="acronym">DNS</acronym> resolver, which
reads <code class="filename">/etc/resolv.conf</code> and queries the listed
<acronym class="acronym">DNS</acronym> servers directly.</p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
		See <a class="xref" href="#multihomed" title="Servers with multiple IP addresses" shape="rect">the section called “Servers with multiple IP addresses”</a> for a better way of
		accomplishing the same results.
	      </p></div></dd><dt><span class="term"><code class="filename">esmtproutes</code></span></dt><dd><p>
This file is used by the ESMTP module, and it contains one or more lines in
the following form:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
<em class="replaceable"><code>domain</code></em>:<em class="replaceable"><code>relay</code></em>[,<em class="replaceable"><code>port</code></em>][/SECURITY=STARTTLS][/SECURITY=REQUIRED][/SECURITY=SMTPS]
</pre></div><p>
<em class="replaceable"><code>domain</code></em> is any SMTP domain. <em class="replaceable"><code>relay</code></em> specifies a
fixed mail relay for this domain. <em class="replaceable"><code>relay</code></em> 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 <code class="filename">esmtproutes</code>,
the <span class="application">Courier</span> mail server
looks for MX and A records as usual (and always delivers to port 25). If the
domain is found in <code class="filename">esmtproutes</code>, however, any MX or A records for
the domain are ignored; instead the <span class="application">Courier</span> mail server delivers the message to the specified
relay.</p><p>
<em class="replaceable"><code>relay</code></em> can be another domain, or an explicit <acronym class="acronym">IP</acronym> address inside
brackets. For example, if <code class="filename">esmtproutes</code> contains the following:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
example.com: relay.domain.com
domain.com: [192.168.0.2]
</pre></div><p>
Mail for <code class="literal">example.com</code> is delivered to
<code class="literal">relay.domain.com</code>, ignoring any MX records for
<code class="literal">example.com</code>. Mail for <code class="literal">domain.com</code> will be delivered
to the machine at <acronym class="acronym">IP</acronym> address 192.168.0.2. All other domains will have their MX
and A records looked up.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
Unlike Qmail, the <span class="application">Courier</span> mail server
looks up MX and A records for
<code class="literal">relay.example.com</code> (Qmail only looks up A records).</p></div><p>
<code class="filename">esmtproutes</code> may contain comments, any line that starts with
the # character is ignored. Also, wildcards are allowed:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
 .example.com: [192.168.0.3],26
</pre></div><p>
This specifies that any address of the form
<code class="literal">&lt;anything@anything.example.com&gt;</code> will be delivered to the
mail server at this <acronym class="acronym">IP</acronym> address, but on port 26.</p><p>
<code class="filename">esmtproutes</code> is read from top to bottom, stopping as soon as a
first match is found.</p><p>
<code class="literal">domain</code> may be empty, this specifies a smarthost for all
domains. For example, if <code class="filename">esmtproutes</code> contains the following
text:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
example.com: relay.example.com
        :[192.168.0.4]
</pre></div><p>
This specifies that all mail to <code class="literal">example.com</code> is rerouted to
<code class="literal">relay.example.com</code>. All other mail is routed to the <acronym class="acronym">IP</acronym>
address <code class="literal">192.168.0.4</code>.</p><p>
If relay is empty, the <span class="application">Courier</span> mail server
interprets it as an explicit directive to use
MX and A records from <acronym class="acronym">DNS</acronym>. For example:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
example.com:
:[192.168.0.4]
</pre></div><p>
This uses MX and A records for all messages to <code class="literal">example.com</code>.
All other mail is rerouted to the <acronym class="acronym">IP</acronym> address
<code class="literal">192.168.0.4</code>.</p><p>
	      The <code class="literal">/SECURITY=STARTTLS</code> flag indicates that
	      mail to this domain will use the <code class="literal">SECURITY</code>
	      ESMTP extension. See the <span class="application">Courier</span> mail
	      server installation notes for a description of
	      <code class="literal">SECURITY</code>, what it does, and how to configure
	      it.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
		<code class="literal">/SECURITY=STARTTLS</code> does
		<span class="emphasis"><em>not</em></span> refer to the standard implementation
		of <acronym class="acronym">SMTP</acronym> over
		<acronym class="acronym">TLS</acronym>, but a
		<span class="application">Courier</span>-specific extension.
		<span class="application">Courier</span> automatically sends
		mail using encryption if it's enabled and the remote server
		advertises <code class="literal">STARTTLS</code>.
	      </p></div><p>
	      <code class="literal">/SECURITY=SMTPS</code> uses an encrypted
	      <acronym class="acronym">SMTP</acronym> connection. This is an alternative
	      to <code class="literal">STARTTLS</code>. Encrypted
	      <acronym class="acronym">SMTP</acronym> uses a different port, port 465, which
	      must be specified explicitly:
	    </p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
: relay.example.com,465 /SECURITY=SMTPS
</pre></div><p>
	      This example forwards all mail to
	      <code class="literal">relay.example.com</code> on port 465 using
	      encrypted <acronym class="acronym">SMTP</acronym>.
	    </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
		If you intend to use <code class="code">/SECURITY=SMTPS</code> to forward
		all your mail to your provider's mail server over
		<code class="code">smtps</code> additional you should also set
		<code class="code">ESMTP_TLS_VERIFY_DOMAIN=1</code>,
		<code class="code">TLS_VERIFYPEER=PEER</code>, and
		<code class="code">TLS_TRUSTCERTS</code> to a list of trusted certificate
		authorities (<span class="application">Courier</span>'s configuration
		script should provide a default value for
		<code class="code">TLS_TRUSTCERTS</code> on most platforms), in the
		<code class="filename">courierd</code> configuration file.
	      </p><p>
		Otherwise, <code class="code">TLS</code> 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
		<code class="code">SMTPS</code>. Poorly-managed Internet providers will
		just install a self-signed certificate, and will not be able to
		explain why they require <code class="code">SMTPS</code>, 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 <code class="code">/SECURITY=SMTPS</code>
		without actually enabling all the extra validation that's
		actually needed to gain any kind of a secure mail
		transmission channel.
	      </p></div><p>
	      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.
	    </p><p>
	      When the <span class="application">Courier</span> 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 <span class="application">Courier</span> 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.
	    </p><p>
	      The <code class="literal">/SECURITY=REQUIRED</code> flag blocks
	      the <span class="application">Courier</span> 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, <code class="literal">/SECURITY=REQUIRED</code> prevents
	      a man-in-the-middle attack where the remote mail server's
	      advertisement of is <code class="literal">STARTTLS</code> capability
	      gets suppressed, and the mail gets sent in the clear.
	    </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
		<code class="code">ESMTP_TLS_VERIFY_DOMAIN=1</code>,
		<code class="code">TLS_VERIFYPEER=PEER</code>, and
		<code class="code">TLS_TRUSTCERTS</code> should also be set, in the
		<code class="filename">courierd</code> configuration file, as described
		above, for the same reasons, in this case.
	      </p></div><p>
	      To summarize:
	    </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">/SECURITY=STARTTLS</code></span></dt><dd><p>
		    <span class="application">Courier</span>-specific extension,
		    use a private certificate authority to set up a secure
		    mail network, while supporting regular encrypted
		    <acronym class="acronym">TLS</acronym> with the rest of the world.
		  </p></dd><dt><span class="term"><code class="literal">/SECURITY=SMTPS</code></span></dt><dd><p>
		    Use regular encrypted <acronym class="acronym">SSL/TLS</acronym> with
		    this mail server. Use this flag with an
		    <code class="filename">esmtproutes</code> entry to
		    a server on port 465 (smtps).
		  </p></dd><dt><span class="term"><code class="literal">/SECURITY=REQUIRED</code></span></dt><dd><p>
		    Must use the <code class="literal">STARTTLS</code> extension to
		    open a regular encrypted <acronym class="acronym">TLS</acronym> connection
		    with this server on the regular SMTP port 25.
		  </p></dd></dl></div><p>
	      Changes to
	      <code class="filename">esmtproutes</code>
	      take effect immediately, more or less. Existing
	      <span class="command"><strong>courieresmtp</strong></span> processes that already have an
	      established connection will ignore any changes.
	    </p></dd><dt><span class="term"><code class="filename">esmtptimeout</code></span></dt><dd><p>
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.</p></dd><dt><span class="term"><code class="filename">esmtptimeoutconnect</code></span></dt><dd><p>
This file contains one line of text that specifies the timeout for an SMTP
connection attempt.  Most <acronym class="acronym">TCP</acronym>/<acronym class="acronym">IP</acronym> stacks wait an extraordinary long period of
time for SMTP connections to go through. This configuration setting limits
the amount of time the <span class="application">Courier</span> mail server waits for the SMTP connection to complete. The
default timeout is one minute. Set <code class="filename">esmtptimeoutconnect</code> to 0 in
order to use whatever default timeout your <acronym class="acronym">TCP</acronym>/<acronym class="acronym">IP</acronym> stack uses.</p></dd><dt><span class="term"><code class="filename">esmtptimeoutdata</code></span></dt><dd><p>
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.</p></dd><dt><span class="term"><code class="filename">esmtptimeouthelo</code></span></dt><dd><p>
This file contains one line of text that specifies the timeout for the
initial EHLO or HELO command. The <span class="application">Courier</span> 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.</p></dd><dt><span class="term"><code class="filename">esmtptimeoutkeepalive</code></span></dt><dd><p>
This file contains one line of text that specifies how often outbound SMTP
sessions are kept idle after delivering a message. After the <span class="application">Courier</span> 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 <span class="application">Courier</span> 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.</p><p>
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.</p></dd><dt><span class="term"><code class="filename">esmtptimeoutkeepaliveping</code></span></dt><dd><p>
This file contains one line of text that specifies how often the <span class="application">Courier</span> mail server will
issue a useless RSET command when the connection is idle (see
<code class="filename">esmtptimeoutkeepalive</code>). While waiting for any more messages to
deliver to the same domain, or for the <code class="filename">esmtptimeoutkeepalive</code>
interval to expire, <span class="command"><strong>courieresmtp</strong></span> 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
<code class="filename">esmtptimeoutkeepalive</code> 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 <span class="application">Courier</span> mail server configured for a maximum number of 200 outbound SMTP sessions and a
30 second <code class="filename">esmtptimeoutkeepaliveping</code> setting, then you can have
as much as an average of around seven pings every second!</p></dd><dt><span class="term"><code class="filename">esmtptimeoutquit</code></span></dt><dd><p>
This file contains one line of text that specifies how long the <span class="application">Courier</span> mail server waits
for the external SMTP server to acknowledge the QUIT command, before the <span class="application">Courier</span> mail server
unilaterally tears down the connection. The default value is 10 seconds. This
must be a small value because the <span class="application">Courier</span> mail server needs to be able to shut down quickly,
on very short notice.</p></dd><dt><span class="term"><code class="filename">faxqueuetime</code></span></dt><dd><p>
This file specifies how long the <span class="application">Courier</span> mail server normally tries to repeatedly resend a
fax message (if the <code class="literal">courierfax</code> module is enabled).
The default E-mail message retry timeout
(the <code class="filename">queuetime</code> 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.</p><p>
<code class="filename">faxqueuetime</code> specifies the timeout for fax messages.
This time interval is specified in the same way as
<code class="filename">queuetime</code>
(see <code class="filename">queuetime</code> for more information).</p></dd><dt><span class="term"><code class="filename">faxnotifyrc</code></span></dt><dd><p>
This file specifies which mailbox the <span class="application">Courier</span> mail server should deliver received faxes
(if this option is enabled).
See the <span class="application">Courier</span> mail server's installation notes for more information.</p></dd><dt><span class="term"><code class="filename">faxrc</code></span></dt><dd><p>
This file configures the <span class="application">Courier</span> mail server's outbound faxing and dialing parameters.
Consult the comments in the default file for additional information, and
the
<a class="ulink" href="courierfax.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">courierfax</span>(8)</span></a>
manual page for more information.</p></dd><dt><span class="term"><code class="filename">hosteddomains</code></span></dt><dd><p>
This file lists locally-hosted domains.  It is very similar in function to
the <code class="filename">locals</code> control file.  Any address with a domain listed in
<code class="filename">hosteddomains</code> is considered to be a local address.  The
difference between <code class="filename">hosteddomains</code> and <code class="filename">locals</code> is that
domains listed in <code class="filename">hosteddomains</code> are not removed from individual
addresses before looking up the location of their mailboxes.  For example, if
the domain "<code class="literal">example.com</code>" appears in <code class="filename">locals</code>, the
address <code class="literal">user@example.com</code> will have <code class="literal">example.com</code>
removed, and then the <span class="application">Courier</span> mail server will look for a local mailbox named
"<code class="literal">user</code>".</p><p>
If the domain "<code class="literal">example.com</code>" appears in
<code class="filename">hosteddomains</code> instead, the
<span class="application">Courier</span> mail server will look for a local mailbox
named "<code class="literal">user@example.com</code>" instead.</p><p>
	      The contents of the <code class="filename">hosteddomains</code>
	      configuration file is a list of domains, one per line,
	      in lowercase.  You must run the
	      <span class="command"><strong>makehosteddomains</strong></span> command, followed by
	      <span class="command"><strong>courier restart</strong></span> (this restarts the server)
	      for any changes to take
	      effect.
	    </p><p>
Additionally, <code class="filename">hosteddomains</code> can specify simple domain
aliases.
See the complete description in the
<a class="ulink" href="makehosteddomains.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">makehosteddomains</span>(8)</span></a>
manual page.</p></dd><dt><span class="term"><code class="filename">ipout</code>, <code class="filename">ip6out</code></span></dt><dd><p>
	      Non-default IP addresses to send outgoing ESMTP messages
	      from. See <a class="xref" href="#multihomed" title="Servers with multiple IP addresses" shape="rect">the section called “Servers with multiple IP addresses”</a> and
	      <a class="xref" href="#maybemultihomed" title="Simulating a server with multiple IP addresses" shape="rect">the section called “Simulating a server with multiple IP addresses”</a>, below,
	      for more information.
	    </p></dd><dt><span class="term"><code class="filename">ldapaddressbook</code></span></dt><dd><p>
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:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
name&lt;tab&gt;host&lt;tab&gt;port&lt;tab&gt;suffix&lt;tab&gt;binddn&lt;tab&gt;bindpw
</pre></div><p>
"<span class="token">&lt;tab&gt;</span>" is the ASCII tab character.


<span class="quote">“<span class="quote">name</span>”</span> is the
unique name for this LDAP server. <span class="quote">“<span class="quote">host</span>”</span> and <span class="quote">“<span class="quote">port</span>”</span> specify the
connection parameters. <span class="quote">“<span class="quote">suffix</span>”</span> specifies the root LDAP entry whose
subtree gets searched. The <span class="quote">“<span class="quote">binddn</span>”</span> and <span class="quote">“<span class="quote">bindpw</span>”</span> fields are not
presently used (they were used in earlier version of
the webmail server, before the
LDAP search interface was rewritten and simplified).</p></dd><dt><span class="term"><code class="filename">ldapaliasrc</code></span></dt><dd><p>
This file is used by the courierldapaliasd process. See
<a class="ulink" href="courierldapaliasd.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">courierldapaliasd</span>(8)</span></a>
for more information.</p></dd><dt><span class="term"><code class="filename">locallowercase</code></span></dt><dd><p>
If this file exists, the <span class="application">Courier</span> mail
server will not distinguish being lowercase and
uppercase local accounts, so that <code class="literal">john@example.com</code> and
<code class="literal">John@example.com</code> will refer to the same local mailbox (where
<code class="literal">example.com</code> is your domain). <code class="literal">Postmaster</code>,
<code class="literal">postmaster</code>, and <code class="literal">POSTMASTER</code> always refer to the same
account, even if <code class="filename">locallowercase</code> does not exist.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
If <code class="filename">locallowercase</code> exists you cannot have any system
accounts that contain uppercase letters. <code class="filename">locallowercase</code> applies
only to local mail.  Mail addressed to external domains will always have the
case of the addresses preserved.</p></div></dd><dt><span class="term"><code class="filename">locals</code></span></dt><dd><p>
This file contains one or more lines of text, where each line contains a
valid mail domain. Any E-mail address without <code class="literal">@domain</code>, or with a
domain that can be found in <code class="filename">locals</code> will be considered to be an
address of a local mailbox. A domain can be specified with a leading dot:
</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
 .domain.com
</pre></div><p>
This is called a "wildcard". Any domain ending in <code class="literal">domain.com</code>,
such as <code class="literal">a.domain.com</code>, <code class="literal">b.domain.com</code>,
<code class="literal">a.b.c.domain.com</code> - but NOT <code class="literal">somedomain.com</code> - will be
considered local.  Note that <code class="literal">domain.com</code> is NOT included in this
wildcard.  Both "<code class="literal">domain.com</code>" and "<code class="literal">.domain.com</code>"
should be listed.</p><p>
Specific hosts can be excluded from the wildcard.  Example:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
 !host.domain.com
 .domain.com
</pre></div><p>
<code class="literal">anything.domain.com</code> is considered to be a local domain, except for
<code class="literal">host.domain.com</code>.  Note that "<code class="literal">!host.domain.com</code>" must appear in
<code class="filename">locals</code> before the <code class="literal">.domain.com</code> wildcard.</p><p>
The "<code class="literal">!hostname</code>" syntax is also valid in the
<code class="filename">esmtpacceptmailfor</code> control file.</p><p>
If <code class="filename">locals</code> does not exist, the
<span class="application">Courier</span> mail server uses the contents of the
<code class="filename">me</code> control file (note that <code class="filename">me</code> specifies only one
domain, second and subsequent lines are ignored).  Also, see
<code class="filename">hosteddomains</code>.</p></dd><dt><span class="term"><code class="filename">localtimeout</code></span></dt><dd><p>
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
<code class="filename">localtimeout</code>
is specified in the same way as
<code class="filename">queuetime</code>
(see <code class="filename">queuetime</code> for more information).</p></dd><dt><span class="term"><code class="filename">logindomainlist</code></span></dt><dd><p>
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 <span class="application">Courier</span> mail server's webmail
server is used to provide mail access for more than one domain.  Instead of
typing "<code class="literal">user@domain</code>" to log in, it will only be necessary
to enter "<code class="literal">user</code>",
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.</p><div class="blockquote"><blockquote class="blockquote"><div class="blockquote-title"><p><strong>Enhanced login domain listing</strong></p></div><p>
The enhanced <code class="filename">logindomainlist</code> makes it possible to
specify a separate list of domain for each virtual web site,
and more control over the defaults.</p><p>What if you don't want to display a drop down menu?
Administrators can now
specify records that generate a hidden field in
<code class="filename">login.html</code>, or
an editable text field, allowing sqwebmail to show only one mail login domain
to each user per access <acronym class="acronym">URL</acronym> or <acronym class="acronym">IP</acronym> address. This functionality can greatly
reduce confusion for first time webmail users, and greatly speed the login
process for frequent webmail users.</p><p>
Finally, the new <code class="filename">logindomainlist</code> file offers a new tool to
ease maintenance. Administrators can now use wildcards to "rewrite" the
domain portion of the access <acronym class="acronym">URL</acronym> to the mail domain equivalent. For example,
the following record can rewrite the <acronym class="acronym">URL</acronym> "<code class="literal">mail.*.com</code>" to the
mail domain "<code class="literal">*.com</code>"</p><p><code class="literal">*.com:mail.*.com:@</code></p><p>
This powerful wildcard functionality can ease the login process for most
of your server's mail domains with just one or two
<code class="filename">logindomainlist</code> records.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">File Format</span></dt><dd><p>
Let's take a look at the NEW <code class="filename">logindomainlist</code> file
format:</p><p>
<code class="literal">firstfield:secondfield:thirdfield</code></p><p>
Above, we can see that the new <code class="filename">logindomainlist</code> records are
made up of three fields delimited by colons. But what does each field
do?</p><p>
<code class="literal">First Field</code> - 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
"<code class="literal">user@domain.com</code>", "<code class="literal">domain.com</code>"
is the mail domain.</p><p>
<code class="literal">Second Field</code> - the second field contains the
"access domain".
The access domain contains an <acronym class="acronym">URL</acronym> or <acronym class="acronym">IP</acronym> address that is used to figure out
which mail domain to use by default. For example, in the following
<code class="filename">logindomainlist</code> record:</p><p>
<code class="literal">domain1.com:domain2.com</code></p><p>
"<code class="literal">domain2.com</code>" is the "access domain" and
"<code class="literal">domain1.com</code>" is the "mail domain". If the user logs
into the following <acronym class="acronym">URL</acronym>:</p><p>
<code class="literal">http://domain2.com/cgi-bin/sqwebmail</code></p><p>
His default "mail domain" will be "<code class="literal">domain1.com</code>".</p><p>
<code class="literal">Third Field</code> - 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.</p><p>
Finally, the <code class="filename">logindomainlist</code> 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.</p><p>
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.</p></dd><dt><span class="term">Modifiers</span></dt><dd><p>
<code class="literal">@</code> - the '@' modifier can be used to create a hidden field on
the <code class="filename">login.html</code> 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.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
The '@' modifier ALLOWS the use of wildcards to automate the
relationship between "access domains" and "mail domains". See the heading
"<span class="emphasis"><em>Wildcards</em></span>" below for more
information about wildcarding.</p></div><p>
<code class="literal">-</code> - the '-' modifier can be used to create an editable text
field on the <code class="filename">login.html</code> page which contains the
default mail domain.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
The '-' modifier ALLOWS the use of wildcards to automate the
relationship between "access domains" and "mail domains". See the heading
"<span class="emphasis"><em>Wildcards</em></span>" below for more information about
wildcarding.</p></div><p>
<code class="literal">group string</code> - 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 <code class="filename">login.html</code> page.
Records
with the SAME group string will be displayed together in the drop down. For
example, if your <code class="filename">logindomainlist</code> file contains the following
records:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
     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</pre></div><p>
And the user logs into sqwebmail with the following <acronym class="acronym">URL</acronym>:</p><p>
<code class="literal">http://domain4.com/cgi-bin/sqwebmail</code></p><p>
He will see a drop down containing ONLY the following domains:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
     domain1.com
     domain3.com
     domain5.com</pre></div><p>
"<code class="literal">domain3.com</code>" will be automatically selected, or defaulted.
Only the records in the <code class="literal">firstgroup</code> will be visible to the
user.
This functionality is great for organizations with more than one mail
domain.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
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.</p></div></dd><dt><span class="term">Wildcards</span></dt><dd><p>
If a record's modifier allows wildcarding (See
"<span class="emphasis"><em>Modifiers</em></span>" 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. <acronym class="acronym">IP</acronym>
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 <acronym class="acronym">IP</acronym> address.</p><p>
In the <code class="filename">logindomainlist</code> 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 <code class="filename">logindomainlist</code>
record:</p><p>
<code class="literal">*.com:mail.*.com:@</code></p><p>
If the user logs into sqwebmail with the following <acronym class="acronym">URL</acronym>:</p><p>
<code class="literal">http://mail.mydomain.com/cgi-bin/sqwebmail</code></p><p>
The asterisk in the second field will represent the string
"<code class="literal">mydomain</code>". This string will then replace the asterisk
in the first field to give the following default mail domain:
<code class="literal">mydomain.com</code></p><p>
Similarly, if the following record exists in the
<code class="filename">logindomainlist</code> file:</p><p>
<code class="literal">*:*:@</code></p><p>
Then ANY <acronym class="acronym">URL</acronym> the user uses to access sqwebmail will be automatically used
for the default mail domain.</p><p>
But the first field doesn't _HAVE_ to contain an asterisk. The following
will work just fine:</p><p>
<code class="literal">mydomain.com:mydomain.*:@</code></p><p>
The above example will allow the user to access the
"<code class="literal">mydomain.com</code>" mail domain from any of the following <acronym class="acronym">URL</acronym>s:
"<code class="literal">mydomain.org</code>", "<code class="literal">mydomain.net</code>",
"<code class="literal">mydomain.us</code>", etc...</p><p>
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 <acronym class="acronym">URL</acronym>. This is useful because the
<code class="filename">logindomainlist</code> 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.</p></dd></dl></div></blockquote></div></dd><dt><span class="term"><code class="filename">maildirfilterconfig</code></span></dt><dd><p>
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 <span class="application">Courier</span> mail server.  Refer to the installlation instructions for additional
information.</p></dd><dt><span class="term"><code class="filename">maildirshared</code></span></dt><dd><p>
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
<a class="ulink" href="maildirmake.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">maildirmake</span>(1)</span></a>
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
<a class="ulink" href="maildirmake.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">maildirmake</span>(1)</span></a>
for more information.</p></dd><dt><span class="term"><code class="filename">maildrop</code></span></dt><dd><p>
This file contains one line whose contents is a pathname to the
<a class="ulink" href="maildrop.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">maildrop</span>(1)</span></a>
mail delivery agent. If the <span class="application">Courier</span> mail server knows
that the delivery agent used to delivery mail locally is
<a class="ulink" href="maildrop.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">maildrop</span>(1)</span></a>
then certain delivery optimizations
are possible. This configuration file does NOT actually specify that
<a class="ulink" href="maildrop.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">maildrop</span>(1)</span></a>
should be used as a local mail delivery
agent, it only specifies where
<a class="ulink" href="maildrop.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">maildrop</span>(1)</span></a>
is installed. The default local mail delivery instructions are specified in the
<code class="filename">courierd</code> configuration file. If the specified delivery
instruction specify running an external program whose pathname matches the
one specified by this configuration file, the <span class="application">Courier</span> mail server assumes that it's
<a class="ulink" href="maildrop.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">maildrop</span>(1)</span></a>,
and will use maildrop-specific options to optimize mail delivery.</p><p>
This configuration file is initialized, by default, to point to the
version of
<a class="ulink" href="maildrop.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">maildrop</span>(1)</span></a>
that's integrated with the <span class="application">Courier</span> mail server. The integrated version of
<a class="ulink" href="maildrop.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">maildrop</span>(1)</span></a>
is configured slightly differently than
the standalone version of
<a class="ulink" href="maildrop.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">maildrop</span>(1)</span></a>.</p><p>
Although you can set the <code class="filename">maildrop</code> configuration file to point
to some other version of the <span class="command"><strong>maildrop</strong></span> mail filter,
you MUST set the
<code class="filename">maildropfilter</code> configuration file (see below), to point to the
integrated version of <span class="command"><strong>maildrop</strong></span>.</p></dd><dt><span class="term"><code class="filename">maildropfilter</code></span></dt><dd><p>
This file contains one line whose contents is a pathname to the
<a class="ulink" href="maildrop.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">maildrop</span>(1)</span></a>
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 <span class="application">Courier</span> 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 <span class="application">Courier</span> mail server will not accept the message for delivery. This means
that when receiving mail via ESMTP, the <span class="application">Courier</span> mail server will reject the ESMTP transaction
without even accepting the message from the remote mail server.</p><p>
This file is not installed by default. To activate mail filtering for
local recipients, simply copy the contents of the <code class="filename">maildrop</code>
configuration file to <code class="filename">maildropfilter</code>.</p></dd><dt><span class="term"><code class="filename">maildroprc</code></span></dt><dd><p>
This file contains systemwide mail filtering instructions for
<a class="ulink" href="maildrop.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">maildrop</span>(1)</span></a>
deliveries.  This configuration file is
optional, and is used by
<a class="ulink" href="maildrop.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">maildrop</span>(1)</span></a>
when it
is invoked as a traditional post-delivery mail filter.  See
<a class="ulink" href="maildropfilter.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">maildropfilter</span>(6)</span></a>
for more information.</p></dd><dt><span class="term"><code class="filename">me</code></span></dt><dd><p>
This file contains one line whose contents is a valid machine name. When a
single installation of the <span class="application">Courier</span> mail server is shared over a network, each machine that's
running the <span class="application">Courier</span> mail server must have a unique <code class="filename">me</code> file. If me is missing,
The <span class="application">Courier</span> mail server uses the result of the <code class="function">gethostname</code>() system call.</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>
If you change the contents of this configuration file, it may be necessary
to rerun the <span class="command"><strong>makealiases</strong></span> 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
<span class="command"><strong>makealiases</strong></span>.</p></div></dd><dt><span class="term"><code class="filename">msgidhost</code></span></dt><dd><p>
If a message does not have a <code class="literal">Message-ID:</code> header, the <span class="application">Courier</span> mail server may
decide to create one. The host portion of the new header will be set to the
contents of <code class="filename">msgidhost</code>, which contains one line of text. If
<code class="filename">msgidhost</code> does not exist, <code class="filename">me</code> will
be used in its
place. Changes to this file take effect immediately.</p></dd><dt><span class="term"><code class="filename">nochangingfrom</code></span></dt><dd><p>
The <span class="application">Courier</span> mail server's webmail server lets the contents of the <code class="literal">From:</code>
header be set for mailed messages. If this configuration file exists, the
ability to set the contents of the <code class="literal">From:</code> header is disabled.</p></dd><dt><span class="term"><code class="filename">queuelo</code>,
<code class="filename">queuehi</code>,
<code class="filename">queuefill</code></span></dt><dd><p>
These configuration settings tune the <span class="application">Courier</span> mail server's mail queue processing.
The <span class="application">Courier</span> mail server does not load the entire mail queue metadata in memory.
<code class="filename">queuelo</code> contains a number that specifies the
queue <span class="quote">“<span class="quote">low watermark</span>”</span> message count.
<code class="filename">queuehi</code> contains a number that specifies the
queue <span class="quote">“<span class="quote">high watermark</span>”</span> message count.
<code class="filename">queuefill</code> specifies a time interval,
<span class="quote">“<span class="quote">queue refill</span>”</span> in seconds.
The number in <code class="filename">queuefill</code> may optionally be followed
by "m", indicating that the queue refill is specified in minutes.</p><p>
<code class="filename">queuehi</code> specifies the maximum number of messages that
are loaded into memory.
The <span class="application">Courier</span> mail server reads the mail queue on disk until either it reads all of it, or
it reads the number of messages specified by
<code class="filename">queuehi</code>.
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.</p><p>
When the number of messages in memory falls below <code class="filename">queuelo</code>,
The <span class="application">Courier</span> mail server goes back to disk and attempts to fill the memory queue to the top,
again.</p><p>
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 <span class="application">Courier</span> mail server simultaneously tries to
clear the existing backlog, and process any new mail at the same time.
Up to the <span class="application">Courier</span> mail server 0.41, all of this generally translates to the <span class="application">Courier</span> mail server giving
priority to newly arrived mail, and processing the backed up mail queue
if spare resources are available.</p><p>
The <code class="filename">queuefill</code> setting was added in the <span class="application">Courier</span> mail server 0.42, in
an attempt to keep new mail from excessively delaying existing mail during
a major queue backup.
<code class="filename">queuefill</code> specifies a time interval.
When the <span class="application">Courier</span> mail server completely fills the memory queue it sets a timer.
After the interval given by <code class="filename">queuefill</code> The <span class="application">Courier</span> 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 <span class="application">Courier</span> mail server finds older messages in the mail queue they will be pushed to the
top of the scheduling queue, and given priority.</p><p>
Smaller <code class="filename">queuefill</code> time intervals means more frequent
trips to the disk, and more overhead.
But, in exchange for that, during a mail backlog the <span class="application">Courier</span> mail server will spend more time
handling a greater number of delayed messages.
Larger <code class="filename">queuefill</code> time intervals means less frequent
trips to the disk, and less overhead, in exchange for less "fairness"
during large mail backlogs.</p><p>
<code class="filename">queuefill</code> 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 <code class="filename">queuelo</code> and
<code class="filename">queuehi</code> values are computed at run time.
<code class="filename">queuelo</code> defaults to the larger of 200, and the
sum total of configured
mail delivery slots, both local and remote.
<code class="filename">queuehi</code>, if not explicitly set, defaults to the smaller
of twice the <code class="filename">queuelo</code>, or <code class="filename">queuelo</code>
plus 1000.</p></dd><dt><span class="term"><code class="filename">queuetime</code></span></dt><dd><p>
This file specifies how long the <span class="application">Courier</span> 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
'<code class="literal">w</code>'
for weeks, or
'<code class="literal">d</code>'
for days. It is also possible to use
'<code class="literal">h</code>'
for hours,
'<code class="literal">m</code>'
for
minutes, or
'<code class="literal">s</code>'
for seconds. Only integers are allowed, fractions are
prohibited. However, you can use
'<code class="literal">1w2d</code>'
to specify one week and two days. If
<code class="filename">queuetime</code> is missing, the <span class="application">Courier</span> mail server makes repeated delivery
attempts
for one week.</p></dd><dt><span class="term"><code class="filename">retryalpha, retrybeta, retrygamma, retrymaxdelta</code></span></dt><dd><p>
These control files specify the schedule with which the <span class="application">Courier</span> mail server tries to deliver
each message that has a temporary, transient, delivery failure.
<code class="filename">retryalpha</code> and <code class="filename">retrygamma</code> contain a time interval,
specified in the same way as <code class="filename">queuetime</code>. <code class="filename">retrybeta</code>
and <code class="filename">retrymaxdelta</code> contain small integral numbers
only.</p><p>
The <span class="application">Courier</span> mail server will first make <code class="filename">retrybeta</code> delivery attempts, waiting
for the time interval specified by <code class="filename">retryalpha</code> between each
attempt. Then, the <span class="application">Courier</span> mail server waits for the amount of time specified by
<code class="filename">retrygamma</code>, then the <span class="application">Courier</span> mail server will make another
<code class="filename">retrybeta</code> delivery attempts, <code class="filename">retryalpha</code> amount of
time apart. If still undeliverable, the <span class="application">Courier</span> mail server waits <code class="filename">retrygamma</code>*2
amount of time before another <code class="filename">retrybeta</code> delivery attempts, with
<code class="filename">retryalpha</code> amount of time apart. The next delay will be
<code class="filename">retrygamma</code>*4 amount of time long, the next one
<code class="filename">retrygamma</code>*8, and so on.
<code class="filename">retrymaxdelta</code> sets the
upper limit on the exponential backoff. Eventually the <span class="application">Courier</span> mail server will keep waiting
<code class="filename">retrygamma</code>*(2^<code class="filename">retrymaxdelta</code>) amount of time before making
<code class="filename">retrybeta</code> delivery attempts <code class="filename">retryalpha</code> amount of
time apart, until the <code class="filename">queuetime</code> interval expires.</p><p>
The default values are:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">retryalpha</code></span></dt><dd><p>
Five minutes</p></dd><dt><span class="term"><code class="filename">retrybeta</code></span></dt><dd><p>
Three times</p></dd><dt><span class="term"><code class="filename">retrygamma</code></span></dt><dd><p>
Fifteen minutes</p></dd><dt><span class="term"><code class="filename">retrymaxdelta</code></span></dt><dd><p>
Three</p></dd></dl></div><p>
This results in the <span class="application">Courier</span> 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.</p></dd><dt><span class="term"><code class="filename">sizelimit</code></span></dt><dd><p>
Maximum size of the message, in bytes, that the <span class="application">Courier</span> mail server accepts for delivery.
The <span class="application">Courier</span> mail server rejects larger messages. If <code class="filename">sizelimit</code> is set to zero,
The <span class="application">Courier</span> mail server accepts as large message as available disk space permits. If the
environment variable <code class="envar">SIZELIMIT</code> is set at the time a new message
is received, it takes precedence and the <span class="application">Courier</span> mail server uses the contents of the
environment variable instead. Changes to this file take effect immediately.
The <code class="envar">SIZELIMIT</code> environment variable is for use by individual mail
submission agents.  For example, it can be set by the <code class="filename">smtpaccess</code>
configuration file (see
<a class="ulink" href="makesmtpaccess.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">makesmtpaccess</span>(8)</span></a>
for more information) for mail from certain <acronym class="acronym">IP</acronym> addresses.</p><p>
If <code class="filename">sizelimit</code> does not exist, and <code class="envar">SIZELIMIT</code> is
not set, the maximum message size defaults to 10485760 bytes.</p></dd><dt><span class="term"><code class="filename">submitdelay</code></span></dt><dd><p>
<code class="filename">submitdelay</code> 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
<a class="ulink" href="cancelmsg.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">cancelmsg</span>(1)</span>
</a>
command to reject duplicate messages in the queue
(and return them back to the envelope sender).</p><p>
<code class="filename">submitdelay</code> specifies a time interval in the same format as
<code class="filename">queuetime</code>.</p></dd><dt><span class="term"><code class="filename">usexsender</code></span></dt><dd><p>
If this configuration file exists, the <span class="application">Courier</span> mail server's webmail server will set the
<code class="literal">X-Sender: header</code> on all outgoing messages. This is a good idea
if the webmail server allows the user to set the contents of the
<code class="literal">From:</code> header. Note that the <span class="application">Courier</span> 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.</p></dd><dt><span class="term"><code class="filename">uucpme</code></span></dt><dd><p>
<code class="filename">uucpme</code> sets the UUCP nodename of the <span class="application">Courier</span> mail server mail relay.  See
<a class="ulink" href="courieruucp.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">courieruucp</span>(8)</span></a>
for more information.</p></dd><dt><span class="term"><code class="filename">uucpneighbors</code></span></dt><dd><p>
<code class="filename">uucpneighbors</code> is used by the <span class="command"><strong>courieruucp</strong></span> module to
specify the <span class="application">Courier</span> mail server's configuration for relaying mail via UUCP.  See
<a class="ulink" href="courieruucp.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">courieruucp</span>(8)</span></a>
for more information.</p></dd><dt><span class="term"><code class="filename">uucprewriteheaders</code></span></dt><dd><p>
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.</p></dd><dt><span class="term"><code class="filename">vhost.<em class="replaceable"><code>ip-address</code></em></code>, <code class="filename">vhost.<em class="replaceable"><code>domain</code></em></code></span></dt><dd><p>
	      Enable per-message virtual configuration settings described in
	      <a class="xref" href="#multihomed" title="Servers with multiple IP addresses" shape="rect">the section called “Servers with multiple IP addresses”</a> and
	      <a class="xref" href="#maybemultihomed" title="Simulating a server with multiple IP addresses" shape="rect">the section called “Simulating a server with multiple IP addresses”</a>, below,
	      for more information.
	    </p></dd><dt><span class="term"><code class="filename">warntime</code></span></dt><dd><p>
<code class="filename">warntime</code> specifies an amount of time in the same format as
<code class="filename">queuetime</code>. If a message still has not been delivered after this
period of time, the <span class="application">Courier</span> mail server sends a warning message (a "delayed" Delivery Status
Notification) to the sender. If <code class="filename">warntime</code> is missing, the <span class="application">Courier</span> mail server
sets <code class="filename">warntime</code> to four hours.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
The time interval specified by <code class="filename">warntime</code> is only
approximate. The <span class="application">Courier</span> mail server sends a delayed Delivery Status Notification at the
conclusion of the first attempted delivery after <code class="filename">warntime</code> has
elapsed.</p></div></dd></dl></div></div><div class="refsect2"><a id="idm139938116240800" shape="rect"> </a><h3>Webmail template files</h3><p>
HTML output from the webmail server is generated from the template files in
<code class="filename">/usr/lib/courier/sqwebmail/html/en-us</code>.
It is possible to translate the webmail interface into another language
simply by creating another subdirectory underneath
<code class="filename">/usr/lib/courier/sqwebmail/html</code>, then meticulously translating
each <code class="filename">.html</code> 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.</p><p>
The directory <code class="filename">/usr/lib/courier/sqwebmail/html/en-us</code> 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.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">CHARSET</span></dt><dd><p>
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.</p><p>
The default English HTML templates use strictly the <span class="quote">“<span class="quote">us-ascii</span>”</span>
subset, and the <code class="filename">CHARSET</code> contains
<code class="literal">utf-8,iso-8859-1</code>.
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 <code class="literal">UTF-8</code>, falling back to
<code class="literal">ISO-8859-1</code> for browsers that do not support
<code class="literal">UTF-8</code>.</p></dd><dt><span class="term">footer</span></dt><dd><p>
The contents of this file, if it exists, are appended to all messages sent
by the webmail server.</p></dd><dt><span class="term">ISPELLDICT</span></dt><dd><p>
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 <span class="command"><strong>ispell</strong></span>, or
<span class="command"><strong>aspell</strong></span>.</p></dd><dt><span class="term">LANGUAGE</span></dt><dd><p>
This file consists of a single line of text, which
should always be the same as the name of its directory
(<code class="literal">en-us</code>).</p></dd><dt><span class="term">LANGUAGE_PREF</span></dt><dd><p>
This file is not needed at runtime, its contents are used during
installation.
See <code class="filename">webmail/html/README_LANG</code> in the source
distribution for more information.</p></dd><dt><span class="term">LOCALE</span></dt><dd><p>
The corresponding C locale for these templates.</p></dd><dt><span class="term">TIMEZONELIST</span></dt><dd><p>
This file lists the available timezones on the login screen.
See the comments in this file for more information.</p></dd></dl></div></div><div class="refsect2"><a id="SPF" shape="rect"> </a><h3>Sender Policy Framework Keywords</h3><p>
	The <span class="application">Courier</span> mail server can perform <span class="quote">“<span class="quote">Sender Policy Framework</span>”</span> checks on up to
	three addresses for each message.
	This is controlled by setting the following variables:
	<code class="envar">BOFHSPFHELO</code>,
	<code class="envar">BOFHSPFMAILFROM</code>, and
	<code class="envar">BOFHSPFFROM</code>.
	Each variable is set to a comma-separated list of the following keywords:
	<span class="quote">“<span class="quote">off</span>”</span> - SPF verification disabled (default);
	<span class="quote">“<span class="quote">none</span>”</span>,
	<span class="quote">“<span class="quote">neutral</span>”</span>,
	<span class="quote">“<span class="quote">pass</span>”</span>,
	<span class="quote">“<span class="quote">fail</span>”</span>,
	<span class="quote">“<span class="quote">softfail</span>”</span>,
	<span class="quote">“<span class="quote">error</span>”</span>,
	<span class="quote">“<span class="quote">unknown</span>”</span> - 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;
	<span class="quote">“<span class="quote">all</span>”</span> - shorthand for all possible SPF results, use
	<span class="quote">“<span class="quote">all</span>”</span> to run SPF in informational mode only, recording the
	SPF status in the <code class="literal">Received-SPF:</code> header;
	<span class="quote">“<span class="quote">allowok</span>”</span> - automatically pass the SPF verification if
	the sender's IP address is found in a DNS access whitelist, any
	whitelist given in the <code class="option">-allow</code> option to
	<span class="command"><strong>couriertcpd</strong></span>, see the
	<span class="quote">“<span class="quote">DNS ACCESS LISTS</span>”</span> section in
	<a class="ulink" href="couriertcpd.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">couriertcpd</span>(1)</span>
	</a>.
      </p><p>
	A rejected SPF result gets kicked back with a permanent error indication
	if the SPF result is listed in <code class="envar">BOFHSPFHARDERROR</code>, and
	a temporary error indication otherwise.</p><p>
	When enabling SPF checking, the keyword list should always include
	<span class="quote">“<span class="quote">pass</span>”</span> (it makes no sense to do otherwise) and
	<span class="quote">“<span class="quote">none</span>”</span>.
	The keyword list should also include <span class="quote">“<span class="quote">softfail</span>”</span>,
	<span class="quote">“<span class="quote">neutral</span>”</span>, and <span class="quote">“<span class="quote">unknown</span>”</span>.
	See the SPF draft for a description of these status results.
	At some distant future, the keyword list will only include
	<span class="quote">“<span class="quote">pass</span>”</span>, rejecting all senders without a stated policy.
	This might be desirable at some point in the future, but not right now.</p><p>
	The <code class="envar">BOFHSPFFROM</code> list may also include an additional keyword,
	<span class="quote">“<span class="quote">mailfromok</span>”</span>.
	<code class="envar">BOFHSPFMAILFROM</code> and
	<code class="envar">BOFHSPFFROM</code> are trade-offs.
	Using <code class="envar">BOFHSPFMAILFROM</code> is faster, and it does not require
	the entire message to be received, before running the SPF check.
	<code class="envar">BOFHSPFFROM</code> checking can only occur after the entire message
	is received, but it's more reliable.
	If <span class="quote">“<span class="quote">mailfromok</span>”</span> is listed, the <code class="literal">From:</code> is not
	checked if the <code class="literal">MAIL FROM</code> command was checked
	with the <span class="quote">“<span class="quote">pass</span>”</span> result.</p><p>
	In other words:
	the <code class="literal">From:</code> header is checked if
	<code class="literal">MAIL FROM</code> was empty, or did not pass the SPF checks.
	If <code class="literal">MAIL FROM</code> passed the SPF check the <span class="application">Courier</span> mail server won't bother
	looking at the <code class="literal">From:</code> header.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
	  A conservative policy should not reject failed SPF checks from the
	  <code class="literal">From:</code>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 <acronym class="acronym">IP</acronym> address, and it will fail the SPF check unless
	  the domain SPF explicitly authorizes the mailing list processor's <acronym class="acronym">IP</acronym>
	  address.</p><p>
	  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 <span class="quote">“<span class="quote">mailfromok</span>”</span> keyword can validate
	  the mailing list's return address, and forego checking of
	  the <span class="quote">“<span class="quote">From:</span>”</span> header from the mailing list, while still checking
	  the <span class="quote">“<span class="quote">From:</span>”</span> header from everyone else.</p><p>
	  Another alternative is to use
	  <code class="envar">opt BOFHSPFFROM=all</code> for advisory purposes only.
	  Post-delivery mail filters can key off the <span class="quote">“<span class="quote">Received-SPF</span>”</span>
	  header.</p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
	  The <span class="application">Courier</span> mail server can add up to three <span class="quote">“<span class="quote">Received-SPF</span>”</span> headers of its own,
	  one for each SPF check.
	  The <span class="application">Courier</span> mail server renames any existing <span class="quote">“<span class="quote">Received-SPF</span>”</span> header as
	  <span class="quote">“<span class="quote">Old-Received-SPF</span>”</span>.
	  All <span class="quote">“<span class="quote">Received-SPF</span>”</span> headers delivered to a local mailbox will
	  always come from the <span class="application">Courier</span> mail server.</p></div></div><div class="refsect2"><a id="multihomed" shape="rect"> </a><h3>Servers with multiple IP addresses</h3><p>
	The <span class="application">Courier</span> mail server's default
	configuration listens on port 25 on all IP addresses. If the
	server has more than one IP address, <span class="application">Courier</span>
	accepts connections on any IP address.
	Adjust the settings in the <code class="filename">esmtpd</code> configuration
	file to explicitly list which IP addresses
	<span class="application">Courier</span> should listenson.
	This also applies to the ESMTP over SSL server on port 465 configured
	by <code class="filename">esmtpd-ssl</code>, and the <acronym class="acronym">MSA</acronym>
	server on port 587, configured by <code class="filename">esmtpd-msa</code>.
      </p><p>
	That's for incoming EMSTP. For outgoing ESMTP connections,
	the <span class="application">Courier</span> 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.
      </p><p>
	The
	<code class="filename">ipout</code> and
	<code class="filename">ip6out</code> configuration files set an explicit IP
	address for <span class="application">Courier</span>'s outgoing connections:
      </p><div class="blockquote"><blockquote class="blockquote"><div class="informalexample"><pre class="programlisting" xml:space="preserve">
# echo "192.168.0.1" &gt;/etc/courier/ipout
# echo "fec0::230:48ff:fec4:429c" &gt;/etc/courier/ip6out</pre></div></blockquote></div><p>
	This example specifies <code class="literal">192.168.0.1</code> as the IP
	address to make connections from for IPv4 destinations, and
	<code class="literal">fec0::230:48ff:fec4:429c</code> for IPv6 destinations.
      </p><p>
	If the <span class="application">Courier</span>
	mail server runs on a host with two IPv4 addresses,
	<code class="literal">192.168.0.1</code>,
	<code class="literal">192.168.1.1</code>, the above example uses
	<code class="literal">192.168.0.1</code> to send the relayed message to IPv4
	destinations even if <span class="application">Courier</span> received the
	message from a client that connected to the other addresses.
      </p><p>
	If the <span class="application">Courier</span> mail server accepts an
	ESMTP connection and a message from an authenticated client with
	relaying privileges, in a smarthost role, and forwards the message
	via ESMTP, <span class="application">Courier</span> normally uses the server's
	default IP address, or the one set by
	<code class="filename">ipout</code> or <code class="filename">ipout6</code>.
	When the <span class="application">Courier</span> mail servers runs on
	more than
	one IP address, it's possible to selectively
	set the outgoing IP address based on which one of those IP addresses
	the message was received at.
	A simple, basic
	configuration forwards the message from the same IP addresses
	it was received from, but it doesn't have to be, it can be a different
	one.
      </p><p>
	The first step is to enable a per-message, non-default configuration
	settings, like the outgoing IP address, by creating a zero-length
	<code class="filename">vhost.<em class="replaceable"><code>ip-address</code></em></code>
	file:
      </p><div class="blockquote"><blockquote class="blockquote"><div class="informalexample"><pre class="programlisting" xml:space="preserve">
# touch &gt;/etc/courier/vhost.192.168.0.1
# touch &gt;"/etc/courier/vhost.fec0::230:48ff:fec4:429c"</pre></div></blockquote></div><p>
	This enables non-default settings for messages received from a client
	that connects to one of these IP addresses.
	These two IP addresses (one IPv4 and one IPv6 address) are, presumably,
	two of the server's IP addresses. This is not a client's IP address,
	these are the server's IP addresses. These may be the only two
	IP addresses the server has, or the server can have more IP addresses,
	but these are the only two IP addresses for which custom settings
	get enabled.
      </p><p>
	One such custom setting would be
	a different IP address for outgoing connections
	depending on the IP address of the connection the message was
	originally received from:
      </p><div class="blockquote"><blockquote class="blockquote"><div class="informalexample"><pre class="programlisting" xml:space="preserve">
# echo "192.168.0.1" &gt;/etc/courier/ipout.192.168.0.1
# echo "192.168.1.1" &gt;/etc/courier/ipout.192.168.1.1</pre></div></blockquote></div><p>
	<span class="quote">“<span class="quote"><code class="filename">ipout.<em class="replaceable"><code>address</code></em></code></span>”</span>
	sets the IP address for outgoing connections for messages received
	from a client connection to
	<span class="quote">“<span class="quote"><em class="replaceable"><code>address</code></em></span>”</span> only.
	Just an <code class="filename">ipout</code> applies to all other messages, except
	ones which have an <code class="filename">ipout.<em class="replaceable"><code>address</code></em></code>
	in existence.
	The above example specifies that, on a server with these two IP
	addresses, messages received from a client that's connected to either
	IP address get forwarded (from a client that normally authenticates
	and receives relaying privileges) using a connection from the same
	IP address.
	If the server has any other IP addresses, the IP address in
	<code class="filename">ipout</code> takes effect (or the default system-specified
	IP address).
      </p><p>
	For convenience, an empty <code class="filename">ipout.<em class="replaceable"><code>address</code></em></code>
	gets interpreted as if it contains
	the same <em class="replaceable"><code>address</code></em>.
	The above example is equivalent to:
      </p><div class="blockquote"><blockquote class="blockquote"><div class="informalexample"><pre class="programlisting" xml:space="preserve">
# touch /etc/courier/ipout.192.168.0.1
# touch /etc/courier/ipout.192.168.1.1</pre></div></blockquote></div><p>
	The formal configuration rules are as follows, for a message
	received from IP address
	<span class="quote">“<span class="quote"><em class="replaceable"><code>address</code></em></span>”</span>, which may be an
	IPv4 or an IPv6 address:
      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
	    The IPv4 address and the IPv6 address for outgoing ESMTP connections
	    get specified by the contents of
	    <code class="filename">/etc/courier/ipout.<em class="replaceable"><code>address</code></em></code>
	    and
	    <code class="filename">/etc/courier/ip6out.<em class="replaceable"><code>address</code></em></code>, respectively.
	  </p></li><li class="listitem"><p>
	    If the file exists, but is empty, the same
	    <em class="replaceable"><code>address</code></em> becomes the IP address for the
	    outgoing connection.
	  </p></li><li class="listitem"><p>
	    The above rules are in effect only if
	    <code class="filename">/etc/courier/vhost.<em class="replaceable"><code>address</code></em></code> exists,
	  </p></li><li class="listitem"><p>
	    If the file does not exist, or if
	    <code class="filename">/etc/courier/vhost.<em class="replaceable"><code>address</code></em></code>
	    does not exist, the contents of
	    <code class="filename">/etc/courier/ipout</code>, for IPv4 connections, and
	    <code class="filename">/etc/courier/ip6out</code>, for IPv6 connections
	    set the IP address.
	  </p></li><li class="listitem"><p>
	    Otherwise, the <span class="application">Courier</span> mail server
	    uses the default IP address determined by the system's network
	    configuration.
	  </p></li><li class="listitem"><p>
	    In
	    <code class="filename">/etc/courier/ipout.<em class="replaceable"><code>address</code></em></code>
	    and
	    <code class="filename">/etc/courier/ip6out.<em class="replaceable"><code>address</code></em></code>,
	    an address of "0" also specifies the system's default IP address.
	  </p></li></ul></div><p>
	It is possible for the <span class="application">Courier</span> mail server
	to receive a message from an IPv6 connection, and forward it to an
	IPv4 address, or vice versa.
	The <em class="replaceable"><code>address</code></em> portion of
	<code class="filename">/etc/courier/ipout.<em class="replaceable"><code>address</code></em></code>
	and
	<code class="filename">/etc/courier/ip6out.<em class="replaceable"><code>address</code></em></code>,
	specifies the IP address the client used to connect to
	<span class="application">Courier</span> and may be either an IPv4 or an
	IPv6 address, in both cases! For example:
      </p><div class="blockquote"><blockquote class="blockquote"><div class="informalexample"><pre class="programlisting" xml:space="preserve">
# echo "192.168.0.1" &gt;/etc/courier/ipout.192.168.0.1
# echo "fec0::230:48ff:fec4:429c" &gt;/etc/courier/ip6out.192.168.0.1</pre></div></blockquote></div><p>
	This means that when a client connects to the
	<span class="application">Courier</span> mail server using the IP address
	<code class="literal">192.168.0.1</code> and relays a message, if the message
	gets forwarded to an IPv4 address,
	<span class="application">Courier</span> uses the same IP address,
	and if it gets forwarded to an IPv6 address
	<span class="application">Courier</span> uses this IPv6 address.
	The above also probably means that:
      </p><div class="blockquote"><blockquote class="blockquote"><div class="informalexample"><pre class="programlisting" xml:space="preserve">
# echo "192.168.0.1" &gt;"/etc/courier/ipout.fec0::230:48ff:fec4:429c"
# echo "fec0::230:48ff:fec4:429c" &gt;"/etc/courier/ipout.fec0::230:48ff:fec4:429c"</pre></div></blockquote></div><p>
	So if an IPv6 client connects to <span class="application">Courier</span>
	on this IPv6 address and relays a message,
	<span class="application">Courier</span> uses the same IPv6 address, or
	<code class="literal">192.168.0.1</code> depending on the destination.
      </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
	  Notwithstanding the IP address set in an
	  <code class="filename">ipout</code> or an
	  <code class="filename">ip6out</code> 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.
	</p></div><p>
	Additionally, for all other configuration files described in this
	manual page, the <span class="application">Courier</span> mail server uses
	<span class="quote">“<span class="quote"><code class="filename">filename.<em class="replaceable"><code>address</code></em></code></span>”</span> if it exists,
	in place of
	<span class="quote">“<span class="quote"><code class="filename">filename</code></span>”</span> when processing messages
	received from <span class="quote">“<span class="quote">address</span>”</span>, either an IPv4 or an IPv6
	address.
      </p><p>
	This is used in all contexts where it makes sense to do so:
      </p><div class="blockquote"><blockquote class="blockquote"><div class="informalexample"><pre class="programlisting" xml:space="preserve">
# echo "relay.example.com" &gt;/etc/courier/me.192.168.0.1
# echo "firewall.example.com" &gt;/etc/courier/me.192.168.1.1</pre></div></blockquote></div><p>
	This example specifies <span class="quote">“<span class="quote">relay.example.com</span>”</span> as the
	contents of the <code class="filename">me</code> configuration file,
	described earlier in this manual page, when processing messages
	received by clients that connect to <code class="literal">192.168.0.1</code>,
	and <span class="quote">“<span class="quote">firewall.example.com</span>”</span> for processing messages
	received by clients that connect to <code class="literal">192.168.1.1</code>.
      </p><p>
	<span class="quote">“<span class="quote"><code class="filename">me</code></span>”</span>
	is the default hostname for
	most common <span class="application">Courier</span> mail server configuration
	settings, such as the server's name in the ESMTP greeting banner,
	what <span class="application">Courier</span> calls itself in the
	ESMTP <span class="command"><strong>EHLO/HELO</strong></span> commands, and other contexts,
	unless overridden by a more specific setting.
      </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
	  The IP address-specific configuration settings get used only in the
	  context of processing messages, and have no impact on other parts of
	  the <span class="application">Courier</span> mail server that do not have
	  a direct relationship to a specific message. One such example would
	  be when
	  <span class="application">Courier</span> 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.
	</p></div></div><div class="refsect2"><a id="maybemultihomed" shape="rect"> </a><h3>Simulating a server with multiple IP addresses</h3><p>
	As described in the previous section,
	the existence of <code class="filename">vhost.<em class="replaceable"><code>ip-address</code></em></code>
	enables configuration settings only for messages that were received
	at one of the IP addresses that the
	<span class="application">Courier</span> mail server accepts connections on.
      </p><p>
	It's possible to partially achieve the same end results by creating
	<code class="filename">vhost.<em class="replaceable"><code>domain</code></em></code>:
      </p><div class="blockquote"><blockquote class="blockquote"><div class="informalexample"><pre class="programlisting" xml:space="preserve">
# touch &gt;/etc/courier/vhost.example.com</pre></div></blockquote></div><p>
	This enables per-message specific configuration for messages received
	from authenticated clients whose authenticated ID ends
	with <span class="quote">“<span class="quote">@example.com</span>”</span>.
	If the server has more than one IP address, but, for whatever reason,
	only receives mail on one of them but wants to use the other one for
	outgoing mail for this domain:
      </p><div class="blockquote"><blockquote class="blockquote"><div class="informalexample"><pre class="programlisting" xml:space="preserve">
# echo '192.168.0.1' &gt;/etc/courier/ipout.example.com</pre></div></blockquote></div><p>
	This sets this IP address for
	all outgoing messages with a <span class="quote">“<span class="quote">@example.com</span>”</span> authenticated
	client.
	It's important to note the following limitations:
      </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
	    The Courier authentication library (see installation instructions)
	    must be configured with accounts and mailboxes that follow the
	    <span class="quote">“<span class="quote">user@domain</span>”</span> format.
	  </p></li><li class="listitem"><p>
	    Not all configuration settings can be customized in a
	    <code class="filename"><em class="replaceable"><code>setting</code></em>.<em class="replaceable"><code>domain</code></em></code>.
	    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
	    <span class="quote">“<span class="quote">me</span>”</span> configuration setting gets set before the
	    return address is received, so the contents of a domain-specific
	    <span class="quote">“<span class="quote">me</span>”</span> may not be in effect in all contexts.
	  </p></li><li class="listitem"><p>
	    Anyone can use any return address they wish. Some mitigation is
	    possible, of course, using measures such as
	    <acronym class="acronym">SPF</acronym>, but it would be mistake to believe that this
	    is much more than just eye candy.
	  </p></li><li class="listitem"><p>
	    Both an IP address and domain-based <span class="quote">“<span class="quote">vhost</span>”</span>s are
	    allowed. An IP address-based vhost takes precedence.
	  </p></li></ul></div></div></div><div class="refsect1"><a id="idm139938116075264" shape="rect"> </a><h2>BUGS</h2><p>
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.</p><p>
<span class="command"><strong>courier start</strong></span> fails if the <span class="application">Courier</span> mail server has detected a fatal
operational error. In this situation the top-level
<span class="command"><strong>courierd</strong></span> daemon sleeps for
a minute, before automatically restarting. During this sleep interval courier
stop does not work.</p></div><div class="refsect1"><a id="idm139938116071472" shape="rect"> </a><h2>SEE ALSO</h2><p>
<a class="ulink" href="cancelmsg.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">cancelmsg</span>(1)</span>
</a>,
<a class="ulink" href="maildirmake.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">maildirmake</span>(1)</span>
</a>,
<a class="ulink" href="maildrop.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">maildrop</span>(1)</span>
</a>,
<a class="ulink" href="preline.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">preline</span>(1)</span>
</a>,
<a class="ulink" href="sendmail.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">sendmail</span>(1)</span>
</a>,
<a class="ulink" href="testmxlookup.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">testmxlookup</span>(1)</span>
</a>,
<a class="ulink" href="dot-courier.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">dot-courier</span>(5)</span>
</a>,
<a class="ulink" href="authlib.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">authlib</span>(7)</span>
</a>,
<a class="ulink" href="courierfax.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">courierfax</span>(8)</span>
</a>,
<a class="ulink" href="courierfilter.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">courierfilter</span>(8)</span>
</a>,
<a class="ulink" href="courierfilter.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">filterctl</span>(8)</span>
</a>,
<a class="ulink" href="courierldapaliasd.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">courierldapaliasd</span>(8)</span>
</a>,
<a class="ulink" href="courierpop3d.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">courierpop3d</span>(8)</span>
</a>,
<a class="ulink" href="courierpop3d.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">courierpop3d</span>(8)</span>
</a>,
<a class="ulink" href="couriertcpd.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">couriertcpd</span>(8)</span>
</a>,
<a class="ulink" href="courieruucp.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">courieruucp</span>(8)</span>
</a>,
<a class="ulink" href="esmtpd.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">esmtpd</span>(8)</span>
</a>,
<a class="ulink" href="imapd.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">imapd</span>(8)</span>
</a>,
<a class="ulink" href="localmailfilter.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">localmailfilter</span>(7)</span>
</a>,
<a class="ulink" href="mailq.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">mailq</span>(1)</span>
</a>,
<a class="ulink" href="makeacceptmailfor.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">makeacceptmailfor</span>(8)</span>
</a>,
<a class="ulink" href="makealiases.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">makealiases</span>(8)</span>
</a>,
<a class="ulink" href="makehosteddomains.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">makehosteddomains</span>(8)</span>
</a>,
<a class="ulink" href="makepercentrelay.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">makepercentrelay</span>(8)</span>
</a>,
<a class="ulink" href="makesmtpaccess.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">makesmtpaccess</span>(8)</span>
</a>,
<a class="ulink" href="makeuserdb.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">makeuserdb</span>(8)</span>
</a>,
<a class="ulink" href="makeuserdb.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">pw2userdb</span>(8)</span>
</a>,
<a class="ulink" href="mkdhparams.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">mkdhparams</span>(8)</span>
</a>,
<a class="ulink" href="mkesmtpdcert.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">mkesmtpdcert</span>(8)</span>
</a>,
<a class="ulink" href="mkimapdcert.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">mkimapdcert</span>(8)</span>
</a>,
<a class="ulink" href="pop3d.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">pop3d</span>(8)</span>
</a>,
<a class="ulink" href="submit.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">submit</span>(8)</span>
</a>,
<a class="ulink" href="userdb.html" target="_top" shape="rect">
<span class="citerefentry"><span class="refentrytitle">userdb</span>(8)</span>
</a>.</p></div></div></body></html>
courier-doc 0.78.0-2ubuntu2 / usr / share / doc / courier-doc / html / courier.html
