1 .\" For license terms, see the file COPYING in this directory.
4 fetchmail \- fetch mail from a POP or IMAP server
7 \fBfetchmail\fR [\fIoptions\fR] [\fImailserver...\fR]
11 is a mail-retrieval and forwarding utility; it fetches
12 mail from remote mailservers and forwards it to your local (client)
13 machine's delivery system. You can then handle the retrieved mail
14 using normal mail user agents such as \fIelm\fR(1) or \fIMail\fR(1).
15 The \fBfetchmail\fR utility can be run in a daemon mode to repeatedly
16 poll one or more systems at a specified interval.
20 program can gather mail from servers supporting any of the common
21 mail-retrieval protocols: POP2, POP3, IMAP2bis, and IMAP4. It can
22 also use the ESMTP ETRN extension. (The RFCs describing all these
23 protocols are listed below.)
27 is primarily intended to be used over on-demand TCP/IP links (such as
28 SLIP or PPP connections), it may also be useful as a message transfer
29 agent for sites which refuse for security reasons to permit
30 (sender-initiated) SMTP transactions with sendmail.
32 As each message is retrieved \fIfetchmail\fR normally delivers it via SMTP to
33 port 25 on the machine it is running on (localhost), just as though it
34 were being passed in over a normal TCP/IP link. The mail will then be
35 delivered locally via your system's MDA (Mail Delivery Agent, usually
36 \fIsendmail\fR(8) but your system may use a different one such
37 as \fIsmail\fR, \fImmdf\fR, or \fIqmail\fR). All the delivery-control
38 mechanisms (such as \fI.forward\fR files) normally available through
39 your system MDA will therefore work.
43 is controlled by command-line options and a run control file,
44 \fI~/.fetchmailrc\fR, the syntax of which we describe below. Command-line
49 Each server name that you specify following the options on the
50 command line will be queried. If you don't specify any servers
51 on the command line, each server in your
55 To facilitate the use of
57 In scripts, pipelines, etc., it returns an appropriate exit code upon
58 termination -- see EXIT CODES below.
61 The following options modify the behavior of \fIfetchmail\fR. It is
62 seldom necessary to specify any of these once you have a
63 working \fI.fetchmailrc\fR file set up.
65 Some special options are not covered here, but are documented insttead
66 in sections on AUTHENTICATION and DAEMON MODE which follows.
70 Displays the version information for your copy of
72 No mail fetch is performed.
73 Instead, for each server specified, all option information
74 that would be computed if
76 were connecting to that server is displayed. Any non-printables in
77 passwords or other string names are shown as backslashed C-like
78 escape sequences. This option is useful for verifying that your
79 options are set the way you want them.
82 Return a status code to indicate whether there is mail waiting,
83 without actually fetching or deleting mail (see EXIT CODES below).
84 This option doesn't play well with queries to multiple sites, doen't
85 work with ETRN, and is ignored in daemon mode. It's also prone to
86 false positives if you leave read but undeleted mail in your server
90 Silent mode. Suppresses all progress/status messages that are normally
91 echoed to standard error during a fetch. The --verbose option
95 Verbose mode. All control messages passed between
97 and the mailserver are echoed to stderr. Overrides --silent.
100 Retrieve both old (seen) and new messages from the mailserver. The
101 default is to fetch only messages the server has not marked seen.
102 Note that POP2 retrieval behaves as though --all is always on (see
103 RETRIEVAL FAILURE MODES below) and this option does not work with ETRN.
106 Keep retrieved messages on the remote mailserver. Normally, messages
107 are deleted from the folder on the mailserver after they have been retrieved.
110 option causes retrieved messages to remain in your folder on the
111 mailserver. This option does not work with ETRN.
114 Delete retrieved messages from the remote mailserver. This
115 option forces retrieved mail to be deleted. It may be useful if
116 you have specified a default of \fBnokill\fR in your
117 \fI.fetchmailrc\fR. This option is forced on with ETRN.
120 POP3/IMAP only. Delete old (previously retrieved) messages from the mailserver
121 before retrieving new messages. This option does not work with ETRN.
122 .SS Protocol and Query Options
124 .B \-p, \--protocol proto
125 Specify the protocol to used when communicating with the remote
126 mailserver. If no protocol is specified,
128 will try each of the supported protocols in turn, terminating after
129 any successful attempt.
131 may be one of the following:
134 Post Office Protocol 2
136 Post Office Protocol 3
138 Use POP3 with MD5 authentication.
140 Use POP3 with RPOP authentication.
142 Use POP3 with Kerberos authentication on port 1109.
144 IMAP2bis, IMAP4, or IMAP4rev1 (\fIfetchmail\fR autodetects their capabilities).
146 Use the ESMTP ETRN option.
148 All these alternatives work in basically the same way (communicating
149 with standard server daemons to fetch mail already delivered to a
150 mailbox on the server) except ETRN. The ETRN mode allows you to ask a
151 compliant ESMTP server (such as BSD sendmail at release 8.8.0 or
152 higher) to immediately open an sender-SMTP connection to your your
153 client machine and begin forwarding any items addressed to your client
154 machine in the server's queue of undelivered mail.
157 The option permits you to specify a TCP/IP port to connect on.
158 This option will seldom be necessary as all the supported protocols have
159 well-established default port numbers.
161 .B \-r folder, --remote folder
162 Causes a specified non-default mail folder on the mailserver to be retrieved.
163 The syntax of the folder name is server dependent, as is the default
164 behavior when no folder is specified. This option is not available
166 .SS Delivery Control Options
168 .B \-S host, --smtphost host
169 Specify a hunt list of hosts to forward mail to.
170 In ETRN mode, set the host that the mailserver is asked to ship mail to.
171 Hosts are tried in list order; the first one that is up becomes the
172 forwarding or ETRN target for the current run.
175 You can force mail to be passed to an MDA directly (rather than
176 forwarded to port 25) with the -mda or -m option. If \fIfetchmail\fR
177 is running as root, it sets its userid to that of the target user
178 while delivering mail through an MDA. Some possible MDAs are
179 "/usr/sbin/sendmail -oem", "/usr/lib/sendmail -oem",
180 "/usr/bin/formail", and "/usr/bin/deliver". Local delivery addresses
181 will be inserted into the MDA command wherever you place a %s. Do
182 \fInot\fR use an MDA like
183 "sendmail -oem -t" that dispatches on the contents of To/Cc/Bcc, it
184 will create mail loops and bring the just wrath of many postmasters
186 .SS Resource Limit Control Options
189 Takes a maximum octet size argument. Messages larger than this size
190 will not be fetched, not be marked seen, and will be left on the
191 server (in foreground sessions, the progress messages will note that
192 they are "oversized"). The --all option overrides this one. This
193 option is intended for those needing to strictly control fetch time
194 in interactive mode. It may not be used with daemon mode,
195 as users would never receive a notification that messages were waiting.
196 This option does not work with ETRN.
199 Specify the maximum number of messages that will be shipped to an SMTP
200 listener before the connection is deliberately torn down and rebuilt
201 (defaults to 0, meaning no limit). While \fBsendmail\fR(8) normally
202 initiates delivery of a message immediately after receiving the
203 message terminator, some SMTP listeners are not so prompt. MTAs like
204 \fIqmail\fR(8) and \fIsmail\fR(8) will wait till the delivery socket is
205 shut down to deliver. This may produce annoying delays when
207 is processing very large batches. Setting the batch limit to some
208 nonzero size will prevent these delays.
209 This option does not work with ETRN.
212 Limit the number of messages accepted from a given server in a single
213 poll. By default there is no limit.
214 .SS Authentication Options
216 .B \-u name, --username name
217 Specifies the user identification to be used when logging in to the mailserver.
218 The appropriate user identification is both server and user-dependent.
219 The default is your login name on the client machine that is running
221 See USER AUTHENTICATION below for a complete description.
223 .B \-I specification, --interface specification
224 Require that a specific interface device be up and have a specific local
225 IP address (or range) before polling. Frequently
227 is used over a transient point-to-point TCP/IP link established directly
228 to a mailserver via SLIP or PPP. That is a relatively secure channel.
229 But when other TCP/IP routes to the mailserver exist (e.g. when the link
230 is connected to an alternate ISP), your username and password may be
231 vulnerable to snooping (especially when daemon mode automatically polls
232 for mail, shipping a clear password over the net at predictable
233 intervals). The --interface option may be used to prevent this. When
234 the specified link is not up or is not connected to a matching IP
235 address, polling will be skipped. The format is:
237 interface/iii.iii.iii.iii/mmm.mmm.mmm.mmm
239 The field before the first slash is the interface name (i.e. sl0, ppp0
240 etc.). The field before the second slash is the acceptable IP address.
241 The field after the second slash is a mask which specifies a range of
242 IP addresses to accept. If no mask is present 255.255.255.255 is
243 assumed (i.e. an exact match). This option is currently only supported
246 .B \-M interface, --monitor interface
247 Daemon mode can cause transient links which are automatically taken down
248 after a period of inactivity (e.g. PPP links) to remain up
249 indefinitely. This option identifies a system TCP/IP interface to be
250 monitored for activity. After each poll interval, if the link is up but
251 no other activity has occurred on the link, then the poll will be
252 skipped. This option is currently only supported under Linux.
255 This option permits you to specify an authentication type (see USER
256 AUTHENTICATION below for details). The possible values are
257 \&`\fBpassword\fR' and `\fBkerberos\fR'. This option is provided
258 primarily for developers; choosing KPOP protocol automatically selects
259 Kerberos authentication, and all other alternatives use ordinary
260 password authentication (though APOP uses a generated one-time
261 key as the password).
262 This option does not work with ETRN.
263 .SS Miscellaneous Options
265 .B \-f pathname, --fetchmailrc pathname
266 Specify a non-default name for the
270 .B \-i pathname, --idfile pathname
271 Specify an alternate name for the .fetchids file used to save POP3
277 edits RFC-822 address headers (To, From, Cc, Bcc, and Reply-To) in
278 fetched mail so that any mail IDs local to the server are expanded to
279 full addresses (@ and the mailserver hostname are appended). This enables
280 replies on the client to get addressed correctly (otherwise your
281 mailer might think they should be addressed to local users on the
282 client machine!). This option disables the rewrite. (This option is
283 provided to pacify people who are paranoid about having an MTA edit
284 mail headers and want to know they can prevent it, but it is generally
285 not a good idea to actually turn off rewrite.)
286 When using ETRN, the rewrite option is ineffective.
289 This option changes the header
291 assumes will carry a copy of the mail's envelope address. Normally
292 this is `X-Envelope-To' but as this header is not standard, practice
293 varies. See the discussion of multidrop address handling below.
295 .SH USER AUTHENTICATION
296 Every mode except ETRN requires authentication of the client.
297 Normal user authentication in
299 is very much like the authentication mechanism of
301 The correct user-id and password depend upon the underlying security
302 system at the mailserver.
304 If the mailserver is a Unix machine on which you have an ordinary user
305 account, your regular login name and password are used with
307 If you use the same login name on both the server and the client machines,
308 you needn't worry about specifying a user-id with the
311 the default behavior is to use your login name on the client machine as the
312 user-id on the server machine. If you use a different login name
313 on the server machine, specify that login name with the
315 option. e.g. if your login name is 'jsmith' on a machine named 'mailgrunt',
320 fetchmail -u jsmith mailgrunt
322 The default behavior of
324 is to prompt you for your mailserver password before the connection is
325 established. This is the safest way to use
327 and ensures that your password will not be compromised. You may also specify
328 your password in your
330 file. This is convenient when using
332 in daemon mode or with scripts.
334 If you do not specify a password, and
336 cannot extract one from your
338 file, it will look for a
340 file in your home directory before requesting one interactively; if an
341 entry matching the mailserver is found in that file, the password will
344 man page for details of the syntax of the
346 file. (This feature may allow you to avoid duplicating password
347 information in more than one file.)
349 On mailservers that do not provide ordinary user accounts, your user-id and
350 password are usually assigned by the server administrator when you apply for
351 a mailbox on the server. Contact your server administrator if you don't know
352 the correct user-id and password for your mailbox account.
354 Early versions of POP3 (RFC1081, RFC1225) supported a crude form of
355 independent authentication using the
357 file on the mailserver side. Under this RPOP variant, a fixed
358 per-user ID equivalent to a password was sent in clear over a link to
359 a reserved port, with the command RPOP rather than PASS to alert the
360 server that it should do special checking. RPOP is supported
363 (you can specify `protocol RPOP' to have the program send `RPOP'
364 rather than `PASS') but its use is strongly discouraged. This
365 facility was vulnerable to spoofing and was withdrawn in RFC1460.
367 RFC1460 introduced APOP authentication. In this variant of POP3,
368 you register an APOP password on your server host (the program
369 to do this with on the server is probably called \fIpopauth\fR(8)). You
370 put the same password in your
374 logs in, it sends a cryptographically secure hash of your password and
375 the server greeting time to the server, which can verify it by
376 checking its authorization database.
378 If your \fIfetchmail\fR was built with Kerberos support and you specify
379 Kerberos authentication (either with --auth or the \fI.fetchmailrc\fR
380 option \fBauthenticate kerberos\fR) it will try to get a Kerberos
381 ticket from the mailserver at the start of each query.
390 in daemon mode. You must specify a numeric argument which is a
391 polling interval in seconds.
395 puts itself in background and runs forever, querying each specified
396 host and then sleeping for the given polling interval.
402 will, therefore, poll all the hosts described in your
404 file (except those explicitly excluded with the `skip' verb) once
405 every fifteen minutes.
407 Only one daemon process is permitted per user; in daemon mode,
409 makes a per-user lockfile to guarantee this. The option
411 will kill a running daemon process. Otherwise, calling fetchmail with
412 a daemon in the background sends a wakeup signal to the daemon,
413 forcing it to poll mailservers immediately.
419 option allows you to set a server-nonresponse timeout in seconds. If
420 a mailserver does not send a greeting message or respond to commands for
421 the given number of seconds, \fIfetchmail\fR will hang up on it.
422 Without such a timeout \fIfetchmail\fR might hang up indefinitely
423 trying to fetch mail from a down host. This would be particularly
424 annoying for a \fIfetchmail\fR running in background.
430 option allows you to redirect status messages emitted while in daemon
431 mode into a specified logfile (follow the option with the logfile name).
432 The logfile is opened for append, so previous messages aren't deleted.
433 This is primarily useful for debugging configurations.
437 option allows you to redirect status and error messages emitted while in
440 system daemon if available.
441 Messages are logged with an id of \fBfetchmail\fR, the facility \fBLOG_MAIL\fR,
442 and priorities \fBLOG_ERR\fR, \fBLOG_ALERT\fR or \fBLOG_INFO\fR.
443 This option is intended for logging status and error messages which
444 indicate the status of the daemon and the results while fetching mail
446 Error messages for command line options and parsing the \fI.fetchmailrc\fR
447 file are still written to stderr, or the specified log file if the
453 The \fI/etc/syslog.conf\fR file might contain the following to log
454 all messages from \fIfetchmail\fR to a single file:
459 *.* /var/log/fetchmail
464 or --nodetach option suppresses detachment of the daemon process
465 from its control terminal. This is primarily useful for debugging.
467 Note that while running in daemon mode polling a POP server, transient
468 errors (such as DNS failures or sendmail delivery refusals) may force
469 the fetchall option on for the duration of the next polling cycle.
470 This is a robustness feature. It means that if a message is fetched
471 (and thus marked seen by the mailserver) but not delivered locally due
472 to some transient error, it will be re-fetched during the next poll
473 cycle. (The IMAP logic doesn't delete messages until they're
474 delivered, so this problem does not arise.)
476 .SH RETRIEVAL FAILURE MODES
477 The protocols \fIfetchmail\fR uses to talk to mailservers are next to
478 bulletproof. In normal operation forwarding to port 25, no message is
479 ever deleted (or even marked for deletion) on the host until the SMTP
480 listener on the client has acknowledged to \fIfetchmail\fR that the
481 message has been accepted for delivery. When forwarding to an MDA,
482 however, there is more possibility of error (because there's no way
483 for fetchmail to get a reliable positive acknowledgement from the MDA).
485 The normal mode of \fIfetchmail\fR is to try to download only `new'
486 messages, leaving untouched (and undeleted) messages you have already
487 read directly on the server (or fetched with a previous \fIfetchmail
488 --keep\fR). But you may find that messages you've already read on the
489 server are being fetched (and deleted) even when you don't specify
490 --all. There are several reasons this can happen.
492 One could be that you're using POP2. The POP2 protocol includes no
493 representation of `new' or `old' state in messages, so \fIfetchmail\fR
494 must treat all messages as new all the time. But POP2 is obsolete, so
497 Under POP3, blame RFC1725. That version of the POP3 protocol
498 specification removed the LAST command, and some POP servers follow it
499 (you can verify this by invoking \fIfetchmail -v\fR to the mailserver
500 and watching the response to LAST early in the query). The
501 \fIfetchmail\fR code tries to compensate by using POP3's UID feature,
502 storing the identifiers of messages seen in each session until the
503 next session, in the \fI.fetchids\fR file. But this doesn't track
504 messages seen with other clients, or read directly with a mailer on
505 the host but not deleted afterward. A better solution would be to
508 Another potential POP3 problem might be servers that insert messages
509 in the middle of mailboxes (some VMS implementations of mail are
510 rumored to do this). The \fIfetchmail\fR code assumes that new
511 messages are appended to the end of the mailbox; when this is not true
512 it may treat some old messages as new and vice versa. The only
513 real fix for this problem is to switch to IMAP.
515 The IMAP code uses the presence or absence of the server flag \eSeen
516 to decide whether or not a message is new. Under Unix, it counts on
517 your IMAP server to notice the BSD-style Status flags set by mail user
518 agents and set the \eSeen flag from them when appropriate. All Unix
519 IMAP servers we know of do this, though it's not specified by the IMAP
520 RFCs. If you ever trip over a server that doesn't, the symptom will
521 be that messages you have already read on your host will look new to
522 the server. In this (unlikely) case, only messages you fetched with
523 \fIfetchmail --keep\fR will be both undeleted and marked old.
525 In ETRN mode, \fIfetchmail\fR does not actually retrieve messages;
526 instead, it asks the server's SMTP listener to start a queue flush
527 to the client via SMTP. Therefore it sends only undelivered messages.
532 allow administrators to set up `spam filters' that block unsolicited email
533 from specified domains. A MAIL FROM line that triggers this feature
534 will elicit an SMTP response with an error code of 571. The
536 code recognizes this error and discards the message. This is the
538 circumstance under which fetchmail ever discards mail.
540 .SH THE RUN CONTROL FILE
541 The preferred way to set up fetchmail (and the only way if you want to
542 avoid specifying passwords each time it runs) is to write a
543 \&\fI.fetchmailrc\fR file in your home directory. When there is a
544 conflict between the command-line arguments and the arguments in this
545 file, the command-line arguments take precedence.
547 To protect the security of your passwords, your \fI~/.fetchmailrc\fR
548 may not have more than 600 (u=rw,g=,o=) permissions;
550 will complain and exit otherwise.
552 You may read the \fI.fetchmailrc\fR file as a list of commands to
555 is called with no arguments.
557 Comments begin with a '#' and extend through the end of the line.
558 Otherwise the file consists of a series of server entries or global
559 option statements in a free-format, token-oriented syntax.
561 There are four kinds of tokens: grammar keywords, numbers
562 (i.e. decimal digit sequences), unquoted strings, and quoted strings.
563 A quoted string is bounded by double quotes and may contain
564 whitespace (and quoted digits are treated as a string). An unquoted
565 string is any whitespace-delimited token that is neither numeric, string
566 quoted nor contains the special characters `,', `;', `:', or `='.
568 Any amount of whitespace separates tokens in server entries, but is
569 otherwise ignored. You may use standard C-style escapes (\en, \et,
570 \eb, octal, and hex) to embed non-printable characters or string
571 delimiters in strings.
573 Each server entry consists of one of the keywords `poll' or `skip',
574 followed by a server name, followed by server options, followed by any
575 number of user descriptions.
577 The `poll' verb tells fetchmail to query this host when it is run with
578 no arguments. The `skip' verb tells
580 not to poll this host unless it is explicitly named on the command
581 line. (The `skip' verb allows you to experiment with test entries
582 safely, or easily disable entries for hosts that are temporarily down.)
584 Legal server options are:
588 authenticate (or auth)
597 Legal user options are
603 remotefolder (or remote)
625 All options correspond to the obvious command-line arguments except
626 the following: `aka', `is', `to', `dns'/`no dns', `password',
627 \&`preconnect', `localdomains', `stripcr'/`no stripcr' and
630 The `is' or `to' keywords associate the following local (client)
631 name(s) (or server-name to client-name mappings separated by =) with
632 the mailserver user name in the entry. If an is/to list has `*' as
633 its last name, unrecognized names are simply passed through.
635 A single local name can be used to support redirecting your mail when
636 your username on the client machine is different from your name on the
637 mailserver. When there is only a single local name, mail is forwarded
638 to that local username regardless of the message's Received, To, Cc,
639 and Bcc headers. In this case
641 never does DNS lookups.
643 When there is more than one local name (or name mapping) the
644 \fIfetchmail\fR code does look at the Received, To, Cc, and Bcc
645 headers of retrieved mail (this is `multidrop mode'). It looks for
646 addresses with hostname parts that match your `aka' or `localdomains'
647 options, and usually also for hostname parts which DNS tells it are
648 aliases of the mailserver. See the discussion of `dns',
649 `localdomains', and `aka' for details on how matching addresses are
650 handled. If \fIfetchmail\fR cannot match any mailserver usernames or
651 localdomain addresses, the default recipient is the calling user.
653 The `dns' option (normally on) controls the way addresses from
654 multidrop mailboxes are checked. On, it enables logic to check each
655 host address that doesn't match an `aka' or `localdomains' declaration
656 by looking it up with DNS. When a mailserver username is recognized
657 attached to a matching hostname part, its local mapping is added to
658 the list of local recipients.
660 The `aka' option is for use with multidrop mailboxes. It allows you
661 to pre-declare a list of DNS aliases for a server. This is an
662 optimization hack that allows you to trade space for speed. When
664 while processing a multidrop mailbox, grovels through message headers
665 looking for names of the mailserver, pre-declaring common ones can
666 save it from having to do DNS lookups.
668 The `localdomains' option allows you to declare a list of domains
669 which fetchmail should consider local. When fetchmail is parsing
670 address lines in multidrop modes, and a trailing segment of a host
671 name matches a declared local doman, that address is passed through
672 to the listener or MDA unaltered (local-name mappings are \fInot\fR
675 If you are using `localdomains', you may also need to specify \&`no
676 envelope', which disables \fIfetchmail\fR's normal attempt to deduce
677 an envelope address from the Received line or X-Envelope-To header or
678 whatever header has been previously set by `envelope'. If you set `no
679 envelope' in the defaults entry it is possible to undo that in
680 individual entries by using `envelope <string>'.
682 The \fBpassword\fR option requires a string argument, which is the password
683 to be used with the entry's server.
685 The `preconnect' keyword allows you to specify a shell command to be
686 executed just before each time
688 establishes a mailserver connection. This may be useful if you are
689 attempting to set up secure POP connections with the aid of
692 The `stripcr' option controls whether carriage returns are stripped
693 out of retrieved mail before it is forwarded. It is normally not
694 necessary to set this, because it defaults to `on' (CR stripping
695 enabled) when there is an MDA declared but `off' (CR stripping
696 disabled) when forwarding is via SMTP.
698 Legal protocol identifiers are
708 Legal authentication types are `password' or `kerberos'. The former
709 specifies authentication by normal transmission of a password (the
710 password may be plaintext or subject to protocol-specific encryption
711 as in APOP); the second tells \fIfetchmail\fR to try to get a Kerberos
712 ticket at the start of each query instead, and send an arbitrary
713 string as the password.
715 Specifying `kpop' sets POP3 protocol over port 1109 with Kerberos
716 authentication. These defaults may be overridden by later options.
718 You can use the noise keywords `and', `with',
719 `has', `wants', and `options' anywhere in an entry to make
720 it resemble English. They're ignored, but but can make entries much
721 easier to read at a glance. The punctuation characters ':', ';' and
722 ',' are also ignored.
724 The words `here' and `there' have useful English-like
725 significance. Normally `user eric is esr' would mean that
726 mail for the remote user `eric' is to be delivered to `esr',
727 but you can make this clearer by saying `user eric there is esr here',
728 or reverse it by saying `user esr here is eric there'
730 For backward compatibility, the word `server' is a synonym for `poll'.
732 There is currently just one global option statement; `set logfile = '
733 followed by a string sets the same global specified by --logfile. A
734 command-line --logfile option will override this.
739 poll SERVERNAME protocol PROTOCOL username NAME password PASSWORD
745 poll pop.provider.net protocol pop3 username jsmith password secret1
748 Or, using some abbreviations:
751 poll pop.provider.net proto pop3 user jsmith password secret1
754 Multiple servers may be listed:
757 poll pop.provider.net proto pop3 user jsmith pass secret1
758 poll other.provider.net proto pop2 user John.Smith pass My^Hat
761 Here's a version of those two with more whitespace and some noise words:
764 poll pop.provider.net proto pop3
765 user jsmith, with password secret1, is jsmith here;
766 poll other.provider.net proto pop2:
767 user John.Smith, with password My^Hat, is John.Smith here;
770 This version is much easier to read and doesn't cost significantly
771 more (parsing is done only once, at startup time).
774 If you need to include whitespace in a parameter string, enclose the
775 string in double quotes. Thus:
778 poll mail.provider.net with proto pop3:
779 user jsmith there has password "u can't krak this"
780 is jws here and wants mda "/bin/mail"
783 You may have an initial server description headed by the keyword
784 `defaults' instead of `poll' followed by a name. Such a record
785 is interpreted as defaults for all queries to use. It may be overwritten
786 by individual server descriptions. So, you could write:
791 poll pop.provider.net
793 poll mail.provider.net
794 user jjsmith there has password secret2
797 It's possible to specify more than one user per server (this is only
798 likely to be useful when running fetchmail in daemon mode as root).
799 The `user' keyword leads off a user description, and every user
800 description except optionally the first one must include it. If the
801 first description lacks the `user' keyword, the name of the invoking
802 user is used (in a future version, the option to omit the `user'
803 keyword may be removed). Here's a contrived example:
806 poll pop.provider.net proto pop3 port 3111
808 user jsmith with pass secret1 is smith here
809 user jones with pass secret2 is jjones here
812 This says that the user invoking \fIfetchmail\fR has the same username
813 on pop.provider.net, and password `gumshoe' there. It also associates
814 the local username `smith' with the pop.provider.net username `jsmith'
815 and the local username `jjones' with the pop.provider.net username
818 This example is contrived because, in practice, you are very unlikely
819 to be specifying multiple users per server unless running it as root
820 (thus the `pass gumshoe' would try to fetch root's mail on
821 pop-provider.net, which is probably not what you want). In any case,
822 we strongly recommend always having an explicit \&`user' clause when
823 specifying multiple users per mailserver. In a future version, the
824 option not to explicitly declare the username may be removed.
826 Here's what a simple retrieval configuration for a multi-drop mailbox
830 poll pop.provider.net:
831 user maildrop with pass secret1 to golux hurkle=happy snark here
834 This says that the mailbox of account `maildrop' on the server is a
835 multi-drop box, and that messages in it should be parsed for the
836 server user names `golux', `hurkle', and `snark'. It further
837 specifies that `golux' and `snark' have the same name on the
838 client as on the server, but mail for server user `hurkle' should be
839 delivered to client user `happy'.
841 Here's an example of another kind of multidrop connection:
844 poll pop.provider.net localdomains loonytoons.org:
845 user maildrop with pass secret1 to esr * here
848 This also says that the mailbox of account `maildrop' on the server is
849 a multi-drop box. It tells fetchmail that any address in the
850 loonytoons.org domain (including subdomain addresses like
851 `joe@daffy.loonytoons.org') should be passed through to the local SMTP
852 listener without modification. Be careful of mail loops if you do this!
854 .SH THE USE AND ABUSE OF MULTIDROP MAILBOXES
855 Use the multiple-local-recipients feature with caution -- it can bite.
856 Also note that all multidrop features are ineffective in ETRN mode.
858 .SS Header vs. Envelope addresses
859 The fundamental problem is that by having your mailserver toss several
860 peoples' mail in a box, you may have thrown away potentially vital
861 information about who each piece of mail was actually addressed to
862 (the `envelope address', as opposed to the addresses in the RFC822
863 To/Cc/Bcc headers). This `envelope address' is the address you need
864 in order to reroute mail properly.
868 can deduce the envelope address. If the mailserver MTA is
870 and the item of mail had just one recipient, the MTA will have written
871 a `for' clause that gives the envelope addressee into its Received
872 header. But this doesn't work reliably for other MTAs, nor if there is more
875 Alternatively, some SMTP listeners and/or mail servers insert a header
876 in each message containing a copy of the envelope addresses. This
877 header (when it exists) is often `X-Envelope-To'. Fetchmail's
878 assumption about this can be changed with the -E or `envelope' option.
880 Sometimes, unfortunately, neither of these methods works. When they
881 both fail, fetchmail must fall back on the contents of To/Cc/Bcc
882 headers to try to determine recipient addressees -- and these are not
883 reliable. In particular, mailing-list software often ships mail with
884 the list broadcast address in the To header.
888 cannot deduce a recipient address that is local, and the intended
889 recipient address was anyone other than fetchmail's invoking user,
890 mail will get lost. This is what makes the multidrop feature risky.
892 .SS Good Ways To Use Multidrop Mailboxes
893 Multiple local names can be used to administer a mailing list from the
894 client side of a \fIfetchmail\fR collection. Suppose your name is
895 \&`esr', and you want to both pick up your own mail and maintain a mailing
896 list called (say) "fetchmail-friends", and you want to keep the alias
897 list on your client machine.
899 On your server, you can alias \&`fetchmail-friends' to `esr'; then, in
900 your \fI.fetchmailrc\fR, declare \&`to esr fetchmail-friends here'.
901 Then, when mail including `fetchmail-friends' as a local address
902 gets fetched, the list name will be appended to the list of
903 recipients your SMTP listener sees. Therefore it will undergo alias
904 expansion locally. Be sure to include `esr' in the local alias
905 expansion of fetchmail-friends, or you'll never see mail sent only to
906 the list. Also be sure that your listener has the "me-too" option set
907 (sendmail's -oXm command-line option or OXm declaration) so your name
908 isn't removed from alias expansions in messages you send.
910 This trick is not without its problems, however. You'll begin to see
911 this when a message comes in that is addressed only to a mailing list
912 you do \fInot\fR have declared as a local name. Each such message
913 will feature an `X-Fetchmail-Warning' header which is generated
914 because fetchmail cannot find a valid local name in the recipient
915 addresses. Such messages default (as was described above) to being
916 sent to the local user running
918 but the program has no way to know that that's actually the right thing.
920 .SS Bad Ways To Abuse Multidrop Mailboxes
921 Multidrop mailboxes and
923 serving multiple users in daemon mode do not mix. The problem, again, is
924 mail from mailing lists, which typically does not have an individual
925 recipient address on it. Unless
927 can deduce an envelope address, such mail will only go to the account
928 running fetchmail (probably root).
930 .SS Speeding Up Multidrop Checking
931 Normally, when multiple user are declared
933 extracts recipient addresses as described above and checks each host
934 part with DNS to see if it's an alias of the mailserver. If so, the
935 name mappings described in the to ... here declaration are done and
936 the mail locally delivered.
938 This is the safest but also slowest method. To speed it up,
939 pre-declare mailserver aliases with `aka'; these are checked before
940 DNS lookups are done. If you're certain your aka list contains
942 DNS aliases of the mailserver (and all MX names pointing at it)
943 you can declare `no dns' to suppress DNS lookups entirely and
944 \fIonly\fR match against the aka list.
947 To facilitate the use of
949 in shell scripts, an exit code is returned to give an indication
950 of what occurred during a given connection.
952 The exit codes returned by
956 One or more messages were successfully retrieved.
958 There was no mail awaiting retrieval.
960 An error was encountered when attempting to open a socket for the POP
961 connection. If you don't know what a socket is, don't worry about it --
962 just treat this as an 'unrecoverable error'.
964 The user authentication step failed. This usually means that a bad
965 user-id, password, or APOP id was specified.
967 Some sort of fatal protocol error was detected.
969 There was a syntax error in the arguments to
972 The run control file had bad permissions.
974 There was an error condition reported by the server (POP3 only).
976 Exclusion error. This means
978 either found another copy of itself already running, or failed in such
979 a way that it isn't sure whether another copy is running.
983 run failed while trying to do an SMTP port open or transaction.
985 Internal error. You should see a message on standard error with
990 queries more than one host, the returned status is that of the last
994 Eric S. Raymond <esr@snark.thyrsus.com>.
996 .SH BACKWARD COMPATIBILITY
997 This program is descended from and replaces
999 by Carl Harris <ceharris@mal.com>; the internals are quite different,
1000 but some of its interface design is directly traceable to that
1001 ancestral program. Some effort has been made to preserve compatibility.
1003 If called through a link named `popclient', \fIfetchmail\fR will look
1004 in ~/.poprc for its run control file. As long as the file does not
1005 use the removed `localfolder' option or `limit' (which now takes a
1006 maximum byte size rather than a line count), this will often work.
1007 (The new run control file syntax also has to be a little stricter
1008 about the order of options than the old, in order to support multiple
1009 user descriptions per server; thus you may have to rearrange things a
1012 Run control files in the .poprc format will trigger a warning. To
1013 eliminate this warning, add the `username' keyword before your first user
1014 entry per server (it is already required before second and subsequent
1015 user entries per server. In some future version the `username' keyword
1021 default run control file
1024 default location of file associating hosts with last message IDs seen
1025 (used only with newer RFC1725-compliant POP3 servers supporting the
1028 ~/.netrc your FTP run control file, which (if present) will be
1029 searched for passwords as a last resort before prompting for one
1033 lock file to help prevent concurrent runs (non-root mode).
1035 /var/run/fetchmail.pid
1036 lock file to help prevent concurrent runs (root mode).
1039 For correct initialization,
1041 requires either that both the USER and HOME environment variables are
1042 correctly set, or that \fBgetpwuid\fR(3) be able to retrieve a password
1043 entry from your user ID.
1045 .SH BUGS AND KNOWN PROBLEMS
1046 Use of any of the supported protocols other than APOP, KPOP, or ETRN requires
1047 that the program send unencrypted passwords over the TCP/IP connection
1048 to the mailserver. This creates a risk that name/password pairs
1049 might be snaffled with a packet sniffer or more sophisticated
1050 monitoring software. Under Linux, the --interface option can be used
1051 to restrict polling to availability of a specific interface device with
1052 a specific local IP address, but snooping is still possible if (a)
1053 either host has a network device that can be opened in promiscuous mode,
1054 or (b) the intervening network link can be tapped.
1056 Send comments, bug reports, gripes, and the like to Eric S. Raymond
1060 elm(1), mail(1), sendmail(8), popd(8), imapd(8)
1061 .SH APPLICABLE STANDARDS
1064 RFC 821, RFC 1869, RFC 1652, RFC 1870, RFC 1985
1073 RFC 1081, RFC 1225, RFC 1460, RFC 1725, RFC 1939
1076 RFC 1460, RFC 1725, RFC 1939
1085 RFC 1730, RFC 1731, RFC 1732, RFC 2060, RFC 2061
projects / ~andy / fetchmail / blob