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 Force UIDL use (effective only with POP3). Force client-side tracking
158 of `newness' of messages. Use with `keep' to use a mailbox as a baby
159 news drop for a group of users; if the mailbox is periodically purged,
160 every member will get a chance to read the message.
163 The option permits you to specify a TCP/IP port to connect on.
164 This option will seldom be necessary as all the supported protocols have
165 well-established default port numbers.
167 .B \-r folder, --remote folder
168 Causes a specified non-default mail folder on the mailserver to be retrieved.
169 The syntax of the folder name is server dependent, as is the default
170 behavior when no folder is specified. This option is not available
172 .SS Delivery Control Options
174 .B \-S host, --smtphost host
175 Specify a hunt list of hosts to forward mail to.
176 In ETRN mode, set the host that the mailserver is asked to ship mail to.
177 Hosts are tried in list order; the first one that is up becomes the
178 forwarding or ETRN target for the current run.
181 You can force mail to be passed to an MDA directly (rather than
182 forwarded to port 25) with the -mda or -m option. If \fIfetchmail\fR
183 is running as root, it sets its userid to that of the target user
184 while delivering mail through an MDA. Some possible MDAs are
185 "/usr/sbin/sendmail -oem", "/usr/lib/sendmail -oem",
186 "/usr/bin/formail", and "/usr/bin/deliver". Local delivery addresses
187 will be inserted into the MDA command wherever you place a %s. Do
188 \fInot\fR use an MDA like
189 "sendmail -oem -t" that dispatches on the contents of To/Cc/Bcc, it
190 will create mail loops and bring the just wrath of many postmasters
192 .SS Resource Limit Control Options
195 Takes a maximum octet size argument. Messages larger than this size
196 will not be fetched, not be marked seen, and will be left on the
197 server (in foreground sessions, the progress messages will note that
198 they are "oversized"). The --all option overrides this one. This
199 option is intended for those needing to strictly control fetch time
200 in interactive mode. It may not be used with daemon mode,
201 as users would never receive a notification that messages were waiting.
202 This option does not work with ETRN.
205 Specify the maximum number of messages that will be shipped to an SMTP
206 listener before the connection is deliberately torn down and rebuilt
207 (defaults to 0, meaning no limit). While \fBsendmail\fR(8) normally
208 initiates delivery of a message immediately after receiving the
209 message terminator, some SMTP listeners are not so prompt. MTAs like
210 \fIqmail\fR(8) and \fIsmail\fR(8) will wait till the delivery socket is
211 shut down to deliver. This may produce annoying delays when
213 is processing very large batches. Setting the batch limit to some
214 nonzero size will prevent these delays.
215 This option does not work with ETRN.
218 Limit the number of messages accepted from a given server in a single
219 poll. By default there is no limit.
220 .SS Authentication Options
222 .B \-u name, --username name
223 Specifies the user identification to be used when logging in to the mailserver.
224 The appropriate user identification is both server and user-dependent.
225 The default is your login name on the client machine that is running
227 See USER AUTHENTICATION below for a complete description.
229 .B \-I specification, --interface specification
230 Require that a specific interface device be up and have a specific local
231 IP address (or range) before polling. Frequently
233 is used over a transient point-to-point TCP/IP link established directly
234 to a mailserver via SLIP or PPP. That is a relatively secure channel.
235 But when other TCP/IP routes to the mailserver exist (e.g. when the link
236 is connected to an alternate ISP), your username and password may be
237 vulnerable to snooping (especially when daemon mode automatically polls
238 for mail, shipping a clear password over the net at predictable
239 intervals). The --interface option may be used to prevent this. When
240 the specified link is not up or is not connected to a matching IP
241 address, polling will be skipped. The format is:
243 interface/iii.iii.iii.iii/mmm.mmm.mmm.mmm
245 The field before the first slash is the interface name (i.e. sl0, ppp0
246 etc.). The field before the second slash is the acceptable IP address.
247 The field after the second slash is a mask which specifies a range of
248 IP addresses to accept. If no mask is present 255.255.255.255 is
249 assumed (i.e. an exact match). This option is currently only supported
252 .B \-M interface, --monitor interface
253 Daemon mode can cause transient links which are automatically taken down
254 after a period of inactivity (e.g. PPP links) to remain up
255 indefinitely. This option identifies a system TCP/IP interface to be
256 monitored for activity. After each poll interval, if the link is up but
257 no other activity has occurred on the link, then the poll will be
258 skipped. This option is currently only supported under Linux.
261 This option permits you to specify an authentication type (see USER
262 AUTHENTICATION below for details). The possible values are
263 \&`\fBpassword\fR' and `\fBkerberos\fR'. This option is provided
264 primarily for developers; choosing KPOP protocol automatically selects
265 Kerberos authentication, and all other alternatives use ordinary
266 password authentication (though APOP uses a generated one-time
267 key as the password).
268 This option does not work with ETRN.
269 .SS Miscellaneous Options
271 .B \-f pathname, --fetchmailrc pathname
272 Specify a non-default name for the
276 .B \-i pathname, --idfile pathname
277 Specify an alternate name for the .fetchids file used to save POP3
283 edits RFC-822 address headers (To, From, Cc, Bcc, and Reply-To) in
284 fetched mail so that any mail IDs local to the server are expanded to
285 full addresses (@ and the mailserver hostname are appended). This enables
286 replies on the client to get addressed correctly (otherwise your
287 mailer might think they should be addressed to local users on the
288 client machine!). This option disables the rewrite. (This option is
289 provided to pacify people who are paranoid about having an MTA edit
290 mail headers and want to know they can prevent it, but it is generally
291 not a good idea to actually turn off rewrite.)
292 When using ETRN, the rewrite option is ineffective.
295 This option changes the header
297 assumes will carry a copy of the mail's envelope address. Normally
298 this is `X-Envelope-To' but as this header is not standard, practice
299 varies. See the discussion of multidrop address handling below.
301 .SH USER AUTHENTICATION
302 Every mode except ETRN requires authentication of the client.
303 Normal user authentication in
305 is very much like the authentication mechanism of
307 The correct user-id and password depend upon the underlying security
308 system at the mailserver.
310 If the mailserver is a Unix machine on which you have an ordinary user
311 account, your regular login name and password are used with
313 If you use the same login name on both the server and the client machines,
314 you needn't worry about specifying a user-id with the
317 the default behavior is to use your login name on the client machine as the
318 user-id on the server machine. If you use a different login name
319 on the server machine, specify that login name with the
321 option. e.g. if your login name is 'jsmith' on a machine named 'mailgrunt',
326 fetchmail -u jsmith mailgrunt
328 The default behavior of
330 is to prompt you for your mailserver password before the connection is
331 established. This is the safest way to use
333 and ensures that your password will not be compromised. You may also specify
334 your password in your
336 file. This is convenient when using
338 in daemon mode or with scripts.
340 If you do not specify a password, and
342 cannot extract one from your
344 file, it will look for a
346 file in your home directory before requesting one interactively; if an
347 entry matching the mailserver is found in that file, the password will
350 man page for details of the syntax of the
352 file. (This feature may allow you to avoid duplicating password
353 information in more than one file.)
355 On mailservers that do not provide ordinary user accounts, your user-id and
356 password are usually assigned by the server administrator when you apply for
357 a mailbox on the server. Contact your server administrator if you don't know
358 the correct user-id and password for your mailbox account.
360 Early versions of POP3 (RFC1081, RFC1225) supported a crude form of
361 independent authentication using the
363 file on the mailserver side. Under this RPOP variant, a fixed
364 per-user ID equivalent to a password was sent in clear over a link to
365 a reserved port, with the command RPOP rather than PASS to alert the
366 server that it should do special checking. RPOP is supported
369 (you can specify `protocol RPOP' to have the program send `RPOP'
370 rather than `PASS') but its use is strongly discouraged. This
371 facility was vulnerable to spoofing and was withdrawn in RFC1460.
373 RFC1460 introduced APOP authentication. In this variant of POP3,
374 you register an APOP password on your server host (the program
375 to do this with on the server is probably called \fIpopauth\fR(8)). You
376 put the same password in your
380 logs in, it sends a cryptographically secure hash of your password and
381 the server greeting time to the server, which can verify it by
382 checking its authorization database.
384 If your \fIfetchmail\fR was built with Kerberos support and you specify
385 Kerberos authentication (either with --auth or the \fI.fetchmailrc\fR
386 option \fBauthenticate kerberos\fR) it will try to get a Kerberos
387 ticket from the mailserver at the start of each query.
396 in daemon mode. You must specify a numeric argument which is a
397 polling interval in seconds.
401 puts itself in background and runs forever, querying each specified
402 host and then sleeping for the given polling interval.
408 will, therefore, poll all the hosts described in your
410 file (except those explicitly excluded with the `skip' verb) once
411 every fifteen minutes.
413 Only one daemon process is permitted per user; in daemon mode,
415 makes a per-user lockfile to guarantee this. The option
417 will kill a running daemon process. Otherwise, calling fetchmail with
418 a daemon in the background sends a wakeup signal to the daemon,
419 forcing it to poll mailservers immediately.
425 option allows you to set a server-nonresponse timeout in seconds. If
426 a mailserver does not send a greeting message or respond to commands for
427 the given number of seconds, \fIfetchmail\fR will hang up on it.
428 Without such a timeout \fIfetchmail\fR might hang up indefinitely
429 trying to fetch mail from a down host. This would be particularly
430 annoying for a \fIfetchmail\fR running in background.
436 option allows you to redirect status messages emitted while in daemon
437 mode into a specified logfile (follow the option with the logfile name).
438 The logfile is opened for append, so previous messages aren't deleted.
439 This is primarily useful for debugging configurations.
443 option allows you to redirect status and error messages emitted while in
446 system daemon if available.
447 Messages are logged with an id of \fBfetchmail\fR, the facility \fBLOG_MAIL\fR,
448 and priorities \fBLOG_ERR\fR, \fBLOG_ALERT\fR or \fBLOG_INFO\fR.
449 This option is intended for logging status and error messages which
450 indicate the status of the daemon and the results while fetching mail
452 Error messages for command line options and parsing the \fI.fetchmailrc\fR
453 file are still written to stderr, or the specified log file if the
459 The \fI/etc/syslog.conf\fR file might contain the following to log
460 all messages from \fIfetchmail\fR to a single file:
465 *.* /var/log/fetchmail
470 or --nodetach option suppresses detachment of the daemon process
471 from its control terminal. This is primarily useful for debugging.
473 Note that while running in daemon mode polling a POP server, transient
474 errors (such as DNS failures or sendmail delivery refusals) may force
475 the fetchall option on for the duration of the next polling cycle.
476 This is a robustness feature. It means that if a message is fetched
477 (and thus marked seen by the mailserver) but not delivered locally due
478 to some transient error, it will be re-fetched during the next poll
479 cycle. (The IMAP logic doesn't delete messages until they're
480 delivered, so this problem does not arise.)
482 .SH RETRIEVAL FAILURE MODES
483 The protocols \fIfetchmail\fR uses to talk to mailservers are next to
484 bulletproof. In normal operation forwarding to port 25, no message is
485 ever deleted (or even marked for deletion) on the host until the SMTP
486 listener on the client has acknowledged to \fIfetchmail\fR that the
487 message has been accepted for delivery. When forwarding to an MDA,
488 however, there is more possibility of error (because there's no way
489 for fetchmail to get a reliable positive acknowledgement from the MDA).
491 The normal mode of \fIfetchmail\fR is to try to download only `new'
492 messages, leaving untouched (and undeleted) messages you have already
493 read directly on the server (or fetched with a previous \fIfetchmail
494 --keep\fR). But you may find that messages you've already read on the
495 server are being fetched (and deleted) even when you don't specify
496 --all. There are several reasons this can happen.
498 One could be that you're using POP2. The POP2 protocol includes no
499 representation of `new' or `old' state in messages, so \fIfetchmail\fR
500 must treat all messages as new all the time. But POP2 is obsolete, so
503 Under POP3, blame RFC1725. That version of the POP3 protocol
504 specification removed the LAST command, and some POP servers follow it
505 (you can verify this by invoking \fIfetchmail -v\fR to the mailserver
506 and watching the response to LAST early in the query). The
507 \fIfetchmail\fR code tries to compensate by using POP3's UID feature,
508 storing the identifiers of messages seen in each session until the
509 next session, in the \fI.fetchids\fR file. But this doesn't track
510 messages seen with other clients, or read directly with a mailer on
511 the host but not deleted afterward. A better solution would be to
514 Another potential POP3 problem might be servers that insert messages
515 in the middle of mailboxes (some VMS implementations of mail are
516 rumored to do this). The \fIfetchmail\fR code assumes that new
517 messages are appended to the end of the mailbox; when this is not true
518 it may treat some old messages as new and vice versa. The only
519 real fix for this problem is to switch to IMAP.
521 The IMAP code uses the presence or absence of the server flag \eSeen
522 to decide whether or not a message is new. Under Unix, it counts on
523 your IMAP server to notice the BSD-style Status flags set by mail user
524 agents and set the \eSeen flag from them when appropriate. All Unix
525 IMAP servers we know of do this, though it's not specified by the IMAP
526 RFCs. If you ever trip over a server that doesn't, the symptom will
527 be that messages you have already read on your host will look new to
528 the server. In this (unlikely) case, only messages you fetched with
529 \fIfetchmail --keep\fR will be both undeleted and marked old.
531 In ETRN mode, \fIfetchmail\fR does not actually retrieve messages;
532 instead, it asks the server's SMTP listener to start a queue flush
533 to the client via SMTP. Therefore it sends only undelivered messages.
538 allow administrators to set up `spam filters' that block unsolicited email
539 from specified domains. A MAIL FROM line that triggers this feature
540 will elicit an SMTP response with an error code of 571. The
542 code recognizes this error and discards the message. This is the
544 circumstance under which fetchmail ever discards mail.
546 .SH THE RUN CONTROL FILE
547 The preferred way to set up fetchmail (and the only way if you want to
548 avoid specifying passwords each time it runs) is to write a
549 \&\fI.fetchmailrc\fR file in your home directory. When there is a
550 conflict between the command-line arguments and the arguments in this
551 file, the command-line arguments take precedence.
553 To protect the security of your passwords, your \fI~/.fetchmailrc\fR
554 may not have more than 600 (u=rw,g=,o=) permissions;
556 will complain and exit otherwise.
558 You may read the \fI.fetchmailrc\fR file as a list of commands to
561 is called with no arguments.
563 Comments begin with a '#' and extend through the end of the line.
564 Otherwise the file consists of a series of server entries or global
565 option statements in a free-format, token-oriented syntax.
567 There are four kinds of tokens: grammar keywords, numbers
568 (i.e. decimal digit sequences), unquoted strings, and quoted strings.
569 A quoted string is bounded by double quotes and may contain
570 whitespace (and quoted digits are treated as a string). An unquoted
571 string is any whitespace-delimited token that is neither numeric, string
572 quoted nor contains the special characters `,', `;', `:', or `='.
574 Any amount of whitespace separates tokens in server entries, but is
575 otherwise ignored. You may use standard C-style escapes (\en, \et,
576 \eb, octal, and hex) to embed non-printable characters or string
577 delimiters in strings.
579 Each server entry consists of one of the keywords `poll' or `skip',
580 followed by a server name, followed by server options, followed by any
581 number of user descriptions.
583 The `poll' verb tells fetchmail to query this host when it is run with
584 no arguments. The `skip' verb tells
586 not to poll this host unless it is explicitly named on the command
587 line. (The `skip' verb allows you to experiment with test entries
588 safely, or easily disable entries for hosts that are temporarily down.)
590 Legal server options are:
594 authenticate (or auth)
603 Legal user options are
609 remotefolder (or remote)
631 All options correspond to the obvious command-line arguments except
632 the following: `aka', `is', `to', `dns'/`no dns', `password',
633 \&`preconnect', `localdomains', `stripcr'/`no stripcr' and
636 The `is' or `to' keywords associate the following local (client)
637 name(s) (or server-name to client-name mappings separated by =) with
638 the mailserver user name in the entry. If an is/to list has `*' as
639 its last name, unrecognized names are simply passed through.
641 A single local name can be used to support redirecting your mail when
642 your username on the client machine is different from your name on the
643 mailserver. When there is only a single local name, mail is forwarded
644 to that local username regardless of the message's Received, To, Cc,
645 and Bcc headers. In this case
647 never does DNS lookups.
649 When there is more than one local name (or name mapping) the
650 \fIfetchmail\fR code does look at the Received, To, Cc, and Bcc
651 headers of retrieved mail (this is `multidrop mode'). It looks for
652 addresses with hostname parts that match your `aka' or `localdomains'
653 options, and usually also for hostname parts which DNS tells it are
654 aliases of the mailserver. See the discussion of `dns',
655 `localdomains', and `aka' for details on how matching addresses are
656 handled. If \fIfetchmail\fR cannot match any mailserver usernames or
657 localdomain addresses, the default recipient is the calling user.
659 The `dns' option (normally on) controls the way addresses from
660 multidrop mailboxes are checked. On, it enables logic to check each
661 host address that doesn't match an `aka' or `localdomains' declaration
662 by looking it up with DNS. When a mailserver username is recognized
663 attached to a matching hostname part, its local mapping is added to
664 the list of local recipients.
666 The `aka' option is for use with multidrop mailboxes. It allows you
667 to pre-declare a list of DNS aliases for a server. This is an
668 optimization hack that allows you to trade space for speed. When
670 while processing a multidrop mailbox, grovels through message headers
671 looking for names of the mailserver, pre-declaring common ones can
672 save it from having to do DNS lookups.
674 The `localdomains' option allows you to declare a list of domains
675 which fetchmail should consider local. When fetchmail is parsing
676 address lines in multidrop modes, and a trailing segment of a host
677 name matches a declared local doman, that address is passed through
678 to the listener or MDA unaltered (local-name mappings are \fInot\fR
681 If you are using `localdomains', you may also need to specify \&`no
682 envelope', which disables \fIfetchmail\fR's normal attempt to deduce
683 an envelope address from the Received line or X-Envelope-To header or
684 whatever header has been previously set by `envelope'. If you set `no
685 envelope' in the defaults entry it is possible to undo that in
686 individual entries by using `envelope <string>'.
688 The \fBpassword\fR option requires a string argument, which is the password
689 to be used with the entry's server.
691 The `preconnect' keyword allows you to specify a shell command to be
692 executed just before each time
694 establishes a mailserver connection. This may be useful if you are
695 attempting to set up secure POP connections with the aid of
698 The `stripcr' option controls whether carriage returns are stripped
699 out of retrieved mail before it is forwarded. It is normally not
700 necessary to set this, because it defaults to `on' (CR stripping
701 enabled) when there is an MDA declared but `off' (CR stripping
702 disabled) when forwarding is via SMTP.
704 Legal protocol identifiers are
714 Legal authentication types are `password' or `kerberos'. The former
715 specifies authentication by normal transmission of a password (the
716 password may be plaintext or subject to protocol-specific encryption
717 as in APOP); the second tells \fIfetchmail\fR to try to get a Kerberos
718 ticket at the start of each query instead, and send an arbitrary
719 string as the password.
721 Specifying `kpop' sets POP3 protocol over port 1109 with Kerberos
722 authentication. These defaults may be overridden by later options.
724 You can use the noise keywords `and', `with',
725 `has', `wants', and `options' anywhere in an entry to make
726 it resemble English. They're ignored, but but can make entries much
727 easier to read at a glance. The punctuation characters ':', ';' and
728 ',' are also ignored.
730 The words `here' and `there' have useful English-like
731 significance. Normally `user eric is esr' would mean that
732 mail for the remote user `eric' is to be delivered to `esr',
733 but you can make this clearer by saying `user eric there is esr here',
734 or reverse it by saying `user esr here is eric there'
736 For backward compatibility, the word `server' is a synonym for `poll'.
738 There are currently two global option statements; `set logfile = '
739 followed by a string sets the same global specified by --logfile. A
740 command-line --logfile option will override this. Also, `set daemon'
741 sets the poll interval as --daemon does. This can be overridden by
742 a command-line --daemon option; iin particular --daemon 0 can be used
743 to force foreground operation.
748 poll SERVERNAME protocol PROTOCOL username NAME password PASSWORD
754 poll pop.provider.net protocol pop3 username jsmith password secret1
757 Or, using some abbreviations:
760 poll pop.provider.net proto pop3 user jsmith password secret1
763 Multiple servers may be listed:
766 poll pop.provider.net proto pop3 user jsmith pass secret1
767 poll other.provider.net proto pop2 user John.Smith pass My^Hat
770 Here's a version of those two with more whitespace and some noise words:
773 poll pop.provider.net proto pop3
774 user jsmith, with password secret1, is jsmith here;
775 poll other.provider.net proto pop2:
776 user John.Smith, with password My^Hat, is John.Smith here;
779 This version is much easier to read and doesn't cost significantly
780 more (parsing is done only once, at startup time).
783 If you need to include whitespace in a parameter string, enclose the
784 string in double quotes. Thus:
787 poll mail.provider.net with proto pop3:
788 user jsmith there has password "u can't krak this"
789 is jws here and wants mda "/bin/mail"
792 You may have an initial server description headed by the keyword
793 `defaults' instead of `poll' followed by a name. Such a record
794 is interpreted as defaults for all queries to use. It may be overwritten
795 by individual server descriptions. So, you could write:
800 poll pop.provider.net
802 poll mail.provider.net
803 user jjsmith there has password secret2
806 It's possible to specify more than one user per server (this is only
807 likely to be useful when running fetchmail in daemon mode as root).
808 The `user' keyword leads off a user description, and every user
809 description except optionally the first one must include it. If the
810 first description lacks the `user' keyword, the name of the invoking
811 user is used (in a future version, the option to omit the `user'
812 keyword may be removed). Here's a contrived example:
815 poll pop.provider.net proto pop3 port 3111
817 user jsmith with pass secret1 is smith here
818 user jones with pass secret2 is jjones here
821 This says that the user invoking \fIfetchmail\fR has the same username
822 on pop.provider.net, and password `gumshoe' there. It also associates
823 the local username `smith' with the pop.provider.net username `jsmith'
824 and the local username `jjones' with the pop.provider.net username
827 This example is contrived because, in practice, you are very unlikely
828 to be specifying multiple users per server unless running it as root
829 (thus the `pass gumshoe' would try to fetch root's mail on
830 pop-provider.net, which is probably not what you want). In any case,
831 we strongly recommend always having an explicit \&`user' clause when
832 specifying multiple users per mailserver. In a future version, the
833 option not to explicitly declare the username may be removed.
835 Here's what a simple retrieval configuration for a multi-drop mailbox
839 poll pop.provider.net:
840 user maildrop with pass secret1 to golux hurkle=happy snark here
843 This says that the mailbox of account `maildrop' on the server is a
844 multi-drop box, and that messages in it should be parsed for the
845 server user names `golux', `hurkle', and `snark'. It further
846 specifies that `golux' and `snark' have the same name on the
847 client as on the server, but mail for server user `hurkle' should be
848 delivered to client user `happy'.
850 Here's an example of another kind of multidrop connection:
853 poll pop.provider.net localdomains loonytoons.org:
854 user maildrop with pass secret1 to esr * here
857 This also says that the mailbox of account `maildrop' on the server is
858 a multi-drop box. It tells fetchmail that any address in the
859 loonytoons.org domain (including subdomain addresses like
860 `joe@daffy.loonytoons.org') should be passed through to the local SMTP
861 listener without modification. Be careful of mail loops if you do this!
863 .SH THE USE AND ABUSE OF MULTIDROP MAILBOXES
864 Use the multiple-local-recipients feature with caution -- it can bite.
865 Also note that all multidrop features are ineffective in ETRN mode.
867 .SS Header vs. Envelope addresses
868 The fundamental problem is that by having your mailserver toss several
869 peoples' mail in a box, you may have thrown away potentially vital
870 information about who each piece of mail was actually addressed to
871 (the `envelope address', as opposed to the addresses in the RFC822
872 To/Cc/Bcc headers). This `envelope address' is the address you need
873 in order to reroute mail properly.
877 can deduce the envelope address. If the mailserver MTA is
879 and the item of mail had just one recipient, the MTA will have written
880 a `for' clause that gives the envelope addressee into its Received
881 header. But this doesn't work reliably for other MTAs, nor if there is more
884 Alternatively, some SMTP listeners and/or mail servers insert a header
885 in each message containing a copy of the envelope addresses. This
886 header (when it exists) is often `X-Envelope-To'. Fetchmail's
887 assumption about this can be changed with the -E or `envelope' option.
889 Sometimes, unfortunately, neither of these methods works. When they
890 both fail, fetchmail must fall back on the contents of To/Cc/Bcc
891 headers to try to determine recipient addressees -- and these are not
892 reliable. In particular, mailing-list software often ships mail with
893 the list broadcast address in the To header.
897 cannot deduce a recipient address that is local, and the intended
898 recipient address was anyone other than fetchmail's invoking user,
899 mail will get lost. This is what makes the multidrop feature risky.
901 .SS Good Ways To Use Multidrop Mailboxes
902 Multiple local names can be used to administer a mailing list from the
903 client side of a \fIfetchmail\fR collection. Suppose your name is
904 \&`esr', and you want to both pick up your own mail and maintain a mailing
905 list called (say) "fetchmail-friends", and you want to keep the alias
906 list on your client machine.
908 On your server, you can alias \&`fetchmail-friends' to `esr'; then, in
909 your \fI.fetchmailrc\fR, declare \&`to esr fetchmail-friends here'.
910 Then, when mail including `fetchmail-friends' as a local address
911 gets fetched, the list name will be appended to the list of
912 recipients your SMTP listener sees. Therefore it will undergo alias
913 expansion locally. Be sure to include `esr' in the local alias
914 expansion of fetchmail-friends, or you'll never see mail sent only to
915 the list. Also be sure that your listener has the "me-too" option set
916 (sendmail's -oXm command-line option or OXm declaration) so your name
917 isn't removed from alias expansions in messages you send.
919 This trick is not without its problems, however. You'll begin to see
920 this when a message comes in that is addressed only to a mailing list
921 you do \fInot\fR have declared as a local name. Each such message
922 will feature an `X-Fetchmail-Warning' header which is generated
923 because fetchmail cannot find a valid local name in the recipient
924 addresses. Such messages default (as was described above) to being
925 sent to the local user running
927 but the program has no way to know that that's actually the right thing.
929 .SS Bad Ways To Abuse Multidrop Mailboxes
930 Multidrop mailboxes and
932 serving multiple users in daemon mode do not mix. The problem, again, is
933 mail from mailing lists, which typically does not have an individual
934 recipient address on it. Unless
936 can deduce an envelope address, such mail will only go to the account
937 running fetchmail (probably root).
939 .SS Speeding Up Multidrop Checking
940 Normally, when multiple user are declared
942 extracts recipient addresses as described above and checks each host
943 part with DNS to see if it's an alias of the mailserver. If so, the
944 name mappings described in the to ... here declaration are done and
945 the mail locally delivered.
947 This is the safest but also slowest method. To speed it up,
948 pre-declare mailserver aliases with `aka'; these are checked before
949 DNS lookups are done. If you're certain your aka list contains
951 DNS aliases of the mailserver (and all MX names pointing at it)
952 you can declare `no dns' to suppress DNS lookups entirely and
953 \fIonly\fR match against the aka list.
956 To facilitate the use of
958 in shell scripts, an exit code is returned to give an indication
959 of what occurred during a given connection.
961 The exit codes returned by
965 One or more messages were successfully retrieved.
967 There was no mail awaiting retrieval.
969 An error was encountered when attempting to open a socket for the POP
970 connection. If you don't know what a socket is, don't worry about it --
971 just treat this as an 'unrecoverable error'.
973 The user authentication step failed. This usually means that a bad
974 user-id, password, or APOP id was specified.
976 Some sort of fatal protocol error was detected.
978 There was a syntax error in the arguments to
981 The run control file had bad permissions.
983 There was an error condition reported by the server (POP3 only).
985 Exclusion error. This means
987 either found another copy of itself already running, or failed in such
988 a way that it isn't sure whether another copy is running.
992 run failed while trying to do an SMTP port open or transaction.
994 Internal error. You should see a message on standard error with
999 queries more than one host, the returned status is that of the last
1003 Eric S. Raymond <esr@snark.thyrsus.com>.
1005 .SH BACKWARD COMPATIBILITY
1006 This program is descended from and replaces
1008 by Carl Harris <ceharris@mal.com>; the internals are quite different,
1009 but some of its interface design is directly traceable to that
1010 ancestral program. Some effort has been made to preserve compatibility.
1012 If called through a link named `popclient', \fIfetchmail\fR will look
1013 in ~/.poprc for its run control file. As long as the file does not
1014 use the removed `localfolder' option or `limit' (which now takes a
1015 maximum byte size rather than a line count), this will often work.
1016 (The new run control file syntax also has to be a little stricter
1017 about the order of options than the old, in order to support multiple
1018 user descriptions per server; thus you may have to rearrange things a
1021 Run control files in the .poprc format will trigger a warning. To
1022 eliminate this warning, add the `username' keyword before your first user
1023 entry per server (it is already required before second and subsequent
1024 user entries per server. In some future version the `username' keyword
1030 default run control file
1033 default location of file associating hosts with last message IDs seen
1034 (used only with newer RFC1725-compliant POP3 servers supporting the
1037 ~/.netrc your FTP run control file, which (if present) will be
1038 searched for passwords as a last resort before prompting for one
1042 lock file to help prevent concurrent runs (non-root mode).
1044 /var/run/fetchmail.pid
1045 lock file to help prevent concurrent runs (root mode).
1048 For correct initialization,
1050 requires either that both the USER and HOME environment variables are
1051 correctly set, or that \fBgetpwuid\fR(3) be able to retrieve a password
1052 entry from your user ID.
1054 .SH BUGS AND KNOWN PROBLEMS
1055 Use of any of the supported protocols other than APOP, KPOP, or ETRN requires
1056 that the program send unencrypted passwords over the TCP/IP connection
1057 to the mailserver. This creates a risk that name/password pairs
1058 might be snaffled with a packet sniffer or more sophisticated
1059 monitoring software. Under Linux, the --interface option can be used
1060 to restrict polling to availability of a specific interface device with
1061 a specific local IP address, but snooping is still possible if (a)
1062 either host has a network device that can be opened in promiscuous mode,
1063 or (b) the intervening network link can be tapped.
1065 Send comments, bug reports, gripes, and the like to Eric S. Raymond
1069 elm(1), mail(1), sendmail(8), popd(8), imapd(8)
1070 .SH APPLICABLE STANDARDS
1073 RFC 821, RFC 1869, RFC 1652, RFC 1870, RFC 1985
1082 RFC 1081, RFC 1225, RFC 1460, RFC 1725, RFC 1939
1085 RFC 1460, RFC 1725, RFC 1939
1094 RFC 1730, RFC 1731, RFC 1732, RFC 2060, RFC 2061
projects / ~andy / fetchmail / blob