______________________________________________________________________________
| File Upload Script                Version 5.03                             |
| Created on 4/8/96                 Last Modified: 06/19/97 17:30            |
| Scripts Found at:                 http://www.terminalp.com/scripts/        |
| Copyright 1996 By Jeff Carnahan   jeffc@terminalp.com                      |
|____________________________________________________________________________|
| If you run into any problems while trying to configure this scripts, help  |
| is available.  The steps you should take to get the fastest results, are:  |
|       1) Read this file thoroughly                                         |
|       2) If you are still having difficulty installing this script, send   |
|          e-mail to: script-help@terminalp.com                              |
|          Include any error messages you are receiving and as much detail   |
|          as you can so I can spot your problem.  Also, please include      |
|          the variables at the top of the script.                           |
|                                                                            |
|   Hopefully I will be able to help you solve your problems.  Thank you.    |
|____________________________________________________________________________|
| Copyright (C) 1996 Jeffrey D. Carnahan                                     |
|                                                                            |
| 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.                                   |
|                                                                            |
| A full copy of the GNU General Public License can be retrieved from        |
| http://www.terminalp.com/scripts/copying.html                              |
|                                                                            |
| - Jeff Carnahan <jeffc@terminalp.com>                                      |
|____________________________________________________________________________|

This script is to be used to upload files via Netscape Navigator 2.0+'s new
multipart/form-data MIME type.  Via this MIME type, users can select files
on their systems to be sent to the server running this CGI-BIN script.  
There are restrictions on the HTML Forms and what they have to have in them.
This script is for use with the POST method, (since the file-length is
unknown). It will work with the GET method, but I *HIGHLY* recommend the
POST method.  One other thing that you should be familiar with is that this
script will only work with The Microsoft Internet Explorer if the user has
installed Microsoft's upgrade, which gives MSIE this feature.


The script, file-upload.cgi, needs to be placed in your server's cgi-bin and
the anonymous WWW user must have the ability to read/execute the script.

Setting Up the Upload Script:
===============================

The file-upload.cgi script does not have to be extensively configured
to get it to work.  In fact, there is only 1 line you need to manually 
modify under the file-upload.cgi, script.  First, you must make sure the 
top line of the script matches the location of you Perl interpreter.

You can find the location of your Perl interpreter on your system, by
executing the command: 'which perl5' at the UNIX command prompt.  A 
typical use of this command looks like this:

$ which perl5
/usr/local/bin/perl5
$ 

In this case, you have just found that the location of Perl on your system,
is "/usr/local/bin/perl5".  To update the file-upload.cgi script, you need
to append this value to '#!'.  So, for this example, the first line of the 
'new-upload.cgi' script should look like:

#!/usr/local/bin/perl5

*************************************************************************
        NOTE:        This script MUST use Perl 5+ To Work!
*************************************************************************

Necessary Variables:
--------------------

    Finally, to configure the variables, you need to complete the following 
    steps:
    
    1) Type "chmod 755 ./file-upload.cgi" in the directory where 
       file-upload.cgi resides. (This makes your script executable)

    2) Make sure that the file, CGI.pm that came with this script is in
       the same directory as file-upload.cgi.  The file-upload.cgi script
       looks to CGI.pm to get information about how to handle uploaded
       files.

    3) Type "chmod 644 ./CGI.pm" in the directory where file-upload.cgi
       and CGI.pm reside.  (This makes CGI.pm readable by the script)

    4) Type "perl5 ./install" to finish configuring your script.

A Sample Session looks like:

<--- Start Of Captured Session --->
$
$ chmod 755 ./file-upload.cgi
$ chmod 644 ./CGI.pm
$ perl5 ./install
Thank You For Obtaining my File Upload Script.

This will now configure your copy of the script.

Please Answer The Following Questions:

 ..... [bulk suppressed] .....

Ok. Please use the values in these variables inside the script.

# <------- Snip Here ------->
$userid        = "1234";
$groupid       = "1000";
$path          = "/usr/www/terminalp/scripts";
$url           = "http://www.terminalp.com/scripts";
$overwrite     = "0";
$success_url   = "";
# <------- Snip Here ------->

$
<--- End Of Captured Session --->

    Thanks to the install program, we now know what we need to add to the
    file-upload.cgi script to finish the configuration.  In this case, we 
    would copy the variables between the two #<------- Snip Here ------> 
    lines, and use the information inside the file-upload.cgi file. After 
    that is done, no further modification to file-upload.cgi is needed.


