An Overview of qmail Dave Sill, de5@ornl.gov December 1996 INTRODUCTION qmail is a mail transfer agent (MTA). Although it performs the same job(s) as sendmail, and speaks the same network protocol (SMTP), it differs fundamentally in the way it works. Sendmail has been *the* UNIX MTA from the beginning, and it takes a little time to unlearn the sendmail way and learn the qmail way. This document highlights some of the biggest differences between qmail and sendmail and provides a high-level overview of qmail, but qmail is well-documented and this document doesn't attempt to cover all of the details. ARCHITECTURE Sendmail consists of one large, complicated, setuid root program that listens to the SMTP port, delivers local and remote mail, accepts messages locally for delivery, rebuilds the alias database, prints the status of the queue, etc. The only part of the MTA process that sendmail doesn't do itself is local delivery--that's usually passed off to /bin/mail, procmail, or some other delivery agent. qmail consists of a suite of daemons and programs, each running under a different UID and performing a specific task. Only one of those parts is setuid (but not setuid root), and only one runs as root (the part that does local delivery needs to be root so it can setuid to the user's UID). USER-VISIBLE CHANGES qmail, by default, delivers mail to $HOME/Mailbox, rather than /usr/spool/username. Setting the $MAIL environment variable appropriately will tell most Mail User Agent's (MUA's) where to look for new mail. Some, such as PINE, require changing a configuration variable. If disk quotas are used, this will result in mailboxes being charged against the user's quota. qmail doesn't use .forward files, it uses .qmail* files. Some very simple .forward files can be renamed to .qmail, others will require some reformatting. qmail assumes that messages to addresses whose host names contain at least one dot are fully-qualified: it doesn't try paring down the domain or using the DNS search path to find a valid host if the one user supplied is invalid. For example, on sws5.ctd.ornl.gov, if one sends a message to "de5@sws1", qmail will assume that to mean "de5@sws1.ctd.ornl.gov". But if one sends a message to "de5@arm3.esd", qmail will assume that to mean just that: "de5@arm3.esd". The desired behavior, sending to "de5@arm3.esd.ornl.gov" can be achieved by using "de5@arm3.esd+", or by specifying the fully-qualified domain name. SMTP SERVICE Sendmail is normally run with the "-d" flag to cause it to run as a daemon listening to port 25. qmail supplies qmail-smtpd which is usually invoked by inetd. This is practical because qmail-smtpd is very small compared to sendmail and it can be invoked quickly. This allows one to use tcp_wrappers to control who can connect to the SMTP port. INJECTING MAIL Messages are usually originated on sendmail systems by /bin/mail, which invokes /usr/lib/sendmail. qmail supplies a /usr/lib/sendmail replacement which accepts most of the necessary sendmail options. LOCAL DELIVERY Once sendmail has determined that a message is to be delivered to a local user, it checks the user's home directory for the existence of a .forward file. If it finds one, it reads it to determine how to deliver the message. If it doesn't find one, it passes the message to the Mlocal mailer (usually /bin/mail), which appends the message to the user's mail file in the mail spool directory (/usr/spool/mail, /var/mail, etc.). Lines in .forward files can redirect delivery to other users (local or remote), files, or programs. Once qmail has determined that a message is to be delivered to a local user, it checks the user's home directory for the existence of one or more .qmail files. If it finds one, it reads it to determine how to deliver the message. If it doesn't find one, it appends the message to the user's mail file in ~user/Mailbox. Lines in .qmail files can redirect delivery to other users (local or remote), mailbox files, maildir directories, or programs. Note: qmail only delivers to users whose UID's are not 0 and whose home directory exists and is owned by them. If you want to receive mail sent to root, you'll need to set up an alias. Also, qmail converts usernames to lowercase, so it can't deliver to users with uppercase letters in their usernames. REMOTE DELIVERY Sendmail delivers messages serially, i.e., a message sent to multiple recipients is sorted by mail exchange (MX), and a copy is sent to each MX, one after the other, with multiple recipients, if necessary. qmail delivers in parallel: all deliveries are queued immediately, and up to concurrencyremote (default 20) qmail-remote processes start delivering one copy of the message to each recipient. If multiple recipients are on the same MX, qmail will *not* bundle them into a single multiple-recipient delivery. ALIASES Sendmail uses an alias table (/etc/aliases) to construct an alias database in dbm or Berkeley db format. When the table is modified, the database must be rebuilt to reflect the changes. While the database is being rebuilt, processing of incoming mail is suspended. The alias database overrides users, so if there's a user named "foo" and an alias named "foo", sendmail delivers to the foo alias. qmail implements aliases via .qmail files in the user alias's home directory. Changes are effective immediately and there's no interruption of the flow of incoming mail. Users take precedence over aliases, so mail will go to user "foo", not the "foo" alias. The qmail-users feature can be used to create a table/database similar to sendmail's for mapping incoming addresses to local users. A separate package, qmsmac, supports a more complete clone of sendmail aliases. EXTENDED ADDRESSING With qmail, users can receive mail sent to addresses of the form username-extension. Delivery to extended addresses is controlled by ~username/.qmail-extension or ~username/.qmail-default. For example, if user foo wants to be able to receive mail sent to foo-bar@foo.ornl.gov, he can create .qmail-bar in his home directory to control where messages sent to that address are delivered--or he can create .qmail-default which will control where messages sent to foo-whatever are delivered, provided there's not a .qmail-whatever file. Extended addresses are handy for directing mailing list mail into separate folders, implementing user-controlled mailing lists, and managing virtual domains. MAILING LISTS Mailing lists are implemented in sendmail via aliases: either hard-coded in the alias table, or indirectly through :include: files. Lists are either managed manually or through an add-on application like Majordomo or Smartlist. The alias table has to be modified to create or remove lists, so only the system administrator perform these functions. Mailing lists can be implemented in qmail the way they are in sendmail: via system-wide aliases in ~alias/.qmail files, the qmsmac database, or the qmail-users feature, but they can also be implemented via user-defined extended addresses. qmail even includes a simple list manager to handle subscribes/unsubscribes. CONFIGURATION Sendmail is configured primarily through the sendmail.cf file. Sendmail must be restarted for configuration changes to take effect. qmail is configured primarily through files in the /var/qmail/control directory. Some changes take effect immediately, others require HUP'ing the qmail-send process. INSTALLATION Sendmail installation requires installation of the sendmail binary and various links to it, the sendmail.cf file, the alias table, and the mqueue directory, though the last two are usually already there. qmail installation requires installation of the qmail binaries, the control directory, the ~alias directory and .qmail files, the queue tree, two new groups, and various (currently seven) new user ID's. All of the files and directories must be accessible under /var/qmail (configurable at compile-time), but can be symlinked to/from various places under /usr/local and /var/local. Note that if you install the qmail binaries under /usr/local/sbin, qmail's "forward" will overwrite our own "forward". POP SERVICE There are two options for POP service with qmail. First is qmail-pop3d, which is included with the distribution. It has the advantage of using qmail's robust maildir format for storing messages. That also turns out to be a disadvantage, though, because there aren't any MUA's that natively support this format. Therefore, qmail-pop3d is best for mail servers that don't have people logging in and reading mail directly with local MUA's. The second option is to modify one of the available pop daemons such as Quallcomm's qpopper to use $HOME/Mailbox instead of the central spool mailbox. This is a trivial change (add a flag to tell it to look in the home directory, change the name of the file it's looking for). If you need this, let me know and I'll dig up the details. MORE INFORMATION Man pages and other documentation are included with the distribution, available from ftp://ws.ctd.ornl.gov/unix/mail/qmail. The official web site, which includes HTMLified man pages, is http://pobox.com/~djb/qmail.html. An unofficial web site is http://www.qmail.org. You can join the qmail mailing list by sending an empty message to djb-qmail-request@koobera.math.uic.edu.