rev1.03b,02-07-97
PlanetWide HTTP/1.0 Web Server for OS/2
Third Planet Software Creations
RR#5 Belwood, Ontario, CANADA, N0B 1J0





COPYRIGHT/LEGAL:

This software is provided on an "as-is" basis. We offer no warranty on this software whatsoever, and you use it at your own risk.

The files contained in this package may not be modified or reverse-engineered or decompiled in any form for any reason. Problems with the executable or documentation should be brought to the attention of Third Planet Software Creations for correction.

You are free to use the "freeware" version of this software indefinitely. If you find that this software is suitable for your application, please contact us and let us know.

PlanetWide Web Server for OS/2 (c) copyright 1996,1997 Third Planet Software Creations.

{Top}

OVERVIEW:

PlanetWide is a multithreaded 32-bit OS/2 web server. It is meant to serve high volumes of data efficiently. It is not meant to be pretty. We assume that you're using a web server to provide nice displays to others, not yourself. It does, however, report lots of important information to you, the Webmaster. It has no graphical user interface, only a functional one. And it doesn't chew up memory like it's going out of style.

Since this is only a beta, it doesn't support every feature of some web servers, but it does support the important ones.

{Top}

FEATURES IN THIS RELEASE:

If you have features you'd like to see, let us know. If we think it's a suitable idea, we'll do it.

{Top}

SYSTEM REQUIREMENTS:

{Top}

UPGRADING PREVIOUS INSTALLATION TO A NEW VERSION:

If you already have a version of PlanetWide installed and running, then you only need to follow three basic steps.
  1. Unzip the PlanetWide ZIP archive into a temporary directory.

  2. Copy WEBSERV.EXE into the directory of your previous installation.

  3. Run WEBSERV.EXE from the command line, or double-click our fabulous icon. You are back in business.

  4. Edit your PlanetWide ICON preferences to reflect the new version of the software.


{Top}

NEW INSTALLATION PROCEDURE:

  1. Create a directory called WEBSERV (or anything you like)

  2. CD to that directory and unzip PWWS103B.ZIP

  3. Unzipping will produce 17 files:

  4. Run MAKEICON.CMD to put our beautiful icon on your desktop.(modesty!)

  5. Edit WEBSERV.CNF to suit your installation - it's very simple. If you're unsure of what values to use, see below.

  6. Place your INDEX.HTM, INDEX.HTML, DEFAULT.HTM, or DEFAULT.HTML in the same directory you installed to. Don't be alarmed about having your config files in the same directory as your main page, that's what EXCLUDE.CNF is for.

  7. If you have some files in your WEBSERV subdirectory structure which you do not want to be sent, place the names of these files in the file EXCLUDE.CNF, one file per line. Use forward slashes only in your filenames.

    eg: users/bob/bobspage.html big_ones.htm etc..

  8. Run WEBSERV.EXE from the command line, or double-click our fabulous icon.

{Top}

SPECIFYING THE PORT#:

WEBSERV.EXE is able to be started on any IP PORT#. The default is PORT:80 if no port parameter has been specified.

(eg: to start the server on PORT:8888)

[OS/2 Session]

x:\webserv\WEBSERV 8888

[WPS Icon]

Path and File name: webserv.exe

Parameters: 8888

Working Directory: x:\webserv

Note: Multiple web servers can co-exist with each session serving a different port.

{Top}

CONFIGURING THE SERVER (WEBSERV.CNF):

Here's the typical contents of the WEBSERV.CNF file:



SERVERNAME - The IP address of your machine (eg:10.10.10.10) or the domain name associated with your server (eg: www.myserver.ca).

KILLSTRING - This is the string which you can use to kill your server from a remote location. You should change this string to avoid others shutting down your server. If you never want to be able to shut down your server remotely, change this string to something like:

"kfjhglqi3976t4uc#$Tgf8g7345uvdf".


To shut down PlanetWide from your browser, simply enter the URL like this:

http://www.myserver.ca/SHUT_DOWN_NOW


MAXCONN - Depending on your available bandwidth, the power of your machine, the volume of traffic to your server, etc. you may wish to limit the number of connections to PlanteWide. By specifying a value of 40 here you make it so that anyone trying to connect to the server will have to wait if there are already 40 outstanding requests.

