'\" t

.\" ** The above line should force tbl to be used as a preprocessor **

.\"

.\" Manual page in man(7) format with tbl(1) and groff_www(7)

.\" macros for fetchmail

.\"

.\" For license terms, see the file COPYING in this directory.

.\"

.\"

.\" Load www macros to process .URL requests, this requires groff:

.mso www.tmac

.\"

.TH fetchmail 1 "fetchmail 6.3.22" "fetchmail" "fetchmail reference manual"

.SH NAME

fetchmail \- fetch mail from a POP, IMAP, ETRN, or ODMR-capable server

.SH SYNOPSIS

\fBfetchmail\fP [\fIoption...\fP] [\fImailserver...\fP]

.br

\fBfetchmailconf\fP

.SH DESCRIPTION

\fBfetchmail\fP is a mail-retrieval and forwarding utility; it fetches

mail from remote mailservers and forwards it to your local (client)

machine's delivery system.  You can then handle the retrieved mail using

normal mail user agents such as \fBmutt\fP(1), \fBelm\fP(1) or

\fBMail\fP(1).  The \fBfetchmail\fP utility can be run in a daemon mode

to repeatedly poll one or more systems at a specified interval.

.PP

The \fBfetchmail\fP program can gather mail from servers supporting any

of the common mail-retrieval protocols: POP2 (legacy, to be removed from

future release), POP3, IMAP2bis, IMAP4, and IMAP4rev1.  It can also use

the ESMTP ETRN extension and ODMR.  (The RFCs describing all these

protocols are listed at the end of this manual page.)

.PP

While \fBfetchmail\fP is primarily intended to be used over on-demand

TCP/IP links (such as SLIP or PPP connections), it may also be useful as

a message transfer agent for sites which refuse for security reasons to

permit (sender-initiated) SMTP transactions with sendmail.

.SS SUPPORT, TROUBLESHOOTING

.PP

For troubleshooting, tracing and debugging, you need to increase

fetchmail's verbosity to actually see what happens. To do that, please

run \fBboth of the two following commands,

adding all of the options you'd normally use.\fP

.IP

.nf

env LC_ALL=C fetchmail \-V \-v \-\-nodetach \-\-nosyslog

.fi

.IP

(This command line prints in English how fetchmail understands your

configuration.)

.IP

.nf

env LC_ALL=C fetchmail \-vvv  \-\-nodetach \-\-nosyslog

.fi

.IP

(This command line actually runs fetchmail with verbose English output.)

.PP

Also see 

.URL "http://fetchmail.berlios.de/fetchmail-FAQ.html#G3" "item #G3 in fetchmail's FAQ"

.PP

You can omit the LC_ALL=C part above if you want output in the local

language (if supported). However if you are posting to mailing lists,

please leave it in. The maintainers do not necessarily understand your

language, please use English.

.SS CONCEPTS

If \fBfetchmail\fP is used with a POP or an IMAP server (but not with

ETRN or ODMR), it has two fundamental modes of operation for each user

account from which it retrieves mail: \fIsingledrop\fP- and

\fImultidrop\fP-mode.

.IP "In singledrop-mode,"

\fBfetchmail\fP assumes that all messages in the user's account

(mailbox) are intended for a single recipient.  The identity of the

recipient will either default to the local user currently executing

\fBfetchmail\fP, or will need to be explicitly specified in the

configuration file.

.IP

\fBfetchmail\fP uses singledrop-mode when the fetchmailrc configuration

contains at most a single local user specification for a given server

account.

.IP "In multidrop-mode,"

\fBfetchmail\fP assumes that the mail server account actually contains

mail intended for any number of different recipients.  Therefore,

\fBfetchmail\fP must attempt to deduce the proper "envelope recipient"

from the mail headers of each message.  In this mode of operation,

\fBfetchmail\fP almost resembles a mail transfer agent (MTA).

.IP

Note that neither the POP nor IMAP protocols were intended for use in

this fashion, and hence envelope information is often not directly

available.  The ISP must stores the envelope information in some message

header \fBand\fP. The ISP must also store one copy of the message per

recipient. If either of the conditions is not fulfilled, this process is

unreliable, because \fBfetchmail\fP must then resort to guessing the

true envelope recipient(s) of a message. This usually fails for mailing

list messages and Bcc:d mail, or mail for multiple recipients in your

domain.

.IP

\fBfetchmail\fP uses multidrop-mode when more than one local user and/or

a wildcard is specified for a particular server account in the

configuration file.

.IP "In ETRN and ODMR modes,"

these considerations do not apply, as these protocols are based on SMTP,

which provides explicit envelope recipient information. These protocols

always support multiple recipients.

.PP

As each message is retrieved, \fBfetchmail\fP 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.

\fBfetchmail\fP provides the SMTP server with an envelope recipient

derived in the manner described previously.  The mail will then be

delivered according to your MTA's rules (the Mail Transfer Agent is

usually \fBsendmail\fP(8), \fBexim\fP(8), or \fBpostfix\fP(8)).

Invoking your system's MDA (Mail Delivery Agent) is the duty of your

MTA.  All the delivery-control mechanisms (such as \fI.forward\fP files)

normally available through your system MTA and local delivery agents

will therefore be applied as usual.

.PP

If your fetchmail configuration sets a local MDA (see the \-\-mda

option), it will be used directly instead of talking SMTP to port 25.

.PP

If the program \fBfetchmailconf\fP is available, it will assist you in

setting up and editing a fetchmailrc configuration.  It runs under the X

window system and requires that the language Python and the Tk toolkit

(with Python bindings) 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 supports, and warn you of potential problems with that

server.

.SH GENERAL OPERATION

The behavior of \fBfetchmail\fP is controlled by command-line options and a

run control file, \fI~/.fetchmailrc\fP,

the syntax of which we describe in a later section (this file is what

the \fBfetchmailconf\fP program edits).  Command-line options override

\fI~/.fetchmailrc\fP 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 'poll' entry in your \fI~/.fetchmailrc\fP file will be

queried.

.PP

To facilitate the use of \fBfetchmail\fP in scripts and pipelines, it

returns an appropriate exit code upon termination -- see EXIT CODES

below.

.PP

The following options modify the behavior of \fBfetchmail\fP.  It is

seldom necessary to specify any of these once you have a

working \fI.fetchmailrc\fP file set up.

.PP

Almost all options have a corresponding keyword which can be used to

declare them in a \fI.fetchmailrc\fP file.

.PP

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 \fBfetchmail\fP.  No mail

fetch is performed.  Instead, for each server specified, all the option

information that would be computed if \fBfetchmail\fP 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 options are set the way you want them.

.TP

.B \-c | \-\-check

Return a status code to indicate whether there is mail waiting,

without actually fetching or deleting mail (see EXIT CODES below).

This option turns off daemon mode (in which it would be useless).  It

doesn't play well with queries to multiple sites, and doesn't work

with ETRN or ODMR.  It will return a false positive if you leave read but

undeleted mail in your server mailbox and your fetch protocol can't

tell kept messages from new ones.  This means it will work with IMAP,

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 output 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 \fBfetchmail\fP

and the mailserver are echoed to stdout.  Overrides \-\-silent.

Doubling this option (\-v \-v) causes extra diagnostic information

to be printed.

.TP

.B \-\-nosoftbounce

(since v6.3.10, Keyword: set no softbounce, since v6.3.10)

.br

Hard bounce mode. All permanent delivery errors cause messages to be

deleted from the upstream server, see "no softbounce" below.

.TP

