Provided by: courier-mta_1.0.6-1build2_amd64 bug

NAME

       courier - The Courier mail server

SYNOPSIS

       courier {start | stop | restart | flush | flush qid  | clear user@domain  | clear all  |
               show all }

DESCRIPTION

       The Courier mail server is a modular multi-protocol E-mail transport agent. The courier
       command is an administrative command, and most of its options are only available to the
       superuser.

       "courier start" starts the server by running /usr/lib/courier/courierctl.start in the
       background. "courier stop" immediately stops all the Courier mail server processes and
       aborts all current mail deliveries. "courier restart" restarts the Courier mail server
       server. A restart is often needed for certain configuration changes to take effect.
       "courier restart" waits for all current deliveries to complete before restarting. This is
       the "nice" way to restart the mail server. "courier flush" takes all undelivered messages
       in the queue and attempts to deliver them immediately, instead of waiting until their next
       scheduled attempted delivery time. "courier flush" can be optionally followed by a message
       queue ID in order to schedule an immediate delivery attempt for only a single message.
       Message queue IDs are displayed by the mailq(1)[1] command.

       Please note that courier start runs the main Courier mail server scheduling engine only.
       It does not start any other daemons that you may have, such as the ESMTP or the IMAP
       daemon.

       "courier show all" lists all E-mail addresses currently blacklisted for backscatter.
       "courier clear user@domain" manually clears <user@domain> from the backscatter blacklist.
       "courier clear all" removes all addresses from the backscatter blacklist. When the Courier
       mail server encounters a delivery failure to an E-mail address the Courier mail server may
       stop accepting any more messages to the same address in order to minimize generation of
       so-called "backscatter bounces". This does not occur in all cases, see "Backscatter
       suppression" in the Courier mail server's installation instructions for more information.

       The Courier mail server will resume accepting messages to the blacklisted address if the
       delivery attempt originally encountered a temporary failure, and a subsequent retry
       succesfully delivered the message, or if more than two hours elapsed since the delivery
       failure. Use the "clear" command to manually clear the E-mail address from the backscatter
       blacklist. This may be useful if the undeliverable message is manually removed from the
       Courier mail server's mail queue, using the "cancel" command. Even if the message is
       cancelled, the Courier mail server will continue to refuse accepting mail for this address
       for up to two hours. The "clear" command can be use to reenable mail acceptance before
       then.

   CONFIGURATION FILES
       The Courier mail server uses several configuration files which are located in
       /etc/courier. These configuration files are plain text files that can be modified with any
       text editor. In certain instances a subdirectory is used, and all plain text files in the
       subdirectory are concatenated and are considered to be a single, consolidated,
       configuration file. Unless otherwise specified, you must run courier restart for any
       changes to these files to take effect.

       aliasfilteracct
           This file contains one line, containing the home directory of the account that's used
           for filtering mail addressed to local alias lists.

           When mail filtering is enabled, local recipients have the ability to define mail
           filters which can selectively reject unwanted mail.  /etc/courier/aliases may define
           local mail aliases that contain one or more recipients. If it is desired to use local
           mail filtering for mail addressed to an alias address, designate a local account that
           will be used to specify filtering instructions, and put its home directory into this
           control file. The filtering argument will be "alias-address" where address is the name
           of the alias. See localmailfilter(7)[2] for more information.

           Due to technical limitations, content filtering is not available for
           multiple-recipient aliases.

           Changes to this file take effect immediately.

       autoresponsesquota
           This file sets the systemwide quota on autoreplies, if autoreplies and mail filtering
           are enabled. Note that this can only really be effective if there is no login access
           to the mail account, since this autoreply quota can be trivially overriden.

           The autoresponsesquota file contains one line: "Cnnn" or "Snnn" (or both strings, on
           the same line).  Cnnn: allow up to #nnn autoreplies to be created.  Snnn: allow up to
           #nnn bytes as the total size of all autoreplies, combined. If both Cnnn and Snnn are
           specified, both quotas apply. If this file does not exist, there is no limit on
           autoreplies. This quota setting applies systemwide. To override the quota setting for
           a particular Maildir, create the autoresponsesquota file in that Maildir (which takes
           precedence).

       backuprelay
           This file contains one line, containing a name of a machine where mail will be
           rerouted if it cannot be immediately delivered. Spaces are not allowed in this file.

           Mail gets rerouted if it cannot be delivered after the time interval specified by the
           warntime configuration file. When backuprelay is provided a delayed delivery status
           notification will NOT be generated. The message will be rerouted even if the
           recipient's delivery status notification setting does not include a delayed
           notification request.

           This feature is intended for use by relays that handle large quantities of mail, where
           you don't want to accumulate a large mail queue for unreachable mail servers. Please
           note that ALL undeliverable mail will be rerouted in this fashion. Even if the
           recipient of a message is a local recipient - and the recipient's mail filter is
           rejecting the message with a temporary error code - the message will still be rerouted
           if it's undeliverable after the specified amount of time.

           Although currently SMTP is the only meaningful application for this feature, the
           Courier mail server is a protocol-independent mail server, and the backup relay
           function can be extended to other protocols, as they become available.

           Multiple backup relays can be used by simply assigning multiple IP addresses to the
           same machine name. Note that the Courier mail server checks for both MX and A records
           for the machine specified in this configuration file.

           It's important to note that when this setting is specified, warning messages get
           turned off for all messages, including messages addressed to local recipients. If a
           temporary delivery error prevents a message from being delivered to a local mailbox,
           it remains in the queue until the temporary error condition gets cleared. Normally, if
           the message remains in the queue beyond the warning interval, the warning message gets
           generated. When this setting is specified, the warning message gets replaced with a
           forward to the backup relay, but this occurs only for messages that are delivered via
           SMTP.

       batchsize
           This file contains one line, containing a single number. This number specifies the
           absolute maximum number of recipients for a single message. If the Courier mail server
           receives a message with more recipients, the message is duplicated as often as
           necessary until each copy of the message has no more than batchsize recipients. If
           batchsize is missing, it defaults to 100 recipients per message.

       bofh
           This configuration file configures domain-based junk mail filters. Lines in this
           configuration files that begin with the # character are considered comments, and are
           ignored. The remaining lines contain the following directives, in any order:

           badfrom user@domain
               Reject all mail with the return address of <user@domain>.

           badfrom @domain
               Reject all mail with the return address of <anything@domain>.

           badfrom @.domain
               Reject all mail with the return address of <anything@anything.domain>.

           badfrom user@.domain
               Reject all mail with the return address of <user@anything.domain>.

           badmx N
               Reject all mail with a return address in any mail domain whose listed mail servers
               include server "N". "N" is an IP address. The BOFHCHECKDNS option in the esmtp
               configuration file must also be enabled (this is the default setting) in order for
               this additional checking to take place. Note that this is "best effort" check. A
               DNS failure to look up A records for hostnames returned in the MX record may hide
               the blacklisted server from view.

           freemail domain [domain2] [domain3]...
               Reject all mail with a return address <anything@domain> unless the mail is
               received from a mail relay whose hostname is in the same domain. "domain2" and
               "domain3" are optional, and specifies other domains that the mail relay's hostname
               may belong to. For example: "freemail example.com domain.com" specifies that mail
               with a return address @example.com will be accepted only from a mail relay with a
               hostname in the example.com or domain.com domain. Note that this setting requires
               that DNS lookup be enabled for incoming ESMTP connections (which is the default
               setting).

           spamtrap user@domain
               Reject all mail that has <user@domain> listed as one of its recipients.

                   Note
                   For local mailboxes, 'domain' must be set to the contents of the me
                   configuration file, or the server's hostname. Also, this check is made after
                   any alias processing takes place. Suggested usage: create a single local
                   spamtrap account, then create aliases in the alias file that point to the
                   spamtrap account.

           maxrcpts N [hard]
               Accept the first N recipient addresses per message, maximum. The remaining
               recipients are rejected. An optional verbatim token "hard" specifies that the
               remaining recipients will immediately be returned as undeliverable (otherwise the
               remaining recipients are rejected as "temporary unavailable", and may be accepted
               on a later delivery attempt). If not specified, the first 100 recipients are
               accepted.

           opt BOFHCHECKHELO=1
               Verify the hostname provided in the ESMTP HELO/EHLO statement.  “opt
               BOFHCHECKHELO=1” is a global default, which may be overridden by setting the
               BOFHCHECKHELO environment variable in the SMTP access file. See
               makesmtpaccess(8)[3] for more information.  “opt BOFHCHECKHELO=1” enables ESMTP
               HELO/EHLO checking by default, and ESMTP HELO/EHLO checking may be turned off for
               individual IP address ranges by setting BOFHCHECKHELO to 0 using
               makesmtpaccess(8)[3]. Alternatively, HELO/EHLO checking may be turned off by
               default, and enabled for specific IP address ranges by using makesmtpaccess(8)[3]
               to set BOFHCHECKHELO to 1. See makesmtpaccess(8)[3] for more information.

           opt BOFHCHECKHELO=2
               Setting to BOFHCHECKHELO 2 has the effect of returning a temporary SMTP error
               code, instead of a permanent SMTP error code, for a failed HELO/EHLO SPF check.

           opt BOFHHEADERLIMIT=n
               Reject messages whose headers exceed n bytes in size (minimum 1,000 bytes, default
               100,000 bytes).

           opt BOFHNOBASE64TEXT=1
               Reject messages with base64-encoded text/plain or text/html content.

           opt BOFHSPFHELO=keywords
               Use Sender Policy Framework to verify the HELO or EHLO domain sent by the
               connecting SMTP client. See Sender Policy Framework Keywords below for a list of
               possible keywords.

               SPF checking is not used for HELO or EHLO commands that specify an IP address
               instead of a domain name.

                   Note
                   This setting may be used in combination with opt BOFHCHECKHELO=1. The
                   BOFHCHECKHELO=1 check is disabled if SPF verification of the HELO/EHLO results
                   in the SPF status of “pass”. This makes sense: if the HELO/EHLO domains
                   complies with the domain's SPF, it is not necessary to check it further.

           opt BOFHSPFMAILFROM=keywords
               Use Sender Policy Framework to verify the return address in the MAIL FROM command
               sent by the connecting SMTP client. See Sender Policy Framework Keywords below for
               a list of possible keywords.

                   Note
                   No SPF checking is done for if the MAIL FROM command specifies an empty return
                   address (a bounce). There's nothing to check.

           opt BOFHSPFFROM=keywords
               Use Sender Policy Framework to verify the return address in the From: header. See
               Sender Policy Framework Keywords below for important information, and a list of
               possible keywords.

           opt BOFHSPFHARDERROR=keywords
               This setting lists the unacceptable SPF results that should result in a permanent
               error. All other unacceptable SPF results are kicked back with a temporary error
               indication, inviting the sender to try again later.

               The default setting for BOFHSPFHARDERROR is fail,softfail.

           opt BOFHSPFTRUSTME=1
               Disable all SPF checks for any connecting client that has relaying privileges
               (RELAYCLIENT is explicitly set, or inherited after a successful SMTP
               authentication).

           opt BOFHSPFNOVERBOSE=1
               This setting disables custom SPF rejection messages. Any SPF rejection message
               specified by the SPF policy is replaced by a stock, bland message. The author of
               this SPF implementation believes that there's a minor security issue with letting
               an external site control the error messages issued by your mail server. The same
               author does not believe that this is such a big deal, but security-sensitive minds
               may choose to enable this setting, and sleep easy at night.

           opt BOFHSUPPRESSBACKSCATTER=list
               This is one of the two settings that controls which messages are subject to
               backscatter suppression. The other setting, ESMTP_BLOCKBACKSCATTER is set in the
               courierd configuration file, which contains further documentation.

               “list” is a comma-separated list of message sources. The possible message sources
               are:

               authsmtp
                   Messages received via SMTP from clients with relaying privileges
                   (authenticated SMTP, or IP addresses that always have relaying privileges.

               smtp
                   All other messages received via SMTP.

               none
                   Do not suppress backscatter messages from any source.

               The default setting is “opt BOFHSUPPRESSBACKSCATTER=smtp”. The other possible
               values are “opt BOFHSUPPRESSBACKSCATTER=smtp,authsmtp” (which suppresses
               backscatter from all SMTP mail), and “opt BOFHSUPPRESSBACKSCATTER=none”.

       calendarmode
           This configuration file enables basic calendaring features in the webmail server.
           Calendaring is currently considered experimental in nature, and the current
           implementation provides basic calendaring services. If this file does not exist,
           calendaring options are disabled. If this file exists it should contain a single word:
           "local". For example:

               echo "local" >/etc/courier/calendarmode
           This configuration file must be globally readable, so make sure that your umask is not
           set too tight.

       courierd
           This configuration file specifies several parameters relating to general the Courier
           mail server configuration. A default configuration file will be installed, and you
           should consult its contents for additional information.

       defaultdomain
           This file contains one line whose contents is a valid mail domain. Most header
           rewriting functions will append @defaultdomain to all E-mail addresses that do not
           specify a domain. If defaultdomain is missing, the Courier mail server uses the
           contents of the me control file.

           When the ESMTP server receives a “RCPT TO” command containing the address
           <user@[ip.address]>, and the IP address is the same as the IP address of the socket
           it's listening on, the ESMTP server replaces the IP address with the contents of the
           defaultdomain control file. If defaultdomain is missing, the Courier mail server uses
           the contents of the me control file.

           The contents of defaultdomain are also appended to return addresses to mail sent from
           the Courier mail server's webmail server, if they don't already have a domain. If
           defaultdomain does not exist, the Courier mail server's webmail server obtain the
           machine hostname, and uses that.

               Note
               The mail domain in defaultdomain should be one of the local domains, as defined by
               the locals and the hosteddomains control files.

               Otherwise, if a domain-less address in mail headers gets augmented with
               defaultdomain and the recipient replies to the message, upon receipt Courier won't
               recognize the recipient address as a local mailbox. This might not necessarily be
               wrong, but the consequences of such an action must be clearly understood.

               Warning
               If you change the contents of this configuration file, it may be necessary to
               rerun the makealiases command again, else your mail will promptly begin to bounce.
               If you don't have this configuration file defined, and you change the system's
               network host name, you may also need to run makealiases.

       dotextension
           This file contains one line whose contents specify the name of dot-files in users'
           home directories which contain delivery instructions. If this file does not exist, the
           Courier mail server reads $HOME/.courier, $HOME/.courier-foo, $HOME/.courier-default,
           and so on. If this file contains the text "qmail", the Courier mail server will
           instead read $HOME/.qmail, $HOME/.qmail-foo, $HOME/.qmail-default, and so on.

       dsnfrom
           This file contains one line specifying the contents of the From: header that the
           Courier mail server puts in all delivery status notifications. This file specifies a
           complete header, except for the "From: " part. If dsnfrom is missing, then the Courier
           mail server uses the following header: "Courier mail server mail server at me" <@>

       dsnlimit
           Maximum size, in bytes, of a message whose contents are included in delivery status
           notifications. By default, the entire message is only included in non-delivery notices
           (failures). Only the headers will be returned for delay notifications (warnings) and
           return receipts; or for failures if the original message is larger than dsnlimit. If
           missing, dsnlimit is set to 32K.

           The sender can request that the entire message be returned even on delayed notices or
           return receipts, however the Courier mail server will ignore this request if the
           message size exceeds this limit.

       enablefiltering
           This configuration file enables the global mail filtering API for selected mail
           sources. This file, if it exists, contains a single line of text that specifies which
           kind of mail will be filtered. The possible values are:

           esmtp
               Enables global mail filtering for mail received via ESMTP.

           local
               Specifies that mail received from logged on users, via sendmail, and mail
               forwarded from dot-courier(5)[4] will be filtered using the global mail filtering
               API.

           uucp
               Specifies that mail received from UUCP will be filtered.

           If you want to specify more than one source of mail, such as ESMTP and local mail,
           specify both esmtp and local, separated by a space character.

               Note
               The global mail filtering API is described, in detail, in the courierfilter(8)[5]
               manual page. This is NOT the traditional user-controlled mail filtering, such as
               maildrop(1)[6]. A global mail filter is a daemon process that selectively accepts
               or rejects incoming mail, based on arbitrary criteria.

       esmtpacceptmailfor
           This file lists all domains that the Courier mail server accepts mail for via ESMTP.
           This file is in the same format as the locals file. If this file is missing, the
           Courier mail server uses the single domain specified in me (or the system machine
           name).

       esmtpacceptmailfor.dat
           This is a binary database file that lists additional domains that the Courier mail
           server accepts mail for, just like esmtpacceptmailfor. A binary database file will be
           faster than a flat text file when the number of domains is large. The Courier mail
           server will accept mail for domains listed in either esmtpacceptmailfor or
           esmtpacceptmailfor.dat.  esmtpacceptmailfor.dat is created by the makeacceptmailfor
           command. You can use both esmtpacceptmailfor.dat and esmtpacceptmailfor at the same
           time. Put your most popular domains in esmtpacceptmailfor, and put the rest of them
           into esmtpacceptmailfor.dat.

       esmtpauthclient
           This configuration file configures ESMTP authentication for the ESMTP client. This is
           a text file of zero or more lines that contain the following fields:

               relay userid password
           When the Courier mail server connects to a remote ESMTP relay, the Courier mail server
           will authenticate itself using userid and password. These fields are separated by one
           or more whitespace characters. Because this file contains passwords, it must not be
           world or group readable, and owned by the user "courier".

           ESMTP negotiation will take place, and the Courier mail server will use a SASL
           authentication method supported by both the Courier mail server and the remote ESMTP
           server. Currently the Courier mail server supports PLAIN, LOGIN and CRAM-MD5
           authentication. CRAM-MD5 is preferred over the other two, and PLAIN is preferred over
           LOGIN.

           The Courier mail server also supports ESMTP over SSL (the ESMTP STARTTLS extension).
           If ESMTP STARTTLS is enabled, STARTTLS will be used to establish a secure link first.
           The authentication will take place afterwards, over a secure channel.

           Changes to this file take effect, more or less, immediately (existing connections are
           not affected, but new connections will read the updated data).

       esmtpd
           This file is used to initialize the environment and parameters for courieresmtpd. A
           default file will be provided during installation. See the comments in the file for
           more information. For changes to this file to take effect you run the esmtpd stop
           command followed by esmtpd start.

       esmtpdelay
           This file contains one line of text that specifies how long courieresmtp waits after a
           failure to contact the remote mail server before another attempt is made.
           courieresmtp (not to be confused with courieresmtpd) delivers outgoing mail to remote
           mail servers. The timeout is specified as an integral number, optionally followed by m
           - minutes, or h - hours. Otherwise it is specified in seconds.

           The courieresmtp process delivers mail that's routed to external mail relays, via
           ESMTP. When attempting to initally contact a mail server courieresmtp waits for the
           amount of time specified by esmtptimeoutconnect (see below).  esmtptimeoutconnect is
           usually set to a relatively long period of time, in order to accomodate slow mail
           servers. A large number of messages queued up for an unreachable mail server can tie
           up delivery slots that can be put to a better use by reassigning them for mail to
           another domain. Although the Courier mail server does not usually assign all delivery
           slots for messages to the same domain (this is a tuneable parameter), it is still not
           very healthy to have a bunch of courieresmtp daemons spinning their wheels, doing
           nothing.

           The situation worsens when there is a large number of mail relays that accept mail for
           the same domain, and all of them are unreachable due to a network failure. That's
           because the esmtptimeout waiting period is used for each individual mail relay.
           Multiply esmtptimeout by the number of servers to see how large the delay really will
           be.

           esmtpdelay is implemented internally in the courieresmtp module. The main the Courier
           mail server scheduling daemon is not aware of what's happening internally in
           courieresmtp. When courieresmtp fails to contact any mail relay for the domain, the
           message is postponed, and the esmtpdelay timer is set. Any additional messages
           received by the same courieresmtp daemon (for the same domain), are immediately
           postponed without any attempt to contact a remote mail relay. When the amount of time
           set by esmtpdelay expires, courieresmtp will attempt to make another delivery attempt
           as usual.

           If esmtpdelay does not exist, the default delay is five minutes. Any messages that are
           postponed look like any other temporary failure to courierd. Delivery attempts are
           rescheduled as if a real temporary failure took place. Therefore it does not make
           sense to set esmtpdelay to be greater than retryalpha (see below). When retryalpha is
           smaller is esmtpdelay, you'll just messages spinning through the mail queue, with
           useless delivery attempts being attempted because esmtpdelay still hasn't expired.

           Occasionally you might observe somewhat strange behavior on systems with heavy mail
           traffic.  esmtpdelay applies separately to each individual instance of courieresmtp.
           When a remote mail server keeps going up and down, it is possible to end up with
           multiple courieresmtp daemons handling mail for the same domain, but only some of them
           will encounter a network failure, purely by the luck of the draw. The remaining
           daemons will be able to establish a connection. So you'll end up with some
           courieresmtp daemons being able to deliver mail immediately, while the rest are still
           waiting patiently for esmtpdelay to expire, postponing all messages in the meantime.
           Some messages - but not all - will be immediately postponed without a delivery
           attempt, becauses they ended up getting to a daemon which is waiting for esmtpdelay to
           expire.

           Another anomalous situation may happen when a courieresmtp daemon gets reassigned to
           another domain, and then receives more mail for the previous domain. This can happen
           when you have a lot of mail going through. Although the Courier mail server tries to
           shuffle all mail for same domain into one pile, the scheduler still tries to dispatch
           mail on "first-come, first-serve" basis, as much as possible. When that happens
           another delivery attempt will be made immediately, because the previous esmtpdelay was
           cancelled when the daemon got reassigned to another domain.

           There can also be occasional abnormalities that affect systems with light traffic.
           When there is a domain with several mail relays of equal priority, one mail relay is
           chosen at random for the connection attempt. If some of the equal-priority mail relays
           are unreachable and a courieresmtp daemon picks it, it will start the esmtpdelay timer
           and refuse to deliver any more mail until it expires, even if most of the mail servers
           are functional. This will happen only with mail relays of the lowest priority.
           Otherwise, courieresmtp will always try to contact another mail relay of a still lower
           priority, before giving up and setting the esmtpdelay timer. Another courieresmtp
           daemon will not be started for the same domain if there's already an existing one, so
           all delivery attempts will be turned away until esmtpdelay expires. Another
           courieresmtp daemon will be started only in the event of multiple simultaneous
           delivery attempts that happen to coincide at the same time.

           This is somewhat mitigated by the fact that all courieresmtp daemons are killed after
           a short period of total inactivity (currently one minute), so that longer intervals
           specified by esmtpdelay are ignored. Note, however, that receiving a message to
           deliver, and then postponing it immediately, does count as some activity.

           esmtpdelay can be turned off by setting it to 0 seconds.  esmtpdelay is designed for
           servers that handle heavy amount of mail that wish to avoid having outbound delivery
           slots tied up due to network failures, at an expense of an occasional anomalous
           behavior due to harmless paranoia.  esmtpdelay may prove to actually make things worse
           for systems that carry only light mail traffic, if they are burdened with a task of
           exchanging mail primarily with external systems that are not properly maintained.

       esmtpgreeting
           The complete greeting banner displayed by courieresmtpd. Changes to this file take
           effect immediately.

       esmtphelo
           This file contains one line of text, what the Courier mail server calls itself in the
           EHLO or HELO command sent to a remote SMTP server.  me is used if this file does not
           exist.

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

               echo '*' >esmtphelo
           (Note the single quotes, to prevent “*” from being expanded by the shell). The Courier
           mail server will take the IP address of the local side of the connection to the remote
           SMTP server, look up the IP address in DNS, and use the hostname from the reverse DNS
           lookup. This might be useful when the Courier mail server server is multihomed. The
           Courier mail server will look up the local IP address of each individual connection,
           and use that in its EHLO or HELO command.

               Note
               Functioning DNS is required. Using the hosts file, or an equivalent, won't work.
               This function uses the Courier mail server's native DNS resolver, which reads
               /etc/resolv.conf and queries the listed DNS servers directly.

               Note
               See the section called “Servers with multiple IP addresses” for a better way of
               accomplishing the same results.

       esmtproutes
           This file is used by the ESMTP module, and it contains one or more lines in the
           following form:

               domain:relay[,port][/SECURITY=STARTTLS][/SECURITY=REQUIRED][/SECURITY=SMTPS]
           domain is any SMTP domain.  relay specifies a fixed mail relay for this domain.  relay
           is optionally followed by a comma and a port number, to specify a port other than the
           default port 25. If an address's domain is not found in esmtproutes, the Courier mail
           server looks for MX and A records as usual (and always delivers to port 25). If the
           domain is found in esmtproutes, however, any MX or A records for the domain are
           ignored; instead the Courier mail server delivers the message to the specified relay.

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

               example.com: relay.domain.com
               domain.com: [192.168.0.2]
           Mail for example.com is delivered to relay.domain.com, ignoring any MX records for
           example.com. Mail for domain.com will be delivered to the machine at IP address
           192.168.0.2. All other domains will have their MX and A records looked up.

               Note
               Unlike Qmail, the Courier mail server looks up MX and A records for
               relay.example.com (Qmail only looks up A records).
           esmtproutes may contain comments, any line that starts with the # character is
           ignored. Also, wildcards are allowed:

                .example.com: [192.168.0.3],26
           This specifies that any address of the form <anything@anything.example.com> will be
           delivered to the mail server at this IP address, but on port 26.

           esmtproutes is read from top to bottom, stopping as soon as a first match is found.

           domain may be empty, this specifies a smarthost for all domains. For example, if
           esmtproutes contains the following text:

               example.com: relay.example.com
                       :[192.168.0.4]
           This specifies that all mail to example.com is rerouted to relay.example.com. All
           other mail is routed to the IP address 192.168.0.4.

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

               example.com:
               :[192.168.0.4]
           This uses MX and A records for all messages to example.com. All other mail is rerouted
           to the IP address 192.168.0.4.

           The /SECURITY=STARTTLS flag indicates that mail to this domain will use the SECURITY
           ESMTP extension. See the Courier mail server installation notes for a description of
           SECURITY, what it does, and how to configure it.

               Note
               /SECURITY=STARTTLS does not refer to the standard implementation of SMTP over TLS,
               but a Courier-specific extension.  Courier automatically sends mail using
               encryption if it's enabled and the remote server advertises STARTTLS.
           /SECURITY=SMTPS uses an encrypted SMTP connection. This is an alternative to STARTTLS.
           Encrypted SMTP uses a different port, port 465, which must be specified explicitly:

               : relay.example.com,465 /SECURITY=SMTPS
           This example forwards all mail to relay.example.com on port 465 using encrypted SMTP.

               Note
               If you intend to use /SECURITY=SMTPS to forward all your mail to your provider's
               mail server over smtps additional you should also set ESMTP_TLS_VERIFY_DOMAIN=1,
               TLS_VERIFYPEER=PEER, and TLS_TRUSTCERTS to a list of trusted certificate
               authorities (Courier's configuration script should provide a default value for
               TLS_TRUSTCERTS on most platforms), in the courierd configuration file.

               Otherwise, TLS still gets used to send mail, but the smarthost's certificate does
               not get validated. Properly-managed Internet providers should install a valid
               certificate, signed by a trusted authority, if they require SMTPS. Poorly-managed
               Internet providers will just install a self-signed certificate, and will not be
               able to explain why they require SMTPS, if it's trivially compromised with a
               man-in-the-middle attack that a non-validated certificate enables, so either find
               a more competent provider, or use /SECURITY=SMTPS without actually enabling all
               the extra validation that's actually needed to gain any kind of a secure mail
               transmission channel.
           A combination of broken mail servers written by incompetent programmers, and
           poorly-managed Internet providers will result in a mail server that advertises the
           ability to use an encrypted connection to receive mail, but either disconnect
           immediately, or return an error message when the sender takes up the receiver's offer
           to do so.

           When the Courier mail server connects to another server that claims to support an
           encrypted connection, tries to enable it, then fails because the other mail server
           drops the connection or returns an error message, all subsequent connection attempts
           to the same mail server will ignore the server's false advertising, and proceed to
           send mail without attempting to enable encryption. The Courier mail server remembers
           not to use the encryption with this server for the next 2-4 hours (depending on an
           internal log file's rotation schedule). Once the remote mail server emerges from the
           penalty box, the next connection attempt will try again, and see if it's still doesn't
           work.

           The /SECURITY=REQUIRED flag blocks the Courier mail server from sending mail to the
           remote server unless a standard encryped connection can get established. If it's known
           that the given mail server should only receive encrypted mail, /SECURITY=REQUIRED
           prevents a man-in-the-middle attack where the remote mail server's advertisement of is
           STARTTLS capability gets suppressed, and the mail gets sent in the clear.

               Note
               ESMTP_TLS_VERIFY_DOMAIN=1, TLS_VERIFYPEER=PEER, and TLS_TRUSTCERTS should also be
               set, in the courierd configuration file, as described above, for the same reasons,
               in this case.
           To summarize:

           /SECURITY=STARTTLS
               Courier-specific extension, use a private certificate authority to set up a secure
               mail network, while supporting regular encrypted TLS with the rest of the world.

           /SECURITY=SMTPS
               Use regular encrypted SSL/TLS with this mail server. Use this flag with an
               esmtproutes entry to a server on port 465 (smtps).

           /SECURITY=REQUIRED
               Must use the STARTTLS extension to open a regular encrypted TLS connection with
               this server on the regular SMTP port 25.

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

       esmtptimeout
           This file contains one line of text that specifies the timeout for an SMTP command.
           The timeout is specified as an integral number, optionally followed by m - minutes, or
           h - hours. Otherwise it is specified in seconds. This timeout is used for all SMTP
           commands, unless the SMTP command has a dedicated timeout defined by a different
           configuration file. The default timeout is ten minutes.

       esmtptimeoutconnect
           This file contains one line of text that specifies the timeout for an SMTP connection
           attempt. Most TCP/IP stacks wait an extraordinary long period of time for SMTP
           connections to go through. This configuration setting limits the amount of time the
           Courier mail server waits for the SMTP connection to complete. The default timeout is
           one minute. Set esmtptimeoutconnect to 0 in order to use whatever default timeout your
           TCP/IP stack uses.

       esmtptimeoutdata
           This file contains one line of text that specifies the timeout for transferring the
           message contents or individual replies. The default timeout is five minutes. You WILL
           HAVE TO bump this up if you're on a slow link, and you want to send large messages. A
           28.8Kbps link can be optimistically expected to push 3,000 bytes per second. With a
           five minute cutoff, you will not be able to send or receive anything larger than about
           870 Kb. You have no business sending or receiving 870 Kb messagesl, if all you have is
           an analog 28.8Kbps connection.

       esmtptimeouthelo
           This file contains one line of text that specifies the timeout for the initial EHLO or
           HELO command. The Courier mail server will wait this amount of time to receive the
           initial greeting banner from the remote SMTP server, and a response to the subsequent
           EHLO/HELO command. The default value is 5 minutes.

       esmtptimeoutkeepalive
           This file contains one line of text that specifies how often outbound SMTP sessions
           are kept idle after delivering a message. After the Courier mail server connects to an
           SMTP server and completes the attempt to deliver the message, the SMTP session is kept
           idle for this time interval before being shut down. If the Courier mail server
           receives another message for the same domain, it will be delivered using the existing
           SMTP session, instead of establishing a new one. Note that some SMTP servers have a
           very short idle timeout, Qmail's is only two minutes. The default value is 60 seconds.

           Note that there's also a separate limit to the maximum number of simultaneous SMTP
           sessions to the same domain. That limit is currently four, which is adequate for
           nearly every situation, so for now it will be set by an undocumented configuration
           file.

       esmtptimeoutkeepaliveping
           This file contains one line of text that specifies how often the Courier mail server
           will issue a useless RSET command when the connection is idle (see
           esmtptimeoutkeepalive). While waiting for any more messages to deliver to the same
           domain, or for the esmtptimeoutkeepalive interval to expire, courieresmtp will
           transmit RSET commands at regular intervals specified by this configuration file. The
           default value is 0 seconds, which turns off the keepalive ping altogether. This
           configuration settings must be for a shorter time interval than esmtptimeoutkeepalive
           for it to make any sense. Note that other system administrators may consider this to
           be a very rude thing to do. Also keep in mind that this may generate quite a bit of
           idle traffic. If you have the Courier mail server configured for a maximum number of
           200 outbound SMTP sessions and a 30 second esmtptimeoutkeepaliveping setting, then you
           can have as much as an average of around seven pings every second!

       esmtptimeoutquit
           This file contains one line of text that specifies how long the Courier mail server
           waits for the external SMTP server to acknowledge the QUIT command, before the Courier
           mail server unilaterally tears down the connection. The default value is 10 seconds.
           This must be a small value because the Courier mail server needs to be able to shut
           down quickly, on very short notice.

       faxqueuetime
           This file specifies how long the Courier mail server normally tries to repeatedly
           resend a fax message (if the courierfax module is enabled). The default E-mail message
           retry timeout (the queuetime setting) is one week, which is a reasonable timeout value
           for E-mail messages (taking into account downed circuits, or crashed servers).
           However, it doesn't make sense to keep trying to redeliver fax messages for a whole
           week.

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

       faxnotifyrc
           This file specifies which mailbox the Courier mail server should deliver received
           faxes (if this option is enabled). See the Courier mail server's installation notes
           for more information.

       faxrc
           This file configures the Courier mail server's outbound faxing and dialing parameters.
           Consult the comments in the default file for additional information, and the
           courierfax(8)[7] manual page for more information.

       hosteddomains
           This file lists locally-hosted domains. It is very similar in function to the locals
           control file. Any address with a domain listed in hosteddomains is considered to be a
           local address. The difference between hosteddomains and locals is that domains listed
           in hosteddomains are not removed from individual addresses before looking up the
           location of their mailboxes. For example, if the domain "example.com" appears in
           locals, the address user@example.com will have example.com removed, and then the
           Courier mail server will look for a local mailbox named "user".

           If the domain "example.com" appears in hosteddomains instead, the Courier mail server
           will look for a local mailbox named "user@example.com" instead.

           The contents of the hosteddomains configuration file is a list of domains, one per
           line, in lowercase. You must run the makehosteddomains command, followed by courier
           restart (this restarts the server) for any changes to take effect.

           Additionally, hosteddomains can specify simple domain aliases. See the complete
           description in the makehosteddomains(8)[8] manual page.

       ipout, ip6out
           Non-default IP addresses to send outgoing ESMTP messages from. See the section called
           “Servers with multiple IP addresses” and the section called “Simulating a server with
           multiple IP addresses”, below, for more information.

       ldapaddressbook
           This file is used by the webmail server. It contain a default systemwide list of
           accessible LDAP address books. A default file will be installed, listing some common
           Internet address books. Each line in this file contains the following information:

               name<tab>host<tab>port<tab>suffix<tab>binddn<tab>bindpw
           "<tab>" is the ASCII tab character.  “name” is the unique name for this LDAP server.
           “host” and “port” specify the connection parameters.  “suffix” specifies the root LDAP
           entry whose subtree gets searched. The “binddn” and “bindpw” fields are not presently
           used (they were used in earlier version of the webmail server, before the LDAP search
           interface was rewritten and simplified).

       ldapaliasrc
           This file is used by the courierldapaliasd process. See courierldapaliasd(8)[9] for
           more information.

       locallowercase
           If this file exists, the Courier mail server will not distinguish being lowercase and
           uppercase local accounts, so that john@example.com and John@example.com will refer to
           the same local mailbox (where example.com is your domain).  Postmaster, postmaster,
           and POSTMASTER always refer to the same account, even if locallowercase does not
           exist.

               Note
               If locallowercase exists you cannot have any system accounts that contain
               uppercase letters.  locallowercase applies only to local mail. Mail addressed to
               external domains will always have the case of the addresses preserved.

       locals
           This file contains one or more lines of text, where each line contains a valid mail
           domain. Any E-mail address without @domain, or with a domain that can be found in
           locals will be considered to be an address of a local mailbox. A domain can be
           specified with a leading dot:

                .domain.com
           This is called a "wildcard". Any domain ending in domain.com, such as a.domain.com,
           b.domain.com, a.b.c.domain.com - but NOT somedomain.com - will be considered local.
           Note that domain.com is NOT included in this wildcard. Both "domain.com" and
           ".domain.com" should be listed.

           Specific hosts can be excluded from the wildcard. Example:

                !host.domain.com
                .domain.com
           anything.domain.com is considered to be a local domain, except for host.domain.com.
           Note that "!host.domain.com" must appear in locals before the .domain.com wildcard.

           The "!hostname" syntax is also valid in the esmtpacceptmailfor control file.

           If locals does not exist, the Courier mail server uses the contents of the me control
           file (note that me specifies only one domain, second and subsequent lines are
           ignored). Also, see hosteddomains.

       localtimeout
           This file specifies the watchdog timer for local mail deliveries. If a local mail
           delivery attempt does not complete in the proscribed time interval, the delivering
           process ID is killed. The time interval in localtimeout is specified in the same way
           as queuetime (see queuetime for more information).

       logindomainlist
           If this file exists then the webmail login screen will have a drop-down list whose
           contents will be read from this file. This file should contain a list of E-mail
           domains, one per line. It should be created if the Courier mail server's webmail
           server is used to provide mail access for more than one domain. Instead of typing
           "user@domain" to log in, it will only be necessary to enter "user", and select the
           domain from the drop-down list. If this file does not exist it will be necessary to
           enter the full E-mail address into the webmail login screen.  The enhanced
           logindomainlist makes it possible to specify a separate list of domain for each
           virtual web site, and more control over the defaults.

           What if you don't want to display a drop down menu? Administrators can now specify
           records that generate a hidden field in login.html, or an editable text field,
           allowing sqwebmail to show only one mail login domain to each user per access URL or
           IP address. This functionality can greatly reduce confusion for first time webmail
           users, and greatly speed the login process for frequent webmail users.

           Finally, the new logindomainlist file offers a new tool to ease maintenance.
           Administrators can now use wildcards to "rewrite" the domain portion of the access URL
           to the mail domain equivalent. For example, the following record can rewrite the URL
           "mail.*.com" to the mail domain "*.com"

           *.com:mail.*.com:@

           This powerful wildcard functionality can ease the login process for most of your
           server's mail domains with just one or two logindomainlist records.

           File Format
               Let's take a look at the NEW logindomainlist file format:

               firstfield:secondfield:thirdfield

               Above, we can see that the new logindomainlist records are made up of three fields
               delimited by colons. But what does each field do?

               First Field - the first field contains the "mail domain" for which we would like
               the user to log in under. The mail domain is the part of an email address after
               the @ symbol. For example, in the email address "user@domain.com", "domain.com" is
               the mail domain.

               Second Field - the second field contains the "access domain". The access domain
               contains an URL or IP address that is used to figure out which mail domain to use
               by default. For example, in the following logindomainlist record:

               domain1.com:domain2.com

               "domain2.com" is the "access domain" and "domain1.com" is the "mail domain". If
               the user logs into the following URL:

               http://domain2.com/cgi-bin/sqwebmail

               His default "mail domain" will be "domain1.com".

               Third Field - the third field may contain a modifier. The modifier may be either a
               single character modifier, or a group identification string. The single character
               modifiers and the group modifier are described in detail below.

               Finally, the logindomainlist file may also contain comments and empty lines. Empty
               lines can be used to group records visually, and comments can be used to explain
               why a certain record or group of records look the way they do.

               If the first character of a line is a '#', then the entire line is considered a
               comment and is ignored. If the first character of a line contains whitespace, the
               entire line is assumed to be an empty line and is ignored.

           Modifiers
               @ - the '@' modifier can be used to create a hidden field on the login.html page
               which contains the default mail domain. In addition, this field will automatically
               display the default mail domain in plain text to the right of the userid text box.

                   Note
                   The '@' modifier ALLOWS the use of wildcards to automate the relationship
                   between "access domains" and "mail domains". See the heading "Wildcards" below
                   for more information about wildcarding.
               - - the '-' modifier can be used to create an editable text field on the
               login.html page which contains the default mail domain.

                   Note
                   The '-' modifier ALLOWS the use of wildcards to automate the relationship
                   between "access domains" and "mail domains". See the heading "Wildcards" below
                   for more information about wildcarding.
               group string - If no modifier is specified in the third field, or if the third
               field modifier is a group identifier string, then a drop down menu will be
               displayed on the login.html page. Records with the SAME group string will be
               displayed together in the drop down. For example, if your logindomainlist file
               contains the following records:

                        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
               And the user logs into sqwebmail with the following URL:

               http://domain4.com/cgi-bin/sqwebmail

               He will see a drop down containing ONLY the following domains:

                        domain1.com
                        domain3.com
                        domain5.com
               "domain3.com" will be automatically selected, or defaulted. Only the records in
               the firstgroup will be visible to the user. This functionality is great for
               organizations with more than one mail domain.

                   Note
                   The group string modifier does NOT allow the use of wildcards to automate the
                   relationship between "access domains" and "mail domains". This is because drop
                   down menus are fundamentally incompatible with wildcards.

           Wildcards
               If a record's modifier allows wildcarding (See "Modifiers" above for information
               about which modifiers allow wildcarding and which do not.) then the first and
               second fields of that record _MAY_ contain wildcards. Wildcards match against the
               HTTP_HOST CGI environment variable only.  IP addresses can NOT be used if either
               the first or second fields contain the wildcard character. However, if neither the
               first nor second fields contain the wildcard character, then the second field can
               contain an IP address.

               In the logindomainlist file, an asterisk (*) character in either the first and/or
               second field represents a wildcard. Any asterisk in the second field will be used
               to match an access domain. If an asterisk exists in the first field then any
               characters which the asterisk in the second field represents will replace the
               asterisk in the first field when sqwebmail determines the default mail domain.
               However, asterisks are not required in either the first or second fields. They are
               totally optional. For example, given the following logindomainlist record:

               *.com:mail.*.com:@

               If the user logs into sqwebmail with the following URL:

               http://mail.mydomain.com/cgi-bin/sqwebmail

               The asterisk in the second field will represent the string "mydomain". This string
               will then replace the asterisk in the first field to give the following default
               mail domain: mydomain.com

               Similarly, if the following record exists in the logindomainlist file:

               *:*:@

               Then ANY URL the user uses to access sqwebmail will be automatically used for the
               default mail domain.

               But the first field doesn't _HAVE_ to contain an asterisk. The following will work
               just fine:

               mydomain.com:mydomain.*:@

               The above example will allow the user to access the "mydomain.com" mail domain
               from any of the following URLs: "mydomain.org", "mydomain.net", "mydomain.us",
               etc...

               And finally, the first field doesn't have to contain anything at all! If the first
               field is empty, that record will serve as an explicit no-default mail domain. No
               default mail domain will be specified if the second field matches the user's login
               URL. This is useful because the logindomainlist is searched from the top down. Any
               wildcard records at the bottom of the list will be overridden by records closer to
               the top. An "explicit no-default" record can be used to specify certain domains as
               "system account" domains so that no default mail domain is specified.

       maildirfilterconfig
           This file, if exists, sets the global defaults for mail filtering in the webmail
           server. Mail filtering in the webmail server is a subject worthy of special mention. A
           full description of how to install and configure webmail-based mail filtering is
           included in the installation notes for the Courier mail server. Refer to the
           installlation instructions for additional information.

       maildirshared
           This file, if exists, specifies the location of shared maildirs for the webmail and
           IMAP server. Normally, each mailbox must be separately configured to access every
           shared maildir, by the maildirmake(1)[10] command. This file allows shared maildirs to
           be set globally for everyone. Everyone's webmail and IMAP server will pick up the
           shared maildirs specified in this file. See maildirmake(1)[10] for more information.

       maildrop
           This file contains one line whose contents is a pathname to the maildrop(1)[6] mail
           delivery agent. If the Courier mail server knows that the delivery agent used to
           delivery mail locally is maildrop(1)[6] then certain delivery optimizations are
           possible. This configuration file does NOT actually specify that maildrop(1)[6] should
           be used as a local mail delivery agent, it only specifies where maildrop(1)[6] is
           installed. The default local mail delivery instructions are specified in the courierd
           configuration file. If the specified delivery instruction specify running an external
           program whose pathname matches the one specified by this configuration file, the
           Courier mail server assumes that it's maildrop(1)[6], and will use maildrop-specific
           options to optimize mail delivery.

           This configuration file is initialized, by default, to point to the version of
           maildrop(1)[6] that's integrated with the Courier mail server. The integrated version
           of maildrop(1)[6] is configured slightly differently than the standalone version of
           maildrop(1)[6].

           Although you can set the maildrop configuration file to point to some other version of
           the maildrop mail filter, you MUST set the maildropfilter configuration file (see
           below), to point to the integrated version of maildrop.

       maildropfilter
           This file contains one line whose contents is a pathname to the maildrop(1)[6] mail
           delivery filter. In addition to being a delivery agent, maildrop can also be used as a
           mail filtering engine. If this file exists, the Courier mail server will be capable of
           invoking recipient-specified mail filters when a message is received. If the mail
           filtering rules reject the message, the Courier mail server will not accept the
           message for delivery. This means that when receiving mail via ESMTP, the Courier mail
           server will reject the ESMTP transaction without even accepting the message from the
           remote mail server.

           This file is not installed by default. To activate mail filtering for local
           recipients, simply copy the contents of the maildrop configuration file to
           maildropfilter.

       maildroprc
           This file contains systemwide mail filtering instructions for maildrop(1)[6]
           deliveries. This configuration file is optional, and is used by maildrop(1)[6] when it
           is invoked as a traditional post-delivery mail filter. See maildropfilter(6)[11] for
           more information.

       me
           This file contains one line whose contents is a valid machine name. When a single
           installation of the Courier mail server is shared over a network, each machine that's
           running the Courier mail server must have a unique me file. If me is missing, The
           Courier mail server uses the result of the gethostname() system call.

               Warning
               If you change the contents of this configuration file, it may be necessary to
               rerun the makealiases command again, else your mail will promptly begin to bounce.
               If you don't have this configuration file defined, and you change the system's
               network host name, you may also need to run makealiases.

       msgidhost
           If a message does not have a Message-ID: header, the Courier mail server may decide to
           create one. The host portion of the new header will be set to the contents of
           msgidhost, which contains one line of text. If msgidhost does not exist, me will be
           used in its place. Changes to this file take effect immediately.

       nochangingfrom
           The Courier mail server's webmail server lets the contents of the From: header be set
           for mailed messages. If this configuration file exists, the ability to set the
           contents of the From: header is disabled.

       queuelo, queuehi, queuefill
           These configuration settings tune the Courier mail server's mail queue processing. The
           Courier mail server does not load the entire mail queue metadata in memory.  queuelo
           contains a number that specifies the queue “low watermark” message count.  queuehi
           contains a number that specifies the queue “high watermark” message count.  queuefill
           specifies a time interval, “queue refill” in seconds. The number in queuefill may
           optionally be followed by "m", indicating that the queue refill is specified in
           minutes.

           queuehi specifies the maximum number of messages that are loaded into memory. The
           Courier mail server reads the mail queue on disk until either it reads all of it, or
           it reads the number of messages specified by queuehi. As messages are delivered they
           are removed from the memory and disk. Messages that are deferred for another delivery
           attempt are removed from memory, but kept on the disk.

           When the number of messages in memory falls below queuelo, The Courier mail server
           goes back to disk and attempts to fill the memory queue to the top, again.

           This is, basically, a capsule summary of the mail queue processing logic. Many small,
           low level details are omitted; this is just an executive overview. When new messages
           arrive during a large mail backlog, the new messages are also loaded into the memory
           queue, if there's room for them. Therefore, during a large mail backlog the Courier
           mail server simultaneously tries to clear the existing backlog, and process any new
           mail at the same time. Up to the Courier mail server 0.41, all of this generally
           translates to the Courier mail server giving priority to newly arrived mail, and
           processing the backed up mail queue if spare resources are available.

           The queuefill setting was added in the Courier mail server 0.42, in an attempt to keep
           new mail from excessively delaying existing mail during a major queue backup.
           queuefill specifies a time interval. When the Courier mail server completely fills the
           memory queue it sets a timer. After the interval given by queuefill The Courier mail
           server will go back and re-fill the mail queue even if the number of messages did not
           fall below the low watermark. If the Courier mail server finds older messages in the
           mail queue they will be pushed to the top of the scheduling queue, and given priority.

           Smaller queuefill time intervals means more frequent trips to the disk, and more
           overhead. But, in exchange for that, during a mail backlog the Courier mail server
           will spend more time handling a greater number of delayed messages. Larger queuefill
           time intervals means less frequent trips to the disk, and less overhead, in exchange
           for less "fairness" during large mail backlogs.

           queuefill defaults to five minutes, if not specified. Explicitly setting it to 0
           seconds turns off the queue re-filling completely, essentially reverting to pre-0.42
           behavior. The default queuelo and queuehi values are computed at run time.  queuelo
           defaults to the larger of 200, and the sum total of configured mail delivery slots,
           both local and remote.  queuehi, if not explicitly set, defaults to the smaller of
           twice the queuelo, or queuelo plus 1000.

       queuetime
           This file specifies how long the Courier mail server normally tries to repeatedly
           deliver a message, before giving up and returning it as undeliverable. Messages are
           immediately returned as undeliverable when a permanent failure is encountered (such as
           the recipient address not being valid). Attempts to deliver the message when there's a
           temporary, transient, error (such as the network being down) will be repeatedly made
           for the duration of time specified by this configuration file. This file contains a
           number followed by the letter 'w' for weeks, or 'd' for days. It is also possible to
           use 'h' for hours, 'm' for minutes, or 's' for seconds. Only integers are allowed,
           fractions are prohibited. However, you can use '1w2d' to specify one week and two
           days. If queuetime is missing, the Courier mail server makes repeated delivery
           attempts for one week.

       retryalpha, retrybeta, retrygamma, retrymaxdelta
           These control files specify the schedule with which the Courier mail server tries to
           deliver each message that has a temporary, transient, delivery failure.  retryalpha
           and retrygamma contain a time interval, specified in the same way as queuetime.
           retrybeta and retrymaxdelta contain small integral numbers only.

           The Courier mail server will first make retrybeta delivery attempts, waiting for the
           time interval specified by retryalpha between each attempt. Then, the Courier mail
           server waits for the amount of time specified by retrygamma, then the Courier mail
           server will make another retrybeta delivery attempts, retryalpha amount of time apart.
           If still undeliverable, the Courier mail server waits retrygamma*2 amount of time
           before another retrybeta delivery attempts, with retryalpha amount of time apart. The
           next delay will be retrygamma*4 amount of time long, the next one retrygamma*8, and so
           on.  retrymaxdelta sets the upper limit on the exponential backoff. Eventually the
           Courier mail server will keep waiting retrygamma*(2^retrymaxdelta) amount of time
           before making retrybeta delivery attempts retryalpha amount of time apart, until the
           queuetime interval expires.

           The default values are:

           retryalpha
               Five minutes

           retrybeta
               Three times

           retrygamma
               Fifteen minutes

           retrymaxdelta
               Three

           This results in the Courier mail server delivering each message according to the
           following schedule, in minutes: 5, 5, 5, 15, 5, 5, 30, 5, 5, 60, 5, 5, then repeating
           120, 5, 5, until the message expires.

       sizelimit
           Maximum size of the message, in bytes, that the Courier mail server accepts for
           delivery. The Courier mail server rejects larger messages. If sizelimit is set to
           zero, The Courier mail server accepts as large message as available disk space
           permits. If the environment variable SIZELIMIT is set at the time a new message is
           received, it takes precedence and the Courier mail server uses the contents of the
           environment variable instead. Changes to this file take effect immediately. The
           SIZELIMIT environment variable is for use by individual mail submission agents. For
           example, it can be set by the smtpaccess configuration file (see makesmtpaccess(8)[3]
           for more information) for mail from certain IP addresses.

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

       submitdelay
           submitdelay specifies the delay before the first delivery attempt for a message that
           has been entered into the mail queue. Normally, the first delivery attempt is made as
           soon as possible. This setting delays the initial delivery attempt. It is normally
           used when you have a mail filter installed that detects duplicate messages arriving in
           a short period of time. If the mail filter detects this situation it can use the
           cancelmsg(1)[12] command to reject duplicate messages in the queue (and return them
           back to the envelope sender).

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

       usexsender
           If this configuration file exists, the Courier mail server's webmail server will set
           the X-Sender: header on all outgoing messages. This is a good idea if the webmail
           server allows the user to set the contents of the From: header. Note that the Courier
           mail server records the system userid of the sender in all locally-sent messages
           (which includes messages mailed by the webmail server), which is sufficient in most
           cases. In cases where you have many virtual accounts that share the same system
           userid, this configuration file provides a way to positively identify the sender of
           the outgoing message.

       uucpme
           uucpme sets the UUCP nodename of the Courier mail server mail relay. See
           courieruucp(8)[13] for more information.

       uucpneighbors
           uucpneighbors is used by the courieruucp module to specify the Courier mail server's
           configuration for relaying mail via UUCP. See courieruucp(8)[13] for more information.

       uucprewriteheaders
           If this file exists, headers of messages sent to/from UUCP addresses will be
           rewritten. Normally, only the message envelope sender and recipients are rewritten,
           the existence of this file causes the headers to be rewritten as well.

       vhost.ip-address, vhost.domain
           Enable per-message virtual configuration settings described in the section called
           “Servers with multiple IP addresses” and the section called “Simulating a server with
           multiple IP addresses”, below, for more information.

       warntime
           warntime specifies an amount of time in the same format as queuetime. If a message
           still has not been delivered after this period of time, the Courier mail server sends
           a warning message (a "delayed" Delivery Status Notification) to the sender. If
           warntime is missing, the Courier mail server sets warntime to four hours.

               Note
               The time interval specified by warntime is only approximate. The Courier mail
               server sends a delayed Delivery Status Notification at the conclusion of the first
               attempted delivery after warntime has elapsed.

   Webmail template files
       HTML output from the webmail server is generated from the template files in
       /usr/lib/courier/sqwebmail/html/en-us. It is possible to translate the webmail interface
       into another language simply by creating another subdirectory underneath
       /usr/lib/courier/sqwebmail/html, then meticulously translating each .html file. Each
       template file contains well-formed HTML, with dynamic content marked off by tags. Note
       that the large comment blocks in each HTML file need to be translated too, since they are
       inserted as dynamic content, elsewhere.

       The directory /usr/lib/courier/sqwebmail/html/en-us also contains several configuration
       files, in addition to the HTML template files. Doing so allows this configuration
       information to be defined for each available language.

       CHARSET
           This file consists of a single line of text, which names the character set used by the
           HTML template files. It is possible to specify multiple character set, by separating
           them with commas, provided that HTML templates use only the common portions of all
           listed character set.

           The default English HTML templates use strictly the “us-ascii” subset, and the CHARSET
           contains utf-8,iso-8859-1. When multiple character sets are listed, the first
           character set that's supported by the browser is picked, so with UTF-8 capable
           browsers the default webmail interface will use UTF-8, falling back to ISO-8859-1 for
           browsers that do not support UTF-8.

       footer
           The contents of this file, if it exists, are appended to all messages sent by the
           webmail server.

       ISPELLDICT
           This file consists of a single line of text, which contains the name of the dictionary
           used for spell-checking. It is passed as an argument to ispell, or aspell.

       LANGUAGE
           This file consists of a single line of text, which should always be the same as the
           name of its directory (en-us).

       LANGUAGE_PREF
           This file is not needed at runtime, its contents are used during installation. See
           webmail/html/README_LANG in the source distribution for more information.

       LOCALE
           The corresponding C locale for these templates.

       TIMEZONELIST
           This file lists the available timezones on the login screen. See the comments in this
           file for more information.

   Sender Policy Framework Keywords
       The Courier mail server can perform “Sender Policy Framework” checks on up to three
       addresses for each message. This is controlled by setting the following variables:
       BOFHSPFHELO, BOFHSPFMAILFROM, and BOFHSPFFROM. Each variable is set to a comma-separated
       list of the following keywords: “off” - SPF verification disabled (default); “none”,
       “neutral”, “pass”, “fail”, “softfail”, “error”, “unknown” - these keywords correspond to
       the possible results of an SPF check, the message is accepted for the listed SPF results
       only, any other SPF result is rejected; “all” - shorthand for all possible SPF results,
       use “all” to run SPF in informational mode only, recording the SPF status in the
       Received-SPF: header; “allowok” - automatically pass the SPF verification if the sender's
       IP address is found in a DNS access whitelist, any whitelist given in the -allow option to
       couriertcpd, see the “DNS ACCESS LISTS” section in couriertcpd(1)[14].

       A rejected SPF result gets kicked back with a permanent error indication if the SPF result
       is listed in BOFHSPFHARDERROR, and a temporary error indication otherwise.

       When enabling SPF checking, the keyword list should always include “pass” (it makes no
       sense to do otherwise) and “none”. The keyword list should also include “softfail”,
       “neutral”, and “unknown”. See the SPF draft for a description of these status results. At
       some distant future, the keyword list will only include “pass”, rejecting all senders
       without a stated policy. This might be desirable at some point in the future, but not
       right now.

       The BOFHSPFFROM list may also include an additional keyword, “mailfromok”.
       BOFHSPFMAILFROM and BOFHSPFFROM are trade-offs. Using BOFHSPFMAILFROM is faster, and it
       does not require the entire message to be received, before running the SPF check.
       BOFHSPFFROM checking can only occur after the entire message is received, but it's more
       reliable. If “mailfromok” is listed, the From: is not checked if the MAIL FROM command was
       checked with the “pass” result.

       In other words: the From: header is checked if MAIL FROM was empty, or did not pass the
       SPF checks. If MAIL FROM passed the SPF check the Courier mail server won't bother looking
       at the From: header.

           Note
           A conservative policy should not reject failed SPF checks from the From:header,
           because it can be counterproductive in some situations. This is because when a sender
           from a domain with a published SPF policy sends a message to a mailing list, the
           message goes through the mailing list processor's IP address, and it will fail the SPF
           check unless the domain SPF explicitly authorizes the mailing list processor's IP
           address.

           This is very unlikely. The end result is that domains with a published SPF record get
           punished, and domains without an SPF record get off scott free. Mailing lists should
           be encouraged to publish their own SPF records for mailing list traffic; then the
           “mailfromok” keyword can validate the mailing list's return address, and forego
           checking of the “From:” header from the mailing list, while still checking the “From:”
           header from everyone else.

           Another alternative is to use opt BOFHSPFFROM=all for advisory purposes only.
           Post-delivery mail filters can key off the “Received-SPF” header.

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

   Servers with multiple IP addresses
       The Courier mail server's default configuration listens on port 25 on all IP addresses. If
       the server has more than one IP address, Courier accepts connections on any IP address.
       Adjust the settings in the esmtpd configuration file to explicitly list which IP addresses
       Courier should listenson. This also applies to the ESMTP over SSL server on port 465
       configured by esmtpd-ssl, and the MSA server on port 587, configured by esmtpd-msa.

       That's for incoming EMSTP. For outgoing ESMTP connections, the Courier mail server does
       not specify an IP address by default, and lets the server select one. The server selects a
       default IP address based on a server's network configuration. The selection criteria is
       platform specific, and is typically based on the system's IP routing tables.

       The ipout and ip6out configuration files set an explicit IP address for Courier's outgoing
       connections:

           # echo "192.168.0.1" >/etc/courier/ipout
           # echo "fec0::230:48ff:fec4:429c" >/etc/courier/ip6out

       This example specifies 192.168.0.1 as the IP address to make connections from for IPv4
       destinations, and fec0::230:48ff:fec4:429c for IPv6 destinations.

       If the Courier mail server runs on a host with two IPv4 addresses, 192.168.0.1,
       192.168.1.1, the above example uses 192.168.0.1 to send the relayed message to IPv4
       destinations even if Courier received the message from a client that connected to the
       other addresses.

       If the Courier 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,
       Courier normally uses the server's default IP address, or the one set by ipout or ipout6.
       When the Courier 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.

       The first step is to enable a per-message, non-default configuration settings, like the
       outgoing IP address, by creating a zero-length vhost.ip-address file:

           # touch >/etc/courier/vhost.192.168.0.1
           # touch >"/etc/courier/vhost.fec0::230:48ff:fec4:429c"

       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.

       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:

           # echo "192.168.0.1" >/etc/courier/ipout.192.168.0.1
           # echo "192.168.1.1" >/etc/courier/ipout.192.168.1.1

       “ipout.address” sets the IP address for outgoing connections for messages received from a
       client connection to “address” only. Just an ipout applies to all other messages, except
       ones which have an ipout.address 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 ipout takes effect (or the default system-specified
       IP address).

       For convenience, an empty ipout.address gets interpreted as if it contains the same
       address. The above example is equivalent to:

           # touch /etc/courier/ipout.192.168.0.1
           # touch /etc/courier/ipout.192.168.1.1

       The formal configuration rules are as follows, for a message received from IP address
       “address”, which may be an IPv4 or an IPv6 address:

       •   The IPv4 address and the IPv6 address for outgoing ESMTP connections get specified by
           the contents of /etc/courier/ipout.address and /etc/courier/ip6out.address,
           respectively.

       •   If the file exists, but is empty, the same address becomes the IP address for the
           outgoing connection.

       •   The above rules are in effect only if /etc/courier/vhost.address exists,

       •   If the file does not exist, or if /etc/courier/vhost.address does not exist, the
           contents of /etc/courier/ipout, for IPv4 connections, and /etc/courier/ip6out, for
           IPv6 connections set the IP address.

       •   Otherwise, the Courier mail server uses the default IP address determined by the
           system's network configuration.

       •   In /etc/courier/ipout.address and /etc/courier/ip6out.address, an address of "0" also
           specifies the system's default IP address.

       It is possible for the Courier mail server to receive a message from an IPv6 connection,
       and forward it to an IPv4 address, or vice versa. The address portion of
       /etc/courier/ipout.address and /etc/courier/ip6out.address, specifies the IP address the
       client used to connect to Courier and may be either an IPv4 or an IPv6 address, in both
       cases! For example:

           # echo "192.168.0.1" >/etc/courier/ipout.192.168.0.1
           # echo "fec0::230:48ff:fec4:429c" >/etc/courier/ip6out.192.168.0.1

       This means that when a client connects to the Courier mail server using the IP address
       192.168.0.1 and relays a message, if the message gets forwarded to an IPv4 address,
       Courier uses the same IP address, and if it gets forwarded to an IPv6 address Courier uses
       this IPv6 address. The above also probably means that:

           # echo "192.168.0.1" >"/etc/courier/ipout.fec0::230:48ff:fec4:429c"
           # echo "fec0::230:48ff:fec4:429c" >"/etc/courier/ipout.fec0::230:48ff:fec4:429c"

       So if an IPv6 client connects to Courier on this IPv6 address and relays a message,
       Courier uses the same IPv6 address, or 192.168.0.1 depending on the destination.

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

       Additionally, for all other configuration files described in this manual page, the Courier
       mail server uses “filename.address” if it exists, in place of “filename” when processing
       messages received from “address”, either an IPv4 or an IPv6 address.

       This is used in all contexts where it makes sense to do so:

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

       This example specifies “relay.example.com” as the contents of the me configuration file,
       described earlier in this manual page, when processing messages received by clients that
       connect to 192.168.0.1, and “firewall.example.com” for processing messages received by
       clients that connect to 192.168.1.1.

       “me” is the default hostname for most common Courier mail server configuration settings,
       such as the server's name in the ESMTP greeting banner, what Courier calls itself in the
       ESMTP EHLO/HELO commands, and other contexts, unless overridden by a more specific
       setting.

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

   Simulating a server with multiple IP addresses
       As described in the previous section, the existence of vhost.ip-address enables
       configuration settings only for messages that were received at one of the IP addresses
       that the Courier mail server accepts connections on.

       It's possible to partially achieve the same end results by creating vhost.domain:

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

       This enables per-message specific configuration for messages received from authenticated
       clients whose authenticated ID ends with “@example.com”. 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:

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

       This sets this IP address for all outgoing messages with a “@example.com” authenticated
       client. It's important to note the following limitations:

       •   The Courier authentication library (see installation instructions) must be configured
           with accounts and mailboxes that follow the “user@domain” format.

       •   Not all configuration settings can be customized in a setting.domain. The trivial
           example would be the ESMTP server banner. The mail server emits the banner before it's
           ready to receive the first message, so no return address-based customization is
           possible, of course, to select an ESMTP server banner. Additionally, the “me”
           configuration setting gets set before the return address is received, so the contents
           of a domain-specific “me” may not be in effect in all contexts.

       •   Anyone can use any return address they wish. Some mitigation is possible, of course,
           using measures such as SPF, but it would be mistake to believe that this is much more
           than just eye candy.

       •   Both an IP address and domain-based “vhost”s are allowed. An IP address-based vhost
           takes precedence.

BUGS

       Flushing a single message will not work if the message queue is backed up. When that
       happens, your only available option is to flush the entire queue.

       courier start fails if the Courier mail server has detected a fatal operational error. In
       this situation the top-level courierd daemon sleeps for a minute, before automatically
       restarting. During this sleep interval courier stop does not work.

SEE ALSO

       cancelmsg(1)[12], maildirmake(1)[10], maildrop(1)[6], preline(1)[15], sendmail(1)[16],
       testmxlookup(1)[17], dot-courier(5)[4], authlib(7)[18], courierfax(8)[7],
       courierfilter(8)[5], filterctl(8)[5], courierldapaliasd(8)[9], courierpop3d(8)[19],
       courierpop3d(8)[19], couriertcpd(8)[14], courieruucp(8)[13], esmtpd(8)[20], imapd(8)[21],
       localmailfilter(7)[2], mailq(1)[1], makeacceptmailfor(8)[22], makealiases(8)[23],
       makehosteddomains(8)[8], makepercentrelay(8)[24], makesmtpaccess(8)[3], makeuserdb(8)[25],
       pw2userdb(8)[25], mkdhparams(8)[26], mkesmtpdcert(8)[27], mkimapdcert(8)[28],
       pop3d(8)[29], submit(8)[30], userdb(8)[31].

AUTHOR

       Sam Varshavchik
           Author

NOTES

        1. mailq(1)
           http://www.courier-mta.org/mailq.html

        2. localmailfilter(7)
           http://www.courier-mta.org/localmailfilter.html

        3. makesmtpaccess(8)
           http://www.courier-mta.org/makesmtpaccess.html

        4. dot-courier(5)
           http://www.courier-mta.org/dot-courier.html

        5.

           courierfilter(8)
           http://www.courier-mta.org/courierfilter.html

        6.

           maildrop(1)
           http://www.courier-mta.org/maildrop.html

        7. courierfax(8)
           http://www.courier-mta.org/courierfax.html

        8. makehosteddomains(8)
           http://www.courier-mta.org/makehosteddomains.html

        9. courierldapaliasd(8)
           http://www.courier-mta.org/courierldapaliasd.html

       10. maildirmake(1)
           http://www.courier-mta.org/maildirmake.html

       11. maildropfilter(6)
           http://www.courier-mta.org/maildropfilter.html

       12. cancelmsg(1)
           http://www.courier-mta.org/cancelmsg.html

       13. courieruucp(8)
           http://www.courier-mta.org/courieruucp.html

       14. couriertcpd(1)
           http://www.courier-mta.org/couriertcpd.html

       15.

           preline(1)
           http://www.courier-mta.org/preline.html

       16.

           sendmail(1)
           http://www.courier-mta.org/sendmail.html

       17.

           testmxlookup(1)
           http://www.courier-mta.org/testmxlookup.html

       18.

           authlib(7)
           http://www.courier-mta.org/authlib.html

       19.

           courierpop3d(8)
           http://www.courier-mta.org/courierpop3d.html

       20.

           esmtpd(8)
           http://www.courier-mta.org/esmtpd.html

       21.

           imapd(8)
           http://www.courier-mta.org/imapd.html

       22.

           makeacceptmailfor(8)
           http://www.courier-mta.org/makeacceptmailfor.html

       23.

           makealiases(8)
           http://www.courier-mta.org/makealiases.html

       24.

           makepercentrelay(8)
           http://www.courier-mta.org/makepercentrelay.html

       25.

           makeuserdb(8)
           http://www.courier-mta.org/makeuserdb.html

       26.

           mkdhparams(8)
           http://www.courier-mta.org/mkdhparams.html

       27.

           mkesmtpdcert(8)
           http://www.courier-mta.org/mkesmtpdcert.html

       28.

           mkimapdcert(8)
           http://www.courier-mta.org/mkimapdcert.html

       29.

           pop3d(8)
           http://www.courier-mta.org/pop3d.html

       30.

           submit(8)
           http://www.courier-mta.org/submit.html

       31.

           userdb(8)
           http://www.courier-mta.org/userdb.html