1 1. Controlling the appearance of outgoing messages
2 1.1. How do I set up host masquerading?
3 1.2. How do I set up user masquerading?
5 2. Routing outgoing messages
6 2.1. How do I send local messages to another host?
7 2.2. How do I set up a null client?
8 2.3. How do I send outgoing mail through UUCP?
9 2.4. How do I set up a separate queue for a SLIP/PPP link?
10 2.5. How do I deal with ``CNAME lookup failed temporarily''?
12 3. Routing incoming messages by host
13 3.1. How do I receive mail for another host name?
14 3.2. How do I set up a virtual domain?
15 3.3. How do I set up several virtual domains for one user?
17 4. Routing incoming messages by user
18 4.1. How do I forward unrecognized usernames to another host?
19 4.2. How do I set up a mailing list?
20 4.3. How do I use majordomo with qmail?
21 4.4. How do I use procmail with qmail?
22 4.5. How do I use elm's filter with qmail?
23 4.6. How do I create aliases with dots?
26 5.1. How do I run qmail-smtpd under tcpserver?
27 5.2. How do I set up qmail-qmtpd?
28 5.3. How do I set up qmail-pop3d?
29 5.4. How do I allow selected clients to use this host as a relay?
30 5.5. How do I fix up messages from broken SMTP clients?
32 6. Configuring MUAs to work with qmail
33 6.1. How do I make BSD mail generate a Date with the local time zone?
34 6.2. How do I stop pine from crashing?
35 6.3. How do I make MH work with qmail?
36 6.4. How do I stop Sun's dtcm from hanging?
38 7. Managing the mail system
39 7.1. How do I safely stop qmail-send?
40 7.2. How do I manually run the queue?
41 7.3. How do I rejuvenate a message?
42 7.4. How do I organize a big network?
43 7.5. How do I back up and restore the queue disk?
46 8.1. How do I tell qmail to do more deliveries at once?
47 8.2. How do I keep a copy of all incoming and outgoing mail messages?
48 8.3. How do I switch slowly from sendmail to qmail?
52 1. Controlling the appearance of outgoing messages
55 1.1. How do I set up host masquerading? All the users on this host,
56 zippy.af.mil, are users on af.mil. When joe sends a message to fred, the
57 message should say ``From: joe@af.mil'' and ``To: fred@af.mil'', without
60 Answer: echo af.mil > /var/qmail/control/defaulthost; chmod 644
61 /var/qmail/control/defaulthost.
64 1.2. How do I set up user masquerading? I'd like my own From lines to
65 show boss@af.mil rather than god@heaven.af.mil.
67 Answer: Add MAILHOST=af.mil and MAILUSER=boss to your environment. To
68 override From lines supplied by your MUA, add QMAILINJECT=f to your
73 2. Routing outgoing messages
76 2.1. How do I send local messages to another host? All the mail for
77 af.mil should be delivered to our disk server, pokey.af.mil. I've set up
78 an MX from af.mil to pokey.af.mil, but when a user on the af.mil host
79 sends a message to boss@af.mil, af.mil tries to deliver it locally. How
82 Answer: Remove af.mil from /var/qmail/control/locals. If qmail-send is
83 running, give it a HUP. Make sure the MX is set up properly before you
84 do this. Also make sure that pokey can receive mail for af.mil---see
88 2.2. How do I set up a null client? I'd like zippy.af.mil to
89 send all mail to bigbang.af.mil.
91 Answer: echo :bigbang.af.mil > /var/qmail/control/smtproutes;
92 chmod 644 /var/qmail/control/smtproutes. Disable local delivery as in
93 question 2.1. Turn off qmail-smtpd in /etc/inetd.conf.
96 2.3. How do I send outgoing mail through UUCP? I need qmail to send all
97 outgoing mail via UUCP to my upstream UUCP site, gonzo.
103 into control/virtualdomains and
105 |preline -df /usr/bin/uux - -r -gC -a"$SENDER" gonzo!rmail "($EXT2@$HOST)"
107 into ~alias/.qmail-uucp-default. (For some UUCP software you will need
108 to use -d instead of -df. Also, you may need to insert a space between
109 -a and "$SENDER" for bounces to work properly.) If qmail-send is
110 running, give it a HUP.
113 2.4. How do I set up a separate queue for a SLIP/PPP link?
115 Answer: Use serialmail (http://pobox.com/~djb/serialmail.html).
118 2.5. How do I deal with ``CNAME lookup failed temporarily''? The log
119 showed that a message was deferred for this reason. Why is qmail doing
120 CNAME lookups, anyway?
122 Answer: The SMTP standard does not permit aliased hostnames, so qmail
123 has to do a CNAME lookup in DNS for every sender and recipient host. If
124 the relevant DNS server is down, qmail defers the message. It will try
129 3. Routing incoming messages by host
132 3.1. How do I receive mail for another host name? I'd like our disk
133 server, pokey.af.mil, to receive mail addressed to af.mil. I've set up
134 an MX from af.mil to pokey.af.mil, but how do I get pokey to treat
135 af.mil as a name for the local host?
137 Answer: Add af.mil to /var/qmail/control/locals and to
138 /var/qmail/control/rcpthosts. If qmail-send is running, give it a HUP.
141 3.2. How do I set up a virtual domain? I'd like any mail for
142 nowhere.mil, including root@nowhere.mil and postmaster@nowhere.mil and
143 so on, to be delivered to Bob. I've set up the MX already.
149 into control/virtualdomains. Add nowhere.mil to control/rcpthosts. If
150 qmail-send is running, give it a HUP.
152 Now mail for whatever@nowhere.mil will be delivered locally to
153 bob-whatever. Bob can set up ~bob/.qmail-default to catch all the
154 possible addresses, ~bob/.qmail-info to catch info@nowhere.mil, etc.
157 3.3. How do I set up several virtual domains for one user? Bob wants
158 another virtual domain, everywhere.org, but he wants to handle
159 nowhere.mil users and everywhere.org users differently. How can we do
160 that without setting up a second account?
162 Answer: Put two lines into control/virtualdomains:
164 nowhere.mil:bob-nowhere
165 everywhere.org:bob-everywhere
167 Add nowhere.mil and everywhere.org to control/rcpthosts. If qmail-send
168 is running, give it a HUP.
170 Now Bob can set up separate .qmail-nowhere-* and everywhere-* files. He
171 can even set up .qmail-nowhere-default and .qmail-everywhere-default.
175 4. Routing incoming messages by user
178 4.1. How do I forward unrecognized usernames to another host? I'd like
179 to set up a LUSER_RELAY pointing at bigbang.af.mil.
183 | forward "$LOCAL"@bigbang.af.mil
185 into ~alias/.qmail-default.
188 4.2. How do I set up a mailing list? I'd like me-sos@my.host.name to be
189 forwarded to a bunch of people.
191 Answer: Put a list of addresses into ~me/.qmail-sos, one per line. Then
192 incoming mail for me-sos will be forwarded to each of those addresses.
193 You should also touch ~me/.qmail-sos-owner so that bounces come back to
194 you rather than the original sender. If you want subscriptions to be
195 handled automatically, put
197 | qlist2 sos my.host.name
199 into ~me/.qmail-sos-request. Anyone who wants to subscribe can simply
200 send a message to me-sos-request@my.host.name.
203 4.3. How do I use majordomo with qmail?
205 Answer: You need to patch majordomo so that it creates qmail-style
206 lists. See ftp://koobera.math.uic.edu/pub/software/majordomo+qmail.gz.
207 Exception: qmsmac understands sendmail-style :include: files, so you
208 shouldn't patch majordomo if you're using qmsmac.
211 4.4. How do I use procmail with qmail?
217 into ~/.qmail. You'll have to use a full path for procmail unless
218 procmail is in the system's startup PATH. Note that procmail will try to
219 deliver to /usr/spool/mail/$USER by default; to change this, change
220 SYSTEM_MBOX in procmail's config.h.
223 4.5. How do I use elm's filter with qmail?
229 into ~/.qmail. You'll have to use a full path for filter unless filter
230 is in the system's startup PATH.
233 4.6. How do I create aliases with dots? I tried setting up
234 ~alias/.qmail-P.D.Q.Bach, but it doesn't do anything.
236 Answer: Use .qmail-p:d:q:bach. Dots are converted to colons, and
237 uppercase is converted to lowercase.
241 5. Setting up servers
244 5.1. How do I run qmail-smtpd under tcpserver? inetd is barfing at high
245 loads, cutting off service for ten-minute stretches. I'd also like
246 better connection logging.
248 Answer: First, install the tcpserver program, part of the ucspi-tcp
249 package (http://pobox.com/~djb/ucspi-tcp.html). Second, remove the smtp
250 line from /etc/inetd.conf, and put the line
252 tcpserver -u 7770 -g 2108 0 smtp /var/qmail/bin/qmail-smtpd &
254 into your system startup files. Replace 7770 with your qmaild uid, and
255 replace 2108 with your nofiles gid. Don't forget the &. The change will
256 take effect at your next reboot.
258 By default, tcpserver allows at most 40 simultaneous qmail-smtpd
259 processes. To raise this limit to 400, use tcpserver -c 400. To keep
260 track of who's connecting and for how long, run (on two lines)
262 tcpserver -v -u 7770 -g 2108 0 smtp /var/qmail/bin/qmail-smtpd \
263 2>&1 | /var/qmail/bin/splogger smtpd 3 &
266 5.2. How do I set up qmail-qmtpd?
268 Answer: Two steps. First, put a
272 line into /etc/services. Second, put (all on one line)
274 qmtp stream tcp nowait qmaild
275 /var/qmail/bin/tcp-env tcp-env /var/qmail/bin/qmail-qmtpd
277 into /etc/inetd.conf, and give inetd a HUP.
279 If you have tcpserver installed, skip the inetd step, and set up
281 tcpserver -u 7770 -g 2108 0 qmtp /var/qmail/bin/qmail-qmtpd &
283 replacing 7770 and 2108 with the qmaild uid and nofiles gid. See
284 question 5.1 for more details.
287 5.3. How do I set up qmail-pop3d?
289 Answer: Four steps. First, install the checkpassword program
290 (http://pobox.com/~djb/checkpwd.html). Second, make sure you have a
294 line in /etc/services. Third, put (all on one line)
296 pop3 stream tcp nowait root /var/qmail/bin/qmail-popup
297 qmail-popup YOURHOST /bin/checkpassword /var/qmail/bin/qmail-pop3d Maildir
299 into /etc/inetd.conf, and give inetd a HUP; replace YOURHOST with your
300 host's fully qualified domain name. Fourth, set up Maildir delivery for
301 any user who wants to read mail via POP.
303 If you have tcpserver installed, skip the inetd step, and set up (on two
306 tcpserver 0 pop3 /var/qmail/bin/qmail-popup YOURHOST \
307 /bin/checkpassword /var/qmail/bin/qmail-pop3d Maildir &
309 replacing YOURHOST with your host's fully qualified domain name. See
310 question 5.1 for more details.
312 Security note: pop3d should be used only within a secure network;
313 otherwise an eavesdropper can steal passwords.
316 5.4. How do I allow selected clients to use this host as a relay? I see
317 that qmail-smtpd rejects messages to any host not listed in
318 control/rcpthosts. I know I could entirely disable this feature by
319 removing control/rcpthosts, but I want to be more selective.
321 Answer: Three steps. First, install tcp-wrappers, available separately,
322 including hosts_options. Second, change your qmail-smtpd line in
325 smtp stream tcp nowait qmaild /usr/local/bin/tcpd
326 /var/qmail/bin/tcp-env /var/qmail/bin/qmail-smtpd
328 (all on one line) and give inetd a HUP. Third, in tcpd's hosts.allow,
329 make a line setting the environment variable RELAYCLIENT to the empty
330 string for the selected clients:
332 tcp-env: 1.2.3.4, 1.2.3.5: setenv = RELAYCLIENT
334 Here 1.2.3.4 and 1.2.3.5 are the clients' IP addresses. qmail-smtpd
335 ignores control/rcpthosts when RELAYCLIENT is set. (It also appends
336 RELAYCLIENT to each envelope recipient address. See question 5.5 for an
339 Alternative procedure, if you are using tcpserver: Install tcpcontrol
340 (http://pobox.com/~djb/tcpcontrol.html). Create /etc/tcp.smtp containing
342 1.2.3.6:allow,RELAYCLIENT=""
343 127.:allow,RELAYCLIENT=""
345 to allow clients with IP addresses 1.2.3.6 and 127.*. Run
347 tcpmakectl /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp
351 tcpcontrol /etc/tcp.smtp.cdb
353 before /var/qmail/bin/qmail-smtpd in your tcpserver line.
356 5.5. How do I fix up messages from broken SMTP clients?
358 Answer: Three steps. First, put
360 | [ "@$HOST" = "@fixme" ] || ( echo Permission denied; exit 100 )
361 | qmail-inject -f "$SENDER" -- "$EXT2"
363 into ~alias/.qmail-fixup-default. Second, put
367 into /var/qmail/control/virtualdomains, and give qmail-send a HUP.
368 Third, follow the procedure in question 5.4, but set RELAYCLIENT to the
371 tcp-env: 1.2.3.6, 1.2.3.7: setenv = RELAYCLIENT @fixme
373 Here 1.2.3.6 and 1.2.3.7 are the clients' IP addresses. If you are using
374 tcpserver and tcpcontrol instead of inetd and tcpd, put
376 1.2.3.6:allow,RELAYCLIENT="@fixme"
377 1.2.3.7:allow,RELAYCLIENT="@fixme"
379 into /etc/tcp.smtp, and run tcpmakectl as in question 5.4.
383 6. Configuring MUAs to work with qmail
386 6.1. How do I make BSD mail generate a Date with the local time zone?
387 When I send mail, I'd rather use the local time zone than GMT, since
388 some MUAs don't know how to display Date in the receiver's time zone.
392 set sendmail=/var/qmail/bin/datemail
394 into your .mailrc or your system-wide Mail.rc. Beware that BSD mail is
395 neither secure nor reliable.
398 6.2. How do I stop pine from crashing? When I ask any version of pine
399 past 3.91 to send mail, it crashes.
403 sendmail-path=/usr/lib/sendmail -oem -oi -t
405 into /usr/local/lib/pine.conf. (This will work with sendmail too.)
406 Beware that pine is neither secure nor reliable.
409 6.3. How do I make MH work with qmail?
413 postproc: /usr/mh/lib/spost
415 into each user's .mh_profile. (This will work with sendmail too.) Beware
416 that MH is neither secure nor reliable.
419 6.4. How do I stop Sun's dtcm from hanging?
421 Answer: There is a novice programming error in dtcm, known as ``failure
422 to close the output side of the pipe in the child.'' Sun has, at the
423 time of this writing, not yet provided a patch. Sorry.
427 7. Managing the mail system
430 7.1. How do I safely stop qmail-send? Back when we were running
431 sendmail, it was always tricky to kill sendmail without risking the loss
432 of current deliveries; what should I do with qmail-send?
434 Answer: Go ahead and kill the qmail-send process. It will shut down
435 cleanly. Wait for ``exiting'' to show up in the log. To restart it, run
436 qmail-start the same way as it's run from your system boot scripts.
439 7.2. How do I manually run the queue? I'd like qmail to try delivering
440 all the remote messages right now.
442 Answer: Give the qmail-send process an ALRM.
445 7.3. How do I rejuvenate a message? Somebody broke into Eric's computer
446 again; it's going to be down for at least another two days. I know Eric
447 has been expecting an important message---in fact, I see it sitting here
448 in /var/qmail/queue/mess/15/26902. It's been in the queue for six days;
449 how can I make sure it isn't bounced tomorrow?
451 Answer: Just touch /var/qmail/queue/info/15/26902. (This is the only
452 form of queue modification that's safe while qmail is running.)
455 7.4. How do I organize a big network? I have a lot of machines, and I
456 don't know where to start.
458 Answer: First, choose the domain name where your users will receive
459 mail. This is normally the shortest domain name you control. If you are
460 in charge of *.movie.edu, you can use addresses like joe@movie.edu.
462 Second, choose the machine that will know what to do with different
463 users at movie.edu. Set up a host name in DNS for this machine:
465 mailhost.movie.edu IN A 1.2.3.4
466 4.3.2.1.in-addr.arpa IN PTR mailhost.movie.edu
468 Here 1.2.3.4 is the IP address of that machine.
470 Third, make a list of machines where mail should end up. For example, if
471 mail for Bob should end up on Bob's workstation, put Bob's workstation
472 onto the list. For each of these machines, set up a host name in DNS:
474 bobshost.movie.edu IN A 1.2.3.7
475 7.3.2.1.in-addr.arpa IN PTR bobshost.movie.edu
477 Fourth, install qmail on bobshost.movie.edu. qmail will automatically
478 configure itself to accept messages for bob@bobshost.movie.edu and
479 deliver them to ~bob/Mailbox on bobshost. Do the same for the other
480 machines where mail should end up.
482 Fifth, install qmail on mailhost.movie.edu. Put
484 movie.edu:alias-movie
486 into control/virtualdomains on mailhost. Then forward bob@movie.edu to
487 bob@bobshost.movie.edu, by putting
489 bob@bobshost.movie.edu
491 into ~alias/.qmail-movie-bob. Do the same for other users.
493 Sixth, put movie.edu into control/rcpthosts on mailhost.movie.edu, so
494 that mailhost.movie.edu will accept messages for users at movie.edu.
496 Seventh, set up an MX record in DNS to deliver movie.edu messages to
499 movie.edu IN MX 10 mailhost.movie.edu
501 Eighth, on all your machines, put movie.edu into control/defaulthost.
504 7.5. How do I back up and restore the queue disk?
508 One difficulty is that you can't get a consistent snapshot of the queue
509 while qmail-send is running. Another difficulty is that messages in the
510 queue must have filenames that match their inode numbers.
512 However, the big problem is that backups---even twice-daily backups---
513 are far too unreliable for mail. If your disk dies, there will be very
514 little overlap between the messages saved in the last backup and the
515 messages that were lost.
517 There are several ways to add real reliability to a mail server. Battery
518 backups will keep your server alive, letting you park the disk to avoid
519 a head crash, when the power goes out. Solid-state disks have their own
520 battery backups. RAID boxes let you replace dead disks without losing
528 8.1. How do I tell qmail to do more deliveries at once? It's running
529 only 20 parallel qmail-remote processes.
531 Answer: Decide how many deliveries you want to allow at once. Put that
532 number into control/concurrencyremote. Restart qmail-send as in question
533 7.1. If your system has resource limits, make sure you set the
534 descriptors limit to at least double the concurrency plus 5; otherwise
535 you'll get lots of unnecessary deferrals whenever a big burst of mail
536 shows up. Note that qmail also imposes a compile-time concurrency limit,
537 120 by default; this is set in conf-spawn.
540 8.2. How do I keep a copy of all incoming and outgoing mail messages?
542 Answer: Set QUEUE_EXTRA to "Tlog\0" and QUEUE_EXTRALEN to 5 in extra.h.
543 Recompile qmail. Put ./msg-log into ~alias/.qmail-log.
545 You can also use QUEUE_EXTRA to, e.g., record the Message-ID of every
548 | awk '/^$/ { exit } /^[mM][eE][sS][sS][aA][gG][eE]-/ { print }'
550 from ~alias/.qmail-log.
553 8.3. How do I switch slowly from sendmail to qmail? I'm thinking of
554 moving the heaven.af.mil network over to qmail, but first I'd like to
555 give my users a chance to try out qmail without affecting current
556 sendmail deliveries. We're using NFS.
558 Answer: Find a host in your network, say pc.heaven.af.mil, that isn't
559 running an SMTP server. (If addresses at pc.heaven.af.mil are used, you
560 should already have an MX pointing pc.heaven.af.mil to your mail hub.)
562 Set up a new MX record pointing lists.heaven.af.mil to pc.heaven.af.mil.
563 Install qmail on pc.heaven.af.mil. Replace pc with lists in the control
564 files. Make the qmail man pages available on all your machines.
566 Now tell your users about qmail. A user can forward joe@heaven.af.mil to
567 joe@lists.heaven.af.mil to get ~/Mailbox delivery; he can set up .qmail
568 files; he can start running his own mailing lists @lists.heaven.af.mil.
570 When you're ready to turn sendmail off, you can set up pc.heaven.af.mil
571 as your new mail hub. Add heaven.af.mil to control/locals, and change
572 the heaven.af.mil MX to point to pc.heaven.af.mil. Make sure you leave
573 lists.heaven.af.mil in control/locals so that transition addresses will