
			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 for 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
--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 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
  compaterbility with maildir.

* Your mta can be persuaded to deliver mail in the right format (see below).

* The only two processes that will be accessing your mailboxes are your MTA
  and Solid POP.

* At the moment bulletins don't work with with it, I'm working on it ;-)

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

The only MTA this has been tried with is Exim (www.exim.org), If you want to
get it working with another MTA 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 these docs.

Exim
----

Change the local delivary transport as follows:

remove the 'file' line and replace with:

directory = /path/to/your/mailboxes/${local_part}/

(make sure this is the same as Solid POP's MailDropName setting)

add:

	create_directory
	directory_mode = 0770 	# you may want 0700
	maildir_format
	prefix = ""
	suffix = ""

This gets you maildir support.

Then add:

	use_crlf			# \r\n line endings
	check_string = "."		# escape lines ending with '.'
	escape_string = ".."		# with another '.'

Which gets you the rest.

You might be able to do the same thing with the 'bsmtp one' option, but I
havn't tried it.

You might also need to play with the group and mode settings. (and make sure
the spop3d user is in that group).

Qmail
-----

You might be able to do something with safecat:

http://www.nb.net/~lbudney/linux/software/safecat.html

and a perl script to mangle the mails...

sendmail
--------

You might be able to do something with E=\r\n or the smtp delivery agent
type in the flags field, or safecat and a perl script as above.

Other
-----

* you don't have to do true maildir - the crlfmaildir stuff only looks in
  the 'new' dir, but you will have to be certain that any files in there
  get writtem atomicly.

* Solid POP uses the filenames and MD5 to create the UIDL values, so
  creating the filenames out of as much vairable data as possible is a
  good idea.

* The wire format for POP3 is the same as SMTP, if you MTA supports 'batch
  smtp' ('bsmtp') then it can write the files in the right format. But you
  may need to filter out SMTP commands (HELO, RCPT TO, MAIL FROM etc).


Contact
-------

Work: jasper@ivision.co.uk
Play: jasper@pointless.net

				COPYRIGHT

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



				    Jerzy Balamut <jurekb@dione.ids.pl>
