1fetchmail(1)              fetchmail reference manual              fetchmail(1)
2
3
4

NAME

6       fetchmail - fetch mail from a POP, IMAP, ETRN, or ODMR-capable server
7
8

SYNOPSIS

10       fetchmail [option...] [mailserver...]
11       fetchmailconf
12
13

DESCRIPTION

15       fetchmail  is  a mail-retrieval and forwarding utility; it fetches mail
16       from remote mail servers 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
22       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
28       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
33
34   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
40
41              env LC_ALL=C fetchmail -V -v --nodetach --nosyslog
42
43              (This command line prints in English how  fetchmail  understands
44              your configuration.)
45
46
47              env LC_ALL=C fetchmail -vvv  --nodetach --nosyslog
48
49              (This  command line actually runs fetchmail with verbose English
50              output.)
51
52       Also see item #G3 in fetchmail's FAQ ⟨https://fetchmail.sourceforge.io/
53       fetchmail-FAQ.html#G3⟩
54
55       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
60

TLS (SSL) QUICKSTART

62       Your fetchmail distribution should have come with  a  README.SSL  file,
63       which  see.  It is recommended to configure all polls with --ssl --ssl‐
64       proto tls1.2+ if supported by the server,  which  configures  fetchmail
65       along  recent  IETF  proposed  standards  and  best  current practices,
66       RFC-8314, RFC-8996, RFC-8997.
67
68

CONCEPTS

70       If fetchmail is used with a POP or an IMAP server (but not with ETRN or
71       ODMR),  it has two fundamental modes of operation for each user account
72       from which it retrieves mail: singledrop- and multidrop-mode.
73
74       In singledrop-mode,
75              fetchmail assumes that all messages in the user's account (mail‐
76              box)  are  intended for a single recipient.  The identity of the
77              recipient will either default to the local user  currently  exe‐
78              cuting fetchmail, or will need to be explicitly specified in the
79              configuration file.
80
81              fetchmail uses singledrop-mode when the  fetchmailrc  configura‐
82              tion  contains  at  most a single local user specification for a
83              given server account.
84
85       In multidrop-mode,
86              fetchmail assumes that the mail server account actually contains
87              mail  intended  for  any number of different recipients.  There‐
88              fore, fetchmail must attempt to deduce the proper "envelope  re‐
89              cipient" from the mail headers of each message.  In this mode of
90              operation, fetchmail almost  resembles  a  mail  transfer  agent
91              (MTA).
92
93              Note  that  neither the POP nor IMAP protocols were intended for
94              use in this fashion, and hence envelope information is often not
95              directly  available.   The ISP must stores the envelope informa‐
96              tion in some message header and. The ISP  must  also  store  one
97              copy  of  the message per recipient. If either of the conditions
98              is not fulfilled, this process is unreliable, because  fetchmail
99              must then resort to guessing the true envelope recipient(s) of a
100              message. This usually fails for mailing list messages and  Bcc:d
101              mail, or mail for multiple recipients in your domain.
102
103              fetchmail  uses  multidrop-mode  when  more  than one local user
104              and/or a wildcard is specified for a particular  server  account
105              in the configuration file.
106
107       In ETRN and ODMR modes,
108              these  considerations do not apply, as these protocols are based
109              on SMTP, which provides explicit envelope recipient information.
110              These protocols always support multiple recipients.
111
112       As  each  message is retrieved, fetchmail normally delivers it via SMTP
113       to port 25 on the machine it is running on (localhost), just as  though
114       it  were being passed in over a normal TCP/IP link.  fetchmail provides
115       the SMTP server with an envelope recipient derived in  the  manner  de‐
116       scribed  previously.  The mail will then be delivered according to your
117       MTA's rules (the Mail Transfer Agent is usually  sendmail(8),  exim(8),
118       or  postfix(8)).   Invoking  your system's MDA (Mail Delivery Agent) is
119       the duty of your MTA.  All the  delivery-control  mechanisms  (such  as
120       .forward  files)  normally  available through your system MTA and local
121       delivery agents will therefore be applied as usual.
122
123       If your fetchmail configuration sets a local MDA  (see  the  --mda  op‐
124       tion), it will be used directly instead of talking SMTP to port 25.
125
126       If  the  program fetchmailconf is available, it will assist you in set‐
127       ting up and editing a fetchmailrc configuration.  It runs under  the  X
128       window  system and requires that the language Python and the Tk toolkit
129       (with Python bindings) be present on your system.   If  you  are  first
130       setting  up  fetchmail for single-user mode, it is recommended that you
131       use Novice mode.  Expert mode provides complete  control  of  fetchmail
132       configuration,  including  the multidrop features.  In either case, the
133       'Autoprobe' button will tell you the most capable protocol a given mail
134       server supports, and warn you of potential problems with that server.
135
136

PREFACE ON THIS MANUAL

138       Fetchmail's  run-time  strings have been translated (localized) to some
139       languages, but the manual is only available in English.  In some situa‐
140       tions,  for  comparing  output  to  manual, it may be helpful to switch
141       fetchmail to English output by overriding the locale variables, for in‐
142       stance:
143
144
145              env LC_ALL=C fetchmail # add other options before the hash
146
147
148              env LANG=en fetchmail # other options before the hash
149
150       or similar. Details vary by operating system.
151
152

GENERAL OPERATION

