OLIVER Version 2.01

Extension for Form-Based File Upload in HTML
Compliant with MS-ISAPI Spec V.2.0
Montreal, August 6th 1998


Readme file content
*******************

   * Overview
   * Installation
   * How It Works
   * Oliver Simple Evocation
   * Oliver Complexe Evocation
   * Multiple Upload Web Page
   * Uploading files under multiple sub-directories
   * Configuring the upload status window
   * Log file structure
   * Limitations
   * Troubleshooting
   * Oliver on the Internet
   * Help a Shareware Author!!!
   * Software Ch-Ch-Ch-Ch-Changes
   * Known bugs
   * Thanks
   * Registration
   * Conclusion



Overview
========

   Oliver is an ISAPI Extension DLL for IIS server to accept 
   form-based file upload in HTML. The extension interprets forms 
   with the ENCTYPE="multipart/form-data" tag.

   Here are some Oliver features:

     - Redirection implementation.
     - Live upload progress window on client side.
     - All server upload activity logged.
     - Support for simultaneous upload.
     - Each uploads are tagged with a unique upload identifier.
     - You can pass a QueryString to the redirected URI.
     - Internal query 'name=value' substitution implementation.
     - Multiple Content-Disposition support.
     - Support for internal substitution of traditional CGI variables.
     - Control the maximum file size that can be upload on the server.
     - Control the minimum free disk space to keep on the server.
     - Automatic virus detection on uploaded files.
     - Automatic SMTP upload email warning service.
     - Send the uploaded file as a uuencoded attachement email.
     - Uploaded files are prefixed for security reasons.
     - You can reject uploads depending on remote filename extension.
     - Accept only files with special file extension.
     - Support for long file names.
     - Support file names containing space characters.
     - Dump command to help you analyse software installation problems.
     - Support for multiple upload web page.
     - Server Environment variable substitution support.
     - Upload files under multiple sub-directories.
     - Internal substitution support for JavaScript redirection URI's.
     - Internal extension activity tracing.
     - Control the upload dump filename.


   Developed and tested under the following environment:

     - O.S...... Windows NT workstation V.4.0 B1381 PID2 Service Pack 3
     - Server... Microsoft Personnal Web Server V.4.0
     - Client... Netscape Navigator V.4.05 
                 and Microsoft Internet Explorer V.4.01 SP1


   Important Information:

   +============================================================+
   |   IMPORTANT WARNING IMPORTANT WARNING IMPORTANT WARNING    |
   |============================================================|
   |                                                            |
   |        --> This can be a serious security hole <--         |
   |  NEVER ALLOW UPLOADING TO YOUR WEB SERVER CGI DIRECTORY!   |
   |  NEVER ALLOW UPLOADING TO YOUR WEB SERVER CGI DIRECTORY!   |
   |  NEVER ALLOW UPLOADING TO YOUR WEB SERVER CGI DIRECTORY!   |
   |  NEVER ALLOW UPLOADING TO YOUR WEB SERVER CGI DIRECTORY!   |
   |  NEVER ALLOW UPLOADING TO YOUR WEB SERVER CGI DIRECTORY!   |
   |       --> This can be a serious security hole <--          |
   |                                                            |
   +------------------------------------------------------------+ 

   +============================================================+
   |                SHAREWARE VERSION LIMITATION                |
   |============================================================|
   |                                                            |
   | With the Shareware version of Oliver, you won't be able    |
   | to upload forms containing more than 100000 bytes of data. |
   |                                                            |
   | > There is no upload limits with the registered version  < |
   | > There is no upload limits with the registered version  < |
   | > There is no upload limits with the registered version  < |
   |                                                            |
   +------------------------------------------------------------+ 


   Remarks:

   For more information on form-based file upload in HTML, 
   please consult the Request For Comments, RFC#1867.



Installation
============

   There is no installation program.
   But the manual installation steps are very easy:

   1/ Copy isgt32.dll under the IIS server scripts directory.
      Ex.: copy isgt32.dll c:\Inetsrv\Scripts

   2/ Copy the supplied oliver directory and all HTML files 
      under your web server document root directory.
      Customize all these HTML files to reflect your web 
      environment.

   3/ Copy isgt32.ini under the Windows home directory.
      Ex.: copy isgt32.ini c:\Winnt
      Edit the copied c:\winnt\isgt32.ini file to make it 
      reflect your environment configuration.

   4/ Test Oliver by opening the Upload.html
      file supplied with this software package.



