Note Earl's regression fix for SSL_CTX_clear_options() on older OpenSSL.

[~andy/fetchmail] / fetchmail.man

diff --git a/fetchmail.man b/fetchmail.man
index 2f5268273e9e697ad788595e7488399369899d7a..56026d0bea96acb40d896a9c351a9565036c215b 100644 (file)
--- a/fetchmail.man
+++ b/fetchmail.man
@@ -10,7 +10,7 @@
 .\" 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.22" "fetchmail" "fetchmail reference manual"
 
 .SH NAME
 fetchmail \- fetch mail from a POP, IMAP, ETRN, or ODMR-capable server
@@ -48,7 +48,7 @@ adding all of the options you'd normally use.\fP
 
 .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
@@ -56,7 +56,7 @@ configuration.)
 
 .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.)
@@ -365,7 +365,7 @@ email if this happens.
 .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
@@ -474,23 +474,26 @@ Also see \-\-sslcert above.
 (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)
@@ -699,7 +702,7 @@ maildrop easier to understand.
 
 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
@@ -918,8 +921,8 @@ excruciating exactness, \fBkerberos_v4\fP), \fBgssapi\fP,
 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).
@@ -931,7 +934,9 @@ 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.
+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>
@@ -2672,7 +2677,7 @@ mail" to be an error condition (for instance, for cron jobs), use a
 POSIX-compliant shell and add
 
 .nf
-|| [ $? -eq 1 ]
+|| [ $? \-eq 1 ]
 .fi
 
 to the end of the fetchmail command line, note that this leaves 0
@@ -2776,6 +2781,16 @@ then that name is used as the default local name.  Otherwise
 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
@@ -2808,7 +2823,7 @@ it).
 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.
@@ -2818,6 +2833,10 @@ character, for instance "demonstr@ti on". These are rather uncommon and
 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
@@ -2982,7 +3001,8 @@ LMTP:
 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.