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 store the envelope information
96              in some message header and. The ISP must also store one copy  of
97              the  message  per  recipient. If either of the conditions is not
98              fulfilled, this process is unreliable,  because  fetchmail  must
99              then resort to guessing the true envelope recipient(s) of a mes‐
100              sage. 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       You  can access TLS-encrypted services by specifying the options start‐
1191       ing with --ssl, such as --ssl,  --sslproto,  --sslcertck,  and  others.
1192       You  can  also  do  this  using  the  corresponding user options in the
1193       .fetchmailrc file.  Some services, such as POP3 and IMAP, have  differ‐
1194       ent  well  known ports defined for the SSL encrypted services.  The en‐
1195       crypted ports will be selected automatically when SSL is enabled and no
1196       explicit  port  is  specified.    Also, the --sslcertck command line or
1197       sslcertck run control file option should be used to force  strict  cer‐
1198       tificate checking with older fetchmail versions - see below.
1199
1200       If  TLS  or  SSL is not configured, fetchmail will usually still try to
1201       use STARTTLS somewhat  opportunistically.  In  practice,  is  it  still
1202       mandatory  because  --sslcertck is a default setting and implicitly re‐
1203       quires STARTTLS.
1204
1205       STARTTLS can be enforced by using --sslproto auto and defeated by using
1206       --sslproto  ''.   STARTTLS  connections  use the same port as the unen‐
1207       crypted version of the protocol and negotiate TLS via special  command.
1208       The  --sslcertck  command  line  or  sslcertck  run control file option
1209       should be used to force strict certificate checking - see below.
1210
1211       --sslcertck is recommended: When connecting to an SSL or TLS  encrypted
1212       server, the server presents a certificate to the client for validation.
1213       The certificate is checked to verify that the common name in  the  cer‐
1214       tificate  matches  the  name of the server being contacted and that the
1215       effective and expiration dates in the certificate indicate that  it  is
1216       currently  valid.   If  any  of these checks fail, a warning message is
1217       printed, but the connection continues.  The server certificate does not
1218       need  to  be  signed  by any specific Certifying Authority and may be a
1219       "self-signed" certificate. If the --sslcertck command  line  option  or
1220       sslcertck run control file option is used, fetchmail will instead abort
1221       if any of these checks fail, because it must assume  that  there  is  a
1222       man-in-the-middle attack in this scenario, hence fetchmail must not ex‐
1223       pose clear-text passwords. Use of the sslcertck or  --sslcertck  option
1224       is therefore advised; it has become the default in fetchmail 6.4.0.
1225
1226       Some  SSL  encrypted  servers may request a client side certificate.  A
1227       client side public SSL certificate and private SSL key  may  be  speci‐
1228       fied.   If  requested  by the server, the client certificate is sent to
1229       the server for validation.  Some servers may  require  a  valid  client
1230       certificate and may refuse connections if a certificate is not provided
1231       or if the certificate is not valid.  Some servers  may  require  client
1232       side  certificates be signed by a recognized Certifying Authority.  The
1233       format for the key files and the certificate files is that required  by
1234       the underlying SSL libraries (OpenSSL in the general case).
1235
1236       A  word  of care about the use of SSL: While above mentioned setup with
1237       self-signed server certificates retrieved over the  wires  can  protect
1238       you from a passive eavesdropper, it does not help against an active at‐
1239       tacker. It is clearly an improvement  over  sending  the  passwords  in
1240       clear, but you should be aware that a man-in-the-middle attack is triv‐
1241       ially possible (in particular with tools such as dsniff ⟨https://
1242       monkey.org/~dugsong/dsniff/⟩,  ).   Use  of strict certificate checking
1243       with a certification authority recognized by server and client, or per‐
1244       haps  of  an  SSH tunnel (see below for some examples) is preferable if
1245       you care seriously about the security of your mailbox and passwords.
1246
1247

POP3 VARIANTS

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

ALTERNATE AUTHENTICATION FORMS/METHODS

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

DAEMON MODE

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

ADMINISTRATIVE OPTIONS

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

RETRIEVAL FAILURE MODES

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

SPAM FILTERING

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

SMTP/ESMTP ERROR HANDLING

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

THE RUN CONTROL FILE

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

DEBUGGING FETCHMAIL

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

INTERACTION WITH RFC 822

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

CONFIGURATION EXAMPLES

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

THE USE AND ABUSE OF MULTIDROP MAILBOXES

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

SOCKS

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

EXIT CODES

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

FILES

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

ENVIRONMENT

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

SIGNALS

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

BUGS, LIMITATIONS, AND KNOWN PROBLEMS

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

AUTHOR

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

SEE ALSO

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

APPLICABLE STANDARDS

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