.B \-\-softbounce

(since v6.3.10, Keyword: set softbounce, since v6.3.10)

.br

Soft bounce mode. All permanent delivery errors cause messages to be

left on the upstream server if the protocol supports that. Default to

match historic fetchmail documentation, to be changed to hard bounce

mode in the next fetchmail release.

.SS Disposal Options

.TP

.B \-a | \-\-all | (since v6.3.3) \-\-fetchall

(Keyword: fetchall, since v3.0)

.br

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

or ODMR.  While the \-a and \-\-all command-line and fetchall rcfile

options have been supported for a long time, the \-\-fetchall

command-line option was added in v6.3.3.

.TP

.B \-k | \-\-keep

(Keyword: keep)

.br

Keep retrieved messages on the remote mailserver.  Normally, messages

are deleted from the folder on the mailserver after they have been retrieved.

Specifying the \fBkeep\fP option causes retrieved messages to remain in

your folder on the mailserver.  This option does not work with ETRN or

ODMR. If used with POP3, it is recommended to also specify the \-\-uidl

option or uidl keyword.

.TP

.B \-K | \-\-nokeep

(Keyword: nokeep)

.br

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\fP in your

\&\fI.fetchmailrc\fP.  This option is forced on with ETRN and ODMR.

.TP

.B \-F | \-\-flush

(Keyword: flush)

.br

POP3/IMAP only.  This is a dangerous option and can cause mail loss when

used improperly. It deletes old (seen) messages from the mailserver

before retrieving new messages.  \fBWarning:\fP This can cause mail loss if

you check your mail with other clients than fetchmail, and cause

fetchmail to delete a message it had never fetched before.  It can also

cause mail loss if the mail server marks the message seen after

retrieval (IMAP2 servers). You should probably not use this option in your

configuration file. If you use it with POP3, you must use the 'uidl'

option. What you probably want is the default setting: if you don't

specify '\-k', then fetchmail will automatically delete messages after

successful delivery.

.TP

.B \-\-limitflush

POP3/IMAP only, since version 6.3.0.  Delete oversized messages from the

mailserver before retrieving new messages. The size limit should be

separately specified with the \-\-limit option.  This option does not

work with ETRN or ODMR.

.SS Protocol and Query Options

.TP

.B \-p <proto> | \-\-proto <proto> | \-\-protocol <proto>

(Keyword: proto[col])

.br

Specify the protocol to use when communicating with the remote

mailserver.  If no protocol is specified, the default is AUTO.

\fBproto\fP may be one of the following:

.RS

.IP AUTO

Tries IMAP, POP3, and POP2 (skipping any of these for which support

has not been compiled in).

.IP POP2

Post Office Protocol 2 (legacy, to be removed from future release)

.IP POP3

Post Office Protocol 3

.IP APOP

Use POP3 with old-fashioned MD5-challenge authentication.

Considered not resistant to man-in-the-middle attacks.

.IP RPOP

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 (\fBfetchmail\fP automatically detects their capabilities).

.IP ETRN

Use the ESMTP ETRN option.

.IP ODMR

Use the the On-Demand Mail Relay ESMTP profile.

.RE

.PP

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 and ODMR.  The ETRN mode

allows you to ask a compliant ESMTP server (such as BSD sendmail at

release 8.8.0 or higher) to immediately open a sender-SMTP connection

to your client machine and begin forwarding any items addressed to

your client machine in the server's queue of undelivered mail.   The

ODMR mode requires an ODMR-capable server and works similarly to

ETRN, except that it does not require the client machine to have

a static DNS.

.TP

.B \-U | \-\-uidl

(Keyword: uidl)

.br

Force UIDL use (effective only with POP3).  Force client-side tracking

of 'newness' of messages (UIDL stands for "unique ID listing" and is

described in RFC1939).  Use with 'keep' to use a mailbox as a baby

news drop for a group of users. The fact that seen messages are skipped

is logged, unless error logging is done through syslog while running in

daemon mode.  Note that fetchmail may automatically enable this option

depending on upstream server capabilities.  Note also that this option

may be removed and forced enabled in a future fetchmail version. See

also: \-\-idfile.

.TP

.B \-\-idle (since 6.3.3)

(Keyword: idle, since before 6.0.0)

.br

Enable IDLE use (effective only with IMAP). Note that this works with

only one folder at a given time.  While the idle rcfile keyword had been

supported for a long time, the \-\-idle command-line option was added in

version 6.3.3. IDLE use means that fetchmail tells the IMAP server to

send notice of new messages, so they can be retrieved sooner than would

be possible with regular polls.

.TP

.B \-P <portnumber> | \-\-service <servicename>

(Keyword: service) Since version 6.3.0.

.br

The service option permits you to specify a service name to connect to.

You can specify a decimal port number here, if your services database

lacks the required service-port assignments. See the FAQ item R12 and

the \-\-ssl documentation for details. This replaces the older \-\-port

option.

.TP

.B \-\-port <portnumber>

(Keyword: port)

.br

Obsolete version of \-\-service that does not take service names.

\fBNote:\fP this option may be removed from a future version.

.TP

.B \-\-principal <principal>

(Keyword: principal)

.br

The principal option permits you to specify a service principal for

mutual authentication.  This is applicable to POP3 or IMAP with Kerberos

4 authentication only.  It does not apply to Kerberos 5 or GSSAPI.  This

option may be removed in a future fetchmail version.

.TP

.B \-t <seconds> | \-\-timeout <seconds>

(Keyword: timeout)

.br

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,

\fBfetchmail\fP will drop the connection to it.  Without such a timeout

\fBfetchmail\fP might hang until the TCP connection times out, trying to fetch

mail from a down host, which may be very long.

This would be particularly annoying for a \fBfetchmail\fP running in the

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 calling user will be notified by

email if this happens.

.IP

Beginning with fetchmail 6.3.10, the SMTP client uses the recommended minimum

timeouts from RFC-5321 while waiting for the SMTP/LMTP server it is talking to.

You can raise the timeouts even more, but you cannot shorten them. This is to

avoid a painful situation where fetchmail has been configured with a short

timeout (a minute or less), ships a long message (many MBytes) to the local

MTA, which then takes longer than timeout to respond "OK", which it eventually

will; that would mean the mail gets delivered properly, but fetchmail cannot

notice it and will thus refetch this big message over and over again.

.TP

.B \-\-plugin <command>

(Keyword: plugin)

.br

The plugin option allows you to use an external program to establish the TCP

connection.  This is useful if you want to use 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 primitive, and these tokens 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)

.br

Identical to the plugin option above, but this one is used for the SMTP

connections.

.TP

.B \-r <name> | \-\-folder <name>

(Keyword: folder[s])

.br

Causes a specified non-default mail folder on the mailserver (or

comma-separated list of folders) to be retrieved.  The syntax of the

folder name is server-dependent.  This option is not available under

POP3, ETRN, or ODMR.

.TP

.B \-\-tracepolls

(Keyword: tracepolls)

.br

Tell fetchmail to poll trace information in the form 'polling 

account %s' and 'folder %s' to the Received line it generates,

where the %s parts are replaced by the user's remote name, the poll

