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 \--principal <principal>
+(Keyword: principal)
+The principal option permits you to specify a service principal for
+mutual authentication. This is applicable to POP3 or IMAP with Kerberos
+authentication.
.TP
.B \-t, --timeout <seconds>
(Keyword: timeout)
the calkling user will be notified by email if this happens.
.TP
.B \--plugin <command>
-(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.
+(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, SSL, ssh, or need some special firewalling setup. The
+program will be looked up in $PATH and can optionally be passed the
+hostname and port as arguments using "%h" and "%p" respectively (note
+that the interpolation logic is rather promitive, and these token must
+be bounded by whitespace or beginning of string or end of string).
+Fetchmail will write to the plugin's stdin and read from the plugin's
+stdout.
.TP
.B \--plugout <command>
(Keyword: plugout)
name of the SMTP server (as specified by --smtphost, or defaulted to
"localhost") is used when this is not specified.
.TP
+.B --smtpname <user@domain>
+(Keyword: smtpname)
+Specify the domain and user to be put in RCPT TO lines shipped to SMTP.
+The default user is the current local user.
+.TP
.B \-Z <nnn>, --antispam <nnn[, nnn]...>
(Keyword: antispam)
Specifies the list of numeric SMTP errors that are to be interpreted
.B \-l <maxbytes>, --limit <maxbytes>
(Keyword: 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 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.
+will not be fetched and will be left on the server (in foreground
+sessions, the progress messages will note that they are "oversized").
+If the fetch protocol permits (in particular, under IMAP or POP3
+without the fetchall option) the message will not be marked seen 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 <interval>, --warnings <interval>
(Keyword: warnings)
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 --showdots
+option (keyword: set showdots) forces fetchmail to show progress dots
+even if the current tty is not stdout (for example logfiles).
+Starting with fetchmail version 5.3.0,
+progress dots are only shown on stdout by default.
.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
ever deleted (or even marked for deletion) on the host until the SMTP
listener on the client has acknowledged to \fIfetchmail\fR that the
-message has been accepted for delivery or rejected due to a apam
+message has been accepted for delivery or rejected due to a spam
block. When forwarding to an MDA, however, there is more possibility
of error (because there's no way for fetchmail to get a reliable
positive acknowledgement from the MDA).
Specify protocol (case insensitive):
POP2, POP3, IMAP, IMAP-K4, IMAP-GSS, APOP, KPOP
T}
+local[domains] \& T{
+Specify domain(s) to be regarded as local
+T}
port -P T{
Specify TCP/IP service port
T}
smtpaddress -D T{
Specify the domain to be put in RCPT TO lines
T}
+smtpname T{
+Specify the user and domain to be put in RCPT TO lines
+T}
antispam -Z T{
Specify what SMTP returns are interpreted as spam-policy blocks
T}
dropstatus \& T{
Strip Status and X-Mozilla-Status lines out of incoming mail
T}
+dropdelivered \& T{
+Strip Delivered-To lines out of incoming mail
+T}
mimedecode \& T{
Convert quoted-printable to 8-bit in MIME messages
T}
no dropstatus \& T{
Don't drop Status headers (default)
T}
+no dropdelivered \& T{
+Don't drop Delivered-To headers (default)
+T}
no mimedecode \& T{
Don't convert quoted-printable to 8-bit in MIME messages (default)
T}
Max # messages to fetch in single connect
T}
expunge -e T{
-Perform an expunge on every #th message (IMAP only)
+Perform an expunge on every #th message (IMAP and POP3 only)
T}
properties \& T{
String value is ignored by fetchmail (may be used by extension scripts)
the following: `via', `interval', `aka', `is', `to', `dns'/`no dns',
`checkalias'/`no checkalias', `password', `preconnect', `postconnect',
`localdomains', `stripcr'/`no stripcr', `forcecr'/`no forcecr',
-`pass8bits'/`no pass8bits' `dropstatus/no dropstatus', `mimedecode/no
-mimedecode', `idle/no idle', and `no envelope'.
+`pass8bits'/`no pass8bits' `dropstatus/no dropstatus',
+`dropdelivered/no dropdelivered', `mimedecode/no mimedecode', `idle/no
+idle', 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,
Status line in it has been seen. (Note: the empty Status lines
inserted by some buggy POP servers are unconditionally discarded.)
.PP
+The `dropdelivered' option controls wether Delivered-To headers will
+be kept in fetched mail (the default) or discarded. These headers are
+added by Qmail and Postfix mailservers in order to avoid mail loops but
+may get in your way if you try to "mirror" a mailserver within the same
+domain. Use with caution.
+.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
mailhost.net sleep 20 </dev/null >/dev/null";
.fi
+.PP
+Here's an another example configuration using ssh and the plugin option.
+The queries are made directly on the stdin and stdout of imapd via ssh.
+Note that in this setup, IMAP authentication can be skipped.
+
+.nf
+poll mailhost.net with proto imap and preauth ssh:
+ plugin "ssh %h /usr/sbin/imapd";
+.fi
+
.SH THE USE AND ABUSE OF MULTIDROP MAILBOXES
Use the multiple-local-recipients feature with caution -- it can bite.
Also note that all multidrop features are ineffective in ETRN mode.
.IP 2
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'.
+just treat this as an 'unrecoverable error'. This error can also be
+because a protocol fetchmail wants to use is not listed in /etc/services.
.IP 3
The user authentication step failed. This usually means that a bad
user-id, password, or APOP id was specified. Or it may mean that you
lock file to help prevent concurrent runs (root mode, systems without /var/run).
.SH ENVIRONMENT
-If either the LOGNAME or USER 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)
-must 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).
+If the FETCHMAILUSER variable is set, it is used as the name of the
+calling user (default local name) for purposes such as mailing error
+notifications. Otherwise, if either the LOGNAME or USER 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) must 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).
If the environment variable FETCHMAILHOME is set to a valid and
existing directory name, the .fetchmailrc and .fetchids and
spurious socket error messages or silently hang in the presence of
various network or server errors.
.PP
+The combination of using a remote name with embedded spaces and POP3
+UIDs will not work; the UIDL-handling code will core-dump while trying
+to read in what it sees as malformed .fetchids lines, typically
+on the second poll after startup.
+.PP
+The UIDL code is generally flaky and tends to lose its state on errors
+and line drops (so that old messages are re-seen). If this happens to
+you, switch to IMAP4.
+.PP
+The `principal' option only handles Kerberos IV, not V.
+.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
projects / ~andy / fetchmail / blobdiff