
Fast Forward - The World's Easiest Proxy Server
================================================

Haven't you always wished there was a proxy server that made you feel good
inside?  So that you'd know you were doing the absolute best thing possible
for your network traffic?  So that you could sit back and rest assured that
all those little packets got where they were supposed to be going?  I'll bet
you can almost see them waving at you and saying "Thanks!" as they whiz by, 
can't you?

Well, I'm pleased to report that Worldvisions Fast Forward fulfills some of
the above criteria -- it's a proxy server.  More than that, though, it makes
it *easy*.  At Worldvisions, one of our primary design goals is always to make 
powerful and flexible software that's simple to set up and use.  After all, 
why should using software be hard?  We couldn't think of a reason either.

If you're already excited and want to try it out right away, you can fast
forward through this document (HA HA HA!!  I crack me up!) and read the
section on Compiling and Installing Fast Forward.  If you're curious about
who we are and what we do, please read on.

Fast Forward makes redirecting TCP/IP streams and UDP packets a snap.  All
you need to know is what IP address and what port to listen on, and what
address and what port you want incoming connections to be directed to.  That's
all there is to it.  Sound pretty easy?  We figure it *should* be easy.  
That's mostly what motivates us to do what we do.

It may sound like we're crusaders for the good of the world.  Not true at all;
we simply think that good software shouldn't need to be complicated.  Actually
Fast Forward arose from one of our other projects, the "Worldvisions Weaver".
Three components of the Weaver project are being released for free (under the
LGPL; see below).  The rest of the Weaver will probably be released for free
eventually, but to maintain our competitive edge (and also save our
programmers from looking silly) we're keeping the rest to ourselves for now.
No promises about that.  If you're curious, however, there are pointers to
more information about all our projects at the end of this file.

But even though Weaver isn't free, Fast Forward certainly is, and it always
will be.  So have fun!  It is our hope that all Linux distributions will
eventually integrate this and other free components of Weaver, to help make
Linux (even more of) a killer Internet workstation.

But first there is something we should tell you:

The GNU Library General Public License
======================================

Fast Forward was written by Dave Coombs and Avery Pennarun of Worldvisions
Computer Technology, Inc. and is released to the public under the terms of
GNU's LGPL, or Library General Public License.

This is not quite the same as the General Public License (GPL) that most
Linux software uses.  The LGPL is actually *less* restrictive -- you can use
LGPL software inside your own programs, and you are *not* required to place
your program under the GPL or LGPL.  That means companies or individuals
can, if they want, take all the code in Fast Forward and use it in a product
without giving anyone their own source code.

But there's a catch, of course -- basically, you have to make the source
code to Fast Forward available to users, and if you *change* the Fast Forward
code in any way, you must also release the changes under the terms of the
LGPL.  That means you have to give out the source code to your changes.
That also means that we or anyone can build a product based on the modified
Fast Forward, and although the source code to Fast Forward must be provided,
the rest of the system does not have to be (L)GPL'd.

We think that this is a fair way to share this software, because it
guarantees that everyone can fix bugs and when anyone does, everyone can get
the patch.  But still, people can build small Linux systems based on Fast
Forward (...like our Weaver) without having to give out the source code to
their *entire* main program.

Naturally none of that is legally binding.  The nice people at GNU have
prepared the legalese already and you can find their license verbatim in the
file COPYING.LIB.  Please read it carefully before distributing (or, worse,
nnot distributing) modified copies of Fast Forward, because the rules aren't
quite as simple as I've made them sound.


Compiling and Installing Fast Forward
=====================================

Currently there doesn't exist a pre-compiled Debian or Red Hat package for
Fast Forward, though this will change at some point.  But for now, you're
going to have to compile it for yourself.  This is not too difficult as long
as you have a few things installed on your Linux system:

	- gcc 2.7.2 or higher, with g++ (but you don't necessarily need
		libg++ or libstdc++, as Fast Forward doesn't need them)

	- GNU make; you may need version 3.75 or higher, I'm not sure.

Almost any halfway modern Linux system should have all of these.

Building Fast Forward is a simple matter.  First, check the Makefile to see
if everything looks okay to you.  By default, fastforward will install in
/usr/local/bin.  That's probably right for most systems.

To build and install Fast Forward, then:
	make
	make install

Assuming you don't have any compiler errors (and really, you shouldn't,
right?) you now have an installed Fast Forward system.


Configuring Fast Forward
========================

And now that I've got you convinced that you absolutely, positively *need*
to set up and use Fast Forward for the rest of your life (if you're still 
not convinced, go back and read about the happy packets.  Picture them
smiling with gratitude if it helps), I will tell you the bad news:  
You need to make a configuration file.

