See http://cr.yp.to/qmail/faq.html for newer FAQs not included in this
document, and http://qmail.org/ for qmail community contributions.

1. Controlling the appearance of outgoing messages
1.1. How do I set up host masquerading?
1.2. How do I set up user masquerading?
1.3. How do I set up Mail-Followup-To automatically?

2. Routing outgoing messages
2.1. How do I send local messages to another host?
2.2. How do I set up a null client?
2.3. How do I send outgoing mail through UUCP?
2.4. How do I set up a separate queue for a SLIP/PPP link?
2.5. How do I deal with ``CNAME lookup failed temporarily''?

3. Routing incoming messages by host
3.1. How do I receive mail for another host name?
3.2. How do I set up a virtual domain?
3.3. How do I set up several virtual domains for one user?

4. Routing incoming messages by user
4.1. How do I forward unrecognized usernames to another host?
4.2. How do I set up a mailing list?
4.3. How do I use majordomo with qmail?
4.4. How do I use procmail with qmail?
4.5. How do I use elm's filter with qmail?
4.6. How do I create aliases with dots?
4.7. How do I use sendmail's .forward files with qmail?
4.8. How do I use sendmail's /etc/aliases with qmail?
4.9. How do I make qmail defer messages during NFS or NIS outages?
4.10. How do I change which account controls an address?

5. Setting up servers
5.1. How do I run qmail-smtpd under tcpserver?
5.2. How do I set up qmail-qmtpd?
5.3. How do I set up qmail-pop3d?
5.4. How do I allow selected clients to use this host as a relay?
5.5. How do I fix up messages from broken SMTP clients?
5.6. How do I set up qmail-qmqpd?

6. Configuring MUAs to work with qmail
6.1. How do I make BSD mail generate a Date with the local time zone?
6.2. How do I make pine work with qmail?
6.3. How do I make MH work with qmail?
6.4. How do I stop Sun's dtcm from hanging?

7. Managing the mail system
7.1. How do I safely stop qmail-send?
7.2. How do I manually run the queue?
7.3. How do I rejuvenate a message?
7.4. How do I organize a big network?
7.5. How do I back up and restore the queue disk?
7.6. How do I run a supervised copy of qmail?
7.7. How do I avoid syslog?

8. Miscellany
8.1. How do I tell qmail to do more deliveries at once?
8.2. How do I keep a copy of all incoming and outgoing mail messages?
8.3. How do I switch slowly from sendmail to qmail?



1. Controlling the appearance of outgoing messages


1.1. How do I set up host masquerading? All the users on this host,
zippy.af.mil, are users on af.mil. When joe sends a message to fred, the
message should say ``From: joe@af.mil'' and ``To: fred@af.mil'', without
``zippy'' anywhere.

Answer: echo af.mil > /var/qmail/control/defaulthost; chmod 644
/var/qmail/control/defaulthost.


1.2. How do I set up user masquerading? I'd like my own From lines to
show boss@af.mil rather than god@heaven.af.mil.

Answer: Add MAILHOST=af.mil and MAILUSER=boss to your environment. To
override From lines supplied by your MUA, add QMAILINJECT=f to your
environment.


1.3. How do I set up Mail-Followup-To automatically? When I send a
message to the sos@heaven.af.mil mailing list, I'd like to include
``Mail-Followup-To: sos@heaven.af.mil''.

Answer: Add QMAILMFTFILE=$HOME/.lists to your environment, and put
sos@heaven.af.mil into ~/.lists.



2. Routing outgoing messages


2.1. How do I send local messages to another host? All the mail for
af.mil should be delivered to our disk server, pokey.af.mil. I've set up
an MX from af.mil to pokey.af.mil, but when a user on the af.mil host
sends a message to boss@af.mil, af.mil tries to deliver it locally. How
do I stop that?

Answer: Remove af.mil from /var/qmail/control/locals. If qmail-send is
running, give it a HUP. Make sure the MX is set up properly before you
do this. Also make sure that pokey can receive mail for af.mil---see
question 3.1.


2.2. How do I set up a null client? I'd like zippy.af.mil to
send all mail to bigbang.af.mil.

Answer: echo :bigbang.af.mil > /var/qmail/control/smtproutes;
chmod 644 /var/qmail/control/smtproutes. Disable local delivery as in
question 2.1. Turn off qmail-smtpd in /etc/inetd.conf.


2.3. How do I send outgoing mail through UUCP? I need qmail to send all
outgoing mail via UUCP to my upstream UUCP site, gonzo.

Answer: Put

   :alias-uucp

into control/virtualdomains and

   |preline -df /usr/bin/uux - -r -gC
      -a"${SENDER:-MAILER-DAEMON}" gonzo!rmail "($DEFAULT@$HOST)"

