FileChucker

Frequently Asked Questions


How do I customize FileChucker?
How do I embed FileChucker in another page, or within my site's existing layout?

I get an Internal Server Error after I edit filechucker.cgi!
I get an error when I try to call FileChucker from PHP using virtual().
I get an error in the middle of my upload.
FileChucker's upload progress bar doesn't work.
FileChucker won't thumbnail a certain image file; or, FileChucker's file-list page gets cut off partway through the list.

What's the biggest file that FileChucker can upload?
How fast can FileChucker upload files?

How do I enable the image features (thumbnails, rotation...)?
How do I add my own fields / text boxes to the upload form?
How do I enable email notifications, or fix email-sending errors?
How do I add an email field and send a notification email to the entered address?
How do I make my form fields appear in the notification email?
How do I use one FileChucker for multiple forms/pages on my site?
How can I hide or password-protect certain features?
How do I give each of my users their own private uploads folder?
FileChucker (sometimes) says I'm not logged in, when I really am!
How do I ...

 

How do I customize FileChucker?

Just edit filechucker_prefs.cgi in a text editor; it contains many adjustable settings.  You'll probably want to adjust $PREF{title} and $PREF{intro} in PREFs Section 07, for example.

To customize the styling (look and feel), just add your own CSS to the $PREF{custom_css_section} setting in PREFs Section 07 (older/trial versions) or $PREF{css} in PREFs Section 16 (newer versions).  To include an external CSS file, use a CSS @import statement:

$PREF{css} = qq`

\@import url("/mystylesheet.css");

[rest of FileChucker's CSS here]

`;

Notice that the @-symbol on the @import statement must be escaped with a backslash, otherwise Perl will treat it as a variable, which will result in an error.

[ Top – FileChucker Homepage – Instructions – Download – Purchase ]

 

How do I embed FileChucker in another page, or within my site's existing layout?

Embedding Method A: call filechucker.cgi from your PHP or SSI/shtml page:

  1. Within the <head> section of the PHP or SSI/shtml page where you want to embed FileChucker, add the following lines:

    <script type="text/javascript" src="/cgi-bin/filechucker.cgi?js"></script>

    <link rel="stylesheet" type="text/css" media="all" href="/cgi-bin/filechucker.cgi?css" />
  2. If your page is a PHP page, then add the following line to it wherever you want FileChucker's output to appear:

    <?PHP virtual("/cgi-bin/filechucker.cgi?" . $_SERVER['QUERY_STRING']); ?>


    Or, if your page is a plain HTML page with an extension of .htm or .html, rename its extension to .shtml and then add the following line to it wherever you want FileChucker's output to appear:

    <!--#include virtual="/cgi-bin/filechucker.cgi?$QUERY_STRING" -->
  3. In your filechucker_prefs.cgi file, set $PREF{print_full_html_tags} = 'no'.  Then set $PREF{here} = '/mypage.php' or '/mypage.shtml' where 'mypage' is the name of the page where you've embedded it.

    Now visit www.yoursite.com/mypage.php (or shtml) and you'll see FileChucker in the page.

    See step #5 of the installation instructions for more details on calling FileChucker from another page.

Embedding Method B: call filechucker.cgi directly, and let it display your HTML template file:

If your server doesn't support the PHP/SSI/shtml that's necessary for Embedding Method A (above), then you can use an HTML template file instead.  Your page will look exactly the same as with Method A; the difference is that Method B requires you to use the full URL to the CGI script itself, since your server doesn't support any other way.

First you create an HTML file in whatever way you normally create web pages.  Name this file encodable_app_template.html.  In the <head> section of this file, put the strings %%css%% and %%js%% each on their own line.  Then in the <body> section of the file, wherever you want FileChucker's output to go, put the string %%encodable_app_output%%.  Now upload this HTML file onto your website in its top level (i.e. not in a subfolder).

