Copyright 2007 by ArkanoiD <ark@eltex.net>

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.


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 }

     -authall parameter enables authentication if needed, -extnd means
     extended authorization should be requested by authsrv and -auth
     is similar to -commands but specifies list of commands available
     after authentication (it includes all -commands parameters implicitly).

  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

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

