courier

Name

courier -- Courier

Synopsis

courier {start | stop | restart | flush | flush qid}

DESCRIPTION

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

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

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

CONFIGURATION FILES

Courier uses several configuration files which are located in /usr/local/courier/etc. 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. /usr/local/courier/etc/aliases may define local mail aliases that contain one or more recipients. If it is desired to use local mail filtering for mail addressed to an alias address, designate a local account that will be used to specify filtering instructions, and put its home directory into this control file. The filtering argument will be "alias-address" where address is the name of the alias. See localmailfilter(7) for more information.

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

Changes to this file take effect immediately.

authdaemonrc

This file configures the authdaemond authentication proxy. See authlib(7) for more information.

authldaprc

This file configures LDAP authentication. See authlib(7) for more information.

authmodulelist

This file contains one line that contains a list of installed authentication modules. Authentication modules are used to associate a local mail address with an actual account, that includes properties such as home directory, user id, group id, and others.

Authentication modules are selected at configuration time, and are used in two ways. Standalone authentication modules are installed in the /usr/local/courier/libexec/authlib directory, and are used for authenticating discrete incoming sessions, such as as POP3, IMAP; and ESMTP-authenticated relaying. Usually there are several authentication modules installed: for example authuserdb is used to authenticate virtual accounts, and authpam is used to authenticate real system accounts. Each server - POP3, IMAP, or the ESMTP server - receives a list of authentication modules on the command line, and, after installation it is possible to disable or rearrange the available authentication modules simply by specifying different parameters to the server.

Some servers, however, are directly linked with the authentication modules, mainly for performance reasons. Courier's core mail scheduler also needs to authenticate accounts in order to locate their associated mailboxes. Starting a separate process to obtain the location of a mailbox, for every message delivered by the system, is too much unnecessary overhead, so the authentication modules are directly linked in. Courier's HTTP webmail server also uses statically-linked modules.

For those situations, the /usr/local/courier/etc/authmodulelist configuration file is used to select which authentication modules are used, and in which order. A default configuration file will be installed, listing all the configured authentication modules. If this file is missing, all available authentication modules will be used, in the order that they were configured.

authmysqlrc

This file configures MySQL authentication. See authlib(7) for more information.

autoresponsesquota

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

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

backuprelay

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

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

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

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

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

batchsize

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

bofh

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

badfrom user@domain

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

badfrom @domain

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

badfrom @.domain

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

badmx N

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

freemail domain [domain2] [domain3]...

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

spamtrap user@domain

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

NOTE:

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

maxrcpts N [hard]

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

opt BOFHBADMIME=action

Set default disposition of mail with invalid or corrupted MIME headers. Possible settings for action are: accept - accept and pass on the corrupted message, untouched; reject - reject and return the mail as undeliverable; wrap - "wrap" the message as an attachment, that must be separately opened (this is the default action). This setting applies to mail that's generated locally, or which is sent from IP addresses that do not have an explicit BOFHBADMIME setting listed in the smtpaccess configuration file. smtpaccess can be used to set BOFHBADMIME for specific sending IP address ranges only. See makesmtpaccess(8) for more information.

NOTE:

BOFHMIME=accept implies MIME=none (see submit(8) for more information).

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" >/usr/local/courier/etc/calendarmode

This configuration file must be globally readable, so make sure that your umask is not set too tight.

courierd

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

defaultdomain

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

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

dotextension

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

dsnfrom

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

dsnlimit

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

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

enablefiltering

This configuration file specifies whether mail filtering is enable. 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

Specifies that mail received via ESMTP will be filtered.

local

Specifies that mail received from logged on users, via sendmail, and mail forwarded from >dot-courier(5) will be filtered.

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.

esmtpacceptmailfor

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

esmtpacceptmailfor.dat

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

esmtpauthclient

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

relay userid password

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

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

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

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

esmtpd

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

esmtpdelay

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

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

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

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

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

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

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

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

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

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

esmtpgreeting

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

esmtphelo

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

esmtproutes

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

domain:relay[,port][/SECURITY=STARTTLS][/SECURITY=NONE]

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

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

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, Courier looks up MX and A records for relay.example.com (Qmail only looks up A records).

esmtproutes may contain comments, any line that starts with the # character is ignored. Also, wildcards are allowed:

 .example.com: [192.168.0.3],26

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

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

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

example.com: relay.example.com
        :[192.168.0.4]

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

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

example.com:
:[192.168.0.4]

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

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

The /SECURITY=NONE flag prevents Courier from using the STARTTLS ESMTP extension even if the remote server claims to support it. Use this flag to deliver mail to misconfigured Microsoft Exchange relays that claim to support STARTTLS, but always report a failure to a STARTTLS request.

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

esmtptimeout

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

esmtptimeoutconnect

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

esmtptimeoutdata

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

esmtptimeouthelo

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

esmtptimeoutkeepalive

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

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

esmtptimeoutkeepaliveping

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

esmtptimeoutquit

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

faxqueuetime

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

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

faxnotifyrc

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

faxrc

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

footer

If this file exists, its contents will be automatically appended to all messages sent by the webmail server.

hosteddomains

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

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

The contents of the hosteddomains configuration file is a list of domains, one per line, in lowercase. You must run the makehosteddomains command for any changes to take effect.

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.

ldapaliasrc

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

locallowercase

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

NOTE:

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

locals

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

 .domain.com

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

Specific hosts can be excluded from the wildcard. Example:

 !host.domain.com
 .domain.com

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

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

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

logindomainlist

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

maildirfilterconfig

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

maildirshared

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

maildrop

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

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

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

maildropfilter

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

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

maildroprc

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

me

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

NOTE:

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

msgidhost

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

nochangingfrom

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

queuetime

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

retryalpha, retrybeta, retrygamma, retrydelta

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

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

The default values are:

retryalpha

Five minutes

retrybeta

Three times

retrygamma

Fifteen minutes

retrymaxdelta

Three

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

sizelimit

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

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

submitdelay

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

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

usexsender

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

uucpme

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

uucpneighbors

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

uucprewriteheaders

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

warntime

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

NOTE:

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

BUGS

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

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

SEE ALSO

cancelmsg(1), maildirmake(1), maildrop(1), preline(1), sendmail(1), testmxlookup(1), dot-courier(5), authlib(7), courierfax(8), courierfilter(8), filterctl(8), courierldapaliasd(8), courierpop3d(8), courierpop3d(8), couriertcpd(8), courieruucp(8), esmtpd(8), imapd(8), localmailfilter(7), mailq(1), makeacceptmailfor(8), makealiases(8), makehosteddomains(8), makepercentrelay(8), makesmtpaccess(8), makeuserdb(8), pw2userdb(8), mkesmtpdcert(8), mkimapdcert(8), pop3d(8), submit(8), userdb(8).