Qmail
From InstallationWiki
| Official Page |
| Project Documentation |
| Download |
|
If you're diving into this article, chances are you're entirely new to qmail. There are many very good qmail installation guides and tutorials that are available for free on the Internet. The current version of qmail was published on June 15th, 1998. Since then what has changed the most about the qmail experience is the accumulation of expertise and experience in using and tailoring it for the most common situations and even some uncommon ones.
Without delving into the architecture, qmail is extremely modular. In many ways, qmail is less of a mail server and more of mail server architecture. Pieces of qmail can be replaced, rearranged, filtered, and extended as necessary to achieve virtually any feature the administrator desires. However, along the same lines, qmail requires certain assistance to provide some features one ordinarily expects. Qmail's SMTP server, for example, cannot talk to the network by itself; this ability is provided by software like inetd or tcpserver or similar. This design makes qmail's components secure and much simpler and easier to verify. This design also makes the details of how the qmail components are hooked together a vital part of the system configuration, as opposed to a single monolithic server with a complex configuration file that can achieve the same thing. You need a basic understanding of UNIX-style operating system conventions and features, simple command-line operations, and how to edit text files.
Contents |
[edit] The Minimum Qmail System
Qmail comes with a set of minimal install instructions, in a file named INSTALL. It contains eighteen relatively basic steps for compiling qmail on most systems and for getting it running. These are somewhat simple, but can be trimmed even further if you're not trying to replace an existing mail server.
[edit] Basic Configuration
Once all five steps are completed, a working, bare-bones installation of qmail is ready in /var/qmail. However, in many situations, a barebones installation is insufficient.
The basic questions to answer when configuring an email server on a new system include:
- What should be done with mail when it is received?
- Which mail should be accepted?
The most common and simplest answers to the first question generally fall into one of the following two categories: either mail should be relayed to a smarter mail server or the mail should be delivered locally.
The second question can often become far more complicated due to spam and viruses and the like, but the most basic answer is generally a list of domain names for which this email server is responsible.
As you can tell already, various answers to these questions can result in wildly different behaviors. For example, if no mail should be accepted from the network, no mail should be delivered locally, and all mail should be forwarded to a specific mail server, then this is considered mini-qmail. In such a situation, many of the more complex features of qmail can be eliminated. In different circumstances, the qmail server may need to accept any and all email and forward it to a central mail server (for example, a mail proxy or a caching forwarder). Or it may need to accept email for a specific domain and deliver it to system-defined users (the standard setup). Or it may need to accept email for a set of domains and deliver it locally via some virtual-domain configuration. There could be any number of additional complications, twists, and turns.
The most basic answers to these questions are specified to qmail via configuration files. Which mail should be accepted is generally specified by files in the /var/qmail/control directory, and what to do with mail that has been accepted is generally specified in a combination of files in the control directory and the rc file (which was set up in Default Mail Delivery section of the installation procedure). Note though, that the rc file is a shell script. Much of qmail configuration is in the form of scripts controlling how qmail and its related binaries are run.
The most basic, most important control files for qmail are: me, rcpthosts, locals, smtproutes, and defaultdomain. The files are not necessarily created by default or by the ./config scripts; but they control qmail's most important functionality. They control, respectively, the name of the server, which domains' mail to accept, which domains are to be considered local once mail addressed to them is accepted for delivery, where to send outbound mail, and which domain to append to bare
usernames to transform them into real email addresses. The defaultdomain and me files are simple one-line files. In the case of me, this line is considered the name of the server. In the case of defaultdomain, this line is considered the name to append (for example, example.com) to a bare username (for example, user) to construct a valid email address (for example, user@example.com) when necessary. The rcpthosts and locals files are simply lists of domains, one domain per line in the file. The most complex of the four, smtproutes, is also rather simple. Each line of the file consists of three fields separated by colons. The first field is the domain that needs to be routed this way and the second field is the domain name or IP address (in square brackets) of the server to which matching email must be sent. The third field is the port on the server to connect to, which if not present, defaults to port 25. For example:
somewhere.com:[1.2.3.4]
This line in the file informs qmail that any email sent to an address ending in @somewhere.com must be forwarded to the IP address 1.2.3.4. The files smtproutes, rcpthosts, and locals can all use prefix-wildcards. A prefix-wildcard is a line that begins with a period, followed by the suffix that must match following the period. For example:
.somewhere.com:mail.isp.com
This line in the smtproutes file will match email addresses ending in @here.somewhere.com, @there.somewhere.com, @anywhere.somewhere.com, and so forth, where there is an arbitrary string and a period preceding somewhere.com. Note that it doesn't match the bare @somewhere.com. Emails addressed to matching domains are forwarded to mail.isp.com.
Finally there is the special case, where there is nothing to the left of the first colon as shown in the following example:
:mail.isp.com:1000
This line in the smtproutes file will send all email to the mail.isp.com server listening on port 1000. In the smtproutes file, the first match is the one that is used, and this line will match anything. As such, it's usually at the end of the file.
There are many more files that qmail looks for in the /var/qmail/control directory. Explanations of how they work and what they do can be found in the qmail man pages, however, they are generally for more involved configuration tasks and non-basic qmail installations.
Default delivery instructions are part of simple execution.
[edit] Simple Execution
There are two primary architectural segments of qmail involved in setting up a standard SMTP email server. The first is the set of programs that work together to perform mail deliveries, either locally or remotely, and the second is the set of programs that work together to accept messages via the SMTP protocol.
[edit] qmail-start
The programs that work together to perform mail deliveries are: qmail-send, qmail-lspawn, qmail-rspawn, and qmail-clean, as well as any program that they spawn to complete their tasks (like qmail-remote, qmail-local, procmail, etc.). Most of these have corresponding users. In particular, qmail-send and qmail-clean operate as the qmails user, and qmail-rspawn (and qmail-remote) operate as qmailr. The qmail-lspawn program runs as root, because it must be able to deliver mail to each user as that user. In any case, all of these programs are spawned by the command qmail-start. This command takes two optional argumentsa default delivery command and a logging command. To understand exactly how this works, take a look at the most basic of the scripts in the /var/qmail/boot directory, home:
#!/bin/sh # Using splogger to send the log through syslog. # Using qmail-local to deliver messages to ~/Mailbox by default. exec env - PATH="/var/qmail/bin:$PATH" \ qmail-start ./Mailbox splogger qmail
The first part of this script is fairly straightforward: using the env command to remove all environment variables before executing qmail-start, it then sets the PATH environment variable to make sure that the qmail bin directory is the first place searched for qmail's binaries. The second part, executing qmail-start with arguments, requires a little more explanation.
When qmail makes an email delivery, every delivery is made from the perspective of a program running as the receiving user, in the receiving user's home directory. Delivery instructions are treated as if they came from a dot-qmail file, with one delivery instruction per line. From that point onwards, file names are treated as mbox-formated mailboxes, directory names (indicated by ending a file name with a forward-slash (/)) are treated as Maildir-formatted mailboxes, and commands (indicated by starting the line with a pipe symbol (|)) are all located and executed from within the addressed user's home directory. Thus, using a relative file name, such as ./Mailbox, specifies a file named Mailbox within the current directory at the time of delivery i.e. the addressed user's home directory.
In this case, the default delivery method is very simple, deliver mail to an mbox-formatted file named Mailbox in the user's home directory. However, the argument specifying the default delivery method can be more complex. Take, for example, the home+df file in /var/qmail/boot:
#!/bin/sh # Using splogger to send the log through syslog. # Using dot-forward to support sendmail-style ~/.forward files. # Using qmail-local to deliver messages to ~/Mailbox by default. exec env - PATH="/var/qmail/bin:$PATH" \ qmail-start '|dot-forward .forward ./Mailbox' splogger qmail
Note that because of the rules of shell-script quoting, the first argument to qmail-start in this case is the full text between the single quotes, or:
|dot-forward .forward ./Mailbox
Note that the single argument is, in fact, two lines. Just as if these lines were in the user's .qmail file, this causes the dot-forward command to run first, and if it returns with a code that indicates that the mail has been delivered via instructions in a .forward file, the delivery is considered complete. On the other hand, if it returns with a code that indicates that the user did not have a .forward file in his or her home directory, qmail will instead deliver mail to the Mailbox file, just as it would have if the home file's delivery instructions were used.
The text after the mail-delivery specification causes qmail-send to send all logging information to the program specified. In this case, the splogger program will be run with the argument qmail. The splogger program takes the output from qmail-send, prefixes it with "qmail", and logs it via the standard syslog mechanism. If neither the splogger command nor any other command is provided as an argument to qmail-send, qmail-send will send its logging information to standard output (or rather, file descriptor one).
To run this program by hand, simply run your chosen rc file, as follows:
/bin/sh /var/qmail/rc &
The ampersand at the end ensures that the program executes in the background.
[edit] qmail-smtpd
The set of programs that provide SMTP servicereceiving SMTP connections (and thus, email) from the networkis organized around qmail-smtpd. Rather than including basic networking features in the qmail SMTP daemon executable, qmail-smtpd, qmail pushes that responsibility to a helper program such as tcpserver, inetd, xinetd, or tcpsvd, among others. This design decision makes for many useful opportunities. For example, the qmail SMTP service can be tested from the command-line without needing extra software by simply running /var/qmail/bin/qmail-smtpd. (Note that the DATA phase of the SMTP conversation requires CRLFs rather than simply LFs. The correct line endings can be generated by pressing Ctrl V and then pressing Enter twice.)
Getting qmail-smtpd to listen to the network requires extra software. Many systems come with either inetd or xinetd and they can be configured to run qmail-smtpd very easily. For example, an inetd.conf entry for qmail-smtpd might look like this (all one line):
smtp stream tcp nowait qmaild /var/qmail/bin/tcp-env tcp-env /var/qmail/bin/qmail-smtpd
The current best practice for running qmail-smtpd is to use the tcpserver program, also written by the author of qmail, Dr. Bernstein, which is distributed as part of the ucspi-tcp package (http://cr.yp.to/ucspi-tcp.html). It can be used as follows:
tcpserver -u `id -u qmaild` -g `id -g qmaild` \ 0 smtp /var/qmail/bin/qmail-smtpd &
This command can be run manually, added to your system's startup commands, or executed using Bernstein's daemontools (http://cr.yp.to/daemontools.html) package. If added to your system's startup commands, the ampersand (&) is critical. The arguments to tcpserver are straightforwardfirst, the user and group IDs, then 0 to specify that it will listen to all network interfaces, then smtp to specify that it will use the SMTP port (25), and finally, the command to be run when a connection is made to that network port.
Standard qmail-smtpd does not take any run-time arguments; however, its behavior can be modified at run time by using environment variables. In particular, qmail-smtpd pays attention to the following environment variables:
| Environment Variable | Description | ||
|---|---|---|---|
TCPLOCALHOST
| The DNS hostname corresponding to the local interface in the connection. | ||
TCPLOCALIP
| The local IP address in the connection. | ||
TCPLOCALPORT
|
The local port number (usually 25 when used with qmail-smtpd). | ||
| Environment Variable | Description | ||
TCPREMOTEHOST
| The DNS hostname of the remote system. | ||
TCPREMOTEINFO
| The username responsible for the connection (usually determined using the ident protocol). | ||
TCPREMOTEIP
| The IP address of the remote system. | ||
TCPREMOTEPORT
| The port number used by the remote system. | ||
DATABYTES
| The maximum number of bytes allowed in a message. | ||
RELAYCLIENT
| The existence of this variable (even if it contains an empty string) allows the sender to relay any email message. The content of this variable is appended to each recipient address. |
Most of these variables (the ones that begin with TCP) are set by the program that handles the network operations. The tcpserver and tcpsvd programs set these variables. For programs that do not set these variables (for example, inetd and xinetd), tcp-env will set them. The environment variable you will most commonly need to set yourself is RELAYCLIENT. If this variable is present in the environment, qmail-smtpd accepts any mail for delivery even if the destination addresses are not in the control/rcpthosts file. For example, an ISP that relays email from all of its customers generally adds the RELAYCLIENT variable to qmail-smtpd's environment, if the connecting client is in its network.
While tcpserver, tcpsvd, and tcp-env will set specific environment variables, any other variable (such as RELAYCLIENT) will generally need to be set using a more generic method. Environment variables can be set in many ways, like using the standard env utility, the shell's export/setenv features, and tcprules files.
[edit] Administrative Conveniences
Qmail setup as described so far can provide full email service. This setup is, however, rather minimal, and lacks many administrative, maintenance, and troubleshooting features. Because qmail is designed to be modular, these deficiencies are easily remedied with additional programs. asd
[edit] ucspi-tcp and daemontools
The most widely recommended method for running qmail uses the daemontools and ucspi-tcp packages, both written by the author of qmail, Dr. Bernstein.
The ucspi-tcp package consists of a set of useful programs for connecting to the network and maintaining simple databases of environment-variable/connection rules. For example, tcpserver is included as part of ucspi-tcp.
The daemontools package contains the svscan/supervise programs for running, monitoring, and controlling long-running programs (daemons), and for connecting them to safe logging mechanisms (e.g. multilog). The default installation of daemontools creates a /service directory. To control a daemon with svscan, add a directory for that daemon to the /service directory. The svscan program starts up an instance of the supervise program for each subdirectory of the /service directory. Each of these directories must contain a shell script named run that contains all the necessary commands for starting the specific daemon. The run script must not exit until the daemon it commands exits. When the run script exits, the directory's supervise process restarts it, unless the supervise process has been told not to do so (for e.g. by placing a file named down in the subdirectory).
The combination of these two packages is a powerful setup for controlling, monitoring, and maintaining a qmail server.
[edit] Installation
Installing these packages is very simple. The ucspi-tcp package can be installed by simply downloading it (http://cr.yp.to/ucspi-tcp/ucspi-tcp-0.88.tar.gz), decompressing it, and running make setup check in the decompressed source directory.
The daemontools' installation is slightly more complicated.
1. You must create a /package directory:
mkdir -p /package chmod 1755 /package cd /package
2. Download the daemontools source into this /package directory, decompress it, and move into the resulting folders, as follows:
wget http://cr.yp.to/daemontools/daemontools-0.76.tar.gz tar xzvf daemontools-0.76.tar.gz rm daemontools-0.76.tar.gz cd admin/daemontools-0.76
3. Compile and install the daemontools programs:
./package/install
4. If you're on a BSD system, reboot to start up the svscan program, or run it manually as follows:
csh -cf '/command/svscanboot &'
If you're using a system that uses /etc/inittab, you should add svscanboot to the /etc/inittab, for example, with a line similar to the following:
SV:123456:respawn:/command/svscanboot
[edit] Using tcpserver
Basic use of the tcpserver program from the ucspi-tcp package has been covered previously. However, the tcpserver program has many options that are of importance to a well-maintained qmail installation. There are two main areas where tcpserver shines and is often configured according to the system-administrator's personal preference. The first is in data collection; the second is in setting appropriate environment variables and asserting behaviors based on which remote system connects to tcpserver.
The tcpserver program can collect some basic information about the remote server, as described by the possible environment variables in the previous table. However, in many cases, such information is either irrelevant or unnecessary, and the collection of such data can be eliminated to improve connection latency. For example, looking up the remote host's IP address in DNS or attempting to make an ident query to identify the remote user may not provide much benefit, but does slow down connection attempts. Turning off such queries may improve initial connection latency, if that is a concern.
For example, by default, tcpserver looks up the remote host's hostname in DNS. If this is unnecessary, giving tcpserver the -H flag prevents this, and consequently prevents tcpserver from providing the TCPREMOTEHOST environment variable to whatever program it runs (e.g. qmail-smtpd). Similarly, if ident information is unnecessary, giving tcpserver the -R flag will prevent it from performing that query.
The tcpserver program can also be configured to use a small database (in CDB format) of rules defining when to allow or deny connections and which (if any) environment variables to set, based on the data it knows about the remote host.
The most common method of specifying these connection rules is to create a text file, /etc/tcp.smtp, in a specific format that is compiled by the tcprules program into the CDB database used by tcpserver (e.g. /etc/tcp.smtp.cdb). The format of a rule in a tcprules file (such as /etc/tcp.smtp) is:
matcher : decision , environment-variables (if any)
Connection rules are matched on a first-match-wins basis. For example:
192.168.1.2:deny 192.168.1.:allow,RELAYCLIENT="" =www.example.com:allow,RELAYCLIENT="" =:allow :deny
This rule file would deny all connections from the 192.168.1.2 IP address, but would allow anything else in the 192.168.1.x IP range to connect and would set the RELAYCLIENT environment variable for those connections. If the DNS hostname of the remote host is www.example.com, this file allows that host to connect and sets the RELAYCLIENT environment variable. Any other host that has a hostname (denoted by the = sign) is allowed to connect, and finally any other connection attempt (i.e. from a host without a hostname) is rejected.
This rule file can be compiled into a CDB database file as follows:
tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp
The tcpserver program can then be told to use that CDB database by giving it the -x flag with the name of the CDB file, for example:
tcpserver -u `id -u qmaild` -g `id -g qmaild` \ -x /etc/tcp.smtp.cdb \ 0 smtp /var/qmail/bin/qmail-smtpd
[edit] Using svscan
The basic format of a supervise-controlled service is a folder containing a shell script named run. This shell script eventually must run the service (daemon) that is to be controlled and must not exit until that daemon does. A good example of what might go into a run file is the /var/qmail/rc script built as part of the previously discussed basic qmail install. This script prepares qmail to run, and then runs it. As long as qmail-start is still running, the script does not exit. Thus, a very simple service folder for the delivery side of qmail is a folder containing that rc file, renamed run.
[edit] Logging
An extension to the previously described basic service-directory format is possible. The extension is to add a folder named log within the daemon's directory, which contains another shell script named run. In this extension, the standard output of the first first-level run file is piped as input to the log directory's run file. In this way, the daemon can be stopped and started independently of the logging mechanism, which can be any logging mechanism that accepts standard input, such as splogger or something similar. An easy, powerful method of logging is the multilog program (a part of the daemontools package), which saves log output in a crash-resistant, automatically rotating manner with high-precision timestamps.
Ordinarily, qmail-start uses the logging mechanism specified in the rc file, usually splogger. However, if the rc file (and thus, qmail-start) is controlled by svscan, it can be more useful to remove the logging argument from the rc file. This change causes qmail-send's log messages to be sent to standard output, which can then be used by svscan's more flexible logging architecture. There's no benefit from this if you are using the splogger utility, but more powerful logging tools, such as multilog, do benefit from the change. The run file for the qmail-send service directory might look something like the following:
#!/bin/sh exec env - PATH="/var/qmail/bin:$PATH" \ qmail-start ./Mailbox
A log/run file for the qmail-send service directory might look similar to the following:
#!/bin/sh exec setuidgid qmaill multilog t /var/log/qmail/qmail-send/
The beginning of this command, setuidgid qmaill uses the setuidgid tool from the ucspi-tcp package. The previous command is essentially equivalent to the following:
exec su qmaill -c 'multilog t /var/log/qmail/qmail-send/'
This is because both switch to a different user (qmaill) before running the rest of the command, but the setuidgid version is easier to read and type. The reason for using the qmaill user for logging is that it prevents the logs from being altered even if an attacker controls the process generating the logs (qmail-send, in this case).
This same structure can be used for running qmail-smtpd in a controllable, monitorable fashion. Simply create a directory for it (e.g. /var/qmail/supervise/smtpd) and create a run file for it, such as:
#!/bin/sh QUID=`id -u qmaild` QGID=`id -g qmaild` LOCAL=`head -1 /var/qmail/control/me` if [ ! f /var/qmail/control/rcpthosts ]; then echo "Without a rcpthosts file, qmail is an open relay." echo "Open relays are spammer havens." echo "Please use a rcpthosts file." exit 1 fi exec tcpserver -R -l "$LOCAL" -H \ -x /etc/tcp.smtp.cdb \ -u "$QUID" -g "$QGID" \ 0 smtp \ /var/qmail/bin/qmail-smtpd 2>&1
Then create in that directory another directory named log, and in the log directory, a run file such as:
#!/bin/sh exec setuidgid qmail multilog t /var/log/qmail/smtpd/
Once these files are created, telling svscan to use them to control the service they specify is a two-step process. First, make sure that the run files are executable:
chmod +x /var/qmail/supervise/smtpd/run chmod +x /var/qmail/supervise/smtpd/log/run
Then link the daemon's directory into /service, as follows:
ln -s /var/qmail/supervise/smtpd /service/qmail-smtpd
Wait a few moments, and then run the following to double-check that all is well.
svstat /service/qmail-smtpd
If it started as it should, the output of that command should indicate that the service in question (qmail-smtpd) has been running for a few seconds already. You can perform essentially the same procedure on the qmail-start service directory, or any other daemon to be controlled by svscan.
Once svscan is controlling a folder and the associated daemon, you can command the daemon with the svc command. For example:
svc -d /service/qmail-smtpd
This will order the qmail-smtpd service to stop by sending it a TERM signal. Using the -h flag instead of -d will cause the service to receive a HUP signal; in the case of qmail-start, this causes qmail to re-read many of its configuration files. This reread-config-on-HUP is a behavior shared by many UNIX daemons. The -u flag will cause the service to start again after having been stopped by the -d flag. The -t flag, like the -d flag, also sends a TERM signal. However, unlike the -d flag, the service is restarted as soon as it exits.
It is important to note that the TERM signal sent by the -t and -d flags does not cause all daemons to exit immediately. For example, when qmail-send receives a TERM signal, it finishes all deliveries currently in progress before exitingwhich means that it may take several minutes to exit. To bring a daemon down immediately, use the -k flag, which sends the un-ignorable KILL signal. Note, though, that while the KILL signal will immediately terminate any process not protected by the kernel, the signal is not propagated to any of the daemon's child processes. Also, the -k flag alone allows the server to restart once it exits (similar to the -t flag). Thus, it is often used after the -d flag has been used first, to terminate a recalcitrant daemon.
[edit] Source
The content was taken from Qmail Quickstarter: Install, Set Up and Run your own Email Server Chapter 1: Basic QMail. The book is available from Packt Publishing.
