==============================================================================
README for cmd-gw 0.6                                               1997-07-20
==============================================================================

Copyright 1997 by Eberhard Mattes <mattes@azu.informatik.uni-stuttgart.de>
Donated to the public domain.  No warranty.


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

cmd-gw is an add-on for the TIS Firewall Toolkit 2.0; it enables users
to execute programs such as ping and traceroute on the gateway host.


Warning
-------

cmd-gw is only as safe as your dig, finger, ping, and traceroute
clients are.  If these have some way for running a program named on
the command line or for compromising the gateway host in other ways,
you're in trouble.  Otherwise, cmd-gw should be safe.

It's not yet possible to configure cmd-gw to run the programs
chroot-ed.


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

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

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

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

3. In cmd-gw/cmd-gw.c, configure the commands and programs to be run
   (see next section).

4. Compile the libraries and the program:

        cd libem
        make
        cd ../cmd-gw
        make

5. Copy cmd-gw to the target directory:

        cp cmd-gw /usr/local/etc

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


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

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

  groupid <GROUP>

     Run with group ID <GROUP>.

     Example:
          cmd-gw: groupid nogroup

  hosts <HOST-PATTERN>...

     Specify access permissions.

     Example:
          cmd-gw: permit-hosts 199.99.99.*
          cmd-gw: deny-hosts 199.99.99.1

  userid <USER>

     Run with user ID <USER>.

     Example:
          cmd-gw: userid nouser

The commands understood by cmd-gw and the programs to be run must be
configured in the source code (sorry).  This is done by modifying the
`cmds' and `pgms' arrays in cmd-gw/cmd-gw.c.  The `cmds' array defines
the commands; the columns have the following meaning:

1. name of the command
2. index into `pgms' table (1-based), or 0 for internal command
3. help message
4. 0 for external command, pointer to function for internal command

The `pgms' array contains the absolute path names for the external
commands.  Before compiling cmd-gw you should adjust the path names
for your system.

To add a command, add an entry to the `cmds' array, using the next
available index in the second column (if there are 4 entries in
`pgms', choose index 5).  Then, add the absolute path name to the end
of `pgms'.

To remove a command, delete the entry from the `cmds' array, remove
the path name from the `pgms' array, and renumber the remaining
entries of the `cmds' array.  To remove the `finger' command, for
instance, from the default configuration, remove the "finger" line
from `cmds', remove the "/usr/bin/finger" line from `pgms', replace 3
with 2, 4 with 3 in the second column of `cmds'.


Running cmd-gw
--------------

cmd-gw can be run either from inetd:

        cmd-gw

or as daemon:

        cmd-gw -daemon <PORT>

<PORT> is the port number.


Using cmd-gw
------------

Just telnet to the configured port on the gateway machine and type the
desired command.  You can get help by typing `?' or `help'.  You can
quit by typing `exit' or `quit'.


Future plans
------------

- use netperm-table for configuring the commands

- add cmd-tn program:  cmd-tn traceroute a.b.c.d >route1

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