1fetchmail(1) fetchmail reference manual fetchmail(1)
2
6 fetchmail - fetch mail from a POP, IMAP, ETRN, or ODMR-capable server
7
10 fetchmail [option...] [mailserver...]
11 fetchmailconf
12
15 fetchmail is a mail-retrieval and forwarding utility; it fetches mail
16 from remote mailservers and forwards it to your local (client) ma‐
17 chine's delivery system. You can then handle the retrieved mail using
18 normal mail user agents such as mutt(1), elm(1) or Mail(1). The fetch‐
19 mail utility can be run in a daemon mode to repeatedly poll one or more
20 systems at a specified interval.
21 The fetchmail program can gather mail from servers supporting any of
23 the common mail-retrieval protocols: POP2 (legacy, to be removed from
24 future release), POP3, IMAP2bis, IMAP4, and IMAP4rev1. It can also use
25 the ESMTP ETRN extension and ODMR. (The RFCs describing all these pro‐
26 tocols are listed at the end of this manual page.)
27 While fetchmail is primarily intended to be used over on-demand TCP/IP
29 links (such as SLIP or PPP connections), it may also be useful as a
30 message transfer agent for sites which refuse for security reasons to
31 permit (sender-initiated) SMTP transactions with sendmail.
32 SUPPORT, TROUBLESHOOTING
35 For troubleshooting, tracing and debugging, you need to increase fetch‐
36 mail's verbosity to actually see what happens. To do that, please run
37 both of the two following commands, adding all of the options you'd
38 normally use.
39 env LC_ALL=C fetchmail -V -v --nodetach --nosyslog
42 (This command line prints in English how fetchmail understands
44 your configuration.)
45 env LC_ALL=C fetchmail -vvv --nodetach --nosyslog
48 (This command line actually runs fetchmail with verbose English
50 output.)
51 Also see item #G3 in fetchmail's FAQ ⟨https://fetchmail.sourceforge.io/
53 fetchmail-FAQ.html#G3⟩
54 You can omit the LC_ALL=C part above if you want output in the local
56 language (if supported). However if you are posting to mailing lists,
57 please leave it in. The maintainers do not necessarily understand your
58 language, please use English.
59
65 If fetchmail is used with a POP or an IMAP server (but not with ETRN or
66 ODMR), it has two fundamental modes of operation for each user account
67 from which it retrieves mail: singledrop- and multidrop-mode.
68 In singledrop-mode,
70 fetchmail assumes that all messages in the user's account (mail‐
71 box) are intended for a single recipient. The identity of the
72 recipient will either default to the local user currently exe‐
73 cuting fetchmail, or will need to be explicitly specified in the
74 configuration file.
75 fetchmail uses singledrop-mode when the fetchmailrc configura‐
77 tion contains at most a single local user specification for a
78 given server account.
79 In multidrop-mode,
81 fetchmail assumes that the mail server account actually contains
82 mail intended for any number of different recipients. There‐
83 fore, fetchmail must attempt to deduce the proper "envelope re‐
84 cipient" from the mail headers of each message. In this mode of
85 operation, fetchmail almost resembles a mail transfer agent
86 (MTA).
87 Note that neither the POP nor IMAP protocols were intended for
89 use in this fashion, and hence envelope information is often not
90 directly available. The ISP must stores the envelope informa‐
91 tion in some message header and. The ISP must also store one
92 copy of the message per recipient. If either of the conditions
93 is not fulfilled, this process is unreliable, because fetchmail
94 must then resort to guessing the true envelope recipient(s) of a
95 message. This usually fails for mailing list messages and Bcc:d
96 mail, or mail for multiple recipients in your domain.
97 fetchmail uses multidrop-mode when more than one local user
99 and/or a wildcard is specified for a particular server account
100 in the configuration file.
101 In ETRN and ODMR modes,
103 these considerations do not apply, as these protocols are based
104 on SMTP, which provides explicit envelope recipient information.
105 These protocols always support multiple recipients.
106 As each message is retrieved, fetchmail normally delivers it via SMTP
108 to port 25 on the machine it is running on (localhost), just as though
109 it were being passed in over a normal TCP/IP link. fetchmail provides
110 the SMTP server with an envelope recipient derived in the manner de‐
111 scribed previously. The mail will then be delivered according to your
112 MTA's rules (the Mail Transfer Agent is usually sendmail(8), exim(8),
113 or postfix(8)). Invoking your system's MDA (Mail Delivery Agent) is
114 the duty of your MTA. All the delivery-control mechanisms (such as
115 .forward files) normally available through your system MTA and local
116 delivery agents will therefore be applied as usual.
117 If your fetchmail configuration sets a local MDA (see the --mda op‐
119 tion), it will be used directly instead of talking SMTP to port 25.
120 If the program fetchmailconf is available, it will assist you in set‐
122 ting up and editing a fetchmailrc configuration. It runs under the X
123 window system and requires that the language Python and the Tk toolkit
124 (with Python bindings) be present on your system. If you are first
125 setting up fetchmail for single-user mode, it is recommended that you
126 use Novice mode. Expert mode provides complete control of fetchmail
127 configuration, including the multidrop features. In either case, the
128 'Autoprobe' button will tell you the most capable protocol a given
129 mailserver supports, and warn you of potential problems with that
130 server.
131
134 Fetchmail's run-time strings have been translated (localized) to some
135 languages, but the manual is only available in English. In some situa‐
136 tions, for comparing output to manual, it may be helpful to switch
137 fetchmail to English output by overriding the locale variables, for in‐
138 stance:
139 env LC_ALL=C fetchmail # add other options before the hash
142 env LANG=en fetchmail # other options before the hash
145 or similar. Details vary by operating system.
147
150 The behavior of fetchmail is controlled by command-line options and a
151 run control file, ~/.fetchmailrc, the syntax of which we describe in a
152 later section (this file is what the fetchmailconf program edits).
153 Command-line options override ~/.fetchmailrc declarations.
154 Each server name that you specify following the options on the command
156 line will be queried. If you do not specify any servers on the command
157 line, each 'poll' entry in your ~/.fetchmailrc file will be queried,
158 unless the idle option is used, which see.
159 To facilitate the use of fetchmail in scripts and pipelines, it returns
161 an appropriate exit code upon termination -- see EXIT CODES below.
162 The following options modify the behavior of fetchmail. It is seldom
164 necessary to specify any of these once you have a working .fetchmailrc
165 file set up.
166 Almost all options have a corresponding keyword which can be used to
168 declare them in a .fetchmailrc file.
169 Some special options are not covered here, but are documented instead
171 in sections on AUTHENTICATION and DAEMON MODE which follow.
172 General Options
174 -? | --help
175 Displays option help.
176 -V | --version
178 Displays the version information for your copy of fetchmail. No
179 mail fetch is performed. Instead, for each server specified,
180 all the option information that would be computed if fetchmail
181 were connecting to that server is displayed. Any non-printables
182 in passwords or other string names are shown as backslashed C-
183 like escape sequences. This option is useful for verifying that
184 your options are set the way you want them.
185 -c | --check
187 Return a status code to indicate whether there is mail waiting,
188 without actually fetching or deleting mail (see EXIT CODES be‐
189 low). This option turns off daemon mode (in which it would be
190 useless). It doesn't play well with queries to multiple sites,
191 and doesn't work with ETRN or ODMR. It will return a false pos‐
192 itive if you leave read but undeleted mail in your server mail‐
193 box and your fetch protocol can't tell kept messages from new
194 ones. This means it will work with IMAP, not work with POP2,
195 and may occasionally flake out under POP3.
196 -s | --silent
198 Silent mode. Suppresses all progress/status messages that are
199 normally echoed to standard output during a fetch (but does not
200 suppress actual error messages). The --verbose option overrides
201 this.
202 -v | --verbose
204 Verbose mode. All control messages passed between fetchmail and
205 the mailserver are echoed to stdout. Overrides --silent. Dou‐
206 bling this option (-v -v) causes extra diagnostic information to
207 be printed.
208 --nosoftbounce
210 (since v6.3.10, Keyword: set no softbounce, since v6.3.10)
211 Hard bounce mode. All permanent delivery errors cause messages
212 to be deleted from the upstream server, see "no softbounce" be‐
213 low.
214 --softbounce
216 (since v6.3.10, Keyword: set softbounce, since v6.3.10)
217 Soft bounce mode. All permanent delivery errors cause messages
218 to be left on the upstream server if the protocol supports that.
219 This option is on by default to match historic fetchmail docu‐
220 mentation, and will be changed to hard bounce mode in the next
221 fetchmail release.
222 Disposal Options
224 -a | --all | (since v6.3.3) --fetchall
225 (Keyword: fetchall, since v3.0)
226 Retrieve both old (seen) and new messages from the mailserver.
227 The default is to fetch only messages the server has not marked
228 seen. Under POP3, this option also forces the use of RETR
229 rather than TOP. Note that POP2 retrieval behaves as though
230 --all is always on (see RETRIEVAL FAILURE MODES below) and this
231 option does not work with ETRN or ODMR. While the -a and --all
232 command-line and fetchall rcfile options have been supported for
233 a long time, the --fetchall command-line option was added in
234 v6.3.3.
235 -k | --keep
237 (Keyword: keep)
238 Keep retrieved messages on the remote mailserver. Normally,
239 messages are deleted from the folder on the mailserver after
240 they have been retrieved. Specifying the keep option causes re‐
241 trieved messages to remain in your folder on the mailserver.
242 This option does not work with ETRN or ODMR. If used with POP3,
243 it is recommended to also specify the --uidl option or uidl key‐
244 word.
245 -K | --nokeep
247 (Keyword: nokeep)
248 Delete retrieved messages from the remote mailserver. This op‐
249 tion forces retrieved mail to be deleted. It may be useful if
250 you have specified a default of keep in your .fetchmailrc. This
251 option is forced on with ETRN and ODMR.
252 -F | --flush
254 (Keyword: flush)
255 POP3/IMAP only. This is a dangerous option and can cause mail
256 loss when used improperly. It deletes old (seen) messages from
257 the mailserver before retrieving new messages. Warning: This
258 can cause mail loss if you check your mail with other clients
259 than fetchmail, and cause fetchmail to delete a message it had
260 never fetched before. It can also cause mail loss if the mail
261 server marks the message seen after retrieval (IMAP2 servers).
262 You should probably not use this option in your configuration
263 file. If you use it with POP3, you must use the 'uidl' option.
264 What you probably want is the default setting: if you don't
265 specify '-k', then fetchmail will automatically delete messages
266 after successful delivery.
267 --limitflush
269 POP3/IMAP only, since version 6.3.0. Delete oversized messages
270 from the mailserver before retrieving new messages. The size
271 limit should be separately specified with the --limit option.
272 This option does not work with ETRN or ODMR.
273 Protocol and Query Options
275 -p <proto> | --proto <proto> | --protocol <proto>
276 (Keyword: proto[col])
277 Specify the protocol to use when communicating with the remote
278 mailserver. If no protocol is specified, the default is AUTO.
279 proto may be one of the following:
280 AUTO Tries IMAP, POP3, and POP2 (skipping any of these for
282 which support has not been compiled in).
283 POP2 Post Office Protocol 2 (legacy, to be removed from future
285 release)
286 POP3 Post Office Protocol 3
288 APOP Use POP3 with old-fashioned MD5-challenge authentication.
290 Considered not resistant to man-in-the-middle attacks.
291 RPOP Use POP3 with RPOP authentication.
293 KPOP Use POP3 with Kerberos V4 authentication on port 1109.
295 SDPS Use POP3 with Demon Internet's SDPS extensions.
297 IMAP IMAP2bis, IMAP4, or IMAP4rev1 (fetchmail automatically
299 detects their capabilities).
300 ETRN Use the ESMTP ETRN option.
302 ODMR Use the the On-Demand Mail Relay ESMTP profile.
304 All these alternatives work in basically the same way (communicating
306 with standard server daemons to fetch mail already delivered to a mail‐
307 box on the server) except ETRN and ODMR. The ETRN mode allows you to
308 ask a compliant ESMTP server (such as BSD sendmail at release 8.8.0 or
309 higher) to immediately open a sender-SMTP connection to your client ma‐
310 chine and begin forwarding any items addressed to your client machine
311 in the server's queue of undelivered mail. The ODMR mode requires an
312 ODMR-capable server and works similarly to ETRN, except that it does
313 not require the client machine to have a static DNS.
314 -U | --uidl
316 (Keyword: uidl)
317 Force UIDL use (effective only with POP3). Force client-side
318 tracking of 'newness' of messages (UIDL stands for "unique ID
319 listing" and is described in RFC1939). Use with 'keep' to use a
320 mailbox as a baby news drop for a group of users. The fact that
321 seen messages are skipped is logged, unless error logging is
322 done through syslog while running in daemon mode. Note that
323 fetchmail may automatically enable this option depending on up‐
324 stream server capabilities. Note also that this option may be
325 removed and forced enabled in a future fetchmail version. See
326 also: --idfile.
327 --idle (since 6.3.3)
329 (Keyword: idle, since before 6.0.0)
330 Enable IDLE use (effective only with IMAP). Note that this works
331 with only one account and one folder at a given time, other
332 folders or accounts will not be polled when idle is in effect!
333 While the idle rcfile keyword had been supported for a long
334 time, the --idle command-line option was added in version 6.3.3.
335 IDLE use means that fetchmail tells the IMAP server to send no‐
336 tice of new messages, so they can be retrieved sooner than would
337 be possible with regular polls.
338 -P <portnumber> | --service <servicename>
340 (Keyword: service) Since version 6.3.0.
341 The service option permits you to specify a service name to con‐
342 nect to. You can specify a decimal port number here, if your
343 services database lacks the required service-port assignments.
344 See the FAQ item R12 and the --ssl documentation for details.
345 This replaces the older --port option.
346 Note that this does not magically switch between TLS-wrapped and start‐
348 tls modes, if you specify a port number or service name here that is
349 TLS-wrapped, meaning it starts to negotiate TLS before sending applica‐
350 tion data in the clear, you may need to specify --ssl on the command
351 line or ssl in your rcfile.
352 --port <portnumber>
354 (Keyword: port)
355 Obsolete version of --service that does not take service names.
356 Note: this option may be removed from a future version.
357 --principal <principal>
359 (Keyword: principal)
360 The principal option permits you to specify a service principal
361 for mutual authentication. This is applicable to POP3 or IMAP
362 with Kerberos 4 authentication only. It does not apply to Ker‐
363 beros 5 or GSSAPI. This option may be removed in a future
364 fetchmail version.
365 -t <seconds> | --timeout <seconds>
367 (Keyword: timeout)
368 The timeout option allows you to set a server-nonresponse time‐
369 out in seconds. If a mailserver does not send a greeting mes‐
370 sage or respond to commands for the given number of seconds,
371 fetchmail will drop the connection to it. Without such a time‐
372 out fetchmail might hang until the TCP connection times out,
373 trying to fetch mail from a down host, which may be very long.
374 This would be particularly annoying for a fetchmail running in
375 the background. There is a default timeout which fetchmail -V
376 will report. If a given connection receives too many timeouts
377 in succession, fetchmail will consider it wedged and stop retry‐
378 ing. The calling user will be notified by email if this hap‐
379 pens.
380 Beginning with fetchmail 6.3.10, the SMTP client uses the recom‐
382 mended minimum timeouts from RFC-5321 while waiting for the
383 SMTP/LMTP server it is talking to. You can raise the timeouts
384 even more, but you cannot shorten them. This is to avoid a
385 painful situation where fetchmail has been configured with a
386 short timeout (a minute or less), ships a long message (many
387 MBytes) to the local MTA, which then takes longer than timeout
388 to respond "OK", which it eventually will; that would mean the
389 mail gets delivered properly, but fetchmail cannot notice it and
390 will thus refetch this big message over and over again.
391 --plugin <command>
393 (Keyword: plugin)
394 The plugin option allows you to use an external program to es‐
395 tablish the TCP connection. This is useful if you want to use
396 ssh, or need some special firewalling setup. The program will
397 be looked up in $PATH and can optionally be passed the hostname
398 and port as arguments using "%h" and "%p" respectively (note
399 that the interpolation logic is rather primitive, and these to‐
400 kens must be bounded by whitespace or beginning of string or end
401 of string). Fetchmail will write to the plugin's stdin and read
402 from the plugin's stdout.
403 --plugout <command>
405 (Keyword: plugout)
406 Identical to the plugin option above, but this one is used for
407 the SMTP connections.
408 -r <name> | --folder <name>
410 (Keyword: folder[s])
411 Causes a specified non-default mail folder on the mailserver (or
412 comma-separated list of folders) to be retrieved. The syntax of
413 the folder name is server-dependent. This option is not avail‐
414 able under POP3, ETRN, or ODMR.
415 --tracepolls
417 (Keyword: tracepolls)
418 Tell fetchmail to poll trace information in the form 'polling
419 account %s' and 'folder %s' to the Received line it generates,
420 where the %s parts are replaced by the user's remote name, the
421 poll label, and the folder (mailbox) where available (the Re‐
422 ceived header also normally includes the server's true name).
423 This can be used to facilitate mail filtering based on the ac‐
424 count it is being received from. The folder information is writ‐
425 ten only since version 6.3.4.
426 --ssl (Keyword: ssl)
428 Causes the connection to the mail server to be encrypted via
429 SSL, by negotiating SSL directly after connecting (SSL-wrapped
430 mode). Please see the description of --sslproto below! More
431 information is available in the README.SSL file that ships with
432 fetchmail.
433 Note that even if this option is omitted, fetchmail may still
435 negotiate SSL in-band for POP3 or IMAP, through the STLS or
436 STARTTLS feature. You can use the --sslproto option to modify
437 that behavior.
438 If no port is specified, the connection is attempted to the well
440 known port of the SSL version of the base protocol. This is
441 generally a different port than the port used by the base proto‐
442 col. For IMAP, this is port 143 for the clear protocol and port
443 993 for the SSL secured protocol; for POP3, it is port 110 for
444 the clear text and port 995 for the encrypted variant.
445 If your system lacks the corresponding entries from /etc/ser‐
447 vices, see the --service option and specify the numeric port
448 number as given in the previous paragraph (unless your ISP had
449 directed you to different ports, which is uncommon however).
450 --sslcert <name>
452 (Keyword: sslcert)
453 For certificate-based client authentication. Some SSL encrypted
454 servers require client side keys and certificates for authenti‐
455 cation. In most cases, this is optional. This specifies the
456 location of the public key certificate to be presented to the
457 server at the time the SSL session is established. It is not
458 required (but may be provided) if the server does not require
459 it. It may be the same file as the private key (combined key
460 and certificate file) but this is not recommended. Also see
461 --sslkey below.
462 NOTE: If you use client authentication, the user name is fetched
464 from the certificate's CommonName and overrides the name set
465 with --user.
466 --sslkey <name>
468 (Keyword: sslkey)
469 Specifies the file name of the client side private SSL key.
470 Some SSL encrypted servers require client side keys and certifi‐
471 cates for authentication. In most cases, this is optional.
472 This specifies the location of the private key used to sign
473 transactions with the server at the time the SSL session is es‐
474 tablished. It is not required (but may be provided) if the
475 server does not require it. It may be the same file as the pub‐
476 lic key (combined key and certificate file) but this is not rec‐
477 ommended.
478 If a password is required to unlock the key, it will be prompted
480 for at the time just prior to establishing the session to the
481 server. This can cause some complications in daemon mode.
482 Also see --sslcert above.
484 --sslproto <value>
486 (Keyword: sslproto, NOTE: semantic changes since v6.4.0)
487 This option has a dual use, out of historic fetchmail behaviour.
488 It controls both the SSL/TLS protocol version and, if --ssl is
489 not specified, the STARTTLS behaviour (upgrading the protocol to
490 an SSL or TLS connection in-band). Some other options may how‐
491 ever make TLS mandatory.
492 Only if this option and --ssl are both missing for a poll, there will
494 be opportunistic TLS for POP3 and IMAP, where fetchmail will attempt to
495 upgrade to TLSv1 or newer.
496 Recognized values for --sslproto are given below. You should normally
498 chose one of the auto-negotiating options, i. e. 'auto' or one of the
499 options ending in a plus (+) character. Note that depending on OpenSSL
500 library version and configuration, some options cause run-time errors
501 because the requested SSL or TLS versions are not supported by the par‐
502 ticular installed OpenSSL library.
503 '', the empty string
505 Disable STARTTLS. If --ssl is given for the same server,
506 log an error and pretend that 'auto' had been used in‐
507 stead.
508 'auto' (default). Since v6.4.0. Require TLS. Auto-negotiate
510 TLSv1 or newer, disable SSLv3 downgrade. (fetchmail
511 6.3.26 and older have auto-negotiated all protocols that
512 their OpenSSL library supported, including the broken
513 SSLv3).
514 'SSL23'
516 see 'auto'.
517 'SSL3' Require SSLv3 exactly. SSLv3 is broken, not supported on
519 all systems, avoid it if possible. This will make fetch‐
520 mail negotiate SSLv3 only, and is the only way besides
521 'SSL3+' to have fetchmail 6.4.0 or newer permit SSLv3.
522 'SSL3+'
524 same as 'auto', but permit SSLv3 as well. This is the
525 only way besides 'SSL3' to have fetchmail 6.4.0 or newer
526 permit SSLv3.
527 'TLS1' Require TLSv1. This does not negotiate TLSv1.1 or newer,
529 and is discouraged. Replace by TLS1+ unless the latter
530 chokes your server.
531 'TLS1+'
533 Since v6.4.0. See 'auto'.
534 'TLS1.1'
536 Since v6.4.0. Require TLS v1.1 exactly.
537 'TLS1.1+'
539 Since v6.4.0. Require TLS. Auto-negotiate TLSv1.1 or
540 newer.
541 'TLS1.2'
543 Since v6.4.0. Require TLS v1.2 exactly.
544 'TLS1.2+'
546 Since v6.4.0. Require TLS. Auto-negotiate TLSv1.2 or
547 newer.
548 'TLS1.3'
550 Since v6.4.0. Require TLS v1.3 exactly.
551 'TLS1.3+'
553 Since v6.4.0. Require TLS. Auto-negotiate TLSv1.3 or
554 newer.
555 Unrecognized parameters
557 are treated the same as 'auto'.
558 NOTE: you should hardly ever need to use anything other than ''
560 (to force an unencrypted connection) or 'auto' (to enforce TLS).
561 --sslcertck
563 (Keyword: sslcertck, default enabled since v6.4.0)
564 --sslcertck causes fetchmail to require that SSL/TLS be used and
565 disconnect if it can not successfully negotiate SSL or TLS, or
566 if it cannot successfully verify and validate the certificate
567 and follow it to a trust anchor (or trusted root certificate).
568 The trust anchors are given as a set of local trusted certifi‐
569 cates (see the sslcertfile and sslcertpath options). If the
570 server certificate cannot be obtained or is not signed by one of
571 the trusted ones (directly or indirectly), fetchmail will dis‐
572 connect, regardless of the sslfingerprint option.
573 Note that CRL (certificate revocation lists) are only supported
575 in OpenSSL 0.9.7 and newer! Your system clock should also be
576 reasonably accurate when using this option.
577 --nosslcertck
579 (Keyword: no sslcertck, only in v6.4.X)
580 The opposite of --sslcertck, this is a discouraged option. It
581 permits fetchmail to continue connecting even if the server cer‐
582 tificate failed the verification checks. Should only be used
583 together with --sslfingerprint.
584 --sslcertfile <file>
586 (Keyword: sslcertfile, since v6.3.17)
587 Sets the file fetchmail uses to look up local certificates. The
588 default is empty. This can be given in addition to --sslcert‐
589 path below, and certificates specified in --sslcertfile will be
590 processed before those in --sslcertpath. The option can be used
591 in addition to --sslcertpath.
592 The file is a text file. It contains the concatenation of
594 trusted CA certificates in PEM format.
595 Note that using this option will suppress loading the default
597 SSL trusted CA certificates file unless you set the environment
598 variable FETCHMAIL_INCLUDE_DEFAULT_X509_CA_CERTS to a non-empty
599 value.
600 --sslcertpath <directory>
602 (Keyword: sslcertpath)
603 Sets the directory fetchmail uses to look up local certificates.
604 The default is your OpenSSL default directory. The directory
605 must be hashed the way OpenSSL expects it - every time you add
606 or modify a certificate in the directory, you need to use the
607 c_rehash tool (which comes with OpenSSL in the tools/ subdirec‐
608 tory). Also, after OpenSSL upgrades, you may need to run c_re‐
609 hash; particularly when upgrading from 0.9.X to 1.0.0.
610 This can be given in addition to --sslcertfile above, which see
612 for precedence rules.
613 Note that using this option will suppress adding the default SSL
615 trusted CA certificates directory unless you set the environment
616 variable FETCHMAIL_INCLUDE_DEFAULT_X509_CA_CERTS to a non-empty
617 value.
618 --sslcommonname <common name>
620 (Keyword: sslcommonname; since v6.3.9)
621 Use of this option is discouraged. Before using it, contact the
622 administrator of your upstream server and ask for a proper SSL
623 certificate to be used. If that cannot be attained, this option
624 can be used to specify the name (CommonName) that fetchmail ex‐
625 pects on the server certificate. A correctly configured server
626 will have this set to the hostname by which it is reached, and
627 by default fetchmail will expect as much. Use this option when
628 the CommonName is set to some other value, to avoid the "Server
629 CommonName mismatch" warning, and only if the upstream server
630 can't be made to use proper certificates.
631 --sslfingerprint <fingerprint>
633 (Keyword: sslfingerprint)
634 Specify the fingerprint of the server key (an MD5 hash of the
635 key) in hexadecimal notation with colons separating groups of
636 two digits. The letter hex digits must be in upper case. This is
637 the format that fetchmail uses to report the fingerprint when an
638 SSL connection is established. When this is specified, fetchmail
639 will compare the server key fingerprint with the given one, and
640 the connection will fail if they do not match, regardless of the
641 sslcertck setting. The connection will also fail if fetchmail
642 cannot obtain an SSL certificate from the server. This can be
643 used to prevent man-in-the-middle attacks, but the finger print
644 from the server must be obtained or verified over a secure chan‐
645 nel, and certainly not over the same Internet connection that
646 fetchmail would use.
647 Using this option will prevent printing certificate verification
649 errors as long as --nosslcertck is in effect.
650 To obtain the fingerprint of a certificate stored in the file
652 cert.pem, try:
653 openssl x509 -in cert.pem -noout -md5 -fingerprint
655 For details, see x509(1ssl).
657 Delivery Control Options
659 -S <hosts> | --smtphost <hosts>
660 (Keyword: smtp[host])
661 Specify a hunt list of hosts to forward mail to (one or more
662 hostnames, comma-separated). Hosts are tried in list order; the
663 first one that is up becomes the forwarding target for the cur‐
664 rent run. If this option is not specified, 'localhost' is used
665 as the default. Each hostname may have a port number following
666 the host name. The port number is separated from the host name
667 by a slash; the default port is "smtp". If you specify an abso‐
668 lute path name (beginning with a /), it will be interpreted as
669 the name of a UNIX socket accepting LMTP connections (such as is
670 supported by the Cyrus IMAP daemon) Example:
671 --smtphost server1,server2/2525,server3,/var/imap/socket/lmtp
673 This option can be used with ODMR, and will make fetchmail a re‐
675 lay between the ODMR server and SMTP or LMTP receiver.
676 WARNING: if you use address numeric IP addresses here, be sure
678 to use --smtpaddress or --smtpname (either of which see) with a
679 valid SMTP address literal!
680 --fetchdomains <hosts>
682 (Keyword: fetchdomains)
683 In ETRN or ODMR mode, this option specifies the list of domains
684 the server should ship mail for once the connection is turned
685 around. The default is the FQDN of the machine running fetch‐
686 mail.
687 -D <domain> | --smtpaddress <domain>
689 (Keyword: smtpaddress)
690 Specify the domain to be appended to addresses in RCPT TO lines
691 shipped to SMTP. When this is not specified, the name of the
692 SMTP server (as specified by --smtphost) is used for SMTP/LMTP
693 and 'localhost' is used for UNIX socket/BSMTP.
694 NOTE: if you intend to use numeric addresses, or so-called ad‐
696 dress literals per the SMTP standard, write them in proper SMTP
697 syntax, for instance --smtpaddress "[192.0.2.6]" or --smtpad‐
698 dress "[IPv6:2001:DB8::6]".
699 --smtpname <user@domain>
701 (Keyword: smtpname)
702 Specify the domain and user to be put in RCPT TO lines shipped
703 to SMTP. The default user is the current local user. Please
704 also see the NOTE about --smtpaddress and address literals
705 above.
706 -Z <nnn> | --antispam <nnn[, nnn]...>
708 (Keyword: antispam)
709 Specifies the list of numeric SMTP errors that are to be inter‐
710 preted as a spam-block response from the listener. A value of
711 -1 disables this option. For the command-line option, the list
712 values should be comma-separated. Note that the antispam values
713 only apply to "MAIL FROM" responses in the SMTP/LMTP dialogue,
714 but several MTAs (Postfix in its default configuration, qmail)
715 defer the anti-spam response code until after the RCPT TO. --an‐
716 tispam does not work in these circumstances. Also see --soft‐
717 bounce (default) and its inverse.
718 -m <command> | --mda <command>
720 (Keyword: mda)
721 This option lets fetchmail use a Message or Local Delivery Agent
722 (MDA or LDA) directly, rather than forward via SMTP or LMTP.
723 To avoid losing mail, use this option only with MDAs like mail‐
725 drop or MTAs like sendmail that exit with a nonzero status on
726 disk-full and other delivery errors; the nonzero status tells
727 fetchmail that delivery failed and prevents the message from be‐
728 ing deleted on the server.
729 If fetchmail is running as root, it sets its user id while de‐
731 livering mail through an MDA as follows: First, the FETCH‐
732 MAILUSER, LOGNAME, and USER environment variables are checked in
733 this order. The value of the first variable from his list that
734 is defined (even if it is empty!) is looked up in the system
735 user database. If none of the variables is defined, fetchmail
736 will use the real user id it was started with. If one of the
737 variables was defined, but the user stated there isn't found,
738 fetchmail continues running as root, without checking remaining
739 variables on the list. Practically, this means that if you run
740 fetchmail as root (not recommended), it is most useful to define
741 the FETCHMAILUSER environment variable to set the user that the
742 MDA should run as. Some MDAs (such as maildrop) are designed to
743 be setuid root and setuid to the recipient's user id, so you
744 don't lose functionality this way even when running fetchmail as
745 unprivileged user. Check the MDA's manual for details.
746 Some possible MDAs are "/usr/sbin/sendmail -i -f %F -- %T"
748 (Note: some several older or vendor sendmail versions mistake --
749 for an address, rather than an indicator to mark the end of the
750 option arguments), "/usr/bin/deliver" and "/usr/bin/maildrop -d
751 %T". Local delivery addresses will be inserted into the MDA
752 command wherever you place a %T; the mail message's From address
753 will be inserted where you place an %F.
754 Do NOT enclose the %F or %T string in single quotes! For both
756 %T and %F, fetchmail encloses the addresses in single quotes
757 ('), after removing any single quotes they may contain, before
758 the MDA command is passed to the shell.
759 Do NOT use an MDA invocation that dispatches on the contents of
761 To/Cc/Bcc, like "sendmail -i -t" or "qmail-inject", it will cre‐
762 ate mail loops and bring the just wrath of many postmasters down
763 upon your head. This is one of the most frequent configuration
764 errors!
765 Also, do not try to combine multidrop mode with an MDA such as
767 maildrop that can only accept one address, unless your upstream
768 stores one copy of the message per recipient and transports the
769 envelope recipient in a header; you will lose mail.
770 The well-known procmail(1) package is very hard to configure
772 properly, it has a very nasty "fall through to the next rule"
773 behavior on delivery errors (even temporary ones, such as out of
774 disk space if another user's mail daemon copies the mailbox
775 around to purge old messages), so your mail will end up in the
776 wrong mailbox sooner or later. The proper procmail configuration
777 is outside the scope of this document. Using maildrop(1) is usu‐
778 ally much easier, and many users find the filter syntax used by
779 maildrop easier to understand.
780 Finally, we strongly advise that you do not use qmail-inject.
782 The command line interface is non-standard without providing
783 benefits for typical use, and fetchmail makes no attempts to ac‐
784 commodate qmail-inject's deviations from the standard. Some of
785 qmail-inject's command-line and environment options are actually
786 dangerous and can cause broken threads, non-detected duplicate
787 messages and forwarding loops.
788 --lmtp (Keyword: lmtp)
791 Cause delivery via LMTP (Local Mail Transfer Protocol). A ser‐
792 vice host and port must be explicitly specified on each host in
793 the smtphost hunt list (see above) if this option is selected;
794 the default port 25 will (in accordance with RFC 2033) not be
795 accepted.
796 --bsmtp <filename>
798 (Keyword: bsmtp)
799 Append fetched mail to a BSMTP file. This simply contains the
800 SMTP commands that would normally be generated by fetchmail when
801 passing mail to an SMTP listener daemon.
802 An argument of '-' causes the SMTP batch to be written to stan‐
804 dard output, which is of limited use: this only makes sense for
805 debugging, because fetchmail's regular output is interspersed on
806 the same channel, so this isn't suitable for mail delivery. This
807 special mode may be removed in a later release.
808 Note that fetchmail's reconstruction of MAIL FROM and RCPT TO
810 lines is not guaranteed correct; the caveats discussed under THE
811 USE AND ABUSE OF MULTIDROP MAILBOXES below apply. This mode has
812 precedence before --mda and SMTP/LMTP.
813 --bad-header {reject|accept}
815 (Keyword: bad-header; since v6.3.15)
816 Specify how fetchmail is supposed to treat messages with bad
817 headers, i. e. headers with bad syntax. Traditionally, fetchmail
818 has rejected such messages, but some distributors modified
819 fetchmail to accept them. You can now configure fetchmail's be‐
820 haviour per server.
821 Resource Limit Control Options
824 -l <maxbytes> | --limit <maxbytes>
825 (Keyword: limit)
826 Takes a maximum octet size argument, where 0 is the default and
827 also the special value designating "no limit". If nonzero, mes‐
828 sages larger than this size will not be fetched and will be left
829 on the server (in foreground sessions, the progress messages
830 will note that they are "oversized"). If the fetch protocol
831 permits (in particular, under IMAP or POP3 without the fetchall
832 option) the message will not be marked seen.
833 An explicit --limit of 0 overrides any limits set in your run
835 control file. This option is intended for those needing to
836 strictly control fetch time due to expensive and variable phone
837 rates.
838 Combined with --limitflush, it can be used to delete oversized
840 messages waiting on a server. In daemon mode, oversize notifi‐
841 cations are mailed to the calling user (see the --warnings op‐
842 tion). This option does not work with ETRN or ODMR.
843 -w <interval> | --warnings <interval>
845 (Keyword: warnings)
846 Takes an interval in seconds. When you call fetchmail with a
847 'limit' option in daemon mode, this controls the interval at
848 which warnings about oversized messages are mailed to the call‐
849 ing user (or the user specified by the 'postmaster' option).
850 One such notification is always mailed at the end of the the
851 first poll that the oversized message is detected. Thereafter,
852 re-notification is suppressed until after the warning interval
853 elapses (it will take place at the end of the first following
854 poll).
855 -b <count> | --batchlimit <count>
857 (Keyword: batchlimit)
858 Specify the maximum number of messages that will be shipped to
859 an SMTP listener before the connection is deliberately torn down
860 and rebuilt (defaults to 0, meaning no limit). An explicit
861 --batchlimit of 0 overrides any limits set in your run control
862 file. While sendmail(8) normally initiates delivery of a mes‐
863 sage immediately after receiving the message terminator, some
864 SMTP listeners are not so prompt. MTAs like smail(8) may wait
865 till the delivery socket is shut down to deliver. This may pro‐
866 duce annoying delays when fetchmail is processing very large
867 batches. Setting the batch limit to some nonzero size will pre‐
868 vent these delays. This option does not work with ETRN or ODMR.
869 -B <number> | --fetchlimit <number>
871 (Keyword: fetchlimit)
872 Limit the number of messages accepted from a given server in a
873 single poll. By default there is no limit. An explicit --fetch‐
874 limit of 0 overrides any limits set in your run control file.
875 This option does not work with ETRN or ODMR.
876 --fetchsizelimit <number>
878 (Keyword: fetchsizelimit)
879 Limit the number of sizes of messages accepted from a given
880 server in a single transaction. This option is useful in reduc‐
881 ing the delay in downloading the first mail when there are too
882 many mails in the mailbox. By default, the limit is 100. If
883 set to 0, sizes of all messages are downloaded at the start.
884 This option does not work with ETRN or ODMR. For POP3, the only
885 valid non-zero value is 1.
886 --fastuidl <number>
888 (Keyword: fastuidl)
889 Do a binary instead of linear search for the first unseen UID.
890 Binary search avoids downloading the UIDs of all mails. This
891 saves time (especially in daemon mode) where downloading the
892 same set of UIDs in each poll is a waste of bandwidth. The num‐
893 ber 'n' indicates how rarely a linear search should be done. In
894 daemon mode, linear search is used once followed by binary
895 searches in 'n-1' polls if 'n' is greater than 1; binary search
896 is always used if 'n' is 1; linear search is always used if 'n'
897 is 0. In non-daemon mode, binary search is used if 'n' is 1;
898 otherwise linear search is used. The default value of 'n' is 4.
899 This option works with POP3 only.
900 -e <count> | --expunge <count>
902 (Keyword: expunge)
903 Arrange for deletions to be made final after a given number of
904 messages. Under POP2 or POP3, fetchmail cannot make deletions
905 final without sending QUIT and ending the session -- with this
906 option on, fetchmail will break a long mail retrieval session
907 into multiple sub-sessions, sending QUIT after each sub-session.
908 This is a good defense against line drops on POP3 servers. Un‐
909 der IMAP, fetchmail normally issues an EXPUNGE command after
910 each deletion in order to force the deletion to be done immedi‐
911 ately. This is safest when your connection to the server is
912 flaky and expensive, as it avoids resending duplicate mail after
913 a line hit. However, on large mailboxes the overhead of re-in‐
914 dexing after every message can slam the server pretty hard, so
915 if your connection is reliable it is good to do expunges less
916 frequently. Also note that some servers enforce a delay of a
917 few seconds after each quit, so fetchmail may not be able to get
918 back in immediately after an expunge -- you may see "lock busy"
919 errors if this happens. If you specify this option to an integer
920 N, it tells fetchmail to only issue expunges on every Nth
921 delete. An argument of zero suppresses expunges entirely (so no
922 expunges at all will be done until the end of run). This option
923 does not work with ETRN or ODMR.
924 Authentication Options
927 -u <name> | --user <name> | --username <name>
928 (Keyword: user[name])
929 Specifies the user identification to be used when logging in to
930 the mailserver. The appropriate user identification is both
931 server and user-dependent. The default is your login name on
932 the client machine that is running fetchmail. See USER AUTHEN‐
933 TICATION below for a complete description.
934 -I <specification> | --interface <specification>
936 (Keyword: interface)
937 Require that a specific interface device be up and have a spe‐
938 cific local or remote IPv4 (IPv6 is not supported by this option
939 yet) address (or range) before polling. Frequently fetchmail is
940 used over a transient point-to-point TCP/IP link established di‐
941 rectly to a mailserver via SLIP or PPP. That is a relatively
942 secure channel. But when other TCP/IP routes to the mailserver
943 exist (e.g. when the link is connected to an alternate ISP),
944 your username and password may be vulnerable to snooping (espe‐
945 cially when daemon mode automatically polls for mail, shipping a
946 clear password over the net at predictable intervals). The
947 --interface option may be used to prevent this. When the speci‐
948 fied link is not up or is not connected to a matching IP ad‐
949 dress, polling will be skipped. The format is:
950 interface/iii.iii.iii.iii[/mmm.mmm.mmm.mmm]
952 The field before the first slash is the interface name (i.e.
954 sl0, ppp0 etc.). The field before the second slash is the ac‐
955 ceptable IP address. The field after the second slash is a mask
956 which specifies a range of IP addresses to accept. If no mask
957 is present 255.255.255.255 is assumed (i.e. an exact match).
958 This option is currently only supported under Linux and FreeBSD.
959 Please see the monitor section for below for FreeBSD specific
960 information.
961 Note that this option may be removed from a future fetchmail
963 version.
964 -M <interface> | --monitor <interface>
966 (Keyword: monitor)
967 Daemon mode can cause transient links which are automatically
968 taken down after a period of inactivity (e.g. PPP links) to re‐
969 main up indefinitely. This option identifies a system TCP/IP
970 interface to be monitored for activity. After each poll inter‐
971 val, if the link is up but no other activity has occurred on the
972 link, then the poll will be skipped. However, when fetchmail is
973 woken up by a signal, the monitor check is skipped and the poll
974 goes through unconditionally. This option is currently only
975 supported under Linux and FreeBSD. For the monitor and inter‐
976 face options to work for non root users under FreeBSD, the
977 fetchmail binary must be installed SGID kmem. This would be a
978 security hole, but fetchmail runs with the effective GID set to
979 that of the kmem group only when interface data is being col‐
980 lected.
981 Note that this option may be removed from a future fetchmail
983 version.
984 --auth <type>
986 (Keyword: auth[enticate])
987 This option permits you to specify an authentication type (see
988 USER AUTHENTICATION below for details). The possible values are
989 any, password, kerberos_v5, kerberos (or, for excruciating ex‐
990 actness, kerberos_v4), gssapi, cram-md5, otp, ntlm, msn (only
991 for POP3), external (only IMAP) and ssh. When any (the default)
992 is specified, fetchmail tries first methods that don't require a
993 password (EXTERNAL, GSSAPI, KERBEROS IV, KERBEROS 5); then it
994 looks for methods that mask your password (CRAM-MD5, NTLM, X-OTP
995 - note that MSN is only supported for POP3, but not autoprobed);
996 and only if the server doesn't support any of those will it ship
997 your password en clair. Other values may be used to force vari‐
998 ous authentication methods (ssh suppresses authentication and is
999 thus useful for IMAP PREAUTH). (external suppresses authentica‐
1000 tion and is thus useful for IMAP EXTERNAL). Any value other
1001 than password, cram-md5, ntlm, msn or otp suppresses fetchmail's
1002 normal inquiry for a password. Specify ssh when you are using
1003 an end-to-end secure connection such as an ssh tunnel; specify
1004 external when you use TLS with client authentication and specify
1005 gssapi or kerberos_v4 if you are using a protocol variant that
1006 employs GSSAPI or K4. Choosing KPOP protocol automatically se‐
1007 lects Kerberos authentication. This option does not work with
1008 ETRN. GSSAPI service names are in line with RFC-2743 and IANA
1009 registrations, see Generic Security Service Application Program
1010 Interface (GSSAPI)/Kerberos/Simple Authentication and Security
1011 Layer (SASL) Service Names ⟨https://www.iana.org/assignments/
1012 gssapi-service-names/⟩.
1013 Miscellaneous Options
1015 -f <pathname> | --fetchmailrc <pathname>
1016 Specify a non-default name for the ~/.fetchmailrc run control
1017 file. The pathname argument must be either "-" (a single dash,
1018 meaning to read the configuration from standard input) or a
1019 filename. Unless the --version option is also on, a named file
1020 argument must have permissions no more open than 0700
1021 (u=rwx,g=,o=) or else be /dev/null.
1022 -i <pathname> | --idfile <pathname>
1024 (Keyword: idfile)
1025 Specify an alternate name for the .fetchids file used to save
1026 message UIDs. NOTE: since fetchmail 6.3.0, write access to the
1027 directory containing the idfile is required, as fetchmail writes
1028 a temporary file and renames it into the place of the real id‐
1029 file only if the temporary file has been written successfully.
1030 This avoids the truncation of idfiles when running out of disk
1031 space.
1032 --pidfile <pathname>
1034 (Keyword: pidfile; since fetchmail v6.3.4)
1035 Override the default location of the PID file that is used as a
1036 lock file. Default: see "ENVIRONMENT" below. Note that many
1037 places in the code and documentation, the term "lock file" is
1038 used. This file contains the process ID of the running fetch‐
1039 mail on the first line and potentially the daemon interval on a
1040 second line.
1041 -n | --norewrite
1043 (Keyword: no rewrite)
1044 Normally, fetchmail edits RFC-822 address headers (To, From, Cc,
1045 Bcc, and Reply-To) in fetched mail so that any mail IDs local to
1046 the server are expanded to full addresses (@ and the mailserver
1047 hostname are appended). This enables replies on the client to
1048 get addressed correctly (otherwise your mailer might think they
1049 should be addressed to local users on the client machine!).
1050 This option disables the rewrite. (This option is provided to
1051 pacify people who are paranoid about having an MTA edit mail
1052 headers and want to know they can prevent it, but it is gener‐
1053 ally not a good idea to actually turn off rewrite.) When using
1054 ETRN or ODMR, the rewrite option is ineffective.
1055 -E <line> | --envelope <line>
1057 (Keyword: envelope; Multidrop only)
1058 In the configuration file, an enhanced syntax is used:
1059 envelope [<count>] <line>
1060 This option changes the header fetchmail assumes will carry a
1062 copy of the mail's envelope address. Normally this is 'X-Enve‐
1063 lope-To'. Other typically found headers to carry envelope in‐
1064 formation are 'X-Original-To' and 'Delivered-To'. Now, since
1065 these headers are not standardized, practice varies. See the
1066 discussion of multidrop address handling below. As a special
1067 case, 'envelope "Received"' enables parsing of sendmail-style
1068 Received lines. This is the default, but discouraged because it
1069 is not fully reliable.
1070 Note that fetchmail expects the Received-line to be in a spe‐
1072 cific format: It must contain "by host for address", where host
1073 must match one of the mailserver names that fetchmail recognizes
1074 for the account in question.
1075 The optional count argument (only available in the configuration
1077 file) determines how many header lines of this kind are skipped.
1078 A count of 1 means: skip the first, take the second. A count of
1079 2 means: skip the first and second, take the third, and so on.
1080 -Q <prefix> | --qvirtual <prefix>
1082 (Keyword: qvirtual; Multidrop only)
1083 The string prefix assigned to this option will be removed from
1084 the user name found in the header specified with the envelope
1085 option (before doing multidrop name mapping or localdomain
1086 checking, if either is applicable). This option is useful if you
1087 are using fetchmail to collect the mail for an entire domain and
1088 your ISP (or your mail redirection provider) is using qmail.
1089 One of the basic features of qmail is the Delivered-To: message
1090 header. Whenever qmail delivers a message to a local mailbox it
1091 puts the username and hostname of the envelope recipient on this
1092 line. The major reason for this is to prevent mail loops. To
1093 set up qmail to batch mail for a disconnected site the ISP-mail‐
1094 host will have normally put that site in its 'Virtualhosts' con‐
1095 trol file so it will add a prefix to all mail addresses for this
1096 site. This results in mail sent to 'username@userhost.user‐
1097 dom.dom.com' having a Delivered-To: line of the form:
1098 Delivered-To: mbox-userstr-username@userhost.example.com
1100 The ISP can make the 'mbox-userstr-' prefix anything they choose
1102 but a string matching the user host name is likely. By using
1103 the option 'envelope Delivered-To:' you can make fetchmail reli‐
1104 ably identify the original envelope recipient, but you have to
1105 strip the 'mbox-userstr-' prefix to deliver to the correct user.
1106 This is what this option is for.
1107 --configdump
1109 Parse the ~/.fetchmailrc file, interpret any command-line op‐
1110 tions specified, and dump a configuration report to standard
1111 output. The configuration report is a data structure assignment
1112 in the language Python. This option is meant to be used with an
1113 interactive ~/.fetchmailrc editor like fetchmailconf, written in
1114 Python.
1115 -y | --yydebug
1117 Enables parser debugging, this option is meant to be used by de‐
1118 velopers only.
1119 Removed Options
1122 -T | --netsec
1123 Removed before version 6.3.0, the required underlying inet6_apps
1124 library had been discontinued and is no longer available.
1125
1128 All modes except ETRN require authentication of the client to the
1129 server. Normal user authentication in fetchmail is very much like the
1130 authentication mechanism of ftp(1). The correct user-id and password
1131 depend upon the underlying security system at the mailserver.
1132 If the mailserver is a Unix machine on which you have an ordinary user
1134 account, your regular login name and password are used with fetchmail.
1135 If you use the same login name on both the server and the client ma‐
1136 chines, you needn't worry about specifying a user-id with the -u option
1137 -- the default behavior is to use your login name on the client machine
1138 as the user-id on the server machine. If you use a different login
1139 name on the server machine, specify that login name with the -u option.
1140 e.g. if your login name is 'jsmith' on a machine named 'mailgrunt', you
1141 would start fetchmail as follows:
1142 fetchmail -u jsmith mailgrunt
1144 The default behavior of fetchmail is to prompt you for your mailserver
1146 password before the connection is established. This is the safest way
1147 to use fetchmail and ensures that your password will not be compro‐
1148 mised. You may also specify your password in your ~/.fetchmailrc file.
1149 This is convenient when using fetchmail in daemon mode or with scripts.
1150 Using netrc files
1153 If you do not specify a password, and fetchmail cannot extract one from
1154 your ~/.fetchmailrc file, it will look for a ~/.netrc file in your home
1155 directory before requesting one interactively; if an entry matching the
1156 mailserver is found in that file, the password will be used. Fetchmail
1157 first looks for a match on poll name; if it finds none, it checks for a
1158 match on via name. See the ftp(1) man page for details of the syntax
1159 of the ~/.netrc file. To show a practical example, a .netrc might look
1160 like this:
1161 machine hermes.example.org
1163 login joe
1164 password topsecret
1165 You can repeat this block with different user information if you need
1167 to provide more than one password.
1168 This feature may allow you to avoid duplicating password information in
1170 more than one file.
1171 On mailservers that do not provide ordinary user accounts, your user-id
1173 and password are usually assigned by the server administrator when you
1174 apply for a mailbox on the server. Contact your server administrator
1175 if you don't know the correct user-id and password for your mailbox ac‐
1176 count.
1177 Secure Socket Layers (SSL) and Transport Layer Security (TLS)
1180 All retrieval protocols can use SSL or TLS wrapping for the transport.
1181 Additionally, POP3 and IMAP retrival can also negotiate SSL/TLS by
1182 means of STARTTLS (or STLS).
1183 Note that fetchmail currently uses the OpenSSL library, which is se‐
1185 verely underdocumented, so failures may occur just because the program‐
1186 mers are not aware of OpenSSL's requirement of the day. For instance,
1187 since v6.3.16, fetchmail calls OpenSSL_add_all_algorithms(), which is
1188 necessary to support certificates using SHA256 on OpenSSL 0.9.8 -- this
1189 information is deeply hidden in the documentation and not at all obvi‐
1190 ous. Please do not hesitate to report subtle SSL failures.
1191 You can access SSL encrypted services by specifying the options start‐
1193 ing with --ssl, such as --ssl, --sslproto, --sslcertck, and others.
1194 You can also do this using the corresponding user options in the
1195 .fetchmailrc file. Some services, such as POP3 and IMAP, have differ‐
1196 ent well known ports defined for the SSL encrypted services. The en‐
1197 crypted ports will be selected automatically when SSL is enabled and no
1198 explicit port is specified. Also, the --sslcertck command line or
1199 sslcertck run control file option should be used to force strict cer‐
1200 tificate checking with older fetchmail versions - see below.
1201 If SSL is not configured, fetchmail will usually opportunistically try
1203 to use STARTTLS. STARTTLS can be enforced by using --sslproto auto and
1204 defeated by using --sslproto ''. TLS connections use the same port as
1205 the unencrypted version of the protocol and negotiate TLS via special
1206 command. The --sslcertck command line or sslcertck run control file op‐
1207 tion should be used to force strict certificate checking - see below.
1208 --sslcertck is recommended: When connecting to an SSL or TLS encrypted
1210 server, the server presents a certificate to the client for validation.
1211 The certificate is checked to verify that the common name in the cer‐
1212 tificate matches the name of the server being contacted and that the
1213 effective and expiration dates in the certificate indicate that it is
1214 currently valid. If any of these checks fail, a warning message is
1215 printed, but the connection continues. The server certificate does not
1216 need to be signed by any specific Certifying Authority and may be a
1217 "self-signed" certificate. If the --sslcertck command line option or
1218 sslcertck run control file option is used, fetchmail will instead abort
1219 if any of these checks fail, because it must assume that there is a
1220 man-in-the-middle attack in this scenario, hence fetchmail must not ex‐
1221 pose cleartext passwords. Use of the sslcertck or --sslcertck option is
1222 therefore advised; it has become the default in fetchmail 6.4.0.
1223 Some SSL encrypted servers may request a client side certificate. A
1225 client side public SSL certificate and private SSL key may be speci‐
1226 fied. If requested by the server, the client certificate is sent to
1227 the server for validation. Some servers may require a valid client
1228 certificate and may refuse connections if a certificate is not provided
1229 or if the certificate is not valid. Some servers may require client
1230 side certificates be signed by a recognized Certifying Authority. The
1231 format for the key files and the certificate files is that required by
1232 the underlying SSL libraries (OpenSSL in the general case).
1233 A word of care about the use of SSL: While above mentioned setup with
1235 self-signed server certificates retrieved over the wires can protect
1236 you from a passive eavesdropper, it doesn't help against an active at‐
1237 tacker. It's clearly an improvement over sending the passwords in
1238 clear, but you should be aware that a man-in-the-middle attack is triv‐
1239 ially possible (in particular with tools such as dsniff ⟨https://
1240 monkey.org/~dugsong/dsniff/⟩, ). Use of strict certificate checking
1241 with a certification authority recognized by server and client, or per‐
1242 haps of an SSH tunnel (see below for some examples) is preferable if
1243 you care seriously about the security of your mailbox and passwords.
1244
1247 Early versions of POP3 (RFC1081, RFC1225) supported a crude form of in‐
1248 dependent authentication using the .rhosts file on the mailserver side.
1249 Under this RPOP variant, a fixed per-user ID equivalent to a password
1250 was sent in clear over a link to a reserved port, with the command RPOP
1251 rather than PASS to alert the server that it should do special check‐
1252 ing. RPOP is supported by fetchmail (you can specify 'protocol RPOP'
1253 to have the program send 'RPOP' rather than 'PASS') but its use is
1254 strongly discouraged, and support will be removed from a future fetch‐
1255 mail version. This facility was vulnerable to spoofing and was with‐
1256 drawn in RFC1460.
1257 RFC1460 introduced APOP authentication. In this variant of POP3, you
1259 register an APOP password on your server host (on some servers, the
1260 program to do this is called popauth(8)). You put the same password in
1261 your ~/.fetchmailrc file. Each time fetchmail logs in, it sends an MD5
1262 hash of your password and the server greeting time to the server, which
1263 can verify it by checking its authorization database.
1264 Note that APOP is no longer considered resistant against man-in-the-
1266 middle attacks.
1267 RETR or TOP
1270 fetchmail makes some efforts to make the server believe messages had
1271 not been retrieved, by using the TOP command with a large number of
1272 lines when possible. TOP is a command that retrieves the full header
1273 and a fetchmail-specified amount of body lines. It is optional and
1274 therefore not implemented by all servers, and some are known to imple‐
1275 ment it improperly. On many servers however, the RETR command which re‐
1276 trieves the full message with header and body, sets the "seen" flag
1277 (for instance, in a web interface), whereas the TOP command does not do
1278 that.
1279 fetchmail will always use the RETR command if "fetchall" is set.
1281 fetchmail will also use the RETR command if "keep" is set and "uidl" is
1282 unset. Finally, fetchmail will use the RETR command on Maillennium
1283 POP3/PROXY servers (used by Comcast) to avoid a deliberate TOP misin‐
1284 terpretation in this server that causes message corruption.
1285 In all other cases, fetchmail will use the TOP command. This implies
1287 that in "keep" setups, "uidl" must be set if "TOP" is desired.
1288 Note that this description is true for the current version of fetch‐
1290 mail, but the behavior may change in future versions. In particular,
1291 fetchmail may prefer the RETR command because the TOP command causes
1292 much grief on some servers and is only optional.
1293
1295 If your fetchmail was built with Kerberos support and you specify Ker‐
1296 beros authentication (either with --auth or the .fetchmailrc option au‐
1297 thenticate kerberos_v4) it will try to get a Kerberos ticket from the
1298 mailserver at the start of each query. Note: if either the pollname or
1299 via name is 'hesiod', fetchmail will try to use Hesiod to look up the
1300 mailserver.
1301 If you use POP3 or IMAP with GSSAPI authentication, fetchmail will ex‐
1303 pect the server to have RFC1731- or RFC1734-conforming GSSAPI capabil‐
1304 ity, and will use it. Currently this has only been tested over Ker‐
1305 beros V, so you're expected to already have a ticket-granting ticket.
1306 You may pass a username different from your principal name using the
1307 standard --user command or by the .fetchmailrc option user.
1308 If your IMAP daemon returns the PREAUTH response in its greeting line,
1310 fetchmail will notice this and skip the normal authentication step.
1311 This can be useful, e.g. if you start imapd explicitly using ssh. In
1312 this case you can declare the authentication value 'ssh' on that site
1313 entry to stop .fetchmail from asking you for a password when it starts
1314 up.
1315 If you use client authentication with TLS1 and your IMAP daemon returns
1317 the AUTH=EXTERNAL response, fetchmail will notice this and will use the
1318 authentication shortcut and will not send the passphrase. In this case
1319 you can declare the authentication value 'external'
1320 on that site to stop fetchmail from asking you for a password when it
1321 starts up.
1322 If you are using POP3, and the server issues a one-time-password chal‐
1324 lenge conforming to RFC1938, fetchmail will use your password as a pass
1325 phrase to generate the required response. This avoids sending secrets
1326 over the net unencrypted.
1327 Compuserve's RPA authentication is supported. If you compile in the
1329 support, fetchmail will try to perform an RPA pass-phrase authentica‐
1330 tion instead of sending over the password en clair if it detects "@com‐
1331 puserve.com" in the hostname.
1332 If you are using IMAP, Microsoft's NTLM authentication (used by Micro‐
1334 soft Exchange) is supported. If you compile in the support, fetchmail
1335 will try to perform an NTLM authentication (instead of sending over the
1336 password en clair) whenever the server returns AUTH=NTLM in its capa‐
1337 bility response. Specify a user option value that looks like 'user@do‐
1338 main': the part to the left of the @ will be passed as the username and
1339 the part to the right as the NTLM domain.
1340 ESMTP AUTH
1343 fetchmail also supports authentication to the ESMTP server on the
1344 client side according to RFC 2554. You can specify a name/password
1345 pair to be used with the keywords 'esmtpname' and 'esmtppassword'; the
1346 former defaults to the username of the calling user.
1347
1350 Introducing the daemon mode
1351 In daemon mode, fetchmail puts itself into the background and runs for‐
1352 ever, querying each specified host and then sleeping for a given
1353 polling interval.
1354 Starting the daemon mode
1356 There are several ways to make fetchmail work in daemon mode. On the
1357 command line, --daemon <interval> or -d <interval> option runs fetch‐
1358 mail in daemon mode. You must specify a numeric argument which is a
1359 polling interval (time to wait after completing a whole poll cycle with
1360 the last server and before starting the next poll cycle with the first
1361 server) in seconds.
1362 Example: simply invoking
1364 fetchmail -d 900
1366 will, therefore, poll all the hosts described in your ~/.fetchmailrc
1368 file (except those explicitly excluded with the 'skip' verb) a bit less
1369 often than once every 15 minutes (exactly: 15 minutes + time that the
1370 poll takes).
1371 It is also possible to set a polling interval in your ~/.fetchmailrc
1373 file by saying 'set daemon <interval>', where <interval> is an integer
1374 number of seconds. If you do this, fetchmail will always start in dae‐
1375 mon mode unless you override it with the command-line option --daemon 0
1376 or -d0.
1377 Only one daemon process is permitted per user; in daemon mode, fetch‐
1379 mail sets up a per-user lockfile to guarantee this. (You can however
1380 cheat and set the FETCHMAILHOME environment variable to overcome this
1381 setting, but in that case, it is your responsibility to make sure you
1382 aren't polling the same server with two processes at the same time.)
1383 Awakening the background daemon
1385 Normally, calling fetchmail with a daemon in the background sends a
1386 wake-up signal to the daemon and quits without output. The background
1387 daemon then starts its next poll cycle immediately. The wake-up sig‐
1388 nal, SIGUSR1, can also be sent manually. The wake-up action also clears
1389 any 'wedged' flags indicating that connections have wedged due to
1390 failed authentication or multiple timeouts.
1391 Terminating the background daemon
1393 The option -q or --quit will kill a running daemon process instead of
1394 waking it up (if there is no such process, fetchmail will notify you).
1395 If the --quit option appears last on the command line, fetchmail will
1396 kill the running daemon process and then quit. Otherwise, fetchmail
1397 will first kill a running daemon process and then continue running with
1398 the other options.
1399 Useful options for daemon mode
1401 The -L <filename> or --logfile <filename> option (keyword: set logfile)
1402 is only effective when fetchmail is detached and in daemon mode. Note
1403 that the logfile must exist before fetchmail is run, you can use the
1404 touch(1) command with the filename as its sole argument to create it.
1405 This option allows you to redirect status messages into a specified
1406 logfile (follow the option with the logfile name). The logfile is
1407 opened for append, so previous messages aren't deleted. This is pri‐
1408 marily useful for debugging configurations. Note that fetchmail does
1409 not detect if the logfile is rotated, the logfile is only opened once
1410 when fetchmail starts. You need to restart fetchmail after rotating the
1411 logfile and before compressing it (if applicable).
1412 The --syslog option (keyword: set syslog) allows you to redirect status
1414 and error messages emitted to the syslog(3) system daemon if available.
1415 Messages are logged with an id of fetchmail, the facility LOG_MAIL, and
1416 priorities LOG_ERR, LOG_ALERT or LOG_INFO. This option is intended for
1417 logging status and error messages which indicate the status of the dae‐
1418 mon and the results while fetching mail from the server(s). Error mes‐
1419 sages for command line options and parsing the .fetchmailrc file are
1420 still written to stderr, or to the specified log file. The --nosyslog
1421 option turns off use of syslog(3), assuming it's turned on in the
1422 ~/.fetchmailrc file. This option is overridden, in certain situations,
1423 by --logfile (which see).
1424 The -N or --nodetach option suppresses backgrounding and detachment of
1426 the daemon process from its control terminal. This is useful for de‐
1427 bugging or when fetchmail runs as the child of a supervisor process
1428 such as init(8) or Gerrit Pape's runit(8). Note that this also causes
1429 the logfile option to be ignored.
1430 Note that while running in daemon mode polling a POP2 or IMAP2bis
1432 server, transient errors (such as DNS failures or sendmail delivery re‐
1433 fusals) may force the fetchall option on for the duration of the next
1434 polling cycle. This is a robustness feature. It means that if a mes‐
1435 sage is fetched (and thus marked seen by the mailserver) but not deliv‐
1436 ered locally due to some transient error, it will be re-fetched during
1437 the next poll cycle. (The IMAP logic doesn't delete messages until
1438 they're delivered, so this problem does not arise.)
1439 If you touch or change the ~/.fetchmailrc file while fetchmail is run‐
1441 ning in daemon mode, this will be detected at the beginning of the next
1442 poll cycle. When a changed ~/.fetchmailrc is detected, fetchmail
1443 rereads it and restarts from scratch (using exec(2); no state informa‐
1444 tion is retained in the new instance). Note that if fetchmail needs to
1445 query for passwords, of that if you break the ~/.fetchmailrc file's
1446 syntax, the new instance will softly and silently vanish away on
1447 startup.
1448
1451 The --postmaster <name> option (keyword: set postmaster) specifies the
1452 last-resort username to which multidrop mail is to be forwarded if no
1453 matching local recipient can be found. It is also used as destination
1454 of undeliverable mail if the 'bouncemail' global option is off and ad‐
1455 ditionally for spam-blocked mail if the 'bouncemail' global option is
1456 off and the 'spambounce' global option is on. This option defaults to
1457 the user who invoked fetchmail. If the invoking user is root, then the
1458 default of this option is the user 'postmaster'. Setting postmaster to
1459 the empty string causes such mail as described above to be discarded -
1460 this however is usually a bad idea. See also the description of the
1461 'FETCHMAILUSER' environment variable in the ENVIRONMENT section below.
1462 The --nobounce behaves like the "set no bouncemail" global option,
1464 which see.
1465 The --invisible option (keyword: set invisible) tries to make fetchmail
1467 invisible. Normally, fetchmail behaves like any other MTA would -- it
1468 generates a Received header into each message describing its place in
1469 the chain of transmission, and tells the MTA it forwards to that the
1470 mail came from the machine fetchmail itself is running on. If the in‐
1471 visible option is on, the Received header is suppressed and fetchmail
1472 tries to spoof the MTA it forwards to into thinking it came directly
1473 from the mailserver host.
1474 The --showdots option (keyword: set showdots) forces fetchmail to show
1476 progress dots even if the output goes to a file or fetchmail is not in
1477 verbose mode. Fetchmail shows the dots by default when run in --ver‐
1478 bose mode and output goes to console. This option is ignored in
1479 --silent mode.
1480 By specifying the --tracepolls option, you can ask fetchmail to add in‐
1482 formation to the Received header on the form "polling {label} account
1483 {user}", where {label} is the account label (from the specified rcfile,
1484 normally ~/.fetchmailrc) and {user} is the username which is used to
1485 log on to the mail server. This header can be used to make filtering
1486 email where no useful header information is available and you want mail
1487 from different accounts sorted into different mailboxes (this could,
1488 for example, occur if you have an account on the same server running a
1489 mailing list, and are subscribed to the list using that account). The
1490 default is not adding any such header. In .fetchmailrc, this is called
1491 'tracepolls'.
1492
1495 The protocols fetchmail uses to talk to mailservers are next to bullet‐
1496 proof. In normal operation forwarding to port 25, no message is ever
1497 deleted (or even marked for deletion) on the host until the SMTP lis‐
1498 tener on the client side has acknowledged to fetchmail that the message
1499 has been either accepted for delivery or rejected due to a spam block.
1500 When forwarding to an MDA, however, there is more possibility of error.
1502 Some MDAs are 'safe' and reliably return a nonzero status on any deliv‐
1503 ery error, even one due to temporary resource limits. The maildrop(1)
1504 program is like this; so are most programs designed as mail transport
1505 agents, such as sendmail(1), including the sendmail wrapper of Postfix
1506 and exim(1). These programs give back a reliable positive acknowledge‐
1507 ment and can be used with the mda option with no risk of mail loss.
1508 Unsafe MDAs, though, may return 0 even on delivery failure. If this
1509 happens, you will lose mail.
1510 The normal mode of fetchmail is to try to download only 'new' messages,
1512 leaving untouched (and undeleted) messages you have already read di‐
1513 rectly on the server (or fetched with a previous fetchmail --keep).
1514 But you may find that messages you've already read on the server are
1515 being fetched (and deleted) even when you don't specify --all. There
1516 are several reasons this can happen.
1517 One could be that you're using POP2. The POP2 protocol includes no
1519 representation of 'new' or 'old' state in messages, so fetchmail must
1520 treat all messages as new all the time. But POP2 is obsolete, so this
1521 is unlikely.
1522 A potential POP3 problem might be servers that insert messages in the
1524 middle of mailboxes (some VMS implementations of mail are rumored to do
1525 this). The fetchmail code assumes that new messages are appended to
1526 the end of the mailbox; when this is not true it may treat some old
1527 messages as new and vice versa. Using UIDL whilst setting fastuidl 0
1528 might fix this, otherwise, consider switching to IMAP.
1529 Yet another POP3 problem is that if they can't make tempfiles in the
1531 user's home directory, some POP3 servers will hand back an undocumented
1532 response that causes fetchmail to spuriously report "No mail".
1533 The IMAP code uses the presence or absence of the server flag \Seen to
1535 decide whether or not a message is new. This isn't the right thing to
1536 do, fetchmail should check the UIDVALIDITY and use UID, but it doesn't
1537 do that yet. Under Unix, it counts on your IMAP server to notice the
1538 BSD-style Status flags set by mail user agents and set the \Seen flag
1539 from them when appropriate. All Unix IMAP servers we know of do this,
1540 though it's not specified by the IMAP RFCs. If you ever trip over a
1541 server that doesn't, the symptom will be that messages you have already
1542 read on your host will look new to the server. In this (unlikely)
1543 case, only messages you fetched with fetchmail --keep will be both un‐
1544 deleted and marked old.
1545 In ETRN and ODMR modes, fetchmail does not actually retrieve messages;
1547 instead, it asks the server's SMTP listener to start a queue flush to
1548 the client via SMTP. Therefore it sends only undelivered messages.
1549
1552 Many SMTP listeners allow administrators to set up 'spam filters' that
1553 block unsolicited email from specified domains. A MAIL FROM or DATA
1554 line that triggers this feature will elicit an SMTP response which (un‐
1555 fortunately) varies according to the listener.
1556 Newer versions of sendmail return an error code of 571.
1558 According to RFC2821, the correct thing to return in this situation is
1560 550 "Requested action not taken: mailbox unavailable" (the draft adds
1561 "[E.g., mailbox not found, no access, or command rejected for policy
1562 reasons].").
1563 Older versions of the exim MTA return 501 "Syntax error in parameters
1565 or arguments".
1566 The postfix MTA runs 554 as an antispam response.
1568 Zmailer may reject code with a 500 response (followed by an enhanced
1570 status code that contains more information).
1571 Return codes which fetchmail treats as antispam responses and discards
1573 the message can be set with the 'antispam' option. This is one of the
1574 only three circumstance under which fetchmail ever discards mail (the
1575 others are the 552 and 553 errors described below, and the suppression
1576 of multidropped messages with a message-ID already seen).
1577 If fetchmail is fetching from an IMAP server, the antispam response
1579 will be detected and the message rejected immediately after the headers
1580 have been fetched, without reading the message body. Thus, you won't
1581 pay for downloading spam message bodies.
1582 By default, the list of antispam responses is empty.
1584 If the spambounce global option is on, mail that is spam-blocked trig‐
1586 gers an RFC1892/RFC1894 bounce message informing the originator that we
1587 do not accept mail from it. See also BUGS.
1588
1591 Besides the spam-blocking described above, fetchmail takes special ac‐
1592 tions — that may be modified by the --softbounce option — on the fol‐
1593 lowing SMTP/ESMTP error response codes
1594 452 (insufficient system storage)
1596 Leave the message in the server mailbox for later retrieval.
1597 552 (message exceeds fixed maximum message size)
1599 Delete the message from the server. Send bounce-mail to the orig‐
1600 inator.
1601 553 (invalid sending domain)
1603 Delete the message from the server. Don't even try to send
1604 bounce-mail to the originator.
1605 Other errors greater or equal to 500 trigger bounce mail back to the
1607 originator, unless suppressed by --softbounce. See also BUGS.
1608
1611 The preferred way to set up fetchmail is to write a .fetchmailrc file
1612 in your home directory (you may do this directly, with a text editor,
1613 or indirectly via fetchmailconf). When there is a conflict between the
1614 command-line arguments and the arguments in this file, the command-line
1615 arguments take precedence.
1616 To protect the security of your passwords, your ~/.fetchmailrc may not
1618 normally have more than 0700 (u=rwx,g=,o=) permissions; fetchmail will
1619 complain and exit otherwise (this check is suppressed when --version is
1620 on).
1621 You may read the .fetchmailrc file as a list of commands to be executed
1623 when fetchmail is called with no arguments.
1624 Run Control Syntax
1626 Comments begin with a '#' and extend through the end of the line. Oth‐
1627 erwise the file consists of a series of server entries or global option
1628 statements in a free-format, token-oriented syntax.
1629 There are four kinds of tokens: grammar keywords, numbers (i.e. decimal
1631 digit sequences), unquoted strings, and quoted strings. A quoted
1632 string is bounded by double quotes and may contain whitespace (and
1633 quoted digits are treated as a string). Note that quoted strings will
1634 also contain line feed characters if they run across two or more lines,
1635 unless you use a backslash to join lines (see below). An unquoted
1636 string is any whitespace-delimited token that is neither numeric,
1637 string quoted nor contains the special characters ',', ';', ':', or
1638 '='.
1639 Any amount of whitespace separates tokens in server entries, but is
1641 otherwise ignored. You may use backslash escape sequences (\n for LF,
1642 \t for HT, \b for BS, \r for CR, \nnn for decimal (where nnn cannot
1643 start with a 0), \0ooo for octal, and \xhh for hex) to embed non-print‐
1644 able characters or string delimiters in strings. In quoted strings, a
1645 backslash at the very end of a line will cause the backslash itself and
1646 the line feed (LF or NL, new line) character to be ignored, so that you
1647 can wrap long strings. Without the backslash at the line end, the line
1648 feed character would become part of the string.
1649 Warning: while these resemble C-style escape sequences, they are not
1651 the same. fetchmail only supports these eight styles. C supports more
1652 escape sequences that consist of backslash (\) and a single character,
1653 but does not support decimal codes and does not require the leading 0
1654 in octal notation. Example: fetchmail interprets \233 the same as \xE9
1655 (Latin small letter e with acute), where C would interpret \233 as oc‐
1656 tal 0233 = \x9B (CSI, control sequence introducer).
1657 Each server entry consists of one of the keywords 'poll' or 'skip',
1659 followed by a server name, followed by server options, followed by any
1660 number of user (or username) descriptions, followed by user options.
1661 Note: the most common cause of syntax errors is mixing up user and
1662 server options or putting user options before the user descriptions.
1663 For backward compatibility, the word 'server' is a synonym for 'poll'.
1665 You can use the noise keywords 'and', 'with', 'has', 'wants', and 'op‐
1667 tions' anywhere in an entry to make it resemble English. They're ig‐
1668 nored, but but can make entries much easier to read at a glance. The
1669 punctuation characters ':', ';' and ',' are also ignored.
1670 Poll vs. Skip
1672 The 'poll' verb tells fetchmail to query this host when it is run with
1673 no arguments. The 'skip' verb tells fetchmail not to poll this host
1674 unless it is explicitly named on the command line. (The 'skip' verb
1675 allows you to experiment with test entries safely, or easily disable
1676 entries for hosts that are temporarily down.)
1677 Keyword/Option Summary
1679 Here are the legal options. Keyword suffixes enclosed in square brack‐
1680 ets are optional. Those corresponding to short command-line options
1681 are followed by '-' and the appropriate option letter. If option is
1682 only relevant to a single mode of operation, it is noted as 's' or 'm'
1683 for singledrop- or multidrop-mode, respectively.
1684 Here are the legal global options:
1686 Keyword Opt Mode Function
1689 ────────────────────────────────────────────────────────────────────
1690 set daemon -d Set a background poll interval in
1691 seconds.
1692 set postmaster Give the name of the last-resort
1693 mail recipient (default: user run‐
1694 ning fetchmail, "postmaster" if
1695 run by the root user)
1696 set bouncemail Direct error mail to the sender
1697 (default)
1698 set no bouncemail Direct error mail to the local
1699 postmaster (as per the 'postmas‐
1700 ter' global option above).
1701 set no spambounce Do not bounce spam-blocked mail
1702 (default).
1703 set spambounce Bounce blocked spam-blocked mail
1712 (as per the 'antispam' user op‐
1713 tion) back to the destination as
1714 indicated by the 'bouncemail'
1715 global option. Warning: Do not
1716 use this to bounce spam back to
1717 the sender - most spam is sent
1718 with false sender address and thus
1719 this option hurts innocent by‐
1720 standers.
1721 set no softbounce Delete permanently undeliverable
1722 mail. It is recommended to use
1723 this option if the configuration
1724 has been thoroughly tested.
1725 set softbounce Keep permanently undeliverable
1726 mail as though a temporary error
1727 had occurred (default).
1728 set logfile -L Name of a file to append error and
1729 status messages to. Only effec‐
1730 tive in daemon mode and if fetch‐
1731 mail detaches. If effective,
1732 overrides set syslog.
1733 set pidfile -p Name of the PID file.
1734 set idfile -i Name of the file to store UID
1735 lists in.
1736 set syslog Do error logging through sys‐
1737 log(3). May be overridden by set
1738 logfile.
1739 set no syslog Turn off error logging through
1740 syslog(3). (default)
1741 set properties String value that is ignored by
1742 fetchmail (may be used by exten‐
1743 sion scripts).
1744 Here are the legal server options:
1746 Keyword Opt Mode Function
1749 ─────────────────────────────────────────────────────────────────
1750 via Specify DNS name of mailserver,
1751 overriding poll name
1752 proto[col] -p Specify protocol (case insensi‐
1753 tive): POP2, POP3, IMAP, APOP,
1754 KPOP
1755 local[domains] m Specify domain(s) to be regarded
1756 as local
1757 port Specify TCP/IP service port (obso‐
1758 lete, use 'service' instead).
1759 service -P Specify service name (a numeric
1760 value is also allowed and consid‐
1761 ered a TCP/IP port number).
1762 auth[enticate] Set authentication type (default
1763 'any')
1764 timeout -t Server inactivity timeout in sec‐
1765 onds (default 300)
1766 envelope -E m Specify envelope-address header
1767 name
1768 no envelope m Disable looking for envelope ad‐
1769 dress
1770 qvirtual -Q m Qmail virtual domain prefix to re‐
1771 move from user name
1772 aka m Specify alternate DNS names of
1773 mailserver
1774 interface -I specify IP interface(s) that must
1775 be up for server poll to take
1776 place
1777 monitor -M Specify IP address to monitor for
1778 activity
1779 plugin Specify command through which to
1780 make server connections.
1781 plugout Specify command through which to
1782 make listener connections.
1783 dns m Enable DNS lookup for multidrop
1786 (default)
1787 no dns m Disable DNS lookup for multidrop
1788 checkalias m Do comparison by IP address for
1789 multidrop
1790 no checkalias m Do comparison by name for mul‐
1791 tidrop (default)
1792 uidl -U Force POP3 to use client-side
1793 UIDLs (recommended)
1794 no uidl Turn off POP3 use of client-side
1795 UIDLs (default)
1796 interval Only check this site every N poll
1797 cycles; N is a numeric argument.
1798 tracepolls Add poll tracing information to
1799 the Received header
1800 principal Set Kerberos principal (only use‐
1801 ful with IMAP and kerberos)
1802 esmtpname Set name for RFC2554 authentica‐
1803 tion to the ESMTP server.
1804 esmtppassword Set password for RFC2554 authenti‐
1805 cation to the ESMTP server.
1806 bad-header How to treat messages with a bad
1807 header. Can be reject (default) or
1808 accept.
1809 Here are the legal user descriptions and options:
1811 Keyword Opt Mode Function
1814 ───────────────────────────────────────────────────────────────────────
1815 user[name] -u This is the user description and
1816 must come first after server de‐
1817 scription and after possible
1818 server options, and before user
1819 options.
1820 It sets the remote user name if by
1822 itself or followed by 'there', or
1823 the local user name if followed by
1824 'here'.
1825 is Connect local and remote user
1826 names
1827 to Connect local and remote user
1828 names
1829 pass[word] Specify remote account password
1830 ssl Connect to server over the speci‐
1831 fied base protocol using SSL en‐
1832 cryption
1833 sslcert Specify file for client side pub‐
1834 lic SSL certificate
1835 sslcertck Enable strict certificate checking
1836 and abort connection on failure.
1837 Default only since fetchmail
1838 v6.4.0.
1839 no sslcertck Disable strict certificate check‐
1840 ing and permit connections to con‐
1841 tinue on failed verification. Dis‐
1842 couraged. Should only be used to‐
1843 gether with sslfingerprint.
1844 sslcertfile Specify file with trusted CA cer‐
1845 tificates
1846 sslcertpath Specify c_rehash-ed directory with
1847 trusted CA certificates.
1848 sslfingerprint <HASH> Specify the expected server cer‐
1849 tificate finger print from an MD5
1850 hash. Fetchmail will disconnect
1851 and log an error if it does not
1852 match.
1853 sslkey Specify file for client side pri‐
1854 vate SSL key
1855 sslproto Force ssl protocol for connection
1856 folder -r Specify remote folder to query
1857 smtphost -S Specify smtp host(s) to forward to
1858 fetchdomains m Specify domains for which mail
1860 should be fetched
1861 smtpaddress -D Specify the domain to be put in
1862 RCPT TO lines
1863 smtpname Specify the user and domain to be
1864 put in RCPT TO lines
1865 antispam -Z Specify what SMTP returns are in‐
1866 terpreted as spam-policy blocks
1867 mda -m Specify MDA for local delivery
1868 bsmtp Specify BSMTP batch file to append
1869 to
1870 preconnect Command to be executed before each
1871 connection
1872 postconnect Command to be executed after each
1873 connection
1874 keep -k Don't delete seen messages from
1875 server (for POP3, uidl is recom‐
1876 mended)
1877 flush -F Flush all seen messages before
1878 querying (DANGEROUS)
1879 limitflush Flush all oversized messages be‐
1880 fore querying
1881 fetchall -a Fetch all messages whether seen or
1882 not
1883 rewrite Rewrite destination addresses for
1884 reply (default)
1885 stripcr Strip carriage returns from ends
1886 of lines
1887 forcecr Force carriage returns at ends of
1888 lines
1889 pass8bits Force BODY=8BITMIME to ESMTP lis‐
1890 tener
1891 dropstatus Strip Status and X-Mozilla-Status
1892 lines out of incoming mail
1893 dropdelivered Strip Delivered-To lines out of
1894 incoming mail
1895 mimedecode Convert quoted-printable to 8-bit
1896 in MIME messages
1897 idle Idle waiting for new messages af‐
1898 ter each poll (IMAP only)
1899 no keep -K Delete seen messages from server
1900 (default)
1901 no flush Don't flush all seen messages be‐
1902 fore querying (default)
1903 no fetchall Retrieve only new messages (de‐
1904 fault)
1905 no rewrite Don't rewrite headers
1906 no stripcr Don't strip carriage returns (de‐
1907 fault)
1908 no forcecr Don't force carriage returns at
1909 EOL (default)
1910 no pass8bits Don't force BODY=8BITMIME to ESMTP
1911 listener (default)
1912 no dropstatus Don't drop Status headers (de‐
1913 fault)
1914 no dropdelivered Don't drop Delivered-To headers
1915 (default)
1916 no mimedecode Don't convert quoted-printable to
1917 8-bit in MIME messages (default)
1918 no idle Don't idle waiting for new mes‐
1919 sages after each poll (IMAP only)
1920 limit -l Set message size limit
1921 warnings -w Set message size warning interval
1922 batchlimit -b Max # messages to forward in sin‐
1923 gle connect
1924 fetchlimit -B Max # messages to fetch in single
1925 connect
1926 fetchsizelimit Max # message sizes to fetch in
1927 single transaction
1928 fastuidl Use binary search for first unseen
1929 message (POP3 only)
1930 expunge -e Perform an expunge on every #th
1931 message (IMAP and POP3 only)
1932 properties String value is ignored by fetch‐
1934 mail (may be used by extension
1935 scripts)
1936 All user options must begin with a user description (user or username
1938 option) and follow all server descriptions and options.
1939 In the .fetchmailrc file, the 'envelope' string argument may be pre‐
1941 ceded by a whitespace-separated number. This number, if specified, is
1942 the number of such headers to skip over (that is, an argument of 1 se‐
1943 lects the second header of the given type). This is sometime useful
1944 for ignoring bogus envelope headers created by an ISP's local delivery
1945 agent or internal forwards (through mail inspection systems, for in‐
1946 stance).
1947 Keywords Not Corresponding To Option Switches
1949 The 'folder' and 'smtphost' options (unlike their command-line equiva‐
1950 lents) can take a space- or comma-separated list of names following
1951 them.
1952 All options correspond to the obvious command-line arguments, except
1954 the following: 'via', 'interval', 'aka', 'is', 'to', 'dns'/'no dns',
1955 'checkalias'/'no checkalias', 'password', 'preconnect', 'postconnect',
1956 'localdomains', 'stripcr'/'no stripcr', 'forcecr'/'no forcecr',
1957 'pass8bits'/'no pass8bits' 'dropstatus/no dropstatus', 'dropdeliv‐
1958 ered/no dropdelivered', 'mimedecode/no mimedecode', 'no idle', and 'no
1959 envelope'.
1960 The 'via' option is for if you want to have more than one configuration
1962 pointing at the same site. If it is present, the string argument will
1963 be taken as the actual DNS name of the mailserver host to query. This
1964 will override the argument of poll, which can then simply be a distinct
1965 label for the configuration (e.g. what you would give on the command
1966 line to explicitly query this host).
1967 The 'interval' option (which takes a numeric argument) allows you to
1969 poll a server less frequently than the basic poll interval. If you say
1970 'interval N' the server this option is attached to will only be queried
1971 every N poll intervals.
1972 Singledrop vs. Multidrop options
1974 Please ensure you read the section titled THE USE AND ABUSE OF MUL‐
1975 TIDROP MAILBOXES if you intend to use multidrop mode.
1976 The 'is' or 'to' keywords associate the following local (client)
1978 name(s) (or server-name to client-name mappings separated by =) with
1979 the mailserver user name in the entry. If an is/to list has '*' as its
1980 last name, unrecognized names are simply passed through. Note that un‐
1981 til fetchmail version 6.3.4 inclusively, these lists could only contain
1982 local parts of user names (fetchmail would only look at the part before
1983 the @ sign). fetchmail versions 6.3.5 and newer support full addresses
1984 on the left hand side of these mappings, and they take precedence over
1985 any 'localdomains', 'aka', 'via' or similar mappings.
1986 A single local name can be used to support redirecting your mail when
1988 your username on the client machine is different from your name on the
1989 mailserver. When there is only a single local name, mail is forwarded
1990 to that local username regardless of the message's Received, To, Cc,
1991 and Bcc headers. In this case, fetchmail never does DNS lookups.
1992 When there is more than one local name (or name mapping), fetchmail
1994 looks at the envelope header, if configured, and otherwise at the Re‐
1995 ceived, To, Cc, and Bcc headers of retrieved mail (this is 'multidrop
1996 mode'). It looks for addresses with hostname parts that match your
1997 poll name or your 'via', 'aka' or 'localdomains' options, and usually
1998 also for hostname parts which DNS tells it are aliases of the
1999 mailserver. See the discussion of 'dns', 'checkalias', 'localdomains',
2000 and 'aka' for details on how matching addresses are handled.
2001 If fetchmail cannot match any mailserver usernames or localdomain ad‐
2003 dresses, the mail will be bounced. Normally it will be bounced to the
2004 sender, but if the 'bouncemail' global option is off, the mail will go
2005 to the local postmaster instead. (see the 'postmaster' global option).
2006 See also BUGS.
2007 The 'dns' option (normally on) controls the way addresses from mul‐
2009 tidrop mailboxes are checked. On, it enables logic to check each host
2010 address that does not match an 'aka' or 'localdomains' declaration by
2011 looking it up with DNS. When a mailserver username is recognized at‐
2012 tached to a matching hostname part, its local mapping is added to the
2013 list of local recipients.
2014 The 'checkalias' option (normally off) extends the lookups performed by
2016 the 'dns' keyword in multidrop mode, providing a way to cope with re‐
2017 mote MTAs that identify themselves using their canonical name, while
2018 they're polled using an alias. When such a server is polled, checks to
2019 extract the envelope address fail, and fetchmail reverts to delivery
2020 using the To/Cc/Bcc headers (See below 'Header vs. Envelope ad‐
2021 dresses'). Specifying this option instructs fetchmail to retrieve all
2022 the IP addresses associated with both the poll name and the name used
2023 by the remote MTA and to do a comparison of the IP addresses. This
2024 comes in handy in situations where the remote server undergoes frequent
2025 canonical name changes, that would otherwise require modifications to
2026 the rcfile. 'checkalias' has no effect if 'no dns' is specified in the
2027 rcfile.
2028 The 'aka' option is for use with multidrop mailboxes. It allows you to
2030 pre-declare a list of DNS aliases for a server. This is an optimiza‐
2031 tion hack that allows you to trade space for speed. When fetchmail,
2032 while processing a multidrop mailbox, grovels through message headers
2033 looking for names of the mailserver, pre-declaring common ones can save
2034 it from having to do DNS lookups. Note: the names you give as argu‐
2035 ments to 'aka' are matched as suffixes -- if you specify (say) 'aka ne‐
2036 taxs.com', this will match not just a hostname netaxs.com, but any
2037 hostname that ends with '.netaxs.com'; such as (say) pop3.netaxs.com
2038 and mail.netaxs.com.
2039 The 'localdomains' option allows you to declare a list of domains which
2041 fetchmail should consider local. When fetchmail is parsing address
2042 lines in multidrop modes, and a trailing segment of a host name matches
2043 a declared local domain, that address is passed through to the listener
2044 or MDA unaltered (local-name mappings are not applied).
2045 If you are using 'localdomains', you may also need to specify 'no enve‐
2047 lope', which disables fetchmail's normal attempt to deduce an envelope
2048 address from the Received line or X-Envelope-To header or whatever
2049 header has been previously set by 'envelope'. If you set 'no envelope'
2050 in the defaults entry it is possible to undo that in individual entries
2051 by using 'envelope <string>'. As a special case, 'envelope "Received"'
2052 restores the default parsing of Received lines.
2053 The password option requires a string argument, which is the password
2055 to be used with the entry's server.
2056 The 'preconnect' keyword allows you to specify a shell command to be
2058 executed just before each time fetchmail establishes a mailserver con‐
2059 nection. This may be useful if you are attempting to set up secure POP
2060 connections with the aid of ssh(1). If the command returns a nonzero
2061 status, the poll of that mailserver will be aborted.
2062 Similarly, the 'postconnect' keyword similarly allows you to specify a
2064 shell command to be executed just after each time a mailserver connec‐
2065 tion is taken down.
2066 The 'forcecr' option controls whether lines terminated by LF only are
2068 given CRLF termination before forwarding. Strictly speaking RFC821 re‐
2069 quires this, but few MTAs enforce the requirement so this option is
2070 normally off (only one such MTA, qmail, is in significant use at time
2071 of writing).
2072 The 'stripcr' option controls whether carriage returns are stripped out
2074 of retrieved mail before it is forwarded. It is normally not necessary
2075 to set this, because it defaults to 'on' (CR stripping enabled) when
2076 there is an MDA declared but 'off' (CR stripping disabled) when for‐
2077 warding is via SMTP. If 'stripcr' and 'forcecr' are both on, 'stripcr'
2078 will override.
2079 The 'pass8bits' option exists to cope with Microsoft mail programs that
2081 stupidly slap a "Content-Transfer-Encoding: 7bit" on everything. With
2082 this option off (the default) and such a header present, fetchmail de‐
2083 clares BODY=7BIT to an ESMTP-capable listener; this causes problems for
2084 messages actually using 8-bit ISO or KOI-8 character sets, which will
2085 be garbled by having the high bits of all characters stripped. If
2086 'pass8bits' is on, fetchmail is forced to declare BODY=8BITMIME to any
2087 ESMTP-capable listener. If the listener is 8-bit-clean (as all the ma‐
2088 jor ones now are) the right thing will probably result.
2089 The 'dropstatus' option controls whether nonempty Status and X-Mozilla-
2091 Status lines are retained in fetched mail (the default) or discarded.
2092 Retaining them allows your MUA to see what messages (if any) were
2093 marked seen on the server. On the other hand, it can confuse some new-
2094 mail notifiers, which assume that anything with a Status line in it has
2095 been seen. (Note: the empty Status lines inserted by some buggy POP
2096 servers are unconditionally discarded.)
2097 The 'dropdelivered' option controls whether Delivered-To headers will
2099 be kept in fetched mail (the default) or discarded. These headers are
2100 added by Qmail and Postfix mailservers in order to avoid mail loops but
2101 may get in your way if you try to "mirror" a mailserver within the same
2102 domain. Use with caution.
2103 The 'mimedecode' option controls whether MIME messages using the
2105 quoted-printable encoding are automatically converted into pure 8-bit
2106 data. If you are delivering mail to an ESMTP-capable, 8-bit-clean lis‐
2107 tener (that includes all of the major MTAs like sendmail), then this
2108 will automatically convert quoted-printable message headers and data
2109 into 8-bit data, making it easier to understand when reading mail. If
2110 your e-mail programs know how to deal with MIME messages, then this op‐
2111 tion is not needed. The mimedecode option is off by default, because
2112 doing RFC2047 conversion on headers throws away character-set informa‐
2113 tion and can lead to bad results if the encoding of the headers differs
2114 from the body encoding.
2115 The 'idle' option is intended to be used with IMAP servers supporting
2117 the RFC2177 IDLE command extension, but does not strictly require it.
2118 If it is enabled, and fetchmail detects that IDLE is supported, an IDLE
2119 will be issued at the end of each poll. This will tell the IMAP server
2120 to hold the connection open and notify the client when new mail is
2121 available. If IDLE is not supported, fetchmail will simulate it by pe‐
2122 riodically issuing NOOP. If you need to poll a link frequently, IDLE
2123 can save bandwidth by eliminating TCP/IP connects and LOGIN/LOGOUT se‐
2124 quences. On the other hand, an IDLE connection will eat almost all of
2125 your fetchmail's time, because it will never drop the connection and
2126 allow other polls to occur unless the server times out the IDLE. It
2127 also doesn't work with multiple folders; only the first folder will
2128 ever be polled.
2129 The 'properties' option is an extension mechanism. It takes a string
2131 argument, which is ignored by fetchmail itself. The string argument
2132 may be used to store configuration information for scripts which re‐
2133 quire it. In particular, the output of '--configdump' option will make
2134 properties associated with a user entry readily available to a Python
2135 script.
2136 Miscellaneous Run Control Options
2138 The words 'here' and 'there' have useful English-like significance.
2139 Normally 'user eric is esr' would mean that mail for the remote user
2140 'eric' is to be delivered to 'esr', but you can make this clearer by
2141 saying 'user eric there is esr here', or reverse it by saying 'user esr
2142 here is eric there'
2143 Legal protocol identifiers for use with the 'protocol' keyword are:
2145 auto (or AUTO) (legacy, to be removed from future release)
2147 pop2 (or POP2) (legacy, to be removed from future release)
2148 pop3 (or POP3)
2149 sdps (or SDPS)
2150 imap (or IMAP)
2151 apop (or APOP)
2152 kpop (or KPOP)
2153 Legal authentication types are 'any', 'password', 'kerberos', 'ker‐
2156 beros_v4', 'kerberos_v5' and 'gssapi', 'cram-md5', 'otp', 'msn' (only
2157 for POP3), 'ntlm', 'ssh', 'external' (only IMAP). The 'password' type
2158 specifies authentication by normal transmission of a password (the
2159 password may be plain text or subject to protocol-specific encryption
2160 as in CRAM-MD5); 'kerberos' tells fetchmail to try to get a Kerberos
2161 ticket at the start of each query instead, and send an arbitrary string
2162 as the password; and 'gssapi' tells fetchmail to use GSSAPI authentica‐
2163 tion. See the description of the 'auth' keyword for more.
2164 Specifying 'kpop' sets POP3 protocol over port 1109 with Kerberos V4
2166 authentication. These defaults may be overridden by later options.
2167 There are some global option statements: 'set logfile' followed by a
2169 string sets the same global specified by --logfile. A command-line
2170 --logfile option will override this. Note that --logfile is only effec‐
2171 tive if fetchmail detaches itself from the terminal and the logfile al‐
2172 ready exists before fetchmail is run, and it overrides --syslog in this
2173 case. Also, 'set daemon' sets the poll interval as --daemon does.
2174 This can be overridden by a command-line --daemon option; in particular
2175 --daemon 0 can be used to force foreground operation. The 'set postmas‐
2176 ter' statement sets the address to which multidrop mail defaults if
2177 there are no local matches. Finally, 'set syslog' sends log messages
2178 to syslogd(8).
2179
2182 Fetchmail crashing
2183 There are various ways in that fetchmail may "crash", i. e. stop opera‐
2184 tion suddenly and unexpectedly. A "crash" usually refers to an error
2185 condition that the software did not handle by itself. A well-known
2186 failure mode is the "segmentation fault" or "signal 11" or "SIGSEGV" or
2187 just "segfault" for short. These can be caused by hardware or by soft‐
2188 ware problems. Software-induced segfaults can usually be reproduced
2189 easily and in the same place, whereas hardware-induced segfaults can go
2190 away if the computer is rebooted, or powered off for a few hours, and
2191 can happen in random locations even if you use the software the same
2192 way.
2193 For solving hardware-induced segfaults, find the faulty component and
2195 repair or replace it. The Sig11 FAQ ⟨https://www.bitwizard.nl/sig11/⟩
2196 may help you with details.
2197 For solving software-induced segfaults, the developers may need a
2199 "stack backtrace".
2200 Enabling fetchmail core dumps
2203 By default, fetchmail suppresses core dumps as these might contain
2204 passwords and other sensitive information. For debugging fetchmail
2205 crashes, obtaining a "stack backtrace" from a core dump is often the
2206 quickest way to solve the problem, and when posting your problem on a
2207 mailing list, the developers may ask you for a "backtrace".
2208 1. To get useful backtraces, fetchmail needs to be installed without
2210 getting stripped of its compilation symbols. Unfortunately, most bi‐
2211 nary packages that are installed are stripped, and core files from sym‐
2212 bol-stripped programs are worthless. So you may need to recompile
2213 fetchmail. On many systems, you can type
2214 file `which fetchmail`
2216 to find out if fetchmail was symbol-stripped or not. If yours was un‐
2218 stripped, fine, proceed, if it was stripped, you need to recompile the
2219 source code first. You do not usually need to install fetchmail in or‐
2220 der to debug it.
2221 2. The shell environment that starts fetchmail needs to enable core
2223 dumps. The key is the "maximum core (file) size" that can usually be
2224 configured with a tool named "limit" or "ulimit". See the documentation
2225 for your shell for details. In the popular bash shell, "ulimit -Sc un‐
2226 limited" will allow the core dump.
2227 3. You need to tell fetchmail, too, to allow core dumps. To do this,
2229 run fetchmail with the -d0 -v options. It is often easier to also add
2230 --nosyslog -N as well.
2231 Finally, you need to reproduce the crash. You can just start fetchmail
2233 from the directory where you compiled it by typing ./fetchmail, so the
2234 complete command line will start with ./fetchmail -Nvd0 --nosyslog and
2235 perhaps list your other options.
2236 After the crash, run your debugger to obtain the core dump. The debug‐
2238 ger will often be GNU GDB, you can then type (adjust paths as neces‐
2239 sary) gdb ./fetchmail fetchmail.core and then, after GDB has started up
2240 and read all its files, type backtrace full, save the output (copy &
2241 paste will do, the backtrace will be read by a human) and then type
2242 quit to leave gdb. Note: on some systems, the core files have differ‐
2243 ent names, they might contain a number instead of the program name, or
2244 number and name, but it will usually have "core" as part of their name.
2245
2248 When trying to determine the originating address of a message, fetch‐
2249 mail looks through headers in the following order:
2250 Return-Path:
2252 Resent-Sender: (ignored if it doesn't contain an @ or !)
2253 Sender: (ignored if it doesn't contain an @ or !)
2254 Resent-From:
2255 From:
2256 Reply-To:
2257 Apparently-From:
2258 The originating address is used for logging, and to set the MAIL FROM
2260 address when forwarding to SMTP. This order is intended to cope grace‐
2261 fully with receiving mailing list messages in multidrop mode. The in‐
2262 tent is that if a local address doesn't exist, the bounce message won't
2263 be returned blindly to the author or to the list itself, but rather to
2264 the list manager (which is less annoying).
2265 In multidrop mode, destination headers are processed as follows: First,
2267 fetchmail looks for the header specified by the 'envelope' option in
2268 order to determine the local recipient address. If the mail is ad‐
2269 dressed to more than one recipient, the Received line won't contain any
2270 information regarding recipient addresses.
2271 Then fetchmail looks for the Resent-To:, Resent-Cc:, and Resent-Bcc:
2273 lines. If they exist, they should contain the final recipients and
2274 have precedence over their To:/Cc:/Bcc: counterparts. If the Resent-*
2275 lines don't exist, the To:, Cc:, Bcc: and Apparently-To: lines are
2276 looked for. (The presence of a Resent-To: is taken to imply that the
2277 person referred by the To: address has already received the original
2278 copy of the mail.)
2279
2282 Note that although there are password declarations in a good many of
2283 the examples below, this is mainly for illustrative purposes. We rec‐
2284 ommend stashing account/password pairs in your $HOME/.netrc file, where
2285 they can be used not just by fetchmail but by ftp(1) and other pro‐
2286 grams.
2287 The basic format is:
2289 poll SERVERNAME protocol PROTOCOL username NAME password PASS‐
2292 WORD
2293 Example:
2296 poll pop.provider.net protocol pop3 username "jsmith" password "secret1"
2299 Or, using some abbreviations:
2302 poll pop.provider.net proto pop3 user "jsmith" password "secret1"
2305 Multiple servers may be listed:
2308 poll pop.provider.net proto pop3 user "jsmith" pass "secret1"
2311 poll other.provider.net proto pop2 user "John.Smith" pass "My^Hat"
2312 Here's the same version with more whitespace and some noise words:
2315 poll pop.provider.net proto pop3
2318 user "jsmith", with password secret1, is "jsmith" here;
2319 poll other.provider.net proto pop2:
2320 user "John.Smith", with password "My^Hat", is "John.Smith" here;
2321 If you need to include whitespace in a parameter string or start the
2324 latter with a number, enclose the string in double quotes. Thus:
2325 poll mail.provider.net with proto pop3:
2328 user "jsmith" there has password "4u but u can't krak this"
2329 is jws here and wants mda "/bin/mail"
2330 You may have an initial server description headed by the keyword 'de‐
2333 faults' instead of 'poll' followed by a name. Such a record is inter‐
2334 preted as defaults for all queries to use. It may be overwritten by in‐
2335 dividual server descriptions. So, you could write:
2336 defaults proto pop3
2339 user "jsmith"
2340 poll pop.provider.net
2341 pass "secret1"
2342 poll mail.provider.net
2343 user "jjsmith" there has password "secret2"
2344 It's possible to specify more than one user per server. The 'user'
2347 keyword leads off a user description, and every user specification in a
2348 multi-user entry must include it. Here's an example:
2349 poll pop.provider.net proto pop3 port 3111
2352 user "jsmith" with pass "secret1" is "smith" here
2353 user jones with pass "secret2" is "jjones" here keep
2354 This associates the local username 'smith' with the pop.provider.net
2357 username 'jsmith' and the local username 'jjones' with the
2358 pop.provider.net username 'jones'. Mail for 'jones' is kept on the
2359 server after download.
2360 Here's what a simple retrieval configuration for a multidrop mailbox
2363 looks like:
2364 poll pop.provider.net:
2367 user maildrop with pass secret1 to golux 'hurkle'='happy' snark here
2368 This says that the mailbox of account 'maildrop' on the server is a
2371 multidrop box, and that messages in it should be parsed for the server
2372 user names 'golux', 'hurkle', and 'snark'. It further specifies that
2373 'golux' and 'snark' have the same name on the client as on the server,
2374 but mail for server user 'hurkle' should be delivered to client user
2375 'happy'.
2376 Note that fetchmail, until version 6.3.4, did NOT allow full user@do‐
2379 main specifications here, these would never match. Fetchmail 6.3.5 and
2380 newer support user@domain specifications on the left-hand side of a
2381 user mapping.
2382 Here's an example of another kind of multidrop connection:
2385 poll pop.provider.net localdomains loonytoons.org toons.org
2388 envelope X-Envelope-To
2389 user maildrop with pass secret1 to * here
2390 This also says that the mailbox of account 'maildrop' on the server is
2393 a multidrop box. It tells fetchmail that any address in the loony‐
2394 toons.org or toons.org domains (including sub-domain addresses like
2395 'joe@daffy.loonytoons.org') should be passed through to the local SMTP
2396 listener without modification. Be careful of mail loops if you do
2397 this!
2398 Here's an example configuration using ssh and the plugin option. The
2401 queries are made directly on the stdin and stdout of imapd via ssh.
2402 Note that in this setup, IMAP authentication can be skipped.
2403 poll mailhost.net with proto imap:
2406 plugin "ssh %h /usr/sbin/imapd" auth ssh;
2407 user esr is esr here
2408
2411 Use the multiple-local-recipients feature with caution -- it can bite.
2412 All multidrop features are ineffective in ETRN and ODMR modes.
2413 Also, note that in multidrop mode duplicate mails may be suppressed. A
2415 piece of mail is considered duplicate if it does not have a discernable
2416 envelope recipient address, has the same header as the message immedi‐
2417 ately preceding and more than one addressee. Such runs of messages may
2418 be generated when copies of a message addressed to multiple users are
2419 delivered to a multidrop box. (To be precise, fetchmail 6.2.5 through
2420 6.4.X use an MD5 hash of the raw message header, and only fetchmail
2421 6.4.16+ document this properly. Fetchmail 5.0.8 (1999-09-14) through
2422 6.2.4 used only the Message-ID header. 5.0.7 and older did not sup‐
2423 press duplicates.)
2424 Note that this duplication killer code checking the entire header is
2426 very restrictive and may not suppress many duplicates in practice - for
2427 instance, if some X-Original-To or Delivered-To header differs. This
2428 is intentional and correct in such situations: wherever envelope infor‐
2429 mation is available, it should be used for reliable delivery of mailing
2430 list and blind carbon copy (Bcc) messages. See the subsection Duplicate
2431 suppression below for suggestions.
2432 Header vs. Envelope addresses
2435 The fundamental problem is that by having your mailserver toss several
2436 peoples' mail in a single maildrop box, you may have thrown away poten‐
2437 tially vital information about who each piece of mail was actually ad‐
2438 dressed to (the 'envelope address', as opposed to the header addresses
2439 in the RFC822 To/Cc headers - the Bcc is not available at the receiving
2440 end). This 'envelope address' is the address you need in order to
2441 reroute mail properly.
2442 Sometimes fetchmail can deduce the envelope address. If the mailserver
2444 MTA is sendmail and the item of mail had just one recipient, the MTA
2445 will have written a 'by/for' clause that gives the envelope addressee
2446 into its Received header. But this doesn't work reliably for other
2447 MTAs, nor if there is more than one recipient. By default, fetchmail
2448 looks for envelope addresses in these lines; you can restore this de‐
2449 fault with -E "Received" or 'envelope Received'.
2450 As a better alternative, some SMTP listeners and/or mail servers insert
2452 a header in each message containing a copy of the envelope addresses.
2453 This header (when it exists) is often 'X-Original-To', 'Delivered-To'
2454 or 'X-Envelope-To'. Fetchmail's assumption about this can be changed
2455 with the -E or 'envelope' option. Note that writing an envelope header
2456 of this kind exposes the names of recipients (including blind-copy re‐
2457 cipients) to all receivers of the messages, so the upstream must store
2458 one copy of the message per recipient to avoid becoming a privacy prob‐
2459 lem.
2460 Postfix, since version 2.0, writes an X-Original-To: header which con‐
2462 tains a copy of the envelope as it was received.
2463 Qmail and Postfix generally write a 'Delivered-To' header upon deliver‐
2465 ing the message to the mail spool and use it to avoid mail loops.
2466 Qmail virtual domains however will prefix the user name with a string
2467 that normally matches the user's domain. To remove this prefix you can
2468 use the -Q or 'qvirtual' option.
2469 Sometimes, unfortunately, neither of these methods works. That is the
2471 point when you should contact your ISP and ask them to provide such an
2472 envelope header, and you should not use multidrop in this situation.
2473 When they all fail, fetchmail must fall back on the contents of To/Cc
2474 headers (Bcc headers are not available - see below) to try to determine
2475 recipient addressees -- and these are unreliable. In particular, mail‐
2476 ing-list software often ships mail with only the list broadcast address
2477 in the To header.
2478 Note that a future version of fetchmail may remove To/Cc parsing!
2480 When fetchmail cannot deduce a recipient address that is local, and the
2482 intended recipient address was anyone other than fetchmail's invoking
2483 user, mail will get lost. This is what makes the multidrop feature
2484 risky without proper envelope information.
2485 A related problem is that when you blind-copy a mail message, the Bcc
2487 information is carried only as envelope address (it's removed from the
2488 headers by the sending mail server, so fetchmail can see it only if
2489 there is an X-Envelope-To header). Thus, blind-copying to someone who
2490 gets mail over a fetchmail multidrop link will fail unless the the
2491 mailserver host routinely writes X-Envelope-To or an equivalent header
2492 into messages in your maildrop.
2493 In conclusion, mailing lists and Bcc'd mail can only work if the server
2495 you're fetching from
2496 (1) stores one copy of the message per recipient in your domain and
2498 (2) records the envelope information in a special header (X-Origi‐
2500 nal-To, Delivered-To, X-Envelope-To).
2501 Good Ways To Use Multidrop Mailboxes
2504 Multiple local names can be used to administer a mailing list from the
2505 client side of a fetchmail collection. Suppose your name is 'esr', and
2506 you want to both pick up your own mail and maintain a mailing list
2507 called (say) "fetchmail-friends", and you want to keep the alias list
2508 on your client machine.
2509 On your server, you can alias 'fetchmail-friends' to 'esr'; then, in
2511 your .fetchmailrc, declare 'to esr fetchmail-friends here'. Then, when
2512 mail including 'fetchmail-friends' as a local address gets fetched, the
2513 list name will be appended to the list of recipients your SMTP listener
2514 sees. Therefore it will undergo alias expansion locally. Be sure to
2515 include 'esr' in the local alias expansion of fetchmail-friends, or
2516 you'll never see mail sent only to the list. Also be sure that your
2517 listener has the "me-too" option set (sendmail's -oXm command-line op‐
2518 tion or OXm declaration) so your name isn't removed from alias expan‐
2519 sions in messages you send.
2520 This trick is not without its problems, however. You'll begin to see
2522 this when a message comes in that is addressed only to a mailing list
2523 you do not have declared as a local name. Each such message will fea‐
2524 ture an 'X-Fetchmail-Warning' header which is generated because fetch‐
2525 mail cannot find a valid local name in the recipient addresses. Such
2526 messages default (as was described above) to being sent to the local
2527 user running fetchmail, but the program has no way to know that that's
2528 actually the right thing.
2529 Bad Ways To Abuse Multidrop Mailboxes
2532 Multidrop mailboxes and fetchmail serving multiple users in daemon mode
2533 do not mix. The problem, again, is mail from mailing lists, which typ‐
2534 ically does not have an individual recipient address on it. Unless
2535 fetchmail can deduce an envelope address, such mail will only go to the
2536 account running fetchmail (probably root). Also, blind-copied users
2537 are very likely never to see their mail at all.
2538 If you're tempted to use fetchmail to retrieve mail for multiple users
2540 from a single mail drop via POP or IMAP, think again (and reread the
2541 section on header and envelope addresses above). It would be smarter
2542 to just let the mail sit in the mailserver's queue and use fetchmail's
2543 ETRN or ODMR modes to trigger SMTP sends periodically (of course, this
2544 means you have to poll more frequently than the mailserver's expiry pe‐
2545 riod). If you can't arrange this, try setting up a UUCP feed.
2546 If you absolutely must use multidrop for this purpose, make sure your
2548 mailserver writes an envelope-address header that fetchmail can see.
2549 Otherwise you will lose mail and it will come back to haunt you.
2550 Speeding Up Multidrop Checking
2553 Normally, when multiple users are declared fetchmail extracts recipient
2554 addresses as described above and checks each host part with DNS to see
2555 if it's an alias of the mailserver. If so, the name mappings described
2556 in the "to ... here" declaration are done and the mail locally deliv‐
2557 ered.
2558 This is a convenient but also slow method. To speed it up, pre-declare
2560 mailserver aliases with 'aka'; these are checked before DNS lookups are
2561 done. If you're certain your aka list contains all DNS aliases of the
2562 mailserver (and all MX names pointing at it - note this may change in a
2563 future version) you can declare 'no dns' to suppress DNS lookups en‐
2564 tirely and only match against the aka list.
2565 Duplicate suppression on multidrop
2568 If fetchmail's duplicate suppression code does not kick in for your
2569 multidrop mail account, other options is using sieve, or for instance
2570 Courier's maildrop package (and in particular, its reformail program
2571 with the -D option) as the delivery agent (either from fetchmail, or
2572 from your local mail server that fetchmail injects into).
2573
2576 Support for socks4/5 is a compile time configuration option. Once com‐
2577 piled in, fetchmail will always use the socks libraries and configura‐
2578 tion on your system, there are no run-time switches in fetchmail - but
2579 you can still configure SOCKS: you can specify which SOCKS configura‐
2580 tion file is used in the SOCKS_CONF environment variable.
2581 For instance, if you wanted to bypass the SOCKS proxy altogether and
2583 have fetchmail connect directly, you could just pass
2584 SOCKS_CONF=/dev/null in the environment, for example (add your usual
2585 command line options - if any - to the end of this line):
2586 env SOCKS_CONF=/dev/null fetchmail
2588
2591 To facilitate the use of fetchmail in shell scripts, an exit status
2592 code is returned to give an indication of what occurred during a given
2593 connection.
2594 The exit codes returned by fetchmail are as follows:
2596 0 One or more messages were successfully retrieved (or, if the -c
2598 option was selected, were found waiting but not retrieved).
2599 1 There was no mail awaiting retrieval. (There may have been old
2601 mail still on the server but not selected for retrieval.) If you
2602 do not want "no mail" to be an error condition (for instance,
2603 for cron jobs), use a POSIX-compliant shell and add
2604 || [ $? -eq 1 ]
2606 to the end of the fetchmail command line, note that this leaves
2608 0 untouched, maps 1 to 0, and maps all other codes to 1. See
2609 also item #C8 in the FAQ.
2610 2 An error was encountered when attempting to open a socket to re‐
2612 trieve mail. If you don't know what a socket is, don't worry
2613 about it -- just treat this as an 'unrecoverable error'. This
2614 error can also be because a protocol fetchmail wants to use is
2615 not listed in /etc/services.
2616 3 The user authentication step failed. This usually means that a
2618 bad user-id, password, or APOP id was specified. Or it may mean
2619 that you tried to run fetchmail under circumstances where it did
2620 not have standard input attached to a terminal and could not
2621 prompt for a missing password.
2622 4 Some sort of fatal protocol error was detected.
2624 5 There was a syntax error in the arguments to fetchmail, or a
2626 pre- or post-connect command failed.
2627 6 The run control file had bad permissions.
2629 7 There was an error condition reported by the server. Can also
2631 fire if fetchmail timed out while waiting for the server.
2632 8 Client-side exclusion error. This means fetchmail either found
2634 another copy of itself already running, or failed in such a way
2635 that it isn't sure whether another copy is running.
2636 9 The user authentication step failed because the server responded
2638 "lock busy". Try again after a brief pause! This error is not
2639 implemented for all protocols, nor for all servers. If not im‐
2640 plemented for your server, "3" will be returned instead, see
2641 above. May be returned when talking to qpopper or other servers
2642 that can respond with "lock busy" or some similar text contain‐
2643 ing the word "lock".
2644 10 The fetchmail run failed while trying to do an SMTP port open or
2646 transaction.
2647 11 Fatal DNS error. Fetchmail encountered an error while perform‐
2649 ing a DNS lookup at startup and could not proceed.
2650 12 BSMTP batch file could not be opened.
2652 13 Poll terminated by a fetch limit (see the --fetchlimit option).
2654 14 Server busy indication.
2656 23 Internal error. You should see a message on standard error with
2658 details.
2659 24 - 26, 28, 29
2661 These are internal codes and should not appear externally.
2662 When fetchmail queries more than one host, return status is 0 if any
2664 query successfully retrieved mail. Otherwise the returned error status
2665 is that of the last host queried.
2666
2669 ~/.fetchmailrc, $HOME/.fetchmailrc, $HOME_ETC/.fetchmailrc, $FETCHMAIL‐
2670 HOME/fetchmailrc
2671 default run control file (location can be overridden with environ‐
2672 ment variables)
2673 ~/.fetchids, $HOME/.fetchids, $HOME_ETC/.fetchids, $FETCHMAIL‐
2675 HOME/.fetchids
2676 default location of file recording last message UIDs seen per
2677 host. (location can be overridden with environment variables)
2678 ~/.fetchmail.pid, $HOME/.fetchmail.pid, $HOME_ETC/.fetchmail.pid,
2680 $FETCHMAILHOME/fetchmail.pid
2681 default location of lock file (sometimes called pidfile or PID
2682 file, see option pidfile) to help prevent concurrent runs (non-
2683 root mode). (location can be overridden with environment vari‐
2684 ables)
2685 ~/.netrc, $HOME/.netrc, $HOME_ETC/.netrc
2687 your FTP run control file, which (if present) will be searched for
2688 passwords as a last resort before prompting for one interactively.
2689 (location can be overridden with environment variables)
2690 /var/run/fetchmail.pid
2692 lock file (pidfile) to help prevent concurrent runs (root mode,
2693 Linux systems).
2694 /etc/fetchmail.pid
2696 lock file (pidfile) to help prevent concurrent runs (root mode,
2697 systems without /var/run).
2698
2701 Fetchmail's behavior can be altered by providing it with environment
2702 variables. Some may alter the operation of libraries that fetchmail
2703 links against, for instance, OpenSSL. Note that in daemon mode, you
2704 will need to quit the background daemon process and start a new fetch‐
2705 mail daemon for environment changes to take effect.
2706 FETCHMAILHOME
2708 If this environment variable is set to a valid and existing di‐
2709 rectory name, fetchmail will read $FETCHMAILHOME/fetchmailrc
2710 (the dot is missing in this case), $FETCHMAILHOME/.fetchids
2711 (keeping its dot) and $FETCHMAILHOME/fetchmail.pid (without dot)
2712 rather than from the user's home directory. The .netrc file is
2713 always looked for in the the invoking user's home directory (or
2714 $HOME_ETC) regardless of FETCHMAILHOME's setting.
2715 FETCHMAILUSER
2718 If this environment variable is set, it is used as the name of
2719 the calling user (default local name) for purposes such as mail‐
2720 ing error notifications. Otherwise, if either the LOGNAME or
2721 USER variable is correctly set (e.g. the corresponding UID
2722 matches the session user ID) then that name is used as the de‐
2723 fault local name. Otherwise getpwuid(3) must be able to re‐
2724 trieve a password entry for the session ID (this elaborate logic
2725 is designed to handle the case of multiple names per userid
2726 gracefully).
2727 FETCHMAIL_DISABLE_CBC_IV_COUNTERMEASURE
2730 (since v6.3.22): If this environment variable is set and not
2731 empty, fetchmail will disable a countermeasure against an SSL
2732 CBC IV attack (by setting SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS).
2733 This is a security risk, but may be necessary for connecting to
2734 certain non-standards-conforming servers. See fetchmail's NEWS
2735 file and fetchmail-SA-2012-01.txt for details. Earlier fetch‐
2736 mail versions (v6.3.21 and older) used to disable this counter‐
2737 measure, but v6.3.22 no longer does that as a safety precaution.
2738 FETCHMAIL_POP3_FORCE_RETR
2741 (since v6.3.9): If this environment variable is defined at all
2742 (even if empty), fetchmail will forgo the POP3 TOP command and
2743 always use RETR. This can be used as a workaround when TOP does
2744 not work properly.
2745 FETCHMAIL_INCLUDE_DEFAULT_X509_CA_CERTS
2748 (since v6.3.17): If this environment variable is set and not
2749 empty, fetchmail will always load the default X.509 trusted cer‐
2750 tificate locations for SSL/TLS CA certificates, even if
2751 --sslcertfile and --sslcertpath are given. The latter locations
2752 take precedence over the system default locations. This is use‐
2753 ful in case there are broken certificates in the system directo‐
2754 ries and the user has no administrator privileges to remedy the
2755 problem.
2756 HOME (documented since 6.4.1): This variable is nomally set to the
2759 user's home directory. If it is set to a different directory
2760 than what is in the password database, HOME takes precedence.
2761 HOME_ETC
2764 (documentation corrected to match behaviour of code since
2765 6.4.1): If the HOME_ETC variable is set, it will override fetch‐
2766 mail's idea of $HOME, i. e. fetchmail will read .fetchmailrc,
2767 .fetchids, .fetchmail.pid and .netrc from $HOME_ETC instead of
2768 $HOME (or if HOME is also unset, from the passwd file's home di‐
2769 rectory location).
2770 If HOME_ETC and FETCHMAILHOME are both set, FETCHMAILHOME takes
2772 prececence and HOME_ETC will be ignored.
2773 SOCKS_CONF
2776 (only if SOCKS support is compiled in) this variable is used by
2777 the socks library to find out which configuration file it should
2778 read. Set this to /dev/null to bypass the SOCKS proxy.
2779 SSL_CERT_DIR
2782 (with truly OpenSSL 1.1.1 compatible library): overrides
2783 OpenSSL's idea of the default trust directory or path (which
2784 contains individual certificate files and hashed symlinks), see
2785 the SSL_CTX_set_default_verify_paths(3) manual page for details,
2786 it may be in the openssl development package. If using another
2787 library's OpenSSL compatibility interface, this may not work.
2788 Since this variable only specifies a default value, the option
2789 --sslcertpath takes precedence if given.
2790 SSL_CERT_FILE
2793 (with truly OpenSSL 1.1.1 compatible library): overrides
2794 OpenSSL's idea of the default trust certificate bundle file
2795 (which contains a concatenation of base64-encoded certificates
2796 in PEM format), see the SSL_CTX_set_default_verify_paths(3) man‐
2797 ual page for details, it may be in the openssl development pack‐
2798 age. If using another library's OpenSSL compatibility inter‐
2799 face, this may not work. Since this variable only specifies a
2800 default value, the option --sslcertfile takes precedence if
2801 given.
2802
2805 If a fetchmail daemon is running as root, SIGUSR1 wakes it up from its
2806 sleep phase and forces a poll of all non-skipped servers. For compati‐
2807 bility reasons, SIGHUP can also be used in 6.3.X but may not be avail‐
2808 able in future fetchmail versions.
2809 If fetchmail is running in daemon mode as non-root, use SIGUSR1 to wake
2811 it (this is so SIGHUP due to logout can retain the default action of
2812 killing it).
2813 Running fetchmail in foreground while a background fetchmail is running
2815 will do whichever of these is appropriate to wake it up.
2816
2819 Please check the NEWS file that shipped with fetchmail for more known
2820 bugs than those listed here.
2821 Fetchmail cannot handle user names that contain blanks after a "@"
2823 character, for instance "demonstr@ti on". These are rather uncommon and
2824 only hurt when using UID-based --keep setups, so the 6.3.X versions of
2825 fetchmail won't be fixed.
2826 Fetchmail cannot handle configurations where you have multiple accounts
2828 that use the same server name and the same login. Any user@server com‐
2829 bination must be unique.
2830 The assumptions that the DNS and in particular the checkalias options
2832 make are not often sustainable. For instance, it has become uncommon
2833 for an MX server to be a POP3 or IMAP server at the same time. There‐
2834 fore the MX lookups may go away in a future release.
2835 The mda and plugin options interact badly. In order to collect error
2837 status from the MDA, fetchmail has to change its normal signal handling
2838 so that dead plugin processes don't get reaped until the end of the
2839 poll cycle. This can cause resource starvation if too many zombies ac‐
2840 cumulate. So either don't deliver to a MDA using plugins or risk being
2841 overrun by an army of undead.
2842 The --interface option does not support IPv6 and it is doubtful if it
2844 ever will, since there is no portable way to query interface IPv6 ad‐
2845 dresses.
2846 The RFC822 address parser used in multidrop mode chokes on some @-ad‐
2848 dresses that are technically legal but bizarre. Strange uses of quot‐
2849 ing and embedded comments are likely to confuse it.
2850 In a message with multiple envelope headers, only the last one pro‐
2852 cessed will be visible to fetchmail.
2853 Use of some of these protocols requires that the program send unen‐
2855 crypted passwords over the TCP/IP connection to the mailserver. This
2856 creates a risk that name/password pairs might be snaffled with a packet
2857 sniffer or more sophisticated monitoring software. Under Linux and
2858 FreeBSD, the --interface option can be used to restrict polling to
2859 availability of a specific interface device with a specific local or
2860 remote IP address, but snooping is still possible if (a) either host
2861 has a network device that can be opened in promiscuous mode, or (b) the
2862 intervening network link can be tapped. We recommend the use of ssh(1)
2863 tunnelling to not only shroud your passwords but encrypt the entire
2864 conversation.
2865 Use of the %F or %T escapes in an mda option could open a security
2867 hole, because they pass text manipulable by an attacker to a shell com‐
2868 mand. Potential shell characters are replaced by '_' before execution.
2869 The hole is further reduced by the fact that fetchmail temporarily dis‐
2870 cards any suid privileges it may have while running the MDA. For maxi‐
2871 mum safety, however, don't use an mda command containing %F or %T when
2872 fetchmail is run from the root account itself.
2873 Fetchmail's method of sending bounces due to errors or spam-blocking
2875 and spam bounces requires that port 25 of localhost be available for
2876 sending mail via SMTP.
2877 If you modify ~/.fetchmailrc while a background instance is running and
2879 break the syntax, the background instance will die silently. Unfortu‐
2880 nately, it can't die noisily because we don't yet know whether syslog
2881 should be enabled. On some systems, fetchmail dies quietly even if
2882 there is no syntax error; this seems to have something to do with buggy
2883 terminal ioctl code in the kernel.
2884 The -f - option (reading a configuration from stdin) is incompatible
2886 with the plugin option.
2887 The 'principal' option only handles Kerberos IV, not V.
2889 Interactively entered passwords are truncated after 63 characters. If
2891 you really need to use a longer password, you will have to use a con‐
2892 figuration file.
2893 A backslash as the last character of a configuration file will be
2895 flagged as a syntax error rather than ignored.
2896 The BSMTP error handling is virtually nonexistent and may leave broken
2898 messages behind.
2899 Send comments, bug reports, gripes, and the like to the fetchmail-devel
2901 list ⟨fetchmail-devel@lists.sourceforge.net⟩
2902 An HTML FAQ ⟨https://fetchmail.sourceforge.io/fetchmail-FAQ.html⟩ is
2905 available at the fetchmail home page, it should also accompany your in‐
2906 stallation.
2907
2910 Fetchmail is currently maintained by Matthias Andree and Rob Funk with
2911 major assistance from Sunil Shetye (for code) and Rob MacGregor (for
2912 the mailing lists).
2913 Most of the code is from Eric S. Raymond ⟨esr@snark.thyrsus.com⟩ . Too
2915 many other people to name here have contributed code and patches.
2916 This program is descended from and replaces popclient, by Carl Harris
2918 ⟨ceharris@mal.com⟩ ; the internals have become quite different, but
2919 some of its interface design is directly traceable to that ancestral
2920 program.
2921 This manual page has been improved by Matthias Andree, R. Hannes Bein‐
2923 ert, and Héctor García.
2924
2927 README, README.SSL, README.SSL-SERVER, The Fetchmail FAQ ⟨https://
2928 www.fetchmail.info/fetchmail-FAQ.html⟩, mutt(1), elm(1), mail(1), send‐
2929 mail(8), popd(8), imapd(8), netrc(5).
2930 The fetchmail home page. ⟨https://www.fetchmail.info/⟩
2932 The fetchmail home page (alternative URI). ⟨https://
2934 fetchmail.sourceforge.io/⟩
2935 The maildrop home page. ⟨https://www.courier-mta.org/maildrop/⟩
2937
2939 Note that this list is just a collection of references and not a state‐
2940 ment as to the actual protocol conformance or requirements in fetch‐
2941 mail.
2942 SMTP/ESMTP:
2944 RFC 821, RFC 2821, RFC 1869, RFC 1652, RFC 1870, RFC 1983, RFC
2945 1985, RFC 2554.
2946 mail:
2948 RFC 822, RFC 2822, RFC 1123, RFC 1892, RFC 1894.
2949 POP2:
2951 RFC 937
2952 POP3:
2954 RFC 1081, RFC 1225, RFC 1460, RFC 1725, RFC 1734, RFC 1939, RFC
2955 1957, RFC 2195, RFC 2449.
2956 APOP:
2958 RFC 1939.
2959 RPOP:
2961 RFC 1081, RFC 1225.
2962 IMAP2/IMAP2BIS:
2964 RFC 1176, RFC 1732.
2965 IMAP4/IMAP4rev1:
2967 RFC 1730, RFC 1731, RFC 1732, RFC 2060, RFC 2061, RFC 2195, RFC
2968 2177, RFC 2683.
2969 ETRN:
2971 RFC 1985.
2972 ODMR/ATRN:
2974 RFC 2645.
2975 OTP: RFC 1938.
2977 LMTP:
2979 RFC 2033.
2980 GSSAPI:
2982 RFC 1508, RFC 1734, Generic Security Service Application Program
2983 Interface (GSSAPI)/Kerberos/Simple Authentication and Security
2984 Layer (SASL) Service Names ⟨https://www.iana.org/assignments/
2985 gssapi-service-names/⟩.
2986 TLS: RFC 2595.
2988fetchmail 6.4.19 2021-03-29 fetchmail(1)