.\" Load www macros to process .URL requests, this requires groff:
.mso www.tmac
.\"
-.TH fetchmail 1 "fetchmail 6.3.18-pre2" "fetchmail" "fetchmail reference manual"
+.TH fetchmail 1 "fetchmail 6.3.25" "fetchmail" "fetchmail reference manual"
.SH NAME
fetchmail \- fetch mail from a POP, IMAP, ETRN, or ODMR-capable server
.IP
.nf
-env LC_ALL=C fetchmail -V -v --nodetach --nosyslog
+env LC_ALL=C fetchmail \-V \-v \-\-nodetach \-\-nosyslog
.fi
.IP
(This command line prints in English how fetchmail understands your
.IP
.nf
-env LC_ALL=C fetchmail -vvv --nodetach --nosyslog
+env LC_ALL=C fetchmail \-vvv \-\-nodetach \-\-nosyslog
.fi
.IP
(This command line actually runs fetchmail with verbose English output.)
(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
.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
+\&'\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
\&'\fBTLS1\fP'. The default behaviour if this option is unset is: for
-connections without \-\-ssl, use \&'\fBTLS1\fP' that fetchmail will
+connections without \-\-ssl, use \&'\fBTLS1\fP' so that fetchmail will
opportunistically try STARTTLS negotiation with TLS1. You can configure
this option explicitly if the default handshake (TLS1 if \-\-ssl is not
-used, does not work for your server.
+used) does not work for your server.
.IP
Use this option with '\fBTLS1\fP' value to enforce a STARTTLS
connection. In this mode, it is highly recommended to also use
-\-\-sslcertck (see below).
+\-\-sslcertck (see below). Note that this will then cause fetchmail
+v6.3.19 to force STARTTLS negotiation even if it is not advertised by
+the server.
.IP
To defeat opportunistic TLSv1 negotiation when the server advertises
-STARTTLS or STLS, use \fB''\fP. 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.
+STARTTLS or STLS, and use a cleartext connection use \fB''\fP. 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)
.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
Finally, we strongly advise that you do \fBnot\fP use qmail-inject. The
command line interface is non-standard without providing benefits for
-typical use, and fetchmail makes no attempts to accomodate
+typical use, and fetchmail makes no attempts to accommodate
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
When \fBany\fP (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
+(CRAM-MD5, NTLM, X\-OTP - note that MSN is only supported for POP3, but not
+autoprobed); 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\fP suppresses authentication and is thus useful for IMAP PREAUTH).
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.
+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
.B \-f <pathname> | \-\-fetchmailrc <pathname>
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
command line or sslcertck run control file option should be used to
force strict certificate checking - see below.
.PP
-.B \-\-sslcertck is recommended: When connecting to an SSL or TLS encrypted server, the
+.B \-\-sslcertck is 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
control file option is used, fetchmail will instead abort if any of
these checks fail, because it must assume that there is a
man-in-the-middle attack in this scenario, hence fetchmail must not
-expose cleartest passwords. Use of the sslcertck or \-\-sslcertck option
+expose cleartext passwords. Use of the sslcertck or \-\-sslcertck option
is therefore advised.
.PP
Some SSL encrypted servers may request a client side certificate. A client
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 POP2 or 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)
POSIX-compliant shell and add
.nf
-|| [ $? -eq 1 ]
+|| [ $? \-eq 1 ]
.fi
to the end of the fetchmail command line, note that this leaves 0
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
RFC 2033.
.TP 5
GSSAPI:
-RFC 1508.
+RFC 1508, RFC 1734,
+.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" .
.TP 5
TLS:
RFC 2595.
projects / ~andy / fetchmail / blobdiff