Welcome to Linux Knowledge Base and Tutorial
"The place where you learn linux"
International Rescue Committe

 Create an AccountHome | Submit News | Your Account  

Tutorial Menu
Linux Tutorial Home
Table of Contents

· Introduction to Operating Systems
· Linux Basics
· Working with the System
· Shells and Utilities
· Editing Files
· Basic Administration
· The Operating System
· The X Windowing System
· The Computer Itself
· Networking
· System Monitoring
· Solving Problems
· Security
· Installing and Upgrading
· Linux and Windows

Glossary
MoreInfo
Man Pages
Linux Topics
Test Your Knowledge

Site Menu
Site Map
FAQ
Copyright Info
Terms of Use
Privacy Info
Disclaimer
WorkBoard
Thanks
Donations
Advertising
Masthead / Impressum
Your Account

Communication
Feedback
Forums
Private Messages
Surveys

Features
HOWTOs
News Archive
Submit News
Topics
User Articles
Web Links

Google
Google


The Web
linux-tutorial.info

Who's Online
There are currently, 197 guest(s) and 0 member(s) that are online.

You are an Anonymous user. You can register for free by clicking here

  

fetchmail




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

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

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

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

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

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

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

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

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

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

       -v | --verbose
              with ETRN or ODMR.

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

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

       -F | --flush
              POP3/IMAP  only.  Delete old (previously retrieved)
              messages from the mailserver before retrieving  new
              messages.  This  option  does not work with ETRN or
              ODMR.  In  combination  with  the  --limit  option,
              --flush  can  be  used to delete oversized messages
              waiting on the server.  Warning: if your local  MTA
              hangs  and  fetchmail 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 setting: if you don't  specify  `-k',  then
              fetchmail  will automatically delete messages after
              successful delivery.

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

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

              POP2   Post Office Protocol 2

              POP3   Post Office Protocol 3

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

              RPOP   Use POP3 with RPOP authentication.

       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
              is described in RFC1725).  Use with `keep' to use a
              mailbox as a baby news drop for a group  of  users.
              The  fact that seen messages are skipped is logged,
              unless error logging is done through  syslog  while
              running in daemon mode.

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

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

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

       --plugin <command>
              (Keyword:  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
              the  folder  name is server-dependent.  This option
              is not available under POP3, ETRN, or ODMR.

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

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

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

       --sslkey <name>
              (Keyword: sslkey) Specifies the file  name  of  the
              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
              added to the  end  of  the  list  as  an  invisible
              This  option  can  be used with ODMR, and will make
              fetchmail a relay between the ODMR server 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
              prevents the message from  being  deleted  off  the
              server.   If  fetchmail is running as root, it sets
              its userid to that of the target user while  deliv­
              ering  mail through an MDA.  Some possible MDAs are
              "/usr/sbin/sendmail     -i     -f      %F      %T",
              "/usr/bin/deliver"  and  "/usr/bin/procmail  -d %T"
              (but the latter is usually redundant as  it's  what
              SMTP  listeners normally forward to).  Local deliv­
              ery addresses will be inserted into the MDA command
              wherever  you  place  a %T; the mail message's From
              address will be inserted where you place an %F.  In
              both  cases  the  addresses  are enclosed in single
              quotes ('), after removing any single  quotes  they
              may  contain,  before  the MDA command is passed to
              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.  Combined with --flush, it can  be  used  to
              delete  oversized messages waiting on a server.  In
              daemon mode, oversize notifications are  mailed  to
              the calling user (see the --warnings option).  This
              option does not work with ETRN or ODMR.

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

       -b <count> | --batchlimit <count>
              (Keyword: batchlimit) Specify the maximum number of
              messages  that  will be shipped to an SMTP listener
              before the connection is deliberately torn down and
              rebuilt  (defaults  to  0,  meaning  no limit).  An
              explicit --batchlimit of 0 overrides any limits set
              in  your  run control file.  While sendmail(8) nor­
              mally initiates delivery of a  message  immediately
              after  receiving  the message terminator, some SMTP
              listeners are not so prompt.   MTAs  like  smail(8)
              may  wait  till the delivery socket is shut down to
              (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.  Also  note
              that  some servers enforce a delay of a few seconds
              after each quit, so fetchmail may not  be  able  to
              get back in immediately after an expunge -- you may
              see "lock busy" errors  if  this  happens.  If  you
              specify  this  option  to  an  integer  N, it tells
              fetchmail to  only  issue  expunges  on  every  Nth
              delete.   An  argument  of zero suppresses expunges
              entirely (so no expunges at all will be done  until
              the  end  of  run).  This option does not work with
              ETRN or ODMR.

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

       -I <specification> | --interface <specification>
              (Keyword: interface) Require that a specific inter­
              face  device  be  up  and  have a specific local or
              remote IP address (or range) before polling.   Fre­
              quently  fetchmail  is used over a transient point-
              to-point TCP/IP  link  established  directly  to  a
              mailserver  via  SLIP or PPP.  That is a relatively
              secure channel.  But when other  TCP/IP  routes  to
              the  mailserver  exist  (e.g. when the link is con­
              nected to an  alternate  ISP),  your  username  and
              password  may be vulnerable to snooping (especially
              when daemon  mode  automatically  polls  for  mail,
              shipping  a  clear  password  over  the net at pre­
              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.
              After  each poll interval, if the link is up but no
              other activity has occurred on the link,  then  the
              poll  will  be skipped.  However, when fetchmail is
              woken up by a signal, the monitor check is  skipped
              and  the  poll  goes through unconditionally.  This
              option is currently only supported under Linux  and
              FreeBSD.   For the monitor and interface options to
              work for non root users under FreeBSD,  the  fetch­
              mail binary must be installed SGID kmem. This would
              be a security hole, but  fetchmail  runs  with  the
              effective  GID  set  to that of the kmem group only
              when interface data is being collected.

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

   Miscellaneous Options
       -f <pathname> | --fetchmailrc <pathname>
              Specify  a  non-default name for the ~/.fetchmailrc
              run control file.  The pathname  argument  must  be
              either "-" (a single dash, meaning to read the con­
              (@ 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
              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
       to the server.  Normal user authentication in fetchmail is
       very much like the  authentication  mechanism  of  ftp(1).
       The  correct user-id and password depend upon the underly­
       ing security system at the mailserver.

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

              fetchmail -u jsmith mailgrunt

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

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

       On mailservers that do not provide ordinary user accounts,
       your user-id and password  are  usually  assigned  by  the
       server  administrator  when you apply for a mailbox on the
       server.  Contact your server administrator  if  you  don't
       know  the  correct  user-id  and password for your mailbox
       account.
       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
       can declare the authentication value `ssh'  on  that  site
       entry  to  stop  .fetchmail from asking you for a password
       when it starts up.

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

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

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

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

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

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


