This is a cached copy of the original document which can be found here
By Adam McKenna (adam-howto@flounder.net)
Last Modified: Sunday, 18-Jun-2000 03:29:53 EDT
here
Table of Contents:
i. IntroductionWhy 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:
Now when I say qmail is easier than sendmail, you must believe me, although you won't for the first few hours. qmail documentation, despite being well written and very complete, can sometimes be very esoteric, Most of it is not step-by-step instructions like a howto. 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 them. (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.
Before even attempting to install qmail, the following requirements must be met:
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:
This HOWTO assumes that:
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:
qmailYou will of course begin by unpacking your tarballs to an appropriate place (such as /usr/local/src/)
(We'll need to become root now.)root:/usr/local/src# gzip -d qmail-1.03.tar.gz root:/usr/local/src# tar xf qmail-1.03.tar
Then you need to change to the qmail-1.03 folder.
root:/usr/local/src# cd qmail-1.03
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 are done reading the INSTALL files, you won't need the rest of this HOWTO!
You're still reading. That means you didn't read the files. Bad sysadmin! Go sit in a corner for 15 minutes, or field helpdesk calls, or something equally annoying.
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.
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
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
Next, we need to create all of the users and groups that the various qmail daemons run as. See INSTALL.ids for these groups. If you run Debian Linux then the users and groups are already created for you (how nice of Debian!). 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: IF YOU DO NOT CREATE THESE USERS AND GROUPS, QMAIL WILL NOT WORK. ***
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:/usr/local/src# tar zxvf rblsmtpd-0.70.tar.gz root:/usr/local/src# cd rblsmtpd-0.70 root:/usr/local/src/rblsmtpd-0.70# make setup check
This will produce an rblsmtpd binary in /usr/local/bin.
Do the same for ucspi-tcp, daemontools, fastforward and dot-forward. If everything compiles and installs correctly, you should be done compiling.
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 12: Control Files for a description of some of the commonly used control files and what they do.
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.
Now that you've installed qmail, you'll need to set everything up so that qmail starts when your system comes up. In order to accomplish this, we're going to use svscan, which is part of the daemontools package.
If you've followed the HOWTO carefully so far, daemontools should already be installed in /usr/local/bin.
First, we'll need to create the daemontools services directory. Dan Bernstein recommends using /service for this directory. If you want to use a different directory, feel free. Just remember to replace /service with whatever directory you're using in the directions below.
# mkdir /service # mkdir /var/qmail/supervise # mkdir /var/qmail/supervise/qmail-send # chmod +t /var/qmail/supervise/qmail-send # mkdir /var/qmail/supervise/qmail-send/log # mkdir /var/qmail/supervise/qmail-smtpd # chmod +t /var/qmail/supervise/qmail-smtpd # mkdir /var/qmail/supervise/qmail-smtpd/log # mkdir /var/log/qmail # mkdir /var/log/qmail/qmail-send # mkdir /var/log/qmail/qmail-smtpd # chown qmaill /var/log/qmail # chown qmaill /var/log/qmail/*
Because of the way svscan works, we aren't going to actually create any directories under /service. Instead, we're going to create the real directories under /var/qmail/supervise. Later on, we'll make symlinks in /service to these directories, but not yet.
The next thing we need to do is make it so that svscan starts every time the system starts. On my system, I accomplish this with a simple rc script:
#!/bin/sh -e
# /etc/init.d/svscan : start or stop svscan.
# borrowed from http://Web.InfoAve.Net/~dsill/lwq.html#start-qmail
# modified by Adam McKenna <adam@flounder.net>
case "$1" in
start)
echo -n "Starting djb services: svscan "
env - PATH="/usr/local/bin:$PATH" svscan /service &
echo $! > /var/run/svscan.pid
echo "."
;;
stop)
echo -n "Stopping djb services: svscan "
kill `cat /var/run/svscan.pid`
echo -n "services "
svc -dx /service/*
echo -n " logging "
svc -dx /service/*/log
echo "."
;;
restart|reload|force-reload)
$0 stop
$0 start
;;
*)
echo 'Usage: /etc/init.d/svscan {start|stop|restart}'
exit 1
esac
exit 0
If you correctly add this script to init, svscan will start each time you boot your system. Please see the documentation for your particular system or distribution to find out how to add things to init.
If you are running Debian GNU/Linux, you would issue the following command (assuming that your script is installed at /etc/init.d/svscan):
# update-rc.d svscan defaults
In order to control qmail itself, another simple script can be used:
#!/bin/sh -e
# /etc/init.d/qmail : start or stop the qmail mail subsystem.
# borrowed from http://Web.InfoAve.Net/~dsill/lwq.html#start-qmail
# modified by Adam McKenna <adam@flounder.net>
PATH=$PATH:/usr/local/bin:/var/qmail/bin
case "$1" in
start)
echo -n "Starting mail-transport-agent:"
svc -u /var/qmail/supervise/*
echo -n " qmail"
svc -u /var/qmail/supervise/*/log
echo " logging."
;;
stop)
echo -n "Stopping mail-transport-agent: "
echo -n " qmail"
svc -d /var/qmail/supervise/*
echo " logging"
svc -d /var/qmail/supervise/*/log
;;
restart)
$0 stop
$0 start
;;
reload|force-reload)
echo "Reloading 'locals' and 'virtualdomains' control files."
start-stop-daemon --stop --quiet --oknodo --signal HUP --exec /usr/sbin/qmail-send
;;
*)
echo 'Usage: /etc/init.d/qmail {start|stop|restart|reload}'
exit 1
esac
exit 0
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 file 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 -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
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
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
/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'
Maildir is an alternate way of delivering messages. Maildirs have the following benefits:
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. A good idea is to 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.
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 one minute. 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.
rblsmtpd is a generic program that 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 file 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 -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 -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.
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.
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 likey, 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)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.
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?
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.
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.
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
I'd like to thank the following people:
You didn't think you were going to get off that easy, did you? Well, don't worry, I'm not asking for much. If this HOWTO helped you, I would appreciate it if you would send me a postcard, or if you are feeling especially thankful, an Amazon.com buy.com Gift Certificate would be cool.