INSTALL 

Last updated: 10 October 2000

This document is updated between releases.  So please read 
it each time you download a new version of Qpopper.

For release notes please refer doc/Release.Notes

Send your patches and bug reports to qpopper@qualcomm.com.

Note: there is now an unofficial mailing list for QPopper.
See the README file for details.



SECTIONS:
    1. QUICKNOTES
    2. CONFIGURE OPTIONS.
    3. RUN-TIME OPTIONS (COMMAND LINE OPTIONS).
    4. RUN-TIME OPTIONS (READ FROM CONFIG FILE).
    5. APOP
    6. BULLETINS
    7. SERVER MODE
    8. STANDALONE MODE.
    9. COMPILE TIME MACROS (for other options)
    NOTES
    DEBUGGING



1. QUICKNOTES:
--------------

If you modify qpopper, be sure to edit the file
popper/banner.h and add a string (instructions are in this
file).

To compile qpopper, change to the directory to where the 
sources of qpopper are located and run the following 
commands. 

    ./configure
    make

Running the configure script builds the Makefile for your 
operating system. Using the default settings, the Makefile 
can run correctly for the following operating Systems: 
Solaris, HPUX, IRIX, Linux, and Digital OSF1.  

Note that if you are using shadow password, you should run
configure with --enable-specialauth, for example 
        ./configure --enable-specialauth

However, on some platforms this is not required, for example,
IRIX, Solaris, BSD.  Using this flag on systems where it is
not needed may result in compilation errors (such as
"undefined symbol: auth_user").

Running 'make' builds qpopper for your operating system. 
After 'make' finishes, you need to copy the resulting popper
executable to a public location.  Although there is no required 
location, many sysadmins prefer /usr/local/lib, and this is 
used in example lines (such as /etc/inetd.conf lines).

If using standalone mode, configure your system to launch
Qpopper at start-up.  See section STANDALONE MODE for more
information on standalone mode.

If not using standalone mode, modify your /etc/inetd.conf
file to contain the line below.  (You may have to modify it to
support your version of the file and your specific qpopper
location, if it is not /usr/local/lib):

   pop3 stream tcp nowait root /usr/local/lib/popper qpopper -s

NOTE: If you have a lot of users connecting, you may need to
increase the inetd timeout value, to prevent it from assuming
popper is looping, which causes it to kill popper and write a
log entry noting "service looping".  You can increase the global
inetd timeout by passing inetd a command line argument.  On some
systems, you can alter the timeout for qpopper by changing
"nowait" to "nowait.timeout", for example, "nowait.400".

If your OS does not have an inetd.conf file, then it may use 
the config file /etc/servers.  Use the following line:

   pop3    tcp     /usr/local/lib/popper    qpopper -s

If you use Linux 7 or later with xinetd instead of inetd,
create a file called 'pop3' in the '/etc/xinetd.d' directory
that contains the following lines (adjust the 'server_args'
and 'server' lines to suit your needs):

    service pop3
    {
        socket_type     = stream
        protocol        = tcp
        wait            = no
        user            = root
        server          = /usr/local/lib/popper
        server_args     = qpopper -s
        port            = 110
    }

For all OS versions (other than Linux 7 with xinetd instead of
inetd), your /etc/services file needs to include the following
line:

   pop3         110/tcp                # Post Office

NOTE: Be sure to remove (or comment out) any lines from 
/etc/services which have the same port (110) and remove 
(or comment out) any corresponding lines from /etc/inetd.conf
or you may have problems, such as "address already in use"
errors.

Restart inetd with a kill -HUP inetdpid (some systems can 
use inetd -c).

(On Linux, you can use 'ps x | grep inetd' to find the pid of
inetd.  On many flavors of Unix you can use 'ps -e | grep inetd'.
Note that you need to be root to do this.)
    
If you have modified these files for AIX, use refresh -s inetd'.

If you are running NIS, please don't forget to update your 
maps.

