Provided by: qpopper-drac_4.0.5-4sarge1_i386 bug

NAME

       qpopper -- POP3 server (v4.0)

SYNOPSIS

       /usr/local/lib/popper [ [ address ] [ : ] [ port ] ]
            [ -b buildir ] [ -c ] [ -d ] [ -D drac-host ]
            [ -e login_delay=nn,expire=nn ] [ -f config-file ]
            [ -k ] [ -K service ] [ -l0|1|2 ] [ -p0|1|2|3|4 ]
            [ -R ] [ -s ] [ -S ] [ -t trace-file ] [ -T timeout ]
            [ -u ] [ -U ] [ -v ] [ -y log-facility ]

NOTE

       This man page may be out of date.  Please see the Administrator’s Guide
       included  in  the  distribution  or  on  the  Qpopper   web   site   at
       www.qpopper.org/documentation.html

DESCRIPTION

       Qpopper  is  a  POP3 server to enable POP3 clients to read and download
       mail. This server implements the POP protocol defined in RFC  1939  and
       the RFC 2449 extensions.  This implementation runs on a variety of Unix
       platforms, including Linux.

       The server also enables clients to send mail using XTND XMIT, which  is
       processed via sendmail(8).

OPTIONS

       [address][:][port]
              If  compiled  as  a standalone daemon (instead of being run from
              inetd), you can can specify the IP address and/or port number to
              bind   to   at   run-time   as   parameter   1,   e.g.,  ’popper
              199.46.50.7:8110 -S’ or ’popper 8110 -S -T600’.  If IPv6 support
              is  compiled  in,  address can be also IPv6 address by enclosing
              the address with ‘[’ and ‘]’.  If not specified, the IP  address
              defaults  to all available.  The default port is 110 except when
              _DEBUG (not simply DEBUG) is defined, then it is 8765.

              See the Administrator’s  Guide  file  for  more  information  on
              standalone mode.

       -b bulldir
              Turns  on  the  bulletin  feature  and  specifies  the  bulletin
              directory path.  The command line overrides the  compiled  value
              if  it is defined.  To enable bulletins by default and specify a
              default  bulletin  directory  during  compilation,  include  the
              --enable-bulletins=bull-directory flag when running ./configure.
              The usual bulletin directory is /var/spool/bulls.

              A bulletin database can be used to track the  bulletins  instead
              of  the  users’  home  directory.   This  feature  is enabled by
              including the --enable-bulldb=bull-directory flag  when  running
              ./configure.

       -c     Downcases  user  names.   This  permits users to configure their
              clients with user names in UPPER or MiXeD case, and still login,
              assuming their actual user name is all lower case.

       -d     Turns  on  debug logging if compiled (pass --enable-debugging to
              ./configure).   All  debugging  information   is   saved   using
              syslog(8).   If this option is used, it should be first, so that
              debug records are generated for subsequent options.

       -D drac-host
              If  compiled  with  --enable-drac,  specifies  the  drac   host.
              Defaults to localhost.

       -e x=value,...
              Sets  POP3  extensions.  Sets x to the specified value.  Used to
              include Login Delay and/or Expire  response  tags  to  the  CAPA
              command.

              Remember  neither Expire nor Login Delay is enforced by qpopper;
              Sysadmins have to implement them by some other means.   However,
              you  can  enforce  EXPIRE  0  (no retention at all) by using the
              --enable-auto-delete  flag  with   ./configure.    This   causes
              messages  to be automatically deleted after they are downloaded.

       -f config-file
              Reads additional run-time options from config-file.  See Config-
              File Options for option names and syntax.

       -k     Enables  Kerberos  authentication when qpopper has been compiled
              with --with-kerberos5.  You must  already  have  libraries  that
              support Kerberos.

       -K service
              The  specified Kerberos service is used instead of the compiled-
              in value.  The default is rcmd, but pop is also common.

       -l 0|1|2
              Sets TLS/SSL handling.  Must have compiled with OpenSSL  or  SSL
              Plus.

              0 is the default.  TLS/SSL is not supported.

              1  enables  the  STLS command.  This permits a client to attempt
              TLS/SSL negotiation after connecting.

              2 Causes Qpopper to attempt TLS negotiation when a client  first
              connects.  This is for alternate-port support.

       -p 0|1|2|3|4
              Sets  plain-text password handling options.  To use this option,
              you must have an alternative to plain-text passwords  available,
              such as APOP.

              0  is  the  default, which permits plain-text passwords only for
              those users who are not in the APOP database.

              1 disables plain-text passwords for all users,  even  those  who
              are not in the APOP database.

              2 permits plain-text passwords for all users, even those who are
              in the APOP database (this allows clients to fall back on plain-
              text authentication if they do not support APOP).

              3  allows plain-text passwords only for connections on the loop-
              back (127.*.*.*)  address.

              4  permits  plain-text  passwords  only  if  TLS/SSL  has   been
              negotiated for the session (requires an executable compiled with
              OpenSSL or SSL Plus).

       -R     Disables reverse lookups on client IP addresses.

       -t trace-file
              Turns on debug logging if compiled (pass  --enable-debugging  to
              ./configure)  and  writes  the  trace  information in trace-file
              using fprintf(3V).  If this option is used, it should be  first,
              so that debug records are generated for subsequent options.

       -s     Turns  on  statistics logging using syslog(8) or trace-file.  At
              the end of each popper session,  the  following  information  is
              logged:  username,  number  of messages deleted, number of bytes
              deleted, number of message left on server, number of bytes  left
              on server.

       -S     Enables  server mode.  This mode reduces disk I/O and disk space
              usage when popper is used on a system that serves POP only users
              exclusively.

       -T timeout
              option  changes  the  default  compiled  value  POP_TIMEOUT  for
              terminating a session with a pop client.

              When the server is waiting for a  command  to  arrive  from  the
              client,  it  times out after the specified number of seconds and
              terminates the session.  This  avoids  having  popper  processes
              hang  forever  waiting for command input from clients which have
              terminated abnormally or are hung.

              A small value is ok for  small  to  medium  networks  where  the
              network  delay  is  within  a  few  seconds.  In this case 15-30
              seconds is not unreasonable.   Networks  with  large  delays  in
              sending  packets  (e.g., SLIP links) may require a larger value.
              In this case 300 seconds (5 minutes) is not unreasonable.

              Note that  RFC  1939  requires  a  minimum  of  600  second  (10
              minutes).

       -u     After  a  user authenticates, process options from a file called
              .qpopper-options in the user’s home directory.  This file can be
              owned by and writable by the user.

       -U     After  a  user authenticates, process options from a file called
              .<user>.qpopper-options in the spool directory, where <user>  is
              the user name.  This file should not be owned by nor writable by
              the user.

       -v     Report the current version and exit.

       Processing Options are described below.

   Processing Options
       Here  are some options the values of which are  announced  to  clients.
       Syntax of the options is:

                      opt=value,...

       This sets option opt to be value.  Multiple options can be specified at
       one instance and are comma separated.

       The following are the options supported:
              login_delay
              expire

   Config-File Options
       You can set Qpopper run-time options either from the command line or in
       a configuration file.

       Configuration  files  use different option names and a different syntax
       than the command-line (because command-line options are limited to  one
       character).

       The general syntax of the config file (in ABNF) is:

           config-line  ::= comment-line / reset-line / set-line

           comment-line ::= "#" <comment-text to end of line>

           reset-line   ::= "reset" boolean-option

           set-line     ::= implicit-set / explicit-set

           explicit-set ::= "set" option "=" value

           implicit-set ::= "set" boolean-option

           option       ::= boolean-option / integer-option /
                             string-option / mnemonic-option

           value        ::= "true" / "false" / integer / name

           string       ::= <"> 1*255 CHAR <">

           CHAR         ::= <any printable character except space or tab>

       In  other words the line starts with set or reset, then an option name,
       and either ends there or has an = followed by a value.

       A comment line starts with #.  The rest of the line  is  ignored.   You
       can  also  use  #  to  end  any line.  Everything else on the line is a
       comment.

       Note that reset can only be used with boolean options.  The =  and  the
       value  are omitted when reset is used.  When set is used with a boolean
       option, you can omit the = and value if you wish (it defaults to true),
       or you can use any of the four values true, false, 1, or 0.

       Some  options  are  "restricted",  meaning that they can’t be used in a
       .qpopper-options  file  in  a  user’s  home  directory  and/or   in   a
       <user>.qpopper-options file in the spool directory.

       The following are the command line options you can use:

       announce-login-delay
           Type: Integer
           Equivalent switch: "-elogin_delay=xx"
           Restricted: no

       announce-expire
           Type: Integer
           Equivalent switch: "-e expire=xxx"
           Restricted: no

       bulldir
           Type: Name
           Equivalent switch: "-b bulldir"
           Restricted: no

       bulldb-nonfatal
           Type: Boolean
           Equivalent switch: "-B"
           Restricted: no

           Only valid if compiled with --enable-bulldb.

       clear-text-password
           Type: Mnemonic
           Equivalent switch: "-p0|1|2|3|4"
           Values:

           default
                  Permits  clear-text  passwords  for any user not in the APOP
                  database.

           never  Clear-text passwords are never permitted.  Users not in  the
                  APOP database are unable to use Qpopper.

           always Clear-text passwords are always permitted, even for users in
                  the APOP database.

           local  Clear-text passwords are  permitted  only  when  the  client
                  connects through the local interface (127.*.*.*).

           tls    Clear-text  passwords  are  permitted  when TLS/SSL has been
                  negotiated for the session.  Available only if compiled with
                  OpenSSL or SSL Plus.

           ssl    (Same as tls).
           Restricted:  not  valid  in a configuration file in the user’s home
           directory nor in the spool directory.

       config-file
           Type: Name
           Equivalent switch: "-f config-file"
           Restricted: no

       debug
           Type: Boolean
           Equivalent switch: "-d debug
           Restricted: no

           Only valid if compiled with --enable-debug.

       downcase-user
           Type: Boolean
           Equivalent switch: "-c"
           Restricted: not valid in a configuration file in  the  user’s  home
           directory nor in the spool directory.

       drac-host
           Type: Name
           Equivalent switch: "-D drac-host"
           Restricted: no

           Only valid if compiled with --enable-drac

       kerberos
           Type: Boolean
           Equivalent switch: "-k"
           Restricted:  not  valid  in a configuration file in the user’s home
           directory nor in the spool directory.

           Only valid if compiled with --enable-kerberos5 or -DKERBEROS

       kerberos-service
           Type: Name
           Equivalent switch: "-K service-name"
           Restricted: not valid in a configuration file in  the  user’s  home
           directory nor in the spool directory.

           Only valid if compiled with --enable-kerberos5 or -DKERBEROS

       mail-lock-check
           Type: Integer
           Equivalent switch: "-L msgs"
           Restricted: no

       reverse-lookup
           Type: Boolean
           Equivalent switch: "-R" (Sense reversed!)
           Restricted:  not  valid  in a configuration file in the user’s home
           directory nor in the spool directory.

           Sense reversed from command-line switch.  Using -R is the  same  as
           ’SET REVERSE-LOOKUP = FALSE’.

       server-mode
           Type: Boolean
           Equivalent switch: "-S"
           Restricted: no

       statistics
           Type: Boolean
           Equivalent switch: "-s"
           Restricted: no

       timeout
           Type: Integer
           Equivalent switch: "-T timeout"
           Restricted: no

       tls-support
           Type: Mnemonic
           Equivalent switch: "-l"
           Values:

           default
                  TLS/SSL not supported.

           none   (same as default).

           stls   Enables support for the STLS command.

           alternate-port
                  Enables alternate-port TLS/SSL.
           Restricted:  not  valid  in a configuration file in the user’s home
           directory nor in the spool directory.

           Only valid if compiled with OpenSSL or SSL Plus.

       tracefile
           Type: Name
           Equivalent switch: "-t logfile"
           Restricted: no

           Only valid if compiled with --enable-debug.

       spool-options
           Type: Integer
           Equivalent switch: "-U"
           Restricted: not valid in a configuration file in  the  user’s  home
           directory nor in the spool directory.

       user-options
           Type: Integer
           Equivalent switch: "-u"
           Restricted:  not  valid  in a configuration file in the user’s home
           directory nor in the spool directory.

