NOTE: a more readable HTML version of this INSTALL document can be found in courier/doc/install.html.
NOTE:
This documentation describes manual installation of the Courier mail server. This is a somewhat involved process that may overwhelm people that do not have prior experience with installing large software packages. Many Linux-based distributions and BSD-family systems have separately-maintained, preconfigured, ready-to-install packages that can be loaded with much less investment of time. Installing a pre-built package would probably be the best approach in this case.
Should you choose to install a platform-specific prebuilt package, you should carefully read any custom documentation files that are included in the package. Most platform-specific packages provide custom, non-default configuration settings that are optimized for that platform unique needs and requirements. Feedback about platform-specific precompiled packages should be copied to the development group that maintains the package, in additional to the platform-neutral
courier-users
mailing list. They will appreciate the feedback, and take it into consideration when preparing the next revision of the platform-specific package.
Read this document in its entirety before entering a single command. Installing the Courier mail server for the first time will take a while. If possible, consider looking around for anyone who has already packaged the Courier mail server for your operating system, and save yourself the hassle.
Fortunately, it gets easier with each subsequent installation. The Courier mail server 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.
The Courier mail server'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 the Courier mail server 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.
There's a new setting, SYSLOCALE, in the courierd configuration file, which initializes the environment from the default system locale. The configuration script heuristically searches for a list of known locale initialization scripts on various platforms, if found.
If your platform's locale configuration script's name is not known to the configuration script, manually specify your default system locale in this configuration setting.
The webmlmd tool has been significantly enhanced, with a new administration screen that consists of three new template files: style.css.tmpl, webmlmlistadmin.tmpl.html, and webmlmlistadminpw.html.html. These three template files must be installed in each mailing list directory. You may copy them manually, or use the couriermlm update command. couriermlm update overwrites all your list-specific customizations, so make backups first!
The logic for outbound authenticated SMTP has changed. This is when the Courier mail server sends outbound mail through a smarthost that requires authentication.
The specified smarthost's name is still looked up in DNS, as before. When smtp.example.com is specified as the smarthost's name, The Courier mail server looks up any MX or A records for smtp.example.com. A connection gets established to a server whose name may be different than the original DNS hostname, if it gets redirected via an MX or a CNAME record.
In earlier versions of the Courier mail server, the smarthost's userid and password must be listed using the resulting server's physical, resolved name. Starting with version 0.55, the smarthost's original DNS name must be listed instead. In all cases now, the name of the server listed in esmtpauthclient will now match the name specified in esmtproutes.
After updating to 0.55, the contents of the esmtpauthclient configuration file may need updating.
IMPORTANT: After updating to 0.55, all existing couriermlm mailing list directories must be updated with new configuration files. See the "update" command in the "MANUAL COMMANDS" section of the couriermlm(1) manual page. If you run many mailing lists, you are strongly advised to install the new version of the Courier mail server on another machine and become re-acquainted with couriermlm's configuration. In an emergency, make a backup copy of the couriermlm command from your existing version of the Courier mail server, before installing this update.
Version 2.0 of maildrop, in the Courier mail server 0.52, introduces a new pattern matching engine that uses the PCRE library, that uses a completely different syntax. However, very few changes should be required to upgrade existing maildrop recipes to the new syntax.
After upgrading from the Courier mail server 0.51, or earlier, review the maildropfilter manual page which has been revised to document the new pattern matching syntax. The legacy pattern matching engine is still available by setting MAILDROP_OLD_REGEXP to 1. See also the "Conversion of maildrop 1.x pattern to 2.0" section in the manual page, for more information.
couriermlm
's default configuration now treats
both the userid and the domain portion of E-mail addresses as
case-insensitive.
Any existing mailing list that has subscribers whose E-mail
addresses contain uppercase addresses must explicitly set the new
CASESENSITIVE=1
list option, using the
couriermlm
command, otherwise those subscribers will
have problems unsubscribing or posting messages to the list.
The Courier mail server's default configuration now includes backscatter suppression. Review Backscatter suppression, below, for any needed configuration changes.
Beginning with 0.48, the authentication library that used to be a part of the Courier mail server's source has been spun off into a standalone authentication library.
You must download and install the Courier mail server
authentication library from http://www.courier-mta.org/authlib/
before upgrading. Review the documentation in the
courier-authlib
package for more information.
As part of installing courier-authlib
, the
configuration files in the Courier mail server's
configuration directory that relate to authentication will be
copied to courier-authlib
's configuration directory.
The files are: authdaemonrc
,
authmysqlrc
, authpgsqlrc
,
authldaprc
, and userdb
(together with
the .dist
versions). This works only as long as the
Courier mail server was installed in one of the known
default installation directories. The documentation in
courier-authlib
explains what to do if the existing
version of the Courier mail server is installed in a
non-default location.
In any case, after upgrading to 0.48 these configuration files
in the Courier mail server's configuration directory will
no longer be used. To avoid future confusion the old copies of
these configuration files (including the .dist
files), should be removed from the Courier mail server's
configuration directory. They now live in the Courier mail
server-authlib's configuration directory
(/usr/local/etc/authlib
, or whatever was specified
to the Courier mail server-authlib's
configure
script).
The command to start the webmail server daemon has changed. The system startup script must be modified to run the new command: "/usr/lib/courier/sbin/webmaild start". Additionally, this scripts also starts pcpd, if required. It is no longer necessary to start pcpd by hand.
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 the Courier mail server 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 the Courier mail server.
Make a backup copy of your current sysconfdir, then
delete the old version of the Courier mail server.
"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 the Courier mail server:
The courier-authlib
package must be installed
and configured prior to installing the Courier mail
server. Download the courier-authlib
package
from http://www.courier-mta.org/authlib/
.
The Courier mail server 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 the Courier mail server to compile.
The PCRE library (http:/www.pcre.org) is required.
This library (http://www.gnu.org/software/libidn/) implements support for internationalized domain names.
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.
Either library must be installed.
FAM (http://oss.sgi.com/projects/fam/) or
Gamin is optional. If FAM or Gamin is installed,
it is used for an enhanced IMAP 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/GnuTLS. If OpenSSL or GnuTLS 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 the Courier mail server. 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.
Most of the LDAP support code is already provided by the Courier mail server authentication library. Some LDAP features, such as LDAP-based mail aliases, are implemented in the Courier mail server directly. OpenLDAP client libraries must be installed. If OpenLDAP is not installed, LDAP directory features are disabled.
This optional software is required to send E-mail messages via fax. The Courier mail server will compile and install without this software, but you will not be able to send faxes. All packages must be installed prior to installing the Courier mail server, and binaries from all packages must be installed in the default PATH before running the Courier mail server'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 the Courier mail server 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 the Courier mail server 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
.
The Courier mail server 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 the Courier mail server from running.
NOTE: Linux-Mandrake includes the Openwall patch in the alternative "secure" kernel package. The Courier mail server 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:
The Courier mail server 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. The Courier mail server can also be used as a traditional mail server, accepting and storing messages in individual mailboxes that are accessible via POP3, IMAP, or webmail.
The Courier mail server 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, The Courier mail server'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, The Courier mail server already includes a fully integrated POP3 and IMAP server.
Still, if circumstances absolutely require for you to stick with mailbox files, The Courier mail server 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.
The Courier mail server 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. The Courier mail server does not support dot-locks, and the Courier mail server does not support a separate mail directory for mailbox files. Mailbox files must be located in the home directory of each individual account.
The Courier mail server 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.
The Courier mail server will be happy to hand off all
local mail to procmail
, or anything else for the
actual delivery.
The Courier mail server 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 the Courier mail server.
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, The Courier mail server will install
as user/group daemon
(or some other suitable
user/group id). Only two of the Courier mail server'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 the Courier mail server'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 the
Courier mail server to use a well-defined existing user
and group ID, such as daemon
.
The Courier mail server, 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 mail server 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 the Courier mail server consists of several
hundred individual files (at the last count), so if you install
the Courier mail server 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 the Courier mail server 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, The Courier mail server'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. The
Courier mail server 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 the Courier mail server.
The Courier mail server has the ability to send outgoing SMTP mail through a Socks 5 proxy. The Socks 5 proxy option requires a separate module to be installed before installing the Courier mail server. Download the Socks 5 proxy client library from http://www.courier-mta.org/download.php#sox and follow its installation instructions. Binary RPMs can be built from the source code tarball by following the procedure outlined in http://www.courier-mta.org/FAQ.html#rpm using the "courier-sox-version" tarball, and installing the "courier-sox" and "courier-sox-devel" binary RPMs afterwards.
NOTE: Be sure to read the README, NEWS, and INSTALL files in the Courier mail server Socks 5 library toolkit, before attempting to install it for the first time (unless using the RPM build method).
Socks proxying must be implemented in relatively low-level
manner, and may not work on all operating systems. This is why it
is packaged separately, in case that it doesn't work. The
configure
script, described in the following
section, enables Socks 5 support automatically if the
Courier mail server Socks 5 proxy client library is
already installed. To make sure that the library is installed
correctly, specify the "--with-socks
" option to the
following configure
script. This option aborts the
configure
script if it does not detect the
Courier mail server Socks 5 proxy client library.
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 the Courier mail server
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 the
Courier mail server. 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 the 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 the Courier mail server 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 the
Courier mail server. Do not attempt to install the
Courier mail server 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
The Courier mail server 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 the Courier mail server uses
internally.
--enable-mimecharset=charset
Specify the default character set the Courier mail
server 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 the Courier mail server 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 the
Courier mail server.
--exec-prefix=pathname
Specify where the Courier mail server'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 mail server 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
Specify 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 the Courier mail
server's configuration files are installed. This option
defaults to the subdirectory "etc
" in the
directory specified by the --prefix
option.
--localstatedir=pathname
Specify 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
The Courier mail server 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 the Courier
mail server uses internally.
--enable-mimecharset=charset
Specify the default character set the Courier mail
server 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.
--without-explicitsync
Normally the Courier mail server 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
Specify the contents of the PATH
environment
variable that is inherited by custom programs started by the
Courier mail server 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>
, The Courier
mail server 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 the Courier mail
server-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, The Courier
mail server's ESMTP
server will also advertise a
dummy ESMTP capability called
XCOURIEREXTENSIONS
, and will not recognize any
the Courier mail server-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 the Courier mail server 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.
--with-random=/dev/path, --without-random
Sometimes the Courier mail server 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 the Courier
mail server will generate some noise on its own. The
Courier mail server will generate noise based on the
output of a random ps command, and several other, hopefully
unpredictable, sources.
--with-gnutls
- Use the GnuTLS library even if
the OpenSSL library is also installed. The Courier mail
server automatically uses whichever one is available. The
OpenSSL library is selected if both are present. Use this
option to override and select GnuTLS instead.--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 the Courier mail server use an external, previously installed, root CA database.
--with-waitfunc=wait, --with-waitfunc=wait3
Specify 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
The Courier mail server'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.
--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 for the webmail server. 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 the typed message. These settings can also be adjusted at runtime. See Maximum message size, below.
--with-maxmsgsize=bytes
Sets the upper limit of messages composed in the webmail server, the main text and all the attachments. This setting can also be adjusted at runtime. See Maximum message size, below.
--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.
If you'll be using the webmail server, you MUST add an
hourly cron job to run the
/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). This setting gives the initial configuration, that can be individually adjusted in the Preferences screen.
--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 the Courier mail server without this option,
run make check
, then reconfigure the
Courier mail server with this option.
IPv6 support in the Courier mail server 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 the Courier mail server 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 the Courier mail server. If
make
completes succesfully, run make
check
. make check
runs some simple internal
tests. It is not feasible to run a complete check of the
Courier mail server'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 the Courier mail server.
If you use the GNU version of make
, and you would
like to see which files the Courier mail server 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 the Courier mail server 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 the Courier mail
server binaries with debugging data, which is probably a good
idea to do while the Courier mail server 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 the Courier mail server 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 mail server RPM package will install and the old configuration files will be silently removed, since they were not installed using RPM.
The Courier mail server 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 the
Courier mail server'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 the Courier mail server, blow away your current
server before running make install
.
There are four setuid binaries in the Courier mail
server that are owned by root: sendmail
,
maildrop
, webmail
and
webadmin
. There's also one setgid binary,
sqwebpasswd
.
/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/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 the Courier mail server'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/sqwebpasswd
is
described in detail in the "OPTIONAL:
Changing mail account passwords using the webmail server"
section.
A first-time the Courier mail server installation may not require the system startup scripts to be modified to start the Courier mail server at system boot. Until the system's functionality is verified, the system will probably continue to use the existing mail server. Still, most the Courier mail server configurations will require two things to be started before any part of the system is put to use:
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 the Courier mail server 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 the Courier
mail server is installed in /usr/lib/courier
.
Run the showmodules
utility after all files have
been installed, but before you attempt to start the
Courier mail server. The showmodules
utility
attempts to load and initialize transport modules that have been
configured, without actually starting up the Courier mail
server. 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 the Courier mail server, 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.
Start the Courier mail server 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
.
Run the perftest1
script, which can be found in
the directory containing the Courier mail server'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. The
Courier mail server 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 the
Courier mail server.
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.
Note that 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
the Courier mail server 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. The Courier mail server 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 the Courier mail server 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.
NOTE: Authenticated SMTP is preferred over defining explicit IP address ranges. When combined with SSL, authenticated SMTP enables relaying privileges to any sender that securely provides a valid login/password, from any IP address, instead of only a small range of preauthorized IP addresses. The "OPTIONAL: Configure ESMTP authentication and SSL" section, later in this installation guide, gives more information on enabling authenticated SMTP and SSL-based encryption.
Furthermore, preauthorized IP address ranges are vulnerable to being a source of abusive backscatter E-mail. Using authenticated SMTP together with the optional backscatter setting, described in the following section, prevents transmission of abusive backscatter bounces to external recipients even from trusted senders that have been compromised.
NOTE: It is important to know that the Courier mail server's default backscatter configuration means that if the Courier mail server receives a message for delivery to a local mailbox, and encounters an error during the delivery, the sender may not receive a delivery failure notification. The most common reason is an error in a custom mail filtering script. The next most common reason is a configuration error (the Courier mail server authentication library gives the account's home directory, optional non-default mailbox location, the account's system userid and groupid; but they differ from the actual files and directories (the home directory or the account's mailbox does not exist, exists somewhere else, or they're owned by a different userid or groupid).
When installing the Courier mail server for the first time, it is usually helpful to termporary turn off the default backscatter filters, by setting BOFHSUPPRESSBACKSCATTER to "none", as described below. Remove this setting after the Courier mail server is installed and its basic functions appear to be working.
The term "backscatter" refers to non-delivery reports sent to a forged return address. SMTP was created a long time ago, in better times when everyone trusted each other. Anyone could provide any return address for any E-mail message.
Times have changed. At the time this documentation is written, most surveys report that between 75% and 80% of Internet E-mail is junk E-mail or viruses, with a forged return address.
Backscatter becomes a problem when a mail server does not reject unwanted mail. The mail server decides that the message is unwanted only after it is accepted. It generates a non-delivery notice, and sends it to the original message's return address. Because viruses and junk mail use random forged return addresses, the unfortunate victim of address forgery must deal with large amounts of useless non-delivery notices from the mailbox. Not to mention a bunch of uninformed people who think he is responsible for sending the virus or the junk mail to them.
There's now a growing consensus that backscatter bounces should be considered E-mail abuse. The Courier mail server is already very good at minimizing the amount of backscatter, by the virtue of refusing to receive any mail to a nonexistent local mailbox. However it's still possible for the Courier mail server to bounce a received message. Several settings control how the Courier mail server filters out its own backscatter, and avoids becoming a nuisance to others.
Two settings are available. The first setting instructs the
Courier mail server to simply discard backscatter bounces.
This is the ESMTP_BLOCKBACKSCATTER
setting in the
courierd configuration file. This setting lists the
so-called "message sources" which are dropped by the SMTP client.
All messages from any matching source are quietly discarded. The
default setting lists one message source: a code that means "a
delivery status notification for a message received via SMTP from
a non-authenticated source". "Non-authenticated" means a message
received from an IP address that does not have relaying
privileges, and did not authenticate. It's also possible to
include authenticated SMTP sources; or it's possible to disable
this setting altogether, instructing the Courier mail
server to deliver all bounces via SMTP, even if they may
potentially be backscatter.
Note that messages received in other ways (such as messages sent via the sendmail command) are not affected. Their bounces will be sent via SMTP in all cases (although there exists an undocumented setting to block those bounces too). Also, bounces are always delivered to local mailboxes, this setting is ignored for local mail deliveries.
The default setting means that if the Courier mail server receives a message via SMTP for delivery to a local mailbox, and it bounces for some reason, the bounce will be discarded.
The Courier mail server is also often used as a smarthost for SMTP clients. These SMTP clients either connect from trusted IP addresses (IP addresses that belong to the organization that runs the mail server), or that succesfully authenticate, using SMTP authenticate. If those messages bounce, the non-delivery report gets delivered, because the default setting only drops bounces from non-authenticated source (a connection from a trusted IP address is always processed as if the sender succesfully authenticated).
NOTE: Sometimes the Courier mail server serves as a backup MX for another organization. If mail cannot be delivered to the primary MX (it rejects the message, or the message times out), the bounce will be discarded, because the message was probably received from a non-authenticated source.
The second setting minimizes the possibility of generating a bounce, of any kind, in the first place. The second setting controls the backscatter suppression list, which is a list of blacklisted E-mail addresses.
When the Courier mail server fails to deliver a message to an address, this address goes on the suppression list, and the Courier mail server will refuse to accept any more messages to the same address. If the delivery failure was a temporary failure, any future messages will also be turned away with a temporary error. A permanent delivery failure results in future messages rejected with a permanent error.
Note that the suppression list does not apply to messages already accepted by the Courier mail server, and which are in its mail queue. The suppression list is checked when the Courier mail server is receiving a new message. The Courier mail server automatically clears an address from the suppression list after two hours. If the original message encountered a temporary delivery failure, The Courier mail server periodically tries again to re-deliver the message. If the message continues to encounter a temporary delivery failure, the clock starts running again, from the beginning, If a re-delivery attempts succeeds, the address is cleared from the suppression list, and the Courier mail server will now accept more messages to the same address, immediately.
If a message keeps encountering temporary delivery failures, the time before re-delivery attempts gets longer. It's possible that it could take more than two hours for another delivery attempt, on a busy mail server. The address then falls off the list, and the Courier mail server will accept another message to the undeliverable address. This situation is unavoidable, but is not considered to be a major issue.
The second setting is the BOFHSUPPRESSBACKSCATTER
setting, in the bofh configuration file. See the
courier(8)
man page for more information. The
default BOFHSUPPRESSBACKSCATTER
setting also filters
only messages from non-authenticated SMTP sources against the
suppression list.
The suppression list is not updated when problematic messages
are manually removed from the mail queue (using the
"courier cancel
" command). Even though the stuck
messages are deleted, The Courier mail server will
continue to refuse messages to suppressed addresses, until they
time out. Use the "courier clear
" command to
manually clear addresses from the suppression list, if so
desired.
NOTE: A mailbox that exceeded its storage quota results in temporary delivery failures. Therefore, when a mailbox fills up, The Courier mail server stops accepting any more messages to this mailbox (there might be one or two messages already in the mail queue, but that shouldn't be a major issue). Mail deliveries will resume when the mailbox goes below the quota (although this may take an hour, or two, as explained previously). It's possible that an existing version of the Courier mail server was originally modified to generate a permanent delivery failure for a quota exceeded condition. This change should now be undone, in order for backscatter suppression to work properly.
The third setting is the DSNTOAUTHADDR=1
setting
in the courierd configuration file. This setting, when
enabled, alters bounce handling of messages that were received
from an authenticated SMTP connection.
Bounces of authenticated messages are processed according to the previous two settings, except that the bounce message gets sent (if it gets sent at all) to the authenticated login address, instead of the message's return address.
NOTE: This works only if the Courier mail server is configured, via the Courier mail server Authentication Library, to validate login IDs that consist of a full E-mail address, "
user@domain
", with the login ID corresponding to the mailbox's E-mail address.
Enabling this setting removes the possibility of the Courier mail server sending abusive backscatter bounces to external recipients, from a compromised trusted sender, even if the compromised trusted sender uses authenticated SMTP. Instead of sending the bounces to the forged return address, they get redirected to the sender's mailbox.
NOTE: The authenticated address is used for bounces only. When the message gets sent to its listed recipients, the message's return address gets used, as usual.
NOTE: Authenticated SMTP must be used for this option to have any effect. When relaying privileges are granted to explicit IP address ranges (see the preceding "Create smtp access list" section), The Courier mail server will not have the sender's authenticated login address (unless the sender voluntary authenticates).
Review/edit contents of various configuration files in
/usr/lib/courier/etc
:
courierd
this file controls general aspects of the Courier
mail server'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 the Courier mail
server 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 the Courier
mail server 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 the Courier mail server'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.
esmtpd-msa
this file controls the Courier mail server'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 the Courier mail server's POP3 server. The Courier mail server'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 the Courier mail server's IMAP server. The Courier mail server'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.
echo "qmail" >/usr/lib/courier/etc/dotextension
Run this command if you are installing the Courier mail
server on a system that's currently running the Qmail mail
server. The Courier mail server will now read
.qmail
files for delivery instructions, instead of
.courier
files. The Courier mail server'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 the Courier mail server 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, The Courier mail server 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 the Courier mail server to accept mail for all
subdomains of this domain.
The Courier mail server is capable of sending and receiving mail via UUCP. The Courier mail server does not implement UUCP directly, but instead uses your existing UUCP software to send and receive mail.
The Courier mail server's UUCP functionality has been tested with Taylor UUCP 1.06. It's likely that some minor tweaking will be necessary to get the Courier mail server 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 the Courier mail
server uses directly. The format of the
uucpneighbors
configuration file is described in the
makeuucpneighbors(8)
manual page.
/usr/lib/courier/etc/uuucprewriteheaders
The Courier mail server 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, The Courier mail server 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 the Courier mail server accepting mail for one address, and delivering the mail to another address. A one-to-many substitution results in the Courier mail server accepting mail for one address, and delivering a separate copy of the message to every address defined by the alias.
The Courier mail server 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.
The Courier mail server 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.
The Courier mail server includes several options for selectively filtering mail. In general, The Courier mail server provides only the plug-in interfaces by which arbitrary external mail filters can be used to selectively accept or reject messages. The Courier mail server 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.
The Courier mail server provides two mail filtering interfaces:
these filters are installed and will be used to filter every incoming message. Global mail filters are permanently running daemons that create and listen on a filesystem domain socket. Each new message that the Courier mail server receives must be acknowledged by every global mail filter. Note that if global mail filters are installed, but their daemons are not running, The Courier mail server will not accept any new messages.
this filter can be used when the message is addressed to a
local recipient - when the Courier mail server itself
will deliver the message to a physical mailbox. Local mail
filtering is designed to be primarily used by the
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.
The Courier mail server 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.
The Courier mail server 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 the Courier mail server, run the command
/usr/lib/courier/sbin/courier start
. To stop the
Courier mail server, 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 the Courier mail server'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.
You now have several options for migrating from your existing mail server to the Courier mail server:
/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.
The Courier mail server 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
initialize the ESMTPAUTH
configuration setting.
The configuration file
/usr/lib/courier/etc/esmtpd-msa
is used for the
ESMTP submission server on port 587. Setting this variable in
esmtpd
is sufficient, because
esmtpd-msa
merely supplements the settings in
esmtpd
. Explicitly initialize this setting in
esmtpd-msa
only if you wish to apply it to port
587 only.
ESMTPAUTH
is a list of SASL authentication
methods to use use. Currently, The Courier mail server
supports LOGIN
, PLAIN
,
CRAM-SHA1
and CRAM-MD5
. The list of
authentication methods is sometimes influenced by the
installed authentication modules in the Courier mail
server Authentication Library. Not all authentication modules
implement CRAM-MD5/SHA1
. The authentication
modules that support CRAM-MD5/SHA1 authentication are:
authuserdb
, authldap
,
authmysql
, and authpgsql
.
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.The Courier mail server also supports ESMTP over TLS/SSL, by using the ESMTP STARTTLS extension:
To add SSL support you have to install OpenSSL or GnuTLS
before installing the Courier mail server. Download
OpenSSL from http://www.openssl.org/
,
or GnuTLS from http://www.gnutls.org
.
OpenSSL's support is well-tested, the GnuTLS version is a relatively new addition, and is considered experimental. Follow OpenSSL's or GnuTLS's installation instructions, then build the Courier mail server.
NOTE: Most systems already have an available OpenSSL or GnuTLS package. Do not build OpenSSL or GnuTLS yourself, if a prebuilt package is already available. Just install the prebuilt package.
NOTE: The development libraries must be installed in addition to the runtime package, in order to build the Courier mail server. On most systems, the development files (header files, libraries, etc...) are provided in a separate "devel" package. The base OpenSSL/GnuTLS package is not sufficient to build the Courier mail server, the development libraries must be installed.
The OpenSSL library is selected when both OpenSSL and
GnuTLS libraries are found by the configure
script. Use the --with-gnutls
option to
explicitly select GnuTLS library over OpenSSL.
/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
the Courier mail server 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 mail server userid (the userid used
to install the Courier mail server, 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.The Courier mail server will also use TLS/SSL when sending ESMTP mail, automatically. If the remote mail server support STARTTLS, The Courier mail server 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, The Courier mail server 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 the Courier mail server will bounce the
recipient.
Starting with version 0.34, The Courier mail server
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.
The Courier mail server 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 the Courier mail server. Therefore, at present time both the sending and the receiving mail relay must be running the Courier mail server 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. The Courier mail server 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 the Courier mail server will send the message. The Courier mail server 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, The Courier mail server 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 the Courier mail server. 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
. The Courier mail server 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
. The Courier mail server 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
. The Courier mail server
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 the
Courier mail server 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 the
Courier mail server 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
The
Courier mail server 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.
The Courier mail server can optionally check the return address on all SMTP mail for the sender's published Sender Policy Framework (SPF). Keep in mind SPF is an experimental protocol that's still maturing. The Courier mail server's SPF configuration is set up in the "bofh" configuration file, and is fully explained in the courier(8) manual page.
The Courier mail server includes an integrated IMAP server. The following steps set it up:
/usr/lib/courier/etc/imapd
. If you want
to use IMAP SASL authentication, set up the
IMAP_CAPABILITY
variable. It performs the
equivalent function as the ESMTPAUTH
variable 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 the Courier IMAP server. 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 add SSL support you have to install OpenSSL or GnuTLS
before installing the Courier mail server. Download
OpenSSL from http://www.openssl.org/
,
or GnuTLS from http://www.gnutls.org
.
OpenSSL's support is well-tested, the GnuTLS version is a relatively new addition, and is considered experimental. Follow OpenSSL's or GnuTLS's installation instructions, then build the Courier mail server.
NOTE: Most systems already have an available OpenSSL or GnuTLS package. Do not build OpenSSL or GnuTLS yourself, if a prebuilt package is already available. Just install the prebuilt package.
NOTE: The development libraries must be installed in addition to the runtime package, in order to build the Courier mail server. On most systems, the development files (header files, libraries, etc...) are provided in a separate "devel" package. The base OpenSSL/GnuTLS package is not sufficient to build the Courier mail server, the development libraries must be installed.
The OpenSSL library is selected when both OpenSSL and GnuTLS
libraries are found by the configure
script. Use the
--with-gnutls
option to explicitly select GnuTLS
library over OpenSSL.
The /usr/lib/courier/etc/imapd-ssl
configuration
file sets some additional options for SSL support, 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 the Courier mail server 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 FAM, the File Alteration Monitor (http://oss.sgi.com/projects/fam/) or Gamin 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 the Courier mail server 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.
The Courier mail server 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 POP3AUTH
variable. It performs the equivalent function as the
corresponding variable 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
.
It is possible to distribute IMAP and POP3 mailboxes between multiple server.
See imap/README.proxy
for more information.
The Courier mail server can use SSL certificates for authentication purposes. That is, instead of using a login ID and a password, for accessing the mailbox, The Courier mail server uses a client-side SSL certificate. For certificate authentication purposes, one of the fields in your certificates' subject must match the login ID in the authentication database. Consider the following certificate:
... Subject: C=US,ST=New York,L=New York,O=Acme Widgets Inc,CN=John Smith,emailAddress=johnsmith@example.com
If the emailAddress
field is configured as the
login ID, the authentication database must provide login details
for johnsmith@example.com
. To enable certificate
authentication, edit the following configuration files in
sysconfdir: imapd-ssl
,
pop3d-ssl
, esmtpd
and
esmtpd-ssl
(the esmtpd
files enable SSL
certificate authentication for incoming SMTP
connections, if a good SSL certificate is provided, the client
receives mail relaying privileges). All of these configuration
files require the same set of changes:
Set TLS_TRUSTCERTS
to the filename with your
certificate authority's X.509 certificate.
Change the TLS_VERIFYPEER
setting to
"PEER
". The setting can also be changed to
"REQUIREPEER
" to require all SSL/TLS connections
to provide a certificate. Otherwise, it is optional. If the
mail client provides an SSL certificate, it may be used to
authenticate. Without a certificate, password-based
authentication remains an option.
Change the TLS_EXTERNAL
setting to the name
of the certificate subject field that gives the login ID. In
the above example, this would be
"TLS_EXTERNAL=emailaddress
".
NOTE: GnuTLS's
certtool
uses "emailaddress
".
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/sbin/webmaild start
(It is also possible to run "webmaild stop
" from
the system shutdown script in order to shut down webmail service
gracefully).
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.
The following extension may be necessary to make webmail work when SELinux kernel extensions are turned on:
allow httpd_sys_script_t var_t:sock_file write; allow httpd_sys_script_t unconfined_t:unix_stream_socket connectto;
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, The
Courier mail server'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 the Courier mail server.
NOTE: Courier mail server 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.
The OpenLDAP development toolkit must be installed before building SqWebMail, in order for LDAP search code to compile.
The file ldapaddressbook
configuration file
should contain a default systemwide list of accessible address
book. See courier(8) for more
information. A default file will be installed, listing some
common Internet address books. Each line in this file contains
the following information:
name<tab>host<tab>port<tab>suffix<tab>binddn<tab>bindpw
<tab> is a single ASCII TAB character. name is the unique name for this LDAP server. host and port specify the connection parameters. suffix specifies the root LDAP entry whose subtree gets searched. The binddn and bindpw fields are not presently used (they were used in earlier version of the webmail server, before the LDAP search interface was rewritten and simplified).
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.
Messages composed in the webmail server are limited in size. The additional limitation are on top of the limit set in the sizelimit configuration file, see the courier(8) manual page.
The --with-maxargsize
,
--with-maxformargsize
, and
--with-maxmsgsize
options to the
configure
script set the parameters that control the
maximum size of messages and attachments. These parameters can
also be set through the following environment variables.
NOTE: The
configure
script parameters define the minimum settngs. The following environment variables may be used to set larger limits only.NOTE: These settings limit only the maximum size of messages sent from the webmail server. The limit on the incoming message size is set by other Courier mail server settings (usually the sizelimit setting also).
SQWEBMAIL_MAXARGSIZE
--with-maxargsize
parameter to the configure script
). This is the
maximum message that can be typed into the webmail server.
NOTE: The webmail server has an inactivity timeout. While composing a new message use the "Preview" button frequently to save the unfinished message and keep the session from timing out.
SQWEBMAIL_MAXATTSIZE
--with-maxargsize
parameter to
the configure script
).
NOTE: Attaching binary files to E-mail messages
incurs an overhead of approximately 33%. E-mail is really not
the optimum medium for exchanging files. Setting
SQWEBMAIL_MAXATTSIZE
to 4000000 will effectively
allow attaching files of up to 3000000 bytes in length,
approximately.
SQWEBMAIL_MAXMSGSIZE
--with-maxmsgsize
parameter to the configure
script
). There can be any number of attachments, each
one up to SQWEBMAIL_MAXATTSIZE
bytes long, but the
sum total of the entire message cannot exceed
SQWEBMAIL_MAXMSGSIZE
.These variables must be set in the environment that runs the
webmail CGI
program. With Apache, these variables
can be set in the httpd.conf file by the
SetEnv
command. httpd.conf example:
SetEnv SQWEBMAIL_MAXATTSIZE 1000000 SetEnv SQWEBMAIL_MAXMSGSIZE 4000000
NOTE: These settings are global, and apply to all mailboxes. However, advanced Apache configuration can be used to use different environment variable settings with different virtual hosts.
NOTE: On 32-bit platforms, the maximum limits may not exceed 2 gigabytes. A 64-bit platform is required to have SqWebMail capable of handling attachments and messages larger than 2 gigabytes.
A random seed is required for preventing certain kinds of external attacks against the SqWebMail server. The random seed must be a constant value, only varying between different instances of SqWebMail. By default the random seed is derived from the inode number of one of the supporting script files. The script file ordinarily remains constant, thus the random seed does not change, but different SqWebMail installs will end up with a different seed.
When a pool of SqWebMail servers is combined for load-balancing, all servers must use the same random seed. This is done by defining the SQWEBMAIL_RANDSEED environment variable. This can be set in the httpd.conf as well:
SetEnv SQWEBMAIL_RANDSEED 82738AZ
SQWEBMAIL_RANDSEED should contain up to ten letters or numbers.
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 library. The login ID and password are validated by the authentication library, 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 the
Courier mail server'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.
There are some options which can be used to change the webmail
server's behavior for individual accounts, or globally, using the
"Account Options" feature in the Courier mail server
Authentication library. The individual account's setting takes
precedence over the DEFAULTOPTIONS settings in the
authdaemonrc configuration, so for example if you want to
disable webmail access for most accounts but enable it for a
select few, you can set
DEFAULTOPTIONS="disablewebmail=1"
in the
authdaemonrc
configuration file, and add the option
disablewebmail=0
to individual accounts. See the
section "Account options" in README_authlib.html in the
courier-authlib package for more information on setting the
following account options:
disablewebmail
- if set to a non-zero value, this
account will not be permitted to login to webmail (e.g. because
the user is only allowed to use POP3 or IMAP)
wbnochangingfrom
- if set to a non-zero value,
the webmail server will not allow the From:
header
to be changed, it will always have its default value.
wbnochangepass
- if set to a non-zero value, the
webmail server will not allow passwords to be changed. See
"Changing mail account passwords using the
webmail server", below, for more information.
wbusexsender
- if set to a non-zero value, the
webmail server will attach an X-Sender:
header to
all outgoing messages. This can be used in the event you would
like to be able to modify the From: header, yet also be able to
track sent mail to the original account.
wbnoimages
- if set to a non-zero value then no
images or icons will be used. The generated interface will be a
text-only interface.
wbnodsn
- set to a non-zero value then the option
to request delivery confirmation receipts will not be shown.
After installing the webmail server be sure to test that the login password can be changed through the webmail server.
If you do not want to use the password change function you can
also remove the sqwebpasswd
program. This is a
helper program, installed with the set-groupid bit set, that
relays the password change request to the authentication daemon,
through the filesystem socket that is not globally accessible.
The password change request consists of the account name, the old
password, and the new password. The password change request is
validated by the authentication daemon, and the old password must
match the existing password on the account, before the password
change goes through. This set-groupid helper program is safe to
use.
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.
The Courier mail server 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 actually implemented in
the Courier mail server Authentication Library. See
ACCOUNT OPTIONSin the auth_generic
manual page.
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 the Courier mail server, must also be installed. The Courier mail server does not handle the actual job of faxing. The Courier mail server only reformats E-mail messages as fax images, and runs mgetty+sendfax to send the fax. The Courier mail server 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 the Courier mail server. 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. The Courier mail server does not use the spooling scripts found in the mgetty+sendfax package. The Courier mail server 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:
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. The Courier mail server 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.
On the cover page, the sender's name, the recipient's name, and the fax subject gets taken from the E-mail message's headers. The ability to use non-Latin characters depends on the support from the underlying tools, ghostscript and groff, for the default system locale.
Install the NetPBM library 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. The Courier mail server 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:
sends a low-resolution fax.
Ignore attachments that the Courier mail server doesn't know how to convert to a FAX image format. Normally, if an attachment cannot be converted the whole message is returned as undeliverable.
sends only the cover page. This can be useful for .courier files. See the courierfax(8) manual page for an example.
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.
The Courier mail server 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.
The Courier mail server log analyzer (the courier-analog package) is a Perl script that generates log summaries for the Courier mail server. The Courier mail server log analyzer generates log summaries for incoming and outgoing SMTP connections, and IMAP and POP3 activity. courier-analog can generate output in text or HTML format.
The Courier log analyzer is not included in the main the Courier mail server tarball, it must be downloaded separately from http://www.courier-mta.org/download.php#analog. After downloading and installing this package, see the courier-analog manual page for more information.
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 the
Courier mail server 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 the 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 ${ACCESSFILE}.dat || ${sbindir}/makesmtpaccess . ${sysconfdir}/esmtpd-msa case x$ESMTPDSTART in x[yY]*) esmtpdcert=1 ;; esac test -f ${ACCESSFILE}.dat || ${sbindir}/makesmtpaccess-msa ${sbindir}/courierfilter start echo -n " courierfilter" if test -x ${sbindir}/courierldapaliasd then ${sbindir}/courierldapaliasd start echo -n " courierldapaliasd" fi if test -f ${libexecdir}/courier/sqwebmaild then ${sbindir}/webmaild 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 if test -x ${bindir}/webmlmd then . ${sysconfdir}/webmlmrc if test "$LISTS" != "" then ${bindir}/webmlmd start ${sysconfdir}/webmlmrc && \ echo -n " webmlmd" fi fi echo "" ;; stop) echo -n "Stopping the Courier mail server:" if test -x ${bindir}/webmlmd then ${bindir}/webmlmd stop ${sysconfdir}/webmlmrc echo -n " webmlmd" fi 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 ${sbindir}/webmaild stop echo -n " webmail" fi if test -x ${sbindir}/courierldapaliasd then ${sbindir}/courierldapaliasd stop echo -n " courierldapaliasd" 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.