Note that you also need to copy the man pages.  Generally, this
requires that you copy man/*.8 to /usr/man/man8.



2. CONFIGURE OPTIONS (COMPILATION OPTIONS):
-------------------------------------------

The following flags can be passed to ./configure to enable
compile-time changes:

 --enable-debugging       Compiles in debugging code

 --enable-servermode      Enable SERVER_MODE.  See section
                          SERVER MODE for details.
 
 --enable-bulletins=path  Enable bulletins and set the path for
                          the bulletin directory (default is
                          /var/spool/bulls).  See section
                          BULLETINS for details.

 --enable-bulldb=path     Enable bulletins, set the path for the
                          bulletin directory (default is
                          /var/spool/bulls), and enable use of
                          database for tracking bulletins.  See 
                          section BULLETINS for details.

 --with-new-bulls=number  Specify the maximum number of bulletins 
                          for new users (default is 10).  See 
                          section BULLETINS for details.

 --enable-popbulldir=path Specify an alternate location for users'
                          popbull files.

 --enable-specialauth     Enable secure crypt or shadow passwords.
                          Needed on most, but not all, OSes.

 --with-pam=servicename   Use PAM authentication.  The default
                          service name is "pop3".
 
 --enable-apop=path       Set the pop.auth file path (default is
                          /etc/pop.auth).  See section APOP for
                          details and instructions.

 --enable-scram=path      Include scram capability in AUTHDB file
                          (default path is /etc/pop.auth).

 --with-popuid=pop        Set the user who owns the pop.auth file.
                          (The default is "pop").  See section 
                          APOP for details and instructions.

 --enable-log-login       Log successful user authentications.
                          See LOG_LOGIN in section MACROS for
                          more information.

 --enable-auto-delete     Automatically delete downloaded msgs.
                          See "AUTO_DELETE" in section MACROS for
                          more information.

 --enable-shy             Hide qpopper version number.  See SHY
                          in section MACROS for more information.

 --with-warnings          Enable additional compiler warnings.

 --enable-hash-spool=1|2  Use hashed spool directory.  See 
                          HASH_SPOOL in section MACROS for more
                          information.  The default method is 2.
 
 --enable-home-dir-mail=file
                          Use a spool file in the user's home
                          directory.  See HOMEDIRMAIL in section
                          MACROS for more information.  The
                          default file name is ".mail".

 --enable-temp-drop-dir=path
                          Specify an alternate directory for 
                          temporary mail drop files.  The default
                          is the spool directory.

 --with-log-facility=name Specifies the log facility.  Default
                          is LOG_LOCAL1 or LOG_MAIL, depending
                          on the OS.

 --enable-uw-kludge       Checks for and hides UW IMAP status message.
 
 --enable-group-bulls     Show bulletins by groups (group name is second
                          element in bulletin name).  See BULLETINS.

 --enable-timing          Writes timing information to log at session end.
                          Includes whole seconds (elapsed) for
                          authentication, initialization, and cleanup.

 --enable-drac=lib-path   Enables use of DRAC.  Specify path to drac
                          libraries, or leave blank if installed in usual
                          place.  DRAC is a method of authorizing SMTP
                          sessions for IP addresses which have recently
                          authenticated using POP.  This can be useful,
                          but long term solution is SMTP AUTH.

 --enable-old-uidl        Generates UIDs using old (pre-3.x) style
                          encoding.  This is only useful if you set
                          NO_STATUS and have existing users with old
                          (pre-3.x) spool files and you want to keep the
                          UIDs the same.

 --disable-status         Prevent Qpopper from writing 'Status' or 
                          'X-UIDL' headers (sets NO_STATUS).  This forces
                          UIDs for each message to be recalculated in each
                          session.

 --enable-keep-temp-drop  Prevents Qpopper from deleting the temp drop
                          files.

 --disable-check-pw-max   Prevents Qpopper from checking for expired
                          passwords.

 ---disable-old-spool-loc Don't check for old .user.pop files in old
                          locations when HASH_SPOOL or HOMEDIRMAIL used.

 --disable-check-hash-dir Doesn't check for or create hash spool
                          directories.  Use this if you pre-create the
                          directories.

 --enable-server-mode-group-include=group
                          Sets server mode for users in the specified
                          group.

 --enable-server-mode-group-exclude=group
                          Sets server mode OFF for users in the specified
                          group.

 --enable-secure-nis-plus Set this if you are using secure NIS+.
 
 --disable-optimizations  Turns off all compiler optimizations.  Useful
                          when running under a debugger.

 --with-kerberos5=dir     Enables use of Kerberos V libraries.
                          Optionally specify library location.  Sets
                          KRB5_KRB4_COMPAT to allow for backwards
                          compatibility with Kerberos IV servers.

 --enable-any-kerberos-principal
                          Permits use of any Kerberos principle in
                          client authentication.

 --enable-kuserok         Uses kuserok() to vet users.

 --enable-ksockinst       Uses getsockinst() for Kerberos instance.

 --enable-standalone      Creates standalone POP daemon instead of
                          one to be run out of inetd.  Can specify IP
                          address and/or port number to bind to as
                          parameter 1, e.g.,
                          'popper 199.46.50.7:8110 -S' or
                          'popper 8110 -S -T600'.  If not specified,
                          IP address defaults to all available.  The
                          default port is 110 except when _DEBUG (not
                          simply DEBUG) is defined, then it is 8765.

 --enable-auth-file=path  Permits access only to users listed in the
                          specified file.  Format is one user per line.

 --enable-nonauth-file=path
                          Denies access to users listed in the specified
                          file.  Format is one user per line.

 --disable-update-abort   Does not go into UPDATE state on abort.  Use
                          this to comply with RFC 1939.



3. RUN-TIME OPTIONS (COMMAND LINE OPTIONS):
-------------------------------------------

You can set Qpopper run-time options either from
the command line or in a config file.

The following are the command line options you can use.

popper [-b bulldir [-B] [-c] [-d] [-D drac-host] 
       [-e login_delay=nn,expire=nn] [-f config-file] [-k] [-K service]
       [-s] [-S] [-t trace-file] [-T timeout] [-u] [-R]

Note that some systems may have limitations on the length or
number of command line arguments in inetd.conf.  (For example,
the Solaris inetd.conf man page states that no more than five 
arguments are permitted.)  You may wish to use config files for
run-time options to get around this limit, or to set options on
a per-user basis. See the '-f' and '-u' command-line options for
details, and the following section "RUN-TIME OPTIONS (CONFIG FILE)"
for details.

-b bulldir     This is the location of the bulletin 
               directory.  The command line overrides the 
               compiled value if it is defined.   
               
               A bulletin database can be used to track the 
               bulletins instead of .popbull files in the users
               home directory. This feature is enabled with the
               --enable-bulldb flag ./configure.  This also
               requires two blank files called BULLDIR/bulldb.pag
               and BULLDIR/bulldb.dir.  
               
               See the BULLETINS section for more information.

-B             If compiled with --enable-bulldb, allows sessions to
               proceed even if the bulletin database can't be opened.
               This allows users to get their mail, but may mean some
               users won't see some bulletins for a possibly long time
               or even at all. 

-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             Enables debug logging if compiled (pass
               --enable-debugging to ./configure).  Output is in
               syslog.  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             Set POP3 extensions.  Announces the Login Delay
               and Expire response tags to the CAPA command.
               By default the expire field is EXPIRE NEVER.

               Remember these are not enforced by qpopper;
               Sysadmins have to implement them by some other 
               means.

-f config-file Reads additional run-time options from the specified
               file.  See the following section "RUN-TIME OPTIONS
               (CONFIG FILE)" for option names and syntax.

-k             If compiled with --enable-kerberos5, this flag enables
               Kerberos support only.  In qpopper, enter this
               command at the appropriate kpop port in inetd.

-K service     If compiled with --enable-kerberos5, this flag specifies
               the Kerberos service to use (same as the compile time
               KERBEROS_SERVICE define).  The default is "rcmd",
               although the use of "pop" is popular.

-p 0|1|2|3     Set clear text handling options when APOP is
               available: 0 is default (clear text passwords only
               permitted for users not in the APOP database); 1 means
               that clear text passwords are never permitted for any
               user (users not in the APOP database cannot login); 2
               means clear text passwords are always permitted (even
               if an APOP entry exists), which allows them to be used
               as a fallback; 3 means they are permitted on the local
               interface (127.*.*.*) only.

-R             Disables reverse lookups on client IP addresses.

-s             This enables statistics logging.  After each session
               ends, a statistics record is written to the log.
               This record looks like:
                   Stats: randy 0 0 1 385 randy.example.org 192.168.2.4
               Username----^    ^ ^ ^  ^          ^               ^
               Deleted msgs-----! ! !  !          !               !
               Deleted octets-----! !  !          !               !
               Msgs left on server--!  !          !               !
               Octets left on server---!          !               !
               Name of client machine-------------!               !
               IP address of client machine-----------------------!

-S             Enables server mode if --enable-servermode was not
               specified at configuration time.  See section SERVER
               MODE for details.

-t logfile     Enables debug logging if compiled (pass
               --enable-debugging to ./configure).  Output is written
               to the file specified as 'logfile'.  If this option is
               used, it should be first, so that debug records are
               generated for subsequent options.

-T timeout     You can change the compiled default for read 
               timeouts. This value causes qpopper to 
               terminate the connection with the client and 
               move the messages back to the user's maildrop
               if no input is received in this many seconds.

               The RFC states that this timeout should be 600 
               seconds (10 minutes). However, ideal settings 
               in many cases are between 30 and 120 seconds.

-u             Reads additional run-time options from a file named
               '.qpopper-options' in the user's home directory, if
               present.  See the following section "RUN-TIME OPTIONS
               (CONFIG FILE)" for option names and syntax.



4. RUN-TIME OPTIONS (READ FROM CONFIG FILE):
-------------------------------------------

You can set Qpopper run-time options either from
the command line or in a config file.

Config 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 / 
                     name-option

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

    name         ::= 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.

The following are the command line options you can use:

    OPTION NAME                     OPTION TYPE   R  EQUIVALENT SWITCH
    -----------------------------   -----------   -  -----------------
    announce-login-delay            Integer       F  -elogin_delay=xx
    announce-expire                 Integer       F  -eexpire=xxx
    bulldir                         Name          F  -b bulldir
    bulldb-nonfatal                 Boolean       F  -B
        Only valid if compiled with --enable-bulldb
    bulldb-max-retries              Integer       F  (none)
        Only valid if compiled with --enable-bulldb
    clear-text-password             Integer       T  -p0|1|2|3
    config-file                     Name          F  -f config-file
    debug                           Boolean       F  -d debug
        Only valid if compiled with --enable-debug.
    downcase-user                   Boolean       T  -c
    drac-host                       Name          F  -D drac-host
        Only valid if compiled with --enable-drac
    kerberos                        Boolean       T  -k
        Only valid if compiled with --enable-kerberos5 or F  -DKERBEROS
    kerberos-service                Name          T  -K service-name
        Only valid if compiled with --enable-kerberos5 or F  -DKERBEROS
    mail-lock-check                 Integer       F  -L msgs
    reverse-lookup                  Boolean       T  -R <Sense reversed!>
        Sense reversed from command-line switch.  Using '-R' is the
        same as 'SET REVERSE-LOOKUP FALSE'.
    server-mode                     Boolean       F  -S
    statistics                      Boolean       F  -s
    timeout                         Integer       F  -T timeout
    tracefile                       Name          F  -t logfile
        Only valid if compiled with --enable-debug.
    user-options                    Integer       T  -u



5. APOP:
--------

APOP is an alternate authentication method.  This is a secure
method to authenticate without passing the password in 
cleartext over the wire. Building this support to the server
would require DBM or GDBM libraries to exist on the system. 
GDBM is a GNU's version of dbm which can be obtained from any
of GNU's distribution sites.

To setup APOP - 
 *  Create a user account (example: "pop") to be used for 
   administering the APOP users. 
 *  Choose a location where popauth will place the authentication
   files (make sure this is read/write accessible only to the
   administering account ("pop").  Typically "/etc/pop.auth".
 *  Run configure script with the options --enable-apop and
   --with-popuid.

 e.g.,: ./configure --enable-apop=/etc/pop.auth --with-popuid=pop

   The first definition is the location of the authentication 
   files; the second specifies the administering account that 
   owns the authentication database.
 *  Run make, and this should produce executables "popauth" and
   "popper".
 *  Move the executables to a public location.
 *  Change the owner on popauth to administering account ("pop")
   and set SUID.

 e.g.,: chown pop popauth
        chmod u+s popauth

 *  Initialize the authentication database files by running the
   following command:

   popauth -init

 *  New users can be added by root or the administering ("pop")
   user with the following command:

        popauth -user <user>

   Or removed with the following command:

        popauth -delete <user>

   Any other user can add themselves or change their password 
   with the following command: 

        popauth

 *  Scripts or other non-interactive processes can add or change the
   password for a user with the following command:
   
        popauth -user <user> <password>



6. BULLETINS:
-------------

Bulletins can be used to send canned messages to all POP users.
Bulletins are placed as plain text files in a specified format 
under a directory known to the server.


6.1) To Enable Bulletins:
 *  Choose the directory where the bulletins reside.
    Typically "/var/spool/bulls".  The directory should be 
    readable with user privileges.
    
 *  Run the configure script with option --enable-bulletins.
    (In addition to any other options.)

    example: ./configure --enable-bulletins=/var/spool/bulls

 *  Running 'make' then produces the popper executable.
 
 *  Use the command line option -b to override the compiled
    value for the bulletin directory, if desired.

 *  If you want to use a central database instead of individual
    files in users' home directories to track which bulletins have
    been seen by which users, follow the instructions later in this
    section.
    


6.2) Writing Bulletins:
     Bulletins have to be placed as files in the BULLDIR 
     and the directory should be readable and the files 
     inside readable with user privileges.

     Readable file names can be chosen for bulletins 
     using the number.string form, for example, 
     00001.Bulletin_one, 00002.2hr_Downtime_2-4-95.
     Give each bulletin a unique and ascending order number.
     The number portion of the filename should be 1 + the largest
     bulletin number in directory. [Warning : Recycling the 
     bulletin numbers is not supported yet.]
     
     You can limit bulletins to certain groups by using the
     --enable-group-bulls flag with ./configure, and putting the
     group name as the second element in the bulletin file name.
     For example, the bulletin "001.staff.new_program_installed"
     would be seen only by members of the "staff" group.

     Bulletins must be in the same format as messages in the
     mail spool. For example: 

    -------------- start message -------------
    From qpop Wed Nov  9 13:31:08 1994
    Date: Wed, 9 Nov 1994 13:31:07 -0800 (PST)
    From: "POP Administrator" <postmaster@localhost>
    Subject: Example bulletin

    This is an example bulletin to demonstrate the format
    in which bulletins have to be written.  This message 
    is appended to the mailspool when the user checks 
    his/her mail.

    If you remove this file later on, it won't be seen by users
    who haven't checked their mail since you created this
    bulletin.

    Try to preserve the rfc822 header format, especially date
    format.  Failing which clients may not parse information 
    in headers correctly. 
    
    Allow a blank line between headers and message body.
    --------------- end message --------------

    Do not include the --- start message --- and 
    --- end message --- lines to your bulletin.


6.3) How bulletins work:
     During POP sessions, after user authentication, qpopper
     copies the bulletins placed in the BULLDIR to the users'
     message spool.  Qpopper figures out the last bulletin seen
     by the user by placing in the user's home directory a file
     called '~/.popbull'.  This file contains the number of the
     last bulletin seen by the user.  Any bulletin in the BULLDIR
     with a number greater than the one in '~/.popbull' is copied
     to the users message spool.
     
     A bulletin database can be used to track the bulletins instead
     of .popbull files in the users' home directory.  This feature is
     enabled by using the '--enable-bulldb=/var/spool/bulls' flag 
     instead of the '--enable-bulletins' flag with './configure'.
     This also requires creating two blank files called 
     BULLDIR/bulldb.pag and BULLDIR/bulldb.dir.  Qpopper must be able
     to link with either ndbm or gdbm.
     
     If you use the bulletin database feature, it reads old 
     '~user/.popbull' files if they exist (but does not update them).
     
     If you have a busy server, using a central database may impose
     concurrency issues: if too many users POP their mail at the same
     time, it may be difficult for some users to obtain write access
     to the bulletins database.  By default, this results in an error.

     If your system has the 'usleep' function, this is detected by the
     configure script, and should help the problem of multiple users.
     Even so, you may have a problem.  If you want to use a bulletin
     database anyway (to avoid problems with users who lack a home
     directory or who exceed disk quota for their home directory), you
     can adjust the bulletin database behavior with run-time options.

     Using the '-B' or 'bulldb-nonfatal' option allows the POP session
     to continue even if the bulletins database can't be opened.  As
     a result, your users will get their mail, but may not see some
     bulletins for possibly a long time, or even at all.

     You can also set the maximum times Qpopper tries to lock the
     database with the 'bulldb-max-retries' option.  When the database
     is in use by another user, Qpopper tries repeatedly to access it,
     pausing for an amount of time in between.  On systems with the
     'usleep' function, this amount of time is a small random number of
     microseconds (somewhere between 1 microsecond and .5 seconds),
     and the default value for 'bulldb-max-retries' is 75.  This
     usually results in a maximum delay well under a minute.  On
     systems without the 'usleep' function, Qpopper waits between one
     and 'bulldb-max-retries' seconds, which by default is 10.  This
     may result in a maximum delay under two minutes, but with far
     fewer attempts, and therefore less chance of success.  To see if
     your system has the 'usleep' function, try a 'man usleep' or do
     'fgrep USLEEP config.h' after running ./configure.  If you see
     '#define HAVE_USLEEP 1' then you have the 'usleep' function.
      

6.4) Maximum Bulletins for New Users
     New users receive all bulletins by default. You can specify
     the max bulletin value for new qpopper users.  Pass 
     '--with-new-bulls=10' to './configure' to give new users a 
     maximum of ten bulletins.



7. SERVER MODE:
---------------

7.1) To enable server mode:
    Server mode can now be enabled on a per-user basis.  You set
    the default for all users at compile time, and can override
    this with a new default at run-time.  You can cause specific
    users to either use or not use server mode, regardless of the
    defaults.
    
    To specify server mode as a default for all users at compile
    time, run the configure script, adding '--enable-servermode'.
    
    To specify server mode as a default for all users at run time,
    use the '-S' run-time flag or the 'server-mode' option in a
    configuration file.
    
    To indicate that users of a specific group should use server
    mode (regardless of the default), run the configure script,
    adding '--enable-server-mode-group-include=group', where
    'group' is the name of the group.  Users who are members of
    this group will use server mode.
    
    To indicate that users of a specific group should NOT use
    server mode (regardless of the default), run the configure
    script, adding '--enable-server-mode-group-exclude=group',
    where 'group' is the name of the group.  Users who are members
    of this group will NOT use server mode.
    
    To set server mode on or off for a specific user, place a
    file called '.qpopper-options' in the user's home directory,
    use the "server-mode" option in this file, and use the '-u'
    command-line flag or include the 'user-options' option in a
    config file.
    
    The determination of server mode is thus (in order):
        1.  Compile-time default (--enable-server-mode).
        2.  Run-time default ('-S' or 'server-mode').
        3.  Compile-time inclusion group 
            (--enable-server-mode-group-include=group) that
            user is a member of.
        4.  Compile-time exclusion group 
            (--enable-server-mode-group-exclude=group) that
            user is a member of.
        5.  User's '.qpopper-options' file.

7.2) When to use server mode: 
    This mode of operation is specifically designed to work with 
   POP accounts only.  Use this mode for better throughput from the
   server when there is a huge user base to the server.  Read all
   the sections about server mode before enabling.

7.3) Bottleneck in normal mode:
    In the default mode, the server after authentication copies the 
   mail in users' message spool to a temporary file (.user.pop).
   When the user terminates the session the undeleted messages are
   moved back to the message spool.  When users download all
   messages and delete them from the server (which is commonly
   done by most sites and clients) in every session, the server need
   not copy the message spool to the temporary file.  This is also
   true for users who leave all their mail on the server and do 
   occasional mailchecks. For large pop servers, the extra IO
   processing can be a performance problem. SERVER-MODE is available
   to improve the performance of the mentioned users (that is, either
   deleting all messages or no messages).

7.4) Server Mode Operation:
    Enabling SERVER_MODE assumes that the other program that writes
   to the message spool is the delivery agent.  In server mode, the 
   mailspool is locked, scanned, and then unlocked.  Qpopper assumes
   that new messages are only be appended to the mailspool, and 
   existing messages will not be altered.  After retrieving messages, 
   qpopper checks for any remaining messages (undeleted messages) for 
   status and UID updates.  If there are any changes, it updates the 
   mailspool.

7.5) Benefits of Server Mode:
    The benefit of using this mode is that the mailspool is not
   copied to the temporary spool area unless mail is left on 
   the server, and when messages are read and/or deleted.  The 
   NO_STATUS flag causes qpopper to ignore the Status header and 
   recalculates the UID each time the mailspool is run.  When new 
   messages are read, the new UID and Status headers are not updated 
   and no copy of the mailspool is done.  
    
   In server mode, if all messages are deleted, then the 
   mailspool is truncated (unless new messages have arrived).  
   The initial copy is not processed, and IO cycles are saved.  



8. STANDALONE MODE:
-------------------

Normally, Qpopper is launched from inetd (or similar program).  You
can build a version of Qpopper which operates as a standalone daemon
if you prefer.  Use the '--enable-standalone' configure option.  You
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 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.

While standalone mode may offer better performance than using inetd,
be aware that you may lose capabilities such as load throttling,
address filtering, etc.



9. MACROS:
----------

There are options to consider when doing a build.  If you 
want to change any of the default settings, edit config.h
after running './configure'.  To set a macro, add a '#define'
line.  For example, to set macro 'FOO', add '#define FOO'.

The most useful of these can be set by passing an appropriate
flag (e.g., --enable-debugging) to ./configure, which is the
recommended way.

a) MMDF_SEP_CHAR -- Default is '\001' (<CTL>-A).  
A line that starts with this character is 
considered an MMDF separator.  The rest of the 
line is copied as the separator regardless of its 
value.

b) BULLDIR -- Is the compiled value as opposed to 
the command line option that enables bulletins. 
You can specify this value by adding
'--enable-bulletins=/var/spool/bulls' to ./configure.
This makes bulletins the default regardless of the 
command line options.  See section BULLETINS for
instructions and details.

Using '--enable-bulldb=/var/spool/bulls' with 
./configure uses an ndbm or gdbm database to track
bulletins sent to pop users.  If you use this feature,
it reads the old ~user/.popbull files if they exist. 
You must create two blank files in /var/spool/bulls
called bulldb.pag and bulldb.dir.

c) NEWBULLCNT -- New users receive all bulletins 
by default. This value reduces the max bulletin 
value for new qpopper users.  Pass 
'--with-new-bulls=10' to give new users a maximum
of ten bulletins.  See section BULLETINS for
instructions and details.

d) OFF_T -- If "off_t" is not typedefed for you, 
then set this definition to a type that lseek and 
ftruncate and expect it as an offset parameter.
UID_T, GID_T, and PID_T are also available for 
portability.

e) BLOCK_UID -- This value protects mailboxes of 
all UIDs, at and below, from being accessed via 
qpopper.  The default value is 10 meaning 
that root and other users with UID values of 10 
and under are not able to login via qpopper.

f) POP_FACILITY -- Specifies the log facility.
Default is LOG_LOCAL1 or LOG_MAIL, depending on
the OS.  Pass --with-log-facility=name to
./configure to change.

g) KERBEROS -- To use Kerberos V libraries, pass
'--with-kerberos5' to ./configure.  Or, define
this value and KRB4 if you want to use Kerberos IV
libraries.  For Kerberos IV you must also update 
the makefile so you can load the appropriate 
libraries(-lkrb).  This option works only if you 
have Kerberos headers and libraries installed.

Pass '--enable-kuserok' to ./configure if you want to
use the kuserok() function to vet users.

Pass '--enable-any-kerberos-principal' if you want to
accept any Kerberos principal in the client request.

Pass '--enable-ksockinst' if your system has the
getsockinst() function.   It gets the IP address of the
local end of a connection and looks up the host name and
uses that for the Kerberos instance.  This allows using
different instances for different virtual addresses on
the same machine.

You can also define KERBEROS_SERVICE to specify which
Kerberos service to use, the default is "rcmd", but
the use of "pop" is common.  The '-K service' run-time
flag can be used instead of the KERBEROS_SERVICE
define.

You can remove KRB5_KRB4_COMPAT from config.h if you are
using the Kerberos V libraries and want to disable
backwards compatibility with a Kerberos IV server.

Define NO_CROSSREALM if desired.

h1) AUTHFILE -- Define this value to specify a 
file which allows only users listed in the file 
to have qpopper access.  Use --enable-auth-file=file
flag with ./configure.  The format is a list of
user IDs, one per line.

h2) NONAUTHFILE -- Define this value to specify 
a file which excludes listed users.  Use the
--enable-nonauth-file=file flag with ./configure.
The format is a list of user IDs, one per line.

i) SPEC_POP_AUTH -- Define this value if your system 
supports special authorization mechanisms like 
shadow passwords or special crypt programs. 
Usually you can use the '--enable-specialauth'
flag to './configure' and all will work.  Note
that on certain systems you do not need this flag in order
to use shadow passwords, and using the flag may results in
compilation errors such as "undefined symbol: auth_user".

j) RPOP -- This feature allows the pop client to 
use the hosts.equiv and .rhosts files for 
system/user validation.  This feature is not 
recommended since it can spoof both a PC or Mac 
system.

k) SECURENISPLUS -- Add this definition if you are 
running secure NIS+; that is, when the qpopper 
server cannot access a user's encrypted password.
Configure flag: --enable-secure-nis-plus.

l) DEBUG -- Verbose logging requires the -d 
command line argument to enable.  Enable this if you
are having problems figuring out why qpopper is not
working.  Remember that it generates a lot of output,
and log files on busy systems expand quickly.
Configure flag: --enable-debugging.
        
m) SETPROCTITLE -- This definition controls 
whether setproctitle() should be used to display 
user, host, and status in the process title.  
Your OS must support this feature.

n) KEEP_TEMP_DROP -- Keep the .user.pop file.  It 
can determine the last time a user has accessed 
his/her mail.

o) BIND43 -- BSD 4.3 is a domain name service.

p) SYSLOG42 -- The QUALCOMM qpopper defaults to 
BSD 4.3 syslog.

q) HOMEDIRMAIL -- If mail is spooled into the
user's home directory, define this macro to be
the correct file name for your system.  Configure
flag: --enable-home-dir-mail=Mailbox.

r) APOP="/etc/pop.auth" -- This value is the 
location of the authorization database.  Users 
found in this DB may not use user/pass 
authentication (since they are found in the apop 
database) unless you use the '-p' run-time flag to
authorize it.  See section APOP for instructions and
configure flag.

s) POPUID="pop" -- This value is the username of 
the owner of the apop database.  See section APOP
for instructions and configure flag.

t) GNUPASS -- This definition specifies the use of 
the (modified) GNU getpass routine which allows 
longer than 8 character passwords to be entered 
when using popauth. There is also a definition 
within popauth (NO_GETLINE) if you compile this 
code, and it complains of not having a getline 
routine.

u) CONTENT_LENGTH -- If your MTA (Mail Transport 
Agent) inserts a Content-Length header into the 
message, you must define this option.  This is
usually set automatically.

v) SERVER_MODE -- See SERVER MODE section for 
details and configure flag.

w) NO_STATUS -- Do not update the status Header of 
the message and do not store the UID in the 
message header.  This forces the UID for every message
to be recalculated in each session.  Configure flag:
--disable-status.

x) NOUPDATEONABORT -- By default, qpopper enters 
update state on session abort. This flag causes 
qpopper to ignore any changes (deletions) if the 
qpopper session is aborted.  Note that RFC 1939,
section 6 (et al) prohibits the qpopper default
behavior, but experience showed that otherwise
users on noisy lines were often unable to delete
their mail.  Define this macro to inhibit the
default behavior, and obey RFC 1939.  Configure
flag: --disable-update-abort.

y) HASH_SPOOL=(1|2) -- Mail is deposited into the 
mailspools by either (1) hashing the first 4 
characters or (2) by using mailspools in 
directories as in the following:  /<1st 
letter>/<2nd letter>/file.  For example, if the
spool directory is "/var/mail", the spool file for
user "maida" would be:
   /var/mail/maida          HASH_SPOOL not set
   /var/mail/o/maida        HASH_SPOOL=1
   /var/mail/m/a/maida      HASH_SPOOL=2

Use the --enable-hash-spool configure flag to set
this.

z) BULLDB -- Use a central database located in the 
bulletin directory instead of a user's home 
directory.  This feature uses the user's .popbull 
file the first time for backwards compatibility.  
BULLDBDIR can be defined in the makefile if an 
alternate location for the bulletin database is 
desired.  See section BULLETINS for more
information and the configure flags.

aa) CHECK_SHELL -- Enable this compile time feature 
to lock out users via the shell value.  A user 
shell of /POPPER/ANY/SHELL allows the user 
access but blocks other programs that check 
shells.
        
ab) GDBM -- This value uses the GNU GDBM library 
instead of NDBM.

ac) _DEBUG -- This permits popper to be run from a shell,
for hard-core and heavy debugging.

ad) LOG_LOGIN -- When set to 1, qpopper logs successful
authentications.  This can be useful, for example, to
permit subsequent SMTP sessions from the same IP address
within a short time period, in the absence of SMTP AUTH
support in your SMTP clients and server.  Configure flag
is --enable-log-login.

ae) AUTO_DELETE -- When defined, qpopper automatically
and unconditionally deletes messages that have been
downloaded using the RETR command (the normal command for
accessing messages).  CAUTION: this could result in lost
mail.  Be sure to inform your users that this will be in
effect before enabling this.  Also, the NOUPDATEONABORT
flag must also be defined.  Use the configure flag
--enable-auto-delete to set both flags. 

af) SHY -- Define if you don't want qpopper to display its 
version in the banner or CAPA INPLEMENTATION response of
unauthenticated users.  Some people feel this makes qpopper
more secure, since it avoids advertising if you are running
aversion which has a known vulnerability.  Others feel it is
counter-productive, since it also avoids advertising if you
are running a known-fixed version, and may lead attackers to
simply try exploits they otherwise would avoid.  Configure
flag: --enable-shy.

ag) USE_PAM -- Define to use PAM for authentication.  The
service name is "pop3".  Configure flag: --enable-pam=service
name.

ah) TRACE_MSG_BODY -- Define to include message bodies in
trace information written with -t or -d run-time flag.



NOTES:

1) Qpopper uses /etc/passwd to validate the userid for any user 
   in any mode (user/pass, kerberos, apop, authuser, nonauthuser).  
   The reason being that the mail spool file must be owned by 
   someone, and ownership relationships live in /etc/passwd.  So, a 
   user name must exist in both the passwd file as well as any of 
   the other files associated with other authentication methods.

2) When qpopper runs, it moves your mailspool to a 
   temporary location (.user.pop).  The default location 
   is the mail spool directory.  /tmp is an 
   alternative but is considered to be a security risk.  A 
   system reboot usually clears the temporary .user.pop 
   files.  For performance reasons, a sysadmin who has 
   1000+ users can create a separate spool directory for 
   qpopper files; /usr/spool/poptemp is preferable.  You
   can do this by using the --enable-temp-drop-dir flag
   when running ./configure.  Permissions should be the 
   same as your mailspool with the same owner and group.

3) In the mail spool directory, some systems have 
   symbolic links from /usr/mail to /usr/spool/mail. Make 
   sure you check this before installing qpopper.

4) Your spool directory needs to have ownership and permissions
   set correctly.  Normally, this directory has owner 'root'
   and group 'mail', and is set 'drwxrwxr-x' or 'drwxrwxrwt'.
   (The second form sets the sticky bit to prevent non-owners
   from deleting or renaming files.)

   By default, Qpopper sets its group ID to the group of the
   spool directory before setting its UID to that of the user.
   Thus, by making the spool directory group 'mail' and making
   it group writable, Qpopper is able to create and modify the
   user's spool and the dot-lock file.  Since no users are
   part of the 'mail' group, this is secure.

5) Do not use qpopper over NFS. 

6) OS-Specific notes:

   SCO -- Some versions of SCO use the crypt_d library, others 
   the crypt_i library.  This distribution assumes crypt_d. SCO
   requires loading the Standard and TCP/IP development 
   environments to get the sockets and crypt libraries.

   Also, if you wish to use the elf binaries (to use dynamic
   instead of static linkage for C run-time functions), you need
   to edit the Makefiles so that the LIBS line is: 
           -lnsl -lsocket -lcrypt -lprot -lm -lx -ltinfo
   and the CFLAGS line has "-s -O -belf".  (-s means strip the 
   symbols (you can omit this if you choose),  -belf means use elf 
   binaries.)

   IRIX -- The default spool directory is /usr/mail; some 
   systems use /usr/spool/mail.

   FreeBSD -- This requires the crypt library for password 
   comparisons.   

   OSF/1 -- If you are not using enhanced security (shadow 
   passwords), then don't use --enable-specialauth.  Otherwise, you 
   receive a link error stating that set_auth_parameters() is 
   not defined.

   A/UX -- A/UX does not support the sticky bit, so the default 
   dir is /tmp.  If you want to support shadow passwords, you 
   need to use --enable-specialauth with ./config.  A shadow 
   passwd library is also required.  You can find one on
   jagubox.gsfc.nasa.gov.  A/UX requires gcc and libUTIL.a,
   also available on jagubox to build this version of qpopper.

   ISC -- APOP does not work because the port was installed on a 
   system without dbm.  If you want to use APOP, then get a 
   working dbm library, change the link line, and add the APOP 
   definitions.

   SUNOS -- Some systems don't seem to have strerr defined in 
   the default location.  You may need to use the alternate 
   CFLAGS to compile correctly.

   NCR -- You may need to increase STRTHRESH, for example, a 600 
   user system needs to increase from 0x200000 to 0x600000.

   Next -- You should probably use NetInfo Manager available 
   under Next Admin to change your services file.

7) Bulletins -- The From line must be complete with address and 
   date.  If qpopper can use full From lines, then a simple 
   "From" line causes the message to get concatenated to the 
   previous message.

8) "-no-mime" user name hack --  As a way to enable MIME-mangling
   (reduce multipart MIME messages to a single text part, no
   attachments) 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".



DEBUGGING:

The first step in troubleshooting qpopper is to try and
telnet in to it.  Generally, the easiest way to do this
is to telnet from the host where you just installed
qpopper to itself.  You need to specify the POP3 port
in the telnet command.  So, if you just installed 
qpopper on a host called "penguin", enter the following
command (without the quotes): "telnet penguin pop3".

INETD is not servicing the POP port if you receive one of 
the following error messages:

    1. "connect: Connection refused"

    2. "connect: Connection closed"
        
If you receive message 1, check your services file and make 
sure the port name "POP3" is exactly the same as the one in 
inetd.conf.  Also, it can indicate that you have not reset 
inetd (kill -HUP <inetd PID>) (some systems can use inetd -c). 

If you receive message 2, this indicates that inetd has the 
correct port assigned to qpopper, but that either the
program cannot be located, or it is failing on startup.  If 
you are compiling with a listed OS, chances are the POP 
program is not named correctly in the /etc/inetd.conf file.  
Otherwise, add the -d flag and check your log messages for 
the source of the problem.  It may also be the case that you
have duplicate port numbers assigned in /etc/inetd.conf.  This
is often indicated by a log entry containing the error message
"address already in use."

A tip to check that you have the Qpopper executable correctly
listed in inetd.conf is to find the line in an editor, then
copy the text specifying the executable path, then go to a
command prompt and type 'ls -l ' and paste in the text.  For
example, in the inetd.conf line:
   pop3    tcp     /usr/local/lib/popper    qpopper -s
copy this:         ^^^^^^^^^^^^^^^^^^^^^


If you are unsure where your log is located, try /var/log/, and
if you still can't find it, see if you have a file called
/etc/syslog.conf, and if so, look inside.

If you have correctly installed qpopper as far as inetd 
is concerned, you will see the following line, which is 
the POP banner or greeting:

+OK QPOP (version 3.1) at <system> starting. <13625.811191280@system>

Now, you need to enter two commands to authenticate yourself 
to qpopper and gain access to your mail. Make sure you have a message 
or two queued so you can ensure that qpopper is pointing 
at the correct mail spool file.  Be aware that the password 
is echoed back: 

    you type:    user <your user name here>
    you see:     +OK Password required for <your user name here>
    you type:    pass <your password here>
    you see:     +OK mark has 2 message(s) (4123 octets).

If you have the authority and if you have two messages, you 
can enter QUIT to exit.  LIST and UIDL are two commands to 
list messages by size and ID.  At this point, Eudora or any 
other pop client should not have any problems communicating 
with your Qpopper.


If you see the message:
   Unable to process From lines (envelops), change recognition modes

it indicates that your mailbox is corrupted; that is, the 
first line which includes the From header or MMDF separator 
is not recognizable.  Or there may be a From line displayed 
that has never appeared before.  Edit the mail spool file 
and examine the first line.  If the first line is blank, then 
remove it until you reach the From line.


If an error message displays indicating that your password 
is incorrect, you might be using a shadow password, and you 
may need to use the --enable-specialauth flag when running
configure (after doing a make clean).  Or, you might be 
using a UID less than 11 (default) which is automatically 
blocked from access.


Check the Qpopper Frequently Asked Questions (FAQ) page
at <http://www.qpopper.org/faq.html> for more 
trouble-shooting tips.










