+'\" t
+.\" ** The above line should force tbl to be used as a preprocessor **
+.\"
+.\" Man page for fetchmail
+.\"
.\" For license terms, see the file COPYING in this directory.
.TH fetchmail 1
.SH NAME
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\fR in your
-\fI.fetchmailrc\fR. This option is forced on with ETRN.
+\&\fI.fetchmailrc\fR. This option is forced on with ETRN.
.TP
.B \-F, --flush
POP3/IMAP only. Delete old (previously retrieved) messages from the mailserver
before retrieving new messages. This option does not work with ETRN.
+Warning: if your local MTA hangs and fetchmail is aborted, the next
+time you run fetchmail, it will delete mail that was never delivered to you.
+What you probably want is the default setting: if you don't specify `-k', then
+fetchmail will automatically delete messages after successful delivery.
.SS Protocol and Query Options
.TP
.B \-p, \--protocol proto
.IP IMAP-K4
IMAP4, or IMAP4rev1 (\fIfetchmail\fR autodetects their capabilities)
with RFC 1731 Kerberos v4 authentication.
+.IP IMAP-GSS
+IMAP4, or IMAP4rev1 (\fIfetchmail\fR autodetects their capabilities)
+with RFC 1731 GSSAPI authentication.
.IP ETRN
Use the ESMTP ETRN option.
.RE
.B \-U, --uidl
(Keyword: uidl)
Force UIDL use (effective only with POP3). Force client-side tracking
-of `newness' of messages. Use with `keep' to use a mailbox as a baby
-news drop for a group of users; if the mailbox is periodically purged,
-every member will get a chance to read the message.
+of `newness' of messages (UIDL stands for ``unique ID listing'' and is
+described in RFC1725). Use with `keep' to use a mailbox as a baby
+news drop for a group of users.
.TP
.B \-P, --port
(Keyword: port)
hostnames, comma-separated). In ETRN mode, set the host that the
mailserver is asked to ship mail to. Hosts are tried in list order;
the first one that is up becomes the forwarding or ETRN target for the
-current run.
+current run. Each hostname may have a '/'-delimited suffix specifying
+a port or service to forward to; the default is 25 (or "smtp" under
+IPv6).
+.TP
+.B \-D domain, --smtpaddress domain
+(Keyword: smtpaddress)
+Specify the domain to be put in RCPT TO lines shipped to SMTP. The
+name of the SMTP server (as specified by --smtphost, or defaulted to
+"localhost") is used when this is not specified.
+.TP
+.B \-Z nnn, --antispam nnn
+(Keyword: antispam)
+Specifies the numeric SMTP error that is to be interpreted as a
+spam-block response from the listener. A value of -1 disables
+this option.
.TP
.B \-m, \--mda
(Keyword: mda)
while delivering mail through an MDA. Some possible MDAs are
"/usr/sbin/sendmail -oem", "/usr/lib/sendmail -oem",
"/usr/bin/formail", and "/usr/bin/deliver". Local delivery addresses
-will be inserted into the MDA command wherever you place a %s. Do
+will be inserted into the MDA command wherever you place a %T; the
+mail message's From address will be inserted where you place an %F. Do
\fInot\fR use an MDA invocation like
"sendmail -oem -t" that dispatches on the contents of To/Cc/Bcc, it
will create mail loops and bring the just wrath of many postmasters
skipped. This option is currently only supported under Linux.
.TP
.B \-A, --auth
-(Keyword: auth[enticate])
+(Keyword: auth[enticate])
This option permits you to specify a preauthentication type (see USER
AUTHENTICATION below for details). The possible values are
-\&`\fBpassword\fR' and `\fBkerberos\fR' (or, for excruciating
-exactness, `\fBkerberos_v4\fR'). This option is provided
+\&`\fBpassword\fR', `\fBkerberos_v5\fR' and `\fBkerberos\fR' (or, for
+excruciating exactness, `\fBkerberos_v4\fR'). This option is provided
primarily for developers; choosing KPOP protocol automatically selects
-Kerberos preauthentication, and all other alternatives use
-password authentication (though APOP uses a generated one-time
-key as the password and IMAP-K4 uses RFC1731 Kerberos v4 authentication).
-This option does not work with ETRN.
+Kerberos preauthentication, and all other alternatives use password
+authentication (though APOP uses a generated one-time key as the
+password and IMAP-K4 uses RFC1731 Kerberos v4 authentication). This
+option does not work with ETRN.
.SS Miscellaneous Options
.TP
.B \-f pathname, --fetchmailrc pathname
Received lines. This is the default, and it should not be necessary
unless you have globally disabled Received parsing with `no envelope'
in the \fI.fetchmailrc\fR file.
+.TP
+.B -Q, --qvirtual
+(Keyword: qvirtual)
+The string assigned to this option will be removed from the user
+name found in the header specified with the \fIenvelope\fR option.
+This option is useful if you are using
+.I fetchmail
+to collect the mail for an entire domain and your ISP (or your mail
+redirection provider) is using qmail.
+One of the basic features of qmail is the
+.sp
+\&`Delivered-To:'
+.sp
+message header. Whenever qmail delivers a message to a local mailbox
+it puts the username and hostname of the envelope recipient on this
+line. The major reason for this is to prevent mail loops. To set up
+qmail to batch mail for a disconnected site the ISP-mailhost will have
+normally put that site in its `Virtualhosts' control file so it will
+add a prefix to all mail addresses for this site. This results in mail
+sent to 'username@userhost.userdom.dom.com' having a
+\&`Delivered-To:' line of the form:
+.sp
+Delivered-To: mbox-userstr-username@userhost.userdom.dom.com
+.sp
+The ISP can make the 'mbox-userstr-' prefix anything they choose
+but a string matching the user host name is likely.
+By using the option `envelope Delivered-To:' you can make fetchmail reliably
+identify the original envelope recipient, but you have to strip the
+`mbox-userstr-' prefix to deliver to the correct user.
+This is what this option is for.
-.SH USER AUTHENTICATION
+.SH USER AUTHENTICATION AND ENCRYPTION
Every mode except ETRN requires authentication of the client.
Normal user authentication in
.I fetchmail
is very much like the authentication mechanism of
-.I ftp(1).
+.IR ftp (1).
The correct user-id and password depend upon the underlying security
system at the mailserver.
.PP
If you use IMAP-K4, \fIfetchmail\fR will expect the IMAP server to have
RFC1731-conformant AUTHENTICATE KERBEROS_V4 capability, and will use it.
.PP
+If you use IMAP-GSS, \fIfetchmail\fR will expect the IMAP server to have
+RFC1731-conformant AUTHENTICATE GSSAPI capability, and will use it.
+Currently this has only been tested over Kerberos V, so you're expected
+to already have a ticket-granting ticket. You may pass a username different
+from your principal name using the standard \fB--user\fR command or by
+the \fI.fetchmailrc\fR option \fBuser\fR.
+.PP
If you are using POP3, and the server issues a one-time-password
challenge conforming to RFC1938, \fIfetchmail\fR will use your
password as a pass phrase to generate the required response. This
avoids sending secrets over the net unencrypted.
+.PP
+Compuserve's RPA authentication (similar to APOP) is supported. If
+you are using POP3, and the RPA code has been compiled into your
+binary, and you query a server in the Compuserve csi.com domain,
+\fIfetchmail\fR will try to perform an RPA pass-phrase authentication
+instead of sending over the password en clair.
+.PP
+If you are using IPsec, the -T (--netsec) option can be used to pass
+an IP security request to be used when outgoing IP connections are
+initialized. You can also do this using the `netsec' server option
+in the .fetchmailrc file. In either case, the option value is a
+string in the format accepted by the net_security_strtorequest()
+function of the inet6_apps library.
.SH DAEMON MODE
The
.PP
Only one daemon process is permitted per user; in daemon mode,
.I fetchmail
-makes a per-user lockfile to guarantee this. The option
+makes a per-user lockfile to guarantee this.
+.PP
+Normally, calling fetchmail with a daemon in the background sends a
+wakeup signal to the daemon, forcing it to poll mailservers
+immediately. (The wakeup signal is SIGHUP if fetchmail is running as
+root, SIGUSR1 otherwise.)
+.PP
+The option
.B --quit
-will kill a running daemon process. Otherwise, calling fetchmail with
-a daemon in the background sends a wakeup signal to the daemon,
-forcing it to poll mailservers immediately. (The wakeup signal is
-SIGHUP if fetchmail is running as root, SIGUSR1 otherwise.)
+will kill a running daemon process instead of waking it up (if there
+is no such option,
+.I fetchmail
+notifies you). If the --quit option is the only command-line option,
+that's all there is to it.
+.PP
+The quit option may also be mixed with other command-line options; its
+effect is to kill any running daemon before doing what the other
+options specify in combination with the rc file.
.PP
The
.B -t
or
.B --timeout
-option (keyword: timeout)allows you to set a server-nonresponse
+option (keyword: timeout) 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,
\fIfetchmail\fR will hang up on it. Without such a timeout
\fIfetchmail\fR might hang up indefinitely trying to fetch mail from a
down host. This would be particularly annoying for a \fIfetchmail\fR
-running in background.
+running in background. There is a default timeout which fetchmail -V
+will report.
.PP
The
.B -L
option was used.
.PP
The
+.B --invisible
+option tries to make fetchmail invisible. Normally, fetchmail behaves
+like any other MTA would -- it generates a Received header into each
+message describing its place in the chain of transmission, and tells
+the MTA it forwards to that the mail came from the machine fetchmail
+itself is running on. If the invisible option is on, the Received
+header is suppressed and fetchmail tries to spoof the MTA it forwards
+to into thinking it came directly from the mailserver host.
+.PP
+The
.B \-N
or --nodetach option suppresses backgrounding and detachment of the
daemon process from its control terminal. This is primarily useful
.PP
The
.I fetchmail
-code recognizes any of these error codes and discards the message. This is the
+code recognizes and discards the message on a code that defaults to
+sendmail's 571 but can be set with the `antispam' option. This is the
.I only
circumstance under which fetchmail ever discards mail.
.P
T}
proto[col] -p T{
Specify protocol (case insensitive):
-POP2, POP3, IMAP, IMAP-K4, APOP, KPOP
+POP2, POP3, IMAP, IMAP-K4, IMAP-GSS, APOP, KPOP
T}
port -P T{
Specify TCP/IP service port
no envelope \& T{
Disable looking for envelope address
T}
+qvirtual -Q T{
+Qmail virtual domain prefix to remove from user name
+T}
aka \& T{
Specify alternate DNS names of mailserver
T}
smtphost -S T{
Specify smtp host(s) to forward to
T}
+smtpaddress -D T{
+Specify the domain to be put in RCPT TO lines
+T}
+antispam -Z T{
+Specify what SMTP return is interpreted as a spam-policy block
+T}
mda -m T{
Specify MDA for local delivery
T}
Force BODY=8BITMIME to ESMTP listener
T}
dropstatus \& T{
-Strip Status lines out of incoming mail
+Strip Status and X-Mozilla-Status lines out of incoming mail
+T}
+mimedecode \& T{
+Convert quoted-printable to 8-bit in MIME messages (default)
T}
no keep -K T{
Delete seen messages from server (default)
no dropstatus \& T{
Don't drop Status headers (default)
T}
+no mimedecode \& T{
+Don't convert quoted-printable to 8-bit in MIME messages
+T}
limit -l T{
Set message size limit
T}
.TE
.PP
Remember that all user options must \fIfollow\fR all server options.
+.PP
+In the .fetchmailrc file, the `envelope' string argument may be
+preceded by a whitespace-separated number. This number, if specified,
+is the number of such headers to skip (that is, an argument of 1
+selects the second header of the given type). This is sometime useful
+for ignoring bogus Received headers created by an ISP's local delivery
+agent.
.SS Keywords Not Corresponding To Option Switches
.PP
The `folder' and `smtphost' options (unlike their command-line
the following: `via', `interval', `aka', `is', `to', `dns'/`no dns',
\&`password', \&`preconnect', \&`postconnect', `localdomains',
\&`stripcr'/`no stripcr', \&`forcecr'/`no forcecr', `pass8bits'/`no
-pass8bits' `dropstatus/no dropstatus', and `no envelope'.
+pass8bits' `dropstatus/no dropstatus', `mimedecode/no mimedecode',
+and `no envelope'.
.PP
The `via' option is for use with ssh, or if you want to have more
than one configuration pointing at the same site. If it is present,
of `dns', `localdomains', and `aka' for details on how matching
addresses are handled. If \fIfetchmail\fR cannot match any mailserver
usernames or localdomain addresses, the default recipient is the
-calling user.
+calling user (as set by the USER or LOGNAME variable in the
+environment; you could use this to redirect to an alias like postmaster).
.PP
The `dns' option (normally on) controls the way addresses from
multidrop mailboxes are checked. On, it enables logic to check each
the listener is 8-bit-clean (as all the major ones now are) the right
thing will probably result.
.PP
-The `dropstatus' option controls whether nonempty Status lines are
-retained in fetched mail (the default) or discarded. Retaining them
-allows your MUA to see what messages (if any) were marked seen on the
-client. On the other hand, it can confuse some new-mail notifiers,
-which assume that anything with a Status line in it has been seen.
-(Note: the empty Status lines inserted by some buggy POP servers are
-unconditionally discarded.)
+The `dropstatus' option controls whether nonempty Status and
+X-Mozilla-Status lines are retained in fetched mail (the default) or
+discarded. Retaining them allows your MUA to see what messages (if
+any) were marked seen on the server. On the other hand, it can
+confuse some new-mail notifiers, which assume that anything with a
+Status line in it has been seen. (Note: the empty Status lines
+inserted by some buggy POP servers are unconditionally discarded.)
+.PP
+The `mimedecode' option controls whether MIME messages using the
+quoted-printable encoding are automatically converted into pure
+8-bit data. If you are delivering mail to an ESMTP-capable,
+8-bit-clean listener (that includes all of the major programs
+like sendmail), then this will automatically convert quoted-printable
+message headers and data into 8-bit data, making it easier to
+understand when reading mail. If your e-mail programs know how to
+deal with MIME messages, then this option is not needed.
.PP
.SS Miscellaneous Run Control Options
The words `here' and `there' have useful English-like
pop3 (or POP3)
imap (or IMAP)
imap-k4 (or IMAP-K4)
+ imap-gss (or IMAP-GSS)
apop (or APOP)
kpop (or KPOP)
Specifying `kpop' sets POP3 protocol over port 1109 with Kerberos V4
preauthentication. These defaults may be overridden by later options.
.PP
-There are currently three global option statements; `set logfile = '
+There are currently three global option statements; `set logfile'
followed by a string sets the same global specified by --logfile. A
command-line --logfile option will override this. Also, `set daemon'
sets the poll interval as --daemon does. This can be overridden by
to force foreground operation. Finally, `set syslog' sends log
messages to syslogd(8).
+.SH INTERACTION WITH RFC 822
+When trying to detertmine the originating address of a message,
+fetchmail looks through headers in the following order:
+
+ Return-Path:
+ Resent-Sender:
+ Sender:
+ Resent-From:
+ From:
+ Reply-To:
+ Apparently-From:
+
+The originating address is used for logging, and to set the MAIL FROM
+address when forwarding to SMTP. This order is intended to cope
+gracefully with receiving mailing list messages in multidrop mode. The
+intent is that if a local address doesn't exist, the bounce message
+won't be returned blindly to the author or to the list itself, but
+rather to the list manager (which is less annoying).
+
+In multidrop mode, destination headers are processed as follows:
+First, fetchmail looks for the Received: header (or whichever one is
+specified by the `envelope' option) to determine the local
+recipient adress. If the mail is addressed to more than one recipient,
+the Received line won't contain any information regarding recipient adresses.
+
+Then fetchmail looks for the Resent-To:, Resent-Cc:, and Resent-Bcc:
+lines. If they exists, they should contain the final recipients and
+have precedence over their To:/Cc:/Bcc: counterparts. If the Resent-*
+lines doesn't exist, the To:, Cc:, Bcc: and Apparently-To: lines are
+looked for. (The presence of a Resent-To: is taken to impluy that the
+person referred by the To: address has already received the original
+copy of the mail).
+
.SH CONFIGURATION EXAMPLES
Basic format is:
preconnect command sets up the ssh.
.nf
-poll mailhost.net via localhost port 1234 with pop3:
+poll mailhost.net via localhost port 1234 with proto pop3:
preconnect "ssh -f -L 1234:mailhost.net:110
mailhost.net sleep 20 </dev/null >/dev/null";
.fi
messages; it is therefore regarded by some administrators as a
security/privacy problem.
.PP
+A slight variation of the `X-Envelope-To' header is the `Delivered-To' put
+by qmail to avoid mail loops. It will probably prefix the user name with a
+string that normally matches the user's domain. To remove this prefix you
+can use the -Q or `qvirtual' option.
+.PP
Sometimes, unfortunately, neither of these methods works. When they
-both fail, fetchmail must fall back on the contents of To/Cc/Bcc
+all fail, fetchmail must fall back on the contents of To/Cc/Bcc
headers to try to determine recipient addressees -- and these are not
reliable. In particular, mailing-list software often ships mail with
only the list broadcast address in the To header.
your FTP run control file, which (if present) will be searched for
passwords as a last resort before prompting for one interactively.
.TP 5
-~/.fetchmail
+~/.fetchmail.pid
lock file to help prevent concurrent runs (non-root mode).
.TP 5
/var/run/fetchmail.pid
whichever of these is appropriate to wake it up.
.SH BUGS AND KNOWN PROBLEMS
-The RFC822 parser used in multidrop mode chokes on some @-addresses that
-are technically legal but bizarre. Strange uses of quoting and
-embedded comments are likely to confuse it.
+The RFC822 address parser used in multidrop mode chokes on some
+@-addresses that are technically legal but bizarre. Strange uses of
+quoting and embedded comments are likely to confuse it.
.PP
-Use of any of the supported protocols other than POP3 with OTP, APOP,
-KPOP, IMAP-K4, or ETRN requires that the program send unencrypted
+Use of any of the supported protocols other than POP3 with OTP or RPA, APOP,
+KPOP, IMAP-K4, IMAP-GSS, or ETRN requires that the program send unencrypted
passwords over the TCP/IP connection to the mailserver. This creates
a risk that name/password pairs might be snaffled with a packet
sniffer or more sophisticated monitoring software. Under Linux, the
that can be opened in promiscuous mode, or (b) the intervening network
link can be tapped.
.PP
+Use of the %F or %T escapes in an mda option could open a security
+hole, because they pass text manipulable by an attacker to a shell
+command. The hole is reduced by the fact that fetchmail temporarily
+discards any suid privileges it may have while running the MDA. To
+avoid potential problems, (1) enclose the %F and %T escapes in single
+quotes within the option, and (2) never use an mda command containing
+%F or %T when fetchmail is run from the root account itself.
+.PP
Send comments, bug reports, gripes, and the like to Eric S. Raymond
<esr@thyrsus.com>. An HTML FAQ is available at the fetchmail home
page; surf to http://www.ccil.org/~esr/fetchmail or do a WWW search
projects / ~andy / fetchmail / blobdiff