"Fossies" - the Fresh Open Source Software Archive

Member "courier-1.2.2/INSTALL" (19 Feb 2023, 202014 Bytes) of package /linux/misc/courier-1.2.2.tar.bz2:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "INSTALL": 1.1.11_vs_1.2.0.

    1    NOTE: a more readable HTML version of this INSTALL document can be found
    2    in courier/doc/install.html.
    4                                   Installation
    6 Building rpm and deb packages
    8    These are not the same packages as the ones from various distributions'
    9    repositories. These packages carry a higher internal revision level in
   10    order to prevent them from getting upgraded by the distribution packaging.
   11    These packages exist in order to have a convenient way of updating after a
   12    release without waiting for the distribution's package to get built.
   14    NOTE: If a distribution package is already installed it should be removed
   15    completely before switching to the upstream version (dnf remove or apt
   16    purge). Preserve any existing configuration files, beforehand, in order to
   17    restore it after switching packages. This applies to all Courier packages.
   18    A switch to this courier package requires switching the courier-unicode
   19    and courier-authlib packages too.
   21    NOTE: These packages use their own, generic, installation layout that may
   22    deviate slightly from the package installation conventions preferred by
   23    the distributions:
   25      • The main "courier" package. This installs the main mail server that
   26        starts locally but does not listen on the smtp port until the
   27        appropriate esmtpd configuration files enable the smtp port
   28        listener(s).
   30      • The "courier-maildrop" package. This package installs the maildrop
   31        mail filter.
   33      • The "courier-imapd" and "courier-pop3d" packages. Installing them
   34        results in the IMAP and the POP3 server getting started and listening
   35        on the respective ports, and a self-signed SSL certificate gets
   36        automatically generated, for testing purposes, until it gets replaced
   37        by your real one.
   39      • The "courier-webmail" package. This package installs the sqwebmail
   40        webmail server.
   42      • The "courier-mlm" package. This package installs the couriermlm
   43        mailing list manager.
   45      • The "courier-mlm-web" package. This package installs couriermlm's
   46        web-based gateway.
   48      • The "courier-webadmin" package. This installs the webadmin module, for
   49        a basic browser-based configuration module. The "courier-ldap" module
   50        installs the LDAP-based alias daemon and the webadmin page for
   51        configuring it. The "courier-mysql" and "courier-pgsql" packages
   52        install webadmin pages for configuring mysql and postgres-based
   53        account authentication. The "courier-fax" package installs webadmin
   54        pages and scripts for integrating with the mgetty+sendfax gateway.
   56      • deb only: the "-apache2" deb packages install apache2 configuration
   57        files that enable each corresponding module.
   59    The main "courier" package starts all modules, whichever modules are
   60    installed. Depending on the distribution installing the main "courier"
   61    package may or may not automatically start it. Installing or uninstalling
   62    an additional package with a service may or may not result in an
   63    appropriate restart.
   65   rpm
   67    Run dnf install rpm-build if it's not installed already, then:
   69  rpmbuild -ta courier-version.tar.bz2
   71    If this fails due to any missing dependencies, install them. This will
   72    eventually create source and binary RPM packages. This works for all
   73    Courier packages.
   75   Changing the options that the RPMs are built with
   77    Building the RPMs directly from the source tarball uses the default
   78    options programmed into the tarball. Sometimes you may want to use
   79    different options. For example, you might want to enable fixes for certain
   80    bugs in some IMAP clients. Use the following procedure to build the RPMs
   81    with different options:
   83      • First, build the RPM packages using the default options.
   84      • In addition to binary RPM packages, rpmbuild will create a source RPM
   85        package (filename.src.rpm)
   86      • Install the source RPM package: rpm -i courier-version.src.rpm.
   87      • The contents of the source RPM package get installed into your rpm
   88        build directory, which is usually $HOME/rpm/package.
   89      • Edit the .spec file, modifying the default configuration. You will
   90        need to have some understanding of how RPM spec files work, then use
   91        the modified spec file to build your custom package: rpmbuild -ba
   92        filename.spec
   94 Building DEB packages
   96    Create an empty directory and copy/move the tarball into it:
   98  $ mkdir tmp
   99  $ mv courier-VERSION.tar.bz2 tmp
  100  $ cd tmp
  102    Unpack the tarball and cd into the unpacked subdirectory:
  104  $ tar xvf courier-VERSION.tar.bz2
  105  $ cd courier-VERSION
  107    Run the courier-debuild script, which is a wrapper for debuild, and
  108    forwards its parameters to it:
  110  $ courier-debuild -us -uc
  112    NOTE: the above steps must be followed strictly. The courier-debuild
  113    script expects the distributed tarball in its parent directory.
  115    This eventually produces a deb subdirectory with .deb packages that can be
  116    installed with "dpkg -i".
  118 Maintainer Mode (see README in the git repository to set up)
  120    make rpm or make deb, as appropriate, will:
  122     1. Increment an internal release number.
  124     2. Run make dist.
  126     3. Proceed and build a new release, creating the native packages in the
  127        rpm or deb subdirectory.
  129 Manual installation
  131    > ═════════════════════════════════════════════════════════════════════════
  133    > NOTE:
  135    > This documentation describes manual installation of the Courier mail
  136    > server. This is a somewhat involved process that may overwhelm people
  137    > that do not have prior experience with installing large software
  138    > packages. Many distributions have a separately-maintained,
  139    > preconfigured, ready-to-install packages that can be loaded with much
  140    > less investment of time. Installing a pre-built package would probably
  141    > be the best approach in this case.
  143    > Should you choose to install a platform-specific prebuilt package, you
  144    > should carefully read any custom documentation files that are included
  145    > in the package. Most platform-specific packages provide custom,
  146    > non-default configuration settings that are optimized for that
  147    > platform's unique policies. Feedback about platform-specific precompiled
  148    > packages should be copied to the development group that maintains the
  149    > package, in additional to the platform-neutral courier-users mailing
  150    > list.
  152    > ═════════════════════════════════════════════════════════════════════════
  154    Read this document in its entirety before entering a single command.
  155    Installing the Courier mail server for the first time will take a while.
  156    If possible, consider looking around for anyone who has already packaged
  157    the Courier mail server for your operating system, and save yourself the
  158    hassle.
  160    Fortunately, it gets easier with each subsequent installation. The Courier
  161    mail server is a complicated piece of software. Most problems people will
  162    have are likely to be with the configuring and installing it correctly.
  163    Designing complex software that compiles and installs on a wide variety of
  164    POSIX systems is not a trivial task.
  166    The Courier mail server's configuration and installation scripts are very
  167    flexible in setting up installation directories for each logical set of
  168    files - configuration files, binaries, scripts, the mail queue, and more.
  169    If you begin by installing someone else's package, instead of installing
  170    everything yourself, you should take careful notes where things are
  171    installed. If you later decide to roll your own package, you will either
  172    need to use a COMPLETELY IDENTICAL configuration, or take care to back up
  173    your old configuration, and then restore it after the upgrade. The
  174    following documentation refers to the default location of various
  175    configuration files (and other files as well). If you choose to install
  176    some files in a non-default location (either by yourself, or by using
  177    someone else's package), you will need to take this into account while
  178    reading the following documentation.
  180    This cannot be emphasized enough: the configuration defaults are very
  181    generic; the goal is to have the default configuration settings work for
  182    almost everyone. In every case using at least a couple of non-default
  183    parameters will make the Courier mail server work better on your system.
  184    You should anticipate going through several trial-and-error installs,
  185    tweaking the options to see what works better for you.
  187    NOTE: older versions of the linuxconf configuration tool are hardwired for
  188    sendmail. They like to change the permission of the sendmail wrapper to
  189    match the permissions they think the real sendmail should have. Older
  190    versions of linuxconf also have a tendency to create the /var/spool/mqueue
  191    directory, even if sendmail is not installed.
  193 Table Of Contents
  195    The following table of contents might look intimidating at first, but some
  196    sections are marked "optional". These sections are not required for a
  197    basic installation as a simple ESMTP server.
  199      • Upgrading an existing installation
  200      • Overview
  201      • Preparing for installation
  202      • OPTIONAL: Install the Socks 5 client toolkit
  203      • Run configure
  204      • IPv6
  205      • Compile and run make check
  206      • Installation
  207      • Install configuration files
  208      • Adjust system paranoia level
  209      • Post-installation setup
  210      • Post-installation checks
  211      • OPTIONAL: Configure webadmin
  212      • Create system aliases
  213      • Create smtp access list
  214      • Backscatter suppression
  215      • Miscellaneous configuration
  216      • Define local domains
  217      • OPTIONAL: Configure UUCP
  218      • OPTIONAL: Configure LDAP aliasing
  219      • OPTIONAL: Enable standard mail filters
  220      • OPTIONAL: Configure custom mail filtering
  221      • Create a list of domains to accept mail for
  222      • Starting and stopping the Courier mail server
  223      • Run the Courier mail server in parallel to your mail server
  224      • OPTIONAL: Configure ESMTP authentication and SSL
  225      • OPTIONAL: Configure ESMTP smarthosting
  226      • OPTIONAL: Configure the SECURITY ESMTP extension
  227      • OPTIONAL: Configure the Sender Policy Framework
  228      • OPTIONAL: Configure the IMAP server
  229      • OPTIONAL: Configure IMAP shared folders
  230      • OPTIONAL: Configure IMAP over SSL
  231      • OPTIONAL: Certificate Authentication
  232      • OPTIONAL: Sending mail via an IMAP connection
  233      • OPTIONAL: Configure IMAP realtime folder status updates
  234      • OPTIONAL: Configure SMAP
  235      • OPTIONAL: Configure the POP3 server
  236      • OPTIONAL: Configure POP3 over SSL
  237      • OPTIONAL: Configure the IMAP/POP3 aggregator proxy
  238      • OPTIONAL: Configure the webmail server
  239      • OPTIONAL: Configure webmail calendaring
  240      • OPTIONAL: Configure mail filtering for the webmail server
  241      • OPTIONAL: Changing mail account passwords using the webmail server
  242      • OPTIONAL: Configure autoreplies for the webmail server
  243      • OPTIONAL: Configure encryption for the webmail server
  244      • OPTIONAL: Install automatically-appended footer text for webmail
  245        messages
  246      • OPTIONAL: Quota support
  247      • OPTIONAL: Account OPTIONS
  248      • OPTIONAL: Configure outbound faxing
  249      • OPTIONAL: Configure inbound faxing
  250      • OPTIONAL: Install the Courier mail server log analyzer
  251      • OPTIONAL: Configure Courier IP address-specific settings for servers
  252        with multiple IP addresses
  253      • OPTIONAL: Configure hostname-dependent configuration
  254      • Decommission your existing mail server
  255      • Sample init script
  257 Upgrading an existing installation
  259   Upgrading from the Courier mail server 1.0.16 or earlier
  261    The IMAP server switched to using the inotify kernel API directly instead
  262    of the legacy FAM/Gamin daemon. When using virtual mail accounts it will
  263    be necessary to increase the kernel's configured limit on the maximum
  264    number of inotify file descriptors, see the IMAP server configuration
  265    notes, below.
  267   Upgrading from the Courier mail server 0.73.1, or earlier
  269    The unicode library in Courier is now a separate package. Download the
  270    Courier Unicode Library before updating to 0.74, or later.
  272   Upgrading from the Courier mail server 0.72, or earlier
  274    Version 0.73 removes the TLS_DHCERTFILE parameter from esmtpd, esmtpd-ssl,
  275    imap, and pop3d configuration files. DH parameters, and DH parameters
  276    only, get read from the new TLS_DHPARAMS file (and the other functionaly
  277    of TLS_DHCERTFILE, for DSA certificates, is merged into TLS_CERTFILE).
  278    After upgrading, run the mkdhparams script to create a new TLS_DHPARAMS
  279    file.
  281   Upgrading from the Courier mail server 0.66.3, or earlier
  283    In 0.67, the IMAP server resets the epoch for an internal sequence number
  284    generator for new mailboxes. This is an internal attribute of individual
  285    IMAP folders, that's defined by the IMAP specification. Each folder in a
  286    mailbox carries an individual sequence number, it is defined as a 32 bit
  287    integer value, and required to be a monotonically increasing value. and
  288    RFC 2060 recommended that "... a good value to use for the unique
  289    identifier validity value is a 32-bit representation of the creation
  290    date/time of the mailbox."
  292    On modern platforms, the system time is now a 64 bit value (even on the
  293    remaining 32 bit platforms). With Y2038K on the horizon, it's time to
  294    reset the epoch (the new epoch, for anyone who cares, runs until the year
  295    2069). The upgrade impact on existing systems is as follows.
  297    There is no impact on existing folders in existing mailboxes. New folders
  298    will have their internal sequence number in the new epoch.
  300    One potential issue exists if a folder gets deleted by the IMAP client,
  301    and then recreated later. The new folder will now get a lower sequence
  302    number. Although this is technically not allowed, it's unlikely to cause
  303    problems with most IMAP clients. If the same IMAP client deletes and
  304    recreated the mailbox, the client should be completely up to speed. If,
  305    however, there's an IMAP client that accesses the same folder, and some
  306    other IMAP client deletes and recreates the same folder, this might cause
  307    confusion. Most IMAP clients are likely to recover automatically; most
  308    IMAP clients only care that the new sequence number they see is different
  309    from the previous one, in order to trigger a full resynchronization with
  310    the server. In case an IMAP client fails to resynchronize, the remedy is
  311    to remove the IMAP account configuration from the client, and add it back
  312    in.
  314    Copying a mailbox by directly copying the files in maildirs preserves each
  315    folder's epoch. However if a mailbox gets migrated by copying its contents
  316    over IMAP, the folders on the destination IMAP server will not necessarily
  317    have a monotonically higher value -- neither does IMAP guarantee that
  318    different IMAP servers must be in agreement with each other on the subject
  319    of sequence numbers -- and if IMAP clients are repointed to a new server
  320    they may experience problems opening existing mailboxes. To remedy this
  321    situation it will be necessary to completely remove and then reconfigure
  322    the IMAP account, in the IMAP client. Again, verbatim copying of maildirs
  323    has no issues.
  325    A marginal situation exists where if a server completely runs of disk
  326    space, or if there's a hardware failure, and the IMAP server is unable to
  327    retrieve or save an existing folder's sequence number, and must now start
  328    afresh and generate a new one, the IMAP server running on a new epoch will
  329    recover with a lower sequence than the one that existed before. The
  330    rememdy is the same: remove the IMAP account configuration from the
  331    client, and then recreate it.
  333   Upgrading from the Courier mail server 0.63.0, or earlier
  335    There's a new setting, SYSLOCALE, in the courierd configuration file,
  336    which initializes the environment from the default system locale. The
  337    configuration script heuristically searches for a list of known locale
  338    initialization scripts on various platforms, if found.
  340    If your platform's locale configuration script's name is not known to the
  341    configuration script, manually specify your default system locale in this
  342    configuration setting.
  344   Upgrading from the Courier mail server 0.55.1, or earlier
  346    The webmlmd tool has been significantly enhanced, with a new
  347    administration screen that consists of three new template files:
  348    style.css.tmpl, webmlmlistadmin.tmpl.html, and
  349    webmlmlistadminpw.html.html. These three template files must be installed
  350    in each mailing list directory. You may copy them manually, or use the
  351    couriermlm update command. couriermlm update overwrites all your
  352    list-specific customizations, so make backups first!
  354   Upgrading from the Courier mail server 0.54.2, or earlier
  356    The logic for outbound authenticated SMTP has changed. This is when the
  357    Courier mail server sends outbound mail through a smarthost that requires
  358    authentication.
  360    The specified smarthost's name is still looked up in DNS, as before. When
  361    smtp.example.com is specified as the smarthost's name, The Courier mail
  362    server looks up any MX or A records for smtp.example.com. A connection
  363    gets established to a server whose name may be different than the original
  364    DNS hostname, if it gets redirected via an MX or a CNAME record.
  366    In earlier versions of the Courier mail server, the smarthost's userid and
  367    password must be listed using the resulting server's physical, resolved
  368    name. Starting with version 0.55, the smarthost's original DNS name must
  369    be listed instead. In all cases now, the name of the server listed in
  370    esmtpauthclient will now match the name specified in esmtproutes.
  372    After updating to 0.55, the contents of the esmtpauthclient configuration
  373    file may need updating.
  375    IMPORTANT: After updating to 0.55, all existing couriermlm mailing list
  376    directories must be updated with new configuration files. See the "update"
  377    command in the "MANUAL COMMANDS" section of the couriermlm(1) manual page.
  378    If you run many mailing lists, you are strongly advised to install the new
  379    version of the Courier mail server on another machine and become
  380    re-acquainted with couriermlm's configuration. In an emergency, make a
  381    backup copy of the couriermlm command from your existing version of the
  382    Courier mail server, before installing this update.
  384   Upgrading from the Courier mail server 0.51, or earlier
  386    Version 2.0 of maildrop, in the Courier mail server 0.52, introduces a new
  387    pattern matching engine that uses the PCRE library, that uses a completely
  388    different syntax. However, very few changes should be required to upgrade
  389    existing maildrop recipes to the new syntax.
  391    After upgrading from the Courier mail server 0.51, or earlier, review the
  392    maildropfilter manual page which has been revised to document the new
  393    pattern matching syntax. The legacy pattern matching engine is still
  394    available by setting MAILDROP_OLD_REGEXP to 1. See also the "Conversion of
  395    maildrop 1.x pattern to 2.0" section in the manual page, for more
  396    information.
  398   Upgrading from the Courier mail server 0.49.0, or earlier
  400    couriermlm's default configuration now treats both the userid and the
  401    domain portion of E-mail addresses as case-insensitive.
  403    Any existing mailing list that has subscribers whose E-mail addresses
  404    contain uppercase addresses must explicitly set the new CASESENSITIVE=1
  405    list option, using the couriermlm command, otherwise those subscribers
  406    will have problems unsubscribing or posting messages to the list.
  408   Upgrading from the Courier mail server 0.48.2, or earlier
  410    The Courier mail server's default configuration now includes backscatter
  411    suppression. Review Backscatter suppression, below, for any needed
  412    configuration changes.
  414   Upgrading from the Courier mail server 0.47, or earlier
  416    Beginning with 0.48, the authentication library that used to be a part of
  417    the Courier mail server's source has been spun off into a standalone
  418    authentication library.
  420    You must download and install the Courier mail server authentication
  421    library from http://www.courier-mta.org/authlib/ before upgrading. Review
  422    the documentation in the courier-authlib package for more information.
  424    As part of installing courier-authlib, the configuration files in the
  425    Courier mail server's configuration directory that relate to
  426    authentication will be copied to courier-authlib's configuration
  427    directory. The files are: authdaemonrc, authmysqlrc, authpgsqlrc,
  428    authldaprc, and userdb (together with the .dist versions). This works only
  429    as long as the Courier mail server was installed in one of the known
  430    default installation directories. The documentation in courier-authlib
  431    explains what to do if the existing version of the Courier mail server is
  432    installed in a non-default location.
  434    In any case, after upgrading to 0.48 these configuration files in the
  435    Courier mail server's configuration directory will no longer be used. To
  436    avoid future confusion the old copies of these configuration files
  437    (including the .dist files), should be removed from the Courier mail
  438    server's configuration directory. They now live in the Courier mail
  439    server-authlib's configuration directory (/usr/local/etc/authlib, or
  440    whatever was specified to the Courier mail server-authlib's configure
  441    script).
  443   Upgrading from the Courier mail server 0.45.4 or earlier
  445    The command to start the webmail server daemon has changed. The system
  446    startup script must be modified to run the new command:
  447    "/usr/lib/courier/sbin/webmaild start". Additionally, this scripts also
  448    starts pcpd, if required. It is no longer necessary to start pcpd by hand.
  450   Upgrading from the Courier mail server 0.44.0 or earlier
  452    Version 0.44.1 introduced an updated webmail implementation. The suid
  453    cgi-bin binary has been replaced by a combination of a stub and a daemon
  454    process. After upgrading to 0.44.1 you will need to modify your system
  455    startup script to run /usr/lib/courier/libexec/courier/sqwebmaild start.
  456    See below for more information.
  458   Upgrading from the Courier mail server 0.42.2 or earlier
  460    After upgrading from the Courier mail server 0.42.2, or earlier, any
  461    existing mail in POP3 mailboxes may show up as new mail, by some mail
  462    clients. This is a one-time event.
  464   Upgrading from the Courier mail server 0.42.0 or earlier
  466    Version 0.43 introduced some functional changes to the LDAP, MySQL, and
  467    PostgreSQL authentication modules. A new DEFAULTDELIVERY setting is added
  468    to each module, incorporating some functionality previously done by the
  469    MAILDIR setting. Previously, MAILDIR served two purposes: 1) define the
  470    default location to the primary mailbox, relative to the account's home
  471    directory, 2) provide default mail delivery instructions, overriding
  472    DEFAULTDELIVERY in the courierd configuration file.
  474    Starting with this version, MAILDIR only specifies the default location
  475    for the primary mailbox, and this setting is now used only by the POP3,
  476    IMAP, and Webmail servers. The new DEFAULTDELIVERY setting specifies the
  477    default mail delivery instructions. Sites that previously used MAILDIR may
  478    now need to copy its setting to DEFAULTDELIVERY.
  480   Upgrading from the Courier mail server 0.34.1 or earlier
  482    Version 0.35 introduced the ability to update system passwords from the
  483    webmail server. If you are using the authuserdb authentication module,
  484    rerun the makeuserdb script after upgrading to 0.35 or later.
  486    Prior to 0.35, the default configuration of the webmail server maintained
  487    a separate webmail password file. The webmail server did not have the
  488    logic to update system login passwords, the approach was to copy system
  489    login passwords into a webmail password file. Changing the webmail
  490    password involved simply updating the webmail password file, and life was
  491    good.
  493    In 0.35, logic was added to update the real system password file, and the
  494    eliminate the webmail password file. After upgrading in 0.35, it will
  495    probably be necessary to reset all mail account passwords on existing
  496    accounts, since the webmail password file is not being used any more, and
  497    most people have probably changed their webmail passwords.
  499    As the result of the password change, the default configuration script
  500    will now always build the authdaemond authentication module by default.
  501    Previously, authdaemond was built by default only if LDAP or MySQL support
  502    was necessary.
  504   Upgrading from the Courier mail server 0.29.1 or earlier
  506    Version 0.30 changed the format of most configuration files. The new
  507    configuration file format allows configuration files to be automatically
  508    upgraded. The automatic upgrade feature requires that both the old and the
  509    new installation have preformatted configuration files. Therefore, when
  510    upgrading from version 0.29.1 or earlier, use the following procedure to
  511    upgrade the existing configuration files.
  513    All configuration files are installed in the same directory, "sysconfdir".
  514    sysconfdir is a configurable parameter, it's usually /usr/lib/courier/etc.
  515    sysconfdir is /etc/courier in the RPM and the DEB version of the Courier
  516    mail server.
  518     Back up your existing sysconfdir
  520    Make a backup copy of your current sysconfdir, then delete the old version
  521    of the Courier mail server. "rm -rf /usr/lib/courier" will do nicely. All
  522    the possible configurable settings are in sysconfdir, everything else can
  523    simply go.
  525     Back up your existing sysconfdir
  527    Make a backup copy of your current sysconfdir. The upgrade process
  528    reinstalls several default configuration files; specifically
  529    sysconfdir/aliases/system and sysconfdir/smtpaccess/default. Any additions
  530    to these files will normally be lost in the upgrade, and can be restored
  531    from the backup afterwards. Don't forget to rerun makealiases and
  532    makesmtpaccess.
  534     Install the new version
  536    Follow the installation procedure in the next section (including the make
  537    install-configure). The following configuration files are now preformatted
  538    for automatic installation:
  540     ldapaddressbook
  541     esmtpd
  542     esmtpd-msa
  543     courierd
  544     pop3d
  545     pop3d-ssl
  546     imapd
  547     imapd-ssl
  548     ldapaliasrc
  549     authldaprc
  550     authmysqlrc
  551     authpgsqlrc
  552     authdaemonrc
  554    NOTE: depending upon your configuration, you may not actually have every
  555    one of these files installed, so just disregard the ones that are not
  556    present. Manually edit filename, and retype any custom modifications from
  557    the backup copy of the configuration file. This is a hassle, but it only
  558    needs to be done once. Future upgrades will be 99% automatic.
  560    Any custom configuration changes are generally confined to these
  561    configuration files only. Very rarely are any configuration changes made
  562    to the remaining configuration files. If necessary, they can simply be
  563    restored from the backup copy made in the previous step. Something to keep
  564    in mind is that future versions may add additional complexity to other
  565    configuration files, resulting in additional configuration files being
  566    reformatted for automatic upgrading.
  568 Overview
  570    You will need the following software in order to compile and install the
  571    Courier mail server:
  573     1. The Courier Unicode Library
  575        The courier-unicode package must be installed and configured prior to
  576        installing the Courier mail server. Download the courier-unicode
  577        package from http://www.courier-mta.org/unicode/.
  579     2. The Courier mail server Authentication Library
  581        The courier-authlib package must be installed and configured prior to
  582        installing the Courier mail server. Download the courier-authlib
  583        package from http://www.courier-mta.org/authlib/.
  585     3. A C++ compiler
  587        The Courier mail server is primarily developed and built with gcc.
  588        Other C++ compiler may or may not work. Solaris's C++ compiler is
  589        reported to work without any problems. There are some issues with
  590        AIX's xlC compiler, which mostly has to do with the C++ libraries and
  591        header files. IBM has released a GNU/Linux development toolkit for
  592        AIX, which may help in getting the Courier mail server to compile.
  594     4. PCRE
  596        The PCRE2 library (http:/www.pcre.org) is required.
  598     5. wget
  600        The wget command must be installed.
  602     6. GNU IDN library
  604        This library (http://www.gnu.org/software/libidn/) implements support
  605        for internationalized domain names.
  607     7. GNU make
  609        On the BSD platform family GNU make is usually installed as gmake.
  610        Simply replace 'make' with 'gmake' in the following instructions. GNU
  611        make is REQUIRED. Use anything else at your own risk.
  613     8. Perl 5
  615        A recent version of Perl needs to be installed.
  617     9. GDBM or Berkeley DB library
  619        Either library must be installed.
  621    10. OpenSSL or GnuTLS
  623        Support for SSL/TLS requires OpenSSL/GnuTLS. All features that require
  624        SSL/TLS are disabled unless OpenSSL or GnuTLS is installed.
  626    11. OpenLDAP
  628        Support for LDAP directory services requires OpenLDAP client libraries
  629        to be installed. If OpenLDAP is not installed LDAP directory features
  630        are disabled. Sometimes there's some confusion when commercial LDAP
  631        servers are used, which come with their own development toolkits,
  632        which use a different API than OpenLDAP. Even if a commercial LDAP
  633        server is used to provide LDAP services, OpenLDAP is still required to
  634        enable LDAP services in the Courier mail server. Also, note that you
  635        need OpenLDAP development libraries and files. On most systems, the
  636        development files are packaged separately, in addition to the runtime
  637        OpenLDAP libraries. Make sure that you have not just the runtime
  638        OpenLDAP libraries installed, but the development libraries as well.
  640        Most of the LDAP support code is already provided by the Courier mail
  641        server authentication library. Some LDAP features, such as LDAP-based
  642        mail aliases, are implemented in the Courier mail server directly.
  643        OpenLDAP client libraries must be installed. If OpenLDAP is not
  644        installed, LDAP directory features are disabled.
  646    12. mgetty+sendfax, groff or troff (not tested), ghostscript, and NetPBM
  648        This optional software is required to send E-mail messages via fax.
  649        The Courier mail server will compile and install without this
  650        software, but you will not be able to send faxes. All packages must be
  651        installed prior to installing the Courier mail server, and binaries
  652        from all packages must be installed in the default PATH before running
  653        the Courier mail server's configure script.
  655        mgetty+sendfax, ghostscript, and groff, are required for basic fax
  656        support, which supports faxing of plain text, Postscript, and
  657        PDF-formatted content. It's probably possible to use the original UNIX
  658        troff instead of groff, but this has not been tested. Installing
  659        NetPBM adds the ability to fax GIF, JPEG, and PNG images.
  661    The typical sequence of commands to install the Courier mail server is as
  662    follows. Read the following section before running these commands:
  664     ./configure [options]
  665     make
  666     make check       # Optional -- see below
  667     make install
  668     make install-configure
  670    These commands are described in greater detail in the following sections.
  672    ══════════════════════════════════════════════════════════════════════════
  674    > If you're using gmake (the make on GNU/Linux, and gmake everywhere
  675    > else), and you are compiling the Courier mail server on a workstation
  676    > with multiple CPUs and plenty of memory, set the following environment
  677    > variable:
  679       MAKEFLAGS="-j 4"; export MAKEFLAGS         # Bourne or Korn shell
  681    > or:
  683       setenv MAKEFLAGS="-j 4"                    # The C shell
  685    > This must be done before running the configure script. This works only
  686    > with gmake.
  688    ══════════════════════════════════════════════════════════════════════════
  690    > The Courier mail server will not work on a Linux kernel that's been
  691    > patched with the Openwall security patch in its default configuration.
  692    > The current version of the Openwall patch has a non-default option that
  693    > turns off the portion of the Openwall patch which prevents the Courier
  694    > mail server from running.
  696    > NOTE: Linux-Mandrake includes the Openwall patch in the alternative
  697    > "secure" kernel package. The Courier mail server will not run on
  698    > Linux-Mandrake under the alternative "secure" kernel. This package must
  699    > be removed and the standard kernel package must be installed.
  701    ══════════════════════════════════════════════════════════════════════════
  703 Preparing for installation
  705    The first step consists of gathering some information about your existing
  706    mail system. Before proceeding, you will need to identify and resolve the
  707    following issues:
  709      • Maildirs or mailbox files
  711    The Courier mail server can be used as a simple mail relay -- which does
  712    not store any mail locally but is merely a gateway between internal and
  713    external mail systems. The Courier mail server can also be used as a
  714    traditional mail server, accepting and storing messages in individual
  715    mailboxes that are accessible via POP3, IMAP, or webmail.
  717    The Courier mail server defaults to storing mail in maildirs, not
  718    traditional flat file mailbox files. Maildirs require less I/O and CPU
  719    resources; they do not use locking; and multiple clients can read and
  720    write from maildirs simultaneously. Maildirs scale very well to servers
  721    with multiple CPUs. Some benchmark numbers on maildirs are available from
  722    http://www.courier-mta.org/mbox-vs-maildir/.
  724    Additionally, The Courier mail server's integrated POP3, IMAP, and
  725    HTTP/webmail servers support maildir mailboxes only. They do not support
  726    mailbox files.
  728    If you have an existing mail server in service, chances are that your
  729    current mail server delivers mail to mailbox files. You should consider
  730    migrating and converting to maildirs, but this will require that you also
  731    upgrade your POP3 server, your IMAP server, and all your other mail
  732    clients to software that supports maildirs. Fortunately, The Courier mail
  733    server already includes a fully integrated POP3 and IMAP server.
  735    Still, if circumstances absolutely require for you to stick with mailbox
  736    files, The Courier mail server has limited compatibility support for
  737    delivering mail to mailbox files, but you have more homework to do:
  739      • What locking mechanism is used on mailbox files
  741    If you decide to stick with mailbox files, you must know - of course -
  742    where your mailboxes are located, and what locking mechanism is being used
  743    by your mail software. Mailbox files require some form of locking, because
  744    only one application can access the mailbox file at the same time.
  745    Unfortunately, different operating systems use different locking methods.
  746    There are several possible locking strategies that can be used: so-called
  747    "dot-locks", or one of three possible kinds of file locking calls. You
  748    will need to consult the documentation for your existing mail software to
  749    determine what locking mechanisms you should use.
  751    In most cases, mailbox files are located in a separate partition, usually
  752    the directory /var/spool/mail. In some instances, mailbox files may be
  753    kept in the home directory of each individual account, and the mail is
  754    delivered to either $HOME/Mailbox, or $HOME/INBOX. Again, you will have to
  755    figure this out by yourself.
  757    The Courier mail server can deliver mail to mailbox files only if the
  758    default mailbox file is in the home directory of each individual account,
  759    and if you use file locking. The Courier mail server does not support
  760    dot-locks, and the Courier mail server does not support a separate mail
  761    directory for mailbox files. Mailbox files must be located in the home
  762    directory of each individual account.
  764    The Courier mail server can use a recipient database (userdb) that can
  765    specify a non-default location for a recipient's mailbox. In theory, it is
  766    possible to point each account to its individual mailbox in
  767    /var/spool/mail, or somewhere else. However, that's a tedious task that
  768    must be done manually for each account, and is likely to be a major
  769    maintenance issue.
  771    A better solution is to use a separate local mail delivery agent. Your
  772    existing mail system is very likely to include a separate local mail
  773    delivery agent. If you already use a mail delivery agent such as procmail,
  774    you probably already have it set to use the correct locking mechanism for
  775    mailbox files, and it already knows where the mailbox files are. The
  776    Courier mail server will be happy to hand off all local mail to procmail,
  777    or anything else for the actual delivery.
  779    The Courier mail server source distribution includes the maildrop mail
  780    delivery agent which has some additional file locking options, however
  781    you'll have less problems if you stick with procmail in the beginning, and
  782    switch to maildrop after you've gained some experience configuring and
  783    installing the Courier mail server.
  785      • Create the courier user and group IDs
  787    You should create a new userid and groupid named "courier". That's
  788    optional, but highly recommended. If this is not done, The Courier mail
  789    server will install as user/group daemon (or some other suitable
  790    user/group id). Only two of the Courier mail server's daemon processes run
  791    as a superuser (and one of them is perpetually waiting for a non-superuser
  792    daemon process to terminate, in order to restart it). Everything else runs
  793    as a non-superuser process. Ideally, you should reserve a separate user
  794    and group ID for the Courier mail server's use only, so a compromised mail
  795    system cannot be used to compromise the rest of the system. If push comes
  796    to shove, you can set up the Courier mail server to use a well-defined
  797    existing user and group ID, such as daemon.
  799      • Define the installation directory
  801    The Courier mail server, by default, installs in /usr/lib/courier.
  802    Everything goes in there: binaries, scripts, configuration files, and
  803    manual pages. You will have to configure your man command to look for
  804    manual pages in /usr/lib/courier/man by adding this directory to the
  805    MANPATH environment variable. You will also need to add
  806    /usr/lib/courier/bin and /usr/lib/courier/sbin (for the root user only) to
  807    the default PATH. The Courier mail server's RPM and DEB packages install a
  808    script that automatically implements that.
  810    Note that this installation layout is nothing more than a basic default,
  811    chosen because this simple arrangement works for everyone. The
  812    installation layout can be easily changed. For example, binaries can go to
  813    /usr/local/bin, and configuration files to /usr/local/etc. But keep in
  814    mind that the Courier mail server consists of several hundred individual
  815    files (at the last count), so if you install the Courier mail server
  816    somewhere else it might be very cumbersome to keep track of where
  817    everything went, and it will lead to almost guaranteed problems later,
  818    when you upgrade.
  820    You should try to use some kind of a packaging system in order to keep
  821    track of your the Courier mail server installation. Once you choose a
  822    packaging system, you should stick to it. If you switch to a different
  823    packaging system you should take extreme care to remove your previous
  824    package, and install your new package. Extreme configuration flexibility
  825    means that different packages will install in different places, and even
  826    have different file ownerships!
  828    For example, The Courier mail server's source code tarball can be built
  829    into a binary RPM package. The binary RPM package installs configuration
  830    files in /etc/courier, the mail queue in /var/spool/courier, and
  831    everything else in /usr/lib/courier. If you install this package, and
  832    later decide to either create your own package or use someone else's, you
  833    will have to make sure to use the same settings, or remove this package
  834    completely, before installing your new package. I mean it when I say
  835    "remove my package completely". That includes the mail queue containing
  836    any unsent messages. The Courier mail server will not function if it's
  837    reinstalled using a different user/group ID, or if you use a different
  838    value for any other option.
  840      • Conclusion
  842    Once these issues are squared away, you are ready to configure and install
  843    the Courier mail server.
  845 OPTIONAL: Install the Socks 5 client toolkit
  847    The Courier mail server has the ability to send outgoing SMTP mail through
  848    a Socks 5 proxy. The Socks 5 proxy option requires a separate module, the
  849    Socks 5 client/server proxy to be installed before installing the Courier
  850    mail server. Download the Socks 5 proxy client library from
  851    http://www.courier-mta.org/download.html#sox and follow its installation
  852    instructions.
  854    > NOTE: Be sure to read the README, NEWS, and INSTALL files in the Courier
  855    > mail server Socks 5 library toolkit, before attempting to install it for
  856    > the first time (unless using the RPM or DEB build method).
  858    Socks proxying must be implemented in relatively low-level manner, and may
  859    not work on all operating systems. This is why it is packaged separately,
  860    in case that it doesn't work. The configure script, described in the
  861    following section, enables Socks 5 support automatically if the Courier
  862    mail server Socks 5 proxy client library is already installed. To make
  863    sure that the library is installed correctly, specify the "--with-socks"
  864    option to the following configure script. This option aborts the configure
  865    script if it does not detect the Courier mail server Socks 5 proxy client
  866    library.
  868 Run configure
  870    After you are squared away with the preliminaries, run the configure
  871    script:
  873    ./configure [ options ]
  875    > NOTE
  877    > You MUST run the configure script as normal user, not root. Did you
  878    > extract the tarball as root? It won't work. Delete everything you have
  879    > just extracted, as root. Log in as a normal user. Extract the source
  880    > code as a normal user, then run configure. You will do everything as a
  881    > normal user, except for the final step of installing the compiled
  882    > software. When you're ready to do a make install, later, su yourself to
  883    > root, and run make install.
  885    The configure script can take a while to complete. There will be more then
  886    thirty separate configuration scripts that will be executed by this
  887    command. To an untrained eye it may seem that the same configuration
  888    script is stuck in a loop; that's because all these configuration scripts
  889    share a lot of code. It may take as much as 15-20 minutes for configure to
  890    finish on a slow machine - even more.
  892    You must have the uux command in your default search path if you intend to
  893    use the Courier mail server to relay mail via UUCP. You may need to modify
  894    your PATH environment variable to include the directory containing uux.
  896    gcc/egcs is officially blessed for building the Courier mail server. In
  897    most cases there's no need to tweak any compiler-specific settings. Note
  898    that there currently may be some unresolved issues with gcc 2.96. gcc 2.91
  899    has been tested and known to work. Occasionally some of your system
  900    libraries may be stuck in some oddball directory that is not searched by
  901    default. Non-standard options for the compiler or linker can be set by
  902    putting them into environment variables. This must be done before running
  903    the configurescript:
  905      • CFLAGS
  907        Additional flags for the C compiler.
  909      • CXXFLAGS
  911        Additional flags for the C++ compiler.
  913      • LDFLAGS
  915        Additional flags for the linker.
  917      • LDADD
  919        Additional libraries to link with. NOTE - everything will be linked
  920        with these libraries.
  922    The complete reference to all configure script options is provided below.
  923    The most important options are:
  925      • --prefix=pathname
  927        Install the Courier mail server in pathname, instead of the default
  928        location of /usr/lib/courier. Note - the examples in the rest of this
  929        text assumes this is where you will install the Courier mail server.
  930        Do not attempt to install the Courier mail server in a directory whose
  931        name contains spaces or punctuation marks. Periods or dashes are fine,
  932        but refrain the temptation to use other, exotic, punctuation.
  934      • --with-db=db or --with-db=gdbm
  936        The Courier mail server requires either the GDBM or the DB database
  937        library. GDBM is used if both are present. This option forces the
  938        selection of the database library.
  940      • --with-locking-method=function
  942        Select a file locking function. Available functions are: fcntl, lockf,
  943        and flock. Not every function is available on every platform. If this
  944        option is not present, configure tries each one, and takes the first
  945        one that works. You can select a specific locking function by using
  946        this option. This affects both the locking used for delivering mail to
  947        mailbox files, and for other kinds of locking that the Courier mail
  948        server uses internally.
  950      • --enable-mimecharset=charset
  952        Specify the default character set the Courier mail server uses when
  953        adding MIME headers to a message. If not specified, us-ascii is used.
  955      • --without-tcpddns
  957        Use this option if you are running a small network without access to a
  958        DNS server. This option will cause couriertcpd to use the system
  959        resolver's gethostby functions instead of issuing DNS queries. Also:
  960        you must initialize the esmtproutes control file with the IP addresses
  961        of all your servers.
  963   configure reference
  965    Here's a comprehensive list of options for the configure script. They are
  966    presented in no particular order. In almost all cases, the configure
  967    script will automatically figure out the correct values, but sometimes it
  968    is necessary to specify them explicitly. If you ever have a need to
  969    manually specify any configuration option, try to determine whether you
  970    need it because of a particular unique case that involves your server
  971    only, or whether it affects any server running your hardware, or system.
  972    In the later case, try to investigate if it's possible for configure to be
  973    a bit smarter and make the right decision.
  975      • --prefix=pathname
  977        Install the Courier mail server in pathname, instead of the default
  978        location of /usr/lib/courier. Note - the examples in the rest of this
  979        text assumes this is where you will install the Courier mail server.
  981      • --exec-prefix=pathname
  983        Specify where the Courier mail server's machine-executable binaries
  984        should be installed. This defaults to the same directory as given by
  985        the --prefix option. There will be three subdirectories created
  986        underneath exec-prefix: bin - user-executable binaries; sbin -
  987        superuser-only binaries; libexec - other binaries that are not
  988        directly invoked from the command line, but are started by other
  989        Courier mail server commands.
  991      • --bindir=pathname, --sbindir=pathname, --libexecdir=pathname
  993        These options override the default value for the corresponding
  994        subdirectory underneath --exec-prefix (see above). The bindir
  995        directory contains programs that can be executed by anyone. sbindir
  996        contains programs that can only be executed by the superuser.
  997        libexecdir contains programs and libraries that cannot be directly
  998        executed from the command line. The default locations are the bin,
  999        sbin, and libexec subdirectories underneath the directory specified by
 1000        exec_prefix.
 1002      • --datadir=pathname
 1004        Specify the directory where miscellaneous shell scripts, Perl scripts,
 1005        and data files will be installed. This option defaults to the
 1006        subdirectory "share" in the directory specified by the --prefix
 1007        option.
 1009      • --sysconfdir=pathname
 1011        Specifies the directory where the Courier mail server's configuration
 1012        files are installed. This option defaults to the subdirectory "etc" in
 1013        the directory specified by the --prefix option.
 1015      • --localstatedir=pathname
 1017        Specify the directory that will hold the mail queue, and other
 1018        temporary data. This option defaults to the subdirectory "var" in the
 1019        directory specified by the --prefix option.
 1021      • --without-ipv6
 1023        Do not compile IPv6 support. IPv6 support, if available is normally
 1024        automatically detected and enabled. Use --without-ipv6 to disable it.
 1025        IPv6 implementations on various platforms is still in flux, and IPv6
 1026        support will not be enabled if the detection logic fails. Use
 1027        --with-ipv6 in order to fail the configuration stage if IPv6 is not
 1028        detected, instead of silently continuing with IPv4 support only. See
 1029        "IPv6" below for more information.
 1031      • --with-db=db or --with-db=gdbm
 1033        The Courier mail server requires either the GDBM or the DB database
 1034        library. GDBM is used if both are present. This option forces the
 1035        selection of the database library.
 1037      • --with-locking-method=function
 1039        Select a file locking function. Available functions are: fcntl, lockf,
 1040        and flock. Not every function is available on every platform. If this
 1041        option is not present, configure will choose the first locking
 1042        function that's available. You can select a specific locking function
 1043        by using this option. This affects both the locking used for
 1044        delivering mail to mailbox files, and for other kinds of locking that
 1045        the Courier mail server uses internally.
 1047      • --enable-mimecharset=charset
 1049        Specify the default character set the Courier mail server uses when
 1050        adding MIME headers to a message. If not specified, us-ascii will be
 1051        used.
 1053      • --without-tcpddns
 1055        \Use this option if you are running a small network without access to
 1056        a DNS server. This option will cause couriertcpd to use the system
 1057        resolver's gethostby functions instead of issuing DNS queries. Also:
 1058        you will have to initialize the smtproutes control file with the IP
 1059        addresses of all your servers.
 1061      • --without-explicitsync
 1063        Normally the Courier mail server will automatically sync, or flush out
 1064        all file buffers to disk, at certain key points in order to try to
 1065        minimize the extent the mail queue can get corrupted if the system
 1066        crashes. If the mail queue is installed on a reliable disk array or a
 1067        network file server, this may not be necessary, and will only serve to
 1068        slow down the mail delivery. Use this option to turn off syncing.
 1070      • --with-dirsync
 1072        Also explicitly sync the parent directory. There's a school of thought
 1073        which believes that the Linux ext2 filesystem requires the parent
 1074        directory to also be synced, in addition to the new message file
 1075        that's just been written to disk. There's another school of thought
 1076        that thinks that this issue is completely blown out of proportion, and
 1077        is really nothing more than a tempest in a teapot. However -- to
 1078        accomodate the former school of thought -- this option adds a little
 1079        bit of extra code to sync the parent directory.
 1081      • --with-shellpath=path
 1083        Specify the contents of the PATH environment variable that is
 1084        inherited by custom programs started by the Courier mail server to
 1085        deliver messages. If not specified, PATH will be set to
 1086        /bin:/usr/bin:/usr/local/bin.
 1088      • --disable-local-extensions
 1090        Normally, in addition to accepting mail that's addressed to
 1091        <user@domain.com>, The Courier mail server can accept mail that's
 1092        addressed to <user-xxx@domain.com>, for arbitrary values of xxx. In
 1093        order for that to happen the user has to create a special file with
 1094        delivery instructions. See the dot-courier(5) manual page for more
 1095        information. This option disables this feature.
 1097      • --with-paranoid-smtpext
 1099        Be paranoid when negotiating the Courier mail server-specific ESMTP
 1100        extensions with remote servers. The Courier mail server defines and
 1101        implements certain experimental ESMTP extensions: XVERP and XEXDATA.
 1102        Problems may result in the event that someone else uses the same name
 1103        to implement some other extension. If this option is specified, The
 1104        Courier mail server's ESMTP server will also advertise a dummy ESMTP
 1105        capability called XCOURIEREXTENSIONS, and will not recognize any the
 1106        Courier mail server-specific extensions unless the remote mail server
 1107        also advertises this dummy ESMTP capability.
 1109      • --enable-workarounds-for-imap-client-bugs
 1111        There are several confirmed bugs in some IMAP clients that do not
 1112        properly implement the IMAP4rev1 protocol. This option enables some
 1113        workarounds for those buggy IMAP clients. NOTE: make check will fail
 1114        if this option is used. You should first configure without this
 1115        option, and if all post-configuration tests succeed, rerun configure
 1116        with this option and recompile.
 1118      • --with-qdircount=n
 1120        Set n to be the number of mail queue subdirectories. In order to
 1121        improve the speed of access to the mail queue, messages are stored in
 1122        subdirectories, hashed by the message queue number. n specifies how
 1123        many subdirectories will be created. If this option is not specified,
 1124        100 subdirectories will be used. WARNING: once you've installed the
 1125        Courier mail server once, if you decide to reconfigure and reinstall,
 1126        you MUST use the same subdirectory count (by default, or explicitly),
 1127        otherwise you'll end up with a big mess on your hands if you have ANY
 1128        messages in the mail queue. If you need to change this option, wait
 1129        for all messages in the queue to be flushed out, and reinstall with an
 1130        empty mail queue.
 1132      • --with-random=/dev/path, --without-random
 1134        Sometimes the Courier mail server sometimes needs a good source of
 1135        random noise. If configure finds /dev/urandom, it will use that. If
 1136        your random device is named otherwise, specify it using this option.
 1137        If you don't want to use a random device, specify --without-random,
 1138        and the Courier mail server will generate some noise on its own. The
 1139        Courier mail server will generate noise based on the output of a
 1140        random ps command, and several other, hopefully unpredictable,
 1141        sources.
 1143      • --with-gnutls - Use the GnuTLS library even if the OpenSSL library is
 1144        also installed. The Courier mail server automatically uses whichever
 1145        one is available. The OpenSSL library is selected if both are present.
 1146        Use this option to override and select GnuTLS instead.
 1147      • --without-certdb
 1149        Do not install a default set of trusted X.509 root CA certs (in order
 1150        to validate the remote server's X.509 certificate). See "Configure
 1151        ESMTP authentication and SSL" for more information.
 1153      • --with-certdb=pathname
 1155        Do not install the default set, but put pathname as the default
 1156        location of the root CA database, into the configuration file. This is
 1157        a convenient option to have the Courier mail server use an external,
 1158        previously installed, root CA database.
 1160      • --with-certsdir=pathname
 1162        Set up configuration files and scripts that reference the server's SSL
 1163        certificates to use the pathname directory, instead of the directory
 1164        specified by the --datadir option. Scripts that create temporary
 1165        self-signed certificates to be used for testing (mkimapdcert,
 1166        mkpop3dcert, et. al.) install the generated certificate in this
 1167        directory, and it's referenced from the corresponding configuration
 1168        files.
 1170      • --with-waitfunc=wait, --with-waitfunc=wait3
 1172        Specify the system call to use to asynchronously reap child processes.
 1173        This is a sticky one, because the behavior of the wait and wait3
 1174        system calls varies greatly depending on the level of each individual
 1175        system's POSIX compliance. The configure script will attempt to
 1176        compile and run some test programs in order to attempt to figure out
 1177        which system call actually works. If the configure script fails, or if
 1178        it selects a wrong function (which will be evident when mail delivery
 1179        stops, and you have a bunch of zombies that are not being reaped), you
 1180        might have to manually specify it using either option. In that case,
 1181        however, you should also examine the test programs, investigate what
 1182        went wrong, and patch the test programs to give a correct result for
 1183        your system.
 1185      • --without-ispell, --with-ispell=program
 1187        The Courier mail server's webmail server can use spell checking, if
 1188        the ispell program is available (aspell can be used too). If configure
 1189        finds ispell, spell checking is enabled. Use --without-ispell to
 1190        forcefully disable spell checking. If ispell is not in the current
 1191        search path, use --with-ispell=program to explicitly set the location
 1192        of ispell. See "Configure the webmail server" for more information on
 1193        ispell or aspell.
 1195      • --enable-imageurl=/url
 1197        Use /url/ as the URL to the static images displayed by the webmail
 1198        server. HTML pages are dynamically generated by the webmail server
 1199        CGI, but they also include some static icons. The webmail CGI will use
 1200        /url as the URL to the directory containing the static images. The
 1201        default URL is "/webmail", which means that the static images must be
 1202        installed in the <DocumentRoot>/webmail directory. This is a manual
 1203        process that is described in more detail in the "Configure the webmail
 1204        server" section, below.
 1206      • --enable-https, --enable-https=login, --enable-https=auto
 1208        If you have an SSL-enabled web server, use the --enable-https option
 1209        in order to configure webmail access for SSL. Use --enable-https=login
 1210        in order to use SSL only when logging in, to send the password. Use
 1211        --enable-https=auto to generate relative URLs, so that users can
 1212        connect with either http or https and their session will remain that
 1213        way.
 1215        --enable-https=login and --enable-https=auto require that your http
 1216        and https URLs that refer to the webmail CGI be identical (which is
 1217        the usual default).
 1219        --enable-https=auto is the default. Use --disable-https if you need to
 1220        completely disable https, for some reason.
 1222      • --enable-hardtimeout=7200
 1224        set the hard timeout for webmail sessions (in seconds). The default is
 1225        2 hours. webmail sessions are unequivocally logged out after the
 1226        indicated time interval.
 1228      • --enable-softtimeout=1200
 1230        set the inactivity timeout for webmail sessions (in seconds). The
 1231        default is 20 minutes. webmail sessions are logged out if there's no
 1232        activity for the indicated time interval.
 1234      • --with-defaultlang=lang
 1236        reserved for future use.
 1238      • --enable-mimetypes=file:file:file
 1240        this is a colon-separated list of all of your mime.types files. The
 1241        mime.types configuration files are used to map file extension to their
 1242        corresponding MIME content types. The configuration script will look
 1243        in several directories where mime.types usually exists. You can use
 1244        this option to explicitly specify a list of mime.types files to be
 1245        used, instead of the default.
 1247      • --enable-bannerprog=pathname
 1249        advanced option that sets a banner program that the webmail server
 1250        will execute. This program should print HTML, on standard output, to
 1251        generate a typical banner.
 1253      • --with-maxargsize=bytes,--with-maxformargsize=bytes
 1255        Sets an upper limit on the size of CGI arguments for the webmail
 1256        server. Normally there's no reason to modify the defaults (500,000 and
 1257        2,000,000 bytes). The latter is generally the maximum allowed size of
 1258        an attachment. The former is generally the maximum allowed size of the
 1259        typed message. These settings can also be adjusted at runtime. See
 1260        Maximum message size, below.
 1262      • --with-maxmsgsize=bytes
 1264        Sets the upper limit of messages composed in the webmail server, the
 1265        main text and all the attachments. This setting can also be adjusted
 1266        at runtime. See Maximum message size, below.
 1268      • --with-cachedir=dir, --with-cacheowner=userid
 1270        The webmail server uses a cache of currently active logins. The
 1271        webmail server binary, is executed for each and every HTTP request,
 1272        and the user's maildir needs to be quickly located each time. Because
 1273        hitting the authentication module can be expensive (think
 1274        MySQL/PostgreSQL/LDAP query for every HTTP request!) the webmail
 1275        server will cache this information in order to avoid having your
 1276        authentication server brought down to its knees. By default, the
 1277        directory /usr/lib/courier/var/webmail-logincache will be used, owned
 1278        by the bin user. These options can be used to specify a different
 1279        location for the webmail login cache directory.
 1281        If you'll be using the webmail server, you MUST add an hourly cron job
 1282        to run the /usr/lib/courier/share/sqwebmail/cleancache.pl script which
 1283        deletes expired cache records from the cache directory. Add the
 1284        following command to be executed from cron at least once an hour:
 1286  su -c "/usr/lib/courier/share/sqwebmail/cleancache.pl" bin
 1288        (This assumes that your cache directory is owned by the bin user).
 1289        There's no need to set up this cron job if the webmail server is not
 1290        used. NOTE: your su command may use different options or syntax, check
 1291        the su manual page to confirm the correct syntax.
 1293      • --without-gzip
 1295        if the configuration script finds the gzip utility, the webmail server
 1296        will automatically use gzip compression for some large web pages (if
 1297        the client browser supports gzip compression). Use this option to turn
 1298        off gzip compression.
 1300      • --disable-autorenamesent
 1302        do not rename the Sent folder every month. This option can also be
 1303        controlled by the SQWEBMAIL_AUTORENAMESENT environment variable (which
 1304        can be set in Apache's httpd.conf, for example). This setting gives
 1305        the initial configuration, that can be individually adjusted in the
 1306        Preferences screen.
 1308      • --with-calendarpurge=N
 1310        if calendaring is enabled, purge expired calendar events after N days
 1311        (default: 30).
 1313      • --with-trashquota
 1315        include deleted messages, and the Trash folder, in the estimated quota
 1316        usage for maildirs. Quotas are optional, see the file
 1317        maildir/README.maildirquota.html for more information. The default
 1318        configuration does not count messages marked as deleted (but not yet
 1319        expunged) and the contents of the Trash folder (which are
 1320        automatically purged by the server) against the quota usage. NOTE - if
 1321        this option is used, make check WILL FAIL. You should first configure
 1322        the Courier mail server without this option, run make check, then
 1323        reconfigure the Courier mail server with this option.
 1325 IPv6
 1327    IPv6 support in the Courier mail server means basically the following:
 1329      • ESMTP, IMAP, and POP3 servers will create an IPv6 socket and accept
 1330        IPv6 connections.
 1331      • The ESMTP client will attempt to resolve AAAA records in addition to A
 1332        records.
 1333      • Headers in incoming mail will log IPv6 addresses, instead of IPv4
 1334        addresses. Delivery Status Notifications and log files will also
 1335        reflect IPv6 addresses.
 1337    IPv6 implementations are required to accept IPv4 connections on IPv6
 1338    sockets, so IPv6 sockets should be able to receive both IPv4 and IPv6
 1339    connections. In the event that your IPv6 implementation is not stable, or
 1340    is partially incomplete, IPv6 support in the Courier mail server should be
 1341    disabled.
 1343    The configuration script will attempt to detect whether IPv6 structures
 1344    and functions are available, and automatically enable IPv6 support if they
 1345    are found. The --without-ipv6 option disables IPv6 support, which may be
 1346    desired for the following reasons:
 1348      • The IPv6 implementation on your platform is incomplete.
 1349      • The IPv6 implementation on your platform is actually not available,
 1350        despite the presence of IPv6 structures and functions. Most GNU/Linux
 1351        distributions ship without IPv6 support enabled in the default kernel
 1352        build. The Courier mail server automatically falls back to creating an
 1353        IPv4 socket, if it can't create an IPv6 socket, so things should
 1354        continue to work in that case. However, each such attempt is likely to
 1355        result in an error message logged to /var/log/messages -- modprobe is
 1356        whining that it can't find an IPv6 module to load. On systems that
 1357        handle a large amount of traffic the log files can fill up rather
 1358        quickly.
 1359      • Implementing IPv6 can increase the amount of DNS traffic, even if
 1360        there is no IPv6 support in the kernel. Even if the Courier mail
 1361        server falls back to IPv4 sockets, it will continue to resolve IPv6
 1362        addresses, resulting in some extra DNS queries. There won't be a lot
 1363        of extra DNS queries, but there will be some. Also, there are still
 1364        some DNS servers that cannot correctly handle IPv6 queries, and
 1365        attempts to deliver mail to these domains will fail despite the
 1366        presence of valid IPv4 records.
 1368    IPv6 support is still a bit spotty in some places. If the configuration
 1369    checks fail, IPv6 support will be quietly suppressed. If you expect IPv6
 1370    support to be present, the --with-ipv6 flag can be used to abort
 1371    configuration if IPv6 support was not detected.
 1373 Compile and run make check
 1375      make
 1376      make check
 1378    If the configure script ran without errors, run make to build the Courier
 1379    mail server. If make completes succesfully, run make check. make check
 1380    runs some simple internal tests. It is not feasible to run a complete
 1381    check of the Courier mail server's behavior, but make check does
 1382    automatically run some tests on several modules.
 1384    If make check fails, you need to do some detective work. Investigate the
 1385    source of the failure. It is possible that the issue can be resolved by
 1386    specifying different options to the configure script, in which case you
 1387    have to go back and rerun the configure script again.
 1389 Installation
 1391    su yourself to root, if you want to do a live install, then run make
 1392    install or make install-strip to install the Courier mail server. If you
 1393    use the GNU version of make, and you would like to see which files the
 1394    Courier mail server installs and where, don't su yourself to root, but set
 1395    the make variable named DESTDIR. For example:
 1397    make install DESTDIR=/var/tmp/courier-inst
 1399    The contents of DESTDIR are prepended to the name of every file installed,
 1400    so if --prefix was set to /usr/lib/courier, the files will be installed in
 1401    /var/tmp/courier-inst/usr/lib/courier. This only works if you use GNU
 1402    make.
 1404    NOTE: you must make sure that your umask is 022 before you run make
 1405    install.
 1407    If executed by root, make install automatically sets the correct ownership
 1408    on the installed files. Non-root make installs do not set the ownership,
 1409    but still set correct permissions. This feature is mainly for use by
 1410    people who are rolling the Courier mail server into a prebuilt package,
 1411    since this allows them to build the package as a normal user, not root. In
 1412    this situation the command make install-perms will be very useful. This
 1413    command creates a file called permissions.dat. This file contains a
 1414    complete listing of everything that will be installed, and what the
 1415    correct permissions are on every file.
 1417    make install installs the Courier mail server binaries with debugging
 1418    data, which is probably a good idea to do while the Courier mail server is
 1419    in development. Use makeinstall-strip to install binaries without
 1420    debugging data. Some systems have a broken install utility, so make
 1421    install-strip may fail.
 1423 Install configuration files
 1425    The following command creates and updates configuration files. It must be
 1426    executed after running make install:
 1428    make install-configure
 1430    This command copies each configuration file "filename.dist" to "filename".
 1431    The existing filename is backed up as filename.bak. If upgrading from the
 1432    Courier mail server 0.30 or later, the previous configuration settings in
 1433    filename.bak will be automatically copied to filename, provided that they
 1434    are still valid. If a configuration setting may no longer be valid, it
 1435    will be reset to its default value. The output of make install-configure
 1436    will indicate the status of each configuration setting, therefore it is
 1437    advistable to save the output to a file, and examine it:
 1439    make install-configure >upgrade.log
 1441    Versions prior to 0.30 cannot have their configuration settings
 1442    automatically preserved, and must be restored manually from filename.bak.
 1443    Do not simply copy filename.bak to filename, this will lose all the
 1444    formatting codes that allow automatic upgrades.
 1446   PAM configuration
 1448    If you use PAM library for authentication, you may need to set up PAM for
 1449    authenticating POP3 logins, IMAP logins, webmail logins, and/or ESMTP
 1450    authentication. In most cases, all you have to do is install
 1451    /usr/lib/courier/etc/pop3d.authpam as /etc/pam.d/pop3,
 1452    /usr/lib/courier/etc/imapd.authpam as /etc/pam.d/imap,
 1453    /usr/lib/courier/etc/webmail.authpam as /etc/pam.d/webmail, and
 1454    /usr/lib/courier/etc/esmtp.authpam as /etc/pam.d/esmtp. However you will
 1455    have to consult your PAM documentation, and the manual pages for authpam,
 1456    in order to make sure.
 1458    Some versions of the PAM library, do not use the /etc/pam.d directory.
 1459    Instead they use a single configuration file /etc/pam.conf. Here's an
 1460    example of what needs to be added to /etc/pam.conf on FreeBSD 4.0. NOTE:
 1461    other platforms may need something similar:
 1463  imap  auth    required        pam_unix.so      try_first_pass
 1464  imap  account required        pam_unix.so
 1465  imap  session required        pam_permit.so
 1466  pop3  auth    required        pam_unix.so      try_first_pass
 1467  pop3  account required        pam_unix.so
 1468  pop3  session required        pam_permit.so
 1469  esmtp auth    required        pam_unix.so      try_first_pass
 1470  esmtp account required        pam_unix.so
 1471  esmtp session required        pam_permit.so
 1473   Building RPM and DEB packages
 1475    NOTE: If an RPM or a DEB package gets built as per this INSTALL file
 1476    resulting packages may not install if you have an existing IMAP or an
 1477    existing POP3 server installed. The RPM packages will contain these PAM
 1478    configuration files, and they will conflict with any PAM configuration
 1479    files installed by another IMAP or POP3 server. If you manually installed
 1480    an IMAP or a POP3 server without creating a distribution package, the
 1481    Courier mail server package will install and the old configuration files
 1482    will get silently removed, since they were not installed using rpm or
 1483    dpkg.
 1485    The Courier mail server includes integrated POP3, IMAP, and webmail
 1486    servers, however they only work with maildirs. Decide if you want to keep
 1487    using your current server, or switch to the Courier mail server's
 1488    IMAP/POP3/webmail servers. If you want to keep your existing servers, back
 1489    up the contents of your /etc/pam.d directory before installing the RPM or
 1490    the DEB package, install it, then restore the overwritten files. If you
 1491    want to switch to the Courier mail server, blow away your current server
 1492    before running make install.
 1494 Adjust system paranoia level
 1496    There are four setuid binaries in the Courier mail server that are owned
 1497    by root: sendmail, maildrop, webmail and webadmin. There's also one setgid
 1498    binary, sqwebpasswd.
 1500    /usr/lib/courier/bin/maildrop is the mail filter. If you do not need mail
 1501    filtering, you can remove it. The setuid root privilege is only needed to
 1502    implement mail filtering "on the wire", when receiving mail from an
 1503    external mail relay (see localmailfilter(7) for more information).
 1504    Removing the setuid root bit still allows traditional mail filtering to be
 1505    used, after the message is received and delivered to the mailbox.
 1507    /usr/lib/courier/libexec/courier/webmail/webmail is the webmail CGI. It is
 1508    executed by the web server, and needs to change its userid/groupid, in
 1509    order to enter the maildir. If you do not need webmail access, you can
 1510    remove it. An alternative is to implement virtual mailboxes, owned by a
 1511    non-privileged userid, and change the ownership of the webmail CGI to the
 1512    non-privileged user (you will also need to use the --with-cacheowner
 1513    option to the configure script since the webmail process must have write
 1514    access to the webmail login cache directory).
 1516    /usr/lib/courier/libexec/courier/webmail/webadmin is the wrapper for the
 1517    web-based administration tool. See below for more information.
 1519    /usr/lib/courier/bin/sendmail is the command line mail sender. Its first
 1520    order of business is to set its group id to the Courier mail server's
 1521    group id, and restore the original userid, dropping root. The reason that
 1522    it needs root setuid is to set its real group id, because setting the
 1523    setgid bit on the executable is not enough. The setgid bit sets only the
 1524    effective group id, and the root setuid bit is required to set both
 1525    effective and real group ids. Both real and effective group IDs are needed
 1526    in order to be able to implement maildrop mail filtering.
 1528    /usr/lib/courier/libexec/courier/sqwebpasswd is described in detail in the
 1529    "OPTIONAL: Changing mail account passwords using the webmail server"
 1530    section.
 1532 Post-installation setup
 1534    A first-time the Courier mail server installation may not require the
 1535    system startup scripts to be modified to start the Courier mail server at
 1536    system boot. Until the system's functionality is verified, the system will
 1537    probably continue to use the existing mail server. Still, most the Courier
 1538    mail server configurations will require two things to be started before
 1539    any part of the system is put to use:
 1541      • An hourly cron job needs to be created to run the cleancache.pl
 1542        script, which purges expired webmail login cache records. Logging in
 1543        to the mail account via the web creates a file in a temporary
 1544        directory that caches the login session identity. The output of make
 1545        install includes the command that needs to be set up as a cron job by
 1546        root. The cron job runs su to change to the userid that owns the login
 1547        cache directory, then runs the purge script. The su command on some
 1548        system uses a slightly different syntax than what's shown by make
 1549        install. It may be necessary to consult the su man page before setting
 1550        up the cron job. Run the su command as root, to make sure that its
 1551        syntax is correct, before setting up the cron job. The cron job can be
 1552        omitted if webmail is not going to be used.
 1553      • Run the mkdhparams script to create the DH parameter file. A monthly
 1554        job should also be created to run the mkdhparams script, in order to
 1555        periodically generate a new set of DH parameters. DH parameters are
 1556        used to set up encrypted connections.
 1558 Post-installation checks
 1560    The following tests should be run to verify that your installation works
 1561    properly. These tests are not really comprehensive tests, they only make
 1562    sure that the basic functionality is there, and they definitely must be
 1563    done the first time you install a version of the Courier mail server on
 1564    your system. If you later reinstall the same version on the same platform,
 1565    using the same configuration, you don't need to run these installation
 1566    checks (but you better be sure that the reinstallation is COMPLETELY
 1567    identical to the original install). You might also wish to rerun these
 1568    installation checks after upgrading your base operating system.
 1570    The following documentation assumes that the Courier mail server is
 1571    installed in /usr/lib/courier.
 1573   Verify module installation
 1575    Run the showmodules utility after all files have been installed, but
 1576    before you attempt to start the Courier mail server. The showmodules
 1577    utility attempts to load and initialize transport modules that have been
 1578    configured, without actually starting up the Courier mail server. Running
 1579    showmodules should result in something that looks like this:
 1581     showmodules[5060]: Loading STATIC transport module libraries.
 1582     showmodules[5060]: Installing i586-gnu-linux [0/0]
 1583     showmodules[5060]: Installing local
 1584     showmodules[5060]: Installed local
 1585     showmodules[5060]: Installing esmtp
 1586     showmodules[5060]: Installed esmtp
 1587     showmodules[5060]: Installing dsn
 1588     showmodules[5060]: Installed dsn
 1589     showmodules[5060]: Initializing local
 1590     showmodules[5060]: Initializing esmtp
 1591     showmodules[5060]: Initializing dsn
 1593   Test child process termination
 1595    In this test, you will start the Courier mail server, then attempt to
 1596    rapidly pump through as many messages as fast as possible, to verify that
 1597    asynchronous child process termination handling works. For this test (and
 1598    the following tests) you need to use a test account.
 1600    Log on to the test account and run maildirmake to create two maildirs:
 1601    maildirmake $HOME/test, and maildirmake $HOME/bounces.
 1603    Create $HOME/.courier-test-default, containing one line: ./test. Create
 1604    $HOME/.courier, containing one line: ./bounces. If you previously selected
 1605    .qmail compatibility, you will need to use .qmail-test-default and .qmail,
 1606    of course. Keep that in mind as you work through the remaining tests.
 1608    Start the Courier mail server as root:
 1610    /usr/lib/courier/sbin/courier start
 1612    Check your system log files for any error messages. Run the ps command,
 1613    and check that you only have the following processes running: courierd
 1614    (two processes), courierdsn, courieruucp, courieresmtp, and courierlocal.
 1615    You will also have a couple of "logger" processes hanging around, that's
 1616    ok too.
 1618    One of the two courierd processes will be running as root. The
 1619    courierlocal process will also be running as root. All other processes
 1620    will be running as the courier (or daemon, or mail) user. courieruucp may
 1621    be running as uucp.
 1623    Run the perftest1 script, which can be found in the directory containing
 1624    the Courier mail server's source code:
 1626  sh perftest1 1000 "user-test-1 user-test-2 user-test-3 user-test-4 user-test-5"
 1628    Run this script while logged on to the test account. Replace "user" with
 1629    the name of your test account. This will send 1000 messages with five
 1630    recipients per message. You should end up with exactly 5000 messages in
 1631    $HOME/test/new. Count them.
 1633    Monitor the system logs. There will be a lot of activity. On my test
 1634    system, the system logger usually backs up. The Courier mail server
 1635    generates log messages faster than the logger can record them. When all
 1636    the activity stops, count how many files you have in $HOME/test/new. For
 1637    extra credit, total up the Delivered-To: headers in all the messages,
 1638    there should be 1000 headers for each one of the five addresses.
 1640    If you did not get 5000 messages, and mailq comes up empty, check
 1641    $HOME/bounces/new. If you're lucky, the rest bounced. That's still a
 1642    problem, but the bounces will help you to investigate things further.
 1644    If you did not get 5000 messages, and mailq shows some messages remaining
 1645    in the queue, and ps shows some dead zombie processes that are not being
 1646    reaped, this means that asynchronous process termination is not working.
 1647    You will need to examine your configuration to see whether configure
 1648    selected the wait or the wait3 function. Unpack the source code again and
 1649    rerun configure. This time use the --with-waitfunc option to choose the
 1650    other wait function, manually. Recompile, reinstall, and rerun this test.
 1652    If you did get all the messages, go through your syslog for extra-extra
 1653    credit. grep it for the word "defer" to see if any messages required
 1654    multiple delivery attempts. This shouldn't happen either.
 1656    If your hardware has enough juice to pump through 5000 messages in a short
 1657    period of time, rerun this test with a larger number of messages. Before
 1658    doing that, wipe the Maildirs clean, in order to confirm the message
 1659    count, later. The test must run for at least 3-4 minutes in order to get
 1660    meaningful results.
 1662   User/group ID check
 1664    For this test you will need to use or create a regular user test account,
 1665    which will be referred to as user. You can use the same test account you
 1666    used in the last test, but erase all .courier (or .qmail) files.
 1668    In user's home directory, create .courier which contains the following
 1669    text:
 1671  | /usr/bin/id >ID
 1672  | /usr/bin/env >ENV
 1674    Make sure that your id and env commands are in /usr/bin. If not, use the
 1675    correct path.
 1677    Send a single message to user:
 1679    echo "To: user" | /usr/lib/courier/bin/sendmail
 1681    Thie message will disappear into the never-never land, so don't waste time
 1682    looking for it. Just examine, very closely, the contents of the ID and the
 1683    ENV files in user's home directory. Double check what user and the group
 1684    ids recorded in ID match user's. Pay close attention to any auxiliary
 1685    group IDs, make sure that they haven't "leaked" from the root user who
 1686    started the Courier mail server.
 1688    Also, examine the environment, in ENV. Check the manual page for
 1689    dot-courier, ENV should contain only the documented environment variables,
 1690    and any environment variables that are defined in the
 1691    /usr/lib/courier/etc/courierd file.
 1693 OPTIONAL: Configure webadmin
 1695    This is a web-based administration tool. webadmin is a web CGI
 1696    application. It is necessary to have a local web server installed in order
 1697    to use webadmin. Apache will do, but so will any other server with a
 1698    complete CGI implementation (PHP is not required). Installing webadmin is
 1699    a three step process:
 1701     1. Move /usr/lib/courier/libexec/courier/webmail/webadmin to your web
 1702        server's SSL cgi-bin directory.
 1704     2. Add the following command to your system startup script:
 1706  /var/www/cgi-bin/webadmin daemon &
 1708        (or the actual cgi-bin directory). Executing the cgi-bin webadmin with
 1709        a "daemon" parameter starts the daemon process.
 1711        It might be useful to manage webadmin with courierlogger: using
 1712        "courierlogger -pid=/usr/lib/courier/var/webadmin.pid -start
 1713        .../webadmin daemon" to start webadmin and "courierlogger
 1714        -pid=/usr/lib/courier/var/webadmin.pid -stop" to stop it.
 1716     3. Execute "make install-webadmin-password". This prompts for a password,
 1717        which is saved in the file /usr/lib/courier/etc/webadmin/password.
 1719     4. Edit "/usr/lib/courier/etc/webadmin/restartcmd", this file contains
 1720        one line, a command that webadmin runs to restart courier. This
 1721        defaults to "courier restart". If Courier gets set up to run under
 1722        systemd this should be changed to like:
 1724  systemctl restart courier.service &
 1726        ... or try-restart. It is important to use & to run systemctl in the
 1727        background. webadmin uses this as an indication for proper signal
 1728        handling setup. webadmin blocks signals when installing an updated
 1729        configuration, but commands executed in the background have their
 1730        signal handling reset to default. systemd will signal processes to
 1731        terminate when restarting them. webadmin's blocked signals permit it
 1732        to finish installing any remaining updates. systemctl will wait for
 1733        the restart to finish, but it's part of the service that's getting
 1734        restarted, so this process needs to run in a background, with default
 1735        signal handling so that systemctl itself gets terminated.
 1737     5. Edit "/usr/lib/courier/etc/webadmin/restartauthcmd", this file
 1738        contains one line, a command that webadmin runs to restart the Courier
 1739        authentication library service. This defaults to "authdaemond
 1740        restart". If courier-authlib gets set up to run under systemd this
 1741        should be changed to an "systemctl restart", or maybe "systemctl
 1742        try-restart", for example: systemctl try-restart
 1743        courier-authlib.service.
 1745     6. The web server SHOULD be configured to run webadmin from the cgi-bin
 1746        directory using SSL only. webadmin's authentication is rather simple:
 1747        the password is saved in a cookie. Unless SSL is used, the webadmin
 1748        password can be intercepted in transit. If SSL is not available, an
 1749        acceptable level of security can be achieved by setting up a firewall
 1750        that allows web access only from trusted IP addresses, then use a
 1751        dedicated webadmin password. This is not perfect, but is generally
 1752        adequate. A firewall is a good idea even if SSL is used. This is not
 1753        Fort Knox, and webadmin is not going to be publicly accessible, so the
 1754        only needed security is to keep everyone out except for authorized IP
 1755        addresses.
 1757        Note that webadmin, by default, will enforce this restriction: either
 1758        SSL, or access from a local IP address. Create an empty file
 1759        /usr/lib/courier/etc/webadmin/unsecureok to allow non-SSL webadmin
 1760        connections from remote IP addresses. Alternative, the unsecuredok
 1761        file may consist of a single line with one or more IP addresses,
 1762        separated by spaces. Non-SSL access will get accepted from these IP
 1763        addresses only:
 1765  echo >unsecuredok
 1767    webadmin is designed to be self-explanatory. Configuration options are
 1768    divided into logical sections. Changes made to configuration options do
 1769    not take effect immediately. To apply configuration changes, select
 1770    "Install new configuration" from the main menu. To cancel all changes
 1771    made, select "Cancel new configuration". Selecting "Install new
 1772    configuration" will apply all the changes to the configuration files, and
 1773    restart any the Courier mail server modules that must be restarted in
 1774    order for the changes to take effect.
 1776    If you decide to use webadmin, most of the remaining steps in this INSTALL
 1777    document can be done using webadmin's equivalent screens.
 1779 Create system aliases
 1781    You must now specify which account gets postmaster mail. The Courier mail
 1782    server does NOT deliver any mail to root. You must use a non-privileged
 1783    for postmaster mail. You will also need to specify where your postmaster
 1784    account is. In the following example the same account is used for both,
 1785    but you can easily use separate mailboxes.
 1787    Let's say that you want postmaster mail to be delivered to the user
 1788    "admin".
 1790    Create /usr/lib/courier/etc/aliases/system using any text editor. An
 1791    example aliases/system file is created by make install, and you can simply
 1792    edit what you have there. The default contents of this file are as
 1793    follows:
 1795    root: postmaster
 1797    mailer-daemon: postmaster
 1799    MAILER-DAEMON: postmaster
 1801    uucp: postmaster
 1803    You need to append the following line:
 1805    postmaster: admin
 1807    These aliases cause all mail addressed to root, postmaster, or
 1808    mailer-daemon, to be delivered to admin's account. If you want root's mail
 1809    delivered somewhere else, you can replace "root: postmaster", with
 1810    something else.
 1812    Run the following command as root:
 1814    /usr/lib/courier/sbin/makealiases
 1816    This command creates /usr/lib/courier/etc/aliases.dat, a database that
 1817    contains your new aliases.
 1819    Send a test message:
 1821    echo "To: postmaster" | /usr/lib/courier/bin/sendmail
 1823    Check admin's mailbox, the message should be there.
 1825    Let's do it again:
 1827    echo "To: postmaster" | /usr/lib/courier/bin/sendmail -Nsuccess
 1829    This time, in addition to the blank message, the sending account should
 1830    receive a return receipt.
 1832    Additional aliases can be either added to this file, or placed in any
 1833    other text file in the /usr/lib/courier/etc/aliases directory.
 1835 Create smtp access list
 1837    You need to define which IP addresses are allowed to relay SMTP mail
 1838    through the server. The installation script creates
 1839    /usr/lib/courier/etc/smtpaccess/default containing an example of how to
 1840    enable relaying for IP address, and several reserved netblocks.
 1841    You can either append additional entries to this file, or put your
 1842    additional entries in any other file in the
 1843    /usr/lib/courier/etc/smtpaccess subdirectory. Afterwars, run the following
 1844    as root:
 1846    /usr/lib/courier/sbin/makesmtpaccess
 1848    This command creates the /usr/lib/courier/etc/smtpaccess.dat database that
 1849    couriertcpd uses to initialize the environment for courieresmtpd.
 1851    You will need to rerun makesmtpaccess in order to rebuild smtpaccess.dat
 1852    after any changes in the smtpaccess subdirectory.
 1854    The default the Courier mail server configuration applies smtpaccess.dat
 1855    to both the regular ESMTP server (port 25), and the message submission
 1856    server (port 587). It is possible to set up different access files for
 1857    both ports. To do that, edit /usr/lib/courier/etc/esmtpd-msa, and
 1858    explicitly set ACCESSFILE to a different file, create that file, and use
 1859    the makesmtpaccess-msa command to compile the dedicated port 587 access
 1860    database.
 1862    > NOTE: Authenticated SMTP is preferred over defining explicit IP address
 1863    > ranges. When combined with SSL, authenticated SMTP enables relaying
 1864    > privileges to any sender that securely provides a valid login/password,
 1865    > from any IP address, instead of only a small range of preauthorized IP
 1866    > addresses. The "OPTIONAL: Configure ESMTP authentication and SSL"
 1867    > section, later in this installation guide, gives more information on
 1868    > enabling authenticated SMTP and SSL-based encryption.
 1870    > Furthermore, preauthorized IP address ranges are vulnerable to being a
 1871    > source of abusive backscatter E-mail. Using authenticated SMTP together
 1872    > with the optional backscatter setting, described in the following
 1873    > section, prevents transmission of abusive backscatter bounces to
 1874    > external recipients even from trusted senders that have been
 1875    > compromised.
 1877 Backscatter suppression
 1879    > NOTE: It is important to know that the Courier mail server's default
 1880    > backscatter configuration means that if the Courier mail server receives
 1881    > a message for delivery to a local mailbox, and encounters an error
 1882    > during the delivery, the sender may not receive a delivery failure
 1883    > notification. The most common reason is an error in a custom mail
 1884    > filtering script. The next most common reason is a configuration error
 1885    > (the Courier mail server authentication library gives the account's home
 1886    > directory, optional non-default mailbox location, the account's system
 1887    > userid and groupid; but they differ from the actual files and
 1888    > directories (the home directory or the account's mailbox does not exist,
 1889    > exists somewhere else, or they're owned by a different userid or
 1890    > groupid).
 1892    > When installing the Courier mail server for the first time, it is
 1893    > usually helpful to termporary turn off the default backscatter filters,
 1894    > by setting BOFHSUPPRESSBACKSCATTER to "none", as described below. Remove
 1895    > this setting after the Courier mail server is installed and its basic
 1896    > functions appear to be working.
 1898    The term "backscatter" refers to non-delivery reports sent to a forged
 1899    return address. SMTP was created a long time ago, in better times when
 1900    everyone trusted each other. Anyone could provide any return address for
 1901    any E-mail message.
 1903    Times have changed. At the time this documentation is written, most
 1904    surveys report that between 75% and 80% of Internet E-mail is junk E-mail
 1905    or viruses, with a forged return address.
 1907    Backscatter becomes a problem when a mail server does not reject unwanted
 1908    mail. The mail server decides that the message is unwanted only after it
 1909    is accepted. It generates a non-delivery notice, and sends it to the
 1910    original message's return address. Because viruses and junk mail use
 1911    random forged return addresses, the unfortunate victim of address forgery
 1912    must deal with large amounts of useless non-delivery notices from the
 1913    mailbox. Not to mention a bunch of uninformed people who think he is
 1914    responsible for sending the virus or the junk mail to them.
 1916    There's now a growing consensus that backscatter bounces should be
 1917    considered E-mail abuse. The Courier mail server is already very good at
 1918    minimizing the amount of backscatter, by the virtue of refusing to receive
 1919    any mail to a nonexistent local mailbox. However it's still possible for
 1920    the Courier mail server to bounce a received message. Several settings
 1921    control how the Courier mail server filters out its own backscatter, and
 1922    avoids becoming a nuisance to others.
 1924    Two settings are available. The first setting instructs the Courier mail
 1925    server to simply discard backscatter bounces. This is the
 1926    ESMTP_BLOCKBACKSCATTER setting in the courierd configuration file. This
 1927    setting lists the so-called "message sources" which are dropped by the
 1928    SMTP client. All messages from any matching source are quietly discarded.
 1929    The default setting lists one message source: a code that means "a
 1930    delivery status notification for a message received via SMTP from a
 1931    non-authenticated source". "Non-authenticated" means a message received
 1932    from an IP address that does not have relaying privileges, and did not
 1933    authenticate. It's also possible to include authenticated SMTP sources; or
 1934    it's possible to disable this setting altogether, instructing the Courier
 1935    mail server to deliver all bounces via SMTP, even if they may potentially
 1936    be backscatter.
 1938    Note that messages received in other ways (such as messages sent via the
 1939    sendmail command) are not affected. Their bounces will be sent via SMTP in
 1940    all cases (although there exists an undocumented setting to block those
 1941    bounces too). Also, bounces are always delivered to local mailboxes, this
 1942    setting is ignored for local mail deliveries.
 1944    The default setting means that if the Courier mail server receives a
 1945    message via SMTP for delivery to a local mailbox, and it bounces for some
 1946    reason, the bounce will be discarded.
 1948    The Courier mail server is also often used as a smarthost for SMTP
 1949    clients. These SMTP clients either connect from trusted IP addresses (IP
 1950    addresses that belong to the organization that runs the mail server), or
 1951    that succesfully authenticate, using SMTP authenticate. If those messages
 1952    bounce, the non-delivery report gets delivered, because the default
 1953    setting only drops bounces from non-authenticated source (a connection
 1954    from a trusted IP address is always processed as if the sender succesfully
 1955    authenticated).
 1957    > NOTE: Sometimes the Courier mail server serves as a backup MX for
 1958    > another organization. If mail cannot be delivered to the primary MX (it
 1959    > rejects the message, or the message times out), the bounce will be
 1960    > discarded, because the message was probably received from a
 1961    > non-authenticated source.
 1963    The second setting minimizes the possibility of generating a bounce, of
 1964    any kind, in the first place. The second setting controls the backscatter
 1965    suppression list, which is a list of blacklisted E-mail addresses.
 1967    When the Courier mail server fails to deliver a message to an address,
 1968    this address goes on the suppression list, and the Courier mail server
 1969    will refuse to accept any more messages to the same address. If the
 1970    delivery failure was a temporary failure, any future messages will also be
 1971    turned away with a temporary error. A permanent delivery failure results
 1972    in future messages rejected with a permanent error.
 1974    Note that the suppression list does not apply to messages already accepted
 1975    by the Courier mail server, and which are in its mail queue. The
 1976    suppression list is checked when the Courier mail server is receiving a
 1977    new message. The Courier mail server automatically clears an address from
 1978    the suppression list after two hours. If the original message encountered
 1979    a temporary delivery failure, The Courier mail server periodically tries
 1980    again to re-deliver the message. If the message continues to encounter a
 1981    temporary delivery failure, the clock starts running again, from the
 1982    beginning, If a re-delivery attempts succeeds, the address is cleared from
 1983    the suppression list, and the Courier mail server will now accept more
 1984    messages to the same address, immediately.
 1986    If a message keeps encountering temporary delivery failures, the time
 1987    before re-delivery attempts gets longer. It's possible that it could take
 1988    more than two hours for another delivery attempt, on a busy mail server.
 1989    The address then falls off the list, and the Courier mail server will
 1990    accept another message to the undeliverable address. This situation is
 1991    unavoidable, but is not considered to be a major issue.
 1993    The second setting is the BOFHSUPPRESSBACKSCATTER setting, in the bofh
 1994    configuration file. See the courier(8) man page for more information. The
 1995    default BOFHSUPPRESSBACKSCATTER setting also filters only messages from
 1996    non-authenticated SMTP sources against the suppression list.
 1998    The suppression list is not updated when problematic messages are manually
 1999    removed from the mail queue (using the "courier cancel" command). Even
 2000    though the stuck messages are deleted, The Courier mail server will
 2001    continue to refuse messages to suppressed addresses, until they time out.
 2002    Use the "courier clear" command to manually clear addresses from the
 2003    suppression list, if so desired.
 2005    > NOTE: A mailbox that exceeded its storage quota results in temporary
 2006    > delivery failures. Therefore, when a mailbox fills up, The Courier mail
 2007    > server stops accepting any more messages to this mailbox (there might be
 2008    > one or two messages already in the mail queue, but that shouldn't be a
 2009    > major issue). Mail deliveries will resume when the mailbox goes below
 2010    > the quota (although this may take an hour, or two, as explained
 2011    > previously). It's possible that an existing version of the Courier mail
 2012    > server was originally modified to generate a permanent delivery failure
 2013    > for a quota exceeded condition. This change should now be undone, in
 2014    > order for backscatter suppression to work properly.
 2016    The third setting is the DSNTOAUTHADDR=1 setting in the courierd
 2017    configuration file. This setting, when enabled, alters bounce handling of
 2018    messages that were received from an authenticated SMTP connection.
 2020    Bounces of authenticated messages are processed according to the previous
 2021    two settings, except that the bounce message gets sent (if it gets sent at
 2022    all) to the authenticated login address, instead of the message's return
 2023    address.
 2025    > NOTE: This works only if the Courier mail server is configured, via the
 2026    > Courier mail server Authentication Library, to validate login IDs that
 2027    > consist of a full E-mail address, "user@domain", with the login ID
 2028    > corresponding to the mailbox's E-mail address.
 2030    Enabling this setting removes the possibility of the Courier mail server
 2031    sending abusive backscatter bounces to external recipients, from a
 2032    compromised trusted sender, even if the compromised trusted sender uses
 2033    authenticated SMTP. Instead of sending the bounces to the forged return
 2034    address, they get redirected to the sender's mailbox.
 2036    > NOTE: The authenticated address is used for bounces only. When the
 2037    > message gets sent to its listed recipients, the message's return address
 2038    > gets used, as usual.
 2040    > NOTE: Authenticated SMTP must be used for this option to have any
 2041    > effect. When relaying privileges are granted to explicit IP address
 2042    > ranges (see the preceding "Create smtp access list" section), The
 2043    > Courier mail server will not have the sender's authenticated login
 2044    > address (unless the sender voluntary authenticates).
 2046 Miscellaneous configuration
 2048    Review/edit contents of various configuration files in
 2049    /usr/lib/courier/etc:
 2051      • courierd
 2053        this file controls general aspects of the Courier mail server's
 2054        message processing. A default file is installed with comments
 2055        describing what the various options are. Review the default options,
 2056        and make whatever changes you deem appropriate. You will probably need
 2057        to make changes to this configuration file in order to select the
 2058        correct way to deliver local mail (whether to have the Courier mail
 2059        server handle the delivery directly, or whether to run procmail or
 2060        maildrop). There are comments in this file that tell you what needs to
 2061        be done to have the Courier mail server use a separate local mail
 2062        delivery agent, such as procmail, for mail delivery. Read and follow
 2063        the instructions there.
 2065      • esmtpd
 2067        this is an important file that controls the Courier mail server's
 2068        ESMTP server. Options in this file include setting the maximum limit
 2069        on simultaneous server connections, whether to disable certain
 2070        optional SMTP features, whether or not you have a mail filter module
 2071        installed, and whether or not DNS-based blacklists or whitelists are
 2072        used.
 2074      • esmtpd-msa
 2076        this file controls the Courier mail server's ESMTP message submission
 2077        server (RFC 2476). The settings in this file supplement the settings
 2078        in esmtpd. The default startup script first reads esmtpd, then
 2079        esmtpd-msa in order to initialize the ESMTP message submission server
 2080        on port 587.
 2082      • smtpaccess
 2084        this configuration file/directory is used to ban explicit IP addresses
 2085        from connecting to the ESMTP server at all, or to specify which IP
 2086        address ranges are allowed to relay mail through the ESMTP server. The
 2087        default file turns on relaying in a couple of reserved IP address
 2088        ranges, as an example. The makesmtpaccess command must be executed for
 2089        any changes to smtpaccess to take effect.
 2091      • pop3d
 2093        this file sets various options for the Courier mail server's POP3
 2094        server. The Courier mail server's POP3 server can be used only if mail
 2095        is stored in Maildirs. You will need to use another POP3 server if you
 2096        choose to deliver your mail to legacy mailbox files. A default
 2097        configuration file is installed, describing the available options.
 2099      • imapd
 2101        this file sets various options for the Courier mail server's IMAP
 2102        server. The Courier mail server's IMAP server can be used only if mail
 2103        is stored in Maildirs. You will need to use another IMAP server if you
 2104        choose to deliver your mail to legacy mailbox files. A default
 2105        configuration file is installed, describing the available options.
 2107     Qmail compatibility mode.
 2109  echo "qmail" >/usr/lib/courier/etc/dotextension
 2111    Run this command if you are installing the Courier mail server on a system
 2112    that's currently running the Qmail mail server. The Courier mail server
 2113    will now read .qmail files for delivery instructions, instead of .courier
 2114    files. The Courier mail server's .courier files are mostly compatible with
 2115    Qmail's .qmail files, but there are some minor differences. Still, most of
 2116    your .qmail files should work without too many problems.
 2118 Define local domains
 2120    The configuration file /usr/lib/courier/etc/locals is a list of all the
 2121    domains that are considered local. Mail to any address in any local domain
 2122    is handled as a local delivery. If this file does not exist the Courier
 2123    mail server will use the contents of the me configuration file, or it will
 2124    obtain its machine name from the operating system.
 2126    This file contains a list of domains, one per line. In most cases you need
 2127    to initialize this file to contain every hostname that has a DNS A, or
 2128    AAAA, record pointing to any IP address assigned to this machine,
 2129    including "localhost". You will also need to include any domain that lists
 2130    this machine as its primary MX relay.
 2132    You may also include domain wildcards in locals by prefixing the domain
 2133    with a period. For example: ".example.com" will treat any domain
 2134    underneath example.com - like a.example.com, b.example.com - as a local
 2135    domain. Note that this does not include example.com itself, so you may
 2136    need to list it explicitly as well!
 2138    NOTE: The makealiases command must be entered after making any changes to
 2139    this file.
 2141 Create a list of domains to accept mail for
 2143    If you would like your server to function as a backup mail relay for other
 2144    domains, create /usr/lib/courier/etc/esmtpacceptmailfor. This is a plain
 2145    text file, containing a list of domains, one per line. This file lists all
 2146    domains your server will accept mail for. NOTE: if you create this file,
 2147    you MUST include all your local domains. Usually you can simply append
 2148    what you have in /usr/lib/courier/etc/locals. If
 2149    /usr/lib/courier/etc/esmtpacceptmailfor does not exist, The Courier mail
 2150    server will accept mail only for the machine name listed in
 2151    /usr/lib/courier/etc/me, (or the system machine name).
 2153    Like /usr/lib/courier/etc/locals, prepending a period to a domain name in
 2154    esmtpacceptmailfor will cause the Courier mail server to accept mail for
 2155    all subdomains of this domain.
 2157 OPTIONAL: Configure UUCP
 2159    The Courier mail server is capable of sending and receiving mail via UUCP.
 2160    The Courier mail server does not implement UUCP directly, but instead uses
 2161    your existing UUCP software to send and receive mail.
 2163    The Courier mail server's UUCP functionality has been tested with Taylor
 2164    UUCP 1.06. It's likely that some minor tweaking will be necessary to get
 2165    the Courier mail server working with other UUCP builds. Give it a shot,
 2166    and keep an eye out for problems.
 2168   /usr/lib/courier/etc/uucpme
 2170    This configuration file must be initialized to list the UUCP node name
 2171    that this machine is known as. Currently the Courier mail server does not
 2172    support multiple UUCP node aliases for the same machine.
 2174   /usr/lib/courier/etc/uucpneighbors
 2176    This configuration file contains a list of all the nodes that your machine
 2177    talks to via UUCP. Obviously this information will be a duplicate of the
 2178    corresponding data in your existing UUCP configuration files, and some
 2179    maintenance will be necessary to keep both lists in sync. That is,
 2180    unfortunately, unavoidable. The makeuucpneighbors commands turns this
 2181    plain text file into a database, which is what the Courier mail server
 2182    uses directly. The format of the uucpneighbors configuration file is
 2183    described in the makeuucpneighbors(8) manual page.
 2185   /usr/lib/courier/etc/uuucprewriteheaders
 2187    The Courier mail server automatically rewrites message envelope addresses
 2188    from ESMTP to UUCP format. If this file exists, the addresses in the
 2189    headers of messages sent to/from UUCP addresses will also be rewritten.
 2191 Configure UUCP domain aliases
 2193    The Courier mail server can accept mail addressed to <user@example.com>,
 2194    and then forward it to uucp!bang!path!user, via UUCP. This is done by
 2195    adding a UUCP virtual domain alias to your aliases file, see "Create
 2196    system aliases". Append the following entry to your /etc/aliases, then run
 2197    the makealiases command:
 2199     @example.com: uucp!bang!path!
 2201    See the makealiases(8) manual page for more information.
 2203 OPTIONAL: Configure LDAP aliasing
 2205    In addition to using LDAP for authentication and for managing accounts,
 2206    The Courier mail server can use an LDAP directory for routing, or
 2207    "aliasing" mail.
 2209    The term "aliasing" refers to substituting one or more addresses for
 2210    another address. A one-to-one substitution results in the Courier mail
 2211    server accepting mail for one address, and delivering the mail to another
 2212    address. A one-to-many substitution results in the Courier mail server
 2213    accepting mail for one address, and delivering a separate copy of the
 2214    message to every address defined by the alias.
 2216    The Courier mail server supports a basic form of aliasing using a GDBM or
 2217    DB-based database. The makealiases(8) command reads a plain text file
 2218    containing the aliasing rules, the creates a GDBM or a DB database. Each
 2219    recipient address is looked up in the database, and if an alias is defined
 2220    for the recipient address, it is used in place of the original address.
 2221    Aliasing can be used against individual addresses, one by one. An extended
 2222    form of aliasing maps an entire domain to a single local address, using
 2223    dot-courier(5) delivery instruction files.
 2225    The Courier mail server can use an LDAP directory instead of a GDBM or a
 2226    DB database, to perform essentially the same function. If OpenLDAP is
 2227    available at time of installation, the installation script installs the
 2228    courierldapaliasd(8) program and a ldapaliasrc configuration file. It will
 2229    be necessary to enter appropriate information into ldapaliasrc, and
 2230    arrange to run "courierldapaliasd start" at system boot time (it is a
 2231    background daemon process that opens persistent connections to the LDAP
 2232    server).
 2234    Additional instructions for setting up LDAP-based aliasing are found in
 2235    the courierldapaliasd(8) manual page.
 2237 OPTIONAL: Enable standard mail filters
 2239    The Courier mail server includes several options for selectively filtering
 2240    mail. In general, The Courier mail server provides several plug-in
 2241    interfaces for external mail filters, that can be used to selectively
 2242    accept or reject messages.
 2244    Please note that running mail filters can have a non-trivial impact on
 2245    mail system performance and throughput.
 2247    There are three standard mail filtering modules:
 2249      • verifyfilter - Verify all E-mail's return addresses, see the
 2250        verifyfilter(8) manual page for more information.
 2251      • dupfilter - Block duplicate messages, see the dupfilter(8) manual page
 2252        for more information.
 2253      • ratefilter - Limit the rate of messages per sender see the
 2254        ratefilter(8) manual page for more information.
 2256    To enable a mail filter, for example:
 2258  filterctl start verifyfilter
 2260    The filterctl installs the filter, and the courierfilter starts them, see
 2261    Starting and stopping the Courier mail server.
 2263 OPTIONAL: Configure custom mail filtering
 2265    The Courier mail server comes with some sample code that demonstrates how
 2266    to write a mail filter. The Courier mail server provides two mail
 2267    filtering interfaces:
 2269      • Global mail filters
 2271        these filters are installed and will be used to filter every incoming
 2272        message. Global mail filters are permanently running daemons that
 2273        create and listen on a filesystem domain socket. Each new message that
 2274        the Courier mail server receives must be acknowledged by every global
 2275        mail filter. Note that if global mail filters are installed, but their
 2276        daemons are not running, The Courier mail server will not accept any
 2277        new messages.
 2279      • Local mail filter
 2281        this filter can be used when the message is addressed to a local
 2282        recipient - when the Courier mail server itself will deliver the
 2283        message to a physical mailbox. Local mail filtering is designed to be
 2284        primarily used by the maildrop mail filter. With the local mail
 2285        filtering installed, individual recipients can create files containing
 2286        mail filtering instructions that can selectively accept or reject
 2287        individual messages.
 2289    See courierfilter(8) for more information on global mail filters.
 2291    See maildropfilter(7) for more information on local mail filters.
 2293 Miscellaneous UUCP configuration
 2295    The Courier mail server sends UUCP mail by running rmail via uux. The
 2296    configuration script searches for the uux command in the default search
 2297    path. If your uux command is not in a directory that's in your search path
 2298    you will have to modify PATH before running configure.
 2300    The Courier mail server receives UUCP mail by expecting your UUCP software
 2301    to run the rmail command, which is installed in /usr/lib/courier/bin.
 2302    (It's actually a soft link to sendmail, but we'll talk about it later).
 2303    Your UUCP software probably does not run commands from this directory by
 2304    default, so you will have to make the necessary adjustments. You can
 2305    always create another soft link in a directory that UUCP searches by
 2306    default.
 2308 Starting and stopping the Courier mail server
 2310    To start the Courier mail server, run the command
 2311    /usr/lib/courier/sbin/courier start. To stop the Courier mail server, run
 2312    the command /usr/lib/courier/sbin/courier stop. See the courier(8) manual
 2313    page for more information.
 2315    You should add these commands to your system startup and shutdown scripts.
 2317    Note that this command starts and stops the Courier mail server's core
 2318    processes only. It does not start any additional daemon processes that you
 2319    may need, such as the mail filtering daemon, the ESMTP server daemon, the
 2320    POP3 server daemon, or the IMAP server daemon.
 2322    The commands courierfilter start, courierfilter stop, esmtpd start, esmtpd
 2323    stop, esmtpd-msa start, esmtpd-msa stop, pop3d start, pop3d stop, imapd
 2324    start, and imapd stop (all commands are installed in the sbin directory)
 2325    are used to start or stop their respective daemons, and they should be
 2326    added to your system startup and shutdown scripts, where required. As
 2327    described in the relevant manual pages, courierfilter should be the first
 2328    daemon process to start, and the last one to terminate. The remaining
 2329    daemons may be started in any order.
 2331 Run the Courier mail server in parallel to your mail server
 2333    You now have several options for migrating from your existing mail server
 2334    to the Courier mail server:
 2336      • Your existing mail server can continue to handle incoming mail, by
 2337        listening on the smtp port. The Courier mail server will be used to
 2338        send all outgoing mail. This is accomplished by configuring your mail
 2339        software to run /usr/lib/courier/bin/sendmail to send mail, instead of
 2340        your current sendmail program.
 2341      • The Courier mail server can handle incoming mail by listening on the
 2342        smtp port, and your existing mail server can continue to handle all
 2343        outgoing mail. You will need to stop your existing mail server from
 2344        listening on the smtp port, and run the following command:
 2346  /usr/lib/courier/sbin/esmtpd start
 2348        from your system start up script. You should also add
 2349        /usr/lib/courier/sbin/esmtpd stop to your system shutdown script. Note
 2350        that there's a separate script that starts the ESMTP submission server
 2351        on port 587 - /usr/lib/courier/sbin/esmtpd-msa, that is used in an
 2352        analogous fashion.
 2354 OPTIONAL: Configure ESMTP authentication and SSL
 2356    The Courier mail server supports authenticated ESMTP in order to grant
 2357    ESMTP relaying privileges to remote users. The following steps set up
 2358    authenticated ESMTP:
 2360      • Edit /usr/lib/courier/etc/esmtpd and initialize the ESMTPAUTH
 2361        configuration setting. The configuration file
 2362        /usr/lib/courier/etc/esmtpd-msa is used for the ESMTP submission
 2363        server on port 587. Setting this variable in esmtpd is sufficient,
 2364        because esmtpd-msa merely supplements the settings in esmtpd.
 2365        Explicitly initialize this setting in esmtpd-msa only if you wish to
 2366        apply it to port 587 only.
 2368        ESMTPAUTH is a list of SASL authentication methods to use use.
 2369        Currently, The Courier mail server supports LOGIN, PLAIN, CRAM-SHA1
 2370        and CRAM-MD5. The list of authentication methods is sometimes
 2371        influenced by the installed authentication modules in the Courier mail
 2372        server Authentication Library. Not all authentication modules
 2373        implement CRAM-MD5/SHA1. The authentication modules that support
 2374        CRAM-MD5/SHA1 authentication are: authuserdb, authldap, authmysql, and
 2375        authpgsql.
 2377      • Your authentication modules may require additional configuration, you
 2378        will have to take care of that too. For example, authpam - the PAM
 2379        authentication module - requires that you also configure your PAM
 2380        library. In this case, you need to configure your PAM library to
 2381        support the "esmtp" service. The PAM library configuration details
 2382        depend on your particular operating system, and are beyond the scope
 2383        of this document. Consult the documentation for your PAM library for
 2384        more information.
 2385      • Restart the Courier mail server.
 2387   ESMTP over TLS/SSL
 2389    The Courier mail server also supports ESMTP over TLS/SSL, by using the
 2390    ESMTP STARTTLS extension:
 2392      • To add SSL support you have to install OpenSSL or GnuTLS before
 2393        installing the Courier mail server. Download OpenSSL from
 2394        http://www.openssl.org/, or GnuTLS from http://www.gnutls.org.
 2396        Follow OpenSSL's or GnuTLS's installation instructions, then build the
 2397        Courier mail server.
 2399        > NOTE: Most systems already have an available OpenSSL or GnuTLS
 2400        > package. Do not build OpenSSL or GnuTLS yourself, if a prebuilt
 2401        > package is already available. Just install the prebuilt package.
 2403        > NOTE: The development libraries must be installed in addition to the
 2404        > runtime package, in order to build the Courier mail server. On most
 2405        > systems, the development files (header files, libraries, etc...) are
 2406        > provided in a separate "devel" package. The base OpenSSL/GnuTLS
 2407        > package is not sufficient to build the Courier mail server, the
 2408        > development libraries must be installed.
 2410        The OpenSSL library is selected when both OpenSSL and GnuTLS libraries
 2411        are found by the configure script. Use the --with-gnutls option to
 2412        explicitly select GnuTLS library over OpenSSL.
 2414      • STARTTLS is enabled simply by installing an X.509 certificate as
 2415        /usr/lib/courier/share/esmtpd.pem. If this file exists, the STARTTLS
 2416        ESMTP extension will be automatically advertised. This file must be
 2417        owned by the userid the Courier mail server is installed as, and MUST
 2418        NOT be world readable!
 2419      • Note that SSL requires a signed X.509 certificate. You can generate
 2420        your own self-signed certificates with OpenSSL, but mail clients will
 2421        display a warning message the first time they connect to the server.
 2422        To prevent the warning message, you will need to pay money to have
 2423        your certificate signed by a certificate authority. The gory details
 2424        of setting up SSL is beyond the scope of this document, and you should
 2425        consult the OpenSSL documentation for more information.
 2426      • The certificate must be installed as
 2427        /usr/lib/courier/share/esmtpd.pem. This file MUST NOT HAVE any group
 2428        or world permissions! It must be owned by the Courier mail server
 2429        userid (the userid used to install the Courier mail server, usually
 2430        courier or daemon).
 2431      • In times of extreme desperation the script
 2432        /usr/lib/courier/sbin/mkesmtpdcert can be used to generate
 2433        /usr/lib/courier/share/esmtpd.pem. This script will silently terminate
 2434        if OpenSSL is not installed, or if the esmtpd.pem certificate file
 2435        already exists (so it will not be overwritten). This makes it easier
 2436        to have this script invoked from a package install script.
 2437      • Restart the Courier mail server's ESMTP server after installing the
 2438        X.509 certificate.
 2440    The Courier mail server will also use TLS/SSL when sending ESMTP mail,
 2441    automatically. If the remote mail server support STARTTLS, The Courier
 2442    mail server will use it automatically.
 2444    SSL/TLS settings for the ESMTP client can be adjusted in the
 2445    /usr/lib/courier/etc/courierd configuration file. When sending mail using
 2446    SSL, The Courier mail server can optionally verify the remote server's
 2447    X.509 certificate. This is done by setting ESMTP_TLS_VERIFY_DOMAIN to 1,
 2448    in /usr/lib/courier/etc/courierd.
 2450    The configuration script checks for the system's list of trusted
 2451    certificate authorities, and initializes TLS_TRUSTCERTS in the courierd
 2452    configuration file, during installation. When the Courier connects to a
 2453    remote server, setting ESMTP_TLS_VERIFY_DOMAIN to 1 in the courierd
 2454    configuration file (usually /usr/lib/courier/etc/courierd or
 2455    /etc/courierd) enables certificate verifications. However, many mail
 2456    servers on the Internet use self-signed certificates, so this is generally
 2457    of little use.
 2459 OPTIONAL: Configure ESMTP smarthosting
 2461    Initialize the esmtproutes configuration file if all outgoing mail need to
 2462    be forwarded to your Internet provider's mail server, or some other
 2463    "smarthost". See courier(8) for more information:
 2465    : relay.example.com
 2467    This forwards all mail to relay.example.com
 2469    : relay.example.com,587
 2471    This forwards all mail to relay.example.com on port 587.
 2473    : relay.example.com,465 /SECURITY=SMTPS
 2475    This forwards all mail to relay.example.com on port 465, using encrypted
 2476    SMTP.
 2478    If the smarthost requires authentication, initialize the esmtpauthclient
 2479    configuration file:
 2481    relay.example.com,587 john@example.com snerkle
 2483    When the Courier mail server connects to relay.example.com on port 587, it
 2484    will authentication using the userid of "john@example.com" and password
 2485    "snerkle".
 2487 OPTIONAL: Configure the SECURITY ESMTP extension
 2489    The Courier mail server includes an experimental extension to ESMTP that
 2490    can be used to set up secure E-mail delivery between trusted mail relays
 2491    over an untrusted network. This is implemented by an experimental ESMTP
 2492    extension in the Courier mail server. Therefore, at present time both the
 2493    sending and the receiving mail relay must be running the Courier mail
 2494    server that's configured to support this extension. The specification for
 2495    this ESMTP extension is publicly available. This is a very small extension
 2496    of the existing, draft-standard STARTTLS ESMTP extension. The SECURITY
 2497    extension should only require minor changes to existing mail servers and
 2498    clients that already implement STARTTLS.
 2500   Overview
 2502    The first necessary step is to read the formal definition of the SECURITY
 2503    extension, which can be found on http://www.courier-mta.org. Although the
 2504    following instructions do not use any information directly from this
 2505    document, it is important to understandi how this mechanism works. This
 2506    will be very useful in troubleshooting. This is not called an
 2507    "experimental" extension just for the hell of it.
 2509    The SECURITY extension builds on top of several existing, proven,
 2510    technologies in order to deliver mail with the highest level of security
 2511    that can possibly be implemented using the existing technology. The
 2512    several steps in implementing the SECURITY extension:
 2514     1. Install and configure the STARTTLS ESMTP extension. This extension
 2515        uses TLS/SSL encryption for sending mail.
 2516     2. Create a private, controlled, X.509 Certificate Authority.
 2517     3. Use the private CA to sign X.509 certificates of all mail nodes in the
 2518        trusted mail network. This CA's certificate is also installed in every
 2519        trusted mail node.
 2521    The SECURITY extension is an optional tag that's attached to an E-mail
 2522    message. The Courier mail server requires STARTTLS to forward
 2523    SECURITY-tagged messages, and the receiving mail nodes must present an
 2524    X.509 certificate, signed by the private Certificate Authority, before the
 2525    Courier mail server will send the message. The Courier mail server will
 2526    refuse to send the message to a mail node that does not support STARTTLS,
 2527    or doesn't present a suitable X.509 certificate.
 2529    Therefore, in an ideal world, mail clients will simply tag messages with
 2530    the SECURITY extension. Obviously, this means that mail clients must be
 2531    updated to implement this feature. Until this happens, The Courier mail
 2532    server will provide a workaround that automatically tags all messages for
 2533    selected domains with the SECURITY extension. This is not a perfect
 2534    solution, and it has some minor limitations, which will be mentioned
 2535    later.
 2537   Install and configure the STARTTLS ESMTP extension
 2539    The first step is to implement ESMTP STARTTLS. Use the instructions
 2540    elsewhere in this document to activate ESMTP STARTTLS support. The
 2541    following instructions use the scripts from OpenSSL 0.9.6, but should also
 2542    work with OpenSSL 0.9.5a.
 2544   Create a private X.509 Certificate Authority
 2546    Create an empty subdirectory:
 2548      mkdir /etc/myca
 2549      cd /etc/myca
 2551    There's a convenient OpenSSL script called CA.pl that you want to copy to
 2552    the current directory:
 2554      cp /usr/share/ssl/misc/CA.pl .
 2556    Your OpenSSL package may have CA.pl installed someplace else. Find it, and
 2557    copy it to /etc/myca. The CA.pl needs to be slightly modified before it
 2558    can be used. Find the following commands in CA.pl, and change them as
 2559    follows:
 2561    Replace:
 2563        system ("$REQ -new -keyout newreq.pem -out newreq.pem $DAYS");
 2565    replace with:
 2567        system ("$REQ -new -nodes -keyout newreq.pem -out newreq.pem $DAYS");
 2569    Also replace:
 2571        system ("$REQ -new -x509 -keyout " .
 2572            "${CATOP}/private/$CAKEY -out ${CATOP}/$CACERT $DAYS");
 2574    replace with:
 2576        system ("$REQ -new -nodes -x509 -keyout " .
 2577            "${CATOP}/private/$CAKEY -out ${CATOP}/$CACERT $DAYS");
 2579    The CA.pl script creates password-protected certificate keys by default.
 2580    Password protected certificates currently do not work with the Courier
 2581    mail server. Adding the -nodes parameter turns off password protection.
 2582    This means that it is vital to make sure that the trusted mail relays are
 2583    properly secured. All the encryption in the world will not be of much use
 2584    if the mail relays are running a rootable FTP server (for example).
 2585    Anyway, run CA.pl to create a new certificate authority:
 2587      ./CA.pl -newca
 2589    CA.pl prompts for a basic description of the new CA, then creates the
 2590    certificate and the certificate key. The CA's root certificate is saved in
 2591    /etc/myca/demoCA/cacert.pem.
 2593   Use the private CA to sign X.509 certificates of all trusted mail nodes
 2595    This step must be performed to create the X.509 certificates for every
 2596    mail node in the trusted secure network. First, a certificate request is
 2597    created:
 2599      ./CA.pl -newreq
 2601    CA.pl prompts for a basic description of the new certificate. Special care
 2602    must be paid to the "commonName" setting. "commonName" MUST be set to the
 2603    hostname of the trusted mail node, NOT its mail domain. For example, given
 2604    the following DNS setup for example.com:
 2606       example.com.  MX 10 mx1.example.com.
 2607       example.com.  MX 20 mx2.example.com.
 2609       mx1.example.com. A
 2610       mx2.example.com. A
 2612    This domain will need two certificates, one with "commonName" set to
 2613    "mx1.example.com", and one with "commonName" set to mx2.example.com.
 2615    Running ./CA.pl produces a certificate request in the file newreq.pem. Run
 2616    the following command to sign it:
 2618      ./CA.pl -signreq
 2620    This step creates the file newcert.pem that contains a new signed
 2621    certificate. The private key from the original certificate request must be
 2622    appended to this file, before the certificate can be used. Simply take the
 2623    newreq.pem file from the previous step, and append the private key in that
 2624    file to newcert.pem. The resulting certificate file should look something
 2625    like this:
 2627     [ description of the certificate ]
 2629  -----BEGIN CERTIFICATE-----
 2631     [ binary goo ]
 2633  -----END CERTIFICATE-----
 2634  -----BEGIN RSA PRIVATE KEY-----
 2636     [ binary goo ]
 2638  -----END RSA PRIVATE KEY-----
 2640    The OpenSSL documentation contains instructions on how to perform the
 2641    equivalent procedure with Diffie-Hellman instead of RSA.
 2643   Configure trusted mail nodes
 2645    Two files must be installed on every trusted mail node.
 2647      • The mail node's certificate, the newcert.pem file from the previous
 2648        step. The following documentation assumes that this file is installed
 2649        as /etc/mycert.pem. This mail node will use this certificate to
 2650        authenticate itself to other trusted mail nodes.
 2651      • The certificate authority file, cacert.pem. The following
 2652        documentation assumes that it's installed as /etc/cacert.pem. The CA's
 2653        certificate is used to authenticate other trusted mail nodes.
 2655    Edit the /usr/lib/courier/etc/esmtpd configuration file. Set TLS_CERTFILE
 2656    to /etc/mycert.pem. The Courier mail server will use TLS_CERTFILE to
 2657    authenticate itself to other trusted mail nodes.
 2659    Edit the /usr/lib/courier/etc/courierd configuration file. Set
 2660    TLS_TRUSTSECURITYCERTS to /etc/cacert.pem. The Courier mail server will
 2661    not send ESMTP mail tagged with the SECURITY extension to other mail
 2662    relays unless they produce a certificate that's signed by
 2665   Testing
 2667    The following simple steps can be carried out to verify that everything is
 2668    working correctly. These examples use two mail nodes called
 2669    send.example.com and receive.example.com. The test messages are sent from
 2670    send.example.com, and are addressed to receive.example.com. The Courier
 2671    mail server must be restarted on both send and receive, after
 2672    reconfiguring the machines for each test. It is not strictly necessary to
 2673    do this every time, actually, but it's simply easier to do make it a part
 2674    of the routine. It is necessary to restart both the main the Courier mail
 2675    server daemon processes as well as the separate ESMTP daemon process (on
 2676    receive):
 2678      courier stop
 2679      courier start
 2680      esmtpd stop
 2681      esmtpd start
 2683     1. Temporary get rid of /usr/lib/courier/bin/couriertls wrapper on
 2684        receive.example.com. Rename it to couriertls.save. STARTTLS is
 2685        automatically disabled if couriertls is missing,
 2686     2. Run the following command on send.example.com:
 2688      echo "To: postmaster" | /usr/lib/courier/bin/sendmail \
 2689                -S STARTTLS postmaster@receive.example.com
 2691        This message should bounce back since receive has STARTTLS disabled.
 2693     3. Restore couriertls on receive.example.com, but then rename it on
 2694        send.example.com. The situation is now reversed, and the test message
 2695        should still bounce.
 2696     4. Restore couriertls on send.example.com. Edit receive's
 2697        /usr/lib/courier/etc/esmtpd file. Comment out the current TLS_CERTFILE
 2698        setting (which points to the private CA certificate). Reset
 2699        TLS_CERTFILE to /usr/lib/courier/share/esmtpd.pem, which is the
 2700        self-signed test certificate created by the mkesmtpdcert script, when
 2701        STARTTLS support in the Courier mail server was first set up.
 2703        Send a test message WITHOUT the "-S STARTTLS" option. This message
 2704        should go through, assuming all the other setting in all configuration
 2705        files are the initial defaults. The regular ESMTP STARTTLS extension,
 2706        without authentication, will be used the deliver this message. Verify
 2707        this by checking the headers in the received message on
 2708        receive.example.com.
 2710        Send a test message WITH the "-S STARTTLS" option. It should bounce,
 2711        even though receive.example.com supports STARTTLS. That's because it
 2712        is using an X.509 certificate that's not signed by the private CA
 2713        authority.
 2715     5. Restore TLS_CERTFILE on receive, and send a test message with the -S
 2716        STARTTLS option, which should now go through.
 2718   Force SECURITY for selected domains
 2720    As demonstrated by the test messages, messages must be tagged with the
 2721    SECURITY extension in order for them to be securely transmitted. This must
 2722    be done by the sending mail client. Until mail clients support SECURITY
 2723    The Courier mail server can automatically add the SECURITY tag to every
 2724    message addressed to a domain. This is done by entering the domain in the
 2725    esmtproutes configuration file using the following syntax:
 2727  receive.example.com:  /SECURITY=STARTTLS
 2729    Repeat the tests in the previous section, but this time add and delete
 2730    this entry in /usr/lib/courier/etc/esmtproutes instead of using the -S
 2731    STARTTLS option. The test messages must still bounce or not bounce in the
 2732    same way.
 2734    Consult the courier(8) manual page for more information on the esmtproutes
 2735    configuration file.
 2737   Limitations
 2739    This setup makes it virtually impossible to intercept mail traffic between
 2740    trusted mail nodes. Even if the DNS cache is poisoned to intercept mail to
 2741    a hostile mail node, mail will not go through since the attacker will not
 2742    have a signed X.509 cert. However, all is lost if the mail nodes
 2743    themselves are compromised directly. After securing the compromised node,
 2744    everything must be rebuilt. A new CA must be created, and all mail nodes
 2745    must now receive new certificates. Once support for certificate revocation
 2746    lists is improved, this situation will get somewhat better.
 2748    Another possible way to mitigate that possibility is to use a different
 2749    certificate authority for every trusted mail node. TLS_TRUSTSECURITYCERTS
 2750    can point to a directory, instead of a file. This directory can contain
 2751    multiple certificate authorities (hashed by OpenSSL's c_rehash script).
 2752    Then, only the compromised mail node's authority certificate needs to be
 2753    tossed out, regenerated, and redistributed.
 2755    TODO: it may be possible to avoid generating individual certificates, and
 2756    distribute self-signed certificate authority certs only, with a
 2757    properly-initialized commonName field. This needs to be researched.
 2759    There are some minor differences between using -S STARTTLS versus putting
 2760    the domain into esmtproutes. If the sending mail node forward mail to this
 2761    domain via UUCP, -S STARTTLS will bounce. Since esmtproutes does not apply
 2762    to UUCP, putting this domain in esmtproutes will have no effect
 2763    whatsoever.
 2765 OPTIONAL: Configure the Sender Policy Framework
 2767    The Courier mail server can optionally check the return address on all
 2768    SMTP mail for the sender's published Sender Policy Framework (SPF). Keep
 2769    in mind SPF is an experimental protocol that's still maturing. The Courier
 2770    mail server's SPF configuration is set up in the "bofh" configuration
 2771    file, and is fully explained in the courier(8) manual page.
 2773 OPTIONAL: Configure the IMAP server
 2775    The Courier mail server includes an integrated IMAP server. The following
 2776    steps set it up:
 2778      • If using virtual mail accounts the system limit on the maximum number
 2779        of inotify file descriptors, /proc/sys/fs/inotify/max_user_instances,
 2780        will likely need to be increased, since all IMAP processes will be
 2781        running under the same userid. Rough metric is the maximum number of
 2782        concurrent IMAP sessions multiplied by 4. On very large servers it may
 2783        also be necessary to increase /proc/sys/fs/inotify/max_user_watches, a
 2784        rough metric would be at least 5 times the max_user_instances setting.
 2785      • Edit /usr/lib/courier/etc/imapd. If you want to use IMAP SASL
 2786        authentication, set up the IMAP_CAPABILITY variable. It performs the
 2787        equivalent function as the ESMTPAUTH variable in the esmtpd
 2788        configuration file, except that IMAP_CAPABILITY also sets several
 2789        other IMAP capabilities that are advertised to IMAP clients. Also, for
 2790        IMAP, CRAM-MD5/SHA1 authentication has been tested, and is known to
 2791        work, so it is listed as a default. Also, note than if the authpam
 2792        authentication module is used, you will need to configure the "imap"
 2793        PAM service. Other authentication modules have their own requirements
 2794        too.
 2795      • Uninstall any existing IMAP server that you have, remove the entry for
 2796        the IMAP port in /etc/inetd.conf, and restart the inetd daemon.
 2797      • Add the following command to your system startup script
 2799  /usr/lib/courier/sbin/imapd start
 2801        Of course, add /usr/lib/courier/sbin/imapd stop to your shutdown
 2802        script too.
 2804    NOTE: if you have previously installed the stand-alone version of the
 2805    Courier IMAP server, you will need to remove it prior to using the
 2806    directly integrated version. They use the same base source code, but have
 2807    a slightly different configuration.
 2809    NOTE: this IMAP server supports maildirs only. It does not support mbox
 2810    file mailboxes.
 2812 Configure IMAP shared folders
 2814    It is possible to share folders between different mailboxes, via IMAP. See
 2815    the file maildir/README.sharedfolders.(txt|html) for more information.
 2817 OPTIONAL: Configure IMAP over SSL
 2819    To add SSL support you have to install OpenSSL or GnuTLS before installing
 2820    the Courier mail server. Download OpenSSL from http://www.openssl.org/, or
 2821    GnuTLS from http://www.gnutls.org.
 2823    OpenSSL's support is well-tested, the GnuTLS version is a relatively new
 2824    addition, and is considered experimental. Follow OpenSSL's or GnuTLS's
 2825    installation instructions, then build the Courier mail server.
 2827    > NOTE: Most systems already have an available OpenSSL or GnuTLS package.
 2828    > Do not build OpenSSL or GnuTLS yourself, if a prebuilt package is
 2829    > already available. Just install the prebuilt package.
 2831    > NOTE: The development libraries must be installed in addition to the
 2832    > runtime package, in order to build the Courier mail server. On most
 2833    > systems, the development files (header files, libraries, etc...) are
 2834    > provided in a separate "devel" package. The base OpenSSL/GnuTLS package
 2835    > is not sufficient to build the Courier mail server, the development
 2836    > libraries must be installed.
 2838    The OpenSSL library is selected when both OpenSSL and GnuTLS libraries are
 2839    found by the configure script. Use the --with-gnutls option to explicitly
 2840    select GnuTLS library over OpenSSL.
 2842    The /usr/lib/courier/etc/imapd-ssl configuration file sets some additional
 2843    options for SSL support, which you may need to adjust. Consult that
 2844    configuration file for additional information. Then, you also have to run
 2845    the /usr/lib/courier/sbin/imapd-ssl script from your system startup and
 2846    shutdown scripts, just like the /usr/lib/courier/sbin/imapd script. You
 2847    may accept both SSL and non-SSL connections by running both scripts.
 2849    Note that SSL requires a valid, signed, X.509 certificate to be installed
 2850    where the Courier mail server expects to find it. The default location for
 2851    the X.509 certificate, in PEM format, is /usr/lib/courier/share/imapd.pem.
 2852    The X.509 certificate must be signed by a certificate authority that is
 2853    known to the IMAP client. You can generate your own self-signed
 2854    certificate by running the script /usr/lib/courier/share/mkimapdcert which
 2855    will work too, except that IMAP clients using SSL will display a warning
 2856    message the first time they connect to the server. To get rid of the
 2857    warning message you'll have to pay for a signed X.509 certificate. The
 2858    gory details of setting up SSL is beyond the scope of this document, and
 2859    you should consult the OpenSSL documentation for more information.
 2861    The mkimapdcert script will not overwrite an existing imapd.pem
 2862    certificate, in order to allow precompiled packages to simply call
 2863    mkimapdcert after installation, without worry.
 2865    The IMAP server also supports the IMAP STARTTLS extension as an
 2866    alternative or a complement to IMAP over SSL. The
 2867    /usr/lib/courier/etc/imapd-ssl configuration file is also used to enable
 2868    or disable IMAP STARTTLS, which has all the same requirements and
 2869    prerequisites as IMAP over SSL.
 2871 OPTIONAL: Sending mail via an imap connection
 2873    This server allows using the IMAP connection to send E-mail. Normally, the
 2874    IMAP protocol provides only access to mail in an existing mail account,
 2875    and mail clients must use SMTP in order to send mail. The Courier IMAP
 2876    server has an optional setting to enable mail to be send via an IMAP
 2877    connection in a manner that should work with all existing IMAP mail
 2878    clients. This can be useful when an account is logged in from a shared
 2879    access pool which normally blocks most access to the SMTP port.
 2881    This is implemented by enabling a setting in the imapd configuration file
 2882    that designates a folder as a special "Outbox" folder. The default setting
 2883    is a folder called "Outbox" (IMAP path INBOX.Outbox), but the name can be
 2884    changed to anything. This folder, for the most part, is no different than
 2885    any other folder. If a folder by that name doesn't exist, it needs to be
 2886    created, just like any other IMAP folder. It looks and acts like any other
 2887    folder, except that each message added to the folder, via IMAP's APPEND or
 2888    COPY command, will also be mailed out by the Courier IMAP server to the
 2889    addresses listed in the To:, Cc:, and Bcc: headers.
 2891    It should be possible to use this to send mail from any IMAP client by:
 2893     1. Composing a draft message, telling the IMAP client to save the draft
 2894        message in its drafts folder on the IMAP server.
 2895     2. Opening the drafts folder, and moving or copying the message to the
 2896        Outbox folder.
 2897     3. The act of copying the message into the Outbox folder will send the
 2898        mail. There won't be any explicit notification to the fact that the
 2899        message was sent, so it's a good idea to include your own E-mail
 2900        address on the Cc: list.
 2902    > NOTE: it is tempting to configure the IMAP mail client to use Outbox as
 2903    > its default folder for saving drafts. Resist the temptation. If you
 2904    > forget, you'll save a partially completed draft, which will be then
 2905    > obediently mailed out.
 2907    > NOTE: the message, in addition to being sent, will be saved in the
 2908    > folder in the normal fashion. After saving the message, reopen the
 2909    > Outbox folder and delete the sent message, or move it someplace else.
 2911    > NOTE: when enabled, the Courier IMAP server will advertize a private
 2912    > XCOURIEROUTBOX IMAP capability. It is theoretically possible to code an
 2913    > IMAP mail client that reads this capability and automatically configures
 2914    > itself accordingly -- when this IMAP capability is present -- to send
 2915    > E-mail in the normal way but using the IMAP connection. At this time,
 2916    > I'm not aware of any actual mail clients that know how to do this.
 2918    > NOTE: many mail clients save some additional internal information in
 2919    > headers of draft messages. The internal information is normally removed
 2920    > before the mail client sends the message. Make sure that none of this
 2921    > extra information is something that should not be mailed out.
 2923 OPTIONAL: Configure IMAP realtime folder status updates
 2925    It's possible to allow multiple clients to open the same folder, and have
 2926    all clients to be simultaneously notified of any changes to the folder
 2927    contents.
 2929    After installing the server see the imapd(8) manual page for more
 2930    information.
 2932 OPTIONAL: Configure SMAP
 2934    Starting with the Courier mail server 0.43, the IMAP server supports an
 2935    experimental mail access protocol, dubbed "Simple Mail Access Protocol".
 2936    SMAP is an experiment to provide enhanced mail processing beyond what's
 2937    currently possible with IMAP. SMAP's purpose is to prototype and develop
 2938    advanced mail access functionality that's not possible with IMAP. SMAP is
 2939    disabled by default. Uncomment the SMAP_CAPABILITY setting in the imapd
 2940    configuration file in order to enable SMAP. The Cone mail client supports
 2941    SMAP.
 2943 OPTIONAL: Configure the POP3 server
 2945    The Courier mail server includes an integrated POP3 server. The following
 2946    steps will set it up:
 2948      • Edit /usr/lib/courier/etc/pop3d. Very few POP3 clients support POP3
 2949        SASL authentication, but if you want to use it, for some reason,
 2950        uncomment the POP3AUTH variable. It performs the equivalent function
 2951        as the corresponding variable in the esmtpd and imapd configuration
 2952        files. For POP3, SASL LOGIN authentication has been tested, and is
 2953        known to work, and CRAM-MD5/SHA1 has not been tested. Also, note than
 2954        if authpam is used, you will need to configure the "pop3" PAM service.
 2955        Other authentication modules have their own requirements.
 2956      • Uninstall any existing POP3 server that you have, remove the entry for
 2957        the POP3 port in /etc/inetd.conf, and restart the inetd daemon.
 2958      • Add the following command to your system startup script:
 2960  /usr/lib/courier/sbin/pop3d start
 2962        Of course, add /usr/lib/courier/sbin/pop3d stop to your shutdown
 2963        script too.
 2965    NOTE: this POP3 server supports maildirs only. It does not support mbox
 2966    file mailboxes.
 2968 OPTIONAL: Configure POP3 over SSL
 2970    Implementing POP3 over SSL is very similar to implementing IMAP over SSL.
 2971    The only differences are that the startup/shutdown command is
 2972    "/usr/lib/courier/sbin/pop3d start" and "/usr/lib/courier/sbin/pop3d
 2973    stop", the configuration file is /usr/lib/courier/etc/pop3d, the name of
 2974    the required SSL certificate is /usr/lib/courier/share/pop3d.pem, and the
 2975    command to generate a test SSL certificate is mkpop3dcert.
 2977 OPTIONAL: Configure the IMAP/POP3 aggregator proxy
 2979    It is possible to distribute IMAP and POP3 mailboxes between multiple
 2980    server.
 2982    See imap/README.proxy for more information.
 2986    The Courier mail server can use SSL certificates for authentication
 2987    purposes. That is, instead of using a login ID and a password, for
 2988    accessing the mailbox, The Courier mail server uses a client-side SSL
 2989    certificate. For certificate authentication purposes, one of the fields in
 2990    your certificates' subject must match the login ID in the authentication
 2991    database. Consider the following certificate:
 2993    ...
 2994    Subject: C=US,ST=New York,L=New York,O=Acme Widgets Inc,CN=John Smith,emailAddress=johnsmith@example.com
 2996    If the emailAddress field is configured as the login ID, the
 2997    authentication database must provide login details for
 2998    johnsmith@example.com. To enable certificate authentication, edit the
 2999    following configuration files in sysconfdir: imapd-ssl, pop3d-ssl, esmtpd
 3000    and esmtpd-ssl (the esmtpd files enable SSL certificate authentication for
 3001    incoming SMTP connections, if a good SSL certificate is provided, the
 3002    client receives mail relaying privileges). All of these configuration
 3003    files require the same set of changes:
 3005      • Set TLS_TRUSTCERTS to the filename with your certificate authority's
 3006        X.509 certificate.
 3008      • Change the TLS_VERIFYPEER setting to "PEER". The setting can also be
 3009        changed to "REQUIREPEER" to require all SSL/TLS connections to provide
 3010        a certificate. Otherwise, it is optional. If the mail client provides
 3011        an SSL certificate, it may be used to authenticate. Without a
 3012        certificate, password-based authentication remains an option.
 3014      • Change the TLS_EXTERNAL setting to the name of the certificate subject
 3015        field that gives the login ID. In the above example, this would be
 3016        "TLS_EXTERNAL=emailaddress".
 3018        > NOTE: GnuTLS's certtool uses "email" as the name of this field. If
 3019        > the Courier mail server is compiled with GnuTLS, you should still
 3020        > specify this field as "emailaddress".
 3022 OPTIONAL: Configure the webmail server
 3024    The integrated webmail server is made up of two parts. The first part, by
 3025    default, is installed as /usr/lib/courier/libexec/courier/webmail. You can
 3026    simply copy this binary executable to your web server's cgi-bin directory,
 3027    or create a link from the cgi-bin directory to this program. This is a
 3028    small stub program that connects, via a local socket, to the sqwebmaild
 3029    daemon process, which implements the webmail service. It is necessary to
 3030    start the webmail server by adding the following command to the system
 3031    startup screen (so that the webmail server gets automatically started at
 3032    boot):
 3034    /usr/lib/courier/sbin/webmaild start
 3036    (It is also possible to run "webmaild stop" from the system shutdown
 3037    script in order to shut down webmail service gracefully).
 3039    Note that the webmail server is used to access mail in existing accounts
 3040    only. There is no provision to create accounts through the webmail
 3041    interface (nor there should be).
 3043   SELinux
 3045    The following extension may be necessary to make webmail work when SELinux
 3046    kernel extensions are turned on:
 3048  allow httpd_sys_script_t var_t:sock_file write;
 3049  allow httpd_sys_script_t unconfined_t:unix_stream_socket connectto;
 3051   Spell checking
 3053    The webmail server can use either the ispell or the aspell package for
 3054    spell checking. Install ispell or aspell before installing the Courier
 3055    mail server.
 3057    NOTE: Courier mail server assumes that the spell checking dictionary is
 3058    called "english". Some systems use a different name for the default spell
 3059    checking dictionary. To change the name of the spell checking dictionary
 3060    used by the webmail server, put the name of the dictionary into the file
 3061    /usr/lib/courier/share/sqwebmail/html/en-us/ISPELLDICT.
 3063   Images
 3065    It is also necessary to install the static icon images used by the webmail
 3066    server. The installation script copies the static images to the
 3067    /usr/lib/courier/share/sqwebmail/images directory. By default, the webmail
 3068    server uses the URL "/webmail/" to specify the location of the static
 3069    images, for example: /webmail/folders.gif. This means that you must create
 3070    a subdirectory called "webmail" in your web server's document root -
 3071    typically /usr/local/etc/apache/htdocs/webmail, or
 3072    /usr/local/www/htdocs/webmail, or something similar. You will need to
 3073    determine the actual location of your web root directory, which varies
 3074    from system to system. Then, create a subdirectory named "webmail", and
 3075    copy all the icons to that directory.
 3077    Another possibility is to install a soft link, instead of creating the
 3078    webmail sub directory, and point the soft link to
 3079    /usr/lib/courier/share/sqwebmail/images (you also must make sure that the
 3080    web server is configured to follow symlinks).
 3082    There is a configuration option, --enable-imageurl, that can be used to
 3083    use something other than /webmail/ as the URL prefix for images.
 3085   Alternative timezones
 3087    The file /usr/lib/courier/share/sqwebmail/html/en-us/TIMEZONELIST contains
 3088    a list of alternative timezones. By default all dates and times are shown
 3089    in the server's default timezone, and the dropdown list on the login
 3090    screen can be used to select an alternative timezone. The default
 3091    alternative timezone list that lists only a small number of timezones.
 3092    Additional timezones can be entered into this file to be shown on the
 3093    login web page.
 3095   LDAP address book import
 3097    The webmail server can import E-mail addresses from public LDAP address
 3098    books into an individual address book. A default systemwide list of
 3099    accessible LDAP address books is defined for everyone, and individuals can
 3100    configure additional LDAP address books for themselves.
 3102    The OpenLDAP development toolkit must be installed before building
 3103    SqWebMail, in order for LDAP search code to compile.
 3105    The file ldapaddressbook configuration file should contain a default
 3106    systemwide list of accessible address book. See courier(8) for more
 3107    information. A default file will be installed, listing some common
 3108    Internet address books. Each line in this file contains the following
 3109    information:
 3111  name<tab>host<tab>port<tab>suffix<tab>binddn<tab>bindpw
 3113    <tab> is a single ASCII TAB character. name is the unique name for this
 3114    LDAP server. host and port specify the connection parameters. suffix
 3115    specifies the root LDAP entry whose subtree gets searched. The binddn and
 3116    bindpw fields are not presently used (they were used in earlier version of
 3117    the webmail server, before the LDAP search interface was rewritten and
 3118    simplified).
 3120   Webmail session timeouts
 3122    A login session is automatically logged out after certain period of
 3123    inactivity. The timeout period defaults to 20 minutes, and is set by the
 3124    --enable-softtimeout option to the configure script. It is also possible
 3125    to adjust this value by setting the SQWEBMAIL_TIMEOUTSOFT environment
 3126    variable. For example, with Apache, by adding the following to httpd.conf:
 3130    There is also a hard timeout, which logs out a session no matter what. The
 3131    default of two hours is changed with the --enable-hardtimeout option to
 3132    the configure script, and the SQWEBMAIL_TIMEOUTHARD environment variable.
 3134    WARNING:
 3136    The hard timeout interval is used to calculate the maintenance of the
 3137    login cache (if that option is selected). This factor is used in the
 3138    cleancache.pl cleanup script, and changes to this value must be
 3139    coordinated appropriately. It is not possible to use different hard
 3140    timeout values with the same login cache (in different virtual domains, as
 3141    described in the next session). Leisurely tinkering with this environment
 3142    variable is STRONGLY DISCOURAGED, it's very easy to screw up the whole
 3143    system. You've been warned.
 3145    If you adjust the hard timeout, you must simultaneously delete your
 3146    current login cache directory, and adjust $timeouthard in the installed
 3147    cleancache.pl script.
 3149   Maximum message sizes
 3151    Messages composed in the webmail server are limited in size. The
 3152    additional limitation are on top of the limit set in the sizelimit
 3153    configuration file, see the courier(8) manual page.
 3155    The --with-maxargsize, --with-maxformargsize, and --with-maxmsgsize
 3156    options to the configure script set the parameters that control the
 3157    maximum size of messages and attachments. These parameters can also be set
 3158    through the following environment variables.
 3160    > NOTE: The configure script parameters define the minimum settngs. The
 3161    > following environment variables may be used to set larger limits only.
 3163    > NOTE: These settings limit only the maximum size of messages sent from
 3164    > the webmail server. The limit on the incoming message size is set by
 3165    > other Courier mail server settings (usually the sizelimit setting also).
 3168    Approximate maximum size, in bytes, of the message, excluding any
 3169    attachments (overrides the --with-maxargsize parameter to the configure
 3170    script). This is the maximum message that can be typed into the webmail
 3171    server.
 3173    NOTE: The webmail server has an inactivity timeout. While composing a new
 3174    message use the "Preview" button frequently to save the unfinished message
 3175    and keep the session from timing out.
 3178    Approximate maximum size, of each allowed attachment. (overrides the
 3179    --with-maxargsize parameter to the configure script).
 3181    NOTE: Attaching binary files to E-mail messages incurs an overhead of
 3182    approximately 33%. E-mail is really not the optimum medium for exchanging
 3183    files. Setting SQWEBMAIL_MAXATTSIZE to 4000000 will effectively allow
 3184    attaching files of up to 3000000 bytes in length, approximately.
 3187    Approximate maximum size, of a message, including the text portion and all
 3188    attachments (overrides the --with-maxmsgsize parameter to the configure
 3189    script). There can be any number of attachments, each one up to
 3190    SQWEBMAIL_MAXATTSIZE bytes long, but the sum total of the entire message
 3191    cannot exceed SQWEBMAIL_MAXMSGSIZE.
 3193    These variables must be set in the environment that runs the webmail CGI
 3194    program. With Apache, these variables can be set in the httpd.conf file by
 3195    the SetEnv command. httpd.conf example:
 3197    SetEnv SQWEBMAIL_MAXATTSIZE 1000000
 3198    SetEnv SQWEBMAIL_MAXMSGSIZE 4000000
 3200    > NOTE: These settings are global, and apply to all mailboxes. However,
 3201    > advanced Apache configuration can be used to use different environment
 3202    > variable settings with different virtual hosts.
 3204    > NOTE: On 32-bit platforms, the maximum limits may not exceed 2
 3205    > gigabytes. A 64-bit platform is required to have SqWebMail capable of
 3206    > handling attachments and messages larger than 2 gigabytes.
 3208   Random seed
 3210    A random seed is required for preventing certain kinds of external attacks
 3211    against the SqWebMail server. The random seed must be a constant value,
 3212    only varying between different instances of SqWebMail. By default the
 3213    random seed is derived from the inode number of one of the supporting
 3214    script files. The script file ordinarily remains constant, thus the random
 3215    seed does not change, but different SqWebMail installs will end up with a
 3216    different seed.
 3218    When a pool of SqWebMail servers is combined for load-balancing, all
 3219    servers must use the same random seed. This is done by defining the
 3220    SQWEBMAIL_RANDSEED environment variable. This can be set in the httpd.conf
 3221    as well:
 3223    SetEnv SQWEBMAIL_RANDSEED 82738AZ
 3225    SQWEBMAIL_RANDSEED should contain up to ten letters or numbers.
 3227   Domain-based templates
 3229    The default set of templates for the dynamically generated HTML is
 3230    installed in /usr/local/share/sqwebmail/html. When the same server is used
 3231    to provide webmail access for multiple domains it is possible to specify a
 3232    different set of HTML templates for each domain.
 3234    This functionality is not directly implemented in SqWebMail, simply
 3235    because there is no standard way to specify this. Instead, this is
 3236    something that will need some minor work set up.
 3238    Domain-based templates are implemented by making the web server set the
 3239    environment variables SQWEBMAIL_TEMPLATEDIR prior to running the sqwebmail
 3240    binary. The contents of this environment variable override the default
 3241    location of /usr/local/share/sqwebmail/html. By having the web server
 3242    initialize this variable based on the domain name it is possible to
 3243    present different templates, based on the domain name used.
 3245    To do this, make copies of the HTML template directory,
 3246    /usr/local/share/sqwebmail/html. Then, configure the web server to
 3247    initialize SQWEBMAIL_TEMPLATEDIR appropriately. For example, with Apache:
 3249    <VirtualHost a.b.c.d>
 3250      ServerName webmail.example.com
 3251      [...]
 3252      SetEnv SQWEBMAIL_TEMPLATEDIR /usr/local/share/webmail/webmail.example.com
 3253      [...]
 3254    </VirtualHost>
 3256    The possibilities are endless.
 3258   Name-based templates
 3260    It is now possible to display two or more templates from the same CGI
 3261    binary WITHOUT setting up multiple domain names.
 3263    For example, with Name-based templates an sqwebmail administrator can set
 3264    up sqwebmail to display a template in the /usr/local/share/sqwebmail/html
 3265    directory when sqwebmail is called from the URL:
 3266    http://www.foo.com/cgi-bin/sqwebmail
 3268    And display a different template in the
 3269    /usr/local/share/sqwebmail/alternate-html directory when sqwebmail is
 3270    called from the URL: http://www.foo.com/cgi-bin/sqwebmail-alt-template
 3272    This is made possible by a little web server magic (explained below in the
 3273    section entitled "Apache Name-based template configuration example") and
 3274    the setting of TWO sqwebmail environment variables:
 3279    You should recognize the SQWEBMAIL_TEMPLATEDIR environment variable from
 3280    the section above on Domain-based templates. If you haven't read that
 3281    section yet, please do so now.
 3283    The SQWEBMAIL_IMAGEURL environment variable is new in versions of
 3284    sqwebmail greater than sqwebmail- It allows us to set, at
 3285    run time, the image URL, or the root URL, in which to look for our
 3286    template's images. This image URL is then automatically inserted into the
 3287    current template anytime a conditional image tag or an IMAGEURL tag is
 3288    encountered.
 3290    This is an example of a conditional image tag:
 3292    [#@image.gif, ... @text@#]
 3294    The conditional image tag is replaced at template processing time with an
 3295    HTML <img src="..."> tag if (hence the word "conditional") sqwebmail is
 3296    set up to display images.
 3298    This is an example of an IMAGEURL tag:
 3300    [#IMAGEURL#]
 3302    The IMAGEURL tag is replaced at template processing time with the contents
 3303    of the SQWEBMAIL_IMAGEURL environment variable, if set, and otherwise with
 3304    the value of the --with-imageurl configure option, which defaults to
 3305    "/webmail".
 3307   Apache Name-based template configuration example
 3309    Let's take a look at a simple Apache Name-based sqwebmail template
 3310    configuration example:
 3313    # Sqwebmail Alternate Template URL
 3314    ScriptAlias /cgi-bin/sqwebmail-alt-template "/usr/local/apache/cgi-bin/sqwebmail"
 3316    <Location /cgi-bin/sqwebmail-alt-template>
 3317        Setenv SQWEBMAIL_TEMPLATEDIR "/usr/local/share/sqwebmail/alternate-template"
 3318        Setenv SQWEBMAIL_IMAGEURL "/alternate-webmail"
 3319        [...]
 3320    </Location>
 3323    The above should allow your users to run sqwebmail with the template in
 3324    /usr/local/share/sqwebmail/alternate-template and an image URL of
 3325    /alternate-webmail, simply by calling sqwebmail from the following URL:
 3327    http://www.yourdomain.com/cgi-bin/sqwebmail-alt-template
 3329    The original sqwebmail templates would then still be available from this
 3330    URL:
 3332    http://www.yourdomain.com/cgi-bin/sqwebmail
 3334    Using Apache's <Location> directive we can utilize a virtually unlimited
 3335    number of templates without setting up a single virtual domain.
 3337 OPTIONAL: Configure webmail calendaring
 3339    Optional calendaring services can be enabled in the webmail server. Right
 3340    now, the current implementation provides basic calendaring services. For
 3341    more information on calendaring, see the file pcp/README.html.
 3343 OPTIONAL: Configure mail filtering for the webmail server
 3345    This is an optional feature where the webmail server is used to
 3346    automatically set up mail filtering rules to forward or deliver incoming
 3347    mail to folders. This feature requires maildrop to be used as the local
 3348    mail delivery agent.
 3350    Edit the courierd configuration file, and follow the instructions in that
 3351    file to install maildrop as the local mail delivery agent. Then, follow
 3352    the instruction below to create the maildirfilter configuration file,
 3353    which may be installed either in the global configuration file directory
 3354    (/usr/lib/courier/etc by default), or in each individual Maildir (which
 3355    overrides the global default).
 3357    Implementing mail filtering requires a couple of dominos to fall in the
 3358    right order. This is not difficult to do, but is a bit tricky. Here's how
 3359    it works, in general. Specifics follow.
 3361    Some people would probably have a difficult time setting it up. That's to
 3362    be expected. The implementation allows only selected accounts to be set up
 3363    for mail filtering, so the suggested way is to attempt to set up mail
 3364    filtering for one account only, test it to make sure it works, then roll
 3365    it out globally.
 3367   The big picture
 3369    The maildrop mail filter is used to do the actual mail filtering. maildrop
 3370    must be installed as your local mail delivery agent. The next thing to do
 3371    is to actually learn how maildrop works, and learn its filtering language.
 3372    Although the mail filter will be automaticaly generated here, you still
 3373    need to become familiar with the filtering language in order to
 3374    troubleshoot any installation problems. maildrop comes with manual pages
 3375    documenting the filtering language, as well as some examples. Read them.
 3377   The little picture
 3379    Here's what's going to happen. The webmail server will automatically
 3380    generate a maildrop filtering recipe. maildrop reads the recipe, and does
 3381    its thing. Sounds simple enough, right?
 3383    Well, it's not. There are a few little details that need to be resolved.
 3385    For starters, the default maildrop filtering recipe is $HOME/.mailfilter.
 3386    That's how things usually work physical system accounts are used. When
 3387    virtual mailboxes are installed, things are less murky. There are several
 3388    ways to set up virtual mailboxes, described elsewhere in this INSTALL
 3389    file, so the actual implementation varies from system to system. Somehow,
 3390    the virtual mailboxes share the same physical account, and have the same
 3391    $HOME. In that case the usual approach is for each virtual mailbox to have
 3392    the corresponding mail filtering recipe manually specified to maildrop as
 3393    an extra command line argument. Review the maildrop documentation for more
 3394    information.
 3396    Now, on the other hand, the webmail server doesn't really know anything
 3397    about physical and virtual accounts. The mapping between a login ID and
 3398    the maildir is completely encapsulated in the black box-type
 3399    authentication library. The login ID and password are validated by the
 3400    authentication library, which obtains the maildir corresponding to the
 3401    login ID, and the webmail server is started for that maildir. Whether or
 3402    not a login ID corresponds to an actual system account or to virtual
 3403    account, that's something the webmail server doesn't really know, or care.
 3404    All it cares about is the maildir where all the mail is, and that's the
 3405    end of the story. (The IMAP and POP3 servers work the same way).
 3407    So, the issue is that the webmail server needs to find the corresponding
 3408    maildrop filtering recipe, so it knows where to write the mail delivery
 3409    instructions. That's the deal
 3411    In order for mail filtering to be enabled, it is necessary to initialize
 3412    the file named maildirfilterconfig in the maildir itself. This is where
 3413    the webmail server runs, so it simply reads this file. The contents of
 3414    this file should be as follows:
 3416  MAILDIRFILTER=pathtomailfilter
 3417  MAILDIR=pathtomaildir
 3419    pathtomailfilter specifies the location of the maildrop filtering recipe
 3420    for this maildir, relative to the maildir itself. Set the current
 3421    directory to the maildir directory. Now ask yourself, where's my maildrop
 3422    filtering recipe?
 3424    In most cases, where virtual mailboxes are not used, everyone's maildir is
 3425    $HOME/Maildir, and maildrop uses $HOME/.mailfilter by default. In this
 3426    case, pathtomailfilter must be set to ../.mailfilter.
 3428    When virtual mail accounts are used, this will obviously be something
 3429    else. The only requirement is that the maildrop filtering recipe and the
 3430    maildir must be on the same filesystem or partition.
 3432    pathtomaildir is the other half of the story. When maildrop gets a message
 3433    to deliver, maildrop needs to know where the mailboxes and folders are.
 3434    Maildrop begins running in what it considers to be the recipient's home
 3435    directory, reading either .mailfilter, by default, or the file specified
 3436    on the command line.
 3438    The webmail server needs to generate filtering instruction that deliver
 3439    messages to its maildir. By default, the maildir for non-virtual accounts
 3440    is $HOME/Maildir, so pathtomaildir needs to be set to ./Maildir.
 3442   Summary for virtual accounts
 3444    Basically, 99% of the time MAILDIRFILTER will be ../.mailfilter and
 3445    MAILDIR will be ./Maildir. When virtual mail accounts are used, maildrop
 3446    still must be used as a mail delivery agent. Somehow, the correct maildir
 3447    that corresponds to the recipient's mail account must be specified as the
 3448    argument to maildrop. Usually all or most virtual accounts are set up
 3449    inside a single physical account. In that case it is necessary to set up a
 3450    different maildrop filtering recipe file for each virtual mail account
 3451    (since everyone's $HOME/.mailfilter will be the same file), and in each
 3452    maildir specify the relative path to its corresponding filtering recipe,
 3453    and the relative path to the maildir from the default home directory.
 3454    Then, for each virtual mail account, the mail server must run maildrop to
 3455    do the actual mail delivery, explicitly specifying the filtering recipe to
 3456    be used.
 3458   The global maildirfilterconfig file
 3460    In most cases where virtual mail accounts are not used, every maildir's
 3461    maildirfilterconfig should be the same. As an alternative to installing
 3462    the same maildirfilterconfig in each maildir, it is possible to install a
 3463    single maildirfilterconfig systemwide.
 3465    Install the global maildirfilterconfig in the Courier mail server's
 3466    configuration directory (/usr/lib/courier/etc by default).
 3468    The global maildirfilterconfig will be used unless maildirfilterconfig
 3469    exists in the maildir directory. Therefore, the global maildirfilterconfig
 3470    can be used to provide a default for the majority of the mail accounts,
 3471    and any exceptions are handled by installing maildirfilterconfig in the
 3472    maildir directory, whose contents will override the global file.
 3474   Happy filtering.
 3476    If everything is set up correctly, the webmail menu will present a new
 3477    link to a screen where mail filtering rules are defined and installed. A
 3478    mail filter consists of a condition, and an action. A condition is usually
 3479    based on the contents of some header, or the message body. Regular
 3480    expressions are allowed. Which means that certain special characters must
 3481    be quoted. For example, to search for the string "[announce]" verbatim in
 3482    the subject header, it must be entered as "\[announce\]". Pattern
 3483    matching, for now, is case-insensitive. The regular expression syntax uses
 3484    pretty much the same syntax as Perl. See the maildropfilter manual page
 3485    for more information.
 3487    Multiple mail filtering rules can be installed. Their relative order can
 3488    be rearranged by selecting a filtering rule, then selecting either the
 3489    "Up" or the "Down" button. It is necessary to select "Save all changes"
 3490    for any changes to the filtering rules to take effect. Leaving that page
 3491    in any other way will throw away all changes made.
 3493   Webmail runtime configuration
 3495    There are some options which can be used to change the webmail server's
 3496    behavior for individual accounts, or globally, using the "Account Options"
 3497    feature in the Courier mail server Authentication library. The individual
 3498    account's setting takes precedence over the DEFAULTOPTIONS settings in the
 3499    authdaemonrc configuration, so for example if you want to disable webmail
 3500    access for most accounts but enable it for a select few, you can set
 3501    DEFAULTOPTIONS="disablewebmail=1" in the authdaemonrc configuration file,
 3502    and add the option disablewebmail=0 to individual accounts. See the
 3503    section "Account options" in README_authlib.html in the courier-authlib
 3504    package for more information on setting the following account options:
 3506    disablewebmail - if set to a non-zero value, this account will not be
 3507    permitted to login to webmail (e.g. because the user is only allowed to
 3508    use POP3 or IMAP)
 3510    wbnochangingfrom - if set to a non-zero value, the webmail server will not
 3511    allow the From: header to be changed, it will always have its default
 3512    value.
 3514    wbnochangepass - if set to a non-zero value, the webmail server will not
 3515    allow passwords to be changed. See "Changing mail account passwords using
 3516    the webmail server", below, for more information.
 3518    wbusexsender - if set to a non-zero value, the webmail server will attach
 3519    an X-Sender: header to all outgoing messages. This can be used in the
 3520    event you would like to be able to modify the From: header, yet also be
 3521    able to track sent mail to the original account.
 3523    wbnoimages - if set to a non-zero value then no images or icons will be
 3524    used. The generated interface will be a text-only interface.
 3526    wbnodsn - set to a non-zero value then the option to request delivery
 3527    confirmation receipts will not be shown.
 3529 OPTIONAL: Changing mail account passwords using the webmail server
 3531    After installing the webmail server be sure to test that the login
 3532    password can be changed through the webmail server.
 3534    If you do not want to use the password change function you can also remove
 3535    the sqwebpasswd program. This is a helper program, installed with the
 3536    set-groupid bit set, that relays the password change request to the
 3537    authentication daemon, through the filesystem socket that is not globally
 3538    accessible. The password change request consists of the account name, the
 3539    old password, and the new password. The password change request is
 3540    validated by the authentication daemon, and the old password must match
 3541    the existing password on the account, before the password change goes
 3542    through. This set-groupid helper program is safe to use.
 3544 OPTIONAL: Configure autoreplies for the webmail server
 3546    Enabling mail filtering, according to the instructions in the previous
 3547    section, automatically enables MIME autoreply capability. The webmail
 3548    interface can be used to configure simple autoresponders. By default there
 3549    is no limit on the number of the size of created autoreplies, therefore it
 3550    is recommended that a quota be set up on the autoreplies.
 3552    An global autoreply quota is set up by initializing the
 3553    /usr/lib/courier/etc/autoresponsesquota configuration file. This file sets
 3554    the autoreply quota globally. An autoresponsesquota file in the Maildir
 3555    will override the global quota setting for that maildir only. See the
 3556    courier(8) manual page for the description of the autoresponsesquota file.
 3558    Autoreplies can include any valid MIME content (MIME content other than
 3559    plain text can be uploaded). The following special procedure needs to be
 3560    used to prepare multipart autoreply content, such as text and html
 3561    alternatives of the same message:
 3563    Assign a filename extension to the message/rfc822 MIME content. For
 3564    example, edit your mime.types file, find the message/rfc822 MIME type
 3565    (append one if it's not in mime.types), and make sure that it has at least
 3566    one filename extension, such as "msg".
 3568    Prepare the multipart MIME autoreply. The most convenient way is to
 3569    prepare a normal E-mail message using a conventional E-mail client. Save
 3570    the RFC822-formatted message in a file with a ".msg" extension, and upload
 3571    it on the autoreply screen.
 3573    Webmail handles uploaded message/rfc822 content by removing all headers
 3574    except the MIME headers, leaving the MIME content type header, and the
 3575    actual MIME content.
 3577    Normally there is no limit on the number or the total size of autoreplies
 3578    configured via the webmail server. A quota can be installed by
 3579    initializing the autoresponsesquota configuration file. See courier(8) for
 3580    more information.
 3582 OPTIONAL: Configure encryption for the webmail server
 3584    This is an optional feature in the webmail server that uses GnuPG to send
 3585    and receive encrypted/signed E-mail. There is no encryption code in the
 3586    webmail server, it uses GnuPG to do encryption and decryption. For more
 3587    information on setting up and using encryption, read the file
 3588    gpglib/README.html in the source distribution.
 3590 OPTIONAL: Install automatically-appended footer text for webmail messages
 3592    /usr/lib/courier/share/sqwebmail/html/LANG/footer - if this file exists,
 3593    its contents will be appended to the end of every sent message from the
 3594    webmail server. The actual directory where sqwebmail's html language files
 3595    are installed may be different with prebuilt Courier packages. LANG is the
 3596    language code here, there can be a separate footer per installed language.
 3597    The footer file carries the following requirements:
 3599      • The footer file must be coded in UTF-8.
 3601      • The footer file must follow the format=flowed; delsp=yes format, as
 3602        specified by RFC 3676. Capsule summary:
 3604           • Paragraphs are delimited by blank lines.
 3606           • Paragraphs that consist of more than one line must have a
 3607             trailing space ending each line except the last line in the
 3608             paragraph.
 3610           • That trailing space is in addition to a space that delimits
 3611             individual words in most Western languages. Therefore, a line
 3612             that ends on a word without punctuation and continues with the
 3613             next word at the beginning of the next line must end with two
 3614             spaces: the usual space that separates individual words, and a
 3615             second space that indicates that the paragraph continues on the
 3616             next line.
 3618           • Restated: a line that ends with a space is logically joined with
 3619             the next line, after the trailing space is logically removed.
 3621           • Lines that begin with a space character or the ">" character must
 3622             have an additional space character prepended to them. This
 3623             leading space character is logically removed from the contents of
 3624             the line.
 3626        A convenient way to format text in flowed format is to use the leaf
 3627        editor that's part of the Cone package.
 3629      • Signature content gets formatted as part of the message together with
 3630        the rest of the content. Sender-selected option to format the message
 3631        as either a plain text message, or using wiki-style HTML markup
 3632        applies to the footer file too. The footer file's contents should be
 3633        constructed taking into account the possibility that wiki-style HTML
 3634        markup may get optionally applied to the footer content.
 3636 OPTIONAL: Quota support
 3638    There are two ways to implement a quota on the size of a mail account:
 3639    filesystem quotas and maildir quotas:
 3641   Filesystem quotas
 3643    The maximum disk space quota is implemented within the operating system's
 3644    filesystem support code. Here, the operating system enforces the maximum
 3645    disk space that can be used by each account. This is the only reliable
 3646    quota implementation if individual accounts have login access to the mail
 3647    account. Maildir quotas (see below) are implemented entirely within the
 3648    maildir support code, and can easily be superceeded by anyone with login
 3649    access to the mail account. Additionally, mail accounts must all be system
 3650    accounts. Virtual accounts -- that share the same physical system userid
 3651    -- cannot usually be support by filesystem-based quotas, because all mail
 3652    accounts have the same userid and groupid.
 3654    The webmail server cannot be used with filesystem quotas. The webmail
 3655    server creates and maintains, all by itself, a number of database files
 3656    that are used to quickly index and access messages. If an account exceeds
 3657    its disk quota, the webmail server will not be able to create and update
 3658    those database file, which results in a rather spectacular crash. If login
 3659    access is available, it is possible to log in and manually delete some
 3660    files to reclaim some disk space. If login access is not available, the
 3661    administrator will have to manually fix the account -- the webmail server
 3662    will not even be able to open an existing folder and delete messages in
 3663    order to free up disk space. There is some good news, though: the IMAP and
 3664    the POP3 server can still be used to access and delete messages from the
 3665    mail account. Due to the way that out-of-quota condition is handled by the
 3666    IMAP server, some IMAP clients may mark any existing messages in the
 3667    account as unread, but that is a minor glitch that does no harm.
 3669   Maildir quotas
 3671    The Courier mail server can manually enforce a quota for mail accounts
 3672    that use maildirs. This quota enforcement is implemented entirely in
 3673    software, and is available only when maildirs are used. This quota
 3674    implementation will also work with virtual accounts. Maildir quota support
 3675    is available only with userdb, LDAP, MySQL and PostgreSQL authentication
 3676    back-ends. Maildir quotas are supported by IMAP, POP3, and the webmail
 3677    server. To add a maildir quota with userdb, run the following commands,
 3678    for example:
 3680  userdb account set quota=quota
 3681  makeuserdb
 3683    Here, account identifies the account to which the quota applies, and quota
 3684    is the quota specification, as described in the maildirquota(7) manual
 3685    page.
 3687    To implement a quota with an LDAP, MySQL, or a PostgreSQL back end, simply
 3688    follow the instructions given in the corresponding configuration file.
 3690 Account OPTIONS
 3692    It is possible to adjust certain parameters on an account-by-account
 3693    basis. This feature is actually implemented in the Courier mail server
 3694    Authentication Library. See ACCOUNT OPTIONSin the auth_generic manual
 3695    page.
 3697 OPTIONAL: Configure outbound faxing
 3699    Fax sending is disabled by default and must be explicitly enabled,
 3700    according to the following instructions. After fax sending is enabled,
 3701    addressing an E-mail message to <5552000@fax> will have this message
 3702    faxed.
 3704    Of course, the necessary hardware and software must be available. The
 3705    requisite hardware is a class 2 faxmodem attached to a serial port.
 3706    Additional software, separate from the Courier mail server, must also be
 3707    installed. The Courier mail server does not handle the actual job of
 3708    faxing. The Courier mail server only reformats E-mail messages as fax
 3709    images, and runs mgetty+sendfax to send the fax. The Courier mail server
 3710    also needs additional software to convert E-mail messages to faxes. All
 3711    additional software must be separately installed, configured, and tested
 3712    before enabling faxing in the Courier mail server. Most systems already
 3713    include the following software as part of the base operating system, so in
 3714    most cases adding fax support will not actually require any additional
 3715    software to be installed, only minor reconfiguration of existing software:
 3717   mgetty+sendfax
 3719    mgetty+sendfax works with most Class 2 faxmodems. The Courier mail server
 3720    does not use the spooling scripts found in the mgetty+sendfax package. The
 3721    Courier mail server uses its own mail spool. A fax message is handled no
 3722    differently than any other E-mail message. The only difference is that the
 3723    E-mail message is addressed to <phonenumber@fax>.
 3725    mgetty+sendfax should be configured with its default settings, EXCEPT as
 3726    follows:
 3728      • In /etc/mgetty+sendfax, the "max-tries-continue" setting must be set
 3729        to "n".
 3731   groff or troff, ghostscript, NetPBM
 3733    Conversion of E-mail messages to faxes uses ghostscript, and groff. It
 3734    should be possible to use the original UNIX troff instead of groff, but
 3735    this has not been tested. The Courier mail server generates the fax cover
 3736    page from the contents of the E-mail message's headers. The initial text
 3737    portion of the E-mail message will appear as fax cover page comments. Note
 3738    that the initial text portion of the E-mail message must be in plain text,
 3739    not HTML. E-mail attachments will be converted and attached as additional
 3740    fax pages. E-mail attachments may contain plain text, Postscript or PDF
 3741    documents. Other attachments will result in the E-mail message being
 3742    returned as undeliverable.
 3744    On the cover page, the sender's name, the recipient's name, and the fax
 3745    subject gets taken from the E-mail message's headers. The ability to use
 3746    non-Latin characters depends on the support from the underlying tools,
 3747    ghostscript and groff, for the default system locale.
 3749    Install the NetPBM library to add the ability to fax GIF, JPEG, and PNG
 3750    images. Each image will be converted to a single fax page. Images in
 3751    excess of 1500x1500 pixels (approximately) will be truncated, and color
 3752    images will be dithered to black-and-white.
 3754   Enabling faxing
 3756    The configuration file /usr/lib/courier/etc/faxrc must be edited in order
 3757    to enable faxing. This file sets up the dialing parameters, and the
 3758    default file disables faxing by rejecting all phone numbers. The
 3759    configuration file has extensive comments that explain how dialing
 3760    parameters are set.
 3762    Using webadmin to set up fax sending is highly recommended. A proper faxrc
 3763    will automatically hide all the local daling conventions. Webadmin knows
 3764    how to generate the dialing configuration for the North American dialing
 3765    plan, with a configurable area code. Faxes should be addressed to a fixed
 3766    ten digit area code+phone number address, <nnnxxxxxxx@fax>, which will be
 3767    converted for dialing from the local area code appropriately. Webadmin can
 3768    also optionally enable faxing to international 011 phone numbers. Webadmin
 3769    can also fall back to a bare configuration where all phone numbers are
 3770    dialed as-is, for locations outside of North America.
 3772   Sending faxes
 3774    E-mail messages may contain attachments. The Courier mail server combines
 3775    all attachments in the message into a single fax transmission. Attachment
 3776    types may be freely mixed. A single message may contain one plain text,
 3777    and one PDF attachment, for example. It is possible to select certain
 3778    options, as follows:
 3780      • <phonenumber@fax-lowres>
 3782        sends a low-resolution fax.
 3784      • <phonenumber@fax-ignore>
 3786        Ignore attachments that the Courier mail server doesn't know how to
 3787        convert to a FAX image format. Normally, if an attachment cannot be
 3788        converted the whole message is returned as undeliverable.
 3790      • <phonenumber@fax-cover>
 3792        sends only the cover page. This can be useful for .courier files. See
 3793        the courierfax(8) manual page for an example.
 3795    These options can be combined: <phonenumber>@fax-lowres-ignore>.
 3797   Cover pages
 3799    /usr/lib/courier/etc/faxcoverpage.tr is the troff source for the FAX cover
 3800    page, which includes the first plain text section of the E-mail message.
 3801    Do not attempt to play with faxcoverpage.tr without a clear understanding
 3802    of troff. It is safe to make trivial changes (such as replacing the
 3803    "FACSIMILE COVER PAGE" text).
 3805   Dialing
 3807    The /usr/lib/courier/etc/faxrc configuration file provides rudimentary
 3808    phone number rewriting logic (stuff like dialing "9," to get outside line
 3809    from a PBX). The default faxrc configuration file specifies a typical
 3810    dialing configuration for the North American numbering plan, with seven
 3811    digit local phone numbers, and 1+ten digit long distance phone numbers.
 3812    The area code in the default faxrc configuration file is set to "999", you
 3813    will need to change it to your area code (there are two places in faxrc
 3814    where the area code needs to be set).
 3816    In general, messages should be addressed to the full ten-digit phone
 3817    numbers. The local area code will be stripped automatically, and "1" will
 3818    be dialed before all other area codes. If this is done in practice, local
 3819    area code changes will only require an update to faxrc, without any need
 3820    to update the address book.
 3822    Comments in the faxrc configuration file explain the format of the phone
 3823    number rewriting rules, in the event that local phone system customization
 3824    is required (for example, dialing 9 to get an outside line). Several
 3825    places in North America now use ten digit local phone number overlays,
 3826    with 1+ten digit long distance dialing. TODO: Use webadmin if you are not
 3827    sure how to set this up.
 3829   Security
 3831    The default faxrc configuration file allows only locally-generated faxes.
 3832    faxrc must be modified in order to accept faxes via ESMTP.
 3834    Additionally, faxes are accepted via ESMTP only if the FAXRELAYCLIENT
 3835    variable is set. See the makesmtpaccess(8) man page for additional
 3836    information.
 3838 OPTIONAL: Configure inbound faxing
 3840    mgetty has an option that runs a script called "new_fax" after it receives
 3841    a fax. The default location for this script is either
 3842    /usr/local/lib/etc/mgetty+sendfax/new_fax or /etc/mgetty+sendfax/new_fax.
 3843    Consult your mgetty documentation to determine if the new_fax option is
 3844    enabled, and the exact script location.
 3846    The Courier mail server provides a script -
 3847    /usr/lib/courier/share/faxmail/new_fax - that can be used as mgetty's
 3848    new_fax script. This script converts incoming faxes to PNG images, and
 3849    delivers it to a local mailbox. Simply copy this script to mgetty's etc
 3850    directory (or install a soft link there), to automatically drop incoming
 3851    faxes to a local mailboxes.
 3853    The /usr/lib/courier/etc/faxnotifyrc configuration file specifies the
 3854    mailbox that receives incoming faxes, and several other related options.
 3856 OPTIONAL: Install the Courier mail server log analyzer
 3858    The Courier mail server log analyzer (the courier-analog package) is a
 3859    Perl script that generates log summaries for the Courier mail server. The
 3860    Courier mail server log analyzer generates log summaries for incoming and
 3861    outgoing SMTP connections, and IMAP and POP3 activity. courier-analog can
 3862    generate output in text or HTML format.
 3864    The Courier log analyzer is not included in the main the Courier mail
 3865    server tarball, it must be downloaded separately from
 3866    http://www.courier-mta.org/download.html#analog. After downloading and
 3867    installing this package, see the courier-analog manual page for more
 3868    information.
 3870 OPTIONAL: Configure Courier IP address-specific settings for servers with
 3871 multiple IP addresses
 3873    When running Courier on a server that has more than one IP address, it's
 3874    possible to configure Courier to have a "vanity" configuration for each IP
 3875    address, such as the IP address for outgoing connections for relaying
 3876    messages received by a client that connects to each address, or its server
 3877    name that it uses in the "Received:" headers that Courier adds to each
 3878    message.
 3880    See the "Servers with multiple IP addresses" section in the courier(8)
 3881    manual page for more information.
 3883 OPTIONAL: configure hostname-dependent configuration
 3885    Several Courier configuration files specify settings that reference the
 3886    server's fully-qualified domain name. It is possible to have a fixed set
 3887    of configuration files with the key configuration files using a wildcard
 3888    placeholder for the system hostname, and replicate these configuration
 3889    files to multiple servers with externally- assigned hostname (and likely
 3890    IP addresses), such as DHCP-provided ones; with the server's hostname
 3891    referenced by the relevant placeholders.
 3893    Example: replicate the same set of configuration files to servers assigned
 3894    hostnames of "mx1" and "mx2", via DHCP, with Courier recognizing its
 3895    fully-qualified domain name as "mx1.example.com" and "mx2.example.com",
 3896    respectively.
 3898    See the "Hostname-dependent configuration" section of the courier(8)
 3899    manual page for more information.
 3901 Decommission your existing mail server
 3903    This step consists of flushing the mail queue of your existing mail server
 3904    and removing it from the system.
 3906    If you're using sendmail, edit your startup script, and start sendmail
 3907    with the option '-q30m' only. Remove the -bd option. This causes sendmail
 3908    to stop listening on port 25, and stay as a daemon process only for the
 3909    purpose of running the queue every 30 minutes.
 3911    If you're using Qmail, remove tcpserver from your system startup script.
 3913    Wait for all existing mail to flush itself out, then permanently remove
 3914    your existing server.
 3916    Depending on your system, you may need to create a bunch of soft links,
 3917    such as /usr/bin/sendmail, /usr/sbin/sendmail, /lib/sendmail, or
 3918    /etc/sendmail that point to /usr/lib/courier/bin/sendmail. If you want to
 3919    receive mail via UUCP you will also need to make sure that UUCP knows to
 3920    find rmail in /usr/lib/courier/bin as well.
 3922 Sample init script
 3924    You're now ready to configure your system to start the Courier mail server
 3925    at system boot time (and shut it down at system shutdown). If your system
 3926    uses system-V init scripts, here's a sample script that you can install in
 3927    your /etc/rc?.ddirectories. This is a slightly modified version of the
 3928    init script that's used in the Courier RPM or DEB package
 3929    (courier.sysvinit file in the source code tarball).
 3931    NOTE: the following script may take a long time to finish, the very first
 3932    time it runs. That's because the script automatically creates test SSL
 3933    certificates the first time the script runs (provided that SSL support is
 3934    available). This can take as much as 5-6 minutes on a slow machine.
 3935    Subsequent starts should take only a few seconds.
 3937  #! /bin/sh
 3938  #
 3939  # chkconfig: 2345 35 65
 3940  # description: Courier - SMTP server
 3941  #
 3942  # NOTE: The 'restart' here does a "hard" stop, and a start.  Be gentle, use
 3943  # "courierd restart" for a kindler, gentler, restart.
 3944  #
 3945  #
 3947  prefix="/usr/lib/courier"
 3948  exec_prefix="/usr/lib/courier"
 3949  sysconfdir="/usr/lib/courier/etc"
 3950  sbindir="${exec_prefix}/sbin"
 3951  libexecdir="/usr/lib/courier/libexec"
 3952  datadir="/usr/lib/courier/share"
 3954  case "$1" in
 3955  start)
 3956          cd /
 3957          # Start daemons.
 3958          touch /var/lock/subsys/courier
 3960          echo -n "Starting the Courier mail server:"
 3962          # Use default DH parameter file, if it does not exist.
 3964          if test ! -f ${datadir}/dhparams.pem
 3965          then
 3966              ln ${datadir}/dhparams.pem.dist ${datadir}/dhparams.pem
 3967          fi
 3969          # First time after install create aliases.dat and makesmtpaccess.dat
 3971          test -f ${sysconfdir}/aliases.dat || ${sbindir}/makealiases
 3973          esmtpdcert=0
 3975          . ${sysconfdir}/esmtpd
 3976          case x$ESMTPDSTART in
 3977          x[yY]*)
 3978                  esmtpdcert=1
 3979                  ;;
 3980          esac
 3982          test -f ${ACCESSFILE}.dat || ${sbindir}/makesmtpaccess
 3984          . ${sysconfdir}/esmtpd-msa
 3985          case x$ESMTPDSTART in
 3986          x[yY]*)
 3987                  esmtpdcert=1
 3988                  ;;
 3989          esac
 3991          test -f ${ACCESSFILE}.dat || ${sbindir}/makesmtpaccess-msa
 3993          ${sbindir}/courierfilter start
 3994          echo -n " courierfilter"
 3996          if test -x ${sbindir}/courierldapaliasd
 3997          then
 3998                  ${sbindir}/courierldapaliasd start
 3999                  echo -n " courierldapaliasd"
 4000          fi
 4002          if test -f ${libexecdir}/courier/sqwebmaild
 4003          then
 4004                  ${sbindir}/webmaild start
 4005                  echo -n " webmail"
 4006          fi
 4008          ${sbindir}/courier start
 4009          echo -n " courierd"
 4011          if test "$esmtpdcert" = 1
 4012          then
 4013  # If we do not have a certificate, make one up.
 4015                  if test ! -f ${datadir}/esmtpd.pem
 4016                  then
 4017                          if test -x $COURIERTLS
 4018                          then
 4019                                  echo -n " generating-ESMTP-SSL-certificate..."
 4020                                  ${sbindir}/mkesmtpdcert >/dev/null 2>&1
 4021                          fi
 4022                  fi
 4023          fi
 4025          . ${sysconfdir}/esmtpd
 4026          case x$ESMTPDSTART in
 4027          x[yY]*)
 4029                  ${sbindir}/esmtpd start
 4030                  echo -n " esmtpd"
 4031                  ;;
 4032          esac
 4034          . ${sysconfdir}/esmtpd-msa
 4035          case x$ESMTPDSTART in
 4036          x[yY]*)
 4038                  ${sbindir}/esmtpd-msa start
 4039                  echo -n " esmtpd-msa"
 4040                  ;;
 4041          esac
 4043          if test -x ${sbindir}/pop3d
 4044          then
 4045                  POP3DSTART=""
 4046                  POP3DSSLSTART=""
 4048                  if test -f ${sysconfdir}/pop3d
 4049                  then
 4050                          . ${sysconfdir}/pop3d
 4051                  fi
 4052                  case x$POP3DSTART in
 4053                  x[yY]*)
 4054                          ${sbindir}/pop3d start
 4055                          echo -n " pop3d"
 4056                          ;;
 4057                  esac
 4058                  if test -f ${sysconfdir}/pop3d-ssl
 4059                  then
 4060                          . ${sysconfdir}/pop3d-ssl
 4061                  fi
 4062                  case x$POP3DSSLSTART in
 4063                  x[yY]*)
 4064                          if test -x $COURIERTLS
 4065                          then
 4066  # If we do not have a certificate, make one up.
 4068                                  if test ! -f ${datadir}/pop3d.pem
 4069                                  then
 4070                                          echo -n " generating-POP3-SSL-certificate..."
 4072                                          ${sbindir}/mkpop3dcert >/dev/null 2>&1
 4073                                  fi
 4075                                  ${sbindir}/pop3d-ssl start && \
 4076                                          echo -n " pop3d-ssl"
 4077                          fi
 4078                          ;;
 4079                  esac
 4080          fi
 4082          if test -x ${sbindir}/imapd
 4083          then
 4084                  . ${sysconfdir}/imapd
 4085                  case x$IMAPDSTART in
 4086                  x[yY]*)
 4087                          ${sbindir}/imapd start
 4088                          echo -n " imapd"
 4089                          ;;
 4090                  esac
 4091                  . ${sysconfdir}/imapd-ssl
 4092                  case x$IMAPDSSLSTART in
 4093                  x[yY]*)
 4094                          if test -x $COURIERTLS
 4095                          then
 4096  # If we do not have a certificate, make one up.
 4098                                  if test ! -f ${datadir}/imapd.pem
 4099                                  then
 4100                                          echo -n " generating-IMAP-SSL-certificate..."
 4102                                          ${sbindir}/mkimapdcert >/dev/null 2>&1
 4103                                  fi
 4105                                  ${sbindir}/imapd-ssl start && \
 4106                                          echo -n " imapd-ssl"
 4107                          fi
 4108                          ;;
 4109                  esac
 4110          fi
 4112          if test -x ${bindir}/webmlmd
 4113          then
 4114                  . ${sysconfdir}/webmlmrc
 4115                  if test "$LISTS" != ""
 4116                  then
 4117                          ${bindir}/webmlmd start ${sysconfdir}/webmlmrc && \
 4118                                  echo -n " webmlmd"
 4119                  fi
 4120          fi
 4122          echo ""
 4123          ;;
 4124  stop)
 4125          echo -n "Stopping the Courier mail server:"
 4127          if test -x ${bindir}/webmlmd
 4128          then
 4129                  ${bindir}/webmlmd stop ${sysconfdir}/webmlmrc
 4130                  echo -n " webmlmd"
 4131          fi
 4133          if test -x ${sbindir}/imapd
 4134          then
 4135                  ${sbindir}/imapd stop
 4136                  echo -n " imapd"
 4137          fi
 4139          if test -x ${sbindir}/imapd-ssl
 4140          then
 4141                  ${sbindir}/imapd-ssl stop
 4142                  echo -n " imapd-ssl"
 4143          fi
 4145          ${sbindir}/esmtpd-msa stop
 4146          echo -n " esmtpd-msa"
 4148          ${sbindir}/esmtpd stop
 4149          echo -n " esmtpd"
 4151          if test -x ${sbindir}/pop3d
 4152          then
 4153                  ${sbindir}/pop3d stop
 4154                  echo -n " pop3d"
 4155          fi
 4157          if test -x ${sbindir}/pop3d-ssl
 4158          then
 4159                  ${sbindir}/pop3d-ssl stop
 4160                  echo -n " pop3d-ssl"
 4161          fi
 4163          ${sbindir}/courier stop
 4164          echo -n " courierd"
 4166          if test -f ${libexecdir}/courier/sqwebmaild
 4167          then
 4168                  ${sbindir}/webmaild stop
 4169                  echo -n " webmail"
 4170          fi
 4172          if test -x ${sbindir}/courierldapaliasd
 4173          then
 4174                  ${sbindir}/courierldapaliasd stop
 4175                  echo -n " courierldapaliasd"
 4176          fi
 4178          ${sbindir}/courierfilter stop
 4179          echo " courierfilter"
 4180          ;;
 4181  restart)
 4182          $0 stop
 4183          $0 start
 4184          ;;
 4185  esac
 4186  exit 0
 4188    The reason I test for the existence of the POP3 and IMAP server binaries
 4189    is because I build the POP3 and IMAP servers as separate sub-packages,
 4190    that do not have to be installed. These tests avoid the need for each
 4191    sub-package to install its own startup script.