<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">
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="#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
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>
<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>
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>
-
-<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>
+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>Fetchmail using IMAP usually supports the proprietary NTLM mode used
with Microsoft Exchange servers. "Usually" here means that it fails on some
</ul>
</blockquote>
-<p>But, the best option involves finding a server that runs better
-software.</p>
-
<h2><a id="S3" name="S3">S3. How can I use fetchmail with HP
OpenMail?</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>
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>
projects / ~andy / fetchmail / blobdiff