Now open your filechucker_prefs.cgi file and find the $PREF{print_full_html_tags} setting and set it to "no".  Near there, you'll also find the $PREF{encodable_app_template_file} setting; set that to "%PREF{DOCROOT}/encodable_app_template.html"; 

Now visit www.yoursite.com/cgi-bin/filechucker.cgi and it'll use your template file.

[ Top – FileChucker Homepage – Instructions – Download – Purchase ]

 

I get an Internal Server Error after I edit filechucker.cgi!

The simple solution is: don't change filechucker.cgi at all.  Instead, only edit filechucker_prefs.cgi, as explained above.

The long answer is that many text editors mess up the line-endings in text files in ways that don't show up within the editor itself, so you don't notice them until you try to execute the file as a script on a server that requires proper line endings.  Editors that are known to mess up the line endings are Word, Notepad, GoLive, Dreamweaver, etc.; one editor that's known to handle the line endings properly is WordPad.  So if you must edit filechucker.cgi, first make a backup copy of it, and then try using WordPad.  Of course, if you run Linux or Mac OS X, most editors will handle the line endings properly; it's Windows that messes everything up, as usual.

[ Top – FileChucker Homepage – Instructions – Download – Purchase ]

 

I get an error when I try to call FileChucker from PHP using virtual().

If you get an error saying "call to undefined function virtual()" then that means your server doesn't support PHP's virtual() function.  That's OK; you just need to try one of the other methods for calling FileChucker, as explained in step #5 of the instructions.

[ Top – FileChucker Homepage – Instructions – Download – Purchase ]

 

I get an error in the middle of my upload.

If, during an upload, you get an error like "server cannot be found", "page cannot be displayed", "connection was reset", or "connection timed out", this is not a problem within FileChucker; rather, it's either a problem with your network connection, a problem with the server's network connection, or a problem within the server itself.

In some cases (usually only on IIS/Windows servers) these may be caused by the server's setting for CGI execution timeout.  In no case is this caused by PHP settings (php.ini, etc), because FileChucker is not written in PHP and therefore is not affected nor limited by PHP settings.

In any case, these problems are all beyond FileChucker's control, and you'll need to ask your hosting company for support with them.  It may be helpful to do a few test uploads from different computers on different internet connections to help pinpoint the source of the problem.

Though not a guaranteed fix, one thing that may help in some situations is to set the $PREF{disable_upload_hook} setting to 'yes'.  This slightly changes how FileChucker processes the upload internally, and as a side-effect it can sometimes work around certain server issues.

[ Top – FileChucker Homepage – Instructions – Download – Purchase ]

 

FileChucker's upload progress bar doesn't work.

FileChucker has been installed on thousands of websites, and its progress bar works properly on the vast majority of them: on both dedicated and shared servers, on Windows, Linux, Mac OS X, IIS, and Apache servers, and virtually every major hosting company around.  On a small percentage of servers, there are Apache filters that interfere with the real-time status information necessary to have a real-time progress bar, and on most of those servers, the problem can be fixed by putting the following lines in the /cgi-bin/.htaccess file:

<IfModule mod_security.c>
# Turn off mod_security filtering.
SecFilterEngine Off

# The below probably isn't needed,
# but better safe than sorry.
SecFilterScanPOST Off
</IfModule>

However, on perhaps 1 or 2 percent of servers, those lines don't fix the problem.  Servers in this tiny minority seem to be doing some kind of write-caching which causes the uploaded file to not really get written to disk until after the whole thing is already uploaded, which makes it impossible for FileChucker to monitor the progress of the upload, and therefore impossible to display a progress bar.

FileChucker isn't doing anything unusual when it uploads files: it uses the standard facilities provided by the CGI.pm module, which is a standard Perl module.  However, FileChucker can also bypass this module and do the upload in a more manual sort of way, by setting $PREF{disable_upload_hook}='yes' in PREFs Section Z in the /cgi-bin/filechucker_prefs.cgi file.  Still, on some servers, neither the standard way nor the manual workaround result in a properly-working progress bar.

