rev1.10,08-97

                            PlanetWide OS/2 Web Server
                 (c)Copyright 1997 Payne-Mennie Computing Services


   It is assumed that you are the Webmaster administrating the server and
   are already familiar with the HTML language tags and their uses. Also,
   that you understand the operation of the OS/2 Warp environment and can
   perform the described tasks in our documentation.



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 binaries or
documentation should be brought to the attention of Payne-Mennie Computing 
Services for correction.

You are granted use of this "shareware" version of PlanetWide v1.10 OS/2 Web 
Server for a reasonable period of time allowing you to evaluate the suitability
and operation of the software. After the evaluation period you should consider
registering your copy with Payne-Mennie Computing Services. 
(see: how to register)


OVERVIEW:
========

Welcome!
PlanetWide v1.10 is a powerful, multithreaded, 32-bit OS/2 HTTP Web Server.
It was developed to serve high volumes of data from the OS/2 Warp platform,
and do it efficiently!

As the webmaster, you require an HTTP server that is lean on the system 
resources, and still performs.  PlanetWide was written with a text-based 
interface, preserving precious memory and virtual swap space. 

There is also a lot of important information available to you in the log file,
and in the text window. Further explanation is available; (see: log file ).

The server configuration is very simple, and you should be up and running in
just a few minutes. Enjoy.



FEATURES IN THIS RELEASE:
========================

       Configurable maximum number of connections

       Configurable maximum packet size (BLOCKSIZE).

       Support for a large number of simultaneous connections.

       Full reverse DNS lookup per connection.

       Complete logging of all incoming connections including

       Number of threads in use at the time.
           - Peak threads.
           - Client IP address or domain name (DNS lookup).
           - File delivered.
           - File requested even if file is nonexistent or the
             user does not have permission to receive it.

       Built-in NCSA imagemap support (RECT, CIRCLE, POLY, and DEFAULT).

       CGI interfrace for running external EXE and CMD files (GET and POST).

       Allow/disallow any IP number, range, or subnet on a per directory basis.

       Directory and file security on a per directory basis.

       Configurable remote server kill from your web browser.


  Do you know of a feature that should be included in PlanetWide? Contact us 
  and let us know. If we think it's a suitable idea, we'll include it in a 
  future release.


SYSTEM REQUIREMENTS:
===================

    - OS/2 Warp Connect, or Warp v4.0.
    - HPFS formatted partition.
    - TCPIP v2.0 (or IAK).
    - Recommend 12MB of RAM if your machine is more than just a web server.
    - Internet service with a static IP address.



UPGRADING FROM A PREVIOUS VERSION:
=================================

If you have a previous version of PlanetWide installed and running, then you
only need to follow five(5) simple steps.


  1. Unzip the PlanetWide ZIP archive into a temporary directory.


  2. Copy the new WEBSERV.EXE into your existing server directory.


  3. Edit your WEBSERV.CNF and add the following line:
     (configure the reverse DNS lookup support: Enable=YES Disable=NO)

     LOOKUP YES


  4. Edit the PlanetWide WPS ICON preferences to reflect the new version number
     of the software (v1.10).

 
  5. Run WEBSERV.EXE from the command line, or use the PlanetWide WPS icon.


 ONLINE DOCUMENTATION: OPTIONAL
 ====================
  You may include online documentation to your web server by following this
  simple procedure:

  Create a subdirectory of your c:\webserv\ called x:\webserv\doc\ and 
  unzip PWDOCS.ZIP into it. These online documents and tutorials are 
  available to you through your web client such as Netscape Navigator(tm)
  for OS/2. 

  Included: Frames/HTML
            Standard/HTML
            ASCII TEXT

                                                        

 CGI-BIN: OPTIONAL
 =======
  You may add CGI support to your web server by following this simple 
  procedure:

  Create a subdirectory of your x:\webserv\  called x:\webserv\cgi-bin\ 
  and unzip the CGI-BIN.ZIP into it. The files contained within the zip 
  archive are POST and GET Method CGI's and their sources which will add 
  functionality to your web server software. 

  Included: Guestbook (POST METHOD)
            Guestbook (GET METHOD)

  See the online documentation for more information and easy tutorials.


  * You are back in business *



NEW INSTALLATION PROCEDURE:
==========================

