The "Noob Link" Technical Reference Index About Homepage

  ___  __  __    _    ___ _     
 / _ \|  \/  |  / \  |_ _| |    
| | | | |\/| | / _ \  | || |    
| |_| | |  | |/ ___ \ | || |___ 
 \__\_\_|  |_/_/   \_\___|_____|

Setting up Qmail on Debian
Qmail on Debian
Vince Hillier
Revision 0.2
1. Purpose of this document.
2. Author.
3. Copyright and Disclaimer.
4. About Qmail.
5. Installing Qmail.
6. Deployment.
     a. Null Clients.
     b. Servers.
     c. Virtual Hosting.
7. Maildir.
8. Backup Mail Server.
9. Relaying.
10. POP.
11. POP On A DNS Server.

1. Purpose Of This Document

The purpose of this document is to demonstrate the deployment of the Qmail mail server, in numerous situations. No previous knowledge of Qmail if necessary, as this paper will walk you through every step.

2. Author

This paper was written by Vince Hillier. Vince has an extensive IT background focusing on Linux, and is also an aspiring technical writer. He has written many other papers which are available on his website - as listed in section 3.

3. Copyright and Disclaimer

Please, feel free to do whatever you would like to these papers, so long as credit is given where it is due. Do not take this paper, plaster your name on it, and post it anywhere as yours. My name must remain on the paper, with no exceptions.

You can always find the most updated versions of my papers at

4. About Qmail

Qmail is an extremely nice MTA (Mail Transfer Agent). It's small, fast, and coded with security in mind from step one. There is a unclaimed $500 cash reward for anyone who discovers a security issue with Qmail.

5. Installing Qmail
apt-get install ucspi-tcp-src
apt-get install qmail-src
apt-get install procmail

That will install ucspi-tcp, procmail, and the qmail source. Next we have to compile and install Qmail. When issuing the above commands, take note of the additional packages installed, you should remove them after the installation of Qmail for security measures. By removing the compilation utilities, you make it that much harder for attackers to compile programs on the host.

The next step is to actually install Qmail, we'll do this as outlined below.


This should compile fine, when you are asked whether or not you'd like to delete all files except the qmail-xxx.deb, and if you'd like to install Qmail answer Y. You might also want to keep the qmail-xxx.deb and ucspi-tcp-xxx.deb files handy, as they can be reused on other servers saves you a lot of time when you use precompiled binaries.

6. Deployment

You have to make a choice whether you want to run a null client or server, see each section respectively to find out move about both.

a. Null Clients

Null clients forward all of there mail to another host for handling. If you have for example, a network with 5 linux machines, rather then having qmail listening on all of them, and having 5 accounts to check for mail, a simple solution is to have 4 machines send mail to the main mail server. Null Clients do not listen on any interface, because they only relay mail to the main server. Below is the setup procedure for null clients.

echo > /var/qmail/control/smtproutes

remove all entries in /var/qmail/control/local

edit /etc/init.d/qmail and comment the following:

# prevent denial-of-service attacks, with ulimit
# ulimit -v 8192
# sh -c "start-stop-daemon --start --quiet --user qmaild \
#    --exec /usr/bin/tcpserver -- -R -H \
#    -u `id -u qmaild` -g `id -g nobody` -x /etc/tcp.smtp.cdb 0 smtp \

#    /usr/sbin/qmail-smtpd 2>&1 | $logger -t qmail -p mail.notice &"

Restart qmail:

/etc/init.d/qmail restart

That's it! You've setup you're Null Client! The next thing you have to do is make sure the main server that is to receive all the mail is configured to accept mail for that host. (See Backup Mail Server)

b. Servers

Server instances of qmail offer mail delivery, and retrieval (see 10 - POP) for local and remote users. If you have 1 server on your network, and you need a MTA, then this is the setup you want.

Setup the domains you receive mail for by adding them to /var/qmail/locals and /var/qmail/rcpthosts.

echo "" > /var/qmail/{locals,rcpthosts}
echo "" > /var/qmail/{locals,rcpthosts}

Add your user account aliases to /var/qmail/aliases/

echo "user" > .qmail-user

In the above line the "user" would be the real account on the system, and .qmail-user would be the name that you want people to be able to mail you at - for example, if your username was hillierv, you would use a line like this:

echo "hillierv" > .qmail-vince

Then all mail sent to would actually be delivered to the local account, hillierv.

Add your domains to /var/qmail/control/

The files in this section are pretty straightforward, the locals file is a list of domains that this host receives mail for. You also have to specify domains that you wish to receive mail for in the rcpthosts file. (See Backup Mail Server for information on how to receive mail for another server, without delivering it to a local user.)

c. Virtual Hosting

A common feature desired by a lot of people is the ability to have and two different people. However, we also know that there can really only be one user "joe" on the system. Qmail offers a very easy way to do this.

Say your' main domain (the one listed in /var/qmail/control/me) is, and you've recently been asked to provide mail for the name What we have to do is add the following line to /var/qmail/control/rcpthosts:

