                          [{( Project ReD )}]
                          [{(  Ver 0.6.5  )}]
                          [{( by FJ Pizlo )}]

** License **

Project ReD is Copyright (C) 1997 Filip Pizlo

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

Contact info is below.

** Intro **

Project ReD is a coding job I started a while ago, and it has grown quite a
bit from a simple HTTPD.  It is coded in Java, and takes advantage of all of
Java's cool features, such as: multithreading, memory sharing, dynamics,
security, and extendability.  It is still in the beta stages, but it has
already passed many tests, which show that Red can already be used as a
personal WWW server.

** Setup **

A quick note before beginning: DO NOT UNZIP redstart.zip!!!!

This Beta release runs best on Windows 95 or UNIX with JDK 1.1 and JSDK 1.0.
The minimum requirements are JRE 1.1.  Pre-1.1 versions of Java will not
work!

Project ReD is quite complicated to start up manually, so I made a proggie
that makes startup scripts for you.  This is the vissetup.class Java program.
Run it (probably by doing "java vissetup"), and it will quickly make the
scripts.  In UNIX, it will make a simple shell script, and in Windows it
will code up a batch file.  Nice, eh?

Then just type "red" (./red in UNIX) and Project ReD will start running.
This should be very easy.  If you wish to configure Red, type "config", or
"./redconfig" in UNIX.

To run it on systems not supported in vissetup.class, do:
   $ java -classpath redstart.zip:<normal classpath> start
In this case the <normal classpath> should be replaced with whatever the
classpath usually is.  This is normally c:\java\lib\classes.zip in Windows
95 systems (if you have a version later the JDK 1.0.2, it might be
c:\jdk1.1.4\lib\classes.zip, depending on your JDK version; you should know
this classpath anyways, it is kinda necessary), and in UNIX systems should
be /usr/local/java/lib/classes.zip.  Also note, though that on Windows
systems the ':' should be a ';'

Both methods will run Project ReD, first checking for upgrades.  As a note,
redstart.zip has the basic startup code, and project.red has the bulk of the
classes.  If project.red is deleted, Red will not run.  It won't run,
either, if you do not have redstart.zip.  If you lose any vital files, but
you still have setup.class and vissetup.class, you can just run vissetup and
you will have the option of downloading everything again.

The default settings are:

Listen port	-- 80 (all conventional WWW servers run on 80)
WWW directory	-- directory from which you ran "red"
Server name	-- your machine's IP address, or localhost
Index files	-- searched in this order: index.html, index.cgi, index.txt

If you wish to change these settings, run the configuration utility
(explained above).  This will give you the ability to change just about
everything.

** Commandline Options **

Project ReD accepts several commandline options/parameters.  Here they are:
-nocheck	do not check for upgrades (speedier startup)
-checkonly	check for upgrades and notify user, but don't download
-norun		check and download upgrades but don't run Red
-help		display the help message

There also are many options that the JDK VM accepts, and some valuable
features that can be used in certain OSs.  Read on to find out about those.

In the case of UNIX, you might want to run it as nice and put it in the
background using '&'.

In windows, I recommend you open an MS DOS prompt dedicated to Red, and
minimize it once it is up and running.

Everything is logged to main.log.  But, all errors are sent to standard
error, so in Windows you will be able to see these in the MS DOS prompt.

It is also recommended that you change the memory usage parameters on JDK. 
Here are parameters that worked perfectly fine during my testing:
   -ss32768 -oss65536 -ms131072  -mx1572864

So, in UNIX it is best to run Red like so:
   $ nice java -ss32768 -oss65536 -ms131072 -mx1572864 -classpath <classpath> start &
   Red/x.y.z -- Yo!

In Windows here is whats best:
   C:\RED>java -ss32768 -oss65536 -ms131072 -mx1572864 -classpath <classpath> start
   Red/x.y.z -- Yo!

Note, that this requires that you either create your own "red" script, or
modify the existing one.  Don't blame me if something gets screwed up!

In case you are wondering, these special parameters limit how much RAM Java
will allocate ahead of time, and how much RAM Java will ever use.  Under
these parameters, Java will use up at most about 2MB of RAM.  Normally it
might conveniently expand its self to 5MB right on startup.  Since Red is a
personal WWW server, we do not want it to be a memory hog.

** Pipeline **

This latest version of Red has a very well optimized pipeline architecture. 
I recently used my proggie called beatdown.C, which, as the name implies,
beats the daemon down.  The latest non-pipeline version got a score of 5.69
(request handled per second on loopback).  This current pipeline version got
8.375.  This means that the pipeline architecture speeds us up approximetly
50%.  Nice, eh?

The most effective way to optimize Red is to edit the "pipeline" entry in
the config file.  Project ReD uses a pipelined architecture to improve
speed, and the "pipeline" entry lets you determine how many threads will be
used for each node.  For those who don't know the terminology, a pipeline is
like a production line.  Each station on the production line is called a node.
When a request is recieved, it starts at the first node (connecth) and as
Red processes the request, it makes its way down the pipeline, node after
node.  Here is a tree of all the nodes, and which one has the ability of
relay to which:

