.\" Load www macros to process .URL requests, this requires groff:
.mso www.tmac
.\"
-.TH fetchmail 1 "fetchmail 6.3.15-beta1" "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
.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.)
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
.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
-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' 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
.br
Append fetched mail to a BSMTP file. This simply contains the SMTP
commands that would normally be generated by fetchmail when passing
-mail to an SMTP listener daemon. An argument of '\-' causes the mail
-to be written to standard output. Note that fetchmail's
-reconstruction of MAIL FROM and RCPT TO lines is not guaranteed
-correct; the caveats discussed under THE USE AND ABUSE OF MULTIDROP
-MAILBOXES below apply. This mode has precedence before \-\-mda and
-SMTP/LMTP.
+mail to an SMTP listener daemon.
+
+An argument of '\-' causes the SMTP batch to be written to standard
+output, which is of limited use: this only makes sense for debugging,
+because fetchmail's regular output is interspersed on the same channel,
+so this isn't suitable for mail delivery. This special mode may be
+removed in a later release.
+
+Note that fetchmail's reconstruction of MAIL FROM and RCPT TO lines is
+not guaranteed correct; the caveats discussed under THE USE AND ABUSE OF
+MULTIDROP MAILBOXES below apply. This mode has precedence before
+\-\-mda and SMTP/LMTP.
.TP
.B \-\-bad\-header {reject|accept}
(Keyword: bad\-header; since v6.3.15)
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, 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).
\&\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.
+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
.B \-f <pathname> | \-\-fetchmailrc <pathname>
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.
.SS Secure Socket Layers (SSL) and Transport Layer Security (TLS)
.PP
+Note that fetchmail currently uses the OpenSSL library, which is
+severely underdocumented, so failures may occur just because the
+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
+documentation and not at all obvious. Please do not hesitate to report
+subtle SSL failures.
+.PP
You can access SSL encrypted services by specifying the \-\-ssl option.
You can also do this using the "ssl" user option in the .fetchmailrc
file. With SSL encryption enabled, queries are initiated over a
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
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,
+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
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}
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):
-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:
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
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
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
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
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