Then add the following line to /var/qmail/control/virtualdomains:

What is the :user you ask? Well, the user that controls's mail. The user then sets up .qmail files in their home directory, to let qmail know what to do with that mail.

So, if they wanted to be valid, all they would have to do is create the file .qmail-joe in their home directoy, and add the username of the person who should receive the mail sent to to it. The following line will suffice:

echo "username" > ~/.qmail-joe

Then all mail sent to will be sent to username.

Alternatively, you could create the file .qmail-default, which is a "catch all" file, what this means is that all mail sent to will be delivered to the username contained in it, it's the same format as the above .qmail-joe file.

7. Maildir

My preferred mail format is Maildir. There are some advantages to using Maildir opposed to mbox. One is that Maildir handles delivery better, messages are put into directories. There for you'll never see some problems like you see in mbox formats, with mbox all your mail is stored in one big file, which is obviously prone to error. To use MailDir there are a couple things you have to do:

Right near the top of /etc/init.d/qmail there is 3 lines, comment out the first one, and uncomment the one that has Maildir in it.


alias_empty="|/usr/sbin/qmail-procmail"  # procmail delivery to /var/spool/mail
#alias_empty="./Maildir/"       # This uses qmail preferred ~/Maildir/ directory
# You may want to maildirmake /etc/skel/Maildir
#alias_empty="./Mailbox"        # This uses Mailbox file in users $HOME


#alias_empty="|/usr/sbin/qmail-procmail"  # delivery to /var/spool/mail

#alias_empty="./Maildir/"       # This uses qmail preferred ~/Maildir/ directory
# You may want to maildirmake /etc/skel/Maildir
alias_empty="./Mailbox"        # This uses Mailbox file in users $HOME

Ok, now that qmail will use Maildir, we have to actually create the Maildir. We're going to create a Maildir in the global profile so all future accounts automatically use Maildir, and setup existing accounts to use Maildir.

For future accounts:

cd /etc/skel
maildirmake Maildir

echo ./Maildir > .qmail

For current accounts (this script assumes all directories in /home are user accounts):

cd /home
for i in `ls /home`
cd $i
maildirmake Maildir
echo ./Maildir > .qmail

cd ..
8. Backup Mail Server

If you are for example, running as a backup MX for another domain, that mail should not be delivered locally. But rather be queued to deliver to the host later. If you want to accomplish this, it's very easy to do, just specify the domain you are a MX for in the rcpthosts file ONLY. When a message is received, if the domain matches any hosts in rcpthosts, it's then compared to the locals file, if there is a match in locals, it is delivered locally, if not it's queued for later delivery to the host that should have received the message, but was unreachable at the time.

9. Relaying

The process of sending mail through your mail server is known as relaying. Of course, you wouldn't want just anyone to send mail through your server, that would lead to a lot of spam originating from your hosts, wastes of bandwidth, and your mail server probably being listed in a Black List which thousands of people use to prevent "open relays" from sending mail to them.

To control who sends mail through our server, we use access controls. For a host to be allowed to send mail through your server, they'll have to be specifically authorized to do so. We use /etc/tcp.smtp to control this.

Add the IPs that you wish to allow to relay through your server to /etc/tcp.smtp

Now that the IPs are added, we have to add them to the database by issuing the following command:

tcprules tcp.smtp.cdb tcp.smtp.temp < tcp.smtp

Now we restart qmail:

/etc/init.d/qmail restart
10. POP

If you wish to allow people to remotely retrieve mail from your server, you have to setup POP. POP - Post Office Protocol is the method of delivering mail from the server to the remote client. Debian makes setting this up trivial for us.

In /etc/init.d, uncomment the following lines

# Uncomment the following lines to automatically start the pop3 server

#sh -c "start-stop-daemon --start --quiet --user root \
#    --exec /usr/bin/tcpserver -- \
#    0 pop-3 /usr/sbin/qmail-popup `hostname`.`dnsdomainname` \
#    /usr/bin/checkpassword /usr/sbin/qmail-pop3d Maildir &"

Of course, you leave the first line commented, and only uncomment lines 2 through 5.

11. POP On A DNS Server

If you run POP and a DNS server on the same machine, you have to add -H -R to the following line:

# Uncomment the following lines to automatically start the pop3 server
#sh -c "start-stop-daemon --start --quiet --user root \
#    --exec /usr/bin/tcpserver -- \
#   0 pop-3 /usr/sbin/qmail-popup `hostname`.`dnsdomainname` \
#  /usr/bin/checkpassword /usr/sbin/qmail-pop3d Maildir &"

So the above becomes:

# Uncomment the following lines to automatically start the pop3 server
sh -c "start-stop-daemon --start --quiet --user root \
   --exec /usr/bin/tcpserver -- -R -H \
  0 pop-3 /usr/sbin/qmail-popup `hostname`.`dnsdomainname` \
 /usr/bin/checkpassword /usr/sbin/qmail-pop3d Maildir &"

This prevents a lookup loop that will make your POP sessions pause for >1 minute.