Installing qmail under FreeBSD

Aaron Hill



This document describes how to set up the qmail mail transfer agent on a FreeBSD system. These instructions are known to work with FreeBSD versions 4.2 through to 6.2, and it is expected they will work with versions earlier and later than that range. This document is intended to be quite minimalist. It contains only the raw instructions for installing qmail under FreeBSD distilled from the qmail documentation. As such, it is not a substitute for reading the documentation.

Table of Contents

1. Pre-Installation
2. Installation
3. Post-installation
A. Contacting the Author
B. Credits

1. Pre-Installation

You need a FreeBSD system with the ports system installed. The machine should be connectied to an active Internet connection.

You should always update the ports system before installing any new software from it, this will ensure you are getting the latest and most secure version of the software available. More information on how to use CVS to update the ports system is available at The FreeBSD Project.

Of course if you want to receive email from the Internet you will need the FreeBSD system listed in an MX record of a correctly registered domain. The steps on how to do this will not be covered in this document.

You will need to know the Fully Qualified Domain Name (FQDN) of the FreeBSD machine. This is basically the DNS name of the machine. For example if your server's name is known in DNS as when the instructions below ask you to type the text HOSTNAME you should replace the word HOSTNAME with the word mailserver. Or when the instructions ask you to enter the text DOMAIN you should replace that word with the words

The following Installation instructions must be performed as the user root.

2. Installation

2.1. Install qmail

# cd /usr/ports/mail/qmail
# make all install clean

Check the boxes for:


Click OK. After installation, enable qmail by running the script:

# /var/qmail/scripts/enable-qmail

2.2. Install tcpserver

# cd /usr/ports/sysutils/ucspi-tcp
# make all install clean

Check the boxes for:


Click OK.

2.3. Install checkpassword

# cd /usr/ports/security/checkpassword
# make all install clean

2.4. Ensure man(1) can find the qmail man pages

Make the following change to the file /etc/manpath.config:

# echo "OPTIONAL_MANPATH /var/qmail/man" >> /etc/manpath.config

Then run:

# makewhatis

so that the manpages can be used immediately.

2.5. Permit access to the SMTP port

# echo ",RELAYCLIENT=\"\"" > /etc/tcp.smtp

At this point, if you have a LAN on which client machines will require access to the SMTP port to send email, add the network part of the LAN's IP address space. For example, if hosts on the LAN are in the range–, issue this command:

# echo "192.168.0.:allow,RELAYCLIENT=\"\"" >> /etc/tcp.smtp

Finally, build the ruleset for tcpserver:

# echo :allow >> /etc/tcp.smtp
# /usr/local/bin/tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp

2.6. Modify skeleton directory files in /usr/share/skel

2.6.1. dot.cshrc

Find the following line in dot.cshrc:

set mail = (/var/mail/$USER)

and modify the file as follows:

#set mail = (/var/mail/$USER) 
setenv MAIL ~/Mailbox
setenv MAILDIR ~/Maildir
setenv MAILTMP ~/Maildir/tmp/tmpfile
alias mail '/var/qmail/bin/maildir2mbox;/var/qmail/bin/qail'
alias pine '/var/qmail/bin/maildir2mbox;/var/qmail/bin/pinq'
alias elm  '/var/qmail/bin/maildir2mbox;/var/qmail/bin/elq'

2.6.2. dot.shrc

Append the following lines to the end of dot.shrc

alias mail='/var/qmail/bin/maildir2mbox;/var/qmail/bin/qail'
alias pine='/var/qmail/bin/maildir2mbox;/var/qmail/bin/pinq'
alias elm='/var/qmail/bin/maildir2mbox;/var/qmail/bin/elq'

2.6.3. dot.qmail

Create the file dot.qmail and add this line:


2.6.4. Maildir

Execute the following command to make the Maildir directory:

# /var/qmail/bin/maildirmake /usr/share/skel/Maildir

2.7. Set up existing users for qmail

2.7.1. Create Maildir and .qmail

Execute the following commands for each existing user:

# cp -R /usr/share/skel/Maildir ~USERSNAME/
# cp /usr/share/skel/dot.qmail ~USERSNAME/.qmail

2.7.2. Modify each user's shell startup file

Determine the login shell for each user, and modify the startup file for that shell in the manner described above.

If you are confident that a user has not modified their .cshrc and .shrc files, you can just copy the files /usr/share/skel/dot.cshrc and /usr/share/skel/dot.shrc over the files ~USERNAME/.cshrc and ~USERNAME/.shrc.