BULLETINS

       The  bulletin  feature  gives  system  administrators  a  way  to  send
       important  announcements  to  all  POP  users without having to do mass
       mailings.

       The bulletin directory  contains  one  file  per  bulletin.  Each  file
       contains a single mail message with a header and body in normal mailbox
       format. The first line of each such bulletin must be a  "From  "  line.
       The  easiest  way  for  sysadmins  to  create such bulletins is to mail
       themselves a copy of the bulletin using the account to which they  want
       replies  to be sent, then use their mail program to save the message to
       a file in the  bulletin  directory  in  mailbox  format.  The  bulletin
       directory must be world readable.

       The name of each bulletin file begins with the bulletin number, and may
       optionally continue with any other characters. E.g., the file  name  of
       bulletin number 23 might be "23.pophost_down_sunday".

       Popper  creates  a  file  named  .popbull in the home directory of each
       user.  This file contains a single line recording the highest  numbered
       bulletin received by the user.

       Each  time a POP client connects to the server, any new bulletins which
       the user has not received previously are automatically appended to  the
       user’s mail.

       When  a  bulletin  is  copied, the "To" header line is replaced by "To:
       username@thishost",  and  any  "Status:"  header  lines  are   deleted.
       Otherwise, the bulletin is copied as is.

       When  a  new  user  checks  for mail the first time, popper creates the
       .popbull file in the user’s  home  directory  and  seeds  it  with  the
       current  maximum  bulletin  number.  Thus  new  users  do  not  get old
       bulletins.

       Bulletins can  be  enabled  by  default,  and  the  bulletin  directory
       specified, by including the --enable-bulletins=bull-directory flag when
       running ./configure.

       To use a database instead of .popbull files in users’ home  directories
       for tracking the highest bulletin seen by a user, include the --enable-
       bulldb=bull-directory flag when running  ./configure.   You  must  also
       create two empty files in the bulletin directory, called bulldb.pag and
       bulldb.dir.  When a bulletin database is used, qpopper checks  for  and
       uses  any  .popbull  files  in  the  user’s  home directory, to provide
       continuity.

       To specify the maximum number of bulletins sent to new  users,  include
       the  --with-new-bulls  flag  when  running  ./configure.   For example,
       --with-new-bulls=10 says that new users get at most ten bulletins.

