The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.

NAME

Net::Server::POP3 - The Server Side of the POP3 Protocol for email

SYNOPSIS

use Net::Server::POP3;
my $server = Net::Server::POP3->new(
  severopts    => \%options,
  authenticate => \&auth,
  list         => \&list,
  retrieve     => \&retrieve,
  delete       => \&delete,
  size         => \&size,
  welcome      => "Welcome to my mail server.",
);
$server->startserver();

DESCRIPTION

Net::Server::POP3 is intended to handle the nitty-gritty details of talking to mail clients, so that in writing a custom POP3 server you don't have to actually read RFC documents. The backend things (such as where mail comes from and what messages are in the user's mailbox at any given time) are left up to your code (or another module), but this module handles the POP3 protocol for you. Also, the details of listening for client connections and so on are handled by Net::Server.

This approach allows for some flexibility. Your code may choose to generate messages on the fly, proxy them from another mail server, retrieve them from a local maildir or mailbox of some kind, or whatever. See the sample scripts in this distribution for examples.

This code is still very much beta. There are known bugs. Some things (e.g., APOP) haven't even been implemented yet. You have been warned. See the Bugs section for details.

The code as it stands now works, for some definition of "works". With the included simpletest.pl script I have successfully served test messages that I have retrieved with Mozilla Mail/News. Additionally, with the included proxytest.pl script I have successfully proxied mail from an ISP mail server to a client. However, much remains to be done.

It is strongly recommended to run with Taint checking enabled.

These are the RFCs that I know about and intend to implement:

http://www.faqs.org/rfcs/rfc1939.html
http://www.faqs.org/rfcs/rfc2449.html

If you know of any other RFCs that seem pertinent, let me know.

USAGE

This module is designed to be the server/daemon itself and so to handle all of the communication to/from the client(s). The actual details of obtaining, storing, and keeping track of messages are left to other modules or to the user's own code. (See the sample scripts simpletest.pl (simple) and proxytest.pl (somewhat more involved) in this distribution for examples.)

The main method is startserver(), which starts the server. The following named arguments may be passed either to new() or to startserver(). All callbacks should be passed as coderefs. If you pass an argument to new() and then pass an argument of the same name to startserver(), the one passed to startserver() overrides the one passed to new(). stopserver() has not been implemented yet and so neither has restartserver(), but they are planned for an eventual future version.

EOL

A string containing the characters that should be printed on a socket to cause perl to emit an RFC-compliant CRLF. The new default is "\015\012", which theoretically should work perfectly everywhere, from what I have read, but if you get mangled newlines, this may be why. This new default needs testing on as many platforms as possible to ensure that it is, in fact, correct everywhere.

The default used to be "\n", which worked on my development platform (Linux Mandrake 9.2). On some systems this needed to be set to "\r\n". Setting it to the wrong thing caused breakage either way. If the default doesn't work for you, experiment. If you set it to "\r\n" on systems where "\n" will work, you get extraneous ^M characters on the ends of all the lines at the recieving end, which among other things can cause most of the headers not to be recognized as such and instead to be displayed in the body, depending on the mail client. Going the other way, if you set it to "\n" on platforms where "\r\n" would work correctly, the whole thing may just not work at all, or other weirdness may ensue, such as the entire message (headers, body, and all) appearing on one line.

The EOL string is optional; you only need to specify it if the default is the wrong value.

port

The port number to listen on. 110 is the default. The user or group you are running as needs permission to listen on this port.

The port number is optional. You only need to specify it if you want to listen on a different port than 110.

servertype

A type of server implemented by Net::Server (q.v.) The default is 'Fork', which is suitable for installations with a small number of users.

The servertype is optional. You only need to specify it if you want to use a different type other than 'Fork'.

serveropts

A hashref containing extra named arguments to pass to Net::Server. Particularly recommended for security reasons are user, group, and chroot. See the docs for Net::Server for more information.

The serveropts hashref is optional. You only need to supply it if you have optional arguments to pass through to Net::Server.

connect

This callback, if supplied, will be called when a client connects. This is the recommended place to allocate resources such as a database connection handle.

The connect callback is optional; you only need to supply it if you have setup to do when a client connects.

disconnect

This callback, if supplied, is called when the client disconnects. If there is any cleanup to do, this is the place to do it. Note that message deletion should not be handled here, but in the delete callback.

The disconnect callback is optional; you only need to supply it if you have cleanup to do when a client disconnects.

authenticate

The authenticate callback is passed a username, password, and IP address. If the username and password are valid and the user is allowed to connect from that address and authenticate by the USER/PASS method, then the callback should try to get a changelock on the mailbox and return 1 if successful; it must return something other than 1 if any of that fails. (Returning 0 does not specify the details of what went wrong; other values may in future versions have particular meanings.)