How It Works
============
                                                      ___________ 
  +--------+           Data Upload --->              /           \
  |        |------->------------------>------------- |           |
  |  Web   |                                         |    Web    |
  | Client |----<------------<------------+          |   Server  |
  |        |                              |          |           |
  +--------+                         Redirection     \___________/
       \ _                                |                |
       |\                                /|\               |
     Redirection                          |(Rejected)     \|/ 
          \                             __|__              | 
   ######################              /     \           ISAPI 
   #                    #             /       \            | 
   #    Write data      #  (Accepted)+         +     *************
   #  Virus Detection   # /_________ | Upload  | /__ *           *
   #  Log Transaction   # \          |Security | \   * Oliver    *
   # SMTP Warning Email #            |         |     * Analyzer  *
   #                    #            +         +     * Extension *
   ######################             \       /      *           *
                                       \_____/       *************




Oliver Simple Evocation
=======================

   HTML Code sample:

<FORM ENCTYPE="multipart/form-data"
      NAME="UploadForm"
      ACTION="http://your.server.address/scripts/isgt32.dll"
      METHOD=POST>
  <P>
  <INPUT NAME="filedata" TYPE="file"   SIZE="43">
  <INPUT NAME="reset"    TYPE="reset"  VALUE="Reset ">
  <INPUT NAME="submit"   TYPE="submit" VALUE="Upload">
  <P>
</FORM>



Oliver Complexe Evocation
=========================

   You can specify a query string on the Oliver Action command. 
   By doing so, oliver will append the specified query string to
   the redirection URL. There is also some Oliver internal substitution
   tags you can use to analyse and process the upload request on the
   redirection side. In the following example, the query string 
   "val1=1&val2=!OVL_LOCAL_FILENAME" will be trapped by Oliver. 
   He then will substitute !OVL_LOCAL_FILENAME by the uploaded file path,
   and will make a redirection like: 

      http://srv/path/ok.html?val1=1&val2=c:\tmp\afile


<FORM ENCTYPE="multipart/form-data"
      NAME="UploadForm"
      ACTION="http://your.server.address/scripts/isgt32.dll?val1=1&val2=!OVL_LOCAL_FILENAME"
      METHOD=POST>
  <P>
  <INPUT NAME="filedata" TYPE="file"   SIZE="43">
  <INPUT NAME="reset"    TYPE="reset"  VALUE="Reset ">
  <INPUT NAME="submit"   TYPE="submit" VALUE="Upload">
  <P>
</FORM>

   ----------------------   -------------------------------------------------  
   Tags                     Substitued By
   ----------------------   -------------------------------------------------  
   !"A_Cgi_Variable"        GetServerVariable on that value. Ex.: !REMOTE_HOST
   !"A_System_Env_Variable" GetEnv on that value. Ex.: !OS, !PATH
   !OLV_LOCAL_FILENAME      Filename for the local uploaded file
   !OLV_LOCAL_FILESIZE      Uploaded file size in bytes
   !OLV_TARGET_DIRECTORY    Target upload directory
   !OLV_REMOTE_FILENAME     Client file path
   !OLV_LOG_FILENAME        Oliver log file path
   !OLV_UPLOAD_ID           Oliver Unique Upload ID Identifier

   !OLV_UPLOAD_STATUS       Oliver Request Status

                            Status Mapping
                            -------------------------------------------------
                            200.....Ok. Successful Upload
                            210.....Internal /About command execution
                            211.....Internal /Dump command execution
                            250.....Virus scanning done successfully
                            252.....Advise EMail successfully sent
                            900.....Unable to open data file
                            910.....Unable to malloc (not enough memory)
                            920.....No data in extension control block
                            930.....Unable to re-open data file
                            940.....File already exist
                            950.....Data file empty
                            960.....Unable to create local file
                            970.....Write disk error
                            975.....File extension rejected
                            980.....File pointer position error
                            991.....Unable to exec the virus scan command
                            999.....Unexpected error
                           13xx.....Error occurred while sending email
                           19xx.....Error occurred while uuencoding attachment mail


   A more complexe upload form would be as the following. In that case, 
   you can specify other input fields in the HTML form to request more 
   information from the uploader client. Oliver will then merge the
   query string AND the fields submitted values to the redirection
   URL as follow: (With no CR/LF)

      http://srv/path/ok.html?val1=1&val2=C:\tmp\afile
      &description=This+is+a+new+file...&username=Your+Name
      &email=you@here.com&radio1=True&session=1234567890


