R2d2

This software has been built using and depends on ServerKit.

Overview

R2d2 is an efficient multi-threaded RFC1939-compliant POP3 server intended for use with a MySQL-based accounts db and Maildir-based maildrops. Optional TLS (previously/also known as SSL) support is also implemented, in both POP-SSL (port 995) form and the STLS extended POP3 capability.

This server does have some unique requirements for the Maildir structure, the maildir message filenames must not exceed 70 characters up to but not including the ':' seperator. The filenames must also include the "rfc822 size" of the messages they store, presented in all-caps hexadecimal following a 'Z' character in the "middle" portion of the unique name.

These requirements mean a specialized delivery routine must be utilized which ensures 70 character long unique filenames and calculates the rfc822 size during delivery placing it in the filename accordingly.


Usage

It is advised that you read the ServerKit documentation before trying to use this module, as most of the basic usage is simply using ServerKit, nothing specific to this module.

You will probably want to use the included ServerKit personality as a starting point, found in the source archive as a directory named personality. Within the personality you will find a c11n file, a modules subdirectory, and a svsdir subdirectory.

The c11n file is a ServerKit configuration file, you will need to at least modify the database settings so ServerKit can successfully communicate with your database system. Another configuration value that you will almost certainly have to set is maildrop_query_format_string.

The maildrop_query_format_string is the SQL query r2d2 will use to authenticate email users and retrieve the authenticated users' maildir path. See the Configuration section for a list of supported substitutions for use in the format string.

You are responsible for creating a query that is compatible with your mail system database schema, and ensuring that the query will:

  1. return an empty set when authentication fails
  2. return the correct maildir path when authentication succeeds

Interpreting the logs

The log output of r2d2 is mostly self-explanatory. All logging is done via ServerKits logging facilities, which means the logs can go through the traditional syslog() interface or may bypass the traditional syslog() method by sending UDP syslog messages directly over the network to a syslog collection server for greater efficiency.

The only unique aspects of r2d2 logging are the delays count and sequence string presented on disconnect log entries which occur at the end of every r2d2 pop3 session.

Delays refer to the number of socket-based IO delays detected by r2d2 which resulted in handing the session off to the delayed work manager in ServerKit.

Sequence presents a record of what commands were issued throughout the POP3 session in the order they were received. For example:

  server.pop3.r2d2[13906]: [1] disconnected: peer quit, sequence="upsUr4d4q" delays="3"
The above example issued USER PASS STAT UIDL RETR RETR RETR RETR DELE DELE DELE DELE QUIT.

Here is a list of all the sequence characters and their meaning:
c CAPA
u USER
p PASS
q QUIT
s STAT
U UIDL
i UIDL msgnum
L LIST
l LIST msgnum
d DELE
R RSET
r RETR
t TOP
n NOOP
^ STLS Only possible on TLS-enabled builds
! Invalid command


Configuration

The following configuration options are supported:
NameTypeDescription
min_sessions integer Minimum number of sessions to allocate.
max_sessions integer Maximum number of sessions to allocate.
min_threads integer Minimum number of worker threads to create.
max_threads integer Maximum number of worker threads to create.
database string Identifier of database connection pool instance to use, see ServerKit configuration for assistance with database connection pool configuration.
backlog integer Size of kernel-level connection backlog, passed to listen() as-is
address string Address to listen on
port integer Port to bind to
maildrop_query_format_string string SQL query with some special characters which get substituted at runtime. Currently supported substitutions include:
  • %u POP3 USER argument
  • %p POP3 PASS argument
The following options are only available when TLS support has been compiled into r2d2.
tls_address string Address to listen on for "Secure pop" connections, irrelevant when tls_port is 0
tls_port integer Port to bind to for "Secure pop" connections, setting to 0 disables the "Secure pop" on a seperate port feature, but leaves the STLS capability intact.
x509_key_file string X509 Certificate key file for the server
x509_cert_file string X509 Certificate file for the server

You can query the module for its supported configuration options by simply running it like a normal executable program. This is the preferred method of keeping informed on what configuration values are supported and what the defaults are.

Here is some sample output of running the module:
swivel@volatile:~/src/r2d2-0.0.2$ ./r2d2.so
ServerKit bundled module inspector

- Summary -
Name: r2d2
Description: High performance Maildir POP3 server designed for large scale usage
Module version: 0.0.2
ServerKit build environment version: 1.2.0
Authors: Vito Caputo <vcaput**NOSPAM**.com>

- Supported configuration options & defaults -
port = 110
address = "0.0.0.0"
backlog = 32
min_sessions = 128
max_sessions = 32768
max_threads = 500
min_threads = 10
# database = ""
maildrop_query_format_string = "SELECT Maildrop FROM EmailAddress WHERE Address=\"%u\" AND BINARY Password=PASSWORD('%p') AND PopAttribute=1"
x509_key_file = "key.pem"
x509_cert_file = "cert.pem"
tls_port = 995
tls_address = "0.0.0.0"


Source archives

Release date Tar.gz MD5 checksum
12-04-2007 r2d2-0.0.3.tar.gz 209554a21d2f096d3f01b66966c20b74
11-30-2007 r2d2-0.0.2.tar.gz a1d29d9f19a9dc459b34609241894596
11-21-2007 r2d2-0.0.1.tar.gz 611a7928f6244c0c64545a04d1007bb2

License

R2d2 is distributed under these terms:
You must retain as-is all copyright-related notices in the source and program
output.

You are otherwise free to modify, use, or distribute this program in binary
or source form, as long as all copyright notices remain unmodified.

You must make the source available to those you distribute binaries to, if
you distribute binaries built from modified source you must make the modified
source available (similar to GPLv2).

Contribute

I accept patches or feature requests, simply email me at the email address contained within the source tree. I am also always looking for testers so if you're willing to test new features, let me know.

If you would like to contribute to this project monetarily, feel free to donate via the paypal button below.

© 2008 Vito Caputo