13.5 Picking Up Mail with IMAP and Web Mail
| Although POP is by far the most common way for users to collect their mail, many mail servers also offer IMAP and web mail. IMAP is conceptually similar to POP except that the client program has a full set of tools to manipulate the mailbox on the server. The advantage of IMAP over POP is that the mailbox remains on the server, so the user can use different mail programs from different locations, seeing consistent mailbox contents at all times. While qmail provides no IMAP server of its own, the IMAP server from the Courier mail package uses Maildirs as its mailbox format and works well with qmail. I describe its setup below. Web mail provides access to a mailbox using a web browser as the mail client. Many web mail packages are available on the Net that use POP or IMAP to access the user mailboxes. They're not specific to qmail, so I don't describe them here. The Courier package includes a web mail component called SqWebMail that uses Maildirs as its mailbox format. I describe its installation later in this chapter. Maildirs don't have to be locked while a client reads or updates them, so the POP and IMAP servers and SqWebMail can access the same mailbox simultaneously without trouble. Systems based on mboxes can't do that. I routinely have my mailbox open in pine on a BSD system, Pegasus and Opera 7 on a Windows laptop, and SqWebMail on a web browser, all at the same time without any trouble. You can download the sources for Courier IMAP and SqWebMail by following the links from http://www.courier-mta.org/download.php. As of the time this book was written, the current version of Courier IMAP is 1.7.0 and of SqWebMail is 3.5.0. Courier IMAP and SqWebMail share the same user validation scheme, an "auth" framework that calls out to a variety of authorization modules to handle everything from passwd files to vpopmail to MySQL (different from the vpopmail flavor) to LDAP. Once you have it set up for one, it's easy to transfer to the other. Courier IMAP includes a POP server that provides no more function than the qmail one but uses the Courier authentication scheme, letting your POP and IMAP login rules be consistent.
13.5.1 Courier's Extended Maildir++All of the pieces of the Courier package support an upwardly compatible extended version of Maildirs known as Maildir++. The extensions allow subfolders within a Maildir and provide a convention for folders that can be shared among multiple users (a feature used by the IMAP server). A subfolder is merely a Maildir that exists within another Maildir. For example, a subfolder called spam would be Maildir/.spam and spam.mmf would be Maildir/.spam.mmf. Even though folders can be logically nested, all subfolder directories are directly located in the main Maildir. Each subfolder has the usual tmp, cur, and new directories, as well as a zero-length file named maildirfolder that tells programs that it's a subfolder and to look in the parent directory for quota files and the like. From qmail's point of view, a subfolder is just a Maildir, and qmail can deliver messages to them the same as to any other Maildir. This comes in handy for delivery-time mail sorting. If, say, you want mail tagged by your spam filter to go into a separate subfolder, your .qmail or .procmailrc can deliver the spam to Maildir/.spam/, and the rest of the mail to Maildir/. A shared Maildir is one that's world-readable. By convention, the file shared-maildirs in a regular Maildir contains a list of shared Maildirs, each on a line in the form: nickname tab path-to-shared-Maildir Courier IMAP and SqWebMail create symlinks as needed to make the messages in folders in the shared Maildirs look like they're in folders in the user's own Maildir. The Courier programs create a lot of other files in the Maildirs, such as the signature and address book for SqWebMail. Qmail ignores everything but the three defined directories, so the extra files cause no compatibility trouble. 13.5.2 Installing Courier IMAPOnce you've downloaded the Courier IMAP source, unpack it into a directory (see Unpacking bz2 Files). The configuration for Courier IMAP is intended to be almost entirely automatic, detecting whether you have packages such as OpenSSL, MySQL, and vpopmail installed and, if so, compiling optional subpackages for them. When the automated scheme works, it's great. When it doesn't quite work, it's a pain in the neck. Read the INSTALL file carefully before building and installing the package, because the installation instructions may have changed from the ones here. First configure it by running configure. The configuration process runs recursively in a long set of subdirectories, so it can take several minutes. Then build it with make. (The instructions say to use GNU gmake on BSD systems, but I've found that the configuration files are built for the BSD make.) Assuming that works, become super-user and type make install to install the files, and then type make install-configure to configure the installed files. This installs the package into /usr/lib/courier-imap.
Once it's installed, you have some more setup to do before you start up the servers. There are separate servers for POP and IMAP. If you have OpenSSL installed, there are two more servers for POP-SSL and IMAP-SSL. To add to the confusion, some clients connect to the regular server on the regular POP or IMAP port, and then use a "starttls" command to switch to secure mode, while other clients connect to different ports (993 for IMAP, 995 for POP) and start the secure mode negotiation immediately. Courier IMAP supports both modes, but you have to start them separately. If you're using SSL, this is a good time to generate your SSL certificates. The certs that Courier generates are self-signed, which makes most MUAs pop up warning messages, but they're adequate for debugging. To get rid of the warnings, you must get your certificates signed by one of the signing services that signs web server certs, at about $100 per signature. The files etc/imapd.cnf and etc/pop3d.cnf contain the info needed to create the certificates. You must change the CN line from the default localhost to the name of your mail server or some MUAs, including Eudora, won't talk to you at all. While you're at it, you might as well update the C (Country), ST (State), L (Locality), O (Organization), and emailAddress lines so that when users check the certificate, which they will when their MUAs complain about it, the values look reasonable: [ req_dn ] C=US ST=NY L=Trumansburg O=The Example Organization OU=Automatically-generated IMAP SSL key CN=mail.example.com emailAddress=postmaster@example.com Once you've fixed up the certificate data, run share/mkimapdcert and share/mkpop3dcert to create the SSL certificates. Now check the server configuration files etc/imapd, etc/imapd-ssl, etc/pop3d, and etc/pop3d-ssl (each is a shell script that sets variables imported into the startup scripts), and make any needed adjustments. The most likely variables to use are ADDRESS and SSLADDRESS if you want your servers to run on a specific IP address, and use MAXDAEMONS to limit the number of simultaneous sessions. Also check authdaemonrc, which controls the authorization daemon that validates logins, in particular the authmodulelist line, which lists all of the authorization modules it'll use. You'll often want to remove some of them. See man/man7/authlib.7, which describes all the modules. Now you're ready to start up the daemons: # cd /usr/lib/courier-imap/libexec # ./imapd.rc start # start imap on 143 # ./pop3d.rc start # start pop3 on 110 # ./imapd-ssl.rc start # start ssl imap on 993 # ./pop3d-ssl.rc start # start ssl pop3 on 995 Check that you can log into your new server. To test the POP server, telnet into it as described earlier in this chapter in the discussion of the qmail POP server. IMAP is an extremely complex protocol, but fortunately the commands to log in and check a mailbox are pretty simple. In this example, you literally type c1, c2, and c3, which are transaction identifiers used to match up responses with requests: $ telnet yourserver imap Trying 10.31.42.80... Connected to yourserver. Escape character is '^]'. * OK Courier-IMAP ready. Copyright 1998-2003 Double Precision, Inc. See COPYING for distribution information. c1 login yourname yourpassword c1 OK LOGIN Ok. c2 select INBOX * FLAGS (\Draft \Answered \Flagged \Deleted \Seen \Recent) * OK [PERMANENTFLAGS (\Draft \Answered \Flagged \Deleted \Seen)] Limited * 31 EXISTS * 0 RECENT * OK [UIDVALIDITY 1043726086] Ok c2 OK [READ-WRITE] Ok c3 logout * BYE Courier-IMAP server shutting down c3 OK LOGOUT completed To check that SSL is working, log into the various servers from MUAs and check that it works. If your MUA supports SSL, it will complain about the self-signed certificates before it lets you log in. Assuming you're happy with the results, add the previous startup lines to one of the /etc/rc files on BSD systems. On System V and Linux systems, see the courier-imap.sysvinit script created in the build directory but not installed. Again, read the lengthy INSTALL for the most up to date installation instructions. 13.5.3 Courier IMAP and Pop-Before-SMTPAlthough Courier IMAP supports about 15,000 different features, a general purpose POP-before-SMTP is not one of them unless you're using vpopmail. If you are, build Courier IMAP without authdaemon, and add -DHAVE_OPEN_SMTP_RELAY to the DEFS line in the authlib Makefile to have it include the relay code. The vpopmail FAQ at http://www.inter7.com/vpopmail/FAQ.txt has more details at question 34. For other authorization schemes, this oversight is easily remedied. Each of the .rc files, when it starts a server, runs couriertcpd, a TCP daemon similar to tcpserver. Like tcpserver, it takes as its arguments a cascade of programs to run whenever an incoming connection arrives. Also like tcpserver, salient facts about the connection are placed in the environment, including TCPREMOTEIP for the remote host. In imapd.rc, for example, this rather complex command starts the server: /usr/bin/env - /bin/bash -c " set -a ; prefix=/usr/lib/courier-imap ; exec_prefix=/usr/lib/courier-imap ; bindir=${exec_prefix}/bin ; libexecdir=/usr/lib/courier-imap/libexec ; . ${prefix}/etc/pop3d ; \ . ${prefix}/etc/pop3d-ssl ; \ TLS_PROTOCOL=$TLS_STARTTLS_PROTOCOL ; \ export TLS_PROTOCOL ; /usr/lib/courier-imap/libexec/couriertcpd -address=$ADDRESS \ -stderrlogger=/usr/lib/courier-imap/libexec/courierlogger \ -stderrloggername=imapd \ -maxprocs=$MAXDAEMONS -maxperip=$MAXPERIP \ -pid=$PIDFILE $TCPDOPTS \ $PORT ${exec_prefix}/sbin/imaplogin $LIBAUTHMODULES \ ${exec_prefix}/bin/imapd Maildir" This sets variables, reads two configuration scripts from etc, and runs couriertcpd. When a connection arrives, it runs imaplogin, which after validating the login, runs imapd. If you're using relay-ctrl, the instructions for integrating it with Courier IMAP are in the ANNOUNCEMENT file. First you make a symlink in /usr/lib/courier-imap/libexec/authlib to /usr/sbin/relay-ctrl-allow. Then add relay-ctrl-allow to the end of the list of AUTHMODULES in the file /usr/lib/courier-imap/etc/imapd, which tells IMAP to run that program every time someone logs in. Finally, insert this line in front of the couriertcpd line in the startup script: envdir /etc/relay-ctrl relay-ctrl-chdir \ and restart Courier IMAP. You must modify all four .rc scripts to do POP-before-SMTP, but you can add the same line to each of them to use the same openrelay script.
13.5.4 Installing SqWebMailOnce you have Courier-IMAP installed, SqWebMail is a snap to install. Unpack the bzipped file, configure, and install. SqWebMail runs from your web server, so the main program is installed in a cgi-bin directory and run on demand from the web server. If you're planning to run it from a virtual domain, create the web server directories for the domain's home page and cgi-bin if you haven't already done so. The installation process creates a directory of icon files that must be the webmail subdirectory of the domain and a directory tree of auxiliary files that shouldn't be visible via the web server at all, usually in /usr/local/share/sqwebmail. If you're not using Courier-IMAP, and you're using the authorization daemon, you must add a line to your system startup scripts to start the daemon. If you are using Courier-IMAP, use the same daemon it uses. The configuration script has an enormous set of options, but the ones you most likely need are the ones to set the location of the cgi-bin and image directories. If you've installed Courier-IMAP with authdaemon, you also must tell SqWebMail to use the same authdaemon directory: ./configure \ --enable-cgibindir=/var/www/cgi-sqweb \ --enable-imagedir=/var/www/sqwebmail/webmail \ --with-authdaemonvar=/usr/lib/courier-imap/var/authdaemon \ --disable-autorenamesent The last option to the configure command turns off a feature that automatically creates monthly subfolders of sent mail, which I don't find useful. Once the lengthy configuration process completes, build and install the program following the INSTALL instructions: $ make configure-check $ make $ make check $ su # installation must be superuser # make install # or make install-strip to strip symbols # make install-configure Start authdaemon if needed, following the hints displayed by the install program, and then try sqwebmail with a URL like http://mail.myvirt.com/cgi-bin/sqwebmail. The installation program lists many further possible customizations. One you should install is /usr/local/share/sqwebmail/sendit.sh, the script that actually sends outgoing mail from SqWebMail. The version I use is this, to send mail using qmail-inject: # $1 is the return address, $2 is the logged in sqwebmail user { echo "Received: from [$REMOTE_ADDR] ($2); via SqWebMail 3.5.0" cat } | /var/qmail/bin/qmail-inject -f "$1" |