BLOCKSIZE - This is the maximum packet size for the server. If this number is high, you will be able to service less connections, but the ones that you are servicing will receive more data at a time. If this number is low, you will be able to service moreconnections, but the efficiency will be a bit lower due to packet header overhead, etc. The default blocksize is 600 bytes. We recommend leaving it there unless you feel like experimenting.

Note: This number is only a packet size. Your web pages can be any size you like. Just remember the poor saps with 28.8 modems, like me. ;-)

{Top}

CONFIGURING FILE EXCLUSIONS (EXCLUDE.CNF):

This file is where you list the files that you don't want people to have access to, even if they reference them directly. Such files include server executables, configuration files, security files, and maybe even log files.

The EXCLUDE.CNF file is only read when the server is started, so if you change it, you must restart the server for the changes to take effect. Files are listed one file per line.

The contents of this file are as follows when PlanetWide is unzipped:



A FILTER file in each directory is automatically excluded and can not be downloaded. See FILTERING IP ADDRESSES for more information.

{Top}

PROGRAM DIRECTORIES - (/CGI-BIN):

Once the PlanetWide software has been unpacked and placed into a working directory, you must create a sub-directory called:

\CGI-BIN\

This is where the server will store and reference CGI interface programs.

Note: The CGI interface is available in GET METHOD only at this time. Code to support the POST METHOD is being added to the next version of PlanetWide.

{Top}

THE CONTENT-TYPE FILE (DATATYPE.CNF):

This file contains the file extension of the content type (ie JPG for JPEG files) and the "Content-type" that PlanetWide sends out when it encounters that type. If, for example, a new type of MPEG format is developed, and the files have the extension .MP3, you would add a line to this file like this:

MP3 video mpeg3

Which would cause PlanetWide to output "Content-type: video/mpeg3" when it encounters a .MP3 file.

The current contents of the DATATYPE.CNF file are as follows:

{Top}

FILTERING IP ADDRESSES (FILTER):

Place this file in directories which require security. Each entry in the FILTER file is able to ENABLE or DISABLE individual access to every file in that directory by WORKSTATION or ENTIRE SUBNET.

The following example will deny access to a workstation with the IP address 196.20.10.52:

- 196.20.10.52

^--- Note the "minus sign" for "deny"

Note that subsequent lines may alter the state of any previous line of security. You may enable security for a workstation at the top of this file, and then disable it at the bottom of this file. The last status is assumed to be the requested state.

By using a zero in the address, you can isolate particular subnets. Use a '-' to deny, and a '+' to add access.

For example, the following will only allow access to machines residing on subnet 131.104.0.0.

- 0.0.0.0 + 131.104.0.0

By default, everyone is allowed in to browse your web pages and links. By specifying "-0.0.0.0" you can deny everyone. By adding subsequent lines, you can let individuals or subnets gain access.

The following will only allow access to those on subnet 131.104.0.0, but deny access to 131.104.68.10:

- 0.0.0.0 + 131.104.0.0 - 131.104.68.10

{Top}

ERR404.HTM:

ERR404.HTM is the file which contains the infamous "ERROR 404" message. When a file or document is not found, the appropriate header is sent, and this page is displayed to the web client. You can customize it if you don't like ours, or you can leave it like it is.

If you make a really cool replacement for the ERR404.HTM file, send it to us!

{Top}

PLANET.ICO:

I drew this myself. Like it?



README.ICO:

This was borrowed from my desktop. Like it?

{Top}

IMAGE MAP SUPPORT:

PlanetWide web server has built-in support for handling IMAGE-MAP deployment and is very easy to setup.

IMAGE-MAPS are maintained by the web-page owner in their own user directory. This removes all responsibilities of the WEBMASTER.

There are three steps to creating a working Image Map:

1. Build a *.MAP file containing clickable regions plus the action to associate with each clickable region.

2. Build the ANCHOR BLOCK *.MAP reference file.

3. Associate the image file and add the ISMAP switch to the <IMG> tag.



1a. Build the MAP file:

- Create the mouse coordinate *.MAP file with your favourite IMAP application, or with a text editor.

*IMAGE MAP support for (RECT) rectangular clickable regions only at this time.*


Note: Place this file in the directory containing the source HTML file (eg: X:/webserv/users/bob/ ). Do not place this in the /WEBSERV/CGI-BIN/ directory as the server will not be able to locate it when the Image Map is clicked.



1b. Sample MAP file: PLANETWIDEBETA2.MAP

# the software homepage
rect http://www.pr.uoguelph.ca/cpayne/planet.htm 28,248 324,280
# download beta zip file
rect http://www.pr.uoguelph.ca/cpayne/beta/pw10b.zip 28,308 324,339
#the os/2 life support station
rect http://www.pr.uoguelph.ca/cpayne/index2.htm 28,366 324,400
#email us ....
rect mailto:"cepayne@uoguleph.ca" 28,422 324,459
default http://www.pr.uoguelph.ca/cpayne/planetwidebeta2.htm



1c. MAP entry definitions:

The NCSA format of the file dictates that you may include comments for each entry, preceded by the '#' hash symbol. Comments are ignored by PlanetWide.

Start your definition entry by specifying the METHOD of detection, RECT for rectangle.

Follow up with the COMMAND to be executed as in the Sample MAP File, link a web page address, mailto: function, link filename, etc...

After the command comes the mouse coordinates(x,y x,y) associated with the clickable region of the image.

Note: RECT mouse coordinates are: TOP-LEFT(x,y) then, BOTTOM-RIGHT(x,y) positions on the image.

Save the *.MAP file in the user directory.

{Top}

2a. Include the ANCHOR BLOCK:

The <A HERF="..."> </A> anchor block tag must contain the following pieces of information to create a working Image Map:

SERVER-ADDRESS + /cgi-bin/imagemap/ + /USER-DIRECTORY/ + *.MAP

Server Address: the legal Web or IP address of your server. IMAP Key: /cgi-bin/imagemap/ is included to inform the server software that this tag hosts an image-map routine. This directory is fictional and does not need to be created on the hard disk.

User Directory: the user directory in which the *.MAP file is located must immediately follow the IMAP Key.

eg: If the *.MAP file is located in /users/BOB/, this will be the user directory in the command.

*.MAP: this is the name of the image map file defining the clickable regions for the web clients. The filename can be up to 255 characters in length as supported on the HPFS partition.



2b. Sample:

<A HREF="http://www.pr.uoguelph.ca/cgi-bin/imagemap/cpayne/planetwidebeta2.map">
<IMG SRC="......">
</A>



3a. Associate the image file:

The <IMG> image tag must contain the following pieces of information:

<IMG SRC="SERVER-ADDRESS + /USER-IMAGE-DIRECTORY/ + IMAGE FILENAME" ISMAP>

Server Address: the legal Web or IP address of your server.

User Image Directory: the user directory where the image file is located. Typically, only JPG/JPEG or GIF images are used in Image Map routines due to filesize.

IMAGE Filename: the name of the image to be displayed to the web client.

ISMAP: this parameter informs the web client to track the mouse cursor location. The coordinates are passed to PlanetWide to be decoded using the *.MAP file.



Save your HTM/HTML file to the user directory.

Happy clicking!

{Top}

CONCLUSION(what?? already?):

This is a BETA (no, not the fish).
The documentation assumes that the person administrating the server is familiar with HTML language tags and their use.

If you have ANY installation or administration problems that we can help you with, E-mail us!

Don't be afraid! If you're having trouble, chances are you're not alone.

If you use the PlanetWide server, send us some mail including your URL! We'd love to hear from you and even visit your web site.

Check our web page for updates and helpful hints! Yes, our own server is running PlanetWide!

{Top}


HOW TO CONTACT THIRD PLANET SOFTWARE CREATIONS:

Email us: cepayne@uoguelph.ca

On the Web: http://www.pr.uoguelph.ca/cpayne/planet.htm

POST: Third Planet Software Creations, RR#5 Belwood, Ontario, CANADA, N0B 1J0


© 1996,1997 Third Planet Software Creations.