(all on one line) into ~alias/.qmail-uucp-default. (For some UUCP
software you will need to use -d instead of -df.) If qmail-send is
running, give it a HUP.


2.4. How do I set up a separate queue for a SLIP/PPP link?

Answer: Use serialmail (http://pobox.com/~djb/serialmail.html).


2.5. How do I deal with ``CNAME lookup failed temporarily''? The log
showed that a message was deferred for this reason. Why is qmail doing
CNAME lookups, anyway?

Answer: The SMTP standard does not permit aliased hostnames, so qmail
has to do a CNAME lookup in DNS for every recipient host. If the
relevant DNS server is down, qmail defers the message. It will try again
soon.



3. Routing incoming messages by host


3.1. How do I receive mail for another host name? I'd like our disk
server, pokey.af.mil, to receive mail addressed to af.mil. I've set up
an MX from af.mil to pokey.af.mil, but how do I get pokey to treat
af.mil as a name for the local host?

Answer: Add af.mil to /var/qmail/control/locals and to
/var/qmail/control/rcpthosts. If qmail-send is running, give it a HUP
(or do svc -h /var/run/qmail if qmail is supervised).


3.2. How do I set up a virtual domain? I'd like any mail for
nowhere.mil, including root@nowhere.mil and postmaster@nowhere.mil and
so on, to be delivered to Bob. I've set up the MX already.

Answer: Put

   nowhere.mil:bob

into control/virtualdomains. Add nowhere.mil to control/rcpthosts. If
qmail-send is running, give it a HUP (or do svc -h /var/run/qmail if
qmail is supervised).

Now mail for whatever@nowhere.mil will be delivered locally to
bob-whatever. Bob can set up ~bob/.qmail-default to catch all the
possible addresses, ~bob/.qmail-info to catch info@nowhere.mil, etc.


3.3. How do I set up several virtual domains for one user? Bob wants
another virtual domain, everywhere.org, but he wants to handle
nowhere.mil users and everywhere.org users differently. How can we do
that without setting up a second account?

Answer: Put two lines into control/virtualdomains:

   nowhere.mil:bob-nowhere
   everywhere.org:bob-everywhere

Add nowhere.mil and everywhere.org to control/rcpthosts. If qmail-send
is running, give it a HUP (or do svc -h /var/run/qmail if qmail is
supervised).

Now Bob can set up separate .qmail-nowhere-* and everywhere-* files. He
can even set up .qmail-nowhere-default and .qmail-everywhere-default.



4. Routing incoming messages by user


4.1. How do I forward unrecognized usernames to another host? I'd like
to set up a LUSER_RELAY pointing at bigbang.af.mil.

Answer: Put

   | forward "$LOCAL"@bigbang.af.mil

into ~alias/.qmail-default.


4.2. How do I set up a mailing list? I'd like me-sos@my.host.name to be
forwarded to a bunch of people.

Answer: Put a list of addresses into ~me/.qmail-sos, one per line. Then
incoming mail for me-sos will be forwarded to each of those addresses.
You should also touch ~me/.qmail-sos-owner so that bounces come back to
you rather than the original sender.

Alternative: ezmlm (http://pobox.com/~djb/ezmlm.html) is a modern
mailing list manager, supporting automatic subscriptions, confirmations,
archives, fully automatic bounce handling (including warnings to
subscribers saying which messages they've missed), and more.


4.3. How do I use majordomo with qmail?

Answer: See ftp://ftp.eyrie.org/pub/software/majordomo/mjqmail and
http://www.qmail.org for various methods. majordomo 2.0 is expected to
support qmail directly.

Beware that majordomo's lists are not crashproof.



4.4. How do I use procmail with qmail?

Answer: Put 

   | preline procmail

into ~/.qmail. You'll have to use a full path for procmail unless
procmail is in the system's startup PATH. Note that procmail will try to
deliver to /var/spool/mail/$USER by default; to change this, see
INSTALL.mbox.


4.5. How do I use elm's filter with qmail?

Answer: Put 

   | preline filter

into ~/.qmail. You'll have to use a full path for filter unless filter
is in the system's startup PATH.


4.6. How do I create aliases with dots? I tried setting up
~alias/.qmail-P.D.Q.Bach, but it doesn't do anything.

Answer: Use .qmail-p:d:q:bach. Dots are converted to colons, and
uppercase is converted to lowercase.


4.7. How do I use sendmail's .forward files with qmail?

Answer: Install the dot-forward package
(http://pobox.com/~djb/dot-forward.html).


4.8. How do I use sendmail's /etc/aliases with qmail?

Answer: Install the fastforward package
(http://pobox.com/~djb/fastforward.html).


4.9. How do I make qmail defer messages during NFS or NIS outages? If
~joe suddenly disappears, I'd like mail for joe to be deferred.

Answer: Build a qmail-users database, so that qmail no longer checks
home directories and the password database. This takes three steps.
First, put your complete user list (including local and NIS passwords)
into /var/qmail/users/passwd. Second, run

   # qmail-pw2u -h < /var/qmail/users/passwd > /var/qmail/users/assign

Here -h means that every user must have a home directory; if you happen
to run qmail-pw2u during an NFS outage, it will print an error message
and stop. Third, run

   # qmail-newu

Make sure to rebuild the database whenever you change your user list.


4.10. How do I change which account controls an address? I set up
~alias/.qmail-www, but qmail is looking at ~www/.qmail instead.

Answer: If you do

   # chown root ~www

then qmail will no longer consider www to be a user; see qmail-getpw.0.
For more precise control over address assignments, see qmail-users.0.



5. Setting up servers


5.1. How do I run qmail-smtpd under tcpserver? inetd is barfing at high
loads, cutting off service for ten-minute stretches. I'd also like
better connection logging.

Answer: First, install the tcpserver program, part of the ucspi-tcp
package (http://pobox.com/~djb/ucspi-tcp.html). Second, remove the smtp
line from /etc/inetd.conf, and put the line

   tcpserver -u 7770 -g 2108 0 smtp /var/qmail/bin/qmail-smtpd &

into your system startup files. Replace 7770 with your qmaild uid, and
replace 2108 with your nofiles gid. Don't forget the &. The change will
take effect at your next reboot.

By default, tcpserver allows at most 40 simultaneous qmail-smtpd
processes. To raise this limit to 400, use tcpserver -c 400. To keep
track of who's connecting and for how long, run (on two lines)

   tcpserver -v -u 7770 -g 2108 0 smtp /var/qmail/bin/qmail-smtpd \
   2>&1 | /var/qmail/bin/splogger smtpd 3 &


5.2. How do I set up qmail-qmtpd?

Answer: Two steps. First, put a

   qmtp 209/tcp

line into /etc/services. Second, put (all on one line)

   qmtp stream tcp nowait qmaild
   /var/qmail/bin/tcp-env tcp-env /var/qmail/bin/qmail-qmtpd

into /etc/inetd.conf, and give inetd a HUP.

If you have tcpserver installed, skip the inetd step, and set up

   tcpserver -u 7770 -g 2108 0 qmtp /var/qmail/bin/qmail-qmtpd &

replacing 7770 and 2108 with the qmaild uid and nofiles gid. See
question 5.1 for more details on tcpserver.


5.3. How do I set up qmail-pop3d? My old POP server works with mbox
delivery; I'd like to switch to maildir delivery.

Answer: Four steps. First, install the checkpassword program
(http://pobox.com/~djb/checkpwd.html). Second, make sure you have a

   pop3 110/tcp

line in /etc/services. Third, put (all on one line, including
qmail-popup twice)

   pop3 stream tcp nowait root
   /var/qmail/bin/qmail-popup qmail-popup
   YOURHOST /bin/checkpassword /var/qmail/bin/qmail-pop3d Maildir

into /etc/inetd.conf, and give inetd a HUP; replace YOURHOST with your
host's fully qualified domain name. Fourth, set up Maildir delivery for
any user who wants to read mail via POP.

If you have tcpserver installed, skip the inetd step, and set up (on two
lines)

   tcpserver 0 pop3 /var/qmail/bin/qmail-popup YOURHOST \
   /bin/checkpassword /var/qmail/bin/qmail-pop3d Maildir &

replacing YOURHOST with your host's fully qualified domain name. See
question 5.1 for more details on tcpserver.

Security note: pop3d should be used only within a secure network;
otherwise an eavesdropper can steal passwords.


5.4. How do I allow selected clients to use this host as a relay? I see
that qmail-smtpd rejects messages to any host not listed in
control/rcpthosts.

Answer: Three steps. First, install tcp-wrappers, available separately,
including hosts_options. Second, change your qmail-smtpd line in
inetd.conf to

   smtp stream tcp nowait qmaild /usr/local/bin/tcpd
   /var/qmail/bin/tcp-env /var/qmail/bin/qmail-smtpd

(all on one line) and give inetd a HUP. Third, in tcpd's hosts.allow,
make a line setting the environment variable RELAYCLIENT to the empty
string for the selected clients:

   tcp-env: 1.2.3.4, 1.2.3.5: setenv = RELAYCLIENT

Here 1.2.3.4 and 1.2.3.5 are the clients' IP addresses. qmail-smtpd
ignores control/rcpthosts when RELAYCLIENT is set. (It also appends
RELAYCLIENT to each envelope recipient address.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                