THE POP TRANSACTION CYCLE

       The Qpopper server is a single program (called popper) that is launched
       by  inetd  when  it  gets  a service request on the POP TCP port.  (The
       official port number specified in RFC 1939 for POP version  3  is  port
       110.   However, some POP3 clients attempt to contact the server at port
       109, the POP version 2 port.  Unless you are running both POP2 and POP3
       servers,  you  can simply define both ports for use by the POP3 server.
       This is explained in the installation instructions later on.)

       The qpopper program initializes and verifies that the peer  IP  address
       is registered in the local domain (unless the -R command-line option is
       used), logging a warning message when  a  connection  is  made  with  a
       client  whose  IP  address does not have a canonical name.  For systems
       using BSD 4.3 bind, it also checks to see if a  canonical  name  lookup
       for  the  client  returns  the  same peer IP address, logging a warning
       message if it does not.

       The server enters the authorization state, during which the client must
       correctly identify itself by providing a valid Unix userid and password
       on the server’s host machine (or successfully authenticate  using  APOP
       or AUTH).  No other exchanges are allowed during this state (other than
       a request to quit.)  If authentication  fails,  a  warning  message  is
       logged and the session ends.

       Once  the user is identified, qpopper changes its user and group ids to
       match that of the user and enters the transaction  state.   The  server
       makes  a  temporary  copy  of the user’s maildrop which is used for all
       subsequent transactions  (unless  running  in  server  mode  ).   These
       include  the  bulk  of  POP  commands  to  retrieve  mail, delete mail,
       undelete mail, and so forth.

       When the client quits, the server enters the final update state, during
       which  the  network connection is terminated and the user’s maildrop is
       updated with the (possibly) modified temporary maildrop.

