projects.standblue.net -> qmail installation notes

Notes on installing qmail

These instructions were written using Red Hat Linux and assume that the user is logged in as root. Read Life with qmail to get a understanding of how qmail works. I do not like the directories that LWQ uses (/var/qmail/supervise/qmail-send, etc) so this page uses a more generic type of configuration.

This guide is designed so that most of the commands and blocks of commands can be directly copied and pasted into terminal windows, but you may need to remove any leading whitespace on a line.

Installed Software

Software that will be installed:

Removing sendmail

First things first, find and remove the sendmail package that was most likely installed with your operating system. To find the package names on Red Hat Linux or other RPM based distributions:

  shell# rpm -qa|grep sendmail
  sendmail-doc-8.11.0-8
  sendmail-cf-8.11.0-8
  sendmail-8.11.0-8

To quickly remove all these packages:

  shell# for i in `rpm -qa|grep sendmail`; do rpm -e --nodeps $i; done

Downloading, Compiling and Installing

With sendmail gone we can begin the qmail installation. Create the /package and /usr/local/src/email directories:

  mkdir /package
  mkdir /usr/local/src/email

Next, download all the necessary files by copying the following and pasting it into your terminal:

  cd /usr/local/src/email
  wget http://cr.yp.to/software/qmail-1.03.tar.gz
  wget http://cr.yp.to/ucspi-tcp/ucspi-tcp-0.88.tar.gz
  wget http://cr.yp.to/cdb/cdb-0.75.tar.gz
  wget http://cr.yp.to/software/mess822-0.58.tar.gz
  wget http://cr.yp.to/checkpwd/checkpassword-0.90.tar.gz
  cd /package
  wget http://cr.yp.to/daemontools/daemontools-0.76.tar.gz

Now all the necessary packages are downloaded. The first thing to be installed is daemontools.

  cd /package
  tar xzf daemontools-0.76.tar.gz
  cd admin/daemontools-0.76/
  package/install

On Linux systems svscanboot will start immediately, BSD systems will need to be restarted.

Now switch back to the /usr/local/src/email directory to begin installing the other utility packages:

  cd /usr/local/src/email
  tar xzf mess822-0.58.tar.gz
  (cd mess822-0.58; make setup check)
  tar xzf cdb-0.75.tar.gz
  (cd cdb-0.75; make setup check)
  tar xzf ucspi-tcp-0.88.tar.gz
  (cd ucspi-tcp-0.88; make setup check)
  tar xzf checkpassword-0.90.tar.gz
  (cd checkpassword-0.90; make setup check)

The next step is to install qmail. Unpack the tarball and cd to the src directory:

  tar xzf qmail-1.03.tar.gz
  cd qmail-1.03

Two steps need to be completed before qmail can be compiled. First, the /var/qmail directory needs to be created, do this now:

  mkdir /var/qmail

Second, the qmail users and groups need to be added to the system. The following is what I use on Red Hat Linux systems:

  groupadd nofiles
  useradd -M -g nofiles -d /var/qmail/alias alias
  useradd -M -g nofiles -d /var/qmail qmaild
  useradd -M -g nofiles -d /var/qmail qmaill
  useradd -M -g nofiles -d /var/qmail qmailp
  groupadd qmail
  useradd -M -g qmail -d /var/qmail qmailq
  useradd -M -g qmail -d /var/qmail qmailr
  useradd -M -g qmail -d /var/qmail qmails

The -M flag is added to prevent the useradd program from copying the contents of the /etc/skel directory to the users home directory.

Finally, compile and install qmail:

  make setup check

Initial Configuration

The next step is to create the default configuration for qmail. If your machine has a valid name in DNS then run the ./config command from the qmail source directory:

  ./config

If DNS is not configured for the machine then use the ./config-fast command and pass the desired hostname as a parameter (replace host.example.com with your actual hostname):

  ./config-fast host.example.com

Create the root, postmaster and MAILER-DAEMON aliases to your account:

  echo youracct > /var/qmail/alias/.qmail-root 
  echo youracct > /var/qmail/alias/.qmail-postmaster
  echo youracct > /var/qmail/alias/.qmail-mailer-daemon