154       The  behavior  of fetchmail is controlled by command-line options and a
155       run control file, ~/.fetchmailrc, the syntax of which we describe in  a
156       later  section  (this  file  is  what the fetchmailconf program edits).
157       Command-line options override ~/.fetchmailrc declarations.
158
159       Each server name that you specify following the options on the  command
160       line will be queried.  If you do not specify any servers on the command
161       line, each 'poll' entry in your ~/.fetchmailrc file  will  be  queried,
162       unless the idle option is used, which see.
163
164       To facilitate the use of fetchmail in scripts and pipelines, it returns
165       an appropriate exit code upon termination -- see EXIT CODES below.
166
167       The following options modify the behavior of fetchmail.  It  is  seldom
168       necessary  to specify any of these once you have a working .fetchmailrc
169       file set up.
170
171       Almost all options have a corresponding keyword which can  be  used  to
172       declare them in a .fetchmailrc file.
173
174       Some  special  options are not covered here, but are documented instead
175       in sections on AUTHENTICATION and DAEMON MODE which follow.
176
177   General Options
178       -? | --help
179              Displays option help.
180
181       -V | --version
182              Displays the version information for your copy of fetchmail.  No
183              mail  fetch  is  performed.  Instead, for each server specified,
184              all the option information that would be computed  if  fetchmail
185              were  connecting to that server is displayed.  Any non-printable
186              characters in passwords or other string names are shown as back-
187              slashed C-like escape sequences.  This option is useful for ver‐
188              ifying that your options are set the way you want them.
189
190       -c | --check
191              Return a status code to indicate whether there is mail  waiting,
192              without  actually  fetching or deleting mail (see EXIT CODES be‐
193              low).  This option turns off daemon mode (in which it  would  be
194              useless).  It does not play well with queries to multiple sites,
195              and does not work with ETRN or ODMR.  It  will  return  a  false
196              positive  if  you  leave  read but undeleted mail in your server
197              mailbox and your fetch protocol cannot tell kept  messages  from
198              new  ones.   This  means  it  will work with IMAP, not work with
199              POP2, and may occasionally flake out under POP3.
200
201       -s | --silent
202              Silent mode.  Suppresses all progress/status messages  that  are
203              normally  echoed to standard output during a fetch (but does not
204              suppress actual error messages).  The --verbose option overrides
205              this.
206
207       -v | --verbose
208              Verbose mode.  All control messages passed between fetchmail and
209              the mail server are echoed to stdout.  Overrides --silent.  Dou‐
210              bling this option (-v -v) causes extra diagnostic information to
211              be printed.
212
213       --nosoftbounce
214              (since v6.3.10, Keyword: set no softbounce, since v6.3.10)
215              Hard bounce mode. All permanent delivery errors  cause  messages
216              to  be deleted from the upstream server, see "no softbounce" be‐
217              low.
218
219       --softbounce
220              (since v6.3.10, Keyword: set softbounce, since v6.3.10)
221              Soft bounce mode. All permanent delivery errors  cause  messages
222              to be left on the upstream server if the protocol supports that.
223              This option is on by default to match historic  fetchmail  docu‐
224              mentation,  and  will be changed to hard bounce mode in the next
225              fetchmail release.
226
227   Disposal Options
228       -a | --all | (since v6.3.3) --fetchall
229              (Keyword: fetchall, since v3.0)
230              Retrieve both old (seen) and new messages from the mail  server.
231              The  default is to fetch only messages the server has not marked
232              seen.  Under POP3, this option  also  forces  the  use  of  RETR
233              rather  than  TOP.   Note  that POP2 retrieval behaves as though
234              --all is always on (see RETRIEVAL FAILURE MODES below) and  this
235              option  does not work with ETRN or ODMR.  While the -a and --all
236              command-line and fetchall rcfile options have been supported for
237              a  long  time,  the  --fetchall command-line option was added in
238              v6.3.3.
239
240       -k | --keep
241              (Keyword: keep)
242              Keep retrieved messages on the remote  mail  server.   Normally,
243              messages  are  deleted  from the folder on the mail server after
244              they have been retrieved.  Specifying the keep option causes re‐
245              trieved  messages  to  remain in your folder on the mail server.
246              This option does not work with ETRN or ODMR. If used with  POP3,
247              it is recommended to also specify the --uidl option or uidl key‐
248              word.
249
250       -K | --nokeep
251              (Keyword: nokeep)
252              Delete retrieved messages from the remote mail server.  This op‐
253              tion  forces  retrieved mail to be deleted.  It may be useful if
254              you have specified a default of keep in your .fetchmailrc.  This
255              option is forced on with ETRN and ODMR.
256
257       -F | --flush
258              (Keyword: flush)
259              POP3/IMAP  only.   This is a dangerous option and can cause mail
260              loss when used improperly. It deletes old (seen)  messages  from
261              the  mail  server before retrieving new messages.  Warning: This
262              can cause mail loss if you check your mail  with  other  clients
263              than  fetchmail,  and cause fetchmail to delete a message it had
264              never fetched before.  It can also cause mail loss if  the  mail
265              server  marks  the message seen after retrieval (IMAP2 servers).
266              You should probably not use this option  in  your  configuration
267              file.  If  you use it with POP3, you must use the 'uidl' option.
268              What you probably want is the default setting:  if  you  do  not
269              specify  '-k', then fetchmail will automatically delete messages
270              after successful delivery.
271
272       --limitflush
273              POP3/IMAP only, since version 6.3.0.  Delete oversized  messages
274              from  the  mail  server before retrieving new messages. The size
275              limit should be separately specified with  the  --limit  option.
276              This option does not work with ETRN or ODMR.
277
278   Protocol and Query Options
279       -p <proto> | --proto <proto> | --protocol <proto>
280              (Keyword: proto[col])
281              Specify  the  protocol to use when communicating with the remote
282              mail server.  If no protocol is specified, the default is  AUTO.
283              proto may be one of the following:
284
285              AUTO   Tries  IMAP,  POP3,  and  POP2 (skipping any of these for
286                     which support has not been compiled in).
287
288              POP2   Post Office Protocol 2 (legacy, to be removed from future
289                     release)
290
291              POP3   Post Office Protocol 3
292
293              APOP   Use POP3 with old-fashioned MD5-challenge authentication.
294                     Considered not resistant to man-in-the-middle attacks.
295
296              RPOP   Use POP3 with RPOP authentication.
297
298              KPOP   Use POP3 with Kerberos V4 authentication on port 1109.
299
300              SDPS   Use POP3 with Demon Internet's SDPS extensions.
301
302              IMAP   IMAP2bis, IMAP4, or  IMAP4rev1  (fetchmail  automatically
303                     detects their capabilities).
304
305              ETRN   Use the ESMTP ETRN option.
306
307              ODMR   Use the On-Demand Mail Relay ESMTP profile.
308
309       All  these  alternatives  work in basically the same way (communicating
310       with standard server daemons to fetch mail already delivered to a mail‐
311       box  on  the server) except ETRN and ODMR.  The ETRN mode allows you to
312       ask a compliant ESMTP server (such as BSD sendmail at release 8.8.0  or
313       higher) to immediately open a sender-SMTP connection to your client ma‐
314       chine and begin forwarding any items addressed to your  client  machine
315       in  the server's queue of undelivered mail.   The ODMR mode requires an
316       ODMR-capable server and works similarly to ETRN, except  that  it  does
317       not require the client machine to have a static DNS.
318
319       -U | --uidl
320              (Keyword: uidl)
321              Force  UIDL  use  (effective only with POP3).  Force client-side
322              tracking of 'newness' of messages (UIDL stands  for  "unique  ID
323              listing" and is described in RFC1939).  Use with 'keep' to use a
324              mailbox as a baby news drop for a group of users. The fact  that
325              seen  messages  are  skipped  is logged, unless error logging is
326              done through syslog while running in  daemon  mode.   Note  that
327              fetchmail  may automatically enable this option depending on up‐
328              stream server capabilities.  Note also that this option  may  be
329              removed  and  forced  enabled in a future fetchmail version. See
330              also: --idfile.
331
332       --idle (since 6.3.3)
333              (Keyword: idle, since before 6.0.0)
334              Enable IDLE use (effective only with IMAP). Note that this works
335              with  only  one  account  and  one folder at a given time, other
336              folders or accounts will not be polled when idle is  in  effect!
337              While  the  idle  rcfile  keyword  had been supported for a long
338              time, the --idle command-line option was added in version 6.3.3.
339              IDLE  use means that fetchmail tells the IMAP server to send no‐
340              tice of new messages, so they can be retrieved sooner than would
341              be possible with regular polls.
342
343       -P <portnumber> | --service <servicename>
344              (Keyword: service) Since version 6.3.0.
345              The service option permits you to specify a service name to con‐
346              nect to.  You can specify a decimal port number  here,  if  your
347              services  database  lacks the required service-port assignments.
348              See the FAQ item R12 and the --ssl  documentation  for  details.
349              This replaces the older --port option.
350
351       Note that this does not magically switch between TLS-wrapped and START‐
352       TLS modes, if you specify a port number or service name  here  that  is
353       TLS-wrapped, meaning it starts to negotiate TLS before sending applica‐
354       tion data in the clear, you may need to specify --ssl  on  the  command
355       line or ssl in your rcfile.
356
357       --port <portnumber>
358              (Keyword: port)
359              Obsolete  version of --service that does not take service names.
360              Note: this option may be removed from a future version.
361
362       --principal <principal>
363              (Keyword: principal)
364              The principal option permits you to specify a service  principal
365              for  mutual  authentication.  This is applicable to POP3 or IMAP
366              with Kerberos 4 authentication only.  It does not apply to  Ker‐
367              beros  5  or  GSSAPI.   This  option  may be removed in a future
368              fetchmail version.
369
370       -t <seconds> | --timeout <seconds>
371              (Keyword: timeout)
372              The timeout option allows you to set a server-non-response time‐
373              out  in seconds.  If a mail server does not send a greeting mes‐
374              sage or respond to commands for the  given  number  of  seconds,
375              fetchmail  will drop the connection to it.  Without such a time‐
376              out fetchmail might hang until the  TCP  connection  times  out,
377              trying  to  fetch mail from a down host, which may be very long.
378              This would be particularly annoying for a fetchmail  running  in
379              the  background.   There is a default timeout which fetchmail -V
380              will report.  If a given connection receives too  many  timeouts
381              in succession, fetchmail will consider it wedged and stop retry‐
382              ing.  The calling user will be notified by email  if  this  hap‐
383              pens.
384
385              Beginning with fetchmail 6.3.10, the SMTP client uses the recom‐
386              mended minimum timeouts from  RFC-5321  while  waiting  for  the
387              SMTP/LMTP  server  it is talking to.  You can raise the timeouts
388              even more, but you cannot shorten  them.  This  is  to  avoid  a
389              painful  situation  where  fetchmail  has been configured with a
390              short timeout (a minute or less), ships  a  long  message  (many
391              MBytes)  to  the local MTA, which then takes longer than timeout
392              to respond "OK", which it eventually will; that would  mean  the
393              mail gets delivered properly, but fetchmail cannot notice it and
394              will thus re-fetch this big message over and over again.
395
396       --plugin <command>
397              (Keyword: plugin)
398              The plugin option allows you to use an external program  to  es‐
399              tablish  the  TCP connection.  This is useful if you want to use
400              ssh, or need some special firewall setup.  The program  will  be
401              looked  up  in  $PATH and can optionally be passed the host name
402              and port as arguments using "%h"  and  "%p"  respectively  (note
403              that  the interpolation logic is rather primitive, and these to‐
404              kens must be bounded by whitespace or beginning of string or end
405              of string).  Fetchmail will write to the plugin's stdin and read
406              from the plugin's stdout.
407
408       --plugout <command>
409              (Keyword: plugout)
410              Identical to the plugin option above, but this one is  used  for
411              the SMTP connections.
412
413       -r <name> | --folder <name>
414              (Keyword: folder[s])
415              Causes  a  specified  non-default mail folder on the mail server
416              (or comma-separated list of folders) to be retrieved.  The  syn‐
417              tax  of the folder name is server-dependent.  This option is not
418              available under POP3, ETRN, or ODMR.
419
420       --tracepolls
421              (Keyword: tracepolls)
422              Tell fetchmail to poll trace information in  the  form  'polling
423              account  %s'  and 'folder %s' to the Received line it generates,
424              where the %s parts are replaced by the user's remote  name,  the
425              poll  label,  and  the folder (mailbox) where available (the Re‐
426              ceived header also normally includes the  server's  true  name).
427              This  can  be used to facilitate mail filtering based on the ac‐
428              count it is being received from. The folder information is writ‐
429              ten only since version 6.3.4.
430
431       --ssl  (Keyword: ssl)
432              Causes  the  connection  to  the mail server to be encrypted via
433              SSL, by negotiating SSL directly after connecting  (called  SSL-
434              wrapped  mode, or Implicit TLS by RFC-8314).  Please see the de‐
435              scription of --sslproto below!  More information is available in
436              the README.SSL file that ships with fetchmail.
437
438              Note  that  even  if this option is omitted, fetchmail may still
439              negotiate SSL in-band for POP3 or  IMAP,  through  the  STLS  or
440              STARTTLS  feature.   You can use the --sslproto option to modify
441              that behavior.
442
443              If no port is specified, the connection is attempted to the well
444              known  port  of  the  SSL version of the base protocol.  This is
445              generally a different port than the port used by the base proto‐
446              col.  For IMAP, this is port 143 for the clear protocol and port
447              993 for the SSL secured protocol; for POP3, it is port  110  for
448              the clear text and port 995 for the encrypted variant.
449
450              If  your  system  lacks the corresponding entries from /etc/ser‐
451              vices, see the --service option and  specify  the  numeric  port
452              number  as  given in the previous paragraph (unless your ISP had
453              directed you to different ports, which is uncommon however).
454
455       --sslcert <name>
456              (Keyword: sslcert)
457              For certificate-based client authentication.  Some SSL encrypted
458              servers  require client side keys and certificates for authenti‐
459              cation.  In most cases, this is optional.   This  specifies  the
460              location  of  the  public key certificate to be presented to the
461              server at the time the SSL session is established.   It  is  not
462              required  (but  may  be provided) if the server does not require
463              it.  It may be the same file as the private  key  (combined  key
464              and  certificate  file)  but  this  is not recommended. Also see
465              --sslkey below.
466
467              NOTE: If you use client authentication, the user name is fetched
468              from  the  certificate's  CommonName  and overrides the name set
469              with --user.
470
471       --sslkey <name>
472              (Keyword: sslkey)
473              Specifies the file name of the  client  side  private  SSL  key.
474              Some SSL encrypted servers require client side keys and certifi‐
475              cates for authentication.  In  most  cases,  this  is  optional.
476              This  specifies  the  location  of  the private key used to sign
477              transactions with the server at the time the SSL session is  es‐
478              tablished.   It  is  not  required  (but may be provided) if the
479              server does not require it. It may be the same file as the  pub‐
480              lic key (combined key and certificate file) but this is not rec‐
481              ommended.
482
483              If a password is required to unlock the key, it will be prompted
484              for  at  the  time just prior to establishing the session to the
485              server.  This can cause some complications in daemon mode.
486
487              Also see --sslcert above.
488
489       --sslproto <value>
490              (Keyword: sslproto, NOTE: semantic changes since v6.4.0)
491              This option has a dual use, out of historic fetchmail behaviour.
492              It  controls  both the SSL/TLS protocol version and, if --ssl is
493              not specified, the STARTTLS behaviour (upgrading the protocol to
494              an  SSL  or TLS connection in-band). Some other options may how‐
495              ever make TLS mandatory.
496
497              Only if this option and --ssl are both missing for a poll, there
498              will  be  opportunistic  TLS  for POP3 and IMAP, where fetchmail
499              will attempt to upgrade to TLSv1 or newer.
500
501              Recognized values for --sslproto are  given  below.  You  should
502              normally  choose  one  of  the  auto-negotiating  options, i. e.
503              'tls1.2+' or ´auto' or one of the other options ending in a plus
504              (+)  character.   Note that depending on OpenSSL library version
505              and configuration, some options cause  run-time  errors  because
506              the  requested SSL or TLS versions are not supported by the par‐
507              ticular installed OpenSSL library.
508
509              'TLS1.2+'
510                     (recommended). Since v6.4.0. Require TLS.  Auto-negotiate
511                     TLSv1.2 or newer.
512
513              'auto' (default).  Since  v6.4.0.  Require  TLS.  Auto-negotiate
514                     TLSv1 or  newer,  disable  SSLv3  downgrade.   (fetchmail
515                     6.3.26  and older have auto-negotiated all protocols that
516                     their OpenSSL library  supported,  including  the  broken
517                     SSLv3).
518
519              '', the empty string
520                     Disable  STARTTLS. If --ssl is given for the same server,
521                     log an error and pretend that 'auto' had  been  used  in‐
522                     stead.
523
524              'SSL23'
525                     see 'auto'.
526
527              'SSL3' Require  SSLv3 exactly. SSLv3 is broken, not supported on
528                     all systems, avoid it if possible.  This will make fetch‐
529                     mail  negotiate  SSLv3  only, and is the only way besides
530                     'SSL3+' to have fetchmail 6.4.0 or newer permit SSLv3.
531
532              'SSL3+'
533                     same as 'auto', but permit SSLv3 as  well.  This  is  the
534                     only  way besides 'SSL3' to have fetchmail 6.4.0 or newer
535                     permit SSLv3.
536
537              'TLS1' Require TLSv1. This does not negotiate TLSv1.1 or  newer,
538                     and  is  discouraged.  Replace by TLS1+ unless the latter
539                     chokes your server.
540
541              'TLS1+'
542                     Since v6.4.0. See 'auto'.
543
544              'TLS1.1'
545                     Since v6.4.0. Require TLS v1.1 exactly.
546
547              'TLS1.1+'
548                     Since v6.4.0.  Require  TLS.  Auto-negotiate  TLSv1.1  or
549                     newer.
550
551              'TLS1.2'
552                     Since v6.4.0. Require TLS v1.2 exactly.
553
554              'TLS1.3'
555                     Since v6.4.0. Require TLS v1.3 exactly.
556
557              'TLS1.3+'
558                     Since  v6.4.0.  Require  TLS.  Auto-negotiate  TLSv1.3 or
559                     newer.
560
561              Unrecognized parameters
562                     are treated the same as 'auto'.
563
564              NOTE: you should hardly ever need to use anything other than  ''
565              (to force an unencrypted connection) or 'auto' (to enforce TLS).
566
567       --sslcertck
568              (Keyword: sslcertck, default enabled since v6.4.0)
569              --sslcertck causes fetchmail to require that SSL/TLS be used and
570              disconnect unless it can successfully negotiate SSL or  TLS,  or
571              if  it  cannot  successfully verify and validate the certificate
572              and follow it to a trust anchor (or trusted  root  certificate).
573              The  trust  anchors are given as a set of local trusted certifi‐
574              cates (see the sslcertfile  and  sslcertpath  options).  If  the
575              server certificate cannot be obtained or is not signed by one of
576              the trusted ones (directly or indirectly), fetchmail  will  dis‐
577              connect, regardless of the sslfingerprint option.
578
579       --nosslcertck
580              (Keyword: no sslcertck, only in v6.4.X)
581              The  opposite  of  --sslcertck, this is a discouraged option. It
582              permits fetchmail to continue connecting even if the server cer‐
583              tificate  failed  the  verification checks.  Should only be used
584              together with --sslfingerprint.
585
586       --sslcertfile <file>
587              (Keyword: sslcertfile, since v6.3.17)
588              Sets the file fetchmail uses to look up local certificates.  The
589              default  is  empty.  This can be given in addition to --sslcert‐
590              path below, and certificates specified in --sslcertfile will  be
591              processed before those in --sslcertpath.  The option can be used
592              in addition to --sslcertpath.
593
594              The file is a  text  file.  It  contains  the  concatenation  of
595              trusted CA certificates in PEM format.
596
597              Note  that  using  this option will suppress loading the default
598              SSL trusted CA certificates file unless you set the  environment
599              variable  FETCHMAIL_INCLUDE_DEFAULT_X509_CA_CERTS to a non-empty
600              value.
601
602       --sslcertpath <directory>
603              (Keyword: sslcertpath)
604              Sets the directory fetchmail uses to look up local certificates.
605              The  default  is  your  OpenSSL default directory. The directory
606              must be hashed the way OpenSSL expects it - every time  you  add
607              or  modify  a  certificate in the directory, you need to use the
608              c_rehash tool (which comes with OpenSSL in the tools/ sub-direc‐
609              tory).  Also,  after OpenSSL upgrades, you may need to run c_re‐
610              hash.
611
612              This can be given in addition to --sslcertfile above, which  see
613              for precedence rules.
614
615              Note that using this option will suppress adding the default SSL
616              trusted CA certificates directory unless you set the environment
617              variable  FETCHMAIL_INCLUDE_DEFAULT_X509_CA_CERTS to a non-empty
618              value.
619
620       --sslcommonname <common name>
621              (Keyword: sslcommonname; since v6.3.9)
622              Use of this option is discouraged. Before using it, contact  the
623              administrator  of  your upstream server and ask for a proper SSL
624              certificate to be used. If that cannot be attained, this  option
625              can  be used to specify the name (CommonName) that fetchmail ex‐
626              pects on the server certificate.  A correctly configured  server
627              will  have this set to the host name by which it is reached, and
628              by default fetchmail will expect as much. Use this  option  when
629              the  CommonName is set to some other value, to avoid the "Server
630              CommonName mismatch" warning, and only if the upstream  server's
631              operator cannot be made to use proper certificates.
632
633       --sslfingerprint <fingerprint>
634              (Keyword: sslfingerprint)
635              Specify  the  fingerprint  of the server key (an MD5 hash of the
636              key) in hexadecimal notation with colons  separating  groups  of
637              two digits. The letter hex digits must be in upper case. This is
638              the format that fetchmail uses to report the fingerprint when an
639              SSL connection is established. When this is specified, fetchmail
640              will compare the server key fingerprint with the given one,  and
641              the connection will fail if they do not match, regardless of the
642              sslcertck setting. The connection will also  fail  if  fetchmail
643              cannot  obtain  an SSL certificate from the server.  This can be
644              used to prevent man-in-the-middle attacks, but the finger  print
645              from the server must be obtained or verified over a secure chan‐
646              nel, and certainly not over the same  Internet  connection  that
647              fetchmail would use.
648
649              Using this option will prevent printing certificate verification
650              errors as long as --nosslcertck is in effect.
651
652              To obtain the fingerprint of a certificate stored  in  the  file
653              cert.pem, try:
654
655                   openssl x509 -in cert.pem -noout -md5 -fingerprint
656
657              For details, see x509(1ssl).
658
659   Delivery Control Options
660       -S <hosts> | --smtphost <hosts>
661              (Keyword: smtp[host])
662              Specify  a  hunt  list  of hosts to forward mail to (one or more
663              host names, comma-separated). Hosts are tried in list order; the
664              first  one that is up becomes the forwarding target for the cur‐
665              rent run.  If this option is not specified, 'localhost' is  used
666              as the default.  Each host name may have a port number following
667              the host name.  The port number is separated from the host  name
668              by a slash; the default port is "smtp".  If you specify an abso‐
669              lute path name (beginning with a /), it will be  interpreted  as
670              the name of a UNIX socket accepting LMTP connections (such as is
671              supported by the Cyrus IMAP daemon) Example:
672
673                   --smtphost server1,server2/2525,server3,/var/imap/socket/lmtp
674
675              This option can be used with ODMR, and will make fetchmail a re‐
676              lay between the ODMR server and SMTP or LMTP receiver.
677
678              WARNING:  if  you use address numeric IP addresses here, be sure
679              to use --smtpaddress or --smtpname (either of which see) with  a
680              valid SMTP address literal!
681
682       --fetchdomains <hosts>
683              (Keyword: fetchdomains)
684              In  ETRN or ODMR mode, this option specifies the list of domains
685              the server should ship mail for once the  connection  is  turned
686              around.   The  default is the FQDN of the machine running fetch‐
687              mail.
688
689       -D <domain> | --smtpaddress <domain>
690              (Keyword: smtpaddress)
691              Specify the domain to be appended to addresses in RCPT TO  lines
692              shipped  to  SMTP.  When  this is not specified, the name of the
693              SMTP server (as specified by --smtphost) is used  for  SMTP/LMTP
694              and 'localhost' is used for UNIX socket/BSMTP.
695
696              NOTE:  if  you intend to use numeric addresses, or so-called ad‐
697              dress literals per the SMTP standard, write them in proper  SMTP
698              syntax,  for  instance  --smtpaddress "[192.0.2.6]" or --smtpad‐
699              dress "[IPv6:2001:DB8::6]".
700
701       --smtpname <user@domain>
702              (Keyword: smtpname)
703              Specify the domain and user to be put in RCPT TO  lines  shipped
704              to  SMTP.   The  default  user is the current local user. Please
705              also see the  NOTE  about  --smtpaddress  and  address  literals
706              above.
707
708       -Z <nnn> | --antispam <nnn[, nnn]...>
709              (Keyword: antispam)
710              Specifies  the list of numeric SMTP errors that are to be inter‐
711              preted as a spam-block response from the listener.  A  value  of
712              -1  disables this option.  For the command-line option, the list
713              values should be comma-separated.  Note that the antispam values
714              only  apply  to "MAIL FROM" responses in the SMTP/LMTP dialogue,
715              but several MTAs (Postfix in its default  configuration,  qmail)
716              defer the anti-spam response code until after the RCPT TO. --an‐
717              tispam does not work in these circumstances.  Also  see  --soft‐
718              bounce (default) and its inverse.
719
720       -m <command> | --mda <command>
721              (Keyword: mda)
722              This option lets fetchmail use a Message or Local Delivery Agent
723              (MDA or LDA) directly, rather than forward via SMTP or LMTP.
724
725              To avoid losing mail, use this option only with MDAs like  mail‐
726              drop  or  MTAs  like sendmail that exit with a nonzero status on
727              disk-full and other delivery errors; the  nonzero  status  tells
728              fetchmail that delivery failed and prevents the message from be‐
729              ing deleted on the server.
730
731              If fetchmail is running as root, it sets its user id  while  de‐
732              livering  mail  through  an  MDA  as follows:  First, the FETCH‐
733              MAILUSER, LOGNAME, and USER environment variables are checked in
734              this  order.  The value of the first variable from his list that
735              is defined (even if it is empty!) is looked  up  in  the  system
736              user  database.  If  none of the variables is defined, fetchmail
737              will use the real user id it was started with.  If  one  of  the
738              variables  was  defined, but the user stated there is not found,
739              fetchmail continues running as root, without checking  remaining
740              variables  on the list.  Practically, this means that if you run
741              fetchmail as root (not recommended), it is most useful to define
742              the  FETCHMAILUSER environment variable to set the user that the
743              MDA should run as. Some MDAs (such as maildrop) are designed  to
744              be  setuid root and setuid to the recipient's user id, so you do
745              not lose functionality this way even when running  fetchmail  as
746              unprivileged user.  Check the MDA's manual for details.
747
748              Some  possible  MDAs  are  "/usr/sbin/sendmail  -i  -f %F -- %T"
749              (Note: some several older or vendor sendmail versions mistake --
750              for  an address, rather than an indicator to mark the end of the
751              option arguments), "/usr/bin/deliver" and "/usr/bin/maildrop  -d
752              %T".   Local  delivery  addresses  will be inserted into the MDA
753              command wherever you place a %T; the mail message's From address
754              will be inserted where you place an %F.
755
756              Do  NOT  enclose the %F or %T string in single quotes!  For both
757              %T and %F, fetchmail encloses the  addresses  in  single  quotes
758              ('),  after  removing any single quotes they may contain, before
759              the MDA command is passed to the shell.
760
761              Do NOT use an MDA invocation that dispatches on the contents  of
762              To/Cc/Bcc, like "sendmail -i -t" or "qmail-inject", it will cre‐
763              ate mail loops and bring the just wrath of many postmasters down
764              upon  your head.  This is one of the most frequent configuration
765              errors!
766
767              Also, do not try to combine multidrop mode with an MDA  such  as
768              maildrop  that can only accept one address, unless your upstream
769              stores one copy of the message per recipient and transports  the
770              envelope recipient in a header; you will lose mail.
771
772              The  well-known  procmail(1)  package  is very hard to configure
773              properly, it has a very nasty "fall through to  the  next  rule"
774              behavior on delivery errors (even temporary ones, such as out of
775              disk space if another user's  mail  daemon  copies  the  mailbox
776              around  to  purge old messages), so your mail will end up in the
777              wrong mailbox sooner or later. The proper procmail configuration
778              is outside the scope of this document. Using maildrop(1) is usu‐
779              ally much easier, and many users find the filter syntax used  by
780              maildrop easier to understand.
781
782              Finally,  we  strongly  advise that you do not use qmail-inject.
783              The command line interface  is  non-standard  without  providing
784              benefits for typical use, and fetchmail makes no attempts to ac‐
785              commodate qmail-inject's deviations from the standard.  Some  of
786              qmail-inject's command-line and environment options are actually
787              dangerous and can cause broken threads,  non-detected  duplicate
788              messages and forwarding loops.
789
790
791       --lmtp (Keyword: lmtp)
792              Cause  delivery via LMTP (Local Mail Transfer Protocol).  A ser‐
793              vice host and port must be explicitly specified on each host  in
794              the  smtphost  hunt list (see above) if this option is selected;
795              the default port 25 will (in accordance with RFC  2033)  not  be
796              accepted.
797
798       --bsmtp <filename>
799              (Keyword: bsmtp)
800              Append  fetched  mail to a BSMTP file.  This simply contains the
801              SMTP commands that would normally be generated by fetchmail when
802              passing mail to an SMTP listener daemon.
803
804              An  argument of '-' causes the SMTP batch to be written to stan‐
805              dard output, which is of limited use: this only makes sense  for
806              debugging, because fetchmail's regular output is interspersed on
807              the same channel, so this is not  suitable  for  mail  delivery.
808              This special mode may be removed in a later release.
809
810              Note  that  fetchmail's  reconstruction of MAIL FROM and RCPT TO
811              lines is not guaranteed correct; the caveats discussed under THE
812              USE AND ABUSE OF MULTIDROP MAILBOXES below apply.  This mode has
813              precedence before --mda and SMTP/LMTP.
814
815       --bad-header {reject|accept}
816              (Keyword: bad-header; since v6.3.15)
817              Specify how fetchmail is supposed to  treat  messages  with  bad
818              headers, i. e. headers with bad syntax. Traditionally, fetchmail
819              has rejected  such  messages,  but  some  distributors  modified
820              fetchmail  to accept them. You can now configure fetchmail's be‐
821              haviour per server.
822
823
824   Resource Limit Control Options
825       -l <maxbytes> | --limit <maxbytes>
826              (Keyword: limit)
827              Takes a maximum octet size argument, where 0 is the default  and
828              also the special value designating "no limit".  If nonzero, mes‐
829              sages larger than this size will not be fetched and will be left
830              on  the  server  (in  foreground sessions, the progress messages
831              will note that they are "oversized").   If  the  fetch  protocol
832              permits  (in particular, under IMAP or POP3 without the fetchall
833              option) the message will not be marked seen.
834
835              An explicit --limit of 0 overrides any limits set  in  your  run
836              control  file.  This  option  is  intended  for those needing to
837              strictly control fetch time due to expensive and variable  phone
838              rates.
839
840              Combined  with  --limitflush, it can be used to delete oversized
841              messages waiting on a server.  In daemon mode, oversize  notifi‐
842              cations  are  mailed to the calling user (see the --warnings op‐
843              tion). This option does not work with ETRN or ODMR.
844
845       -w <interval> | --warnings <interval>
846              (Keyword: warnings)
847              Takes an interval in seconds.  When you call  fetchmail  with  a
848              'limit'  option  in  daemon  mode, this controls the interval at
849              which warnings about oversized messages are mailed to the  call‐
850              ing  user  (or  the  user specified by the 'postmaster' option).
851              One such notification is always mailed at the end of  the  first
852              poll that the oversized message is detected.  Thereafter, re-no‐
853              tification  is  suppressed  until  after  the  warning  interval
854              elapses  (it  will  take place at the end of the first following
855              poll).
856
857       -b <count> | --batchlimit <count>
858              (Keyword: batchlimit)
859              Specify the maximum number of messages that will be  shipped  to
860              an SMTP listener before the connection is deliberately torn down
861              and rebuilt (defaults to 0,  meaning  no  limit).   An  explicit
862              --batchlimit  of  0 overrides any limits set in your run control
863              file.  While sendmail(8) normally initiates delivery of  a  mes‐
864              sage  immediately  after  receiving the message terminator, some
865              SMTP listeners are not so prompt.  MTAs like smail(8)  may  wait
866              till the delivery socket is shut down to deliver.  This may pro‐
867              duce annoying delays when fetchmail  is  processing  very  large
868              batches.  Setting the batch limit to some nonzero size will pre‐
869              vent these delays.  This option does not work with ETRN or ODMR.
870
871       -B <number> | --fetchlimit <number>
872              (Keyword: fetchlimit)
873              Limit the number of messages accepted from a given server  in  a
874              single poll.  By default there is no limit. An explicit --fetch‐
875              limit of 0 overrides any limits set in your  run  control  file.
876              This option does not work with ETRN or ODMR.
877
878       --fetchsizelimit <number>
879              (Keyword: fetchsizelimit)
880              Limit  the  number  of  sizes  of messages accepted from a given
881              server in a single transaction.  This option is useful in reduc‐
882              ing  the  delay in downloading the first mail when there are too
883              many mails in the mailbox.  By default, the limit  is  100.   If
884              set  to  0,  sizes  of all messages are downloaded at the start.
885              This option does not work with ETRN or ODMR.  For POP3, the only
886              valid non-zero value is 1.
887
888       --fastuidl <number>
889              (Keyword: fastuidl)
890              Do  a  binary instead of linear search for the first unseen UID.
891              Binary search avoids downloading the UIDs  of  all  mails.  This
892              saves  time  (especially  in  daemon mode) where downloading the
893              same set of UIDs in each poll is a waste of bandwidth. The  num‐
894              ber  'n' indicates how rarely a linear search should be done. In
895              daemon mode, linear search  is  used  once  followed  by  binary
896              searches  in 'n-1' polls if 'n' is greater than 1; binary search
897              is always used if 'n' is 1; linear search is always used if  'n'
898              is  0.  In  non-daemon  mode, binary search is used if 'n' is 1;
899              otherwise linear search is used. The default value of 'n' is  4.
900              This option works with POP3 only.
901
902       -e <count> | --expunge <count>
903              (Keyword: expunge)
904              Arrange  for  deletions to be made final after a given number of
905              messages.  Under POP2 or POP3, fetchmail cannot  make  deletions
906              final  without  sending QUIT and ending the session -- with this
907              option on, fetchmail will break a long  mail  retrieval  session
908              into multiple sub-sessions, sending QUIT after each sub-session.
909              This is a good defense against line drops on POP3 servers.   Un‐
910              der  IMAP,  fetchmail  normally  issues an EXPUNGE command after
911              each deletion in order to force the deletion to be done  immedi‐
912              ately.   This  is  safest  when your connection to the server is
913              flaky and expensive, as it avoids re-sending duplicate mail  af‐
914              ter a line hit.  However, on large mailboxes the overhead of re-
915              indexing after every message can slam the server pretty hard, so
916              if  your  connection  is reliable it is good to do expunges less
917              frequently.  Also note that some servers enforce a  delay  of  a
918              few seconds after each quit, so fetchmail may not be able to get
919              back in immediately after an expunge -- you may see "lock  busy"
920              errors if this happens. If you specify this option to an integer
921              N, it tells fetchmail  to  only  issue  expunges  on  every  Nth
922              delete.  An argument of zero suppresses expunges entirely (so no
923              expunges at all will be done until the end of run).  This option
924              does not work with ETRN or ODMR.
925
926
927   Authentication Options
928       -u <name> | --user <name> | --username <name>
929              (Keyword: user[name])
930              Specifies  the user identification to be used when logging in to
931              the mail server.  The appropriate user  identification  is  both
932              server  and  user-dependent.   The default is your login name on
933              the client machine that is running fetchmail.  See USER  AUTHEN‐
934              TICATION below for a complete description.
935
936       -I <specification> | --interface <specification>
937              (Keyword: interface)
938              Require  that  a specific interface device be up and have a spe‐
939              cific local or remote IPv4 (IPv6 is not supported by this option
940              yet) address (or range) before polling.  Frequently fetchmail is
941              used over a transient point-to-point TCP/IP link established di‐
942              rectly  to  a mail server via SLIP or PPP.  That is a relatively
943              secure channel.  But when other TCP/IP routes to the mail server
944              exist  (e.g.,  when  the link is connected to an alternate ISP),
945              your username and password may be vulnerable to snooping  (espe‐
946              cially when daemon mode automatically polls for mail, shipping a
947              clear password over the  net  at  predictable  intervals).   The
948              --interface option may be used to prevent this.  When the speci‐
949              fied link is not up or is not connected to  a  matching  IP  ad‐
950              dress, polling will be skipped.  The format is:
951
952                   interface/iii.iii.iii.iii[/mmm.mmm.mmm.mmm]
953
954              The  field  before  the first slash is the interface name (i.e.,
955              sl0, ppp0 etc.).  The field before the second slash is  the  ac‐
956              ceptable IP address.  The field after the second slash is a mask
957              which specifies a range of IP addresses to accept.  If  no  mask
958              is  present  255.255.255.255  is assumed (i.e., an exact match).
959              This option is currently only supported under Linux and FreeBSD.
960              Please  see  the  monitor section for below for FreeBSD specific
961              information.
962
963              Note that this option may be removed  from  a  future  fetchmail
964              version.
965
966       -M <interface> | --monitor <interface>
967              (Keyword: monitor)
968              Daemon  mode  can  cause transient links which are automatically
969              taken down after a period of inactivity (e.g., PPP links) to re‐
970              main  up  indefinitely.   This option identifies a system TCP/IP
971              interface to be monitored for activity.  After each poll  inter‐
972              val, if the link is up but no other activity has occurred on the
973              link, then the poll will be skipped.  However, when fetchmail is
974              woken  up by a signal, the monitor check is skipped and the poll
975              goes through unconditionally.  This  option  is  currently  only
976              supported  under  Linux and FreeBSD.  For the monitor and inter‐
977              face options to work for  non  root  users  under  FreeBSD,  the
978              fetchmail binary must be installed setgid kmem.  This would be a
979              security hole, but fetchmail runs with the effective GID set  to
980              that  of  the  kmem group only when interface data is being col‐
981              lected.
982
983              Note that this option may be removed  from  a  future  fetchmail
984              version.
985
986       --auth <type>
987              (Keyword: auth[enticate])
988              This  option  permits you to specify an authentication type (see
989              USER AUTHENTICATION below for details).  The possible values are
990              any,  password,  kerberos_v5, kerberos (or, for excruciating ex‐
991              actness, kerberos_v4), gssapi, cram-md5, otp,  ntlm,  msn  (only
992              for POP3), external (only IMAP) and ssh.  When any (the default)
993              is specified, fetchmail tries first methods that do not  require
994              a  password (EXTERNAL, GSSAPI, KERBEROS IV, KERBEROS 5); then it
995              looks for methods that mask your password (CRAM-MD5, NTLM, X-OTP
996              -  note  that  MSN  is  only  supported  for POP3, but not auto-
997              probed); and only if the server does not support  any  of  those
998              will  it  ship  your  password unencrypted.  Other values may be
999              used to force various authentication methods: ssh suppresses au‐
1000              thentication and is thus useful for IMAP PREAUTH (if you are us‐
1001              ing a secure --plugin, for instance, a properly configured  ssh,
1002              you  may  also need to set --sslproto '' or, in the rcfile, ssl‐
1003              proto '', in order to avoid fetchmail negotiating STARTTLS  over
1004              SSH).  external suppresses authentication and is thus useful for
1005              IMAP EXTERNAL.  Any value other than password,  cram-md5,  ntlm,
1006              msn or otp suppresses fetchmail's normal inquiry for a password.
1007              Specify ssh when you are using an end-to-end  secure  connection
1008              such as an ssh tunnel (in this case you may also want to specify
1009              --sslproto '', which see); specify external  when  you  use  TLS
1010              with  client authentication and specify gssapi or kerberos_v4 if
1011              you are using a protocol variant  that  employs  GSSAPI  or  K4.
1012              Choosing  KPOP protocol automatically selects Kerberos authenti‐
1013              cation.  This option does not work with  ETRN.   GSSAPI  service
1014              names are in line with RFC-2743 and IANA registrations, see
1015              Generic Security Service Application Program Interface (GSS‐
1016              API)/Kerberos/Simple Authentication and Security Layer (SASL)
1017              Service Names ⟨https://www.iana.org/assignments/
1018              gssapi-service-names/⟩.
1019
1020   Miscellaneous Options
1021       -f <pathname> | --fetchmailrc <pathname>
1022              Specify  a  non-default  name for the ~/.fetchmailrc run control
1023              file.  The pathname argument must be either "-" (a single  dash,
1024              meaning  to  read  the  configuration  from standard input) or a
1025              filename.  Unless the --version option is also on, a named  file
1026              argument   must   have   permissions  no  more  open  than  0700
1027              (u=rwx,g=,o=) or else be /dev/null.
1028
1029       -i <pathname> | --idfile <pathname>
1030              (Keyword: idfile)
1031              Specify an alternate name for the .fetchids file  used  to  save
1032              message  UIDs.  NOTE: since fetchmail 6.3.0, write access to the
1033              directory containing the idfile is required, as fetchmail writes
1034              a  temporary  file and renames it into the place of the real id‐
1035              file only if the temporary file has been  written  successfully.
1036              This  avoids  the truncation of idfiles when running out of disk
1037              space.
1038
1039       --pidfile <pathname>
1040              (Keyword: pidfile; since fetchmail v6.3.4)
1041              Override the default location of the PID file that is used as  a
1042              lock  file.   Default:  see  "ENVIRONMENT" below. Note that many
1043              places in the code and documentation, the term  "lock  file"  is
1044              used.   This  file contains the process ID of the running fetch‐
1045              mail on the first line and potentially the daemon interval on  a
1046              second line.
1047
1048       -n | --norewrite
1049              (Keyword: no rewrite)
1050              Normally, fetchmail edits RFC-822 address headers (To, From, Cc,
1051              Bcc, and Reply-To) in fetched mail so that any mail IDs local to
1052              the server are expanded to full addresses (@ and the mail server
1053              host name are appended).  This enables replies on the client  to
1054              get  addressed correctly (otherwise your mailer might think they
1055              should be addressed to local  users  on  the  client  machine!).
1056              This  option  disables the rewrite.  (This option is provided to
1057              pacify people who are paranoid about having  an  MTA  edit  mail
1058              headers  and  want to know they can prevent it, but it is gener‐
1059              ally not a good idea to actually turn off rewrite.)  When  using
1060              ETRN or ODMR, the rewrite option is ineffective.
1061
1062       -E <line> | --envelope <line>
1063              (Keyword: envelope; Multidrop only)
1064              In the configuration file, an enhanced syntax is used:
1065              envelope [<count>] <line>
1066
1067              This  option  changes  the header fetchmail assumes will carry a
1068              copy of the mail's envelope address.  Normally this is  'X-Enve‐
1069              lope-To'.   Other  typically found headers to carry envelope in‐
1070              formation are 'X-Original-To' and  'Delivered-To'.   Now,  since
1071              these  headers  are  not  standardized, practice varies. See the
1072              discussion of multidrop address handling below.   As  a  special
1073              case,  'envelope  "Received"'  enables parsing of sendmail-style
1074              Received lines.  This is the default, but discouraged because it
1075              is not fully reliable.
1076
1077              Note  that  fetchmail  expects the Received-line to be in a spe‐
1078              cific format: It must contain "by host for address", where  host
1079              must  match  one  of the mail server names that fetchmail recog‐
1080              nizes for the account in question.
1081
1082              The optional count argument (only available in the configuration
1083              file) determines how many header lines of this kind are skipped.
1084              A count of 1 means: skip the first, take the second. A count  of
1085              2 means: skip the first and second, take the third, and so on.
1086
1087       -Q <prefix> | --qvirtual <prefix>
1088              (Keyword: qvirtual; Multidrop only)
1089              The  string  prefix assigned to this option will be removed from
1090              the user name found in the header specified  with  the  envelope
1091              option  (before  doing  multidrop  name  mapping  or localdomain
1092              checking, if either is applicable). This option is useful if you
1093              are using fetchmail to collect the mail for an entire domain and
1094              your ISP (or your mail redirection  provider)  is  using  qmail.
1095              One  of the basic features of qmail is the Delivered-To: message
1096              header.  Whenever qmail delivers a message to a local mailbox it
1097              puts  the  username  and  host name of the envelope recipient on
1098              this line.  The major reason for this is to prevent mail  loops.
1099              To  set  up qmail to batch mail for a disconnected site the ISP-
1100              mailhost will have normally put that site in its  'Virtualhosts'
1101              control  file  so it will add a prefix to all mail addresses for
1102              this site. This results in mail sent to 'username@userhost.user‐
1103              dom.dom.com' having a Delivered-To: line of the form:
1104
1105              Delivered-To: mbox-userstr-username@userhost.example.com
1106
1107              The ISP can make the 'mbox-userstr-' prefix anything they choose
1108              but a string matching the user host name is  likely.   By  using
1109              the option 'envelope Delivered-To:' you can make fetchmail reli‐
1110              ably identify the original envelope recipient, but you  have  to
1111              strip the 'mbox-userstr-' prefix to deliver to the correct user.
1112              This is what this option is for.
1113
1114       --configdump
1115              Parse the ~/.fetchmailrc file, interpret  any  command-line  op‐
1116              tions  specified,  and  dump  a configuration report to standard
1117              output.  The configuration report is a data structure assignment
1118              in the language Python.  This option is meant to be used with an
1119              interactive ~/.fetchmailrc editor like fetchmailconf, written in
1120              Python.
1121
1122       -y | --yydebug
1123              Enables parser debugging, this option is meant to be used by de‐
1124              velopers only.
1125
1126
1127   Removed Options
1128       -T | --netsec
1129              Removed before version 6.3.0, the required underlying inet6_apps
1130              library had been discontinued and is no longer available.
1131
1132

USER AUTHENTICATION AND ENCRYPTION

1134       All  modes  except  ETRN  require  authentication  of the client to the
1135       server.  Normal user authentication in fetchmail is very much like  the
1136       authentication  mechanism  of ftp(1).  The correct user-id and password
1137       depend upon the underlying security system at the mail server.
1138
1139       If the mail server is a Unix machine on which you have an ordinary user
1140       account,  your regular login name and password are used with fetchmail.
1141       If you use the same login name on both the server and  the  client  ma‐
1142       chines, you needn't worry about specifying a user-id with the -u option
1143       -- the default behavior is to use your login name on the client machine
1144       as  the  user-id  on  the server machine.  If you use a different login
1145       name on the server machine, specify that login name with the -u option.
1146       E.g.,  if  your  login name is 'jsmith' on a machine named 'mailgrunt',
1147       you would start fetchmail as follows:
1148
1149              fetchmail -u jsmith mailgrunt
1150
1151       The default behavior of fetchmail is to prompt you for your mail server
1152       password  before the connection is established.  This is the safest way
1153       to use fetchmail and ensures that your password  will  not  be  compro‐
1154       mised.  You may also specify your password in your ~/.fetchmailrc file.
1155       This is convenient when using fetchmail in daemon mode or with scripts.
1156
1157
1158   Using netrc files
1159       If you do not specify a password, and fetchmail cannot extract one from
1160       your ~/.fetchmailrc file, it will look for a ~/.netrc file in your home
1161       directory before requesting one interactively; if an entry matching the
1162       mail  server  is found in that file, the password will be used.  Fetch‐
1163       mail first looks for a match on poll name; if it finds none, it  checks
1164       for  a  match  on via name.  See the ftp(1) man page for details of the
1165       syntax of the ~/.netrc file.  To show a  practical  example,  a  .netrc
1166       might look like this:
1167
1168              machine hermes.example.org
1169              login joe
1170              password topsecret
1171
1172       You  can  repeat this block with different user information if you need
1173       to provide more than one password.
1174
1175       This feature may allow you to avoid duplicating password information in
1176       more than one file.
1177
1178       On  mail servers that do not provide ordinary user accounts, your user-
1179       id and password are usually assigned by the server  administrator  when
1180       you apply for a mailbox on the server.  Contact your server administra‐
1181       tor if you do not know the correct user-id and password for your  mail‐
1182       box account.
1183
1184
1185   Secure Socket Layers (SSL) and Transport Layer Security (TLS)
1186       All  retrieval protocols can use SSL or TLS wrapping for the transport.
1187       Additionally, POP3 and IMAP retrieval can  also  negotiate  SSL/TLS  by
1188       means of STARTTLS (or STLS).
1189
1190       Note  that fetchmail currently uses the OpenSSL library, which is some‐
1191       what under-documented, so failures may occur just because the  program‐
1192       mers  are not aware of OpenSSL's requirement of the day.  For instance,
1193       since v6.3.16, fetchmail calls OpenSSL_add_all_algorithms(),  which  is
1194       necessary to support certificates using SHA256 on OpenSSL 0.9.8 -- this
1195       information is deeply hidden in the documentation and not at all  obvi‐
1196       ous.  Please do not hesitate to report subtle TLS or SSL failures.
1197
1198       You  can access TLS-encrypted services by specifying the options start‐
1199       ing with --ssl, such as --ssl,  --sslproto,  --sslcertck,  and  others.
1200       You  can  also  do  this  using  the  corresponding user options in the
1201       .fetchmailrc file.  Some services, such as POP3 and IMAP, have  differ‐
1202       ent  well  known ports defined for the SSL encrypted services.  The en‐
1203       crypted ports will be selected automatically when SSL is enabled and no
1204       explicit  port  is  specified.    Also, the --sslcertck command line or
1205       sslcertck run control file option should be used to force  strict  cer‐
1206       tificate checking with older fetchmail versions - see below.
1207
1208       If  TLS  or  SSL is not configured, fetchmail will usually still try to
1209       use STARTTLS somewhat  opportunistically.  In  practice,  is  it  still
1210       mandatory  because  --sslcertck is a default setting and implicitly re‐
1211       quires STARTTLS.
1212
1213       STARTTLS can be enforced by using --sslproto auto and defeated by using
1214       --sslproto  ''.   STARTTLS  connections  use the same port as the unen‐
1215       crypted version of the protocol and negotiate TLS via special  command.
1216       The  --sslcertck  command  line  or  sslcertck  run control file option
1217       should be used to force strict certificate checking - see below.
1218
1219       --sslcertck is recommended: When connecting to an SSL or TLS  encrypted
1220       server, the server presents a certificate to the client for validation.
1221       The certificate is checked to verify that the common name in  the  cer‐
1222       tificate  matches  the  name of the server being contacted and that the
1223       effective and expiration dates in the certificate indicate that  it  is
1224       currently  valid.   If  any  of these checks fail, a warning message is
1225       printed, but the connection continues.  The server certificate does not
1226       need  to  be  signed  by any specific Certifying Authority and may be a
1227       "self-signed" certificate. If the --sslcertck command  line  option  or
1228       sslcertck run control file option is used, fetchmail will instead abort
1229       if any of these checks fail, because it must assume  that  there  is  a
1230       man-in-the-middle attack in this scenario, hence fetchmail must not ex‐
1231       pose clear-text passwords. Use of the sslcertck or  --sslcertck  option
1232       is therefore advised; it has become the default in fetchmail 6.4.0.
1233
1234       Some  SSL  encrypted  servers may request a client side certificate.  A
1235       client side public SSL certificate and private SSL key  may  be  speci‐
1236       fied.   If  requested  by the server, the client certificate is sent to
1237       the server for validation.  Some servers may  require  a  valid  client
1238       certificate and may refuse connections if a certificate is not provided
1239       or if the certificate is not valid.  Some servers  may  require  client
1240       side  certificates be signed by a recognized Certifying Authority.  The
1241       format for the key files and the certificate files is that required  by
1242       the underlying SSL libraries (OpenSSL in the general case).
1243
1244       A  word  of care about the use of SSL: While above mentioned setup with
1245       self-signed server certificates retrieved over the  wires  can  protect
1246       you from a passive eavesdropper, it does not help against an active at‐
1247       tacker. It is clearly an improvement  over  sending  the  passwords  in
1248       clear, but you should be aware that a man-in-the-middle attack is triv‐
1249       ially possible (in particular with tools such as dsniff ⟨https://
1250       monkey.org/~dugsong/dsniff/⟩,  ).   Use  of strict certificate checking
1251       with a certification authority recognized by server and client, or per‐
1252       haps  of  an  SSH tunnel (see below for some examples) is preferable if
1253       you care seriously about the security of your mailbox and passwords.
1254
1255

POP3 VARIANTS

1257       Early versions of POP3 (RFC1081, RFC1225) supported a crude form of in‐
1258       dependent  authentication  using  the  .rhosts  file on the mail server
1259       side.  Under this RPOP variant, a fixed per-user  ID  equivalent  to  a
1260       password  was  sent  in  clear over a link to a reserved port, with the
1261       command RPOP rather than PASS to alert the server  that  it  should  do
1262       special  checking.   RPOP  is  supported  by fetchmail (you can specify
1263       'protocol RPOP' to have the program send 'RPOP' rather than 'PASS') but
1264       its use is strongly discouraged, and support will be removed from a fu‐
1265       ture fetchmail version.  This facility was vulnerable to  spoofing  and
1266       was withdrawn in RFC1460.
1267
1268       RFC1460  introduced  APOP authentication.  In this variant of POP3, you
1269       register an APOP password on your server host  (on  some  servers,  the
1270       program to do this is called popauth(8)).  You put the same password in
1271       your ~/.fetchmailrc file.  Each time fetchmail logs in, it sends an MD5
1272       hash of your password and the server greeting time to the server, which
1273       can verify it by checking its authorization database.
1274
1275       Note that APOP is no longer considered  resistant  against  man-in-the-
1276       middle attacks.
1277
1278
1279   RETR or TOP
1280       fetchmail  makes  some  efforts to make the server believe messages had
1281       not been retrieved, by using the TOP command with  a  large  number  of
1282       lines  when  possible.  TOP is a command that retrieves the full header
1283       and a fetchmail-specified amount of body  lines.  It  is  optional  and
1284       therefore  not implemented by all servers, and some are known to imple‐
1285       ment it improperly. On many servers however, the RETR command which re‐
1286       trieves  the  full  message  with header and body, sets the "seen" flag
1287       (for instance, in a web interface), whereas the TOP command does not do
1288       that.
1289
1290       fetchmail  will  always  use  the  RETR  command  if "fetchall" is set.
1291       fetchmail will also use the RETR command if "keep" is set and "uidl" is
1292       unset.   Finally,  fetchmail  will  use the RETR command on Maillennium
1293       POP3/PROXY servers (used by Comcast) to avoid a deliberate  TOP  misin‐
1294       terpretation in this server that causes message corruption.
1295
1296       In  all  other  cases, fetchmail will use the TOP command. This implies
1297       that in "keep" setups, "uidl" must be set if "TOP" is desired.
1298
1299       Note that this description is true for the current  version  of  fetch‐
1300       mail,  but  the  behavior may change in future versions. In particular,
1301       fetchmail may prefer the RETR command because the  TOP  command  causes
1302       much grief on some servers and is only optional.
1303

ALTERNATE AUTHENTICATION FORMS/METHODS

1305       If  your fetchmail was built with Kerberos support and you specify Ker‐
1306       beros authentication (either with --auth or the .fetchmailrc option au‐
1307       thenticate  kerberos_v4)  it will try to get a Kerberos ticket from the
1308       mail server at the start of each query.  Note: if either  the  pollname
1309       or  via  name  is 'hesiod', fetchmail will try to use Hesiod to look up
1310       the mail server.
1311
1312       If you use POP3 or IMAP with GSSAPI authentication, fetchmail will  ex‐
1313       pect  the server to have RFC1731- or RFC1734-conforming GSSAPI capabil‐
1314       ity, and will use it.  Currently this has only been  tested  over  Ker‐
1315       beros 5,  so you are expected to already have a ticket-granting ticket.
1316       You may pass a username different from your principal  name  using  the
1317       standard --user command or by the .fetchmailrc option user.
1318
1319       If  your IMAP daemon returns the PREAUTH response in its greeting line,
1320       fetchmail will notice this and skip  the  normal  authentication  step.
1321       This  can be useful, e.g., if you start imapd explicitly using ssh.  In
1322       this case you can declare the authentication value 'ssh' on  that  site
1323       entry  to stop .fetchmail from asking you for a password when it starts
1324       up.
1325
1326       If you use client authentication with TLS1 and your IMAP daemon returns
1327       the AUTH=EXTERNAL response, fetchmail will notice this and will use the
1328       authentication shortcut and will not send the passphrase. In this  case
1329       you can declare the authentication value 'external'
1330        on  that site to stop fetchmail from asking you for a password when it
1331       starts up.
1332
1333       If you are using POP3, and the server issues a one-time-password  chal‐
1334       lenge conforming to RFC1938, fetchmail will use your password as a pass
1335       phrase to generate the required response. This avoids  sending  secrets
1336       over the net unencrypted.
1337
1338       Compuserve's  RPA  authentication  is  supported. If you compile in the
1339       support, fetchmail will try to perform an RPA  pass-phrase  authentica‐
1340       tion  instead  of  sending  over the password unencrypted if it detects
1341       "@compuserve.com" in the host name.
1342
1343       If you are using IMAP, Microsoft's NTLM authentication (used by  Micro‐
1344       soft  Exchange)  is supported. If you compile in the support, fetchmail
1345       will try to perform an NTLM authentication (instead of sending over the
1346       password  unencrypted) whenever the server returns AUTH=NTLM in its ca‐
1347       pability  response.  Specify  a  user  option  value  that  looks  like
1348       'user@domain':  the  part  to  the  left of the @ will be passed as the
1349       username and the part to the right as the NTLM domain.
1350
1351
1352   ESMTP AUTH
1353       fetchmail also supports authentication  to  the  ESMTP  server  on  the
1354       client  side  according  to  RFC 2554.  You can specify a name/password
1355       pair to be used with the keywords 'esmtpname' and 'esmtppassword';  the
1356       former defaults to the username of the calling user.
1357
1358

DAEMON MODE

1360   Introducing the daemon mode
1361       In daemon mode, fetchmail puts itself into the background and runs for‐
1362       ever, querying each specified  host  and  then  sleeping  for  a  given
1363       polling interval.
1364
1365   Starting the daemon mode
1366       There  are  several  ways to make fetchmail work in daemon mode. On the
1367       command line, --daemon <interval> or -d <interval> option  runs  fetch‐
1368       mail  in  daemon  mode.  You must specify a numeric argument which is a
1369       polling interval (time to wait after completing a whole poll cycle with
1370       the  last server and before starting the next poll cycle with the first
1371       server) in seconds.
1372
1373       Example: simply invoking
1374
1375              fetchmail -d 900
1376
1377       will, therefore, poll all the hosts described  in  your  ~/.fetchmailrc
1378       file (except those explicitly excluded with the 'skip' verb) a bit less
1379       often than once every 15 minutes (exactly: 15 minutes + time  that  the
1380       poll takes).
1381
1382       It  is  also  possible to set a polling interval in your ~/.fetchmailrc
1383       file by saying 'set daemon <interval>', where <interval> is an  integer
1384       number of seconds.  If you do this, fetchmail will always start in dae‐
1385       mon mode unless you override it with the command-line option --daemon 0
1386       or -d0.
1387
1388       Only  one  daemon process is permitted per user; in daemon mode, fetch‐
1389       mail sets up a per-user lock file to guarantee this.  (You can  however
1390       cheat  and  set the FETCHMAILHOME environment variable to overcome this
1391       setting, but in that case, it is your responsibility to make  sure  you
1392       are not polling the same server with two processes at the same time.)
1393
1394   Awakening the background daemon
1395       Normally,  calling  fetchmail  with  a daemon in the background sends a
1396       wake-up signal to the daemon and quits without output.  The  background
1397       daemon  then  starts its next poll cycle immediately.  The wake-up sig‐
1398       nal, SIGUSR1, can also be sent manually. The wake-up action also clears
1399       any  'wedged'  flags  indicating  that  connections  have wedged due to
1400       failed authentication or multiple timeouts.
1401
1402   Terminating the background daemon
1403       The option -q or --quit will kill a running daemon process  instead  of
1404       waking  it up (if there is no such process, fetchmail will notify you).
1405       If the --quit option appears last on the command line,  fetchmail  will
1406       kill  the  running  daemon  process and then quit. Otherwise, fetchmail
1407       will first kill a running daemon process and then continue running with
1408       the other options.
1409
1410   Useful options for daemon mode
1411       The -L <filename> or --logfile <filename> option (keyword: set logfile)
1412       is only effective when fetchmail is detached and in daemon  mode.  Note
1413       that  the  logfile  must exist before fetchmail is run, you can use the
1414       touch(1) command with the filename as its sole argument to create it.
1415       This option allows you to redirect status  messages  into  a  specified
1416       logfile  (follow  the  option  with  the logfile name).  The logfile is
1417       opened for append, so previous messages are not deleted.  This is  pri‐
1418       marily  useful  for  debugging configurations. Note that fetchmail does
1419       not detect if the logfile is rotated, the logfile is only  opened  once
1420       when fetchmail starts. You need to restart fetchmail after rotating the
1421       logfile and before compressing it (if applicable).
1422
1423       The --syslog option (keyword: set syslog) allows you to redirect status
1424       and error messages emitted to the syslog(3) system daemon if available.
1425       Messages are logged with an id of fetchmail, the facility LOG_MAIL, and
1426       priorities LOG_ERR, LOG_ALERT or LOG_INFO.  This option is intended for
1427       logging status and error messages which indicate the status of the dae‐
1428       mon and the results while fetching mail from the server(s).  Error mes‐
1429       sages for command line options and parsing the  .fetchmailrc  file  are
1430       still  written to stderr, or to the specified log file.  The --nosyslog
1431       option turns off use of syslog(3), assuming it  is  turned  on  in  the
1432       ~/.fetchmailrc file.  This option is overridden, in certain situations,
1433       by --logfile (which see).
1434
1435       The -N or --nodetach option suppresses backgrounding and detachment  of
1436       the  daemon  process from its control terminal.  This is useful for de‐
1437       bugging or when fetchmail runs as the child  of  a  supervisor  process
1438       such  as init(8) or Gerrit Pape's runit(8).  Note that this also causes
1439       the logfile option to be ignored.
1440
1441       Note that while running in daemon  mode  polling  a  POP2  or  IMAP2bis
1442       server, transient errors (such as DNS failures or sendmail delivery re‐
1443       fusals) may force the fetchall option on for the duration of  the  next
1444       polling  cycle.  This is a robustness feature.  It means that if a mes‐
1445       sage is fetched (and thus marked seen by the mail server) but  not  de‐
1446       livered locally due to some transient error, it will be re-fetched dur‐
1447       ing the next poll cycle.  (The IMAP logic does not delete messages  un‐
1448       til they're delivered, so this problem does not arise.)
1449
1450       If  you touch or change the ~/.fetchmailrc file while fetchmail is run‐
1451       ning in daemon mode, this will be detected at the beginning of the next
1452       poll  cycle.   When  a  changed  ~/.fetchmailrc  is detected, fetchmail
1453       rereads it and restarts from scratch (using exec(2); no state  informa‐
1454       tion is retained in the new instance).  Note that if fetchmail needs to
1455       query for passwords, of that if you  break  the  ~/.fetchmailrc  file's
1456       syntax,  the  new  instance  will  softly  and  silently vanish away on
1457       startup.
1458
1459

ADMINISTRATIVE OPTIONS

1461       The --postmaster <name> option (keyword: set postmaster) specifies  the
1462       last-resort  username  to which multidrop mail is to be forwarded if no
1463       matching local recipient can be found. It is also used  as  destination
1464       of  undeliverable mail if the 'bouncemail' global option is off and ad‐
1465       ditionally for spam-blocked mail if the 'bouncemail' global  option  is
1466       off  and  the 'spambounce' global option is on. This option defaults to
1467       the user who invoked fetchmail.  If the invoking user is root, then the
1468       default of this option is the user 'postmaster'.  Setting postmaster to
1469       the empty string causes such mail as described above to be discarded  -
1470       this  however  is  usually a bad idea.  See also the description of the
1471       'FETCHMAILUSER' environment variable in the ENVIRONMENT section below.
1472
1473       The --nobounce behaves like the  "set  no  bouncemail"  global  option,
1474       which see.
1475
1476       The --invisible option (keyword: set invisible) tries to make fetchmail
1477       invisible.  Normally, fetchmail behaves like any other MTA would --  it
1478       generates  a  Received header into each message describing its place in
1479       the chain of transmission, and tells the MTA it forwards  to  that  the
1480       mail  came from the machine fetchmail itself is running on.  If the in‐
1481       visible option is on, the Received header is suppressed  and  fetchmail
1482       tries  to  spoof  the MTA it forwards to into thinking it came directly
1483       from the mail server host.
1484
1485       The --showdots option (keyword: set showdots) forces fetchmail to  show
1486       progress  dots even if the output goes to a file or fetchmail is not in
1487       verbose mode.  Fetchmail shows the dots by default when run  in  --ver‐
1488       bose  mode  and  output  goes  to  console.  This  option is ignored in
1489       --silent mode.
1490
1491       By specifying the --tracepolls option, you can ask fetchmail to add in‐
1492       formation  to  the Received header on the form "polling {label} account
1493       {user}", where {label} is the account label (from the specified rcfile,
1494       normally  ~/.fetchmailrc)  and  {user} is the username which is used to
1495       log on to the mail server. This header can be used  to  make  filtering
1496       email where no useful header information is available and you want mail
1497       from different accounts sorted into different  mailboxes  (this  could,
1498       for  example, occur if you have an account on the same server running a
1499       mailing list, and are subscribed to the list using that  account).  The
1500       default is not adding any such header.  In .fetchmailrc, this is called
1501       'tracepolls'.
1502
1503

RETRIEVAL FAILURE MODES

1505       The protocols fetchmail uses to talk to mail servers are next  to  bul‐
1506       letproof.   In  normal  operation  forwarding to port 25, no message is
1507       ever deleted (or even marked for deletion) on the host until  the  SMTP
1508       listener on the client side has acknowledged to fetchmail that the mes‐
1509       sage has been either accepted for delivery or rejected due  to  a  spam
1510       block.
1511
1512       When forwarding to an MDA, however, there is more possibility of error.
1513       Some MDAs are 'safe' and reliably return a nonzero status on any deliv‐
1514       ery  error, even one due to temporary resource limits.  The maildrop(1)
1515       program is like this; so are most programs designed as  mail  transport
1516       agents,  such as sendmail(1), including the sendmail wrapper of Postfix
1517       and exim(1).  These programs give back a reliable positive acknowledge‐
1518       ment  and  can  be  used with the mda option with no risk of mail loss.
1519       Unsafe MDAs, though, may return 0 even on delivery  failure.   If  this
1520       happens, you will lose mail.
1521
1522       The normal mode of fetchmail is to try to download only 'new' messages,
1523       leaving untouched (and undeleted) messages you have  already  read  di‐
1524       rectly  on  the  server  (or fetched with a previous fetchmail --keep).
1525       But you may find that messages you have already read on the server  are
1526       being  fetched (and deleted) even when you do not specify --all.  There
1527       are several reasons this can happen.
1528
1529       One could be that you are using POP2.  The POP2  protocol  includes  no
1530       representation  of  'new' or 'old' state in messages, so fetchmail must
1531       treat all messages as new all the time.  But POP2 is obsolete, so  this
1532       is unlikely.
1533
1534       A  potential  POP3 problem might be servers that insert messages in the
1535       middle of mailboxes (some VMS implementations of mail are rumored to do
1536       this).   The  fetchmail  code assumes that new messages are appended to
1537       the end of the mailbox; when this is not true it  may  treat  some  old
1538       messages  as  new and vice versa.  Using UIDL whilst setting fastuidl 0
1539       might fix this, otherwise, consider switching to IMAP.
1540
1541       Yet another POP3 problem is that if they cannot make temporary files in
1542       the  user's home directory, some POP3 servers will hand back an undocu‐
1543       mented response that causes fetchmail to spuriously report "No mail".
1544
1545       The IMAP code uses the presence or absence of the server flag \Seen  to
1546       decide whether or not a message is new.  This is not the right thing to
1547       do, fetchmail should check the UIDVALIDITY and use UID, but it does not
1548       do  that  yet.  Under Unix, it counts on your IMAP server to notice the
1549       BSD-style Status flags set by mail user agents and set the  \Seen  flag
1550       from  them when appropriate.  All Unix IMAP servers we know of do this,
1551       though it is not specified by the IMAP RFCs.  If you ever trip  over  a
1552       server  that  does  not, the symptom will be that messages you have al‐
1553       ready read on your host will look new to  the  server.   In  this  (un‐
1554       likely)  case,  only messages you fetched with fetchmail --keep will be
1555       both undeleted and marked old.
1556
1557       In ETRN and ODMR modes, fetchmail does not actually retrieve  messages;
1558       instead,  it  asks the server's SMTP listener to start a queue flush to
1559       the client via SMTP.  Therefore it sends only undelivered messages.
1560
1561

SPAM FILTERING

1563       Many SMTP listeners allow administrators to set up 'spam filters'  that
1564       block  unsolicited  email  from specified domains.  A MAIL FROM or DATA
1565       line that triggers this feature will elicit an SMTP response which (un‐
1566       fortunately) varies according to the listener.
1567
1568       Newer versions of sendmail return an error code of 571.
1569
1570       According  to RFC2821, the correct thing to return in this situation is
1571       550 "Requested action not taken: mailbox unavailable" (the  draft  adds
1572       "[E.g.,  mailbox  not  found, no access, or command rejected for policy
1573       reasons].").
1574
1575       Older versions of the exim MTA return 501 "Syntax error  in  parameters
1576       or arguments".
1577
1578       The postfix MTA runs 554 as an antispam response.
1579
1580       Zmailer  may  reject  code with a 500 response (followed by an enhanced
1581       status code that contains more information).
1582
1583       Return codes which fetchmail treats as antispam responses and  discards
1584       the  message can be set with the 'antispam' option.  This is one of the
1585       only three circumstance under which fetchmail ever discards  mail  (the
1586       others  are the 552 and 553 errors described below, and the suppression
1587       of multi-dropped messages with a message-ID already seen).
1588
1589       If fetchmail is fetching from an IMAP  server,  the  antispam  response
1590       will be detected and the message rejected immediately after the headers
1591       have been fetched, without reading the message body.   Thus,  you  will
1592       not pay for downloading spam message bodies.
1593
1594       By default, the list of antispam responses is empty.
1595
1596       If  the spambounce global option is on, mail that is spam-blocked trig‐
1597       gers an RFC1892/RFC1894 bounce message informing the originator that we
1598       do not accept mail from it. See also BUGS.
1599
1600

SMTP/ESMTP ERROR HANDLING

1602       Besides  the spam-blocking described above, fetchmail takes special ac‐
1603       tions — that may be modified by the --softbounce option — on  the  fol‐
1604       lowing SMTP/ESMTP error response codes
1605
1606       452 (insufficient system storage)
1607            Leave the message in the server mailbox for later retrieval.
1608
1609       552 (message exceeds fixed maximum message size)
1610            Delete the message from the server.  Send bounce-mail to the orig‐
1611            inator.
1612
1613       553 (invalid sending domain)
1614            Delete the message from the server.   Do  not  even  try  to  send
1615            bounce-mail to the originator.
1616
1617       Other  errors  greater  or equal to 500 trigger bounce mail back to the
1618       originator, unless suppressed by --softbounce. See also BUGS.
1619
1620

THE RUN CONTROL FILE

1622       The preferred way to set up fetchmail is to write a  .fetchmailrc  file
1623       in  your  home directory (you may do this directly, with a text editor,
1624       or indirectly via fetchmailconf).  When there is a conflict between the
1625       command-line arguments and the arguments in this file, the command-line
1626       arguments take precedence.
1627
1628       To protect the security of your passwords, your ~/.fetchmailrc may  not
1629       normally  have more than 0700 (u=rwx,g=,o=) permissions; fetchmail will
1630       complain and exit otherwise (this check is suppressed when --version is
1631       on).
1632
1633       You may read the .fetchmailrc file as a list of commands to be executed
1634       when fetchmail is called with no arguments.
1635
1636   Run Control Syntax
1637       Comments begin with a '#' and extend through the end of the line.  Oth‐
1638       erwise the file consists of a series of server entries or global option
1639       statements in a free-format, token-oriented syntax.
1640
1641       There are four kinds of tokens: grammar keywords, numbers (i.e.,  deci‐
1642       mal  digit  sequences), unquoted strings, and quoted strings.  A quoted
1643       string is bounded by double quotes  and  may  contain  whitespace  (and
1644       quoted  digits are treated as a string).  Note that quoted strings will
1645       also contain line feed characters if they run across two or more lines,
1646       unless  you  use  a  backslash  to join lines (see below).  An unquoted
1647       string is any  whitespace-delimited  token  that  is  neither  numeric,
1648       string  quoted  nor  contains  the special characters ',', ';', ':', or
1649       '='.
1650
1651       Any amount of whitespace separates tokens in  server  entries,  but  is
1652       otherwise  ignored.  You may use backslash escape sequences (\n for LF,
1653       \t for HT, \b for BS, \r for CR, \nnn for  decimal  (where  nnn  cannot
1654       start with a 0), \0ooo for octal, and \xhh for hex) to embed non-print‐
1655       able characters or string delimiters in strings.  In quoted strings,  a
1656       backslash at the very end of a line will cause the backslash itself and
1657       the line feed (LF or NL, new line) character to be ignored, so that you
1658       can  wrap long strings. Without the backslash at the line end, the line
1659       feed character would become part of the string.
1660
1661       Warning: while these resemble C-style escape sequences,  they  are  not
1662       the  same.  fetchmail only supports these eight styles. C supports more
1663       escape sequences that consist of backslash (\) and a single  character,
1664       but  does  not support decimal codes and does not require the leading 0
1665       in octal notation.  Example: fetchmail interprets \233 the same as \xE9
1666       (Latin  small letter e with acute), where C would interpret \233 as oc‐
1667       tal 0233 = \x9B (CSI, control sequence introducer).
1668
1669       Each server entry consists of one of the  keywords  'poll'  or  'skip',
1670       followed  by a server name, followed by server options, followed by any
1671       number of user (or username) descriptions, followed  by  user  options.
1672       Note:  the  most  common  cause  of syntax errors is mixing up user and
1673       server options or putting user options before the user descriptions.
1674
1675       For backward compatibility, the word 'server' is a synonym for 'poll'.
1676
1677       You can use the noise keywords 'and', 'with', 'has', 'wants', and  'op‐
1678       tions'  anywhere in an entry to make it resemble English.  They are ig‐
1679       nored, but can make entries much easier to read at a glance.  The punc‐
1680       tuation characters ':', ';' and ',' are also ignored.
1681
1682   Poll versus Skip
1683       The  'poll' verb tells fetchmail to query this host when it is run with
1684       no arguments.  The 'skip' verb tells fetchmail not to  poll  this  host
1685       unless  it  is  explicitly named on the command line.  (The 'skip' verb
1686       allows you to experiment with test entries safely,  or  easily  disable
1687       entries for hosts that are temporarily down.)
1688
1689   Keyword/Option Summary
1690       Here are the legal options.  Keyword suffixes enclosed in square brack‐
1691       ets are optional.  Those corresponding to  short  command-line  options
1692       are  followed  by  '-' and the appropriate option letter.  If option is
1693       only relevant to a single mode of operation, it is noted as 's' or  'm'
1694       for singledrop- or multidrop-mode, respectively.
1695
1696       Here are the legal global options:
1697
1698
1699       Keyword             Opt   Mode   Function
1700       ────────────────────────────────────────────────────────────────────
1701       set daemon          -d           Set  a background poll interval in
1702                                        seconds.
1703       set postmaster                   Give the name of  the  last-resort
1704                                        mail recipient (default: user run‐
1705                                        ning  fetchmail,  "postmaster"  if
1706                                        run by the root user)
1707       set    bouncemail                Direct  error  mail  to the sender
1708                                        (default)
1709       set no bouncemail                Direct error  mail  to  the  local
1710                                        postmaster  (as  per the 'postmas‐
1711                                        ter' global option above).
1712       set no spambounce                Do not  bounce  spam-blocked  mail
1713                                        (default).
1714       set    spambounce                Bounce  blocked  spam-blocked mail
1715                                        (as per the  'antispam'  user  op‐
1716                                        tion)  back  to the destination as
1717                                        indicated  by   the   'bouncemail'
1718                                        global  option.   Warning:  Do not
1719                                        use this to bounce  spam  back  to
1720                                        the  sender  -  most  spam is sent
1721                                        with false sender address and thus
1722                                        this  option  hurts  innocent  by‐
1723                                        standers.
1724       set no softbounce                Delete  permanently  undeliverable
1725                                        mail.  It  is  recommended  to use
1726                                        this option if  the  configuration
1727                                        has been thoroughly tested.
1728       set    softbounce                Keep   permanently   undeliverable
1729                                        mail as though a  temporary  error
1730                                        had occurred (default).
1731       set logfile         -L           Name of a file to append error and
1732                                        status messages to.   Only  effec‐
1733                                        tive  in daemon mode and if fetch‐
1734                                        mail  detaches.    If   effective,
1735                                        overrides set syslog.
1736       set pidfile         -p           Name of the PID file.
1737
1738
1739       set idfile          -i           Name  of  the  file  to  store UID
1740                                        lists in.
1741       set    syslog                    Do  error  logging  through   sys‐
1742                                        log(3).  May  be overridden by set
1743                                        logfile.
1744       set no syslog                    Turn  off  error  logging  through
1745                                        syslog(3). (default)
1746       set properties                   String  value  that  is ignored by
1747                                        fetchmail (may be used  by  exten‐
1748                                        sion scripts).
1749
1750       Here are the legal server options:
1751
1752
1753       Keyword          Opt   Mode   Function
1754       ─────────────────────────────────────────────────────────────────
1755       via                           Specify  DNS  name of mail server,
1756                                     overriding poll name
1757       proto[col]       -p           Specify  protocol  (case  insensi‐
1758                                     tive):  POP2,  POP3,  IMAP,  APOP,
1759                                     KPOP
1760       local[domains]         m      Specify domain(s) to  be  regarded
1761                                     as local
1762       port                          Specify TCP/IP service port (obso‐
1763                                     lete, use 'service' instead).
1764       service          -P           Specify service  name  (a  numeric
1765                                     value  is also allowed and consid‐
1766                                     ered a TCP/IP port number).
1767       auth[enticate]                Set authentication  type  (default
1768                                     'any')
1769       timeout          -t           Server  inactivity timeout in sec‐
1770                                     onds (default 300)
1771       envelope         -E    m      Specify  envelope-address   header
1772                                     name
1773       no envelope            m      Disable  looking  for envelope ad‐
1774                                     dress
1775       qvirtual         -Q    m      Qmail virtual domain prefix to re‐
1776                                     move from user name
1777       aka                    m      Specify  alternate  DNS  names  of
1778                                     mail server
1779       interface        -I           specify IP interface(s) that  must
1780                                     be  up  for  server  poll  to take
1781                                     place
1782       monitor          -M           Specify IP address to monitor  for
1783                                     activity
1784       plugin                        Specify  command  through which to
1785                                     make server connections.
1786       plugout                       Specify command through  which  to
1787                                     make listener connections.
1788       dns                    m      Enable  DNS  lookup  for multidrop
1789                                     (default)
1790       no dns                 m      Disable DNS lookup for multidrop
1791       checkalias             m      Do comparison by  IP  address  for
1792                                     multidrop
1793       no checkalias          m      Do  comparison  by  name  for mul‐
1794                                     tidrop (default)
1795       uidl             -U           Force  POP3  to  use   client-side
1796                                     UIDLs (recommended)
1797       no uidl                       Turn  off  POP3 use of client-side
1798                                     UIDLs (default)
1799       interval                      Only check this site every N  poll
1800                                     cycles; N is a numeric argument.
1801       tracepolls                    Add  poll  tracing  information to
1802                                     the Received header
1803       principal                     Set Kerberos principal (only  use‐
1804                                     ful with IMAP and kerberos)
1805       esmtpname                     Set  name  for RFC2554 authentica‐
1806                                     tion to the ESMTP server.
1807       esmtppassword                 Set password for RFC2554 authenti‐
1808                                     cation to the ESMTP server.
1809
1810
1811       bad-header                    How  to  treat messages with a bad
1812                                     header. Can be reject (default) or
1813                                     accept.
1814
1815       Here are the legal user descriptions and options:
1816
1817
1818       Keyword            Opt       Mode   Function
1819       ───────────────────────────────────────────────────────────────────────
1820       user[name]         -u               This  is  the user description and
1821                                           must come first after  server  de‐
1822                                           scription   and   after   possible
1823                                           server options,  and  before  user
1824                                           options.
1825
1826                                           It sets the remote user name if by
1827                                           itself or followed by 'there',  or
1828                                           the local user name if followed by
1829                                           'here'.
1830       is                                  Connect  local  and  remote   user
1831                                           names
1832       to                                  Connect   local  and  remote  user
1833                                           names
1834       pass[word]                          Specify remote account password
1835       ssl                                 Connect to server over the  speci‐
1836                                           fied  base  protocol using SSL en‐
1837                                           cryption
1838       sslcert                             Specify file for client side  pub‐
1839                                           lic SSL certificate
1840       sslcertck                           Enable strict certificate checking
1841                                           and abort connection  on  failure.
1842                                           Default   only   since   fetchmail
1843                                           v6.4.0.
1844       no sslcertck                        Disable strict certificate  check‐
1845                                           ing and permit connections to con‐
1846                                           tinue on failed verification. Dis‐
1847                                           couraged.  Should only be used to‐
1848                                           gether with sslfingerprint.
1849       sslcertfile                         Specify file with trusted CA  cer‐
1850                                           tificates
1851       sslcertpath                         Specify c_rehash-ed directory with
1852                                           trusted CA certificates.
1853       sslfingerprint     <HASH>           Specify the expected  server  cer‐
1854                                           tificate  finger print from an MD5
1855                                           hash.  Fetchmail  will  disconnect
1856                                           and  log  an  error if it does not
1857                                           match.
1858       sslkey                              Specify file for client side  pri‐
1859                                           vate SSL key
1860       sslproto                            Force ssl protocol for connection
1861       folder             -r               Specify remote folder to query
1862       smtphost           -S               Specify smtp host(s) to forward to
1863       fetchdomains                 m      Specify  domains  for  which  mail
1864                                           should be fetched
1865       smtpaddress        -D               Specify the domain to  be  put  in
1866                                           RCPT TO lines
1867       smtpname                            Specify  the user and domain to be
1868                                           put in RCPT TO lines
1869       antispam           -Z               Specify what SMTP returns are  in‐
1870                                           terpreted as spam-policy blocks
1871       mda                -m               Specify MDA for local delivery
1872       bsmtp                               Specify BSMTP batch file to append
1873                                           to
1874       preconnect                          Command to be executed before each
1875                                           connection
1876       postconnect                         Command  to be executed after each
1877                                           connection
1878       keep               -k               Do not delete seen  messages  from
1879                                           server  (for  POP3, uidl is recom‐
1880                                           mended)
1881
1882
1883       flush              -F               Flush  all  seen  messages  before
1884                                           querying (DANGEROUS)
1885       limitflush                          Flush  all  oversized messages be‐
1886                                           fore querying
1887       fetchall           -a               Fetch all messages whether seen or
1888                                           not
1889       rewrite                             Rewrite  destination addresses for
1890                                           reply (default)
1891       stripcr                             Strip carriage returns  from  ends
1892                                           of lines
1893       forcecr                             Force  carriage returns at ends of
1894                                           lines
1895       pass8bits                           Force BODY=8BITMIME to ESMTP  lis‐
1896                                           tener
1897       dropstatus                          Strip  Status and X-Mozilla-Status
1898                                           lines out of incoming mail
1899       dropdelivered                       Strip Delivered-To  lines  out  of
1900                                           incoming mail
1901       mimedecode                          Convert  quoted-printable to 8-bit
1902                                           in MIME messages
1903       idle                                Idle waiting for new messages  af‐
1904                                           ter each poll (IMAP only)
1905       no keep            -K               Delete  seen  messages from server
1906                                           (default)
1907       no flush                            Do not flush all seen messages be‐
1908                                           fore querying (default)
1909       no fetchall                         Retrieve  only  new  messages (de‐
1910                                           fault)
1911       no rewrite                          Do not rewrite headers
1912       no stripcr                          Do not strip carriage returns (de‐
1913                                           fault)
1914       no forcecr                          Do  not  force carriage returns at
1915                                           EOL (default)
1916       no pass8bits                        Do  not  force  BODY=8BITMIME   to
1917                                           ESMTP listener (default)
1918       no dropstatus                       Do  not  drop  Status headers (de‐
1919                                           fault)
1920       no dropdelivered                    Do not drop  Delivered-To  headers
1921                                           (default)
1922       no mimedecode                       Do not convert quoted-printable to
1923                                           8-bit in MIME messages (default)
1924       no idle                             Do not idle waiting for  new  mes‐
1925                                           sages after each poll (IMAP only)
1926       limit              -l               Set message size limit
1927       warnings           -w               Set message size warning interval
1928       batchlimit         -b               Max  # messages to forward in sin‐
1929                                           gle connect
1930       fetchlimit         -B               Max # messages to fetch in  single
1931                                           connect
1932       fetchsizelimit                      Max  #  message  sizes to fetch in
1933                                           single transaction
1934       fastuidl                            Use binary search for first unseen
1935                                           message (POP3 only)
1936       expunge            -e               Perform  an  expunge  on every #th
1937                                           message (IMAP and POP3 only)
1938       properties                          String value is ignored by  fetch‐
1939                                           mail  (may  be  used  by extension
1940                                           scripts)
1941
1942       All user options must begin with a user description (user  or  username
1943       option) and follow all server descriptions and options.
1944
1945       In  the  .fetchmailrc  file, the 'envelope' string argument may be pre‐
1946       ceded by a whitespace-separated number.  This number, if specified,  is
1947       the  number of such headers to skip over (that is, an argument of 1 se‐
1948       lects the second header of the given type).  This is  sometimes  useful
1949       for  ignoring bogus envelope headers created by an ISP's local delivery
1950       agent or internal forwards (through mail inspection  systems,  for  in‐
1951       stance).
1952
1953   Keywords Not Corresponding To Option Switches
1954       The  'folder' and 'smtphost' options (unlike their command-line equiva‐
1955       lents) can take a space- or comma-separated  list  of  names  following
1956       them.
1957
1958       All  options  correspond  to the obvious command-line arguments, except
1959       the following: 'via', 'interval', 'aka', 'is',  'to',  'dns'/'no  dns',
1960       'checkalias'/'no  checkalias', 'password', 'preconnect', 'postconnect',
1961       'localdomains',   'stripcr'/'no   stripcr',   'forcecr'/'no   forcecr',
1962       'pass8bits'/'no   pass8bits'  'dropstatus/no  dropstatus',  'dropdeliv‐
1963       ered/no dropdelivered', 'mimedecode/no mimedecode', 'no idle', and  'no
1964       envelope'.
1965
1966       The 'via' option is for if you want to have more than one configuration
1967       pointing at the same site.  If it is present, the string argument  will
1968       be taken as the actual DNS name of the mail server host to query.  This
1969       will override the argument of poll, which can then simply be a distinct
1970       label  for  the configuration (e.g., what you would give on the command
1971       line to explicitly query this host).
1972
1973       The 'interval' option (which takes a numeric argument)  allows  you  to
1974       poll a server less frequently than the basic poll interval.  If you say
1975       'interval N' the server this option is attached to will only be queried
1976       every N poll intervals.
1977
1978   Singledrop versus Multidrop options
1979       Please  ensure  you  read  the section titled THE USE AND ABUSE OF MUL‐
1980       TIDROP MAILBOXES if you intend to use multidrop mode.
1981
1982       The 'is' or  'to'  keywords  associate  the  following  local  (client)
1983       name(s)  (or  server-name  to client-name mappings separated by =) with
1984       the mail server user name in the entry.  If an is/to list  has  '*'  as
1985       its  last name, unrecognized names are simply passed through. Note that
1986       until fetchmail version 6.3.4 inclusively, these lists could only  con‐
1987       tain  local  parts of user names (fetchmail would only look at the part
1988       before the @ sign). fetchmail versions 6.3.5 and newer support full ad‐
1989       dresses  on  the left hand side of these mappings, and they take prece‐
1990       dence over any 'localdomains', 'aka', 'via' or similar mappings.
1991
1992       A single local name can be used to support redirecting your  mail  when
1993       your  username on the client machine is different from your name on the
1994       mail server.  When there is only a single local name, mail is forwarded
1995       to  that  local  username regardless of the message's Received, To, Cc,
1996       and Bcc headers.  In this case, fetchmail never does DNS lookups.
1997
1998       When there is more than one local name  (or  name  mapping),  fetchmail
1999       looks  at  the envelope header, if configured, and otherwise at the Re‐
2000       ceived, To, Cc, and Bcc headers of retrieved mail (this  is  'multidrop
2001       mode').   It  looks  for addresses with host name parts that match your
2002       poll name or your 'via', 'aka' or 'localdomains' options,  and  usually
2003       also  for  host  name  parts which DNS tells it are aliases of the mail
2004       server.  See the discussion of 'dns', 'checkalias', 'localdomains', and
2005       'aka' for details on how matching addresses are handled.
2006
2007       If  fetchmail cannot match any mail server usernames or localdomain ad‐
2008       dresses, the mail will be bounced.  Normally it will be bounced to  the
2009       sender,  but if the 'bouncemail' global option is off, the mail will go
2010       to the local postmaster instead.  (see the 'postmaster' global option).
2011       See also BUGS.
2012
2013       The  'dns'  option  (normally  on) controls the way addresses from mul‐
2014       tidrop mailboxes are checked.  On, it enables logic to check each  host
2015       address  that  does not match an 'aka' or 'localdomains' declaration by
2016       looking it up with DNS.  When a mail server username is recognized  at‐
2017       tached  to a matching host name part, its local mapping is added to the
2018       list of local recipients.
2019
2020       The 'checkalias' option (normally off) extends the lookups performed by
2021       the  'dns'  keyword in multidrop mode, providing a way to cope with re‐
2022       mote MTAs that identify themselves using their  canonical  name,  while
2023       they're polled using an alias.  When such a server is polled, checks to
2024       extract the envelope address fail, and fetchmail  reverts  to  delivery
2025       using  the  To/Cc/Bcc  headers  (See  below 'Header versus Envelope ad‐
2026       dresses').  Specifying this option instructs fetchmail to retrieve  all
2027       the  IP  addresses associated with both the poll name and the name used
2028       by the remote MTA and to do a comparison of  the  IP  addresses.   This
2029       comes in handy in situations where the remote server undergoes frequent
2030       canonical name changes, that would otherwise require  modifications  to
2031       the rcfile.  'checkalias' has no effect if 'no dns' is specified in the
2032       rcfile.
2033
2034       The 'aka' option is for use with multidrop mailboxes.  It allows you to
2035       pre-declare  a  list of DNS aliases for a server.  This is an optimiza‐
2036       tion hack that allows you to trade space for  speed.   When  fetchmail,
2037       while  processing  a multidrop mailbox, grovels through message headers
2038       looking for names of the mail server,  pre-declaring  common  ones  can
2039       save it from having to do DNS lookups.  Note: the names you give as ar‐
2040       guments to 'aka' are matched as suffixes -- if you specify  (say)  'aka
2041       netaxs.com',  this  will match not just a host name netaxs.com, but any
2042       host name that ends with '.netaxs.com'; such as  (say)  pop3.netaxs.com
2043       and mail.netaxs.com.
2044
2045       The 'localdomains' option allows you to declare a list of domains which
2046       fetchmail should consider local.  When  fetchmail  is  parsing  address
2047       lines in multidrop modes, and a trailing segment of a host name matches
2048       a declared local domain, that address is passed through to the listener
2049       or MDA unaltered (local-name mappings are not applied).
2050
2051       If you are using 'localdomains', you may also need to specify 'no enve‐
2052       lope', which disables fetchmail's normal attempt to deduce an  envelope
2053       address  from  the  Received  line  or X-Envelope-To header or whatever
2054       header has been previously set by 'envelope'.  If you set 'no envelope'
2055       in the defaults entry it is possible to undo that in individual entries
2056       by using 'envelope <string>'.  As a special case, 'envelope "Received"'
2057       restores the default parsing of Received lines.
2058
2059       The  password  option requires a string argument, which is the password
2060       to be used with the entry's server.
2061
2062       The 'preconnect' keyword allows you to specify a shell  command  to  be
2063       executed just before each time fetchmail establishes a mail server con‐
2064       nection.  This may be useful if you are attempting to set up secure POP
2065       connections  with  the aid of ssh(1).  If the command returns a nonzero
2066       status, the poll of that mail server will be aborted.
2067
2068       Similarly, the 'postconnect' keyword similarly allows you to specify  a
2069       shell command to be executed just after each time a mail server connec‐
2070       tion is taken down.
2071
2072       The 'forcecr' option controls whether lines terminated by LF  only  are
2073       given CRLF termination before forwarding.  Strictly speaking RFC821 re‐
2074       quires this, but few MTAs enforce the requirement  so  this  option  is
2075       normally  off  (only one such MTA, qmail, is in significant use at time
2076       of writing).
2077
2078       The 'stripcr' option controls whether carriage returns are stripped out
2079       of retrieved mail before it is forwarded.  It is normally not necessary
2080       to set this, because it defaults to 'on' (CR  stripping  enabled)  when
2081       there  is  an  MDA declared but 'off' (CR stripping disabled) when for‐
2082       warding is via SMTP.  If 'stripcr' and 'forcecr' are both on, 'stripcr'
2083       will override.
2084
2085       The 'pass8bits' option exists to cope with Microsoft mail programs that
2086       stupidly slap a "Content-Transfer-Encoding: 7bit" on everything.   With
2087       this  option off (the default) and such a header present, fetchmail de‐
2088       clares BODY=7BIT to an ESMTP-capable listener; this causes problems for
2089       messages  actually  using 8-bit ISO or KOI-8 character sets, which will
2090       be garbled by having the high bits  of  all  characters  stripped.   If
2091       'pass8bits'  is on, fetchmail is forced to declare BODY=8BITMIME to any
2092       ESMTP-capable listener.  If the listener is 8-bit-clean (as all the ma‐
2093       jor ones now are) the right thing will probably result.
2094
2095       The 'dropstatus' option controls whether nonempty Status and X-Mozilla-
2096       Status lines are retained in fetched mail (the default)  or  discarded.
2097       Retaining  them  allows  your  MUA  to  see what messages (if any) were
2098       marked seen on the server.  On the other hand, it can confuse some new-
2099       mail notifiers, which assume that anything with a Status line in it has
2100       been seen.  (Note: the empty Status lines inserted by  some  buggy  POP
2101       servers are unconditionally discarded.)
2102
2103       The  'dropdelivered'  option controls whether Delivered-To headers will
2104       be kept in fetched mail (the default) or discarded. These  headers  are
2105       added  by  qmail  and Postfix mail servers in order to avoid mail loops
2106       but may get in your way if you try to "mirror" a mail server within the
2107       same domain. Use with caution.
2108
2109       The  'mimedecode'  option  controls  whether  MIME  messages  using the
2110       quoted-printable encoding are automatically converted into  pure  8-bit
2111       data.  If you are delivering mail to an ESMTP-capable, 8-bit-clean lis‐
2112       tener (that includes all of the major MTAs like  sendmail),  then  this
2113       will  automatically  convert  quoted-printable message headers and data
2114       into 8-bit data, making it easier to understand when reading  mail.  If
2115       your e-mail programs know how to deal with MIME messages, then this op‐
2116       tion is not needed.  The mimedecode option is off by  default,  because
2117       doing  RFC2047 conversion on headers throws away character-set informa‐
2118       tion and can lead to bad results if the encoding of the headers differs
2119       from the body encoding.
2120
2121       The  'idle'  option is intended to be used with IMAP servers supporting
2122       the RFC2177 IDLE command extension, but does not strictly  require  it.
2123       If it is enabled, and fetchmail detects that IDLE is supported, an IDLE
2124       will be issued at the end of each poll.  This will tell the IMAP server
2125       to  hold  the  connection  open  and notify the client when new mail is
2126       available.  If IDLE is not supported, fetchmail will simulate it by pe‐
2127       riodically  issuing  NOOP.  If you need to poll a link frequently, IDLE
2128       can save bandwidth by eliminating TCP/IP connects and LOGIN/LOGOUT  se‐
2129       quences.  On  the other hand, an IDLE connection will eat almost all of
2130       your fetchmail's time, because it will never drop  the  connection  and
2131       allow  other  polls  to occur unless the server times out the IDLE.  It
2132       also does not work with multiple folders; only the  first  folder  will
2133       ever be polled.
2134
2135       The  'properties'  option is an extension mechanism.  It takes a string
2136       argument, which is ignored by fetchmail itself.   The  string  argument
2137       may  be  used  to store configuration information for scripts which re‐
2138       quire it.  In particular, the output of '--configdump' option will make
2139       properties  associated  with a user entry readily available to a Python
2140       script.
2141
2142   Miscellaneous Run Control Options
2143       The words 'here' and 'there'  have  useful  English-like  significance.
2144       Normally  'user  eric  is esr' would mean that mail for the remote user
2145       'eric' is to be delivered to 'esr', but you can make  this  clearer  by
2146       saying 'user eric there is esr here', or reverse it by saying 'user esr
2147       here is eric there'
2148
2149       Legal protocol identifiers for use with the 'protocol' keyword are:
2150
2151           auto (or AUTO) (legacy, to be removed from future release)
2152           pop2 (or POP2) (legacy, to be removed from future release)
2153           pop3 (or POP3)
2154           sdps (or SDPS)
2155           imap (or IMAP)
2156           apop (or APOP)
2157           kpop (or KPOP)
2158
2159
2160       Legal authentication types are  'any',  'password',  'kerberos',  'ker‐
2161       beros_v4',  'kerberos_v5'  and 'gssapi', 'cram-md5', 'otp', 'msn' (only
2162       for POP3), 'ntlm', 'ssh', 'external' (only IMAP).  The 'password'  type
2163       specifies  authentication  by  normal  transmission  of a password (the
2164       password may be plain text or subject to  protocol-specific  encryption
2165       as  in  CRAM-MD5);  'kerberos' tells fetchmail to try to get a Kerberos
2166       ticket at the start of each query instead, and send an arbitrary string
2167       as the password; and 'gssapi' tells fetchmail to use GSSAPI authentica‐
2168       tion.  See the description of the 'auth' keyword for more.
2169
2170       Specifying 'kpop' sets POP3 protocol over port 1109  with  Kerberos  V4
2171       authentication.  These defaults may be overridden by later options.
2172
2173       There  are  some  global option statements: 'set logfile' followed by a
2174       string sets the same global specified  by  --logfile.   A  command-line
2175       --logfile option will override this. Note that --logfile is only effec‐
2176       tive if fetchmail detaches itself from the terminal and the logfile al‐
2177       ready exists before fetchmail is run, and it overrides --syslog in this
2178       case.  Also, 'set daemon' sets the  poll  interval  as  --daemon  does.
2179       This can be overridden by a command-line --daemon option; in particular
2180       --daemon 0 can be used to force foreground operation. The 'set postmas‐
2181       ter'  statement  sets  the  address to which multidrop mail defaults if
2182       there are no local matches.  Finally, 'set syslog' sends  log  messages
2183       to syslogd(8).
2184
2185

DEBUGGING FETCHMAIL

2187   Fetchmail crashing
2188       There are various ways in that fetchmail may "crash", i. e. stop opera‐
2189       tion suddenly and unexpectedly. A "crash" usually refers  to  an  error
2190       condition  that  the  software  did  not handle by itself. A well-known
2191       failure mode is the "segmentation fault" or "signal 11" or "SIGSEGV" or
2192       just  "segfault" for short. These can be caused by hardware or by soft‐
2193       ware problems. Software-induced segfaults  can  usually  be  reproduced
2194       easily and in the same place, whereas hardware-induced segfaults can go
2195       away if the computer is rebooted, or powered off for a few  hours,  and
2196       can  happen  in  random locations even if you use the software the same
2197       way.
2198
2199       For solving hardware-induced segfaults, find the faulty  component  and
2200       repair  or replace it.  The Sig11 FAQ ⟨https://www.bitwizard.nl/sig11/
2201       may help you with details.
2202
2203       For solving software-induced  segfaults,  the  developers  may  need  a
2204       "stack backtrace".
2205
2206
2207   Enabling fetchmail core dumps
2208       By  default,  fetchmail  suppresses  core  dumps as these might contain
2209       passwords and other  sensitive  information.  For  debugging  fetchmail
2210       crashes,  obtaining  a  "stack backtrace" from a core dump is often the
2211       quickest way to solve the problem, and when posting your problem  on  a
2212       mailing list, the developers may ask you for a "backtrace".
2213
2214       1.  To  get  useful backtraces, fetchmail needs to be installed without
2215       getting stripped of its compilation symbols.  Unfortunately,  most  bi‐
2216       nary packages that are installed are stripped, and core files from sym‐
2217       bol-stripped programs are worthless.  So  you  may  need  to  recompile
2218       fetchmail. On many systems, you can type
2219
2220               file `which fetchmail`
2221
2222       to  find  out if fetchmail was symbol-stripped or not. If yours was un‐
2223       stripped, fine, proceed, if it was stripped, you need to recompile  the
2224       source  code first. You do not usually need to install fetchmail in or‐
2225       der to debug it.
2226
2227       2. The shell environment that starts fetchmail  needs  to  enable  core
2228       dumps.  The  key  is the "maximum core (file) size" that can usually be
2229       configured with a tool named "limit" or "ulimit". See the documentation
2230       for  your shell for details. In the popular bash shell, "ulimit -Sc un‐
2231       limited" will allow the core dump.
2232
2233       3. You need to tell fetchmail, too, to allow core dumps.  To  do  this,
2234       run  fetchmail with the -d0 -v options.  It is often easier to also add
2235       --nosyslog -N as well.
2236
2237       Finally, you need to reproduce the crash. You can just start  fetchmail
2238       from  the directory where you compiled it by typing ./fetchmail, so the
2239       complete command line will start with ./fetchmail -Nvd0 --nosyslog  and
2240       perhaps list your other options.
2241
2242       After the crash, run your debugger to obtain the core dump.  The debug‐
2243       ger will often be GNU GDB, you can then type (adjust  paths  as  neces‐
2244       sary) gdb ./fetchmail fetchmail.core and then, after GDB has started up
2245       and read all its files, type backtrace full, save the  output  (copy  &
2246       paste  will  do,  the  backtrace will be read by a human) and then type
2247       quit to leave gdb.  Note: on some systems, the core files have  differ‐
2248       ent  names, they might contain a number instead of the program name, or
2249       number and name, but it will usually have "core" as part of their name.
2250
2251

INTERACTION WITH RFC 822

2253       When trying to determine the originating address of a  message,  fetch‐
2254       mail looks through headers in the following order:
2255
2256               Return-Path:
2257               Resent-Sender: (ignored if it does not contain an @ or !)
2258               Sender: (ignored if it does not contain an @ or !)
2259               Resent-From:
2260               From:
2261               Reply-To:
2262               Apparently-From:
2263
2264       The  originating  address is used for logging, and to set the MAIL FROM
2265       address when forwarding to SMTP.  This order is intended to cope grace‐
2266       fully  with  receiving mailing list messages in multidrop mode. The in‐
2267       tent is that if a local address does not exist, the bounce message will
2268       not be returned blindly to the author or to the list itself, but rather
2269       to the list manager (which is less annoying).
2270
2271       In multidrop mode, destination headers are processed as follows: First,
2272       fetchmail  looks  for  the header specified by the 'envelope' option in
2273       order to determine the local recipient address.  If  the  mail  is  ad‐
2274       dressed  to more than one recipient, the Received line will not contain
2275       any information regarding recipient addresses.
2276
2277       Then fetchmail looks for the Resent-To:,  Resent-Cc:,  and  Resent-Bcc:
2278       lines.   If  they  exist,  they should contain the final recipients and
2279       have precedence over their To:/Cc:/Bcc: counterparts.  If the  Resent-*
2280       lines  do  not  exist,  the To:, Cc:, Bcc: and Apparently-To: lines are
2281       looked for. (The presence of a Resent-To: is taken to  imply  that  the
2282       person  referred  by  the To: address has already received the original
2283       copy of the mail.)
2284
2285

CONFIGURATION EXAMPLES

2287       Note that although there are password declarations in a  good  many  of
2288       the  examples below, this is mainly for illustrative purposes.  We rec‐
2289       ommend stashing account/password pairs in your $HOME/.netrc file, where
2290       they  can  be  used  not just by fetchmail but by ftp(1) and other pro‐
2291       grams.
2292
2293       The basic format is:
2294
2295
2296              poll SERVERNAME protocol PROTOCOL username NAME  password  PASS‐
2297              WORD
2298
2299
2300       Example:
2301
2302
2303              poll pop.provider.net protocol pop3 username "jsmith" password "secret1"
2304
2305
2306       Or, using some abbreviations:
2307
2308
2309              poll pop.provider.net proto pop3 user "jsmith" password "secret1"
2310
2311
2312       Multiple servers may be listed:
2313
2314
2315              poll pop.provider.net proto pop3 user "jsmith" pass "secret1"
2316              poll other.provider.net proto pop2 user "John.Smith" pass "My^Hat"
2317
2318
2319       Here's the same version with more whitespace and some noise words:
2320
2321
2322              poll pop.provider.net proto pop3
2323                   user "jsmith", with password secret1, is "jsmith" here;
2324              poll other.provider.net proto pop2:
2325                   user "John.Smith", with password "My^Hat", is "John.Smith" here;
2326
2327
2328       If  you  need  to include whitespace in a parameter string or start the
2329       latter with a number, enclose the string in double quotes.  Thus:
2330
2331
2332              poll mail.provider.net with proto pop3:
2333                   user "jsmith" there has password "4u but u cannot krak this"
2334                   is jws here and wants mda "/bin/mail"
2335
2336
2337       You may have an initial server description headed by the  keyword  'de‐
2338       faults'  instead of 'poll' followed by a name.  Such a record is inter‐
2339       preted as defaults for all queries to use. It may be overwritten by in‐
2340       dividual server descriptions.  So, you could write:
2341
2342
2343              defaults proto pop3
2344                   user "jsmith"
2345              poll pop.provider.net
2346                   pass "secret1"
2347              poll mail.provider.net
2348                   user "jjsmith" there has password "secret2"
2349
2350
2351       It  is  possible  to specify more than one user per server.  The 'user'
2352       keyword leads off a user description, and every user specification in a
2353       multi-user entry must include it.  Here's an example:
2354
2355
2356              poll pop.provider.net proto pop3 port 3111
2357                   user "jsmith" with pass "secret1" is "smith" here
2358                   user jones with pass "secret2" is "jjones" here keep
2359
2360
2361       This  associates  the  local username 'smith' with the pop.provider.net
2362       username  'jsmith'  and  the   local   username   'jjones'   with   the
2363       pop.provider.net  username  'jones'.   Mail  for 'jones' is kept on the
2364       server after download.
2365
2366
2367       Here's what a simple retrieval configuration for  a  multidrop  mailbox
2368       looks like:
2369
2370
2371              poll pop.provider.net:
2372                   user maildrop with pass secret1 to golux 'hurkle'='happy' snark here
2373
2374
2375       This  says  that  the  mailbox of account 'maildrop' on the server is a
2376       multidrop box, and that messages in it should be parsed for the  server
2377       user  names  'golux', 'hurkle', and 'snark'.  It further specifies that
2378       'golux' and 'snark' have the same name on the client as on the  server,
2379       but  mail  for  server user 'hurkle' should be delivered to client user
2380       'happy'.
2381
2382
2383       Note that fetchmail, until version 6.3.4, did NOT allow  full  user@do‐
2384       main specifications here, these would never match.  Fetchmail 6.3.5 and
2385       newer support user@domain specifications on the  left-hand  side  of  a
2386       user mapping.
2387
2388
2389       Here's an example of another kind of multidrop connection:
2390
2391
2392              poll pop.provider.net localdomains loonytoons.org toons.org
2393                   envelope X-Envelope-To
2394                   user maildrop with pass secret1 to * here
2395
2396
2397       This  also says that the mailbox of account 'maildrop' on the server is
2398       a multidrop box.  It tells fetchmail that any  address  in  the  loony‐
2399       toons.org  or  toons.org  domains  (including sub-domain addresses like
2400       'joe@daffy.loonytoons.org') should be passed through to the local  SMTP
2401       listener  without  modification.   Be  careful  of mail loops if you do
2402       this!
2403
2404
2405       Here's an example configuration using ssh and the plugin  option.   The
2406       queries  are  made  directly  on the stdin and stdout of imapd via ssh.
2407       Note that in this setup, IMAP authentication can be skipped.
2408
2409
2410              poll mailhost.net with proto imap:
2411                   plugin "ssh %h /usr/sbin/imapd" auth ssh;
2412                   user esr is esr here
2413
2414

THE USE AND ABUSE OF MULTIDROP MAILBOXES

2416       Use the multiple-local-recipients feature with caution -- it can  bite.
2417       All multidrop features are ineffective in ETRN and ODMR modes.
2418
2419       Also, note that in multidrop mode duplicate mails may be suppressed.  A
2420       piece of mail is considered duplicate if it does not have a discernible
2421       envelope  recipient address, has the same header as the message immedi‐
2422       ately preceding and more than one addressee.  Such runs of messages may
2423       be  generated  when copies of a message addressed to multiple users are
2424       delivered to a multidrop box. (To be precise, fetchmail  6.2.5  through
2425       6.4.X  use  an  MD5  hash of the raw message header, and only fetchmail
2426       6.4.16+ document this properly.  Fetchmail 5.0.8  (1999-09-14)  through
2427       6.2.4  used  only  the Message-ID header.  5.0.7 and older did not sup‐
2428       press duplicates.)
2429
2430       Note that this duplication killer code checking the  entire  header  is
2431       very restrictive and may not suppress many duplicates in practice - for
2432       instance, if some X-Original-To or Delivered-To header  differs.   This
2433       is intentional and correct in such situations: wherever envelope infor‐
2434       mation is available, it should be used for reliable delivery of mailing
2435       list and blind carbon copy (Bcc) messages. See the subsection Duplicate
2436       suppression below for suggestions.
2437
2438
2439   Header versus Envelope addresses
2440       The fundamental problem is that by having your mail server toss several
2441       peoples' mail in a single maildrop box, you may have thrown away poten‐
2442       tially vital information about who each piece of mail was actually  ad‐
2443       dressed  to (the 'envelope address', as opposed to the header addresses
2444       in the RFC822 To/Cc headers - the Bcc is not available at the receiving
2445       end).   This  'envelope  address'  is  the address you need in order to
2446       reroute mail properly.
2447
2448       Sometimes fetchmail can deduce  the  envelope  address.   If  the  mail
2449       server MTA is sendmail and the item of mail had just one recipient, the
2450       MTA will have written a 'by/for' clause that  gives  the  envelope  ad‐
2451       dressee  into  its Received header. But this does not work reliably for
2452       other MTAs, nor if there is  more  than  one  recipient.   By  default,
2453       fetchmail  looks for envelope addresses in these lines; you can restore
2454       this default with -E "Received" or 'envelope Received'.
2455
2456       As a better alternative, some SMTP listeners and/or mail servers insert
2457       a  header  in each message containing a copy of the envelope addresses.
2458       This header (when it exists) is often  'X-Original-To',  'Delivered-To'
2459       or  'X-Envelope-To'.   Fetchmail's assumption about this can be changed
2460       with the -E or 'envelope' option.  Note that writing an envelope header
2461       of  this kind exposes the names of recipients (including blind-copy re‐
2462       cipients) to all receivers of the messages, so the upstream must  store
2463       one copy of the message per recipient to avoid becoming a privacy prob‐
2464       lem.
2465
2466       Postfix, since version 2.0, writes an X-Original-To: header which  con‐
2467       tains a copy of the envelope as it was received.
2468
2469       Qmail and Postfix generally write a 'Delivered-To' header upon deliver‐
2470       ing the message to the mail spool and  use  it  to  avoid  mail  loops.
2471       Qmail  virtual  domains however will prefix the user name with a string
2472       that normally matches the user's domain. To remove this prefix you  can
2473       use the -Q or 'qvirtual' option.
2474
2475       Sometimes,  unfortunately, neither of these methods works.  That is the
2476       point when you should contact your ISP and ask them to provide such  an
2477       envelope  header,  and  you should not use multidrop in this situation.
2478       When they all fail, fetchmail must fall back on the contents  of  To/Cc
2479       headers (Bcc headers are not available - see below) to try to determine
2480       recipient addressees -- and these are unreliable.  In particular, mail‐
2481       ing-list software often ships mail with only the list broadcast address
2482       in the To: header.
2483
2484       Note that a future version of fetchmail may remove To/Cc parsing!
2485
2486       When fetchmail cannot deduce a recipient address that is local, and the
2487       intended  recipient  address was anyone other than fetchmail's invoking
2488       user, mail will get lost.  This is what  makes  the  multidrop  feature
2489       risky without proper envelope information.
2490
2491       A  related  problem is that when you blind-copy a mail message, the Bcc
2492       information is carried only as envelope address (it is removed from the
2493       headers  by  the  sending  mail server, so fetchmail can see it only if
2494       there is an X-Envelope-To header).  Thus, blind-copying to someone  who
2495       gets  mail  over  a  fetchmail multidrop link will fail unless the mail
2496       server host routinely writes X-Envelope-To or an equivalent header into
2497       messages in your maildrop.
2498
2499       In conclusion, mailing lists and Bcc'd mail can only work if the server
2500       you are fetching from
2501
2502       (1)    stores one copy of the message per recipient in your domain and
2503
2504       (2)    records the envelope information in a special  header  (X-Origi‐
2505              nal-To, Delivered-To, X-Envelope-To).
2506
2507
2508   Good Ways To Use Multidrop Mailboxes
2509       Multiple  local names can be used to administer a mailing list from the
2510       client side of a fetchmail collection.  Suppose your name is 'esr', and
2511       you  want  to  both  pick  up your own mail and maintain a mailing list
2512       called (say) "fetchmail-friends", and you want to keep the  alias  list
2513       on your client machine.
2514
2515       On  your  server,  you can alias 'fetchmail-friends' to 'esr'; then, in
2516       your .fetchmailrc, declare 'to esr fetchmail-friends here'.  Then, when
2517       mail including 'fetchmail-friends' as a local address gets fetched, the
2518       list name will be appended to the list of recipients your SMTP listener
2519       sees.   Therefore  it will undergo alias expansion locally.  Be sure to
2520       include 'esr' in the local alias  expansion  of  fetchmail-friends,  or
2521       you'll  never  see  mail sent only to the list.  Also be sure that your
2522       listener has the "me-too" option set (sendmail's -oXm command-line  op‐
2523       tion  or OXm declaration) so your name is not removed from alias expan‐
2524       sions in messages you send.
2525
2526       This trick is not without its problems, however.  You'll begin  to  see
2527       this  when  a message comes in that is addressed only to a mailing list
2528       you do not have declared as a local name.  Each such message will  fea‐
2529       ture  an 'X-Fetchmail-Warning' header which is generated because fetch‐
2530       mail cannot find a valid local name in the recipient  addresses.   Such
2531       messages  default  (as  was described above) to being sent to the local
2532       user running fetchmail, but the program has no way to know that this is
2533       actually the right thing.
2534
2535
2536   Bad Ways To Abuse Multidrop Mailboxes
2537       Multidrop mailboxes and fetchmail serving multiple users in daemon mode
2538       do not mix.  The problem, again, is mail from mailing lists, which typ‐
2539       ically  does  not  have an individual recipient address on it.   Unless
2540       fetchmail can deduce an envelope address, such mail will only go to the
2541       account  running  fetchmail  (probably root).  Also, blind-copied users
2542       are very likely never to see their mail at all.
2543
2544       If you are tempted to use fetchmail to retrieve mail for multiple users
2545       from  a  single  mail drop via POP or IMAP, think again (and reread the
2546       section on header and envelope addresses above).  It would  be  smarter
2547       to just let the mail sit in the mail server's queue and use fetchmail's
2548       ETRN or ODMR modes to trigger SMTP sends periodically (of course,  this
2549       means  you  have  to poll more frequently than the mail server's expiry
2550       period).  If you cannot arrange this, try setting up a UUCP feed.
2551
2552       If you absolutely must use multidrop for this purpose, make  sure  your
2553       mail  server  writes an envelope-address header that fetchmail can see.
2554       Otherwise you will lose mail and it will come back to haunt you.
2555
2556
2557   Speeding Up Multidrop Checking
2558       Normally, when multiple users are declared fetchmail extracts recipient
2559       addresses  as described above and checks each host part with DNS to see
2560       if it is an alias of the mail server.  If so,  the  name  mappings  de‐
2561       scribed  in the "to ... here" declaration are done and the mail locally
2562       delivered.
2563
2564       This is a convenient but also slow method.  To speed it up, pre-declare
2565       mail  server  aliases  with 'aka'; these are checked before DNS lookups
2566       are done.  If you are certain your aka list contains all DNS aliases of
2567       the mail server (and all MX names pointing at it - note this may change
2568       in a future version) you can declare 'no dns' to suppress  DNS  lookups
2569       entirely and only match against the aka list.
2570
2571
2572   Duplicate suppression on multidrop
2573       If  fetchmail's  duplicate  suppression  code does not kick in for your
2574       multidrop mail account, other options is using sieve, or  for  instance
2575       Courier's  maildrop  package  (and in particular, its reformail program
2576       with the -D option) as the delivery agent (either  from  fetchmail,  or
2577       from your local mail server that fetchmail injects into).
2578
2579

SOCKS

2581       Support  for socks4/5 is a compile time configuration option. Once com‐
2582       piled in, fetchmail will always use the socks libraries and  configura‐
2583       tion  on your system, there are no run-time switches in fetchmail - but
2584       you can still configure SOCKS: you can specify which  SOCKS  configura‐
2585       tion file is used in the SOCKS_CONF environment variable.
2586
2587       For  instance,  if  you wanted to bypass the SOCKS proxy altogether and
2588       have   fetchmail   connect    directly,    you    could    just    pass
2589       SOCKS_CONF=/dev/null  in  the  environment, for example (add your usual
2590       command line options - if any - to the end of this line):
2591
2592       env SOCKS_CONF=/dev/null fetchmail
2593
2594

EXIT CODES

2596       To facilitate the use of fetchmail in  shell  scripts,  an  exit status
2597       code  is returned to give an indication of what occurred during a given
2598       connection.
2599
2600       The exit codes returned by fetchmail are as follows:
2601
2602       0      One or more messages were successfully retrieved (or, if the  -c
2603              option was selected, were found waiting but not retrieved).
2604
2605       1      There  was no mail awaiting retrieval.  (There may have been old
2606              mail still on the server but not selected for retrieval.) If you
2607              do  not  want  "no mail" to be an error condition (for instance,
2608              for cron jobs), use a POSIX-compliant shell and add
2609
2610              || [ $? -eq 1 ]
2611
2612              to the end of the fetchmail command line, note that this  leaves
2613              0  untouched,  maps  1  to 0, and maps all other codes to 1. See
2614              also item #C8 in the FAQ.
2615
2616       2      An error was encountered when attempting to open a socket to re‐
2617              trieve  mail.  If you do not know what a socket is, do not worry
2618              about it -- just treat this as an 'unrecoverable  error'.   This
2619              error  can  also be because a protocol fetchmail wants to use is
2620              not listed in /etc/services.
2621
2622       3      The user authentication step failed.  This usually means that  a
2623              bad user-id, password, or APOP id was specified.  Or it may mean
2624              that you tried to run fetchmail under circumstances where it did
2625              not  have  standard  input  attached to a terminal and could not
2626              prompt for a missing password.
2627
2628       4      Some sort of fatal protocol error was detected.
2629
2630       5      There was a syntax error in the arguments  to  fetchmail,  or  a
2631              pre- or post-connect command failed.
2632
2633       6      The run control file had bad permissions.
2634
2635       7      There  was  an error condition reported by the server.  Can also
2636              fire if fetchmail timed out while waiting for the server.
2637
2638       8      Client-side exclusion error.  This means fetchmail either  found
2639              another  copy of itself already running, or failed in such a way
2640              that it is not sure whether another copy is running.
2641
2642       9      The user authentication step failed because the server responded
2643              "lock  busy".  Try again after a brief pause!  This error is not
2644              implemented for all protocols, nor for all servers.  If not  im‐
2645              plemented  for  your  server,  "3" will be returned instead, see
2646              above.  May be returned when talking to qpopper or other servers
2647              that  can respond with "lock busy" or some similar text contain‐
2648              ing the word "lock".
2649
2650       10     The fetchmail run failed while trying to do an SMTP port open or
2651              transaction.
2652
2653       11     Fatal  DNS error.  Fetchmail encountered an error while perform‐
2654              ing a DNS lookup at startup and could not proceed.
2655
2656       12     BSMTP batch file could not be opened.
2657
2658       13     Poll terminated by a fetch limit (see the --fetchlimit option).
2659
2660       14     Server busy indication.
2661
2662       23     Internal error.  You should see a message on standard error with
2663              details.
2664
2665       24 - 26, 28, 29
2666              These are internal codes and should not appear externally.
2667
2668       When  fetchmail  queries  more than one host, return status is 0 if any
2669       query successfully retrieved mail. Otherwise the returned error  status
2670       is that of the last host queried.
2671
2672

FILES

2674       ~/.fetchmailrc, $HOME/.fetchmailrc, $HOME_ETC/.fetchmailrc, $FETCHMAIL‐
2675       HOME/fetchmailrc
2676            default run control file (location can be overridden with environ‐
2677            ment variables)
2678
2679       ~/.fetchids,    $HOME/.fetchids,    $HOME_ETC/.fetchids,    $FETCHMAIL‐
2680       HOME/.fetchids
2681            default location of file recording  last  message  UIDs  seen  per
2682            host.  (location can be overridden with environment variables)
2683
2684       ~/.fetchmail.pid,    $HOME/.fetchmail.pid,    $HOME_ETC/.fetchmail.pid,
2685       $FETCHMAILHOME/fetchmail.pid
2686            default location of lock file (sometimes  called  pidfile  or  PID
2687            file,  see  option  pidfile) to help prevent concurrent runs (non-
2688            root mode).  (location can be overridden  with  environment  vari‐
2689            ables)
2690
2691       ~/.netrc, $HOME/.netrc, $HOME_ETC/.netrc
2692            your FTP run control file, which (if present) will be searched for
2693            passwords as a last resort before prompting for one interactively.
2694            (location can be overridden with environment variables)
2695
2696       /var/run/fetchmail.pid
2697            lock  file  (pidfile)  to help prevent concurrent runs (root mode,
2698            Linux systems).
2699
2700       /etc/fetchmail.pid
2701            lock file (pidfile) to help prevent concurrent  runs  (root  mode,
2702            systems without /var/run).
2703
2704

ENVIRONMENT

2706       Fetchmail's  behavior  can  be altered by providing it with environment
2707       variables. Some may alter the operation  of  libraries  that  fetchmail
2708       links  against,  for  instance, OpenSSL.  Note that in daemon mode, you
2709       will need to quit the background daemon process and start a new  fetch‐
2710       mail daemon for environment changes to take effect.
2711
2712       FETCHMAILHOME
2713              If  this environment variable is set to a valid and existing di‐
2714              rectory name,  fetchmail  will  read  $FETCHMAILHOME/fetchmailrc
2715              (the  dot  is  missing  in  this case), $FETCHMAILHOME/.fetchids
2716              (keeping its dot) and $FETCHMAILHOME/fetchmail.pid (without dot)
2717              rather  than from the user's home directory.  The .netrc file is
2718              always looked for in the  invoking  user's  home  directory  (or
2719              $HOME_ETC) regardless of FETCHMAILHOME's setting.
2720
2721
2722       FETCHMAILUSER
2723              If  this  environment variable is set, it is used as the name of
2724              the calling user (default local name) for purposes such as mail‐
2725              ing  error  notifications.   Otherwise, if either the LOGNAME or
2726              USER variable is correctly  set  (e.g.,  the  corresponding  UID
2727              matches  the  session user ID) then that name is used as the de‐
2728              fault local name.  Otherwise getpwuid(3) must  be  able  to  re‐
2729              trieve a password entry for the session ID (this elaborate logic
2730              is designed to handle the case of multiple  names  per  user  ID
2731              gracefully).
2732
2733
2734       FETCHMAIL_DISABLE_CBC_IV_COUNTERMEASURE
2735              (since  v6.3.22):  If  this  environment variable is set and not
2736              empty, fetchmail will disable a countermeasure  against  an  SSL
2737              CBC  IV  attack (by setting SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS).
2738              This is a security risk, but may be necessary for connecting  to
2739              certain  non-standards-conforming servers.  See fetchmail's NEWS
2740              file and fetchmail-SA-2012-01.txt for details.   Earlier  fetch‐
2741              mail  versions (v6.3.21 and older) used to disable this counter‐
2742              measure, but v6.3.22 no longer does that as a safety precaution.
2743
2744
2745       FETCHMAIL_POP3_FORCE_RETR
2746              (since v6.3.9): If this environment variable is defined  at  all
2747              (even  if  empty), fetchmail will forgo the POP3 TOP command and
2748              always use RETR. This can be used as a workaround when TOP  does
2749              not work properly.
2750
2751
2752       FETCHMAIL_INCLUDE_DEFAULT_X509_CA_CERTS
2753              (since  v6.3.17):  If  this  environment variable is set and not
2754              empty, fetchmail will always load the default X.509 trusted cer‐
2755              tificate   locations   for  SSL/TLS  CA  certificates,  even  if
2756              --sslcertfile and --sslcertpath are given.  The latter locations
2757              take precedence over the system default locations.  This is use‐
2758              ful in case there are broken certificates in the system directo‐
2759              ries  and the user has no administrator privileges to remedy the
2760              problem.
2761
2762
2763       HOME   (documented since 6.4.1): This variable is normally set  to  the
2764              user's  home  directory.  If  it is set to a different directory
2765              than what is in the password database, HOME takes precedence.
2766
2767
2768       HOME_ETC
2769              (documentation  corrected  to  match  behaviour  of  code  since
2770              6.4.1): If the HOME_ETC variable is set, it will override fetch‐
2771              mail's idea of $HOME, i. e. fetchmail  will  read  .fetchmailrc,
2772              .fetchids,  .fetchmail.pid  and .netrc from $HOME_ETC instead of
2773              $HOME (or if HOME is also unset, from the passwd file's home di‐
2774              rectory location).
2775
2776              If  HOME_ETC and FETCHMAILHOME are both set, FETCHMAILHOME takes
2777              precedence and HOME_ETC will be ignored.
2778
2779
2780       SOCKS_CONF
2781              (only if SOCKS support is compiled in) this variable is used  by
2782              the socks library to find out which configuration file it should
2783              read. Set this to /dev/null to bypass the SOCKS proxy.
2784
2785
2786       SSL_CERT_DIR
2787              (with  truly  OpenSSL  1.1.1  compatible   library):   overrides
2788              OpenSSL's  idea  of  the  default trust directory or path (which
2789              contains individual certificate files and hashed symlinks),  see
2790              the SSL_CTX_set_default_verify_paths(3) manual page for details,
2791              it may be in the openssl development package.  If using  another
2792              library's  OpenSSL  compatibility  interface, this may not work.
2793              Since this variable only specifies a default value,  the  option
2794              --sslcertpath takes precedence if given.
2795
2796
2797       SSL_CERT_FILE
2798              (with   truly   OpenSSL  1.1.1  compatible  library):  overrides
2799              OpenSSL's idea of the  default  trust  certificate  bundle  file
2800              (which  contains  a concatenation of base64-encoded certificates
2801              in PEM format), see the SSL_CTX_set_default_verify_paths(3) man‐
2802              ual page for details, it may be in the openssl development pack‐
2803              age.  If using another library's  OpenSSL  compatibility  inter‐
2804              face,  this  may not work.  Since this variable only specifies a
2805              default value, the  option  --sslcertfile  takes  precedence  if
2806              given.
2807
2808

SIGNALS

2810       If  a fetchmail daemon is running as root, SIGUSR1 wakes it up from its
2811       sleep phase and forces a poll of all non-skipped servers. For  compati‐
2812       bility  reasons, SIGHUP can also be used in 6.3.X but may not be avail‐
2813       able in future fetchmail versions.
2814
2815       If fetchmail is running in daemon mode as non-root, use SIGUSR1 to wake
2816       it  (this  is  so SIGHUP due to logout can retain the default action of
2817       killing it).
2818
2819       Running fetchmail in foreground while a background fetchmail is running
2820       will do whichever of these is appropriate to wake it up.
2821
2822

BUGS, LIMITATIONS, AND KNOWN PROBLEMS

2824       Please  check  the NEWS file that shipped with fetchmail for more known
2825       bugs than those listed here.
2826
2827       Fetchmail cannot handle user names that  contain  blanks  after  a  "@"
2828       character, for instance "demonstr@ti on". These are rather uncommon and
2829       only hurt when using UID-based --keep setups, so the 6.X.Y versions  of
2830       fetchmail will not be fixed.
2831
2832       Fetchmail cannot handle configurations where you have multiple accounts
2833       that use the same server name and the same login. Any user@server  com‐
2834       bination must be unique.
2835
2836       The  assumptions  that the DNS and in particular the checkalias options
2837       make are not often sustainable. For instance, it  has  become  uncommon
2838       for  an  MX server to be a POP3 or IMAP server at the same time. There‐
2839       fore the MX lookups may go away in a future release.
2840
2841       The mda and plugin options interact badly.  In order to  collect  error
2842       status from the MDA, fetchmail has to change its normal signal handling
2843       so that dead plugin processes do not get reaped until the  end  of  the
2844       poll cycle.  This can cause resource starvation if too many zombies ac‐
2845       cumulate.  So either do not deliver to a MDA using plugins or risk  be‐
2846       ing overrun by an army of undead.
2847
2848       The  --interface  option does not support IPv6 and it is doubtful if it
2849       ever will, since there is no portable way to query interface  IPv6  ad‐
2850       dresses.
2851
2852       The  RFC822  address parser used in multidrop mode chokes on some @-ad‐
2853       dresses that are technically legal but bizarre.  Strange uses of  quot‐
2854       ing and embedded comments are likely to confuse it.
2855
2856       In  a  message  with  multiple envelope headers, only the last one pro‐
2857       cessed will be visible to fetchmail.
2858
2859       Use of some of these protocols requires that  the  program  send  unen‐
2860       crypted  passwords over the TCP/IP connection to the mail server.  This
2861       creates a risk that name/password pairs might be snaffled with a packet
2862       sniffer  or  more  sophisticated  monitoring software.  Under Linux and
2863       FreeBSD, the --interface option can be  used  to  restrict  polling  to
2864       availability  of  a  specific interface device with a specific local or
2865       remote IP address, but snooping is still possible if  (a)  either  host
2866       has a network device that can be opened in promiscuous mode, or (b) the
2867       intervening network link can be tapped.  We recommend the use of ssh(1)
2868       tunnelling  to  not  only  shroud your passwords but encrypt the entire
2869       conversation.
2870
2871       Use of the %F or %T escapes in an mda  option  could  open  a  security
2872       hole, because they pass text manipulable by an attacker to a shell com‐
2873       mand.  Potential shell characters are replaced by '_' before execution.
2874       The hole is further reduced by the fact that fetchmail temporarily dis‐
2875       cards any set-uid privileges it may have while running  the  MDA.   For
2876       maximum  safety, however, do not use an mda command containing %F or %T
2877       when fetchmail is run from the root account itself.
2878
2879       Fetchmail's method of sending bounces due to  errors  or  spam-blocking
2880       and  spam  bounces  requires that port 25 of localhost be available for
2881       sending mail via SMTP.
2882
2883       If you modify ~/.fetchmailrc while a background instance is running and
2884       break  the syntax, the background instance will die silently.  Unfortu‐
2885       nately, it cannot die noisily because we do not yet know whether syslog
2886       should  be  enabled.   On  some systems, fetchmail dies quietly even if
2887       there is no syntax error; this seems to have something to do with buggy
2888       terminal ioctl code in the kernel.
2889
2890       The  -f  -  option (reading a configuration from stdin) is incompatible
2891       with the plugin option.
2892
2893       The 'principal' option only handles Kerberos IV, not V.
2894
2895       Interactively entered passwords are truncated after 63  characters.  If
2896       you  really  need to use a longer password, you will have to use a con‐
2897       figuration file.
2898
2899       A backslash as the last character  of  a  configuration  file  will  be
2900       flagged as a syntax error rather than ignored.
2901
2902       The  BSMTP error handling is virtually nonexistent and may leave broken
2903       messages behind.
2904
2905       Send comments, bug reports, gripes, and the like to the fetchmail-devel
2906       list ⟨fetchmail-devel@lists.sourceforge.net⟩
2907
2908
2909       An  HTML  FAQ  ⟨https://fetchmail.sourceforge.io/fetchmail-FAQ.html⟩ is
2910       available at the fetchmail home page, it should also accompany your in‐
2911       stallation.
2912
2913

AUTHOR

2915       Fetchmail  is currently maintained by Matthias Andree and Rob Funk with
2916       major assistance from Sunil Shetye (for code) and  Rob  MacGregor  (for
2917       the mailing lists).
2918
2919       Most of the code is from Eric S. Raymond ⟨esr@snark.thyrsus.com⟩ .  Too
2920       many other people to name here have contributed code and patches.
2921
2922       This program is descended from and replaces popclient, by  Carl  Harris
2923       ⟨ceharris@mal.com⟩  ;  the  internals  have become quite different, but
2924       some of its interface design is directly traceable  to  that  ancestral
2925       program.
2926
2927       This  manual page has been improved by Matthias Andree, R. Hannes Bein‐
2928       ert, and Héctor García.
2929
2930

SEE ALSO

2932       README, README.SSL, README.SSL-SERVER, The Fetchmail FAQ ⟨https://
2933       www.fetchmail.info/fetchmail-FAQ.html⟩, mutt(1), elm(1), mail(1), send‐
2934       mail(8), popd(8), imapd(8), netrc(5).
2935
2936       The fetchmail home page.  ⟨https://www.fetchmail.info/
2937
2938       The fetchmail home page (alternative URI).  ⟨https://
2939       fetchmail.sourceforge.io/⟩
2940
2941       The maildrop home page.  ⟨https://www.courier-mta.org/maildrop/
2942

APPLICABLE STANDARDS

2944       Note that this list is just a collection of references and not a state‐
2945       ment as to the actual protocol conformance or  requirements  in  fetch‐
2946       mail.
2947
2948       SMTP/ESMTP:
2949            RFC  821,  RFC  2821,  RFC 1869, RFC 1652, RFC 1870, RFC 1983, RFC
2950            1985, RFC 2554.
2951
2952       mail:
2953            RFC 822, RFC 2822, RFC 1123, RFC 1892, RFC 1894.
2954
2955       POP2:
2956            RFC 937
2957
2958       POP3:
2959            RFC 1081, RFC 1225, RFC 1460, RFC 1725, RFC 1734,  RFC  1939,  RFC
2960            1957, RFC 2195, RFC 2449.
2961
2962       APOP:
2963            RFC 1939.
2964
2965       RPOP:
2966            RFC 1081, RFC 1225.
2967
2968       IMAP2/IMAP2BIS:
2969            RFC 1176, RFC 1732.
2970
2971       IMAP4/IMAP4rev1:
2972            RFC  1730,  RFC  1731, RFC 1732, RFC 2060, RFC 2061, RFC 2195, RFC
2973            2177, RFC 2683.
2974
2975       ETRN:
2976            RFC 1985.
2977
2978       ODMR/ATRN:
2979            RFC 2645.
2980
2981       OTP: RFC 1938.
2982
2983       LMTP:
2984            RFC 2033.
2985
2986       GSSAPI:
2987            RFC 1508, RFC 1734, Generic Security Service Application Program
2988            Interface (GSSAPI)/Kerberos/Simple Authentication and Security
2989            Layer (SASL) Service Names ⟨https://www.iana.org/assignments/
2990            gssapi-service-names/⟩.
2991
2992       TLS: RFC 2595.
2993
2994
2995
2996fetchmail 6.4.24                  2021-11-20                      fetchmail(1)
Impressum