<FORM ENCTYPE="multipart/form-data"
      NAME="UploadForm"
      ACTION="http://your.server.address/scripts/isgt32.dll?val1=1&val2=!OVL_LOCAL_FILENAME"
      METHOD=POST>
  <INPUT NAME="filedata" TYPE="file" SIZE="43"><BR>
  Desc: <INPUT NAME="description" TYPE="text" VALUE="This is a new file..." SIZE="38"><BR>
  Name: <INPUT NAME="username" TYPE="text" VALUE="Your Name" SIZE="38"><BR>
  Mail: <INPUT NAME="email" TYPE="text" VALUE="you@here.com" SIZE="38"><BR>
  True  <INPUT TYPE="radio" NAME="radio1" VALUE="True" CHECKED> 
  False <INPUT TYPE="radio" NAME="radio1" VALUE="False"><P>
  <INPUT TYPE="hidden" NAME="session" VALUE="1234567890">
  <INPUT TYPE="reset" VALUE="Reset ">
  <INPUT TYPE="submit" VALUE="Upload">
</FORM>



Multiple Upload Web Page
========================

   Oliver configure himself by searching the following initialization file:
   "drive:\windows_home\oliver_extension_base_file_name.ini".
   So you can implement multiple upload pages by copying/renaming the 
   extension dll file and the initialization file. 
   
   For example;
   /scripts/isgt32.dll will search for c:\winnt\isgt32.ini
   /scripts/upload.dll will search for c:\winnt\upload.ini



Uploading files under multiple sub-directories
==============================================

   You can allow uploading under multiple sub-directories by using
   "!OLV_TARGET_SUBDIRECTORY=adirectory" on the Oliver Query String.
   The directory specified by !OLV_TARGET_SUBDIRECTORY must exist and
   must be a sub-directory of the upload target directory. The upload
   target directory is the one that is configured in the Oliver 
   initialization file.

<FORM ENCTYPE="multipart/form-data"
      NAME="UploadForm"
      ACTION="http://your.server.address/scripts/isgt32.dll?!OLV_TARGET_SUBDIRECTORY=subdir"
      METHOD=POST>
  <P>
  <INPUT NAME="filedata" TYPE="file"   SIZE="43">
  <INPUT NAME="reset"    TYPE="reset"  VALUE="Reset ">
  <INPUT NAME="submit"   TYPE="submit" VALUE="Upload">
  <P>
</FORM>

   NOTE1: The ACTION tag must be enclosed between quotes characters.
          The file will then be uploaded under the "TARGET_DIRECTORY\subdir"
          directory.

   NOTE2: If the specified sub-directory dont exist, you can let Oliver
          to create the directory by setting 'CreateSubDir=1' in the Oliver
          initialization file.



Configuring the upload status window
====================================

   1/ In the Oliver initialization file, configure the following:

        - All fields of the [UploadStatus] section.
        - Fields 'OliverDocRoot' and 'OliverUrlRoot' in the [Oliver] section

   2/ Copy the 'uplstart.html' file under the directory specified
      by the configured OliverDocRoot directory. Customize this file
      to reflect your Web environment. (Use the /InitStatus Oliver 
      initialization command in the URL tag of the Refresh meta html 
      tag ONLY in this paticular page!)

   3/ In the HTML file that the client will receive to select
      the file to upload, set a form like this one:

      <FORM ENCTYPE="multipart/form-data"
            NAME="UploadForm"
            ACTION="http://your.server.address/scripts/isgt32.dll"
            METHOD=POST>
        <INPUT NAME="filedata" TYPE="file" SIZE="43">
        <INPUT TYPE="submit" 
               VALUE="Upload"
               onClick="window.open('http://your.server.address/Oliver/uplstart.html','statusWindow','menubar=no,resizable=yes,height=260,width=350');">
      </FORM>



Log file structure
==================

   date - upl_id - remote_ip - local_filename - upl_status_code - upl_status_message



Limitations
===========

   1/ Maximum number of bytes accepted for the shareware version..... 100000
   2/ Maximum number of bytes accepted for the registered version.... Unlimited
   3/ Maximum number of form inputs accepted......................... 100 pairs
   4/ Maximum lenght for redirection URI............................. 255
   5/ Maximum lenght for redirection query string after substitution. 16384
   6/ Maximum lenght for redirection URL (4 + 5)..................... 16639

                                                

Troubleshooting
===============

   1/ Consult the Oliver log file.

   2/ Consult your Web server log file.

   3/ Oliver internal commands:

      - Dump page... http://your.server.address/scripts/isgt32.dll/dump
        (You must enable this command from the Oliver ini file)

      - About page.. http://your.server.address/scripts/isgt32.dll/about

   4/ Enable the trace option from the Oliver initialization file.

   5/ Contact the author.