Now create symbolic links from /var/qmail/bin/sendmail in /usr/sbin and /usr/lib for compatibility with existing applications:

  ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail
  ln -s /var/qmail/bin/sendmail /usr/lib/sendmail

Creating and Starting the Services

Service Directories

Create the master service directory and any subdirectories for services that you may wish to run (smtpd, pop3d, etc):

  mkdir /var/services
  mkdir -p /var/services/qmail/log
  mkdir -p /var/services/smtpd/log
  mkdir -p /var/services/pop3d/log

Also make any log directories for use with multilog from daemontools:

  mkdir /var/log/qmail
  mkdir /var/log/smtpd
  mkdir /var/log/pop3d
  chown qmaill:nofiles /var/log/qmail /var/log/smtpd /var/log/pop3d

The qmail service

Before the qmail service is created a few decisions must be made. The biggest thing that needs to be decided is which type of mailstore is to be used. In general, the Maildir format is more reliable and favored among qmail administrators. Postfix, Exim and Courier all support the Maildir format as well. Other options are the traditional /var/spool/mail/$USER style (which is mbox format) and the ./Mailbox style (also mbox). These instructions use the Maildir format. If you decide to use another format then a different pop3 server will need to be installed, qmail-pop3d only supports Maildir format.

Use the /var/qmail/bin/maildirmake program to create Maildir's for existing users:

  setuidgid someuser /var/qmail/bin/maildirmake ~someuser/Maildir

Then create a Maildir in the /etc/skel directory so that when new users are added to the system their Maildir's are created automatically:

  /var/qmail/bin/maildirmake /etc/skel/Maildir

Switch to the qmail service directory and open up a file named "run" with your favorite text editor:

  cd /var/services/qmail
  vi run

Paste the following code into the editor (remove any leading spaces):

  #!/bin/sh
  exec env - PATH="/var/qmail/bin:$PATH" qmail-start ./Maildir/

Save the file and exit the editor. Change the permissions on the file to 755 (-rwxr-xr-x):

  chmod 755 run

Now open up the ./log/run file with your editor and add the following (once again, remove all leading whitespace):

  #!/bin/sh
  exec setuidgid qmaill multilog t s200000 n20 /var/log/qmail

Save, exit and change the permissions on the file:

  chmod 755 ./log/run

The qmail service is ready to run. To start it, simply create a symbolic link in the /service directory:

  ln -s /var/services/qmail /service/qmail

Within 5 seconds svscan will notice the new link and start the service. It can be controlled with the svc command from the daemontools package.

The smtpd service

If you wish to accept mail from the outside world via SMTP then a smtpd service needs to be configured. Switch to the /var/services/smtpd directory, open up a file named "run" in your text editor and add the following:

  #!/bin/sh

  PATH="/var/qmail/bin:$PATH"
  export PATH

  QUID=`id -u qmaild`
  QGID=`id -g qmaild`
  SMTPLIMIT=`head -1 /var/qmail/control/concurrencyincoming`
  LOCAL=`head -1 /var/qmail/control/me`

  if [ -z "$QUID" ]; then echo "QUID is empty in /var/services/smtpd/run"; exit 1; fi
  if [ -z "$QGID" ]; then echo "QGID is empty in /var/services/smtpd/run"; exit 1; fi
  if [ -z "$SMTPLIMIT" ]; then echo "SMTPLIMIT is empty in /var/services/smtpd/run"; exit 1; fi
  if [ -z "$LOCAL" ]; then echo "LOCAL is empty in /var/services/smtpd/run"; exit 1; fi
  
  exec /usr/local/bin/softlimit -m 2000000 \
    /usr/local/bin/tcpserver -vR -l "$LOCAL" -c "$SMTPLIMIT" \
      -x /service/smtpd/tcp.cdb -u "$QUID" -g "$QGID" 0 smtp \
        /var/qmail/bin/qmail-smtpd 2>&1

Save, exit and change the permissions on the file to 755.

