@(#)@(#)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.

+   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


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.

SIEVE SUPPORT

Last updated: 27 October 1998 rcg




There are 4 main components for Sieve support:
    o  Platform-independent Sieve engine
    o  Unix Delivery agent
    o  Unix Sieve ACAP Daemon
    o  Sieve GUI


Sieve Engine
----- ------

The Sieve engine is platform independent, and conforms to
draft-showalter-sieve-03.txt, except for (a) REJECT action not
implemented, and (b) wildcard searching not implemented (I plan on
adding Henry Spencer's regexp code).  In addition, I've added support
for envelope matching, and adding extra headers.  The envelope
extension adds 'envelope.rcpt' and 'envelope.from' tests.  The MARK
extension adds an extra header to the message.  The text can optionally
contain ^f, which is replaced with the envelope return path, and/or ^r,
which is replaced with the envelope recipient.

The Sieve engine consists of three primary modules: a Sieve parser, the
actual Sieve execution, and a module which allocates and deallocates
structures used by both.  The Sieve parser uses a platform-independent
scanner/parser (called skanx), which also includes some string-handling
functions (for portability).  Extensive tracing is available; the code
expects have available a callback function to write trace entries.

The Sieve engine has hooks to allow for parsed Sieve scripts to be
cached in memory (or on disk), but this is not yet implemented;
currently each mail message causes the script to be parsed into
structures, executed, and the structures released.

Sieve parsing and execution are separated for two main reasons: to
allow for syntax errors to be detected before any execution has begun,
and to allow for caching.

The Sieve engine is called by a delivery agent, using the Delivery
Agent API (DAA, pronounced "duh").  The incoming message envelope and
headers, and optionally all or the start of the body, are parsed into
structures.  These structures are passed to the Sieve engine.  The
Sieve engine expects various call-back functions to be available at
link time.  These call-backs handle either utility tasks (such as
address parsing), or platform-specific actions (such as generating a
reply or setting the IMAP delivery folder).

The Sieve engine expects to read the Sieve script from a file.  It is
passed the full path to the file, and opens it (using standard C).  It
knows nothing of file system specifics.

The Sieve engine includes calls to simply parse (not execute) a Sieve
script, to check for syntax errors.   Parse-time errors and warnings
are returned in the Sieve structure, as integers (count of
errors/warnings) and strings (specifics of errors/warnings, in the
format specified by draft-gellens-acap-acnt-00.txt).

The Sieve engine has been running on Windows-NT for some months now.


Unix Delivery Agent
---- -------- -----

The Unix delivery agent parses the message headers into the DAA-defined
structures, calls Sieve, and depending on the return value, either
delivers or discards the message.

Current limitations:
    1) The envelope originator MUST be specified, with -f on the command line.
    2) Tracing/logging call-back not yet implemented.
    3) Reply, forward callbacks not yet implemented.
    4) Context stuct get assigned empty strings for envelope originator
       and recipient.
    5) No file locking yet on sieve script.  (Will be implemented using
       dot-locking in the same fashion as sievead.)
    6) Doesn't always write to mailbox correctly.  Messages get
       appended to others.


Unix Sieve ACAP Daemon
---- ----- ---- -----

The Sieve ACAP Daemon (sievead, pronouned "seh'-vee-ad" or
"seh-vee'-ad") listens on the ACAP port (674), or a specified port (we
will apply for one when we publish an I-D on this), and implements just
enough ACAP to allow a client to retrieve or store a Sieve script, as
specified in draft-gellens-acap-acnt-00.txt (that is, using attribute
'account.sieve.script').  The Daemon reads and writes the Sieve script
locally to "~/.sieve_script", using standard dot-file locking as the
*only* file-locking mechanism (no flock() calls).

The Unix sievead is currently working.


Sieve GUI
----- ---

There is a Windows Sieve GUI, and an HTML/Perl based GUI, both of which
allow users to easily create, delete, and modify simple Sieve rules.
Based on the Eudora filters interface, the GUI presents a list of
rules, each of which can have one or two conditions, and up to four
actions.  Only a very limited subset of Sieve is used, to keep things
simple.

The Windows GUI includes an edit box, so power users can roll their
own, using Sieve syntax.

The Windows GUI calls the Sieve engine parser.  It also writes a Sieve
script as a standardized set of comments at the file head.  Only Sieve
syntax which fits into the GUI is written as comments.  The comments
use the same syntax as the filters files in Eudora.  The HTML/Perl GUI
also reads and writes these comments.  The Windows GUI processes the
actual Sieve, and generates the comments as well.  The HTML/Perl GUI
reads and writes the comments, but ignores the actual Sieve syntax.

The Windows GUI is usable, but the HTML/Perl code still needs to have
authentication integrated into it, and needs more extensive testing.

Current Limitations:
    1. The Windows client currently stores authentication and server
       data, *including the password*, in cleartext in the Registry.