README for Internet gateway program (gw) v1.31
Andy McFadden (fadden@uts.amdahl.com)
2-Jun-92


usage: gw [-v] [-f .gwrc]

    -v	: verbose mode
    -f  : specify .gwrc file; default is .gwrc in current working directory


Basically, this program shuttles TCP and UDP packets between two hosts.  You
need to use this when you are running on a network isolated from the Internet,
but have access through an Internet gateway machine.

The program reads from a configuration program (called ".gwrc"), which looks
something like this:

-----
# gw configuration file
#
# format:
# tcp local-port server-name server-port
# udp local-port1 local-port2 client-name client-port
#

# Netrek TCP ports
tcp 2592 bigdog.berkeley.edu 2592
tcp 2593 bezier.Berkeley.EDU 2592
tcp 2594 bronco.ece.cmu.edu 2592
tcp 2595 rwd4.mach.cs.cmu.edu 2592
tcp 2605 calvin.usc.edu 2592
tcp 2615 scrod.cs.washington.edu 2592

# here's a DikuMUD server; telnet to it
tcp 4001 bigboy.cis.temple.edu 4000

# Weather (re)port
tcp 6411 madlab.sprl.umich.edu 3000

# UDP ports

# setup for bezier, client on tde
tcp 4500 bezier.berkeley.edu 2592
udp 5000 5001 tde.uts 5100
-----


More than one person can use a TCP port (it does listen() and accept()), but
only one person can use a UDP port.  The UDP code for "gw" was designed to
work with Netrek, so it may not make sense in other contexts...  Also, note
that "tcp 4000" and "udp 4000" exist in different namespaces, and so do not
conflict.

To use a TCP connection, run netrek as follows:

    netrek -h charon -p 2593

This would attempt to connect to a gw process running on "charon" on port 2593,
which would then connect to bezier.berkeley.edu on port 2592.

The UDP connection is more complicated; both the client and .gwrc must know
about the same set of three ports.  The first two are on the gw machine, the
third is on the client.  Note that you do NOT specify the server machine on
the UDP line.  The recommended course of action is to choose ports based on
the UID of the person playing, and set up the client and .gwrc to have one
set per player.  Including a command-line or menu option is also recommended.

(attempting to use an in-use set of UDP ports will get you an "address already
in use" message when the second client tries to use the same client-port.  The
Netrek client can handle this w/o problems.  Thus it's impossible for two
different people to use the same gw UDP ports unless the .gwrc contains
duplicate definitions.)

Note that it is impossible to run an unmodified blessed binary through a
gateway machine, because one of the mixins is the internet address of the
server.  In this case, the client thinks that the server is the gw host,
while the actualy server has other ideas.  The solution is to tell the
client what the REAL server's IP address is, but that requires a modified
client and a copy of the "official" reserved.c.  I can provide a hacked
netrek/main.c (which will allow you to say "netrek -H bezier" and do all the
hard work for you), but I will not distribute copies of reserved.c.


COMPILING, INSTALLATION, AND SECURITY NOTES:

To install this program you need to configure the list of hosts which you
are willing to accept TCP connections from (all of which should be within
your organization), the organization's general domain name (this is used to
generate warnings if a TCP connection passing data back into the organization
is used), and the location of the log file (which you should chmod 722,
preferrably append-only).  The first two are in gateway.c, the last is in
gw.h.  It works just fine on a Sun 4, and ought to work on most BSD systems.

The logging stuff should work reasonably well with more than one gw process
running simultaneously.  It does an fseek() to EOF followed by an (unbuffered)
fprintf(), so there won't be a problem unless two processes try to write at
almost exactly the same instant.

There is an option called "fascist mode", which you can get by #define-ing
FASCIST in gw.h.  Instead of generating warnings for aberrant behavior, it
prints an error message and terminates.

Aberrant behavior is currently defined as: selecting a machine on the
"allowed" list as a destination, selecting a machine in the local domain
(hard-coded into gateway.c) as a destination, selecting a privileged port
(port# < 1024) as a destination address, and selecting a UDP client port
number < 1024.  Basically, anything which would allow an outsider to send
unsolicited data into your side of the firewall is frowned upon.

In addition, gw will not start up in fascist mode if the log file can't be
opened for writing.

To keep people from tying up ports indefinitely, and to prevent people from
worrying about who's going to kill a shared copy (killing gw kills all of
the connections, ghostbusting any Netrek players), the program times out
after an hour of inactivity.  Note that gw is kill-resistant when in use;
if there are active connections, SIGHUP and SIGTERM will be caught and
munched.  SIGINT will cause the program to print a warning message the first
time, and then exit the second (like sending a mail message).  The signals will
revert to their initial states when there aren't any active connections.


OTHER NOTES:

The lineage of this program is (more or less):
    kpsmith@sgi.com		- original TCP version + first attempt at UDP
    fadden@uts.amdahl.com	- rewrote UDP stuff, added some security
				  features, bug fixes, logging, etc, etc.

It's generally wise to get permission from your site administrator BEFORE
installing this.  They'll find out about it eventually (hi perry!)

If you leave this running in the background after you log off, be sure you've
got the output redirected to a file or /dev/null.  Otherwise, the output can
start appearing on other people's terminals (this behavior was noted on a
Sun 4; it happens because you've released the tty or pty for others to use,
but gw still thinks it's got a controlling terminal).  At any rate, the
one-hour timeout should be left in.

It should now work under Amdahl UTS2.1 (SVR3 with some BSD libraries).