Now open up the ./log/run file with your editor and add the following:

  #!/bin/sh
  exec setuidgid qmaill multilog t s200000 n20 /var/log/smtpd

Save, exit and change the permissions on the file to 755.

You will need to decide the maximum number of concurrent incoming smtp connections you want to allow. A safe default for this is 20. Life with qmail established the practice of using the nonstandard /var/qmail/control/concurrencyincoming file, and I like it, so I will continue to use it here:

  echo 20 > /var/qmail/control/concurrencyincoming

Next you should decide what IP ranges or networks you wish to allow to relay through the mail server. Many small networks will have 192.168.* addresses that should be able to send mail through the qmail server. These addresses or networks will need to be added to the tcprules database so that tcpserver will know to tell qmail-smtpd to accept mail remote domains. Switch to the /var/services/smtpd directory, open a file named "tcp" in your text editor and add something like this:

  127.0.0.1:allow,RELAYCLIENT=""
  192.168.1.:allow,RELAYCLIENT=""

This allows 127.0.0.1 and all the computers with addresses that start with 192.168.1 to relay through the qmail server. Before this is useful it needs to be compiled into a cdb database so that tcpserver can understand it:

  tcprules /service/smtpd/tcp.cdb /service/smtpd/tcp.tmp < /service/smtpd/tcp

The smtpd service is now ready to be started. Once again, simply make a symbolic link in the /service directory and within 5 seconds the service should start:

  ln -s /var/services/smtpd /service/smtpd

The pop3d service

In order to allow remote users to retrieve their local mail with MUA's such as Mozilla Mail or Outlook a pop3d service will need to be configured. I do not recommend allowing system accounts to use pop3 because passwords are sent clear text over the network. The prefered way to store mail is with a tool such as vpopmail or VMailMgr. There are cases where offering pop3 service makes sense, so I will describe the process below.

Switch to the /var/services/pop3d directory, open a file named "run" in your text editor and add the following:

  #!/bin/sh

  LOCAL=`head -1 /var/qmail/control/me`

  exec /usr/local/bin/softlimit -m 2000000 \
    /usr/local/bin/tcpserver -vHR -l "$LOCAL" 0 pop3 \
      /var/qmail/bin/qmail-popup "$LOCAL" /bin/checkpassword \
        /var/qmail/bin/qmail-pop3d Maildir 2>&1

Save, exit and change the permissions on the file to 755.

Now open up the ./log/run file with your editor and add the following:

  #!/bin/sh
  exec setuidgid qmaill multilog t s200000 n20 /var/log/pop3d

Save, exit and change the permissions on the file to 755.

The pop3d service is now ready to be started. Link it into the /service directory and wait for it to start:

  ln -s /var/services/pop3d /service/pop3d

There are many other checkpassword compatible interfaces that will work with qmail-popup. See qmail.org's checkpassword section to see if one better suits your needs.

The resetproctitles service

This is not qmail specific, but if you are reading instructions on how to set up qmail then you most likely do not know much about daemontools either. There is a program that is installed with daemontools called readproctitles. The purpose of readproctitles is to report errors in the output of the ps command. A sample of the output of `ps ax|grep readproc`:

  861 ?        S      0:00 readproctitle service errors: .......................

When everything is going smooth there will be no errors here, only a long line of dots. The program is great for debugging the "run" scripts listed above, but there is a problem. The error messages will stay there until something else bumps them out of the way. This is annoying because you cant tell if you are still experiencing the problem or if the errors are from long ago. To remedy this I always create a service called "resetproctitles" that will reset the readproctitle error string to all dots. Here are the steps:

  mkdir /var/services/resetproctitles
  cd /var/services/resetproctitles
  touch down
  echo '#!/bin/sh' > run
  echo echo -n $(for i in `seq 1 500`; do echo -n .; done) >> run
  chmod 755 run
  ln -s /var/services/resetproctitles /service/resetproctitles

FreeBSD users should use the `jot 500 1` command instead of `seq 1 500`. When you want to clear the readproctitle message just issue the following:

  svc -o /service/resetproctitles

That is all.