1. Introduction
1.1. Audience
Life with qmail is aimed at everyone interested in running qmail, from the rank amateur (newbie) who just installed Linux on a spare PC all the way up to the experienced system administrator or mail administrator. If you find it lacking or unclear, please let me know. Send comments to lwq@sill.org.
There's a wealth of information available on qmail from a variety of sources. Some is targeted to newbies, some assumes that the reader is more experienced. Life with qmail is an attempt to "glue" this information into a single source, filling in some of the cracks and assuming only that the reader has basic skills such as:
- Manipulating files/directories under UNIX
- Operating a web browser or FTP client
- Following directions
1.2. What is qmail?
qmail is an Internet Mail Transfer Agent (MTA) for UNIX-like operating systems. It's a drop-in replacement for the Sendmail system provided with UNIX operating systems. qmail uses the Simple Mail Transfer Protocol (SMTP) to exchange messages with MTA's on other systems.
Note: The name is "qmail", not "Qmail".
1.3. Why use qmail?
Your operating system included an MTA, probably Sendmail, so if you're reading this document you're probably looking for something better. Some of the advantages of qmail over vendor-provided MTA's include:
1.3.1. Security
qmail was designed for high security. Sendmail has a long history of serious security problems. When Sendmail was written, the Net was a much friendlier place. Everyone knew everyone else, and there was little need to design and code for high security. Today's Internet is a much more hostile environment for network servers. Sendmail's author, Eric Allman, has done a good job of tightening up the program, but nothing short of a redesign can achieve true security.
1.3.2. Performance
qmail parallelizes mail delivery, performing up to 20 deliveries simultaneously, by default.
1.3.3. Reliability
Once qmail accepts a message, it guarantees that it won't be lost. qmail also supports a new mailbox format that works reliably even over NFS without locking.
1.3.4. Simplicity
qmail is smaller than any other equivalently-featured MTA.
Note: The official qmail web page, http://cr.yp.to/qmail.html covers the advantages of qmail more extensively.
1.4. History
qmail was written by Dan Bernstein (DJB), http://cr.yp.to/djb.html, a math professor now at the University of Illinois in Chicago. Dr. Bernstein is also well known for his work in the field of cryptography and for his lawsuit against the U.S. government regarding the publishing of encryption source code. See http://www.news.com/News/Item/0,4,36217,00.html?owv for information regarding the lawsuit.
The first public release of qmail, beta version 0.70, occurred on January, 24, 1996. The first gamma release, 0.90, was on August, 1, 1996.
Version 1.0, the first general release, was announced on February, 20, 1997. The current version, 1.03, was released on June, 15, 1998.
The next release is expected to be an evaluation version of 2.0. Some of things that might appear in version 2 are covered at http://cr.yp.to/qmail/future.html.
1.5. Features
The qmail web page, http://cr.yp.to/qmail.html, has a comprehensive list of qmail's features. This section is based heavily on that list.
1.5.1. Setup
- Automatic adaptation to your UNIX variant--no porting needed
- Automatic per-host configuration
- Quick installation--no big list of decisions to make
1.5.2. Security
- Clear separation between addresses, files, and programs
- Minimization of setuid code
- Minimization of root code
- Five-way trust partitioning--security in depth
- Optional logging of one-way message hashes, entire message contents, etc. (See What is QUEUE_EXTRA? in Appendix E.)
1.5.3. Message construction
- RFC 822 and RFC 1123 compliant
- Full support for address groups
- Automatic conversion of old-style address lists to RFC 822 format
- sendmail command for compatibility with current user agents
- Header line length limited only by memory
- Host masquerading (See defaulthost)
- User masquerading (See MAILUSER and MAILHOST)
- Automatic Mail-Followup-To creation (See QMAILMFTFILE)
1.5.4. SMTP service
- RFC 821, RFC 1123, RFC 1651, RFC 1652, and RFC 1854 compliant
- 8-bit clean
- RFC 931/1413/ident/TAP callback--can help track spammers/forgers
- Relay control--stops unauthorized relaying by outsiders
- No interference between relay control and aliases
- Automatic recognition of local IP addresses
- Per-buffer timeouts
- Hop counting
- Parallelism limit (via ucspi-tcp)
- Refusal of connections from known abusers (via ucspi-tcp)
- Relaying and message rewriting for authorized clients
- Optional RBL/ORBS support (via rblsmtpd)
1.5.5. Queue management
- Instant handling of messages added to queue
- Parallelism limits
- Split queue directory--no slowdown when queue gets big
- Quadratic retry schedule--old messages tried less often (see Appendix E)
- Independent message retry schedules
- Automatic safe queueing--no loss of mail if system crashes
- Automatic per-recipient checkpointing
- Automatic queue cleanups
- Queue viewing (See qmail-qread)
- Detailed delivery statistics (via qmailanalog)
1.5.6. Bounces
- QSBMF bounce messages--both machine-readable and human-readable
- HCMSSC support--language-independent RFC 1893 error codes
- Double bounces sent to postmaster
1.5.7. Routing by domain
- Any number of names for local host (See locals)
- Any number of virtual domains (See virtualdomains)
- Domain wildcards (See virtualdomains)
- Configurable "percent hack" support (See percenthack)
- UUCP hook
1.5.8. SMTP delivery
- RFC 821, RFC 974, and RFC 1123 compliant
- 8-bit clean
- Automatic downed host backoffs
- Artificial routing--smarthost, localnet, mailertable (See smtproutes)
- per-buffer timeouts
- Passive SMTP queue--perfect for SLIP/PPP (via serialmail)
- AutoTURN support (via serialmail)
1.5.9. Forwarding and mailing lists
- Sendmail .forward compatibility (via dot-forward)
- Hashed forwarding databases (via fastforward)
- Sendmail /etc/aliases compatibility (via fastforward)
- Address wildcards (See .qmail-default)
- Mailing list owners--automatically divert bounces and vacation messages
- VERPs--automatic recipient identification for mailing list bounces
- Delivered-To--automatic loop prevention, even across hosts
1.5.10. Local delivery
- User-controlled address hierarchy--fred controls fred-anything mbox delivery
- Reliable NFS delivery (See maildir)
- User-controlled program delivery: procmail etc. (See qmail-command)
- Optional new-mail notification (See qbiff)
- Optional NRUDT return receipts (See qreceipt)
- Conditional filtering (See condredirect and bouncesaying)
1.5.11. POP3 service
- RFC 1939 compliant
- UIDL support
- TOP support
- APOP hook
- modular password checking (via checkpassword)
1.6. Related packages
qmail follows the classic UNIX philosophy that each tool should perform a single, well-defined function, and complex functions should be built by connecting a series of simple tools into a "pipeline". The alternative is to build more and more complex tools that re-invent much of the functionality of the simpler tools.
It's not surprising, then, that qmail itself doesn't do everything everyone might want it to do. Here, then, are some of the most popular add-ons written for qmail. Of course, many standard UNIX utilities can also be plugged into qmail.
- dot-forward--a Sendmail .forward file compatibility add-on
- fastforward--a Sendmail alias database compatibility add-on
- ucspi-tcp--an inetd replacement
- daemontools--a set of tools for managing daemons and their logs
- qmailanalog--a set of qmail log file analysis tools
- rblsmtpd--an anti-spam tool
- serialmail--tools for mailing over slow networks
- mess822--tools for parsing Internet mail messages
- ezmlm--a mailing list manager for qmail
1.7. Architecture
Appendix D covers qmail's functional and physical structure. In a nutshell, qmail consists of a series of programs (modules) that perform different tasks.
1.8. License
qmail is copyrighted by the author, Dan Bernstein, and is not distributed with a statement of user's rights. In http://cr.yp.to/softwarelaw.html, he outlines what he thinks your rights are under U.S. copyright law. In http://cr.yp.to/qmail/dist.html he grants the right to distribute qmail source code. Binary distributions are allowed under the terms described there and in http://cr.yp.to/qmail/var-qmail.html, although, at this time, nobody is actually attempting this.
The bottom line is that you can use qmail for any purpose, you can redistribute unmodified qmail source distributions and qualifying var-qmail binary distributions, and you can distribute patches to qmail. You can't distribute modified qmail source code or non-var-qmail binary distributions.
1.9. Comparison with other MTA's
A book could be written about this topic, but it would be tedious reading. Here's a quick comparison of qmail with some of the most common UNIX MTA's.
MTA | Maturity | Security | Features | Performance | Sendmailish | Modular |
qmail | medium | high | high | high | addons | yes |
Sendmail | high | low | high | low | x | no |
Postfix | low | high | medium | high | yes | yes |
exim | medium | low | high | medium | yes | no |
Sendmailish means the MTA behaves like Sendmail in some ways that would make a switch from Sendmail to the alternative MTA more user-transparent, such as the use of .forward files, /etc/aliases, and delivery to /var/spool/mail.
Cameron Laird has a web page comparing these and other free and commercial MTA's at http://starbase.neosoft.com/~claird/comp.mail.misc/MTA_comparison.html.
1.10. Documentation
1.10.1. man pages
The qmail distribution comes with a complete set of man pages. After installation, they're in /var/qmail/man. You'll probably need to add that directory to your MANPATH environment variable.
Shell | Command |
Bourne (/bin/sh) | MANPATH=$MANPATH:/var/qmail/man; export MANPATH |
bash, Korn | export MANPATH=$MANPATH:/var/qmail/man |
C Shell | setenv MANPATH $MANPATH:/var/qmail/man |
At this point, commands in the format "man name-of-qmail-man-page" should display the appropriate man page.
The man pages are also available on-line in HTML format from:
Note: the qmail man pages are loaded with information, but they require careful reading because they're written in a very dense, technical style. You might want to print off a set and read them through once to familiarize yourself with what's there and where it is. Very little information is repeated on multiple pages, so if you don't know where something is covered, it can be hard to find it.
1.10.2. Docs
The qmail distribution includes a series of documents that are installed under /var/qmail/doc. They include:
- FAQ: Frequently Asked Questions, with answers
- INSTALL*: Installation documentation
- PIC.*: Descriptions of how qmail performs key tasks. See the Architecture appendix for more information.
- Various other installation-related documentation
These docs are also available on-line from:
1.10.3. FAQs
There are two official FAQ (Frequently Asked Questions, with answers) documents:
- /var/qmail/doc/FAQ, the plain text version, and
- The web FAQ at http://cr.yp.to/qmail/faq.html.
The web FAQ is more complete.
1.10.4. Books
1.10.4.1. qmail
John Levine and Russell Nelson are writing a qmail book for O'Reilly & Associates (http://www.oreilly.com) which should be available later this year. Russell and John are frequent contributors to the qmail mailing list, and have demonstrated thorough knowledge of qmail and the ability to communicate it effectively and politely. O'Reilly has an excellent reputation in computing-related publishing. This book will undoubtedly become the qmail "bible".
For more information or to order this book when it becomes available, see http://www.amazon.com/exec/obidos/ASIN/1565926285/davesill.
1.10.4.2. Running qmail
Richard Blum has written Running qmail, which is published by Sams. This book has received mixed reviews on the qmail mailing list.
For more information or to order this book, see http://www.amazon.com/exec/obidos/ASIN/0672319454/davesill.
1.10.5. List archives
The qmail e-mail mailing list, maintained by Dan Bernstein, is a valuable source of information. A web archive of the lists messages is kept at:
A search engine for the archive is at:
Other web archives are available at:
Most questions about qmail can be answered by searching the list archives first.
1.10.6. Other Web Sites
- http://cr.yp.to/qmail.html: the official qmail home page.
- http://www.qmail.org: the unofficial qmail home page. Contains lots of information about add-ons and patches, and links to many good qmail web pages on other sites.
- http://www.flounder.net/qmail/qmail-howto.html: Adam McKenna's HOWTO.
1.11. Support
1.11.1. Mailing lists
The following lists reside on list.cr.yp.to. In order to prevent harvesting of e-mail addresses by spammers, I'm avoiding the use of complete, valid addresses and "mailto" URL's.
The lists are managed by ezmlm, which uses different addresses to perform different functions:
- listname@list.cr.yp.to: the submission address. Messages sent here go out to all members of the list. Do not send subscribe/unsubscribe requests here: they won't work, and they'll annoy the subscribers.
- listname-help@list.cr.yp.to: the "help" address. Returns a list of command addresses and general usage information.
- listname-subscribe: send a blank message here to subscribe.
- listname-unsubscribe: send a blank message here to unsubscribe.
To specify a subscription/unsubscription address, say joe@example.com, send the message to:
- listname-subscribe-joe=example.com@list.cr.yp.to.
1.11.1.1. qmail
The main qmail mailing list. Discussion and questions/answers on everything related to qmail, except serialmail. Read the FAQ and search the list archives before posting a question. When you ask questions, please try to include sufficient details to make it possible for people to respond:
- What did you do? What's your configuration? Include qmail-showctl output if you're not sure what's important. What action did you take?
- What did you expect to happen? What was the outcome you were trying to achieve? Don't assume the reader can guess.
- What did happen? Describe the actual result. Include log file clippings and copies of messages, with headers.
1.11.1.2. qmailannounce
The qmail announcement mailing list. New releases are announced here. There's no submission address: it's a read-only list.
1.11.1.3. serialmail
For discussion of the serialmail package.
1.11.1.4. ezmlm
For discussion of the ezmlm mailing list manager.
1.11.2. Consultants
See http://www.qmail.org/top.html#paidsup for a list of commercial support providers.
1.11.3. FAQTS Knowledgebase
A database of qmail-related questions and answers is available at http://qmail.faqts.com. If you have a question that the FAQ doesn't answer, try searching this knowledgebase. It's especially good at answering "how to" questions.
2. Installation
This section covers installing qmail. If you're an experienced system administrator, you can install qmail following the directions in INSTALL in the source distribution. The INSTALL directions are the official installation directions. They're more complex than the Life with qmail directions, and they assume that the reader is an experienced system and mail administrator.
Note: If you choose to install using the following directions, you should read through the entire section to familiarize yourself with the overall process.
2.1. Installation Issues
2.1.1. Binary vs. source code
Due to qmail's restrictive licensing regarding the distribution of prebuilt packages, qmail is usually installed from a source code distribution.
If you're not familiar with the distinction between source code and binaries, imagine ordering a pizza delivered to your house. The "binary" version of the pizza arrives ready-to-eat. The "source code" pizza comes as a kit containing flour, yeast, cheese, sauce, toppings, and directions for cooking the pizza yourself. Source code installations are a little more work for you, but if you follow the directions carefully, the result is the same--or even better. The self-baked pizza will be fresher, you can adjust the toppings to your preferences, and you'll know a lot more about your pizza and how it "works".
2.1.2. Tarball vs. OS-specific package
Some operating systems provide a mechanism for automating source code installations. Returning to the pizza analogy, they make it possible to package the ingredients and directions in such a way that you can just push a button and have the pizza bake itself.
Sounds great, doesn't it?
In practice, it might not be such a good idea. Assembling these packages is pretty difficult, and they might not do things the way they're supposed to. They're software, and like any software, they can have bugs. But even if they're bug free, the convenience they provide comes at a cost. You lose most of the advantages of the self-baked pizza: the ability to adjust the toppings to your personal preferences, and the knowledge of how the pizza was made and how it works.
If qmail was a pizza, the self-building approach might still be the way to go. But it's not: it's a fairly complicated system that the installer/maintainer needs to understand pretty well in order to be able to keep it working smoothly. The self-installing qmail is easier to install than the user-installed version, but the user-installed version is easier to configure and troubleshoot. You install qmail once on a system, but you will probably have several opportunities to reconfigure it or try to figure out why mail isn't flowing the way you think it should.
For this reason, I suggest installing qmail from scratch using the source code tarball, not a Red Hat "RPM" or other "self-installing" bundle.
2.2. Preparation
Before installing qmail on a system, especially if this is your first qmail installation, there are a few things you need to think about.
- 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, 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 under your belt--it's a good idea to formulate a plan.
2.3. System requirements
qmail will install and run on most UNIX and UNIX-like systems, but there are 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, 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. 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 README in the source tree for a list of known compatible releases.
- Access to a domain name server (DNS) is highly recommended. Without one, qmail can only send to remote systems configured in its smtproutes config 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. The serialmail package was designed to make qmail more compatible with poorly-connected systems. See the serialmail section in the Related Packages appendix for more information.
2.4. Download 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, of course, and you should probably also get 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 the 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.
2.5. Build the source
2.5.1. Verify build environment
The first thing you need to do is make sure that 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.
Note: if any one of these tests passes, you can stop and go on to the next section.
- At a command line prompt, type cc and press Enter:
$ cc cc: No input files specified $
- If you get a similar response, you have a C compiler in your path. If not, it 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 these:
- /usr/bin/cc
- /usr/bin/gcc
- /usr/local/bin/cc
- /usr/local/bin/gcc
- /usr/ccs/bin/cc
- If none of these works, you'll have to try something little more platform specific. At the prompt try one of these, depending on which OS you're using:
- Red Hat Linux: rpm -qa | grep gcc or rpm -qa | grep egcs
- FreeBSD: includes GCC by default
- If you can't find a compiler installed, you'll have to locate one and install it. Contact your OS vendor or other OS support channel.
In this section we'll go through the actual steps of compiling qmail. A way to cut-n-paste will come in handy here, but isn't really necessary.
2.5.2. Unpack the distribution
If you made it this far, you have a working C compiler and copies of the tarballs. Copy or move the tarballs to the directory you want to do the work in. /usr/local/src is a good choice, and in this case you can use /usr/local/src/qmail for all three packages.
mkdir -p /usr/local/src/qmail mv *.tar.gz /usr/local/src/qmail
You've got all three packages in /usr/local/src/qmail, so now you can unpack them. At this time you probably want to become root, if you're not already. At a prompt, type the following:
su - cd /usr/local/src/qmail gunzip qmail-1.03.tar.gz tar xvf qmail-1.03.tar gunzip ucspi-tcp-0.88.tar.gz tar xvf ucspi-tcp-0.88.tar gunzip daemontools-0.70.tar.gz tar xvf daemontools-0.70.tar rm *.tar # optional, unless space is very tight
There should now be subdirectories called qmail-1.03, ucspi-tcp-0.88, and daemontools-0.70. Change to the qmail-1.03 directory and let's get started:
cd qmail-1.03
2.5.3. Create directories
Since qmail's installation program creates the subdirectories as they're needed, you only need to create the qmail "home" directory:
mkdir /var/qmail
And on to the next section.
Note: If you want some or all of the qmail files to reside elsewhere than /var, this can be accomplished by creating symbolic links under /var/qmail pointing to the other locations.
For example, a more distributed layout can be achieved by doing:
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
2.5.4. Create users and groups
The easiest way to create the necessary users and groups is to create a little script file to do it for you. In the source directory you'll find a file called INSTALL.ids. It contains the command lines for many platforms, so copying the file to another name and editing that is quick and easy.
cp INSTALL.ids IDS
Then, using your favorite editor, remove all of the file except the lines you want. For example, here's what IDS would look like for FreeBSD after editing:
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
Then to run it, either use chmod to make it executable or run it with sh:
First method:
chmod 700 IDS ./IDS
Second method:
/bin/sh IDS
When the script finishes, all of your users and groups will be created and you can go on to the next section.
But what do you do if your system isn't listed in INSTALL.ids? You'll have to create them manually. 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:
Note: Make sure that 2107 and 2108 aren't already used.
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
Note: Make sure 7790-7796 aren't already in use and that 2107 and 2108 are the same group ids you used above.
You don't specifically need to add any of these lines to the end of the file, that's just the easiest way to explain it here.
You're now ready to continue on to the next section.
2.5.5. Do the build
You're now ready to start building qmail.
In the Verify 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 conf-cc and conf-ld. Say your compiler is gcc, and it's in your PATH. Simply edit conf-cc and conf-ld and replace "cc" with "gcc".
Now type the following:
make setup check
After the build is complete, you'll need to do your post installation configuration. A couple of scripts are provided to make this job a lot easier.
If your DNS is configured properly, this script should be all you need at this point:
./config
If, for some reason, config can't find your hostname in DNS, you'll have to run the config-fast script:
./config-fast the.full.hostname
For example, if your domain is example.com and the hostname of your computer is dolphin, your config-fast line would look like this:
./config-fast dolphin.example.com
qmail is now installed on your system and is ready to be run! The next section will guide you through the steps of starting and testing qmail.
2.6. Install ucspi-tcp
Earlier, you unpacked the qmail, ucpsi-tcp, and daemontools tarballs. In our example, we unpacked them into /usr/local/src/qmail. Now change to the ucpsi-tcp directory:
cd /usr/local/src/qmail/ucspi-tcp-0.88
In the Do the build section, if you modified conf-cc and conf-ld, you'll need to make the same changes in this directory.
Then do:
make make setup check
That's it. ucpsi-tcp is installed.
2.7. Install daemontools
Change to the daemontools build directory:
cd /usr/local/src/qmail/daemontools-0.70
Once again, if you modified conf-cc and conf-ld during the qmail and ucspi-tcp builds, you'll need to make the same changes in this directory.
Then do:
make make setup check
Test the build by following the directions in http://cr.yp.to/daemontools/install.html.
2.8. Start qmail
2.8.1. /var/qmail/rc
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 following:
#!/bin/sh # Using stdout for logging # Using control/defaultdelivery from qmail-local to deliver messages by default exec env - PATH="/var/qmail/bin:$PATH" \ qmail-start "`cat /var/qmail/control/defaultdelivery`"
Use your editor to create the above /var/qmail/rc, then execute these commands:
chmod 755 /var/qmail/rc mkdir /var/log/qmail
At this point you need to decide the default delivery mode for messages that aren't delivered by a .qmail file. The following table outlines some common choices.
Mailbox format | Name | Location | defaultdelivery | Comments |
mbox | Mailbox | $HOME | ./Mailbox | most common, works with most MUA's |
maildir | Maildir | $HOME | ./Maildir/ | more reliable, less MUA support |
mbox | username | /var/spool/mail | See INSTALL.vsm | traditional UNIX mailbox |
See INSTALL.mbox, INSTALL.maildir, and INSTALL.vsm for more information.
To select your default mailbox type, just enter the defaultdelivery value from the table into /var/qmail/control/defaultdelivery. E.g., to select the standard qmail Mailbox delivery, do:
echo ./Mailbox >/var/qmail/control/defaultdelivery
Note: defaultdelivery isn't a standard qmail control file. It's a feature of the /var/qmail/rc file above.
2.8.2. System start-up files
2.8.2.1. The qmail 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 startup/shutdown script like the following:
#!/bin/sh PATH=/var/qmail/bin:/usr/local/bin:/usr/bin:/bin export PATH case "$1" in start) echo -n "Starting qmail: svscan" cd /var/qmail/supervise env - PATH="$PATH" svscan & echo $! > /var/run/svscan.pid echo "." ;; stop) echo -n "Stopping qmail: svscan" kill `cat /var/run/svscan.pid` echo -n " qmail" svc -dx /var/qmail/supervise/* echo -n " logging" svc -dx /var/qmail/supervise/*/log echo "." ;; stat) cd /var/qmail/supervise svstat * */log ;; doqueue|alrm) echo "Sending ALRM signal to qmail-send." svc -a /var/qmail/supervise/qmail-send ;; queue) qmail-qstat qmail-qread ;; reload|hup) echo "Sending HUP signal to qmail-send." svc -h /var/qmail/supervise/qmail-send ;; pause) echo "Pausing qmail-send" svc -p /var/qmail/supervise/qmail-send echo "Pausing qmail-smtpd" svc -p /var/qmail/supervise/qmail-smtpd ;; cont) echo "Continuing qmail-send" svc -c /var/qmail/supervise/qmail-send echo "Continuing qmail-smtpd" svc -c /var/qmail/supervise/qmail-smtpd ;; restart) echo "Restarting qmail:" echo "* Stopping qmail-smtpd." svc -d /var/qmail/supervise/qmail-smtpd echo "* Sending qmail-send SIGTERM and restarting." svc -t /var/qmail/supervise/qmail-send echo "* Restarting qmail-smtpd." svc -u /var/qmail/supervise/qmail-smtpd ;; cdb) tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp 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 doqueue -- 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 HELP ;; *) echo "Usage: $0 {start|stop|restart|doqueue|reload|stat|pause|cont|cdb|queue|help}" exit 1 ;; esac exit 0
This script is also available via http://Web.InfoAve.net/~dsill/qmail-script-dt61.exe. The ".exe" tricks the web server into thinking the script is an executable, which prevents it from converting the file to DOS format.
Note: If you find that qmail exits shortly after the system is rebooted, you can prefix the env command in the "start" section of the script with nohup. E.g.:
nohup env - PATH="$PATH" svscan &
Create the script using your editor or by downloading it with your web browser, then install it into your system's init.d directory, which should be in one of the following locations:
- /etc/init.d
- /sbin/init.d
- /etc/rc.d/init.d
Name the script qmail. 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 runlevel they apply to. The intricacies of the startup directory tree are beyond the scope of this document, so if these simplified instructions don't suffice, consult your system documentation. Your rc directories will probably be in one of:
- /etc
- /sbin
- /etc/rc.d
To create the links, execute the following commands, replacing RCDIR with the location of your system's rc directories:
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: the numbers in the previous step 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.
Make the startup script executable and link it to a directory in your path:
# substitute the correct location of your rc dir on the next two lines chmod 755 /etc/init.d/qmail ln -s /etc/init.d/qmail /usr/local/sbin
2.8.2.2. The supervise scripts
Now 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
Create the /var/qmail/supervise/qmail-send/run file:
#!/bin/sh exec /var/qmail/rc
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
Create the /var/qmail/supervise/qmail-smtpd/run file:
#!/bin/sh QMAILDUID=`id -u qmaild` NOFILESGID=`id -g qmaild` MAXSMTPD=`cat /var/qmail/control/concurrencyincoming` 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 smtp /var/qmail/bin/qmail-smtpd 2>&1
Note: concurrencyincoming isn't a standard qmail control file. It's a feature of the above script.
Note: Under Solaris, the normal id program won't work right in this script. Instead of id, use /usr/xpg4/bin/id, e.g.:
QMAILDUID=`/usr/xpg4/bin/id -u qmaild` NOFILESGID=`/usr/xpg4/bin/id -g qmaild`
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.
Create the concurrencyincoming control file:
echo 20 > /var/qmail/control/concurrencyincoming chmod 644 /var/qmail/control/concurrencyincoming
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
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
Then set up the log directories:
mkdir -p /var/log/qmail/smtpd chown qmaill /var/log/qmail /var/log/qmail/smtpd
2.8.2.3. SMTP Access Control
Allow the local host to inject mail via SMTP:
echo '127.:allow,RELAYCLIENT=""' >>/etc/tcp.smtp /usr/local/sbin/qmail cdb
2.8.3. Stop and disable the installed MTA
Although it's possible to run both qmail and your existing MTA, which is probably Sendmail, simultaneously, I don't recommend it unless you know what you're doing. And, frankly, if you're reading this, you probably don't know what you're doing. :-)
If your existing MTA is Sendmail, you should be able to stop it by running the init.d script with the "stop" argument. E.g., 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, you can locate sendmail's PID using "ps -ef|grep sendmail" or "ps waux|grep sendmail" and stop it using:
kill PID-of-sendmail
If your MTA isn't Sendmail, check its documentation for the correct shutdown procedure.
You should also consider removing the old MTA completely from the system. At least disable the init.d script so it doesn't try to start up again when the system is rebooted.
For Red Hat Linux, removing Sendmail can be accomplished by:
rpm -e --nodeps sendmail
Lastly, replace any existing /usr/lib/sendmail with the qmail version:
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
We're this close to being able to start qmail. The last step is to create a couple system aliases.
2.8.4. Create System Aliases
There are three system aliases that should be created on all qmail installations:
Alias | Purpose |
postmaster | RFC 821 required, points to the mail adminstrator (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 (a local user or a remote address) and create and populate the appropriate .qmail files. For example, say local user dave is both the system and mail administrator:
echo dave > /var/qmail/alias/.qmail-root echo dave > /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
See INSTALL.alias for more details.
2.8.5. Start qmail
Finally, you can start qmail:
/usr/local/sbin/qmail start
2.9. Test the Installation
qmail should now be running. Follow the instructions in TEST.deliver and TEST.receive to verify that it's working correctly. Note that using these instructions, logging will be accomplished by multilog, not splogger.
3. Configuration
You've got qmail installed, either from the recommended source tarball method, or one of the self-compiling packages. This section contains information the mail administrator or system administrator will need to configure qmail to make it work the way they want it to.
3.1. Configuration Files
All of qmail's system configuration files, with the exception of the .qmail files in ~alias, reside in /var/qmail/control. The qmail-control man page contains a table like the following:
Control | Default | Used by | Purpose |
badmailfrom | none | qmail-smtpd | blacklisted From addresses |
bouncefrom | MAILER-DAEMON | qmail-send | username of bounce sender |
bouncehost | me | qmail-send | hostname of bounce sender |
concurrencylocal | 10 | qmail-send | max simultaneous local deliveries |
concurrencyremote | 20 | qmail-send |