If this is your first time installing PlanetWide OS/2 Web Server, carefully
follow these steps. In a few minutes you will have a fully functional server.


 - Create a new directory to contain your web server files. (eg: x:\WEBSERV ).

   (Place your web pages in subdirectories of the newly created x:\WEBSERV).


 - Unzip PWWS110.zip into your new directory.

   (Unzipping will produce many files, including:)
   
       - WEBSERV.EXE - server executible.
       - WEBSERV.CNF - server configuration file(ascii text).
       - WEBSERV.DOC - server documentation file(ascii text).
       - EXCLUDE.CNF - file-exclusions data file(ascii text).
       - DATATYPE.CNF - file-type configuration file(ascii text).
       - ERR404.HTM - default ERROR 404 html page.
       - FILTER - server security filter file(ascii text).
       - MAKEICON.CMD - WPS installation command file.
       - PW.ICO - server WPS Icon.
       - PWDOCS.ZIP - Online documentation and many tutorials.      
       - CGI-BIN.ZIP - POST/GET CGI's and their sources.
       - REGISTER.EXE - BMT MICRO REGISTRATION APPLICATION.

 - Run MAKEICON.CMD to create the WorkPlace Shell folder and Icons on your 
   desktop.


 - Edit WEBSERV.CNF to suit your installation - If you are unsure of what 
   values to use, (see: configuring the server).


 - 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
   configuration files in the server default directory, the EXCLUDE.CNF 
   can be configured to refuse transmission of these files.
   (see: exclude.cnf file).
  
 
 ONLINE DOCUMENTATION: OPTIONAL
 ====================
  You may include online documentation to your web server by following this
  simple procedure:

  Create a subdirectory of your c:\webserv\ called x:\webserv\doc\ and 
  unzip PWDOCS.ZIP into it. These online documents and tutorials are 
  available to you through your web client such as Netscape Navigator(tm)
  for OS/2. 

  Included: Frames/HTML
            Standard/HTML
            ASCII TEXT

                                                        

 CGI-BIN: OPTIONAL
 =======
  You may add CGI support to your web server by following this simple 
  procedure:

  Create a subdirectory of your x:\webserv\  called x:\webserv\cgi-bin\ 
  and unzip the CGI-BIN.ZIP into it. The files contained within the zip 
  archive are POST and GET Method CGI's and their sources which will add 
  functionality to your web server software. 

  Included: Guestbook (POST METHOD)
            Guestbook (GET METHOD)

  See the online documentation for more information and easy tutorials.



 - Run WEBSERV.EXE from the command line, or use the WPS Icon on your desktop.

   * Your server is now up and running! *



SPECIFYING THE PORT#:
====================

WEBSERV.EXE can be configured to start on any tcp/ip port number. If no port 
has been specified, the server defaults to PORT:80.


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

  - from the OS/2 command line:

     x:\webserv\WEBSERV 8888


OR
==

  - from the WPS Icon: (edit the WPS Icon properties)

        Path and File name: webserv.exe

                Parameters: 8888

         Working Directory: x:\webserv



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



RUNNING PLANETWIDE LOCALLY:
==========================

PlanetWide may function as a fully operational web server on a local machine 
without an ISP connection. Running locally is a great way to build your web 
pages.