label, and the folder (mailbox) where available (the Received header

also normally includes the server's true name).  This can be used to

facilitate mail filtering based on the account it is being received

from. The folder information is written only since version 6.3.4.

.TP

.B \-\-ssl

(Keyword: ssl)

.br

Causes the connection to the mail server to be encrypted

via SSL.  Connect to the server using the specified base protocol over a

connection secured by SSL. This option defeats opportunistic starttls

negotiation. It is highly recommended to use \-\-sslproto 'SSL3'

\-\-sslcertck to validate the certificates presented by the server and

defeat the obsolete SSLv2 negotiation. More information is available in

the \fIREADME.SSL\fP file that ships with fetchmail.

.IP

Note that fetchmail may still try to negotiate SSL through starttls even

if this option is omitted. You can use the \-\-sslproto option to defeat

this behavior or tell fetchmail to negotiate a particular SSL protocol.

.IP

If no port is specified, the connection is attempted to the well known

port of the SSL version of the base protocol.  This is generally a

different port than the port used by the base protocol.  For IMAP, this

is port 143 for the clear protocol and port 993 for the SSL secured

protocol, for POP3, it is port 110 for the clear text and port 995 for

the encrypted variant.

.IP

If your system lacks the corresponding entries from /etc/services, see

the \-\-service option and specify the numeric port number as given in

the previous paragraph (unless your ISP had directed you to different

ports, which is uncommon however).

.TP

.B \-\-sslcert <name>

(Keyword: sslcert)

.br

For certificate-based client authentication.  Some SSL encrypted servers

require client side keys and certificates for authentication.  In most

cases, this is optional.  This specifies the location of the public key

certificate to be presented to the server at the time the SSL session is

established.  It is not required (but may be provided) if the server

does not require it.  It may be the same file as the private key

(combined key and certificate file) but this is not recommended. Also

see \-\-sslkey below.

.sp

\fBNOTE:\fP If you use client authentication, the user name is fetched

from the certificate's CommonName and overrides the name set with

\-\-user.

.TP

.B \-\-sslkey <name>

(Keyword: sslkey)

.br

Specifies the file name of the client side private SSL key.  Some SSL

encrypted servers require client side keys and certificates for

authentication.  In most cases, this is optional.  This specifies

the location of the private key used to sign transactions with the server

at the time the SSL session is established.  It is not required (but may

be provided) if the server does not require it. It may be the same file

as the public key (combined key and certificate file) but this is not

recommended.

.IP

If a password is required to unlock the key, it will be prompted for at

the time just prior to establishing the session to the server.  This can

cause some complications in daemon mode.

.IP

Also see \-\-sslcert above.

.TP

.B \-\-sslproto <name>

(Keyword: sslproto)

.br

Forces an SSL/TLS protocol. Possible values are \fB''\fP,

\&'\fBSSL2\fP' (not supported on all systems),

\&'\fBSSL23\fP', (use of these two values is discouraged

and should only be used as a last resort) \&'\fBSSL3\fP', and

\&'\fBTLS1\fP'.  The default behaviour if this option is unset is: for

connections without \-\-ssl, use \&'\fBTLS1\fP' so that fetchmail will

opportunistically try STARTTLS negotiation with TLS1. You can configure

this option explicitly if the default handshake (TLS1 if \-\-ssl is not

used) does not work for your server.

.IP

Use this option with '\fBTLS1\fP' value to enforce a STARTTLS

connection. In this mode, it is highly recommended to also use

\-\-sslcertck (see below).  Note that this will then cause fetchmail

v6.3.19 to force STARTTLS negotiation even if it is not advertised by

the server.

.IP

To defeat opportunistic TLSv1 negotiation when the server advertises

STARTTLS or STLS, and use a cleartext connection use \fB''\fP.  This

option, even if the argument is the empty string, will also suppress the

diagnostic 'SERVER: opportunistic upgrade to TLS.' message in verbose

mode. The default is to try appropriate protocols depending on context.

.TP

.B \-\-sslcertck

(Keyword: sslcertck)

.br

Causes fetchmail to strictly check the server certificate against a set of

local trusted certificates (see the \fBsslcertfile\fP and \fBsslcertpath\fP

options). If the server certificate cannot be obtained or is not signed by one

of the trusted ones (directly or indirectly), the SSL connection will fail,

regardless of the \fBsslfingerprint\fP option.

.IP

Note that CRL (certificate revocation lists) are only supported in

OpenSSL 0.9.7 and newer! Your system clock should also be reasonably

accurate when using this option.

.IP

Note that this optional behavior may become default behavior in future

fetchmail versions.

.TP

.B \-\-sslcertfile <file>

(Keyword: sslcertfile, since v6.3.17)

.br

Sets the file fetchmail uses to look up local certificates.  The default is

empty.  This can be given in addition to \fB\-\-sslcertpath\fP below, and

certificates specified in \fB\-\-sslcertfile\fP will be processed before those

in \fB\-\-sslcertpath\fP.  The option can be used in addition to

\fB\-\-sslcertpath\fP.

.IP

The file is a text file. It contains the concatenation of trusted CA

certificates in PEM format.

.IP

Note that using this option will suppress loading the default SSL trusted CA

certificates file unless you set the environment variable

\fBFETCHMAIL_INCLUDE_DEFAULT_X509_CA_CERTS\fP to a non-empty value.

.TP

.B \-\-sslcertpath <directory>

(Keyword: sslcertpath)

.br

Sets the directory fetchmail uses to look up local certificates. The default is

your OpenSSL default directory. The directory must be hashed the way OpenSSL

expects it - every time you add or modify a certificate in the directory, you

need to use the \fBc_rehash\fP tool (which comes with OpenSSL in the tools/

subdirectory). Also, after OpenSSL upgrades, you may need to run

\fBc_rehash\fP; particularly when upgrading from 0.9.X to 1.0.0.

.IP

This can be given in addition to \fB\-\-sslcertfile\fP above, which see for

precedence rules.

.IP

Note that using this option will suppress adding the default SSL trusted CA

certificates directory unless you set the environment variable

\fBFETCHMAIL_INCLUDE_DEFAULT_X509_CA_CERTS\fP to a non-empty value.

.TP

.B \-\-sslcommonname <common name>

(Keyword: sslcommonname; since v6.3.9)

.br

Use of this option is discouraged. Before using it, contact the

administrator of your upstream server and ask for a proper SSL

certificate to be used. If that cannot be attained, this option can be

used to specify the name (CommonName) that fetchmail expects on the

server certificate.  A correctly configured server will have this set to

the hostname by which it is reached, and by default fetchmail will

expect as much. Use this option when the CommonName is set to some other

value, to avoid the "Server CommonName mismatch" warning, and only if

the upstream server can't be made to use proper certificates.

.TP

.B \-\-sslfingerprint <fingerprint>

(Keyword: sslfingerprint)

.br

Specify the fingerprint of the server key (an MD5 hash of the key) in

hexadecimal notation with colons separating groups of two digits. The letter

hex digits must be in upper case. This is the default format OpenSSL uses,

and the one fetchmail uses to report the fingerprint when an SSL connection

is established. When this is specified, fetchmail will compare the server key

fingerprint with the given one, and the connection will fail if they do not

match regardless of the \fBsslcertck\fP setting. The connection will

also fail if fetchmail cannot obtain an SSL certificate from the server.

This can be used to prevent man-in-the-middle attacks, but the finger

print from the server needs to be obtained or verified over a secure

channel, and certainly not over the same Internet connection that

fetchmail would use.

.IP

Using this option will prevent printing certificate verification errors

as long as \-\-sslcertck is unset.

.IP

To obtain the fingerprint of a certificate stored in the file cert.pem,

try:

.sp

.nf

	openssl x509 \-in cert.pem \-noout \-md5 \-fingerprint

.fi

.sp

For details, see

.BR x509 (1ssl).

.SS Delivery Control Options

.TP

.B \-S <hosts> | \-\-smtphost <hosts>

(Keyword: smtp[host])

.br

Specify a hunt list of hosts to forward mail to (one or more

hostnames, comma-separated). Hosts are tried in list order; the first

one that is up becomes the forwarding target for the current run.  If

this option is not specified, 'localhost' is used as the 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 "smtp".  If you specify an absolute path name (beginning with

a /), it will be interpreted as the name of a UNIX socket accepting

LMTP connections (such as is supported by the Cyrus IMAP daemon)

Example:

.sp

.nf

	\-\-smtphost server1,server2/2525,server3,/var/imap/socket/lmtp

.fi

.sp

This option can be used with ODMR, and will make fetchmail a relay

between the ODMR server and SMTP or LMTP receiver.

.TP

.B \-\-fetchdomains <hosts>

(Keyword: fetchdomains)

.br

In ETRN or ODMR mode, this option specifies the list of domains the

server should ship mail for once the connection is turned around.  The

default is the FQDN of the machine running \fBfetchmail\fP.

.TP

.B \-D <domain> | \-\-smtpaddress <domain>

(Keyword: smtpaddress)

.br

Specify the domain to be appended to addresses

in RCPT TO lines shipped to SMTP. When this is not specified, the name

of the SMTP server (as specified by \-\-smtphost) is used for SMTP/LMTP

and 'localhost' is used for UNIX socket/BSMTP.

.TP

.B \-\-smtpname <user@domain>

(Keyword: smtpname)

.br

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)