The authenticate callback is technically optional, but you need to supply it if you want any users to be able to log in using the USER and PASS commands.

apop

Optional callback for handling APOP auth. If the user attempts APOP auth and this callback exists, it will be passed the username, the digest sent by the user, and the server greeting. If the user's digest is indeed the MD5 digest of the concatenation of the server greeting and the shared secret for that user, then the callback should attempt to lock the mailbox and return true if successful; otherwise, return false.

The apop callback is only needed if you want to supply APOP authentication.

This is not implemented yet, but I plan to implement it in an eventual future version.

list

The list callback, given a valid, authenticated username, must return a list of message-ids of available messages. (Most implementations will ingore the username, since they will already be locked in to the correct mailbox after authentication. That's fine. The username is passed as a help for minimalist implementations.)

The list callback is required.

size

The size callback if it exists will be passed a valid, authenticated username and a message id (from the list returned by the list callback) and must return the message size in octets. If the size callback does not exist, the size will be calculated using the retrieve callback, which is inefficient. Providing the size callback will prevent the retrieve callback from being called unnecessarily, thus improving performance. (Most implementations will ingore the username, since they will already be locked in to the correct mailbox after authentication. That's fine. The username is passed as a help for minimalist implementations.)

Note that very early versions passed only the message id, not the username, to the size callback. This changed in 0.0005, breaking backward-compatibility for the size callback.

The size callback is optional. You only need to provide it if you care about performance.

retrieve

The retrieve callback must accept a valid, authenticated username and a message-id (from the list returned by the list callback) and must return the message as a string. (Most implementations will ingore the username, since they will already be locked in to the correct mailbox after authentication. That's fine. The username is passed as a help for minimalist implementations.)

The retrieve callback is required.

delete

The delete callback gets called with a valid, authenticated username and a message-id that the user/client has asked to delete. (Most implementations will ingore the username, since they will already be locked in to the correct mailbox after authentication. That's fine. The username is passed as a help for minimalist implementations.)

The delete callback is only called in cases where the POP3 protocol says the message should actually be deleted. If the connection terminates abnormally before entering the UPDATE state, the callback is not called, so code using this module does not need to concern itself with marking and unmarking for deletion. When called, it can do whatever it wants, such as actually delete the message, archive it permanently, mark it as no longer to be given to this specific user, or whatever.

This callback is technically optional, but you'll need to supply one if you want to know when to remove messages from the user's maildrop.

welcome

This string is used as the welcome string sent to the client upon connection. It must not be longer than 506 bytes, for arcane reasons involving RFC1939. (startserver will generate a warning at runtime if it is too long.)

The welcome string is optional; a default welcome is supplied.

logindelay

If a number is given, it will be announced in the capabilities list as the minimum delay (in seconds) between successive logins by the same user (which applies to any user). This does NOT enforce the delay; it only causes it to be announced in the capabilities list. The authenticate callback is responsible for enforcement of the delay. The delay SHOULD be enforced if it is announced (RFC 2449).

If the delay may vary per user, logindelay should be a callback routine. If the callback is passed no arguments, it is being asked for the maximum delay for all users; if it is passed an argument, this will be a valid, authenticated username and the callback should return the delay for that particular user. Either way, the return value should be a number of seconds. Again, this does NOT enforce the delay; it only causes it to be announced in the capabilities list. (Some clients may not even ask for the capabilities list, if they do not implement POP3 Extensions (RFC 2449).)

The default is not to announce any particular delay.

expiretime

If a number or the string 'NEVER' is given, it will be announced in the capabilities list as the length of time a message may remain on the server before it expires and may be automatically deleted by the server. (The number is a whole number of days.)

This does NOT actually delete anything; it just announces the timeframe to the client. Clients that do not support POP3 Extensions will not get this announcement. 'NEVER' means the server will never expire messages; 0 means that expiration is immanent and the client should not count on leaving messages on the server. 0 should be announced for example if the mere act of retrieving a message may cause it to expire shortly afterward.

If the message expiration time may vary by user, expiretime should be a callback routine. If the callback is passed no arguments, it is being asked for the minimum expiration time for all users, which it should return (as a whole number of days; 0 is acceptable); if it is passed an argument, this will be a valid, authenticated username and the callback should return the expiration time for this particular user, either as a whole number of days or the string 'NEVER'.

The default is not to announce an expiration time.

DEBUG

Set the level of debugging information desired on standard output. undef means no debug info at all. 0 means only warn when the client uses commands that are not understood. A value of 1 produces various other information about functions that are being called, arguments they are passed, and so on. A value of 2 also uses Data::Dumper to show the state of certain data structures at various times, possibly including entire messages, possibly more than once per message. This can get really verbose. A value of 3 is even more verbose and really doesn't add anything for debugging your code. (Level 3 is intended for debugging the module itself. Actually, all of it was mainly intended for that originally, but the lower levels also proved useful for debugging sample scripts.)

The DEBUG level is optional. The default is 0.

linetimeout

Give the mail client (or user) this many seconds to type or send each line. My reading of RFC1939 is that this shouldn't be less than ten minutes (at least, between commands), but Net::Server::POP3 does not enforce this minimum.

The linetimeout is optional. The default is currently 600 (ten minutes), the minimum specified by the RFC. The default value may change in a future version.

REQUIRES

Net::Server, Exporter

BUGS

DEBUG makes authentication fail

This is really bad, and I hope to fix it very soon. My apologies to anyone who has been bitten by this. The gplproxy example has uncovered a bug wherein passing a nonzero value for DEBUG to new (or probably also startserver) causes authentication to fail. Fixing this will be top priority for the next release.

APOP is not implemented yet.
stopserver and restartserver are not implemented

For now, the only way to stop the server is to kill it. Actually, this may not be true; I'm still investigating this stuff about the Net::Server module.

UIDL

The UIDL implementation uses the message-id as the unique id, rather than calculating a hash as suggested by RFC 1939. In practice, this seems to be what my ISP's mail server does (it calls itself InterMail), which has worked with every client I've thrown at it, so it should be mostly okay, but it's not strictly up to spec I think and may be changed in a later version. I intend to investigate what other major POP3 servers do in this regard before making any changes; if you happen to know e.g. what the POP3 servers do that are usually used with Postfix, Exim, or Qmail, et cetera, drop me a line and let me know. Data about what the POP3 servers used by various ISPs do would also be appreciated.

threads

The issue of thread safety has not even been considered, other than to include this warning that it has not been considered. If someone who actually has experience with threaded programming wants to look it over, that would be great; otherwise, I may try to get to it eventually, but for now it's several items down the Todo list.

character handling

My code all assumes that each character is stored in one byte. I suspect most mail servers do this, but if your code that uses the module produces any Unicode strings, this could make issues. The sample proxy modules are naively assuming that Mail::POP3Client returns strings with octet symantics; I do not know whether this is actually the case. At minimum, this could cause the sizes of the messages to be reported incorrectly (e.g. by LIST).

client IP address

The authenticate callback was not passed the client's IP address as documented, but I think this is fixed now.

line endings

I think the new default value for EOL fixes this bug, but I'm leaving the old information here until I confirm that:

Depending on your platform and possibly your perl version, you might need to set the EOL to "\r\n" instead of the default "\n". However, if your perl version already handles this the way mine does (Linux Mandrake 9.2), setting it to "\r\n" will break it, resulting in the mail client only seeing the first header you send as a header and viewing the rest of the headers as part of the body, which is ugly; in that case you should use "\n". You can now pass an EOL parameter to new or to startserver for this, until I figure out how to fix it for real. The default is "\n" if you don't specify.

Caveat user

There may be other bugs as well; this is not release-quality code yet. Significant changes may be made to the code interface before release quality is reached, so if you use this module now you may have to change your code when you upgrade.

The Todo list is long, and contributions are welcome, especially code but also documentation, sample scripts, or other information such as how the module works with various clients, what platforms and perl versions need which setting for EOL (and how to determine this at runtime), what POP3 servers do what for the UIDL, ...

SUPPORT

Use the source, Luke. You can also contact the author with questions, but the code is supplied on an as-is basis with no warranty. I will try to answer any questions, but this is spare-time stuff for me.

AUTHOR

Jonadab the Unsightly One (Nathan Eady)
jonadab@bright.net
http://www.bright.net/~jonadab/

COPYRIGHT

This program is free software licensed under the terms of...

The BSD License

The full text of the license can be found in the LICENSE file included with this module.

Note that the modules (such as Net::Server) that are used by this module or by the sample scripts are covered under their respective license agreements and are not governed by the license of Net::Server::POP3.

SEE ALSO

perl(1)
Net::Server http://search.cpan.org/search?query=Net::Server
Mail::POP3Client http://search.cpan.org/search?query=Mail::POP3Client
The simpletest.pl script included in the scripts directory in this distribution.
The proxytest.pl script also included in the scripts directory in this distribution.

Net::Server

Mail::POP3Client

simpletest.pl

proxytest.pl

gplproxy.pl

For a more minimalist framework with a different interface, see Net::Server::POP3::Skeleton