Follow the instructions below to create your local web server:


 - Initiate the installation of MPTS networking support from your OS/2 Warp CDROM.
 - Choose to configure your MPTS LAN Adapter.
 - Select the IBM NULL MAC DRIVER as your lan adapter.
 - Add the TCP/IP protocol.
 - Exit and SAVE the new configuration.
 - Shutdown and restart your system.


 - Enter the TCP/IP Configuration utility.
 - Select the Loopback Interface from the interface list.
 - Enable the interface.
 - Enable MANUALLY SELECT IP ADDRESS.
 - The interface defaults to 127.0.0.1 (you may alter this address)
 - Exit and Save your configuration.
 - Shutdown and restart your system.

 
 - Edit the WEBSERV.CNF to reflect your manually configured IP address.

 - Start PlanetWide from command line, or from the WPS Icon.

 - Access your web server by entering the IP address on the URL line of
   your web browser.  ( eg: http://127.0.0.1/mypage/index.htm )

   Congratulations, you are now a one system Internet! Enjoy PlanetWide!



CONFIGURING THE SERVER (WEBSERV.CNF):
====================================

Here is an example of a typical WEBSERV.CNF file:


 SERVERNAME www.myserver.ca
 KILLSTRING SHUT_DOWN_NOW
 MAXCONN 200
 BLOCKSIZE 600



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:


             "<B>kfjhglqi3976t4uc#$Tgf8g7345uvdf</B>"  



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.

             PlanetWide is capable of handling as many connections as there is 
             available system resources.  Busy sites built on large Pentium(tm)
             computers with a lot of memory may service thousands of simul-
             taneous connections.


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 more connections,
             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 wish to experiment with 
             your particular configuration.

             Note: This number is only a packet size.  Your web pages are 
                   NOT limited in size and can be any size you like.  



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: the server
executable, 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.



For each file you wish to exclude, place the /path/filename into your 
EXCLUDE.CNF file:

 - One file entry per line.
 - Use forward slashes only in your filename entries.
 - PlanetWide assumes the root directory to be where webserv.exe is located.



The contents of a new EXCLUDE.CNF is as follows:

 webserv.exe
 exclude.cnf
 webserv.cnf
 datatype.cnf
 webserv.log
 


A sample entry into the EXCLUDE.CNF file:


eg:

   /users/bob/bobspage.html


Note: Filter files in any directory are automatically excluded and do not 
      require an entry in the exclude.cnf. (see: filtering ip addresses).



PROGRAM DIRECTORIES - (/CGI-BIN):
================================

PlanetWide has built-in support for handling the POST-METHOD and GET-METHOD
CGI(common gateway interface). This interface allows the server to host various
external programs such as digit-counters, guest-books and interfaces to 
databases across the web.


During the installation process, a subdirectory of the server directory must be
created to store your EXE and CMD files. The directory is x:\WEBSERV\CGI-BIN\


Note: if your web server directory is named other than x:\webserv, create the 
      \cgi-bin\ directory in the correct location.


For example: if a user accesses a guest-book from a web page, PlanetWide
searches the \CGI-BIN directory for the program specified. If the specified
program is found, it is then initiated. If no matching file is found, 
the request is ignored.


PlanetWide assumes the file extension of a CGI, so there is no need to fully
qualify the CGI filename. If you wish to execute GUESTBOOK.EXE, simply use 
this command:

    <FORM METHOD="POST" ACTION="/cgi-bin/guestbook">


For a tutorial on CGI programming, (see: online cgi tutorial) in the online
documentation stored in the \doc\index.htm location.



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 file 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 an .MP3 file.



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

  HTML text html
  HTM text html
  SHTML text html
  TXT text plain
  TEXT text plain
  CMD text plain
  DOC text plain
  FAQ text plain
  GIF image gif
  JPG image jpeg
  JPEG image jpeg
  JPE image jpeg
  TIF image tiff
  TIFF image tiff
  BMP image bmp
  AU audio basic
  WAV audio x-wav
  WAVE audio x-wav
  SND audio basic
  MID audio x-midi
  MIDI audio x-midi
  AVI video avi
  MPG video mpeg
  MPE video mpeg
  MPEG video mpeg
  INF application x-inf
  PDF application x-pdf
  PS application postscript
  ZIP application zip
  DVI application x-dvi
  OCT application octet-stream



THE LOG FILE: (WEBSERV.LOG):
===========================

A wide variety of information is tracked by the server in its log file called 
WEBSERV.LOG. This is an ASCII formatted text file editable in EPM, or any 
wordprocessor.



UNDERSTANDING THE LOG ENTRIES:
=============================

  Each entry into the LOG file consists of Date/Time Tracking items:

  - Short day name
  - Short month name
  - Day in numberical format
  - 24 hour time (hour:min:sec)
  - Full year
  - Current Thread count (T=n)
  - Peak Thread count (P=n)


  Various processed actions will be appended to the Date/Time Tracking items:
 
  - Server Startup information.
  - Client IP address or domain name ( reverse DNS lookup )
  - File requests (html docs, images, audio, etc....).
  - CGI program executions (POST & GET Method).
  - Error postings (denial of access, or missing pages, missing files).



SAMPLE LOG ENTRIES:
==================

Sun Aug 5 14:00:07 1997 *** SERVER STARTED ***
Tue Aug 5 21:36:24 1997 T=1 (P=7) File: doc/frames/framedoc.htm [393], To: 2.2.2.2, Referer: http://2.2.2.2/doc, Agent: Mozilla/2.02 (OS/2; I)
Tue Aug 5 21:36:25 1997 T=1 (P=7) File: doc/frames/_dfr3.htm [552], To: 2.2.2.2, Referer: ?, Agent: Mozilla/2.02 (OS/2; I)
Tue Aug 5 21:36:25 1997 T=2 (P=7) File: doc/frames/_dfr2.htm [27634], To: 2.2.2.2, Referer: ?, Agent: Mozilla/2.02 (OS/2; I)
Tue Aug 5 21:36:25 1997 T=3 (P=7) File: doc/frames/_dfr1.htm [2950], To: 2.2.2.2, Referer: ?, Agent: Mozilla/2.02 (OS/2; I)
Tue Aug 5 21:36:25 1997 T=4 (P=7) File: doc/frames/images/granite.jpg [10190], To: 2.2.2.2, Referer: http://2.2.2.2/doc/frames/_dfr2.htm, Agent: Mozilla/2.02 (OS/2; I)
Tue Aug 5 21:36:26 1997 T=3 (P=7) File: doc/frames/images/pwback.jpg [10336], To: 2.2.2.2, Referer: http://2.2.2.2/doc/frames/_dfr3.htm, Agent: Mozilla/2.02 (OS/2; I)


Client specific information is included in each log entry which may be of use 
to PlanetWide users.

 - Client IP address or registered domain name: ( TO: 2.2.2.2 / TO: www.myserver.ca )
 - Referer to each request: ( Referer: http://www.altavista.com?s=os2+web+server )
 - Client Agent/web browser:  (Agent: Mozilla/2.02 (OS/2; I) )




FILTERING IP ADDRESSES (FILTER):
===============================

Place this file in directories which require security.  Each entry in the
FILTER file may ENABLE or DISABLE individuals 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 an asterisk(*) 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


- *.*.*.*   
+ 131.104.*.*



By default, everyone is allowed to browse your web pages and links. By
specifying "-*.*.*.*" 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:


- *.*.*.*
+ 131.104.*.*
- 131.104.68.10




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 are welcome to modify this HTML page to 
suit your system.


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



IMAGE MAP SUPPORT:
=================

PlanetWide web server has built-in support for handling clickable images
(IMAGE-MAPs). Currently RECT, CIRCLE, POLY and DEFAULT are available to you 
and your users.


Many NCSA compliant graphical image-map creation tools are available for 
download from the internet.  Most, if not all support RECT, CIRCLE, POLY and 
DEFAULT regions. 


Currently, the POLY image-map function has a limitation of ten(10) points
maximum. Exceeding this limit will cause your imagemap to perform improperly.


All image-maps are maintained by the web-page owner in their own user
directory. This removes all maintenance responsibilities from the Webmaster.

  
To learn more about IMAGE MAP (see: online imap tutorial at \doc\tutorial).



HOW TO REGISTER:
===============

Registering your copy of PlanetWide is encouraged. Not only will the 
registration nag messages go away, but you will receive your own personalized 
copy of PlanetWide OS/2 Web Server.

PlanetWide OS/2 Web Server is priced $45.00 U.S. per copy.



REGISTRATION METHODS:
--------------------

Run the REGISTER.EXE registration program supplied in the PWWS110.ZIP archive.
 
Fill in your information as completely as possible. Submit the registration
while online on the internet, or print the completed form and send it to
BMT MICRO Inc. to:

*Choose the  method of delivery and order quantity from the ORDER INFO screen.



POST:
---- 
      BMT MICRO Inc.
      P.O. Box 15016
      Wilmington, NC
      USA 28408


FAX:
----
      BMT MICRO Inc.
      (800)346-1672
      (910)350-2937


EMAIL:
-----

      BMT@BMTMICRO.COM


PHONE:
-----
      BMT MICRO Inc.
      (800)414-4268
      (910)791-7052


 
Once your registration has been processed, you will receive your personalized
copy of PlanetWide v1.10 via MIME attachment to your email address unless 
otherwise specified.


 Note: If you prefer to have your registered copy of the software sent
       to you on disk(s), please include additional $5.00 U.S. per copy 
       with your order. 



CONCLUSION:
==========

If you have ANY installation or administration problems that we can help you
with, send us E-mail to cepayne@uoguelph.ca. 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 and let us know. Include
your web URL, we would love to hear from you and visit your web site.


          Check our web page for updates and helpful hints!



           Yes, our own web server is running PlanetWide!




HOW TO CONTACT THE AUTHORS:
==========================

  Email us:  cepayne@uoguelph.ca
  

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


 POST:  Payne-Mennie Computing Services
                57 Moss Place
              Guelph, Ontario
                  Canada
                  N1G 4V2



   (c)Copyright 1997 Payne-Mennie Computing Services. All rights reserved.


