HTMLfixIT.com Downloader and Download Counter Installation file. Ver: 0.9. ---------------------------------------------------- In this document: - Summary. - Benefits/Features. - Possible downsides. - Requirements. - File and directory structure. - Installation instructions. - The script doesn't work, what do I do. - Notes for windows servers. - Notes for mod_perl servers. - To Do. Summary ------- After looking around for a good download counter script for our site, and only finding a few that were generally insecure and/or poorly coded, we decided to bite the bullet and write one ourselves. You are looking at the result. It performs several functions: 1. It acts as a counter while downloading files. You simply pass it the name of the file to download, for example: dl.pl?id=somefile.zip and it will increment a counter file and then download the file for the person requesting it. 2. It displays the number of downloads reflected in the download counter mentioned above via Server Side or PHP includes into your actual pages. 3. It comes with a password protected administrative interface (a web page display) where you can see (and reset) the various counts for all your downloadable files. This one script can be used to count and manage multiple files (unlimited number) offered for download on your site. Benefits/Features of this script over other downloaders. -------------------------------------------------------- - The main benefit this script has over some similiar offerings is that it was written with security in mind. It runs in taint mode (look for the -T in the first line of the script) and produces no errors in strict mode with warnings and diagnostics. - It is also very easy to setup and use. It has only a few installation parameters: so its easy to setup. Also, all the configuration settings are in their own file so its easy to upgade to newer versions. - Once set up, you can utilize it for additional files simply by coding your download links correctly in your html page, the script does not require any configuration to add new file counts. - The administrative interface gives you a very tidy display of all the files you have available for download and the number of times each has been downloaded. - Completely modular in design as each section of the script has its own package namespace and all subroutines are passed all parameters they use expicitly, meaning that the code is clean and can run under mod_perl perfectly. (and a good deal faster) - Library, all the reusable code in this application is in a seperate library file. (htmlfixit-lib.pl), and the same library is used in all other htmlfixit.com perl scripts meaning you will get a uniform look and function when using all of our scripts. The library is also well suited for coding your own web scripts. The Possible Downsides. ----------------------- Because it runs in taint mode, your file name offered for download must match a regular expression (regex) which checks the file name to be sure it is valid. Most people will have no difficulty with this as we care- fully crafted the regex which checks this. In short any filename containing underscores, dashes, full stops/periods and alphanumeric characters is acceptable. Some examples of acceptable file names are: downloader-0.7.tar.gz phpinfo.zip stats-counter-0.91.tar.gz filename_break.zip Requirements ------------ - Perl, version 5.03 + (Perl 5.6 or above is preferable.) - CGI module, (standard on all modern Perl installations). - CGI::Cookie, (also standard on modern Perl installations.) - SSI (Server Side Includes) for the file count display (NOTE: SSI is not required to use the counter, only to display the results in-line on your web page unless you have PHP pages, in which case you can use the PHP include, which is much faster then SSI. if you don't want the counts displayed on your page, you need not use either and can just login to the administrative interface to view your file download counts.) - A decent text editor like TextPad or NoteTab. - FTP client. - Coffee. -------------------------------------------------------------------- File and directory structure of the zip and tar files. ----------------------------- The zip or tar files contain files and directories in this layout: |---- dl_counts (empty directory that will contain download count files) | | | | |---- dl.pl (main script file, (basically just runs download.pl)) |---- downloader -----| | (directory) | | |---- htmlfixit-lib.pl (Library file) downloader | | | |---- download.pl (main code file) | | | |---- downloader_config.pl (script configuration file.) | | |---- downloads.php (Optional file to display file counts in php pages.) | (file) | |---- downloader-readme.txt (This file.) Installation instructions. -------------------------- Step 1. Download either the tarball or the zip file from the http://HTMLfixIT.com/free.php site (which uses this very download script to count your download). Step 2. Unzip/untar it in Winzip or whatever extraction tool you use, and save the contents somewhere handy (a new empty directory would be best). You should have the above files and directory structure stated above when you are done: Step 3. Open the downloader_config.pl file in your favorite text editor. (do you and me a favour and download textpad http://textpad.com or notetab http://notetab.com and use one of those editors because notepad will cause problems. Each offers a freeware or shareware version.) Step 4. The config file is well commented to help you in filling in the various configurations. Pay particular attention to the $counterfiledir setting and also the $download_url. For the script to work at all, it MUST have both these settings correct. A more thorough explanation of the two main settings: my $counterfiledir= '/home/httpd/htmlfixit/counter/downloadcounter/'; (Make sure the path ends with the / as in the example above.) If this is not an existing folder on the server, you will be instructed on how to set it up in Step 5. my $download_url = 'http://mydomain.com/downloads/'; and replace http://mydomain.com/downloads/ with the URL (web address) of the directory on the server containing the files you are offering for download. (Again, make sure the URL ends in a / like the example above.) Other settings in this file are the username and password for the administrative interface and the settings for the cookie. All of these are intended to be self explanitory. Step 5. OK, the fun part, fire up your trusty FTP client. (SmartFTP, http://smartftp.com, is a good freebee if you don't have one.) Connect to your hosting provider and move to the web directory root, (where your html pages would be.) Right click in the remote panel, and select "new folder" and call it dl_counts or whatever you like. This should be the directory that you put in $counterfiledir in Step 4. This will be where the downloader script will store its count files. Right click on the new directory and select "Permissions" or "properties" or "chmod" or whatever your FTP client calls permissions. Set this directory to 777, (755 would be better, but it depends on your setup if you can do that, so first set it to 777 and when the script is working correctly, try moving it back to 755 to see if it will work correctly. Note: never set a file to 777, only the directory folder.) If you cannot set permissions numerically, you would use this information to set the check boxes correctly: (777: owner: read/write/execute, group: read/write/execute, others: read/write/execute.) (755: owner: read/write/execute, group: read/execute, others: read/execute.) Step 6. Upload the entire downloader directory into your cgi-bin directory. BE SURE you are uploading it in ASCII not BINARY mode, (check the help file of the FTP client for details on this.) Once uploaded, then highlight and right click on the files within and chose 'permissions' or 'chmod', or 'properties' as above and set this file to chmod 755. (Again 755 represents this, owner: all rights, group: read/execute, others: read/execute. NOTE: do NOT set these to 777!) (Set the permissions on the actual downloader directory to 755 as well.) Step 7. Ensure that the files you will be offering for download are in whatever location you entered in: $download_url in Step 4. Step 8. Open the web page where you will be listing your offered downloads using your text editor or other html editor. For each file you wish to offer as a download, you should create an entry like this: Download my file Of course you should edit the file name and link text to suit. Step 9 (only relevant if your pages use SSI to display the count totals.) If you don't plan to use the SSI count number display, just upload your file to the host again. Otherwise, to display the download count for each file, you need to add some html to the page where you want the count to appear, like so: My file has been downloaded: times. Again the path and filename should be edited to suit. Upload the html file to your site with the link included (Step 9) and the SSI (Step 10) if that is desired. Step 10. (only relevant if your pages are PHP instead of SSI.) Upload the downloads.php file into the same directory as the rest of your php files. In your pages where you want to display a file count, insert this code: My file has been downloaded: times. Replace my_file.tar.gz with the name of the file you wish to display download counts for. Congratulations! You are all done setting up your download counter. If you now go to your html page where the download link was placed, and click on the download button, you should successfully be prompted to save the file. As you download, the counter should have been incremented to one. After you have downloaded the file, if you use the SSI or PHP display, then click refresh in your browser, and you should see the download counter display incremented by 1. Now open your browser and enter this address, (edited to suit of course.) http://mydomain.com/cgi-bin/downloader/dl.pl?login=yes (Do NOT forget or leave off the ?login=yes off the end or this won't work.) You should be presented with a login page. Enter the username and password you used when you edited downloader_config.pl and click the "click to enter" button. If all went well you will see the counts of every file you have setup as a download. NOTE: A download count will not appear until after the file has been downloaded at least once, the reason for that is simple, the count file for that that download won't actually exist until the first time the file is downloaded. It will never say downloaded zero times. In the admin screen, each file has a [reset] option, clicking that will delete the count file for that download and it won't appear again until that download is used again. (and it will re-appear with the count set back to 1) Thats it!!! Enjoy. The script doesn't work, what do I do. -------------------------------------- - Check your file and directory permissions. Improper permissions are one of the most common cause of errors. - Be sure you uploaded the files in ASCII mode. If you used binary mode by mistake you will need to upload them again. - Be sure you didn't edit the files in windows notepad which will result in windows control characters having been inserted automatically all through the perl script. This will ALWAYS give an error on unix systems. - Make sure that the parameters you entered in the configuration section are exactly correct, because even one character out of place will ruin the whole experiance. - Check the server's web error log. If you can't find it in your host home directory, ask your host how you can access it. - Ask a question on the htmlfixit.com forum, being as detailed as possible. Be sure to include the web page address which contains your link and the name of the file you are offering for download. It will also help us to know if you have any other perl programs successfully running on your site as that will help us rule out some problems from the get go. http://htmlfixit.com/cgi-bin/yabb/YaBB.cgi - Pop into the htmlfixit.com chatroom and ask whomever is in there about your problem. http://htmlfixit.com/cgi-bin/irc/irc.cgi - Check out this page: http://www.perl.org/troubleshooting_CGI.html it is from the guys that brought you perl in the first place. - Search google.com for "my CGI script won't run" or "server 500 error", you'll get a lot of info. Depending on your level of expertise, this may be helpful. - Verify that you have permission to run perl programs. Some servers require that the file be named with a .cgi instead of a .pl extension. Try renaming the file on the server (don't just upload it with the different name unless you repeat Step 5, - ASCII mode and set permissions to 755). - Verify that the first line of the program is correct for your server. Most configurations place Perl in the place we have specified in the first line of our script, but occasionally there are minor variations. Notes for Windows servers. ------------------------ - All file paths for configuration should be in windows format with forward slashes instead of back slashes. For example: my $counterfiledir= 'c:/Inetpub/www/counter/downloadcounter/'; - Near the top of download.pl, you will find the following two lines: my $path_to_lib = '.'; my $path_to_config = '.'; These will need to be edited to match the path to the actual directory containing the .pl files eg: my $path_to_lib = 'c:/Inetpub/Scripts/downloader'; my $path_to_config = 'c:/Inetpub/Scripts/downloader'; Windows does not handle relative directories very well, so they must be absolute. - Taint mode most be turned off. In the file dl.pl first line, change the following: change: #!/usr/bin/perl -Tw to: #!/usr/bin/perl -w - Temp directory must be set. in the downloader_config.pl file, near the bottom is the following line: my $tmp_dir = '/tmp'; Windows will not understand that path, it must be changed to: my $tmp_dir = 'c:/temp'; or whatever directory you can store temp session files in. if you don't know of one, just create a directory somewhere that your script can have write access to. (but don't put it in the www directory.) Try c:/temp first before you try anything else. For example: my $tmp_dir = 'c:/somedir/temp'; Be sure the user the web server runs as has read/write access to the directory. Give the directory full write/write/execute permissions to ensure the web server can write to it. again, do NOT put this directory in your web root or cgi-bin, as it would not be very safe. - If you are silly enough to want to run a webserver on win95/98/98SE/ME, you will have to modify the script somewhat, open all the .pl files and put a hash # in front of any line starting with the word: flock Win9x has no file locking method in place and you will get errors when perl tries to lock a file. Notes for mod_perl servers. --------------------------- - Cookies, I have not been able to test the cookie code of the counter in mod_perl due to some server issues at my end, but it should work fine under apache::registry. - As with windows servers, its a good idea to edit the $path_to_lib and $path_to_config variables in download.pl to absolute paths, and the htmlfixit-lib.pl and downloader_config.pl files need not actually be in the same directory as dl.pl. - The SSI may or may not work under mod_perl, depending on your servers setup. - Taint mode must be turned off. In the file dl.pl first line, change the following: change: #!/usr/bin/perl -Tw to: #!/usr/bin/perl -w To Do ----- Nothing really needs to be done, but if enough people ask me I may consider adding an administrative login to allow you to see the download counts more easily (for those not using the SSI display). (JUST DID THAT :) If you think of other things I should add.. let me know. Bugs, Problem or anything else I should be concerned about can be emailed to: franki at htmlfixit.com (replace the 'at' for @. I have it like this because spam bots can read textfiles too.) As always, for what works, thank the giants upon whos' sholders I stand. For what doesn't work, blame me for occasionally falling off.