DAEMON MODE

       The --daemon  <interval>  or  -d  <interval>  option  runs
       fetchmail  in  daemon  mode.   You  must specify a numeric
       argument which is a polling interval in seconds.
       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 back­
       ground sends a wakeup signal to the daemon, forcing it  to
       poll  mailservers  immediately.   (The  wakeup  signal  is
       SIGHUP if fetchmail is running  as  root,  SIGUSR1  other­
       wise.)   The  wakeup action also clears any `wedged' flags
       indicating that connections  have  wedged  due  to  failed
       authentication or multiple timeouts.

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

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

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

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

       The -N or --nodetach option suppresses  backgrounding  and
       detachment  of  the daemon process from its control termi­
       nal.  This is primarily useful for debugging.   Note  that
       If  you  touch  or  change  the  ~/.fetchmailrc file while
       fetchmail 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
       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  temp­
       files in the user's home directory, some POP3 servers will
       hand back an undocumented response that  causes  fetchmail
       to spuriously report "No mail".

       The  IMAP  code uses the presence or absence of the server
       flag \Seen to decide whether or  not  a  message  is  new.
       Under  Unix,  it  counts on your IMAP server to notice the
       BSD-style Status flags set by mail user agents and set the


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

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

       The postfix MTA runs 554 as an antispam response.

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

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

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

       By default, the list of antispam responses is empty.

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


SMTP/ESMTP ERROR HANDLING

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

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

       .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
       quotes  and  may contain whitespace (and quoted digits are
       treated as a string).  An unquoted string is  any  whites­
       pace-delimited  token  that  is  neither  numeric,  string
       quoted nor contains the special characters `,', `;',  `:',
       or `='.

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

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

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

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

   Poll vs. Skip
       The `poll' verb tells fetchmail to query this host when it

       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
       set logfile               Name of a file to dump  error  and
                                 status messages to
       set idfile                Name  of  the  file  to  store UID
                                 lists in
       set syslog                Do  error  logging  through   sys­
                                 log(3).
       set no syslog             Turn  off  error  logging  through
                                 syslog(3).
       set properties            String value is ignored by  fetch­
                                 mail  (may  be  used  by extension
                                 scripts)

       Here are the legal server options:

       Keyword            Opt   Function
       ------------------------------------------------------------
       via                      Specify DNS  name  of  mailserver,
                                overriding poll name
       proto[col]         -p    Specify  protocol  (case  insensi­
                                tive):  POP2,  POP3,  IMAP,  APOP,
                                KPOP
       local[domains]           Specify  domain(s)  to be regarded
                                as local
       port               -P    Specify TCP/IP service port
       auth[enticate]           Set authentication  type  (default
                                `any')
       timeout            -t    Server  inactivity timeout in sec­
                                onds (default 300)
       envelope           -E    Specify  envelope-address   header
                                name
       no envelope              Disable   looking   for   envelope
                                address
       qvirtual           -Q    Qmail  virtual  domain  prefix  to
                                remove from user name
       aka                      Specify  alternate  DNS  names  of
                                mailserver
       interface          -I    specify IP interface(s) that  must
                                be  up  for  server  poll  to take
                                place
       monitor            -M    Specify IP address to monitor  for
                                activity
       plugin                   Specify  command  through which to
                                UIDLs (default)
       interval                 Only check this site every N  poll
                                cycles; N is a numeric argument.
       tracepolls               Add  poll  tracing  information to
                                the Received header
       netsec                   Pass  in  IPsec  security   option
                                request.
       principal                Set  Kerberos principal (only use­
                                ful with imap and kerberos)
       esmtpname                Set name for  RFC2554  authentica­
                                tion to the ESMTP server.
       esmtppassword            Set password for RFC2554 authenti­
                                cation to the ESMTP server.

       Here are the legal user options:

       Keyword            Opt   Function
       ------------------------------------------------------------
       user[name]         -u    Set remote user name  (local  user
                                name if name followed by `here')
       is                       Connect   local  and  remote  user
                                names
       to                       Connect  local  and  remote   user
                                names
       pass[word]               Specify remote account password
       ssl                      Connect  to server over the speci­
                                fied  base  protocol   using   SSL
                                encryption
       sslcert                  Specify  file for client side pub­
                                lic SSL certificate
       sslkey                   Specify file for client side  pri­
                                vate SSL key
       sslproto                 Force ssl protocol for connection
       folder             -r    Specify remote folder to query
       smtphost           -S    Specify smtp host(s) to forward to
       fetchdomains             Specify  domains  for  which  mail
                                should be fetched
       smtpaddress        -D    Specify  the  domain  to be put in
                                RCPT TO lines
       smtpname                 Specify the user and domain to  be
                                put in RCPT TO lines
       antispam           -Z    Specify   what  SMTP  returns  are
                                interpreted as spam-policy blocks
       mda                -m    Specify MDA for local delivery
       bsmtp              -o    Specify BSMTP batch file to append
                                to
       preconnect               Command to be executed before each
                                connection
       postconnect              Command to be executed after  each
                                connection
       keep               -k    Don't  delete  seen  messages from
                                server
                                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)
       properties               String  value is ignored by fetch­
                                mail (may  be  used  by  extension
                                scripts)

       Remember  that  all  user  options  must follow all server
       options.

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

   Keywords Not Corresponding To Option Switches
       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
       poll  name or your `via', `aka' or `localdomains' options,
       and usually also for hostname parts which DNS tells it are
       aliases  of  the mailserver.  See the discussion of `dns',
       `checkalias', `localdomains', and `aka' for details on how
       matching addresses are handled.

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

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

       The `checkalias' option (normally off) extends the lookups

       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
       MDA unaltered (local-name mappings are not applied).

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

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

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

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

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

       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
       and  X-Mozilla-Status  lines  are retained in fetched mail
       (the default) or discarded.  Retaining  them  allows  your
       MUA  to see what messages (if any) were marked seen on the
       server.  On the other hand, it can confuse  some  new-mail
       notifiers,  which  assume that anything with a Status line
       in it has  been  seen.   (Note:  the  empty  Status  lines
       inserted  by  some  buggy  POP servers are unconditionally
       discarded.)

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

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

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

       The  `properties'  option  is  an extension mechanism.  It
       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 @ or !)
               Sender: (ignored if it doesn't contain an @ or !)
               Resent-From:
               From:
               Reply-To:

       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 pop.provider.net proto pop3 user "jsmith" pass "secret1"
         poll other.provider.net proto pop2 user "John.Smith" pass "My^Hat"

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

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

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

       If  you  need to include whitespace in a parameter string,
         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:

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

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

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

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

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

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

       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
       the address you need in order to reroute mail properly.

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

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

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

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

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

       A  related problem is that when you blind-copy a mail mes­
       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.
       (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
              server.  Can also fire if fetchmail timed out while
              waiting for the server.

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

       9      The user authentication  step  failed  because  the
              server  responded  "lock  busy".  Try again after a

       12     BSMTP batch file could not be opened.

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

       14     Server busy indication.

       15     Server timed out during an IMAP IDLE.

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

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


FILES

       ~/.fetchmailrc
            default run control file

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

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

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

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

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


ENVIRONMENT

       If the FETCHMAILUSER variable is set, it is  used  as  the
       name of the calling user (default local name) for purposes
       such as mailing error notifications.  Otherwise, if either
       the  LOGNAME  or  USER variable is correctly set (e.g. the
       corresponding UID matches the session user ID)  then  that
       name  is  used as the default local name.  Otherwise getp­
       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
       can  cause resource starvation if too many zombies accumu­
       late.  So either don't deliver to a MDA using  plugins  or
       risk being overrun by an army of undead.

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

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

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

       Use  of the %F or %T escapes in an mda option could open a
       security hole, because they pass text  manipulable  by  an
       attacker  to  a shell command.  Potential shell characters
       because  we  don't  yet  know  whether  syslog  should  be
       enabled.   On some systems, fetchmail dies quietly even if
       there is no syntax error; this seems to have something  to
       do with buggy terminal ioctl code in the kernel.

       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
       state  on  errors and line drops (so that old messages are
       re-seen).  If this happens to you, switch to IMAP4.

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

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


AUTHOR

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


SEE ALSO

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


APPLICABLE STANDARDS

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

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

       POP2:
            RFC 937

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

       APOP:
            RFC 1460, RFC 1725, RFC 1939.

            RFC 2645.

       OTP: RFC 1938.

       LMTP:
            RFC 2033.

       GSSAPI:
            RFC 1508.

       TLS  RFC 2595.

                                                     fetchmail(1)
  




Login
Nickname

Password

Security Code
Security Code
Type Security Code


Don't have an account yet? You can create one. As a registered user you have some advantages like theme manager, comments configuration and post comments with your name.

Help if you can!


Amazon Wish List

Did You Know?
You can help in many different ways.


Friends



Tell a Friend About Us

Bookmark and Share



Web site powered by PHP-Nuke

Is this information useful? At the very least you can help by spreading the word to your favorite newsgroups, mailing lists and forums.
All logos and trademarks in this site are property of their respective owner. The comments are property of their posters. Articles are the property of their respective owners. Unless otherwise stated in the body of the article, article content (C) 1994-2013 by James Mohr. All rights reserved. The stylized page/paper, as well as the terms "The Linux Tutorial", "The Linux Server Tutorial", "The Linux Knowledge Base and Tutorial" and "The place where you learn Linux" are service marks of James Mohr. All rights reserved.
The Linux Knowledge Base and Tutorial may contain links to sites on the Internet, which are owned and operated by third parties. The Linux Tutorial is not responsible for the content of any such third-party site. By viewing/utilizing this web site, you have agreed to our disclaimer, terms of use and privacy policy. Use of automated download software ("harvesters") such as wget, httrack, etc. causes the site to quickly exceed its bandwidth limitation and are therefore expressly prohibited. For more details on this, take a look here

PHP-Nuke Copyright © 2004 by Francisco Burzi. This is free software, and you may redistribute it under the GPL. PHP-Nuke comes with absolutely no warranty, for details, see the license.
Page Generation: 0.25 Seconds