==============================================================================
README for netpermd 0.2                                             2000-12-11
==============================================================================

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


Introduction
============

NOTE: netpermd is work in progress.  This is a pre-release.  Features,
usage, and configuration will change.

netpermd allows authorized operators to modify netperm-table without
requiring a shell account.  At this stage of development, "connect"
and "permit-destinations" rules can be added for squid-gw.


Installation
============

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

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

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

3. Configure the pathnames defined at the start of netpermd.c, in
   particular PID_FNAME.

4. Compile the libraries and the program:

        cd libem
        make
        cd ../netpermd
        make

5. Copy netpermd to the target directory:

        cp netpermd /usr/local/etc

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

6. Configure netpermd by editing netperm-table and netpermd.cfg, see
   below.

7. Add netpermd to /etc/inetd.conf using a free port of your choice.

8. Send SIGHUP to inetd.


Compilation problems
====================

If your system does not have vsnprintf(), add

  #define DONT_HAVE_VSNPRINTF

to firewall.h and retry.  netpermd requires an ANSI/ISO C compiler and
a POSIX.1 operating system.  If you don't have these, you have to port
netpermd to your system yourself.


Configuration
=============

Currently, netpermd is not configured by rules in netperm-table and
does not use authsrv.

PID_FNAME (defined in netpermd.c) is the name of the pid file (-pf
option) of squid-gw.

netpermd reads /usr/local/etc/netpermd.cfg (USER_FNAME).  That file is
organized in lines.  Empty lines and lines starting with "#" are
ignored.  All other lines are expected to contain at least words,
separated by white space: user, password, and switches.

There are currently two switches, "-connect" and "-destinations".
"-connect" means that "connect" rules for squid-gw can be added by
that user.  "-destinations" means that "permit-destinations" rules can
be added by that user. Following "-destinations", you can specifiy the
configuration classes which can be added by that user.  netpermd uses
the first line in the configuration file which matches the user name
and password entered by the user.  Example:

    cfg17   zU%x#2  -connect
    cfg18   17=42   -destinations
    cfg19   /pwd,/  -connect -destinations java js cookies

Here, user "cfg17" may add "connect" lines.  User "cfg18" may add
"permit-destinations" lines. User "cfg19" may add "connect "lines and
"permit-destinations" lines with classes "java", "js", and "cookies".
He cannot use other classes.

netpermd adds new rules in netperm-table before the line reading

    # netpermd: squid-gw end

For clarity, you might want to add these two lines:

    # netpermd: squid-gw start
    # netpermd: squid-gw end

netpermd will insert the new lines between those lines.


Running netpermd
================

netpermd is started like a telnet daemon by inetd.

To edit netperm-table manually while netpermd is running, either
temporarily disable netpermd (e.g., in inetd.conf) or create
/usr/local/etc/netperm-table.lock (see LOCK_FILE in netpermd.c) before
editing and delete that file after editing.


Using netpermd
==============

Just telnet to the port configured in inetd.conf.  netpermd will ask
for the user name and the password.  If there is a matching user in
the configuration file, a menu will be displayed:

  c  Add a "connect" line (for https)
  d  Add a "destinations" line
  q  Quit

The "c" command will be offered only if "-connect" is specified for
the user.  The "d" command will be offered only if "-destinations" is
specified for the user.


Version 0.1 2000-04-17
----------------------

- First pre-release

Version 0.2 2000-12-11
----------------------

- Note: If you are upgrading from version 0.1, replace "connect" with
  "-connect" in the configuration file!

- Allow addition of "permit-destination" lines

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