UBER-UPLOADER VER 3.6  2006/11/19

CONTENTS
--------
INSTALLATION
    - REQUIREMENTS
    - FILE DESCRIPTIONS (upload required or optional)
    - UBER-UPLOADER SETTINGS
    - SIMPLE INSTALLATION
    - SIMPLE INSTALLATION + REDIRECT TO PHP PAGE
    - INSTALLING EXTRA CONFIG FILES
    - INSTALLING BUBBLY PROGRESS BAR
    - CODE OPTIMIZATION
HELP
    - DEBUGGING UBER-UPLOADER
    - FAILED TO FIND FLENGTH FILE
    - HOW TO VIEW AN ACTIVE UPLOAD
    - HOW DO I TELL IF PERL IS WORKING?
    - HOW DO I TELL IF PHP IS WORKING?
    - MULTI SIMULTANEOUS UPLOADS
    - HOW UBER-UPLOADER WORKS

###############################################################################################################################

REQUIREMENTS
------------
1. Operating System: All BSD Platforms (FreeBSD/NetBSD/OpenBSD/Apple Mac OS X), All POSIX (Linux/BSD/UNIX-like OSes)
2. Apache web server
3. Perl with CGI
4. PHP

###############################################################################################################################

FILE DESCRIPTIONS
-----------------

FILE                                             UPLOAD       DESCRIPTION
----                                             ------       ----------- 
cgi-bin/uber_uploader.pl                         REQUIRED    = Uploads the files to the server and displays the results or redirects.
cgi-bin/uber_uploader_progress.pl                REQUIRED    = Displays a progress bar.
cgi-bin/configs/UberUploads.pm                   REQUIRED    = Default configuration file for Uber-Uploader.
cgi-bin/templates/uber_uploader_progress.tmpl    REQUIRED    = Template file used to display the progress bar.
cgi-bin/templates/uber_uploader_finished.tmpl    REQUIRED    = Template file used to display the upload results through CGI.
php/uber_uploader_file.php                       REQUIRED    = Allows the user to select files to upload.
php/uber_uploader_get_data.php                   REQUIRED    = Gets the status of the current upload.

php/uber_uploader_finished.php                   OPTIONAL    = Displays the upload results in PHP if "$redirect_after_upload" in the config file is enabled.

################################################################################################################################

UBER-UPLOADER SETTINGS
----------------------

