Installation instructions for tpop3d
$Id$

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. (In addition to those noted here, tpop3d supports
standard configure options such as --prefix.) If you are using Mac OS X, please
also review the contents of README.darwin.

NB that tpop3d now obeys the --sysconfdir of configure, so you will need to
set --sysconfdir=/etc if you already have a /etc/tpop3d.conf and do not wish to
move it.

* Authentication

  A number of authentication mechanisms are available:

    auth-pam
    --enable-auth-pam, --enable-pam-leak-hack
      Uses Pluggable Authentication Modules, with a configurable facility name
      (by default, `tpop3d'). On many systems, the PAM implementation leaks
      memory, which can cause the tpop3d daemon process to grow without limit
      over time. Compiling with --enable-pam-leak-hack causes tpop3d to fork
      a child process to do each PAM authentication, which eliminates the leak
      at a slight performance cost.

    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-lib-dir, --with-mysql-include-dir
      Uses a MySQL database, allowing authentication of users in virtual
      domains.

      auth-mysql now supports password hashes in a variety of formats in
      addition to the straight MD5 hashes used in `classic' vmail-sql. These
      are still the default, but other formats are detected by the presence of
      a prefixed token enclosed in { } at the beginning of the password hash
      field in the database. Presently, the code recognises:
    
          {crypt}...        system crypt(3)
          {crypt_md5}...    crypt_md5 as used in Linux-PAM
          {plaintext}...    plain text password used for APOP
          {mysql}...        password hashed using MySQL's PASSWORD()
          {md5}...          straight MD5 hash
          {sha1}...         straight SHA1 hash

      Note that to use APOP, the plaintext password type must be specified for
      a user, but this does not stop them logging in via any other method with
      the same password.

    auth-ldap
    --enable-auth-ldap, --with-openldap-root
      Uses an LDAP directory, allowing authentication of users in virtual
      domains. auth-ldap uses the OpenLDAP client library, version 2, which
      must be installed on your system in order to compile tpop3d with
      auth-ldap support.

    auth-flatfile
    --enable-auth-flatfile
      Uses /etc/passwd-style flat files, one per domain.

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

    auth-perl
    --enable-auth-perl
      Authenticates users via perl subroutines run in an embedded perl
      interpreter. Note that enabling this may increase the size of the tpop3d
      binary alarmingly.

  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. Maildir support
  was contributed by Paul Makepeace. 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.


* TLS (`SSL')

  tpop3d now supports encrypted TLS connections. To enable this, use
  
    --enable-tls

  and possibly --with-openssl-root if configure can't find your OpenSSL
  installation.


* 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.


* BSD mailspool metadata cache

  If you use BSD mailspools, you can opt to have tpop3d cache metadata
  (basically, the offsets of messages within the mailspool) in a file; this
  makes opening the mailspool much faster, especially if it contains numerous
  messages. To enable this feature -- which is experimental -- use

    --enable-mbox-bsd-save-indices

  See tpop3d.conf(5) for information on how to configure this feature.


* 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).


* TCP Wrappers support

  Since tpop3d runs as a daemon, TCP Wrappers cannot be used via the normal
  inetd.conf/tcpd style of operation. You can use `--enable-tcp-wrappers' to
  incorporate native support for TCP Wrappers in tpop3d. If you do this, the
  `daemon name' (the thing which comes before the : in /etc/hosts.allow and
  .deny) may be set using the configuration file option tcp-wrappers-name; this
  is for a similar reason to allowing the PAM service name to be configured.


* DRAC support

  tpop3d can be configured to notify a DRAC server of successful logins,
  by using the `--enable-drac' configure option. This requires the -ldrac
  library.


* 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.


* A note on migrating from an existing POP3 server

  Many POP3 client programs use the UIDL (unique-ID list) facility of the POP3
  protocol to distinguish already-downloaded messages from those left on the
  server. It is very unlikely that your existing POP3 server uses the same
  scheme for unique IDs as does tpop3d. In consequence, when you migrate from
  an existing server to tpop3d, it is likely that users who leave messages on
  the server (rather than deleting them as soon as they download them) will
  retrieve new copies of old messages. Regrettably, this is unavoidable (and is
  not in any way unique to tpop3d).

  For reference (and in lieu of reading mailspool.c and maildir.c for the gory
  details), for BSD mailspools, the unique ID is generated from an MD5 message
  digest of the first part of the message; for maildir, the MD5 hash of the
  filename of the message is used.

  tpop3d does not use the Message-ID field in the message header, for a number
  of reasons.


* Compiler warnings

  If you use GCC to compile tpop3d, you may get some warnings of the form

    warning: missing braces around initializer for `...'

  Ignore these. They are cause by a bug or overzealousness in GCC. Full rant
  available on request.

