.\" Load www macros to process .URL requests, this requires groff:
.mso www.tmac
.\"
-.TH fetchmail 1 "fetchmail 6.3.16" "fetchmail" "fetchmail reference manual"
+.TH fetchmail 1 "fetchmail 6.3.22" "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.)
.br
The principal option permits you to specify a service principal for
mutual authentication. This is applicable to POP3 or IMAP with Kerberos
-authentication.
+4 authentication only. It does not apply to Kerberos 5 or GSSAPI. This
+option may be removed in a future fetchmail version.
.TP
.B \-t <seconds> | \-\-timeout <seconds>
(Keyword: timeout)
.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
Causes fetchmail to strictly check the server certificate against a set of
-local trusted certificates (see the \fBsslcertpath\fP option). If the server
-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\fP option.
+local trusted certificates (see the \fBsslcertfile\fP and \fBsslcertpath\fP
+options). If the server 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\fP option.
.IP
Note that CRL (certificate revocation lists) are only supported in
OpenSSL 0.9.7 and newer! Your system clock should also be reasonably
Note that this optional behavior may become default behavior in future
fetchmail versions.
.TP
+.B \-\-sslcertfile <file>
+(Keyword: sslcertfile, since v6.3.17)
+.br
+Sets the file fetchmail uses to look up local certificates. The default is
+empty. This can be given in addition to \fB\-\-sslcertpath\fP below, and
+certificates specified in \fB\-\-sslcertfile\fP will be processed before those
+in \fB\-\-sslcertpath\fP. The option can be used in addition to
+\fB\-\-sslcertpath\fP.
+.IP
+The file is a text file. It contains the concatenation of trusted CA
+certificates in PEM format.
+.IP
+Note that using this option will suppress loading the default SSL trusted CA
+certificates file unless you set the environment variable
+\fBFETCHMAIL_INCLUDE_DEFAULT_X509_CA_CERTS\fP to a non-empty value.
+.TP
.B \-\-sslcertpath <directory>
(Keyword: sslcertpath)
.br
-Sets the directory fetchmail uses to look up local certificates. The default
-is your OpenSSL default one. The directory must be hashed as OpenSSL expects
-it - every time you add or modify a certificate in the directory, you need
-to use the \fBc_rehash\fP tool (which comes with OpenSSL in the tools/
-subdirectory).
+Sets the directory fetchmail uses to look up local certificates. The default is
+your OpenSSL default directory. The directory must be hashed the way OpenSSL
+expects it - every time you add or modify a certificate in the directory, you
+need to use the \fBc_rehash\fP tool (which comes with OpenSSL in the tools/
+subdirectory). Also, after OpenSSL upgrades, you may need to run
+\fBc_rehash\fP; particularly when upgrading from 0.9.X to 1.0.0.
+.IP
+This can be given in addition to \fB\-\-sslcertfile\fP above, which see for
+precedence rules.
+.IP
+Note that using this option will suppress adding the default SSL trusted CA
+certificates directory unless you set the environment variable
+\fBFETCHMAIL_INCLUDE_DEFAULT_X509_CA_CERTS\fP to a non-empty value.
.TP
.B \-\-sslcommonname <common name>
(Keyword: sslcommonname; since v6.3.9)
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>
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
Delete permanently undeliverable mail. It is recommended to use this
option if the configuration has been thoroughly tested.
T}
-set spambounce \& \& T{
+set softbounce \& \& T{
Keep permanently undeliverable mail as though a temporary error had
occurred (default).
T}
Connect to server over the specified base protocol using SSL encryption
T}
sslcert \& \& T{
-Specify file for client side public SSL certificate
+Specify file for \fBclient side\fP public SSL certificate
+T}
+sslcertfile \& \& T{
+Specify file with trusted CA certificates
+T}
+sslcertpath \& \& T{
+Specify c_rehash-ed directory with trusted CA certificates.
T}
sslkey \& \& T{
-Specify file for client side private SSL key
+Specify file for \fBclient side\fP private SSL key
T}
sslproto \& \& T{
Force ssl protocol for connection
POSIX-compliant shell and add
.nf
-|| [ $? -eq 1 ]
+|| [ $? \-eq 1 ]
.fi
to the end of the fetchmail command line, note that this leaves 0
lock file to help prevent concurrent runs (root mode, systems without /var/run).
.SH ENVIRONMENT
-.B FETCHMAILUSER:
-If the FETCHMAILUSER variable is set, it is used as the name of the
+.IP \fBFETCHMAILHOME\fP
+If this environment variable is set to a valid and
+existing directory name, fetchmail will read $FETCHMAILHOME/fetchmailrc
+(the dot is missing in this case), $FETCHMAILHOME/.fetchids and
+$FETCHMAILHOME/.fetchmail.pid rather than from the user's home
+directory. The .netrc file is always looked for in the the invoking
+user's home directory regardless of FETCHMAILHOME's setting.
+
+.IP \fBFETCHMAILUSER\fP
+If this environment variable is set, it is used as the name of the
calling user (default local name) for purposes such as mailing error
notifications. Otherwise, if either the LOGNAME or USER variable is
correctly set (e.g. the corresponding UID matches the session user ID)
session ID (this elaborate logic is designed to handle the case of
multiple names per userid gracefully).
-.B FETCHMAILHOME:
-If the environment variable FETCHMAILHOME is set to a valid and
-existing directory name, fetchmail will read $FETCHMAILHOME/fetchmailrc
-(the dot is missing in this case), $FETCHMAILHOME/.fetchids and
-$FETCHMAILHOME/.fetchmail.pid rather than from the user's home
-directory. The .netrc file is always looked for in the the invoking
-user's home directory regardless of FETCHMAILHOME's setting.
-
-.B HOME_ETC:
+.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
+the default X.509 trusted certificate locations for SSL/TLS CA certificates,
+even if \fB\-\-sslcertfile\fP and \fB\-\-sslcertpath\fP are given. The latter locations take precedence over the system default locations.
+This is useful in case there are broken certificates in the system directories
+and the user has no administrator privileges to remedy the problem.
+
+.IP \fBHOME_ETC\fP
If the HOME_ETC variable is set, fetchmail will read
$HOME_ETC/.fetchmailrc instead of ~/.fetchmailrc.
If HOME_ETC and FETCHMAILHOME are both set, HOME_ETC will be ignored.
-.B SOCKS_CONF:
+.IP \fBSOCKS_CONF\fP
(only if SOCKS support is compiled in) this variable is used by the
socks library to find out which configuration file it should read. Set
this to /dev/null to bypass the SOCKS proxy.
.SH SIGNALS
-If a
-\fBfetchmail\fP
-daemon is running as root, SIGUSR1 wakes it up from its sleep phase and
-forces a poll of all non-skipped servers. For compatibility reasons,
-SIGHUP can also be used in 6.3.X but may not be available in future
+If a \fBfetchmail\fP daemon is running as root, SIGUSR1 wakes it up from its
+sleep phase and forces a poll of all non-skipped servers. For compatibility
+reasons, SIGHUP can also be used in 6.3.X but may not be available in future
fetchmail versions.
.PP
-If
-\fBfetchmail\fP
-is running in daemon mode as non-root, use SIGUSR1 to wake it (this is
-so SIGHUP due to logout can retain the default action of killing it).
+If \fBfetchmail\fP is running in daemon mode as non-root, use SIGUSR1 to wake
+it (this is so SIGHUP due to logout can retain the default action of killing
+it).
.PP
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