.\" Load www macros to process .URL requests, this requires groff:
.mso www.tmac
.\"
-.TH fetchmail 1 "fetchmail 6.3.24" "fetchmail" "fetchmail reference manual"
+.TH fetchmail 1 "fetchmail 7.0.0-alpha3" "fetchmail" "fetchmail reference manual"
.SH NAME
fetchmail \- fetch mail from a POP, IMAP, ETRN, or ODMR-capable server
to repeatedly poll one or more systems at a specified interval.
.PP
The \fBfetchmail\fP program can gather mail from servers supporting any
-of the common mail-retrieval protocols: POP2 (legacy, to be removed from
-future release), POP3, IMAP2bis, IMAP4, and IMAP4rev1. It can also use
-the ESMTP ETRN extension and ODMR. (The RFCs describing all these
-protocols are listed at the end of this manual page.)
+of the common mail-retrieval protocols: POP3, IMAP2bis, IMAP4, and IMAP4rev1.
+It can also use the ESMTP ETRN extension and ODMR. (The RFCs describing all
+these protocols are listed at the end of this manual page.)
.PP
While \fBfetchmail\fP is primarily intended to be used over on-demand
TCP/IP links (such as SLIP or PPP connections), it may also be useful as
with ETRN or ODMR. It will return a false positive if you leave read but
undeleted mail in your server mailbox and your fetch protocol can't
tell kept messages from new ones. This means it will work with IMAP,
-not work with POP2, and may occasionally flake out under POP3.
+and may occasionally flake out under POP3.
.TP
.B \-s | \-\-silent
Silent mode. Suppresses all progress/status messages that are
Retrieve both old (seen) and new messages from the mailserver. The
default is to fetch only messages the server has not marked seen.
Under POP3, this option also forces the use of RETR rather than TOP.
-Note that POP2 retrieval behaves as though \-\-all is always on (see
-RETRIEVAL FAILURE MODES below) and this option does not work with ETRN
-or ODMR. While the \-a and \-\-all command-line and fetchall rcfile
-options have been supported for a long time, the \-\-fetchall
-command-line option was added in v6.3.3.
+While the \-a and \-\-all command-line and fetchall rcfile options have been
+supported for a long time, the \-\-fetchall command-line option was added in
+v6.3.3.
.TP
.B \-k | \-\-keep
(Keyword: keep)
are deleted from the folder on the mailserver after they have been retrieved.
Specifying the \fBkeep\fP option causes retrieved messages to remain in
your folder on the mailserver. This option does not work with ETRN or
-ODMR. If used with POP3, it is recommended to also specify the \-\-uidl
-option or uidl keyword.
+ODMR.
.TP
.B \-K | \-\-nokeep
(Keyword: nokeep)
fetchmail to delete a message it had never fetched before. It can also
cause mail loss if the mail server marks the message seen after
retrieval (IMAP2 servers). You should probably not use this option in your
-configuration file. If you use it with POP3, you must use the 'uidl'
-option. What you probably want is the default setting: if you don't
+configuration file. What you probably want is the default setting: if you don't
specify '\-k', then fetchmail will automatically delete messages after
successful delivery.
.TP
\fBproto\fP may be one of the following:
.RS
.IP AUTO
-Tries IMAP, POP3, and POP2 (skipping any of these for which support
+Tries IMAP and POP3 (skipping any of these for which support
has not been compiled in).
-.IP POP2
-Post Office Protocol 2 (legacy, to be removed from future release)
.IP POP3
Post Office Protocol 3
-.IP APOP
-Use POP3 with old-fashioned MD5-challenge authentication.
-Considered not resistant to man-in-the-middle attacks.
-.IP RPOP
-Use POP3 with RPOP authentication.
.IP KPOP
-Use POP3 with Kerberos V4 authentication on port 1109.
+Use POP3 with Kerberos V5 authentication on port 1109.
.IP SDPS
Use POP3 with Demon Internet's SDPS extensions.
.IP IMAP
ETRN, except that it does not require the client machine to have
a static DNS.
.TP
-.B \-U | \-\-uidl
-(Keyword: uidl)
-.br
-Force UIDL use (effective only with POP3). Force client-side tracking
-of 'newness' of messages (UIDL stands for "unique ID listing" and is
-described in RFC1939). Use with 'keep' to use a mailbox as a baby
-news drop for a group of users. The fact that seen messages are skipped
-is logged, unless error logging is done through syslog while running in
-daemon mode. Note that fetchmail may automatically enable this option
-depending on upstream server capabilities. Note also that this option
-may be removed and forced enabled in a future fetchmail version. See
-also: \-\-idfile.
-.TP
.B \-\-idle (since 6.3.3)
(Keyword: idle, since before 6.0.0)
.br
(Keyword: sslproto)
.br
Forces an SSL/TLS protocol. Possible values are \fB''\fP,
-\&'\fBSSL2\fP' (not supported on all systems),
-\&'\fBSSL23\fP', (use of these two values is discouraged
-and should only be used as a last resort) \&'\fBSSL3\fP', and
+\&'\fBSSL23\fP' (note however that fetchmail, since v7.0.0, prohibits
+negotiation of SSLv2 -- it has been deprecated for 15 years and is
+insecure), \&'\fBSSL3\fP', and
\&'\fBTLS1\fP'. The default behaviour if this option is unset is: for
connections without \-\-ssl, use \&'\fBTLS1\fP' so that fetchmail will
opportunistically try STARTTLS negotiation with TLS1. You can configure
i. e. headers with bad syntax. Traditionally, fetchmail has rejected such
messages, but some distributors modified fetchmail to accept them. You can now
configure fetchmail's behaviour per server.
+.TP
+.B \-\-retrieve\-error {abort|continue|markseen}
+(Keyword: retrieve\-error; since v7.0)
+.br
+Specify how fetchmail is supposed to treat messages which fail to be
+retrieved due to server errors, i. e. fetching the message body fails with
+a server error. Traditionally, fetchmail has aborted the session leaving
+both the message with the error and any subsequent messages on the server.
+Both the continue and markseen options will allow the session to continue
+enabling subsequent messages on the server to be retrieved. You can now
+configure fetchmail's behaviour per server.
.SS Resource Limit Control Options
.TP
(Keyword: expunge)
.br
Arrange for deletions to be made final after a given number of
-messages. Under POP2 or POP3, fetchmail cannot make deletions final
+messages. Under POP3, fetchmail cannot make deletions final
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
.br
This option permits you to specify an authentication type (see USER
AUTHENTICATION below for details). The possible values are \fBany\fP,
-\&\fBpassword\fP, \fBkerberos_v5\fP, \fBkerberos\fP (or, for
-excruciating exactness, \fBkerberos_v4\fP), \fBgssapi\fP,
+\&\fBpassword\fP, \fBkerberos_v5\fP, \fBgssapi\fP,
\fBcram\-md5\fP, \fBotp\fP, \fBntlm\fP, \fBmsn\fP (only for POP3),
\fBexternal\fP (only IMAP) and \fBssh\fP.
When \fBany\fP (the default) is specified, fetchmail tries
-first methods that don't require a password (EXTERNAL, GSSAPI, KERBEROS\ IV,
+first methods that don't require a password (EXTERNAL, GSSAPI,
KERBEROS\ 5); then it looks for methods that mask your password
(CRAM-MD5, NTLM, X\-OTP - note that MSN is only supported for POP3, but not
autoprobed); and only if the server doesn't
\&\fBmsn\fP or \fBotp\fP suppresses fetchmail's normal inquiry for a
password. Specify \fBssh\fP when you are using an end-to-end secure
connection such as an ssh tunnel; specify \fBexternal\fP when you use
-TLS with client authentication and specify \fBgssapi\fP or
-\&\fBkerberos_v4\fP 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. GSSAPI service names are
-in line with RFC-2743 and IANA registrations, see
+TLS with client authentication and specify \fBgssapi\fP if you are using a
+protocol variant that employs GSSAPI. Choosing KPOP protocol automatically
+selects Kerberos authentication. This option does not work with ETRN.
+GSSAPI service names are in line with RFC-2743 and IANA registrations, see
.URL http://www.iana.org/assignments/gssapi-service-names/ "Generic Security Service Application Program Interface (GSSAPI)/Kerberos/Simple Authentication and Security Layer (SASL) Service Names" .
.SS Miscellaneous Options
.TP
the correct user-id and password for your mailbox account.
.SH POP3 VARIANTS
.PP
-Early versions of POP3 (RFC1081, RFC1225) supported a crude form of
-independent authentication using the \fI.rhosts\fP file on the
-mailserver side. Under this RPOP variant, a fixed per-user ID
-equivalent to a password was sent in clear over a link to a reserved
-port, with the command RPOP rather than PASS to alert the server that it
-should do special checking. RPOP is supported by \fBfetchmail\fP
-(you can specify 'protocol RPOP' to have the program send 'RPOP'
-rather than 'PASS') but its use is strongly discouraged, and support
-will be removed from a future fetchmail version. This
-facility was vulnerable to spoofing and was withdrawn in RFC1460.
-.PP
RFC1460 introduced APOP authentication. In this variant of POP3,
you register an APOP password on your server host (on some servers, the
program to do this is called \fBpopauth\fP(8)). You put the same
database.
\fBNote that APOP is no longer considered resistant against
-man-in-the-middle attacks.\fP
+man-in-the-middle attacks, and should not be used without a verified
+SSL/TLS connection.\fP
.SS RETR or TOP
\fBfetchmail\fP makes some efforts to make the server believe messages
had not been retrieved, by using the TOP command with a large number of
that.
.PP
\fBfetchmail\fP will always use the RETR command if "fetchall" is set.
-\fBfetchmail\fP will also use the RETR command if "keep" is set and
-"uidl" is unset. Finally, \fBfetchmail\fP will use the RETR command on
+As a workaround, \fBfetchmail\fP will use the RETR command on
Maillennium POP3/PROXY servers (used by Comcast) to avoid a deliberate
TOP misinterpretation in this server that causes message corruption.
.PP
-In all other cases, \fBfetchmail\fP will use the TOP command. This
-implies that in "keep" setups, "uidl" must be set if "TOP" is desired.
-.PP
\fBNote\fP that this description is true for the current version of
fetchmail, but the behavior may change in future versions. In
particular, fetchmail may prefer the RETR command because the TOP
.PP
If your \fBfetchmail\fP was built with Kerberos support and you specify
Kerberos authentication (either with \-\-auth or the \fI.fetchmailrc\fP
-option \fBauthenticate kerberos_v4\fP) it will try to get a Kerberos
+option \fBauthenticate kerberos_v5\fP) it will try to get a Kerberos
ticket from the mailserver at the start of each query. Note: if
either the pollname or via name is 'hesiod', fetchmail will try to use
Hesiod to look up the mailserver.
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 'SSL3' option should be
-used to select the SSLv3 protocol (default if unset: v2 or v3). Also,
+no explicit port is specified. The \-\-sslproto 'SSL3' need no longer be
+used to avoid the SSLv2 protocol. Also,
the \-\-sslcertck command line or sslcertck run control file option
should be used to force strict certificate checking - see below.
.PP
.BR runit (8).
Note that this also causes the logfile option to be ignored.
.PP
-Note that while running in daemon mode polling a POP2 or IMAP2bis server,
+Note that while running in daemon mode polling a IMAP2bis server,
transient errors (such as DNS failures or sendmail delivery refusals)
may force the fetchall option on for the duration of the next polling
cycle. This is a robustness feature. It means that if a message is
server are being fetched (and deleted) even when you don't specify
\-\-all. There are several reasons this can happen.
.PP
-One could be that you're using POP2. The POP2 protocol includes no
-representation of 'new' or 'old' state in messages, so \fBfetchmail\fP
-must treat all messages as new all the time. But POP2 is obsolete, so
-this is unlikely.
-.PP
A potential POP3 problem might be servers that insert messages
in the middle of mailboxes (some VMS implementations of mail are
rumored to do this). The \fBfetchmail\fP code assumes that new
T}
proto[col] \-p \& T{
Specify protocol (case insensitive):
-POP2, POP3, IMAP, APOP, KPOP
+POP3, IMAP, KPOP
T}
local[domains] \& m T{
Specify domain(s) to be regarded as local
no checkalias \& m T{
Do comparison by name for multidrop (default)
T}
-uidl \-U \& T{
-Force POP3 to use client-side UIDLs (recommended)
-T}
-no uidl \& \& T{
-Turn off POP3 use of client-side UIDLs (default)
-T}
interval \& \& T{
Only check this site every N poll cycles; N is a numeric argument.
T}
bad-header \& \& T{
How to treat messages with a bad header. Can be reject (default) or accept.
T}
+retrieve-error \& \& T{
+How to behave when messages that cannot be retrieved due to a server error
+are encountered. Can be abort (default), continue or markseen.
+T}
.TE
Here are the legal user descriptions and options:
Command to be executed after each connection
T}
keep \-k \& T{
-Don't delete seen messages from server (for POP3, uidl is recommended)
+Don't delete seen messages from server
T}
flush \-F \& T{
Flush all seen messages before querying (DANGEROUS)
.sp
.nf
auto (or AUTO) (legacy, to be removed from future release)
- pop2 (or POP2) (legacy, to be removed from future release)
pop3 (or POP3)
- sdps (or SDPS)
+ sdps (or SDPS) (a POP3 variant specific to Demon)
+ kpop (or KPOP) (a Kerberos-based variant)
imap (or IMAP)
- apop (or APOP)
- kpop (or KPOP)
.fi
.sp
.PP
-Legal authentication types are 'any', 'password', 'kerberos',
-\&'kerberos_v4', 'kerberos_v5' and 'gssapi', 'cram\-md5', 'otp', 'msn'
-(only for POP3), 'ntlm', 'ssh', 'external' (only IMAP).
+Legal authentication types are 'any', 'password', 'apop' (only for
+POP3), \&'kerberos_v5' and 'gssapi', 'cram\-md5', 'otp', 'msn'
+(only for POP3), 'ntlm', 'ssh', 'external' (only for 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 CRAM-MD5);
-\&'kerberos' tells \fBfetchmail\fP to try to get a Kerberos ticket at the
+authentication by normal transmission of a password;
+\&'kerberos_v5' tells \fBfetchmail\fP to try to get a Kerberos ticket at the
start of each query instead, and send an arbitrary string as the
password; and 'gssapi' tells fetchmail to use GSSAPI authentication.
See the description of the 'auth' keyword for more.
.PP
-Specifying 'kpop' sets POP3 protocol over port 1109 with Kerberos V4
+Specifying 'kpop' sets POP3 protocol over port 1109 with Kerberos V5
authentication. These defaults may be overridden by later options.
.PP
There are some global option statements: 'set logfile'
followed by a string sets the same global specified by \-\-logfile. A
command-line \-\-logfile option will override this. Note that \-\-logfile is
-only effective if fetchmail detaches itself from the terminal and the
+only effective if fetchmail detaches itself from the terminal, is in
+daemon mode, and if the
logfile already exists before fetchmail is run, and it overrides
\-\-syslog in this case. Also,
\&'set daemon' sets the poll interval as \-\-daemon does. This can be
.IP
.nf
poll pop.provider.net proto pop3 user "jsmith" pass "secret1"
-poll other.provider.net proto pop2 user "John.Smith" pass "My^Hat"
+poll other.provider.net proto imap user "John.Smith" pass "My^Hat"
.fi
.PP
.nf
poll pop.provider.net proto pop3
user "jsmith", with password secret1, is "jsmith" here;
-poll other.provider.net proto pop2:
+poll other.provider.net proto imap:
user "John.Smith", with password "My^Hat", is "John.Smith" here;
.fi
The \-f\~\- option (reading a configuration from stdin) is incompatible
with the plugin option.
.PP
-The 'principal' option only handles Kerberos IV, not V.
+The 'principal' option does not work for Kerberos V.
.PP
Interactively entered passwords are truncated after 63 characters. If
you really need to use a longer password, you will have to use a
mail:
RFC 822, RFC 2822, RFC 1123, RFC 1892, RFC 1894.
.TP 5
-POP2:
-RFC 937
.TP 5
POP3:
RFC 1081, RFC 1225, RFC 1460, RFC 1725, RFC 1734, RFC 1939, RFC 1957,
APOP:
RFC 1939.
.TP 5
-RPOP:
-RFC 1081, RFC 1225.
-.TP 5
IMAP2/IMAP2BIS:
RFC 1176, RFC 1732.
.TP 5
projects / ~andy / fetchmail / blobdiff