File:
upload.pl, Tom Melly, tom@tomandlu.co.uk
Provided free and without restrictions. Derived work subject to same.

Description:
This upload script can work with either html (parsed or
unparsed - see below), or as a stand-alone upload application, both
generating the initial upload form and the responses.

In both cases, it handles the upload and transfer of a user's local file to
a specified directory and unique filename.

As well as running under taint-mode, additional security is provided via
various options, including a simple password system.

Instructions:
The script can be invoked in one of two ways. If called without parameters,
and provided $allow_form is set to true (non-zero/non-blank), then the
script will return a basic submission form, using the parameters defined
by the user.

If called with parameters, then it will process the form-submission and
file-upload. It returns the results of the submission (success or failure),
and the reason, if any, for the failure.

If you are calling the script from an external form, then you should ensure
that your form contains the same named-parameters as you have defined in
the form (see below).

As well as your defined parameters, the form should also define 'file' as a
file-input field - e.g. <INPUT TYPE="FILE" NAME="file">.

Additionally, if you have set $password to a value, your form should define
password as an input field.

Make sure that your output directory is writable for submitters.

Sample html files are supplied. The default options on the form are for
running the script as a stand-alone. Here are the option-changes needed
to run the script with sample html pages.

# html options
my $success =         '../upload/up_success.html';
my $fail    =         '../upload/up_fail.html';
my $allow_form =      0;
my $interp_success =  1;
my $interp_fail =     1;
my $link =            '../upload/upload.html';

Note that ../upload/ is assumed to be a writable directory.

As a general note, when setting boolean options, in Perl false is anything
that evaluates to 0 or a 0-length string, so both 0, and "" are false.
              
Options:
General Options:

# file-output options
$filedir = string, output dir for uploaded files
$max_size = int, max. size for file-uploads (approx. due to other form inf.)
$max_dir_size = int, max total size of contents of $filedir

# html options
$success = string|boolean, page to call on success
$fail = string|boolean, page to call on fail
$allow_form = boolean, generate form if called without params
$interp_success = boolean, parse result - see below
$interp_fail = boolean, parse result - see below
$link = string, link given on auto-generated pages;

# mail options
$mailer = string, location of sendmail
$recipient = string, email address of script owner
$mail_recipient =  boolean, mail $recipient on submission
$mail_sys_error =  boolean, mail $recipient on system error

# security options (see also '$allow_form')
@referers =  list ('foo','bar'), allowed referers for submissions
$password =  string|boolean, required password, if false then not required
@valid_ext = list ('txt', 'jpg'), valid file extensions for submissions;

Form Parameter Options:
You may specify the names of the parameters to use in form processing. If
you are using your own html files, then you should ensure that your html
contains references to the same parameters.

Form parameters are defined in the hash-table, %param_hash, as
array-references.

When modifying, deleting or creating a new parameter, care should be taken
not to modify the surrounding hash-definition code.

To add a new parameter, follow this template:
param_name, [description, form-field_type, sort-order, required],

Where:
param_name = string(word), name of parameter
description = string, description of parameter, used in generated output
form-field_type = string(word), cgi.pm type for formfield if generating form
order = int, sort-order for params-output, 1-n (submitted file is always 1st)
required = boolean, whether param is required or not

Parsed HTML:
If either $interp_success or $interp_fail is true, and the $success or $fail
pages are called, then any references to PARAM:foobar will be replaced with
the value of the form parameter foobar - assuming that foobar is defined as
a valid parameter (see above). Note that if $success and $fail are not
defined, then this will make no difference to the behaviour of the script.

As well as user-defined parameters, the following params can also be used:

PARAM:file = the upload dir\filename
PARAM:upfile = the output dir\filename
PARAM:link = the value of $link(see General Options)
PARAM:message = additional info made avail to sub_error (eg missing params)

If you have any bug-reports, suggestions, or just need help, please email:
tom@tomandlu.co.uk