==============================================================================
README for cmd-gw 0.9                                               1998-09-03
==============================================================================

Copyright 1997, 1998 by Eberhard Mattes <em-gw@windhager.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 by
using TELNET.  A client program, cmd-tn, is also provided to simplify
usage.


Warnings
========

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.  At least, it's
safer than telnetting into the gateway host to issue the commands.

Note that the finger command will allow anyone who is allowed access
to cmd-gw to find out who's working on the gateway host (of course,
noone should be working on the gateway host).

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 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 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.)

6. Configure cmd-gw by editing netperm-table, see below.

7. Start cmd-gw (don't forget to arrange for cmd-gw being started
   automatically when the system comes up), see below.

8. Optionally compile cmd-tn for the client machines (it's also built
   by default, in case you want to try it on the gateway host) and
   install cmd-tn and the fw-* scripts on the clients.


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

If your system does not have vsnprintf(), add

  #define DONT_HAVE_VSNPRINTF

to firewall.h and retry.


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>... -commands <COMMAND>...

     Specify access permissions: all hosts matching the host patterns
     are allowed to connect to cmd-gw.  Following the -commands option
     (which isn't optional), the allowed external commands are listed.
     The built-in commands (exit, help, once, quit, ?) are always
     allowed and must not be listed.  If `*' is listed, all external
     commands are allowed.

     Example:
          cmd-gw: deny-hosts 199.99.99.1
          cmd-gw: permit-hosts 199.99.99.99 -commands *
          cmd-gw: permit-hosts 199.99.99.*  -commands finger dig

  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 with TELNET
========================

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'.  By prefixing a command with the
special command `once', cmd-gw will terminate the session
automatically after executing the command.


Using cmd-tn
============

The cmd-tn program simplifies usage of cmd-gw.  It takes the cmd-gw
command and its arguments on the command line and, of course, supports
redirection of the output.  Examples:

        cmd-tn help
        cmd-tn traceroute ftp.some-domain.com
        cmd-tn dig @ns.some-domain.com some-domain.com axfr >/tmp/sd
        cmd-tn finger @host.some-domain.com

cmd-tn connects to the gateway host and port number specified in the
CMDGWSERVER environment variable, which should contain the host name
(or IP address), a colon, and the port number.  Example:

        CMDGWSERVER=gatekeeper:7777

The following shell scripts are included: fw-dig, fw-finger, fw-ping,
fw-traceroute; you need to adapt the value of CMDGWSERVER in these
scripts as they override the global value of CMDGWSERVER (that is,
they don't require CMDGWSERVER to be set globally).  Examples:

        fw-traceroute ftp.some-domain.com
        fw-dig @ns.some-domain.com some-domain.com axfr >/tmp/sd
        fw-finger @host.some-domain.com


Future plans
============

- netperm-table should have more control over the external commands,
  for instance, it should be possible to require a @host argument for
  finger

- authentication

- log termination codes


History
=======

Version 0.7, 1998-01-31
-----------------------

- Clean up the code

- Log commands

- Add `once' command prefix

- Add cmd-tn, fw-dig, fw-finger, fw-ping, and fw-traceroute

Version 0.8, 1998-03-16
-----------------------

- Add `-commands' option (which isn't optional) to `hosts' attribute;
  you have to change netperm-table!

- cmd-tn now uses quotes only if necessary

Version 0.9, 1998-09-03
-----------------------

- Check snprintf() and vsnprintf()

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