.\"
.\" For license terms, see the file COPYING in this directory.
.\"
-.TH fetchmail 1 "fetchmail 6.3.5" "fetchmail" "fetchmail reference manual"
+.TH fetchmail 1 "fetchmail 6.3.7" "fetchmail" "fetchmail reference manual"
.SH NAME
fetchmail \- fetch mail from a POP, IMAP, ETRN, or ODMR-capable server
number of different recipients. Therefore,
.I fetchmail
must attempt to deduce the proper "envelope recipient" from the mail
-headers of each message. In this mode of operation
+headers of each message. In this mode of operation,
.I fetchmail
almost resembles an MTA, however it is important to note that neither
the POP nor IMAP protocols were intended for use in this fashion, and
-hence envelope information is not directly available. Instead,
+hence envelope information is often not directly available. Instead,
.I fetchmail
must resort to a process of informed guess-work in an attempt to
-discover the true envelope recipient of a message. Even if this
+discover the true envelope recipient of a message, unless the ISP stores
+the envelope information in some header (not all do). Even if this
information is present in the headers, the process can
be error-prone and is dependent upon the specific mail server used
for mail retrieval. Multidrop-mode is used when more than one local
methods, since they are based upon the SMTP protocol which
specifically provides the envelope recipient to \fIfetchmail\fR.
.PP
-As each message is retrieved \fIfetchmail\fR normally delivers it via SMTP to
+As each message is retrieved, \fIfetchmail\fR normally delivers it via SMTP to
port 25 on the machine it is running on (localhost), just as though it
were being passed in over a normal TCP/IP link. \fIfetchmail\fR provides
the SMTP server with an envelope recipient derived in the manner described
.B \-\-plugin <command>
(Keyword: plugin) The plugin option allows you to use an external
program to establish the TCP connection. This is useful if you want
-to use socks, SSL, ssh, or need some special firewalling setup. The
+to use SSL, ssh, or need some special firewalling setup. The
program will be looked up in $PATH and can optionally be passed the
hostname and port as arguments using "%h" and "%p" respectively (note
that the interpolation logic is rather primitive, and these token must
(Keyword: ssl)
Causes the connection to the mail server to be encrypted via SSL. Connect
to the server using the specified base protocol over a connection secured
-by SSL. SSL support must be present at the server.
+by SSL. This option defeats TLS negotiation. Use \-\-sslcertck to
+validate the certificates presented by the server.
.sp
Note that fetchmail may still try to negotiate TLS even if this option
is not given. You can use the \-\-sslproto option to defeat this
servers may not request it at all. It may be the same file
as the private key (combined key and certificate file) but this is not
recommended.
+.sp
+.B NOTE:
+If you use client authentication, the user name is fetched from the
+certificate's CommonName and overrides the name set with \-\-user.
.TP
.B \-\-sslkey <name>
(Keyword: sslkey)
.TP
.B \-\-sslproto <name>
(Keyword: sslproto)
-Forces an SSL or TLS protocol. Possible values are '\fBssl2\fR',
-\&'\fBssl3\fR', '\fBssl23\fR', and '\fBtls1\fR'. Try this if the default
-handshake does not work for your server. To defeat automatic TLSv1
-negotiation when the server advertises STARTTLS or STLS, use \fB''\fR or
-\&'\fBssl23\fR'. This option, even if the argument is the empty string,
-will also suppress the diagnostic 'SERVER: opportunistic upgrade to
-TLS.' message in verbose mode. The default is to try appropriate
-protocols depending on context.
+Forces an SSL or TLS protocol. Possible values are '\fBSSL2\fR',
+\&'\fBSSL3\fR', '\fBSSL23\fR', and '\fBTLS1\fR'. Try this if the default
+handshake does not work for your server. Use this option with
+'\fBTLS1\fR' to enforce a TLS connection. To defeat opportunistic TLSv1
+negotiation when the server advertises STARTTLS or STLS, use \fB''\fR.
+This option, even if the argument is the empty string, will also
+suppress the diagnostic 'SERVER: opportunistic upgrade to TLS.' message
+in verbose mode. The default is to try appropriate protocols depending
+on context.
.TP
.B \-\-sslcertck
(Keyword: sslcertck)
Causes fetchmail to strictly check the server certificate against a set of
local trusted certificates (see the \fBsslcertpath\fR option). If the server
-certificate is not signed by one of the trusted ones (directly or indirectly),
-the SSL connection will fail, regardless of the \fBsslfingerprint\fR
-option. This checking should prevent man-in-the-middle attacks against
-the SSL connection. Note that CRLs are seemingly not currently supported
-by OpenSSL in certificate verification! Your system clock should be
-reasonably accurate when using this option.
+certificate cannot be obtained or is not signed by one of the trusted ones
+(directly or indirectly), the SSL connection will fail, regardless of
+the \fBsslfingerprint\fR option.
+Note that CRL are only supported in OpenSSL 0.9.7 and newer! Your system
+clock should also be reasonably accurate when using this option.
.IP
Note that this optional behavior may become default behavior in future
fetchmail versions.
and the one fetchmail uses to report the fingerprint when an SSL connection
is established. When this is specified, fetchmail will compare the server key
fingerprint with the given one, and the connection will fail if they do not
-match regardless of the \fBsslcertck\fR setting.
+match regardless of the \fBsslcertck\fR setting. The connection will
+also fail if fetchmail cannot obtain an SSL certificate from the server.
This can be used to prevent man-in-the-middle attacks, but the finger
print from the server needs to be obtained or verified over a secure
channel, and certainly not over the same Internet connection that
.TP
.B \-m <command> | \-\-mda <command>
(Keyword: mda) You can force mail to be passed to an MDA directly
-(rather than forwarded to port 25) with the \-\-mda or \-m option. To
+(rather than forwarded to port 25) with the \-\-mda or \-m option.
+
+To
avoid losing mail, use this option only with MDAs like maildrop or
MTAs like sendmail that return a nonzero status on disk-full and other
resource-exhaustion errors; the nonzero status tells fetchmail that
delivery failed and prevents the message from being deleted off the
-server. If \fIfetchmail\fR is running as root, it sets its user id to
+server.
+
+If \fIfetchmail\fR is running as root, it sets its user id to
that of the target user while delivering mail through an MDA. Some
possible MDAs are "/usr/sbin/sendmail \-i \-f %F \-\- %T" (\fBNote:\fR
some several older or vendor sendmail versions mistake \-\- for an
"/usr/bin/deliver" and "/usr/bin/maildrop \-d %T". Local delivery
addresses will be inserted into the MDA command wherever you place a
%T; the mail message's From address will be inserted where you place
-an %F. \fBDO NOT ENCLOSE THE %F OR %T STRING IN SINGLE QUOTES!\fR For
-both %T and %F, fetchmail encloses the addresses in single quotes ('),
-after removing any single quotes they may contain, before the MDA
-command is passed to the shell. Do \fINOT\fR use an MDA invocation
-like "sendmail \-i \-t" that dispatches on the contents of To/Cc/Bcc, it
-will create mail loops and bring the just wrath of many postmasters
-down upon your head. Also, do \fInot\fR try to combine multidrop
-mode with an MDA such as maildrop or procmail that can only accept one
-address; you will lose mail.
-
-A word of warning: the well-known
+an %F.
+
+.B "DO NOT ENCLOSE THE %F OR %T STRING IN SINGLE QUOTES!"
+For both %T and %F, fetchmail encloses the addresses in single quotes
+('), after removing any single quotes they may contain, before the MDA
+command is passed to the shell.
+
+\fRDo \fINOT\fP use an MDA invocation that dispatches on the contents of
+To/Cc/Bcc,\fP like "sendmail \-i \-t" or "qmail-inject", it will create
+mail loops and bring the just wrath of many postmasters down upon your
+head. This is one of the most frequent configuration errors!
+
+Also, do \fInot\fR try to combine multidrop mode with an MDA such
+as maildrop that can only accept one address, unless your upstream
+stores one copy of the message per recipient and transports the envelope
+recipient in a header; you will lose mail.
+
+The well-known
.BR procmail (1)
package is very hard to configure properly, it has a very nasty "fall
through to the next rule" behavior on delivery errors (even temporary
ones, such as out of disk space if another user's mail daemon copies the
mailbox around to purge old messages), so your mail will end up in the
wrong mailbox sooner or later. The proper procmail configuration is
-outside the scope of this document though. Using
+outside the scope of this document. Using
.BR maildrop (1)
is usually much easier, and many users find the filter syntax used by
maildrop easier to understand.
+Finally, we strongly advise that you do
+.B not
+use qmail-inject. The command line interface is non-standard without
+providing benefits for typical use, and fetchmail makes no attempts to
+accomodate qmail-inject's deviations from the standard. Some of
+qmail-inject's command-line and environment options are actually
+dangerous and can cause broken threads, non-detected duplicate messages
+and forwarding loops.
+
.TP
.B \-\-lmtp
(Keyword: lmtp)
without sending QUIT and ending the session -- with this option on,
fetchmail will break a long mail retrieval session into multiple
sub-sessions, sending QUIT after each sub-session. This is a good
-defense against line drops on POP3 servers that do not do the
-equivalent of a QUIT on hangup. Under IMAP,
+defense against line drops on POP3 servers. Under IMAP,
.I fetchmail
normally issues an EXPUNGE command after each deletion in order to
force the deletion to be done immediately. This is safest when your
AUTHENTICATION below for details). The possible values are \fBany\fR,
\&\fBpassword\fR, \fBkerberos_v5\fR, \fBkerberos\fR (or, for
excruciating exactness, \fBkerberos_v4\fR), \fBgssapi\fR,
-\fBcram\-md5\fR, \fBotp\fR, \fBntlm\fR, \fBmsn\fR (only for POP3) and
-\fBssh\fR. When \fBany\fR (the default) is specified, fetchmail tries
-first methods that don't require a password (GSSAPI, KERBEROS\ IV,
+\fBcram\-md5\fR, \fBotp\fR, \fBntlm\fR, \fBmsn\fR (only for POP3),
+\fBexternal\fR (only IMAP) and \fBssh\fR.
+When \fBany\fR (the default) is specified, fetchmail tries
+first methods that don't require a password (EXTERNAL, GSSAPI, KERBEROS\ IV,
KERBEROS\ 5); then it looks for methods that mask your password
(CRAM-MD5, X\-OTP - note that NTLM and MSN are not autoprobed for POP3
and MSN is only supported for POP3); and only if the server doesn't
support any of those will it ship your password en clair. Other values
may be used to force various authentication methods
-(\fBssh\fR suppresses authentication and is thus good for IMAP PREAUTH).
+(\fBssh\fR suppresses authentication and is thus useful for IMAP PREAUTH).
+(\fBexternal\fR suppresses authentication and is thus useful for IMAP EXTERNAL).
Any value other than \fBpassword\fR, \fBcram\-md5\fR, \fBntlm\fR,
\&\fBmsn\fR or \fBotp\fR suppresses fetchmail's normal inquiry for a
password. Specify \fBssh\fR when you are using an end-to-end secure
-connection such as an ssh tunnel; specify \fBgssapi\fR or
+connection such as an ssh tunnel; specify \fBexternal\fR when you use
+TLS with client authentication and specify \fBgssapi\fR or
\&\fBkerberos_v4\fR if you are using a protocol variant that employs
GSSAPI or K4. Choosing KPOP protocol automatically selects Kerberos
authentication. This option does not work with ETRN.
This option changes the header
.I fetchmail
assumes will carry a copy of the mail's envelope address. Normally
-this is 'X\-Envelope\-To', but as this header is not standard, practice
-varies. See the discussion of multidrop address handling below. As a
-special case, 'envelope "Received"' enables parsing of sendmail-style
-Received lines. This is the default, and it should not be necessary
-unless you have globally disabled Received parsing with 'no envelope'
-in the \fI.fetchmailrc\fR file.
+this is 'X\-Envelope\-To'. Other typically found headers to carry envelope
+information are 'X\-Original\-To' and 'Delivered\-To'. Now, since
+these headers are not standardized, practice varies. See the discussion
+of multidrop address handling below. As a special case, 'envelope
+"Received"' enables parsing of sendmail-style Received lines. This is
+the default, but discouraged because it is not fully reliable.
+
+.B Note
+that fetchmail expects the Received-line to be in a specific
+format: It must contain "by \fIhost\fP for \fIaddress\fR", where
+\fIhost\fP must match one of the mailserver names that fetchmail
+recognizes for the account in question.
.sp
The optional count argument (only available in the configuration file)
determines how many header lines of this kind are skipped. A count of 1
site entry to stop \fI.fetchmail\fR from asking you for a password
when it starts up.
.PP
+If you use client authentication with \fITLS1\fR and your IMAP daemon
+returns the \fIAUTH=EXTERNAL\fR response, fetchmail will notice this
+and will use the authentication shortcut and will not send the
+passphrase. In this case you can declare the authentication value 'external'
+ on that site to stop \fIfetchmail\fR from asking you for a password
+when it starts up.
+.PP
If you are using POP3, and the server issues a one-time-password
challenge conforming to RFC1938, \fIfetchmail\fR will use your
password as a pass phrase to generate the required response. This
.PP
You can access SSL encrypted services by specifying the \-\-ssl option.
You can also do this using the "ssl" user option in the .fetchmailrc
-file. With SSL encryption enabled, queries are initiated over a connection
-after negotiating an SSL session. Some services, such as POP3 and IMAP,
-have different well known ports defined for the SSL encrypted services.
-The encrypted ports will be selected automatically when SSL is enabled and
-no explicit port is specified.
-.PP
-When connecting to an SSL encrypted server, the server presents a certificate
-to the client for validation. The certificate is checked to verify that
-the common name in the certificate matches the name of the server being
-contacted and that the effective and expiration dates in the certificate
-indicate that it is currently valid. If any of these checks fail, a warning
-message is printed, but the connection continues. The server certificate
-does not need to be signed by any specific Certifying Authority and may
-be a "self-signed" certificate.
+file. With SSL encryption enabled, queries are initiated over a connection
+after negotiating an SSL session, and the connection fails if SSL cannot
+be negotiated. Some services, such as POP3 and IMAP, have different
+well known ports defined for the SSL encrypted services. The encrypted
+ports will be selected automatically when SSL is enabled and no explicit
+port is specified. The \-\-sslproto option can be used to select the SSL
+protocols (default: v2 or v3). The \-\-sslcertck command line or
+sslcertck run control file option should be used to force strict
+certificate checking - see below.
+.PP
+If SSL is not configured, fetchmail will usually opportunistically try to use
+TLS. TLS can be enforced by using \-\-sslproto "TLS1". TLS
+connections use the same port as the unencrypted version of the
+protocol and negotiate TLS via special parameter. The \-\-sslcertck
+command line or sslcertck run control file option should be used to
+force strict certificate checking - see below.
+.PP
+.B \-\-sslcertck
+recommended: When connecting to an SSL or TLS encrypted server, the
+server presents a certificate to the client for validation. The
+certificate is checked to verify that the common name in the certificate
+matches the name of the server being contacted and that the effective
+and expiration dates in the certificate indicate that it is currently
+valid. If any of these checks fail, a warning message is printed, but
+the connection continues. The server certificate does not need to be
+signed by any specific Certifying Authority and may be a "self-signed"
+certificate. If the \-\-sslcertck command line option or sslcertck run
+control file option is used, fetchmail will instead abort if any of
+these checks fail. Use of the sslcertck or \-\-sslcertck option is
+advised.
.PP
Some SSL encrypted servers may request a client side certificate. A client
side public SSL certificate and private SSL key may be specified. If
.PP
A word of care about the use of SSL: While above mentioned
setup with self-signed server certificates retrieved over the wires
-can protect you from a passive eavesdropper it doesn't help against an
+can protect you from a passive eavesdropper, it doesn't help against an
active attacker. It's clearly an improvement over sending the
-passwords in clear but you should be aware that a man-in-the-middle
+passwords in clear, but you should be aware that a man-in-the-middle
attack is trivially possible (in particular with tools such as dsniff,
-http://monkey.org/~dugsong/dsniff/). Use of an ssh tunnel (see
-below for some examples) is preferable if you care seriously about the
-security of your mailbox.
+http://monkey.org/~dugsong/dsniff/). Use of strict certificate checking
+with a certification authority recognized by server and client, or
+perhaps of an SSH tunnel (see below for some examples) is preferable if
+you care seriously about the security of your mailbox and passwords.
.SS ESMTP AUTH
.PP
.B fetchmail
detached. This option allows you to redirect status messages
into a specified logfile (follow the option with the logfile name). The
logfile is opened for append, so previous messages aren't deleted. This
-is primarily useful for debugging configurations.
+is primarily useful for debugging configurations. Note that fetchmail
+does not detect if the logfile is rotated, the logfile is only opened
+once when fetchmail starts. You need to restart fetchmail after rotating
+the logfile and before compressing it (if applicable).
.PP
The
.B \-\-syslog
Add poll tracing information to the Received header
T}
principal \& \& T{
-Set Kerberos principal (only useful with imap and kerberos)
+Set Kerberos principal (only useful with IMAP and kerberos)
T}
esmtpname \& \& T{
Set name for RFC2554 authentication to the ESMTP server.
server less frequently than the basic poll interval. If you say
\&'interval N' the server this option is attached to will only be
queried every N poll intervals.
+.SS Singledrop vs. Multidrop options
+.PP
+Please ensure you read the section titled
+.B THE USE AND ABUSE OF MULTIDROP MAILBOXES
+if you intend to use multidrop mode.
.PP
The 'is' or 'to' keywords associate the following local (client)
name(s) (or server-name to client-name mappings separated by =) with
the mailserver user name in the entry. If an is/to list has '*' as
-its last name, unrecognized names are simply passed through.
+its last name, unrecognized names are simply passed through. Note that
+until \fIfetchmail\fR version 6.3.4 inclusively, these lists could only
+contain local parts of user names (fetchmail would only look at the part
+before the @ sign). \fIfetchmail\fR versions 6.3.5 and
+newer support full addresses on the left hand side of these mappings,
+and they take precedence over any 'localdomains', 'aka', 'via' or
+similar mappings.
.PP
A single local name can be used to support redirecting your mail when
your username on the client machine is different from your name on the
mailserver. When there is only a single local name, mail is forwarded
to that local username regardless of the message's Received, To, Cc,
-and Bcc headers. In this case
+and Bcc headers. In this case,
.I fetchmail
never does DNS lookups.
.PP
-When there is more than one local name (or name mapping) the
-\fIfetchmail\fR code does look at the Received, To, Cc, and Bcc
-headers of retrieved mail (this is 'multidrop mode'). It looks for
-addresses with hostname parts that match your poll name or your 'via',
-\&'aka' or 'localdomains' options, and usually also for hostname parts
-which DNS tells it are aliases of the mailserver. See the discussion
-of 'dns', 'checkalias', 'localdomains', and 'aka' for details on how
-matching addresses are handled.
+When there is more than one local name (or name mapping),
+\fIfetchmail\fR looks at the envelope header, if configured, and
+otherwise at the Received, To, Cc, and Bcc headers of retrieved mail
+(this is 'multidrop mode'). It looks for addresses with hostname parts
+that match your poll name or your 'via', 'aka' or 'localdomains'
+options, and usually also for hostname parts which DNS tells it are
+aliases of the mailserver. See the discussion of 'dns', 'checkalias',
+\&'localdomains', and 'aka' for details on how matching addresses are
+handled.
.PP
If \fIfetchmail\fR cannot match any mailserver usernames or
localdomain addresses, the mail will be bounced.
.PP
Legal authentication types are 'any', 'password', 'kerberos',
\&'kerberos_v4', 'kerberos_v5' and 'gssapi', 'cram\-md5', 'otp', 'msn'
-(only for POP3), 'ntlm', 'ssh'. The 'password' type specifies
+(only for POP3), 'ntlm', 'ssh', 'external' (only IMAP).
+The 'password' type specifies
authentication by normal transmission of a password (the password may be
plain text or subject to protocol-specific encryption as in APOP);
\&'kerberos' tells \fIfetchmail\fR to try to get a Kerberos ticket at the
rather to the list manager (which is less annoying).
In multidrop mode, destination headers are processed as follows:
-First, fetchmail looks for the Received: header (or whichever one is
-specified by the 'envelope' option) to determine the local
-recipient address. If the mail is addressed to more than one recipient,
-the Received line won't contain any information regarding recipient addresses.
+First, fetchmail looks for the header specified by the 'envelope' option
+in order to determine the local recipient address. If the mail is
+addressed to more than one recipient, the Received line won't contain
+any information regarding recipient addresses.
Then fetchmail looks for the Resent-To:, Resent-Cc:, and Resent-Bcc:
lines. If they exist, they should contain the final recipients and
pop.provider.net username 'jones'. Mail for 'jones' is kept on the
server after download.
.PP
-Here's what a simple retrieval configuration for a multi-drop mailbox
+Here's what a simple retrieval configuration for a multidrop mailbox
looks like:
.nf
.fi
This says that the mailbox of account 'maildrop' on the server is a
-multi-drop box, and that messages in it should be parsed for the
+multidrop box, and that messages in it should be parsed for the
server user names 'golux', 'hurkle', and 'snark'. It further
specifies that 'golux' and 'snark' have the same name on the
client as on the server, but mail for server user 'hurkle' should be
delivered to client user 'happy'.
+
+.B Note
+that
+.I fetchmail,
+until version 6.3.4, did NOT allow full user@domain specifications here,
+these would never match. \fIFetchmail\fP 6.3.5 and newer support
+user@domain specifications on the left-hand side of a user mapping.
.PP
Here's an example of another kind of multidrop connection:
.nf
- poll pop.provider.net localdomains loonytoons.org toons.org:
+ poll pop.provider.net localdomains loonytoons.org toons.org
+ envelope X-Envelope-To
user maildrop with pass secret1 to * here
.fi
This also says that the mailbox of account 'maildrop' on the server is
-a multi-drop box. It tells fetchmail that any address in the
+a multidrop box. It tells fetchmail that any address in the
loonytoons.org or toons.org domains (including sub-domain addresses like
\&'joe@daffy.loonytoons.org') should be passed through to the local SMTP
listener without modification. Be careful of mail loops if you do this!
In particular, mailing-list software often ships mail with only
the list broadcast address in the To header.
.PP
-.B Note that a future version of fetchmail may remove To/Cc parsing!
+.B Note that a future version of \fIfetchmail\fP may remove To/Cc parsing!
.PP
When
.I fetchmail
you can declare 'no dns' to suppress DNS lookups entirely and
\fIonly\fR match against the aka list.
+.SH SOCKS
+Support for socks4/5 is a
+.B compile time
+configuration option. Once
+compiled in fetchmail will always use the socks libraries and
+configuration on your system. There are no configuration
+options internal to fetchmail to control this behaviour, and the socks
+and socks5 libraries provide no documented interfaces that fetchmail
+could use to achieve run-time configurability.
+
.SH EXIT CODES
To facilitate the use of
.I fetchmail
-in shell scripts, an exit code is returned to give an indication
+in shell scripts, an exit\ status code is returned to give an indication
of what occurred during a given connection.
.PP
The exit codes returned by
Poll terminated by a fetch limit (see the \-\-fetchlimit option).
.IP 14
Server busy indication.
-.IP 15
-Server timed out during an IMAP IDLE.
.IP 23
Internal error. You should see a message on standard error with
details.
+.IP "24 - 26, 28, 29"
+These are internal codes and should not appear externally.
.PP
When
.I fetchmail
.SH BUGS AND KNOWN PROBLEMS
.PP
+Please check the \fBNEWS\fP file that shipped with fetchmail for more
+known bugs than those listed here.
+.PP
Fetchmail cannot handle user names that contain blanks after a "@"
character, for instance "demonstr@ti on". These are rather uncommon and
only hurt when using UID-based \-\-keep setups, so the 6.3.X versions of
fetchmail won't be fixed.
.PP
-Please check the \fBNEWS\fP file that shipped with fetchmail for more
-known bugs than those listed here.
-.PP
The assumptions that the DNS and in particular the checkalias options
make are not often sustainable. For instance, it has become uncommon for
an MX server to be a POP3 or IMAP server at the same time. Therefore the
projects / ~andy / fetchmail / blobdiff