1 <!doctype HTML public "-//W3O//DTD W3 HTML 3.2//EN">
4 <TITLE>The Fetchmail FAQ</TITLE>
5 <link rev=made href="mailto:esr@snark.thyrsus.com">
6 <meta name="description" content="Frequently asked questions about fetchmail.">
7 <meta name="keywords" content="fetchmail, POP, POP2, POP3, IMAP, remote mail">
10 <table width="100%" cellpadding=0><tr>
11 <td width="30%">Back to <a href="index.html">Fetchmail Home Page</a>
12 <td width="30%" align=center>To <a href="/~esr/sitemap.html">Site Map</a>
13 <td width="30%" align=right>$Date: 1997/11/22 07:26:00 $
16 <H1>Frequently Asked Questions About Fetchmail</H1>
18 Before reporting any bug, please read <a href="#G3">G3</a> for advice
19 on how to include diagnostic information that will get your bug fixed
20 as quickly as possible. <p>
22 If you have a question or answer you think ought to be added to this FAQ list,
23 mail it to fetchmail's maintainer, Eric S. Raymond, at
24 <A HREF="mailto:esr@thyrsus.com">esr@snark.thyrsus.com</A>.<p>
26 <h1>General questions:</h1>
28 <a href="#G1">G1. What is fetchmail and why should I bother?</a><br>
29 <a href="#G2">G2. Where do I find the latest FAQ and fetchmail sources?</a><br>
30 <a href="#G3">G3. I think I've found a bug. Will you fix it?</a><br>
31 <a href="#G4">G4. I have this idea for a neat feature. Will you add it?</a><br>
32 <a href="#G5">G5. Is there a mailing list for exchanging tips?</a><br>
33 <a href="#G6">G6. So, what's this I hear about a fetchmail paper?</a><br>
34 <a href="#G7">G7. What is the best server to use with fetchmail?</a><br>
35 <a href="#G8">G8. How can I avoid sending my password en clair?</a><br>
36 <a href="#G9">G9. Is any special configuration needed to use a dynamic
39 <h1>Build-time problems:</h1>
41 <a href="#B1">B1. I get link failures when I try to build fetchmail.</a><br>
43 <h1>Fetchmail configuration file grammar questions:</h1>
45 <a href="#F1">F1. Why does my old .fetchmailrc no longer work?</a><br>
46 <a href="#F2">F2. The .fetchmailrc parser won't accept my all-numeric user name.</a><br>
47 <a href="#F3">F3. The .fetchmailrc parser won't accept my host or username beginning with `no'.</a><br>
48 <a href="#F4">F4. I'm migrating from popclient. How do I need to modify my .poprc?</a><br>
50 <h1>Configuration questions:</h1>
52 <a href="#C1">C1. Why do I need a .fetchmailrc when running as root on my own machine?</a><br>
53 <a href="#C2">C2. How can I arrange for a fetchmail daemon to get killed when I log out?</a><br>
54 <a href="#C3">C3. How do I know what interface and address to use with --interface?</a><br>
55 <a href="#C4">C4. How can I get fetchmail to work with ssh?</a><br>
56 <a href="#C5">C5. How can I set up support for sendmail's anti-spam 571 response?</a><br>
57 <a href="#C6">C6. How can I do automatic startup/shutdown of fetchmail
58 when I may have multiple login sessions going?</a><br>
60 <h1>Configuration tips for various MTAs and servers.</h1>
62 <a href="#T1">T1. How can I use fetchmail with sendmail?</a><br>
63 <a href="#T2">T2. How can I use fetchmail with qmail?</a><br>
64 <a href="#T3">T3. How can I use fetchmail with exim?</a><br>
65 <a href="#T4">T4. How can I use fetchmail with smail?</a><br>
66 <a href="#T5">T5. How can I use fetchmail with SCO's MMDF?</a><br>
67 <a href="#T6">T6. How can I use fetchmail with Lotus Notes?</a><br>
68 <a href="#T7">T7. How can I use fetchmail with Microsoft Exchange?</a><br>
69 <a href="#T8">T8. How can I use fetchmail with Compuserve RPA?</a><br>
70 <a href="#T9">T9. How can I use fetchmail with HP OpenMail?</a><br>
72 <h1>Runtime fatal errors:</h1>
74 <a href="#R1">R1. Fetchmail's initial gethostbyname call fails on my host.</a><br>
75 <a href="#R2">R2. Fetchmail isn't working, and -v shows `SMTP connect failed' messages.</a><br>
76 <a href="#R3">R3. When I try to configure an MDA, fetchmail doesn't work.</a><br>
77 <a href="#R4">R4. Fetchmail dumps core when given an invalid rc file.</a><br>
78 <a href="#R5">R5. Fetchmail dumps core in -V mode, but operates normally otherwise.</a><br>
79 <a href="#R6">R6. Fetchmail dumps core when I use a .netrc file but works otherwise.</a><br>
80 <a href="#R7">R7. Running fetchmail in daemon mode doesn't work.</a><br>
82 <h1>Disappearing mail</h1>
84 <a href="#D1">D1. I think I've set up fetchmail correctly, but I'm not getting any mail.</a><br>
85 <a href="#D2">D2. All my mail seems to disappear after an interrupt.</a><br>
86 <a href="#D3">D3. Mail that was being fetched when I interrupted my fetchmail seems to have been vanished.</a></br>
88 <h1>Multidrop-mode problems:</h1>
90 <a href="#M1">M1. I've declared local names, but all my multidrop mail is going to root anyway.</a><br>
91 <a href="#M2">M2. I can't seem to get fetchmail to route to a local domain properly.</a><br>
92 <a href="#M3">M3. I tried to run a mailing list using multidrop, and I have a mail loop!</a><br>
93 <a href="#M4">M4. My multidrop fetchmail seems to be having DNS problems.</a><br>
94 <a href="#M5">M5. I'm seeing long DNS delays before each message is processed.</a><br>
95 <a href="#M6">M6. How do I get multidrop mode to work with majordomo?</a>
97 <h1>Mangled mail:</h1>
99 <a href="#X1">X1. Spurious blank lines are appearing in the headers of fetched mail.</a><br>
100 <a href="#X2">X2. My mail client can't see a Subject line.</a><br>
101 <a href="#X3">X3. Messages containing "From" at start of line are being split.</a><br>
102 <a href="#X4">X4. My mail is being mangled in a new and different way.</a><br>
104 <h1>Other Problems:</h1>
106 <a href="#O1">O1. The --logfile option doesn't work if the logfile doesn't exist.</a><br>
107 <a href="#O2">O2. Every time I get a POP or IMAP message the header is
108 dumped to all my terminal sessions.</a><br>
109 <a href="#O3">O3. Does fetchmail reread its rc file every poll cycle?</a><br>
110 <a href="#O4">O4. Why do deleted messages show up again when I take
111 a line hit while downloading?</a><br>
112 <a href="#O5">O5. Why is fetched mail being logged with my name, not the real From address?</a><br>
116 <h2><a name="G1">G1. What is fetchmail and why should I bother?</a></h2>
118 Fetchmail is a one-stop solution to the remote mail retrieval problem
119 for Unix machines, quite useful to anyone with an intermittent PPP or
120 SLIP connection to a remote mailserver. It can collect mail using any
121 variant of POP or IMAP and forwards via port 25 to the local SMTP
122 listener, enabling all the normal forwarding/filtering/aliasing
123 mechanisms that would apply to local mail or mail arriving via a
124 full-time TCP/IP connection.<p>
126 Fetchmail is not a toy or a coder's learning exercise, but an
127 industrial-strength tool capable of transparently handling every
128 retrieval demand from those of a simple single-user ISP connection up
129 to mail retrieval and rerouting for an entire client domain.
130 Fetchmail is easy to configure, unobtrusive in operation, powerful,
131 feature-rich, and well documented. Extensive testing by a large,
132 multi-platform user community has shown that it is as near bulletproof
133 as the underlying protocols permit.<p>
135 If you found this FAQ in the distribution, see the README for fetchmail's
136 full feature list.<p>
139 <h2><a name="G2">G2. Where do I find the latest FAQ and fetchmail
142 The latest HTML FAQ is available alongside the latest fetchmail
143 sources at the fetchmail home page:
144 <a href="http://www.ccil.org/~esr/fetchmail">
145 http://www.ccil.org/~esr/fetchmail</a>. You can also find
147 href="http://sunsite.unc.edu/pub/Linux/system/mail/pop/!INDEX.html">POP
148 mail tools directory on Sunsite</a>.<p>
150 A text dump of this FAQ is included in the fetchmail
151 distribution. Because it freezes at distribution release time, it may
152 not be completely current.<p>
155 <h2><a name="G3">G3. I think I've found a bug. Will you fix it?</a></h2>
157 Yes I will, provided you include enough diagnostic information for me
158 to go on. Send bugs to <a
159 href="mailto:fetchmail-friends">fetchmail-friends</a>. When reporting
160 bugs, please include the following:
163 <li>Your operating system and compiler version.
164 <li>Any command-line options you used.
165 <li>The output of fetchmail -V called with whatever other
166 command-line options you used.
169 It is helpful if you include your .fetchmailrc, but not necessary
170 unless your symptom seems to involve an error in configuration parsing.<p>
172 If fetchmail seems to run and fetch mail, but the headers look mangled
173 (that is headers are missing, or blank lines are inserted in the
174 headers) then read the FAQ items in section <a href="#X1">X</a>
175 before submitting a bug report. Pay special attention to the item on
176 <a href="#generic_mangling">diagnosing mail mangling</a>. There are
177 lots of ways for other programs in the mail chain to screw up that
178 look like fetchmail's fault, but you may be able to fix these by
179 tweaking your configuration.<P>
181 A transcript of the failed session with -v on is almost always useful.
182 It is very important that the transcript include your POP/IMAP server's
183 greeting line, so I can identify it in case of server problems.<P>
185 If the bug involves a core dump or hang, a gdb stack trace is good to have.
186 (Bear in mind that you can attach gdb to a running but hung process by
187 giving the process ID as a second argument.) You will need to
191 CFLAGS=-g LDFLAGS=" " ./configure
194 and then rebuild in order to generate a version that can be gdb-traced.<p>
196 Best of all is a mail file which, when fetched, will reproduce the
197 bug under the latest (current) version.<p>
199 Any bug I can reproduce will usually get fixed very quickly, often
200 within 48 hours. Bugs I can't reproduce are a crapshoot. If the
201 solution isn't obvious when I first look, it may evade me for a long
202 time (or to put it another way, fetchmail is well enough tested that the
203 easy bugs have long since been found). So if you want your bug fixed
204 rapidly, it is not just sufficient but nearly <em>necessary</em> that
205 you give me a way to reproduce it.<p>
208 <h2><a name="G4">G4. I have this idea for a neat feature. Will you add it?</a></h2>
210 Probably not. Most of the feature suggestions I get are for ways to
211 set various kinds of administrative policy or add more spam filtering
212 (the most common one, which I used to get about four million times a week
213 and got <em>really</em> tired of, is for tin-like kill files).<p>
215 You can do spam filtering better with procmail or mailagent on the
216 server side and (if you're the server sysadmin) sendmail.cf domain
217 exclusions. You can do other policy things better with the
218 <CODE>mda</CODE> option and script wrappers around fetchmail. If
219 it's a prime-time-vs.-non-prime-time issue, ask yourself whether a
220 wrapper script called from crontab would do the job.<p>
222 I'm not going to do these; fetchmail's job is transport, not policy, and I
223 refuse to change it from doing one thing well to attempting many things badly.
224 One of my objectives is to keep fetchmail simple so it stays reliable.<p>
226 All that said, if you have a feature idea that really is about a transport
227 problem that can't be handled anywhere but fetchmail, lay it on me. I'm
228 very accommodating about good ideas.<p>
231 <h2><a name="G5">G5. Is there a mailing list for exchanging tips?</a></h2>
233 There is a fetchmail-friends list for people who want to discuss fixes
234 and improvements in fetchmail and help co-develop it. It's at <a
235 href="mailto:fetchmail-friends@thyrsus.com">fetchmail-friends@thyrsus.com</a>.
236 There is also an announcements-only list, <em>fetchmail-announce@thyrsus.com</em>.<P>
238 Both lists are SmartList reflectors; sign up in the usual way with a
239 message containing the word "subscribe" in the subject line sent to
240 <a href="mailto:fetchmail-friends-request@thyrsus.com?subject=subscribe">
241 fetchmail-friends-request@thyrsus.com</a> or
242 <a href="mailto:fetchmail-announce-request@thyrsus.com?subject=subscribe">
243 fetchmail-announce-request@thyrsus.com</a>. (Similarly, "unsubscribe"
244 in the Subject line unsubscribes you, and "help" returns general list help) <p>
247 <h2><a name="G6">G6. So, what's this I hear about a fetchmail paper?</a></h2>
249 Now it can be told! The fetchmail development was also a sociological
250 experiment, an extended test to see if my theory about the critical
251 features of the Linux development model is correct.<p>
253 The experiment was a success. I wrote a paper about it titled
254 <a href="http://www.ccil.org/~esr/writings/cathedral.html">The
255 Cathedral and the Bazaar</a> which was first presented at Linux
256 Kongress '97 in Bavaria and very well received there. It was also
257 given at Atlanta Linux Expo.<p>
259 If you're reading a non-HTML dump of this FAQ, you can find the paper
260 on the Web with a search for that title.<p>
263 <h2><a name="G7">G7. What is the best server to use with fetchmail?</a></h2>
265 Fetchmail will work with any POP, IMAP, or ESMTP/ETRN server that
266 conforms to the relevant RFCs (and even some oughtright broken ones
267 like Microsoft Exchange). This doesn't mean it works equally well
268 with all, however. POP2 servers, and POP3 servers without LAST, limit
269 fetchmail's capabilities in various ways described on the manual
272 Most modern Unixes (and effectively all Linux/*BSD systems) come with
273 POP3 support preconfigured (but beware of the horribly broken POP3
274 server mentioned in <a href="#D2">D2</a>). An increasing minority
275 also feature IMAP (you can detect IMAP support by running fetchmail in
278 If you have the option, we recommend using or installing IMAP4; it has
279 the best facilities for tracking message "seen" states. It also
280 recovers from interrupted connections more gracefully than POP3, and
281 enables some significant performance optimizations.<P>
283 You can find sources for IMAP software at <a
284 href="http://www.imap.org"> The IMAP Connection</a>; we like the
285 freeware UW IMAP and Cyrus products. UW IMAP is the reference
286 implementation of IMAP.<P>
289 <h2><a name="G8">G8. How can I avoid sending my password en clair?</a></h2>
291 Depending on what your mail server you are talking to, this ranges
292 from trivial to impossible. It may even be next to useless.<P>
294 Most people use fetchmail over phone wires, which are hard to tap.
295 Anybody with the skill and resources to do this could get into your
296 server mailbox with much less effort by subverting the server host.
297 So if your provider setup is modem wires going straight into a service
298 box, you probably don't need to worry.<P>
300 In general there is little point in trying to secure your fetchmail
301 transaction unless you trust the security of the server host you are
302 retrieving mail from. Your vulnerability is more likely to be an
303 insecure local network on the server end (e.g. somebody with a TCP/IP
304 packet sniffer intercepting Ethernet traffic between the modem
305 concentrator you dial in to and the mailserver host).<P>
307 Having realized this, you need to ask whether password encryption
308 alone will really address your security exposure. If you think you
309 might be snooped, it's better to use end-to-end encryption on your
310 whole mail stream so none of it can be read. One of the advantages of
311 fetchmail over conventional SMTP-push delivery is that you may be able
312 to arrange this by using ssh(1); see <a href="#C4">C4</a>.<P>
314 If ssh/sshd isn't available, or you find it too complicated for you to
315 set up, password encryption will at least keep a malicious cracker
316 from deleting your mail, and require him to either tap your connection
317 continuously or crack root on the server in order to read it.<P>
319 You can deduce what encryptions your mail server has available by
320 by looking at the server greeting line (and, for IMAP, the
321 response to a CAPABILITY query). Do a <code>fetchmail -v</code>
322 to see these, or telnet direct to the server port (110 for POP3, 143 for
325 The facility you are most likely to have available is APOP. This is a
326 POP3 feature supported by many servers. If you see something in the
327 greeting line that looks like an angle-bracket-enclosed Internet
328 address with a numeric left-hand part, that's an APOP challenge (it
329 will vary each time you log in). You can register a secret on the
330 host (using <code>popauth(8)</code> or some program like it). Specify
331 the secret as your password in your .fetchmailrc; it will be used to
332 encrypt the current challenge, and the encrypted form will be sent
333 back the the server for verification.<P>
335 Alternatively, you may have Kerberos available. This may require you
336 to set up some magic files in your home directory on your client
337 machine, but means you can omit specifying any password at all.<P>
339 Fetchmail supports two different Kerberos schemes. One is a
340 POP3 variant called KPOP; consult the documentation of your mail
341 server to see if you have it (one clue is the string "krb-IV" in the
342 greeting line on port 110). The other is an IMAP facility described
343 by RFC1731. You can tell if this one is present by looking for
344 AUTH=KERBEROS_V4 in the CAPABILITY response.<P>
346 If you are fetching mail from a CompuServe POP3 account, you can use
347 their RPA authentication (which works much like APOP). See <a
348 href="#T7">T7</a> for details.<P>.
350 Your POP3 server may have the RFC1938 OTP capability to use one-time
351 passwords. To check this, look for the string "otp-" in the greeting
352 line. If you see it, and your fetchmail was built with OPIE support
353 compiled in (see the distribution INSTALL file), fetchmail will
354 detect it also. When using OTP, you will specify a password but it
355 will not be sent en clair.<P>
357 Sadly, there is at present (October 1997) no OTP or APOP-like facility
358 generally available on IMAP servers.<P>
361 <h2><a name="G9">G9. Is any special configuration needed to use a dynamic IP address?</a></h2>
363 No. Fetchmail itself doesn't care whether the IP address you use is
364 static (fixed) or dynamic (varying, allocated at connection time by
365 your ISP from an address pool). In fact, fetchmail normally doesn't
366 use your address explicitly at all; it only cares that you have a
369 Only one fetchmail option interacts with your IP address at all,
370 `<code>interface</code>'. This option can be used to set the gateway
371 device and restrict the IP address range fetchmail will use. Such a
372 restriction is sometimes useful for security reasons, especially on
373 multihomed sites. See <a href="http:#C3">C3</a>.<P>
375 I recommend against trying to set up the <code>interface</code> option
376 when initially developing your poll configuration -- it's never
377 necessary to do this just to get a link working. Get the link working
378 first, observe the actual address range you see on connections, and
379 add an <code>interface</code> option (if you need one) later.<P>
382 <h2><a name="B1">B1. I get link failures when I try to build fetchmail.</a></h2>
384 If you get errors resembling these<P>
387 mxget.o(.text+0x35): undefined referenceto `__res_search'
388 mxget.o(.text+0x99): undefined reference to`__dn_skipname'
389 mxget.o(.text+0x11c): undefined reference to`__dn_expand'
390 mxget.o(.text+0x187): undefined reference to`__dn_expand'
391 make: *** [fetchmail] Error 1
394 then you must add "-lresolv" to the LOADLIBS line in your Makefile
395 since you have installed the `bind' package.<P>
398 <h2><a name="F1">F1. Why does my old .fetchmailrc file no longer work?</a></h2>
400 <h3>If your file predates 4.0.6:</h3>
402 Just after the `<CODE>via</CODE>' option was introduced, I realized
403 that the interactions between the `<CODE>via</CODE>',
404 `<CODE>aka</CODE>', and `<CODE>localdomains</CODE>' options were out
405 of control. Their behavior had become complex and confusing, so much so
406 that I was no longer sure I understood it myself. Users were being
407 unpleasantly surprised.<P>
409 Rather than add more options or crock the code, I re-thought it. The
410 redesign simplified the code and made the options more orthogonal, but
411 may have broken some complex multidrop configurations.
413 Any multidrop configurations that depended on the name just after the
414 `<CODE>poll</CODE>' or `<CODE>skip</CODE>' keyword being still
415 interpreted as a DNS name for address-matching purposes, even in the
416 presence of a `<CODE>via</CODE>' option, will break.<P>
418 It is theoretically possible that other unusual configurations (such
419 as those using a non-FQDN poll name to generate Kerberos IV tickets) might
420 also break; the old behavior was sufficiently murky that we can't be
421 sure. If you think this has happened to you, contact the maintainer.<P>
423 <h3>If your file predates 3.9.5:</h3>
425 The `<code>remote</code>' keyword has been changed to `<code>folder</code>'.
426 If you try to use the old keyword, the parser will utter a warning.<P>
428 <h3>If your file predates 3.9:</h3>
430 It could be because you're using a .fetchmailrc that's written in the
431 old popclient syntax without an explicit `<CODE>username</CODE>'
432 keyword leading the first user entry attached to a server entry.
434 This error can be triggered by having a user option such as `<CODE>keep</CODE>'
435 or `<CODE>fetchall</CODE>' before the first explicit username. For
436 example, if you write<p>
439 poll openmail protocol pop3
440 keep user "Hal DeVore" there is hdevore here
443 the `<CODE>keep</CODE>' option will generate an entire user entry with
444 the default username (the name of fetchmail's invoking user).<p>
446 The popclient compatibility syntax was removed in 4.0. It complicated
447 the configuration file grammar and confused users.<p>
449 <h3>If your file predates 2.8:</h3>
451 The `<CODE>interface</CODE>', `<CODE>monitor</CODE>' and
452 `<CODE>batchlimit</CODE>' options changed after 2.8.<p>
454 They used to be global options with `<CODE>set</CODE>' syntax like the
455 batchlimit and logfile options. Now they're per-server options, like
456 `<CODE>protocol</CODE>'.<p>
458 If you had something like<p>
461 set interface = "sl0/10.0.2.15"
464 in your .fetchmailrc file, simply delete that line and insert
465 `interface sl0/10.0.2.15' in the server options part of your `defaults'
468 Do similarly for any `<CODE>monitor</CODE>' or `<CODE>batchlimit</CODE>' options.<p>
471 <h2><a name="F2">F2. The .fetchmailrc parser won't accept my all-numeric user name.</a></h2>
473 So put string quotes around it. :-)<p>
475 The configuration file parser treats any all-numeric token as a
476 number, which will confuse it when it's expecting a name. String
477 quoting forces the token's class.<p>
480 <h2><a name="F3">F3. The .fetchmailrc parser won't accept my host or username beginning with `no'.</a></h2>
482 You're caught in an unfortunate crack between the newer-style syntax
483 for negated options (`no keep', `no rewrite' etc.) and the older style
484 run-on syntax (`nokeep', `norewrite' etc.).<p>
486 You can work around this easily. Just put string quotes around your
489 I haven't fixed this because there is no good fix for it short of
490 implementing a token pushback stack in the lexer. That's more
491 additional complexity than I'm willing to add to banish a very
492 marginal bug with an easy workaround.<p>
495 <h2><a name="F4">F4. I'm migrating from popclient. How do I need to modify my .poprc?</a></h2>
497 If you have been using popclient (the ancestor of this program)
498 at version 3.0b6 or later, start with this<p>
501 (cd; mv .poprc .fetchmailrc)
504 in order to migrate. Be aware that some of popclient's unnecessary
505 options have been removed (see the NOTES file in the distribution for
506 explanation). You can't deliver to a local mail file or to
507 standard output any more, and using an MDA for delivery is
508 discouraged. If you throw those options away, fetchmail will now
509 forward your mail into your system's normal Internet-mail delivery
512 Actually, using an MDA is now almost always the wrong thing; the MDA
513 facility has been retained only for people who can't or won't run a
514 sendmail-like SMTP listener on port 25. The default, SMTP forwarding
515 to port 25, is better for at least two major reasons. One: it feeds
516 retrieved POP and IMAP mail into your system's normal delivery path
517 along with local mail and normal Internet mail, so all your normal
518 filtering/aliasing/forwarding setup for local mail works. Two:
519 because the port 25 listener returns a positive acknowledge, fetchmail
520 can be sure you're not going to lose mail to a disk-full or some other
521 resource-exhaustion problem.<p>
523 If you used to use <CODE>-mda "procmail -d</CODE>
524 <em><you></em><CODE>"</CODE> or something similar, forward to port
525 25 and do "<CODE>| procmail -d</CODE> <em><you></em><CODE>"</CODE> in
526 your ~/.forward file.<p>
528 As long as your new .fetchmailrc file does not use the removed
529 `localfolder' option or `<CODE>limit</CODE>' (which now takes a
530 maximum byte size rather than a line count), a straight move or copy
531 of your .poprc will often work. (The new run control file syntax also
532 has to be a little stricter about the order of options than the old,
533 in order to support multiple user descriptions per server; thus you
534 may have to rearrange things a bit.)<p>
536 Run control files in the minimal .poprc format (without the `username'
537 token) will trigger a warning. To eliminate this warning, add the
538 `<CODE>username</CODE>' keyword before your first user entry per server (it is
539 already required before second and subsequent user entries per server.<p>
541 In some future version the `<CODE>username</CODE>' keyword will be required.<p>
544 <h2><a name="C1">C1. Why do I need a .fetchmailrc when running as root on my own machine?</a></h2>
546 Ian T. Zimmerman <itz@rahul.net> asked:<p>
548 On the machine where I'm the only real user, I run fetchmail as root
549 from a cron job, like this:<p>
552 fetchmail -u "itz" -p POP3 -s bolero.rahul.net
555 This used to work as is (with no .fetchmailrc file in root's home
556 directory) with the last version I had (1.7 or 1.8, I don't
557 remember). But with 2.0, it RECPs all mail to the local root user,
558 unless I create a .fetchmailrc in root's home directory containing:<p>
561 skip bolero.rahul.net proto POP3
565 It won't work if the second line is just "<CODE>user itz</CODE>". This is silly.<p>
567 It seems fetchmail decides to RECP the `default local user' (ie. the
568 uid running fetchmail) unless there are local aliases, and the
569 `default' aliases (itz->itz) don't count. They should.<p>
573 No they shouldn't. I thought about this for a while, and I don't much
574 like the conclusion I reached, but it's unavoidable. The problem is
575 that fetchmail has no way to know, in general, that a local user `itz'
578 "Ah!" you say, "Why doesn't it check the password file to see if the remote
579 name matches a local one?" Well, there are two reasons.<p>
581 One: it's not always possible. Suppose you have an SMTP host declared
582 that's not the machine fetchmail is running on? You lose.<p>
584 Two: How do you know server itz and SMTP-host itz are the same person?
585 They might not be, and fetchmail shouldn't assume they are unless
586 local-itz can explicitly produce credentials to prove it (that is, the
587 server-itz password in local-itz's .fetchmailrc file.).<p>
589 Once you start running down possible failure modes and thinking about
590 ways to tinker with the mapping rules, you'll quickly find that all the
591 alternatives to the present default are worse or unacceptably
592 more complicated or both.<p>
595 <h2><a name="C2">C2. How can I arrange for a fetchmail daemon to get killed when I log out?</a></h2>
597 Fetchmail versions before 2.3 actually used SIGHUP as a wakeup signal.
598 Newer versions use SIGUSR1 for wakeup (and SIGHUP only in
599 background-daemon mode) in order to avoid any potential confusion
600 about logout-time behavior. The right way to dispatch fetchmail on
601 logout is to arrange for the command `fetchmail -q' to be called on
604 Under bash, you can arrange this by putting `fetchmail -q' in the file
605 `~/.bash_logout'. Most csh variants execute `~/.logout' on logout.
606 For other shells, consult your shell manual page.<p>
609 <h2><a name="C3">C3. How do I know what interface and address to use with --interface?</a></h2>
611 This depends a lot on your local networking configuration (and right
612 now you can't use it at all except under Linux). However, here are
613 some important rules of thumb that can help. If they don't work, ask
614 your local sysop or your Internet provider.<p>
616 First, you may not need to use --interface at all. If your machine
617 only ever does SLIP or PPP to one provider, it's almost certainly by a
618 point to point modem connection to your provider's local subnet that's
619 pretty secure against snooping (unless someone can tap your phone or
620 the provider's local subnet!). Under these circumstances, specifying
621 an interface address is fairly pointless.<p>
623 What the option is really for is sites that use more than one
624 provider. Under these circumstances, typically one of your provider
625 IP addresses is your mailserver (reachable fairly securely via the
626 modem and provider's subnet) but the others might ship your packets
627 (including your password) over unknown portions of the general
628 Internet that could be vulnerable to snooping. What you'll use
629 --interface for is to make sure your password only goes over the
632 To determine the device:<p>
635 <li> If you're using a SLIP link, the correct device is probably sl0.
636 <li> If you're using a PPP link, the correct device is probably ppp0.
637 <li> If you're using a direct connection over a local network such as
638 an ethernet, use the command `netstat -r' to look at your routing table.
639 Try to match your mailserver name to a destination entry; if you don't
640 see it in the first column, use the `default' entry. The device name
641 will be in the rightmost column.
644 To determine the address and netmask:<p>
647 <li> If you're talking to slirp, the correct address is probably 10.0.2.15,
648 with no netmask specified. (It's possible to configure slirp to present
649 other addresses, but that's the default.)
651 <li> If you have a static IP address, run `ifconfig <device>', where <device>
652 is whichever one you've determined. Use the IP address given after
653 "inet addr:". That is the IP address for your end of the link, and is
654 what you need. You won't need to specify a netmask.
656 <li> If you have a dynamic IP address, your connection IP will vary randomly
657 over some given range (that is, some number of the least significant bits
658 change from connection to connection). You need to declare an address
659 with the variable bits zero and a complementary netmask that sets
663 To illustrate the rule for dynamic IP addresses, let's suppose you're
664 hooked up via SLIP and your IP provider tells you that the dynamic
665 address pool is 255 addresses ranging from 205.164.136.1 to
666 205.164.136.255. Then<p>
669 interface "sl0/205.164.136.0/255.255.255.0"
672 would work. To range over any value of the last two octets
673 (65536 addresses) you would use<p>
676 interface "sl0/205.164.0.0/255.255.0.0"
680 <h2><a name="C4">C4. How can I get fetchmail to work with ssh?</a></h2>
682 We have two recipes for this. The first is a little easier to set up,
683 but only supports one user at a time.<P>
685 First, a lightly edited version of a recipe from Masafumi NAKANE:<p>
687 1. You must have ssh (the ssh client) on the local host and sshd (ssh
688 server) on the remote mail server. And you have to configure ssh so
689 you can login to the sshd server host without a password. (Refer to ssh
690 man page for several authentication methods.)<p>
692 2. Add something like following to your .fetchmailrc file: <p>
695 poll mailhost port 1234 via localhost with pop3:
696 preconnect "ssh -f -L 1234:mailhost:110 mailhost sleep 20 </dev/null >/dev/null";
699 (Note that 1234 can be an arbitrary port number. Privileged ports can
700 be specified only by root.) The effect of this ssh command is to
701 forward connections made to localhost port 1234 (in above example) to
704 This configuration will enable secure mail transfer. All the
705 conversation between fetchmail and remote pop server will be
708 If sshd is not running on the remote mail server, you can specify
709 intermediate host running it. If you do this, however, communication
710 between the machine running sshd and the POP server will not be encrypted.
711 And the preconnect line would be like this:<p>
714 preconnect "ssh -f -L 1234:mailhost:110 sshdhost sleep 20 </dev/null >/dev/null"
717 You can work this trick with IMAP too, but the port number 110 in the
718 above would need to become 143.<p>
720 Second, a recipe from Charlie Brady <cbrady@ind.tansu.com.au>:<p>
722 Charlie says: "The [previous] recipe certainly works, but
723 the solution I post here is better in a few respects":
726 <LI>this method will not fail if two or more users attempt to use fetchmail
728 <LI>you are able to use the full facilities of tcpd to control access
729 <LI>this method does not depend on the preconnect feature of fetchmail, so
730 can be used for tunneling of other services as well.
737 Make sure that the "socket" program is installed on the server machine.
739 Set up an unprivileged account on your system with a .ssh directory
740 containing an SSH identity file "identity" with no pass phrase,
741 "identity.pub" and "known_hosts" containing the host key of your
742 mailhost. Let's call this account "noddy".
744 On mailhost, set up no-password access for noddy@yourhost. Add to your
745 SSH authorised_keys file:
748 command="socket localhost 110",no-port-forwarding 1024 ......
751 where "<code>1024</code> ......" is the content of noddy's identity.pub file.
753 Create a script /usr/local/bin/ssh.fm and make it executable:
757 exec ssh -q -C -l your.login.id -e none mailhost socket localhost 110
760 Add an entry in inetd.conf for whatever port you choose to use - say:
763 1234 stream tcp nowait noddy /usr/sbin/tcpd /usr/local/bin/ssh.fm
766 Send a HUP signal to your inetd.
769 Now just use localhost:1234 to access your POP server.<P>
772 <h2><a name="C5">C5. How can I set up support for sendmail's anti-spam 571 response?</a></h2>
774 Rachel Polanskis <r.polanskis@nepean.uws.edu.au> writes:<p>
776 Basically you need to use the "check_*" rules in sendmail.
777 These are rules introduced since version 8.8.2<p>
779 The idea is to generate a list of domains and addresses that are placed into
780 a file - I call mine "sendmail.rej" and you place just one domain
781 or email address on each line. During the SMTP transaction, this file
782 is checked and if there is a match, the message is refused, with
783 a suitable "Service not available" message sent back to the sender.<p>
785 With the feature enabled in fetchmail, the mail is simply deleted,
786 with no further processing.<p>
788 The only drawback when blocking spam with fetchmail is that you
789 do not get the satisfaction of sending an error back to the sender.<p>
791 To actually use the check_mail rules in sendmail 8.8.2 or better,
792 you need to know how to generate a sendmail.cf file from the m4
793 config files distributed with sendmail.<p>
795 The actual rules can be found at the following URLS:<p>
797 <a href="http://www.informatik.uni-kiel.de/%7Eca/email/check.html">
798 http://www.informatik.uni-kiel.de/%7Eca/email/check.html</a><p>
800 This one is by Claus Aßman, who has documented more of sendmail then
803 Remember, when copying these rulesets off the web, that there are tabs
804 embedded in them, that may not be preserved. You <em>must</em> reintroduce
805 these tabs into the rules to make them work properly. <p>
807 Once you have your ruleset in place, and have generated a nice sendmail.cf
808 file, and the list of blocked sites, try telneting to your
809 SMTP port to test it, and send a message with a blocked address in it.<p>
811 You should see a message similar to:<p>
814 "571 unsolicited email is refused"
817 Next, if you have access to a host that you can send mail from, that
818 is <em>not</em> your mail host, add that host to your spamlist and
821 Send a message to your mailing address from that host and then pop off
822 the message with fetchmail, using the -v argument. You can monitor
823 the SMTP transaction, and when the FROM address is parsed, if sendmail
824 sees that it is an address in spamlist, fetchmail will flush and
827 Under no circumstances put your <strong>mailhost</strong> or <strong>any host
828 you accept mail from</strong> using fetchmail into your reject file. You
829 <strong>will</strong> lose mail if you do this!!!<p>
831 The check_ rules work, and they work well. Coupled with fetchmail's
832 ability to respond to the appropriate error messages, you can be assured
833 of never seeing a spam from any address you put in the reject list.<p>
835 The only thing that is missing, as mentioned previously, is the ability
836 to allow sendmail to process the message further and generate an error
837 message to the sender. <p>
840 <h2><a name="C6">C6. How can I do automatic startup/shutdown of fetchmail
841 when I may have multiple login sessions going?</a></h2>
843 In the contrib subdirectory of the fetchmail distribution there is
844 some shell code you can add to your .bash_login and .bash_logout
845 profiles that will accomplish this. Thank James Laferriere
846 <babydr@nwrain.net> for it.<p>
849 <h2><a name="T1">T1. How can I use fetchmail with sendmail?</a></h2>
851 No special configuration is required. Eric Allman tells me that if
852 <code>FEATURE(always_add_domain)</code> is included in sendmail's
853 configuration, you can leave the <code>rewrite</code> option off.
856 <h2><a name="T2">T2. How can I use fetchmail with qmail?</a></h2>
858 Turn on the <CODE>forcecr</CODE> option; qmail's listener mode doesn't like
859 header or message lines terminated with bare linefeeds.<p>
861 (This information is thanks to Robert de Bath
862 <robert@mayday.cix.co.uk>.)<p>
864 If a mailhost is using the qmail package (see <a
865 href="http://pobox.com/~djb/qmail.html">http://pobox.com/~djb/qmail.html</a>)
866 then, providing the local hosts are also using qmail, it is possible
867 to set up one fetchmail link to be reliably collect the mail for an
870 One of the basic features of qmail is the `Delivered-To:' message
871 header. Whenever qmail delivers a message to a local mailbox it puts
872 the username and hostname of the envelope recipient on this line. The
873 major reason for this is to prevent mail loops. <p>
875 To set up qmail to batch mail for a disconnected site the ISP-mailhost
876 will have normally put that site in its `virtualhosts' control file so
877 it will add a prefix to all mail addresses for this site. This results
878 in mail sent to 'username@userhost.userdom.dom.com' having a
879 'Delivered-To:' line of the form:<p>
882 Delivered-To: mbox-userstr-username@userhost.userdom.dom.com
885 A single host maildrop will be slightly simpler:
888 Delivered-To: mbox-userstr-username@userhost.dom.com
891 The ISP can make the 'mbox-userstr-' prefix anything they choose
892 but a string matching the user host name is likely.<p>
894 To use this line you must:<p>
897 <li>Ensure the option `envelope Delivered-To:' is in the fetchmail
900 <li>Ensure you have a localdomains containing 'userdom.dom.com' or
901 `userhost.dom.com' respectively.
904 So far this reliably delivers messages to the correct machine of the
905 local network, to deliver to the correct user the 'mbox-userstr-'
906 prefix must be stripped off of the user name. This can be done by
907 setting up an alias within the qmail MTA on each local machine.
908 Simply create a dot-qmail file called '.qmail-mbox-userstr-default'
909 in the alias directory (normally /var/qmail/alias) with the contents:<p>
912 | ../bin/qmail-inject -a -f"$SENDER" "${LOCAL#mbox-userstr-}@$HOST}"
915 Note this <em>does</em> require a modern /bin/sh.<p>
917 Luca Olivetti adds:<P>
919 If you aren't using qmail locally, or you don't want to set up the
920 alias mechanism described above, you can use the option `<code>qvirtual
921 "mbox-userstr-"</code>' in your fetchmail config file to strip the prefix
922 from the local user name.<p>
925 <h2><a name="T3">T3. How can I use fetchmail with exim?</a></h2><p>
927 By default, the exim listener enforces the the RFC1123 requirement
928 that MAIL FROM and RCPT TO addresses you pass to it have to be canonical
929 (e.g. with a fully qualified hostname part). <p>
931 Fetchmail always passes fully qualified RCPT TO addresses. But
932 MAIL FROM is a potential problem if the MTAs upstream from your fetchmail
933 don't necessarily pass canonicalized From and Return-Path addresses,
934 and fetchmail's <CODE>rewrite</CODE> option is off. The specific case
935 where this has come up involves bounce messages generated by sendmail
936 on your mailer host, which have the (un-canonicalized) origin address
939 The right way to fix this is to enable the <CODE>rewrite</CODE> option and
940 have fetchmail canonicalize From and Return-Path addresses with the
941 mailserver hostname before exim sees them. This option is enabled by
942 default, so it won't be off unless you turned it off.<p>
944 If you must run with <CODE>rewrite</CODE> off, there is a switch in exim's
945 configuration files that allows it to accept domainless MAIL FROM
946 addresses; you will have to flip it by putting the line <p>
949 sender_unqualified_hosts = localhost
952 in the main section of the exim configuration file. Note that this
953 will result in such messages having an incorrect domain name attached
954 to their return address (your SMTP listener's hostname rather than
955 that of the remote mail server). <p>
958 <h2><a name="T4">T4. How can I use fetchmail with smail?</a></h2><p>
960 Smail 3.2 is very nearly plug-compatible with sendmail, and may work
961 fine out of the box.<P>
963 We have one report that when processing multiple messages from a
964 single fetchmail session, smail sometimes delivers them in an
965 order other than received-date order. This can be annoying because it
966 scrambles conversational threads. This is not fetchmail's problem,
967 it is an smail "feature" and has been reported to the maintainers
970 Very recent smail versions require an <code>-smtp_hello_verify</code>
971 option in the smail config file. This overrides smail's check to see
972 that the HELO address is actually that of the client machine, which
973 is never going to be the case when fetchmail is in the picture.
974 According to RFC1123 an SMTP listener <em>must</em> allow this
975 mismatch, so smail's new behavior (introduced sometime between
976 3.2.0.90 and 3.2.0.95) is a bug.<P>
979 <h2><a name="T5">T5. How can I use fetchmail with SCO's MMDF?</a></h2><p>
981 We're told this is possible, but difficult and tricky (and we don't
982 have the recipe for it). Our informant suggests dropping MMDF and
983 using sendmail instead.<P>
986 <h2><a name="T6">T6. How can I use fetchmail with Lotus Notes?</a></h2><p>
988 The Lotus Notes SMTP gateway tries to deduce when it should convert \n
989 to \r\n, but its rules are not intuitive. Use `forcecr'.<P>
992 <h2><a name="T7">T7. How can I use fetchmail with Microsoft Exchange?</a></h2><p>
994 M$ Exchange violates the POP3 RFCs. Its LIST command does not reveal
995 the real sizes of mail in the pop mailbox, but the sizes of the
996 compressed versions in the exchange mail database (thanks to Arjan De
997 Vet and Guido Van Rooij for alerting us to this problem).<P>
999 Fetchmail works with M$ Exchange, despite this braindamage. Two
1000 features are compromised. One is that the --limit option will not
1001 work right (it will check against compressed and not actual sizes).
1002 The other is that a too-small SIZE argument may be passed to your
1003 ESMTP listener, assuming you're using one (this should not be a
1004 problem unless the actual size of the message is above the listener's
1005 configured length limit).<P>
1007 If you want these fixed, go bug the Evil Empire. Or, better yet,
1008 install a real operating system on your server and run IMAP.<P>
1011 <h2><a name="T8">T8. How can I use fetchmail with CompuServe RPA?</a></h2>
1013 First, make sure your fetchmail has the RPA support compiled in.
1014 Stock fetchmail binaries (such as you might get from an RPM) don't.
1015 You can check this by looking at the output of <code>fetchmail -V</code>;
1016 if you see the string "+RPA" after the version ID you're good to go,
1017 otherwise you'll have to build your own from sources (see the INSTALL
1018 file in the source distribution for directions).<P>
1020 Give your RPA pass-phrase as your password. An RPA-enabled fetchmail
1021 will automatically check for csi.com in the POP server's greeting
1022 line. If that's found, it will query the server to see if it is
1023 RPA-capable, and if so do an RPA transaction rather than a plain-text
1024 password handshake.<P>
1027 <h2><a name="T9">T9. How can I use fetchmail with HP OpenMail?</a></h2>
1029 No special configuration is required, but OpenMail has an annoying bug
1030 similar to the big one in <a href="#T6">Microsoft Exchange</a>.
1031 The message sizes it gives in the LIST are rounded to the nearest 1024
1032 bytes. It also has a nasty habit of discarding headers it doesn't
1033 recognize, such as X- and Resent- headers.<P>
1035 As with M$ Exchange, the only real fix for these problems is to get a
1036 POP server that isn't brain-dead.<P>
1039 <h2><a name="R1">R1. Fetchmail's initial gethostbyname call fails on my host.</a></h2>
1041 This is probably due to a DNS or NIS misconfiguration. The first
1042 thinh to do is check your /etc/hosts file for duplicate or missing
1043 entries related to your host.<P>
1046 <h2><a name="R2">R2. Fetchmail isn't working, and -v shows `SMTP connect failed' messages.</a></h2>
1048 Fetchmail itself is probably working, but your SMTP port 25 listener
1049 is down or inaccessible.<p>
1051 The first thing to check is if you can telnet to port 25 on your smtp
1052 host (which is normally `localhost' unless you've specified an smtp
1053 option in your .fetchmailrc or on the command line) and get a greeting
1054 line from the listener. If the SMTP host is inaccessible or the listener
1055 is down, fix that first.<p>
1057 If the listener seems to be up when you test with telnet, the most
1058 benign and typical problem is that the listener had a momentary seizure
1059 due to resource exhaustion while fetchmail was polling it -- process
1060 table full or some other problem that stopped the listener process
1061 from forking. If your SMTP host is not `localhost' or something else
1062 in /etc/hosts, the fetchmail glitch could also have been caused by
1063 transient nameserver failure. <p>
1065 Try running fetchmail -v again; if it succeeds, you had one of these
1066 kinds of transient glitch. You can ignore these hiccups, because a
1067 future fetchmail run will get the mail through. <p>
1069 If the listener tests up, but you have chronic failures trying to
1070 connect to it anyway, your problem is more serious. One way to work
1071 around chronic SMTP connect problems is to use --mda. But this only
1072 attacks the symptom; you may have a DNS or TCP routing problem. You
1073 should really try to figure out what's going on underneath before it
1074 bites you some other way. <p>
1076 We have one report (from toby@eskimo.com) that you can sometimes solve
1077 such problems by doing an <CODE>smtp</CODE> declaration with an IP
1078 address that your routing table maps to something other than the
1079 loopback device (he used ppp0).<p>
1081 We also have a report that this error can be caused by having an
1082 /etc/hosts file that associates your client host name with more than
1085 We had another report from a Linux user of fetchmail 2.1 who solved his SMTP
1086 connection problem by removing the reference to -lresolv from his link
1087 line and relinking. Apparently in some older Linux distributions the
1088 libc bind library version works better.<p>
1090 As of 2.2, the configure script has been hacked so the bind library is
1091 linked only if it is actually needed. So under Linux it won't be, and
1092 this particular cause should go away.<p>
1095 <h2><a name="R3">R3. When I try to configure an MDA, fetchmail doesn't work.</a></h2>
1097 (I hear this one from people who have run into the blank-line problem in <a href="#X1">X1</a>.)<p>
1099 Try sending yourself test mail and retrieving it using the
1100 command-line options `<CODE>-k -m cat</CODE>'. This will dump exactly what
1101 fetchmail retrieves to standard output (plus the Received line
1102 fetchmail itself adds to the headers). <p>
1104 If the dump doesn't match what shows up in your mailbox when you
1105 configure an MDA, your MDA is mangling the message. If it doesn't
1106 match what you sent, then fetchmail or something on the server is
1110 <h2><a name="#R4">R4. Fetchmail dumps core when given an invalid rc file.</a></h2>
1112 This is usually reported from AIX or Ultrix, but has even been known
1113 to happen on Linuxes without a recent version of <code>flex</code>
1114 installed. The problem appears to be a result of linking with an
1115 archaic version of lex.<P>
1117 Workaround: fix the syntax of your .fetchmailrc file.<P>
1119 Fix: build and install the latest version of <a
1120 href="ftp://prep.ai.mit.edu/~ftp/pub/gnu">flex</a> from the Free
1121 Software Foundation. An FSF <a
1122 href="http://www.gnu.ai.mit.edu/order/ftp.html">mirror site</a>
1123 will help you get it faster.<P>
1126 <h2><a name="R5">R5. Fetchmail dumps core in -V mode, but operates normally otherwise.</a></h2>
1128 We've had this reported to us under Linux using libc-5.4.17 and gcc-2.7.2.
1129 It does not occur with libc-5.3.12 or earlier versions.<p>
1131 Workaround: link with GNU malloc rather than the stock C library malloc.<p>
1133 We're told there is some problem with the malloc() code in that
1134 version which makes it fragile in the presence of multiple free()
1135 calls on the same pointer (the malloc arena gets corrupted).
1136 Unfortunately it appears from doing gdb traces that whatever free()
1137 calls producing the problem are being made by the C library itself, not the
1138 fetchmail code (they're all from within fclose, and not an fclose called
1139 by fetchmail, either).<p>
1142 <h2><a name="R6">R6. Fetchmail dumps core when I use a .netrc file but works otherwise.</a></h2>
1144 We have a report that under Solaris 2.5 using gcc-2.7.2, if fetchmail
1145 is compiled with -O or -O2, it segfaults on startup when reading a
1148 You can work around this by disabling optimization.<p>
1150 There may be an actual bug here that the optimizer exposes; the stack
1151 trace says the segfault is in free() and has all the earmarks of a heap-
1152 corruption screw. But the symptom doesn't reproduce under Linux with the
1153 same .fetchmailrc and .netrc.<p>
1156 <h2><a name="R7">R7. Running fetchmail in daemon mode doesn't work.</a><br></h2>
1158 We have one report from a Solaris 4.1.4 user that trying to run
1159 fetchmail in detached daemon mode doesn't work, but that using the
1160 same options with -N (nodetach) is OK.<P>
1162 If this happens, you have a specific portability problem with the code
1163 in daemon.c that detaches and backgrounds the daemon fetchmail. Tell
1164 me about it so I can try to fix it. As a workaround, you can start
1165 fetchmail with -N and an ampersand to background it.<P>
1167 This should not happen under Linux or any truly POSIX-conformant Unix.<P>
1170 <h2><a name="D1">D1. I think I've set up fetchmail correctly, but I'm not getting any mail.</a></h2>
1172 Maybe you have a .forward or alias set up that you've forgotten about. You
1173 should probably remove it.<p>
1175 Or maybe you're trying to run fetchmail in multidrop mode as root
1176 without a .fetchmailrc file. This doesn't do what you think it
1177 should; see question <a href="#C1">C1</a>.<p>
1179 Or you may not be connecting to the SMTP listener. Run fetchmail -v
1180 and see <a href="#R1">R1</a>.<p>
1183 <h2><a name="D2">D2. All my mail seems to disappear after an interrupt.</a></h2>
1185 One POP3 daemon used in the Berkeley Unix world that reports itself as
1186 POP3 version 1.004 actually throws the queue away. 1.005 fixed that.
1187 If you're running this one, upgrade immediately.<P>
1189 Many POP servers, if an interruption occurs, will restore the whole
1190 mail queue after about 10 minutes. Others will restore it right
1191 away. If you have an interruption and don't see it right away, cross
1192 your fingers and wait ten minutes before retrying.<P>
1194 Some servers (such as Microsoft's NTMail) are mis-designed to restore
1195 the entire queue, including messages you have deleted. If you have
1196 one of these and it flakes out on you a lot, try setting a small
1197 <code>--fetchlimit</code> value. This will result in more IP connects
1198 to the server but will mean it actually executes changes to the queue
1201 Qualcomm's qpopper, used at many BSD Unix sites, is better behaved.
1202 If its connection is dropped, it will first execute all DELE commands (as
1203 though you had issued a QUIT -- this is a technical violation of
1204 the POP3 RFCs, but a good idea in a world of flaky phone lines). Then it
1205 will re-queue any message that was being downloaded at hangup time.
1206 Still, qpopper may require a noticeable amount of time to do deletions
1207 and clean up its queue. (Fetchmail waits a bit before retrying in
1208 order to avoid a `lock busy' error.)<P>
1211 <h2><a name="D3">D3. Mail that was being fetched when I interrupted my fetchmail seems to have been vanished.</a></h2>
1213 Fetchmail only sends a delete mail request to the server when either
1214 (a) it gets a positive delivery acknowledgement from the SMTP
1215 listener, or (b) it gets an error 571 (the spam-filter error) from the
1216 listener. No interrupt can cause it to lose mail.<p>
1218 However, POP3 has a design problem in that its servers mark a message
1219 `seen' as soon as the fetch command to get it is sent down. If for
1220 some reason the message isn't actually delivered (you take a line hit
1221 during the download, or your port 25 listener can't find enough free
1222 disk space, or you interrupt the delivery in mid-message) that `seen'
1223 message can lurk invisibly in your server mailbox forever.<p>
1225 Workaround: add the `<CODE>fetchall</CODE>' keyword to your POP3 fetch options.<p>
1227 Solution: switch to an <a href="http://www.imap.org">IMAP</a> server.<p>
1230 <h2><a name="M1">M1. I've declared local names, but all my multidrop
1231 mail is going to root anyway.</a></h2>
1233 Somehow your fetchmail is never matching the hostname part of
1234 recipient names to the name of the mailserver machine. This probably
1235 means it is unable to recognize hostname parts as being DNS names of
1236 the mailserver, and indicates some kind of DNS configuration
1237 problem either on the server or your client machine. <p>
1239 The easiest workaround is to add a `<CODE>via</CODE>' option (if
1240 necessary) and add enough aka declarations to cover all of your
1241 mailserver's aliases, then say `<CODE>no dns</CODE>'. This will take
1242 DNS out of the picture (though it means mail may be uncollected if
1243 it's sent to an alias of the mailserver that you don't have
1246 It would be better to fix your DNS, however. DNS problems can hurt
1247 you in lots of ways, for example by making your machines
1248 intermittently or permanently unreachable to the rest of the net.<P>
1251 <h2><a name="M2">M2. I can't seem to get fetchmail to route to a local domain properly.</a></h2>
1253 A lot of people want to use fetchmail as a poor man's internetwork
1254 mail gateway, picking up mail accumulated for a whole domain in a single
1255 server mailbox and then routing based on what's in the To/Cc/Bcc lines.<p>
1257 In general, this is not really a good idea. It would be smarter to
1258 just let the mail sit in the mailserver's queue and use fetchmail's
1259 ETRN mode to trigger SMTP sends periodically (of course, this means
1260 you have to poll more frequently than the mailserver's expiry period).
1261 If you can't arrange this, try setting up a UUCP feed.<P>
1263 If neither of these alternatives is available, multidrop mode may do
1264 (though you <em>are</em> going to get hurt by some mailing list
1265 software; see the caveats under THE USE AND ABUSE OF MULTIDROP
1266 MAILBOXES on the man page). If you want to try it, the way to do it
1267 is with the `<CODE>localdomains</CODE>' option.<p>
1269 In general, if you use localdomains you need to make sure of two other
1272 <strong>1. You've actually set up your .fetchmailrc entry to invoke multidrop mode.</strong><p>
1274 Many people set a `<CODE>localdomains</CODE>' list and then forget
1275 that fetchmail wants to see more than one name (or the wildcard `*')
1276 in a `<CODE>here</CODE>' list before it will do multidrop routing.<p>
1278 <strong>2. You may have to set `no envelope'.</strong><p>
1280 Normally, multidrop mode tries to deduce an envelope address from a message
1281 before parsing the To/Cc/Bcc lines (this enables it to avoid losing to mailing
1282 list software that doesn't put a recipient addess in the To lines).<p>
1284 Some ways of accumulating a whole domain's messages in a single server
1285 mailbox mean it all ends up with a single envelope address that is
1286 useless for rerouting purposes. You may have to set `<CODE>no
1287 envelope</CODE>' to prevent fetchmail from being bamboozled by this.<p>
1289 Check also answer <a href="#T1">T1</a> on a reliable way to do multidrop
1290 delivery if your ISP (or your mail redirection provider) is using qmail.<p>
1293 <h2><a name="M3">M3. I tried to run a mailing list using multidrop, and I have a mail loop!</a></h2>
1295 This isn't fetchmail's fault. Check your mailing list. If the list
1296 expansion includes yourself or anybody else at your mailserver (that is, not on
1297 the client side) you've created a mail loop. Just chop the host part off any
1298 local addresses in the list.<p>
1300 If you use sendmail, you can check the list expansion with
1301 <CODE>sendmail -bv</CODE>.<p>
1304 <h2><a name="M4">M4. My multidrop fetchmail seems to be having DNS problems.</a></h2>
1306 We have one report from a Linux user (not the same one as in <a
1307 href="#R1">R1</a>!) who solved this problem by removing the reference
1308 to -lresolv from his link line and relinking. Apparently in some
1309 recent Linux distributions the libc bind library version works
1312 As of 2.2, the configure script has been hacked so the bind library is linked
1313 only if it is actually needed. So under Linux it won't be, and this problem
1317 <h2><a name="M5">M5. I'm seeing long DNS delays before each message is processed.</a></h2>
1319 Use the `<CODE>aka</CODE>' option to pre-declare as many of your
1320 mailserver's DNS names as you can. When an address's host part
1321 matches an aka name, no DNS lookup needs to be done to check it.<p>
1323 If you're sure you've pre-declared all of your mailserver's DNS dames,
1324 you can use the `<CODE>no dns</CODE>' option to prevent other hostname
1325 parts from being looked up at all.<p>
1327 Sometimes delays are unavoidable. Some SMTP listeners try to call DNS
1328 on the From-address hostname as a way of checking that the address is valid.<p>
1331 <h2><a name="M6">M6. How do I get multidrop mode to work with majordomo?</a></h2>
1333 In order for sendmail to execute the command strings in the majordomo
1334 alias file, it is necessary for sendmail to think that the mail it
1335 receives via SMTP really is destined for a local user name. A normal
1336 virtual-domain setup results in delivery to the default mailbox,
1337 rather than expansion through majordomo.<P>
1339 Michael <michael@bizsystems.com> gave us a recipe for dealing
1340 with this case that pairs a run control file like this:<P>
1343 poll your.pop3.server proto pop3:
1345 localdomains virtual.localdomain1.com virtual.localdomain2.com ...
1346 user yourISPusername is root * here,
1347 password yourISPpassword fetchall
1350 with a hack on your local sendmail.cf like this:<P>
1353 #############################################
1354 # virtual info, local hack for ruleset 98 #
1355 #############################################
1357 # domains to treat as direct mapped local domain
1359 CVvirtual.localdomain1.com virtual.localdomain2.com ...
1360 ---------------------------
1362 -------------------------
1363 # handle virtual users
1365 R$+ <@ $=V . > $: $1 < @ $j . >
1366 R< @ > $+ < @ $=V . > $: $1 < @ $j . >
1367 R< @ > $+ $: $1
1368 R< error : $- $+ > $* $#error $@ $1 $: $2
1369 R< $+ > $+ < @ $+ > $: $>97 $1
1372 This ruleset just strips virtual domain names off the addresses of incoming
1373 mail. Your sendmail must be 8.8 or newer for this to work. Michael
1377 I use this scheme with 2 virtual domains and the default ISP
1378 user+domain and service about 30 mail accounts + majordomo on my
1379 inside pop3 server with fetchmail and sendmail 8.83<P>
1383 <h2><a name="X1">X1. Spurious blank lines are appearing in the headers of fetched mail.</a></h2>
1385 What's probably happening is that the POP/IMAP daemon on your
1386 mailserver is inserting a non-RFC822 header (like X-POP3-Rcpt:) and
1387 something in your delivery path (most likely an old version of the
1388 <em>deliver</em> program, which sendmail often calls to do local delivery) is
1389 failing to recognize it as a header.<p>
1391 This is not fetchmail's problem. The first thing to try is installing
1392 a current version of <em>deliver</em>. If this doesn't work, try to
1393 figure out which other program in your mail path is inserting the
1394 blank line and replace that. If you can't do either of these things,
1395 pick a different MDA (such as procmail) and declare it with the
1396 `<CODE>mda</CODE>' option.<p>
1399 <h2><a name="X2">X2. My mail client can't see a Subject line.</a></h2>
1401 First, see <a href="#X1">X1</a>. This is quite probably the same
1402 problem (X-POP3-Rcpt header or something similar being inserted by
1403 the server and choked on by an old version of <em>deliver</em>).<p>
1405 The O'Reilly sendmail book does warn that IDA sendmail doesn't process
1406 X- headers correctly. If this is your problem, all I can suggest is
1407 replacing IDA sendmail, because it's broken and not RFC822 conformant.<p>
1410 <h2><a name="X3">X3. Messages containing "From" at start of line are being split.</a></h2>
1412 If you know the messages aren't split in your server mailbox, then this
1413 is a problem with your POP/IMAP server, your client-side SMTP listener or
1414 your local delivery agent. Fetchmail cannot split messages.<p>
1416 Some POP daemons ignore Content-Length headers and split messages on
1417 From lines. We have one report that the 2.1 version of the BSD popper
1418 program (as distributed on Solaris 2.5 and elsewhere) is broken this way.<p>
1420 You can test this. Declare an mda of `cat' and send yourself one
1421 piece of mail containing "From" at start of a line. If you see a
1422 split message, your POP/IMAP server is at fault. Upgrade to a more
1425 Sendmail and other SMTP listeners don't split RFC822 messages either.
1426 What's probably happening is either sendmail's local delivery agent or
1427 your mail reader are not quite RFC822-conformant and are breaking
1428 messages on what it thinks are Unix-style From headers. You can
1429 figure out which by looking at your client-side mailbox with vi or
1430 more. If the message is already split in your mailbox, your local
1431 delivery agent is the problem. If it's not, your mailreader is the
1434 If you can't replace the offending program, take a look at your
1435 sendmail.cf file. There will likely be a line something like<p>
1438 Mlocal, P=/usr/bin/procmail, F=lsDFMShP, S=10, R=20/40, A=procmail -Y -d $u
1441 describing your local delivery agent. Try inserting the `E' option in the
1442 flags part (the F= string). This will make sendmail turn each dangerous
1443 start-of-line From into a >From, preventing programs further downstream
1447 <h2><a name="generic_mangling"><a name="X4">X4. My mail is being mangled in a new and different way</a></a></h2>
1449 The first thing you need to do is pin down what program is doing the
1450 mangling. We don't like getting bug reports about fetchmail that are
1451 actually due to some other program's malfeasance, so please go through
1452 this diagnostic sequence before sending us a complaint.<P>
1454 There are five possible culprits to consider, listed here in the order
1455 they pass your mail:<P>
1458 <li> Programs upstream of your server mailbox.
1459 <li> The POP or IMAP server on your mailserver host.
1460 <li> The fetchmail program itself.
1461 <li> Your local sendmail.
1462 <li> Your LDA (local delivery agent), as called by sendmail or
1463 specified by <code>mda</CODE>.
1466 Often it happens that fetchmail itself is OK, but using it exposes
1467 pre-existing bugs in your downstream software, or your downstream
1468 software has a bad interaction with POP/IMAP. You need to pin down
1469 exactly where the message is being garbled in order to deduce what is
1470 actually going on.<P>
1472 The first thing to do is send yourself a test message, and retrieve it
1473 with a .fetchmailrc entry containing the following (or by running with
1474 the equivalent command-line options):<P>
1477 mda "cat >MBOX" keep fetchall
1480 This will capture exactly what fetchmail gets from the server, except
1481 for (a) the extra Received header line fetchmail prepends, (b) header address
1482 changes due to <code>rewrite</code>, and (c) any changes due to the
1483 <code>forcecr</code> and <code>stripcr</code> options. MBOX will in fact
1484 contain what programs downstream of fetchmail see.<P>
1486 The most common causes of mangling are bugs and misconfigurations in
1487 those downstream programs. If MBOX looks unmangled, you will know
1488 that is what is going on and that it is not fetchmail's problem. Take
1489 a look at the other FAQ items in this section for possible clues about
1490 how to fix your problem.<P>
1492 If MBOX looks mangled, the next thing to do is compare it with your
1493 actual server mailbox (if possible). That's why you specified
1494 <code>keep</code>, so the server copy would not be deleted. If your
1495 server mailbox looks mangled, programs upstream of your server mailbox
1496 are at fault. Unfortunately there is probably little you can do about
1497 this aside from complaining to your site postmaster, and nothing at
1498 all fetchmail can do about it!<P>
1500 More likely you'll find that the server copy looks OK. In that case
1501 either the POP/IMAP server or fetchmail is doing the mangling. To
1502 determine which, you'll need to telnet to the server port and simulate
1503 a fetchmail session yourself. This is not actually hard (both POP3
1504 and IMAP are simple, text-only, line-oriented protocols) but requires
1505 some attention to detail. You should be able to use a fetchmail -v
1506 log as a model for a session, but remember that the "*" in your LOGIN
1507 or PASS command dump has to be replaced with your actual password.<P>
1509 The objective of manually simulating fetchmail is so you can see
1510 exactly what fetchmail sees. If you see a mangled message, then your
1511 server is at fault, and you probably need to complain to your
1512 mailserver administrators. However, we like to know what the broken
1513 servers are so we can warn people away from them. So please send
1514 us a transcript of the session including the mangling <em>and the
1515 server's initial greeting line</em>. Please tell us anything else
1516 you think might be useful about the server, like the server host's
1517 operating system.<P>
1519 If your manual fetchmail simulation shows an unmangled message,
1520 congratulations. You've found an actual fetchmail bug. Complain
1521 to us and we'll fix it. Please include the session transcript of
1522 your manual fetchmail simulation along with the other things described
1523 in the FAQ entry on <a href="#G3">reporting bugs</a>.
1526 <h2><a name="O1">O1. The --logfile option doesn't work if the logfile doesn't exist.</a></h2>
1528 This is a feature, not a bug. It's in line with normal practice for
1529 system daemons and allows you to suppress logging by removing the log,
1530 without hacking potentially fragile startup scripts. To get around
1531 it, just touch(1) the logfile before you run fetchmail (this will have
1532 no effect on the contents of the logfile if it already exists).<P>
1535 <h2><a name="O2">O2. Every time I get a POP or IMAP message the header
1536 is dumped to all my terminal sessions.</a></h2>
1538 Fetchmail uses the local sendmail to perform final delivery, which
1539 Netscape and other clients doen't do; the announcement of new messages
1540 is done by a daemon that sendmail pokes. There should be a ``biff''
1541 command to control this. Type
1547 to turn it off. If this doesn't work, try the command
1553 which is essentially what <code>biff -n</code> will do. If this
1554 doesn't work, comment out any reference to ``comsat'' in your
1555 /etc/inetd.conf file and restart inetd.<P>
1557 In Slackware Linux distributions, the last line in /etc/profile is
1569 to solve the problem system-wide.<P>
1572 <h2><a name="O3">O3. Does fetchmail reread its rc file every poll cycle?</a></h2>
1574 No. Fetchmail only reads the rc file once, when it starts up. To
1575 force an rc file reread, do <code>fetchmail -q; fetchmail</code>.<P>
1578 <h2><a name="O4">O4. Why do deleted messages show up again when I take
1579 a line hit while downloading?</a></h2>
1581 Because you're using a POP3 other than Qualcomm qpopper, or an IMAP
1582 with a long expunge interval.<P>
1584 According to the POP3 RFCs, deletes aren't actually performed until
1585 you issue the end-of-session QUIT command. Fetchmail cannot fix this,
1586 it takes cooperation from the. server. There are two possible
1589 One is to switch to qpopper (the freeware POP3 server from Qualcomm,
1590 the Eudora people). The qpopper software violates the POP3 RFCs by
1591 doing an expunge (removing deleted messages) on a line hangup, as well
1592 as on processing a QUIT command.<P>
1594 The other (which we recommend) is to switch to <a
1595 href="http://www.imap.org">IMAP</a>. IMAP has an explicit expunge
1596 command and fetchmail normally uses it to delete messages immediately
1597 after they are downloaded.<P>
1599 If you get very unlucky, you might take a line hit in the window
1600 between the delete and the expunge. If you've set a longer expunge
1601 interval, the window gets wider. This problem should correct itself
1602 the next time you complete a successful query.<P>
1605 <h2><a name="O5">O5. Why is fetched mail being logged with my name, not the real From address?</a></h2>
1607 Because logging is done based on the address indicated by the sending
1608 SMTP's MAIL FROM, and some listeners are picky about that address.<p>
1610 Some SMTP listeners get upset if you try to hand them a MAIL FROM
1611 address naming a different host than the originating site for your
1612 connection. This is a feature, not a bug -- it's supposed to help
1613 prevent people from forging mail with a bogus origin site. (RFC 1123
1614 says you shouldn't do this exclusion...)<p>
1616 Since the originating site of a fetchmail delivery connection is
1617 localhost, this effectively means these picky listeners will barf on
1618 any MAIL FROM address fetchmail hands them with an @ in it!<p>
1620 Versions 2.1 and up try the header From address first and fall back to
1621 the calling-user ID. So if your SMTP listener isn't picky, the log
1625 <table width="100%" cellpadding=0><tr>
1626 <td width="30%">Back to <a href="index.html">Fetchmail Home Page</a>
1627 <td width="30%" align=center>To <a href="/~esr/sitemap.html">Site Map</a>
1628 <td width="30%" align=right>$Date: 1997/11/22 07:26:00 $
1631 <P><ADDRESS>Eric S. Raymond <A HREF="mailto:esr@thyrsus.com"><esr@snark.thyrsus.com></A></ADDRESS>
projects / ~andy / fetchmail / blob