	RCS Ident $Id: README,v 1.7 1999/11/18 18:09:32 root Exp root $

UDP packet relayer -- (c) 1993, Tom Fitzgerald <fitz@wang.com> , 
			(c) 1998, Ted Rule <Ted_Rule@flextech.co.uk>

SUMMARY:

This package consists of 2 components.  udprelay is a daemon process which
runs on a bastion system and forwards UDP packets in and out of a
firewalled network, as directed by a configuration file.  Rsendto.c
provides routines Rsendto and Rrecvfrom, which allow tunnelling through the
bastion to arbitrary outside hosts.  (Rsendto and Rrecvfrom are used like
socks's Rconnect and company, of course).  Rsendto/Rrecvfrom communicate
with udprelay using UDP packets encapsulated in a wrapper that includes the
address of the remote host/port to transfter traffic to.

Un-encapsulated traffic (from programs which were not built with Rsendto)
can be forwarded in and out, but only between specific pairs of inside/
outside systems, with some flexibility added by using distinct local ports
on the bastion host.

INSTALLATION:

The Makefile included in the kit now contains a number of OS specific sections
to try and help modify the compile process for different architectures. In
time, it will be more portable to use a tool such as autoconf to modify these
parameters automatically.

Current Makefile OS specific options allow for:

AIX:		Provided with version 0.2 of code and presumed working.

ODT2.0:		Ditto.

RedHat Linux 4.2:
		This is known to compile and run on kernel 2.0.33,
		gcc version 2.7.2.1

RedHat Linux 5.1:
		This is known to compile and run on kernel 2.0.35,
		gcc version 2.7.2.3
		
RedHat Linux 5.2:
		This is known to compile and run on kernel 2.0.36,
		gcc version 2.7.2.3, glibc 2.0.7.29
		
RedHat Linux 6.0:
		This is known to compile on kernel 2.2.5,
		gcc version egcs-2.91.66, glibc 2.1.1
		
SunOS 5.6 == Solaris 2.6:
		This is known to compile on gcc version 2.8.1, not tested
		as runnable.


Other Makefile options:

CASTSOCK	Used to work round compiler warnings relating to the 
		sockaddr struct type. The OS specific options should cover
		most cases.

USEPOLL		Used to force usage of poll() instead of select(). The original
		version 0.2 code used poll(), but this was not available on
		Linux until glibc and kernel > 2.1.xxx. The code appears to
		function perfectly reasonably using select().

NOBODY		Used to determine the non-root user to switch to after
		interface binding has completed.

DEBUG_VIA_STDOUT
		Used to switch all debug output to stdout. By default the
		compile time options direct ALL debug and error output via
		calls to syslog(), which is easier to use when the process
		is running as a background daemon. It may be desired to use
		this switch whilst debugging new versions of the code...

USE_INET_ADDR	The version 0.2 code used the obsolete inet_addr() call, which
		has been superceded by inet_aton(). Unfortunately, some OS's
		don't yet have inet_aton() - notably Solaris!, so the OS
		specific options should cover this.

USE_FCNTL	If defined via the Makefile, forces the code to issue an
		explicit call to fcntl to make all sockets non-blocking.
		This is the default, but may be experimentally removed
		to debug blocking issues.

USE_IOCTL	The original version 0.2 code used ioctl() instead of fcntl().
		This define may be used to restore the original behaviour.
		If USE_FCNTL is defined, fcntl() is still used in preference.

DFLT_TIMEOUT	Normally set to 3 minutes, this dictates how long each udp
		'instance' will be held open.

DEBUG_TIMEOUT	As above, but used as the default timeout in debug mode.
		This is set to 20 seconds by default, so that the timeouts
		can be more easily tested in debug mode.


To compile the code, just unpack the source and use:

		make

To run the code, use:

	udprelay [ -d <level> ] [ -t <timeout> ] [ -l <facility> ] [ -f <configfile> ]

	where:

	timeout == session close time in secs.
        level == numerical debug verbosity  ( > 1 to log every packet )
        facility == syslog facility indicator ( default LOG_DAEMON )
        d == LOG_DAEMON, 0 == LOG_LOCAL0,
                         1 == LOG_LOCAL1, etc

The process will automatically put itself into background, unlike the previous
version 0.2 of the code. Since this daemon would normally be required to launch
at boot time, a startup script such as /etc/rc.d/init.d/udprelay, (for RedHat),
will generally be required. An example init script for RedHat is included with
the kit.

udprelay should be started at boot time, since it wants to listen on many
ports simultaneously.  It is not inetd-compatible.

If the config file refers to any reserved ports (< 1024), udprelay should
be started as root.  If it is, it will setuid itself to a powerless user-id
specified in the Makefile as soon as it has finished processing the
configuration file.

The configfile (default: /etc/udprelay.conf), ( which may be changed
in udprelay.h if so desired), contains a list of hosts and
ports which packets should be relayed between, and descriptions of
encapsulated ports.

Associations between hosts are described with:

  "relay" host1 remoteport1 localport1 host2 remoteport2 localport2 ["oneway"]

UDP packets from host1:remoteport1 arriving on the local localport1 are to
be forwarded to host2:remoteport2 from local localport2, and vice versa.
If "oneway" is specified, return traffic will NOT be forwarded.

host1 may be wildcarded; *.dom.ain for domain, or * for any host at all.
It may also be an IP address optionally with following ["mask" <addrmask>]
to allow all traffic from that masked IP address.

remoteport1 may be "*" for any remote port. localport2 may be "any",
meaning udprelay can use any available local port.  If host1 and/or
remoteport1 are wildcarded, and localport2 is "any", then udprelay will use
a separate localport2 for each outgoing "session", and will pass
back-traffic that arrives on the appropriate localport2 to the appropriate
host1 (unless oneway is set).  These instances of wildcarded ports are
deleted after 30 minutes with no traffic.

Examples are:

	# Relay traffic back and forth between two NTP servers
	relay clock1.local.domain   ntp ntp clock.outer.domain ntp ntp

	# Send queries from any local ntp query client in the local domain
	# to the ntp server outside, and return responses.
	relay *.local.domain	    ntp ntp clock.outer.domain ntp any

	# Send queries from any outside ntp client to our local ntp server,
	# and return responses.  (This must come after example 2 or example 2
	# will never be utilized).
	relay *			    *   123 clock.local.domain 123 any

	# Forward archie queries from a specific local host to rutgers.
	# Many archie queries can be going on simultaneously from different
	# ports on the local host, using different local ports on the bastion.
	relay host.local.com * 1525 archie.rutgers.edu 1525 any
	relay host.local.com * 191 archie.rutgers.edu 191 any

Encapsulated ports only specify where traffic can come from; each packet
received on an encaps port has a wrapper which specifies where it should be
forwarded to.  They are specified with:

   "encapsulate" hostname localport

Like "relay" lines in the config file, return traffic is passed back (if
the client asks for it) for 30 minutes.  Programs which utilize
encapsulated ports should be built with Rsendto.o.  Clients which want to
take advantage of encapsulated ports will need to be able to get DNS info
from the full Internet, because name-to-address resolution happens on the
client, and only an IP address is passed to udprelay.

Example:

   encapsulate   *.local.domain   1093


NOTES:

Hosts may be specified by name or IP address; host1 fields may be
wildcarded as *.dom.ain or as masked IP addr: "123.45.67.0 mask
255.255.255.0".  1-bits in mask specify bits which must match in sender's
IP address.

Ports may be specified numerically, or as a UDP service listed in
/etc/services.

Multiple "relay" lines may share the same local port.  The destination used
for any packet is the one on the first config line which gives a matching
source host1/remoteport1.  Multiple "encapsulate" lines may also share the
same port; traffic is accepted if any of the (possibly wildcarded) source-
host specifications match the sender.  "relay" lines and "encapsulate"
lines may NOT share the same local port.

No packets will be forwarded from host2 to host1 until at least one has
gone from host1 to host2.  If you want traffic to be initiated from either
side, you'll need 2 "relay" lines.


SPECIFIC INTERFACE BINDING:
It is now possible to dictate the interface to which a given relay or encaps
configuration binds. By including an "interface" line preceding the
corresponding relay" line, one changes the 'current' interface which the
configuration file parsing code applies to any ensuing relay/encaps definitions

If the same port is used by different relay configuration lines, bound to
different interfaces, udprelay will use different "fanouts", and hence different
sockets, for each interface.

Example:

	interface 192.168.14.4
	relay *	    ntp ntp clock.outer.domain ntp any

Will only apply an NTP UDP relay to the 192.168.14.4 interface of this machine.


TIMEOUTS:
The Makefile now has two options for setting the session timeout in seconds
in each of the debug and non-debug modes. A command line override to this
has now been provided. This - in particular - makes it possible to operate
the deamon in debug mode without using the hard coded debug timeout value.


TESTING via DNS:
Since it is generally difficult to find a udp conversant application which
one can use to test the udprelay process, I have found a simple test of the
functionality can be built using DNS. Simply declare a udprelay.conf
configuration on the host, which relays DNS data on port 53 to the local REAL
DNS server - this naturally requires that no real DNS server is running on the
interface one is trying to udprelay via! By invoking dig or nslookup directed
at the udprelay host, and monitoring the syslog files on the syslog server,
one can relatively easily see udprelay in operation.

Even if a DNS server IS running on the udprelay host, bind 8 allows for binding
DNS service to specific interfaces only. Hence by excluding the interface one
binds udprelay to from the list of interfaces which bind itself binds to, one
may even test udprelay on a host running bind. ( It will probably generally be
easiest to use the localhost interface for this purpose, but this is not
essential. )


ACKNOWLEDGEMENTS / THANKS:

Additional functionality -- Joe Angst <morph@slac.com> for clues as to how
to port the poll() code to select().

Augustine Cano <teri@superlink.net> - for testing out many of the patch versions


Ted Rule,
1999
