From djb-qmail-owner-tmaeno-qmail=hpcl.titech.ac.jp@koobera.math.uic.edu Mon Dec 09 20:25:52 1996
Return-Path: <djb-qmail-owner-tmaeno-qmail=hpcl.titech.ac.jp@koobera.math.uic.edu>
Delivered-To: tmaeno-qmail@hpcl.titech.ac.jp
Received: (qmail 10226 invoked from network); 9 Dec 1996 20:25:49 -0000
Received: from koobera.math.uic.edu (qmailr@128.248.178.247)
  by tehanu.hpcl.titech.ac.jp with SMTP; 9 Dec 1996 20:25:49 -0000
Received: (qmail 21529 invoked by uid 666); 9 Dec 1996 20:30:36 -0000
Delivered-To: djb-qmail@koobera.math.uic.edu
Received: (qmail 21526 invoked from network); 9 Dec 1996 20:30:36 -0000
Received: from sws5.ctd.ornl.gov (73@128.219.128.125)
  by koobera.math.uic.edu with SMTP; 9 Dec 1996 20:30:35 -0000
Received: (qmail 28760 invoked by uid 3995); 9 Dec 1996 20:24:45 -0000
Date: 9 Dec 1996 20:24:45 -0000
Message-ID: <19961209202445.28759.qmail@sws5.ctd.ornl.gov>
From: Dave Sill <de5@sws5.ctd.ornl.gov>
To: djb-qmail@koobera.math.uic.edu
Subject: qmail overview
X-Mailer: VM Version 5.96 (beta) with XEmacs 19.14 [Lucid] (mips-sgi-irix6.2) of Wed Jun 26 1996 on pomerol
Organization: Oak Ridge National Lab, Oak Ridge, Tenn., USA
X-Face: "p~Q]mg{;e*}YR|)&Q/&Q\*~5UWfZX34;5M<gHyq0KvGt<$qi6=B7;$3~1p?Jc7-g?1vPVAc%YX$E6]%1jvk:,"f*jA|?~Cxb?WJ5gt}L?qsMAjROM~rHbK27yx=t,L/?IHb8@|cYg8"Y)~0IpU~J.^w,VW)u?M3q-AS{f`@RZ]Wll
X-Disclaimer: My opinions do not necessarily represent those of my employer
Status: OR

Here's an overview of qmail I've written for local sysadmins. There
are a couple things peculiar to our local setup, but most of it is
pretty general.

Send comments directly to me, please.

-Dave

----

                         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.