Installing qmail Step by Step

Taking Some Sensible Advice

Before installing qmail there are a few things you need to think about, especially if this is your first qmail installation:

• If possible, install qmail on a "practice" system. This will give you a chance to make mistakes without losing important mail or interrupting mail service to your users.

• If you don't have a spare system, and your system is already handling mail using Sendmail, Smail, or some other MTA, you can install and test most pieces of qmail without interfering with the existing service.

• When migrating a system from some other MTA to qmail-even if you've got some qmail experience-it's a good idea to formulate a plan. Some guidelines are contained in Chapter 7, "Configuring qmail: Advanced Options."

Verifying the Build Environment

The next thing you need to do is make sure you have the necessary tools to compile a program. How you determine this depends on what flavor of Unix you're using. The easiest way to tell, although it's not guaranteed , is to try it.

At a command-line prompt, type cc and press the Enter key:

$ cc cc: No input files specified $

If you get a similar response, you have a C compiler in your path and you can skip to the next section, "Locating the Source."

If you get an error like this:

$

cc

sh: cc: command not found $

This doesn't necessarily mean you don't have one installed. You might, but maybe it isn't in your path. Of course, it could also mean that you don't have one. Try using these:

• /usr/bin/cc

• /usr/bin/gcc

• /usr/local/bin/cc

• /usr/local/bin/cc

• /usr/ccs/bin/cc

If none of these works, you'll have to try something a little more platform specific. For example, if you're using Red Hat Linux:

rpm -qa  grep gcc or rpm -qa  grep egcs

If you can't find a compiler installed, you'll have to locate one and install it. Contact your operating system vendor or other operating system support channel.

Locating the Source

OK, so you've got a system meeting the requirements ready for installing qmail. The first step is to download the source code for qmail and any other add-ons. You'll need qmail, ucspi-tcp , and daemontools :

