qmail dirty and quick setup for the lazy v1.1
by psygnosis <norbert@feu-nrmf.ph>
This document aims to be a simple and quick guide in configuring qmail. This is a summarization on how I configure qmail on my own network. This document will not give you qmail's history, features, and services. Just a _very simple_ guide. I assume that the reader has a basic knowledge on UNIX and how it works, file permissions, text file editing, adding users, and a basic knowledge on how to use some GNU tools such as gcc, gzip, binutils and tar. Credits to all the sources in the internet, to Dan Bernstein for making such an excellent program, to my collegues, and to Ycel :-) I - Introducing qmail What is qmail?
qmail is an Internal Mail Transfer Agent (MTA) written by Dan Bernstein. qmail uses the Simple Mail Transfer Protocol (SMTP) to exchange messages with MTA's on the Internet. Why use qmail?
There are hundreds of reasons why switch to qmail. Here's a few: II - Preparation for the installation System Requirements:
qmail will install and run on any UNIX or UNIX-like operating system, although
some conditions should be met: Note that you need a working DNS in configuring qmail, normally, DNS responses have been limited to 512 bytes. Unfortunately, some sites (like AOL) returns DNS responses greater than that. So such sites violates the RFC's. qmail's DNS resolver is strictly RFC compliant, and doesn't accept replies that violates the RFC's. Fortunately there are ways we can do so that qmail can accept DNS replies that are non-RFC's.
http://www.flounder.net/qmail/qmail-dns-patch
http://cr.yp.to/djbdns.html
III - Installation OK Let's get our hands dirty!!! :) First of all, become root! 
     NPC$ whoami
     psygnosis
     NPC$ su
     Password:
     NPC# whoami
     root
Create the qmail directory: 
     NPC# mkdir /var/qmail
     NPC# mkdir /var/qmail/alias
Create qmail users and group: Now, we must create the users and groups that the various qmail daemon will run as. Create them using the command adduser, useradd, or vipw (depending on your operating system)
User    Group   HomeDir          Shell
---------------------------------------------
alias   nofiles /var/qmail/alias /bin/nologin
qmaild  nofiles /var/qmail       /bin/nologin
qmaill  nofiles /var/qmail       /bin/nologin
qmailp  nofiles /var/qmail       /bin/nologin
qmailq  qmail   /var/qmail       /bin/nologin
qmailr  qmail   /var/qmail       /bin/nologin
qmails  qmail   /var/qmail       /bin/nologin
Create the qmail control directories and set permissions: 
     NPC# mkdir /var/qmail/supervise
     NPC# mkdir /var/qmail/supervise/qmail-send
     NPC# mkdir /var/qmail/supervise/qmail-smtpd
     NPC# chmod -t /var/qmail/supervise/qmail-send
     NPC# chmod -t /var/qmail/supervise/qmail-smtpd
     NPC# mkdir /var/qmail/supervise/qmail-send/log
     NPC# mkdir /var/qmail/supervise/qmail-smtpd/log
     NPC# mkdir /var/log/qmail
     NPC# mkdir /var/log/qmail/qmail-send
     NPC# mkdir /var/log/qmail/qmail-smtpd
     NPC# chown qmaill /var/log/qmail
     NPC# chown qmaill /var/log/qmail/*
If you're using a POP server, you may also do the following: 
     NPC# mkdir /var/log/qmail/qmail-pop3d
     NPC# chown qmaill /var/log/qmail/qmail-pop3d
Assign qmail aliases:

     NPC# cd /var/qmail/alias
Assign a username for .qmail-root, qmail-postmaster and .qmail-mailer-daemon. Example: NPC# echo psygnosis > .qmail-root Note that to prevent the possibility of qmail running commands as privileged user, qmail ignores users whose UID is 0 but this doesn't mean that qmail won't deliver to root, it just means that such a delivery will have to be handled by a non-root user. Typically the user on .qmail root :-) Unpack the packages: (assuming you'll unpack the packages in /qmail-dist) 
     NPC# mkdir /qmail-dist
     NPC# cd /qmail-dist
     NPC# tar xvfz /path/to/package (e.g. tar xvfz ~/qmail-1.03.tar.gz)
Read the INSTALL files in the qmail source directory for more info. Compile qmail-related packages: 
     NPC# cd /path/to/ucspi-tcp-source
     NPC# make setup check

     NPC# cd /path/to/fastforward-source
     NPC# make setup check

     NPC# cd /path/to/dot-forward-source
     NPC# make setup check
