Installing qmail Step by Step

 < Free Open Study > 



Now we'll go through the process of installing qmail step by step. This section is recommended for first-time qmail installers.

Preparing for the Installation

Before you can install qmail, you should make sure you've got everything you need, including a compatible system, sufficient disk space, the source-code tarballs for qmail and the two support packages, and a working development system.

Checking System Requirements

qmail will install and run on most Unix and Unix-like systems, but there are a few requirements:

  • About 10 megabytes of free space in the build area during the build. After the build, you can free all but 4 megabytes by removing the object files.

  • A complete, functioning C development system including a compiler, system header files, make or gmake, and libraries. The build directions will show you how to tell if you've got the necessary parts.

  • A few megabytes for the binaries, documentation, and configuration files.

  • Sufficient disk space for the queue on an appropriate file system. Small single-user systems only need a couple megabytes. Large servers may need a couple gigabytes.

  • A compatible operating system. Most flavors of Unix are acceptable. See the README file in the source tree for a list of known compatible releases.

  • Access to a DNS resolver is highly recommended. Without one, qmail can only send to remote systems configured in its smtproutes configuration file.

  • Adequate network connectivity. qmail was designed for well-connected systems, so you probably don't want to try to use it for a mailing list server on a 28.8k dial-up line. The serialmail package was designed to make qmail more compatible with poorly connected systems. See the serialmail section in Appendix B, "Related Packages," for more information.

  • The gunzip utility from the gzip package (http://www.gnu.org/directory/gzip.html).

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.

Note 

If any of these links fail, it's probably because the package has been updated. In that case, you should go to http://cr.yp.to/software.html and follow the links to download the current version. It's possible that upgraded versions aren't compatible with the following instructions, so be sure to read the release notes in the "Upgrading from previous versions. . ." sections of the online documentation.

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/src # 

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 # 

Tip 

The umask command is built into the shell. For more information, try help umask or the man page for your shell; for example, try man csh for the C-Shell.

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."

Table 2-2: Compile-Time Configuration Settings

FILE

PURPOSE

DEFAULT

conf-break

The character used to separate user names and extension addresses

-

conf-cc

The compilation command

cc -O2

conf-groups

The names of the two qmail-specific system groups

qmail, nofiles

conf-ld

The load command

cc -s

conf-patrn

File access bits not allowed in home directory or .qmail files

002 (world-writable)

conf-qmail

The qmail home, or master, directory

/var/qmail

conf-spawn

The concurrency limit

120

conf-split

The number of queue subdirectories

23 (should be prime)

conf-users

The qmail-specific system user accounts

See Table 2-3

Table 2-3: The qmail System Accounts

CONF-USERS LINE

DESCRIPTION

DEFAULT

1

Alias user

alias

2

Daemon user

qmaild

3

Log user

qmaill

4

Binary owner

root

5

Password user

qmailp

6

Queue user

qmailq

7

Remote user

qmailr

8

Send user

qmails

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: 

Caution 

Make sure that 2107 and 2108 aren't already used. If they are, choose two group numbers not already in use.

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 

Caution 

Make sure 7790-7796 aren't already used and that 2107 and 2108 are the same group IDs you used previously.

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.

Note 

If the current version is newer than 0.88, check the installation instructions on the ucspi-tcp Web page (http://cr.yp.to/ucspi-tcp.html).

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

start example
 #!/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" 
end example

Caution 

Note that this script uses back quotes ('), which look a little like single quotes (').

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.

Table 2-4: Mailbox Formats and Locations

FORMAT

NAME

LOCATION

DEFAULTDELIVERY

COMMENTS

mbox

Mailbox

$HOME

./Mailbox

Most common, works with most MUAs

maildir

Maildir

$HOME

./Maildir/

More reliable, less MUA support

mbox

username

/var/spool/mail

See INSTALL.vsm

Traditional Unix mailbox

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 # 

Note 

defaultdelivery isn't a standard qmail control file. It's a special feature of the /var/qmail/rc file.

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

start example
 #!/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     ;;   flush|doqueue|alrm)     echo "Sending ALRM signal to qmail-send."     svc -a /service/qmail-send 2>&1 | tee -a $LOG     ;;   queue)     qmail-qstat     qmail-qread     ;;   reload|hup)     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 {start|stop|restart|flush|reload|stat|pause|cont|cdb|queue| help}"     exit 1     ;; esac exit 0 
end example

Note 

This script is also available on the official book Web site (http://www.apress.com).

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 rcN.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 

Note 

These numbers are highly system dependent but somewhat flexible. If Sendmail is currently installed, running the command find RCDIR -name "*sendmail" -print will give you numbers that should work for your system.

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.

Note 

concurrencyincoming isn't a standard qmail control file. It's a special feature of the previous script.

Note 

The memory limit specified in the softlimit command may need to be raised depending upon your operating system and hardware platform. If attempts to connect to port 25 fail, or remote systems are unable to send you mail, try raising it to 3000000 or 4000000.

Note 

Under Solaris, the normal id program won't work correctly in this script. Instead of id, use /usr/xpg4/bin/id; for example, use QMAILDUID='/usr/xpg4/bin/id -u qmaild' and NOFILESGID='/usr/xpg4/bin/id -g qmaild'.

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 # 

Note 

qmail will start automatically shortly after these links are created. If you don't want a partially configured mail system running, do qmailctl stop now.

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. # 

Note 

RELAYCLIENT should be set to the empty string-nothing between the double quotes.

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.

Table 2-5: System Aliases

ALIAS

PURPOSE

postmaster

RFC 2821 required, points to the mail administrator (you)

mailer-daemon

De facto standard recipient for some bounces

root

Redirects mail from privileged account to the system administrator

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.

Tip 

The inst_check script located on the official book Web site (http://www.apress.com) can be used to help ensure that the installation is correct before starting qmail the first time.

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/qmail # 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.

Remote to Postmaster

From an account on another system, send a message to PoStMaStEr@domain, replacing domain with your host's full domain name. Verify that the message was delivered to the postmaster's mailbox, as when you were sending a test message from a local user to local postmaster.

If all of these tests passed, congratulations! You've successfully installed qmail.



 < Free Open Study > 



The Qmail Handbook
The qmail Handbook
ISBN: 1893115402
EAN: 2147483647
Year: 2001
Pages: 186
Authors: Dave Sill

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net