.\" Load www macros to process .URL requests, this requires groff:
.mso www.tmac
.\"
-.TH fetchmail 1 "fetchmail 6.3.19" "fetchmail" "fetchmail reference manual"
+.TH fetchmail 1 "fetchmail 7.0.0-alpha1" "fetchmail" "fetchmail reference manual"
.SH NAME
fetchmail \- fetch mail from a POP, IMAP, ETRN, or ODMR-capable server
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
.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
.IP
Beginning with fetchmail 6.3.10, the SMTP client uses the recommended minimum
timeouts from RFC-5321 while waiting for the SMTP/LMTP server it is talking to.
-You can raise the timeouts even more, but you cannot shorten it. This is to
+You can raise the timeouts even more, but you cannot shorten them. This is to
avoid a painful situation where fetchmail has been configured with a short
timeout (a minute or less), ships a long message (many MBytes) to the local
MTA, which then takes longer than timeout to respond "OK", which it eventually
(Keyword: sslproto)
.br
Forces an SSL/TLS protocol. Possible values are \fB''\fP,
-\&'\fBSSL2\fP', '\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 v6.3.20, 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
.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
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.
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)
.fi
.sp
.PP
-Legal authentication types are 'any', 'password', 'kerberos',
-\&'kerberos_v4', 'kerberos_v5' and 'gssapi', 'cram\-md5', 'otp', 'msn'
+Legal authentication types are 'any', 'password',
+\&'kerberos_v5' and 'gssapi', 'cram\-md5', 'otp', 'msn'
(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 CRAM-MD5);
-\&'kerberos' tells \fBfetchmail\fP to try to get a Kerberos ticket at the
+\&'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'
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
APOP:
RFC 1939.
.TP 5
-RPOP:
-RFC 1081, RFC 1225.
-.TP 5
IMAP2/IMAP2BIS:
RFC 1176, RFC 1732.
.TP 5
projects / ~andy / fetchmail / blobdiff