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


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
       compilation  detected  or  was told about a reliable local
       MDA, it will use that MDA for local delivery instead.   At
       build  time, fetchmail normally looks for executable proc­
       mail(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

       vides complete control of fetchmail configuration, includ­
       ing  the  multidrop  features.  In either case, the `Auto­
       probe' button will tell you the most  capable  protocol  a
       given mailserver supports, and warn you of potential prob­
       lems with that server.


GENERAL OPERATION

       The behavior of fetchmail is  controlled  by  command-line
       options and a run control file, ~/.fetchmailrc, the syntax
       of which we describe in a later section (this file is what
       the  fetchmailconf  program  edits).  Command-line options
       override ~/.fetchmailrc declarations.

       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

              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
              Verbose  mode.  All control messages passed between
              fetchmail and the mailserver are echoed to  stdout.
              Overrides  --silent.   Doubling this option (-v -v)
              causes extra diagnostic information to be  printed.

   Disposal Options
       -a, --all
              (Keyword:  fetchall)  Retrieve  both old (seen) and
              new messages from the mailserver.  The  default  is
              to  fetch  only  messages the server has not marked
              seen.  Under POP3, this option also forces the  use
              of  RETR rather than TOP.  Note that POP2 retrieval
              behaves as though --all is always on (see RETRIEVAL
              FAILURE  MODES below) and this option does not work
              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

              will automatically delete messages after successful
              delivery.

   Protocol and Query Options
       -p, --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
                     port 1109.

              SDPS   Use  POP3  with Demon Internet's SDPS exten­
                     sions.

              IMAP   IMAP2bis,  IMAP4,  or  IMAP4rev1  (fetchmail
                     autodetects their capabilities).

              ETRN   Use the ESMTP ETRN option.

              ODMR   Use  the the On-Demand Mail Relay ESMTP pro­
                     file.

       All these alternatives work  in  basically  the  same  way
       (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

              mailbox as a baby news drop for a group of users.

       -P, --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, --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  calkling
              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­
              nection.   This is useful if you want to use socks,
              SSL, ssh, or need some special  firewalling  setup.
              The  program  will  be  looked  up in $PATH and can
              optionally be passed the hostname and port as argu­
              ments  using  "%h" and "%p" respectively (note that
              the interpolation logic is  rather  primitive,  and
              these token must be bounded by whitespace or begin­
              ning of string or end of string).   Fetchmail  will
              write  to the plugin's stdin and read from the plu­
              gin's stdout.

       --plugout <command>
              (Keyword: plugout) Identical to the  plugin  option
              above,  but  this  one is used for the SMTP connec­
              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

              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­
              cates for authentication.  In most cases,  this  is
              optional.   This specifies the location of the pri­
              vate key used to sign transactions with 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 public key (combined  key  and

              a password is required to unlock the key,  it  will
              be  prompted  for  at the time just prior to estab­
              lishing the session to the server.  This can  cause
              some complications in daemon mode.

       --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

              default.  However, when using Kerberos  authentica­
              tion,  the FQDN of the machine running fetchmail is
              added to the  end  of  the  list  as  an  invisible
              default.  Each hostname may have a port number fol­
              lowing the host name.  The port number is separated
              from  the host name by a slash; the default port is
              25 (or ``smtp'' under IPv6).   If  you  specify  an
              absolute  pathname (beginning with a /), it will be
              interpreted as the name of a UNIX socket  accepting
              LMTP connections (such as is supported by the Cyrus
              IMAP daemon) Example:

                   --smtphost
              server1,server2/2525,server3,/var/imap/socket/lmtp

              This  option  can  be used with ODMR, and will make
              fetchmail a relay between the ODMR server  and  and
              SMTP 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

              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     -oem     -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 -oem -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.

       --lmtp (Keyword: lmtp) Cause delivery via LMTP (Local Mail
              Transfer Protocol).  A service port must be explic­
              itly specified (with a slash suffix) on  each  host
              in  the  smtphost  hunt  list  if  this  option  is
              selected; the default port 25 will  (in  accordance
              with RFC 2033) not be accepted.

       --bsmtp <filename>
              (keyword:  bsmtp)  Append  fetched  mail to a BSMTP
              file.  This simply contains the SMTP commands  that
              would normally be generated by fetchmail when pass­
              ing mail to an SMTP listener daemon.   An  argument
              of  `-'  causes  the mail to be written to standard
              output.  Note that  fetchmail's  reconstruction  of
              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.

              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 qmail(8)
              and 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.   Setting  the batch limit to some nonzero
              size will prevent these delays.  This  option  does
              not work with ETRN or ODMR.

       -B <number>, --fetchlimit <number>
              (Keyword:  fetchlimit) Limit the number of messages
              accepted from a given server in a single poll.   By
              default there is no limit. An explicit --fetchlimit
              of 0 overrides any limits set in your  run  control
              file.  This option does not work with ETRN or ODMR.

       -e <count>, --expunge <count>
              (keyword: expunge) Arrange for deletions to be made
              final after a given number of messages.  Under POP2
              or POP3,  fetchmail  cannot  make  deletions  final
              without sending QUIT and ending the session -- with
              this option on, fetchmail will break  a  long  mail
              retrieval  session into multiple subsessions, send­
              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.  If you

              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

              The field before the first slash is  the  interface
              name  (i.e.  sl0, ppp0 etc.).  The field before the
              second slash is the  acceptable  IP  address.   The
              field after the second slash is a mask which speci­
              fies a range of IP addresses to accept.  If no mask
              is  present  255.255.255.255  is  assumed  (i.e. an
              exact match).  This option is currently  only  sup­
              ported under Linux and FreeBSD. Please see the mon­
              itor section for below for FreeBSD specific  infor­
              mation.

       -M <interface>, --monitor <interface>
              (Keyword:  monitor) Daemon mode can cause transient
              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.

              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  configura­
              tion  from  standard  input) or a filename.  Unless
              the --version option is also on, a named file argu­
              ment  must  have permissions no more open than 0600
              (u=rw,g=,o=) or else be /dev/null.

       -i <pathname>, --idfile <pathname>
              (Keyword: idfile) Specify an alternate name for the
              .fetchids file used to save POP3 UIDs.

       -n, --norewrite
              (Keyword:  no  rewrite)  Normally,  fetchmail edits
              RFC-822 address headers (To,  From,  Cc,  Bcc,  and

              local to the server are expanded to full  addresses
              (@ and the mailserver hostname are appended).  This
              enables replies on the client to get addressed cor­
              rectly  (otherwise  your  mailer  might  think they
              should be addressed to local users  on  the  client
              machine!).    This  option  disables  the  rewrite.
              (This option is provided to pacify people  who  are
              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

              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
              have to strip the `mbox-userstr-' prefix to deliver
              to the correct user.  This is what this  option  is
              for.

       --configdump
              Parse  the  ~/.fetchmailrc file, interpret any com­
              mand-line options specified, and dump a  configura­
              tion  report to standard output.  The configuration
              report is a data structure assignment in  the  lan­
              guage Python.  This option is meant to be used with
              an interactive ~/.fetchmailrc  editor  like  fetch­
              mailconf, written in Python.


USER AUTHENTICATION AND ENCRYPTION

       All  modes  except  ETRN  require  authentication  of  the
       client.  Normal user authentication in fetchmail  is  very
       much  like  the  authentication  mechanism of ftp(1).  The
       correct user-id and password depend  upon  the  underlying
       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 requesting one
       interactively; if an  entry  matching  the  mailserver  is
       found  in that file, the password will be used.  Fetchmail
       first looks for a match on poll name; if it finds none, it

       for details of the syntax of the .netrc file.  (This  fea­
       ture  may allow you to avoid duplicating password informa­
       tion 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
       RPOP rather than PASS to alert the server that  it  should
       do  special checking.  RPOP is supported by fetchmail (you
       can specify `protocol  RPOP'  to  have  the  program  send
       `RPOP'  rather  than  `PASS') but its use is strongly dis­
       couraged.  This facility was vulnerable  to  spoofing  and
       was withdrawn in RFC1460.

       RFC1460  introduced  APOP authentication.  In this variant
       of POP3, you register an APOP password on your server host
       (the  program  to  do  this with on the server is probably
       called popauth(8)).  You put the  same  password  in  your
       .fetchmailrc  file.  Each time fetchmail logs in, it sends
       a cryptographically secure hash of your password  and  the
       server greeting time to the server, which can verify 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

       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
       using the `netsec' server option in the .fetchmailrc file.
       In either case, the option value is a string in the format
       accepted by the  net_security_strtorequest()  function  of
       the inet6_apps library.

       You  can  access  SSL encrypted services by specifying the
       --ssl option.  You can also do this using the "ssl" server
       option  in  the  .fetchmailrc  file.   With SSL encryption
       enabled, queries are initiated  over  a  connection  after
       negotiating  an  SSL session.  Some services, such as POP3
       and IMAP, have different well known ports defined for  the
       SSL  encrypted  services.   The  encrypted  ports  will be
       selected automatically when SSL is enabled and no explicit
       port is specified.

       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.

       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).

       Finally, 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 trivially 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.


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

              fetchmail -d 900

       will, therefore, poll all  the  hosts  described  in  your
       ~/.fetchmailrc file (except those explicitly excluded with
       the `skip' verb) once every fifteen minutes.

       It is possible to set a polling interval in your ~/.fetch­
       mailrc  file  by  saying  `set  daemon  <interval>', where
       <interval> is an integer number of  seconds.   If  you  do
       this,  fetchmail  will  always start in daemon mode unless
       you override it with the command-line option --daemon 0 or
       -d0.

       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

       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
       on  for the duration of the next polling cycle.  This is a
       robustness feature.  It means that if a message is fetched
       (and thus marked seen by the mailserver) but not delivered
       locally due to some transient error, it will be re-fetched
       during  the  next  poll  cycle.   (The  IMAP logic doesn't
       delete messages until they're delivered, so  this  problem
       does not arise.)

       mail is running in daemon mode, this will be  detected  at
       the  beginning  of  the  next  poll cycle.  When a changed
       .fetchmailrc  is  detected,  fetchmail  rereads   it   and
       restarts from scratch (using exec(2); no state information
       is retained in the new instance).  Note also that  if  you
       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'.

       The protocols fetchmail uses to talk  to  mailservers  are
       next  to  bulletproof.   In normal operation forwarding to
       port 25, no message is ever deleted (or  even  marked  for
       deletion)  on  the  host  until  the  SMTP listener on the
       client side has acknowledged to fetchmail that the message
       has been either accepted for delivery or rejected due to a
       spam block.

       When forwarding to an MDA, however, there is  more  possi­
       bility of error.  Some MDAs are `safe' and reliably return
       a nonzero status on any delivery error, even  one  due  to
       temporary  resource  limits.   The  well-known procmail(1)
       program is like this; so are  most  programs  designed  as
       mail  transport  agents, such as sendmail(1), and exim(1).
       These programs give back a reliable positive  acknowledge­
       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

       will hand back an undocumented response that causes fetch­
       mail 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
       fetchmail --keep will be both undeleted and marked old.

       In  ETRN  and  ODMR  modes,  fetchmail  does  not actually
       retrieve messages; instead, it asks the server's SMTP lis­
       tener  to  start  a  queue  flush  to the client via SMTP.
       Therefore it sends only undelivered messages.


SPAM FILTERING

       Many SMTP listeners allow administrators to set  up  `spam
       filters'  that  block  unsolicited  email  from  specified
       domains.  A MAIL FROM or DATA line that triggers this fea­
       ture  will  elicit  an SMTP response which (unfortunately)
       varies according to the listener.

       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 current drafts of the replacement for RFC821,
       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 com­
       mand rejected for policy reasons].").

       The exim MTA returns 501 "Syntax error  in  parameters  or
       arguments", but will move to 550 soon.

       The postfix MTA runs 554 as an antispam response.

       The  fetchmail code recognizes and discards the message on
       any of a list of responses that  defaults  to  [571,  550,
       501, 554] but can be set with the `antispam' option.  This
       is one of the only three circumstance under  which  fetch­
       mail  ever  discards  mail (the others are the 552 and 553
       errors  described  below,  and  the  suppression  of  mul­
       tidropped 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

       reading the message body.  Thus, you won't pay  for  down­
       loading spam message bodies.

       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)
            Delete the message from the server.  Send bounce-mail
            to the originator.

       Other errors trigger bounce mail back to the originator.


THE RUN CONTROL FILE

       The preferred way to  set  up  fetchmail  is  to  write  a
       .fetchmailrc  file in your home directory (you may do this
       directly, with a text editor, or indirectly via fetchmail­
       conf).   When there is a conflict between the command-line
       arguments and the arguments in this file, the command-line
       arguments take precedence.

       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

       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.)

   Keyword/Option Summary
       Here  are the legal options.  Keyword suffixes enclosed in
       square brackets are optional.  Those corresponding to com­
       mand-line  options are followed by `-' and the appropriate
       option letter.

       Here are the legal global options:

       Keyword             Opt   Function
       -------------------------------------------------------------
       set daemon                Set a background poll interval  in
                                 seconds
       set postmaster            Give  the  name of the last-resort
                                 mail recipient
       set no bouncemail         Direct error  mail  to  postmaster
                                 rather than sender
       set no spambounce         Send spam bounces

                                 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
                              `password')
       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
       checkalias             Do  comparison  by  IP address for
                              multidrop
       no checkalias          Do comparison  by  name  for  mul­
                              tidrop (default)

                              UIDLs
       no uidl                Turn off POP3 use  of  client-side
                              UIDLs (default)
       interval               Only  check this site every N poll
                              cycles; N is a numeric argument.
       netsec                 Pass  in  IPsec  security   option
                              request.
       principal              Set  Kerberos principal (only use­
                              ful with imap and kerberos)

       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

                                reply (default)
       stripcr                  Strip  carriage  returns from ends
                                of lines
       forcecr                  Force carriage returns at ends  of
                                lines
       pass8bits                Force  BODY=8BITMIME to ESMTP lis­
                                tener
       dropstatus               Strip Status and  X-Mozilla-Status
                                lines out of incoming mail
       dropdelivered            Strip  Delivered-To  lines  out of
                                incoming mail
       mimedecode               Convert quoted-printable to  8-bit
                                in MIME messages
       idle                     Idle   waiting  for  new  messages
                                after each poll (IMAP only)
       no keep            -K    Delete seen messages  from  server
                                (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.

       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',
       `is',  `to', `dns'/`no dns', `checkalias'/`no checkalias',
       `password', `preconnect',  `postconnect',  `localdomains',
       `stripcr'/`no     stripcr',     `forcecr'/`no    forcecr',
       `pass8bits'/`no  pass8bits'  `dropstatus/no   dropstatus',
       `dropdelivered/no  dropdelivered',  `mimedecode/no mimede­
       code', `idle/no idle', and `no envelope'.

       The `via' option is for if you want to have more than  one
       configuration  pointing  at  the same site.  If it is pre­
       sent, the string argument will be taken as the actual  DNS
       name  of the mailserver host to query.  This will override
       the argument of poll, which can then simply be a  distinct
       label  for  the configuration (e.g. what you would give on
       the command line to explicitly query this host).

       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

       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
       vs.   Envelope   addresses').    Specifying   this  option
       instructs fetchmail to retrieve all the IP addresses asso­
       ciated  with  both  the poll name and the name used by the
       remote MTA and to do a comparison  of  the  IP  addresses.
       This  comes in handy in situations where the remote server
       undergoes frequent canonical name changes, that would oth­
       erwise  require modifications to the rcfile.  `checkalias'
       has no effect if `no dns' is specified in the rcfile.

       The `aka' option is for use with multidrop mailboxes.   It
       allows  you  to  pre-declare  a  list of DNS aliases for a
       server.  This is an optimization hack that allows  you  to
       trade space for speed.  When fetchmail, while processing a
       multidrop mailbox, grovels through message headers looking
       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


       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,
       `stripcr' will override.

       The  `pass8bits' option exists to cope with Microsoft mail
       programs that stupidly slap a  "Content-Transfer-Encoding:
       7bit"  on  everything.  With this option off (the default)
       and such a header present, fetchmail declares BODY=7BIT to
       an  ESMTP-capable  listener; this causes problems for mes­
       sages actually using 8-bit ISO or  KOI-8  character  sets,
       which will be garbled by having the high bits of all char­
       acters stripped.   If  `pass8bits'  is  on,  fetchmail  is
       forced  to declare BODY=8BITMIME to any ESMTP-capable lis­
       tener.  If the listener is 8-bit-clean (as all  the  major
       ones now are) the right thing will probably result.

       The  `dropstatus'  option controls whether nonempty Status

       (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.

       The words `here' and `there' have useful English-like sig­
       nificance.   Normally  `user  eric is esr' would mean that
       mail for the remote user `eric'  is  to  be  delivered  to
       `esr',  but you can make this clearer by saying `user eric
       there is esr here', or reverse it by saying `user esr here
       is eric there'

       Legal  protocol  identifiers  for  use with the `protocol'
       keyword are:

           auto (or AUTO)
           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

               Sender: (ignored if it doesn't contain an @)
               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
       address   doesn't  exist,  the  bounce  message  won't  be
       returned blindly to the author or to the list itself,  but
       rather to the list manager (which is less annoying).

       In  multidrop  mode,  destination headers are processed as
       follows: First, fetchmail looks for the  Received:  header
       (or  whichever  one is specified by the `envelope' option)
       to determine the local recipient address. If the  mail  is
       addressed  to  more  than one recipient, the Received line
       won't  contain   any   information   regarding   recipient
       addresses.

       Then  fetchmail  looks for the Resent-To:, Resent-Cc:, and
       Resent-Bcc: lines.  If they exists,  they  should  contain
       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 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"

       You may have an initial server description headed  by  the
       keyword  `defaults'  instead of `poll' followed by a name.
       Such a record is interpreted as defaults for  all  queries
       to  use.  It  may  be  overwritten  by  individual  server
       descriptions.  So, you could write:

         defaults proto pop3
               user "jsmith"
         poll pop.provider.net
               pass "secret1"
         poll mail.provider.net
               user "jjsmith" there has password "secret2"

       It's possible to specify more than  one  user  per  server
       (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:

               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 'esr' * 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

       Use the multiple-local-recipients feature with caution  --
       it  can  bite.   All multidrop features are ineffective in
       ETRN and ODMR modes.

       Also, note that in multidrop mode duplicate mails are sup­
       pressed.   A  piece  of mail is considered duplicate if it
       has the same message-ID as the message immediately preced­
       ing  and  more  than one addressee.  Such runs of messages
       may be generated when copies of  a  message  addressed  to
       multiple users are delivered to a multidrop box.

   Header vs. Envelope addresses
       The  fundamental problem is that by having your mailserver
       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


       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
       maildrop.

   Good Ways To Use Multidrop Mailboxes
       Multiple local names can be used to administer  a  mailing
       list from the client side of a fetchmail collection.  Sup­
       pose your name is `esr', and you want to both pick up your

       mail-friends", and you want to keep the alias list on your
       client machine.

       On  your  server,  you  can  alias  `fetchmail-friends' to
       `esr'; then, in your .fetchmailrc, declare `to esr  fetch­
       mail-friends here'.  Then, when mail including `fetchmail-
       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.

       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
       mailserver.  If so, the name mappings described in the  to
       ...  here declaration are done and the mail locally deliv­
       ered.

       This is the safest but also slowest method.  To  speed  it
       up,  pre-declare  mailserver aliases with `aka'; these are
       checked before DNS lookups are done.   If  you're  certain
       your  aka  list contains all DNS aliases of the mailserver
       (and all MX names pointing at it) you can declare `no dns'
       to  suppress  DNS  lookups entirely and only match against
       the aka list.


EXIT CODES

       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

              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".

       10     The fetchmail run failed while trying to do an SMTP
              port open or transaction.

       11     Fatal DNS error.  Fetchmail  encountered  an  error
              while  performing a DNS lookup at startup and could
              not proceed.

       12     BSMTP batch file could not be opened.

       13     Poll terminated by a fetch limit (see the  --fetch­
              limit option).

       14     Server busy indication.

       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).

            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
       leading dots on theirt names).  The .netrc file is  looked
       for  in  the the invoking user's home directory regardless
       of FETCHMAILHOME's setting.


SIGNALS

       If a fetchmail daemon is running as root, SIGHUP wakes  it
       up  from  its  sleep  phase  and forces a poll of all non-
       skipped servers (this is in accordance with the usual con­
       ventions for system daemons).

       If  fetchmail  is  running in daemon mode as non-root, use
       SIGUSR1 to wake it (this is so SIGHUP due  to  logout  can
       retain the default action of killing it).

       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

       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
       requires that port 25 of localhost be available for  send­
       ing mail via SMTP.

       If  you  modify a .fetchmailrc while a background instance
       is running and break the syntax, the  background  instance
       will  die  silently.   Unfortunately, it can't die noisily
       because  we  don't  yet  know  whether  syslog  should  be
       enabled.

       The  -f  -  option (reading a configuration from stdin) is
       incompatible with the plugin option.

       The UIDL code is generally flaky and  tends  to  lose  its

       re-seen).  If this happens to you, switch to IMAP4.

       Usuing LMTP with a localname that is not a full email name
       (containing @ and having a host part) will fail.

       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,
            RFC1983, RFC 1985

       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


       ETRN:
            RFC 1985

       ODMR/ATRN:
            RFC 2645

       OTP: RFC 1938

       LMTP:
            RFC 2033

       GSSAPI:
            RFC 1508


Man(1) output converted with man2html