Updating The HTML File:
------------------------
    Next comes updating the included HTML file.  This should be simple, as you
    only need to change one thing to finish the setup.  The part that declares
    the action of the form tag needs to point to the script on your server.
    i.e.: if file-upload.cgi can be found with the URL:
    http://www.myhost.com/cgi-bin/file-upload.cgi
    then that would be the value to put in this field.

    If you want to integrate the form into one of your own HTML documents,
    you **!MUST!** follow the following rules:

        1) The Form Tag *SHOULD* be set to the POST method (The Get Method
           sends information along the URL, which isn't desired if you will
           be sending any type of binary files, or files longer than ~1 k.
        
        2) The Form *MUST* include the ENC-TYPE tag used in the included HTML
           file.

        3) Remember to set the "upload-file" element to have the type field 
           set to "file" as well, this informs Netscape Navigator that you
           will be            putting a filename in this input box.

-----------------------------------------------------------------------------
FAQ's:

   Q: I put the script in my CGI bin directory, but when I access it through
      the web, it says 'File Not Found'.  What gives?
   A: Make sure that you are using the proper URL (make sure you spelled
      everything right, and that the file should indeed exist where you're
      looking), also make sure that you used the 'chmod 755 ./file-upload.cgi'
      command on the script.  If this doesn't work, talk with your system
      administrator.  Your ISP could have a weird setup where your cgi-bin
      directory doesn't really exist where you suspect it should.. =)

   Q: When I run the script through the web, I get a 'Server Error'...
   A: This is most commonly caused by an incorrect configuration.  If
      possible, try running the script at your UNIX command prompt.  Go
      into the directory where the script is, and type './file-upload.cgi'
      and see what happens. Perl should give you some indications as to
      where the error is occurring.  (This error is also commonly generated
      when you forget to put the CGI.pm file in the same directory as the
      file-upload.cgi file. Verify that they are indeed in the same
      directory.)

   Q: My server runs on Windows NT... Is there any way I can use the File-
      Upload script?
   A: Yes, thanks to some tips from other users, I discovered that you can
      indeed run the File-Upload script on a NT server.  Simply follow the
      instructions prompted to you in the ./install program, and it should
      work fine.

   Q: Every time I upload a file, the server says it was less than one byte
      in size, thus it doesn't save the file.  What happened?
   A: This is a known bug in version 5.02.  Re-download the latest version
      from http://www.terminalp.com/scripts/  (Version 5.03+)

   Q: When I run the script, I get an error message from Perl.  It says:

         Can't find string terminator "END_OF_AUTOLOAD" anywhere
         before EOF at CGI.pm line XXX.

         BEGIN failed--compilation aborted at ./file-upload.cgi
         line XXX.

      How can I fix this?
   A: Try re-downloading the CGI.pm module from the CGI.pm home page:
      http://www-genome.wi.mit.edu/ftp/pub/software/WWW/

-----------------------------------------------------------------------------

  Version:  Time Stamp:        History:
  _______________________________________________________________________

      1.00  04/08/96 00:00     The script was created.
      1.10  04/23/96 00:00     Added User and Group ID to allow file
                               changing by the actual user, also updated
                               a security hole which allowed any user with
                               the UID of 1376 to own the uploaded files.
                               Also Updated the INSTALL program and README
                               files.
      3.00  05/07/96 00:00     New release with group and user id fixes, it
                               updates a previously unreleased version (2.0)
      3.10  05/10/96 00:00     Stupid Typo in script fixed, it was
                               causing problems for some users.
      4.00  08/04/96 23:16     Security hole regarding '../' paths
                               fixed.  Thanks to: Rus Berrett.  Mime
                               type error fixed.  Thanks to: Bob Stewart.
      4.01  08/07/96 11:20     Typo fixed in &NoOpen.  Thanks to Marco
                               Dings.
      5.00  10/06/96 21:42     Fully rewrote script around CGI.pm library.
                               As soon as I get the time, I'll write more
                               features into it, but for now, this version
                               is stable (to the best of my knowledge).
      5.01  02/09/97 12:41     Fixed some typo's, and added support for
                               Netscape Communicator.
      5.02  05/07/97 15:37     Fixed a possible binary file uploading,
                               added easier support for NT, and fixed
                               documentation problems. Added the FAQ.
      5.03  06/19/97 17:30     Fixed a bug which resulted in all files
                               appearing to be less than one byte in
                               size, thus uploads weren't saved.

-----------------------------------------------------------------------------
Jeff Carnahan - (jeffc@terminalp.com) - http://www.terminalp.com/scripts/

