

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

		RTSP Proxy Reference Implementation
		Version 1.0.0.0a

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -



OVERVIEW
========

This package contains source code for a reference implmentation of the
application-level RTSP proxy for Unix.  This package is meant to serve
as a reference implementation for those writing firewall software.
The following unicast data transports are supported:

	 *  X-REAL-RDT/UDP  (aka X-PN-TNG/UDP)
	 *  X-REAL-RDT/TCP  (aka X-PN-TNG/TCP)
	 *  RTP/AVP/UDP
	 *  RTP/AVP/TCP 


FILES
=====

The proxy kit contains the following files:

README             Text file that contains instructions on how to build and
                   install the rtspd proxy.
Makefile           The proxy makefile.
main.c             rtspd main function.  The following three C source files
                   comprise the application-level proxy.
rtsp.c             The RTSP state engine. Parses RTSP messages and remaps ports.
rtsp.h             Header file for rtsp.c.
child-main.c       Networking for each client session.
child-main.h       Header file for rtsp.c.
daemon.c           Enables the proxy to run as a daemon.
daemon.h           Header file for daemon.c.
license.txt        License text.
rtspd.8            rstpd man page.
rtspd.8.txt        Text version of the rtspd man page.
rtspv2r2.pdf       RTSP Proxy White Paper.
setup.h            Constants.
simplib.c          Set of functions for hashes, doubly linked-lists, 
                   and memory malloc'ing.
simplib.h          Header file for simplib.c.
util.c             Exiting, logging and signal-handling functions.
util.h             Header file for util.c.


BUILDING THE PROXY
==================

The supplied Makefile has been used to build the proxy on Linux,
FreeBSD and Solaris, and other platforms.  Inspect this file
and adjust as necessary.  

A debug build of the proxy will be created by default, which, along
with providing additional information about the operation of the proxy,
will also log all RTSP traffic between the client and server, which
can be very useful.

If you've previously compiled all or part of the proxy, start with:

	$ make clean

Build the proxy:

	$ make

The binary will be called 'rtspd'.



INSTALLING THE PROXY
====================

For testing and development purposes, installation is quite simple.
Just copy the 'rtspd' binary wherever you want.  It uses no external
configuration files, accepting all configuration via the command-line,
and it performs logging via syslog.

You are encouraged to set permissions and ownership of this command so
that only a specific user can run it, and/or so that it always runs as
a non-privileged user.  For example, you might do the following as the
'root' user:

	# cp rtspd /usr/local/sbin/rtspd
	# cd /usr/local/sbin
	# chown nobody.wheel rtspd
	# chmod 4550 rtspd

Now, any user in the special "wheel" group may start the proxy, and it
will run as the non-privileged user "nobody".  The specific user and
group to choose will depend on which Unix is being used, and on your
site-specific configuration.


USING THE PROXY
===============

To start the proxy listening to the default port, simply run the rtspd
command.  To listen to a different port, -p {port} may be used on the
command-line.

If there is a need to chain multiple proxies together, perhaps to make
it through several levels of firewalls, the "-f {host}:{port}" switch
will forward traffic to another proxy at the specified hostname and port.
"rtspd -f foobar.real.com:7321" would forward network traffic to another
rtsp proxy listening on port 7321 on foobar.real.com.

There is a manpage which further explains how the proxy may be used.


ADDITIONAL NOTES
================

By default, the proxy listens to port 554 for RTSP Control connections.
A different default port may be chosen at compile-time by editing the
Makefile and passing "-DSERV_TCP_PORT=nnnn" on the compiler command-line,
or by changing the value of SERV_TCP_PORT in setup.h.

If the proxy is started by the "root" user it will automatically
setuid to the user "nobody" for safety.

A debug build will currently print the entire contents of RTSP packets,
including any binary data that may be encoded within.  If the client is
using TCP to transfer data rather than UDP, you will likely see garbage
characters being logged to the screen, and it is possible your terminal
will lock.  When running a debug build where TCP may be used for data
transfer, it is recommend that the proxy be started with "nohup rtspd &".
The debug output will then go to the file nohup.out, which vi or emacs
should be able to display, even with the binary data.  Since it is
logging all the data, in TCP mode the nohup.out file can grow quite
large and may need to be truncated periodically.  Alternatively,
one could use "rtspd 2>&1 | cat -v".


BUGS FIXED
==========
This version 1.0.0.0a fixes a bug where the proxy was dependent on retrieving
an even number port from the OS. The code would attempt this n times and
then give up.

