X-Git-Url: http://pileus.org/git/?a=blobdiff_plain;f=fetchmail.man;h=56026d0bea96acb40d896a9c351a9565036c215b;hb=08c75fa2b17a2d81328abaa866e9b7534a5bcee6;hp=011526af83d75c5c73edad7f0243c575facb18cf;hpb=f3a2c372e76e2b08105d4a6749b52d1bac891363;p=~andy%2Ffetchmail diff --git a/fetchmail.man b/fetchmail.man index 011526af..56026d0b 100644 --- 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.10" "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 @@ -38,7 +38,40 @@ 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 a message transfer agent for sites which refuse for security reasons to permit (sender-initiated) SMTP transactions with sendmail. + +.SS SUPPORT, TROUBLESHOOTING +.PP +For troubleshooting, tracing and debugging, you need to increase +fetchmail's verbosity to actually see what happens. To do that, please +run \fBboth of the two following commands, +adding all of the options you'd normally use.\fP + +.IP +.nf +env LC_ALL=C fetchmail \-V \-v \-\-nodetach \-\-nosyslog +.fi +.IP +(This command line prints in English how fetchmail understands your +configuration.) + +.IP +.nf +env LC_ALL=C fetchmail \-vvv \-\-nodetach \-\-nosyslog +.fi +.IP +(This command line actually runs fetchmail with verbose English output.) +.PP +Also see +.URL "http://fetchmail.berlios.de/fetchmail-FAQ.html#G3" "item #G3 in fetchmail's FAQ" .PP +You can omit the LC_ALL=C part above if you want output in the local +language (if supported). However if you are posting to mailing lists, +please leave it in. The maintainers do not necessarily understand your +language, please use English. + + + +.SS CONCEPTS If \fBfetchmail\fP is used with a POP or an IMAP server (but not with ETRN or ODMR), it has two fundamental modes of operation for each user account from which it retrieves mail: \fIsingledrop\fP- and @@ -159,10 +192,25 @@ Verbose mode. All control messages passed between \fBfetchmail\fP and the mailserver are echoed to stdout. Overrides \-\-silent. Doubling this option (\-v \-v) causes extra diagnostic information to be printed. +.TP +.B \-\-nosoftbounce +(since v6.3.10, Keyword: set no softbounce, since v6.3.10) +.br +Hard bounce mode. All permanent delivery errors cause messages to be +deleted from the upstream server, see "no softbounce" below. +.TP +.B \-\-softbounce +(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. .SS Disposal Options .TP .B \-a | \-\-all | (since v6.3.3) \-\-fetchall (Keyword: fetchall, since v3.0) +.br 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. @@ -174,6 +222,7 @@ command-line option was added in v6.3.3. .TP .B \-k | \-\-keep (Keyword: keep) +.br Keep retrieved messages on the remote mailserver. Normally, messages are deleted from the folder on the mailserver after they have been retrieved. Specifying the \fBkeep\fP option causes retrieved messages to remain in @@ -183,12 +232,15 @@ option or uidl keyword. .TP .B \-K | \-\-nokeep (Keyword: nokeep) +.br Delete retrieved messages from the remote mailserver. This option forces retrieved mail to be deleted. It may be useful if you have specified a default of \fBkeep\fP in your \&\fI.fetchmailrc\fP. This option is forced on with ETRN and ODMR. .TP .B \-F | \-\-flush +(Keyword: flush) +.br POP3/IMAP only. This is a dangerous option and can cause mail loss when used improperly. It deletes old (seen) messages from the mailserver before retrieving new messages. \fBWarning:\fP This can cause mail loss if @@ -210,6 +262,7 @@ work with ETRN or ODMR. .TP .B \-p | \-\-proto | \-\-protocol (Keyword: proto[col]) +.br Specify the protocol to use when communicating with the remote mailserver. If no protocol is specified, the default is AUTO. \fBproto\fP may be one of the following: @@ -251,6 +304,7 @@ 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 @@ -263,6 +317,7 @@ also: \-\-idfile. .TP .B \-\-idle (since 6.3.3) (Keyword: idle, since before 6.0.0) +.br Enable IDLE use (effective only with IMAP). Note that this works with only one folder at a given time. While the idle rcfile keyword had been supported for a long time, the \-\-idle command-line option was added in @@ -272,6 +327,7 @@ be possible with regular polls. .TP .B \-P | \-\-service (Keyword: service) Since version 6.3.0. +.br The service option permits you to specify a service name to connect to. You can specify a decimal port number here, if your services database lacks the required service-port assignments. See the FAQ item R12 and @@ -280,46 +336,63 @@ option. .TP .B \-\-port (Keyword: port) +.br Obsolete version of \-\-service that does not take service names. \fBNote:\fP this option may be removed from a future version. .TP .B \-\-principal (Keyword: principal) +.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 | \-\-timeout (Keyword: timeout) +.br The timeout option allows you to set a server-nonresponse timeout in seconds. If a mailserver does not send a greeting message or respond to commands for the given number of seconds, -\fBfetchmail\fP will hang up on it. Without such a timeout -\fBfetchmail\fP might hang indefinitely trying to fetch mail from a -down host. This would be particularly annoying for a \fBfetchmail\fP -running in the background. There is a default timeout which fetchmail\~\-V -will report. If a given connection receives too many timeouts in -succession, fetchmail will consider it wedged and stop retrying. -The calling user will be notified by email if this happens. +\fBfetchmail\fP will drop the connection to it. Without such a timeout +\fBfetchmail\fP might hang until the TCP connection times out, trying to fetch +mail from a down host, which may be very long. +This would be particularly annoying for a \fBfetchmail\fP running in the +background. There is a default timeout which fetchmail\~\-V will report. If a +given connection receives too many timeouts in succession, fetchmail will +consider it wedged and stop retrying. The calling user will be notified by +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 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 +will; that would mean the mail gets delivered properly, but fetchmail cannot +notice it and will thus refetch this big message over and over again. .TP .B \-\-plugin -(Keyword: plugin) The plugin option allows you to use an external -program to establish the TCP connection. This is useful if you want -to use ssh, or need some special firewalling setup. The -program will be looked up in $PATH and can optionally be passed the -hostname and port as arguments using "%h" and "%p" respectively (note -that the interpolation logic is rather primitive, and these tokens must +(Keyword: plugin) +.br +The plugin option allows you to use an external program to establish the TCP +connection. This is useful if you want to use ssh, or need some special +firewalling setup. The program will be looked up in $PATH and can optionally +be passed the hostname and port as arguments using "%h" and "%p" respectively +(note that the interpolation logic is rather primitive, and these tokens must be bounded by whitespace or beginning of string or end of string). Fetchmail will write to the plugin's stdin and read from the plugin's stdout. .TP .B \-\-plugout (Keyword: plugout) +.br Identical to the plugin option above, but this one is used for the SMTP connections. .TP .B \-r | \-\-folder (Keyword: folder[s]) +.br Causes a specified non-default mail folder on the mailserver (or comma-separated list of folders) to be retrieved. The syntax of the folder name is server-dependent. This option is not available under @@ -327,6 +400,7 @@ POP3, ETRN, or ODMR. .TP .B \-\-tracepolls (Keyword: tracepolls) +.br Tell fetchmail to poll trace information in the form 'polling account %s' and 'folder %s' to the Received line it generates, where the %s parts are replaced by the user's remote name, the poll @@ -336,7 +410,9 @@ facilitate mail filtering based on the account it is being received from. The folder information is written only since version 6.3.4. .TP .B \-\-ssl -(Keyword: ssl) Causes the connection to the mail server to be encrypted +(Keyword: ssl) +.br +Causes the connection to the mail server to be encrypted via SSL. Connect to the server using the specified base protocol over a connection secured by SSL. This option defeats opportunistic starttls negotiation. It is highly recommended to use \-\-sslproto 'SSL3' @@ -362,7 +438,7 @@ ports, which is uncommon however). .TP .B \-\-sslcert (Keyword: sslcert) -\& +.br For certificate-based client authentication. Some SSL encrypted servers require client side keys and certificates for authentication. In most cases, this is optional. This specifies the location of the public key @@ -378,6 +454,7 @@ from the certificate's CommonName and overrides the name set with .TP .B \-\-sslkey (Keyword: sslkey) +.br Specifies the file name of the client side private SSL key. Some SSL encrypted servers require client side keys and certificates for authentication. In most cases, this is optional. This specifies @@ -395,32 +472,37 @@ Also see \-\-sslcert above. .TP .B \-\-sslproto (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 @@ -429,16 +511,42 @@ accurate when using this option. Note that this optional behavior may become default behavior in future fetchmail versions. .TP +.B \-\-sslcertfile +(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 (Keyword: sslcertpath) -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). +.br +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 -(Keyword: sslcommonname) +(Keyword: sslcommonname; since v6.3.9) +.br Use of this option is discouraged. Before using it, contact the administrator of your upstream server and ask for a proper SSL certificate to be used. If that cannot be attained, this option can be @@ -451,6 +559,7 @@ the upstream server can't be made to use proper certificates. .TP .B \-\-sslfingerprint (Keyword: sslfingerprint) +.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, @@ -480,6 +589,7 @@ For details, see .TP .B \-S | \-\-smtphost (Keyword: smtp[host]) +.br Specify a hunt list of hosts to forward mail to (one or more hostnames, comma-separated). Hosts are tried in list order; the first one that is up becomes the forwarding target for the current run. If @@ -500,42 +610,62 @@ between the ODMR server and SMTP or LMTP receiver. .TP .B \-\-fetchdomains (Keyword: fetchdomains) +.br In ETRN or ODMR mode, this option specifies the list of domains the server should ship mail for once the connection is turned around. The default is the FQDN of the machine running \fBfetchmail\fP. .TP .B \-D | \-\-smtpaddress -(Keyword: smtpaddress) Specify the domain to be appended to addresses +(Keyword: smtpaddress) +.br +Specify the domain to be appended to addresses in RCPT TO lines shipped to SMTP. When this is not specified, the name of the SMTP server (as specified by \-\-smtphost) is used for SMTP/LMTP and 'localhost' is used for UNIX socket/BSMTP. .TP .B \-\-smtpname (Keyword: smtpname) +.br Specify the domain and user to be put in RCPT TO lines shipped to SMTP. The default user is the current local user. .TP .B \-Z | \-\-antispam (Keyword: antispam) +.br Specifies the list of numeric SMTP errors that are to be interpreted as a spam-block response from the listener. A value of \-1 disables this option. For the command-line option, the list values should be comma-separated. .TP .B \-m | \-\-mda -(Keyword: mda) You can force mail to be passed to an MDA directly -(rather than forwarded to port 25) with the \-\-mda or \-m option. - -To -avoid losing mail, use this option only with MDAs like maildrop or -MTAs like sendmail that return a nonzero status on disk-full and other -resource-exhaustion errors; the nonzero status tells fetchmail that -delivery failed and prevents the message from being deleted off the -server. - -If \fBfetchmail\fP is running as root, it sets its user id to -that of the target user while delivering mail through an MDA. Some -possible MDAs are "/usr/sbin/sendmail \-i \-f %F \-\- %T" (\fBNote:\fP +(Keyword: mda) +.br +This option lets \fBfetchmail\fP use a Message or Local Delivery Agent +(MDA or LDA) directly, rather than forward via SMTP or LMTP. + +To avoid losing mail, use this option only with MDAs like maildrop or +MTAs like sendmail that exit with a nonzero status on disk-full and other +delivery errors; the nonzero status tells fetchmail that delivery failed +and prevents the message from being deleted on the server. + +If \fBfetchmail\fP is running as root, it sets its user id while +delivering mail through an MDA as follows: First, the FETCHMAILUSER, +LOGNAME, and USER environment variables are checked in this order. The +value of the first variable from his list that is defined (even if it is +empty!) is looked up in the system user database. If none of the +variables is defined, fetchmail will use the real user id it was started +with. If one of the variables was defined, but the user stated there +isn't found, fetchmail continues running as root, without checking +remaining variables on the list. Practically, this means that if you +run fetchmail as root (not recommended), it is most useful to define the +FETCHMAILUSER environment variable to set the user that the MDA should +run as. Some MDAs (such as maildrop) are designed to be setuid root and +setuid to the recipient's user id, so you don't lose functionality this +way even when running fetchmail as unprivileged user. Check the MDA's +manual for details. + +Some possible MDAs are "/usr/sbin/sendmail \-i \-f %F \-\- %T" +(\fBNote:\fP some several older or vendor sendmail versions mistake \-\- for an address, rather than an indicator to mark the end of the option arguments), "/usr/bin/deliver" and "/usr/bin/maildrop \-d %T". Local delivery @@ -572,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 @@ -581,24 +711,44 @@ loops. .TP .B \-\-lmtp (Keyword: lmtp) +.br Cause delivery via LMTP (Local Mail Transfer Protocol). A service host and port \fBmust\fP be explicitly specified on each host in the smtphost hunt list (see above) if this option is selected; the default port 25 will (in accordance with RFC 2033) not be accepted. .TP .B \-\-bsmtp -(keyword: bsmtp) +(Keyword: bsmtp) +.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. +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) +.br +Specify how fetchmail is supposed to treat messages with bad headers, +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. + .SS Resource Limit Control Options .TP .B \-l | \-\-limit -(Keyword: limit) Takes a maximum octet size argument, where 0 is the +(Keyword: limit) +.br +Takes a maximum octet size argument, where 0 is the default and also the special value designating "no limit". If nonzero, messages larger than this size will not be fetched and will be left on the server (in foreground sessions, the progress messages @@ -617,6 +767,7 @@ option does not work with ETRN or ODMR. .TP .B \-w | \-\-warnings (Keyword: warnings) +.br Takes an interval in seconds. When you call \fBfetchmail\fP with a 'limit' option in daemon mode, this controls the interval at which warnings about oversized messages are mailed to the calling user @@ -628,6 +779,7 @@ place at the end of the first following poll). .TP .B \-b | \-\-batchlimit (Keyword: batchlimit) +.br Specify the maximum number of messages that will be shipped to an SMTP listener before the connection is deliberately torn down and rebuilt (defaults to 0, meaning no limit). An explicit \-\-batchlimit of 0 @@ -642,6 +794,7 @@ option does not work with ETRN or ODMR. .TP .B \-B | \-\-fetchlimit (Keyword: fetchlimit) +.br Limit the number of messages accepted from a given server in a single poll. By default there is no limit. An explicit \-\-fetchlimit of 0 overrides any limits set in your run control file. @@ -649,6 +802,7 @@ This option does not work with ETRN or ODMR. .TP .B \-\-fetchsizelimit (Keyword: fetchsizelimit) +.br Limit the number of sizes of messages accepted from a given server in a single transaction. This option is useful in reducing the delay in downloading the first mail when there are too many mails in the @@ -659,6 +813,7 @@ non-zero value is 1. .TP .B \-\-fastuidl (Keyword: fastuidl) +.br Do a binary instead of linear search for the first unseen UID. Binary search avoids downloading the UIDs of all mails. This saves time (especially in daemon mode) where downloading the same set of UIDs in @@ -671,7 +826,8 @@ used if 'n' is 0. In non-daemon mode, binary search is used if 'n' is This option works with POP3 only. .TP .B \-e | \-\-expunge -(keyword: expunge) +(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 without sending QUIT and ending the session -- with this option on, @@ -697,6 +853,7 @@ or ODMR. .TP .B \-u | \-\-user | \-\-username (Keyword: user[name]) +.br Specifies the user identification to be used when logging in to the mailserver. The appropriate user identification is both server and user-dependent. The default is your login name on the client machine that is running @@ -705,6 +862,7 @@ See USER AUTHENTICATION below for a complete description. .TP .B \-I | \-\-interface (Keyword: interface) +.br Require that a specific interface device be up and have a specific local or remote IPv4 (IPv6 is not supported by this option yet) address (or range) before polling. Frequently \fBfetchmail\fP @@ -734,6 +892,7 @@ Note that this option may be removed from a future fetchmail version. .TP .B \-M | \-\-monitor (Keyword: monitor) +.br Daemon mode can cause transient links which are automatically taken down after a period of inactivity (e.g. PPP links) to remain up indefinitely. This option identifies a system TCP/IP interface to be @@ -752,6 +911,7 @@ Note that this option may be removed from a future fetchmail version. .TP .B \-\-auth (Keyword: auth[enticate]) +.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 @@ -761,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). @@ -774,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 | \-\-fetchmailrc @@ -787,6 +949,7 @@ else be /dev/null. .TP .B \-i | \-\-idfile (Keyword: idfile) +.br Specify an alternate name for the .fetchids file used to save message UIDs. NOTE: since fetchmail 6.3.0, write access to the directory containing the idfile is required, as fetchmail writes a temporary file @@ -796,21 +959,22 @@ idfiles when running out of disk space. .TP .B \--pidfile (Keyword: pidfile; since fetchmail v6.3.4) +.br Override the default location of the PID file. Default: see "ENVIRONMENT" below. .TP .B \-n | \-\-norewrite (Keyword: no rewrite) -Normally, -\fBfetchmail\fP edits RFC-822 address headers (To, From, Cc, Bcc, and -Reply\-To) in fetched mail so that any mail IDs local to the server are -expanded to full addresses (@ and the mailserver hostname are appended). -This enables replies on the client to get addressed correctly (otherwise -your mailer might think they should be addressed to local users on the -client machine!). This option disables the rewrite. (This option is -provided to pacify people who are paranoid about having an MTA edit -mail headers and want to know they can prevent it, but it is generally -not a good idea to actually turn off rewrite.) +.br +Normally, \fBfetchmail\fP edits RFC-822 address headers (To, From, Cc, +Bcc, and Reply\-To) in fetched mail so that any mail IDs local to the +server are expanded to full addresses (@ and the mailserver hostname are +appended). This enables replies on the client to get addressed +correctly (otherwise your mailer might think they should be addressed to +local users on the client machine!). This option disables the rewrite. +(This option is provided to pacify people who are paranoid about having +an MTA edit mail headers and want to know they can prevent it, but it is +generally not a good idea to actually turn off rewrite.) When using ETRN or ODMR, the rewrite option is ineffective. .TP .B \-E | \-\-envelope @@ -841,6 +1005,7 @@ first and second, take the third, and so on. .TP .B \-Q | \-\-qvirtual (Keyword: qvirtual; Multidrop only) +.br The string prefix assigned to this option will be removed from the user name found in the header specified with the \fIenvelope\fP option (\fIbefore\fP doing multidrop name mapping or localdomain checking, @@ -1038,6 +1203,15 @@ username and the part to the right as the NTLM domain. .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 @@ -1057,7 +1231,8 @@ protocol and negotiate TLS via special command. The \-\-sslcertck 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 @@ -1069,7 +1244,7 @@ certificate. If the \-\-sslcertck command line option or sslcertck run 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 @@ -1160,9 +1335,8 @@ The or .B \-\-logfile option (keyword: set logfile) is only effective when fetchmail is -detached and in daemon mode. Note that the logfile must exist BEFORE -fetchmail is run, you -can use the +detached and in daemon mode. Note that \fBthe logfile must exist +before\fP fetchmail is run, you can use the .BR touch (1) command with the filename as its sole argument to create it. .br @@ -1191,11 +1365,7 @@ The .B \-\-nosyslog option turns off use of .BR syslog (3), -assuming it's turned on in the \fI~/.fetchmailrc\fP file, or that the -.B \-L -or -.B \-\-logfile -option was used. +assuming it's turned on in the \fI~/.fetchmailrc\fP file. .PP The .B \-N @@ -1523,6 +1693,14 @@ Warning: Do not use this to bounce spam back to the sender - most spam is sent with false sender address and thus this option hurts innocent bystanders. T} +set no softbounce \& \& T{ +Delete permanently undeliverable mail. It is recommended to use this +option if the configuration has been thoroughly tested. +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. T} @@ -1627,6 +1805,9 @@ T} esmtppassword \& \& T{ Set password for RFC2554 authentication to the ESMTP server. T} +bad-header \& \& T{ +How to treat messages with a bad header. Can be reject (default) or accept. +T} .TE Here are the legal user descriptions and options: @@ -1655,10 +1836,16 @@ ssl \& \& 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 @@ -2040,7 +2227,8 @@ 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 -logfile already exists before fetchmail is run. Also, +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 overridden by a command-line \-\-daemon option; in particular \-\-daemon\~0 can be used to force foreground operation. The 'set postmaster' @@ -2484,7 +2672,17 @@ One or more messages were successfully retrieved (or, if the \-c option was selected, were found waiting but not retrieved). .IP 1 There was no mail awaiting retrieval. (There may have been old mail still -on the server but not selected for retrieval.) +on the server but not selected for retrieval.) If you do not want "no +mail" to be an error condition (for instance, for cron jobs), use a +POSIX-compliant shell and add + +.nf +|| [ $? \-eq 1 ] +.fi + +to the end of the fetchmail command line, note that this leaves 0 +untouched, maps 1 to 0, and maps all other codes to 1. See also item #C8 +in the FAQ. .IP 2 An error was encountered when attempting to open a socket to retrieve mail. If you don't know what a socket is, don't worry about it -- @@ -2505,9 +2703,7 @@ There was a syntax error in the arguments to The run control file had bad permissions. .IP 7 There was an error condition reported by the server. Can also -fire if -\fBfetchmail\fP -timed out while waiting for the server. +fire if \fBfetchmail\fP timed out while waiting for the server. .IP 8 Client-side exclusion error. This means \fBfetchmail\fP @@ -2567,8 +2763,16 @@ lock file to help prevent concurrent runs (root mode, Linux systems). 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) @@ -2577,42 +2781,49 @@ 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). -.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. @@ -2622,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 @@ -2722,6 +2937,10 @@ Beinert, and H\['e]ctor Garc\['i]a. .SH SEE ALSO .PP +.BR README , +.BR README.SSL , +.BR README.SSL-SERVER , +.URL "http://www.fetchmail.info/fetchmail-FAQ.html" "The Fetchmail FAQ" , .BR mutt (1), .BR elm (1), .BR mail (1), @@ -2782,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.