@(#)@(#)README 2.6 2.6 4/2/91 The Post Office Protocol Server: Installation Guide Introduction The Post Office Protocol server runs on a variety of Unix[1] computers to manage electronic mail for Macintosh and MS-DOS computers. The server was developed at the University of California at Berkeley and conforms fully to the specifications in RFC 1081[2] and RFC 1082[3]. The Berkeley server also has extensions to send electronic mail on behalf of a client. This guide explains how to install the POP server on your Unix computer. It assumes that you are not only familiar with Unix but also capable of performing Unix system administration. How to Obtain the Server The POP server is available via anonymous ftp from ftp.CC.Berkeley.EDU (128.32.136.9, 128.32.206.12). It is in two files in the pub directory: a compressed tar file popper-version.tar.Z and a Macintosh StuffIt archive in BinHex format called MacPOP.sit.hqx. Contents of the Distribution The distribution contains the following: + All of the C source necessary to create the server program. + A visual representation of how the POP system works. + Reprints of RFC 1081 and RFC 1082. + A HyperCard stack POP client implementation using MacTCP. + A man page for the popper daemon. + This guide. Compatibility The Berkeley POP server has been successfully tested on the following Unix operating systems: + Berkeley Systems Distribution 4.3 + Sun Microsystems Operating System versions 3.5 and 4.0 + Ultrix version 2.3 The following POP clients operate correctly with the Berkeley POP server: + The Berkeley HyperMail HyperCard stack for the Apple Macintosh (distributed with the server). + The Stanford University Macintosh Internet Protocol MacMH program. + The Stanford University Personal Computer Internet Protocol MH program. + The mh version 6.0 programs for Unix. Support The Berkeley POP server is not officially supported and is without any warranty, explicit or implied. However, we are interested in your experiences using the server. Bugs, comments and suggestions should be sent electronically to netinfo@garnet.Berkeley.EDU. Operational Characteristics The POP Transaction Cycle The Berkeley POP server is a single program (called popper) that is launched by inetd when it gets a service request on the POP TCP port. (The official port number specified in RFC 1081 for POP version 3 is port 110. However, some POP3 clients attempt to contact the server at port 109, the POP version 2 port. Unless you are running both POP2 and POP3 servers, you can simply define both ports for use by the POP3 server. This is explained in the installation instructions later on.) The popper program initializes and verifies that the peer IP address is registered in the local domain, logging a warning message when a connection is made to a client whose IP address does not have a canonical name. For systems using BSD 4.3 bind, it also checks to see if a cannonical name lookup for the client returns the same peer IP address, logging a warning message if it does not. The the server enters the authorization state, during which the client must correctly identify itself by providing a valid Unix userid and password on the server's host machine. No other exchanges are allowed during this state (other than a request to quit.) If authentication fails, a warning message is logged and the session ends. Once the user is identified, popper changes its user and group ids to match that of the user and enters the transaction state. The server makes a temporary copy of the user's maildrop (ordinarily in /usr/spool/mail) which is used for all subsequent transactions. These include the bulk of POP commands to retrieve mail, delete mail, undelete mail, and so forth. A Berkeley extension also allows the user to submit a mail parcel to the server who mails it using the sendmail program (this extension is supported in the HyperMail client distributed with the server). When the client quits, the server enters the final update state during which the network connection is terminated and the user's maildrop is updated with the (possibly) modified temporary maildrop. Logging The POP server uses syslog to keep a record of its activities. On systems with BSD 4.3 syslogging, the server logs (by default) to the "local0" facility at priority "notice" for all messages except debugging which is logged at priority "debug". The default log file is /usr/spool/mqueue/POPlog. These can be changed, if desired. On systems with 4.2 syslogging all messages are logged to the local log file, usually /usr/spool/mqueue/syslog. Problems If the filesystem which holds the /usr/spool/mail fills up users will experience difficulties. The filesystem must have enough space to hold (approximately) two copies of the largest mail box. Popper (v1.81 and above) is designed to be robust in the face of this problem, but you may end up with a situation where some of the user's mail is in /usr/spool/mail/.userid.pop and some of the mail is in /usr/spool/mail/userid If this happens the System Administrator should clear enough disk space so that the filesystem has at least as much free disk as both mailboxes hold and probably a little more. Then the user should initiate a POP session, and do nothing but quit. If the POP session ends without an error the user can then use POP or another mail program to clean up his/her mailbox. Alternatively, the System Administrator can combine the two files (but popper will do this for you if there is enough disk space). Debugging The popper program will log debugging information when the -d parameter is specified after its invocation in the inetd.conf file. Care should be exercised in using this option since it generates considerable output in the syslog file. Alternatively, the "-t <file-name>" option will place debugging information into file "<file-name>" using fprintf instead of syslog. (To enable debugging, you must edit the Makefile to add -DDEBUG to the compiler options.) For SunOS version 3.5, the popper program is launched by inetd from /etc/servers. This file does not allow you to specify command line arguments. Therefore, if you want to enable debugging, you can specify a shell script in /etc/servers to be launched instead of popper and in this script call popper with the desired arguments. Installation 1. Examine this file for the latest information, warnings, etc. 2. Check the Makefile for conformity with your system. 3. Issue the make command in the directory containing the popper source. 4. Issue the make install command in the directory containing the popper source to copy the program to /usr/etc. 5. Enable syslogging: + For systems with 4.3 syslogging: Add the following line to the /etc/syslog.conf file: local0.notice;local0.debug /usr/spool/mqueue/POPlog Create the empty file /usr/spool/mqueue/POPlog. Kill and restart the syslogd daemon. + For systems with 4.2 syslogging: Be sure that you are logging messages of priority 7 and higher. For example: 7/usr/spool/mqueue/syslog 9/dev/null 6. Update /etc/services: Add the following line to the /etc/services file: pop 110/tcp Note: This is the official port number for version 3 of the Post Office Protocol as defined in RFC 1081. However, some POP3 clients use port 109, the port number for the previous version (2) of POP. Therefore you may also want to add the following line to the /etc/services file: pop2 109/tcp For Sun systems running yp, also do the following: + Change to the /var/yp directory. + Issue the make services command. 7. Update the inetd daemon configuration. Include the second line ONLY if you are running the server at both ports. + On BSD 4.3 and SunOS 4.0 systems, add the following line to the /etc/inetd.conf file: pop stream tcp nowait root /usr/etc/popper popper pop2 stream tcp nowait root /usr/etc/popper popper + On Ultrix systems, add the following line to the /etc/inetd.conf file: pop stream tcp nowait /usr/etc/popper popper pop2 stream tcp nowait /usr/etc/popper popper + On SunOS 3.5 systems, add the following line to the /etc/servers file: pop tcp /usr/etc/popper pop2 tcp /usr/etc/popper Kill and restart the inetd daemon. You can confirm that the POP server is running on Unix by telneting to port 110 (or 109 if you set it up that way). For example: %telnet myhost 110 Trying... Connected to myhost.berkeley.edu. Escape character is '^]'. +OK UCB Pop server (version 1.6) at myhost starting. quit Connection closed by foreign host. Release Notes 1.831uiuc2 Unlinking temporary drop file (safely). (Steve Dorner, 12/12/91) 1.831uiuc1 Make sure user's shell is in /etc/shells. (Paul Pomes) Timeout added. (Steve Dorner, 12/5/91) 1.83 Make sure that everything we do as root is non-destructive. 1.82 Make the /usr/spool/mail/.userid.pop file owned by the user rather than owned by root. 1.81 There were two versions of 1.7 floating around, 1.7b4 and 1.7b5. The difference is that 1.7b5 attempted to save disk space on /usr/spool/mail by deleting the users permanent maildrop after making the temporary copy. Unfortunately, if compiled with -DDEBUG, this version could easily wipe out a users' mail file. This is now fixed. This version also fixes a security hole for systems that have /usr/spool/mail writeable by all users. With this version we go to all new SCCS IDs for all files. This is unfortunate, and we hope it is not too much of a problem. Thanks to Steve Dorner of UIUC for pointing out the major problem. 1.7 Extensive re-write of the maildrop processing code contributed by Viktor Dukhovni <viktor@math.princeton.edu> that greatly reduces the possibility that the maildrop can be corrupted as the result of simultaneous access by two or more processes. Added "pop_dropcopy" module to create a temporary maildrop from the existing, standard maildrop as root before the setuid and setgid for the user is done. This allows the temporary maildrop to be created in a mail spool area that is not world read-writable. This version does *not* send the sendmail "From " delimiter line in response to a TOP or RETR command. Encased all debugging code in #ifdef DEBUG constructs. This code can be included by specifying the DEGUG compiler flag. Note: You still need to use the -d or -t option to obtain debugging output. 1.6 Corrects a bug that causes the server to crash on SunOS 4.0 systems. Uses varargs and vsprintf (if available) in pop_log and pop_msg. This is enabled by the "HAVE_VSPRINTF" compiler flag. For systems with BSD 4.3 bind, performs a cannonical name lookup and searches the returned address(es) for the client's address, logging a warning message if it is not located. This is enabled by the "BIND43" comiler flag. Removed all the includes from popper.h and distributed them throughout the porgrams files, as needed. Reformatted the source to convert tabs to spaces and shorten lines for display on 80-column terminals. 1.5 Creates the temporary maildrop with mode "600" and immediately unlinks it. Uses client's IP address in lieu of a canonical name if the latter cannot be obtained. Added "-t <file-name>" option. The presence of this option causes debugging output to be placed in the file "file-name" using fprintf instead of the system log file using syslog. Corrected maildrop parsing problem. 1.4 Copies user's mail into a temporary maildrop on which all subsequent activity is performed. Added "pop_log" function and replaced "syslog" calls throughout the code with it. 1.3 Corrected updating of Status: header line. Added strncasecmp for systems that do not have one. Used strncasecmp in all appropriate places. This is enabled by the STRNCASECMP compiler flag. 1.2 Support for version 4.2 syslogging added. This is enabled by the SYSLOG42 compiler flag. 1.1 Several bugs fixed. 1.0 Original version. Limitations + The POP server copies the user's entire maildrop to /tmp and then operates on that copy. If the maildrop is particularly large, or inadequate space is available in /tmp, then the server will refuse to continue and terminate the connection. + Simultaneous modification of a single maildrop can result in confusing results. For example, manipulating messages in a maildrop using the Unix /usr/ucb/mail command while a copy of it is being processed by the POP server can cause the changes made by one program to be lost when the other terminates. This problem is being worked on and will be fixed in a later release. Credits The POP server was written by Edward Moy and Austin Shelton with contributions from Robert Campbell (U.C. Berkeley) and Viktor Dukhovni (Princeton University). Edward Moy wrote the HyperMail stack and drew the POP operation diagram. This installation guide was written by Austin Shelton. Footnotes [1] Copyright (c) 1990 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution. Unix is a registered trademark of AT&T corporation. HyperCard and Macintosh are registered trademarks of Apple Corporation. [2] M. Rose, Post Office Protocol - Version 3. RFC 1081, NIC, November 1988. [3] M. Rose, Post Office Protocol - Version 3 Extended Service Offerings. RFC 1082, NIC, November 1988.
Release Notes: popper-1.831beta is no longer beta 30 July 91 Removed popper-1.7.tar.Z popper-1.831beta.tar.Z 03 April 91 Changed mkstemp to mktemp for Ultrix. Sigh. popper-1.83beta.tar.Z 02 April 91 This version makes certain that while running as root we do nothing at all destructive. popper-1.82beta.tar.Z 27 March 91 This version fixes problems on Encore MultiMax and some Sun releases which wouldn't allow a user to ftruncate() a file from an open file descripter unless the user owns the file. Now the user owns the /usr/spool/mail/.userid.pop file. Thanks to Ben Levy of FTP Software and Henry Holtzman of Apple. popper-1.81beta.tar.Z 20 March 91 This version of popper is supposed to fix three problems reported with various versions of popper (all called 1.7 or 1.7something). 1) Dropped network connections meant lost mail files. Some 1.7 versions also risked corrupting mail files. 2) Some versions of 1.7 created temporary drop files with world read and write permissions. 3) Some versions of 1.7 were not careful about opening the temporary drop file. popper-1.7.tar.Z 09 September 90 (updated 20 March 91) This version will exhibit the first problem listed above if it is compiled with -DDEBUG and run without the "-d" (debug) flag. If it is compiled without -DDEBUG it will exhibit only the second and third bug listed above. Cliff Frost poptest@nettlesome.berkeley.edu UC Berkeley
Post Office Protocol (POP) servers for NEXTSTEP 12-Aug-94 The makefile make.next has options set to compile this version of popper on NEXTSTEP 3.2. The compilation and the server have run on a NeXTstation running NS 3.2. I had to modify pop_bull.c and pop_pass.c from the Qualcomm sources in order to get the correct DIR stuct included. See *.dist for originals of modified files. I also renamed and merged some of the README.* files. The sources came from ftp://ftp.qualcomm.com/quest/unix/servers/popper/ To make the MAB executable % make next To install, % make install.next installman To change the compilation you should edit Makefile and/or make.next. Other installation details: As root you will need to add entry(s) to the services: # (echo pop 110/tcp; echo pop2 109/tcp) | niload services . And you will need to add the following line(s) to /private/etc/inetd.conf pop stream tcp nowait root /usr/etc/popper popper pop2 stream tcp nowait root /usr/etc/popper popper Be sure to get the paths right. Then jog the inetd to read the new entries: # kill -HUP `ps cx | fgrep inetd | awk '{print $1}'` See the man page for debugging and logging options. Hugh -- Hugh Secker-Walker | hugh@hodain.ci.net (NeXTmail ok) | hugh@ear.mit.edu
Popper mods contributed by John Norstad of Northwestern University (j-norstad@nwu.edu). Summary ======= 1. Properly clean up on abnormal termination and rewrite the mail drop file. The QC3 mods to catch SIGHUP signals and time out reads were not enough. You also have to catch SIGPIPE signals to avoid being killed when the client connection is aborted while the server is writing (e.g., if you cancel downloading a large message in Eudora, a common operation). 2. Fixed some bad log messages. 3. Added a mod from Don Lewis <gdonl@gv.ssi1.com>. Under SunOS 4.1.3, and possibly other systems, the check for null passwords doesn't work. QC3 checked only for a null password pointer in the struct returned by getpwnam. You also have to check for an empty string returned by getpwnam. 4. Added a -s command line option to generate statistics messages in the log. One message is issued for each session: Stats: username aaa bbb ccc ddd where: aaa = number of messages deleted. bbb = number of bytes deleted. ccc = number of messages left on server. ddd = number of bytes left on server. 5. (The big one). Added a "POP bulletin" feature. This feature gives system administrators a way to send important announcements to all POP users without having to do sendmail mass mailings. The feature is enabled via the -b command line option. This option is followed by the path of the bulletin directory. The bulletin directory contains one file per bulletin. Each file contains a complete single mail message with header and body in mailbox format. The first line of each such bulletin must be a "From " line. The easiest way for sysadmins to create such bulletins is to mail themselves a copy of the bulletin (using the account to which they want replies to be sent), then use their mail program to save the message to a file in the bulletin directory in mailbox format. The bulletin directory must be world readable. The name of each bulletin file begins with the bulletin number, and may optionally continue with any other characters. E.g., the file name of bulletin number 23 might be: 23.pophost_down_sunday Popper creates a file named ".popbull" in the home directory of each user. This file contains a single line recording the highest numbered bulletin received by the user. Bulletins are processed by popper in pop_dropcopy.c, immediately after copying the mail drop to the temporary mail drop, but before building the temporary mail drop index. All bulletins which this user has not received previously are appended to the temporary mail drop file. When bulletins are copied to the temporary mail drop file, all "To" header lines are replaced by "To: username@myhost". Any "Status:" header lines are deleted. Otherwise, the bulletins are copied as is. When a new user checks for mail the first time, popper creates the .popbull file in the user's home directory and seeds it with the current maximum bulletin number. Thus new users do not get old bulletins. All errors are logged and cause the bulletins to not be copied. E.g., if the bulletin directory cannot be located, or the .popbull file doesn't contain a number, or a bulletin does not begin with a "From " line, or a bulletin name does not begin with a number, etc. I use bulletin numbers instead of last mod date/times because I want to make it possible for a sysadmin to, for example, fix a spelling error in a bulletin without having to force all pop users to receive a new copy of the bulletin. 6. Changed the default timeout from 30 to 300 seconds (5 minutes). This value should be reasonably "safe" for even slow dialup connections. 7. Included a mod from Steve Dorner to implement a new "XTND XLST" command. 8. Updated the manpage. 9. Changed the version number to just plain version 2.0. Detailed mods by source code file ================================= version.h: Changed version number to 2.0. --- popper.c: Added a call to catch SIGPIPE signals in addition to SIGHUP signals. Both signals are treated the same way: They set the "hangup" global to "true". Popper gets a SIGPIPE signal if the client aborts the TCP stream while recieving data (e.g., in the middle of downloading a large message). Popper must rewrite the mailbox file in this case. In QC3, popper was being killed and was not rewriting the mailbox file. Rewrote the state loop to make it a bit more clear. Fixed an error in the QC3 log messages. QC3 was writing "POP mailbox update failed" messages when the POP mailbox update actually succeeded, rather than when it failed. --- pop_pass.c: Added a mod from Don Lewis <gdonl@gv.ssi1.com>. Under SunOS 4.1.3, and possibly other systems, the check for null passwords doesn't work. QC3 checked only for a null password pointer in the struct returned by getpwnam. You also have to check for an empty string returned by getpwnam. --- pop_updt.c: Added stats logging code. If the -s switch is specified on the popper command line, the following log message is generated: Stats: username aaa bbb ccc ddd where: aaa = number of messages deleted bbb = number of bytes deleted ccc = number of messages left on server ddd = number of bytes left on server --- popper.h: Add a new field named "stats" to the POP struct. This integer field is non-zero if stats are requested. Add a new field named "bulldir" to the POP struct. This field records the bulletin directory path, or is NULL if the bulletin feature is not enabled via the -b switch. Add extern declaration for pop_xlst. Changed default timeout from 30 seconds to 300 seconds. The default should be a "safe" value. 30 seconds isn't long enough for dialup connections, for example. --- pop_init.c: Process the new -s command line switch. Process the new -b command line switch. --- pop_bull.c: New source file for the bulletin system. --- pop_dropcopy.c: Add call to pop_bull. --- xtnd_xlst.c: New source file for Steve Dorner's "xlst" command. --- pop_get_subcommand.c: Add table entry for Steve Dorner's "xlst" command. --- Makefile: Add pop_bull.c and xtnd_xlst.c to CSRCS and pop_bull.o and xtnd_xlst.o to OBJS. --- popper.8 Updated the manpage to describe the changes.
qpop.2.1.0.Z This version of the popper has been handled by a few sites. It has had a few enhancments added to it as well as making a small departure from the popper RFC. We honor deletes and read messages when the request occurs. The RFC states that messages will not be deleted until the QUIT command is received. We found this to be a problem for dialup users who have connections fail midway through a session. We go one step further with "leave mail on server" enabled by marking messages read when you start to read them. This means that if a session terminates abnormally while reading a message it will be marked as read. This has the advantage of allowing the user to bypass a problem message. The down side is that the message is now unavailable to the user unless they disable "leave mail on server". Read all the other readme's for more information about who changed what. The latest version is 2.1.1 Mark Erikson mark@qualcomm.com This version of the popper was modified by Steve Dorner and Paul Pomes at the UIUC.edu to fix a couple of bugs and add a timeout feature. Version - 2Q1 It was then modified by Keith Pilotti at Qualcomm.com to write out changes to the temporary pop log on an abort. This diverts from the Popper RFC but it made our users life much easier. The below feature is only useful with Eudora's "Leave mail on Server" switch set (or any other client that leaves mail on the server). Basically, if a user has read 5 out of 10 messages and the session dies, the first 5 messages are marked as read. If the 5th message is good but you only receive part of it then it will be skipped (bad). But if the message was bad and caused the mail client to abort then you can continue to receive the rest of your mail (good). Version - 2Q2 This version of the popper was then modified by Mark Erikson to add HPUX file locking calls and a shorter timeout. The timeout can be configured at the command line. The timer for any of these versions starts after a command or message has been delivered and the popper is expecing input from the client. If the response takes longer than the timeout then the popper closes down the socket and cleans up the files. Version - 2Q3 This version fixes a bug in the cleanup code. If an error occurs during the login phase then a core file is dumped. Annoying but not serious since the .user.pop file is unlocked and the popper deals with this old file as a matter of course.
These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.