.br

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 <command> | \-\-mda <command>

(Keyword: mda)

.br

This option lets \fBfetchmail\fP use a Message or Local Delivery Agent

(MDA or LDA) directly, rather than forward via SMTP or LMTP.

To avoid losing mail, use this option only with MDAs like maildrop or

MTAs like sendmail that exit with a nonzero status on disk-full and other

delivery errors; the nonzero status tells fetchmail that delivery failed

and prevents the message from being deleted on the server.

If \fBfetchmail\fP is running as root, it sets its user id while

delivering mail through an MDA as follows:  First, the FETCHMAILUSER,

LOGNAME, and USER environment variables are checked in this order. The

value of the first variable from his list that is defined (even if it is

empty!) is looked up in the system user database. If none of the

variables is defined, fetchmail will use the real user id it was started

with. If one of the variables was defined, but the user stated there

isn't found, fetchmail continues running as root, without checking

remaining variables on the list.  Practically, this means that if you

run fetchmail as root (not recommended), it is most useful to define the

FETCHMAILUSER environment variable to set the user that the MDA should

run as. Some MDAs (such as maildrop) are designed to be setuid root and

setuid to the recipient's user id, so you don't lose functionality this

way even when running fetchmail as unprivileged user.  Check the MDA's

manual for details.

Some possible MDAs are "/usr/sbin/sendmail \-i \-f %F \-\- %T"

(\fBNote:\fP

some several older or vendor sendmail versions mistake \-\- for an

address, rather than an indicator to mark the end of the option arguments),

"/usr/bin/deliver" and "/usr/bin/maildrop \-d %T".  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.

\fBDo NOT enclose the %F or %T string in single quotes!\fP

For both %T and %F, fetchmail encloses the addresses in single quotes 

('), after removing any single quotes they may contain, before the MDA 

command is passed to the shell.

\fBDo NOT use an MDA invocation that dispatches on the contents of 

To/Cc/Bcc,\fP like "sendmail \-i \-t" or "qmail-inject", it will create 

mail loops and bring the just wrath of many postmasters down upon your 

head.  This is one of the most frequent configuration errors!

Also, do \fInot\fP try to combine multidrop mode with an MDA such 

as maildrop that can only accept one address, unless your upstream 

stores one copy of the message per recipient and transports the envelope 

recipient in a header; you will lose mail.

The well-known

.BR procmail (1)

package is very hard to configure properly, it has a very nasty "fall

through to the next rule" behavior on delivery errors (even temporary

ones, such as out of disk space if another user's mail daemon copies the

mailbox around to purge old messages), so your mail will end up in the

wrong mailbox sooner or later. The proper procmail configuration is

outside the scope of this document. Using

.BR maildrop (1)

is usually much easier, and many users find the filter syntax used by

maildrop easier to understand.

Finally, we strongly advise that you do \fBnot\fP use qmail-inject.  The

command line interface is non-standard without providing benefits for

typical use, and fetchmail makes no attempts to accommodate

qmail-inject's deviations from the standard. Some of qmail-inject's

command-line and environment options are actually dangerous and can

cause broken threads, non-detected duplicate messages and forwarding

loops.

.TP

.B \-\-lmtp

(Keyword: lmtp)

.br

Cause delivery via LMTP (Local Mail Transfer Protocol).  A service

host and port \fBmust\fP be explicitly specified on each host in the

smtphost hunt list (see above) if this option is selected; the default

port 25 will (in accordance with RFC 2033) not be accepted.

.TP

.B \-\-bsmtp <filename>

(Keyword: bsmtp)

.br

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 SMTP batch to be written to standard

output, which is of limited use: this only makes sense for debugging,

because fetchmail's regular output is interspersed on the same channel,

so this isn't suitable for mail delivery. This special mode may be

removed in a later release.

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.  This mode has precedence before

\-\-mda and SMTP/LMTP.

.TP

.B \-\-bad\-header {reject|accept}

(Keyword: bad\-header; since v6.3.15)

.br

Specify how fetchmail is supposed to treat messages with bad headers,

i. e. headers with bad syntax. Traditionally, fetchmail has rejected such

messages, but some distributors modified fetchmail to accept them. You can now

configure fetchmail's behaviour per server.

.SS Resource Limit Control Options

.TP

.B \-l <maxbytes> | \-\-limit <maxbytes>

(Keyword: limit)

.br

Takes a maximum octet size argument, where 0 is the

default and also the special value designating "no limit".

If nonzero, messages larger than this size 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.

.sp

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.

.sp

Combined with \-\-limitflush, it can be used to delete oversized

messages waiting on a server.  In daemon mode, oversize notifications

are mailed to the calling user (see the \-\-warnings option). This

option does not work with ETRN or ODMR.

.TP

.B \-w <interval> | \-\-warnings <interval>

(Keyword: warnings)

.br

Takes an interval in seconds.  When you call \fBfetchmail\fP

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, re-notification is

suppressed until after the warning interval elapses (it will take

place at the end of the first following poll).

.TP

.B \-b <count> | \-\-batchlimit <count>

(Keyword: batchlimit)

.br

Specify the maximum number of messages that will be shipped to an SMTP

listener before the connection is deliberately torn down and rebuilt

(defaults to 0, meaning no limit).  An explicit \-\-batchlimit of 0

overrides any limits set in your run control file.  While

\fBsendmail\fP(8) normally initiates delivery of a message immediately

after receiving the message terminator, some SMTP listeners are not so

prompt.  MTAs like \fBsmail\fP(8) may wait till the

delivery socket is shut down to deliver.  This may produce annoying

delays when \fBfetchmail\fP is processing very large batches.  Setting

the batch limit to some nonzero size will prevent these delays.  This

option does not work with ETRN or ODMR.

.TP

.B \-B <number> | \-\-fetchlimit <number>

(Keyword: fetchlimit)

.br

Limit the number of messages accepted from a given server in a single

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 or ODMR.

.TP

.B \-\-fetchsizelimit <number>