LOGGING

       The POP server uses syslog to keep a  record  of  its  activities.   On
       systems  with  BSD  4.3 syslogging, the server logs (by default) to the
       "local0"  facility  at  priority  "notice"  for  all  messages   except
       debugging which is logged at priority "debug".  The default log file is
       /usr/spool/mqueue/POPlog.   These  can  be  changed,  if  desired.   On
       systems  with  4.2  syslogging all messages are logged to the local log
       file, usually /usr/spool/mqueue/syslog.

DEBUGGING

       Qpopper logs debugging information when the -d parameter  is  specified
       after  its invocation in the inetd.conf file.  Care should be exercised
       in using this option since it  generates  considerable  output  in  the
       syslog   file.   Alternatively,  the  "-t  <file-name>"  option  places
       debugging information into file "<file-name>" using fprintf instead  of
       syslog.

       For  SunOS  version  3.5,  the popper program is launched by inetd from
       /etc/servers.  This file does not allow you  to  specify  command  line
       arguments.  Therefore, if you want to enable debugging, you can specify
       a shell script in /etc/servers to be launched instead of popper and  in
       this script call popper with the desired arguments.

       You  can confirm that the POP server is running on Unix by telneting to
       port 110 (or 109 if you set it up that way).  For example:

       %telnet pop.qualcomm.com 110
       Trying...
       Connected to pop.qualcomm.com.
       Escape character is ’^]’.
       +OK QPOP (version 3.0) at pop.qualcomm.com starting.
       quit
       +OK Pop server at pop.qualcomm.com signing off.
       Connection closed by foreign host.

