qmail guide

Introduction
Why qmail?
Why switch to qmail? If you've ever edited a sendmail.cf file, you know why. But there are other reasons to switch. Here are some of the more common reasons:
• Security. qmail is secure. This claim was backed up by a $1000 prize offered by qmail supporters. After a year, the prize money was not claimed, and was sent to the Free Software Foundation. Dan Bernstein, the author of qmail, is also currently offering a $500 prize for anyone who can find a security hole in qmail.
• Speed. qmail is capable of handling millions of deliveries per day on a moderate system. Even a 486 can handle mail volumes of 100,000 messages per day and many simultaneous deliveries.
• Reliability. qmail writes mail to disk before it announces success. This way, even if there is a loss of power in the middle of a disk write, qmail will not lose mail.
• Extremely easy virtual domain administration. There is even an add-on for qmail called vpopmail which supports Virtual POP domains. Using this package, it is possible to set up POP3 users who do not even have UNIX accounts on the system.
• User-controlled mailing lists using ezmlm.
• Intuitive, straightforward, and simple administration.
Like any good software, if you want to get the most out of qmail, you will have to understand the theories behind how it works, and why it does things the way it does. (for a very high-level look at how the components of qmail interact with each other, check out the qmail big picture.)
My first advice to you will be: read all of the INSTALL files, and as many of the man files as you can. Learning how qmail's basic theories differ from those of sendmail's is a key requirement for understanding qmail. Try to get an idea of how qmail works.
Qmail breaks up each specific task of mail handling and assigns each to a different program. Each program is independent. This model has several advantages, including ease of use, faster debugging, and easy integration with custom tools.
Requirements
Before even attempting to install qmail, your system must meet the following requirements:
• You must be running UNIX or a UNIX-like operating system. A mostly complete list of operating systems that qmail supports is contained in the README file which is supplied with the qmail distribution.
• You MUST have a working DNS, and your system must have a DNS name. qmail does not search an /etc/hosts file in order to look up domain names. A workaround is possible using smtproutes, but doing this is not recommended, or desirable in most cases.
• You must have a working C compiler. If your compiler cannot be called using "cc", you will have to edit the conf-* files in the qmail source tree in order to tell qmail what to use.
Our qmail installation
qmail is extremely flexible. It is possible to install it in a zillion different ways. However, if you follow this HOWTO, exactly as it is written, you will wind up with a qmail installation that is surprisingly similar to most sendmail installations, including:
• Support for /etc/aliases
• Support for .forward files
This HOWTO assumes that:
• You have a working knowledge of UNIX and its basic commands
• You know how to add users, and set up init files on your particular flavor/distribution
• You are using GNU utilities, such as patch / tar / binutils / gcc, etc.
Other Documentation
There have been a couple of books written about qmail. I'd recommend picking at least one of these up:
• The qmail Handbook by Dave Sill
• Running qmail by Rich Blum
The following are some other sites that should be of interest to anyone running qmail:
• Dan Bernstein's qmail site.
• the qmail home page.
• Life with Qmail by Dave Sill.
• Inter7, home of vpopmail and qmailadmin
1. Downloading and unpacking the source.
The first step in installing qmail is to download the necessary files from the server.
The packages you will need in order to follow this HOWTO are:
qmail
oversize DNS packet patch for qmail
ucspi-tcp
daemontools
fastforward
dot-forward
Begin by unpacking your tarballs to an appropriate place (such as /usr/local/src/)
(You'll need to become root now.)
root:/usr/local/src# tar zxvf qmail-1.03.tar.gz
Then you need to change to the qmail-1.03 folder.
root:/usr/local/src# cd qmail-1.03
2. RTFM
Once you are in the qmail folder you will want to start by reading the FAQ and INSTALL files.
root:/usr/local/src/qmail-1.03# more INSTALL
root:/usr/local/src/qmail-1.03# more INSTALL.alias
root:/usr/local/src/qmail-1.03# more INSTALL.mbox
etc...
After you return, apply the oversize DNS packet patch. This patch is necessary because some providers (such as AOL) have decided to ignore the RFC's, and return UDP DNS responses that are greater than 512 bytes. qmail's DNS resolver library is strictly RFC compliant, and does not accept non-RFC-compliant replies. This patch enables qmail to correctly process illegal DNS replies. Note that if your caching DNS server is running dnscache (part of djbdns), you do not need to apply this patch.
To apply the patch, do the following (in the qmail source dir)
root:/usr/local/src/qmail-1.03# patch -p1 < /path/to/qmail-103.patch
3. Create the qmail home directory.
The first thing we need to do on our road to qmail is to create the qmail home directory. This is the directory that almost all of qmail will reside in, including the configuration files, the queue, and the actual qmail binaries.
# mkdir /var/qmail
4. Create the necessary users and groups to run qmail.
Next, we need to create all of the users and groups that the various qmail daemons run as. See INSTALL.ids for these groups. The following commands should work on most Linux distributions, and Solaris:
# groupadd nofiles
# useradd -g nofiles -d /var/qmail/alias -s /bin/false alias
# useradd -g nofiles -d /var/qmail -s /bin/false qmaild
# useradd -g nofiles -d /var/qmail -s /bin/false qmaill
# useradd -g nofiles -d /var/qmail -s /bin/false qmailp
# groupadd qmail
# useradd -g qmail -d /var/qmail -s /bin/false qmailq
# useradd -g qmail -d /var/qmail -s /bin/false qmailr
# useradd -g qmail -d /var/qmail -s /bin/false qmails
________________________________________
Note: To obtain instructions for creating the qmail users on other operating systems, or if you are having problems with the commands above, read INSTALL.ids.
________________________________________
*** NOTE: IF YOU DO NOT CREATE THESE USERS AND GROUPS, QMAIL WILL NOT WORK. ***
________________________________________
5. Compile qmail and related programs.
The next step is to compile the programs and make the qmail directory tree.
Type:
root:/usr/local/src/qmail-1.03# make setup check
qmail will then begin compiling. If you get a successful compile, then there will be a new directory tree under /var/qmail containing the complete qmail system.
Compiling the rest of the required programs is trivial on most systems. An example for rblsmtpd:
root:/# mkdir /package
root:/# cd /package
root:/package# tar zxvf /path/to/daemontools-0.76.tar.gz
root:/package# cd admin/daemontools
root:/package/admin/daemontools# package/install

(on BSD systems, reboot now to start daemontools).
For ucspi-tcp, fastforward and dot-forward, the compile is done exactly the same as the qmail-1.03 compile. Untar the tarball, cd into the source directory and type "make setup check". If everything compiles and installs correctly, you are done compiling.
6. Configure qmail.
After qmail compiles, we will want to configure it. The easiest way to do this is:
root:/usr/local/src/qmail-1.03# ./config
The config script tries to do a reverse DNS lookup on all local IP addresses. If this doesn't work, then you've got some dirty work to do. Read INSTALL.ctl. As long as all of your local IP's are in your DNS, then you shouldn't have any problems. Otherwise you can do the following:
root:/usr/local/src/qmail-1.03# ./config-fast your.full.host.name
This will create the necessary files in order to run qmail.
After running config or config-fast, you will probably need to update some of the files in /var/qmail/control in order to make your qmail system usable. See Section 14: Control Files for a description of some of the commonly used control files and what they do.
________________________________________
Warning: If the config scripts fail for some reason, do not attempt to continue this installation! If you start your qmail system without configuring it, it will not work properly, and you will also be running an open relay!
________________________________________
7. Install the qmail aliases.
root:/usr/local/src/qmail-1.03# cd ~alias
root:/var/qmail/alias# echo adam > .qmail-root
root:/var/qmail/alias# echo bob > .qmail-postmaster
root:/var/qmail/alias# echo bob > .qmail-mailer-daemon
Qmail uses files for every alias. This is one of the major ways that qmail differs from sendmail. This is explained in greater detail below. Note that there is an alias for root. This is because root does not receive mail in qmail. In fact, qmail-lspawn will immediately die and bounce the message if UID == 0. Read INSTALL.alias for more instructions.
8. Set up daemontools and create control directories.
Now that you've installed qmail, you'll need to set everything up so that qmail starts when your system comes up. This is taken care of by the daemontools package, which, if you've followed the HOWTO carefully so far, should already be installed in /package/admin/daemontools.
First, we'll need to create the qmail service and log directories.
# mkdir -p /var/qmail/supervise/qmail-send/log
# mkdir -p /var/qmail/supervise/qmail-smtpd/log
# chmod +t /var/qmail/supervise/qmail-send
# chmod +t /var/qmail/supervise/qmail-smtpd
# mkdir -p /var/log/qmail/qmail-send
# mkdir -p /var/log/qmail/qmail-smtpd
# chown -R qmaill /var/log/qmail
________________________________________
Now, it's time to create some stuff in /var/qmail/supervise. First, cd to /var/qmail/supervise/qmail-send.
Here, we need to create a script called run with the following contents:
#!/bin/sh
exec /var/qmail/rc
Now, we need to create /var/qmail/supervise/qmail-send/log/run with the following contents:
#!/bin/sh
exec /usr/local/bin/setuidgid qmaill /usr/local/bin/multilog t s2500000 /var/log/qmail/qmail-send
Now, we will create similar files in /var/qmail/supervise/qmail-smtpd. For run, use the following:
#!/bin/sh
QMAILDUID=`id -u qmaild`
NOFILESGID=`id -g qmaild`
exec /usr/local/bin/softlimit -m 2000000 \
/usr/local/bin/tcpserver -H -R -v -p -x /etc/tcp.smtp.cdb \
-u $QMAILDUID -g $NOFILESGID 0 smtp /var/qmail/bin/qmail-smtpd 2>&1
For log/run:
#!/bin/sh
exec /usr/local/bin/setuidgid qmaill /usr/local/bin/multilog t s2500000 /var/log/qmail/qmail-smtpd
8a. Access Control
Before we can start up our qmail smtpd, we need to do some access control. The simplest way to do this is by using files in /etc. I use /etc/tcp.smtp as my access control file. If you don't need to do any access control, /etc/tcp.smtp can have just one line:
:allow
Note that a default configuration does not allow for ANY relaying, even from localhost. To allow relaying from localhost and your local network, you would have to use something like this:
127.0.0.1:allow,RELAYCLIENT=""
192.168.1.:allow,RELAYCLIENT=""
:allow
For more examples, man tcprules.
After you've created your rules, you need to activate them. tcpserver works by reading a cdb (database) file. You use the tcprules program to build the database file from your /etc/tcp.smtp file. This is accomplished by the following command:
# tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp
9. Kill sendmail!!
If you've gotten this far, that means that you are ready to do away with rickety old sendmail for good. First, find the pid of your sendmail daemon and kill it!!! In Linux:
# killall -TERM sendmail
If you don't feel that you've gained enough pleasure from this experience, then restart sendmail and kill it again. After that, do the following:
# mv /usr/lib/sendmail /usr/lib/sendmail.old
# mv /usr/sbin/sendmail /usr/sbin/sendmail.old
# ln -s /var/qmail/bin/sendmail /usr/lib/sendmail
# ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail

# mv /usr/sbin/newaliases /usr/sbin/newaliases.old
# ln -s /var/qmail/bin/newaliases /usr/sbin/newaliases
________________________________________
Note: /usr/sbin may not exist on your system.
________________________________________
________________________________________
*** IMPORTANT: Killing the sendmail process is not the only step to removing sendmail. You will also need to remove the package from your system, or at the very least keep sendmail from starting when the system is started. You will need to consult the documentation for your particular operating system in order to do this.
________________________________________
10. Create /var/qmail/rc.
/var/qmail/rc is one of the most important qmail files. It is responsible for starting qmail, but more importantly, it tells qmail what to do with every email it receives. rc contains the default delivery instructions for qmail.
We want our system to support .forward files, and deliver mail to /var/spool/mail. Therefore, we need a /var/qmail/rc file that looks something like this:
#!/bin/sh

exec env - PATH="/var/qmail/bin:$PATH" \
qmail-start '|dot-forward .forward
|preline procmail'
There are other sample rc files in the /var/qmail/boot directory. It is generally not advisable to change your rc file unless you know what you're doing.
10a. Maildir.
Maildir is an alternate way of delivering messages. Maildirs have the following benefits:
• Lock-free -- This means Maildirs are reliable over NFS.
• Enables use of qmail-pop3d, a secure POP3 daemon which comes with qmail.
• Programs don't have to stat() /var/spool/mail every time they open your mailbox. On systems with a large userbase, this can make things excruciatingly slow.
• Supported natively by the mutt MUA.
There are also some disadvantages to using Maildirs.
• Some popular mail programs, such as PINE, need to be patched and recompiled in order to use Maildirs. You will need the Bloodhounds International c-client Maildir patch in order to patch Pine.
• Maildirs store each message in its own separate file. This consumes more inodes than keeping mail in one spool file.
If you want to deliver to Maildirs in users' home directories instead of /var/spool/mail, you can change /var/qmail/rc to look something like this:
#!/bin/sh

exec env - PATH="/var/qmail/bin:$PATH" \
qmail-start '|dot-forward .forward
./Maildir/'
Remember, the Maildir must be owned by the user it belongs to. If you create maildirs as root, then you will have to use the chown command in order to change the ownership. You should include a Maildir in /etc/skel, so that the Maildir will be automatically created whenever you make a new user. To learn more about Maildirs, read INSTALL.maildir.
11. Starting qmail.
Everything is in place now, and we are ready to start qmail. Since svscan is already running, all we need to do is create symlinks in /service to our control directories in /var/qmail/supervise.
# ln -s /var/qmail/supervise/* /service/
qmail services should start within a few seconds. To check if the services have started, you can run ps.
# ps auxww | grep qmail
You should see several tasks running, at the very least qmail-send, and some supervise processes. If these processes don't show up within a minute, you've probably done something wrong, and you should go back and retrace your steps.
Once the qmail processes show up, you can test local deliveries by following the instructions in TEST.deliver. You can check to make sure your qmail-smtpd is listening by telneting to port 25 of the local machine.
12. rblsmtpd.
After MAPS, LLC went private, I have not been able to find an open relay database that I am comfortable using. Instead of blocking sites via rblsmtpd, I have instead set up TMDA, the Tagged Message Delivery Agent. It has far exceeded the effectiveness of any IP blackhole list I'v ever used. I very rarely get spam at all anymore, unless it is through one of my other accounts. My spam frequency has gone from approx. 20 spams a day to less than one a week.
Since I'm not recommending the use of rblsmtpd anymore, I am not going to update this section further. The example provided should be enough to get you working with any of the current free open relay blacklists. I strongly advise against using rogue blacklists like SPEWS.
rblsmtpd is a generic program that is part of ucspi-tcp and works with any SMTP server that can run under tcpserver (for example, qmail and sendmail.) If you only want to block sites that are listed in the MAPS RBL, then you do not need to give rblsmtpd any arguments except the name of the SMTP daemon to run. However, if you want to block based on other blocking systems, such as Relay Spam Stopper (RSS), you will need to run multiple instances of rblsmtpd, using the -b flag with the name of the server that you want each invocation to perform lookups at.
In order to add rblsmtpd to your qmail installation, you must make some changes to the run script in /var/qmail/supervise/qmail-smtpd:
#!/bin/sh
QMAILDUID=`id -u qmaild`
NOFILESGID=`id -g qmaild`
exec /usr/local/bin/softlimit -m 2000000 \
/usr/local/bin/tcpserver -H -R -v -p -x /etc/tcp.smtp.cdb \
-u $QMAILDUID -g $NOFILESGID 0 smtp rblsmtpd /var/qmail/bin/qmail-smtpd 2>&1
If you have a good eye, you can see that we've added an rblsmtpd before the qmail-smtpd process. This will block mail which is listed in the rbl.maps.vix.com zone. If we wanted to also use the RSS, we would add another rblsmtpd before qmail-smtpd, ie:
#!/bin/sh
QMAILDUID=`id -u qmaild`
NOFILESGID=`id -g qmaild`
exec /usr/local/bin/softlimit -m 2000000 \
/usr/local/bin/tcpserver -H -R -v -p -x /etc/tcp.smtp.cdb \
-u $QMAILDUID -g $NOFILESGID 0 smtp rblsmtpd rblsmtpd -rrelays.mail-abuse.org /var/qmail/bin/qmail-smtpd 2>&1
You can add as many rblsmtpd processes as you want to check multiple blacklists.
13. RTFM
At this time, it would be a good idea to read some of the official documentation. Of course, you're not going to do that, you're going to continue reading my drivel. I have an almost obscene power over you now. It intoxicates me.
Anyway, back to qmail.
14. The control files.
Once you've got your qmail system set up and running, there are a few things you're going to have to learn how to do. First of all, you'll be happy to know, that virtual hosts are *WAY* easier to do in qmail than they are in sendmail.
Look in your /var/qmail/control directory. Most likely, it'll look something like this:
nose:/var/qmail/control$ ls -la
total 8
drwxr-xr-x 2 root qmail 1024 Sep 29 10:08 .
drwxr-xr-x 10 root root 1024 Sep 18 02:48 ..
-rw-r--r-- 1 root root 22 Sep 18 02:40 defaultdomain
-rw-r--r-- 1 root root 27 Sep 18 02:40 locals
-rw-r--r-- 1 root root 27 Sep 18 02:40 me
-rw-r--r-- 1 root root 17 Sep 18 02:40 plusdomain
-rw-r--r-- 1 root root 27 Sep 18 02:40 rcpthosts
-rw------- 1 root root 147 Sep 29 10:08 virtualdomains
The three most important files here (in order of importance) are:
me -- (in fact qmail can survive with JUST this file. It contains your local host name. Including domain)
rcpthosts -- (All of the hosts that qmail will receive mail for. All of your local domains must be in this file.)
________________________________________
Important: qmail bounces mail for domains not listed in rcpthosts. All of your domains, including virtual domains, must be listed in this file. In addition, not having an rcpthosts file turns your qmail server into an open relay. Running an open relay on the internet is not acceptable, and if you do, you will soon be listed by the various open-relay blacklists such as ORBS and RSS.
________________________________________
locals -- (All of the hosts that are local. I.E. mail sent to these hosts will be delivered to users in /etc/passwd.)
15. dot-qmail.
dot-qmail is an important concept and I think it deserves its own section, even though this document is a HOWTO. This is because you will use dot-qmail for 95% of what you will do with qmail once it's installed.
dot-qmail is what tells qmail-local what to do with a message once it is received. With dot-qmail, a user can forward her mail, create ezmlm mailing lists (such as the qmail mailing list), create aliases under her own username, and call external programs such as autoresponders.
dot-qmail exists in the form of .qmail files in a user's home directory. qmail-local reads these files in order to decide what to do with a message.
When qmail does not find a .qmail file, it follows the default delivery instructions in /var/qmail/rc (or whatever script you are running qmail-start from). Please see the man page for dot-qmail for a listing of the commands available.
The great thing about dot-qmail is that it lets users set up their own aliases. If my user account is named "adam", then I can set up a file called .qmail-info, which will contain commands for processing messages addressed to adam-info. dot-qmail can be used to create as many aliases as you'd like, and can even be used for distribution lists.
16. Virtual domains.
Thanks to dot-qmail, virtual domains are as easy as normal aliases to create. The file virtualdomains uses the following format:
example.com:user
Where user is the username of the user that receives mail for this domain. This seems complicated at first, but it is actually very intuitive.
If my user account adam is specified by virtualdomains to receive mail for example.com, then any .qmail files I create in my home directory will work as aliases for example.com, as well as their normal usage. So, .qmail-info becomes info@example.com.
But what if I want to manage more than one virtual domain from my user account?

The virtualdomains file makes this very intuitive as well. Instead of putting user as the recipient, just put user-ext as the recipient. For example:
example.com:adam-example
example2.com:adam-example2
With this configuration, creating virtual host aliases is just as easy, the only difference is that we add an extension to the dot-qmail filename. Now, info@example.com becomes .qmail-example-info, and info@example2.com becomes .qmail-example2-info, etc.
If .qmail-ext doesn't exist, qmail-local will try some default .qmail files. For example, if ext is foo-bar, qmail-local will try first .qmail-foo-bar, then .qmail-foo- default, and finally .qmail-default. If none of these exist, qmail-local will bounce the message. (Exception: for the basic user address, qmail-local treats a nonexistent .qmail the same as an empty .qmail.) This paragraph was taken directly from the dot-qmail man page.
17. Fastforward.
Most sendmail users will be familiar with /etc/aliases. djb's fastforward package supports everything sendmail supports in /etc/aliases, plus more.
To activate /etc/aliases, put the following in /var/qmail/alias/.qmail-default:
| fastforward -d /etc/aliases.cdb
Congratulations, /etc/aliases is now active. You may add sendmail style aliases to /etc/aliases, along with virtual domain aliases (which sendmail doesn't support). Be sure to run /var/qmail/bin/newaliases after making any changes to /etc/aliases. Read the file ALIASES in your fastforward source distribution for more detailed information.
18. The End.
qmail is an extremely fast, flexible, and secure MTA. There are many other applications for it, and I have not even begun to scratch the surface of what you can do with it. For more information, read the qmail web site

Posted in: Linux