| < 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.
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.
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).
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."
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.
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. |
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.
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.
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."
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 |
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.
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.
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.
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
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
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
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. |
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.
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). |
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.
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.
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"
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.
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. |
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.
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 ;; 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
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.
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
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.
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. |
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.
There are three system aliases that should be created on all qmail installations. Table 2-5 lists them.
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.
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 #
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. |
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.
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.
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.
Send a series of test messages to verify that qmail is working correctly.
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."
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 > |
|