## SYNOPSIS

           fetchmail [option...] [mailserver...]
           fetchmailconf

## DESCRIPTION

           fetchmail is a mail-retrieval and forwarding  utility;  it
           fetches  mail  from  remote mailservers and forwards it to
           your local (client) machine's delivery  system.   You  can
           then  handle  the  retrieved  mail  using normal mail user
           agents such as mutt(1), elm(1) or Mail(1).  The  fetchmail
           utility can be run in a daemon mode to repeatedly poll one
           or more systems at a specified interval.

           The fetchmail program can gather mail  from  servers  sup
           porting  any of the common mail-retrieval protocols: POP2,
           POP3, IMAP2bis, IMAP4, and IMAPrev1.  It can also use  the
           ESMTP  ETRN  extension and ODMR.  (The RFCs describing all
           these protocols are listed  at  the  end  of  this  manual
           page.)

           While  fetchmail is primarily intended to be used over on-
           demand TCP/IP links (such as SLIP or PPP connections),  it
           may  also  be useful as a message transfer agent for sites
           which refuse for security reasons to permit (sender-initi
           ated) SMTP transactions with sendmail.

           As  each  message is retrieved fetchmail normally delivers
           it via SMTP to port 25 on the machine  it  is  running  on
           (localhost), just as though it were being passed in over a
           normal TCP/IP link.   The  mail  will  then  be  delivered
           locally  via  your system's MDA (Mail Delivery Agent, usu
           ally sendmail(8) but your system may use a  different  one
           such  as  smail, mmdf, exim, or qmail).  All the delivery-
           control  mechanisms  (such  as  .forward  files)  normally
           available  through  your  system  MDA  and  local delivery
           agents will therefore work.

           If no port 25 listener is available,  but  your  fetchmail
           configuration was told about a reliable local MDA, it will
           use that MDA for local delivery instead.  At  build  time,
           fetchmail  normally  looks  for executable procmail(1) and
           sendmail(1) binaries.

           If the program fetchmailconf is available, it will  assist
           you in setting up and editing a fetchmailrc configuration.
           It runs under X and requires that the language Python  and
           the  Tk  toolkit  be  present  on your system.  If you are
           first setting up fetchmail for  single-user  mode,  it  is
           recommended  that  you  use Novice mode.  Expert mode pro
           Each server name that you specify following the options on
           the  command  line  will be queried.  If you don't specify
           any servers on the command line, each `poll' entry in your
           ~/.fetchmailrc file will be queried.

           To   facilitate  the  use  of  fetchmail  in  scripts  and
           pipelines, it returns an appropriate exit code upon termi
           nation -- see EXIT CODES below.

           The  following  options  modify the behavior of fetchmail.
           It is seldom necessary to specify any of  these  once  you
           have a working .fetchmailrc file set up.

           Almost  all options have a corresponding keyword which can
           be used to declare them in a .fetchmailrc file.

           Some special options are not covered here, but  are  docu
           mented  instead  in  sections on AUTHENTICATION and DAEMON
           MODE which follow.

       General Options
           -V | --version
                  Displays the version information for your  copy  of
                  fetchmail.   No  mail fetch is performed.  Instead,
                  for each server specified, all the option  informa
                  tion  that would be computed if fetchmail were con
                  necting to that  server  is  displayed.   Any  non-
                  printables  in  passwords or other string names are
                  shown as backslashed C-like escape sequences.  This
                  option  is  useful  for verifying that your options
                  are set the way you want them.

           -c | --check
                  Return a status code to indicate whether  there  is
                  mail waiting, without actually fetching or deleting
                  mail (see EXIT CODES below).  This option turns off
                  daemon  mode  (in  which  it would be useless).  It
                  doesn't play well with queries to  multiple  sites,
                  and doesn't work with ETRN or ODMR.  It will return
                  a false positive if you leave  read  but  undeleted
                  mail in your server mailbox and your fetch protocol
                  can't tell kept messages from new ones.  This means
                  it will work with IMAP, not work with POP2, and may
                  occasionally flake out under POP3.

           -s | --silent
                  Silent mode.  Suppresses all  progress/status  mes
                  sages  that  are  normally echoed to standard error
                  during a fetch (but does not suppress actual  error
                  messages).  The --verbose option overrides this.

           -v | --verbose
                  with ETRN or ODMR.

           -k | --keep
                  (Keyword: keep)  Keep  retrieved  messages  on  the
                  remote  mailserver.  Normally, messages are deleted
                  from the folder on the mailserver after  they  have
                  been  retrieved.  Specifying the keep option causes
                  retrieved messages to remain in your folder on  the
                  mailserver.  This option does not work with ETRN or
                  ODMR.

           -K | --nokeep
                  (Keyword: nokeep) Delete  retrieved  messages  from
                  the   remote   mailserver.    This   option  forces
                  retrieved mail to be deleted.  It may be useful  if
                  you  have  specified  a  default  of  keep  in your
                  .fetchmailrc.  This option is forced on  with  ETRN
                  and ODMR.

           -F | --flush
                  POP3/IMAP  only.  Delete old (previously retrieved)
                  messages from the mailserver before retrieving  new
                  messages.  This  option  does not work with ETRN or
                  ODMR.  Warning: if your local MTA hangs and  fetch
                  mail  is  aborted, the next time you run fetchmail,
                  it will delete mail that  was  never  delivered  to
                  you.   What  you  probably want is the default set
                  ting: if you don't  specify  `-k',  then  fetchmail
                  will automatically delete messages after successful
                  delivery.

       Protocol and Query Options
           -p <proto> | --protocol <proto>
                  (Keyword: proto[col]) Specify the protocol  to  use
                  when  communicating with the remote mailserver.  If
                  no protocol is  specified,  the  default  is  AUTO.
                  proto may be one of the following:

                  AUTO   Tries  IMAP, POP3, and POP2 (skipping any of
                         these for which support has  not  been  com
                         piled in).

                  POP2   Post Office Protocol 2

                  POP3   Post Office Protocol 3

                  APOP   Use  POP3  with  old-fashioned MD5-challenge
                         authentication.

                  RPOP   Use POP3 with RPOP authentication.

                  KPOP   Use POP3 with Kerberos V4 authentication  on

           (communicating  with standard server daemons to fetch mail
           already delivered to a mailbox on the server) except  ETRN
           and  ODMR.   The  ETRN  mode allows you to ask a compliant
           ESMTP server (such as BSD sendmail  at  release  8.8.0  or
           higher)  to  immediately  open a sender-SMTP connection to
           your  client  machine  and  begin  forwarding  any   items
           addressed  to your client machine in the server's queue of
           undelivered mail.   The ODMR mode requires an ODMR-capable
           server  and  works  similarly to ETRN, except that it does
           not require the client machine to have a static DNS.

           -U | --uidl
                  (Keyword: uidl) Force UIDL use (effective only with
                  POP3).   Force client-side tracking of `newness' of
                  messages (UIDL stands for ``unique ID listing'' and
                  is described in RFC1725).  Use with `keep' to use a
                  mailbox as a baby news drop for a group  of  users.
                  The  fact that seen messages are skipped is logged,
                  unless error logging is done through  syslog  while
                  running in daemon mode.

           -P <portnumber> | --port <portnumber>
                  (Keyword:  port)  The  port  option  permits you to
                  specify a TCP/IP port to connect on.   This  option
                  will  seldom be necessary as all the supported pro
                  tocols have well-established default port  numbers.

           --principal <principal>
                  (Keyword:  principal)  The principal option permits
                  you to  specify  a  service  principal  for  mutual
                  authentication.  This is applicable to POP3 or IMAP
                  with Kerberos authentication.

           -t <seconds> | --timeout <seconds>
                  (Keyword: timeout) The timeout option allows you to
                  set  a server-nonresponse timeout in seconds.  If a
                  mailserver does not  send  a  greeting  message  or
                  respond  to  commands  for the given number of sec
                  onds, fetchmail will hang up on it.  Without such a
                  timeout fetchmail might hang up indefinitely trying
                  to fetch mail from a down host.  This would be par
                  ticularly annoying for a fetchmail running in back
                  ground.  There is a default timeout which fetchmail
                  -V will report.  If a given connection receives too
                  many timeouts in succession,  fetchmail  will  con
                  sider it wedged and stop retrying, the calling user
                  will be notified by email if this happens.

           --plugin <command>
                  (Keyword: plugin) The plugin option allows  you  to
                  use  an  external program to establish the TCP con
                  tions  (which  will probably not need it, so it has
                  been separated from plugin).

           -r <name> | --folder <name>
                  (Keyword: folder[s]) Causes a specified non-default
                  mail  folder  on the mailserver (or comma-separated
                  list of folders) to be retrieved.   The  syntax  of
                  the  folder  name is server-dependent.  This option
                  is not available under POP3, ETRN, or ODMR.

           --tracepolls
                  (Keyword: tracepolls) Tell fetchail to  poll  trace
                  information  in the form `polling %s account %s' to
                  the Received line it generates, where the %s  parts
                  are replaced by the user's remote name and the poll
                  label (the Received header also  normally  includes
                  the  server's  truename).   This  can  be  used  to
                  facilate mail filtering based on the account it  is
                  being received from.

           --ssl  (Keyword:  ssl)  Causes  the connection to the mail
                  server to be encrypted via  SSL.   Connect  to  the
                  server  using  the  specified  base protocol over a
                  connection secured by SSL.   SSL  support  must  be
                  present  at  the  server.  If no port is specified,
                  the connection is attempted to the well known  port
                  of  the  SSL version of the base protocol.  This is
                  generally a different port than the  port  used  by
                  the  base protocol.  For IMAP, this is port 143 for
                  the clear protocol and port 993 for the SSL secured
                  protocol.

           --sslcert <name>
                  (Keyword:  sslcert)  Specifies the file name of the
                  client  side  public  SSL  certificate.   Some  SSL
                  encrypted  servers may require client side keys and
                  certificates for authentication.   In  most  cases,
                  this  is  optional.  This specifies the location of
                  the public key certificate to be presented  to  the
                  server  at the time the SSL session is established.
                  It is not required (but may  be  provided)  if  the
                  server  does  not  require  it.   Some  servers may
                  require it, some servers may  request  it  but  not
                  require  it, and some servers may not request it at
                  all.  It may be the same file as  the  private  key
                  (combined key and certificate file) but this is not
                  recommended.

           --sslkey <name>
                  (Keyword: sslkey) Specifies the file  name  of  the
                  client  side  private  SSL key.  Some SSL encrypted
                  servers may require client side keys  and  certifi

           --sslproto <name>
                  (Keyword: sslproto) Forces an ssl protocol.  Possi
                  ble  values are `ssl2', `ssl3' and `tls1'. Try this
                  if the default handshake does  not  work  for  your
                  server.

           --sslcertck
                  (Keyword:  sslcertck)  Causes fetchmail to strictly
                  check the server certificate against a set of local
                  trusted  certificates (see the sslcertpath option).
                  If the server certificate is not signed by  one  of
                  the  trusted ones (directly or indirectly), the SSL
                  connection will fail. This checking should  prevent
                  man-in-the-middle  attacks  against the SSL connec
                  tion. Note that CRLs are  seemingly  not  currently
                  supported  by  OpenSSL in certificate verification!
                  Your system clock  should  be  reasonably  accurate
                  when using this option!

           --sslcertpath <directory>
                  (Keyword: sslcertpath) Sets the directory fetchmail
                  uses to look up local certificates. The default  is
                  your  OpenSSL  default  one.  The directory must be
                  hashed as OpenSSL expects it - every time  you  add
                  or  modify a certificate in the directory, you need
                  to use the c_rehash tool (which comes with  OpenSSL
                  in the tools/ subdirectory).

           --sslfingerprint
                  (Keyword:  sslfingerprint)  Specify the fingerprint
                  of the server key (an MD5 hash of the key) in  hex
                  adecimal  notation with colons separating groups of
                  two digits. The letter hex digits must be in  upper
                  case.  This is the default format OpenSSL uses, and
                  the one fetchmail uses to  report  the  fingerprint
                  when an SSL connection is established. When this is
                  specified, fetchmail will compare  the  server  key
                  fingerprint  with the given one, and the connection
                  will fail if they do not match. This can be used to
                  prevent man-in-the-middle attacks.

       Delivery Control Options
           -S <hosts> | --smtphost <hosts>
                  (Keyword:  smtp[host]) Specify a hunt list of hosts
                  to forward mail to (one or more  hostnames,  comma-
                  separated).  Hosts  are  tried  in  list order; the
                  first one that is up becomes the forwarding  target
                  for  the  current  run.   Normally,  `localhost' is
                  added to the  end  of  the  list  as  an  invisible
                  default.   However, when using Kerberos authentica
                  tion, the FQDN of the machine running fetchmail  is
                  or LMTP receiver.

           --fetchdomains <hosts>
                  (Keyword:  fetchdomains) In ETRN or ODMR mode, this
                  option specifies the list  of  domains  the  server
                  should  ship mail for once the connection is turned
                  around.  The default is the  FQDN  of  the  machine
                  running fetchmail.

           -D <domain> | --smtpaddress <domain>
                  (Keyword:  smtpaddress)  Specify  the  domain to be
                  appended to addresses in RCPT TO lines  shipped  to
                  SMTP.  The name of the SMTP server (as specified by
                  --smtphost, or defaulted to  "localhost")  is  used
                  when this is not specified.

           --smtpname <user@domain>
                  (Keyword:  smtpname) Specify the domain and user to
                  be put in RCPT  TO  lines  shipped  to  SMTP.   The
                  default user is the current local user.

           -Z <nnn> | --antispam <nnn[, nnn]...>
                  (Keyword:  antispam)  Specifies the list of numeric
                  SMTP errors that are to be interpreted as  a  spam-
                  block  response  from  the listener.  A value of -1
                  disables this option.  For the command-line option,
                  the list values should be comma-separated.

           -m <command> | --mda <command>
                  (Keyword:  mda)  You can force mail to be passed to
                  an MDA directly (rather than forwarded to port  25)
                  with the --mda or -m option.  To avoid losing mail,
                  use this option only with  MDAs  like  procmail  or
                  sendmail  that return a nonzero status on disk-full
                  and other resource-exhaustion errors;  the  nonzero
                  status  tells  fetchmail  that  delivery failed and
                  prevents the message from  being  deleted  off  the
                  server.   If  fetchmail is running as root, it sets
                  its userid to that of the target user while  deliv
                  ering  mail through an MDA.  Some possible MDAs are
                  "/usr/sbin/sendmail     -i     -f      %F      %T",
                  "/usr/bin/deliver"  and  "/usr/bin/procmail  -d %T"
                  (but the latter is usually redundant as  it's  what
                  SMTP  listeners normally forward to).  Local deliv
                  ery addresses will be inserted into the MDA command
                  wherever  you  place  a %T; the mail message's From
                  address will be inserted where you place an %F.  Do
                  not  use  an  MDA  invocation like "sendmail -i -t"
                  that dispatches on the contents  of  To/Cc/Bcc,  it
                  will  create mail loops and bring the just wrath of
                  many postmasters down upon your head.

                  MAIL  FROM and RCPT TO lines is not guaranteed cor
                  rect; the caveats discussed under THE USE AND ABUSE
                  OF MULTIDROP MAILBOXES below apply.

       Resource Limit Control Options
           -l <maxbytes> | --limit <maxbytes>
                  (Keyword:  limit)  Takes a maximum octet size argu
                  ment.  Messages larger than this size will  not  be
                  fetched  and  will  be left on the server (in fore
                  ground sessions, the progress  messages  will  note
                  that  they are "oversized").  If the fetch protocol
                  permits (in particular, under IMAP or POP3  without
                  the fetchall option) the message will not be marked
                  seen An explicit --limit of 0 overrides any  limits
                  set  in  your  run  control  file.  This  option is
                  intended for  those  needing  to  strictly  control
                  fetch  time  due  to  expensive  and variable phone
                  rates.  In daemon mode, oversize notifications  are
                  mailed  to  the  calling  user  (see the --warnings
                  option).  This option does not work  with  ETRN  or
                  ODMR.

           -w <interval> | --warnings <interval>
                  (Keyword:  warnings)  Takes an interval in seconds.
                  When you call fetchmail with a  `limit'  option  in
                  daemon  mode,  this  controls the interval at which
                  warnings about oversized messages are mailed to the
                  calling  user  (or the user specified by the `post
                  master' option).  One such notification  is  always
                  mailed  at  the  end of the the first poll that the
                  oversized message is detected.  Thereafter, renoti
                  fication  is  suppressed  until  after  the warning
                  interval elapses (it will take place at the end  of
                  the first following poll).

           -b <count> | --batchlimit <count>
                  (Keyword: batchlimit) Specify the maximum number of
                  messages that will be shipped to an  SMTP  listener
                  before the connection is deliberately torn down and
                  rebuilt (defaults to  0,  meaning  no  limit).   An
                  explicit --batchlimit of 0 overrides any limits set
                  in your run control file.  While  sendmail(8)  nor
                  mally  initiates  delivery of a message immediately
                  after receiving the message terminator,  some  SMTP
                  listeners  are  not  so prompt.  MTAs like smail(8)
                  may wait till the delivery socket is shut  down  to
                  deliver.   This  may  produce  annoying delays when
                  fetchmail is processing very large  batches.   Set
                  ting the batch limit to some nonzero size will pre
                  vent these delays.  This option does not work  with
                  ETRN or ODMR.

                  ing QUIT after each sub-session.  This  is  a  good
                  defense  against line drops on POP3 servers that do
                  not do the equivalent of a QUIT on  hangup.   Under
                  IMAP,  fetchmail normally issues an EXPUNGE command
                  after each deletion in order to force the  deletion
                  to  be  done immediately.  This is safest when your
                  connection to the server is flaky and expensive, as
                  it  avoids  resending  duplicate  mail after a line
                  hit.  However, on large mailboxes the  overhead  of
                  re-indexing after every message can slam the server
                  pretty hard, so if your connection is  reliable  it
                  is  good to do expunges less frequently.  Also note
                  that some servers enforce a delay of a few  seconds
                  after  each  quit,  so fetchmail may not be able to
                  get back in immediately after an expunge -- you may
                  see  "lock  busy"  errors  if  this happens. If you
                  specify this option  to  an  integer  N,  it  tells
                  fetchmail  to  only  issue  expunges  on  every Nth
                  delete.  An argument of  zero  suppresses  expunges
                  entirely  (so no expunges at all will be done until
                  the end of run).  This option does  not  work  with
                  ETRN or ODMR.

       Authentication Options
           -u <name> | --username <name>
                  (Keyword:  user[name]) Specifies the user identifi
                  cation  to  be  used  when  logging   in   to   the
                  mailserver.  The appropriate user identification is
                  both server and  user-dependent.   The  default  is
                  your  login name on the client machine that is run
                  ning fetchmail.  See USER AUTHENTICATION below  for
                  a complete description.

           -I <specification> | --interface <specification>
                  (Keyword: interface) Require that a specific inter
                  face device be up and  have  a  specific  local  or
                  remote  IP address (or range) before polling.  Fre
                  quently fetchmail is used over a  transient  point-
                  to-point  TCP/IP  link  established  directly  to a
                  mailserver via SLIP or PPP.  That is  a  relatively
                  secure  channel.   But  when other TCP/IP routes to
                  the mailserver exist (e.g. when the  link  is  con
                  nected  to  an  alternate  ISP),  your username and
                  password may be vulnerable to snooping  (especially
                  when  daemon  mode  automatically  polls  for mail,
                  shipping a clear password  over  the  net  at  pre
                  dictable intervals).  The --interface option may be
                  used to prevent this.  When the specified  link  is
                  not  up  or  is  not  connected  to  a  matching IP
                  address, polling will be skipped.  The format is:

                       interface/iii.iii.iii.iii/mmm.mmm.mmm.mmm

                  links which are automatically taken  down  after  a
                  period  of inactivity (e.g. PPP links) to remain up
                  indefinitely.   This  option  identifies  a  system
                  TCP/IP  interface  to  be  monitored  for activity.
                  After each poll interval, if the link is up but  no
                  other  activity  has occurred on the link, then the
                  poll will be skipped.  However, when  fetchmail  is
                  woken  up by a signal, the monitor check is skipped
                  and the poll goes  through  unconditionally.   This
                  option  is currently only supported under Linux and
                  FreeBSD.  For the monitor and interface options  to
                  work  for  non root users under FreeBSD, the fetch
                  mail binary must be installed SGID kmem. This would
                  be  a  security  hole,  but fetchmail runs with the
                  effective GID set to that of the  kmem  group  only
                  when interface data is being collected.

           --auth <type>
                  (Keyword:  auth[enticate])  This option permits you
                  to specify an authentication type (see USER AUTHEN
                  TICATION  below  for details).  The possible values
                  are any, `password', `kerberos_v5'  and  `kerberos'
                  (or,  for  excruciating  exactness, `kerberos_v4'),
                  gssapi, cram-md5, otp, ntlm,  and  ssh.   When  any
                  (the  default)  is specified, fetchmail tries first
                  methods that don't require a password (GSSAPI, KER
                  BEROS_IV); then it looks for methods that mask your
                  password (CRAM-MD5, X-OTP, NTLM); and only  if  the
                  server  doesn't  support  any of those will it ship
                  your password en clair.  Other values may  be  used
                  to  force  various authentication methods (ssh sup
                  presses  authentication).   Any  value  other  than
                  password,  cram-md5,  ntlm or otp suppresses fetch
                  mail's normal inquiry for a password.  Specify  ssh
                  when  you are using an end-to-end secure connection
                  such as an  ssh  tunnel;  specify  gssapi  or  ker
                  beros_v4  if  you are using a protocol variant that
                  employs GSSAPI or K4.  Choosing KPOP protocol auto
                  matically  selects  Kerberos  authentication.  This
                  option does not work with ETRN.

       Miscellaneous Options
           -f <pathname> | --fetchmailrc <pathname>
                  Specify a non-default name for  the  ~/.fetchmailrc
                  run  control  file.   The pathname argument must be
                  either "-" (a single dash, meaning to read the con
                  figuration  from  standard  input)  or  a filename.
                  Unless the --version option is  also  on,  a  named
                  file  argument  must  have permissions no more open
                  than 0600 (u=rw,g=,o=) or else be /dev/null.

           -i <pathname> | --idfile <pathname>
                  paranoid  about having an MTA edit mail headers and
                  want to know they can prevent it, but it is  gener
                  ally not a good idea to actually turn off rewrite.)
                  When using ETRN or  ODMR,  the  rewrite  option  is
                  ineffective.

           -E <line> | --envelope <line>
                  (Keyword:  envelope) This option changes the header
                  fetchmail assumes will carry a copy of  the  mail's
                  envelope address.  Normally this is `X-Envelope-To'
                  but  as  this  header  is  not  standard,  practice
                  varies.  See  the  discussion  of multidrop address
                  handling  below.   As  a  special  case,  `envelope
                  "Received"'   enables   parsing  of  sendmail-style
                  Received lines.  This is the default, and it should
                  not  be necessary unless you have globally disabled
                  Received parsing with `no envelope' in the  .fetch
                  mailrc file.

           -Q <prefix> | --qvirtual <prefix>
                  (Keyword:  qvirtual)  The string prefix assigned to
                  this option will be  removed  from  the  user  name
                  found  in  the  header  specified with the envelope
                  option (before  doing  multidrop  name  mapping  or
                  localdomain  checking,  if  either  is applicable).
                  This option is useful if you are using fetchmail to
                  collect  the mail for an entire domain and your ISP
                  (or your mail redirection provider) is using qmail.
                  One of the basic features of qmail is the

                  `Delivered-To:'

                  message  header.  Whenever qmail delivers a message
                  to a local mailbox it puts the username  and  host
                  name  of  the envelope recipient on this line.  The
                  major reason for this is to prevent mail loops.  To
                  set  up qmail to batch mail for a disconnected site
                  the ISP-mailhost will have normally put  that  site
                  in its `Virtualhosts' control file so it will add a
                  prefix to all mail addresses for  this  site.  This
                  results  in  mail  sent to 'username@userhost.user
                  dom.dom.com' having a `Delivered-To:' line  of  the
                  form:

                  Delivered-To:  mbox-userstr-username@userhost.user
                  dom.dom.com

                  The ISP can make the  'mbox-userstr-'  prefix  any
                  thing  they  choose  but a string matching the user
                  host name is likely.  By using the option `envelope
                  Delivered-To:'  you  can  make  fetchmail  reliably
                  identify the original envelope recipient,  but  you

## USER AUTHENTICATION AND ENCRYPTION

           All modes except ETRN require authentication of the client
           to the server.  Normal user authentication in fetchmail is
           very  much  like  the  authentication mechanism of ftp(1).
           The correct user-id and password depend upon the  underly
           ing security system at the mailserver.

           If  the  mailserver is a Unix machine on which you have an
           ordinary user account, your regular login name  and  pass
           word  are  used with fetchmail.  If you use the same login
           name on both the  server  and  the  client  machines,  you
           needn't  worry  about  specifying  a  user-id  with the -u
           option -- the default behavior is to use your  login  name
           on  the  client  machine  as  the  user-id  on  the server
           machine.  If you use a different login name on the  server
           machine, specify that login name with the -u option.  e.g.
           if your login name is 'jsmith' on a machine  named  'mail
           grunt', you would start fetchmail as follows:

                  fetchmail -u jsmith mailgrunt

           The  default  behavior  of  fetchmail is to prompt you for
           your mailserver password before the connection  is  estab
           lished.   This  is  the  safest  way  to use fetchmail and
           ensures that your password will not be  compromised.   You
           may  also  specify  your  password  in your ~/.fetchmailrc
           file.  This is convenient when using fetchmail  in  daemon
           mode or with scripts.

           If  you  do  not  specify a password, and fetchmail cannot
           extract one from your ~/.fetchmailrc file,  it  will  look
           for a ~/.netrc file in your home directory before request
           ing one interactively; if an entry matching the mailserver
           is  found in that file, the password will be used.  Fetch
           mail first looks for a match on poll  name;  if  it  finds
           none,  it  checks for a match on via name.  See the ftp(1)
           man page for details of the syntax of the  ~/.netrc  file.
           (This  feature may allow you to avoid duplicating password
           information in more than one file.)

           On mailservers that do not provide ordinary user accounts,
           your  user-id  and  password  are  usually assigned by the
           server administrator when you apply for a mailbox  on  the
           server.   Contact  your  server administrator if you don't
           know the correct user-id and  password  for  your  mailbox
           account.

           Early  versions  of  POP3  (RFC1081,  RFC1225) supported a
           crude form of independent authentication using the  rhosts
           file  on  the mailserver side.  Under this RPOP variant, a
           fixed per-user ID equivalent to a  password  was  sent  in
           clear  over  a  link  to a reserved port, with the command
           it by checking its authorization database.

           If your fetchmail was built with Kerberos support and  you
           specify Kerberos authentication (either with --auth or the
           .fetchmailrc option authenticate kerberos_v4) it will  try
           to  get a Kerberos ticket from the mailserver at the start
           of each query.  Note: if either the pollnane or  via  name
           is  `hesiod',  fetchmail will try to use Hesiod to look up
           the mailserver.

           If you use POP3 or IMAP with GSSAPI authentication, fetch
           mail   will   expect   the  server  to  have  RFC1731-  or
           RFC1734-conformant GSSAPI capability,  and  will  use  it.
           Currently  this  has  only been tested over Kerberos V, so
           you're expected to already have a ticket-granting  ticket.
           You may pass a username different from your principal name
           using the standard --user command or by  the  .fetchmailrc
           option user.

           If  your  IMAP  daemon returns the PREAUTH response in its
           greeting line, fetchmail will notice  this  and  skip  the
           normal  authentication  step.  This can be useful, e.g. if
           you start imapd explicitly using ssh.  In  this  case  you
           can  declare  the  authentication value `ssh' on that site
           entry to stop .fetchmail from asking you  for  a  password
           when it starts up.

           If  you  are using POP3, and the server issues a one-time-
           password challenge conforming to RFC1938,  fetchmail  will
           use  your  password  as  a  pass  phrase  to  generate the
           required response. This avoids sending  secrets  over  the
           net unencrypted.

           Compuserve's  RPA authentication (similar to APOP) is sup
           ported. If you compile in the support, fetchmail will  try
           to  perform  an  RPA pass-phrase authentication instead of
           sending over the password en clair if  it  detects  "@com
           puserve.com" in the hostname.

           If  you  are  using  IMAP, Microsoft's NTLM authentication
           (used by Microsoft Exchange) is supported. If you  compile
           in  the  support,  fetchmail  will  try to perform an NTLM
           authentication (instead of sending over  the  password  en
           clair)  whenever the server returns AUTH=NTLM in its capa
           bility response. Specify a user option  value  that  looks
           like  `user@domain': the part to the left of the @ will be
           passed as the username and the part to the  right  as  the
           NTLM domain.

           If  you  are  using IPsec, the -T (--netsec) option can be
           used to pass an IP security request to be used when outgo
           ing  IP connections are initialized.  You can also do this

           When  connecting  to  an  SSL encrypted server, the server
           presents a certificate to the client for validation.   The
           certificate  is  checked to verify that the common name in
           the certificate matches the name of the server being  con
           tacted  and that the effective and expiration dates in the
           certificate indicate that it is currently valid.   If  any
           of  these  checks  fail, a warning message is printed, but
           the connection continues.  The server certificate does not
           need to be signed by any specific Certifying Authority and
           may be a "self-signed" certificate.

           Some SSL encrypted servers may request a client side  cer
           tificate.   A  client side public SSL certificate and pri
           vate SSL key  may  be  specified.   If  requested  by  the
           server,  the  client certificate is sent to the server for
           validation.  Some servers may require a valid client  cer
           tificate  and  may  refuse connections if a certificate is
           not provided or if the certificate  is  not  valid.   Some
           servers  may require client side certificates be signed by
           a recognized Certifying Authority.  The format for the key
           files  and  the  certificate files is that required by the
           underlying SSL libraries (OpenSSL in the general case).

           A word of care about the use of SSL: While above mentioned
           setup  with self-signed server certificates retrieved over
           the wires can protect you from a passive  eavesdropper  it
           doesn't  help  against an active attacker. It's clearly an
           improvement over sending the passwords in  clear  but  you
           should  be  aware that a man-in-the-middle attack is triv
           ially possible (in particular with tools such  as  dsniff,
           http://www.monkey.org/~dugsong/dsniff/).   Use  of  an ssh
           tunnel (see below for some examples) is preferable if  you
           care seriously about the security of your mailbox.

           fetchmail also supports authentication to the ESMTP server
           on the client side according to RFC 2554.  You can specify
           a  name/password pair to be used with the keywords `esmtp
           name' and `esmtppassword';  the  former  defaults  to  the
           username of the calling user.

## DAEMON MODE

           The  --daemon  <interval>  or  -d  <interval>  option runs
           fetchmail in daemon mode.   You  must  specify  a  numeric
           argument which is a polling interval in seconds.

           In  daemon  mode,  fetchmail puts itself in background and
           runs forever, querying each specified host and then sleep
           ing for the given polling interval.

           Simply invoking
           Only one daemon process is permitted per user;  in  daemon
           mode,  fetchmail  makes  a  per-user lockfile to guarantee
           this.

           Normally, calling fetchmail with a  daemon  in  the  back
           ground  sends a wakeup signal to the daemon, forcing it to
           poll  mailservers  immediately.   (The  wakeup  signal  is
           SIGHUP  if  fetchmail  is  running as root, SIGUSR1 other
           wise.)  The wakeup action also clears any  `wedged'  flags
           indicating  that  connections  have  wedged  due to failed
           authentication or multiple timeouts.

           The option --quit  will  kill  a  running  daemon  process
           instead  of  waking  it  up  (if there is no such process,
           fetchmail notifies you).  If the --quit option is the only
           command-line option, that's all there is to it.

           The  quit option may also be mixed with other command-line
           options; its effect is to kill any running  daemon  before
           doing  what  the other options specify in combination with
           the rc file.

           The -L <filename> or --logfile <filename> option (keyword:
           set  logfile) allows you to redirect status messages emit
           ted while detached into a specified  logfile  (follow  the
           option  with the logfile name).  The logfile is opened for
           append, so previous messages aren't deleted.  This is pri
           marily useful for debugging configurations.

           The  --syslog  option  (keyword: set syslog) allows you to
           redirect status and error messages  emitted  to  the  sys
           log(3)  system  daemon  if available.  Messages are logged
           with an id of fetchmail, the facility LOG_MAIL, and prior
           ities  LOG_ERR,  LOG_ALERT  or  LOG_INFO.   This option is
           intended for logging status and error messages which indi
           cate the status of the daemon and the results while fetch
           ing mail from the server(s).  Error messages  for  command
           line  options  and parsing the .fetchmailrc file are still
           written to stderr, or to  the  specified  log  file.   The
           --nosyslog  option  turns  off  use of syslog(3), assuming
           it's turned on in the ~/.fetchmailrc file, or that the  -L
           or --logfile <file> option was used.

           The  -N  or --nodetach option suppresses backgrounding and
           detachment of the daemon process from its  control  termi
           nal.   This  is primarily useful for debugging.  Note that
           this also causes the logfile option to be ignored  (though
           perhaps it shouldn't).

           Note  that  while running in daemon mode polling a POP2 or
           IMAP2bis server, transient errors (such as DNS failures or
           sendmail  delivery refusals) may force the fetchall option
           break the ~/.fetchmailrc file's syntax, the  new  instance
           will softly and silently vanish away on startup.

## ADMINISTRATIVE OPTIONS

           The  --postmaster  <name> option (keyword: set postmaster)
           specifies the last-resort username to which multidrop mail
           is  to  be forwarded if no matching local recipient can be
           found.  Normally this is just the user who invoked  fetch
           mail.   If  the invoking user is root, then the default of
           this option is the user `postmaster'.  Setting  postmaster
           to the empty string causes such mail to be discarded.

           The  --nobounce  option  suppresses  the  normal action of
           bouncing errors back to the sender in  an  RFC1894-confor
           mant  error  message.  If nobounce is on, the message will
           go to the postmaster instead.

           The --invisible option (keyword: set invisible)  tries  to
           make  fetchmail  invisible.   Normally,  fetchmail behaves
           like any other MTA would -- it generates a Received header
           into  each  message  describing  its place in the chain of
           transmission, and tells the MTA it forwards  to  that  the
           mail came from the machine fetchmail itself is running on.
           If the invisible option is on, the Received header is sup
           pressed  and  fetchmail tries to spoof the MTA it forwards
           to into thinking it  came  directly  from  the  mailserver
           host.

           The  --showdots  option  (keyword:  set  showdots)  forces
           fetchmail to show progress dots even if the current tty is
           not  stdout  (for example logfiles).  Starting with fetch
           mail version 5.3.0, progress dots are only shown on stdout
           by default.

           By  specifying the --tracepolls option, you can ask fetch
           mail to add information to the Received header on the form
           "polling  {label}  account  {user}",  where {label} is the
           account  label  (from  the  specified   rcfile,   normally
           ~/.fetchmailrc)  and  {user} is the username which is used
           to log on to the mail server. This header can be  used  to
           make filtering email where no useful header information is
           available and you want mail from different accounts sorted
           into  different  mailboxes (this could, for example, occur
           if you have an account on the same server running a  mail
           ing  list,  and  are  subscribed  to  the  list using that
           account). The default is not adding any such  header.   In
           .fetchmailrc, this is called `tracepolls'.

## RETRIEVAL FAILURE MODES

           The  protocols  fetchmail  uses to talk to mailservers are
           ment and can be used with the mda option with no  risk  of
           mail  loss.   Unsafe  MDAs,  though,  may return 0 even on
           delivery failure.  If this happens, you will lose mail.

           The normal mode of fetchmail is to try  to  download  only
           `new' messages, leaving untouched (and undeleted) messages
           you have already read directly on the server  (or  fetched
           with  a previous fetchmail --keep).  But you may find that
           messages you've already  read  on  the  server  are  being
           fetched  (and  deleted) even when you don't specify --all.
           There are several reasons this can happen.

           One could be that you're using POP2.   The  POP2  protocol
           includes no representation of `new' or `old' state in mes
           sages, so fetchmail must treat all messages as new all the
           time.  But POP2 is obsolete, so this is unlikely.

           Under  POP3, blame RFC1725.  That version of the POP3 pro
           tocol specification removed the LAST command, and some POP
           servers  follow it (you can verify this by invoking fetch
           mail -v to the mailserver and  watching  the  response  to
           LAST  early  in  the  query).  The fetchmail code tries to
           compensate by using POP3's UID feature, storing the  iden
           tifiers  of  messages  seen in each session until the next
           session, in the .fetchids file.  But  this  doesn't  track
           messages  seen with other clients, or read directly with a
           mailer on the host but not deleted  afterward.   A  better
           solution would be to switch to IMAP.

           Another  potential  POP3  problem  might  be  servers that
           insert messages in  the  middle  of  mailboxes  (some  VMS
           implementations  of  mail  are  rumored  to do this).  The
           fetchmail code assumes that new messages are  appended  to
           the end of the mailbox; when this is not true it may treat
           some old messages as new and vice versa.   The  only  real
           fix for this problem is to  switch to IMAP.

           Yet  another POP3 problem is that if they can't make temp
           files in the user's home directory, some POP3 servers will
           hand  back  an undocumented response that causes fetchmail
           to spuriously report "No mail".

           The IMAP code uses the presence or absence of  the  server
           flag  \Seen  to  decide  whether  or not a message is new.
           Under Unix, it counts on your IMAP server  to  notice  the
           BSD-style Status flags set by mail user agents and set the
           \Seen flag from them  when  appropriate.   All  Unix  IMAP
           servers  we  know of do this, though it's not specified by
           the IMAP RFCs.  If  you  ever  trip  over  a  server  that
           doesn't,  the  symptom  will  be  that  messages  you have
           already read on your host will look new to the server.  In
           this  (unlikely)  case,  only  messages  you  fetched with

           Newer  versions  of  sendmail return an error code of 571.
           This return value is blessed by RFC1893 as  "Delivery  not
           authorized, message refused".

           According  to RFC2821, the correct thing to return in this
           situation is 550  "Requested  action  not  taken:  mailbox
           unavailable" (the draft adds "[E.g., mailbox not found, no
           access, or command rejected for policy reasons].").

           Older versions of the exim MTA return 501 "Syntax error in
           parameters or arguments".

           The postfix MTA runs 554 as an antispam response.

           Zmailer  may  reject code with a 500 response (followed by
           an enhanced status code that contains more information).

           Return codes which fetchmail treats as antispam  responses
           and  discards  the  message can be set with the `antispam'
           option.  This is one of the only three circumstance  under
           which fetchmail ever discards mail (the others are the 552
           and 553 errors described below,  and  the  suppression  of
           multidropped messages with a message-ID already seen).

           If fetchmail is fetching from an IMAP server, the antispam
           response will be detected and the message rejected immedi
           ately after the headers have been fetched, without reading
           the message body.  Thus, you  won't  pay  for  downloading
           spam message bodies.

           By default, the list of antispam responses is empty.

           If  the spambounce option is on, mail that is spam-blocked
           triggers an RFC1892 bounce message informing the  origina
           tor that we do not accept mail from it.

## SMTP/ESMTP ERROR HANDLING

           Besides the spam-blocking described above, fetchmail takes
           special  actions  on  the   following   SMTP/ESMTP   error
           responses

           452 (insufficient system storage)
                Leave  the  message  in  the server mailbox for later
                retrieval.

           552 (message exceeds fixed maximum message size)
                Delete the message from the server.  Send bounce-mail
                to the originator.

           553 (invalid sending domain)
           To  protect the security of your passwords, when --version
           is not on your ~/.fetchmailrc may not have more than  0600
           (u=rw,g=,o=) permissions; fetchmail will complain and exit
           otherwise.

           You may read the .fetchmailrc file as a list  of  commands
           to be executed when fetchmail is called with no arguments.

       Run Control Syntax
           Comments begin with a '#' and extend through  the  end  of
           the  line.   Otherwise  the  file  consists of a series of
           server entries or global option statements in a  free-for
           mat, token-oriented syntax.

           There  are four kinds of tokens: grammar keywords, numbers
           (i.e. decimal  digit  sequences),  unquoted  strings,  and
           quoted  strings.   A  quoted  string  is bounded by double
           quotes and may contain whitespace (and quoted  digits  are
           treated  as  a string).  An unquoted string is any whites
           pace-delimited  token  that  is  neither  numeric,  string
           quoted  nor contains the special characters `,', `;', `:',
           or `='.

           Any  amount  of  whitespace  separates  tokens  in  server
           entries, but is otherwise ignored. You may use standard C-
           style escapes (\n, \t, \b, octal, and hex) to  embed  non-
           printable characters or string delimiters in strings.

           Each  server  entry consists of one of the keywords `poll'
           or `skip', followed by a server name, followed  by  server
           options,  followed  by  any  number  of user descriptions.
           Note: the most common cause of syntax errors is mixing  up
           user and server options.

           For backward compatibility, the word `server' is a synonym
           for `poll'.

           You can use  the  noise  keywords  `and',  `with',  `has',
           `wants',  and  `options'  anywhere  in an entry to make it
           resemble English.   They're  ignored,  but  but  can  make
           entries  much easier to read at a glance.  The punctuation
           characters ':', ';' and ',' are also ignored.

       Poll vs. Skip
           The `poll' verb tells fetchmail to query this host when it
           is run with no arguments.  The `skip' verb tells fetchmail
           not to poll this host unless it is explicitly named on the
           command  line.   (The `skip' verb allows you to experiment
           with test entries safely, or easily  disable  entries  for
           hosts that are temporarily down.)

                                     mail recipient
           set no bouncemail         Direct error  mail  to  postmaster
                                     rather than sender
           set no spambounce         Send spam bounces
           set logfile               Name  of  a file to dump error and
                                     status messages to
           set idfile                Name of  the  file  to  store  UID
                                     lists in
           set syslog                Do   error  logging  through  sys
                                     log(3).
           set nosyslog              Turn  off  error  logging  through
                                     syslog(3).
           set properties            String  value is ignored by fetch
                                     mail (may  be  used  by  extension
                                     scripts)

           Here are the legal server options:

           Keyword            Opt   Function
           ------------------------------------------------------------
           via                      Specify  DNS  name  of mailserver,
                                    overriding poll name
           proto[col]         -p    Specify  protocol  (case  insensi
                                    tive):  POP2,  POP3,  IMAP,  APOP,
                                    KPOP
           local[domains]           Specify domain(s) to  be  regarded
                                    as local
           port               -P    Specify TCP/IP service port
           auth[enticate]           Set  authentication  type (default
                                    `any')
           timeout            -t    Server inactivity timeout in  sec
                                    onds (default 300)
           envelope           -E    Specify   envelope-address  header
                                    name
           no envelope              Disable   looking   for   envelope
                                    address
           qvirtual           -Q    Qmail  virtual  domain  prefix  to
                                    remove from user name
           aka                      Specify  alternate  DNS  names  of
                                    mailserver
           interface          -I    specify  IP interface(s) that must
                                    be up  for  server  poll  to  take
                                    place
           monitor            -M    Specify  IP address to monitor for
                                    activity
           plugin                   Specify command through  which  to
                                    make server connections.
           plugout                  Specify  command  through which to
                                    make listener connections.
           dns                      Enable DNS  lookup  for  multidrop
                                    (default)
           no dns                   Disable DNS lookup for multidrop
                                    ful with imap and kerberos)
           esmtpname                Set name for  RFC2554  authentica
                                    tion to the ESMTP server.
           esmtppassword            Set password for RFC2554 authenti
                                    cation to the ESMTP server.

           Here are the legal user options:

           Keyword            Opt   Function
           ------------------------------------------------------------
           user[name]         -u    Set remote user name  (local  user
                                    name if name followed by `here')
           is                       Connect   local  and  remote  user
                                    names
           to                       Connect  local  and  remote   user
                                    names
           pass[word]               Specify remote account password
           ssl                      Connect  to server over the speci
                                    fied  base  protocol   using   SSL
                                    encryption
           sslcert                  Specify  file for client side pub
                                    lic SSL certificate
           sslkey                   Specify file for client side  pri
                                    vate SSL key
           sslproto                 Force ssl protocol for connection
           folder             -r    Specify remote folder to query
           smtphost           -S    Specify smtp host(s) to forward to
           fetchdomains             Specify  domains  for  which  mail
                                    should be fetched
           smtpaddress        -D    Specify  the  domain  to be put in
                                    RCPT TO lines
           smtpname                 Specify the user and domain to  be
                                    put in RCPT TO lines
           antispam           -Z    Specify   what  SMTP  returns  are
                                    interpreted as spam-policy blocks
           mda                -m    Specify MDA for local delivery
           bsmtp              -o    Specify BSMTP batch file to append
                                    to
           preconnect               Command to be executed before each
                                    connection
           postconnect              Command to be executed after  each
                                    connection
           keep               -k    Don't  delete  seen  messages from
                                    server
           flush              -F    Flush  all  seen  messages  before
                                    querying
           fetchall           -a    Fetch all messages whether seen or
                                    not
           rewrite                  Rewrite destination addresses  for
                                    reply (default)
           stripcr                  Strip  carriage  returns from ends
                                    of lines
                                    (default)
           no flush                 Don't   flush  all  seen  messages
                                    before querying (default)
           no fetchall              Retrieve   only    new    messages
                                    (default)
           no rewrite               Don't rewrite headers
           no stripcr               Don't   strip   carriage   returns
                                    (default)
           no forcecr               Don't force  carriage  returns  at
                                    EOL (default)
           no pass8bits             Don't force BODY=8BITMIME to ESMTP
                                    listener (default)
           no dropstatus            Don't    drop    Status    headers
                                    (default)
           no dropdelivered         Don't  drop  Delivered-To  headers
                                    (default)
           no mimedecode            Don't convert quoted-printable  to
                                    8-bit in MIME messages (default)
           no idle                  Don't  idle  waiting  for new mes
                                    sages after each poll (IMAP only)
           limit              -l    Set message size limit
           warnings           -w    Set message size warning interval
           batchlimit         -b    Max # messages to forward in  sin
                                    gle connect
           fetchlimit         -B    Max  # messages to fetch in single
                                    connect
           expunge            -e    Perform an expunge  on  every  #th
                                    message (IMAP and POP3 only)
           tracepolls               Add  poll  tracing  information to
                                    the Received header
           properties               String value is ignored by  fetch
                                    mail  (may  be  used  by extension
                                    scripts)

           Remember that all user  options  must  follow  all  server
           options.

           In  the  .fetchmailrc file, the `envelope' string argument
           may be preceded by a  whitespace-separated  number.   This
           number,  if  specified,  is  the number of such headers to
           skip (that is, an argument of 1 selects the second  header
           of  the given type).  This is sometime useful for ignoring
           bogus Received headers created by an ISP's local  delivery
           agent.

       Keywords Not Corresponding To Option Switches
           The `folder' and `smtphost' options (unlike their command-
           line equivalents) can take  a  space-  or  comma-separated
           list of names following them.

           All  options  correspond to the obvious command-line argu
           ments, except the  following:  `via',  `interval',  `aka',

           The `interval' option (which  takes  a  numeric  argument)
           allows you to poll a server less frequently than the basic
           poll interval.  If you say `interval N'  the  server  this
           option  is  attached  to will only be queried every N poll
           intervals.

           The `is' or `to' keywords associate  the  following  local
           (client)  name(s)  (or server-name to client-name mappings
           separated by =) with  the  mailserver  user  name  in  the
           entry.   If an is/to list has `*' as its last name, unrec
           ognized names are simply passed through.

           A single local name can be  used  to  support  redirecting
           your mail when your username on the client machine is dif
           ferent from your name on the mailserver.   When  there  is
           only  a single local name, mail is forwarded to that local
           username regardless of the message's Received, To, Cc, and
           Bcc  headers.   In  this  case  fetchmail  never  does DNS
           lookups.

           When there is more than one local name (or  name  mapping)
           the  fetchmail code does look at the Received, To, Cc, and
           Bcc headers of retrieved mail (this is `multidrop  mode').
           It looks for addresses with hostname parts that match your
           poll name or your `via', `aka' or `localdomains'  options,
           and usually also for hostname parts which DNS tells it are
           aliases of the mailserver.  See the discussion  of  `dns',
           `checkalias', `localdomains', and `aka' for details on how
           matching addresses are handled.

           If fetchmail cannot  match  any  mailserver  usernames  or
           localdomain addresses, the mail will be bounced.  Normally
           it will be bounced to the sender, but if `nobounce' is  on
           it  will  go  to the postmaster (which in turn defaults to
           being the calling user).

           The `dns' option (normally on) controls the way  addresses
           from  multidrop  mailboxes  are  checked.   On, it enables
           logic to check each host address  that  doesn't  match  an
           `aka'  or `localdomains' declaration by looking it up with
           DNS.  When a mailserver username is recognized attached to
           a  matching  hostname  part, its local mapping is added to
           the list of local recipients.

           The `checkalias' option (normally off) extends the lookups
           performed  by the `dns' keyword in multidrop mode, provid
           ing a way to cope with remote  MTAs  that  identify  them
           selves  using  their  canonical name, while they're polled
           using an alias.  When such a server is polled,  checks  to
           extract  the  envelope address fail, and fetchmail reverts
           to delivery using the To/Cc/Bcc headers (See below `Header
           for names of the mailserver, pre-declaring common ones can
           save it from having to do DNS lookups.   Note:  the  names
           you  give as arguments to `aka' are matched as suffixes --
           if you specify (say) `aka netaxs.com', this will match not
           just  a  hostnamed  netaxs.com, but any hostname that ends
           with `.netaxs.com';  such  as  (say)  pop3.netaxs.com  and
           mail.netaxs.com.

           The  `localdomains' option allows you to declare a list of
           domains  which  fetchmail  should  consider  local.   When
           fetchmail is parsing address lines in multidrop modes, and
           a trailing segment of a host name matches a declared local
           domain,  that address is passed through to the listener or
           MDA unaltered (local-name mappings are not applied).

           If you are using `localdomains',  you  may  also  need  to
           specify  `no  envelope', which disables fetchmail's normal
           attempt to deduce an envelope address  from  the  Received
           line  or  X-Envelope-To header or whatever header has been
           previously set by `envelope'.  If you set `no envelope' in
           the defaults entry it is possible to undo that in individ
           ual entries by using `envelope <string>'.   As  a  special
           case,  `envelope  "Received"' restores the default parsing
           of Received lines.

           The password option requires a string argument,  which  is
           the password to be used with the entry's server.

           The  `preconnect'  keyword  allows  you to specify a shell
           command to be executed just  before  each  time  fetchmail
           establishes  a  mailserver connection.  This may be useful
           if you are attempting to set  up  secure  POP  connections
           with  the aid of ssh(1).  If the command returns a nonzero
           status, the poll of that mailserver will be aborted.

           Similarly, the `postconnect' keyword similarly allows  you
           to  specify a shell command to be executed just after each
           time a mailserver connection is taken down.

           The `forcecr' option controls whether lines terminated  by
           LF  only  are  given  CRLF  termination before forwarding.
           Strictly speaking  RFC821  requires  this,  but  few  MTAs
           enforce  the requirement it so this option is normally off
           (only one such MTA, qmail, is in significant use  at  time
           of writing).

           The `stripcr' option controls whether carriage returns are
           stripped out of retrieved mail before it is forwarded.  It
           is normally not necessary to set this, because it defaults
           to `on' (CR  stripping  enabled)  when  there  is  an  MDA
           declared but `off' (CR stripping disabled) when forwarding
           is via SMTP.  If `stripcr'  and  `forcecr'  are  both  on,
           The  `dropstatus'  option controls whether nonempty Status
           and X-Mozilla-Status lines are retained  in  fetched  mail
           (the  default)  or  discarded.  Retaining them allows your
           MUA to see what messages (if any) were marked seen on  the
           server.   On  the other hand, it can confuse some new-mail
           notifiers, which assume that anything with a  Status  line
           in  it  has  been  seen.   (Note:  the  empty Status lines
           inserted by some buggy  POP  servers  are  unconditionally
           discarded.)

           The  `dropdelivered'  option  controls wether Delivered-To
           headers will be kept in fetched mail (the default) or dis
           carded.  These  headers  are  added  by  Qmail and Postfix
           mailservers in order to avoid mail loops but  may  get  in
           your  way  if  you try to "mirror" a mailserver within the
           same domain. Use with caution.

           The `mimedecode' option  controls  whether  MIME  messages
           using the quoted-printable encoding are automatically con
           verted into pure 8-bit data. If you are delivering mail to
           an  ESMTP-capable, 8-bit-clean listener (that includes all
           of the major MTAs like sendmail), then this will automati
           cally  convert  quoted-printable  message headers and data
           into 8-bit data, making it easier to understand when read
           ing  mail.  If  your e-mail programs know how to deal with
           MIME messages,  then  this  option  is  not  needed.   The
           mimedecode option is off by default, because doing RFC2047
           conversion on headers throws away  character-set  informa
           tion  and  can  lead to bad results if the encoding of the
           headers differs from the body encoding.

           The `idle' option is usable only with  IMAP  servers  sup
           porting  the  RFC2177  IDLE  command  extension.  If it is
           enabled, and fetchmail detects that IDLE is supported,  an
           IDLE  will  be  issued at the end of each poll.  This will
           tell the IMAP server  to  hold  the  connection  open  and
           notify the client when new mail is available.  If you need
           to poll a link frequently,  IDLE  can  save  bandwidth  by
           eliminating TCP/IP connects and LOGIN/LOGOUT sequences. On
           the other hand, an IDLE connection will eat almost all  of
           your fetchmail's time, because it will never drop the con
           nection and allow other pools to occur unless  the  server
           times  out  the  IDLE.  It also doesn't work with multiple
           folders; only the first folder will ever be polled.

           The `properties' option is  an  extension  mechanism.   It
           takes  a  string  argument,  which is ignored by fetchmail
           itself.  The string argument may be used to store configu
           ration  information for scripts which require it.  In par
           ticular, the output of  `--configdump'  option  will  make
           properties  associated with a user entry readily available
           to a Python script.
               pop2 (or POP2)
               pop3 (or POP3)
               sdps (or SDPS)
               imap (or IMAP)
               apop (or APOP)
               kpop (or KPOP)

           Legal authentication types are  `any',  `password',  `ker
           beros',  'kereberos_v5'  and  `gssapi', `cram-md5', `otp',
           `ntlm', `ssh`.  The `password' type specifies  authentica
           tion  by  normal  transmission of a password (the password
           may be plaintext or subject to  protocol-specific  encryp
           tion as in APOP); `kerberos' tells fetchmail to try to get
           a Kerberos ticket at the start of each query instead,  and
           send  an  arbitrary  string  as the password; and `gssapi'
           tells fetchmail to use  GSSAPI  authentication.   See  the
           description of the `auth' keyword for more.

           Specifying  `kpop'  sets POP3 protocol over port 1109 with
           Kerberos V4 authentication.  These defaults may  be  over
           ridden by later options.

           There  are  currently  four global option statements; `set
           logfile' followed by a string sets the same global  speci
           fied  by  --logfile.  A command-line --logfile option will
           override this.  Also, `set daemon' sets the poll  interval
           as  --daemon  does.   This can be overridden by a command-
           line --daemon option; in particular --daemon 0 can be used
           to force foreground operation. The `set postmaster' state
           ment sets the address to which multidrop mail defaults  if
           there  are  no local matches.  Finally, `set syslog' sends
           log messages to syslogd(8).

## INTERACTION WITH RFC 822

           When trying to determine the originating address of a mes
           sage,  fetchmail  looks  through  headers in the following
           order:

                   Return-Path:
                   Resent-Sender: (ignored if it doesn't contain an @ or !)
                   Sender: (ignored if it doesn't contain an @ or !)
                   Resent-From:
                   From:
                   Reply-To:
                   Apparently-From:

           The originating address is used for logging,  and  to  set
           the MAIL FROM address when forwarding to SMTP.  This order
           is intended to cope gracefully with receiving mailing list
           messages  in multidrop mode. The intent is that if a local
           the  final  recipients  and  have  precedence  over  their
           To:/Cc:/Bcc:  counterparts.  If the Resent-* lines doesn't
           exist, the To:, Cc:, Bcc:  and  Apparently-To:  lines  are
           looked  for.  (The  presence  of  a Resent-To: is taken to
           imply that the person referred  by  the  To:  address  has
           already received the original copy of the mail).

## CONFIGURATION EXAMPLES

           Note  that  although  there are password declarations in a
           good many of the examples below, this is mainly for illus
           trative  purposes.  We recommend stashing account/password
           pairs in your $HOME/.netrc file, where they  can  be  used
           not just by fetchmail but by ftp(1) and other programs.

           Basic format is:

             poll SERVERNAME protocol PROTOCOL username NAME password PASSWORD

           Example:

             poll pop.provider.net protocol pop3 username "jsmith" password "secret1"

           Or, using some abbreviations:

             poll pop.provider.net proto pop3 user "jsmith" password "secret1"

           Multiple servers may be listed:

             poll pop.provider.net proto pop3 user "jsmith" pass "secret1"
             poll other.provider.net proto pop2 user "John.Smith" pass "My^Hat"

           Here's  a  version  of  those two with more whitespace and
           some noise words:

             poll pop.provider.net proto pop3
                 user "jsmith", with password secret1, is "jsmith" here;
             poll other.provider.net proto pop2:
                 user "John.Smith", with password "My^Hat", is "John.Smith" here;

           This version is much easier to read and doesn't cost  sig
           nificantly  more  (parsing  is  done only once, at startup
           time).

           If you need to include whitespace in a  parameter  string,
           enclose the string in double quotes.  Thus:

             poll mail.provider.net with proto pop3:
                   user "jsmith" there has password "u can't krak this"
                               is jws here and wants mda "/bin/mail"

           (this is only likely to be useful when  running  fetchmail
           in  daemon  mode as root).  The `user' keyword leads off a
           user description, and every user specification in a multi-
           user entry must include it.  Here's an example:

             poll pop.provider.net proto pop3 port 3111
                   user "jsmith" with pass "secret1" is "smith" here
                   user jones with pass "secret2" is "jjones" here keep

           This  associates  the  local  username  `smith'  with  the
           pop.provider.net username `jsmith' and the local  username
           `jjones' with the pop.provider.net username `jones'.  Mail
           for `jones' is kept on the server after download.

           Here's what a simple retrieval configuration for a  multi-
           drop mailbox looks like:

             poll pop.provider.net:
                   user maildrop with pass secret1 to golux 'hurkle'='happy' snark here

           This  says  that  the mailbox of account `maildrop' on the
           server is a multi-drop box, and that messages in it should
           be parsed for the server user names `golux', `hurkle', and
           `snark'.  It further specifies that  `golux'  and  `snark'
           have  the  same  name  on the client as on the server, but
           mail for server  user  `hurkle'  should  be  delivered  to
           client user `happy'.

           Here's an example of another kind of multidrop connection:

             poll pop.provider.net localdomains loonytoons.org toons.org:
                   user maildrop with pass secret1 to * here

           This also says that the mailbox of account  `maildrop'  on
           the  server  is a multi-drop box.  It tells fetchmail that
           any address in the  loonytoons.org  or  toons.org  domains
           (including   subdomain  addresses  like  `joe@daffy.loony
           toons.org') should be passed through  to  the  local  SMTP
           listener  without  modification.  Be careful of mail loops
           if you do this!

           Here's an example configuration using ssh and  the  plugin
           option.   The  queries  are made directly on the stdin and
           stdout of imapd via ssh.  Note that in  this  setup,  IMAP
           authentication can be skipped.

           poll mailhost.net with proto imap:
                   plugin "ssh %h /usr/sbin/imapd" auth ssh;
                           user esr is esr here

## THE USE AND ABUSE OF MULTIDROP MAILBOXES

           toss  several  peoples' mail in a single maildrop box, you
           may have thrown away potentially vital  information  about
           who  each  piece  of  mail  was actually addressed to (the
           `envelope address', as opposed to the header addresses  in
           the RFC822 To/Cc/Bcc headers).  This `envelope address' is
           the address you need in order to reroute mail properly.

           Sometimes fetchmail can deduce the envelope  address.   If
           the  mailserver  MTA  is sendmail and the item of mail had
           just one recipient, the MTA will have written  a  `by/for'
           clause that gives the envelope addressee into its Received
           header. But this doesn't work reliably for other MTAs, nor
           if  there  is more than one recipient.  By default, fetch
           mail looks for envelope addresses in these lines; you  can
           restore  this  default  with  -E  "Received"  or `envelope
           Received'.

           Alternatively, some SMTP  listeners  and/or  mail  servers
           insert  a  header in each message containing a copy of the
           envelope addresses.  This header (when it exists) is often
           `X-Envelope-To'.  Fetchmail's assumption about this can be
           changed with the -E or `envelope' option.  Note that writ
           ing  an  envelope header of this kind exposes the names of
           recipients  (including  blind-copy  recipients)   to   all
           receivers  of  the  messages;  it is therefore regarded by
           some administrators as a security/privacy problem.

           A slight variation of the `X-Envelope-To'  header  is  the
           `Delivered-To'  put  by qmail to avoid mail loops. It will
           probably prefix the user name with a string that  normally
           matches  the  user's domain. To remove this prefix you can
           use the -Q or `qvirtual' option.

           Sometimes, unfortunately, neither of these methods  works.
           When  they  all fail, fetchmail must fall back on the con
           tents of To/Cc/Bcc headers to try to  determine  recipient
           addressees  -- and these are not reliable.  In particular,
           mailing-list software often ships mail with only the  list
           broadcast address in the To header.

           When  fetchmail  cannot deduce a recipient address that is
           local, and the intended recipient address was anyone other
           than  fetchmail's invoking user, mail will get lost.  This
           is what makes the multidrop feature risky.

           A related problem is that when you blind-copy a mail  mes
           sage,  the  Bcc  information  is  carried only as envelope
           address (it's not put in the  headers  fetchmail  can  see
           unless  there is an X-Envelope header).  Thus, blind-copy
           ing to someone who gets mail over a  fetchmail  link  will
           fail  unless  the  the mailserver host routinely writes X-
           Envelope or an equivalent header  into  messages  in  your
           friends'  as  a  local address gets fetched, the list name
           will be appended to the list of recipients your SMTP  lis
           tener  sees.   Therefore  it  will undergo alias expansion
           locally.  Be sure to include  `esr'  in  the  local  alias
           expansion  of  fetchmail-friends, or you'll never see mail
           sent only to the list.  Also be sure  that  your  listener
           has  the "me-too" option set (sendmail's -oXm command-line
           option or OXm declaration) so your name isn't removed from
           alias expansions in messages you send.

           This  trick  is not without its problems, however.  You'll
           begin to  see  this  when  a  message  comes  in  that  is
           addressed  only to a mailing list you do not have declared
           as a local name.  Each such message will  feature  an  `X-
           Fetchmail-Warning'   header  which  is  generated  because
           fetchmail cannot find a valid local name in the  recipient
           addresses.  Such messages default (as was described above)
           to being sent to the local user running fetchmail, but the
           program  has no way to know that that's actually the right
           thing.

       Bad Ways To Abuse Multidrop Mailboxes
           Multidrop mailboxes and fetchmail serving  multiple  users
           in  daemon  mode  do not mix.  The problem, again, is mail
           from mailing lists, which typically does not have an indi
           vidual  recipient  address  on  it.   Unless fetchmail can
           deduce an envelope address, such mail will only go to  the
           account  running  fetchmail (probably root).  Also, blind-
           copied users are very likely never to see  their  mail  at
           all.

           If  you're  tempted  to use fetchmail to retrieve mail for
           multiple users from a single mail drop via  POP  or  IMAP,
           think again (and reread the section on header and envelope
           addresses above).  It would be smarter  to  just  let  the
           mail  sit  in  the  mailserver's queue and use fetchmail's
           ETRN or ODMR modes to trigger SMTP sends periodically  (of
           course,  this  means you have to poll more frequently than
           the mailserver's expiry period).   If  you  can't  arrange
           this, try setting up a UUCP feed.

           If  you  absolutely  must  use multidrop for this purpose,
           make  sure  your  mailserver  writes  an  envelope-address
           header  that  fetchmail  can see.  Otherwise you will lose
           mail and it will come back to haunt you.

       Speeding Up Multidrop Checking
           Normally,  when  multiple  users  are  declared  fetchmail
           extracts recipient addresses as described above and checks
           each host part with DNS to see if it's  an  alias  of  the
           To  facilitate  the  use of fetchmail in shell scripts, an
           exit code is  returned  to  give  an  indication  of  what
           occurred during a given connection.

           The exit codes returned by fetchmail are as follows:

           0      One  or  more  messages were successfully retrieved
                  (or, if the -c  option  was  selected,  were  found
                  waiting but not retrieved).

           1      There  was  no mail awaiting retrieval.  (There may
                  have been old mail still  on  the  server  but  not
                  selected for retrieval.)

           2      An  error was encountered when attempting to open a
                  socket to retrieve mail.  If you don't know what  a
                  socket  is, don't worry about it -- just treat this
                  as an 'unrecoverable error'.  This error  can  also
                  be because a protocol fetchmail wants to use is not
                  listed in /etc/services.

           3      The user authentication step failed.  This  usually
                  means  that a bad user-id, password, or APOP id was
                  specified.  Or it may mean that you  tried  to  run
                  fetchmail under circumstances where it did not have
                  standard input attached to a terminal and could not
                  prompt for a missing password.

           4      Some sort of fatal protocol error was detected.

           5      There was a syntax error in the arguments to fetch
                  mail.

           6      The run control file had bad permissions.

           7      There  was  an  error  condition  reported  by  the
                  server.  Can also fire if fetchmail timed out while
                  waiting for the server.

           8      Client-side exclusion error.  This means  fetchmail
                  either  found  another  copy of itself already run
                  ning, or failed in such a way that  it  isn't  sure
                  whether another copy is running.

           9      The  user  authentication  step  failed because the
                  server responded "lock busy".  Try  again  after  a
                  brief pause!  This error is not implemented for all
                  protocols, nor for all servers.  If not implemented
                  for  your server, "3" will be returned instead, see
                  above.  May be returned when talking to qpopper  or
                  other  servers that can respond with "lock busy" or
                  some similar text containing the word "lock".

           23     Internal error.  You should see a message on  stan
                  dard error with details.

           When  fetchmail  queries more than one host, return status
           is 0 if any query successfully retrieved  mail.  Otherwise
           the  returned  error  status  is  that  of  the  last host
           queried.

## FILES

           ~/.fetchmailrc
                default run control file

           ~/.fetchids
                default location of file associating hosts with  last
                message  IDs  seen (used only with newer RFC1725-com
                pliant POP3 servers supporting the UIDL command).

           ~/.fetchmail.pid
                lock file to help prevent concurrent  runs  (non-root
                mode).

           ~/.netrc
                your FTP run control file, which (if present) will be
                searched  for  passwords  as  a  last  resort  before
                prompting for one interactively.

           /var/run/fetchmail.pid
                lock file to help prevent concurrent runs (root mode,
                Linux systems).

           /etc/fetchmail.pid
                lock file to help prevent concurrent runs (root mode,
                systems without /var/run).

## ENVIRONMENT

           If  the  FETCHMAILUSER  variable is set, it is used as the
           name of the calling user (default local name) for purposes
           such as mailing error notifications.  Otherwise, if either
           the LOGNAME or USER variable is correctly  set  (e.g.  the
           corresponding  UID  matches the session user ID) then that
           name is used as the default local name.   Otherwise  getp
           wuid(3)  must be able to retrieve a password entry for the
           session ID (this elaborate logic is designed to handle the
           case of multiple names per userid gracefully).

           If  the  environment  variable  FETCHMAILHOME  is set to a
           valid and existing directory name,  the  .fetchmailrc  and
           .fetchids  and  .fetchmail.pid files are put there instead
           of in the invoking user's home  directory  (and  lose  the

           Running fetchmail in foreground while a background  fetch
           mail  is running will do whichever of these is appropriate
           to wake it up.

## BUGS AND KNOWN PROBLEMS

           The mda and plugin options interact badly.   In  order  to
           collect error status from the MDA, fetchmail has to change
           its normal signal handling so that dead  plugin  processes
           don't  get  reaped  until the end of the poll cycle.  This
           can cause resource starvation if too many zombies  accumu
           late.   So  either don't deliver to a MDA using plugins or
           risk being overrun by an army of undead.

           The RFC822 address parser used in multidrop mode chokes on
           some  @-addresses  that are technically legal but bizarre.
           Strange uses of quoting and embedded comments  are  likely
           to confuse it.

           In a message with multiple envelope headers, only the last
           one processed will be visible to fetchmail.  To get around
           this,  use  a mailserver-side filter that consolidates the
           contents of all envelope headers into a single one  (proc
           mail,  mailagent, or maildrop can be programmed to do this
           fairly easily).

           Use of some of these protocols requires that  the  program
           send  unencrypted  passwords over the TCP/IP connection to
           the mailserver.  This creates a  risk  that  name/password
           pairs  might  be  snaffled  with  a packet sniffer or more
           sophisticated  monitoring  software.   Under   Linux   and
           FreeBSD,  the  --interface  option can be used to restrict
           polling to availability of  a  specific  interface  device
           with  a  specific local or remote IP address, but snooping
           is still possible if (a) either host has a network  device
           that  can be opened in promiscuous mode, or (b) the inter
           vening network link can be tapped.  We recommend  the  use
           of ssh(1) tunnelling to not only shroud your passwords but
           encrypt the entire conversation.

           Use of the %F or %T escapes in an mda option could open  a
           security  hole,  because  they pass text manipulable by an
           attacker to a shell command.  Potential  shell  characters
           are replaced by `_' before execution.  The hole is further
           reduced by the fact that  fetchmail  temporarily  discards
           any  suid  privileges  it  may have while running the MDA.
           For maximum safety, however, don't use an mda command con
           taining  %F  or  %T  when  fetchmail  is run from the root
           account itself.

           Fetchmail's method of sending bouncemail and spam  bounces
           The  UIDL  code  is  generally flaky and tends to lose its
           state on errors and line drops (so that old  messages  are
           re-seen).  If this happens to you, switch to IMAP4.

           The `principal' option only handles Kerberos IV, not V.

           Send  comments,  bug  reports, gripes, and the like to the
           fetchmail-friends list <fetchmail-friends@lists.ccil.org>.
           An  HTML FAQ is available at the fetchmail home page; surf
           to http://www.tuxedo.org/~esr/fetchmail or do a WWW search
           for pages with `fetchmail' in their titles.

## AUTHOR

           Eric  S.  Raymond <esr@snark.thyrsus.com>.  Too many other
           people to name here have  contributed  code  and  patches.
           This  program is descended from and replaces popclient, by
           Carl Harris <ceharris@mal.com>; the internals have  become
           quite  different,  but  some  of  its  interface design is
           directly traceable to that ancestral program.

## SEE ALSO

           mutt(1), elm(1), mail(1), sendmail(8), popd(8),  imapd(8),
           netrc(5)

## APPLICABLE STANDARDS

           SMTP/ESMTP:
                RFC  821,  RFC2821, RFC 1869, RFC 1652, RFC 1870, RFC
                1983, RFC 1985, RFC 2554.

           mail:
                RFC 822, RFC2822, RFC 1123, RFC 1892, RFC 1894.

           POP2:
                RFC 937

           POP3:
                RFC 1081, RFC 1225, RFC 1460, RFC 1725, RFC1734,  RFC
                1939, RFC 1957, RFC2195, RFC 2449.

           APOP:
                RFC 1460, RFC 1725, RFC 1939.

           RPOP:
                RFC 1081, RFC 1225.

           IMAP2/IMAP2BIS:
                RFC 1176, RFC 1732.

           IMAP4/IMAP4rev1:
                RFC 1730, RFC 1731, RFC 1732, RFC 2060, RFC 2061, RFC
                RFC 1508.

                                                         fetchmail(1)