
	Last update: 4/27/95 (Mark Erikson)

SECTIONS:
	MAKE
	NOTES
	INSTALL
	DEBUGGING
	RUNNING

MAKE:
        To install the popper you need to determine which OS is supported
    and run the appropriate make command.  Just run make for the list of
    available builds.

        There are a few options to consider when doing a build.

	1) popper.h - There are some defines you may want to change

	    a) MMDF_SEP_CHAR - Default is '\001' (<CTL>-A).  A line
			    which starts with this character is considered
			    an MMDF separater.

	    b) BULLDIR - Compiled value as opposed to the command line
			    option.  Does the same thing, enables bulletins.
			    You can also specify this value in the make
			    file -DBULLDIR=/var/spool/bulls.

	    c) NEWBULLCNT - Amount to reduce max bulletin value for
			    new popper users (users without .popbull files).

	    d) OFF_T - If "off_t" is not typedefed for you then set this
		       define to a type that lseek and ftruncate expect
		       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 by the popper.  The
			   default value is 10 (just because).

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

	    a) KERBEROS - Define this value if you want to build a
			    kerberos IV only pop server.

	    b1) AUTHFILE - Define this value to the file you want that
			   only allows users listed in the file to have
			   popper access.  Ex: -DAUTHFILE=\"/etc/authfile\"

	    b2) NONAUTHFILE - Define this value to the file you want that
			      does not allows users listed in the file to
			      have popper access.
			      Ex: -DAUTHFILE=\"/etc/nonauthfile\"

	    c) AUTH - Means that your system supports special authorization
			    mechanisms like shadow passwords or special crypt
			    programs.  The make files have been setup for this
			    as best as I can tell.  SunOS4.x does not support
			    this by default since it requires the C2 code to
			    be loaded which is not done by default.  If you
			    support shadow passwords on SunOS4.x then define
			    SUNOS4 and AUTH in the make.sunos makefile.

	    d) RPOP - This feature allows the pop client to use the hosts.equiv
			    and .rhosts files for system/user validation.
			    This feature is not recommened since it is far
			    to easy to spoof a system on a PC or a Mac.

	    e) DEBUG - Verbose logging (requires -d switch).  Only enable
			    this if you are having problems figuring out
			    why popper is not working.
	    
	    f) KEEP_TEMP_DROP - Keep the .user.pop file around.  It can be
			    used to determine when the last time a user has
			    accessed their mail.  Use in conjunction with
			    LARGESITE.

	    g) LARGESITE - Reduce logging from notification and error to just
			    errors.  This way log files are not cluttered with
			    general traffic info.

	    h) MAILOCK - If your system supports SYSV file locking, define
			    this value.

	    i) BIND43 - BSD 4.3 domain name service.

	    j) HAVE_VSPRINTF - If the vsprintf functions are available on
			       your system.

	    k) STRDUP - Define if your system does not support the strdup()
			library call.

	    l) STRNCASECMP - Define if your system does no support the
			     strncasecmp() library call.

	    m) SYSLOG42 - The Qualcomm popper defaults to BSD 4.3 syslog.

	    n) SYSV - All SVR4 systems define this value.

	    o) BINMAIL_IS_SETGID - If /bin/mail on your system is setgid
				   then you should define this value.

	    p) HOMEDIRMAIL - Define this if mail is spooled into the users
			     home directory.  Check the macro and sprintf
			     statement to make sure the location is correct
			     for your system.

	3) Temporary pop files are placed in the mail spool directory by
	   default.  /tmp is consider to be a security risk and a system
	   reboot will probably clear the temporary .user.pop files.  You
	   may want to change the value of POP_DROP, POP_TMPDROP, and
	   POP_TMPXMIT in the popper.h file.  Many sysadmins who have many
	   users (say 200 or more) create a separate spool directory for
	   popper files.  /usr/spool/poptemp would be a good choice.
	   Permissions should be 1777 (drwxrwxrwt) on the directory.

	4) Mail spool directory.  Some systems have symbolic links from
	   /usr/mail to /usr/spool/mail.  Some don't.  I've tried to guess
	   at which OS uses /usr/man and which uses /usr/spool/mail.
	   Sometimes I guess wrong.  Make sure you check this before
	   installing.

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 in order to get the sockets and crypt libraries.

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

	FreeBSD - Requires the crypt library for password comparisons.
	          Check the FreeBSD.crypt file in the doc directory for
		  locations nearest you :-)

	OSF/1 - If you are not using enhanced security (shadow passwords)
		then turn off the AUTH define.  Otherwise, you will receive
		a link error stating that set_auth_parameters() is not
		defined.

	A/UX - A/UX does no support the sticky bit so the default dir is
		/tmp.  If you want to support shadow passwords, you need
		to add the -DAUTH define into make.aux.  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, build this version of popper.

	BSDi 2.0 - Requires that sys_errlist[]; be commented out on line
		41.  As soon as I get a copy of 2.0 I'll find a nicer
		way to have this code skipped.

	Bulletins - The From line must be complete with address and date.
		    If the popper has determined that it can use full From
		    lines then a simple "From " line will cause the message
		    to get concatenated to the previous message.

INSTALL:
	After running make on the appropriate OS, you need to move the
    popper to a known location.  There is no one correct place.  Many
    sysadmins prefer /usr/local/lib.

	Modify your /etc/inetd.conf file to contain the following line.
    You may have to modify it to support your version of the file:

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

	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/etc/popper	popper -s

	For all OS version you must modify your /etc/services file to
    include the following line.

pop3            110/tcp                         # Post Office

	Restart inetd with a kill -HUP <inetdpid> and you should be all
    set.

DEBUGGING:
	Telnet to the popper port "telnet <popper host> pop3".  If you
    receive one of the following error messages

    "connect: Connection refused"
	    This message is telling you that inetd is not servicing the
	pop port.  Check your services file and make sure the port name
	"pop3" is spelt the same way as the one in inetd.conf.  It can
	also mean that you have not reset inetd (kill -HUP <inetd PID>)
    
    or 

    "connect: Connection closed"
	    or similar messages indicate that inetd has the correct port
	assigned to the popper, 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 mis named in
	the /etc/inetd.conf file.  Otherwise, add the -d flag and check
	your log messages for the source of the problem.

	What you are looking for is the startup banner.  If you see the
    following line then you have correctly installed the popper as far
    as inetd is concerned.

	"+OK UCB Pop server (version 2.1.3-R1) at <system name> starting."

	Now you need to run two commands to authorize yourself.  You
    should make sure you have a message or two queued up so you can
    make sure the popper is pointed at the correct mail spool file.
    Don't be alarmed, the password is echoed back, that's the way it
    is suppose to work:

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

	You have successfully authorized yourself.  You have two messages.
    At this point you can enter "quit" to exit.  list and uidl are two
    commands to list out each message by size and unique ID respectively.
    If you get this far Eudora or any other pop client will not have a
    problem communicating with your popper.


RUNNING:

	There are a couple of command line options you may want to use.

	-b bulldir	- Location of the bulletin directory.  The command
			  line will override the compiled in value if it
			  is defined.  Human readable file names can be
			  created in the form of number.string (eg:
			  00001.Bulletin_one, 00002.2hr_Downtime_2-4-95).

	-d		- Enable debug logging if it has beem compiled in.

	-s		- Enable statistics logging.  Works even when the
			  LARGESITE define is set.

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

	-T timeout	- Change the compiled default for read timeouts.
			  120 seconds seems to be more than long enough.
			  30 seconds is a little short but acceptable for
			  many sites.  This value will cause the popper
			  to terminate the connection with the client and
			  move the messages back to the users maildrop.