FILE                                  SETTING                     DESCRIPTION
----                                  -------                     -----------
cgi-bin/configs/UberUploads.pm        config_file_name            = Name of the config file
cgi-bin/configs/UberUploads.pm        debug_cgi                   = Set to 1 if you want to debug and call ( eg. www.yoursite.com/cgi-bin/uber_uploader.pl?cmd=debug&config_file=UberUpload)
cgi-bin/configs/UberUploads.pm        temp_dir                    = Where Uber-Uploader stores temp files while uploading
cgi-bin/configs/UberUploads.pm        upload_dir                  = Where your files will be uploaded 
cgi-bin/configs/UberUploads.pm        unique_upload_dir           = Upload to a unique directory inside the upload directory 
cgi-bin/configs/UberUploads.pm        create_files_by_rename      = Creates the uploaded files by rename which is very fast. Does not work across mounts or disks.
cgi-bin/configs/UberUploads.pm        max_upload                  = Max upload size in bytes (2 * 1024 * 1024 = 2097152 = 2MB)
cgi-bin/configs/UberUploads.pm        overwrite_existing_files    = Enable/Disable file clobbering
cgi-bin/configs/UberUploads.pm        redirect_after_upload       = Enable/Disable file redirect after upload
cgi-bin/configs/UberUploads.pm        redirect_using_html         = Enable/Disable file redirect using html
cgi-bin/configs/UberUploads.pm        redirect_using_js           = Enable/Disable file redirect using javascript
cgi-bin/configs/UberUploads.pm        delete_param_file           = Enable/Disable param file deletion. Only takes affect with redirect_after_upload=1
cgi-bin/configs/UberUploads.pm        redirect_url                = Path to the PHP upload finished page ( eg. http://www.yoursite.com/upload/uber_uploader_finished.php )
cgi-bin/configs/UberUploads.pm        get_data_url                = Path to PHP get data page ( eg. http://www.yoursite.com/upload/uber_uploader_get_data.php )
cgi-bin/configs/UberUploads.pm    (*) get_data_speed              = How fast the progress bar should refresh (1000 = 1 second, 500 = 0.5 seconds, 250 = 0.25 seconds)
cgi-bin/configs/UberUploads.pm    (@) cedric_progress_bar         = Enable/Disable Cdric style progress bar
cgi-bin/configs/UberUploads.pm        disallow_extentions         = File extentions that should be prevented from being uploaded
cgi-bin/configs/UberUploads.pm    (+) allow_extentions            = Only files with these extentions will be uploaded (NOT USED !!!)
cgi-bin/configs/UberUploads.pm        normalize_file_names        = Enable/Disable file name normalization
cgi-bin/configs/UberUploads.pm        normalize_file_delimiter    = The character that is used for file normalization
cgi-bin/configs/UberUploads.pm        normalize_file_length       = The maximum length of the file name
cgi-bin/configs/UberUploads.pm        link_to_upload              = Enable/Disable link to the uploaded file
cgi-bin/configs/UberUploads.pm        path_to_upload              = Path to the uploaded files (used only if link_to_upload is enabled)
cgi-bin/configs/UberUploads.pm        send_email_on_upload        = Enable/Disable email after upload (UNIX type OS's only)
cgi-bin/configs/UberUploads.pm        html_email_support          = Enable/Disable html email support. Only takes affect with send_email_on_upload=1
cgi-bin/configs/UberUploads.pm        link_to_upload_in_email     = Enable/Disable link to the uploaded file in the email. Only takes affect with send_email_on_upload=1 
cgi-bin/configs/UberUploads.pm        email_subject               = The subject line that will appear in the email
cgi-bin/configs/UberUploads.pm        to_email_address            = Email addresses that should recieve an email containing upload info
cgi-bin/configs/UberUploads.pm        from_email_address          = Email address that the email containing upload info is sent from
cgi-bin/configs/UberUploads.pm        progress_template           = Path to the template file used by the progress bar
cgi-bin/configs/UberUploads.pm        finished_template           = Path to the CGI version of the upload finished page
php/uber_uploader_file.php            path_to_upload_script       = Path to the upload script
php/uber_uploader_file.php            path_to_progress_script     = Path to the progress bar script
php/uber_uploader_file.php            multi_config_files          = Enable/Disable multiple config file support
php/uber_uploader_file.php            config_file                 = Name of the config file used for uploads
php/uber_uploader_file.php            multi_upload_slots          = Enable/Disable multiple upload slots = true or false
php/uber_uploader_file.php            check_disallow_extensions   = Check for disallowed file extensions before uploading
php/uber_uploader_file.php        (x) check_allow_extensions      = Check for allowed file extensions before uploading
php/uber_uploader_file.php            check_file_name_format      = Check the formatting of the file name before uploading
php/uber_uploader_file.php            check_null_file_count       = Make sure the user selected at least 1 file to upload
php/uber_uploader_file.php            check_duplicate_file_count  = Make sure the user did not select duplicate file uploads
php/uber_uploader_file.php            imbedded_progress_bar       = Display the progress bar inline or a pop-up (Opera is always pop-up)
php/uber_uploader_file.php            max_upload_slots            = Maximum upload slots the user is allowed to create


(*) Decreasing this value will result in a smoother 'non-cedric' progress bar, however it will increase the load on the server.
(*) Decreasing this value will result in a more accurate 'cedric' progress bar, however it will increase the load on the server.
(@) Cedric progress bar is smoother but less accurate than a non-cedric progress bar. If progress bar accuracy is paramount, switch to non-cedric progress bar. 
(+) Not Used! You must edit line 206 in uber_uploader.pl to use this feature.
(x) Not Used! If you use this feature, make sure you turn on the 'allow_extentions' config setting as well. (see above)

##################################################################################################################################

SIMPLE INSTALLATION
-------------------
THE BEST WAY to get this script working is do a simple installation before you attempt to modify the code or use advanced features.

Step 1. Upload uber_uploader.pl to your cgi-bin directory. The path will be /var/www/cgi-bin or /usr/local/apache/cgi-bin
Step 2. Make uber_uploader.pl executable with the command chmod 755 uber_uploader.pl
Step 3. Upload uber_uploader_progress.pl to your cgi-bin directory. The path will be /var/www/cgi-bin or /usr/local/apache/cgi-bin
Step 4. Make uber_uploader_progress.pl executable with the command chmod 755 uber_uploader_progress.pl
Step 5. Upload the configs folder to your cgi-bin directory. The path will be /var/www/cgi-bin/ or /usr/local/apache/cgi-bin
Step 6. Upload the templates folder to your cgi-bin directory. The path will be /var/www/cgi-bin or /usr/local/apache/cgi-bin
Step 7. Upload uber_uploader_file.php to your webspace. The path will be /var/www/html or /usr/local/apache/htdocs
Step 8. Upload uber_uploader_get_data.php to your webspace. The path will be /var/www/html or /usr/local/apache/htdocs
Step 9. Load uber_uploader_file.php in your web browser and attempt to do a file upload


Your installation may look something like this
----------------------------------------------
/var/www/cgi-bin/uber_uploader.pl
/var/www/cgi-bin/uber_uploader_progress.pl
/var/www/cgi-bin/configs/UberUploads.pm
/var/www/cgi-bin/templates/uber_uploader_finished.tmpl
/var/www/cgi-bin/templates/uber_uploader_progress.tmpl
/var/www/html/uber_uploader_file.php
/var/www/html/uber_uploader_get_data.php


Note
----
Uber-Uploader will attempt to make the upload and temp directory in your document root but may fail due to permissions. If this occurs, 
you will have to make the directory manually and set the proper (777) permissions. 

The path to the CGI scripts are assumed to be '/cgi-bin/uber_uploader.pl' and '/cgi-bin/uber_uploader_progress.pl'. If this is not the 
case, you must change the '$path_to_upload_script' and '$path_to_progress_script' values in uber_uploader_file.php.

Checklist
---------
1. Make sure you set the proper permissions for uber_uploader.pl and uber_uploader_uploader_progress.pl with the command  (chmod 755 uber_uploader.pl)
2. Make sure the path to perl is correct in uber_uploader.pl and uber_uploader_uploader_progress.pl with the command (which perl)
3. Make sure you have rwx-rwx-rwx (777) permissions on the upload and temp directories.
4. Make sure the the '$path_to_upload_script' and '$path_to_progress_script' values in uber_uploader_file.php are correct.
5. Make sure you have rwx-r-x-r-x (755) permissions on the config and template directories.

####################################################################################################################################

SIMPLE INSTALLATION + REDIRECT TO PHP PAGE
------------------------------------------
Follow steps 1 to 8 of the simple installation.

Step 9. Upload uber_uploader_finished.php to your webspace. The path will be /var/www/html or /usr/local/apache/htdocs
Step 10. Change the value of $redirect_after_upload in UberUploads.pm from 0 to 1
Step 11. Change the value of $redirect_url in UberUploads.pm to the correct path (eg. $redirect_url="http://www.yoursite.com/uber_uploader_finished.php";) 
Step 12. Load uber_uploader_file.php in your web browser and attempt to do a file upload

Your installation may look something like this
----------------------------------------------
/var/www/cgi-bin/uber_uploader.pl
/var/www/cgi-bin/uber_uploader_progress.pl
/var/www/cgi-bin/configs/UberUploads.pm
/var/www/cgi-bin/templates/uber_uploader_finished.tmpl
/var/www/cgi-bin/templates/uber_uploader_progress.tmpl
/var/www/html/uber_uploader_file.php
/var/www/html/uber_uploader_get_data.php
/var/www/html/uber_uploader_finished.php

####################################################################################################################################

INSTALLING MULTIPLE CONFIG FILES
--------------------------------
As of release 3.0, Uber-Uploader supports multiple config files. This is a useful feature if you have several users who require to upload 
to several different locations. The file upload page can be coded to load different config files depending on what user loaded the page
or what kind of upload the user is submitting. For example, lets say we have one user but they would like to upload images, word  
documents and spread sheets into different locations. In this case we need 3 more config files and a file upload page that will allow 
us to select a config file from a drop down. You could also load different config files based on user, you would simply put code at the 
top of the file upload page that would load a config based on user id. eg.

if($user == "Tom"){ $config_file = 'TomUploads'; }
elseif($user == "Sally"){ $config_file = 'SallyUploads'; }
elseif($user == "Harry"){ $config_file = 'HarryUploads'; }
else{ $config_file = 'UberUploads'; } 

#######################################################################################################################################

INSTALLING BUBBLY PROGRESS BAR
------------------------------
Step 1. Upload progress_bar_blue.gif and progress_bar_white.gif located in /php/images/ to your images directory
Step 2. Change the css in uber_uploader_progress.tmpl 

from
.bar1 {background-color:#b3b3b3; position:relative; text-align:left; height:20px; width:400px; border:1px solid #505050;}
.bar2 {background-color:#000099; position:relative; text-align:left; height:20px; width:0%;}

to
.bar1 {background-image:url(/images/progress_bar_white.gif); border:1px solid #505050; text-align:left; width:400px; height:20px; position:relative; }
.bar2 {background-image:url(/images/progress_bar_blue.gif); text-align:left; width:0%; height:20px; position:relative;}

Step 3. Make sure the path to the images are correct

#######################################################################################################################################

CODE OPTIMIZATION
-----------------
Many people who download Uber-Uploader are not developers so it is packaged in such a way as to make it as simple as possible to install. 
However, there are certain ways that Uber-Uploader can be improved if you are a developer and you have an extra 15 minutes to spare.

1. Consolidate duplicate functions 'kak' and 'deldir' into their own module file. (Kak will need a bit of a rewrite).
2. Replace all the $ENV values in the config file with hard coded values.
3. If you are using one config file, you could simply declare the config file in the relevant perl scripts instead of passing it in the query string.
   
#######################################################################################################################################

DEBUGGING UBER-UPLOADER
-----------------------
Uber-Uploader has a debug mode that can display all your config settings in the browser. Simply set 'debug_cgi => 1', in 
the config file and load it in your browser with the debug command eg.

www.yoursite.com/cgi-bin/uber_uploader.pl?cmd=debug

or

www.yoursite.com/cgi-bin/uber_uploader.pl?cmd=debug&config_file=UberUpload

ATTENTION - Do not forget to set 'debug_cgi => 0'; when you are finished.

Another helpful debugging tool is the 'delete_param_file' config setting. If you are redirecting to the uploader_finished.php page, setting
delete_param_file => 0 will leave the .param file in the temp directory for your inspection. Finally, you can use the kak function in 
uber_uploader.pl and uber_uploader_progress.pl to dump values to the screen.

eg. &kak("The value of blarg is: " . $blarg . "<br>", 1, __LINE__);
This will print the value of blarg and exit the script.

eg. &kak("The value of blarg is: " . $blarg . "<br>", 0, __LINE__);
This will print the value of blarg and continue the script.

#######################################################################################################################################

FAILED TO FIND FLENGTH FILE
---------------------------

http://uber-uploader.sourceforge.net/?section=flength

########################################################################################################################################

HOW TO VIEW AN ACTIVE UPLOAD
----------------------------

The 'temp_dir' config setting is assumed to be /tmp/

Steps To View Active Upload
---------------------------
1.  Load uber_uploader_file.php in your web browser.
2.  Right click and 'view page source'.
3.  Look for the following line below the body tag. <!-- TMP_SID: 325d7d52d78083839d4f9ced94821695 --> (Your string will be different)
4.  Open a command line (shell) to your web server and go to the tmp directory.
5.  Start a large upload.
6.  While your files are uploading, get a listing of your tmp directory.
7.  You should now see a directory in tmp called 325d7d52d78083839d4f9ced94821695.
8.  Now get a listing of the 325d7d52d78083839d4f9ced94821695 directory.
9.  You will see a file called 'flength'. This is the file that contains the total size of the upload in bytes.
10. You will also see a file like 'CGItemp3984'. This is a file being uploaded. It will change in size as the file is uploaded.
11. If there is more than one upload, there will be multiple CGItemp files.

So with 3 active file uploads, the file structure will look something like this.
 
/tmp/325d7d52d78083839d4f9ced94821695/flength
/tmp/325d7d52d78083839d4f9ced94821695/CGItemp3984
/tmp/325d7d52d78083839d4f9ced94821695/CGItemp3985
/tmp/325d7d52d78083839d4f9ced94821695/CGItemp3986

PROGRESS BAR NOTE: 

The progress bar reads the total upload size from the flength file. The progress bar then keeps reading the size of 
the /tmp/325d7d52d78083839d4f9ced94821695 directory as files are uploaded and the directory grows in size. It keeps
comparing this number to the one it got from the flength file. That is how the progress bar knows how much information
has been uploaded. 

######################################################################################################################################

HOW DO I TELL IF PERL IS WORKING
--------------------------------

Simply call uber_uploader.pl with the version command.

(eg. www.yoursite.com/cgi-bin/uber_uploader.pl?cmd=version )

You should see version information on the screen. If you do not

1. uber_uploader.pl is not set to executable (chmod 755 uber_uploader.pl)
2. The path to perl is incorrect (type   which perl   on the command line to find the path)
3. Perl is not installed (contact your Sys-admin)
4. Your cgi-bin is not set up correctly (contact your Sys-admin)

######################################################################################################################################

HOW DO I TELL IF PHP IS WORKING
-------------------------------

Step 1. Put this in a file with a '.php' extention.    <? phpinfo(); ?>
Step 2. Upload it to your web server.
Step 3. Load the file in your browser.
 
You should see PHP version information on the screen. 
                                                                         
#######################################################################################################################################

MULTI SIMULTANEOUS UPLOADS
--------------------------

Uber-Uploader is capable of performing multi simultaneous uploads if your web browser is configured properly. Uber-Uploader requires
two connections per upload. One connection is required for the upload and one connection is required for the progress bar. By default
IE and Firefox ships with the ability to make several simultaneous connections. However, you can increase the the amount of
simultaneous connections by changing the following values. Just 'Google' for instructions on changing these values.

IE
--
MaxConnectionsPer1_oserver
MaxConnectionsPerServer

Firfox
------
network.http.max-connections
network.http.max-connections-per-server
network.http.max-persistent-connections-per-server

#######################################################################################################################################

HOW UBER UPLOADER WORKS - The 'temp_dir' config setting is assumed to be /tmp/
-----------------------
1. User loads the file upload page which generates unique 32 character string (SID).
2. User select files and posts SID # to uber_uploader.pl and uber_uploader_progress.pl simultaneously.
3. Upload script creates a SID based directory inside the temp directory.
4. Upload script writes total upload size to a file called flength to the SID based directory.
5. Upload script starts uploading files to the SID based directory.
6. Progress script reads the flength file in the SID based directory.
7. Progress script keeps calling the "get data script" for the status of the SID based directory and produces a progress bar.
8. Upload script finishes and transfers the files from the SID based directory to the upload directory.
9. Upload script outputs results or redirects to "php finished page". 


                                                   |------------------------------------------------------|
                                                   | uber_uploader.pl                                     |
        Post Files and SID # To Upload Script      |                                                      |  Upload Finished Redirect ?
   |------325d7d52d78083839d4f9ced94821695------->>|Upload script creates dir in tmp dir based on SID #   |--325d7d52d78083839d4f9ced94821695--->>
   |                                               |Upload script writes the total upload size to flength |
   |                                               |Upload script starts uploading files                  |
   |                                               |------------------------------------------------------|
   |                                                                     |
   |                                                                     |
|----------------------------------|                                     x
| uber_uploader_file.php           |               |------------------------------------------------------|
|                                  |               | /tmp/325d7d52d78083839d4f9ced94821695/flength        |
| File upload page generates SID # |               | /tmp/325d7d52d78083839d4f9ced94821695/CGItemp3984    |
| 325d7d52d78083839d4f9ced94821695 |               |------------------------------------------------------|
|----------------------------------|                                     x
   |                                                                     |
   |                                                                     |
   |                                               |------------------------------------------------------|
   |                                               | uber_uploader_get_data.php                           |
   |                                               |                                                      |
   |                                               | Get data script reads the size of the SID based dir  |
   |                                               | Get data scripts outputs formatted read result       |
   |                                               |------------------------------------------------------|
   |                                                             x                |
   |                                                             |                |
   |                                                             |                x
   |                                               |------------------------------------------------------|
   |                                               | uber_uploader_progress.pl                            |
   |                                               |                                                      |
   |-----325d7d52d78083839d4f9ced94821695-------->>| Progress bar reads flength file.                     |
          Post SID # To Progress Script            | Progress bar keeps calling uber_uploader_get_data.php|
                                                   | for the upload status.                               |
                                                   |------------------------------------------------------|