Okay, qmail is compiled and installed on your system. Now go back to the build directory to set up an initial configuration:

# cd /usr/local/djb/build/qmail-1.03
# ./config-fast mailhub.example.org

Substitute the fully qualified domain name of your own host for the argument mailhub.example.org.

The config-fast utility will then populate the /var/qmail/control directory with initial settings for your server.

There are now three steps to continue configuration:

• additional settings in /var/qmail/control
• basic aliases in /var/qmail/alias
• user mailboxes

Each of these is discussed in the sub-sections that follow.

qmail does not have a single configuration file. Rather, the files in /var/qmail/control are used collectively to set the parameters for a qmail installation. One of the main tasks of a qmail administrator is to learn the purpose of the configuration files in /var/qmail/control and set them appropriately.

First, have a look at the current settings of the control files with the qmail-showctl utility:

# cd /var/qmail
# bin/qmail-showctl | less

This listing shows not only the control files that are set explicitly, but the default values qmail is using for any control files that may be absent. (The qmail-showctl utility is a good way to see what qmail is thinking about your configuration.)

At this stage we are interested in only a few of the control files:

• control/locals
• control/rcpthosts
• control/queuelifetime
• control/databytes

One of the first decisions qmail has to make is whether an email should be delivered to a user's mailbox on this server, or queued for remote delivery to another server. The entries in control/locals tell qmail what deliveries should be attempted locally.

For example, if an email message is addressed to:

qmail will look in control/locals for any entries matching thishost exactly. If so, qmail will assume someuser has a mailbox on this server.

The example config-fast configuration above will have resulted in just one entry in control/locals:

# cat control/locals
mailhub.example.org

This means that qmail will accept emails to

for local delivery. But emails addressed to

will be queued for remote delivery, because example.org is not listed in control/locals.

I'm guessing this isn't what you want.

So what to do is add entries to control/locals, one per line, for each thishost that qmail should consider local. For example:

# echo "localhost" >> control/locals
# echo "example.org" >> control/locals

Now check what qmail is thinking:

# bin/qmail-showctl | less

You should see a section that reads:

locals:
Messages for mailhub.example.org are delivered locally.
Messages for localhost are delivered locally.
Messages for example.org are delivered locally.

qmail doesn't accept email addressed to just anyone. When another email server (or email program) connects with qmail via smtp, qmail checks control/rcpthosts to see if it should agree to accept the message.

For example, if qmail gets a RCPT TO: for

qmail will look in control/rcpthosts for any entries matching thishost exactly. If so, qmail will accept the message.

As with control/locals, the config-fast procedure will have resulted in just one entry in control/rcpthosts:

# cat control/rcpthosts
mailhub.example.org

This means that qmail will accept messages addressed to:

But emails addressed to:

will be refused.

I'm guessing this isn't what you want.

So what to do is add entries to control/rcpthosts, one per line, for each thishost that qmail should receive mail for. For example:

# echo "localhost" >> control/rcpthosts
# echo "example.org" >> control/rcpthosts

Now check what qmail is thinking:

# bin/qmail-showctl | less

You should see a section that reads:

rcpthosts:
SMTP clients may send messages to recipients at mailhub.example.org.
SMTP clients may send messages to recipients at localhost.
SMTP clients may send messages to recipients at example.org.

Note that control/locals and control/rcpthosts may appear similar, but they actually serve completely different purposes. Until you get involved with virtual hosts, though, the entries in each of these control files will probably be the same.

When qmail queues a message for delivery, it will try mightily to deliver it --though not indefinitely. After messages have been in the queue for more than control/queuelifetime seconds, qmail will give up and bounce the message back to the sender as undeliverable.

The default queuelifetime is one week:

# bin/qmail-showctl | grep queuelifetime
queuelifetime: (Default.) Message lifetime in the queue is 604800 seconds.

I'm guessing this is longer than your users would like.

To bounce undeliverable messages more promptly, so senders will be alerted sooner about any delivery delays, set control/queuelifetime with a value equal to a day or so:

# echo "82800" > control/queuelifetime
# bin/qmail-showctl | grep queuelifetime
queuelifetime: Message lifetime in the queue is 82800 seconds.

Now the message will bounce if not delivered within 23 hours.

By default, qmail will accept email messages of any size:

# bin/qmail-showctl | grep databytes
databytes: (Default.) SMTP DATA limit is 0 bytes.

In this case, 0 means no limit. Your email server can be bombed with message attachments containing gigabytes of nasty Tonya Harding video clips.

Okay, so you want video clips of Tonya Harding.

Sooner or later, though, you'll want to do the right thing:

# echo "4000000" > control/databytes
# bin/qmail-showctl | grep databytes
databytes: SMTP DATA limit is 4000000 bytes.

Here the datalimit is set to about 4 million bytes. (That's octets for our international viewers.) This is plenty big, as big as an entire Yahoo! mailbox. So you can get at least get a few stills of Tonya Harding...

Try to set control/databytes as low as local policy will permit.

The alias account is qmail's user of last resort. If qmail accepts a message to someuser@thishost for local delivery, and it can't find a user named someuser, it will try delivery to user alias.

More importantly, qmail never delivers to user root --that is, any user account with a uid of 0. Instead, qmail always sends all messages addressed to root to the special alias account.

The home directory for user alias is /var/qmail/alias. qmail looks for delivery instructions specified in the .qmail (dot-qmail) files it finds in this directory.

The dot-qmail convention that qmail applies for the alias user is this: look for a file named .qmail-someuser for delivery instructions to follow for someuser.

The configuration step at this point, then, is to give qmail delivery instructions for root, as well as for a few other standard users expected on any email system:

# cd /var/qmail/alias
# echo '&admin@security.example.org' > .qmail-root
# echo '&paula-postmaster' > .qmail-mailer-daemon
# echo '&paula-postmaster' > .qmail-postmaster

In this example, system generated mail sent to user root is forwarded to admin@security.example.org, where the host security.example.org could be another server on the internal network. Mail received and/or generated for mailer-daemon and postmaster will be sent to paula-postmaster, where user paula is presumably an account set up on this server.

You can add any number of aliases you want this way, including aliases for regular users. But we'll see a better way to handle aliases for regular users later on, when we look at the fastforward package.

Okay, qmail has some mail for you, and you are a local user on this system. Where should qmail put it?

Each of your users needs at least one mailbox. Although qmail can be configured to deliver to different types of mailboxes and in different locations, the only one we will consider here is the type known as Maildir, installed in each user's home directory.

First, decide on a standard name to use for the default mailbox on this server. Maildir is a common choice. But let's say this server will mostly be used as a POP server, where most users on the network will collect their mail via POP, rather than login account. So we'll have qmail deliver to Maildir mailboxes named MAILDIR.POP.

For every user you want to receive mail, then, execute a sequence of instructions similar to the following:

# cd /var/qmail
# bin/maildirmake /home/paula/MAILDIR.POP
# chown -R paula /home/paula/MAILDIR.POP
# echo "./MAILDIR.POP/" > /home/paula/.qmail
# echo "./MAILDIR.POP/" > /home/paula/.qmail-default
# chown paula /home/paula/.qmail*

The maildirmake utility is first used to create a Maildir in the user's home directory. That Maildir needs to be owned by the user. Then, some dot-qmail files are created to point to the Maildir qmail should deliver mail to. These dot-qmail files also need to be owned by the user.

Note: the ending slash / is important for the ./MAILDIR.POP/ entries in the dot-qmail files. This tells qmail that the mailbox type is a Maildir.