INSTALL 

Last updated: 28 April 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. RUN-TIME OPTIONS (COMMAND LINE OPTIONS).
    3. CONFIGURE OPTIONS.
    4. APOP
    5. BULLETINS
    6. SERVER MODE
    7. 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).

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 uses 
the config file /etc/servers.  Use the following line:

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

For all OS versions you must modify, 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, the commands 
displayed below may work for you.  First you need to import 
the new inetd.conf file, and then you need to re-init inetd.  
Use the following commands:
        inet imp
        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.




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

The following are the command line options you can use.

popper [-b bulldir [-c] [-d] [-e login_delay=nn,expire=nn]
       [-k] [-s] [-t trace-file] [-T timeout] [-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.)

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

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

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

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

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

-t logfile     If debug and trace files are defined, output 
               from logging goes to the trace file instead of 
               syslog.

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

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




4. 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(for eg:"pop") that would be used for 
   administering the APOP users. 
 *  Choose a location where APOP would place the authentication 
   files (Make sure that would be read/write accessible only to 
   the administering accoung("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 
   will own the authentication database.
 *  Run the 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



5. 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 the server.


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

    eg: ./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.


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

     Readable file names can be choosen 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 
    will be 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, esecially 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.


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

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



6. SERVER MODE:
---------------

6.1) To Enable Server mode:
  * Run the configure script with option --enable-servermode.
   and the rest is the same.

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

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

6.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 will 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.

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



7. MACROS:
----------

There are options to consider when doing a build. If you 
want to change any of the default settings, make the 
appropriate changes to the Makefile while reading this 
document.  The most useful of these can be set by passing
an appropriate flag (e.g., --enable-debugging) to ./configure.

1) popper.h or config.h -- There are some macro definitions
you may want to change.  Most of these can be set using
./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 "5. 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 "5. 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 will not be able to login via the 
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.

2) Makefile -- The makefile for your OS is setup for 
the most common defaults. Below are some values you 
may want to modify.

a) KERBEROS -- Define this value if you want to 
add Kerberos IV support to the server.  Update 
the makefile so you can load the appropriate 
libraries(-lkrb).  This option works only if you 
have Kerberos headers and libraries installed.  
You can also define KUSEROK if you want to use 
the kuserok()function.

b1) AUTHFILE -- Define this value to reference the 
file which allows only users listed in the file 
to have qpopper access.  
Ex: -DAUTHFILE=\"/etc/authfile\"
The format is a list of user id's, one per line.

b2) NONAUTHFILE -- Define this value to reference 
the file which excludes listed users.
Ex: -DNONAUTHFILE=\"/etc/nonauthfile\"
The format is a list of user IDs, one per line.

c) 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, such as BSD, you do not need
this flag in order to use shadow passwords, and using
the flag results in compilation errors such as "undefined
symbol: auth_user".

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

e) SECURENISPLUS -- Add this definition if you are 
running secure NIS+; that is, when the qpopper 
server cannot access a users encrypted password.

f) DEBUG -- Verbose logging requires the -d 
command line argument to enable.  Enable this only 
if you are having problems figuring out why qpopper 
is not working.  Log files on busy systems expand 
quickly.  Configure flag: --enable-debugging.
        
g) 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.

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

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

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

k) HOMEDIRMAIL -- If mail is spooled into the
user's home directory, define this macro to be
the correct file name for your system.

l) 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).  See section "4. APOP" for instructions
and configure flag.

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

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

o) CONTENT_LENGTH -- If your MTA (Mail Transport 
Agent) inserts a Content-Length header into the 
message, you must define this option.

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

q) NO_STATUS -- Do not update the status Header of 
the message and do not store the UID in the 
message header.

r) 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,

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

t) 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 "5. BULLETINS" for more
information and the configure flags.

u) 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.
        
v) GDBM -- This value uses the GNU GDBM library 
instead of NDBM.

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

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

y) AUTO_DELETE -- When defined, qpopper will automatically
and unconditionally delete 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. 

z) SHY -- Define if you don't want qpopper to display its 
version in the banner or CAPA INPLEMENTATION response.  Many 
people feel this makes qpopper more secure, since it avoids 
advertising if you are running a version 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.

aa) USE_PAM -- Define to use PAM for authentication.  The
service name is "pop3".

ab) 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, and the 
startup banner is displayed:

+OK QPOP (version 3.0) 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.










