
			GENERAL INFORMATION
			
The Solid POP3 Server is an implementation of a Post Office Protocol version 3
server that has flexibility as its main goal. The server is easily
configurable and has support for few features such as:
- APOP authentication scheme
- virtual hosting
- maildir and mailbox handling
- bulletins
- expiration of messages
Each user can specify his maildrop (its position and type). The format
used in specification of maildrop's position should handle almost all
widely-used system configurations. The server also seems to be fast, however no
tests have been performed, so it's rather relative feeling. The design used
is very similar to the design of Solar Designer's POPA3D server. This solution
let's minimalize size of code working with root privileges. The code was also
heavily checked for buffer overflow leaks and file races. None have been found
as of now. All operations on files are done with user privileges (exception: 
AuthLog - read spop3d.conf(5) manual). There is no SUID APOP secrets database
management program (as in QPOP). Each user can specify his secret in his own
home directory.

Default maildrop name is /var/spool/mail/%s (read spop3d(8) manual).
Most Linux distributions work with this setting. However on other systems
you should change this value (use "-n" option or edit src/const.h).

The newest version of the server is available under:
	ftp://ftp.pld.org.pl/software/solidpop3d
	ftp://ftp.rudykot.pl/pub/solidpop3d
	ftp://sedez.iq.pl/pub/solidpop3d
	ftp://dione.ids.pl/pub/solidpop3d

Homepage:
	http://solidpop3d.pld.org.pl/

Any suggestions, bug reports, information about successful ports should go to:
	Jerzy Balamut <jurekb@dione.ids.pl>



			    INSTALLING

Consult INSTALL file for generic instructions about installing.

Existance of the user "spop3d" in system is required. Big part of the server
works with this user privileges. Following ./configure options are recognized:
--enable-pam		- add PAM support
--enable-apop		- add APOP authentication scheme support
--enable-mailbox	- add mailbox handling support
--enable-maildir	- add maildir handling support
--enable-crlfmaildir	- add crlfmaildir handling support (see below)
--enable-bulletins	- add bulletins support
--enable-expire		- add support for message expiration
--enable-standalone	- compile server as a standalone server, not inetd
			  server (which is default)
--enable-configfile	- add support for global configuration file
--enable-userconfig	- add support for user configuration file
--enable-last		- add support for LAST command
--enable-mapping	- add support for user names mapping
--enable-nonip		- add support for non-IP based virtuals
--enable-allowroot	- add support for "AllowRootLogin" option
--enable-createmail	- add support for "CreateMailDrop" option
--enable-ipv6		- add support for IPv6 protocol
--enable-resolve	- log resolved host name with IP number
--enable-connect	- log "connect from xxx" message
--enable-logextend	- log peer IP number in few additional places
--enable-statistics	- add support for qpopper-like statistics
--enable-dpuid		- add support for domain-per-uid mechanism
--enable-userpasswd	- add support for user defined passwords
--enable-hashspool	- add support for hashed spools
--with-openssl		- add support for TLS protocol
--with-sasl		- add support for SASL

Support for mailbox, maildir, expiration, configfile and userconfig 
is enabled by default. You can change in the file src/const.h default 
values for some options.

WARNING: The global configuration file should be readable by the "spop3d" 
	 user!!!

Simple installation process could look like this:
$ ./configure
$ make
$ su
# useradd -d /nonexistent -s /nonexistent -M spop3d
# make install
# echo pop3 stream tcp nowait root /usr/sbin/tcpd /usr/local/sbin/spop3d >> /etc/inetd.conf
# killall -HUP inetd

WARNING: On some systems you should replace "pop3" with "pop-3".



				BULLETINS
				
Server looks for bulletins in directory ${localstatedir}/bulletins (default:
/usr/local/var/bulletins). For each bulletin (file) its modification time 
is checked. If this modification time is more recent than the modification time
of the file UserBullFile this bulletin is added to user's maildrop. Server
touches the modification time of the file UserBullFile after all bulletins
are checked. The directory ${localstatedir} and bulletins should be accessable
by any user. Default value for UserBullFile is ".spop3d-bull". Read
spop3d.conf(5) manual for details.



				APOP