2.8. Edit the startup script for qmail

Append the following lines to the end of /etc/rc.conf to set some variables used in the qmail startup script to follow:

# qmail options

In the following sections, HOSTNAME refers to the name of the localhost, and can be determined by running:

# hostname -s

HOSTNAME.DOMAIN refers to the machine's fully qualified domain name (FQDN), and can be determined with:

# hostname

Obviously, DOMAIN refers to the domain in which the machine resides, and is the FQDN minus the HOSTNAME part.

Create /var/qmail/rc:


# This script starts and stops the qmail mail functions.

# Suck in the configuration variables.
if [ -r /etc/defaults/rc.conf ]; then
        . /etc/defaults/rc.conf
elif [ -r /etc/rc.conf ]; then
        . /etc/rc.conf

case "$1" in
        case ${qmail_smtp_enable} in
                # Start the qmail smtp daemon
                /usr/local/bin/tcpserver -H -R -c 255 -x /etc/tcp.smtp.cdb \
                        -u 82 -g 81 0 25 /var/qmail/bin/qmail-smtpd &
                echo -n " qmail-smtp"

        case ${qmail_pop_enable} in
                # Start the qmail pop daemon
                /usr/local/bin/tcpserver -H -R -c 255 0 110 \
                        /var/qmail/bin/qmail-popup HOSTNAME.DOMAIN \
                        /usr/local/bin/checkpassword /var/qmail/bin/qmail-pop3d \
                         Maildir &
                echo -n " qmail-pop"

        case ${qmail_enable} in
                # Start qmail
                exec env - PATH="/var/qmail/bin:$PATH" \
                        qmail-start ./Maildir splogger qmail &
                echo -n " qmail"
        # Stop the smtp daemon
        smtppid=`ps -axw | grep tcpserver | grep smtp | grep -v grep | awk '{ print $1 }'`
        if [ "$smtppid" != "" ]; then
                kill $smtppid
                echo -n " qmail-smtp"

        # Stop the pop daemon
        poppid=`ps -axw | grep tcpserver | grep popup | grep -v grep | awk '{ print $1 }'`
        if [ "$poppid" != "" ]; then
                kill $poppid
                echo -n " qmail-pop"

        # Stop qmail
        qmailpid=`ps -axw | grep qmail-send | grep -v grep | awk '{ print $1 }'`
        if [ "$qmailpid" != "" ]; then
                kill $qmailpid
                echo -n " qmail"
        echo "Usage: `basename $0` {start|stop}" >&2

exit 0

Make the script executable:

chmod 750 /var/qmail/rc

2.9. Set up control files

2.9.1. me

# echo HOSTNAME.DOMAIN > /var/qmail/control/me

2.9.2. rcpthosts

# echo HOSTNAME.DOMAIN > /var/qmail/control/rcpthosts
# echo DOMAIN >> /var/qmail/control/rcpthosts

2.9.3. locals

# echo HOSTNAME.DOMAIN > /var/qmail/control/locals
# echo DOMAIN >> /var/qmail/control/locals

2.9.4. defaulthost

# echo HOSTNAME > /var/qmail/control/defaulthost

2.9.5. defaultdomain

# echo DOMAIN > /var/qmail/control/defaultdomain

2.9.6. plusdomain

# echo DOMAIN > /var/qmail/control/plusdomain

2.10. Redirect root's email

qmail will not send email directly to root. Even if no one else is sending email to root, the system is probably sending its daily checks to root every night, so the barest minimum qmail setup requires an alias for root:

# echo EMAILADDRESS > /var/qmail/alias/.qmail-root

EMAILADDRESS is the real address to which you want root's mail sent. Alias files can contain multiple addresses, but each address must be on a separate line.

3. Post-installation

3.1. Stop sendmail

# killall sendmail
# rm /var/run/

3.2. Start qmail

# /usr/local/etc/rc.d/ start

3.3. Check qmail and tcpserver are running

# ps -ax | grep tcpserver
# ps -ax | grep qmail

3.4. Other issues

3.4.1. Creating local aliases

qmail does not natively support the /etc/mail/aliases file, though it can be made to do so with an add-on package. Read /var/qmail/doc/INSTALL.alias for details on how qmail handles aliases. As a minimum, set up aliases for root (done above), postmaster and mailer-daemon.

A. Contacting the Author

The author of this document is Aaron Hill. Feel free to send details of any errors in this document by email.

B. Credits

Paul Hoadley converted this document from HTML to DocBook XML and back again.