(Keyword: fetchsizelimit)

.br

Limit the number of sizes of messages accepted from a given server in

a single transaction.  This option is useful in reducing the delay in

downloading the first mail when there are too many mails in the

mailbox.  By default, the limit is 100.  If set to 0, sizes of all

messages are downloaded at the start.

This option does not work with ETRN or ODMR.  For POP3, the only valid

non-zero value is 1.

.TP

.B \-\-fastuidl <number>

(Keyword: fastuidl)

.br

Do a binary instead of linear search for the first unseen UID. Binary

search avoids downloading the UIDs of all mails. This saves time

(especially in daemon mode) where downloading the same set of UIDs in

each poll is a waste of bandwidth. The number 'n' indicates how rarely

a linear search should be done. In daemon mode, linear search is used

once followed by binary searches in 'n-1' polls if 'n' is greater than

1; binary search is always used if 'n' is 1; linear search is always

used if 'n' is 0. In non-daemon mode, binary search is used if 'n' is

1; otherwise linear search is used. The default value of 'n' is 4.

This option works with POP3 only.

.TP

.B \-e <count> | \-\-expunge <count>

(Keyword: expunge)

.br

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

sub-sessions, sending QUIT after each sub-session. This is a good

defense against line drops on POP3 servers.  Under IMAP,

\fBfetchmail\fP 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.  Also note that some servers enforce a delay

of a few seconds after each quit, so fetchmail may not be able to get

back in immediately after an expunge -- you may see "lock busy" errors

if this happens. If you specify this option to an integer N,

it tells \fBfetchmail\fP 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

or ODMR.

.SS Authentication Options

.TP

.B \-u <name> | \-\-user <name> | \-\-username <name>

(Keyword: user[name])

.br

Specifies the user identification to be used when logging in to the mailserver.

The appropriate user identification is both server and user-dependent.

The default is your login name on the client machine that is running

\fBfetchmail\fP.

See USER AUTHENTICATION below for a complete description.

.TP

.B \-I <specification> | \-\-interface <specification>

(Keyword: interface)

.br

Require that a specific interface device be up and have a specific local

or remote IPv4 (IPv6 is not supported by this option yet) address (or

range) before polling.  Frequently \fBfetchmail\fP

is used over a transient point-to-point TCP/IP link established directly

to a mailserver via SLIP or PPP.  That is a relatively secure channel.

But when other TCP/IP routes to the mailserver exist (e.g. when the link

is connected to an alternate ISP), your username and password may be

vulnerable to snooping (especially when daemon mode automatically polls

for mail, shipping a clear password over the net at predictable

intervals).  The \-\-interface option may be used to prevent this.  When

the specified link is not up or is not connected to a matching IP

address, polling will be skipped.  The format is:

.sp

.nf

	interface/iii.iii.iii.iii[/mmm.mmm.mmm.mmm]

.fi

.sp

The field before the first slash is the interface name (i.e. sl0, ppp0

etc.).  The field before the second slash is the acceptable IP address.

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 and FreeBSD. Please see the \fBmonitor\fP section for below

for FreeBSD specific information.

.sp

Note that this option may be removed from a future fetchmail version.

.TP

.B \-M <interface> | \-\-monitor <interface>

(Keyword: monitor)

.br

Daemon mode can cause transient links which are automatically taken down

after a period of inactivity (e.g. PPP links) to remain up

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.  However, when fetchmail is woken up by a signal, the

monitor check is skipped and the poll goes through unconditionally.

This option is currently only supported under Linux and FreeBSD.

For the \fBmonitor\fP and \fBinterface\fP 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 \fIonly\fP when interface data is being

collected.

.sp

Note that this option may be removed from a future fetchmail version.

.TP

.B \-\-auth <type>

(Keyword: auth[enticate])

.br

This option permits you to specify an authentication type (see USER

AUTHENTICATION below for details).  The possible values are \fBany\fP,

\&\fBpassword\fP, \fBkerberos_v5\fP, \fBkerberos\fP (or, for

excruciating exactness, \fBkerberos_v4\fP), \fBgssapi\fP,

\fBcram\-md5\fP, \fBotp\fP, \fBntlm\fP, \fBmsn\fP (only for POP3),

\fBexternal\fP (only IMAP) and \fBssh\fP.

When \fBany\fP (the default) is specified, fetchmail tries

first methods that don't require a password (EXTERNAL, GSSAPI, KERBEROS\ IV,

KERBEROS\ 5); then it looks for methods that mask your password

(CRAM-MD5, NTLM, X\-OTP - note that MSN is only supported for POP3, but not

autoprobed); and only if the server doesn't

support any of those will it ship your password en clair.  Other values

may be used to force various authentication methods

(\fBssh\fP suppresses authentication and is thus useful for IMAP PREAUTH).

(\fBexternal\fP suppresses authentication and is thus useful for IMAP EXTERNAL).

Any value other than \fBpassword\fP, \fBcram\-md5\fP, \fBntlm\fP,

\&\fBmsn\fP or \fBotp\fP suppresses fetchmail's normal inquiry for a

password.  Specify \fBssh\fP when you are using an end-to-end secure

connection such as an ssh tunnel; specify \fBexternal\fP when you use

TLS with client authentication and specify \fBgssapi\fP or

\&\fBkerberos_v4\fP if you are using a protocol variant that employs

GSSAPI or K4.  Choosing KPOP protocol automatically selects Kerberos

authentication.  This option does not work with ETRN.  GSSAPI service names are

in line with RFC-2743 and IANA registrations, see

.URL http://www.iana.org/assignments/gssapi-service-names/ "Generic Security Service Application Program Interface (GSSAPI)/Kerberos/Simple Authentication and Security Layer (SASL) Service Names" . 

.SS Miscellaneous Options

.TP

.B \-f <pathname> | \-\-fetchmailrc <pathname>

Specify a non-default name for the \fI~/.fetchmailrc\fP

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 0700 (u=rwx,g=,o=) or

else be /dev/null.

.TP

.B \-i <pathname> | \-\-idfile <pathname>

(Keyword: idfile)

.br

Specify an alternate name for the .fetchids file used to save message

UIDs. NOTE: since fetchmail 6.3.0, write access to the directory

containing the idfile is required, as fetchmail writes a temporary file

and renames it into the place of the real idfile only if the temporary

file has been written successfully. This avoids the truncation of

idfiles when running out of disk space.

.TP

.B \--pidfile <pathname>

(Keyword: pidfile; since fetchmail v6.3.4)

.br

Override the default location of the PID file. Default: see

"ENVIRONMENT" below.

.TP

.B \-n | \-\-norewrite

(Keyword: no rewrite)

.br

Normally, \fBfetchmail\fP edits RFC-822 address headers (To, From, Cc,

Bcc, and Reply\-To) in fetched mail so that any mail IDs local to the

server are expanded to full addresses (@ and the mailserver hostname are

appended).  This enables replies on the client to get addressed

correctly (otherwise your mailer might think they should be addressed to

local users on the client machine!).  This option disables the rewrite.

(This option is provided to pacify people who are paranoid about having

an MTA edit mail headers and want to know they can prevent it, but it is

generally not a good idea to actually turn off rewrite.)

When using ETRN or ODMR, the rewrite option is ineffective.

.TP

.B \-E <line> | \-\-envelope <line>

(Keyword: envelope; Multidrop only)

.br

In the configuration file, an enhanced syntax is used:

.br

\fBenvelope [<count>] <line>\fP

.sp

This option changes the header \fBfetchmail\fP assumes will carry a copy

