==============================================================================
README for pop-gw 0.6                                               2000-04-17
==============================================================================

Copyright 1997-2000 by Eberhard Mattes <em-gw@windhager.de>
Donated to the public domain.  No warranty.


Introduction
------------

pop-gw is an add-on for the TIS Firewall Toolkit 2.0; it enables
selected external users to access an internal POP server.


Installation
------------

1. After installing the TIS Firewall Toolkit, unpack cmd-gw.tar.gz or
   em-gw.tar.gz into the main directory of the TIS Firewall Toolkit:

        cd /sources/fwtk
        gunzip </dist/cmd-gw.tar.gz | tar xf -

2. If your `make' tool requires `.include' instead of `include', replace
   `include' with `.include' in pop-gw/Makefile and libem/Makefile.  (This
   can also be done by running `fixmake' of the TIS Firewall Toolkit.)

3. Compile the libraries and the program:

        cd libem
        make
        cd ../pop-gw
        make

4. Copy pop-gw to the target directory:

        cp pop-gw /usr/local/etc

   (see the definition of DEST in Makefile.config for the target
   directory.)


Compilation problems
--------------------

If your system does not have vsnprintf(), add

  #define DONT_HAVE_VSNPRINTF

to firewall.h and retry.


Configuration
-------------

pop-gw is -- like the TIS FWTK programs -- configured by rules in
netperm-table.  It reads all rules using the pop-gw and * keywords.
pop-gw understands the following attributes:

  groupid <GROUP>

     Run with group ID <GROUP>.

     Example:
          pop-gw: groupid nogroup

  hosts <HOST-PATTERN>... [ -user <USER-PATTERN>... ]

     Specify access permissions.  If the "-user" option is used, POP
     user-ids matching <USER-PATTERN> are allowed for hosts matching
     <HOST-PATTERN>, in addition to the user-ids configured by the
     "user" lines.  "*" in <USER-PATTERN> matches any number of
     characters, "?" matches exactly one character.

     Example:
          pop-gw: deny-hosts unknown
          pop-gw: permit-hosts 199.99.99.1 -user joe
          pop-gw: permit-hosts 199.99.99.2 -user janet jim
          pop-gw: permit-hosts 199.99.99.2 -user *
          pop-gw: permit-hosts 199.99.99.*

  pass-limit <SIZE>

     Limit POP passwords to <SIZE> characters.  The default value is
     31, the maximum value is 256.

  server <HOST>

     Forward to the POP server on <HOST>.  <HOST> can be an IP address
     or a hostname.  This attribute is mandatory.

     Example:
          pop-gw: server pop.internal.foo.bar

  user <USER-PATTERN> ...

     Enable access for POP user-ids matching <USER-PATTERN>, no matter
     from where the connection comes.  "*" in <USER-PATTERN> matches
     any number of characters, "?" matches exactly one character.

     If there are multiple "user" lines, all of them will be read.
     Compare to "hosts"'s "-user" option.

     Example:
          pop-gw: user janet jim joe
          pop-gw: user john jon
          pop-gw: user foo*

  user-limit <SIZE>

     Limit POP user-ids to <SIZE> characters.  The default value is
     31, the maximum value is 256.

  userid <USER>

     Run with user ID <USER>.

     Example:
          pop-gw: userid nouser


Running pop-gw
--------------

pop-gw can be run either from inetd:

        pop-gw

or as daemon:

        pop-gw -daemon <PORT>

<PORT> is the port number.


Using pop-gw
------------

In the mail client, configure the host running pop-gw as POP server.
It is strongly recommended to use the APOP command instead of USER and
PASS, in order to avoid sending the password as clear text.


HISTORY
=======

Version 0.1, 1997-04-09
-----------------------

- Initial version

Version 0.2, 1997-08-22
-----------------------

- Add -user option for permit-hosts

Version 0.3, 1997-08-23
-----------------------

- Add APOP support

Still version 0.3, 1998-01-30
-----------------------------

- Check version of library

Version 0.4, 1998-09-03
-----------------------

- Support multiple "user" lines

- Check snprintf() and vsnprintf()

Version 0.5, 1999-03-17
-----------------------

- Use copy_bidir()

Version 0.6, 2000-04-17
-----------------------

- Support "*" and "?" in POP user-id patterns

- Add "pass-limit" and "user-limit"

==============================================================================
                                THE END
==============================================================================
