Installation instructions for tpop3d $Id: INSTALL,v 1.22 2003/01/09 23:25:59 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. (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 --sysconfidr=/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 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.