Calm down now.  The GOOD news is that it will probably only be a few
lines long, and there's virtually nothing to it.

So, with that in mind, 'su' to root and create the file /etc/fastforward.conf
with your favourite editor.  The easiest way to show the format of the file 
is with an example.  Assuming your computer's name is "fred" and there's
another computer on your local network named "barney", try:
	[Fast Forward]
	fred:4280 = www.worldvisions.ca:80
	0.0.0.0:4223 = barney:23

You can specify any number of entries you like.  Also note that you can use
IP addresses or hostnames interchangeably -- whatever you like.  The first
entry tells Fast Forward to listen on port 4280 on fred, which is your
computer's name.  Incoming connections are redirected to Worldvisions's
web server.

In the second entry, Fast Forward is told to listen on address 0.0.0.0.  This 
means that it should listen on all IP addresses that it's allowed to listen 
on.  If you've got a device on your computer that's correctly set up, Fast 
Forward should accept connections on port 4223, no matter what its IP address
is.

The above is a completely functional configuration file.  Just replace "fred"
with your computer's actual name, and replace "barney" with the name of some
other computer you like.  Then you're ready to try it out.


Testing it for the First Time
=============================

Now that you've compiled and installed Fast Forward, and created a
configuration file, it's time to test it.  To run Fast Forward, type
	fastforward
(surprise!).

Fast Forward will take over your terminal and use it as a place to write
log messages.  At the very beginning, Fast Forward will attempt to read
your configuration file and notify you of any errors.  It will print a 
message for each entry, indicating (hopefully!) that it has set up the 
redirection and that it is listening on the port you specified.

If there are no errors starting Fast Forward, it's time to see if it's
working.  If you created an entry like the second one in the file listed
above, try:
	telnet localhost 4223

You should get "barney"'s telnet port, and be presented with a login prompt.
If so, Fast Forward is doing its job.  For a more rigourous test, point your
web browser at "http://localhost:4280/" and see if you get Worldvisions's web
page.

To exit Fast Forward, just hit Ctrl-C in the terminal it's using.  It will
neatly clean up after itself and go away.


Assuming it Worked...
=====================

If you ran Fast Forward and were able to use its forwarding features
successfully, then you're in business, and you can set up the configuration
file to meet your system's needs.  If you saw any errors in Fast Forward's
output, please let us know -- it could be something weird on your system,
or it could even be a bug in the software.  In either case, we'd be more
than happy to help.

If you want Fast Forward to run in the background, use:
	fastforward >/var/log/fastforward.log 2>&1 &

This will make Fast Forward write its error messages to a log file, rather
than right to your screen.  It will also run in the background, letting you
use that terminal for other things.  To stop it later:
	killall fastforward

If one of your forwarded connections ever says "Too many connections are
open!", it means that you have 20 forwarded connenctions open already.  To
increase the limit, add a line "Maximum Connections = ##" to the configuration
file, where ## is the new limit you want.  20 was an arbitrary number to
prevent things from accidentally spinning out of control.  If you actually
need more than 20, increasing the limit is perfectly okay.


Nah, it Didn't Work After All
=============================

If Fast Forward didn't work, then check its output to see the error messages
it printed.  If you need help deciphering them, feel free to e-mail us.
It could be anything, really, and we'll help you find it.  We want our
software to be useful to you, and if you're having problems, we want to hear
about them.

If you can duplicate the problem, that's great, tell us what you're doing.
Also a copy of the error messages Fast Forward prints would be exceedingly
helpful in trying to track down the problem.  *Please* include this in your
e-mail.  You can easily do this by running:
	fastforward 2>&1 | tee fastforward.out

And e-mail us fastforward.out.


Concluding Notes
================

Plans are forthcoming for turning Fast Forward into a Debian package.  It
would, of course, be nice to see a Red Hat package also.  We don't use Red
Hat here, so we can't do it, but anyone who wants to can go right ahead.  
If you want, we'll put it on our web page along with (eventually) the
Debian package.

This is something of a prerelease of Fast Forward.  We expect it to work in
most situations, but hey, nothing's ever perfect, right?  There may well
be bugs in this thing, so tell us if you find one!  Send us e-mail at:
	fastforward@worldvisions.ca

For information about Worldvisions, Fast Forward, and our other products,
please visit:
	http://www.worldvisions.ca/

Most of all, have fun with it!

And remember:
	Of all the things your mom told you NEVER to touch,
	I bet she never said a thing about Worldvisions software.

