INSTALL 

Last update: 09/12/97

This document is updated between releases.  So please read 
it each time you download a new version of Qpopper.  If you 
have any questions or issues, please contact: 
qpopper@qualcomm.com.

To add a new feature, please read all the sections listed 
below.

SECTIONS:
	INSTALLATION 
	CONFIGURE & MAKE
	NOTES
	DEBUGGING
	RUNNING
	BULLETINS
	SERVER MODE
	APOP

INSTALLATION:
To install the qpopper, change the directory to where the 
sources of qpopper are located and run the following 
commands. 
	./configure
	make
This makes the popper and popauth for your 
Operating system. Although there is no required location, 
many sysadmins prefer /usr/local/lib. 
Modify your /etc/inetd.conf file to contain the line below. 
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/qpopper	qpopper -s

For all OS versions you must modify, your /etc/services file 
needs to include the following line:
pop3         110/tcp                # Post Office

Restart inetd with a kill -HUP <inetdpid>(some systems can 
use inetd -c).
    
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.

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. Please report 
any problem to us at: qpopper@qualcomm.com. 

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.

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

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 also specify this value in the makefile 
DBULLDIR=\"/var/spool/bulls\". This makes
bulletins the default regardless of the command 
line options.  The option -DBULLDB uses
an ndbm or gdbm database for tracking bulletins 
sent to pop users.  If you use this feature, it 
will read the old ~user/.popbull file if it 
exists. -DBULLDB requires two blank files with 
the name of BULLDIR/bulldb.pag and 
BULLDIR/bulldb.dir to be created.

c) NEWBULLCNT - New users receive all bulletins 
by default. This value reduces the max bulletin 
value for new qpopper users.

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

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 id's, one per line.

c) AUTH - Define this value if your system 
supports special authorization mechanisms like 
shadow passwords or special crypt programs. 
Qpoppers makefiles support this feature. 
SunOS4.x does not support this by default, since 
it requires the 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 
Makefile. You may have to port a pop_pass routine 
for your OS before enabling this feature.

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 
commandline argument to enable.  Enable this only 
if you are having problems figuring out why the 
qpopper is not working.  Log files on busy 
systems expand quickly.
	    
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 - Define this value if mail is 
spooled into the users home directory.  Check 
the macro and the sprintf statement in 
pop_dropcopy.c ensuring the is correct 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 if they are found in the apop 
database.

m) POPUID=\"pop\" - This value is the username of 
the owner of the apop database.

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.

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, the qpopper  
enters the update state on abort. This flag 
causes the qpopper to ignore any changes 
(deletions) to occur if a qpopper session is 
aborted.

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.

t) BULLDB - Use a central database located in the 
bulletin directory instead of a users home 
directory.  This feature uses the users .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.

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

3) When qpopper runs, it moves your mailspool to a 
temporary location (.user.pop).  The default location 
is in 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. 
Permissions should be the same as your mailspool with 
the same owner and group.

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

5)  Do not use qpopper over NFS. 


NOTES:

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

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.

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

FreeBSD - This requires the crypt library for password 
comparisons. Check the FreeBSD.crypt file in the doc 
directory for the appropriate locations.

OSF/1 - If you are not using enhanced security (shadow 
passwords), then turn off the AUTH define. 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 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 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.

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

DEBUGGING:
Telnet to the qpopper port "telnet <qpopper host> 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 the qpopper, but that either 
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.

If you have correctly installed the qpopper as far as inetd 
is concerned, you will see the following line, and the 
startup banner is displayed:

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

Now, you need to run two commands to give yourself 
authorization to run qpopper. Make sure you have a message 
or two queued so you can ensure that the qpopper is pointing 
at the correct mail spool file.  Be aware that the password 
is echoed back: 

  	user <your user name here>
    	+OK Password required for <your user name users>
    	pass <your password>
    	+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 get the following message: Unable to process From 
lines (envelops), change recognition modes.

This 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 send 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 -DAUTH definition. Or, you might be 
using a UID less than 11 (default) which is automatically 
blocked from access.


RUNNING:

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

-b bulldir	- This is the location of the bulletin 
directory.  The command line will override the 
compiled value if it is defined.  Readable file 
names can be created using the number.string 
form, for example, 
00001.Bulletin_one,00002.2hr_Downtime_2-4-95. A 
bulletin database can be used to track the 
bulletins instead of the users home directory. 
This feature is enabled with -DBULLDB during 
compilation. -DBULLDB requires two blank files 
including the name of BULLDIR/bulldb.pag and 
the creation of BULLDIR/bulldb.dir.

-d	- Enables the debug logging if compiled.

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

-s	- This enables statistics logging.  

-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 the qpopper to 
terminate the connection with the client and 
move the messages back to the users maildrop 
The RFC states that this timeout should be 600 
seconds (10 minutes). However, ideal settings 
are between 30 and 120 second.


BULLETINS:

	Bulletins are in the following format:

-------------- start message -------------
>From mark Wed Nov  9 13:31:08 1994
Date: Wed, 9 Nov 1994 13:31:07 -0800 (PST)
From: "Mark Erikson" <mark@qualcomm.com>
Subject: test bulletin

This is a test bulletin.  This message will be appended to 
the end of the mailspool when the user logs into the 
qpopper.

Note that you should modify the From: and Subject: headers 
and as well as the Date: header.

--------------- end message --------------

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


SERVER MODE:

This mode of operation is specifically designed to work with 
POP accounts only.

The default mode of the qpopper is to move the mailspool to 
a temporary location.  This keeps other mail programs from 
modifying the mailspool while a pop session is active. When 
complete, the mailspool is moved back to the spool directory 
if there are any messages left.  This process is wasteful if 
you never keep mail on the server, or if you leave mail on 
the server and do occasional mailchecks.  For large pop 
servers, the extra IO processing can be a performance 
problem.  This is the reason SERVER MODE was created.

Enabling SERVER_MODE assumes that only /bin/mail and qpopper 
are accessing the mail spool. In server mode, the mailspool 
is locked, scanned, and then unlocked.  The qpopper assumes 
that only new messages will be appended to the mailspool.  
After retrieving messages, the qpopper checks for any 
remaining messages (undeleted messages)for status and UID 
updates. If there are any changes, it updates the mailspool.

	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 the 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.  
Small sites need not use this feature of the qpopper.


APOP:

APOP is an alternate authentication method.  It is able to 
authenticate without passing the password in cleartext over 
the wire.

To enable this feature, you need to define the following 
compiler definitions:

	APOP=\"/etc/pop.auth\"
	POPUID=\"pop\"

The first definition is the location of the database; the 
second specifies the user/password entry that will own the 
authorization database.

When you build the qpopper with APOP, you also get a program 
called popauth which must be installed in a public location.  
This program must also run SUID as the 'pop' user so that it 
can make modifications to the pop.auth database.
    
NOTE: Make sure the database /etc/pop.auth is owned by 
POPUID and that the permissions are 600.  popauth -init 
creates the file with the proper owner and perms.

The database must be initialized by root with the following 
command:

	    popauth -init

New users can be added by root or the 'pop' user with the 
following command:

	    popauth -user <user>

	Or removed with the following command:

	    popauth -delete <user>

Anyone can add themselves or change their password with the 
following command: 

	    popauth