Oliver on the Internet
======================

   Support Contact:     mailto:ssenechal@sympatico.ca
   Author Home Page:    http://www3.sympatico.ca/ssenechal
   Shareware Updates:   http://www3.sympatico.ca/ssenechal/oliver
   Phone:               (450) 647-0322 (North-East America)



Help a Shareware Author!!!
==========================

   Why dont you use something like:

   <A HREF="http://www3.sympatico.ca/ssenechal/oliver" TARGET="newwindow">
      <IMG SRC="/oliver/olvbannr.gif" ALT="Powered By Oliver" BORDER=0>
   </A>



Software Ch-Ch-Ch-Ch-Changes
============================

   ----------------------------------------------------------------------
   V.0.98  (December 14, 1997)
   ----------------------------------------------------------------------
     - FAQ: Why the name "Oliver"; Cause its the name of my second child!
     - BLD: First Alpha

   ----------------------------------------------------------------------
   V.0.98a (December 16, 1997)
   ----------------------------------------------------------------------
     - IMP: Redirection implementation.
     - FIX: Remove any hardcoded paths. All defines in the ini file now.
     - FIX: Better error detection while receiving data from the client.
     - BLD: First Beta. 

   ----------------------------------------------------------------------
   V.0.98b (December 18, 1997)
   ----------------------------------------------------------------------
     - IMP: Now can pass a QueryString to the redirected URI.
     - IMP: Dump command implementation.
     - IMP: Prefix customizable via the initialization file.
     - IMP: Internal name=value substitution implementation.
     - IMP: Support for substitution of traditional CGI environment.
     - IMP: Add Upload ID Identifier for internal substitution.

   ----------------------------------------------------------------------
   V.0.99 (December 21, 1997)
   ----------------------------------------------------------------------
     - IMP: Add the associated upload ID in the Oliver log file.
     - IMP: Multiple Content-Disposition support.
     - IMP: About command implementation.
     - IMP: Add the EnableDump section.
 
   ----------------------------------------------------------------------
   V.1.00 (December 22, 1997)
   ----------------------------------------------------------------------
     - IMP: Local File Size substitution support.
     - BLD: V.1.00 First Shareware Release.

   ----------------------------------------------------------------------
   V.1.01 (December 23, 1997)
   ----------------------------------------------------------------------
     - FIX: Support for filename containing space characters.
     - IMP: Automatic external virus detection on uploaded files.
     - FIX: Dump data file unlink after transaction.
     - IMP: Counter index now readed from the ini file.
     - BLD: V.1.01 First Beta Release.

   ----------------------------------------------------------------------
   V.1.01 (December 27, 1997)
   ----------------------------------------------------------------------
     - IMP: Security. Transaction accepted depending on file entension.
     - IMP: Security. SMTP warning email automation.

   ----------------------------------------------------------------------
   V.1.01 (December 31, 1997)
   ----------------------------------------------------------------------
     - BLD: V.1.01 Software sub-version "d" general release.

   ----------------------------------------------------------------------
   V.1.02 (January 1st, 1998)
   ----------------------------------------------------------------------
     - BLD: Now working on V.1.02...

   ----------------------------------------------------------------------
   V.1.02 (January 6, 1998)
   ----------------------------------------------------------------------
     - WAR: Ice storm here in montreal.
            Development stopped for a while... Sorry about that ;/
            ( No electricity for 6 days at -14C... ;( So no PC... )

   ----------------------------------------------------------------------
   V.1.02 (January 17, 1998) 
   ----------------------------------------------------------------------
     - FIX: Miscellaneous optimization.
     - IMP: Ability to enable-disable the file prefix stuff.
     - IMP: Oliver now initialize his configuration base on the extension
            file name instead of the 1.01 hard-coded 'Oliver.ini' file 
            name. So can now have more than one Oliver extension on a 
            single web server.
     - BLD: Last 1.02 build.

   ----------------------------------------------------------------------
   V.1.03 (January 30, 1998)
   ----------------------------------------------------------------------
     - BLD: Now working on V.1.03...
     - FIX: All pBlock->GetServerVariable dwLen fixed.
     - FIX: Empty remote address IP in logfile if successful upload. 
     - IMP: Add OS Version Information in Dump command output page.
     - DOC: Add a FAQ.TXT file to the software documentation.

   ----------------------------------------------------------------------
   V.1.03 (Febuary 03, 1998)
   ----------------------------------------------------------------------
     - IMP: Target Sub-directory implementation.

   ----------------------------------------------------------------------
   V.1.03 (March 02, 1998)
   ----------------------------------------------------------------------
     - IMP: JavaScript oliver variable substitution implementation.

   ----------------------------------------------------------------------
   V.1.04 (June 14, 1998)
   ----------------------------------------------------------------------
     - BLD: Now working on V.1.04... (Development. None public version)
     - FIX: Thread safe. Support for simultaneous upload. (IMPORTANT)

   ----------------------------------------------------------------------
   V.1.04 (June 26, 1998)
   ----------------------------------------------------------------------
     - FIX: Miscellaneous fixes for IIS V4 compatibility  (IMPORTANT)
     - WAR: The extension now runs ok on the Micro$oft IIS V4 Server!
     - IMP: /About and /Dump internal commands now logged.
     - FIX: Shareware limitation page not always returned.
     - IMP: Tracing activity option implementation.
     - IMP: Maxsize implementation.

   ----------------------------------------------------------------------
   V.2.00 (June 28, 1998)
   ----------------------------------------------------------------------
     - BLD: Too many important changes. Now working on V.2.00...

   ----------------------------------------------------------------------
   V.2.00 (June 30, 1998)
   ----------------------------------------------------------------------
     - IMP: AcceptExt implementation.
     - IMP: Internal /Dump rejected execution now logged.

   ----------------------------------------------------------------------
   V.2.00 (July 04, 1998)
   ----------------------------------------------------------------------
     - FIX: Ooops... Subdirectory substitution now thread safe.
     - IMP: FreeSpace implementation.

   ----------------------------------------------------------------------
   V.2.00 (July 05, 1998)
   ----------------------------------------------------------------------
     - BLD: V.2.00 official release.
     - BLD: Now working on V2.01...

   ----------------------------------------------------------------------
   V.2.01 (July 25, 1998)
   ----------------------------------------------------------------------
     - IMP: TempFilename implementation.
     - IMP: CreateSubDir implementation.

   ----------------------------------------------------------------------
   V.2.01 (July 28, 1998)
   ----------------------------------------------------------------------
     - IMP: !OLV_DUMP_FILENAME implementation.

   ----------------------------------------------------------------------
   V.2.01 (July 30, 1998)
   ----------------------------------------------------------------------
     - IMP: Upload Status window implementation. Cool stuff! ;)



