.\" 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-alpha5" "fetchmail" "fetchmail reference manual"
.SH NAME
fetchmail \- fetch mail from a POP, IMAP, ETRN, or ODMR-capable server
(since v6.3.10, Keyword: set softbounce, since v6.3.10)
.br
Soft bounce mode. All permanent delivery errors cause messages to be
-left on the upstream server if the protocol supports that. Default to
-match historic fetchmail documentation, to be changed to hard bounce
-mode in the next fetchmail release.
+left on the upstream server if the protocol supports that.
+.B This option is on by default to match historic fetchmail documentation,
+and will be changed to hard bounce mode in the next fetchmail release.
.SS Disposal Options
.TP
.B \-a | \-\-all | (since v6.3.3) \-\-fetchall
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
has not been compiled in).
.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 KPOP
Use POP3 with Kerberos V5 authentication on port 1109.
.IP SDPS
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 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
.br
Specify the fingerprint of the server key (an MD5 hash of the key) in
hexadecimal notation with colons separating groups of two digits. The letter
-hex digits must be in upper case. This is the default format OpenSSL uses,
-and the one fetchmail uses to report the fingerprint when an SSL connection
+hex digits must be in upper case. This is the format
+that 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\fP setting. The connection will
+match, regardless of the \fBsslcertck\fP 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
configure fetchmail's behaviour per server.
.TP
.B \-\-retrieve\-error {abort|continue|markseen}
-(Keyword: retrieve\-error; since v6.4)
+(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
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
programmers are not aware of OpenSSL's requirement of the day.
For instance, since v6.3.16, fetchmail calls
OpenSSL_add_all_algorithms(), which is necessary to support certificates
-with SHA256 on OpenSSL 0.9.8 -- this information is deeply hidden in the
+using SHA256 on OpenSSL 0.9.8 -- this information is deeply hidden in the
documentation and not at all obvious. Please do not hesitate to report
subtle SSL failures.
.PP
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
option turns off use of
.BR syslog (3),
assuming it's turned on in the \fI~/.fetchmailrc\fP file.
+This option is overridden, in certain situations, by \fB\-\-logfile\fP (which
+see).
.PP
The
.B \-N
.BR init (8)
or Gerrit Pape's
.BR runit (8).
-Note that this also causes the logfile option to be ignored (though
-perhaps it shouldn't).
+Note that this also causes the logfile option to be ignored.
.PP
Note that while running in daemon mode polling a IMAP2bis server,
transient errors (such as DNS failures or sendmail delivery refusals)
.SH SMTP/ESMTP ERROR HANDLING
Besides the spam-blocking described above, fetchmail takes special
-actions on the following SMTP/ESMTP error responses
+actions \(em that may be modified by the \-\-softbounce option \(em on
+the following SMTP/ESMTP error response codes
.TP 5
452 (insufficient system storage)
Leave the message in the server mailbox for later retrieval.
Delete the message from the server. Don't even try to send
bounce-mail to the originator.
.PP
-Other errors trigger bounce mail back to the originator. See also BUGS.
+Other errors greater or equal to 500 trigger bounce mail back to the
+originator, unless suppressed by \-\-softbounce. See also BUGS.
.SH THE RUN CONTROL FILE
The preferred way to set up fetchmail is to write a
occurred (default).
T}
set logfile \-L \& T{
-Name of a file to append error and status messages to.
+Name of a file to append error and status messages to. Only effective
+in daemon mode and if fetchmail detaches. If effective, overrides \fBset
+syslog\fP.
T}
set idfile \-i \& T{
Name of the file to store UID lists in.
T}
set syslog \& \& T{
-Do error logging through syslog(3).
+Do error logging through syslog(3). May be overriden by \fBset
+logfile\fP.
T}
set no syslog \& \& T{
Turn off error logging through syslog(3). (default)
T}
proto[col] \-p \& T{
Specify protocol (case insensitive):
-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}
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)
.nf
auto (or AUTO) (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_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);
+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.
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
session ID (this elaborate logic is designed to handle the case of
multiple names per userid gracefully).
+.IP \fBFETCHMAIL_DISABLE_CBC_IV_COUNTERMEASURE\fP
+(since v6.3.22):
+If this environment variable is set and not empty, fetchmail will disable
+a countermeasure against an SSL CBC IV attack (by setting
+SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS). This is a security risk, but may be
+necessary for connecting to certain non-standards-conforming servers.
+See fetchmail's NEWS file and fetchmail-SA-2012-01.txt for details.
+Earlier fetchmail versions (v6.3.21 and older) used to disable this
+countermeasure, but v6.3.22 no longer does that as a safety precaution.
+
.IP \fBFETCHMAIL_INCLUDE_DEFAULT_X509_CA_CERTS\fP
(since v6.3.17):
If this environment variable is set and not empty, fetchmail will always load
Running \fBfetchmail\fP in foreground while a background fetchmail is
running will do whichever of these is appropriate to wake it up.
-.SH BUGS AND KNOWN PROBLEMS
+.SH BUGS, LIMITATIONS, AND KNOWN PROBLEMS
.PP
Please check the \fBNEWS\fP file that shipped with fetchmail for more
known bugs than those listed here.
only hurt when using UID-based \-\-keep setups, so the 6.3.X versions of
fetchmail won't be fixed.
.PP
+Fetchmail cannot handle configurations where you have multiple accounts
+that use the same server name and the same login. Any user@server
+combination must be unique.
+.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