EXTENSIONS

       The server implements several extended commands.

       XTND XMIT: Sends a mail message using /usr/lib/sendmail.

       XTND XLIST header [num]: Extracts and returns the specified header line
       for  the  specified  message number. If the "num" parameter is missing,
       returns the header line for all the messages which  are  not  currently
       marked for deletion.

       XMANGLE: Can be used as a modifier to the TOP, RETR, LIST commands. The
       result is to condense MIME messages into a single part. For example:

              RETR 10 XMANGLE(text=html;headers=to:,cc:,from:,date:)
       results in transforming message 10 into a single part  of  content-type
       text/html with only those headers which were requested.

       Qpopper  also  supports  the  "-no-mime"  user  name hack.  As a way to
       enable MIME-mangling with clients that  do  not  support  XMANGLE,  add
       "-no-mime"  to  the  user  name.  For example, if the userid is "mary",
       enter it in the client as "mary-no-mime".

FILES

       /var/mail               mail files
       /etc/inetd.conf         pop program invocation
       /etc/syslog.conf        logging specifications
       /var/spool/bulls        bulletins
       ~/.popbull              largest bulletin number seen by user

SEE ALSO

       inetd(8), inetd.conf(4), sendmail(8)

AUTHORS

       Randall Gelles, Praveen Yaramada, Laurence  Lundblade,  Mark  Erickson,
       Bob  Campbell, Edward Moy, Austin Shelton, Marshall T Rose, and cast of
       thousands at Rand, UDel, UCI, QUALCOMM Incorporated  and  the  Internet
       user community.