NOTE: a more readable HTML version of this INSTALL document can be found in courier/doc/install.html.
Read this document in its entirety before entering a single command. Installing Courier for the first time will take a while. If possible, consider looking around for anyone who has already packaged Courier for your operating system, and save yourself the hassle.
Fortunately, it gets easier with each subsequent installation. Courier is a complicated piece of software. Most problems people will have are likely to be with the configuring and installing it correctly. Designing complex software that compiles and installs on a wide variety of POSIX systems is not a trivial task.
Courier's configuration and installation scripts are very flexible in setting up installation directories for each logical set of files - configuration files, binaries, scripts, the mail queue, and more. If you begin by installing someone else's package, instead of installing everything yourself, you should take careful notes where things are installed. If you later decide to roll your own package, you will either need to use a COMPLETELY IDENTICAL configuration, or take care to back up your old configuration, and then restore it after the upgrade. The following documentation refers to the default location of various configuration files (and other files as well). If you choose to install some files in a non-default location (either by yourself, or by using someone else's package), you will need to take this into account while reading the following documentation.
This cannot be emphasized enough: the configuration defaults are very generic; the goal is to have the default configuration settings work for almost everyone. In every case using at least a couple of non-default parameters will make Courier work better on your system. You should anticipate going through several trial-and-error installs, tweaking the options to see what works better for you. Even my own pre-configured RPM package uses a number of non-default parameters.
NOTE: older versions of the linuxconf
configuration tool are
hardwired for sendmail. They like to change the permission of the
sendmail
wrapper to match the permissions they think the real
sendmail should have. Older versions of linuxconf
also have a
tendency to create the /var/spool/mqueue
directory, even if
sendmail is not installed.
The following table of contents might look intimidating at first, but some sections are marked "optional". These sections are not required for a basic installation as a simple ESMTP server.
Version 0.44.1 introduced an updated webmail implementation. The suid
cgi-bin binary has been replaced by a combination of a stub and a daemon
process. After upgrading to 0.44.1 you will need to modify your system
startup script to run /usr/lib/courier/libexec/courier/sqwebmaild
start
. See below for more information.
After upgrading from Courier 0.42.2, or earlier, any existing mail in POP3 mailboxes may show up as new mail, by some mail clients. This is a one-time event.
Version 0.43 introduced some functional changes to the LDAP, MySQL, and
PostgreSQL authentication modules. A new DEFAULTDELIVERY setting is added to
each module, incorporating some functionality previously done by the MAILDIR
setting. Previously, MAILDIR served two purposes: 1) define the default
location to the primary mailbox, relative to the account's home directory, 2)
provide default mail delivery instructions, overriding DEFAULTDELIVERY in the
courierd
configuration file.
Starting with this version, MAILDIR only specifies the default location for the primary mailbox, and this setting is now used only by the POP3, IMAP, and Webmail servers. The new DEFAULTDELIVERY setting specifies the default mail delivery instructions. Sites that previously used MAILDIR may now need to copy its setting to DEFAULTDELIVERY.
Version 0.35 introduced the ability to update system passwords from the
webmail server. If you are using the authuserdb
authentication
module, rerun the makeuserdb
script after upgrading to 0.35 or
later.
Prior to 0.35, the default configuration of the webmail server maintained a separate webmail password file. The webmail server did not have the logic to update system login passwords, the approach was to copy system login passwords into a webmail password file. Changing the webmail password involved simply updating the webmail password file, and life was good.
In 0.35, logic was added to update the real system password file, and the eliminate the webmail password file. After upgrading in 0.35, it will probably be necessary to reset all mail account passwords on existing accounts, since the webmail password file is not being used any more, and most people have probably changed their webmail passwords.
As the result of the password change, the default configuration script
will now always build the authdaemond
authentication module by
default. Previously, authdaemond
was built by default only if
LDAP or MySQL support was necessary.
Version 0.30 changed the format of most configuration files. The new configuration file format allows configuration files to be automatically upgraded. The automatic upgrade feature requires that both the old and the new installation have preformatted configuration files. Therefore, when upgrading from version 0.29.1 or earlier, use the following procedure to upgrade the existing configuration files.
All configuration files are installed in the same directory,
"sysconfdir". sysconfdir is a configurable parameter, it's
usually /usr/lib/courier/etc
. sysconfdir is
/etc/courier
in the RPM version of Courier.
Make a backup copy of your current sysconfdir, then delete the old
version of Courier. "rm -rf /usr/lib/courier
" will do nicely.
All the possible configurable settings are in sysconfdir, everything
else can simply go.
Make a backup copy of your current sysconfdir. The upgrade process
reinstalls several default configuration files; specifically
sysconfdir/aliases/system and sysconfdir/smtpaccess/default.
Any additions to these files will normally be lost in the upgrade, and can be
restored from the backup afterwards. Don't forget to rerun
makealiases
and makesmtpaccess
.
Follow the installation procedure in the next section (including the
make install-configure
). The following configuration files are
now preformatted for automatic installation:
ldapaddressbook esmtpd esmtpd-msa courierd pop3d pop3d-ssl imapd imapd-ssl ldapaliasrc authldaprc authmysqlrc authpgsqlrc authdaemonrc
NOTE: depending upon your configuration, you may not actually have every one of these files installed, so just disregard the ones that are not present. Manually edit filename, and retype any custom modifications from the backup copy of the configuration file. This is a hassle, but it only needs to be done once. Future upgrades will be 99% automatic.
Any custom configuration changes are generally confined to these configuration files only. Very rarely are any configuration changes made to the remaining configuration files. If necessary, they can simply be restored from the backup copy made in the previous step. Something to keep in mind is that future versions may add additional complexity to other configuration files, resulting in additional configuration files being reformatted for automatic upgrading.
You will need the following software in order to compile and install Courier:
Courier is primarily developed and built with gcc. Other C++ compiler may or may not work. Solaris's C++ compiler is reported to work without any problems. There are some issues with AIX's xlC compiler, which mostly has to do with the C++ libraries and header files. IBM has released a GNU/Linux development toolkit for AIX, which may help in getting Courier to compile.
On the BSD platform family GNU make is usually installed as gmake. Simply replace 'make' with 'gmake' in the following instructions. GNU make is REQUIRED. Use anything else at your own risk.
A recent version of Perl needs to be installed.
The expect
utility is used by the webmail server to
control the passwd
command in order to change mail login
passwords. expect
is a part of most operating systems. If
you do not have it, you can download it from
http://expect.nist.gov/
. You do not need it if you will not
be using the webmail server, or if you will be creating virtual
(non-system) mail accounts.
Either library must be installed.
IDLE
implementation that provides real-time folder status updates to
concurrent IMAP clients that have the same folder opened. Support for SSL/TLS requires OpenSSL. If OpenSSL is not installed, SSL/TLS features are disabled.
Support for LDAP directory services requires OpenLDAP client libraries to be installed. If OpenLDAP is not installed LDAP directory features are disabled. Sometimes there's some confusion when commercial LDAP servers are used, which come with their own development toolkits, which use a different API than OpenLDAP. Even if a commercial LDAP server is used to provide LDAP services, OpenLDAP is still required to enable LDAP services in Courier. Also, note that you need OpenLDAP development libraries and files. On most systems, the development files are packaged separately, in addition to the runtime OpenLDAP libraries. Make sure that you have not just the runtime OpenLDAP libraries installed, but the development libraries as well.
Support for MySQL and PostgreSQL-based authentication requires, obviously, MySQL/PostgreSQL development libraries. Note - MySQL/PostgreSQL runtime support files is not sufficient to build Courier - you must also install MySQL/PostgreSQL development files and libraries (which may not be installed by default).
This optional software is required to send E-mail messages via fax. Courier will compile and install without this software, but you will not be able to send faxes. All packages must be installed prior to installing Courier, and binaries from all packages must be installed in the default PATH before running Courier's configure script.
mgetty+sendfax, ghostscript, and groff, are required for basic fax support, which supports faxing of plain text, Postscript, and PDF-formatted content. It's probably possible to use the original UNIX troff instead of groff, but this has not been tested. Installing NetPBM adds the ability to fax GIF, JPEG, and PNG images.
The typical sequence of commands to install Courier is as follows. Read the following section before running these commands:
./configure [options] make make check # Optional -- see below make install make install-configure
These commands are described in greater detail in the following sections.
If you're using
gmake
(themake
on GNU/Linux, andgmake
everywhere else), and you are compiling Courier on a workstation with multiple CPUs and plenty of memory, set the following environment variable:MAKEFLAGS="-j 4"; export MAKEFLAGS # Bourne or Korn shellor:setenv MAKEFLAGS="-j 4" # The C shellThis must be done before running the
configure
script. This works only withgmake
.
Courier will not work on a Linux kernel that's been patched with the Openwall security patch in its default configuration. The current version of the Openwall patch has a non-default option that turns off the portion of the Openwall patch which prevents Courier from running.
NOTE: Linux-Mandrake includes the Openwall patch in the alternative "secure" kernel package. Courier will not run on Linux-Mandrake under the alternative "secure" kernel. This package must be removed and the standard kernel package must be installed.
The first step consists of gathering some information about your existing mail system. Before proceeding, you will need to identify and resolve the following issues:
Courier can be used as a simple mail relay -- which does not store any mail locally but is merely a gateway between internal and external mail systems. Courier can also be used as a traditional mail server, accepting and storing messages in individual mailboxes that are accessible via POP3, IMAP, or webmail.
Courier defaults to storing mail in maildirs, not traditional flat file mailbox files. Maildirs require less I/O and CPU resources; they do not use locking; and multiple clients can read and write from maildirs simultaneously. Maildirs scale very well to servers with multiple CPUs. Some benchmark numbers on maildirs are available from http://www.courier-mta.org/mbox-vs-maildir/.
Additionally, Courier's integrated POP3, IMAP, and HTTP/webmail servers support maildir mailboxes only. They do not support mailbox files.
If you have an existing mail server in service, chances are that your current mail server delivers mail to mailbox files. You should consider migrating and converting to maildirs, but this will require that you also upgrade your POP3 server, your IMAP server, and all your other mail clients to software that supports maildirs. Fortunately, Courier already includes a fully integrated POP3 and IMAP server.
Still, if circumstances absolutely require for you to stick with mailbox files, Courier has limited compatibility support for delivering mail to mailbox files, but you have more homework to do:
If you decide to stick with mailbox files, you must know - of course - where your mailboxes are located, and what locking mechanism is being used by your mail software. Mailbox files require some form of locking, because only one application can access the mailbox file at the same time. Unfortunately, different operating systems use different locking methods. There are several possible locking strategies that can be used: so-called "dot-locks", or one of three possible kinds of file locking calls. You will need to consult the documentation for your existing mail software to determine what locking mechanisms you should use.
In most cases, mailbox files are located in a separate partition, usually
the directory /var/spool/mail
. In some instances, mailbox files
may be kept in the home directory of each individual account, and the mail is
delivered to either $HOME/Mailbox, or $HOME/INBOX. Again, you will have to
figure this out by yourself.
Courier can deliver mail to mailbox files only if the default mailbox file is in the home directory of each individual account, and if you use file locking. Courier does not support dot-locks, and Courier does not support a separate mail directory for mailbox files. Mailbox files must be located in the home directory of each individual account.
Courier can use a recipient database (userdb) that can specify a
non-default location for a recipient's mailbox. In theory, it is possible to
point each account to its individual mailbox in /var/spool/mail
,
or somewhere else. However, that's a tedious task that must be done manually
for each account, and is likely to be a major maintenance issue.
A better solution is to use a separate local mail delivery agent. Your
existing mail system is very likely to include a separate local mail delivery
agent. If you already use a mail delivery agent such as
procmail
, you probably already have it set to use the correct
locking mechanism for mailbox files, and it already knows where the mailbox
files are. Courier will be happy to hand off all local mail to
procmail
, or anything else for the actual delivery.
Courier source distribution includes the maildrop
mail
delivery agent which has some additional file locking options, however you'll
have less problems if you stick with procmail in the beginning, and switch to
maildrop
after you've gained some experience configuring and
installing Courier.
courier
user and group IDsYou should create a new userid and groupid named "courier
".
That's optional, but highly recommended. If this is not done, Courier will
install as user/group daemon
(or some other suitable user/group
id). Only two of Courier's daemon processes run as a superuser (and one of
them is perpetually waiting for a non-superuser daemon process to terminate,
in order to restart it). Everything else runs as a non-superuser process.
Ideally, you should reserve a separate user and group ID for Courier's use
only, so a compromised mail system cannot be used to compromise the rest of
the system. If push comes to shove, you can set up Courier to use a
well-defined existing user and group ID, such as daemon
.
Courier, by default, installs in /usr/lib/courier
. Everything
goes in there: binaries, scripts, configuration files, and manual pages. You
will have to configure your man
command to look for manual pages
in /usr/lib/courier/man
by adding this directory to the MANPATH
environment variable. You will also need to add
/usr/lib/courier/bin
and /usr/lib/courier/sbin
(for
the root user only) to the default PATH. The Courier RPM package installs a
script that automatically implements that.
Note that this installation layout is nothing more than a basic default,
chosen because this simple arrangement works for everyone. The installation
layout can be easily changed. For example, binaries can go to
/usr/local/bin
, and configuration files to
/usr/local/etc
. But keep in mind that Courier consists of
several hundred individual files (at the last count), so if you install
Courier somewhere else it might be very cumbersome to keep track of where
everything went, and it will lead to almost guaranteed problems later, when
you upgrade.
You should try to use some kind of a packaging system in order to keep track of your Courier installation. Once you choose a packaging system, you should stick to it. If you switch to a different packaging system you should take extreme care to remove your previous package, and install your new package. Extreme configuration flexibility means that different packages will install in different places, and even have different file ownerships!
For example, Courier's source code tarball can be built by RPM version
3.0.3 or higher, into a binary RPM package. The binary RPM package installs
configuration files in /etc/courier
, the mail queue in
/var/spool/courier
, and everything else in
/usr/lib/courier
. If you install my package, and later decide to
either create your own package or use someone else's, you will have to make
sure to use the same settings, or remove my package completely, before
installing your new package. I mean it when I say "remove my package
completely". That includes the mail queue containing any unsent messages.
Courier will not function if you reinstall it using a different user/group
ID, or if you use a different value for any other option.
Once these issues are squared away, you are ready to configure and install Courier.
After you are squared away with the preliminaries, run the
configure
script:
./configure [ options ]
NOTE
You MUST run the
configure
script as normal user, not root. Did you extract the tarball as root? It won't work. Delete everything you have just extracted, as root. Log in as a normal user. Extract the source code as a normal user, then runconfigure
. You will do everything as a normal user, except for the final step of installing the compiled software. When you're ready to do amake install
, later,su
yourself to root, and runmake install
.
The configure
script can take a while to complete. There will
be more then thirty separate configuration scripts that will be executed by
this command. To an untrained eye it may seem that the same configuration
script is stuck in a loop; that's because all these configuration scripts
share a lot of code. It may take as much as 15-20 minutes for
configure
to finish on a slow machine - even more.
You must have the uux
command in your default search path if
you intend to use Courier to relay mail via UUCP. You may need to modify your
PATH
environment variable to include the directory containing
uux
.
gcc/egcs
is officially blessed for building Courier. In most
cases there's no need to tweak any compiler-specific settings. Note that
there currently may be some unresolved issues with gcc 2.96. gcc 2.91 has
been tested and known to work. Occasionally some of your system libraries may
be stuck in some oddball directory that is not searched by default.
Non-standard options for the compiler or linker can be set by putting them
into environment variables. This must be done before running the
configurescript:
CFLAGS
- additional flags for the C compiler.CXXFLAGS
- additional flags for the C++ compiler.LDFLAGS
- additional flags for linker.LDADD
- additional libraries to link with. NOTE -
everything will be linked with these libraries.The complete reference to all configure
script options is
provided below. The most important options are:
--prefix=pathname
- install Courier in pathname,
instead of the default location of /usr/lib/courier
. Note -
the examples in the rest of this text assumes this is where you will
install Courier. Do not attempt to install Courier in a directory whose
name contains spaces or punctuation marks. Periods or dashes are fine,
but refrain the temptation to use other, exotic, punctuation.--with-db=db
or --with-db=gdbm
- Courier
requires either the GDBM or the DB database library. GDBM is used if both
are present. This option forces the selection of the database library.--with-locking-method=function
- Select a file
locking function. Available functions are: fcntl
,
lockf
, and flock
. Not every function is
available on every platform. If this option is not present,
configure
tries each one, and takes the first one that
works. You can select a specific locking function by using this option.
This affects both the locking used for delivering mail to mailbox files,
and for other kinds of locking that Courier uses internally.--enable-mimecharset=charset
- specifies the default
character set Courier uses when adding MIME headers to a message. If not
specified, us-ascii
is used.--without-tcpddns
- use this option if you are running a
small network without access to a DNS server. This option will cause
couriertcpd
to use the system resolver's gethostby
functions instead of issuing DNS queries. Also: you must initialize the
esmtproutes
control file with the IP addresses of all your
servers.configure
referenceHere's a comprehensive list of options for the configure
script. They are presented in no particular order. In almost all cases, the
configure
script will automatically figure out the correct
values, but sometimes it is necessary to specify them explicitly. If you ever
have a need to manually specify any configuration option, try to determine
whether you need it because of a particular unique case that involves your
server only, or whether it affects any server running your hardware, or
system. In the later case, try to investigate if it's possible for
configure
to be a bit smarter and make the right decision.
--prefix=pathname
- install Courier in
pathname, instead of the default location of
/usr/lib/courier
. Note - the examples in the rest of this
text assumes this is where you will install Courier.--exec-prefix=pathname
- specify where Courier's
machine-executable binaries should be installed. This defaults to the
same directory as given by the --prefix
option. There will
be three subdirectories created underneath exec-prefix
:
bin
- user-executable binaries; sbin
-
superuser-only binaries; libexec
- other binaries that are
not directly invoked from the command line, but are started by other
Courier commands.
--bindir=pathname
, --sbindir=pathname
,
--libexecdir=pathname
- these options override the default
value for the corresponding subdirectory underneath
--exec-prefix
(see above). The bindir
directory
contains programs that can be executed by anyone. sbindir
contains programs that can only be executed by the superuser.
libexecdir
contains programs and libraries that cannot be
directly executed from the command line. The default locations are the
bin
, sbin
, and libexec
subdirectories underneath the directory specified by
exec_prefix
.
--datadir=pathname
- specifies the directory where
miscellaneous shell scripts, Perl scripts, and data files will be
installed. This option defaults to the subdirectory "share
"
in the directory specified by the --prefix
option.
--sysconfdir=pathname
- specifies the directory where
Courier's configuration files are installed. This option defaults to the
subdirectory "etc
" in the directory specified by the
--prefix
option.--localstatedir=pathname
- specifies the directory that
will hold the mail queue, and other temporary data. This option defaults
to the subdirectory "var
" in the directory specified by the
--prefix
option.--without-ipv6
- do not compile IPv6 support. IPv6
support, if available is normally automatically detected and enabled. Use
--without-ipv6
to disable it. IPv6 implementations on
various platforms is still in flux, and IPv6 support will not be enabled
if the detection logic fails. Use --with-ipv6
in order to
fail the configuration stage if IPv6 is not detected, instead of silently
continuing with IPv4 support only. See "IPv6" below
for more information.--with-db=db
or --with-db=gdbm
- Courier
requires either the GDBM or the DB database library. GDBM is used if both
are present. This option forces the selection of the database library.--with-locking-method=
function
-
Select a file locking function. Available functions are:
fcntl
, lockf
, and flock
. Not every
function is available on every platform. If this option is not present,
configure will choose the first locking function that's available. You
can select a specific locking function by using this option. This affects
both the locking used for delivering mail to mailbox files, and for other
kinds of locking that Courier uses internally.--enable-mimecharset=charset
- specifies the
default character set Courier uses when adding MIME headers to a message.
If not specified, us-ascii
will be used.--without-tcpddns
- use this option if you are running a
small network without access to a DNS server. This option will cause
couriertcpd
to use the system resolver's gethostby
functions instead of issuing DNS queries. Also: you will have to
initialize the smtproutes control file with the IP addresses of all your
servers.--with-mailuser=user
- all except two Courier
daemons run as a non-privileged user. This option specifies the userid
that Courier will install and run as.--with-mailgroup=group
- like
--with-mailuser
, but specifies the group ID.--with-mailuid=userid,
--with-mailgid=groupid
- these options specify the
numerical user and group IDs. Do not use these options unless
configure
fails and tells you to use them.--without-explicitsync
- normally Courier will
automatically sync, or flush out all file buffers to disk, at certain key
points in order to try to minimize the extent the mail queue can get
corrupted if the system crashes. If the mail queue is installed on a
reliable disk array or a network file server, this may not be necessary,
and will only serve to slow down the mail delivery. Use this option to
turn off syncing.--with-dirsync
- also explicitly sync the parent
directory. There's a school of thought which believes that the Linux ext2
filesystem requires the parent directory to also be synced, in addition
to the new message file that's just been written to disk. There's another
school of thought that thinks that this issue is completely blown out of
proportion, and is really nothing more than a tempest in a teapot.
However -- to accomodate the former school of thought -- this option adds
a little bit of extra code to sync the parent directory.--with-shellpath=path
- specifies the contents of
the PATH
environment variable that is inherited by custom
programs started by Courier to deliver messages. If not specified,
PATH
will be set to
/bin:/usr/bin:/usr/local/bin
.--disable-local-extensions
- normally, in addition to
accepting mail that's addressed to <user@domain.com>
,
Courier can accept mail that's addressed to
<user-xxx@domain.com>
, for arbitrary values of
xxx. In order for that to happen the user
has to
create a special file with delivery instructions. See the dot-courier(5)
manual page for
more information. This option disables this feature.--with-paranoid-smtpext
- be paranoid when negotiating
Courier-specific ESMTP extensions with remote servers. The Courier mail
server defines and implements certain experimental ESMTP extensions:
XVERP
and XEXDATA
. Problems may result in the
event that someone else uses the same name to implement some other
extension. If this option is specified, Courier's ESMTP
server will also advertise a dummy ESMTP capability called
XCOURIEREXTENSIONS
, and will not recognize any
Courier-specific extensions unless the remote mail server also advertises
this dummy ESMTP capability.--enable-workarounds-for-imap-client-bugs
- there are
several confirmed bugs in some IMAP clients that do not properly
implement the IMAP4rev1 protocol. This option enables some workarounds
for those buggy IMAP clients. NOTE: make check
will fail if
this option is used. You should first configure without this option, and
if all post-configuration tests succeed, rerun configure with this option
and recompile.--with-qdircount=n
- set n to be the number
of mail queue subdirectories. In order to improve the speed of access to
the mail queue, messages are stored in subdirectories, hashed by the
message queue number. n specifies how many subdirectories will be
created. If this option is not specified, 100 subdirectories will be
used. WARNING: once you've installed Courier once, if you decide
to reconfigure and reinstall, you MUST use the same subdirectory count
(by default, or explicitly), otherwise you'll end up with a big mess on
your hands if you have ANY messages in the mail queue. If you need to
change this option, wait for all messages in the queue to be flushed out,
and reinstall with an empty mail queue.--disable-changepass
- disable the ability to change login
passwords in the webmail server. Use this if you don't want to install
the authsystem.passwd
utility (which is installed suid root)
that is used to change login passwords.--without-authpam, --without-authldap, --without-authpwd,
--without-authmysql, --without-authpgsql, --without-authshadow,
--without-authuserdb, --without-authvchkpw, --without-authcram,
--without-authdaemon
- manually disable authentication modules.
Authentication modules are used to verify passwords for POP3 access,
webmail access, authenticated ESMTP relaying, and IMAP access (where
available). They're also used to locate accounts and mailboxes that
correspond to a given local mail address. The configure
script automatically checks the system and selects the appropriate
authentication modules, based upon the available libraries. Rarely is
there a need to manually use these options. It is always possible to
install an authentication module, but to disable it in actual use. See
below for more information. --with-random=/dev/path, --without-random
- for
authenticating, Courier sometimes needs a good source of random noise. If
configure
finds /dev/urandom
, it will use that.
If your random device is named otherwise, specify it using this option.
If you don't want to use a random device, specify
--without-random
, and Courier will generate some
noise on its own. Courier will generate noise based on the output of a
random ps command, and several other, hopefully unpredictable,
sources.--without-certdb
- do not install a default set of trusted
X.509 root CA certs (in order to validate the remote server's X.509
certificate). See "Configure ESMTP authentication
and SSL" for more information.--with-certdb=pathname
- do not install the default
set, but put pathname as the default location of the root CA
database, into the configuration file. This is a convenient option to
have Courier use an external, previously installed, root CA database.--with-waitfunc=wait, --with-waitfunc=wait3
- specifies
the system call to use to asynchronously reap child processes. This is a
sticky one, because the behavior of the wait and wait3 system calls
varies greatly depending on the level of each individual system's POSIX
compliance. The configure script will attempt to compile and run some
test programs in order to attempt to figure out which system call
actually works. If the configure script fails, or if it selects a wrong
function (which will be evident when mail delivery stops, and you have a
bunch of zombies that are not being reaped), you might have to manually
specify it using either option. In that case, however, you should also
examine the test programs, investigate what went wrong, and patch the
test programs to give a correct result for your system.--without-ispell, --with-ispell=program
- Courier's
webmail server can use spell checking, if the ispell program is available
(aspell can be used too). If configure finds ispell, spell checking is
enabled. Use --without-ispell
to forcefully disable spell
checking. If ispell is not in the current search path, use
--with-ispell=program
to explicitly set the location
of ispell. See "Configure the webmail server" for
more information on ispell or aspell.--disable-utf7-folder-encoding
- use this option if you
will not have IMAP access to mail accounts, and provide only webmail
access. IMAP mail clients use modified UTF-7 to encode high 8-bit
characters in folder names. If there will not be IMAP access to mail
accounts, modified UTF-7 support in the webmail served can be removed,
saving a little bit of overhead.--enable-unicode
- include the ability in the IMAP server
to search and sort messages in character sets besides the default
ISO-8859-1/US-ASCII. All character set tables supported by Courier's IMAP
server will be included. See "Configure the IMAP
server" and "Configure the webmail server" for
more information. Additionally, all unicode tables will also be included
in the webmail server. Keep this in mind because the full unicode table
set is quite large. --disable-utf7-folder-encoding
), additionally the webmail
server will be able to translate message text to the local character set,
if the two are different and the unicode tables for both character sets
are available. --enable-unicode=charset,charset,...
- include
ability to search and sort messages, but only for these character sets.
Also, include only these character sets in the webmail server. See "Configure the IMAP server" and "Configure the webmail server" for more
information.--enable-imageurl=/url
- use /url/ as the
URL to the static images displayed by the webmail server. HTML pages are
dynamically generated by the webmail server CGI, but they also include
some static icons. The webmail CGI will use /url as the URL to the
directory containing the static images. The default URL is "/webmail",
which means that the static images must be installed in the
<DocumentRoot>/webmail
directory. This is a manual
process that is described in more detail in the "Configure the webmail server" section, below.--enable-https, --enable-https=login, --enable-https=auto
- if you have an SSL-enabled web server, use the
--enable-https
option in order to configure webmail access
for SSL. Use --enable-https=login
in order to use SSL only
when logging in, to send the password. Use
--enable-https=auto
to generate relative URLs, so that users
can connect with either http or https and their session will remain that
way.--enable-https=login
and --enable-https=auto
require that your http and https URLs that refer to the webmail CGI be
identical (which is the usual default).--enable-https=auto
is the default. Use
--disable-https
if you need to completely disable https, for
some reason. --enable-hardtimeout=7200
- set the hard timeout for
webmail sessions (in seconds). The default is 2 hours. webmail sessions
are unequivocally logged out after the indicated time interval.--enable-softtimeout=1200
- set the inactivity timeout for
webmail sessions (in seconds). The default is 20 minutes. webmail
sessions are logged out if there's no activity for the indicated time
interval.--with-defaultlang=lang
- reserved for future
use.--enable-mimetypes=file:file:file
- this is a
colon-separated list of all of your mime.types
files. The
mime.types
configuration files are used to map file
extension to their corresponding MIME content types. The configuration
script will look in several directories where mime.types
usually exists. You can use this option to explicitly specify a list of
mime.types
files to be used, instead of the default.--enable-bannerprog=pathname
- advanced option that
sets a banner program that the webmail server will execute. This program
should print HTML, on standard output, to generate a typical banner.--with-maxargsize=bytes,--with-maxformargsize=bytes
- sets an upper limit on the size of CGI arguments. Normally there's no
reason to modify the defaults (500,000 and 2,000,000 bytes). The latter
is generally the maximum allowed size of an attachment. The former is
generally the maximum allowed size of a message.--with-cachedir=dir,
--with-cacheowner=userid
- the webmail server uses a cache
of currently active logins. The webmail server binary, is executed for
each and every HTTP request, and the user's maildir needs to be quickly
located each time. Because hitting the authentication module can be
expensive (think MySQL/PostgreSQL/LDAP query for every HTTP request!) the
webmail server will cache this information in order to avoid having your
authentication server brought down to its knees. By default, the
directory /usr/lib/courier/var/webmail-logincache
will be
used, owned by the bin user. These options can be used to specify
a different location for the webmail login cache directory./usr/lib/courier/share/sqwebmail/cleancache.pl
script which deletes expired cache records from the cache directory. Add
the following command to be executed from cron at least once an hour:
su -c "/usr/lib/courier/share/sqwebmail/cleancache.pl" bin
(This assumes that your cache directory is owned by the bin
user). There's no need to set up this cron job if the webmail server is
not used. NOTE: your su command may use different options or syntax,
check the su manual page to confirm the correct syntax.
--without-gzip
- if the configuration script finds the
gzip utility, the webmail server will automatically use gzip compression
for some large web pages (if the client browser supports gzip
compression). Use this option to turn off gzip compression.--disable-autorenamesent
- do not rename the Sent folder
every month. This option can also be controlled by the
SQWEBMAIL_AUTORENAMESENT environment variable (which can be set in
Apache's httpd.conf, for example).--with-calendarpurge=N
- if calendaring is enabled, purge
expired calendar events after N days (default: 30).--with-trashquota
- include deleted messages, and the
Trash folder, in the estimated quota usage for maildirs. Quotas are
optional, see the file maildir/README.maildirquota.html for more
information. The default configuration does not count messages marked as
deleted (but not yet expunged) and the contents of the Trash folder
(which are automatically purged by the server) against the quota usage.
NOTE - if this option is used, make check
WILL FAIL. You
should first configure Courier without this option, run make
check
, then reconfigure Courier with this option.Authentication modules serve two purposes: identify the location of the mailbox for a local mail account; validate the password provided by IMAP, POP3, or Webmail to access the mailbox.
There are several authentication modules available. Each authentication module implements a separate way of authenticating logins, and not all authentication modules can be used on every system. Some authentication modules can be used only on systems that have certain libraries or software installed.
The configure
script checks the system configuration and
automatically prepares a default set of authentication modules which will be
used. The option --without-module
, where "module"
represents the name of the module, can be used to selectively disable the
module. However, there's usually no reason to do that. Modules can be easily
disabled at runtime, by removing them from the authmodulelist
configuration file, or from the authdaemonrc
file if the
authdaemon
module is going to be installed.
Here's a brief list of the available authentication modules:
authpwd
- authenticate against the system passwd file.authshadow
- use instead of authpwd
on
systems that use the shadow password file.authpam
- use the PAM library for authentication.
authpam
MUST be used instead of authpwd
or
authshadow
on systems that use PAM authentication.authuserdb
- authenticate from a GDBM/DB database,
maintained by some simple Perl script that are included with Courier.authcram
- also authenticate from a GDBM/DB database, but
use CRAM-MD5 or CRAM-SHA1 authentication.authmysql
- authenticate from an account file stored in a
MySQL database.authpgsql
- authenticate from an account file stored in a
PostgreSQL database.authldap
- authenticate from an account file stored in an
LDAP directory.authvchkpw
- use the vpopmail library for
authenticating.authdaemon
- use the authdaemond
authentication proxy process (see below).Most of these authentication modules have a corresponding configuration file that define various parameters (server location, field names, etc). After installation you will need to open their configuration files, and follow the instructions in the configuration file.
The list of authentication modules, and their respective order, is read
from the authmodulelist
configuration file, and unwanted
authentication modules can be disabled simply by removing them from this
file. When authdaemon
is installed the list of modules is found
in the authdaemonrc
file instead. When authdaemon
is installed, Courier does not issue authentication requests directly,
instead they are forwarded to the authdaemond
process. This is a
small persistent process that runs in the background and opens persistent
database connections. This is much faster than opening and closing a
connection to the database for each individual authentication request.
Starting with Courier 0.35, the authdaemon
module will always
be installed, unless explicitly disabled by the configure
script. This greatly simplifies these installation instructions.
Additionally, authdaemon
is required in order to be able to
change passwords in the webmail server. If authdaemon
is not
installed, webmail may not be able to change the account password, because
that procedure usually requires elevated privileges (and webmail drops root
privileges right away, while authdaemon
retains them, in the
background).
This module should be used on systems that have the PAM library. With this
module, Courier will use whatever PAM modules are defined for authenticating
the "webmail", "imap", "pop3", or "esmtp" PAM service services. Essentially,
authpam
allows any PAM module to be used for authenticating mail
account logins. NOTE: in addition to including this module, you will have to
take additional, site-specific, steps in order to configure your PAM library
for the "webmail" PAM service. The specific details regarding your PAM
configuration differs from system to system, and you should consult your own
documentation. It might be tempting to throw in a towel and use
authshadow
or authpwd
if you cannot figure out how
to install PAM support, however that is not advisable. It is highly
recommended to use authpam
wherever the PAM library is
available.
Although the exact procedure to configure PAM authentication differs from
system to system, if you have the directory /etc/pam.d
try
creating the file /etc/pam.d/webmail
, containing the following
text:
#%PAM-1.0 auth required /lib/security/pam_pwdb.so shadow nullok account required /lib/security/pam_pwdb.so
Repeat the same for imap
, pop3
, and
esmtp
files. Your system may use the pam_unix.so
module instead of pam_pwdb.so
, and your modules may be located
in a different directory.
If instead of /etc/pam.d
you have a global file named
/etc/pam.conf
, try appending the following lines to the end of
this file:
webmail auth required pam_pwdb.so shadow nullok webmail account required pam_pwdb.so shadow nullok
Repeat the same lines with "imap", "pop3", and "esmtp" entries to set up
authentication for those services as well. Again, you may have to use
pam_unix.so
or specify the full pathname to the PAM module.
HINT: try to look at how other PAM services are set up, and duplicate
their configuration for the webmail
service. A good example to
follow would be the ppp
service, if it exists.
NOTE: If optional webmail calendaring is enabled in groupware mode, PAM must be configured to authenticate the "calendar" service in addition to "webmail". In most cases, creating a soft link from
/etc/pam.d/calendar
to/etc/pam.d/webmail
does the trick.
These modules use GDBM or DB database files, usually
/etc/userdb.dat
and /etc/userdbshadow.dat
to look
up userids and passwords. These files are GDBM or DB database files that are
loosely equivalent in function to /etc/passwd
and
/etc/shadow
. authuserdb
handles the traditional
userid/password logins, and authcram
handles CRAM
authentication. The database files are maintained indirectly by several Perl
scripts (which are included with Courier), which build these database files
from a plain text file, usually called /etc/userdb
that can be
modified using any text editor, or via command line with the aid of these
Perl scripts. /etc/userdb
may also be a subdirectory with
multiple text files of the same format, which are concatenated. This allows
creating virtual mail accounts that do not have a corresponding login account
-- virtual mail accounts that can share the same, reserved, system userid.
/etc/userdb
can also be used to completely supercede
/etc/passwd
. With many accounts it can be quite a drain to have
to continuously linearly scan /etc/passwd
in order to look up an
account. Instead, a fast database lookup can retrieve the same information
from the database file. Read the included manual pages, starting with
for more information.userdb(8)
Edit the authmysqlrc
configuration file to configure this
module. For more information, see the file
authlib/README.authmysql.html
.
Edit the authpgsqlrc
configuration file to configure this
module. PostgreSQL configuration is nearly identical to MySQL information,
see authlib/README.authpostgres.html
for more information.
After running make install
, edit your system's startup script
and have it run authdaemond start
at system boot.
The authdaemond start
is actually a script. Depending on your
system configuration, there may be one or more different
authdaemond
binaries installed, and here's why.
authdaemond.plain
will include all available authentication
modules except for certain "heavy" authentication modules. The current list
of "heavy" authentication modules is authldap
and
authmysql
.
If support for a "heavy" authentication module is selected, there will be
an additional binary installed, such as authdaemond.mysql
or
authdaemond.ldap
. The authdaemond start
script
checks if any "heavy" authentication daemon is installed, and, if so, runs
that. Otherwise, the default authdaemond.plain
binary goes
in.
This allows an easy way to create binary Courier distributions with and
without LDAP or MySQL support. The distributor would simply build Courier on
a machine that contains both LDAP and MySQL development libraries, then take
everything but authdaemond.mysql
and
authdaemond.ldap
and roll it into the base Courier package.
authdaemond.mysql
and authdaemond.ldap
are rolled
into separate sub-packages. Loading a base package installs basic system
authentication services. Adding LDAP or MySQL support is as simple as loading
the corresponding sub-package.
You can find out what authentication modules were actually used, but after
running the configure
script you must also at least run
make
, and have it succesfully complete. Running
make
, compiles the authinfo
program in the
authlib
subdirectory. Run this program to tell you what
authentication modules were compiled in.
To change the list of enabled authentication modules, simply rerun the
configurescript.
IPv6 support in Courier means basically the following:
IPv6 implementations are required to accept IPv4 connections on IPv6 sockets, so IPv6 sockets should be able to receive both IPv4 and IPv6 connections. In the event that your IPv6 implementation is not stable, or is partially incomplete, IPv6 support in Courier should be disabled.
The configuration script will attempt to detect whether IPv6 structures
and functions are available, and automatically enable IPv6 support if they
are found. The --without-ipv6
option disables IPv6 support,
which may be desired for the following reasons:
/var/log/messages
-- modprobe is whining that it
can't find an IPv6 module to load. On systems that handle a large amount
of traffic the log files can fill up rather quickly.IPv6 support is still a bit spotty in some places. If the configuration
checks fail, IPv6 support will be quietly suppressed. If you expect IPv6
support to be present, the --with-ipv6
flag can be used to abort
configuration if IPv6 support was not detected.
make
check
make make check
If the configure
script ran without errors, run
make
to build Courier. If make
completes
succesfully, run make check
. make check
runs some
simple internal tests. It is not feasible to run a complete check of
Courier's behavior, but make check
does automatically run some
tests on several modules.
If make check
fails, you need to do some detective work.
Investigate the source of the failure. It is possible that the issue can be
resolved by specifying different options to the configure
script, in which case you have to go back and rerun the
configure
script again.
su
yourself to root, if you want to do a live install, then
run make install
or make install-strip
to install
Courier. If you use the GNU version of make
, and you would like
to see which files Courier installs and where, don't su
yourself
to root, but set the make
variable named DESTDIR
.
For example:
make install DESTDIR=/var/tmp/courier-inst
The contents of DESTDIR are prepended to the name of every file installed,
so if --prefix
was set to /usr/lib/courier
, the
files will be installed in
/var/tmp/courier-inst/usr/lib/courier
. This only works if you
use GNU make.
NOTE: you must make sure that your umask is 022 before you run make install.
If executed by root, make install
automatically sets the
correct ownership on the installed files. Non-root make installs
do not set the ownership, but still set correct permissions. This feature is
mainly for use by people who are rolling Courier into a prebuilt package,
since this allows them to build the package as a normal user, not root. In
this situation the command make install-perms
will be very
useful. This command creates a file called permissions.dat
. This
file contains a complete listing of everything that will be installed, and
what the correct permissions are on every file.
make install
installs Courier binaries with debugging data,
which is probably a good idea to do while Courier is in development. Use
make
install-strip
to install binaries without
debugging data. Some systems have a broken install
utility, so
make install-strip may fail.
The following command creates and updates configuration files. It must be
executed after running make install
:
make install-configure
This command copies each configuration file "filename.dist" to
"filename". The existing filename is backed up as
filename.bak. If upgrading from Courier 0.30 or later, the previous
configuration settings in filename.bak will be automatically copied to
filename, provided that they are still valid. If a configuration
setting may no longer be valid, it will be reset to its default value. The
output of make install-configure
will indicate the status of
each configuration setting, therefore it is advistable to save the output to
a file, and examine it:
make install-configure >upgrade.log
Versions prior to 0.30 cannot have their configuration settings automatically preserved, and must be restored manually from filename.bak. Do not simply copy filename.bak to filename, this will lose all the formatting codes that allow automatic upgrades.
If you use PAM library for authentication, you may need to set up PAM for
authenticating POP3 logins, IMAP logins, webmail logins, and/or ESMTP
authentication. In most cases, all you have to do is install
/usr/lib/courier/etc/pop3d.authpam
as
/etc/pam.d/pop3
, /usr/lib/courier/etc/imapd.authpam
as /etc/pam.d/imap
,
/usr/lib/courier/etc/webmail.authpam
as
/etc/pam.d/webmail
, and
/usr/lib/courier/etc/esmtp.authpam
as
/etc/pam.d/esmtp
. However you will have to consult your PAM
documentation, and the manual pages for authpam
, in order to
make sure.
Some versions of the PAM library, do not use the /etc/pam.d
directory. Instead they use a single configuration file
/etc/pam.conf
. Here's an example of what needs to be added to
/etc/pam.conf
on FreeBSD 4.0. NOTE: other platforms may need
something similar:
imap auth required pam_unix.so try_first_pass imap account required pam_unix.so imap session required pam_permit.so pop3 auth required pam_unix.so try_first_pass pop3 account required pam_unix.so pop3 session required pam_permit.so esmtp auth required pam_unix.so try_first_pass esmtp account required pam_unix.so esmtp session required pam_permit.so
NOTE: If you build an RPM package directly from the source tarball, the resulting RPMs may not install if you have an existing IMAP or an existing POP3 server installed. The RPM packages will contain these PAM configuration files, and they will conflict with any PAM configuration files installed by another IMAP or POP3 server. If you manually installed an IMAP or a POP3 server without packaging them up into an RPM, the Courier RPM package will install and the old configuration files will be silently removed, since they were not installed using RPM.
Courier includes integrated POP3, IMAP, and webmail servers, however they
only work with maildirs. Decide if you want to keep using your current
server, or switch to Courier's IMAP/POP3/webmail servers. If you want to keep
your existing servers, back up the contents of your /etc/pam.d
directory before installing the RPM, install it, then restore the overwritten
files. If you want to switch to Courier, blow away your current server before
running make install
.
There are six setuid binaries in Courier that are owned by root:
sendmail
, maildrop
, webmail
,
webadmin
, authsystem.passwd
and
authstart
.
/usr/lib/courier/bin/maildrop
is the mail filter. If you do
not need mail filtering, you can remove it. The setuid root privilege is only
needed to implement mail filtering "on the wire", when receiving mail from an
external mail relay (see localmailfilter(7) for more information).
Removing the setuid root bit still allows traditional mail filtering to be
used, after the message is received and delivered to the mailbox.
/usr/lib/courier/libexec/courier/webmail/webmail
is the
webmail CGI. It is executed by the web server, and needs to change its
userid/groupid, in order to enter the maildir. If you do not need webmail
access, you can remove it. An alternative is to implement virtual mailboxes,
owned by a non-privileged userid, and change the ownership of the webmail CGI
to the non-privileged user (you will also need to use the
--with-cacheowner
option to the configure
script
since the webmail process must have write access to the webmail login cache
directory).
/usr/lib/courier/libexec/authlib/changepwd/authsystem.passwd
is used by the webmail server to update mail account passwords. The password
authentication module, authdaemon
is a persistent background
process that receives authentication requests from a privileged filesystem
socket. authsystem.passwd
receives a request to change the mail
account password: the old userid, the old password, and the new password,
then opens the privileged socket and sends the request to the authentication
module. This binary can be deleted if the webmail server is not going to be
used.
/usr/lib/courier/libexec/courier/webmail/webadmin
is the
wrapper for the web-based administration tool. See
below for more information.
/usr/lib/courier/bin/sendmail
is the command line mail
sender. Its first order of business is to set its group id to Courier's group
id, and restore the original userid, dropping root. The reason that it needs
root setuid is to set its real group id, because setting the setgid bit on
the executable is not enough. The setgid bit sets only the effective group
id, and the root setuid bit is required to set both effective and real group
ids. Both real and effective group IDs are needed in order to be able to
implement maildrop mail filtering.
/usr/lib/courier/libexec/courier/modules/esmtp/authstart
is
used by the ESMTP server to implement authenticated ESMTP. The ESMTP server
runs as a non-privileged user. Authenticating a userid and password requires
root privileges, since only root can typically access system passwords.
authstart
is installed without any world read or execute
permissions, and can be executed only by the courier system group id. If you
do not need to implement authenticated ESMTP you can remove
authstart
. Permissions on authstart
will be
tightened up a bit in a future release.
A first-time Courier installation may not require the system startup scripts to be modified to start Courier at system boot. Until the system's functionality is verified, the system will probably continue to use the existing mail server. Still, most Courier configurations will require two things to be started before any part of the system is put to use:
authdaemond
process must be started in order for
authentication to work. The default configuration uses a background
process to authenticate local mail accounts. Run
"/usr/lib/courier/libexec/authlib/authdaemond start
" to
start the background process. Before starting authdaemond
,
review the contents of the /usr/lib/courier/etc/authdaemonrc
configuration file, to select the authentication modules to be used. Some
authentication modules will require additional configuration files to be
initialized (such as authmysqlrc
, authpgsql
and
authldaprc
) before authdaemond
is started.cron
job needs to be created to run the
cleancache.pl
script, which purges expired webmail login
cache records. Logging in to the mail account via the web creates a file
in a temporary directory that caches the login session identity. The
output of make install
includes the command that needs to be
set up as a cron
job by root. The cron
job runs
su
to change to the userid that owns the login cache
directory, then runs the purge script. The su
command on
some system uses a slightly different syntax than what's shown by
make install
. It may be necessary to consult the
su
man page before setting up the cron job. Run the
su
command as root, to make sure that its syntax is correct,
before setting up the cron
job. The cron
job
can be omitted if webmail is not going to be used.The following tests should be run to verify that your installation works properly. These tests are not really comprehensive tests, they only make sure that the basic functionality is there, and they definitely must be done the first time you install a version of Courier on your system. If you later reinstall the same version on the same platform, using the same configuration, you don't need to run these installation checks (but you better be sure that the reinstallation is COMPLETELY identical to the original install). You might also wish to rerun these installation checks after upgrading your base operating system.
The following documentation assumes that Courier is installed in
/usr/lib/courier
.
Run the showmodules
utility after all files have been
installed, but before you attempt to start Courier. The
showmodules
utility attempts to load and initialize transport
modules that have been configured, without actually starting up Courier.
Running showmodules
should result in something that looks like
this:
showmodules[5060]: Loading STATIC transport module libraries.
showmodules[5060]: Installing i586-gnu-linux [0/0]
showmodules[5060]: Installing local
showmodules[5060]: Installed local
showmodules[5060]: Installing esmtp
showmodules[5060]: Installed esmtp
showmodules[5060]: Installing dsn
showmodules[5060]: Installed dsn
showmodules[5060]: Initializing local
showmodules[5060]: Initializing esmtp
showmodules[5060]: Initializing dsn
In this test, you will start Courier, then attempt to rapidly pump through as many messages as fast as possible, to verify that asynchronous child process termination handling works. For this test (and the following tests) you need to use a test account.
Log on to the test account and run maildirmake
to create two
maildirs: maildirmake $HOME/test
, and maildirmake
$HOME/bounces
.
Create $HOME/.courier-test-default
, containing one line:
./test
. Create $HOME/.courier
, containing one line:
./bounces
. If you previously selected .qmail compatibility, you
will need to use .qmail-test-default
and .qmail
, of
course. Keep that in mind as you work through the remaining tests.
Configure Courier for local account authentication. If you intend to use LDAP or MySQL authentication, there are some configuration files that must be edited to configure authentication. See the authlib(8) manual page for more information.
Start Courier as root:
/usr/lib/courier/sbin/courier start
Check your system log files for any error messages. Run the ps command, and check that you only have the following processes running: courierd (two processes), courierdsn, courieruucp, courieresmtp, and courierlocal. You will also have a couple of "logger" processes hanging around, that's ok too.
One of the two courierd processes will be running as root. The
courierlocal process will also be running as root. All other processes will
be running as the courier (or daemon, or mail) user. courieruucp
may be running as uucp
.
If your configuration includes the authdaemon authentication module (see "configure reference" above) you need to start the authdaemond process too:
/usr/lib/courier/libexec/authlib/authdaemond start
Run the perftest1
script, which can be found in the directory
containing Courier's source code:
sh perftest1 1000 "user-test-1 user-test-2 user-test-3 user-test-4 user-test-5"
Run this script while logged on to the test account. Replace "user" with
the name of your test account. This will send 1000 messages with five
recipients per message. You should end up with exactly 5000 messages in
$HOME/test/new
. Count them.
Monitor the system logs. There will be a lot of activity. On my test
system, the system logger usually backs up. Courier generates log messages
faster than the logger can record them. When all the activity stops, count
how many files you have in $HOME/test/new
. For extra credit,
total up the Delivered-To:
headers in all the messages, there
should be 1000 headers for each one of the five addresses.
If you did not get 5000 messages, and mailq
comes up empty,
check $HOME/bounces/new
. If you're lucky, the rest bounced.
That's still a problem, but the bounces will help you to investigate things
further.
If you did not get 5000 messages, and mailq
shows some
messages remaining in the queue, and ps
shows some dead zombie
processes that are not being reaped, this means that asynchronous process
termination is not working. You will need to examine your configuration to
see whether configure
selected the wait
or the
wait3
function. Unpack the source code again and rerun
configure
. This time use the --with-waitfunc
option
to choose the other wait function, manually. Recompile, reinstall, and rerun
this test.
If you did get all the messages, go through your syslog for extra-extra
credit. grep
it for the word "defer" to see if any messages
required multiple delivery attempts. This shouldn't happen either.
If your hardware has enough juice to pump through 5000 messages in a short period of time, rerun this test with a larger number of messages. Before doing that, wipe the Maildirs clean, in order to confirm the message count, later. The test must run for at least 3-4 minutes in order to get meaningful results.
For this test you will need to use or create a regular user test account,
which will be referred to as user. You can use the same test account
you used in the last test, but erase all .courier
(or
.qmail
) files.
In user's home directory, create .courier
which contains the
following text:
| /usr/bin/id >ID
| /usr/bin/env >ENV
Make sure that your id
and env
commands are in
/usr/bin
. If not, use the correct path.
Send a single message to user:
echo "To: user" | /usr/lib/courier/bin/sendmail
Thie message will disappear into the never-never land, so don't waste time
looking for it. Just examine, very closely, the contents of the
ID
and the ENV
files in user's home
directory. Double check what user and the group ids recorded in
ID
match user's. Pay close attention to any auxiliary
group IDs, make sure that they haven't "leaked" from the root user who
started Courier.
Also, examine the environment, in ENV
. Check the manual page
for dot-courier
, ENV
should contain only the
documented environment variables, and any environment variables that are
defined in the /usr/lib/courier/etc/courierd
file.
webadmin
This is a web-based administration tool. webadmin
is a web
CGI application. It is necessary to have a local web server installed in
order to use webadmin
. Apache will do, but so will any other
server with a complete CGI implementation (PHP is not required). Installing
webadmin
is a three step process:
/usr/lib/courier/libexec/courier/webmail/webadmin
to
your web server's SSL cgi-bin
directory. Take care to
preserve the binary's ownership and permissions.make install-webadmin-password
". This prompts for
a password, which is saved in the file
/usr/lib/courier/etc/webadmin/password
.webadmin
from
the cgi-bin
directory using SSL only.
webadmin
's authentication is rather simple: the password is
saved in a cookie. Unless SSL is used, the webadmin
password
can be intercepted in transit. If SSL is not available, an acceptable
level of security can be achieved by setting up a firewall that allows
web access only from trusted IP addresses, then use a dedicated webadmin
password. This is not perfect, but is generally adequate. A firewall is a
good idea even if SSL is used. This is not Fort Knox, and
webadmin
is not going to be publicly accessible, so the only
needed security is to keep everyone out except for authorized IP
addresses. webadmin
, by default, will enforce this
restriction: either SSL, or access from a local IP address. Create the
file /usr/lib/courier/etc/webadmin/unsecureok
to allow
non-SSL webadmin
connections from remote IP addresses.webadmin
is designed to be self-explanatory. Configuration
options are divided into logical sections. Changes made to configuration
options do not take effect immediately. To apply configuration changes,
select "Install new configuration" from the main menu. To cancel all changes
made, select "Cancel new configuration". Selecting "Install new
configuration" will apply all the changes to the configuration files, and
restart any Courier modules that must be restarted in order for the changes
to take effect.
If you decide to use webadmin
, most of the remaining steps in
this INSTALL document can be done using webadmin
's equivalent
screens.
You must now specify which account gets postmaster mail. Courier does NOT deliver any mail to root. You must use a non-privileged for postmaster mail. You will also need to specify where your postmaster account is. In the following example the same account is used for both, but you can easily use separate mailboxes.
Let's say that you want postmaster mail to be delivered to the user "admin".
Create /usr/lib/courier/etc/aliases/system
using any text
editor. An example aliases/system
file is created by make
install
, and you can simply edit what you have there. The default
contents of this file are as follows:
root: postmaster
mailer-daemon: postmaster
MAILER-DAEMON: postmaster
uucp: postmaster
You need to append the following line:
postmaster: admin
These aliases cause all mail addressed to root, postmaster, or mailer-daemon, to be delivered to admin's account. If you want root's mail delivered somewhere else, you can replace "root: postmaster", with something else.
Run the following command as root:
/usr/lib/courier/sbin/makealiases
This command creates /usr/lib/courier/etc/aliases.dat
, a
database that contains your new aliases.
Send a test message:
echo "To: postmaster" | /usr/lib/courier/bin/sendmail
Check admin's mailbox, the message should be there.
Let's do it again:
echo "To: postmaster" | /usr/lib/courier/bin/sendmail
-Nsuccess
This time, in addition to the blank message, the sending account should receive a return receipt.
Additional aliases can be either added to this file, or placed in any
other text file in the /usr/lib/courier/etc/aliases
directory.
You need to define which IP addresses are allowed to relay SMTP mail
through the server. The installation script creates
/usr/lib/courier/etc/smtpaccess/default
containing an example of
how to enable relaying for IP address 127.0.0.1, and several reserved
netblocks. You can either append additional entries to this file, or put your
additional entries in any other file in the
/usr/lib/courier/etc/smtpaccess
subdirectory. Afterwars, run the
following as root:
/usr/lib/courier/sbin/makesmtpaccess
This command creates the /usr/lib/courier/etc/smtpaccess.dat
database that couriertcpd
uses to initialize the environment for
courieresmtpd
.
You will need to rerun makesmtpaccess
in order to rebuild
smtpaccess.dat
after any changes in the smtpaccess
subdirectory.
The default Courier configuration applies smtpaccess.dat
to
both the regular ESMTP server (port 25), and the message submission server
(port 587). It is possible to set up different access files for both ports.
To do that, edit /usr/lib/courier/etc/esmtpd-msa
, and explicitly
set ACCESSFILE
to a different file, create that file, and use
the makesmtpaccess-msa
command to compile the dedicated port 587
access database.
Review/edit contents of various configuration files in
/usr/lib/courier/etc
:
courierd
- this file controls general aspects of Courier's
message processing. A default file is installed with comments describing
what the various options are. Review the default options, and make
whatever changes you deem appropriate. You will probably need to make
changes to this configuration file in order to select the correct way to
deliver local mail (whether to have Courier handle the delivery directly,
or whether to run procmail or maildrop). There are comments in this file
that tell you what needs to be done to have Courier use a separate local
mail delivery agent, such as procmail
, for mail delivery.
Read and follow the instructions there.esmtpd
- this is an important file that controls Courier's
ESMTP server. Options in this file include setting the maximum limit on
simultaneous server connections, whether to disable certain optional SMTP
features, whether or not you have a mail filter module installed, and
whether or not blacklists are used. By default, this file configures
Courier to filter all incoming mail against the MAPS RBL (see http://mail-abuse.org/). There's also
an entry in there for MAPS RSS, however RSS-listed mail does not get
rejected by default, the indicator is only made available for an external
mail filter to use. Instructions for having Courier itself block
RSS-listed relays, in addition to RBL-blacklisted ones, are included.esmtpd-msa
- this file controls Courier's ESMTP message
submission server (RFC 2476). The settings in this file supplement the
settings in esmtpd
. The default startup script first reads
esmtpd
, then esmtpd-msa
in order to initialize
the ESMTP message submission server on port 587.smtpaccess
- this configuration file/directory is used to
ban explicit IP addresses from connecting to the ESMTP server at all, or
to specify which IP address ranges are allowed to relay mail through the
ESMTP server. The default file turns on relaying in a couple of reserved
IP address ranges, as an example. The makesmtpaccess
command
must be executed for any changes to smtpaccess
to take
effect.pop3d
- this file sets various options for Courier's POP3
server. Courier's POP3 server can be used only if mail is stored in
Maildirs. You will need to use another POP3 server if you choose to
deliver your mail to legacy mailbox files. A default configuration file
is installed, describing the available options.imapd
- this file sets various options for Courier's IMAP
server. Courier's IMAP server can be used only if mail is stored in
Maildirs. You will need to use another IMAP server if you choose to
deliver your mail to legacy mailbox files. A default configuration file
is installed, describing the available options.authmodulelist
- authentication modules for the core mail
server. The pop3d
, imapd
, and
esmtpd
, and esmtpd-msa
configuration files
specify standalone authentication modules that are used by the
corresponding servers. Courier's core mail server also needs to use those
authentication modules in order to locate local mailboxes. However, for
speed, those authentication modules are statically linked with Courier's
mail core daemon. In some situations you do not want Courier's mail core
daemon to use an authentication module. The authmodulelist
configuration file contains a list of authentication modules used by
Courier's main mail core daemon. If you want to disable an authentication
module, simply remove it from this file. The default installed file will
be initialized to contain all the authentication modules that are
installed at configuration file.authldap
authentication module. If
you do not want to use your LDAP server in order to look up the location
of mailboxes for local accounts (if the LDAP server is used by some other
application), simply remove authldap
from this configuration
file (and from other configuration files too - esmtpd
,
esmtpd-msa
, imapd
, and pop3d
).--without-authldap
option
for the configure
script, however if you want to install the
authldap module, but not use it right away, this is how you would do
it.authdaemon
authentication module was selected, then
the authmodulelist
configuration file must always specify
only the authdaemon
module, and the
authdaemonrc
configuration file will specify the real
authentication modules that are available.echo "qmail" >/usr/lib/courier/etc/dotextension
Run this command if you are installing Courier on a system that's
currently running the Qmail mail server. Courier will now read
.qmail
files for delivery instructions, instead of
.courier
files. Courier's .courier
files are mostly
compatible with Qmail's .qmail
files, but there are some minor
differences. Still, most of your .qmail
files should work
without too many problems.
The configuration file /usr/lib/courier/etc/locals
is a list
of all the domains that are considered local. Mail to any address in any
local domain is handled as a local delivery. If this file does not exist
Courier will use the contents of the me
configuration file, or
it will obtain its machine name from the operating system.
This file contains a list of domains, one per line. In most cases you need
to initialize this file to contain every hostname that has a DNS A, or AAAA,
record pointing to any IP address assigned to this machine, including
"localhost
". You will also need to include any domain that lists
this machine as its primary MX relay.
You may also include domain wildcards in locals
by prefixing
the domain with a period. For example: ".example.com" will treat any domain
underneath example.com
- like a.example.com
,
b.example.com
- as a local domain. Note that this does not
include example.com
itself, so you may need to list it
explicitly as well!
NOTE: The makealiases
command must be entered after
making any changes to this file.
If you would like your server to function as a backup mail relay for other
domains, create /usr/lib/courier/etc/esmtpacceptmailfor
. This is
a plain text file, containing a list of domains, one per line. This file
lists all domains your server will accept mail for. NOTE: if you create this
file, you MUST include all your local domains. Usually you can simply append
what you have in /usr/lib/courier/etc/locals
. If
/usr/lib/courier/etc/esmtpacceptmailfor
does not exist, Courier
will accept mail only for the machine name listed in
/usr/lib/courier/etc/me
, (or the system machine name).
Like /usr/lib/courier/etc/locals
, prepending a period to a
domain name in esmtpacceptmailfor
will cause Courier to accept
mail for all subdomains of this domain.
Courier is capable of sending and receiving mail via UUCP. Courier does not implement UUCP directly, but instead uses your existing UUCP software to send and receive mail.
Courier's UUCP functionality has been tested with Taylor UUCP 1.06. It's likely that some minor tweaking will be necessary to get Courier working with other UUCP builds. Give it a shot, and keep an eye out for problems.
/usr/lib/courier/etc/uucpme
/usr/lib/courier/etc/uucpneighbors
makeuucpneighbors
commands turns
this plain text file into a database, which is what Courier uses directly.
The format of the uucpneighbors
configuration file is described
in the makeuucpneighbors(8)
manual page.
/usr/lib/courier/etc/uuucprewriteheaders
Courier can accept mail addressed to
<user@example.com>
, and then forward it to
uucp!bang!path!user
, via UUCP. This is done by adding a UUCP
virtual domain alias to your aliases file, see "Create
system aliases". Append the following entry to your
/etc/aliases
, then run the makealiases
command:
@example.com: uucp!bang!path!
See the makealiases(8)
manual
page for more information.
In addition to using LDAP for authentication and for managing accounts, Courier can use an LDAP directory for routing, or "aliasing" mail.
The term "aliasing" refers to substituting one or more addresses for another address. A one-to-one substitution results in Courier accepting mail for one address, and delivering the mail to another address. A one-to-many substitution results in Courier accepting mail for one address, and delivering a separate copy of the message to every address defined by the alias.
Courier supports a basic form of aliasing using a GDBM or DB-based
database. The makealiases(8)
command reads a plain text file containing the aliasing rules, the creates a
GDBM or a DB database. Each recipient address is looked up in the database,
and if an alias is defined for the recipient address, it is used in place of
the original address. Aliasing can be used against individual addresses, one
by one. An extended form of aliasing maps an entire domain to a single local
address, using dot-courier(5)
delivery instruction files.
Courier can use an LDAP directory instead of a GDBM or a DB database, to
perform essentially the same function. If OpenLDAP is available at time of
installation, the installation script installs the courierldapaliasd(8)
program
and a ldapaliasrc
configuration file. It will be necessary to
enter appropriate information into ldapaliasrc, and arrange to run
"courierldapaliasd start
" at system boot time (it is a
background daemon process that opens persistent connections to the LDAP
server).
Additional instructions for setting up LDAP-based aliasing are found in
the courierldapaliasd(8)
manual page.
Courier includes several options for selectively filtering mail. In general, Courier provides only the plug-in interfaces by which arbitrary external mail filters can be used to selectively accept or reject messages. Courier comes only with some sample code that demonstrates how to write a mail filter. An actual mail filter must be written and installed separately. Please note that running mail filters can have a non-trivial impact on mail system performance and throughput.
Courier provides two mail filtering interfaces:
maildrop
mail filter. With the local
mail filtering installed, individual recipients can create files
containing mail filtering instructions that can selectively accept or
reject individual messages.See courierfilter(8)
for
more information on global mail filters.
See maildropfilter(7)
for
more information on local mail filters.
Courier sends UUCP mail by running rmail
via
uux
. The configuration script searches for the uux
command in the default search path. If your uux
command is not
in a directory that's in your search path you will have to modify
PATH
before running configure.
Courier receives UUCP mail by expecting your UUCP software to run the
rmail
command, which is installed in
/usr/lib/courier/bin
. (It's actually a soft link to
sendmail
, but we'll talk about it later). Your UUCP software
probably does not run commands from this directory by default, so you will
have to make the necessary adjustments. You can always create another soft
link in a directory that UUCP searches by default.
To start Courier, run the command /usr/lib/courier/sbin/courier
start
. To stop Courier, run the command
/usr/lib/courier/sbin/courier stop
. See the
courier(8)
manual page for more information.
You should add these commands to your system startup and shutdown scripts.
Note that this command starts and stops Courier's core processes only. It does not start any additional daemon processes that you may need, such as the mail filtering daemon, the ESMTP server daemon, the POP3 server daemon, or the IMAP server daemon.
The commands courierfilter start
, courierfilter
stop
, esmtpd start
, esmtpd stop
,
esmtpd-msa start
, esmtpd-msa stop
, pop3d
start
, pop3d stop
, imapd start
, and
imapd stop
(all commands are installed in the sbin directory)
are used to start or stop their respective daemons, and they should be added
to your system startup and shutdown scripts, where required. As described in
the relevant manual pages, courierfilter
should be the first
daemon process to start, and the last one to terminate. The remaining daemons
may be started in any order.
When the authdaemon
authentication module is used, the
authdaemond start
and authdaemond stop
commands
must also be added to your system scripts. No mail will be processed without
authdaemond
running.
You now have several options for migrating from your existing mail server to Courier:
/usr/lib/courier/bin/sendmail
to send mail, instead of your
current sendmail program./usr/lib/courier/sbin/esmtpd start
from your system start up script. You should also add
/usr/lib/courier/sbin/esmtpd stop
to your system shutdown
script. Note that there's a separate script that starts the ESMTP
submission server on port 587 -
/usr/lib/courier/sbin/esmtpd-msa
, that is used in an
analogous fashion.
Courier supports authenticated ESMTP in order to grant ESMTP relaying privileges to remote users. The following steps set up authenticated ESMTP:
/usr/lib/courier/etc/esmtpd
and uncomment the
AUTHMODULES
and ESMTPAUTH
variables. The
configuration file /usr/lib/courier/etc/esmtpd-msa
is used
for the ESMTP submission server on port 587. Setting these variables in
esmtpd
is sufficient, because esmtpd-msa
merely
supplements the settings in esmtpd
. Explicitly initialize
these settings in esmtpd-msa
only if you wish to apply them
to port 587 only.
AUTHMODULES
is a list of Courier authentication modules
that you want to use. See configure reference
for more information on authentication modules. ESMTPAUTH
is
a list of SASL authentication methods you will use. Currently, Courier
supports LOGIN
and CRAM-MD5
.
CRAM-SHA1
is also implemented on experimental basis.
CRAM-MD5/SHA1
is not implemented in every authentication
module. The authentication modules that support CRAM-MD5/SHA1
authentication are: authcram
(this is the CRAM-MD5/SHA1
version of authuserdb
, use authcram
for
CRAM-MD5/SHA1 and use authuserdb
for LOGIN),
authldap
, and authmysql
.
authpam
-
the PAM authentication module - requires that you also configure your PAM
library. In this case, you need to configure your PAM library to support
the "esmtp" service. The PAM library configuration details depend on your
particular operating system, and are beyond the scope of this document.
Consult the documentation for your PAM library for more information.Courier also supports ESMTP over TLS/SSL, by using the ESMTP STARTTLS extension:
http://www.openssl.org/
. Follow
the instructions provided with OpenSSL to install it. STARTTLS has been
tested with OpenSSL 0.9.5a./usr/lib/courier/share/esmtpd.pem
. If this file exists, the
STARTTLS ESMTP extension will be automatically advertised. This file must
be owned by the userid Courier is installed as, and MUST NOT be world
readable!/usr/lib/courier/share/esmtpd.pem
. This file MUST NOT
HAVE any group or world permissions! It must be owned by the Courier
userid (the userid used to install Courier, usually courier
or daemon
)./usr/lib/courier/sbin/mkesmtpdcert
can be used to generate
/usr/lib/courier/share/esmtpd.pem
. This script will silently
terminate if OpenSSL is not installed, or if the esmtpd.pem certificate
file already exists (so it will not be overwritten). This makes it easier
to have this script invoked from a package install script.Courier will also use TLS/SSL when sending ESMTP mail, automatically. If the remote mail server support STARTTLS, Courier will use it automatically.
SSL/TLS settings for the ESMTP client can be adjusted in the
/usr/lib/courier/etc/courierd
configuration file. When sending
mail using SSL, Courier can optionally verify the remote server's X.509
certificate. This is done by setting ESMTP_TLS_VERIFY_DOMAIN
to
1
, in /usr/lib/courier/etc/courierd
. Also,
TLS_PEERCERTDIR
must be set to a directory that contains PEM
files of X.509 certificates of trusted root certificate authorities. The PEM
files must be hashed by OpenSSL's c_rehash
script. When this is
done, the remote server's X.509 certificate must signed by trusted root CA,
else Courier will bounce the recipient.
Starting with version 0.34, Courier installs a default set of trusted
public certificate authorities, and the default configuration will require
the remote server to present an X.509 certificate that's signed by any
trusted certificate authority. To disable certificate validation, set
ESMTP_TLS_VERIFY_DOMAIN to 0 in /usr/lib/courier/etc/courierd
.
Alternatively, custom certificates may be installed instead. The
TLS_TRUSTCERTS setting in /usr/lib/courier/etc/courierd
specifies the location of trusted certificate authorities.
Courier includes an experimental extension to ESMTP that can be used to set up secure E-mail delivery between trusted mail relays over an untrusted network. This is implemented by an experimental ESMTP extension in Courier. Therefore, at present time both the sending and the receiving mail relay must be running Courier that's configured to support this extension. The specification for this ESMTP extension is publicly available. This is a very small extension of the existing, draft-standard STARTTLS ESMTP extension. The SECURITY extension should only require minor changes to existing mail servers and clients that already implement STARTTLS.
The first necessary step is to read the formal definition of the SECURITY extension, which can be found on http://www.courier-mta.org. Although the following instructions do not use any information directly from this document, it is important to understandi how this mechanism works. This will be very useful in troubleshooting. This is not called an "experimental" extension just for the hell of it.
The SECURITY extension builds on top of several existing, proven, technologies in order to deliver mail with the highest level of security that can possibly be implemented using the existing technology. The several steps in implementing the SECURITY extension:
The SECURITY extension is an optional tag that's attached to an E-mail message. Courier requires STARTTLS to forward SECURITY-tagged messages, and the receiving mail nodes must present an X.509 certificate, signed by the private Certificate Authority, before Courier will send the message. Courier will refuse to send the message to a mail node that does not support STARTTLS, or doesn't present a suitable X.509 certificate.
Therefore, in an ideal world, mail clients will simply tag messages with the SECURITY extension. Obviously, this means that mail clients must be updated to implement this feature. Until this happens, Courier will provide a workaround that automatically tags all messages for selected domains with the SECURITY extension. This is not a perfect solution, and it has some minor limitations, which will be mentioned later.
Create an empty subdirectory:
mkdir /etc/myca cd /etc/myca
There's a convenient OpenSSL script called CA.pl
that you
want to copy to the current directory:
cp /usr/share/ssl/misc/CA.pl .
Your OpenSSL package may have CA.pl
installed someplace else.
Find it, and copy it to /etc/myca
. The CA.pl
needs
to be slightly modified before it can be used. Find the following commands in
CA.pl
, and change them as follows:
Replace:
system ("$REQ -new -keyout newreq.pem -out newreq.pem $DAYS");
replace with:
system ("$REQ -new -nodes -keyout newreq.pem -out newreq.pem $DAYS");
Also replace:
system ("$REQ -new -x509 -keyout " . "${CATOP}/private/$CAKEY -out ${CATOP}/$CACERT $DAYS");
replace with:
system ("$REQ -new -nodes -x509 -keyout " . "${CATOP}/private/$CAKEY -out ${CATOP}/$CACERT $DAYS");
The CA.pl
script creates password-protected certificate keys
by default. Password protected certificates currently do not work with
Courier. Adding the -nodes
parameter turns off password
protection. This means that it is vital to make sure that the trusted mail
relays are properly secured. All the encryption in the world will not be of
much use if the mail relays are running a rootable FTP server (for example).
Anyway, run CA.pl
to create a new certificate authority:
./CA.pl -newca
CA.pl
prompts for a basic description of the new CA, then
creates the certificate and the certificate key. The CA's root certificate is
saved in /etc/myca/demoCA/cacert.pem
.
This step must be performed to create the X.509 certificates for every mail node in the trusted secure network. First, a certificate request is created:
./CA.pl -newreq
CA.pl
prompts for a basic description of the new certificate.
Special care must be paid to the "commonName" setting. "commonName" MUST be
set to the hostname of the trusted mail node, NOT its mail domain. For
example, given the following DNS setup for example.com
:
example.com. MX 10 mx1.example.com. example.com. MX 20 mx2.example.com. mx1.example.com. A 192.68.0.1 mx2.example.com. A 192.68.1.1
This domain will need two certificates, one with "commonName" set to "mx1.example.com", and one with "commonName" set to mx2.example.com.
Running ./CA.pl
produces a certificate request in the file
newreq.pem
. Run the following command to sign it:
./CA.pl -signreq
This step creates the file newcert.pem
that contains a new
signed certificate. The private key from the original certificate request
must be appended to this file, before the certificate can be used. Simply
take the newreq.pem
file from the previous step, and append the
private key in that file to newcert.pem
. The resulting
certificate file should look something like this:
[ description of the certificate ] -----BEGIN CERTIFICATE----- [ binary goo ] -----END CERTIFICATE----- -----BEGIN RSA PRIVATE KEY----- [ binary goo ] -----END RSA PRIVATE KEY-----
The OpenSSL documentation contains instructions on how to perform the equivalent procedure with Diffie-Hellman instead of RSA.
Two files must be installed on every trusted mail node.
newcert.pem
file from the
previous step. The following documentation assumes that this file is
installed as /etc/mycert.pem
. This mail node will use this
certificate to authenticate itself to other trusted mail nodes.cacert.pem
. The following
documentation assumes that it's installed as
/etc/cacert.pem
. The CA's certificate is used to
authenticate other trusted mail nodes.Edit the /usr/lib/courier/etc/esmtpd
configuration file. Set
TLS_CERTFILE
to /etc/mycert.pem
. Courier will use
TLS_CERTFILE
to authenticate itself to other trusted mail
nodes.
Edit the /usr/lib/courier/etc/courierd
configuration file.
Set TLS_TRUSTSECURITYCERTS
to /etc/cacert.pem
.
Courier will not send ESMTP mail tagged with the SECURITY extension to other
mail relays unless they produce a certificate that's signed by
TLS_TRUSTSECURITYCERTS
.
The following simple steps can be carried out to verify that everything is
working correctly. These examples use two mail nodes called
send.example.com
and receive.example.com
. The test
messages are sent from send.example.com
, and are addressed to
receive.example.com
. Courier must be restarted on both
send
and receive
, after reconfiguring the machines
for each test. It is not strictly necessary to do this every time, actually,
but it's simply easier to do make it a part of the routine. It is necessary
to restart both the main Courier daemon processes as well as the separate
ESMTP daemon process (on receive
):
courier stop courier start esmtpd stop esmtpd start
/usr/lib/courier/bin/couriertls
wrapper on receive.example.com
. Rename it to
couriertls.save
. STARTTLS
is automatically
disabled if couriertls
is missing,send.example.com
:
echo "To: postmaster" | /usr/lib/courier/bin/sendmail \ -S STARTTLS postmaster@receive.example.com
This message should bounce back since receive
has
STARTTLS disabled.
couriertls
on receive.example.com
,
but then rename it on send.example.com
. The situation is now
reversed, and the test message should still bounce.couriertls
on send.example.com
. Edit
receive
's /usr/lib/courier/etc/esmtpd
file.
Comment out the current TLS_CERTFILE
setting (which points
to the private CA certificate). Reset TLS_CERTFILE
to
/usr/lib/courier/share/esmtpd.pem
, which is the self-signed
test certificate created by the mkesmtpdcert
script, when
STARTTLS support in Courier was first set up.
Send a test message WITHOUT the "-S STARTTLS" option. This
message should go through, assuming all the other setting in all
configuration files are the initial defaults. The regular ESMTP STARTTLS
extension, without authentication, will be used the deliver this message.
Verify this by checking the headers in the received message on
receive.example.com
.
Send a test message WITH the "-S STARTTLS" option. It should
bounce, even though receive.example.com
supports STARTTLS.
That's because it is using an X.509 certificate that's not signed by the
private CA authority.
TLS_CERTFILE
on receive
, and send a
test message with the -S STARTTLS
option, which should now
go through.As demonstrated by the test messages, messages must be tagged with the
SECURITY
extension in order for them to be securely transmitted.
This must be done by the sending mail client. Until mail clients support
SECURITY
Courier can automatically add the SECURITY
tag to every message addressed to a domain. This is done by entering the
domain in the esmtproutes
configuration file using the following
syntax:
receive.example.com: /SECURITY=STARTTLS
Repeat the tests in the previous section, but this time add and delete
this entry in /usr/lib/courier/etc/esmtproutes
instead of using
the -S STARTTLS
option. The test messages must still bounce or
not bounce in the same way.
Consult the courier(8)
manual page
for more information on the esmtproutes
configuration file.
This setup makes it virtually impossible to intercept mail traffic between trusted mail nodes. Even if the DNS cache is poisoned to intercept mail to a hostile mail node, mail will not go through since the attacker will not have a signed X.509 cert. However, all is lost if the mail nodes themselves are compromised directly. After securing the compromised node, everything must be rebuilt. A new CA must be created, and all mail nodes must now receive new certificates. Once support for certificate revocation lists is improved, this situation will get somewhat better.
Another possible way to mitigate that possibility is to use a different
certificate authority for every trusted mail node.
TLS_TRUSTSECURITYCERTS
can point to a directory, instead of a
file. This directory can contain multiple certificate authorities (hashed by
OpenSSL's c_rehash
script). Then, only the compromised mail
node's authority certificate needs to be tossed out, regenerated, and
redistributed.
TODO: it may be possible to avoid generating individual certificates, and distribute self-signed certificate authority certs only, with a properly-initialized commonName field. This needs to be researched.
There are some minor differences between using -S STARTTLS
versus putting the domain into esmtproutes
. If the
sending mail node forward mail to this domain via UUCP, -S
STARTTLS
will bounce. Since esmtproutes
does not apply to
UUCP, putting this domain in esmtproutes
will have no effect
whatsoever.
Courier includes an integrated IMAP server. The following steps set it up:
/usr/lib/courier/etc/imapd
. If you want to use IMAP
SASL authentication, uncomment the AUTHMODULES
and
IMAP_CAPABILITY
variables. They perform the equivalent
function as the corresponding variables in the esmtpd
configuration file, except that IMAP_CAPABILITY
also sets
several other IMAP capabilities that are advertised to IMAP clients.
Also, for IMAP, CRAM-MD5/SHA1 authentication has been tested, and is
known to work, so it is listed as a default. Also, note than if the
authpam
authentication module is used, you will need to
configure the "imap" PAM service. Other authentication modules have their
own requirements too./etc/inetd.conf
, and restart the
inetd
daemon./usr/lib/courier/sbin/imapd start
Of course, add /usr/lib/courier/sbin/imapd stop
to your
shutdown script too.
NOTE: if you have previously installed the stand-alone version of the Courier-IMAP server, you will need to remove it prior to using the directly integrated version. They use the same base source code, but have a slightly different configuration.
NOTE: this IMAP server supports maildirs only. It does not support mbox file mailboxes.
The IMAP server can sort and search messages using other than the default
us-ascii/iso-8859-1 character set. You can find the list of available
character sets in the file unicode/charsetlist.txt
.
The default configuration includes only the ISO-8859-1/US-ASCII character
set. Use the --enable-unicode
option to include all character
sets.
If the configure
scripts finds that GnuPG 1.0.5 is installed,
the configure
script will also add the utf-8 character set to
the default setting.
It is also possible to include translation tables only for selected character sets. Example:
--enable-unicode=iso-8859-1,utf-8,iso-8859-10
Technically, IMAP servers must support the UTF-8 character set, however few IMAP clients (I've yet to see one, actually) care about UTF-8, so the UTF-8 character set is optional in Courier-IMAP. The only required character set - which is always included, explicitly or implicitly - is ISO-8859-1/US-ASCII.
The utf-8 character set MUST be included if GnuPG 1.0.5 is installed (see "Configure encryption for the webmail server" for more information).
Note that character set translation tables take up additional memory. This
should not be a problem in most cases. Most compilers place the read-only
character set tables into a shared text segment, which is shared by all
running server instances. Using --enable-unicode
should not
really be much of a burden for most modern operating systems.
Attentive individuals will observe that all character set tables are
compiled even without the --enable-unicode option
. That is
normal -- only the explicitly selected character set tables will actually
make it into the final executable.
It is possible to share folders between different mailboxes, via IMAP. See
the file maildir/README.sharedfolders.(txt|html)
for more
information.
To implement IMAP over SSL you will need to separately obtain and install
OpenSSL. Download OpenSSL from http://www.openssl.org/
.
Follow the instructions in the OpenSSL package to install it and configure
it. IMAP over SSL has been tested with OpenSSL 0.9.5a.
The /usr/lib/courier/etc/imapd-ssl
configuration file sets
some additional options for OpenSSL, which you may need to adjust.
Consult that configuration file for additional information. Then, you also
have to run the /usr/lib/courier/sbin/imapd-ssl
script from your
system startup and shutdown scripts, just like the
/usr/lib/courier/sbin/imapd
script. You may accept both SSL and
non-SSL connections by running both scripts.
Note that SSL requires a valid, signed, X.509 certificate to be installed
where Courier expects to find it. The default location for the X.509
certificate, in PEM format, is /usr/lib/courier/share/imapd.pem
.
The X.509 certificate must be signed by a certificate authority that is known
to the IMAP client. You can generate your own self-signed certificate by
running the script /usr/lib/courier/share/mkimapdcert
which will
work too, except that IMAP clients using SSL will display a warning message
the first time they connect to the server. To get rid of the warning message
you'll have to pay for a signed X.509 certificate. The gory details of
setting up SSL is beyond the scope of this document, and you should consult
the OpenSSL documentation for more information.
The mkimapdcert
script will not overwrite an existing
imapd.pem
certificate, in order to allow precompiled packages to
simply call mkimapdcert
after installation, without worry.
The IMAP server also supports the IMAP STARTTLS extension as an
alternative or a complement to IMAP over SSL. The
/usr/lib/courier/etc/imapd-ssl
configuration file is also used
to enable or disable IMAP STARTTLS, which has all the same requirements and
prerequisites as IMAP over SSL.
This server allows using the IMAP connection to send E-mail. Normally, the IMAP protocol provides only access to mail in an existing mail account, and mail clients must use SMTP in order to send mail. The Courier-IMAP server has an optional setting to enable mail to be send via an IMAP connection in a manner that should work with all existing IMAP mail clients. This can be useful when an account is logged in from a shared access pool which normally blocks most access to the SMTP port.
This is implemented by enabling a setting in the imapd
configuration file that designates a folder as a special "Outbox" folder. The
default setting is a folder called "Outbox" (IMAP path INBOX.Outbox), but the
name can be changed to anything. This folder, for the most part, is no
different than any other folder. If a folder by that name doesn't exist, it
needs to be created, just like any other IMAP folder. It looks and acts like
any other folder, except that each message added to the folder, via IMAP's
APPEND or COPY command, will also be mailed out by the Courier-IMAP server to
the addresses listed in the To:
, Cc:
, and
Bcc:
headers.
It should be possible to use this to send mail from any IMAP client by:
NOTE: it is tempting to configure the IMAP mail client to use Outbox as its default folder for saving drafts. Resist the temptation. If you forget, you'll save a partially completed draft, which will be then obediently mailed out.
NOTE: the message, in addition to being sent, will be saved in the folder in the normal fashion. After saving the message, reopen the Outbox folder and delete the sent message, or move it someplace else.
NOTE: when enabled, the Courier-IMAP server will advertize a private
XCOURIEROUTBOX
IMAP capability. It is theoretically possible to code an IMAP mail client that reads this capability and automatically configures itself accordingly -- when this IMAP capability is present -- to send E-mail in the normal way but using the IMAP connection. At this time, I'm not aware of any actual mail clients that know how to do this.
NOTE: many mail clients save some additional internal information in headers of draft messages. The internal information is normally removed before the mail client sends the message. Make sure that none of this extra information is something that should not be mailed out.
If the FAM, the File Alteration Monitor (http://oss.sgi.com/projects/fam/) is installed it will be possible to allow multiple clients to open the same folder, and have all clients to be simultaneously notified of any changes to the folder contents.
After installing the server see the imapd(8) manual page for more information.
Starting with Courier 0.43, the IMAP server supports an experimental mail
access protocol, dubbed "Simple Mail Access Protocol". SMAP is an experiment
to provide enhanced mail processing beyond what's currently possible with
IMAP. SMAP's purpose is to prototype and develop advanced mail access
functionality that's not possible with IMAP. SMAP is disabled by default.
Uncomment the SMAP_CAPABILITY
setting in the imapd
configuration file in order to enable SMAP. The Cone mail client
supports SMAP.
Courier includes an integrated POP3 server. The following steps will set it up:
/usr/lib/courier/etc/pop3d
. Very few POP3 clients
support POP3 SASL authentication, but if you want to use it, for some
reason, uncomment the AUTHMODULES
and POP3AUTH
variables. They perform the equivalent function as the corresponding
variables in the esmtpd
and imapd
configuration
files. For POP3, SASL LOGIN authentication has been tested, and is known
to work, and CRAM-MD5/SHA1 has not been tested. Also, note than if
authpam
is used, you will need to configure the "pop3" PAM
service. Other authentication modules have their own requirements./etc/inetd.conf
, and restart the
inetd
daemon./usr/lib/courier/sbin/pop3d start
Of course, add /usr/lib/courier/sbin/pop3d stop
to your
shutdown script too.
NOTE: this POP3 server supports maildirs only. It does not support mbox file mailboxes.
Implementing POP3 over SSL is very similar to implementing IMAP over SSL.
The only differences are that the startup/shutdown command is
"/usr/lib/courier/sbin/pop3d start
" and
"/usr/lib/courier/sbin/pop3d stop
", the configuration file is
/usr/lib/courier/etc/pop3d
, the name of the required SSL
certificate is /usr/lib/courier/share/pop3d.pem
, and the command
to generate a test SSL certificate is mkpop3dcert
.
The integrated webmail server is made up of two parts. The first part, by
default, is installed as
/usr/lib/courier/libexec/courier/webmail
. You can simply copy
this binary executable to your web server's cgi-bin
directory,
or create a link from the cgi-bin directory to this program. This is a small
stub program that connects, via a local socket, to the
sqwebmaild
daemon process, which implements the webmail service.
It is necessary to start the webmail server by adding the following command
to the system startup screen (so that the webmail server gets automatically
started at boot):
/usr/lib/courier/libexec/courier/sqwebmaild start
(It is also possible to run "sqwebmaild stop
" from the system
shutdown script in order to shut down webmail service gracefully).
sqwebmaild
uses the authentication modules listed in
/usr/lib/courier/etc/authmodulelist
(or
/usr/lib/courier/etc/authdaemonrc
if the authentication daemon
is used).
Note that the webmail server is used to access mail in existing accounts only. There is no provision to create accounts through the webmail interface (nor there should be).
Your web server also needs to be configured to use HTTP/1.0 when talking to any MSIE browser. The MSIE browser has a number of bugs in its HTTP/1.1 implementation, at least as of MSIE 4.x and 5.x. You must configure your web server to use HTTP/1.0 when talking to any MSIE browser (at least until MSIE gets fixed). The problem has to do with downloading attachments. Apparently, MSIE forgets how MIME works, when it uses HTTP/1.1. For the Apache server, insert the following directive in httpd.conf:
BrowserMatch "MSIE" nokeepalive downgrade-1.0 force-response-1.0
Recent versions of Apache already have a similar directive for a specific version of MSIE, MSIE 4.0b2. Just replace it with a browsermatch for any MSIE version.
Most IMAP clients use a Unicode-based encoding method called "modified
UTF7" in order to represent names of folders that contain 8-bit characters.
If there will not be any IMAP access to the mail accounts in question,
there's no need to include all this baggage. The option
--disable-utf7-folder-encoding
to the configure script will turn
this off.
There are a few IMAP clients that do not use modified UTF7 to encode
folder names. The option --disable-utf7-folder-encoding
can be
used if that is the case. It is currently not possible to support both UTF7
and non-UTF7 clients at the same time.
By default, the configure
script works like this. It takes
the character set used for the HTML templates, and loads the Unicode mappings
just for that character set. By default, Courier's webmail server is
distributed with a default set of HTML templates that use the iso-8859-1
character set. If you are installing a modified derivative that includes
additional templates, the configure
script will pick up any
additional character sets used by those templates.
Sometimes it is useful to include additional unicode tables. The list of
available unicode tables can be found in
unicode/charsetlist.txt
. This is useful when there are
alternative encodings for the same base character set, like KOI8-R and
IBM866. The option "--enable-unicode=koi8-r,ibm866
", when used
with koi8-r HTML templates, will allow the webmail server to display
ibm866-encoded E-mail using the koi8-r character set (and vice versa). Note,
for this to work you will need to install a set of KOI8-R HTML templates. In
a pinch, you can simply edit webmail/html/en/CHARSET
.
The webmail server can use either the ispell or the aspell package for spell checking. Install ispell or aspell before installing Courier.
NOTE: Courier assumes that the spell checking dictionary is called
"english". Some systems use a different name for the default spell checking
dictionary. To change the name of the spell checking dictionary used by the
webmail server, put the name of the dictionary into the file
/usr/lib/courier/share/sqwebmail/html/en-us/ISPELLDICT
.
It is also necessary to install the static icon images used by the webmail
server. The installation script copies the static images to the
/usr/lib/courier/share/sqwebmail/images
directory. By default,
the webmail server uses the URL "/webmail/
" to specify the
location of the static images, for example:
/webmail/folders.gif
. This means that you must create a
subdirectory called "webmail
" in your web server's document root
- typically /usr/local/etc/apache/htdocs/webmail
, or
/usr/local/www/htdocs/webmail
, or something similar. You will
need to determine the actual location of your web root directory, which
varies from system to system. Then, create a subdirectory named
"webmail
", and copy all the icons to that directory.
Another possibility is to install a soft link, instead of creating the
webmail
sub directory, and point the soft link to
/usr/lib/courier/share/sqwebmail/images
(you also must make sure
that the web server is configured to follow symlinks).
There is a configuration option, --enable-imageurl
, that can
be used to use something other than /webmail/
as the URL prefix
for images.
The file
/usr/lib/courier/share/sqwebmail/html/en-us/TIMEZONELIST
contains a list of alternative timezones. By default all dates and times are
shown in the server's default timezone, and the dropdown list on the login
screen can be used to select an alternative timezone. The default alternative
timezone list that lists only a small number of timezones. Additional
timezones can be entered into this file to be shown on the login web page.
The webmail server can import E-mail addresses from public LDAP address books into an individual address book. A default systemwide list of accessible LDAP address books is defined for everyone, and individuals can configure additional LDAP address books for themselves.
OpenLDAP runtime libraries and tools are required to be installed in order
to search LDAP address books. It is not necessary to have OpenLDAP
development libraries installed. The webmail server simply runs the
ldapsearch
tool to query LDAP address books, and parses the
results.
The default list of systemwide-accessible LDAP address book is defined in
the ldapaddressbook
configuration file. See courier(8) for more information.
The webmail server runs
/usr/lib/courier/share/sqwebmail/ldapsearch
to search an
external LDAP address book. This is a wrapper shell script that calls
OpenLDAP's ldapsearch
tool. The configuration script attempts to
find the location of where OpenLDAP tools are installed. The path to
ldapsearch
in this shell script should be verified and fixed, if
necessary. The default shell script adds some additional options to
ldapsearch
to limit the search time to sixty seconds, and to
return a maximum of twenty entries from the address book.
Optional calendaring services can be enabled in the webmail server. Right
now, the current implementation provides basic calendaring services. For more
information on calendaring, see the file pcp/README.html
.
A login session is automatically logged out after certain period of
inactivity. The timeout period defaults to 20 minutes, and is set by the
--enable-softtimeout
option to the configure script. It is also
possible to adjust this value by setting the
SQWEBMAIL_TIMEOUTSOFT
environment variable. For example, with
Apache, by adding the following to httpd.conf
:
SetEnv SQWEBMAIL_TIMEOUTSOFT 3600
There is also a hard timeout, which logs out a session no matter what. The
default of two hours is changed with the --enable-hardtimeout
option to the configure script, and the SQWEBMAIL_TIMEOUTHARD
environment variable.
WARNING:
The hard timeout interval is used to calculate the maintenance of the
login cache (if that option is selected). This factor is used in the
cleancache.pl
cleanup script, and changes to this value must be
coordinated appropriately. It is not possible to use different hard timeout
values with the same login cache (in different virtual domains, as described
in the next session). Leisurely tinkering with this environment variable is
STRONGLY DISCOURAGED, it's very easy to screw up the whole system. You've
been warned.
If you adjust the hard timeout, you must simultaneously delete your
current login cache directory, and adjust $timeouthard in the installed
cleancache.pl
script.
The default set of templates for the dynamically generated HTML is
installed in /usr/local/share/sqwebmail/html
. When the same
server is used to provide webmail access for multiple domains it is possible
to specify a different set of HTML templates for each domain.
This functionality is not directly implemented in SqWebMail, simply because there is no standard way to specify this. Instead, this is something that will need some minor work set up.
Domain-based templates are implemented by making the web server set the
environment variables SQWEBMAIL_TEMPLATEDIR
prior to running the
sqwebmail
binary. The contents of this environment variable
override the default location of
/usr/local/share/sqwebmail/html
. By having the web server
initialize this variable based on the domain name it is possible to present
different templates, based on the domain name used.
To do this, make copies of the HTML template directory,
/usr/local/share/sqwebmail/html. Then, configure the web server to
initialize
SQWEBMAIL_TEMPLATEDIR
appropriately. For example,
with Apache:
<VirtualHost a.b.c.d> ServerName webmail.example.com [...] SetEnv SQWEBMAIL_TEMPLATEDIR /usr/local/share/webmail/webmail.example.com [...] </VirtualHost>The possibilities are endless.
It is now possible to display two or more templates from the same CGI binary WITHOUT setting up multiple domain names.
For example, with Name-based templates an sqwebmail administrator can set
up sqwebmail to display a template in the
/usr/local/share/sqwebmail/html
directory when sqwebmail is
called from the URL: http://www.foo.com/cgi-bin/sqwebmail
And display a different template in the
/usr/local/share/sqwebmail/alternate-html
directory when
sqwebmail is called from the URL:
http://www.foo.com/cgi-bin/sqwebmail-alt-template
This is made possible by a little web server magic (explained below in the section entitled "Apache Name-based template configuration example") and the setting of TWO sqwebmail environment variables:
SQWEBMAIL_TEMPLATEDIR
SQWEBMAIL_IMAGEURL
You should recognize the SQWEBMAIL_TEMPLATEDIR environment variable from the section above on Domain-based templates. If you haven't read that section yet, please do so now.
The SQWEBMAIL_IMAGEURL environment variable is new in versions of sqwebmail greater than sqwebmail-3.5.3.20030629. It allows us to set, at run time, the image URL, or the root URL, in which to look for our template's images. This image URL is then automatically inserted into the current template anytime a conditional image tag or an IMAGEURL tag is encountered.
This is an example of a conditional image tag:
[#@image.gif, ... @text@#]
The conditional image tag is replaced at template processing time with an HTML <img src="..."> tag if (hence the word "conditional") sqwebmail is set up to display images.
This is an example of an IMAGEURL tag:
[#IMAGEURL#]
The IMAGEURL
tag is replaced at template processing time with
the contents of the SQWEBMAIL_IMAGEURL
environment variable, if
set, and otherwise with the value of the --with-imageurl
configure option, which defaults to "/webmail
".
Let's take a look at a simple Apache Name-based sqwebmail template configuration example:
# Sqwebmail Alternate Template URL ScriptAlias /cgi-bin/sqwebmail-alt-template "/usr/local/apache/cgi-bin/sqwebmail" <Location /cgi-bin/sqwebmail-alt-template> Setenv SQWEBMAIL_TEMPLATEDIR "/usr/local/share/sqwebmail/alternate-template" Setenv SQWEBMAIL_IMAGEURL "/alternate-webmail" [...] </Location>
The above should allow your users to run sqwebmail with the template in
/usr/local/share/sqwebmail/alternate-template
and an image URL
of /alternate-webmail
, simply by calling sqwebmail from the
following URL:
http://www.yourdomain.com/cgi-bin/sqwebmail-alt-template
The original sqwebmail templates would then still be available from this URL:
http://www.yourdomain.com/cgi-bin/sqwebmail
Using Apache's <Location> directive we can utilize a virtually unlimited number of templates without setting up a single virtual domain.
This is an optional feature where the webmail server is used to automatically set up mail filtering rules to forward or deliver incoming mail to folders. This feature requires maildrop to be used as the local mail delivery agent.
Edit the courierd
configuration file, and follow the
instructions in that file to install maildrop
as the local mail
delivery agent. Then, follow the instruction below to create the
maildirfilter
configuration file, which may be installed either
in the global configuration file directory (/usr/lib/courier/etc
by default), or in each individual Maildir (which overrides the global
default).
Implementing mail filtering requires a couple of dominos to fall in the right order. This is not difficult to do, but is a bit tricky. Here's how it works, in general. Specifics follow.
Some people would probably have a difficult time setting it up. That's to be expected. The implementation allows only selected accounts to be set up for mail filtering, so the suggested way is to attempt to set up mail filtering for one account only, test it to make sure it works, then roll it out globally.
The maildrop mail filter is used to do the actual mail filtering. maildrop must be installed as your local mail delivery agent. The next thing to do is to actually learn how maildrop works, and learn its filtering language. Although the mail filter will be automaticaly generated here, you still need to become familiar with the filtering language in order to troubleshoot any installation problems. maildrop comes with manual pages documenting the filtering language, as well as some examples. Read them.
Here's what's going to happen. The webmail server will automatically generate a maildrop filtering recipe. maildrop reads the recipe, and does its thing. Sounds simple enough, right?
Well, it's not. There are a few little details that need to be resolved.
For starters, the default maildrop filtering recipe is
$HOME/.mailfilter
. That's how things usually work physical
system accounts are used. When virtual mailboxes are installed, things are
less murky. There are several ways to set up virtual mailboxes, described
elsewhere in this INSTALL file, so the actual implementation varies from
system to system. Somehow, the virtual mailboxes share the same physical
account, and have the same $HOME. In that case the usual approach is for each
virtual mailbox to have the corresponding mail filtering recipe manually
specified to maildrop as an extra command line argument. Review the
maildrop documentation for more information.
Now, on the other hand, the webmail server doesn't really know anything about physical and virtual accounts. The mapping between a login ID and the maildir is completely encapsulated in the black box-type authentication layer. The login ID and password are validated by the authentication layer, which obtains the maildir corresponding to the login ID, and the webmail server is started for that maildir. Whether or not a login ID corresponds to an actual system account or to virtual account, that's something the webmail server doesn't really know, or care. All it cares about is the maildir where all the mail is, and that's the end of the story. (The IMAP and POP3 servers work the same way).
So, the issue is that the webmail server needs to find the corresponding maildrop filtering recipe, so it knows where to write the mail delivery instructions. That's the deal
In order for mail filtering to be enabled, it is necessary to initialize
the file named maildirfilterconfig
in the maildir itself. This
is where the webmail server runs, so it simply reads this file. The contents
of this file should be as follows:
MAILDIRFILTER=pathtomailfilter MAILDIR=pathtomaildir
pathtomailfilter specifies the location of the maildrop filtering recipe for this maildir, relative to the maildir itself. Set the current directory to the maildir directory. Now ask yourself, where's my maildrop filtering recipe?
In most cases, where virtual mailboxes are not used, everyone's maildir is
$HOME/Maildir
, and maildrop uses
$HOME/.mailfilter
by default. In this case,
pathtomailfilter must be set to ../.mailfilter
.
When virtual mail accounts are used, this will obviously be something else. The only requirement is that the maildrop filtering recipe and the maildir must be on the same filesystem or partition.
pathtomaildir is the other half of the story. When maildrop
gets a message to deliver, maildrop needs to know where the mailboxes
and folders are. Maildrop begins running in what it considers to be
the recipient's home directory, reading either .mailfilter
, by
default, or the file specified on the command line.
The webmail server needs to generate filtering instruction that deliver
messages to its maildir. By default, the maildir for non-virtual accounts is
$HOME/Maildir, so pathtomaildir needs to be set to
./Maildir
.
Basically, 99% of the time MAILDIRFILTER
will be
../.mailfilter
and MAILDIR
will be
./Maildir
. When virtual mail accounts are used, maildrop
still must be used as a mail delivery agent. Somehow, the correct maildir
that corresponds to the recipient's mail account must be specified as the
argument to maildrop. Usually all or most virtual accounts are set up
inside a single physical account. In that case it is necessary to set up a
different maildrop filtering recipe file for each virtual mail account
(since everyone's $HOME/.mailfilter
will be the same file), and
in each maildir specify the relative path to its corresponding filtering
recipe, and the relative path to the maildir from the default home directory.
Then, for each virtual mail account, the mail server must run maildrop
to do the actual mail delivery, explicitly specifying the filtering recipe to
be used.
maildirfilterconfig
fileIn most cases where virtual mail accounts are not used, every maildir's
maildirfilterconfig
should be the same. As an alternative to
installing the same maildirfilterconfig
in each maildir, it is
possible to install a single maildirfilterconfig
systemwide.
Install the global maildirfilterconfig
in Courier's
configuration directory (/usr/lib/courier/etc
by default).
The global maildirfilterconfig
will be used unless
maildirfilterconfig
exists in the maildir directory. Therefore,
the global maildirfilterconfig
can be used to provide a default
for the majority of the mail accounts, and any exceptions are handled by
installing maildirfilterconfig
in the maildir directory, whose
contents will override the global file.
If everything is set up correctly, the webmail menu will present a new link to a screen where mail filtering rules are defined and installed. A mail filter consists of a condition, and an action. A condition is usually based on the contents of some header, or the message body. Regular expressions are allowed. Which means that certain special characters must be quoted. For example, to search for the string "[announce]" verbatim in the subject header, it must be entered as "\[announce\]". Pattern matching, for now, is case-insensitive. The regular expression syntax uses pretty much the same syntax as Perl. See the maildropfilter manual page for more information.
Multiple mail filtering rules can be installed. Their relative order can be rearranged by selecting a filtering rule, then selecting either the "Up" or the "Down" button. It is necessary to select "Save all changes" for any changes to the filtering rules to take effect. Leaving that page in any other way will throw away all changes made.
After installing the webmail server be sure to test that the login
password can be changed through the webmail server (ignore this if
--disable-changepass
was specified). Be sure to change the
password a couple of times, logging out and back in each time.
For the virtual domain modules (authldap
,
authmysql
, and friends) changing the login is a no-brainer. The
tricky situation is when the webmail server uses system passwords to log in
(the authpwd
, authshadow
, or authpam
authentication module). Different systems use different ways to keep login
passwords. Many systems use the traditional /etc/passwd
and
/etc/shadow
files. Other systems use a binary database; other
systems use NIS. And on some systems the password file lookup library is a
wrapper that goes against an external LDAP directory, or a database. For
maximum compatibility, the webmail server changes login passwords by running
the passwd
command. This is the traditinal *nix command that
changes login passwords. passwd
is an interactive command. It's
normally run from a terminal. the webmail server uses an expect
script - as mentioned in Overview - to answer interactive prompts from
passwd
. The expect
script expects to get a plain,
garden-variety, passwd
command, which acts something like
this:
# passwd Changing password for luser (current) UNIX password: (old password typed here) New UNIX password: (new password typed here) Retype new UNIX password: (new password retyped here) passwd: all authentication tokens updated successfully #
Systems that use a passwd
command with very different prompts
may find that the default expect
script will fail. In which case
it will be necessary to tweak the expect
script to match the
prompts from the system's passwd
command.
Modern systems use a passwd
command that rejects "bad"
passwords - passwords that are based on dictionary words, are too short, or
are obvious for other reasons. When testing the webmail server's ability to
change system passwords be sure to use randomly-generated gibberish for the
test passwords. Otherwise, the default expect
script will
actually be working, but you won't be the wiser. For security reasons, the
actual messages passwd
will not be shown by the webmail
server.
Enabling mail filtering, according to the instructions in the previous section, automatically enables MIME autoreply capability. The webmail interface can be used to configure simple autoresponders. By default there is no limit on the number of the size of created autoreplies, therefore it is recommended that a quota be set up on the autoreplies.
An global autoreply quota is set up by initializing the
/usr/lib/courier/etc/autoresponsesquota
configuration file. This
file sets the autoreply quota globally. An autoresponsesquota
file in the Maildir will override the global quota setting for that maildir
only. See the courier(8) manual page for the
description of the autoresponsesquota
file.
Autoreplies can include any valid MIME content (MIME content other than plain text can be uploaded). The following special procedure needs to be used to prepare multipart autoreply content, such as text and html alternatives of the same message:
Assign a filename extension to the message/rfc822
MIME
content. For example, edit your mime.types
file, find the
message/rfc822
MIME type (append one if it's not in
mime.types
), and make sure that it has at least one filename
extension, such as "msg".
Prepare the multipart MIME autoreply. The most convenient way is to prepare a normal E-mail message using a conventional E-mail client. Save the RFC822-formatted message in a file with a ".msg" extension, and upload it on the autoreply screen.
Webmail
handles uploaded message/rfc822
content
by removing all headers except the MIME headers, leaving the MIME content
type header, and the actual MIME content.
autoresponsesquota
configuration file. See courier(8)
for more information.
This is an optional feature in the webmail server that uses GnuPG to send
and receive encrypted/signed E-mail. There is no encryption code in the
webmail server, it uses GnuPG to do
encryption and decryption. For more information on setting up and using
encryption, read the file gpglib/README.html
in the source
distribution.
There are two ways to implement a quota on the size of a mail account: filesystem quotas and maildir quotas:
The maximum disk space quota is implemented within the operating system's filesystem support code. Here, the operating system enforces the maximum disk space that can be used by each account. This is the only reliable quota implementation if individual accounts have login access to the mail account. Maildir quotas (see below) are implemented entirely within the maildir support code, and can easily be superceeded by anyone with login access to the mail account. Additionally, mail accounts must all be system accounts. Virtual accounts -- that share the same physical system userid -- cannot usually be support by filesystem-based quotas, because all mail accounts have the same userid and groupid.
The webmail server cannot be used with filesystem quotas. The webmail server creates and maintains, all by itself, a number of database files that are used to quickly index and access messages. If an account exceeds its disk quota, the webmail server will not be able to create and update those database file, which results in a rather spectacular crash. If login access is available, it is possible to log in and manually delete some files to reclaim some disk space. If login access is not available, the administrator will have to manually fix the account -- the webmail server will not even be able to open an existing folder and delete messages in order to free up disk space. There is some good news, though: the IMAP and the POP3 server can still be used to access and delete messages from the mail account. Due to the way that out-of-quota condition is handled by the IMAP server, some IMAP clients may mark any existing messages in the account as unread, but that is a minor glitch that does no harm.
Courier can manually enforce a quota for mail accounts that use maildirs. This quota enforcement is implemented entirely in software, and is available only when maildirs are used. This quota implementation will also work with virtual accounts. Maildir quota support is available only with userdb, LDAP, MySQL and PostgreSQL authentication back-ends. Maildir quotas are supported by IMAP, POP3, and the webmail server. To add a maildir quota with userdb, run the following commands, for example:
userdb account set quota=quota makeuserdb
Here, account identifies the account to which the quota applies,
and quota is the quota specification, as described in the maildirquota(7)
manual page.
To implement a quota with an LDAP, MySQL, or a PostgreSQL back end, simply follow the instructions given in the corresponding configuration file.
It is possible to adjust certain parameters on an account-by-account
basis. This feature is only available with userdb
,
LDAP
, MySQL
, and PostgresSQL
authentication. Individual account options are not supported with
system-based authentication modules (password/shadow files, or PAM).
NOTE
This account option implementation is used by Courier, Courier-IMAP, and SqWebMail. Some of the following information may not be applicable. The inapplicable bits should be obvious.
Account options have a single, uniform implementation by all supported
authentication methods. To summarize, account options are listed as a single
text string: a comma-separated list of "OPTION=value
" settings.
At this point, the following options may be used:
disableimap=
nIf "n" is 1, disable IMAP access to this account, without affecting POP3 and webmail access.
disablepop3=
nIf "n" is 1, disable POP3 access to this account, without affecting IMAP and webmail access.
disablewebmail=
nIf "n" is 1, disable webmail access to this account, without affecting IMAP and POP3 access.
sharedgroup=
nameAppend "name" to the name of the top level virtual shared folder index file. This setting restricts which virtual shard folders this account could possibly access (and that's on top of whatever else the access control lists say). See the virtual shared folder documentation for more information.
For technical reasons, group names may not include commas or "|" characters.
Account options are specified via the authentication modules in the following manner:
Use the userdb
command to set a field called
"options
". Example:
userdb user1@example.com set options=disableimap=1,sharedgroup=44 makeuserdb
The option text string here is
"disableimap=1,sharedgroup=44
". It specifies two
options.
Account options are defined by the LDAP_AUXOPTIONS
setting in the authldaprc
configuration file.
LDAP_AUXOPTIONS
consists of a comma-separated list of
"attribute=setting
". "attribute" is the name of an LDAP
attribute, and "setting" is the corresponding account setting name. The
value of the attribute becomes the value of the setting. Unless you
value your sanity, the names of LDAP attributes should be the same as
the actual setting names (in which case "=setting" may be dropped and
LDAP_AUXOPTIONS
becomes a simple comma-separated list of
supported settings), but they don't have to be.
LDAP_AUXOPTIONS
is nothing more than a simple mapping
of LDAP attributes to account settings. A LDAP_AUXOPTIONS
of "shared=sharedgroup,allowimap" means that the LDAP attribute called
"shared" contains the "sharedgroup" setting, as described previously;
and an LDAP attribute of allowimap contains the setting of the same
name.
Account options are defined by MYSQL_AUXOPTIONS_FIELD
or POSTGRESQL_AUXOPTIONS_FIELD
, in its corresponding
configuration file. In the most simplest case, add a character field to
the database, and put the field name into the
MYSQL_AUXOPTIONS_FIELD
or
POSTGRESQL_AUXOPTIONS_FIELD
configuration file setting.
For each account, the character field should contain the literal option
string. Yes, you'll just put "shared=sharedgroup,allowimap" literally,
in that field.
Fortunately, there is a cleaner way to do this, which avoid driving
a database designer batty. Keep in mind that the contents of
MYSQL_AUXOPTIONS_FIELD
/POSTGRESQL_AUXOPTIONS_FIELD
are simply inserted directly into the SQL query that fetches the
account information. Both MySQL and PostgreSQL have a rich SQL that can
be used to manufacture a suitable option string from plain,
garden-variety, database fields. That is, you may define individual
table fields like "allowimap", and "allowpop3", then provide a suitable
(albeit ugly) SQL fragment that combines them together into the
expected option string. An example of such an SQL string is provided in
the comments portion of the configuration file.
NOTE
When using the alternative custom query option, the option string is the last field that the custom SQL query should return.
Fax sending is disabled by default and must be explicitly enabled, according to the following instructions. After fax sending is enabled, addressing an E-mail message to <5552000@fax> will have this message faxed.
Of course, the necessary hardware and software must be available. The requisite hardware is a class 2 faxmodem attached to a serial port. Additional software, separate from Courier, must also be installed. Courier does not handle the actual job of faxing. Courier only reformats E-mail messages as fax images, and runs mgetty+sendfax to send the fax. Courier also needs additional software to convert E-mail messages to faxes. All additional software must be separately installed, configured, and tested before enabling faxing in Courier. Most systems already include the following software as part of the base operating system, so in most cases adding fax support will not actually require any additional software to be installed, only minor reconfiguration of existing software:
mgetty+sendfax works with most Class 2 faxmodems. Courier does not use the spooling scripts found in the mgetty+sendfax package. Courier uses its own mail spool. A fax message is handled no differently than any other E-mail message. The only difference is that the E-mail message is addressed to <phonenumber@fax>.
mgetty+sendfax should be configured with its default settings, EXCEPT as follows:
- In /etc/mgetty+sendfax, the "max-tries-continue" setting must be set to "n".
Conversion of E-mail messages to faxes uses ghostscript, and groff. It should be possible to use the original UNIX troff instead of groff, but this has not been tested. Courier generates the fax cover page from the contents of the E-mail message's headers. The initial text portion of the E-mail message will appear as fax cover page comments. Note that the initial text portion of the E-mail message must be in plain text, not HTML. E-mail attachments will be converted and attached as additional fax pages. E-mail attachments may contain plain text, Postscript or PDF documents. Other attachments will result in the E-mail message being returned as undeliverable.
Install the NetPBM library is installed, to add the ability to fax GIF, JPEG, and PNG images. Each image will be converted to a single fax page. Images in excess of 1500x1500 pixels (approximately) will be truncated, and color images will be dithered to black-and-white.
The configuration file /usr/lib/courier/etc/faxrc must be edited in order to enable faxing. This file sets up the dialing parameters, and the default file disables faxing by rejecting all phone numbers. The configuration file has extensive comments that explain how dialing parameters are set.
Using webadmin to set up fax sending is highly recommended. A proper faxrc will automatically hide all the local daling conventions. Webadmin knows how to generate the dialing configuration for the North American dialing plan, with a configurable area code. Faxes should be addressed to a fixed ten digit area code+phone number address, <nnnxxxxxxx@fax>, which will be converted for dialing from the local area code appropriately. Webadmin can also optionally enable faxing to international 011 phone numbers. Webadmin can also fall back to a bare configuration where all phone numbers are dialed as-is, for locations outside of North America.
E-mail messages may contain attachments. Courier combines all attachments in the message into a single fax transmission. Attachment types may be freely mixed. A single message may contain one plain text, and one PDF attachment, for example. It is possible to select certain options, as follows:
These options can be combined: <phonenumber>@fax-lowres-ignore>.
/usr/lib/courier/etc/faxcoverpage.tr is the troff source for the FAX cover page, which includes the first plain text section of the E-mail message. Do not attempt to play with faxcoverpage.tr without a clear understanding of troff. It is safe to make trivial changes (such as replacing the "FACSIMILE COVER PAGE" text).
The /usr/lib/courier/etc/faxrc configuration file provides rudimentary phone number rewriting logic (stuff like dialing "9," to get outside line from a PBX). The default faxrc configuration file specifies a typical dialing configuration for the North American numbering plan, with seven digit local phone numbers, and 1+ten digit long distance phone numbers. The area code in the default faxrc configuration file is set to "999", you will need to change it to your area code (there are two places in faxrc where the area code needs to be set).
In general, messages should be addressed to the full ten-digit phone
numbers. The local area code will be stripped automatically, and "1" will be
dialed before all other area codes. If this is done in practice, local area
code changes will only require an update to faxrc
, without any
need to update the address book.
Comments in the faxrc
configuration file explain the format
of the phone number rewriting rules, in the event that local phone system
customization is required (for example, dialing 9 to get an outside line).
Several places in North America now use ten digit local phone number
overlays, with 1+ten digit long distance dialing. TODO: Use webadmin
if you are not sure how to set this up.
The default faxrc
configuration file allows only
locally-generated faxes. faxrc
must be modified in order to
accept faxes via ESMTP.
Additionally, faxes are accepted via ESMTP only if the FAXRELAYCLIENT variable is set. See the makesmtpaccess(8) man page for additional information.
mgetty has an option that runs a script called "new_fax" after it receives a fax. The default location for this script is either /usr/local/lib/etc/mgetty+sendfax/new_fax or /etc/mgetty+sendfax/new_fax. Consult your mgetty documentation to determine if the new_fax option is enabled, and the exact script location.
Courier provides a script - /usr/lib/courier/share/faxmail/new_fax - that can be used as mgetty's new_fax script. This script converts incoming faxes to PNG images, and delivers it to a local mailbox. Simply copy this script to mgetty's etc directory (or install a soft link there), to automatically drop incoming faxes to a local mailboxes.
The /usr/lib/courier/etc/faxnotifyrc configuration file specifies the mailbox that receives incoming faxes, and several other related options.
This steps consists of flushing the mail queue of your existing mail server and removing it from the system.
If you're using sendmail, edit your startup script, and start sendmail with the option '-q30m' only. Remove the -bd option. This causes sendmail to stop listening on port 25, and stay as a daemon process only for the purpose of running the queue every 30 minutes.
If you're using Qmail, remove tcpserver
from your system
startup script.
Wait for all existing mail to flush itself out, then permanently remove your existing server.
Depending on your system, you may need to create a bunch of soft links,
such as /usr/bin/sendmail
, /usr/sbin/sendmail
,
/lib/sendmail
, or /etc/sendmail
that point to
/usr/lib/courier/bin/sendmail
. If you want to receive mail via
UUCP you will also need to make sure that UUCP knows to find
rmail
in /usr/lib/courier/bin
as well.
You're now ready to configure your system to start Courier at system boot
time (and shut it down at system shutdown). If your system uses system-V init
scripts, here's a sample script that you can install in your
/etc/rc?.d
directories. This is a slightly modified version of
the init script that's used in my RPM package (courier.sysvinit
file in the source code tarball).
NOTE: the following script may take a long time to finish, the very first time it runs. That's because the script automatically creates test SSL certificates the first time the script runs (provided that SSL support is available). This can take as much as 5-6 minutes on a slow machine. Subsequent starts should take only a few seconds.
#! /bin/sh # # chkconfig: 2345 35 65 # description: Courier - SMTP server # # NOTE: The 'restart' here does a "hard" stop, and a start. Be gentle, use # "courierd restart" for a kindler, gentler, restart. # # prefix="/usr/lib/courier" exec_prefix="/usr/lib/courier" sysconfdir="/usr/lib/courier/etc" sbindir="${exec_prefix}/sbin" libexecdir="/usr/lib/courier/libexec" datadir="/usr/lib/courier/share" case "$1" in start) cd / # Start daemons. touch /var/lock/subsys/courier echo -n "Starting Courier mail server:" # First time after install create aliases.dat and makesmtpaccess.dat test -f ${sysconfdir}/aliases.dat || ${sbindir}/makealiases esmtpdcert=0 . ${sysconfdir}/esmtpd case x$ESMTPDSTART in x[yY]*) esmtpdcert=1 ;; esac test -f ${sysconfdir}/${ACCESSFILE}.dat || ${sbindir}/makesmtpaccess . ${sysconfdir}/esmtpd-msa case x$ESMTPDSTART in x[yY]*) esmtpdcert=1 ;; esac test -f ${sysconfdir}/${ACCESSFILE}.dat || ${sbindir}/makesmtpaccess-msa ${sbindir}/courierfilter start echo -n " courierfilter" if test -x ${libexecdir}/authlib/authdaemond then ${libexecdir}/authlib/authdaemond start echo -n " authdaemond" fi if test -x ${sbindir}/courierldapaliasd then ${sbindir}/courierldapaliasd start echo -n " courierldapaliasd" fi case "`cat ${sysconfdir}/calendarmode 2>/dev/null`" in net) if test -x ${libexecdir}/courier/pcpd then ${libexecdir}/courier/pcpd start fi echo -n " pcpd" ;; *) ;; esac if test -f ${libexecdir}/courier/sqwebmaild then ${libexecdir}/courier/sqwebmaild start echo -n " webmail" fi ${sbindir}/courier start echo -n " courierd" if test "$esmtpdcert" = 1 then # If we do not have a certificate, make one up. if test ! -f ${datadir}/esmtpd.pem then if test -x $COURIERTLS then echo -n " generating-ESMTP-SSL-certificate..." ${sbindir}/mkesmtpdcert >/dev/null 2>&1 fi fi fi . ${sysconfdir}/esmtpd case x$ESMTPDSTART in x[yY]*) ${sbindir}/esmtpd start echo -n " esmtpd" ;; esac . ${sysconfdir}/esmtpd-msa case x$ESMTPDSTART in x[yY]*) ${sbindir}/esmtpd-msa start echo -n " esmtpd-msa" ;; esac if test -x ${sbindir}/pop3d then POP3DSTART="" POP3DSSLSTART="" if test -f ${sysconfdir}/pop3d then . ${sysconfdir}/pop3d fi case x$POP3DSTART in x[yY]*) ${sbindir}/pop3d start echo -n " pop3d" ;; esac if test -f ${sysconfdir}/pop3d-ssl then . ${sysconfdir}/pop3d-ssl fi case x$POP3DSSLSTART in x[yY]*) if test -x $COURIERTLS then # If we do not have a certificate, make one up. if test ! -f ${datadir}/pop3d.pem then echo -n " generating-POP3-SSL-certificate..." ${sbindir}/mkpop3dcert >/dev/null 2>&1 fi ${sbindir}/pop3d-ssl start && \ echo -n " pop3d-ssl" fi ;; esac fi if test -x ${sbindir}/imapd then . ${sysconfdir}/imapd case x$IMAPDSTART in x[yY]*) ${sbindir}/imapd start echo -n " imapd" ;; esac . ${sysconfdir}/imapd-ssl case x$IMAPDSSLSTART in x[yY]*) if test -x $COURIERTLS then # If we do not have a certificate, make one up. if test ! -f ${datadir}/imapd.pem then echo -n " generating-IMAP-SSL-certificate..." ${sbindir}/mkimapdcert >/dev/null 2>&1 fi ${sbindir}/imapd-ssl start && \ echo -n " imapd-ssl" fi ;; esac fi echo "" ;; stop) echo -n "Stopping Courier mail server:" if test -x ${sbindir}/imapd then ${sbindir}/imapd stop echo -n " imapd" fi if test -x ${sbindir}/imapd-ssl then ${sbindir}/imapd-ssl stop echo -n " imapd-ssl" fi ${sbindir}/esmtpd-msa stop echo -n " esmtpd-msa" ${sbindir}/esmtpd stop echo -n " esmtpd" if test -x ${sbindir}/pop3d then ${sbindir}/pop3d stop echo -n " pop3d" fi if test -x ${sbindir}/pop3d-ssl then ${sbindir}/pop3d-ssl stop echo -n " pop3d-ssl" fi ${sbindir}/courier stop echo -n " courierd" if test -f ${libexecdir}/courier/sqwebmaild then ${libexecdir}/courier/sqwebmaild stop echo -n " webmail" fi if test -x ${sbindir}/courierldapaliasd then ${sbindir}/courierldapaliasd stop echo -n " courierldapaliasd" fi if test -x ${libexecdir}/courier/pcpd then ${libexecdir}/courier/pcpd stop echo -n " pcpd" fi if test -x ${libexecdir}/authlib/authdaemond then ${libexecdir}/authlib/authdaemond stop echo -n " authdaemond" fi ${sbindir}/courierfilter stop echo " courierfilter" ;; restart) $0 stop $0 start ;; esac exit 0
The reason I test for the existence of the POP3 and IMAP server binaries is because I build the POP3 and IMAP servers as separate sub-packages, that do not have to be installed. These tests avoid the need for each sub-package to install its own startup script.
PREV: Status/Download | NEXT: FAQ |