NAME
    Mail::POPRelay - Dynamic Relay Access Control

DESCRIPTION
    Mobile POP Relay is designed as a framework to support relaying through many different
    types of POP and email servers. This software is useful for mobile users and is fully
    compatible with virtual domains.

    One of the main differences between this relay server and others is that neither
    modification of the POP server or mail program is needed. This software should integrate
    seamlessly given the correct agent is provided. Each agent possesses the ability to
    specify certain variables in order to create a custom tailored relay agent per your
    servers setup. Here is a list of the available options and their descriptions:

            mailLogFile           
                    Absolute location of the mail log file to monitor (tail).
                    Defaulted to '/var/log/maillog'

            mailProgram
                    Mail program service name.  Used to restart the email server
                    if necessary through /etc/init.d.  Proper naming here should
                    reflect your mail service name in /etc/init.d.
                    Defaulted to 'sendmail'

            mailProgramRestart
                    Should the mail server be restarted after adding to the relay file?
                    This shouldn't be necessary if using an access database style relay file.
                    Defaulted to '0'

            makemapLocation
                    Absolute location of makemap used to create access database style
                    relay files.
                    Defaulted to '/usr/sbin/makemap'

            mailRelayIsDatabase
                    Set accordingly if your mail relay file is a database.
                    Defaulted to '0'

            mailRelayDatabaseType
                    Ignore this value if your mail relay file is not a database.
                    Specify the type for makemap if it is.
                    Defaulted to 'hash'

            mailRelayDirectory
                    A spool directory for creating program related relay tracking
                    files.
                    Defaulted to '/var/spool/poprelay'
                    
            mailRelayFile
                    Absolute location of the mail access relay file.
                    No default value.

            mailRelayPeriod
                    After a user successfully logs in we must set a period for
                    which he/she can relay mail.  Specify this here in seconds.
                    No default value.

    Use the SYNOPSIS to help create your own agents.

SYNOPSIS
    So how do I create my own agents? Simple. Create a file in the ./bin directory for your
    agent and follow the instructions below.

    1) Copy this header into your agent file:

    ----- BEGIN HEADER -----

    use Mail::POPRelay;

    # Mail::POPRelay is designed to be subclassed.

    use strict;

    use Mail::POPRelay;

    use vars qw[@ISA ];

    @ISA = qw[Mail::POPRelay ];

    ----- SNIP -----

    2) Create a configuration for the agent.

    Each agent should work w/ specific POP and Mail daemon configurations. To accommodate
    these configurations, each agent combines different options described above in
    DESCRIPTION.

    As a good foundation to get started, lets re-create the existing generic iPOP3 / Sendmail
    configuration that already exists in the ./bin directory.

    Copy the below agent body into your agent file:

    ----- BEGIN AGENT BODY -----

    my %options = ( mailRelayDirectory => '/var/spool/poprelay', mailRelayPeriod => 86400, #
    in seconds mailLogRegExp => 'ipop3d\[\d+\]:.+user=(\w+) host=.*\[(\d+\.\d+\.\d+\.\d+)\]
    nmsgs=',

            # redhat 7.0 w/ access db
            mailRelayFile         => '/etc/mail/access',
            mailRelayIsDatabase   => 1,
            mailRelayDatabaseType => 'hash',
    );
    my $popDaemon = new Mail::POPRelay::Daemon(\%options);

    ----- SNIP -----

    3) Modify / add or delete agent options

    It may be necessary to change the relaying period. Simply modify the value of
    "mailRelayPeriod" from 86400 to your own value.

    Maybe you aren't running a database compatible mail daemon. This might require switching
    the value of "mailRelayIsDatabase" from 1 to 0 and adding the option "mailProgramRestart
    => 1".

    Modification of the mailLogRegExp option may be necessary. Scan your mail log file for the
    POP authentication line and set a matching regular expression for the mailLogRegExp value.
    The user name must end up in $1 and the relay host in $2.

METHODS
    $popRelay->wipeRelayDirectory();
                Remove all relay access files

    $popRelay->cleanRelayDirectory();
                Remove expired access files

    $popRelay->generateRelayFile();
                Create relay file in relay directory.  An attempt to create 
                the relay directory will be made if it doesn't already exist.
                This method now also handles restarting the mail program and/or
                creating the access db file if necessary.

    $popRelay->restartMailProgram();
                Use is deprecated.  Not absolutely necessary anymore.  Read above.

    $popRelay->addRelayAddress('User Name', 'IP Address')
                Adds a user to relay mail for.

DIAGNOSTICS
    die(). Will write to syslog eventually.

CONTRIBUTIONS
    John Beppu <beppu@lbox.org>
            Found a bug in the signal handlers.  Thanks for looking over my code ;)

    Jefferson S. M <linuxman@trendservices.com.br>
            Provided a testing facility for the ipop3d_vpopd agent.

AUTHOR
    Keith Hoerling <keith@hoerling.com>

SEE ALSO
    Mail::POPRelay::Daemon(3pm), poprelay_cleanup(1p), poprelay_ipop3d(1p).

