PerlPop3 v1.0.2
================

DOCUMENTATION

Usage:

Normally, you would add users in your unix system, and the it's default
spoolfile will be available through pop3.

When using a database, further options are available:

- Same users with different domain names can coexist. Users must provide 
their username in the following format: 'username@domain.name' or 
'username:domain.name'
- APOP can be used. The problem with APOP is that the unencrypted password
must be available to be able to hash it with MD5 and the challenge. As unix
systems use encrypted passwords by default, it is not normally usable. Future
versions may include a stand-alone depository for user passwords (or you can
integate your own!).

Perlpop3 is normally faster as it does NOT load the whole spoolfile into 
memory, it just parses the spool as it's being retrieved. Normally, all 
pop clients just retrieve incrementally each e-mail and then delete them
all.

Users who like to save their whole mail on the server, may notice a slight
delay after authentication while their spool is parsed. This is due that the
spool not only may have had new mail appended, but it allows users to use 
any normal unix email readers without interfering with pop3 access. This is
not normally a problem, but users above 500 megabytes may experience delays 
up to 2-3 minutes (time is dependant on file size, server capacity and load). 
A solution to this is being considered and may appear in future versions.
Also, a very psychotic email client that retrieves mail out of order in big
mailboxes may also suffer delays while the spoolfile is re-parsed. We have 
not seen any client that does this.



Pop3 is developed based on the STD 53 (RFC 1939) and RFC 2449.

It's basically composed of the mayor parts:

- The authentication check
- The mail processing and delivery


AUTHENTICATION:

	Authentication is done by default into the unix user database, but can be 
extended to use a database. See DATABASE below for more details. Also, it can be 
easily modified by changing the get_user_data routine:

( $count, $username, $rpass, $domain, $spool, $uid ) = &get_user_data( $user_input, $pass );

which must return:
Count: Number of users detected with the same username and password (to detect pass clashes)
Username: The lone username, due that input may contani the full email
rpass: The 'right password'.
domain: The domain name portion of the user
spool: the spool dierctory
uid: the correct UID to change the owner of the file

MAIL PROCESSING:

	The spoolfile is read and parsed when the user passes authentication. While 
parsing it checks for a X-UIDL header to manage persistent UIDL information, 
insted of being generated by time-consuming hashing. UIDLS are generated by a 
timestamp and a random number. 
	Mail is usually retrieved sequentially, so the server maintains its place 
on the last mail opened and usually continues right on to the next. This gives
a big advantage in speed and memory usage.

DATABASE USE:

By turning on the $useDatabase option, you can authenticate through a database.
You must have the perl modules DBI and the corresponding DBD for your database
installed.

WARNING: YOU MUST ALSO CONFIGURE YOUR MTA TO DELIVER TO THE RIGHT MAILBOXES 
FOR EACH USER. THIS SOFTWARE DOES NOT RECEIVE EMAIL. One way to do it is to 
create a line in the virtuser file (for sendmail) and the aliases file. 
For example:

Virtuser file:
test@example.com: example.com_test

Aliases file:
example.com_test: /var/mail/example.com/test

For a complete administrative solution via web, contact <scamarena@adsen.com>.

The database can be any you can configure through DBI and DBD. In this case, 
for example, we have a Postgres database called 'popdb' that connects with 
user 'root' and no password:

$database_connect = "dbi:Pg:dbname=popdb";
$database_user = 'root';
$database_password = '';

The database must have a table 'USERS' with the following fields:

username varchar(100);
password varchar(100);
spool varchar(250);
domain varchar(250);

Sizes are flexible and may be any you consider proper.
The spool field must contain a directory where the mailbox resides, which must 
be a file named after the username.

This psql command creates such table:

create table test ( username varchar(100), password varchar(100), 
	spool varchar(250), domain varchar(250) );


POPAUTH:

For an example of using popauth, see this page:
http://www.iecc.com/pop-before-smtp.html

After configuring sendmail, you just set the $use_popauth option to 1 and it will 
update this database. (You must have the DB_File perl module install, see 
the INSTALL file)

RELAY DOMAINS:

Another options of allowing users to send SMTP mail after using POP3, is by updating
the relay-domains file, installed with most installations of sendmail. To use, just
set the $update_relaydomains to 1.


BUGS:

This software has been extensibly used, but sometimes a bug might crop up. 
Please send any weird behaviour or problems to the authors via the sourceforge 
page or directly to <scamarena@adsen.com>.

ACKNOWLEDGEMENTS:

Thanks to the following people for bug reports and security checks:

Enrique Snchez (Nahul)
Pedro Navarro (g33k)

