Installation instructions for tpop3d
$Id: INSTALL,v 1.5 2001/04/23 23:58:15 chris Exp $

Thanks to the efforts of Mark Longair, tpop3d can now be configured and built
using the standard GNU autoconf approach. For most users, it should be
possible to build tpop3d by typing

    ./configure
    make

and to install it using

    make install

However, it is well worth reviewing the various options to configure before
proceeding blindly along this route. Below are various notes about configuring
tpop3d for your system.


* Authentication

  A number of authentication mechanisms are available:

    auth_pam
    --enable-auth-pam
      Uses Pluggable Authentication Modules, with a configurable facility name
      (by default, `tpop3d').

    auth_passwd
    --enable-auth-passwd, --enable-shadow-passwords
      Uses /etc/passwd (and, by a compile time option, /etc/shadow) to
      authenticate local users.

    auth_mysql
    --enable-auth-mysql, --with-mysql-root
      Uses a MySQL database, allowing authentication of users in virtual
      domains.

      By default, auth_mysql uses MD5 hashes of passwords for authentication
      (or clear-text passwords for APOP authentication). By applying the
      patches in mysql_crypt.patch, you can alter this to use passwords which
      are hashed using crypt(3) (as in /etc/passwd on most Unix systems); if
      you apply this patch, you will have to modify the SQL schema for the
      database, creating a crypt_pw column to store the password hashes
      (rather than password_hash). This patch was contributed by Dom
      Gallagher.

    auth_other
    --enable-auth-other
      Passes authentication requests to an external program; designed to allow
      custom virtual domains authentication schemes.

  For tpop3d to be useful, you must enable at least one authentication driver.
  By default, only PAM is switched on; this is correct for most modern Unix
  systems. Older systems should use auth_passwd.


* Mailbox formats

  tpop3d supports traditional BSD-format mailboxes (with messages separated by
  lines beginning `From '), and the maildir format of Qmail. You can select
  these using:

    --enable-mbox-bsd
    --enable-mbox-maildir

  The locations of user mailboxes may be specified in the configuration file;
  if no such specification is given, then `MAILSPOOL_DIR/username' is used.
  You can set the value of MAILSPOOL_DIR with the --with-mailspool-directory
  configure option; however, this is deprecated in favour of the more flexible
  run-time approach. To use this, simply add

    mailbox: /var/spool/mail/$(user)

  to your configuration file. Other possibilities:

    mailbox: maildir:$(home)/Maildir              default maildir location

    mailbox: /var/spool/mail/$(user[0])/$(user)   hashed mailspool directories
    
    mailbox: maildir:$(home)/Maildir bsd:/var/spool/mail/$(user)
                                                  maildir if available, else
                                                  traditional mailspool

  You can also set these options on a per-authenticator basis, with the
  configuration option auth-foo-mailbox.


* Locking of BSD (`Unix') mailspools

  tpop3d supports a number of ways to lock mailspools as compile-time options.
  (Note that this applies to single-file `BSD' or `Unix' mailspools; maildir
  mailboxes do not use file locking at all, instead relying on the atomicity
  of certain filesystem operations. Praise the lord and pass the Single Unix
  Specification, version 2.)

  Unfortunately, Unix mailspool locking is arcane and complex (a less
  charitable author would say "broken"). You may have to experiment to get
  this right.

  Your choices are:

  fcntl(2) locking-- a system locking mechanism supported on all modern
    systems and which works over NFS.

  flock(2) locking-- an older (BSD) locking mechanism which does not work over
    NFS.

  dotfile locking-- an ancient mechanism which uses files ending ".lock" for
    locking; works (kind of) over NFS.

  Switching on several of these means that tpop3d will try to obtain _all_ of
  the locks you specify before accessing a mailspool. If it cannot obtain any
  one of them, it will give up.

  In addition, tpop3d can steal locks from PINE and other cooperating
  programs which are based on the C-Client library from Washington University.
  Internally, the C-Client library may use (normally) flock(2) or (on some
  systems) fcntl(2). tpop3d does not establish C-Client locks itself. If this
  is confusing, read the C-Client source; however, I do not guarantee that
  this will enlighten you.

  It is, unfortunately, not safe simply to turn everything on and hope for the
  best. Some systems, such as modern BSDs, implement flock and fcntl using
  common internals, and on such systems, tpop3d would deadlock while trying to
  obtain both sorts of lock. Some systems, such as Solaris, do not support
  flock(2). Some systems, such as modern Linux distributions, do not use
  dotfile locking at all (and have altered permissions on /var/spool/mail to
  accomodate this). The configure script should detect and handle fcntl/flock
  issues correctly.

  When configuring tpop3d, you should therefore take note of these arguments:

    --enable-flock-locking
    --enable-fcntl-locking
    --enable-dotfile-locking
    --enable-cclient-locking

  which correspond to the options described above. (I reiterate that tpop3d
  does not establish C-Client locks; but `--enable-stealing-cclient-locks' is
  ridiculous even by the standards of GNU long options.)

  On most systems, the C-Client library uses flock(2) locking to lock its own
  lockfiles (really!) but on others where flock(2) is not supported, or where
  the system policy is different (such as new RedHat Linux distributions),
  C-Client will use fcntl(2) locking internally, and you should use the
  configure option --enable-cclient-uses-fcntl to switch on this behaviour.
  If you do not know whether this is the case or not, you can either get hold
  of the source of the version of PINE on your system (perhaps using your
  vendor's package management tools) and see if an appropriate patch has been
  applied, or use a debugging tool such as strace(1) or truss(1). For
  instance, using strace:

    strace -eopen,fcntl,flock `which pine` 2> /tmp/pine-lock-log

  If PINE creates lock files in /tmp and locks them with fcntl, then you
  should switch on --enable-cclient-uses-fcntl. On most systems you will find
  that PINE uses flock for this purpose. In the worst case, it is unlikely
  that disaster will strike if you get this wrong.


* Interaction with PINE and the Washington University IMAP server

  Independent of C-Client-style locking, you can opt for tpop3d not to allow
  users to download or remove the metadata messages which C-Client saves in
  mailspools (these are the ones with subject "DON'T DELETE THIS MESSAGE --
  FOLDER INTERNAL DATA" and an X-IMAP header used to save state associated
  with IMAP UIDs). This is harmless if your users do not use PINE, and
  probably desirable if they do.


* Wording of server responses

  Some people may find that users whose POP3 clients report errors from the
  server verbatim complain at the wording of some server responses. If you are
  in this position, you can use `--disable-snide-comments' (not recommended;
  in my view, this is a technical solution to a social problem, and anyway
  users should get used to their computers being rude to them).


* Development and debugging

  If you are modifying or extending tpop3d, or if you have trouble with the
  server and want to help in debugging it, then you can cause tpop3d to be
  linked with the Electric Fence malloc(3) debugging library using
  --enable-electric-fence, and (on glibc systems only) turn on backtrace
  reporting in the event of a server crash using --enable-backtrace. You may
  also wish to read the file HACKING in the distribution.


* init.d script

  A sample System V init.d script is in the init.d/ subdirectory. This script
  is usable on Linux and easily modifiable for other systems. If you use
  auth_mysql and find that your system comes up sufficiently quickly that
  tpop3d fails to connect to MySQL on startup, you may want to apply the patch
  in init.d/initscript_wait-for-mysqld.patch to the script; this tests for the
  existence of the unix socket which MySQL clients use to communicate with
  MySQL. This patch was contributed by Roberto Braga.


* External authentication programs

  There are sample external authentication programs in scripts/; the perl
  module used by some of them is in TPOP3D-AuthDriver/ and can be installed by
  the standard perl Makefile.PL; make; make install procedure.