of the mail's envelope address.  Normally this is 'X\-Envelope\-To'.

Other typically found headers to carry envelope information are

\&'X\-Original\-To' and 'Delivered\-To'.  Now, since these headers are

not standardized, practice 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,

but discouraged because it is not fully reliable.

Note that fetchmail expects the Received-line to be in a specific

format: It must contain "by \fIhost\fP for \fIaddress\fP", where

\fIhost\fP must match one of the mailserver names that fetchmail

recognizes for the account in question.

.sp

The optional count argument (only available in the configuration file)

determines how many header lines of this kind are skipped. A count of 1

means: skip the first, take the second. A count of 2 means: skip the

first and second, take the third, and so on.

.TP

.B \-Q <prefix> | \-\-qvirtual <prefix>

(Keyword: qvirtual; Multidrop only)

.br

The string prefix assigned to this option will be removed from the user

name found in the header specified with the \fIenvelope\fP option

(\fIbefore\fP doing multidrop name mapping or localdomain checking,

if either is applicable). This option is useful if you are using

\fBfetchmail\fP to collect the mail for an entire domain and your ISP

(or your mail redirection provider) is using qmail.

One of the basic features of qmail is the \fIDelivered\-To:\fP

message header.  Whenever qmail delivers a message to a local mailbox

it puts the username and hostname of the envelope recipient on this

line.  The major reason for this is to prevent mail loops.  To set up

qmail to batch mail for a disconnected site the ISP-mailhost will have

normally put that site in its 'Virtualhosts' control file so it will

add a prefix to all mail addresses for this site. This results in mail

.\" The \&@\& tries to stop HTML converters from making a mailto URL here.

sent to 'username\&@\&userhost.userdom.dom.com' having a

\fIDelivered\-To:\fR line of the form:

.IP

Delivered\-To: mbox\-userstr\-username\&@\&userhost.example.com

.PP

The ISP can make the 'mbox\-userstr\-' prefix anything they choose

but a string matching the user host name is likely.

By using the option 'envelope Delivered\-To:' you can make fetchmail reliably

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 \fI~/.fetchmailrc\fP 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

\fI~/.fetchmailrc\fP editor like \fBfetchmailconf\fP, written in Python.

.SS Removed Options

.TP

.B \-T | \-\-netsec

Removed before version 6.3.0, the required underlying inet6_apps library

had been discontinued and is no longer available.

.SH USER AUTHENTICATION AND ENCRYPTION

All modes except ETRN require authentication of the client to the server.

Normal user authentication in \fBfetchmail\fP is very much like the

authentication mechanism of

.BR ftp (1).

The correct user-id and password depend upon the underlying security

system at the mailserver.

.PP

If the mailserver is a Unix machine on which you have an ordinary user

account, your regular login name and password are used with

.BR fetchmail .

If you use the same login name on both the server and the client machines,

you needn't worry about specifying a user-id with the

.B \-u

option -- the default behavior is to use your login name on the

client machine as the user-id on the server machine.  If you use a

different login name on the server machine, specify that login name

with the

.B \-u

option.  e.g. if your login name is 'jsmith' on a machine named 'mailgrunt',

you would start \fBfetchmail\fP as follows:

.IP

fetchmail \-u jsmith mailgrunt

.PP

The default behavior of \fBfetchmail\fP is to prompt you for your

mailserver password before the connection is established.  This is the

safest way to use \fBfetchmail\fP and ensures that your password will

not be compromised.  You may also specify your password in your

\fI~/.fetchmailrc\fP file.  This is convenient when using

\fBfetchmail\fP in daemon mode or with scripts.

.SS Using netrc files

.PP

If you do not specify a password, and \fBfetchmail\fP cannot extract one

from your \fI~/.fetchmailrc\fP file, it will look for a \fI~/.netrc\fP

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.  Fetchmail first looks for a match on poll name; if it finds none,

it checks for a match on via name.  See the

.BR ftp (1)

man page for details of the syntax of the \fI~/.netrc\fP

file.  To show a practical example, a .netrc might look like

this:

.IP

.nf

machine hermes.example.org

login joe

password topsecret

.fi

.PP

You can repeat this block with different user information if you need to

provide more than one password.

.PP

This feature may allow you to avoid duplicating password

information in more than one file.

.PP

On mailservers that do not provide ordinary user accounts, your user-id and

password are usually assigned by the server administrator when you apply for

a mailbox on the server.  Contact your server administrator if you don't know

the correct user-id and password for your mailbox account.

.SH POP3 VARIANTS

.PP

Early versions of POP3 (RFC1081, RFC1225) supported a crude form of

independent authentication using the \fI.rhosts\fP file on the

mailserver side.  Under this RPOP variant, a fixed per-user ID

equivalent to a password was sent in clear over a link to a reserved

port, with the command RPOP rather than PASS to alert the server that it

should do special checking.  RPOP is supported by \fBfetchmail\fP

(you can specify 'protocol RPOP' to have the program send 'RPOP'

rather than 'PASS') but its use is strongly discouraged, and support

will be removed from a future fetchmail version.  This

facility was vulnerable to spoofing and was withdrawn in RFC1460.

.PP

RFC1460 introduced APOP authentication.  In this variant of POP3,

you register an APOP password on your server host (on some servers, the

program to do this is called \fBpopauth\fP(8)).  You put the same

password in your \fI~/.fetchmailrc\fP file.  Each time \fBfetchmail\fP

logs in, it sends an MD5 hash of your password and the server greeting

time to the server, which can verify it by checking its authorization

database.

\fBNote that APOP is no longer considered resistant against

man-in-the-middle attacks.\fP

.SS RETR or TOP

\fBfetchmail\fP makes some efforts to make the server believe messages

had not been retrieved, by using the TOP command with a large number of

lines when possible.  TOP is a command that retrieves the full header

and a \fBfetchmail\fP-specified amount of body lines. It is optional and

therefore not implemented by all servers, and some are known to

implement it improperly. On many servers however, the RETR command which

retrieves the full message with header and body, sets the "seen" flag

(for instance, in a web interface), whereas the TOP command does not do

that.

.PP

\fBfetchmail\fP will always use the RETR command if "fetchall" is set.

\fBfetchmail\fP will also use the RETR command if "keep" is set and

"uidl" is unset.  Finally, \fBfetchmail\fP will use the RETR command on

Maillennium POP3/PROXY servers (used by Comcast) to avoid a deliberate

TOP misinterpretation in this server that causes message corruption.

.PP

In all other cases, \fBfetchmail\fP will use the TOP command. This

implies that in "keep" setups, "uidl" must be set if "TOP" is desired.

.PP

\fBNote\fP that this description is true for the current version of

fetchmail, but the behavior may change in future versions. In

particular, fetchmail may prefer the RETR command because the TOP

command causes much grief on some servers and is only optional.

.SH ALTERNATE AUTHENTICATION FORMS

.PP

If your \fBfetchmail\fP was built with Kerberos support and you specify

Kerberos authentication (either with \-\-auth or the \fI.fetchmailrc\fP

option \fBauthenticate kerberos_v4\fP) it will try to get a Kerberos

ticket from the mailserver at the start of each query.  Note: if

either the pollname or via name is 'hesiod', fetchmail will try to use

Hesiod to look up the mailserver.

.PP

If you use POP3 or IMAP with GSSAPI authentication, \fBfetchmail\fP will

expect the server to have RFC1731- or RFC1734-conforming 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\fP command or by the \fI.fetchmailrc\fP

