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.
+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
.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.
+.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.
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
.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
\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.
+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)
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.
+the port. Fetchmail will write to the plugin's stdin and read from
+the plugin's stdout.
.TP
.B \--plugout
(Keyword: plugout)
.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 $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
+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
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])
.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
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
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.
+file, or that the
.B -L
or
.B --logfile
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.
.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
The
.I fetchmail
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
+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
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 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:
mda -m T{
Specify MDA for local delivery
T}
-bsmtp -o T{
+bsmtp -o T{
Specify BSMTP batch file to append to
T}
preconnect \& T{
Strip Status and X-Mozilla-Status lines out of incoming mail
T}
mimedecode \& T{
-Convert quoted-printable to 8-bit in MIME messages
+Convert quoted-printable to 8-bit in MIME messages (default)
T}
no keep -K T{
Delete seen messages from server (default)
Don't drop Status headers (default)
T}
no mimedecode \& T{
-Don't convert quoted-printable to 8-bit in MIME messages (default)
+Don't convert quoted-printable to 8-bit in MIME messages
T}
limit -l T{
Set message size limit
T}
-warnings -l 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)
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).
+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
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.
+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
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
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
a DNS lookup at startup and could not proceed.
.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.
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
-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.
-.P
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, 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.
+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
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
-LMTP support is untested. Mail could be lost if some but not all
-deliveries of a message addressed to multiple users fail; such
-deliveries are not retried.
+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
`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
projects / ~andy / fetchmail / blobdiff