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
    This is alpha code. That means it needs work and doesn't yet implement
    everything it should. Don't use it unless you don't mind fixing up the
    parts that you find need fixing up. Lots of parts still need fixing. You
    have been warned.

    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

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.

    port
        The port number to listen on. 110 is the default. You only need to
        supply a port number if you want to listen on a different port. The
        user or group you are running as needs permission to listen on this
        port.

    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. You only need to supply a servertype 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 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. It must not be longer
        than 506 bytes, for arcane reasons involving RFC1939. (The length is
        not checked automatically by Net::Server::POP3, though it may be in
        a future version.) This 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 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.

BUGS
    Some things are just plain not implemented yet. 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. There
    may be other bugs as well; this is very alpha stuff. 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. Caveat user.

SUPPORT
    Use the source, Luke. You can also contact the author with questions,
    but I cannot guarantee that I will be able to answer all of them in a
    satisfactory fashion. The code is supplied on an as-is basis with no
    warranty. I will try, 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 this module uses (such as Net::Server) 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