• qmail ( ftp://cr.yp.to/software/qmail-1.03.tar.gz )

• ucspi-tcp ( ftp://cr.yp.to/ucspi-tcp/ucspi-tcp-0.88.tar.gz )

• daemontools ( ftp://cr.yp.to/daemontools/daemontools-0.70.tar.gz )

Retrieve these files using your Web browser or FTP client.

Building the Source

To use the pizza analogy again, the recipe has now been selected. The ingredients and equipment have been located. It's time to put on your apron, roll up your sleeves, and start cooking.

Unpacking the Distribution

At this point, you've verified that you have a working C compiler and you have copies of the source-code tarballs for qmail, daemontools, and ucspi-tcp. Copy or move the tarballs to the directory in which you want to do the build. /usr/local/src is a good choice.

At this time you probably want to become the superuser, if you are not already:

$

su -

Password:


rootpassword



(won't echo)

#

Copy or move the tarballs to the directory in which you want to do the build:

#

mkdir -p /usr/local/src

#

mv *.tar.gz /usr/local/sr

c #

You've got all three packages in /usr/local/src , so now you can unpack them.

Set your umask so the files and directories you create are publicly accessible by default:

#

umask 022

#

Now uncompress and extract the source files:

#

cd /usr/local/src

#

gunzip qmail-1.03.tar.gz

#

tar xvf qmail-1.03.tar

qmail-1.03/ qmail-1.03/BLURB qmail-1.03/BLURB2

...lots of output followed by something like:

qmail-1.03/tcp-environ.5 qmail-1.03/constmap.h qmail-1.03/constmap.c #

gunzip ucspi-tcp-0.88.tar.gz

#

tar xvf ucspi-tcp-0.88.tar

ucspi-tcp-0.88 ucspi-tcp-0.88/README ucspi-tcp-0.88/TODO

...lots of output followed by something like:

ucspi-tcp-0.88/warn-auto.sh ucspi-tcp-0.88/warn-shsgr ucspi-tcp-0.88/x86cpuid.c #

gunzip daemontools-0.70.tar.gz

#

tar xvf daemontools-0.70.tar

daemontools-0.70 daemontools-0.70/README daemontools-0.70/TODO

...lots of output followed by something like:

daemontools-0.70/warn-auto.sh daemontools-0.70/warn-shsgr daemontools-0.70/x86cpuid.c #

rm *.tar


# optional unless space is very tight

#

The gunzip commands are used to expand the compressed tarballs into their full size and original format. The tar commands extract the tarballs into the original source-code build directories. Once the tarballs are unpacked, they're no longer needed, so we delete them.

There should now be subdirectories called qmail-1.03 , ucspi-tcp-0.88 , and daemontools-0.70 .

Compile-Time Configuration Settings

Most of qmail's configuration settings are run-time selectable. That means that they can be specified at the time the associated program is run. Some, however, are compile-time selectable. To change them, you have to first change the setting, then re-compile and re-install the binaries. Fortunately, the compile-time settings rarely need to be changed after the initial installation. The defaults are reasonable for all but the most extreme installations.

The compile-time configuration settings in qmail are stored in files with names starting with conf- in the build directory. Most of these settings consist of a single value, which must appear on the first line of the file-no blank lines or comments can appear before the setting. Those that require multiple settings, such as conf-users and conf-groups , contain one setting per line, again at the top of the file. Table 2-2 lists the compile-time settings, and Table 2-3 lists the qmail users configured in conf-users . Run-time configuration is covered in Chapter 3, "Configuring qmail: The Basics."

The only compile-time settings you're likely to change are conf-cc and conf-ld , which depend on the names and locations of system utilities. Don't worry about changing these yet.

Creating Directories

Because qmail's installation program creates the subdirectories as they're needed, you only need to create the master qmail directory:

#

mkdir /var/qmail

#

If you want some or all of the qmail files to reside somewhere other than /var , this can be accomplished by creating symbolic links under /var/qmail pointing to the other locations.

For example, say you want the man pages installed under /usr/man, the control files installed under /etc/qmail/control , and the binaries installed under /usr/sbin . This could be achieved by doing this:

#

mkdir /var/qmail

#

ln -s /usr/man /var/qmail/man

#

mkdir /etc/qmail

#

ln -s /etc/qmail /var/qmail/control

#

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

#

This will still allow access to these pieces via the qmail standard /var/qmail/man , /var/qmail/control , and /var/qmail/bin paths.

Creating Users and Groups

The use of multiple system accounts is critical to qmail's security model. Processes running under one account ( compartment ) are prevented-using the normal Unix access control mechanisms-from modifying files belonging to another account. Many versions of Unix provide utilities like adduser , useradd , or mkuser that make this easy. Alternatively, you can manually edit the password and group files and add them yourself.

Linux/Solaris

groupadd nofiles useradd -g nofiles -d /var/qmail/alias alias -s /nonexistent useradd -g nofiles -d /var/qmail qmaild -s /nonexistent useradd -g nofiles -d /var/qmail qmaill -s /nonexistent useradd -g nofiles -d /var/qmail qmailp -s /nonexistent

groupadd

qmail useradd -g qmail -d /var/qmail qmailq -s /nonexistent useradd -g qmail -d /var/qmail qmailr -s /nonexistent useradd -g qmail -d /var/qmail qmails -s /nonexistent

FreeBSD

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

AIX

mkgroup -A nofiles mkuser pgrp=nofiles home=/var/qmail/alias shell=/bin/true alias mkuser pgrp=nofiles home=/var/qmail shell=/bin/true qmaild mkuser pgrp=nofiles home=/var/qmail shell=/bin/true qmaill mkuser pgrp=nofiles home=/var/qmail shell=/bin/true qmailp mkgroup -A qmail mkuser pgrp=qmail home=/var/qmail shell=/bin/true qmailq mkuser pgrp=qmail home=/var/qmail shell=/bin/true qmailr mkuser pgrp=qmail home=/var/qmail shell=/bin/true qmails

Other Operating Systems

Start by using your favorite editor and editing /etc/group . You need to add the following two lines to the end of the file:

qmail:*:2107: nofiles:*:2108:

Next, using vipw (most systems have it; if not, you'll need to use your editor again but this time on /etc/passwd ), add these lines to the end of the file:

alias:*:7790:2108::/var/qmail/alias:/bin/true qmaild:*:7791:2108::/var/qmail:/bin/true qmaill:*:7792:2108::/var/qmail:/bin/true qmailp:*:7793:2108::/var/qmail:/bin/true qmailq:*:7794:2107::/var/qmail:/bin/true qmailr:*:7795:2107::/var/qmail:/bin/true qmails:*:7796:2107::/var/qmail:/bin/true

Installing qmail

You're now ready to start building qmail.

In the "Verifying the Build Environment" section, you located your C compiler. If it's not called cc , or the directory it resides in isn't in your PATH environment variable, you'll need to edit the conf-cc and conf-ld build configuration files. Say your compiler is gcc , and it's in /opt/gnu/bin , which is not in your PATH . Simply edit conf-cc and conf-ld and replace cc with /opt/gnu/bin/gcc .

Now type the following:

#

cd /usr/local/src/qmail-1.03

#

make setup check

The make command will use the file called Makefile to determine which commands must be executed to compile and install the qmail programs, and it will execute those commands. Each command will be displayed as it is executed, as will its output. Because building and installing qmail requires executing hundreds of commands, this will result in lots of output to the screen, if everything goes right. If the last few lines of output look like the following, the build and installation were successful:

nroff -man addresses.5 > addresses.0 nroff -man envelopes.5 > envelopes.0 nroff -man forgeries.7 > forgeries.0 ./install ./instcheck #

At this point, the qmail programs have been built and installed in /var/qmail/bin , an empty queue has been set up under /var/qmail/queue , and the documentation has been installed in /var/qmail/doc and /var/qmail/man .

The next step is to create the basic configuration files under /var/qmail/control . Executing the config script does this. For example, on a host named mash in the domain example.com :

#

./config

Your hostname is mash. Your host's fully qualified

name

in DNS is mash.example.com. Putting mash.example.com into control/me. . . Putting mash.example.com into control/defaultdomain. . . Putting mash.example.com into control/plusdomain. . . Checking local IP addresses: 127.0.0.1: Adding localhost to control/locals. . . 192.168.1.8: Adding mash.example.com to control/locals. . . If there are any other domain names that point to you, you will have to add them to /var/qmail/control/locals. You don't have to worry about aliases, i.e., domains with CNAME records. Copying /var/qmail/control/locals to /var/qmail/control/rcpthosts. . . Now qmail will

refuse

to accept SMTP messages except to those hosts. Make sure to change rcpthosts if you add

hosts

to locals or virtualdomains! #

If config can't find your hostname in DNS- not /etc/hosts -you can instead run the config-fast script:

#

./config-fast

the.full.hostname

For example, if your domain is example.com and the host name of your computer is dolphin , the command would be:

#

./config-fast dolphin.example.com

Your fully qualified host name is dolphin.example.com. Putting dolphin.example.com into control/me. . . Putting example.com into control/defaultdomain. . . Putting example.com into control/plusdomain. . . Putting dolphin.example.com into control/locals. . . Putting dolphin.example.com into control/rcpthosts. . . Now qmail will refuse to accept SMTP messages except to dolphin.example.com. Make sure to change rcpthosts if you add hosts to locals or virtualdomains! #

qmail is now installed and partially configured, but before you can run it you need to install the ucspi-tcp and daemontools helper packages and finish configuring qmail.

Installing ucspi-tcp

Earlier, you unpacked the qmail, ucpsi-tcp, and daemontools tarballs into /usr/local/src . Now change to the ucpsi-tcp build directory:

#

cd /usr/local/src/ucspi-tcp-0.88

#

In the previous section, if you modified conf-cc and conf-ld , you'll need to make the same changes in this directory.

Now build the binaries by executing this:

#

make

Again, the make command will produce quite a bit of output. The last few lines should look like this:

./auto-str auto_home 'head -1 conf-home' > auto_home.c ./compile auto_home.c ./load install hier.o auto_home.o unix.a byte.a ./compile instcheck.c ./load instcheck hier.o auto_home.o unix.a byte.a #

To install the programs under /usr/local/bin , do this:

#

make setup check

./install ./instcheck #

That's it. ucspi-tcp is installed.

Installing daemontools

Change to the daemontools build directory:

#

cd /usr/local/src/daemontools-0.70

#

Once again, if you modified conf-cc and conf-ld during the qmail and ucspitcp builds, you'll need to make the same changes in this directory.

Then build the binaries by executing:

#

make

The last few lines of output from this command should look like:

./auto-str auto_home 'head -1 conf-home' > auto_home.c ./compile auto_home.c ./load install hier.o auto_home.o unix.a byte.a ./compile instcheck.c ./load instcheck hier.o auto_home.o unix.a byte.a #

To install the programs under /usr/local/bin , do this:

#

make setup check

./install ./instcheck #

Now create the /service directory:

#

mkdir /service

#

svscan will scan the /service directory. Each subdirectory, or symbolic link to a directory, will be considered a service, and svscan will fork a copy of supervise to manage the service. Further in the installation we'll create symbolic links in /service for the qmail service.

Next, set up svscan to run on the /service directory each time the system is booted . If your system has an /etc/inittab (Linux or a System V, Release 4 derivative), add the following single line (with no line breaks) to the end of the file:

SV:123456:respawn:env - PATH=/usr/local/bin:/usr/sbin:/usr/bin:/bin svscan /service </dev/null >/dev/console 2>/dev/console

Then tell init to reread /etc/inittab by doing this:

#

kill -HUP 1

#

On BSD-based systems that don't have an /etc/inittab , put the following in /etc/rc.local , creating it if necessary, and reboot the system:

env - PATH=/usr/local/bin:/usr/sbin:/usr/bin:/bin csh -cf 'svscan /service &'

Use ps to verify that svscan is running:

#

ps -ef  grep svscan

root 805 1 0 Apr28 ? 00:00:00 svscan /service root 15939 8547 0 07:47 pts/3 00:00:00 grep svscan #

or

#

ps -waux  grep svscan

root 805 0.0 0.1 1368 372 ? S Apr28 0:00 svscan /service root 15941 0.0 0.2 1624 616 pts/3 S 07:48 0:00 grep svscan #

Finally, run a few tests to make sure the tools work right. First run the automatic test script:

#

cd /usr/local/src/daemontools-0.70

#

./rts > rts.out

#

cmp rts.out rts.exp

#

The second line runs the script and saves the output in rts.out . The third line compares the output with expected output. If all the tests succeeded, the cmp command will generate no output. However, some System V Release 4 derivatives will fail one of the lock tests. This is normal. Now we'll check some of the time-stamp tools:

#

date ./tai64n ./tai64nlocal

2001-03-16 21:46:17.890891500 Fri Mar 16 21:46:17 EST 2001 #

date  sh -c './multilog t e 2>&1' ./tai64nlocal

2001-03-16 21:46:18.063667500 Fri Mar 16 21:46:18 EST 2001 #

The date and time at the beginning of both lines of output should be within a second of the date and time at the end of the line.

Configuring qmail

All of the necessary software has now been compiled and installed. The next step is to complete the initial configuration of qmail. Chapter 3, "Configuring qmail: The Basics," covers configuration in more detail, and Chapter 7, "Configuring qmail: Advanced Options," shows you how to tailor your qmail installation to meet your needs.

qmail Boot Script

The /var/qmail/rc script is run to start the long-running qmail daemons: qmail-send , qmail-clean , qmail-rspawn , and qmail-lspawn . It doesn't deal with short-lived daemons such as qmail-smtpd or qmail-pop3d -those will be handled separately.

In addition to starting the daemons, the boot script is important because it also configures two things: the default delivery instructions and the disposition of log messages from qmail-send .

The default delivery instructions tell qmail where and how to deliver a user's mail if they don't have a .qmail file that gives specific instructions. Normally, the default delivery instructions are specified on the qmail-start command line, but because these instructions can become rather involved in some installations, we'll put them in a new, nonstandard control file called defaultdelivery .

In a simple qmail installation, the output of qmail-start would be directed either to Syslog via the splogger tool, or to multilog , daemontools' logging tool. We're going to go a step further and set qmail up as a managed service with an associated logging service, so we'll just let qmail-start log to standard output.

The /var/qmail/boot directory contains example qmail boot scripts for different configurations: /var/spool/mail vs. $HOME/Mailbox , using Procmail or dot-forward , and various combinations of these. Feel free to examine these, but for our installation we'll use the script in Listing 2-1.

Listing 2-1: The /var/qmail/rc script

#!/bin/sh # Using

stdout

for logging # Using control/defaultdelivery from

qmail-local

to deliver messages by default DELIVERY='cat /var/qmail/control/defaultdelivery' if [ -z "$DELIVERY" ] ; then echo "/var/qmail/control/defaultdelivery is empty or does not exist" 1>&2 exit 1 fi

exec

env - PATH="/var/qmail/bin:$PATH" qmail-start "$DELIVERY"

Use your editor to create the previous /var/qmail/rc , then make the rc file executable:

#

chmod 755 /var/qmail/rc

#

At this point you need to decide the default delivery mode for messages that aren't delivered by a .qmail file. Table 2-4 outlines some common choices.

See "Choosing a Mailbox Format and Location" for more information about these choices.

To select your default mailbox type, just enter the defaultdelivery value from the table into /var/qmail/control/defaultdelivery . For example, to select the standard qmail Mailbox delivery, do this:

#

echo ./Mailbox > /var/qmail/control/defaultdelivery

#

System Startup Files

The qmail system startup files are used to start qmail automatically when the system is booted, shut it down cleanly when the system is halted, and perform maintenance, control, and monitoring tasks while the system is running.

The qmailctl Script

If you were to manually execute the /var/qmail/rc script, qmail would be partially started. But we want qmail started up automatically every time the system is booted, and we want it shut down cleanly when the system is halted.

This is accomplished by creating a control script like the one in Listing 2-2.

Listing 2-2: The qmailctl script

#!/bin/sh # For Red Hat chkconfig # chkconfig: - 30 80 # description: the qmail MTA PATH=/var/qmail/bin:/usr/local/bin:/usr/bin:/bin export PATH LOG=/var/log/qmailctl echo 'date' 'tty' $* >$LOG case "$1" in start) echo "Starting qmail" if svok /service/qmail-send ; then svc -u /service/qmail-send 2>&1  tee -a $LOG else echo qmail-send service not running fi if svok /service/qmail-smtpd ; then svc -u /service/qmail-smtpd 2>&1  tee -a $LOG else echo qmail-smtpd service not running fi if [ -d /var/lock/subsys ]; then touch /var/lock/subsys/qmail fi ;; stop) echo "Stopping qmail" echo "qmail-smtpd" svc -d /service/qmail-smtpd 2>&1  tee -a $LOG echo "qmail-send" svc -d /service/qmail-send 2>&1  tee -a $LOG if [ -f /var/lock/subsys/qmail ]; then rm /var/lock/subsys/qmail fi echo "done" ;; stat) svstat /service/qmail-send svstat /service/qmail-send/log svstat /service/qmail-smtpd svstat /service/qmail-smtpd/log qmail-qstat ;; flushdoqueuealrm) echo "Sending ALRM signal to qmail-send." svc -a /service/qmail-send 2>&1  tee -a $LOG ;; queue) qmail-qstat qmail-qread ;; reloadhup) echo "Sending HUP signal to qmail-send." svc -h /service/qmail-send 2>&1  tee -a $LOG ;; pause) echo "Pausing qmail-send" svc -p /service/qmail-send 2>&1  tee -a $LOG echo "Pausing qmail-smtpd" svc -p /service/qmail-smtpd 2>&1  tee -a $LOG ;; cont) echo "Continuing qmail-send" svc -c /service/qmail-send 2>&1  tee -a $LOG echo "Continuing qmail-smtpd" svc -c /service/qmail-smtpd 2>&1  tee -a $LOG ;; restart) echo "Restarting qmail" echo "Stopping qmail-smtpd." svc -d /service/qmail-smtpd 2>&1  tee -a $LOG echo "Sending qmail-send SIGTERM and restarting." svc -t /service/qmail-send 2>&1  tee -a $LOG echo " Restarting qmail-smtpd." svc -u /service/qmail-smtpd 2>&1  tee -a $LOG echo "done" ;; cdb) tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp 2>&1  tee -a $LOG chmod 644 /etc/tcp.smtp* echo "Reloaded /etc/tcp.smtp." ;; help) cat <<HELP stop -- stops mail service (smtp connections

refused

, nothing goes out) start -- starts mail service (smtp connection accepted, mail can go out) pause -- temporarily stops mail service (connections accepted, nothing

leaves

) cont -- continues

paused

mail service stat -- displays status of mail service cdb -- rebuild the tcpserver cdb file for smtp restart -- stops and restarts smtp, sends qmail-send a

TERM

& restarts it flush -- sends qmail-send ALRM, scheduling queued messages for delivery reload -- sends qmail-send HUP, rereading locals and virtualdomains queue -- shows status of queue alrm -- same as doqueue hup -- same as reload doqueue -- same as flush HELP ;; *) echo "Usage: $0 {startstoprestartflushreloadstatpausecontcdbqueue help}" exit 1 ;; esac exit 0

Create the script using your editor or by copying it from the Web site, then install it into the /var/qmail/bin directory with the name qmailctl .

Make the startup script executable and link it to a directory in your PATH :

#

chmod 755 /var/qmail/bin/qmailctl

#

ln -s /var/qmail/bin/qmailctl /usr/local/sbin

#

Now we need to arrange for /var/qmail/bin/qmailctl start to be executed each time the system boots.

BSD-style rc.local

On BSD-based systems, this is done by adding the following to /etc/rc.local :

if [ -x /var/qmail/bin/qmailctl ]; then /var/qmail/bin/qmailctl start fi

System V-style init.d

On System V-based installations, this can be accomplished by symbolically linking the script to the appropriate directories. First is the init.d directory, which should be in one of the following locations:

• /etc/init.d

• /sbin/init.d

• /etc/rc.d/init.d

You'll also need to link the script into a couple of rc directories. These directories are named like rc N .d , where N is the system runlevel to which they apply. There are many variations in the startup directory tree for different operating systems, so if you can't find the rc directories, consult your system documentation. They will probably be in one of the following locations:

• /etc

• /sbin

• /etc/rc.d

To create the links, execute the following commands, replacing INITDIR and RCDIR with the location of your system's init.d and rc directories:

#

ln -s /var/qmail/bin/qmailctl

INITDIR

/qmail

#

ln -s ../init.d/qmail

RCDIR

/rc0.d/K30qmail

#

ln -s ../init.d/qmail

RCDIR

/rc1.d/K30qmail

#

ln -s ../init.d/qmail

RCDIR

/rc2.d/S80qmail

#

ln -s ../init.d/qmail

RCDIR

/rc3.d/S80qmail

#

ln -s ../init.d/qmail

RCDIR

/rc4.d/S80qmail

#

ln -s ../init.d/qmail

RCDIR

/rc5.d/S80qmail

#

ln -s ../init.d/qmail

RCDIR

/rc6.d/K30qmail

Chapter 5, "Managing qmail," covers using the qmailctl script manually.

The qmail Services

A basic qmail installation requires two services: one for the long-lived daemons and one for incoming SMTP connections. Each service will require a run script, which contains the command used by supervise to start the service, and a log/run script, which contains the multilog command used to log the output of the service to a file.

These scripts are stored under /var/qmail/supervise and symbolically linked to /service . This lets you temporarily remove a service (the link in /service ) without removing the scripts.

First, create the supervise directories for the qmail services:

#

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

#

The chmod +t commands set the "sticky" bit on the main service directories, which tells supervise that the services have logging subservices that also need to be run.

Using your editor, create the /var/qmail/supervise/qmail-send/run file:

#!/bin/sh exec /var/qmail/rc

This just runs the /var/qmail/rc script we've already set up.

Now create the /var/qmail/supervise/qmail-send/log/run file:

#!/bin/sh exec /usr/local/bin/setuidgid qmaill /usr/local/bin/multilog t /var/log/qmail

This log script runs setuidgid from daemontools to change to the qmail log user before executing multilog , which will write its output to the /var/log/qmail directory. Now create the /var/qmail/supervise/qmail-smtpd/run file:

#!/bin/sh # next three lines have backquotes ('), not single quotes (') QMAILDUID='id -u qmaild' NOFILESGID='id -g qmaild' MAXSMTPD='head -1 /var/qmail/control/concurrencyincoming' if [ -z "$QMAILDUID" -o -z "$NOFILESGID" -o -z "$MAXSMTPD" ]; then echo QMAILDUID, NOFILESGID, or MAXSMTPD is unset in echo /var/qmail/supervise/qmail-smtpd/run exit 1 fi exec /usr/local/bin/softlimit -m 2000000 \ /usr/local/bin/tcpserver -v -p -x /etc/tcp.smtp.cdb -c "$MAXSMTPD" \ -u "$QMAILDUID" -g "$NOFILESGID" 0 25 /var/qmail/bin/qmail-smtpd 2>&1

This one is a little more complicated. First, it uses the id command to look up the user ID and group ID of the qmail daemon user. Then, it reads a number from a nonstandard qmail control file, concurrencyincoming , which will limit the number of simultaneous incoming SMTP sessions. Next, it checks to be sure that it's gotten values for these settings before it tries to start tcpserver . Finally, it runs softlimit from daemontools to limit the memory used by each session to 2 megabytes and starts tcpserver from ucspi-tcp listening to the SMTP port. When it accepts a connection, tcpserver will verify that the remote host has access to service by checking /etc/tcp.smtp.cdb before starting a qmail-smtpd running under the qmail daemon user UID and GID to handle the connection.

Create the concurrencyincoming control file:

#

echo 20 > /var/qmail/control/concurrencyincoming

#

chmod 644 /var/qmail/control/concurrencyincoming

#

For a small system, a limit around twenty should be adequate. A large, busy server would, of course, require a higher limit. Create the /var/qmail/supervise/qmail-smtpd/log /run file:

#!/bin/sh exec /usr/local/bin/setuidgid qmaill /usr/local/bin/multilog \ t var/log/qmail/smtpd

Again, the logging will be done as the qmail log user, qmail. These logs will go to files in the /var/log/qmail/smtpd directory.

Make the run files executable:

#

chmod 755 /var/qmail/supervise/qmail-send/run

#

chmod 755 /var/qmail/supervise/qmail-send/log/run

#

chmod 755 /var/qmail/supervise/qmail-smtpd/run

#

chmod 755 /var/qmail/supervise/qmail-smtpd/log/run

#

Next, set up the logging directories:

#

mkdir -p /var/log/qmail/smtpd

#

chown -R qmaill /var/log/qmail

#

Finally, link the services into /service :

#

ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service

#

SMTP Access Control

Normally you won't deny access via SMTP to your mail server because you want to be able to accept mail from all systems. (There are exceptions to this rule, though, and they will be covered in Chapter 8, "Controlling Junk Mail.") But in addition to simply granting or denying access to your SMTP service, you can selectively grant special access to connections coming from trusted systems. This is most frequently used to allow certain hosts to use your service as a relay : a system that accepts mail from a remote sender destined for a remote recipient.

Because qmail-smtpd assumes that all connections are from remote systems-even those from the local host-we'll specifically allow the local host to relay:

#

echo '127.:allow,RELAYCLIENT=""' >/etc/tcp.smtp

#

qmailctl cdb

Reloaded /etc/tcp.smtp. #

The first line adds an entry to the SMTP access file, which will cause tcpserver to set the RELAYCLIENT environment variable to the null string before starting qmail-smtpd for connections coming from IP addresses starting with 127, or, the local host. When qmail-smtpd sees that RELAYCLIENT is set, it will allow the client to relay. The second command rebuilds the SMTP access database used by tcpserver .

Create System Aliases

There are three system aliases that should be created on all qmail installations. Table 2-5 lists them.

To create these aliases, decide where you want each of them to go (probably either your local account or a remote address) and create and populate the appropriate .qmail files. For example, say local user erica is the mail administrator and jessica@blossom.example.net is the system administrator. The following commands will create the appropriate aliases:

#

echo \&jessica@blossom.example.net > /var/qmail/alias/.qmail-root

#

echo \&erica > /var/qmail/alias/.qmail-postmaster

#

ln -s .qmail-postmaster /var/qmail/alias/.qmail-mailer-daemon

#

chmod 644 /var/qmail/alias/.qmail-root /var/qmail/alias/.qmail-postmaster

#

Chapter 3, "Configuring qmail: The Basics," covers aliases in detail.

Stopping and Disabling the Installed Mailer

qmail is now fully installed and configured. There's just one more thing we need to do before we start it: turn off any currently running MTA. Although it's possible to simultaneously run both qmail and your existing MTA, which is probably Sendmail, it's not recommended unless you're experienced .

If your existing MTA is Sendmail, and you're using a System V variant, you should be able to stop it by running its init.d script with the stop argument. For example, one of these should work:

• /etc/init.d/sendmail stop

• /sbin/init.d/sendmail stop

• /etc/rc.d/init.d/sendmail stop

If you can't find an init.d/sendmail script, or you're using a BSD variant, you can locate Sendmail's PID using ps - ef grep sendmail or ps waux grep sendmail and stop it using

#

kill

process-ID-of-sendmail


#

where process-ID-of-sendmail is the process ID (PID) of Sendmail, as displayed by the ps command.

If your MTA isn't Sendmail, check your documentation for the correct shutdown procedure.

You should also consider removing the old MTA completely from your system. At least disable the init.d script or comment the startup command out of /etc/rc.local so it won't be restarted again when the system is rebooted.

For Red Hat Linux, for example, removing Sendmail can be accomplished by

#

rpm -e --nodeps sendmail

Because Sendmail was the de facto Unix MTA for years , many scripts and utilities run it directly to send mail messages. For this reason, qmail and other Unix MTAs provide a sendmail replacement that emulates Sendmail's behavior for injecting messages. qmail's sendmail resides in /var/qmail/bin/sendmail , so we'll symbolically link it to the traditional location of Sendmail's sendmail :

#

mv /usr/lib/sendmail /usr/lib/sendmail.old


#


ignore errors

#

mv /usr/sbin/sendmail /usr/sbin/sendmail.old


# ignore errors

#

chmod 0 /usr/lib/sendmail.old /usr/sbin/sendmail.old


# ignore errors


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


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

#

Starting qmail

If you stopped qmail after creating the links in /service , you should restart it now:

#

qmailctl start

Starting qmail. #

If anything goes wrong, you can always do this:

#

qmailctl stop

Stopping qmail qmail-smtpd qmail-send done #

This will stop all of the qmail services.

Testing the Installation

Now that qmail is up and running, the first thing you should do is make sure it really is up and running. Make sure the long-lived daemons are running, no errors are being logged, and send a set of test messages.

Checking the daemons

The easiest check is to run this:

qmailctl stat

The output should look something like this:

/service/qmail-send: up (pid 925) 326 seconds /service/qmail-send/log: up (pid 927) 326 seconds /service/qmail-smtpd: up (pid 928) 326 seconds /service/qmail-smtpd/log: up (pid 933) 326 seconds messages in queue: 0 messages in queue but not yet preprocessed: 0

The first four lines report the status of the qmail services. All should be reported "up." The rest is the output of qmail-qstat , which will probably not be interesting at this point.

Using the PIDs reported above, 925 and 928, use ps to verify that those processes are running. For System V derivatives:

#

ps -ef  grep 925

qmails 925 921 0 May02 ? 00:00:00 qmail-send root 937 925 0 May02 ? 00:00:00 qmail-lspawn ./Maildir/ qmailr 938 925 0 May02 ? 00:00:00 qmail-rspawn qmailq 939 925 0 May02 ? 00:00:00 qmail-clean #

For BSD derivatives:

#

ps waux  grep 925

qmails 925 0.0 0.1 1392 408 ? S May02 0:00 qmail-send root 2957 0.0 0.2 1624 616 pts/0 S 06:37 0:00 grep 925 #

Both commands show that process 925 is qmail-send running as the qmail send user. The System V version also shows qmail-send 's children: qmail-lspawn running as root , qmail-rspawn running as the qmail remote user, and qmail-clean running as the qmail queue user. If your ps command didn't show the children, do this:

#

ps waux  grep qmail-send

root 921 0.1 1336 348 ? S May02 0:00 supervise qmail-send qmails 925 0.1 1392 408 ? S May02 0:00 qmail-send root 2959 0.2 1624 616 pts/0 S 06:38 0:00 grep qmail-send #

ps waux  grep qmail-lspawn

root 937 0.1 1348 360 ? S May02 0:00 qmail-lspawn ./Maildir/ root 2961 0.2 1624 616 pts/0 S 06:39 0:00 grep qmail-lspawn #

ps waux  grep qmail-rspawn

qmailr 938 0.1 1348 360 ? S May02 0:00 qmail-rspawn root 2963 0.2 1624 616 pts/0 S 06:39 0:00 grep qmail-rspawn #

ps waux  grep qmail-clean

qmailq 939 0.1 1340 368 ? S May02 0:00 qmail-clean root 2965 0.2 1620 600 pts/0 S 06:39 0:00 grep qmail-clean #

Notice that the qmail-lspawn output shows the defaultdelivery ( ./Maildir/ ) setting.

If you find all of the processes running as the correct user, everything looks good so far.

Checking the Logs

Check the qmail-send logs for either a "status" message or a "cannot start" message-it always prints one or the other:

#

cd /var/log/qma

i

l

#

tai64nlocal < current

2001-03-17 18:02:17.301996500 status: local 1/10 remote 0/20 #

If you simply cat or more the log file, you'll see something like this:

@400000003ab3ed03120019d4 status: local 1/10 remote 0/20

The difference is that the TAI64N timestamp won't be converted to local time because you didn't filter the log through tai64nlocal .

If you see a "status" message, qmail-send is successfully running.

Sending Test Messages

Send a series of test messages to verify that qmail is working correctly.

Local User to Local User

Send yourself a blank message:

echo to: me  /var/qmail/bin/

qmail-inject

Replace me with your personal username-not root . This creates a minimal message and injects it into qmail using qmail-inject . Verify that the message has been delivered to your mailbox. If your defaultdelivery is ./Mailbox and you don't have a .qmail file, try:

more ~me/Mailbox

You should see the test message.

If your defaultdelivery is ./Maildir/ , use

#

ls ~me/Maildir/new

994551015.1521.mash #

If the delivery succeeded, the new directory will not be empty.

The /var/log/qmail/current file should contain a set of entries like this:

new msg 53

info

msg 53: bytes 246 from <me@domain> qp 20345 uid 666 starting delivery 1: msg 53 to local me@domain status: local 1/10 remote 0/20 delivery 1: success: did_1+0+0/ status: local 0/10 remote 0/20 end msg 53

Each line will also have a timestamp that looks something like @400000003b3f1d140961f84c .

We'll look at the logs more closely in Chapter 5, "Managing qmail."

Local User to Nonexistent Local Address

If you're currently logged in as root, switch to your normal account:

#

su - me

$

Replace me with your personal username. Send a blank message to an invalid local address:

echo to: nonexistent  /var/qmail/bin/qmail-inject

Check your mailbox as in the previous step. It should contain a bounce message-a message explaining that the message to nonexistent was undeliverable.

The /var/log/qmail/current file should now contain a set of entries like this:

new msg 53 info msg 53: bytes 246 from <me@domain> qp 20351 uid 666 starting delivery 2: msg 53 to local nonexistent@domain status: local 1/10 remote 0/20 delivery 2: failure: Sorry,_no_mailbox_here_by_that_name._(#5.1.1)/ status: local 0/10 remote 0/20 bounce msg 53 qp 20357 end msg 53 new msg 54 info msg 54: bytes 743 from <> qp 20357 uid 666 starting delivery 3: msg 54 to local me@domain status: local 1/10 remote 0/20 delivery 3: success: did_1+0+0/ status: local 0/10 remote 0/20 end msg 54

This shows the attempted delivery to nonexistent , which failed, followed by the delivery of the bounce message.

Local User to Valid Remote Address

Send an empty message to your account on another system:

echo to: me@example.com  /var/qmail/bin/qmail-inject

Check the logs to make sure the message was sent. You should see something like this:

new msg 53 info msg 53: bytes 246 from <me@domain> qp 20372 uid 666 starting delivery 4: msg 53 to remote me@example.com status: local 0/10 remote 1/20 delivery 4: success: 1.2.3.4_accepted_message./... status: local 0/10 remote 0/20 end msg 53

Log into your remote account and verify that the message was received.

Local User to Local Postmaster

Send a message to postmaster . Any combination of uppercase and lowercase letters should work:

echo to: POSTmaster  /var/qmail/bin/qmail-inject

Look for the message in the mailbox specified in /var/qmail/alias/.qmail-postmaster .

Invalid Local User to Invalid Local User

This will test the double bounce mechanism-bounce messages that are undeliverable are redirected to the postmaster. Send a message with invalid sender and recipient:

$

/var/qmail/bin/qmail-inject -f nonexistent


To: unknownuser


Subject: testing


This is a test. This is only a test.


^D


(hold "Ctrl" key and press "D" to send end-of-file)

$

This will send a message from nonexistent to unknownuser . Check the postmaster's mailbox for the double bounce message.

Group Membership Test

This will test delivery to program and verify that the program runs with the right group membership. First, switch to your normal user account if you're not there already:

su - me

Now create a .qmail file to deliver to a program:

echo "groups > MYGROUPS; exit 0" > $HOME/.qmail-groups

Under Solaris, use /usr/ucb/groups instead of simply groups .

This directs mail to me-groups to the groups command, which appends its output to a file called MYGROUPS .

Send an empty message to me-groups :

/var/qmail/bin/qmail-inject me-groups < /dev/null

Verify that MYGROUPS was created and contains the correct output:

cat MYGROUPS

You should see your normal group ID only.

SMTP Server Test

Using telnet , connect to the SMTP server ( qmail-smtpd ) via the SMTP port (25) and manually enter the SMTP commands to send a message to a local user. In the following example, replace me with your username and domain with your host's full domain name:

$

telnet 127.0.0.1 25

Trying 127.0.0.1. . . Connected to 127.0.0.1. Escape character is '^]'. 220 domain ESMTP

helo dude

250 domain

mail from:<me@domain>

250 ok

rcpt to:<me@domain>

250 ok

data

354 go ahead

Subject: testing


This is a test.

. 250 ok 812345679 qp 12345

quit

221 domain Connection closed by foreign host. $

Verify that the message is in your mailbox.

If you get an error like the following from the telnet command, your SMTP service is not configured properly:

$

telnet 127.0.0.1 25

Trying 127.0.0.1... telnet: Unable to connect to remote host: Connection refused $

See Chapter 6, "Troubleshooting qmail," for information about locating and correcting the problem.

Remote User to Local User

From an account on another system, send a message to me@domain , replacing me with your username and domain with your host's full domain name.

Verify that the message is in your mailbox.

Remote User to Invalid Local User

From an account on another system, send a message to nonexistent@domain , replacing domain with your host's full domain name.

Verify that the remote sender's mailbox received a bounce message.

Mail User Agent (MUA) Test

Using a mail user agent (mutt, pine, and so on) on the system, send a message to a valid local user. Send another to a remote address. Verify that both were delivered successfully.