Compile/Build qmail:
Apply the oversize DNS patch: (If you choose to apply the patch) 
     NPC# cd /src/directory/of/qmail #(e.g. cd /qmail-dist/qmail-1.03)
     NPC# patch -p1 < /patch/to/qmail-dns-patch
Build qmail: 
     NPC# cd /patch/to/qmail-source
     NPC# make setup check
     NPC# ./config
The config script will try to do a reverse lookup on all local IP addresses. If this doesn't work, you may try to do the following:
     NPC# ./config-fast your.host.name
Note that you'll probably need to update some files in /var/qmail/control. But almost by default, we don't need to update it.

Install daemontools: 
     NPC# cd /path/to/daemontools
     NPC# cd admin/daemontools-x.x.x (x.x.x depending on the version)
     NPC# package/install
On BSD systems, you must reboot NOW to invoke daemontools or simply issue the command: 
     NPC# csh -cf '/command/svscanboot &'
daemontools by default will create /service directory. If not, create it manually. Optionally, we can make svscan (a part of daemontools) to start every time we reboot. We can accomplish it with a simple script. In Linux, we may try something like this: 
     #!/bin/sh
     case "S1" in
     start)
         echo "Starting svscan..."
         env - PATH="/usr/local/bin:$PATH" svscan &
         echo $! > /var/run/svscan.pid
         ;;
     stop)
          echo "Stopping svscan..."
          kill `cat /var/run/svscan.pid
          svc -dx /service/*
          svc -dx /service/*/log
          ;;
      *)
          esac
          exit
In BSD systems, after installing daemontools, the system will be configured to start svscan every boot. If it fails to start during reboot, put the line: 
     csh -cf '/command/svscanboot &'
in your /etc/rc.local file.

Create the access control file:

qmail, by default does not allow relaying, even by localhost. It only allow the hosts listed on /var/qmail/control files. To allowrelaying from other host (e.g. localhost and local network), create a file named /etc/tcp.smtp and put the following: 
     127.0.0.1:allow,RELAYCLIENT=""
     192.168.0.:allow,RELAYCLIENT=""
     :allow
If you don't need to have any access control just put the line: 
     :allow
in your /etc/tcp.smtp file. For more information, see tcprules man page. After creating the rules, you need to activate them by building a database using the command tcprules: 
     NPC# tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp
Create the /var/qmail/rc file:

Create /var/qmail/rc file. This files tells qmail where to deliver mails. If you want to deliver mail to the typical /var[/spool]/mail directory, the content of /var/qmail/rc would look like this: 
     #!/bin/sh
     exec env - PATH="/var/qmail/bin:$PATH" \
     qmail-start '|dot-forward. forward |preline procmail'
qmail introduces another way to deliver message, it's called Maildir. Every message is stored in a directory. It's lock free, and more reliable. For more information read INSTALL.maildir, INSTALL.mbox and INSTALL.vsm. I'd recommend using Maildir, but we're all a free person. Feel free to select. If you want to use Maildir, you're /var/qmail/rc would look like this: 
     #!/bin/sh
     exec env - PATH="/var/qmail/bin:$PATH" \
     qmail-start '|dot-forward. forward ./Maildir/'
or you can create a file named /var/qmail/control/defaultdelivery and may contain the line like this: 
     ./Maildir/
And you can make your /var/qmail/rc file look like this 
     #!/bin/sh
     exec env - PATH="/var/qmail/bin:$PATH" \
     qmail-start "`cat /var/qmail/control/defaultdelivery`"
Note that I uses backquotes (`), not single quotes ('). Note that to use Maildir, every user should have it's own Maildir directory and must be owned by the user it belongs to. For example as user "psygnosis": 
     NPC$ whoami
     psygnosis
     NPC$ cd ~ <-- go to the home dir
     NPC$ mkdir ~/Maildir
     NPC$ mkdir ~/Maildir/new
     NPC$ mkdir ~/Maildir/cur
     NPC$ mkdir ~/Maildir/tmp
Also don'tforget to create a .qmail file in every home directory: 
     NPC$ whoami
     psygnosis
     NPC$ cd ~ <-- go to the home dir
     NPC$ echo "./Maildir/" > .qmail
Note that .qmail file controls the delivery of the user's mail.If you create Maildirs as root, you have to chown it (see chown man page) in order to change the ownership. I'd recommend putting Maildir in /etc/skel, so that Maildir will be created automatically each time you add a new user. Also putting .qmail file in /etc/skel.
     NPC# mkdir /etc/skel/Maildir
     NPC# mkdir /etc/skel/Maildir/cur
     NPC# mkdir /etc/skel/Maildir/new
     NPC# mkdir /etc/skel/Maildir/tmp
     NPC# echo "./Maildir/" > /etc/skel/.qmail
Don't forget to make /var/qmail/rc file executable:
     NPC# chmod a+x /var/qmail/rc
Create the qmail 'run' scripts:Create the following files named run with the following contents and make them executable using 'chmod +x' (see chmod man page).

For /var/qmail/supervise/qmail-send/run:
#!/bin/sh
exec /var/qmail/rc
For /var/qmail/supervise/qmail-send/log/run:
#!/bin/sh
exec /usr/local/bin/setuidgid qmaill \ 
/usr/local/bin/multilog t s2500000 \
/var/log/qmail/qmail-send
For /var/qmail/supervise/qmail-smtpd/run:
#!/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
Note that I used backquotes (`), not single quotes ('). Also note that the memory limit specified in softlimit (via -m) #may need to be raised depending upon system resources. If attemps to port 25 fails, or the remote system cannot send
you mail, try raising it (e.g. 3000000 or 4000000).

For /var/qmail/supervise/qmail-smtpd/log/run:
#!/bin/sh
exec /usr/local/bin/setuidgid qmaill \
/usr/local/bin/multilog t s2500000 \
/var/log/qmail/qmail-smtpd
Don't forget to make them executable :-)
     NPC# chmod +x /var/qmail/supervise/qmail-send/run
     NPC# chmod +x /var/qmail/supervise/qmail-send/log/run
     NPC# chmod +x /var/qmail/supervise/qmail-smtpd/run
     NPC# chmod +x /var/qmail/supervise/qmail-smtpd/log/run
IV - Running qmail

Kill and Replace sendmail:
Now you're ready to go away with sendmail :-)
     NPC# kill -9 <pid-of-sendmail>
To look for sendmail's pid, perform the command:
     NPC# ps -ef | grep sendmail
In Linux and FreeBSD systems, you can kill sendmail like this:
     NPC# killall -TERM sendmail
If you have zap installed, you may perform like this:
     NPC# zap -y sendmail
Replace the sendmail binaries by renaming the old sendmail, and creating a symlink to qmail. For example:
     NPC# mv /usr/sbin/sendmail /usr/sbin/sendmail.orig
     NPC# mv /usr/lib/sendmail /usr/lib/sendmail.orig
     NPC# ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail
     NPC# ln -s /var/qmail/bin/sendmail /usr/lib/sendmail
     NPC# mv /usr/sbin/newaliases /usr/sbin/newaliases.orig
     NPC# ln -s /var/qmail/bin/newaliases /usr/sbin/newaliases
If you want, you may remove the sendmail package on your system, or keep sendmail off from starting when the system reboots.

Starting qmail:

Alright everything is already done, svscan is already running (if you follow this documentation thoroughly) and listening to /service. Now it's time to create a symlink to /service (since svscan is listening to /service) to the qmail control directory.
     NPC# ln -s /var/qmail/supervise/* /service/
qmail services should start within a few minutes or a few seconds. To check if the service have started, run ps.
     NPC# ps wauxw | grep qmail
You should see several task running, at least qmail-send and some supervise processes. If this processes don't show up within a minute, you've probably done something wrong :-( Go back and retrace.A properly-running, complete (but minimal) qmail system should have the following processes:Once you're quite sure that the processes show up, you can test local deliveries (see the TEST files in the qmail source dir), or you can check if the qmail smtp daemon is listening to a SMTP service by telnetting to port 25 of the machine running qmail.V - The qmail control files
Check your /var/qmail/control directory. The three most important files are:VI - fastforward
Most sendmail users are familiar with /etc/aliases, Dan Bernstein fastforward package supports everything sendmail supports in /etc/aliases (plus more).To activate /etc/aliases, put the following in /var/qmail/alias/.qmail-default file:
     |fastforward -d /etc/aliases.cdb
VII - qmail-pop3d
Maybe you need a good POP server fot qmail. qmail-pop3d is a fine POP server. It is also written by Dan Bernstein. It's modular, and can support multiple authentication scheme. qmail-pop3d only supports Maildir format mailboxes.A qmail-pop3d server consists the 3 major modules: the qmail-popup, is the one who gets the username and password, the checkpassword, is the one that authenticates the username/password, and the qmail-pop3d itself, the POP daemon.Typically, qmail-pop3d can be run via inetd or tcpserver (although again, I'd recommend to run it via tcpserver).To use and install qmail-pop3d, you must have a qmail system running (of course), and make sure that the default delivery will be in ./Maildir/.You must also download the checkpassword package, available at http://www.qmail.org/top.html#checkpassword. If you want simplier authentication, you can grab checkpwd at http://cr.yp.to/checkpwd.html.After downloading the checkpassword package, compile it (of course). For more flexibility in following this document, install the package as /bin/checkpassword :-)Then create the necessary scripts:
     NPC# mkdir /var/qmail/supervise/qmail-pop3d
     NPC# cd /var/qmail/supervise/qmail-pop3d
     NPC# vi run (or use any editor of your choice)
The file /var/qmail/supervise/qmail-pop3d/run should look like this:
#!/bin/sh
exec /usr/local/bin/softlimit -m 2000000 \
/usr/local/bin/tcpserver -v -R -H -l 0 0 110 \
/var/qmail/bin/qmail-popup <pop-domain> /bin/checkpassword \
/var/qmail/bin/qmail-pop3d Maildir 2>$1
Where <pop-domain> is a valid POP server, e.g. pop.psygnosis.org.And make the script executable:
     NPC# chmod +x /var/qmail/supervise/qmail-pop3d/run
Create the log/run script:
     NPC# mkdir /var/qmail/supervise/qmail-pop3d/log/
     NPC# cd /var/qmail/supervise/qmail-pop3d/log
     NPC# vi run (or use any editor of your choice)
The /var/qmail/supervise/qmail-pop3d/log/run may look like this:
#!/bin/sh
exec /usr/local/bin/setuidgid qmaill /usr/local/bin/multilog \
t /var/log/qmail/pop3d
And make the run file executable:
     NPC# chmod +t 
/var/qmail/supervise/qmail-pop3d/log/run
And load qmail-pop3d:
     NPC# svc -u 
/service/qmail-pop3d
VIII - Mailing list manager
ezmlm
ezmlm is a mailing list manager written by Dan Bernstein for use with qmail. It heavily relies on some features of qmail. For more information on ezmlm, see http://www.ezmlm.org or http://cr.yp.to/ezmlm.html. Majordomo
This is the most popular UNIX mailing list manager. It can work on qmail with a simple changes. You can see the qmail/Majordomo FAQ at http://www.eyrie.org/~eagle/faqs/mjqmail.html.

IX - Other related packages
dot-forward
This package is a Sendmail compatibility package. This package gives qmail the ability to use Sendmail's .forward files. For more information on this package, see http://cr.yp.to/dot-forward.html

fastforward
This is another Sendmail compatibility add-on. It can give qmail the ability to use Sendmail's aliases file (usually /etc/aliases). For more information, see http://cr.yp.to/fastforward.html.

ucspi-tcp (pronounced ooks-pie tee see pee)
qmail SMTP is not an stand-alone daemon. It needs to be invoked via inetd, xinetd, or tcpserver. Although inetd can be fine, tcpserver (which is a part of ucspi-tcp package) is the recommended daemon because of the following reasons: Also note that tcpserver is the daemon recommended by Dan Bernstein, the author of qmail. For more information on ucspi-tcp, see http://cr.yp.to/ucspi-tcp.html.

daemontools
This package consists a set of utilities for controlling and monitoring services. This package is HIGHLY RECOMMENDED. The daemontools package consists the major four components: 1.) the supervise, which monitors a service and can restart the service when it dies, 2.) the svc, w/c can send a signal to supervise (e.g. to stop, pause or restart a service), 3.) the multilog tool, which maintains a log for a service, and the 4.) setuidgid tool, w/c has the ability to run a programs for root with a normal user UID and GID. For more information, see http://cr.yp.to/daemontools.html.

IX - Other packages that may be useful

vpopmail - a free GPL software package, to provide an easy way to manage virtual email domains and non /etc/passwd email accounts on your qmail mail server.

courier-imap - an IMAP server that only supports Maildir.

sqwebmail - a web-based email client.

openwebmail - yet another web-based email client written in perl


This document comes with absolutely NO WARRANTY. If you find any errors or have any suggestions, comments, and questions regarding this document. Feel free to email me at norbert@feu-nrmf.ph.