option \fBuser\fP.

.PP

If your IMAP daemon returns the PREAUTH response in its greeting line,

fetchmail will notice this and skip the normal authentication step.

This can be useful, e.g. if you start imapd explicitly using ssh.

In this case you can declare the authentication value 'ssh' on that

site entry to stop \fI.fetchmail\fP from asking you for a password

when it starts up.

.PP

If you use client authentication with \fITLS1\fP and your IMAP daemon

returns the \fIAUTH=EXTERNAL\fP response, fetchmail will notice this

and will use the authentication shortcut and will not send the

passphrase. In this case you can declare the authentication value 'external'

 on that site to stop \fBfetchmail\fP from asking you for a password

when it starts up.

.PP

If you are using POP3, and the server issues a one-time-password

challenge conforming to RFC1938, \fBfetchmail\fP 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 is supported. If you

compile in the support, \fBfetchmail\fP 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

If you are using IMAP, Microsoft's NTLM authentication (used by Microsoft

Exchange) is supported. If you compile in the support, \fBfetchmail\fP

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. Specify a user option value that looks like

\&'user@domain': the part to the left of the @ will be passed as the

username and the part to the right as the NTLM domain.

.SS Secure Socket Layers (SSL) and Transport Layer Security (TLS)

.PP

Note that fetchmail currently uses the OpenSSL library, which is

severely underdocumented, so failures may occur just because the

programmers are not aware of OpenSSL's requirement of the day.

For instance, since v6.3.16, fetchmail calls

OpenSSL_add_all_algorithms(), which is necessary to support certificates

with SHA256 on OpenSSL 0.9.8 -- this information is deeply hidden in the

documentation and not at all obvious.  Please do not hesitate to report

subtle SSL failures.

.PP

You can access SSL encrypted services by specifying the \-\-ssl option.

You can also do this using the "ssl" user option in the .fetchmailrc

file. With SSL encryption enabled, queries are initiated over a

connection after negotiating an SSL session, and the connection fails if

SSL cannot be negotiated.  Some services, such as POP3 and IMAP, have

different well known ports defined for the SSL encrypted services.  The

encrypted ports will be selected automatically when SSL is enabled and

no explicit port is specified. The \-\-sslproto 'SSL3' option should be

used to select the SSLv3 protocol (default if unset: v2 or v3).  Also,

the \-\-sslcertck command line or sslcertck run control file option

should be used to force strict certificate checking - see below.

.PP

If SSL is not configured, fetchmail will usually opportunistically try to use

STARTTLS. STARTTLS can be enforced by using \-\-sslproto "TLS1". TLS

connections use the same port as the unencrypted version of the

protocol and negotiate TLS via special command. The \-\-sslcertck

command line or sslcertck run control file option should be used to

force strict certificate checking - see below.

.PP

.B \-\-sslcertck is recommended:

When connecting to an SSL or TLS encrypted server, the

server presents a certificate to the client for validation.  The

certificate is checked to verify that the common name in the certificate

matches the name of the server being contacted and that the effective

and expiration dates in the certificate indicate that it is currently

valid.  If any of these checks fail, a warning message is printed, but

the connection continues.  The server certificate does not need to be

signed by any specific Certifying Authority and may be a "self-signed"

certificate. If the \-\-sslcertck command line option or sslcertck run

control file option is used, fetchmail will instead abort if any of

these checks fail, because it must assume that there is a

man-in-the-middle attack in this scenario, hence fetchmail must not

expose cleartext passwords. Use of the sslcertck or \-\-sslcertck option

is therefore advised.

.PP

Some SSL encrypted servers may request a client side certificate.  A client

side public SSL certificate and private SSL key may be specified.  If

requested by the server, the client certificate is sent to the server for

validation.  Some servers may require a valid client certificate and may

refuse connections if a certificate is not provided or if the certificate

is not valid.  Some servers may require client side certificates be signed

by a recognized Certifying Authority.  The format for the key files and

the certificate files is that required by the underlying SSL libraries

(OpenSSL in the general case).

.PP

A word of care about the use of SSL: While above mentioned

setup with self-signed server certificates retrieved over the wires

can protect you from a passive eavesdropper, it doesn't help against an

active attacker. It's clearly an improvement over sending the

passwords in clear, but you should be aware that a man-in-the-middle

attack is trivially possible (in particular with tools such as

.URL "http://monkey.org/~dugsong/dsniff/" "dsniff" ,

).  Use of strict certificate checking with a certification authority

recognized by server and client, or perhaps of an SSH tunnel (see below

for some examples) is preferable if you care seriously about the

security of your mailbox and passwords.

.SS ESMTP AUTH

.PP

\fBfetchmail\fP also supports authentication to the ESMTP server on the

client side according to RFC 2554.  You can specify a name/password pair

to be used with the keywords 'esmtpname' and 'esmtppassword'; the former

defaults to the username of the calling user.

.SH DAEMON MODE

.SS Introducing the daemon mode

In daemon mode, \fBfetchmail\fP puts itself into the background and runs

forever, querying each specified host and then sleeping for a given

polling interval.

.SS Starting the daemon mode

There are several ways to make fetchmail work in daemon mode. On the

command line, \fB\-\-daemon\ <interval>\fP or \fB\-d\ <interval>\fP

option runs \fBfetchmail\fP in daemon mode.  You must specify a numeric

argument which is a polling interval (time to wait after completing a 

whole poll cycle with the last server and before starting the next poll 

cycle with the first server) in seconds.

.PP

Example: simply invoking

.IP

fetchmail \-d 900

.PP

will, therefore, poll all the hosts described in your \fI~/.fetchmailrc\fP

file (except those explicitly excluded with the 'skip' verb) a bit less 

often than once every 15 minutes (exactly: 15 minutes + time that the 

poll takes).

.PP

It is also possible to set a polling interval

in your \fI~/.fetchmailrc\fP 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.

.PP

Only one daemon process is permitted per user; in daemon mode,

\fBfetchmail\fP sets up a per-user lockfile to guarantee this.

(You can however cheat and set the FETCHMAILHOME environment variable to

overcome this setting, but in that case, it is your responsibility to

make sure you aren't polling the same server with two processes at the

same time.)

.SS Awakening the background daemon

.PP

Normally, calling fetchmail with a daemon in the background sends a

wake-up signal to the daemon and quits without output. The background

daemon then starts its next poll cycle immediately.  The wake-up signal,

SIGUSR1, can also be sent manually. The wake-up action also clears any

\&'wedged' flags indicating that connections have wedged due to failed

authentication or multiple timeouts.

.SS Terminating the background daemon

.PP

The option

.B \-\-quit

will kill a running daemon process instead of waking it up (if there

is no such process, \fBfetchmail\fP will notify you).

If the \-\-quit option appears last on the command line, \fBfetchmail\fP

will kill the running daemon process and then quit. Otherwise,

\fBfetchmail\fP will first kill a running daemon process and then

continue running with the other options.

.SS Useful options for daemon mode

.PP

The

.B \-L <filename>

or

.B \-\-logfile <filename>

option (keyword: set logfile) is only effective when fetchmail is

detached and in daemon mode. Note that \fBthe logfile must exist

before\fP fetchmail is run, you can use the

.BR touch (1)

command with the filename as its sole argument to create it.

.br

This option allows you to redirect status messages

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. Note that fetchmail

does not detect if the logfile is rotated, the logfile is only opened

once when fetchmail starts. You need to restart fetchmail after rotating

the logfile and before compressing it (if applicable).

.PP