connecth -> request
request -> header, chreq, preprox
header -> error, document, cgi, servlet
chreq -> precgi, predoc, header, presrv
preprox -> proxy
precgi -> header
predoc -> header
presrv -> header
cgi -> postproc
proxy -> postproc
error -> <none>
postproc -> <none>
document -> <none>
servlet -> <none>

All of these nodes are accually multiple threads that handle multiple
requests at once.  Red can function well with only 1 thread in each node. 
It is recommended, though, that there is a different number of threads in
each node, and that there are at least 3 request threads (all other nodes
should have an amount of threads relative to the request node).  It is
REQUIRED that each node has at least 1 thread.  Here is
some important data:

                                # of threads relative
node name	abbreviation	to request	function
error		er		3/2		send error messages
document	dc		2/3		send the contents of the
						file
postproc	pp		1/6		send the data from the
						client to the CGI or relay
						connection
cgi		cg		1/3		send the output of the CGI
servlet		sr		1/3		send the output of the
						servlet
header		hd		1		send a header and decide if
						an error should be sent
precgi		pc		1/3		run the CGI
predoc		pd		2/3		open the document
presrv		ps		1/3		run the servlet
request		rq		1		get request data from client
chreq		cr		1		purify the request data
						(change path data)
preprox		px		1/3		open a proxy relay
						connection
proxy		rx		1/3		send data from relay
						connection to client
connecth	cn		2/3		recieve connections

NOTE: The connecth thread can do fine with only two threads in just about any
	situation.

Remeber that this requires editing the config file.  The configuration
utility will always give a fairly generic pipeline command (it will dissable
nodes that aren't going to be used, such as if you disable CGI), but other
than that, it will not allow any customization.  I might add an "advanced
edit" feature for the pipeline at some point, but not now...

** CGI **

Project ReD supports CGI through GET, HEAD, and POST requests.  Red
identifies CGIs by their extension or by the directory they are in.  I have
tested it on many CGI/1.1 scripts.

The only problem with Red's CGI support is that it will not change the
working directory to the one that the script is in.  Many CGIs will assume
that they are in their own directory, so this may be a problem.  All I can
say is: use Servlets!!!

Other than that minor problem, Red does a wonderful job of supplying an
extended URL as both the parameter and QUERY_STRING, properly handling the
output in GET, HEAD, and POST situations, and cutting off input in cases of
POST.  I trust the CGI part of Red quite a bit!

** Servlet **

Project ReD is now compliant with the Javasoft Servlet API.  Check out
README.servlets for info about Red's implementation of Servlets.

** Proxy **

A proxy is a relay server.  As of version 0.4.0, Red is capable of acting as
an HTTP proxy.  If you want to enable Red's proxy support, edit the config
file and add or uncomment the line "proxy true".  You can also enable it
using the configuration utility.

Red's proxy support has been tested quite a bit now, and it seems to work. 
I trust that it should not cause problems.  I am yet to optimize it, though,
so don't expect the proxy support to be super phast.

As of version 0.4.1, Red has a simple piece of security code in its proxy
threads.  You must edit the contents of the "proxy" file; in it you must add
the IP addresses of the hosts that can use the proxy.  The easiest way of
doing this is to run the configuration utility.  I hope to implement
wildcards sometime soon.  Right now I'm focusing on optimizations.

** Summary of features **

HTTP/1.0 support for GET, HEAD, and POST requests
Partial HTTP/1.1 compliance
MIME support
multiuser support
HTTP/1.1 virtual hosting (through the Host header)
safe exception handling (everything reported)
logging of every action in main.log
logging of all requests in request.log
stability
auto-upgrading
CGI/1.1 support with GET, HEAD, and POST
pipeline architecture
proxy support
Javasoft Servlet API, version 1.0 support with GET, HEAD, and POST
filter support
basic alias support

** Release notes **

I started working on Red in August '97, but I did not get serious until
October.  This version is a fully-functional WWW server, although it is
still Beta.  I keep it classified as Beta because it has not been tested
extensively enough, and it doesn't have all of the features that I
originally promised.

What to expect in the future:
embedded servlets
complete shtml filter

Bugs/Problems/Bottlenecks:
Won't set PWD properly when loading CGIs (see the CGI section for more info)
Can still be crashed by third parties, but preventable by setting timeout
rq (request) node still possibly too large

Fixes/improvements since last major release:
servlet/cgi security added
ping hack added
dyndns client added

** Files **

In order to use Project ReD, you must have all of the following files:
README
README.servlets
LICENSE
vernum
source.zip
project.red
redstart.zip
vissetup.class

If you do not have all of these files, get them.  Their absence is against
the rules of the license, since GPL/2.0 says that you must have all of the
source code, and the license its self must be there.  To get these files,
simply go to http://kaczor.psych.purdue.edu:10000/red/updates/

** About me **

I am 17, a Polak, and I live in Indianapolis IN.  I attend Brebeuf Prep
School.  Here is how you can reach me:

irc: thE_SLaV on UnderNET, Vnode on EFnet
email: pizlo@iquest.net
www: http://kaczor.psych.purdue.edu:10000/
     http://sphinx.psych.purdue.edu:10000/

** The End **
