.\" For license terms, see the file COPYING in this directory.
.TH fetchmail 1
.SH NAME
-fetchmail \- fetch mail from a POP, IMAP, or ETRN-capable ESMTP server
+fetchmail \- fetch mail from a POP, IMAP, or ETRN-capable server
.SH SYNOPSIS
\fBfetchmail\fR [\fIoptions\fR] [\fImailserver...\fR]
As each message is retrieved \fIfetchmail\fR normally delivers it via SMTP to
port 25 on the machine it is running on (localhost), just as though it
were being passed in over a normal TCP/IP link. The mail will then be
-delivered locally via your system's MTA (Mail Delivery Agent, usually
+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 MTA and local delivery agents will therefore work.
+your system MDA and local delivery agents will therefore work.
.PP
The behavior of
.I fetchmail
poll. By default there is no limit. An explicit --fetchlimit of 0
overrides any limits set in your run control file.
This option does not work with ETRN.
+.TP
+.B -e, --expunge
+(keyword: expunge)
+When talking to an IMAP server,
+.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
+connection to the server is flaky and expensive, as it avoids
+resending duplicate mail after a line hit. However, on large
+mailboxes the overhead of re-indexing after every message can slam the
+server pretty hard, so if your connection is reliable it is good to do
+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.
.SS Authentication Options
.TP
.B \-u name, --username name
varies. See the discussion of multidrop address handling below. As a
special case, `envelope "Received"' enables parsing of sendmail-style
Received lines. This is the default, and it should not be necessary
-unless you have globally disable Received parsing with `no envelope'
+unless you have globally disabled Received parsing with `no envelope'
in the \fI.fetchmailrc\fR file.
.SH USER AUTHENTICATION
It is possible to set a polling interval
in your
.I ~/.fetchmailrc
-file by saying `set demon <interval>', where <interval> is an
+file by saying `set daemon <interval>', where <interval> is an
integer number of seconds. If you do this, fetchmail will always
start in daemon mode unless you override it with the command-line
option --daemon 0 or -d0.
or
.B --logfile
option (keyword: set logfile) allows you to redirect status messages
-emitted while in daemon mode into a specified logfile (follow the
+emitted while detached into a specified logfile (follow the
option with the logfile name). The logfile is opened for append, so
previous messages aren't deleted. This is primarily useful for
debugging configurations.
.PP
The
.B \-N
-or --nodetach option suppresses detachment of the daemon process
-from its control terminal. This is primarily useful for debugging.
+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,
transient errors (such as DNS failures or sendmail delivery refusals)
.PP
Each server entry consists of one of the keywords `poll' or `skip',
followed by a server name, followed by server options, followed by any
-number of user descriptions.
+number of user descriptions. Note: the most common cause of syntax
+errors is mixing up user and server options.
.PP
For backward compatibility, the word `server' is a synonym for `poll'.
.PP
preconnect \& T{
Command to be executed before each connection
T}
+postconnect \& T{
+Command to be executed after each connection
+T}
keep -k T{
Don't delete seen messages from server
T}
fetchlimit -B T{
Max # messages to forward 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).
T}
.TE
+.PP
+Remember that all user options must \fIfollow\fR all server options.
.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', `localdomains', `stripcr'/`no stripcr',
-\&`forcecr'/`no forcecr', `pass8bits'/`no pass8bits' `dropstatus/no
-dropstatus', and `no envelope'.
+\&`password', \&`preconnect', \&`postconnect', `localdomains',
+\&`stripcr'/`no stripcr', \&`forcecr'/`no forcecr', `pass8bits'/`no
+pass8bits' `dropstatus/no dropstatus', 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,
establishes a mailserver connection. This may be useful if you are
attempting to set up secure POP connections with the aid of
.IR ssh (1).
+If the command returns a nonzero status, the poll of that mailserver
+will be aborted.
+.PP
+Similarly, the `postconnect' keyword similarly allows you to specify a
+shell command to be executed just after each time a mailserver
+connection is taken down.
.PP
The `forcecr' option controls whether lines terminated by LF only are
given CRLF termination before forwarding. Strictly speaking RFC821
.nf
poll mailhost.net via localhost port 1234 with pop3:
- preconnect "ssh -f -L 1234:mailhost.net:110 mailhost.net sleep 20 </dev/null >/dev/null";
+ preconnect "ssh -f -L 1234:mailhost.net:110
+ mailhost.net sleep 20 </dev/null >/dev/null";
.fi
.SH THE USE AND ABUSE OF MULTIDROP MAILBOXES
.SS Header vs. Envelope addresses
The fundamental problem is that by having your mailserver toss several
-peoples' mail in a box, you may have thrown away potentially vital
-information about who each piece of mail was actually addressed to
-(the `envelope address', as opposed to the header addresses in the RFC822
-To/Cc/Bcc headers). This `envelope address' is the address you need
-in order to reroute mail properly.
+peoples' mail in a single maildrop box, you may have thrown away
+potentially vital information about who each piece of mail was
+actually addressed to (the `envelope address', as opposed to the
+header addresses in the RFC822 To/Cc/Bcc headers). This `envelope
+address' is the address you need in order to reroute mail properly.
.PP
Sometimes
.I fetchmail
can deduce the envelope address. If the mailserver MTA is
.I sendmail
and the item of mail had just one recipient, the MTA will have written
-a `for' clause that gives the envelope addressee into its Received
+a `by/for' clause that gives the envelope addressee into its Received
header. But this doesn't work reliably for other MTAs, nor if there is
more than one recipient. By default, \fIfetchmail\fR looks for
envelope addresses in these lines; you can restore this default with
in each message containing a copy of the envelope addresses. This
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 to all receivers of the messages; it is therefore
-regarded by some administrators as a security/privacy problem.
+Note that writing an envelope header of this kind exposes the names of
+recipients (including blind-copy recopients) to all receivers of the
+messages; it is therefore regarded by some administrators as a
+security/privacy problem.
.PP
Sometimes, unfortunately, neither of these methods works. When they
both fail, fetchmail must fall back on the contents of To/Cc/Bcc
cannot deduce a recipient address that is local, and the intended
recipient address was anyone other than fetchmail's invoking user,
mail will get lost. This is what makes the multidrop feature risky.
+.PP
+A related problem is that when you blind-copy a mail message, the Bcc
+information is carried \fIonly\fR as envelope address (it's not put
+in the headers fetchmail can see unless there is an X-Envelope
+header). Thus, blind-copying to someone who gets mail over a
+fetchmail link will fail unless the the mailserver host routinely
+writes X-Envelope or an equivalent header into messages in your maildrop.
.SS Good Ways To Use Multidrop Mailboxes
Multiple local names can be used to administer a mailing list from the
recipient address on it. Unless
.I fetchmail
can deduce an envelope address, such mail will only go to the account
-running fetchmail (probably root).
+running fetchmail (probably root). Also, blind-copied users are very
+likely never to see their mail at all.
.PP
If you're tempted to use
.I fetchmail
to retrieve mail for multiple users from a single mail drop via POP or
-IMAP, think again. It would be smarter to just let it sit in the
-mailserver's queue and use ETRN mode to trigger SMTP sends
+IMAP, think again (and reread the section on header and envelope
+addresses above). It would be smarter to just let the mail sit in the
+mailserver's queue and use fetchmail's ETRN mode to trigger SMTP sends
periodically (of course, this means you have to poll more frequently
than the mailserver's expiry period). If you can't arrange this, try
setting up a UUCP feed.
+.PP
+If you absolutely \fImust\fR use multidrop for this purpose, make sure
+your mailserver writes an envelope-address header that fetchmail can
+see. Otherwise you \fIwill\fR lose mail and it \fIwill\fR come back
+to haunt you.
.SS Speeding Up Multidrop Checking
Normally, when multiple user are declared
.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
Internal error. You should see a message on standard error with
details.
.PP
lock file to help prevent concurrent runs (non-root mode).
.TP 5
/var/run/fetchmail.pid
-lock file to help prevent concurrent runs (root mode).
+lock file to help prevent concurrent runs (root mode, Linux systems).
+.TP 5
+/etc/fetchmail.pid
+lock file to help prevent concurrent runs (root mode, systems without /var/run).
.SH ENVIRONMENT
For correct initialization,
projects / ~andy / fetchmail / blobdiff