Known bugs
==========

   - None yet... Hmmmm!!!!!?????



Thanks
======

   I specially want to thanks:

    * Beta Tester and Motivation Source:
      Richard Lowe, Internet Consultant, Hughes Rae Ltd
      Tel: 01332 600110   mailto:R.Lowe@hughesrae.co.uk
      Fax: 01332 733244   http://www.hughesrae.co.uk

    * Julie... A 'Real' informatician wife. You know what I mean. ;^/



Registration
============

   This program is Shareware, you may evaluate it for a period of 
   no more than 30 days. After this time you must either register 
   (read REGISTER.TXT) or remove it from your system. Failure to comply 
   with this condition is a violation of the law. As you are aware, 
   authors spend numerous hours to create such programs, and this, 
   to reach your requirements.  Therefore, they need all your support. 

   Please register if you use this program for longer than the trial period. 
   The run-time registration is only $20 US. 

   ####################################################################
   ####################################################################
   ##                                                                ##
   ##  C-Sources are also available. Consult the REGISTER.TXT file   ##
   ##  or contact the author at mailto:ssenechal@sympatico.ca        ##
   ##                                                                ##
   ####################################################################
   ####################################################################


   To register, please send your name, address, a check or money order to:

         Sylvain Senechal
         1324 Bibaud Street
         Longueuil, Quebec (Canada)
         J4M 1G6

         Phone: (450)647-0322
         email: ssenechal@sympatico.ca



Conclusion
==========

   THE SHAREWARE VERSION OF OLIVER IS FREELY DISTRIBUTABLE.
   THE REGISTRATED VERSION OF OLIVER IS NOT FREELY DISTRIBUTABLE.

   OLIVER IS SUPPLIED AS IS. THE AUTHOR DISCLAIMS ALL WARRANTIES, 
   EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THE WARRANTIES 
   OF MERCHANTABILITY AND OF FITNESS FOR ANY PURPOSE. THE AUTHOR ASSUMES 
   NO LIABILITY FOR DAMAGES, DIRECT OR CONSEQUENTIAL, WHICH MAY RESULT 
   FROM THE USE OF OLIVER.
	 




Oliver V.2.01 for Windows
Copyright (C) 1997,1998, by Sylvain Senechal, Montreal, Canada.
All rights reserved.
