Rulerproxy

***************************************************************
* The latest release of Rulerproxy is always available at:    *
* https://gforge.cs.vu.nl/svn/ruler/src/trunk/rulerproxy/     *
***************************************************************

Contents:
- What is Rulerproxy?
- How to compile it
- How to use it
- Files
- Feedback
- Authors



===================
What is Rulerproxy?
===================
Rulerproxy is an application level TCP proxy meant for transparent
deep inspection and/or rewriting of network traffic.  In contrast to
the approach taken by TCP stream reassemblers, Rulerproxy makes use
of the TCP stack of a regular Unix machine to perform TCP connection
interception.

Rulerproxy was developed as part of the EU FP6 Lobster project.


=================
How to compile it
=================
Since Rulerproxy depends on the ivykis event handling library,
first make sure that ivykis is installed and working.  ivykis is
available from:

	http://sourceforge.net/projects/libivykis

If you intend to make use of the pattern matching functionality
of Rulerproxy, install Ruler as well:

	https://gforge.cs.vu.nl/projects/ruler/

Once you have ivykis (and optionally Ruler) installed, open options.h
in your favorite editor, and enable the desired functionality.  Then
type 'make' to build Rulerproxy.


=============
How to use it
=============
Making Rulerproxy intercept TCP connections involves two steps:
- Setting up the network environment and the host OS on the machine
  that Rulerproxy runs on to send incoming TCP connections to the
  Rulerproxy process.
- Setting up Rulerproxy to forward those incoming connections to
  the intended end host.

These steps will be exemplified with a number of example network
scenarios:

1. "Hidden" backend web server on private IP address space.

				|
			 public	| private
		  address space	| address space
				|
			+---------------+			+----------+
		1.2.3.4	|		| 10.0.0.1     10.0.0.2	| internal |
	----------------+   Rulerproxy  +-----------------------+   web    +
			|		|			|  server  |
			+---------------+			+----------+
				|
				|

	In this setup, point www.example.com to 1.2.3.4, and
	configure Rulerproxy to listen for incoming connections on
	port 80 by setting OPT_LISTEN_PORT in options.h to 80.  To
	have the connections forwarded to the internal web server,
	enable OPT_FWD_HARDCODE, set OPT_FWD_HOST to 10.0.0.2, and
	set OPT_FWD_PORT to 80.

	By default, the internal web server will see 10.0.0.1 as
	the TCP source address of all incoming HTTP connections.
	To enable the web server to see the "true" addresses of
	HTTP clients, enable OPT_SNAT_IPTABLES.  (There are a number
	of restrictions associated with this option -- see options.h
	for details.)

	To scan the data sent from the internet to the internal web
	server (HTTP requests), enable OPT_RULER_MATCH_US.  To scan
	the data sent from the internal web server back to the
	internet (HTTP responses), enable OPT_RULER_MATCH_SU.


=====
Files
=====
00README.txt
	This file.

Makefile
	The main Makefile.

main.c
	The stub .c file containing main() which initialises ivykis,
	instantiates a rulerproxy instance, and calls into the ivykis
	event loop.

options.h
	Repository of compile-time configurable options.

rulerproxy.c
rulerproxy.h
	The core connection interception and forwarding code.

tcp_snat.c
tcp_snat.h
	Helper module which allows using Linux iptables SNAT for
	source address transparency.


========
Feedback
========
Please send feedback on Rulerproxy to the authors.


=======
Authors
=======
Lennert Buytenhek <buytenh@wantstofly.org>