Before reporting any bug, please read G3 for -advice on how to include diagnostic information that will get your -bug fixed as quickly as possible.
+Support? Bug reports? Please read G3 for what information is required to get your problem +solved as quickly as possible.
-Note that this FAQ is occasionally updated from the SVN repository +
Note that this FAQ is occasionally updated from the Git repository and speaks in the past tense ("since") about a fetchmail release that is not yet available. Please try a release candidate for that version in case you need the new option.
@@ -70,9 +70,9 @@ below). G1. What is fetchmail and why should I bother?Fetchmail is licensed under the GNU General Public -License.
+href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html">GNU General Public +License v2. Details, including an exception that allows linking +against OpenSSL, are in the COPYING file in the fetchmail +distribution.If you found this FAQ in the distribution, see the README for fetchmail's full feature list.
@@ -333,8 +344,7 @@ POP mail tools directory on iBiblio. distribution. Because it freezes at distribution release time, it may not be completely current. -The first thing you should to is to upgrade to the newest version of
fetchmail, and then see if the problem reproduces. So you'll probably
@@ -344,7 +354,9 @@ save us both time if you upgrade and test with the latest
Bugs will be fixed, provided you include enough diagnostic information
for me to go on. Send bugs to fetchmail-users.
-When reporting bugs, please include the following:
It is very important that the transcript include your +POP/IMAP server's greeting line, so I can identify it in case of server +problems. This transcript will not reveal your passwords, which are +specially masked out precisely so transcripts can be passed around.
+If you have FTP access to your remote mail account, and you have @@ -381,22 +398,17 @@ introduced in the upper half of the sequence; if it doesn't, the failure was introduced in the lower half. Now bisect that half in the same way. In a very few tries, you should be able to identify the exact adjacent pair of versions between which your bug was -introduced – and with information like that, I can usually come up -with a fix very quickly.
- -Another useful thing you can do, if you're using POP3, is to -test for IMAP4 support on your mailserver using the autoprobe -function of fetchmailconf. If you have IMAP4, and fetchmailconf -doesn't tell you it's broken, switch immediately. POP3 is a weak, -poorly-designed protocol with chronic problems, and the later -versions after RFC1725 actually get worse rather than better. -Changing over to IMAP4 may well make your problem go away – and if -your ISP doesn't have IMAP4 support, bug them to supply it.
- -It is helpful if you include your .fetchmailrc file, but not +introduced. Please include session transcripts (as +described in the last bullet point above) of both +the working and failing versions. Often, the source of the problem +can instantly identified by looking at the differences in protocol +transactions.
+ +It may helpful if you include your .fetchmailrc file, but not necessary unless your symptom seems to involve an error in configuration parsing. If you do send in your .fetchmailrc, mask -the passwords first!
+the passwords first! Otherwise, fetchmail -V – as directed above +– will usually suffice.If fetchmail seems to run and fetch mail, but the headers look mangled (that is, headers are missing or blank lines are inserted @@ -407,19 +419,6 @@ mail mangling. There are lots of ways for other programs in the mail chain to screw up that look like fetchmail's fault, but you may be able to fix these by tweaking your configuration.
-A transcript of the failed session with "--nosyslog --nodetach -vvv" -(yes, that's three -v options, enabling debug mode) will almost -always be useful. It is very important that the transcript include your -POP/IMAP server's greeting line, so I can identify it in case of server -problems. This transcript will not reveal your passwords, which are -specially masked out precisely so transcripts can be passed around.
- -If you upgraded your fetchmail and something broke, you should -include session transcripts with "--nosyslog --nodetach -vvv" of both -the working and failing versions. Very often, the source of the problem -can instantly identified by looking at the differences in protocol -transactions.
-If the bug involves a core dump or hang, a gdb stack trace is good to have. (Bear in mind that you can attach gdb to a running but hung process by giving the process ID as a second argument.) @@ -471,32 +470,37 @@ href="esrs-design-notes.html">ESR's design notes. Note that this document is partially obsoleted by the updated design notes.
-The second-most-requested feature for fetchmail, after
content-based filtering, is the ability to have it remove messages
from a maildrop after N days, typically to be used with the
-keep option as a sort of poor man's newsgroup
-facility. Microsoft's Outlook Express supports this.
keep option. Several messaging programs with graphical
+user interface support this feature.
This feature is not yet implemented. It may be at a future date, spare time of developers permitting.
+For the time being, the contrib/ directory contains some unsupported + tools that may help, namely mold-remover.py and delete-later.
+There is a fetchmail-users list <fetchmail-users@lists.berlios.de> for bug reports and people who want to discuss configuration issues of -fetchmail. It's a Mailman list, see http://lists.berlios.de/mailman/listinfo/fetchmail-users.
+fetchmail. Please see G3 above for information you need to +report. It's a Mailman list, see http://lists.berlios.de/mailman/listinfo/fetchmail-users +for info and subscription.There is a fetchmail-devel list <fetchmail-devel@lists.berlios.de> for people who want to discuss fixes and improvements in fetchmail and help co-develop it. It's a Mailman list, which you can sign up for at http://lists.berlios.de/mailman/listinfo/fetchmail-devel. -There is also an announcements-only list, +href="http://lists.berlios.de/mailman/listinfo/fetchmail-devel">http://lists.berlios.de/mailman/listinfo/fetchmail-devel.
+There is also an announcements-only list, <fetchmail-announce@lists.berlios.de>, which you can sign up for at http://lists.berlios.de/mailman/listinfo/fetchmail-announce.
@@ -540,16 +544,7 @@ minority also feature IMAP (you can detect IMAP support by using the utility - unfortunately it does not detect SSL-wrapped variants).If you have the option, we recommend using or installing an -IMAP4rev1 or UIDL- and TOP-capable POP3 server. IMAP enables some -significant performance optimizations.
- -Don't be fooled by NT/Exchange propaganda. M$ Exchange is just -plain broken (see item S2) and NT cannot handle -the sustained load of a high-volume remote mail server. Even -Microsoft itself knows better than to try this; their own Hotmail -service runs over Solaris! For extended discussion, see John -Kirch's excellent white -paper on Unix vs. NT performance.
+IMAP4rev1 or UIDL-capable POP3 server.A decent POP3/IMAP server that has recently become popular is Dovecot.
@@ -1276,7 +1271,7 @@ mainsite.example.com is polled, which with a polling interval of every 5 minutes means that secondary.example.com will be polled every 30 minutes. -Often, startup scripts have a different environment than an @@ -1296,6 +1291,37 @@ host?
smtphost or
smtpname option. See the manual page for details.
+Some users want to write scripts that take action only if mail +could/could not be retrieved, thus fetchmail reports if it has retrieved +messages or not.
+ +If you do not want "no mail" to be an error condition (for instance, +for cron jobs), use a POSIX-compliant shell and add this to the end of +the fetchmail command line, it will change an exit code of 1 to 0 and +others to 1:
++|| [ $? -eq 1 ] ++ +
If you want to map more than one code to 0, you cannot cascade multiple +|| [ $? -eq N ], but you must instead use the +-o operator inside the brackets, (see the test(1) +manpage for details), such as:
+ ++|| [ $? -eq 1 -o $? -eq 9 ] ++ +
A full cron line might then look like this:
+ ++*/15 * * * * fetchmail -s || [ $? -eq 1 ] ++ +
Fetchmail using IMAP supports the proprietary NTLM mode used -with M$ Exchange servers. To enable this, configure fetchmail with +
Fetchmail using IMAP usually supports the proprietary NTLM mode used +with Microsoft Exchange servers. "Usually" here means that it fails on some +servers for reasons that we haven't been able to debug yet, perhaps it's +related to the NTLM domain.
+ +To enable this NTLM mode, configure fetchmail with the --enable-NTLM option and recompile it. Specify a user option value that looks like 'user@domain': the part to the left of the @ will be passed as the username and the part to the right as the NTLM domain.
-M$ Exchange violates the POP3 and IMAP RFCs. Its LIST command +
Microsoft Exchange violates the POP3 and IMAP RFCs. Its LIST command does not reveal the real sizes of mail in the pop mailbox, but the sizes of the compressed versions in the exchange mail database (thanks to Arjan De Vet and Guido Van Rooij for alerting us to this problem).
-Fetchmail works with M$ Exchange, despite this brain damage. Two -features are compromised. One is that the --limit option will not +
Fetchmail works with Microsoft Exchange, despite this brain damage. +Two features are compromised. One is that the --limit option will not work right (it will check against compressed and not actual sizes). The other is that a too-small SIZE argument may be passed to your ESMTP listener, assuming you're using one (this should not be a problem unless the actual size of the message is above the listener's configured length limit).
-Somewhat belatedly, I've learned that there's supposed to be a +
ESR learned that there's supposed to be a registry bit that can fix this breakage:
@@ -1660,7 +1690,7 @@ reported in KB Q168109) deleted. -. The message sizes it gives in the LIST are rounded to the nearest 1024 bytes. It also has a nasty habit of discarding headers it doesn't recognize, such as X- and Resent- headers. - -The Microsoft pod-person who revealed this information to me +
The Microsoft employee who revealed this information to ESR admitted that he couldn't find it anywhere in their public knowledge base.
@@ -1668,7 +1698,7 @@ knowledge base. as its symptom a response to LOGIN that says "NO Ambiguous Alias". Grant Edwards writes: -This means that Exchange Server is too f*&#ing stupid to +
This means that Exchange Server is too [...] stupid to figure out which mailbox belongs to you. Instead of actually keeping track of which inbox belongs to which user, it uses some half-witted, guess-o-matic heuristic to try to guess your mailbox @@ -1676,9 +1706,7 @@ name from your username.
In your case it doesn't work because your username maps to more than one mailbox. For some people it doesn't work because their -username maps to zero mailboxes. This is yet another inept, lame, -almost criminally negligent design decision from our friends in -Redmond.
+username maps to zero mailboxes.You've got several options:
@@ -1689,6 +1717,7 @@ usernames and mailbox names are the same.Get your administrator to add an alias that maps your username explicitly to your mailbox name. +But, the best option involves finding a server that runs better software.
@@ -1702,10 +1731,7 @@ href="#S2">Microsoft Exchange
As with M$ Exchange, the only real fix for these problems is to -get a POP (or preferably IMAP) server that isn't brain-dead. -OpenMail's project manager claims these bugs have been fixed in +
OpenMail's project manager claims these bugs have been fixed in 6.0.
We've had a more recent report (December 2001) that the TOP @@ -1714,13 +1740,11 @@ on something identifying itself as "OpenMail POP3 interface".
The Novell GroupWise IMAP server would be better named -GroupFoolish; it is (according to the designer of IMAP) unusably -broken. Among other things, it doesn't include a required content -length in its BODY[TEXT] response.
+The Novell GroupWise IMAP server is (according to the designer of +IMAP) unusably broken. Among other things, it doesn't include a required +content length in its BODY[TEXT] response.
-Fetchmail works around this problem, but we strongly recommend -voting with your dollars for a server that isn't brain-dead.
+Fetchmail works around this problem to some extent, but no guarantees.
On Jan 9 2001, the people at InfiniteMail sent me mail informing -me that their new 3.61.08 release of InterChange fixes this -problem. I don't have any reports one way or the other yet.
+On Jan 9 2001, the people at InfiniteMail sent ESR mail informing +him that their new 3.61.08 release of InterChange fixed this +problem.
Workaround for older versions: use the fetchall option.
+Google's IMAP servers, as of April 2008, are broken and re-encode +MIME-encoded headers improperly and are not feature-complete yet. The +model how their servers organize mail also deviates in significant ways +from what the POP3 or IMAP protocol 'fathers' conceived. This means all +sorts of strange effects, for instance, your sent mail may show up in +the mail that fetchmail fetches. It's best to avoid fetching mail from +Google until they are using standards-compliant software.
+ +If you still need to use Google's mail service, these links may help (valid as of 2011-04-13):
+Fetchmail can use RFC1731 GSSAPI authorization to safely identify you to your IMAP server, as long as you can share Kerberos V credentials with your mail host and you have a GSSAPI-capable -IMAP server - those are few.
+IMAP server.fetchmail does not compile in support for GSS by -default, since it requires libraries from the Kerberos V -distribution (available via FTP at athena-dist.mit.edu). -If you have these, compiling in GSS support is simple: add a +default, since it requires libraries from a Kerberos V +distribution, such as MIT + Kerberos or Heimdal + Kerberos.
+ +If you have these, compiling in GSS support is simple: add a
You'll need to have the OpenSSL libraries installed, and they
-should at least be version 0.9.6.
+should at least be version 0.9.7.
Configure with --with-ssl. If you have the OpenSSL libraries
-installed in the default location (/usr/local/ssl) ths will
+installed in commonly-used default locations, this will
suffice. If you have them installed in a non-default location,
-you'll need to specify it as an argument to --with-ssl after an
-equal sign.--with-gssapi=[/path/to/krb5/root] option to
configure. For instance, I have all of my Kerberos V libraries
installed under /usr/krb5 so I run configure
@@ -2075,12 +2120,12 @@ SSL?
Fetchmail binaries built this way support ssl,
sslkey, and sslcert options that control
@@ -2444,6 +2489,63 @@ declaration auth password in your .fetchmailrc.
If the upgrade you did encompassed an upgrade to OpenSSL 1.0.0 or newer, you
+may need to run c_rehash on your certificate directories,
+particularly if you are using local certs directories (f. i. through fetchmail's --sslcertpath option).
Reason: OpenSSL 1.0.0, relative to earlier versions, uses a different hash
+for the symbolic links (symlinks) in its certs/ directory, so you
+need to recreate the symlinks by running c_rehash
+ /etc/ssl/certs (adjust this to where your installation keeps its
+certificates), and you cannot easily share this certs directory with
+applications linked against older OpenSSL versions.
Note: OpenSSL's c_rehash script is broken in several versions,
+which can cause malfunction if several OpenSSL tools versions are installed in
+parallel in separate directories. In such cases, you may need a workaround to
+get things going. Assuming your OpenSSL 1.0.0 is installed in
+/opt/openssl1.0.0 and your certificates are in
+/home/hans/certs, you'd do this (the corresponding fetchmail
+option is --sslcertpath /home/hans/certs on the commandline and
+sslcertpath /home/hans/cert in the rcfile):
+env PATH=/opt/openssl1.0.0/bin /opt/openssl1.0.0/bin/c_rehash /home/hans/certs ++ +
First, try upgrading to fetchmail 6.3.18 or newer. Release 6.3.18 has +received a considerable number of bug fixes for the authentication +feature (AUTH, AUTHENTICATE, SASL). Most notably, fetchmail aborts SASL +authentication attempts properly with an asterisk if it detects that it +cannot make progress with a particular authentication scheme. This fixes +issues where GSSAPI-enabled fetchmail cannot authenticate against +Microsoft Exchange 2007 and 2010. Note that this is a +bug in old fetchmail versions!
+ +Fetchmail by default attempts to authenticate using various schemes. +Fetchmail tries these schemes in order of descending security, meaning +the most secure schemes are tried first.
+ +However, sometimes the server offers a secure authentication scheme +that is not properly configured, or an authentication scheme such as +GSSAPI does requires credentials to be acquired externally. In some +situations, fetchmail cannot know the scheme will fail without trying +it. In most cases, fetchmail should proceed to the next authentication +scheme automatically, but this sometimes does not work.
+ +Solution: Configure the right authentication scheme
+explicitly, for instance, with --auth cram-md5 or --auth
+ password on the command line or auth "cram-md5" or
+ auth "password" in the rcfile. Details can be found
+ in the manual page.
+ Note that auth password should only be used
+ across secure links (see the sslcertck and ssl/sslproto options).
+
The symption: 'fetchmail -v' retrieves the first few messages, +
Symptom: 'fetchmail -v' retrieves the first few messages, but hangs returning:
@@ -2676,7 +2778,8 @@ chop the host part off any local addresses in the list.+-
M4. My multidrop fetchmail seems to be having DNS problems.The answer that used to be here no longer applies to fetchmail.
+The answer that used to be here no longer applies to + fetchmail.
M5. I'm seeing long DNS delays before each message is processed.
@@ -2970,11 +3073,8 @@ on reporting bugs.-
X5. Using POP3, retrievals seems to be fetching too much!The information that used to be here pertained to fetchmail 4.4.7 or -older, which should not be used. Use a recent fetchmail version.
- -Workaround: set the
+fetchalloption. Under POP3 -this has the side effect of forcing RETR use.The information that used to be here pertained to fetchmail 4.4.7 or + older, which should not be used. Use a recent fetchmail version.
X6. My mail attachments are being dropped or mangled.
@@ -3114,9 +3214,8 @@ mailtool's format.X7. Some mail attachments are hanging fetchmail.
-This isn't fetchmail's problem either; fetchmail doesn't know -anything about mail attachments and doesn't treat them any -differently from plain message data.
+Fetchmail doesn't know anything about mail attachments and doesn't +treat them any differently from plain message data.
The most usual cause of this problem seems to be bugs in your network transport layer's capability to handle the very large @@ -3137,51 +3236,49 @@ Hayes mode escape "+++".
X8. A spurious ) is being appended to my messages.
-Blame it on that rancid pile of dung and offal called Microsoft -Exchange. Due to the problem described in S2, the -IMAP support in fetchmail cannot follow the IMAP protocol 100%. +
Due to the problem described in S2, the +IMAP support in fetchmail cannot follow the IMAP protocol 100 %. Most of the time it doesn't matter, but if you combine it with an SMTP server that behaves unusually, you'll get a spurious ) at -message end.
+the message end.One piece of software that can trigger this is the Interchange mail server, as used by, e.g., mailandnews.com. Here's what happens:
-1. Someone sends mail to your account. The last line of the +
-
- Someone sends mail to your account. The last line of the message contains text. So at the SMTP level, the message ends with, -e.g. "blahblah\r\n.\r\n" +e.g. "blahblah\r\n.\r\n"
-2. The SMTP handler sees the final "\r\n.\r\n" and recognizes +
- The SMTP handler sees the final "\r\n.\r\n" and recognizes the end of the message. However, instead of doing the normal thing, which is tossing out the ".\r\n" and leaving the first '\r\n' as part of the email body, Interchange throws out the whole "\r\n.\r\n", and leaves the email body without any line terminator at the end of it. RFC821 does not forbid this, though it probably -should. +should.
-3. Fetchmail, or some other IMAP client, asks for the message. +
- Fetchmail, or some other IMAP client, asks for the message. IMAP returns it, but it's enclosed inside parentheses, according to the protocol. The message size in bytes is also present. Because the message doesn't end with a line terminator, the IMAP client -sees: +sees:
-- ....blahblah)...-where the ')' is from IMAP.
+where the ')' is from IMAP.
4. Fetchmail only deals with complete lines, and can't trust the -stated message size because Microsoft Exchange fscks it up.
+- Fetchmail only deals with complete lines, and can't trust the +stated message size because Microsoft Exchange goofs it up.
-5. As a result, fetchmail takes the final 'blahblah)' and puts +
- As a result, fetchmail takes the final 'blahblah)' and puts it at the end of the message it forwards on. If you have verbosity -on, you'll get a message about actual != expected. +on, you'll get a message about actual != expected.
+There is no fix for this. The nuke mentioned in S2 looks more tempting all the time.
+There is no fix for this.
X9. Missing "Content-Transfer-Encoding" header with Domino IMAP
@@ -3197,6 +3294,24 @@ MIME". Solution: switch Domino to "Keep in Sender's format". Kim's list post
Fetchmail is sometimes reported to deliver partial messages. This +is usually related to network outages that occur while fetchmail is +downloading a message body. In such cases, fetchmail has downloaded a +complete header, so your header will be intact. The message body will be +truncated, and fetchmail will later attempt to redownload the +message (providing the server is standards conformant).
+ +The reason for the truncation is that fetchmail streams the body +directly from the POP3/IMAP server into the SMTP/LMTP server or MDA (in +order to save memory), so fetchmail has already written a part of the +message before it notices it will be incomplete, and fetchmail cannot +abort a transaction it has started, and it's unclear if it ever will be +able to, because this is not standardized and the outcome will depend on +the receiving software (be it SMTP/LMTP or MDA).
+The answer that used to be here made no sense.
+The answer that used to be here made no sense and was dropped.
That's in fact a bug in Linux kernels around the late 2.6.2X versions, +rather than fetchmail. Fetchmail has no race bugs around MSG_PEEK, +as of version 6.3.9. The message can safely be ignored.