NAME
Mail::POPRelay - Dynamic Relay Access Control
DESCRIPTION
Mail::POPRelay 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 software and others is that
neither modification of the POP server or mail program is needed.
Mail::POPRelay should integrate seamlessly with any server given the
correct agent and configuration are used.
Agents are executables that provide support for various POP servers.
Each agent possesses the ability to call functions from the
Mail::POPRelay framework, load configuration files and do whatever else
is necessary to support dynamic relaying.
Configuration files allow the user (you) to specify options that are
read by an agent. These options inform the agent how to work with a
server's configuration. Following is a list of available options and
their descriptions:
mailLogFile
Absolute location of the mail log file to watch for incoming
logins. Defaulted to '/var/log/maillog'.
mailProgram
Set to the mail program service name. This option's value will
be replaced with the special %m variable that can be used where
specified. Defaulted to 'sendmail'.
mailProgramRestart
Set to '1' if the mail server must be restarted after modifying
the relay file. This shouldn't be necessary if using an access
database style relay file. Defaulted to '0'.
mailProgramRestartCommand
Set to the command required for restarting your email server.
Special variables %m and %r can be used in this string.
Defaulted to '/etc/init.d/%m restart'.
mailRelayIsDatabase
Set accordingly if your mail relay file is a database. Defaulted
to '0'.
makemapLocation
Usage is deprecated. Reference mailRelayDatabaseCommand.
mailRelayDatabaseType
Usage is deprecated. Reference mailRelayDatabaseCommand.
mailRelayDatabaseCommand
Set to the command required for creating the relay database.
Special variables %m and %r can be used in this string.
Defaulted to '/usr/sbin/makemap hash %r < %r'.
mailRelayDirectory
Absolute location of the spool directory used to create relay
tracking files. Defaulted to '/var/spool/poprelay'.
mailRelayFile
Absolute location of the mail access relay file. This option's
value will be replaced with the special %r variable that can be
used where specified. No default value.
mailRelayFileFormat
Set to the format of your relay file. Special variables %m, %r
and %i may be used in this string. %i is replaced with the
current IP address allow relaying access. Defaulted to '%i
RELAY' if mail relay file is set to '1' or '%i' if not.
mailRelayPeriod
After a user successfully logs in we must set a period for which
he/she can relay mail. Specify this value in seconds. No default
value.
Use the SYNOPSIS to help create your own agents and configuration files.
FLOW
1 An agent is executed with a configuration file
2 The mailLogFile is monitored for instances of mailLogRegExp (loop)
3 A "mailRelayDirectory/(authenticated IP)" file is created if an
instance is found
4 The mailRelayFile is updated based off the mailRelayDirectory spool
5 The mailRelayDatabaseCommand is executed if the mailRelayIsDatabase
option is set
6 The mailProgramRestartCommand is executed if the mailProgramRestart
option is set
Note: The config-file is reloaded when the agent receives a HUP signal.
SYNOPSIS
Creating Custom Agents
o Create a file in the ./bin directory for your agent
o Copy this header into your agent file:
----- BEGIN HEADER -----
use strict;
use Mail::POPRelay;
use vars qw[@ISA ];
# Mail::POPRelay is designed to be subclassed.
@ISA = qw[Mail::POPRelay ];
----- END HEADER -----
o Create a regular expression
This is done to match user authentication log entries for the
POP server you're adding support and is necessary for dynamic
relaying. The regular expression must place the authenticating
user name in $1 and IP address in $2. Monitor the mailLogFile
for incoming user authentication entries if unsure about its
format.
o Use this conventional template to instantiate Mail::POPRelay
----- BEGIN TEMPLATE -----
my $popDaemon = new Mail::POPRelay::Daemon(
$ARGV[0], # config-file to use
{ mailLogRegExp => 'a regular expression',
overridingOption => 'a value',
}
};
----- END TEMPLATE -----
o Overriding options
Any options specified as parameters to Mail::POPRelay::Daemon
will override those in the config-file.
o Calling additional methods
It is possible to call other methods from the POPRelay class in
your agent. Reference the METHODS section below.
Creating Custom Configuration Files
o Create a file in the ./conf directory for your configuration
o Specify one option and value per line
Each line is in the format "optionName = value". Comment lines
begin with a # symbol. Reference the DESCRIPTION section above
for a complete list of options and their meanings.
METHODS
$popRelay->wipeRelayDirectory();
Remove all relay access files in the spool (mailRelayDirectory).
$popRelay->cleanRelayDirectory();
Remove expired access files in the spool (mailRelayDirectory).
$popRelay->generateRelayFile();
Create and write out a relay file based from the access files in
the spool (mailRelayDirectory). An attempt to create the spool
directory will be made if it doesn't already exist. This method
now also handles restarting the mail program and/or creating the
access database file if necessary.
$popRelay->restartMailProgram();
Use is deprecated. Not absolutely necessary anymore. Read above.
$popRelay->addRelayAddress('User Name', 'IP Address')
Adds a relay access file to the spool (mailRelayDirectory).
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>
Verified and tested the ipop3d_vpopd agent.
Dave Doeppel <dave@hyperburn.com>
Verified and tested integration with the Exim mailer.
Fuat Gozetepe <turk@lbox.org>
Verified and tested integration with Slackware.
Mike Polek <mike@pictage.com>
Found a race condition in Daemon.pm where relaying information
could have been lost.
Sven-Oliver Stietzel <dev@netshake.de>
Added a config file for SUSE Linux and Qpopper agent.
AUTHOR
Keith Hoerling <keith@hoerling.com>
SEE ALSO
Mail::POPRelay::Daemon(3pm), poprelay_cleanup(1p), poprelay_ipop3d(1p).