<title>The Fetchmail FAQ</title>
<meta name="description"
content="Frequently asked questions about fetchmail."/>
-<meta name="keywords" content="fetchmail, POP, POP2, POP3, IMAP, remote mail"/>
+<meta name="keywords" content="fetchmail, POP3, IMAP, remote mail"/>
</head>
<body>
<table width="100%" cellpadding="0" summary="Canned page footer">
<hr/>
<h1 id="FAQ">Frequently Asked Questions About Fetchmail</h1>
-<p><strong>Support? Bug reports?</strong> Please read <a
-href="#G3">G3</a> for what information is required to get your problem
+<p><strong>Support? Bug reports?</strong> Please read <a
+href="#G3">G3</a> for what information is required to get your problem
solved as quickly as possible.</p>
-<p>Note that this FAQ is occasionally updated from the SVN repository
+<p>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.</p>
<a href="#C6">C6. Fetchmail works OK started up manually, but not
from an init script.</a><br/>
<a href="#C7">C7. How can I forward mail to another
-host?.</a><br/>
-
+host?</a><br/>
+<a href="#C8">C8. Why is "NOMAIL" an error?/I frequently get messages
+from cron!</a><br/>
<h2 id="C_T">How to make fetchmail play nice with various MTAs</h2>
<a href="#R11">R11. My server is hanging or emitting errors on CAPA.</a><br/>
<a href="#R12">R12. Fetchmail isn't working and reports getaddrinfo
errors.</a><br />
-<a href="#R13">R13. What does "Interrupted system call" mean?</a>
+<a href="#R13">R13. What does "Interrupted system call" mean?</a><br />
+<a href="#R14">R14. Since upgrading fetchmail/OpenSSL, I can no longer connect!</a><br />
+<a href="#R15">R15. Help, I'm getting Authorization failure!</a><br />
<h2 id="C_H">Hangs and lockups</h2>
messages.</a><br/>
<a href="#X9">X9. Missing "Content-Transfer-Encoding" header
with Domino IMAP</a><br/>
+<a href="#X10">X10. Fetchmail delivers partial messages</a><br/>
+
+
<h2 id="C_O">Other problems</h2>
<a href="#O1">O1. The --logfile option doesn't work if the logfile
<a href="#O16">O16. Why is the Fetchmail FAQ only available in
ISO-216 A4 format? How do I get the FAQ in Letter
format?</a><br/>
+<a href="#O17">O17. Linux logs "TCP(fetchmail:...): Application bug, race
+ in MSG_PEEK."</a><br/>
<hr/>
<h1 id="G">General problems</h1>
not audit itself.</p>
<p>Fetchmail is licensed under the <a
-href="http://www.gnu.org/copyleft/gpl.html">GNU General Public
-License</a>.</p>
+href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html">GNU General Public
+License v2</a>. Details, including an exception that allows linking
+against OpenSSL, are in the COPYING file in the fetchmail
+distribution.</p>
<p>If you found this FAQ in the distribution, see the README for
fetchmail's full feature list.</p>
<p>Bugs will be fixed, provided you include enough diagnostic information
for me to go on. Send bugs to <a
href="mailto:fetchmail-users@lists.berlios.de">fetchmail-users</a>.
-When reporting bugs, please include the following:</p>
+When sending bugs or asking for help, please <strong>do not make up
+ information except your password</strong> and please
+<strong>report</strong> the following:</p>
<ol>
<li>Your operating system.</li>
<li>Any command-line options you used.</li>
-<li>The output of <kbd>env LC_ALL=C fetchmail -V</kbd> called with
+<li>The output of <kbd>env LC_ALL=C fetchmail -V</kbd> called with
whatever other command-line options you used.</li>
-<li><strong>The output of <kbd>env LC_ALL=C fetchmail --nodetach -vvv
---nosyslog</kbd> with whatever other command-line options you use
+<li><strong>The output of <kbd>env LC_ALL=C fetchmail --nodetach -vvv
+--nosyslog</kbd> with whatever other command-line options you use
routinely.</strong>
<p>It is very important that the transcript include your
POP/IMAP server's greeting line, so I can identify it in case of server
<p>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! Otherwise, fetchmail -V – as directed above
+the passwords first! Otherwise, fetchmail -V – as directed above
– will usually suffice.</p>
<p>If fetchmail seems to run and fetch mail, but the headers look
<h2><a id="G8" name="G8">G8. What is the best server to use with
fetchmail?</a></h2>
-<p>Fetchmail will work with any POP, IMAP, ETRN, or ODMR server
+<p>Fetchmail will work with any POP3, IMAP, ETRN, or ODMR server
that conforms to the relevant standards/RFCs (and even some outright
broken ones like <a href="#S2">Microsoft Exchange</a> and <a
href="#S6">Novell GroupWise</a>). This doesn't mean it works equally
-well with all, however. POP2 servers, and POP3 servers without UIDL,
+well with all, however. POP3 servers without UIDL
limit fetchmail's capabilities in various ways described on the manual
page.</p>
utility - unfortunately it does not detect SSL-wrapped variants).</p>
<p>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.</p>
-
-<p>Don't be fooled by NT/Exchange propaganda. M$ Exchange is just
-plain broken (see item <a href="#S2">S2</a>) 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 <a href="http://unix-vs-nt.org/kirch/">white
-paper</a> on Unix vs. NT performance.</p>
+IMAP4rev1 or UIDL-capable POP3 server.</p>
<p>A decent POP3/IMAP server that has recently become popular is <a
href="http://dovecot.org/">Dovecot</a>.</p>
fetchmail on, use the <code>smtphost</code> or
<code>smtpname</code> option. See the manual page for details.</p>
+<h2><a id="C8" name="C8">C8. Why is "NOMAIL" an error?/I frequently get messages
+from cron!</a></h2>
+
+<p>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.</p>
+
+<p>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:</p>
+<pre>
+|| [ $? -eq 1 ]
+</pre>
+
+<p>If you want to map more than one code to 0, you cannot cascade multiple
+<strong>|| [ $? -eq N ]</strong>, but you must instead use the
+<strong>-o</strong> operator inside the brackets, (see the test(1)
+manpage for details), such as:</p>
+
+<pre>
+|| [ $? -eq 1 -o $? -eq 9 ]
+</pre>
+
+<p>A full cron line might then look like this:</p>
+
+<pre>
+*/15 * * * * fetchmail -s || [ $? -eq 1 ]
+</pre>
+
+
<hr/>
<h1>How to make fetchmail play nice with various MTAs</h1>
<h2><a id="T1" name="T1">T1. How can I use fetchmail with
a terminating newline get the POP3 message termination dot emitted
-- you guessed it -- right after the last character of the message,
with no terminating newline added. This will hang fetchmail or any
-other RFC-compliant server. IMAP is alleged to work OK, though.</p>
+other RFC-compliant client. IMAP is alleged to work OK, though.</p>
+
+<p>Exchange 2003 SP2 has been observed to alter MIME boundary
+lines in multipart messages between one IMAP FETCH command and the next
+under some circumstances -- for instance, when the top-level
+Content-Transfer-Encoding is "binary" (which is commonplace with Perl's
+MIME::Lite module). This causes MUAs to not detect attachments, but
+render the whole message body as one lump of hardly legible to
+unintelligible text, rather than nicely presenting text part and
+attachments or images separately. The cause is that Exchange uses its
+own message store and needs to convert back to MIME message format
+on-the-fly, and apparently this is sometimes subject to such
+inconsistencies.
+</p>
-<p>Older versions of Exchange are semi-usable. They randomly drop
-attachments on the floor, though. Microsoft acknowledges this
-as a known bug and apparently has no plans to fix it.</p>
+<p>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.</p>
-<p>Fetchmail using IMAP supports the proprietary NTLM mode used
-with M$ Exchange servers. To enable this, configure fetchmail with
+<p>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.</p>
-<p>M$ Exchange violates the POP3 and IMAP RFCs. Its LIST command
+<p>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).</p>
-<p>Fetchmail works with M$ Exchange, despite this brain damage. Two
-features are compromised. One is that the --limit option will not
+<p>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).</p>
-<p>Somewhat belatedly, I've learned that there's supposed to be a
+<p>ESR learned that there's supposed to be a
registry bit that can fix this breakage:</p>
<pre>
deleted.</dd>
</dl>
-<p>The Microsoft pod-person who revealed this information to me
+<p>The Microsoft employee who revealed this information to ESR
admitted that he couldn't find it anywhere in their public
knowledge base.</p>
as its symptom a response to LOGIN that says "NO Ambiguous Alias".
Grant Edwards writes:</p>
-<p>This means that Exchange Server is too f*&#ing stupid to
+<blockquote><p>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
<p>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.</p>
+username maps to zero mailboxes.</p>
<p>You've got several options:</p>
<li>Get your administrator to add an alias that maps your username
explicitly to your mailbox name.</li>
</ul>
-
-<p>But, the best option involves finding a server that runs better
-software.</p>
+</blockquote>
<h2><a id="S3" name="S3">S3. How can I use fetchmail with HP
OpenMail?</a></h2>
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.</p>
-
-<p>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
+<p>OpenMail's project manager claims these bugs have been fixed in
6.0.</p>
<p>We've had a more recent report (December 2001) that the TOP
<h2><a id="S4" name="S4">S4. How can I use fetchmail with Novell GroupWise?</a></h2>
-<p>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.</p>
+<p>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.</p>
-<p>Fetchmail works around this problem, but we strongly recommend
-voting with your dollars for a server that isn't brain-dead.</p>
+<p>Fetchmail works around this problem to some extent, but no guarantees.</p>
<h2><a id="S5" name="S5">S5. How can I use fetchmail with
InterChange?</a></h2>
it reports the message length with attachments but doesn't download
them on TOP or RETR.</p>
-<p>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.</p>
+<p>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.</p>
<h2><a id="S6" name="S6">S6. How can I use fetchmail with MailMax?</a></h2>
the mail that fetchmail fetches. It's best to avoid fetching mail from
Google until they are using standards-compliant software.</p>
+<p>If you still need to use Google's mail service, these links may help (valid as of 2011-04-13):</p>
+<ul>
+ <li><a href="http://mail.google.com/support/bin/topic.py?hl=en&topic=12805">Other ways to access Gmail > POP</a></li>
+ <li><a href="http://mail.google.com/support/bin/topic.py?hl=en&topic=12806">Other ways to access Gmail > IMAP</a></li>
+<li><a href="http://mail.google.com/support/bin/answer.py?hl=en&answer=47948">Using POP on multiple clients or mobile devices</a></li>
+<li><a href="http://mail.google.com/support/bin/answer.py?hl=en&answer=13291">Some [POP3] mail was not downloaded</a></li>
+<li><a href="http://mail.google.com/support/bin/answer.py?hl=en&answer=78774">I'm having problems downloading [IMAP] mail</a></li>
+</ul>
+
<hr/>
<h1>How to set up well-known security and authentication
methods</h1>
<p>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.</p>
+IMAP server.</p>
<p>fetchmail does not compile in support for GSS by
-default, since it requires libraries from the Kerberos V
-distribution (available via FTP at <a
-href="ftp://athena-dist.mit.edu/pub/ATHENA/kerberos">athena-dist.mit.edu</a>).
-If you have these, compiling in GSS support is simple: add a
+default, since it requires libraries from a Kerberos V
+distribution, such as <a href="http://web.mit.edu/Kerberos/">MIT
+ Kerberos</a> or <a href="http://www.h5l.org/">Heimdal
+ Kerberos</a>.</p>
+
+<p>If you have these, compiling in GSS support is simple: add a
<code>--with-gssapi=[/path/to/krb5/root]</code> option to
configure. For instance, I have all of my Kerberos V libraries
installed under /usr/krb5 so I run <code>configure
<p>You'll need to have the <a
href="http://www.openssl.org/">OpenSSL</a> 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 commonly-used default locations, this will
suffice. If you have them installed in a non-default location,
interrupt long-running functions and will then be reported as
"Interrupted system call". These can sometimes be timeouts.</p>
+<h2><a id="R14" name="R14">R14. Since upgrading fetchmail/OpenSSL, I can no longer connect!</a></h2>
+
+<p>If the upgrade you did encompassed an upgrade to OpenSSL 1.0.0 or newer, you
+may need to run <code>c_rehash</code> on your certificate directories,
+particularly if you are using local certs directories (f. i. through fetchmail's <code>--sslcertpath</code> option).</p>
+
+<p>Reason: OpenSSL 1.0.0, relative to earlier versions, uses a different hash
+for the symbolic links (symlinks) in its <code>certs/</code> directory, so you
+need to recreate the symlinks by running <kbd>c_rehash
+ /etc/ssl/certs</kbd> (adjust this to where your installation keeps its
+certificates), and you cannot easily share this certs directory with
+applications linked against older OpenSSL versions.</p>
+
+<p>Note: OpenSSL's <code>c_rehash</code> 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
+<code>/opt/openssl1.0.0</code> and your certificates are in
+<code>/home/hans/certs</code>, you'd do this (the corresponding fetchmail
+option is <kbd>--sslcertpath /home/hans/certs</kbd> on the commandline and
+<kbd>sslcertpath /home/hans/cert</kbd> in the rcfile):</p>
+
+<pre>
+env PATH=/opt/openssl1.0.0/bin /opt/openssl1.0.0/bin/c_rehash /home/hans/certs
+</pre>
+
+<h2><a id="R15" name="R15">R15. Help, I'm getting Authorization failure!</a></h2>
+
+<p>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. <strong>Note</strong> that this is a
+bug in old fetchmail versions!</p>
+
+<p>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.</p>
+
+<p>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.</p>
+
+<p><strong>Solution:</strong> Configure the right authentication scheme
+explicitly, for instance, with <kbd>--auth cram-md5</kbd> or <kbd>--auth
+ password</kbd> on the command line or <code>auth "cram-md5"</code> or
+ <code>auth "password"</code> in the rcfile. Details can be found
+ in the manual page.<br />
+ <strong>Note</strong> that auth password should only be used
+ across secure links (see the sslcertck and ssl/sslproto options).
+ </p>
+
<hr/>
<h1>Hangs and lockups</h1>
<h2><a id="H1" name="H1">H1. Fetchmail hangs when used with
<h2><a id="H3" name="H3">H3. Fetchmail hangs while fetching
mail.</a></h2>
-<p>The symption: 'fetchmail -v' retrieves the first few messages,
+<p>Symptom: 'fetchmail -v' retrieves the first few messages,
but hangs returning:</p>
<pre>
<h2><a id="X7" name="X7">X7. Some mail attachments are hanging
fetchmail.</a></h2>
-<p>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.</p>
+<p>Fetchmail doesn't know anything about mail attachments and doesn't
+treat them any differently from plain message data.</p>
<p>The most usual cause of this problem seems to be bugs in your
network transport layer's capability to handle the very large
<h2><a id="X8" name="X8">X8. A spurious ) is being appended to my
messages.</a></h2>
-<p>Blame it on that rancid pile of dung and offal called Microsoft
-Exchange. Due to the problem described in <a href="#S2">S2</a>, the
-IMAP support in fetchmail cannot follow the IMAP protocol 100%.
+<p>Due to the problem described in <a href="#S2">S2</a>, 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.</p>
+the message end.</p>
<p>One piece of software that can trigger this is the Interchange
mail server, as used by, e.g., mailandnews.com. Here's what
happens:</p>
-<p>1. Someone sends mail to your account. The last line of the
+<ol><li>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"</p>
+e.g. "blahblah\r\n.\r\n"</li>
-<p>2. The SMTP handler sees the final "\r\n.\r\n" and recognizes
+<li>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.</p>
+should.</li>
-<p>3. Fetchmail, or some other IMAP client, asks for the message.
+<li>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:</p>
+sees:
<pre>
-
....blahblah)...
</pre>
-<p>where the ')' is from IMAP.</p>
+<p>where the ')' is from IMAP.</p></li>
-<p>4. Fetchmail only deals with complete lines, and can't trust the
-stated message size because Microsoft Exchange fscks it up.</p>
+<li>Fetchmail only deals with complete lines, and can't trust the
+stated message size because Microsoft Exchange goofs it up.</li>
-<p>5. As a result, fetchmail takes the final 'blahblah)' and puts
+<li>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.</p>
+on, you'll get a message about actual != expected.</li>
+</ol>
-<p>There is no fix for this. The nuke mentioned in <a
-href="#S2">S2</a> looks more tempting all the time.</p>
+<p>There is no fix for this.</p>
<h2><a id="X9" name="X9">X9. Missing "Content-Transfer-Encoding" header
with Domino IMAP</a></h2>
Kim's list post</a>
</p>
+<h2><a id="X10" name="X10">X10. Fetchmail delivers partial
+ messages</a></h2>
+
+<p>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).</p>
+
+<p>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).</p>
+
<hr/>
<h1>Other problems</h1>
<h2><a id="O1" name="O1">O1. The --logfile option doesn't work if
first message in your mailbox. This usually stems from a message like
the one shown below, which is automatically created on your server. This
message shows up if the University of Washington IMAP or PINE software
-is used on the server together with a POP2 or POP3 daemon that is not
+is used on the server together with a POP3 daemon that is not
aware of these messages, such as some versions of Qualcomm Popper
(QPOP):</p>
make fetchmail-FAQ.pdf
</pre>
+<h2><a name="O17">O17. Linux logs "TCP(fetchmail:...): Application bug, race
+ in MSG_PEEK."</a></h2>
+<p>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.</p>
<hr/>
<table width="100%" cellpadding="0" summary="Canned page footer">
projects / ~andy / fetchmail / blobdiff