The

.B \-\-syslog

option (keyword: set syslog) allows you to redirect status and error

messages emitted to the

.BR syslog (3)

system daemon if available.

Messages are logged with an id of \fBfetchmail\fP, the facility \fBLOG_MAIL\fP,

and priorities \fBLOG_ERR\fP, \fBLOG_ALERT\fP or \fBLOG_INFO\fP.

This option is intended for logging status and error messages which

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\fP

file are still written to stderr, or to the specified log file.

The

.B \-\-nosyslog

option turns off use of

.BR syslog (3),

assuming it's turned on in the \fI~/.fetchmailrc\fP file.

.PP

The

.B \-N

or

.B \-\-nodetach

option suppresses backgrounding and detachment of the daemon process

from its control terminal.  This is useful for debugging or when

fetchmail runs as the child of a supervisor process such as

.BR init (8)

or Gerrit Pape's

.BR runit (8).

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 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

fetched (and thus marked seen by the mailserver) but not delivered

locally due to some transient error, it will be re-fetched during the

next poll cycle.  (The IMAP logic doesn't delete messages until

they're delivered, so this problem does not arise.)

.PP

If you touch or change the \fI~/.fetchmailrc\fP file while fetchmail is

running in daemon mode, this will be detected at the beginning of the

next poll cycle.  When a changed \fI~/.fetchmailrc\fP is detected,

fetchmail rereads it and restarts from scratch (using exec(2); no state

information is retained in the new instance).  Note that if fetchmail

needs to query for passwords, of that if you break the

\fI~/.fetchmailrc\fP file's syntax, the new instance will softly and

silently vanish away on startup.

.SH ADMINISTRATIVE OPTIONS

.PP

The

.B \-\-postmaster <name>

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. It is also used as destination of undeliverable mail if

the 'bouncemail' global option is off and additionally for spam-blocked

mail if the 'bouncemail' global option is off and the 'spambounce'

global option is on. This option defaults to the user who invoked

\fBfetchmail\fP.

If the invoking user is root, then the default of this option is

the user 'postmaster'.  Setting postmaster to the empty string causes

such mail as described above to be discarded - this however is usually a

bad idea.

See also the description of the 'FETCHMAILUSER' environment variable in

the ENVIRONMENT section below.

.PP

The

.B \-\-nobounce

behaves like the "set no bouncemail" global option, which see.

.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.

.PP

The

.B \-\-showdots

option (keyword: set showdots) forces fetchmail to show progress dots

even if the output goes to a file or fetchmail is not in verbose mode.

Fetchmail shows the dots by default when run in \-\-verbose mode 

\fIand\fP output goes to console. This option is ignored in \-\-silent mode.

.PP

By specifying the

.B \-\-tracepolls

option, you can ask fetchmail to add information to the Received

header on the form "polling {label} account {user}", where {label} is

the account label (from the specified rcfile, normally ~/.fetchmailrc)

and {user} is the username which is used to log on to the mail

server. This header can be used to make filtering email where no

useful header information is available and you want mail from

different accounts sorted into different mailboxes (this could, for

example, occur if you have an account on the same server running a

mailing list, and are subscribed to the list using that account). The

default is not adding any such header.  In

.IR .fetchmailrc ,

this is called 'tracepolls'.

.SH RETRIEVAL FAILURE MODES

The protocols \fBfetchmail\fP 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 side has acknowledged to \fBfetchmail\fP that

the message has been either accepted for delivery or rejected due to a

spam block.

.PP

When forwarding to an MDA, however, there is more possibility

of error.  Some MDAs are 'safe' and reliably return a nonzero status

on any delivery error, even one due to temporary resource limits.

The

.BR maildrop (1)

program is like this; so are most programs designed as mail transport

agents, such as

.BR sendmail (1),

including the sendmail wrapper of Postfix and

.BR exim (1).

These programs give back a reliable positive acknowledgement and

can be used with the mda option with no risk of mail loss.  Unsafe

MDAs, though, may return 0 even on delivery failure.  If this

happens, you will lose mail.

.PP

The normal mode of \fBfetchmail\fP is to try to download only 'new'

messages, leaving untouched (and undeleted) messages you have already

read directly on the server (or fetched with a previous \fIfetchmail

\-\-keep\fP).  But you may find that messages you've already read on the

server are being fetched (and deleted) even when you don't specify

\-\-all.  There are several reasons this can happen.

.PP

One could be that you're using POP2.  The POP2 protocol includes no

representation of 'new' or 'old' state in messages, so \fBfetchmail\fP

must treat all messages as new all the time.  But POP2 is obsolete, so

this is unlikely.

.PP

A potential POP3 problem might be servers that insert messages

in the middle of mailboxes (some VMS implementations of mail are

rumored to do this).  The \fBfetchmail\fP code assumes that new

messages are appended to the end of the mailbox; when this is not true

it may treat some old messages as new and vice versa.  Using UIDL whilst

setting fastuidl 0 might fix this, otherwise, consider switching to IMAP.

.PP

Yet another POP3 problem is that if they can't make tempfiles in the

user's home directory, some POP3 servers will hand back an

undocumented response that causes fetchmail to spuriously report "No

mail".

.PP

The IMAP code uses the presence or absence of the server flag \eSeen

to decide whether or not a message is new.  This isn't the right thing

to do, fetchmail should check the UIDVALIDITY and use UID, but it

doesn't do that yet. Under Unix, it counts on your IMAP server to notice

the BSD-style Status flags set by mail user agents and set the \eSeen

flag from them when appropriate.  All Unix IMAP servers we know of do

this, though it's not specified by the IMAP RFCs.  If you ever trip over

a server that doesn't, the symptom will be that messages you have

already read on your host will look new to the server.  In this

(unlikely) case, only messages you fetched with \fIfetchmail \-\-keep\fP

will be both undeleted and marked old.

.PP

In ETRN and ODMR modes, \fBfetchmail\fP does not actually retrieve messages;

instead, it asks the server's SMTP listener to start a queue flush

to the client via SMTP.  Therefore it sends only undelivered messages.

.SH SPAM FILTERING

Many SMTP listeners allow administrators to set up 'spam filters' 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

Newer versions of

\fBsendmail\fP

return an error code of 571.

.PP

According to RFC2821, the correct thing to return in this situation is

550 "Requested action not taken: mailbox unavailable" (the draft adds

"[E.g., mailbox not found, no access, or command rejected for policy

reasons].").

.PP

Older versions of the

\fBexim\fP

MTA return 501 "Syntax error in parameters or arguments".

.PP

The

\fBpostfix\fP

MTA runs 554 as an antispam response.

.PP

\fBZmailer\fP

may reject code with a 500 response (followed by an enhanced status

code that contains more information).

.PP

Return codes which

\fBfetchmail\fP

treats as antispam responses and discards

the message can be set with the 'antispam' option.  This is one of the

\fIonly\fP

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

\fBfetchmail\fP

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

By default, the list of antispam responses is empty.

.PP

If the \fIspambounce\fP global option is on, mail that is spam-blocked

triggers an RFC1892/RFC1894 bounce message informing the originator that

we do not accept mail from it. See also BUGS.

.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.  Don't even try to send

bounce-mail to the originator.

.PP

Other errors trigger bounce mail back to the originator. See also BUGS.

.SH THE RUN CONTROL FILE

The preferred way to set up fetchmail is to write a

\&\fI.fetchmailrc\fP file in your home directory (you may do this

directly, with a text editor, or indirectly via \fBfetchmailconf\fP).