Warning: Use APOP only if you really need it (and probably you don't).
It isn't such secure as it looks.


				CRLF MAILDIR

Intro
-----

The 'wire format' for pop3 specifies that e-mails will be sent with \r\n
line endings, and lines begining with '.' are escaped with another '.'.
See RFC1939, a.k.a. STD53 (http://www.rfc.net/get2.php3/std53.html).

This means that with normal maildir (and mailbox, but that has other
problems too) Solid POP has to read through each message to see how long it
will be when it's sent across the network. It has to gets this information
after it's authenticated the client, but before it's sent the +OK response.

With a mailbox containg many large e-mails this can take a long time.

Solid POP then has to go through the whole process again when the client
retrevies the message.

crlfmaildir gets round this be offloading line end conversion and
'byte-stuffing' to a 'delivery agent' called into_crlfmaildir that is
run by the MTA thats delivering mail to the mailboxes.

crlfmaildir is only usefull if:

* You need a really efficent pop server and don't care about breaking
  compatibility with maildir.

* Your mta can be persuaded to deliver mail into a pipe (most can, see
  examples below).

* The only two processes that will be accessing your mailboxes are your MTA
  and Solid POP. (i.e. your running a pure pop server).

Setting up your MTA to deliver to crlf maildir's
------------------------------------------------

If you want to get it working with some MTA (other than Exim, Postfix,
QMail) mail me and I may be able to help. If you get it working on your
own I would be very grateful if you could tell me how you did it so I can
update this document.

Solid Pop3 comes with a program called into_crlfmaildir, by default it's
installed into ${prefix}/sbin. This program takes a single e-mail on
stdin and writes it, in the crlfmaildir format, into the directory specified
on the command line.

You can convert an existing mailbox using formail's -s option (part of the
procmail package).

If into_crlfmaildir encounters any problems it exits with EX_TEMPFAIL
(normaly '75') which will cause most MTA's to re-queue the message and try
again later, allowing you to fix whatever the problem is without losing the
message.

Exim
----

Here's the transport i'm using:

local_delivery:
  driver = pipe
  command = /usr/local/libexec/into_crlfmaildir /var/mail/${substr_4_1:$local_part}/${substr_5_1:$local_part}/${local_part}/
  escape_string = ""
  prefix = ""
  suffix = ""
  freeze_exec_fail
  return_fail_output
  group = mail
  log_defer_output
  log_fail_output
  delivery_date_add
  envelope_to_add
  return_path_add

Our usernames are popXXXX, and MailDropName in spop3d.conf is:

"/var/mail/%d5/%d6/%s"

i.e. sop3d counts from 1 with %d, and exim counts from 0 with ${substr}.

Postfix
-------

Just add the following to /etc/postfix/main.cf

mailbox_command = /usr/local/sbin/into_crlfmaildir /var/mail/$USER

or

mailbox_command = /usr/local/sbin/into_crlfmaildir Maildir

To deliver to 'Maildir' in the users $HOME. Postfix also understands
EX_TEMPFAIL.

QMail
-----

Your starting script (/var/qmail/rc) should look like this:

#! /bin/sh
exec env - PATH="/var/qmail/bin:$PATH" \
qmail-start '|preline /usr/local/sbin/into_crlfmaildir /var/mail/$USER' \
splogger qmail

You may want to use '|preline /usr/local/sbin/into_crlfmaildir Maildir'
to deliver to 'Maildir' in the users $HOME. QMail also understands
EX_TEMPFAIL.

Contact for crlfmaildir
-----------------------

jasper@pointless.net (prefered)
jasper@ivision.co.uk


				COPYRIGHT

The program is distributed under GNU General Public License.
See the file COPYING for details.



				    Jerzy Balamut <jurekb@dione.ids.pl>