If this is the case on your server, you'll need to contact your hosting company, point them to this explanation, and ask if there's anything that they can do.  They can try out the FileChucker demo on this server to see how the progress bar is supposed to work.

[ Top – FileChucker Homepage – Instructions – Download – Purchase ]

 

FileChucker won't thumbnail a certain image file; or, FileChucker's file-list page gets cut off partway through the list.

This is usually caused by an image file that is partially corrupt.  Image corruption is a matter of degree, and depending on exactly what the corruption is, some apps will be able to ignore or work around it, while others won't.

You can usually fix the image by opening it in an image editor and then re-saving it.

In the case of the file-list page's output being truncated, you'll need to determine exactly which file is causing the problem.  To do that, first take note of the name of the last (bottom-most) file that FileChucker displays successfully.  Then, you can either use the Options Menu to turn off the thumbnails and see which file comes next, or you can log into your server via FTP and see which file comes next.

[ Top – FileChucker Homepage – Instructions – Download – Purchase ]

 

What's the biggest file that FileChucker can upload?

FileChucker itself has no limit, other than the $PREF{sizelimit*} settings which you set yourself.  But your server may have other limits, either directly in terms of file size, or indirectly in terms of CPU, RAM, or network limits or issues that cause large uploads to fail.

In general, most servers do not have upload size limits for CGI scripts as they do for PHP scripts; such PHP limits have no effect on FileChucker.  Many clients are using FileChucker specifically for the purpose of uploading large files of several hundred megabytes, and even into the 1-2 gigabyte range in some cases.

If large uploads are failing on your server, one thing that may help in some situations is to set the $PREF{disable_upload_hook} setting to 'yes'.  This slightly changes how FileChucker processes the upload internally, and as a side-effect it can sometimes work around certain server issues.

The only currently known hard limits are:

  • For Apache servers: Apache 1.x, 2.0, and 2.1 cannot accept uploads larger than 2 GB; for that, you must use Apache 2.2.
  • Most (possibly all) 32-bit web browsers cannot upload more than 2 GB.  In our testing, they simply won't respond at all when you hit the "Begin Upload" button with a file larger than 2 GB selected.  In order to upload more than 2 GB at once, you'll need to be running a 64-bit browser, which means you need to be running a 64-bit operating system, which naturally means you must be running 64-bit hardware.

[ Top – FileChucker Homepage – Instructions – Download – Purchase ]

 

How fast can FileChucker upload files?

FileChucker has no built-in speed limit; it automatically sends data as fast as the network connection will accept it.  The only exception is if your server is running an extremely old version of Perl, or if you've manually set the $PREF{disable_upload_hook} setting to 'yes', in which case there is a delay that you can control via the $PREF{sleep_time_during_nonhook_uploads} setting.

In practice, the limiting factor in most uploads will be the upstream speed limit on the visitor's internet connection.  Most residential internet connections have upload speeds that are only one-tenth or one-twentieth as fast as their download speeds.  As of 2008 in the US, upload speeds are often limited to as little as 32-128 KByte/s (which is 256-1024 kbit/s), even for "broadband" connections.

The server's internet connection is also a factor, but in most cases servers have very fast connections, far faster than the upload speed on the visitor's internet connection.

[ Top – FileChucker Homepage – Instructions – Download – Purchase ]

 

How do I enable the image features (thumbnails, rotation...)?

First, you need to have at least ImageMagick or GD installed on your server.  Then you need to try enabling the various $PREF{try_to_use_*} settings in PREFs Section 15.

