'\" 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
.SH SYNOPSIS
\fBfetchmail\fR [\fIoptions\fR] [\fImailserver...\fR]
+.br
+\fBfetchmailconf\fR
.SH DESCRIPTION
.I fetchmail
program can gather mail from servers supporting any of the common
mail-retrieval protocols: POP2, POP3, IMAP2bis, and IMAP4. It can
also use the ESMTP ETRN extension. (The RFCs describing all these
-protocols are listed at the end of this document.)
+protocols are listed at the end of this manual page.)
.PP
While
.I fetchmail
were being passed in over a normal TCP/IP link. The mail will then be
delivered locally via your system's MDA (Mail Delivery Agent, usually
\fIsendmail\fR(8) but your system may use a different one such
-as \fIsmail\fR, \fImmdf\fR, or \fIqmail\fR). All the delivery-control
-mechanisms (such as \fI.forward\fR files) normally available through
-your system MDA and local delivery agents will therefore work.
-.PP
+as \fIsmail\fR, \fImmdf\fR, \fIexim\fR, or \fIqmail\fR). All the
+delivery-control mechanisms (such as \fI.forward\fR files) normally
+available through your system MDA and local delivery agents will
+therefore work.
+.PP
+If the program
+.I fetchmailconf
+is available, it will assist you in setting up and editing a
+fetchmailrc configuration. It runs under X and requires that the
+language Python and the Tk toolkit be present on your system. If
+you are first setting up fetchmail for single-user mode, it is
+recommended that you use Novice mode. Expert mode provides
+complete control of fetchmail configuration, including the
+multidrop features. In either case, the `Autoprobe' button
+will tell you the most capable protocol a given mailserver
+supported, and warn you of potential problems with that server.
+
+.SH GENERAL OPERATION
The behavior of
.I fetchmail
is controlled by command-line options and a run control file,
-\fI~/.fetchmailrc\fR, the syntax of which we describe below. Command-line
-options override
+.IR ~/.fetchmailrc\fR ,
+the syntax of which we describe in a later section (this file is what
+the \fIfetchmailconf\fR program edits). Command-line options override
.I ~/.fetchmailrc
declarations.
.PP
Each server name that you specify following the options on the
command line will be queried. If you don't specify any servers
-on the command line, each server in your
+on the command line, each `poll' entry in your
.I ~/.fetchmailrc
file will be queried.
.PP
To facilitate the use of
.I fetchmail
-In scripts, pipelines, etc., it returns an appropriate exit code upon
+in scripts and pipelines, it returns an appropriate exit code upon
termination -- see EXIT CODES below.
-
-.SH OPTIONS
+.PP
The following options modify the behavior of \fIfetchmail\fR. It is
seldom necessary to specify any of these once you have a
working \fI.fetchmailrc\fR file set up.
.I fetchmailrc
file.
.PP
-Some special options are not covered here, but are documented insttead
-in sections on AUTHENTICATION and DAEMON MODE which follows.
+Some special options are not covered here, but are documented instead
+in sections on AUTHENTICATION and DAEMON MODE which follow.
.SS General Options
.TP
.B \-V, --version
Displays the version information for your copy of
.I fetchmail.
No mail fetch is performed.
-Instead, for each server specified, all option information
+Instead, for each server specified, all the option information
that would be computed if
-.I fetchmail.
+.I fetchmail
were connecting to that server is displayed. Any non-printables in
passwords or other string names are shown as backslashed C-like
escape sequences. This option is useful for verifying that your
not work with POP2, and may occasionally flake out under POP3.
.TP
.B \-s, --silent
-Silent mode. Suppresses all progress/status messages that are normally
-echoed to standard error during a fetch. The --verbose option
-overrides this.
+Silent mode. Suppresses all progress/status messages that are
+normally echoed to standard error during a fetch (but does not
+suppress actual error messages). The --verbose option overrides this.
.TP
.B \-v, --verbose
Verbose mode. All control messages passed between
.I fetchmail
and the mailserver are echoed to stderr. Overrides --silent.
+Doubling this option (-v -v) causes extra diagnostic information
+to be printed.
.SS Disposal Options
.TP
.B \-a, --all
(Keyword: fetchall)
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.
.TP
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
(Keyword: proto[col])
-Specify the protocol to used when communicating with the remote
-mailserver. If no protocol is specified,
-.I fetchmail
-will try each of the supported protocols in turn, terminating after
-any successful attempt.
+Specify the protocol to use when communicating with the remote
+mailserver. If no protocol is specified, the default is AUTO.
.I proto
may be one of the following:
.RS
+.IP AUTO
+Tries each of the supported protocols in turn, terminating after
+any successful attempt.
.IP POP2
Post Office Protocol 2
.IP POP3
Use POP3 with RPOP authentication.
.IP KPOP
Use POP3 with Kerberos V4 authentication on port 1109.
+.IP SDPS
+Use POP3 with Demon Internet's SDPS extensions.
.IP IMAP
IMAP2bis, IMAP4, or IMAP4rev1 (\fIfetchmail\fR autodetects their capabilities).
.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
+.P
All these alternatives work in basically the same way (communicating
with standard server daemons to fetch mail already delivered to a
mailbox on the server) except ETRN. The ETRN mode allows you to ask a
.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)
-The option permits you to specify a TCP/IP port to connect on.
+The port option permits you to specify a TCP/IP port to connect on.
This option will seldom be necessary as all the supported protocols have
well-established default port numbers.
+.TP
+.B \-t, --timeout
+(Keyword: timeout)
+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,
+\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. There is a default timeout which fetchmail -V
+will report.
+.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 socks or need some
+special firewalling setup. The program will be looked up in $PATH and
+it will be passed two arguments: the name of the server and the name of
+the port.
+.TP
+.B \--plugout
+(Keyword: plugout)
+Identical to the plugin option above, but this one is used for the SMTP
+connections (which will probably not need it, so it has been separated
+from plugin).
.TP
.B \-r folder, --folder folder
(Keyword: folder[s])
POP3 or ETRN.
.SS Delivery Control Options
.TP
-.B \-S host, --smtphost host
+.B \-S hosts, --smtphost hosts
(Keyword: smtp[host])
Specify a hunt list of hosts to forward mail to (one or more
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. Normally, `localhost' is added to the end of the list as
+an invisible default. However, when using ETRN mode or Kerberos
+authentication, the FQDN of the machine running fetchmail is added to
+the end of the list as an invisible default. Each hostname may have a
+port number following the host name. The port number is separated from
+the host name by a slash; the default port is 25 (or ``smtp'' under IPv6).
+Example:
+
+ --smtphost server1,server2/2525,server3
+
+.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[,nnn[,nnn...]]
+(Keyword: antispam)
+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)
forwarded to port 25) with the -mda or -m option. If \fIfetchmail\fR
is running as root, it sets its userid to that of the target user
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
+"/usr/sbin/sendmail -oem $USER", "/usr/bin/procmail -d $USER"
+and "/usr/bin/deliver". Local delivery addresses
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
down upon your head.
+.TP
+.B \--lmtp
+(Keyword: lmtp)
+Cause delivery via LMTP (Local Mail Transfer Protocol). A service
+port \fImust\fR be explicitly specified (with a slash suffix) on each
+host in the smtphost hunt list) if this option is selected; the
+default port 25 will (in accordance with RFC 2033) not be accepted.
+.TP
+.B \--bsmtp
+(keyword: bsmtp)
+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.
.SS Resource Limit Control Options
.TP
.B \-l, --limit
Takes a maximum octet size argument. Messages larger than this size
will not be fetched, not be marked seen, and will be left on the
server (in foreground sessions, the progress messages will note that
-they are "oversized"). An explicit --limit of 0 overrides any limits set
-in your run control file. This option is intended for those needing to
-strictly control fetch time in interactive mode. It may not be used
-with daemon mode, as users would never receive a notification that
-messages were waiting. This option does not work with ETRN.
+they are "oversized"). An explicit --limit of 0 overrides any limits
+set in your run control file. This option is intended for those
+needing to strictly control fetch time due to expensive and variable
+phone rates. In daemon mode, oversize notifications are mailed to the
+calling user (see the --warnings option). This option does not work
+with ETRN.
+.TP
+.B \-w, --warnings
+(Keyword: warnings)
+Takes an interval in seconds. When you call
+.I fetchmail
+with a `limit' option in daemon mode, this controls the interval at
+which warnings about oversized messages are mailed to the calling user
+(or the user specified by the `postmaster' option). One such
+notification is always mailed at the end of the the first poll that
+the oversized message is detected. Thereafter, renotification is
+suppressed until after the warning interval elapses (it will take
+place at the end of the first following poll).
.TP
.B -b, --batchlimit
(Keyword: batchlimit)
prompt. MTAs like \fIqmail\fR(8) and \fIsmail\fR(8) may wait till the
delivery socket is shut down to deliver. This may produce annoying
delays when
-.IR fetchmail (8)
+.I fetchmail
is processing very large batches. Setting the batch limit to some
nonzero size will prevent these delays.
This option does not work with ETRN.
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
Specify a non-default name for the
.I .fetchmailrc
-run control file. Unless the --version option is also on, the file must have
-permissions no more open than 0600 (u=rw,g=,o=) or else be /dev/null.
+run control file. The pathname argument must be either "-" (a single
+dash, meaning to read the configuration from standard input) or a
+filename. Unless the --version option is also on, a named file
+argument must have permissions no more open than 0600 (u=rw,g=,o=) or
+else be /dev/null.
.TP
.B \-i pathname, --idfile pathname
+(Keyword: idfile)
Specify an alternate name for the .fetchids file used to save POP3
UIDs.
.TP
.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
+The string prefix assigned to this option will be removed from the user
+name found in the header specified with the \fIenvelope\fR option
+(\fIbefore\fR doing multidrop name mapping or localdomain checking,
+if either is applicable). 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.
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.
+.TP
+.B --configdump
+Parse the
+.I ~/.fetchmailrc
+file, interpret any command-line options specified, and dump a
+configuration report to standard output. The configuration report is
+a data structure assignment in the language Python. This option
+is meant to be used with an interactive
+.I ~/.fetchmailrc
+editor written in Python.
-.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 your \fIfetchmail\fR was built with Kerberos support and you specify
Kerberos preauthentication (either with --auth or the \fI.fetchmailrc\fR
option \fBauthenticate kerberos_v4\fR) it will try to get a Kerberos
-ticket from the mailserver at the start of each query.
+ticket from the mailserver at the start of each query. Note: if
+either the pollnane or via name is `hesiod', fetchmail will try to use
+Hesiod to look up 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
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
-.B -t
-or
-.B --timeout
-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.
+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 -L
.PP
The
.B --syslog
-option (keyword: syslog) allows you to redirect status and error
+option (keyword: set syslog) allows you to redirect status and error
messages emitted to the
.IR syslog (3)
system daemon if available.
from the server(s).
Error messages for command line options and parsing the \fI.fetchmailrc\fR
file are still written to stderr, or the specified log file if the
+The
+.B --nosyslog
+option turns off use of
+.IR syslog (3),
+assuming it's turned on in the
+.I .fetchmailrc
+file.
.B -L
or
.B --logfile
for debugging. Note that this also causes the logfile option to be
ignored (though perhaps it shouldn't).
.PP
-Note that while running in daemon mode polling a POP2 or POP3 server,
+Note that while running in daemon mode polling a POP2 or 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
next poll cycle. (The IMAP logic doesn't delete messages until
they're delivered, so this problem does not arise.)
+.SH ADMINISTRATIVE OPTIONS
+.PP
+The
+.B --postmaster
+option (keyword: set postmaster) specifies the last-resort username to
+which multidrop mail is to be forwarded if no matching local recipient
+can be found. Normally this is just the user who invoked fetchmail.
+If the invoking user is root, then the default of this option is
+the user `postmaster'.
+.PP
+The
+.B --invisible
+option (keyword: set invisible) 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.
+
.SH RETRIEVAL FAILURE MODES
The protocols \fIfetchmail\fR uses to talk to mailservers are next to
bulletproof. In normal operation forwarding to port 25, no message is
.PP
The
.I exim
-MTA returns 501 "Syntax error in parameters or arguments" , but will
+MTA returns 501 "Syntax error in parameters or arguments", but will
move to 550 soon.
.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 any of a list of responses
+that defaults to [571, 550, 501] but can be set with the `antispam'
+option. This is the
.I only
circumstance under which fetchmail ever discards mail.
-.P
+.PP
If
.I fetchmail
is fetching from an IMAP server, the antispam response will be detected and
the message rejected immediately after the headers have been fetched,
without reading the message body. Thus, you won't pay for downloading
spam message bodies.
+.PP
+Mail that is spam-blocked triggers an RFC1892 bounce message informing
+the originator that we do not accept mail from it.
+
+.SH SMTP/ESMTP ERROR HANDLING
+Besides the spam-blocking described above,fetchmail takes special
+actions on the following SMTP/ESMTP error responses
+.TP 5
+452 (insufficient system storage)
+Leave the message in the server mailbox for later retrieval.
+.TP 5
+552 (message exceeds fixed maximum message size)
+Delete the message from the server. Send bounce-mail to the originator.
+.TP 5
+553 (invalid sending domain)
+Delete the message from the server. Send bounce-mail to the originator.
+.PP
+Other errors trigger bounce mail back to the originator.
.SH THE RUN CONTROL FILE
The preferred way to set up fetchmail is to write a
-\&\fI.fetchmailrc\fR file in your home directory. When there is a
-conflict between the command-line arguments and the arguments in this
-file, the command-line arguments take precedence.
+\&\fI.fetchmailrc\fR file in your home directory (you may do this
+directly, with a text editor, or indirectly via \fIfetchmailconf\fR).
+When there is a conflict between the command-line arguments and the
+arguments in this file, the command-line arguments take precedence.
.PP
To protect the security of your passwords, when --version is not on
your \fI~/.fetchmailrc\fR may not have more than 0600 (u=rw,g=,o=) permissions;
safely, or easily disable entries for hosts that are temporarily down.)
.PP
.SS Keyword/Option Summary
-Here are the legal server options. Keyword suffixes enclosed in
+Here are the legal options. Keyword suffixes enclosed in
square brackets are optional. Those corresponding to command-line
options are followed by `-' and the appropriate option letter.
+Here are the legal global options:
+
+.TS
+l l lw34.
+Keyword Opt Function
+_
+set daemon \& T{
+Set a background poll interval in seconds
+T}
+set postmaster \& T{
+Give the name of the last-resort mail recipient
+T}
+set logfile \& T{
+Name of a file to dump error and status messages to
+T}
+set idfile \& T{
+Name of the file to store UID lists in
+T}
+set syslog \& T{
+Do error logging through syslog(3).
+T}
+set nosyslog \& T{
+Turn off error logging through syslog(3).
+T}
+.TE
+
+Here are the legal server options:
+
.TS
l l lw34.
Keyword Opt Function
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
Set preauthentication type (default `password')
T}
timeout -t T{
-Server inactivity timout in seconds (default 300)
+Server inactivity timeout in seconds (default 300)
T}
envelope -E T{
Specify envelope-address header name
monitor -M T{
Specify IP address to monitor for activity
T}
+plugin \& T{
+Specify command through which to make server connections.
+T}
+plugout \& T{
+Specify command through which to make listener connections.
+T}
dns \& T{
Enable DNS lookup for multidrop (default)
T}
no dns \& T{
Disable DNS lookup for multidrop
T}
+checkalias \& T{
+Do comparison by IP address for multidrop
+T}
+no checkalias \& T{
+Do comparison by name for multidrop (default)
+T}
uidl -U T{
Force POP3 to use client-side UIDLs
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 returns are interpreted as spam-policy blocks
+T}
mda -m T{
Specify MDA for local delivery
T}
+bsmtp -o T{
+Specify BSMTP batch file to append to
+T}
preconnect \& T{
Command to be executed before each connection
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
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 (default)
+T}
limit -l T{
Set message size limit
T}
+warnings -l T{
+Set message size warning interval
+T}
batchlimit -b T{
Max # messages to fetch in single connect
T}
expunge -e T{
Perform an expunge on every #th message (IMAP only)
T}
-syslog \& T{
-Do error logging through syslog(3).
+properties \& T{
+String value is ignored by fetchmail (may be used by extension scripts)
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
.PP
All options correspond to the obvious command-line arguments, except
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'.
+`checkalias'/`no checkalias', `password', `preconnect', `postconnect',
+`localdomains', `stripcr'/`no stripcr', `forcecr'/`no forcecr',
+`pass8bits'/`no 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,
addresses with hostname parts that match your poll name or your `via',
`aka' or `localdomains' options, and usually also for hostname parts
which DNS tells it are aliases of the mailserver. See the discussion
-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.
+of `dns', `checkalias', `localdomains', and `aka' for details on how
+matching addresses are handled.
+.PP
+If \fIfetchmail\fR cannot match any mailserver usernames or
+localdomain addresses, the default recipient is the value of the
+`postmaster' global option if that has been set; otherwise it's the
+calling user (as set by the USER or LOGNAME variable in the
+environment).
.PP
The `dns' option (normally on) controls the way addresses from
multidrop mailboxes are checked. On, it enables logic to check each
attached to a matching hostname part, its local mapping is added to
the list of local recipients.
.PP
+The `checkalias' option (normally off) extends the lookups performed
+by the `dns' keyword in multidrop mode, providing a way to cope with
+remote MTAs that identify themselves using their canonical name, while
+they're polled using an alias.
+When such a server is polled, checks to extract the envelope address
+fail, and
+.IR fetchmail
+reverts to delivery using the To/Cc/Bcc headers (See below
+`Header vs. Envelope addresses').
+Specifying this option instructs
+.IR fetchmail
+to retrieve all the IP addresses associated with both the poll name
+and the name used by the remote MTA and to do a comparison of the IP
+addresses. This comes in handy in situations where the remote server
+undergoes frequent canonical name changes, that would otherwise
+require modifications to the rcfile. `checkalias' has no effect if
+`no dns' is specified in the rcfile.
+.PP
The `aka' option is for use with multidrop mailboxes. It allows you
to pre-declare a list of DNS aliases for a server. This is an
optimization hack that allows you to trade space for speed. When
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
+The `properties' option is an extension mechanism. It takes a string
+argument, which is ignored by fetchmail itself. The string argument may be
+used to store configuration information for scripts which require it.
+In particular, the output of `--configdump' option will make properties
+associated with a user entry readily available to a Python script.
.PP
.SS Miscellaneous Run Control Options
The words `here' and `there' have useful English-like
auto (or AUTO)
pop2 (or POP2)
pop3 (or POP3)
+ sdps (or SDPS)
imap (or IMAP)
imap-k4 (or IMAP-K4)
+ imap-gss (or IMAP-GSS)
apop (or APOP)
kpop (or KPOP)
to force foreground operation. Finally, `set syslog' sends log
messages to syslogd(8).
+.SH INTERACTION WITH RFC 822
+When trying to determine 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 address. If the mail is addressed to more than one recipient,
+the Received line won't contain any information regarding recipient addresses.
+
+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 imply that the
+person referred by the To: address has already received the original
+copy of the mail).
+
.SH CONFIGURATION EXAMPLES
Basic format is:
Here's an example of another kind of multidrop connection:
.nf
- poll pop.provider.net localdomains loonytoons.org:
+ poll pop.provider.net localdomains loonytoons.org toons.org:
user maildrop with pass secret1 to esr * here
.fi
This also says that the mailbox of account `maildrop' on the server is
a multi-drop box. It tells fetchmail that any address in the
-loonytoons.org domain (including subdomain addresses like
+loonytoons.org or toons.org domains (including subdomain addresses like
`joe@daffy.loonytoons.org') should be passed through to the local SMTP
listener without modification. Be careful of mail loops if you do this!
.PP
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
header (when it exists) is often `X-Envelope-To'. Fetchmail's
assumption about this can be changed with the -E or `envelope' option.
Note that writing an envelope header of this kind exposes the names of
-recipients (including blind-copy recopients) to all receivers of the
+recipients (including blind-copy recipients) to all receivers of the
messages; it is therefore regarded by some administrators as a
security/privacy problem.
.PP
.I fetchmail
are as follows:
.IP 0
-One or more messages were successfully retrieved.
+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.)
.IP 2
-An error was encountered when attempting to open a socket for the POP
-connection. If you don't know what a socket is, don't worry about it --
+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 --
just treat this as an 'unrecoverable error'.
.IP 3
The user authentication step failed. This usually means that a bad
or some similar text containing the word "lock".
.IP 10
The
-.I fetchmail.
+.I fetchmail
run failed while trying to do an SMTP port open or transaction.
.IP 11
Fatal DNS error. Fetchmail encountered an error while performing
a DNS lookup at startup and could not proceed.
-.IP 11
+.IP 12
+BSMTP batch file could not be opened.
+.IP 23
Internal error. You should see a message on standard error with
details.
.PP
Eric S. Raymond <esr@snark.thyrsus.com>.
This program is descended from and replaces
.IR popclient ,
-by Carl Harris <ceharris@mal.com>; the internals are quite different,
+by Carl Harris <ceharris@mal.com>; the internals have become quite different,
but some of its interface design is directly traceable to that
ancestral program.
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.
+Enabling the `mimedecode' option (which defaults to off) may render
+invalid any PGP signatures attached to mail with quoted-printable headers.
+This bug will be fixed in a future version.
+.PP
+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 or RPA, APOP,
-KPOP, IMAP-K4, or ETRN requires that the program send unencrypted
+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
-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
-for pages with `fetchmail' in their titles.
+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. Potential shell characters are replaced by `_' before
+execution. The hole is further reduced by the fact that fetchmail
+temporarily discards any suid privileges it may have while running the
+MDA. For maximum safety, however, don't use an mda command containing
+%F or %T when fetchmail is run from the root account itself.
+.PP
+Fetchmail's method of sending bouncemail requires that port 25 of localhost
+be available for sending mail via SMTP.
+.PP
+Send comments, bug reports, gripes, and the like to the
+fetchmail-friends list <fetchmail-friends@ccil.org>. An HTML FAQ is
+available at the fetchmail home page; surf to
+http://www.tuxedo.org/~esr/fetchmail or do a WWW search for pages with
+`fetchmail' in their titles.
.SH SEE ALSO
-elm(1), mail(1), sendmail(8), popd(8), imapd(8)
+mutt(1), elm(1), mail(1), sendmail(8), popd(8), imapd(8)
.SH APPLICABLE STANDARDS
.TP 5
SMTP/ESMTP:
RFC 821, RFC 1869, RFC 1652, RFC 1870, RFC1983, RFC 1985
.TP 5
mail:
-RFC 822
+RFC 822, RFC 1892
.TP 5
POP2:
RFC 937
.TP 5
OTP:
RFC 1938
+.TP 5
+LMTP:
+RFC 2033
projects / ~andy / fetchmail / blobdiff