.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
.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
.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
.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. If a given connection receives too many timeouts in
+succession, fetchmail will consider it wedged and stop retrying,
+the calkling user will be notified by email if this happens.
+.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. Fetchmail will write to the plugin's stdin and read from
+the plugin's stdout.
+.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. Each hostname may have a '/'-delimited suffix specifying
-a port or service to forward to; the default is 25 (or "smtp" under
-IPv6).
+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)
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
+.B \-Z nnn, --antispam nnn[,nnn[,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.
+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. 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
-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
+forwarded to port 25) with the -mda or -m option. Be aware that this
+disables some valuable resource-exhaustion checks and error handling
+provided by SMTP listeners; it's not a good idea unless running an
+SMTP listener is impossible. 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 -f %F
+%T", "/usr/bin/deliver" and "/usr/bin/procmail -d %T" (but the latter
+is usually redundant as it's what SMTP listeners usually forward
+to). 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.
This option does not work with ETRN.
.TP
.B -e, --expunge
-(keyword: expunge)
-When talking to an IMAP server,
+(keyword: expunge)
+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,
+fetchmail will break a long mail retrieval session into multiple
+subsessions, sending QUIT after each sub-session. This is a good
+defense against line drops on POP3 servers that do not do the
+equivalent of a QUIT on hangup. Under IMAP,
.I fetchmail
normally issues an EXPUNGE command after each deletion in order to
force the deletion to be done immediately. This is safest when your
expunges less frequently. If you specify this option to an integer N,
it tells
.I fetchmail
-to only issue expunges on every Nth delete. An argument
-of zero suppresses expunges entirely (so no expunges at all will be
-done until the end of run).
-This option does not work with ETRN, POP2, or POP3.
+to only issue expunges on every Nth delete. An argument of zero
+suppresses expunges entirely (so no expunges at all will be done until
+the end of run). This option does not work with ETRN.
.SS Authentication Options
.TP
.B \-u name, --username name
The field after the second slash is a mask which specifies a range of
IP addresses to accept. If no mask is present 255.255.255.255 is
assumed (i.e. an exact match). This option is currently only supported
-under Linux.
+under Linux and FreeBSD. Please see the
+.B monitor
+section for below for FreeBSD specific information.
.TP
.B \-M interface, --monitor interface
(Keyword: monitor)
indefinitely. This option identifies a system TCP/IP interface to be
monitored for activity. After each poll interval, if the link is up but
no other activity has occurred on the link, then the poll will be
-skipped. This option is currently only supported under Linux.
+skipped. This option is currently only supported under Linux and FreeBSD.
+For the
+.B monitor
+and
+.B interface
+options to work for non root users under FreeBSD, the fetchmail binary
+must be installed SGID kmem. This would be a security hole, but
+fetchmail runs with the effective GID set to that of the kmem group
+.I only
+when interface data is being collected.
.TP
.B \-A, --auth
(Keyword: auth[enticate])
.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 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
.I .netrc
file in your home directory before requesting one interactively; if an
entry matching the mailserver is found in that file, the password will
-be used. See the
+be used. Fetchmail first looks for a match on poll name; if it finds none,
+it checks for a match on via name. See the
.IR ftp (1)
man page for details of the syntax of the
.I .netrc
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.
from your principal name using the standard \fB--user\fR command or by
the \fI.fetchmailrc\fR option \fBuser\fR.
.PP
+If your IMAP daemon returns the PREAUTH response in its greeting line,
+fetchmail will notice this and skip the normal authentication step.
+This could be useful, e.g. if you start imapd explicitly using ssh.
+.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.
+Compuserve's RPA authentication (similar to APOP) is supported. If you
+compile in the support, \fIfetchmail\fR will try to perform an RPA pass-phrase
+authentication instead of sending over the password en clair if it
+detects "@compuserve.com" in the hostname.
+.PP
+Microsoft's NTLM authentication (used by Microsoft Exchange) is
+supported. If you compile in the support, \fIfetchmail\fR will try to
+perform an NTLM authentication (instead of sending over the
+password en clair) whenever the server returns AUTH=NTLM in its
+capability response.
.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
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.)
+root, SIGUSR1 otherwise.) The wakeup action also clears any `wedged'
+flags indicating that connections have wedged due to failed
+authentication or multiple timeouts.
.PP
The option
.B --quit
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
-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.
-.PP
The
.B -L
or
.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.
indicate the status of the daemon and the results while fetching mail
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
+file are still written to stderr, or to the specified log file.
+The
+.B --nosyslog
+option turns off use of
+.IR syslog (3),
+assuming it's turned on in the
+.I .fetchmailrc
+file, or that the
.B -L
or
.B --logfile
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
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 --nobounce
+option suppresses the normal action of bouncing errors back to the
+sender in an RFC1894-conformant error message. If nobounce is on, the
+message will go to the postmaster instead.
+.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
.SH SPAM FILTERING
Many SMTP listeners allow administrators to set up `spam filters' that
-block unsolicited email from specified domains. A MAIL FROM line that
+block unsolicited email from specified domains. A MAIL FROM or DATA line that
triggers this feature will elicit an SMTP response which
(unfortunately) varies according to the listener.
.PP
.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 and discards the message on a code that defaults to
-sendmail's 571 but can be set with the `antispam' option. This is the
+code recognizes and discards the message on any of a list of responses
+that defaults to [571, 550, 501, 554] but can be set with the `antispam'
+option. This is one of the
.I only
-circumstance under which fetchmail ever discards mail.
-.P
+three circumstance under which fetchmail ever discards mail (the others
+are the 552 and 553 errors described below, and the suppression of
+multidropped messages with a message-ID already seen).
+.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 no bouncemail \& T{
+Direct error mail to postmaster rather than sender
+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}
+set properties \& T{
+String value is ignored by fetchmail (may be used by extension scripts)
+T}
+.TE
+
+Here are the legal server options:
+
.TS
l l lw34.
Keyword Opt Function
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}
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
+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}
dropstatus \& T{
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)
T}
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}
+warnings -w T{
+Set message size warning interval
+T}
batchlimit -b T{
-Max # messages to fetch in single connect
+Max # messages to forward in single connect
T}
fetchlimit -B T{
-Max # messages to forward in single connect
+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
.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 (as set by the USER or LOGNAME variable in the
-environment; you could use this to redirect to an alias like postmaster).
+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 mail will be bounced.
+Normally it will be bounced to the sender, but if `nobounce' is on
+it will go to the postmaster (which in turn defaults to being the
+calling user).
.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
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 MTAs 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 (but does no harm). The mimedecode
+option is on by default.
+.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
significance. Normally `user eric is esr' would mean that
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)
messages to syslogd(8).
.SH INTERACTION WITH RFC 822
-When trying to detertmine the originating address of a message,
+When trying to determine the originating address of a message,
fetchmail looks through headers in the following order:
Return-Path:
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.
+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 impluy that the
+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).
Example:
.nf
- poll pop.provider.net protocol pop3 username jsmith password secret1
+ poll pop.provider.net protocol pop3 username "jsmith" password "secret1"
.fi
.PP
Or, using some abbreviations:
.nf
- poll pop.provider.net proto pop3 user jsmith password secret1
+ poll pop.provider.net proto pop3 user "jsmith" password "secret1"
.fi
.PP
Multiple servers may be listed:
.nf
- poll pop.provider.net proto pop3 user jsmith pass secret1
- poll other.provider.net proto pop2 user John.Smith pass My^Hat
+ poll pop.provider.net proto pop3 user "jsmith" pass "secret1"
+ poll other.provider.net proto pop2 user "John.Smith" pass "My^Hat"
.fi
Here's a version of those two with more whitespace and some noise words:
.nf
poll pop.provider.net proto pop3
- user jsmith, with password secret1, is jsmith here;
+ user "jsmith", with password secret1, is "jsmith" here;
poll other.provider.net proto pop2:
- user John.Smith, with password My^Hat, is John.Smith here;
+ user "John.Smith", with password "My^Hat", is "John.Smith" here;
.fi
This version is much easier to read and doesn't cost significantly
.nf
poll mail.provider.net with proto pop3:
- user jsmith there has password "u can't krak this"
+ user "jsmith" there has password "u can't krak this"
is jws here and wants mda "/bin/mail"
.fi
.nf
defaults proto pop3
- user jsmith
+ user "jsmith"
poll pop.provider.net
- pass secret1
+ pass "secret1"
poll mail.provider.net
- user jjsmith there has password secret2
+ user "jjsmith" there has password "secret2"
.fi
It's possible to specify more than one user per server (this is only
.nf
poll pop.provider.net proto pop3 port 3111
- user jsmith with pass secret1 is smith here
- user jones with pass secret2 is jjones here
+ user "jsmith" with pass "secret1" is "smith" here
+ user jones with pass "secret2" is "jjones" here
.fi
This associates the local username `smith' with the pop.provider.net
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
Use the multiple-local-recipients feature with caution -- it can bite.
Also note that all multidrop features are ineffective in ETRN mode.
+Also, note that in multidrop mode duplicate mails are suppressed.
+A piece of mail is considered duplicate if it has the same message-ID
+as the message immediately preceding. Such runs of messages may
+be generated when copies of a message addressed to multiple
+users are delivered to a multidrop box.
+
.SS Header vs. Envelope addresses
The fundamental problem is that by having your mailserver toss several
peoples' mail in a single maildrop box, you may have thrown away
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 13
+Poll terminated by a fetch limit (see the --fetchlimit option).
+.IP 23
Internal error. You should see a message on standard error with
details.
.PP
that of the last host queried.
.SH AUTHOR
-Eric S. Raymond <esr@snark.thyrsus.com>.
+Eric S. Raymond <esr@snark.thyrsus.com>. Too many other people to
+name here have contributed code and patches.
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.
lock file to help prevent concurrent runs (root mode, systems without /var/run).
.SH ENVIRONMENT
-For correct initialization,
-.I fetchmail
-requires either that both the USER and HOME environment variables are
-correctly set, or that \fBgetpwuid\fR(3) be able to retrieve a password
-entry from your user ID.
+If either the LOGNAME or USER and the variable is correctly set
+(e.g. the corresponding UID matches the session user ID) then that
+name is used as the default local name. Otherwise \fBgetpwuid\fR(3)
+mudst be able to retrieve a password entry for the session ID (this
+elaborate logic is designed to handle the case of multiple names per
+userid gracefully).
.SH SIGNALS
If a
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.
-.PP
-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
---interface option can be used to restrict polling to availability of
-a specific interface device with a specific local IP address, but
-snooping is still possible if (a) either host has a network device
-that can be opened in promiscuous mode, or (b) the intervening network
-link can be tapped.
+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
+In a message with multiple envelope headers, only the last one
+processed will be visible to fetchmail. To get around this, use a
+mailserver-side filter that consolidates the contents of all envelope
+headers into a single one (procmail, mailagent, or maildrop can be
+orogrammed to do this fairly easily).
+.PP
+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
+and FreeBSD, the --interface option can be used to restrict polling to
+availability of a specific interface device with a specific local IP
+address, but snooping is still possible if (a) either host has a
+network device 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
+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
-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.
+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, RFC1894
.TP 5
POP2:
RFC 937
.TP 5
POP3:
-RFC 1081, RFC 1225, RFC 1460, RFC 1725, RFC 1939
+RFC 1081, RFC 1225, RFC 1460, RFC 1725, RFC 1939, RFC 2449
.TP 5
APOP:
RFC 1460, RFC 1725, RFC 1939
RFC 1176, RFC 1732
.TP 5
IMAP4:
-RFC 1730, RFC 1731, RFC 1732, RFC 2060, RFC 2061
+RFC 1730, RFC 1731, RFC 1732, RFC 2060, RFC 2061, RFC 2195
.TP 5
ETRN:
RFC 1985
.TP 5
OTP:
RFC 1938
+.TP 5
+LMTP:
+RFC 2033
projects / ~andy / fetchmail / blobdiff