If you have ImageMagick installed, then perhaps the easiest way to get FileChucker's image features working is via $PREF{try_to_use_convert_for_rotation} and $PREF{try_to_use_convert_for_resizing}.  Enable those, and that might be all it takes.  Or, you might need to specify the full path to the "convert" command on your server, via the $PREF{convert_command} setting.  If you're running a Windows server, you may run into a problem because Windows includes a built-in convert command which is a disk utility.  So you'll either need to specify the full path to the convert.exe that's within the ImageMagick Program Files folder, or else rename that convert.exe to something else like imgconv.exe, then set $PREF{convert_command} = 'imgconv.exe'.

If you can't get the image features to work using ImageMagick's convert command, then you can try the more traditional method of using either the ImageMagick Perl module or the GD Perl module.  These Perl modules must be explicitly installed on your server; they are NOT automatically installed just because you have ImageMagick itself or GD itself installed.  They are also unrelated to whether you have ImageMagick or GD support in your PHP installation; FileChucker is not a PHP application so anything loaded into PHP is irrelevant.  If you think that you have these Perl modules installed -- or your web host / server admin tells you that they are -- but FileChucker tells you that they aren't, then that means they really aren't.  FileChucker gets its information directly from Perl itself, and if Perl tells FileChucker that the module is not installed, then it's not installed.  The most common sources of confusion here are 1) incorrectly assuming that you automatically have the IM or GD Perl module just because you have IM or GD itself installed, and 2) having multiple Perl installations on the server and having some modules installed under one version of Perl but the script accessing the other, in which case you need to get your Perl situation straightened out and then direct FileChucker to use the correct one (by adjusting the first line in the script).

[ Top – FileChucker Homepage – Instructions – Download – Purchase ]

 

How do I add my own fields / text boxes to the upload form?

Use the $PREF{formfield_NN} options in PREFs Section 07.  For example: 

$PREF{formfield_01}		= 'Company Name:';
$PREF{formfield_01_shortname}	= 'company_name';

[ Top – FileChucker Homepage – Instructions – Download – Purchase ]

 

How do I enable email notifications, or fix email-sending errors?

For multiple Encodable web applications including UserBase and FileChucker, emails can be sent from the script via either SMTP or sendmail.  The main settings are $PREF{smtp_server} and $PREF{path_to_sendmail}; these are in PREFs Section 06 in FileChucker.

The default configuration is to use SMTP with the server set to "localhost" because that works on most servers.  However, you may need to change that to the address of the SMTP server provided by your hosting company, or the address of the SMTP server provided by your ISP.

If your SMTP server requires authentication, which it might if you get "relay" errors, then you'll also need to set the SMTP auth preferences.  You'll need to specify the username and password for an email account on the server in question.  On some servers, this requires installing an updated version of the MIME::Lite Perl module.  MIME::Lite version 3.01_05 is known to handle SMTP auth correctly, and you can download this version from here.  Download and unzip that file, then go into the directory lib/MIME/ and you'll see a file called Lite.pm.  On your server, create the directory cgi-bin/perlmodules/MIME/ and upload the Lite.pm file into it.  This fixes SMTP auth issues on many servers.

If you can't get SMTP-based email to work, then set the SMTP server to null ('') which will cause the script to try to use sendmail instead.  Most Linux servers have sendmail available so this method "just works" on many servers.

With newer versions of the applications, you can make it easier to debug email issues by adding the following lines to your prefs file: 

$PREF{enable_email_test}	= 'yes';
$PREF{email_test_recipient}	= 'you@wherever.com';
$PREF{email_test_sender}	= 'you@wherever.com';

Then open your browser and visit your installation of the application, and add "?do_email_test" on the end of the URL -- for example www.yoursite.com/cgi-bin/filechucker.cgi?do_email_test.  This will cause the script to send an email using your current email settings, and it'll include those settings in the email, so if and when you manage to get an email to go through, you'll be able to see which settings worked.  For the email_test_recipient and sender addresses, you should use a known-good email account, like your personal email address.

Finally, in some cases you may need to check your spam folder, in case your email system uses overly-aggressive spam filtering which causes good emails to be flagged.

