Qmail

qmail is a secure, reliable, efficient, simple mail transport system (MTA)

Installation

NOTE — make sure host fully-qualified domain name is defined. In /etc/hosts:

    127.0.1.1	myhost.domain.com

UPDATE — qmail v1.06-4 is now delivered in a recent update on Debian/Ubuntu. To install:

sudo apt-get install qmail qmail-run qmail-uids-gids

This might fail when upgrading. Typically install script will complain that qmail users are not linked to group nofiles, and have an incorrect home path. Add group and edit /etc/passwd:

sudo addgroup --gid 65533 nofiles
sudo vi /etc/passwd

Older version — On Debian/Ubuntu, install package qmail-src and run the command build-qmail:

sudo apt-get install qmail-src
build-qmail                       # Follow instructions

By default, it will produce a .deb file in /tmp/qmail. Note that the resulting .deb file is linked to uid/gid on your machine. Now install the package:

sudo dpkg -i qmail_1.03-47_i386.deb

If you have a conflict with an existing MTA (like courier-mta), you'll have to remove it first:

sudo dpkg -r --force-all courier-mta           # Force removal, ignore dependencies
sudo dpkg -r --force-all courier-mta-ssl      
sudo dpkg -i qmail_1.03-47_i386.deb
sudo apt-get -f install                        # Fix broken dependencies, if any

Reference

• Package documentation, at /usr/share/doc/qmail
  • check README.Debian.gz for difference between standard and Debian setups,
  • check INSTALL.alias.gz, INSTALL.ctl.gz for quick walkthrough on installation,
  • check TEST.deliver.gz, TEST.receive.gz for some tips on testing your new installation,
  • check the FAQ.gz (virtual domains, i.e. §3 and next).
• Man pages,
  • man dotqmail for the format of ~/.qmail files
  • man qmail-control for list of configuration files, and corresponding man pages.
• Life with qmail, very detailed instructions

A bit of explanation

A quick summary of how things work in qmail. The objective is only to make the configuration simpler to understand. We limit ourselves to local mail delivery (no relay). For more details:

• On the default delivery instruction, see man qmail-start, man qmail-lspawn, man qmail-local,
• on file rcpthosts, see man qmail-smtpd,
• on file locals, see man qmail-send,
• on file virtualdomains, see man qmail-send,
• on files ~/.qmail and ~/.qmail-ext, see man dot-qmail and man qmail-local.

Launching qmail

On Debian, qmail is launched by the script /etc/init.d/qmail. The script starts qmail-start (unless qmail-send is still running). The script also sets the default delivery method to use if none is found by qmail (variable $alias_empty, passed to qmail-start).

Receiving a mail

Done by qmail-smtpd, which accepts only envelope recipient address with a domain listed in file rcpthosts (or address without a @). It forwards the message to qmail-queue, which basically queue it for delivery by qmail-send.

Delivering a mail

Mail delivery is done by qmail-send, which delivers message locally only if recipient address domain is listed in file locals. If not, qmail-send reads file virtualdomains for possible match. If the address starts with username of a local user account (i.e. an account with a home directory), the message is delivered to that account. Otherwise the message is delivered to a special user, alias (~alias is set to /var/qmail/alias, which links to /var/lib/qmail/alias on Debian).

Delivering a mail locally

Done by qmail-local, which delivers message to a local user or non-user account. qmail-local looks for delivery instructions in file ~/.qmail, or file ~/.qmail-ext for virtual users controlled by that user (as defined in file virtualdomains). If file ~/.qmail does not exist, or is empty, qmail-local follows the default delivery instruction as defined in the launch script. On Debian, the mail is forwarded to procmail, which sends the mail to /var/spool/mail as usual (bad, bad, bad, see configuration).

For virtual users, if file ~/.qmail-ext is empty, qmail-local follows the default delivery instruction. If the file does not exist, qmail-local will try several default .qmail files, and if none are found, the mail is bounced.

Remember that mails delivered to non-user accounts (like root, postmaster...) are controlled by the special user alias. For these, qmail-local follows the delivery instructions defined by the files ~alias/.qmail*.

Configuration

We use the paths defined in the Debian package:

• /etc/init.d/qmail — Debian launch script
• /etc/qmail — Control configuration files (/var/qmail/control)
• /var/lib/qmail/alias — Home dir of special user alias (/var/qmail/alias)

Setting up Maildir as default delivery instruction

Edit launch script to select Maildir as default deliver instruction:

# alias_empty="|/usr/sbin/qmail-procmail"  # procmail delivery to /var/spool/mail
alias_empty="./Maildir/"                   # This uses qmail prefered ~/Maildir/ directory

Create Maildir folder for all new user, and for all existing user accounts:

sudo maildirmake /etc/skel/Maildir
for u in abc xyz; do sudo su $u -c "maildirmake /home/$u/Maildir"    # Repeat for all local users

On Debian, it seems that these last steps are done automatically when installing the qmail package.

Why use Maildir instead of Debian default delivery mechanism (see README.Debian.gz and INSTALL.maildir.gz):

• Maildir is safer that /var/spool/mail and prevents any mail loss, even over NFS.
• In Maildir, every mail is a different file, so it can be more easily and efficiently archived (incremental backup).

