
perdition v0.0.0
May 1999
Horms <horms@vergenet.net>
----------------------------------------------------------------------


Overview
--------

Perdition is allows users to connect to a content-free pop server
that will redirect them to their real pop server.  This enables
pop for a domain to be split across multiple real pop servers on
a per user basis. This can also be used to as a POP proxy
especially in firewall applications.

When a connection is made to perdition it reads the USER and PASS
commands and then refers to its popmap to find where the user's
connection should be forwarded to. A connection to the foreign
pop server, perdition then enders the USER and PASS commands to
the foreign server. If authentication is successful then
perdition pipes data between the client and the foreign server.
If authentication fails then the foreign server connection is
closed and the client connection is reset to the state it was in
on initial connection. That is new USER and PASS commands are
expected.

Logs are logged via syslog using the facility mail.  You should
inspect /etc/syslog.conf to find where these logs are written.
Under Red Hat 5.2 these logs will be written to /var/log/maillog.


Options
-------

Perdition does not have a configuration file at this stage.
Instead a number of command line options are provided to control
perditions behavior.


Usage: perdition [options]
  options:
     -h|--help:       Display this message
     -m|--mapname:    gdbm map for users to hosts and port
                        (default /etc/perdition/popmap.db)
     -i|--inetd_mode: Run in inetd mode
     -p|--port:       Port to listen on (default 110)
     -u|--username:   Username to run as (default nobody)
     -g|--group:      Group to run as (default nobody)


Note: The -p option is not used if -i is specified.


Popmap
------

The popmap controls the pop server to which each user will be
directed once they have connected to perdition. The format is;

<username>:<hostname|ip address>[:<port number|service name>]

E.g.

horms:janice.vergenet.net:110
jain:pop3.zipworld.com.au


To build the popmap into a binary format the makegdbm which is
provided as part of perdition is used. To rebuild the popmap run:

makegdbm popmap.db < popmap

Alternatively a makefile is provided in /etc/perdition in the RPM
distribution and you can simply run make in /etc/perdition to
rebuild the popmap.


Stand Alone Mode
----------------

Normally perdition will bind to a port, and listen for
connections.  The default port is 110 and an alternate port can
be specified with the -p command line option. In this mode
perdition will fork to manage clients.

In the RPM distribution perdition can be started and stopped in
stand alone mode using:

/etc/rc.d/init.d/perdition start
and 
/etc/rc.d/init.d/perdition stop

If you are using the RPM and you do not want perdition to run in
stand alone mode at boot up after installation run:

/sbin/chkconfig --del perdition



Inetd Mode
----------

Perdition can be used in conjunction with inetd. This enables
perdition to benefit from tcpd where access can be controlled to
some extent using /etc/hosts.allow and /etc/hosts.deny.

To use perdition with inetd you need to add a line to
/etc/inetd.conf and then restart inetd. The following line was
added to run perdition with inetd under Red Hat 5.2.:

pop-3   stream  tcp     nowait  root    /usr/sbin/tcpd perdition -i

inetd was then restarted by running:

 /etc/rc.d/init.d/inet restart

The procedure for this may vary slightly on different
installations.  In particular the port may be known at pop3
instead of pop-3 in /etc/services and it you may have to run
killall -HUP inetd or worse still kill -HUP <inetd pid> to
restart inetd.



Local Authentication
--------------------

Optionally perdition can be set up to authenticate the user
locally once the USER and PASS commands are entered. This
authentication happens before the connection to the foreign
server is made and must succeed for a connection to the foreign
server to be made. 

Support for this must be compiled into perdition. To do this do
the following;

tar zxf perdition-0.0.0.tar.gz
cd perdition-0.0.0
./configure
edit perdition/etc/Makefile so that -DAUTHENTICATE_IN is added to the CFLAGS
make
make install

If you are using the RPM you could optionally copy
perdition/perdition over /usr/sbin/perdition instead of running
make install. This is a little nasty and if this option becomes
used frequently I will make it more accessible.

This authentication uses PAM and a sample pam configuration file
for perdition can be found in etc/pam.d/perdition in the source
tree. This should be dropped into /etc/pam.d.