[ Top – FileChucker Homepage – Instructions – Download – Purchase ]

 

How do I add an email field and send a notification email to the entered address?

First enable email notifications in PREFs Section 06, then add a set of $PREF{formfield_NN} options in PREFs Section 07 like this: 

$PREF{formfield_01}		= 'Email address:';
$PREF{formfield_01_shortname}	= 'email_address';
$PREF{formfield_01_email}	= 'yes';

[ Top – FileChucker Homepage – Instructions – Download – Purchase ]

 

How do I make my form fields appear in the notification email?

The form fields that you added are in PREFs Section 07, and each one of them has a _shortname, for example you might have: 

$PREF{formfield_01}		= 'Company:';
$PREF{formfield_01_shortname}	= 'company_name';

What you need to do is add those shortnames as variables to the email template, which is in PREFs Section 06, named $PREF{webmaster_notification_email_template} (or $PREF{user_notification_email_template}).  So for the company_name field, you'd add the variable %%company_name%% to that template.

However, if the form field in question is a per-file form field -- that is, if you've set $PREF{formfield_NN_position} = 'perfile' for it -- then you need to add the %%company_name%% variable to the filelist template instead, which is named $PREF{webmaster_notification_email_filelist_template} (or $PREF{user_notification_email_filelist_template}).

[ Top – FileChucker Homepage – Instructions – Download – Purchase ]

 

How do I use one FileChucker for multiple forms/pages on my site?

There are two ways to do this.  The first way is to simply create a second copy of your filechucker.cgi and filechucker_prefs.cgi files.  You can name the copied files whatever you'd like as long as the prefs file matches the main script, for example you could name them "fc2.cgi" and "fc2_prefs.cgi".

The second way would be to use the $PREF{other_prefs_files} settings in PREFs Section Z of your filechucker_prefs.cgi file.  This method uses a single filechucker.cgi file with multiple prefs files.  See the documentation with the $PREF{other_prefs_files} settings for the full instructions.

[ Top – FileChucker Homepage – Instructions – Download – Purchase ]

 

How can I hide or password-protect certain features?

By default there is no password.  To create a password, you must generate a new hash for it, by going to http://yoursite.com/cgi-bin/filechucker.cgi?newpw and entering your new password.  Then take the resulting hash and enter it into one of the $PREF{admin_password_hash} or $PREF{member_password_hash} settings in PREFs Section 03.

By default most features are public; to change that, go to PREFs Section 03 and find the list of groups_allowed_to PREFs: 

$PREF{groups_allowed_to_upload}		= 'public';
$PREF{groups_allowed_to_list_files}	= 'public';
$PREF{groups_allowed_to_delete_items}	= 'public';
...

Simply change the feature in question from 'public' to 'member' or 'admin'.

[ Top – FileChucker Homepage – Instructions – Download – Purchase ]

 

How do I give each of my users their own private uploads folder?

FileChucker itself does not handle usernames, so you'll need a login application like our UserBase login system for this.  UserBase allows you to create individual user accounts for each of your users, and then FileChucker can integrate with UserBase to support those accounts.  So install UserBase, then in FileChucker you'll want to set $PREF{integrate_with_userbase} in PREFs Section 03 and $PREF{enable_userdirs} in PREFs Section 04.

[ Top – FileChucker Homepage – Instructions – Download – Purchase ]

 

FileChucker (sometimes) says I'm not logged in, when I really am!

When this happens, it's often in response to having clicked on a link within a notification email.  It's usually caused by the URL either having, or not having, the "www." in front of your domain name.  Try adding or removing the "www." and see if that fixes things.

The root cause of this problem is the way that web browsers handle cookies.  A cookie set by http://yoursite.com/ cannot be read by http://www.yoursite.com/ and vice-versa, because technically those are different domains for security purposes.  There's no way for an application like FileChucker to override this security setting and read the other domain's cookies.