Create minimum set of aliases

See INSTALL.alias.gz for the list. Basically we need to create alias for root, postmaster, abuse and mailer-daemon:

# As root
cd /var/lib/qmail/alias
echo username>.qmail-root                        # Replace 'username' with account that shall receive 'root' email
echo username>.qmail-postmaster                  # Replace 'username' with account that shall receive 'postmaster' email
ln -sf .qmail-postmaster .qmail-mailer-daemon
ln -sf .qmail-postmaster .qmail-abuse
chmod 644 .qmail*

Note that user alias has home at /var/lib/qmail/alias.

Define domains

See file INSTALL.ctl.gz, man qmail-smtpd, man qmail-send.

At minimum, you must tell qmail your hostname:

# As root
cd /etc/qmail
echo full.host.name > me          # This must the full qualified name of your host (e.g. heaven.com)
chmod 644 me

However it is best to also define some more:

# As root
cd /etc/qmail
echo localhost > rcpthosts        # Is this needed?
echo full.host.name >> rcpthosts  # Append!
echo full.host.name > locals
chmod 644 *

Define delivery instruction for each user

See man dot-qmail. Basically each user may change the way mails address to them are delivered by qmail:

# As user 'username'
cd
echo './Maildir/'>.qmail          # Make sure Maildir is used, whatever the default mechanism
chmod 644 .qmail

More complex rule can be defined. For instance, if the user has several extension addresses, and wants to group all mails delivered to those addresses in a separate Maildir:

maildirmake ~/Maildir-virtual
echo './Maildir-virtual'>.qmail-default
chmod 644 .qmail-default

Alternatively, mails can be forwarded to an external address, or to an auto-reply or mail processing program.

Further configuration

See man qmail-control for a list of all configuration files, and the corresponding man pages.

Testing qmail installation

When everything is set up, it is good practice to test the installation. See file TEST.deliver.gz and TEST.receive.gz for instructions.

Example Configuration on Ubuntu 12.04

Here a quick configuration log on Ubuntu 12.04 for illustration purpose:

• Install qmail:

sudo apt-get install ucspi-tcp qmail

• Configure local domain name.

sudo /usr/lib/qmail/bin/config-fast nxl67170ux.wbi.nxp.com

This should set the files as follows:

wbi.nxp.com               # in /etc/qmail/defaultdomain
nxl67170ux.wbi.nxp.com    # in /etc/qmail/locals
nxl67170ux.wbi.nxp.com    # in /etc/qmail/me
nxp.com                   # in /etc/qmail/plusdomain
nxl67170ux.wbi.nxp.com    # in /etc/qmail/rcpthosts

• Set Maildir as default delivery mechanism:

echo ./Maildir/ | sudo tee /etc/qmail/defaultdelivery

• Configure user alias:

sudo su alias
cd ~alias
maildirmake Maildir
echo beq06659 > .qmail-postmaster    # user 'beq06659' will receive mail for POSTmaster
echo beq06659 > .qmail-root          # ... and root
#echo &alias

• Tell qmail to reload its configuration

sudo pkill -SIGUSR1 qmail

• Run some test

tail --follow /var/log/qmail/current

# in a separate window:
echo to: beq06659 | /var/lib/qmail/bin/qmail-inject
echo to: notfound | /var/lib/qmail/bin/qmail-inject
echo to: beq06659@localhost | /var/lib/qmail/bin/qmail-inject
echo to: beq06659@nxl67170ux.wbi.nxp.com | /var/lib/qmail/bin/qmail-inject
echo to: POSTmaster | /var/lib/qmail/bin/qmail-inject
echo to: root | /var/lib/qmail/bin/qmail-inject

How-To

Forward mails from remote mailbox to several local users

Let's imagine you have a remote mailbox at server myisp.com, and you want to forward all mails delivered to that mailbox to users 'john' and 'jane' on your home pc. Here's what you need to do:

1. Install fetchmail
2. Setup domains and virtual users
3. Setup aliases

Installing fetchmail

fetchmail is a program that retrieves your mails on a remote mail server and forward them to your local mail transport agent (i.e. qmail). We won't explain here how to configure fetchmail, but let's assume that it is configured to fetch regularly mail from server myisp.com and forward them to qmail on your home pc.

Setup domains and virtual users

Let's assume that the FQDN of your home pc is mypc.local. You need to configure the control files as follow:

me	mypc.local
rcpthosts	localhost mypc.local myisp.com
locals	mypc.local
virtualdomains	myisp.com:alias-myisp

With this configuration, any mail sent to any@myisp.com will be addressed to alias-myisp-any@myisp.com and will be delivered locally.

Setup aliases

Let's assume that only mails addressed to family@myisp.com shall be forwarded to user john and jane. Other mails of the same domain (if any) shall be forwarded to john only. Here's how you shall define the delivery instructions for alias myisp:

~alias/.qmail-myisp-family	john jane
~alias/.qmail-myisp-default	john

Note that another solution would be to tell qmail to forward all mails from myisp.com to local extension address john-myisp, and have user john configure his .qmail files accordingly.