NAME

t/server/start - simple POP3 server for testing Mail::Transport::POP3

SYNOPSIS

open( $pop3,"$^X t/server/start t/messages | " );

open( $pop3,"$^X t/server/start t/messages minimal | " );

open( $pop3,"$^X t/server/start t/messages apoponly | " );

open( $pop3,"$^X t/server/start t/messages autodelete | " );

open( $pop3,"$^X t/server/start t/messages noextra | " );

open( $pop3,"$^X t/server/start t/messages standardport | " );

DESCRIPTION

This POP3 server is created for testing the Mail::Transport::POP3 only. It cannot be used as real POP3 server (yet).

The server takes on a randomly selected, free port to prevent interference with existing applications. Start the server by running this script from another script while capturing the output to STDOUT, e.g. like:

open( my $pop3,"$^X t/server/start t/messages |" )
 or die "Could not start POP3 server: $!\n";
my $port = <$pop3>;

The returned $pop3 file handle produces informational texts: it will tell you the port which is occupied by the server, and when the server shuts down. It will also report some statistics on the performance of the server.

The server will be bound to localhost (127.0.0.1) at the port number of the first line that is printed to STDOUT by this script.

The first parameter to the script indicates the directory in which the actual messages (each message as a seperate file) are located. In the example, this is "t/messages".

Any other parameters to the script are optional: they consist of keywords to indicate any settings or peculiarities of certain POP3 server implementations. The following keywords are recognised:

minimal

If the keyword "minimal" is specified, only the minimal set of POP3 commands will be allowed (i.e. USER, PASS, STAT, LIST, RETR, DELE, RSET, NOOP and QUIT). The optional POP3 commands (APOP, TOP and UIDL) are also supported if this keyword is not specified.

apoponly

If the keyword "apoponly" is specified, then authorization will only be allowed with the APOP command (i.e. authorization with USER will yield a negative response). Please note that you cannot use this together with the "minimal" keyword, as APOP is one of the optional POP3 commands (which is excluded if you use the "minimal" keyword).

autodelete

If the keyword "autodelete" is specified, any messages that are completely retrieved with RETR or TOP (without specification of number of lines in the body to return) will be automatically marked for deletion. This will cause those messages to be deleted if the session is finished with a QUIT command. This coincides with system resource restrictions imposed by some providers.

noextra

If the keyword "noextra" is specified, then all messages will be served with a check for a CRLF pair at the end of the original messasge: if a CRLF is found, then only ".\r\n" will be added to indicate the end of a message that are retrieved with RETR or TOP.

standardport

If the keyword "standardport" is specified, then an attempt will be made to start the POP3 server on port 110, the standard POP3 port. Please note that this will only be successful if the current user has sufficient privileges (usually only the root user will be allowed to listen on ports < 1024).

User name is always "user" and the correct password is always "password". Any other combination will always fail. APOP authorization can be used if the "minimal" keyword is not specified. The following script will help you in debugging APOP authorization:

use Digest::MD5 qw(md5_hex);
while (<>) {
  s#\r?\n?$##s;
  print md5_hex( $_.'password' )."\n";
}

Copy the string that was sent by the initial greeting of the server (including the <> brackets), paste this into the running script, press ENTER. The script will respond with a 32 character hexadecimal string. Copy that and the enter the authorization thus:

APOP user 0123456789abcdef0123456789abcdef

Note that the above hex string is only an example of course.

The following commands do not exist in the POP3 protocol, but are intended to simulate certain events.

The BREAK command can be used to simulate the breaking of a connection. After a BREAK is received, the connection is broken by the server (without sending a response to the client). No messages will be deleted even if any messages were marked for deletion. This can also be used to simulate a timeout, of course.

The EXIT command can be used for test-suites: when sent from the client, it will cause the server to shut down (as if an EXIT was sent) whenever the client does a QUIT command. When the servers shuts down, its prints its statistics on STDOUT. Statistics returned are:

- number of succesful logins
- each command + frequency in alphabetical order

so a statistics list for one successful session could be:

1
DELE 102
EXIT 1
LIST 1
PASS 1
QUIT 1
RETR 102
STAT 1
UIDL 1
USER 1