Instead, to fix the problem, you need to configure your website itself to pick one form and stick to it: either always use http://yoursite.com/ without the "www.", or else always use http://www.yoursite.com/ with the "www."  Then if someone visits the "wrong" one, the website will automatically and transparently send the visitor to the "right" one.  To do this, check with your hosting company's control panel; Dreamhost for example has a simple setting for this that you can toggle.  If your hosting company doesn't, and your website runs Apache, then you can add a few lines to your main .htaccess file to make it happen: 

# Use this to automatically redirect www.you.com to just you.com:
#
RewriteEngine On
RewriteCond %{HTTP_HOST}   ^www\.you\.com [NC]
RewriteRule (.*)           http://you.com/$1 [L,R]

# Or, use this to automatically redirect you.com to www.you.com:
#
RewriteEngine On
RewriteCond %{HTTP_HOST}   ^you\.com [NC]
RewriteRule (.*)           http://www.you.com/$1 [L,R]

If you use this code, you don't need to go back into your individual pages and update your links to add/remove the "www." on each one.  The .htaccess code will automatically do that for you, whenever someone visits the wrong domain.  And it will keep the rest of the request intact, so even if the link is a long URL to some page deep within your site, that's no problem: it'll just add or remove the "www." and leave the rest of the URL unchanged.

[ Top – FileChucker Homepage – Instructions – Download – Purchase ]

 

How do I ...

Here are the prefs & sections for some of the most commonly-asked configuration questions.  Just find the appropriate section/pref in your filechucker_prefs.cgi file and then change its setting.

To make FileChucker use your shortcut URL (mysite.com/upload/):

# PREFs Section 02: Paths and Directories.
#
$PREF{here}				= '/upload/';

To hide the path to your uploads directory:

# PREFs Section 03: Security.
#
$PREF{hide_path_to_uploads_dir}		= 'yes';

To disable the form fields that allow the user to choose/create a subdirectory for their uploaded file:

# PREFs Section 05: Subdirectories.
#
$PREF{display_dropdown_box_for_subdir_selection}	= 'no';
$PREF{enable_manual_creation_of_new_subdirs_during_upload}= 'no';

To change the text appearing at the top of the page:

# PREFs Section 07: Upload Form Configuration.
#
$PREF{title} = '<div id="title">FileChucker</div>';
$PREF{intro} = qq`<p style="text-align: center;">Upload some files!</p>`;

To change the max/default number of files to be uploaded:

# PREFs Section 08: Upload Restrictions.
#
$PREF{max_files_allowed}		= 5;
$PREF{num_default_file_elements}	= 1;

To change the limit on how big an upload can be:

# PREFs Section 08: Upload Restrictions.
# Note: 1024*1024*30 is 30 MB, 1024*1024*50 is 50 MB, etc.
#
$PREF{sizelimit_for_strangers}		= 1024*1024*30;
$PREF{sizelimit_for_members}		= 1024*1024*50;
$PREF{sizelimit_for_admins}		= 1024*1024*80;

To limit the kinds of files that can be uploaded/displayed:

# PREFs Section 08: Upload Restrictions.
#
$PREF{only_allow_these_file_extensions}		= '';
$PREF{disallow_these_file_extensions}		= '.exe .php .cgi';
$PREF{allow_files_without_extensions}		= 'yes';
$PREF{disallow_these_strings_within_filenames}	= '\.exe \.php, \.cgi';

To send the upload information to another page after upload is complete:

# PREFs Section 10: Post-Upload.
#
$PREF{after_upload_redirect_to}		= 'http://mysite.com/mypage.php';
$PREF{pass_original_querystring_through}= 'yes';
$PREF{pass_filenames_on_redirect}	= 'yes';
$PREF{pass_formfield_values_on_redirect}= 'yes';

[ Top – FileChucker Homepage – Instructions – Download – Purchase ]