    ----------------------------------------------------------------------
    WEBRELAY Software -- a multithreaded HTTP relay server
    Copyright (C) 1999 Peter Zhang

    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., 675 Mass Ave, Cambridge, MA 02139, USA.

    Please address all correspondence concerning the software to 
    zhangc@ucalgary.ca
    ----------------------------------------------------------------------

This is Version 1.0.5 of the webrelay software. It works on IBM
AIX 4.1, 4.2. Porting to other operating systems has not been done.
If anyone attempts to port the code to other systems, I'd like to know
the results.

You can download the software in the webrelay.tar.gz file from
http://ftp.ucalgary.ca/~zhangc/webrelay.html. Save the file.
Theb uncompress and untar the file:

	# gunzip webrelay.tar.gz
	# tar xvf webrelay.tar

You will find that here is a precompiled executable file
"webrelay_AIX41" for AIX 4.1.5 in the package. Rename it to webrelay. 

	# mv webrelay_AIX41 webrelay

For AIX 4.2 system, you type

	# make

to create an executable file "webrelay" for you. Install the
executable in to /usr/bin/ directory. You need root access 
to do so.

	# cp webrelay /usr/bin/

Make sure the file has the execution permission set.

You need to configure your webrelay server before you run the program.
There is a sample configuration file, dburls.conf, included in the
package. You can edit it to meet your needs. Each record of the
dburls.conf file should be in contained in a single line (i.e., no
line continuation is supported). A record starting with a
leading "#" sign is regarded as a comment. A record consists of four
fields. A sample record in the configuration file looks like

ERL http://erl.lib.ucalgary.ca/cgi-bin/webspirs.cgi 0 #Multiple ERL Databases

where ERL is a DB_KEY which is an abbreviation of the remote URL in
one word. You can come up with your own DB_KEY for any given
webserver. The DB_KEY is followed by a full URL for that remote
webserver. The third field is a number indicating the
mandatory-authentication flag: 0 means false and 1 is true. The last
field starting with a "#" is a description of the remote webserver.

You should create a directory /usr/local/webrelay/ and then copy the
dburls.conf into that directory.

	# mkdir /usr/local/webrelay
	# cp dburls.conf /usr/local/webrelay/

Two log files, log.ar_acclog and log.ar_errlog, are by default created
in the /var/spool/local/log/ directory by the webrelay program. The
former is for access logs and the latter for error logs. Log entries have
similar format to what a normal webserver would have. 

The program is listening on port number 32888 by default. The default
authentication method would be the "custom" authentication. To
overwrite some of the defaults, one can specify parameters from the
command line.
 
If you type the webrelay command with a '-?' or '-h' option, you get a
usage displayed as:

	# /usr/bin/webrelay -?
	Usage: webrelay [-a [basic | custom]] [-d port] [-d debug_level] 
	[-r server_root] [-l server_log] [-u server_user] [-g server_group] 
	[-i session_idletime] [-s session_length] [-?] [-h]

The '-a' option allows you to select either a basic or custom
authentication method, but the latter (a default) is preferred. The
'-p' option allows you to run the program on a port number other than
the default port of 32888. Normally the program runs as a daemon so
the default debug level is zero, meaning not in the debug mode.
The '-d' option is for setting up a debug level when you run it
from the command line (not as a daemon). Choosing higher a debug level
will log more messages. With '-i' ('-s') you specify a session idle
time (length), i.e., after the session idle time (session length), the
session is going to be purged. The default values are: The session
length is 900 seconds (15 minutes), and the session idle time is 900
seconds (5 minutes). The '-r' option specifies a directory (always
with a trailing slash) where the executable file is located other than
in the default /usr/bin/ directory. The '-l' option specifies a
directory for the two log files other than the default
/var/spool/local/log/. 

To run the webrelay, you must be a root user and simply type

	# /usr/bin/webrelay

It will run as a daemon with all the defaults. You can put a line
inside your system /etc/rc.tcpip file such as:

	# Start webrelay
	/usr/bin/webrelay

This way, if your machine is rebooted, the webrelay will be brought up
authomatically at the start up time.

If your webrelay does not come up properly, you should look into
log.ar_errlog file to see if there is any error in
your configuration file, dburls.conf.

In order for the webrelay to receive requests from your users, you
have to "advertise" it to the user through a web page of your
library. This web page is served as a gateway for your users to access
the electronic material of your library. In that library gateway you
implement a page that introduce the DB_KEYs configured in the
dburls.conf file as a "virtual" directory on your host where the
webrelay is running. E.g., for the ERL entry in the dburls.conf file,
you must have a hyperlink in the HTML page:

<a href="webrelay.host.univ.edu:32888/DB=ERL/">ERL databases</a>

where webrelay.host.univ.edu is the hostname on which your webrelay
programming is running and 32888 is the default port number.
You always start the virtual directory with the string "DB="
followed by the DB_KEY defined in the dburls.conf file. What happens
is that a user comes to your library gateway homepage, and clicks on
the hyperlink above. The request is directed to the webrelay, and
the webrelay will relay requests and responses between the client
and the remote webserver. For details on how the webrelay works,
please refer to the article of "A Multithreaded HTTP Relay Server" by
Peter Zhang in Dr. Dobb's Journal.

Feel free to report any problems, bugs, suggestions and comments to
zhangc@ucalgary.ca

