Art Sackett's CGI Redirection Perl Script HOWTO


NOTE! redirect.cgi received an important security update on June 25, 2011. All previous versions should be replaced with the latest version. The new version is mostly backward-compatible, though the ability to allow off-site referrers has been removed. The SSI form generator works as before but is hardened against a potential (not seen in the wild) directory traversal attack.


If you are not viewing this document online at http://www.artsackett.com/freebies/redirect/HOWTO.html it may not be the most current version. This document was written for redirect.cgi Version 0.91, the second public release.


 

 


 

Introduction

This document describes the configuration, installation, and operation of Art Sackett's Redirection Perl Script redirect.cgi, and is applicable to Version 0.91, the second public release.

If you have no experience with installing Perl scripts for CGI applications in the operating system of the server, this might be a troublesome process for you. The installation portion of this document is written specifically for those performing an installation on a server running a Unix (Linux/BSD/et al.) operating system. If you are not so blessed, you will be better off seeking instructions elsewhere, perhaps the FAQ's or Help Files of your own ISP's web site.

I strongly suggest that you read through this document carefully, and make your initial installation one that relies upon default behavior. Once redirect.cgi is in place and working, change those things that you want to one at a time with a test of the new configuration before proceeding to the next item.

It is assumed that you already know that you are permitted to run your own CGI executables on the HTTP ("web") server, and if there are any restrictions regarding the directory or directories into which executables must be placed. Again, your ISP's web site may be your best source of information, and if you have any questions regarding these issues that are not answered there, you should contact your ISP.

That said, the care and feeding of redirect.cgi is straightforward and relatively easy.

 


 

Unpacking the archive

You will need unarchival software to extract the archived distribution. If you are using a graphical unarchival program, the Help file or other documentation that came with it are your best reference. The compression used for the redirect.zip archive can be uncompressed using just about any unzip utility, including DOS versions such as pkunzip. More recent versions of many graphical unarchival programs (such as WinZip[tm]) are also capable of extracting redirect.tgz.

The first step is to place the archive into a preferably empty directory, be it on your hard drive or removable media. This way, there is no danger of accidentally overwriting another file -- the archive contains a very common file name, index.html so this danger is very real. The next step is dependent upon which of the archives you selected as appropriate for your operating system. If you are using a graphical unarchival utility, extract the archive in accordance with its instructions. Otherwise:

That's all there is to extracting the archive.

 


 

Configuration

The configuration of redirect.cgi is simple. In the instructions that follow, you may safely ignore the configuration of options that you do not enable. If at any point along the way you do not understand the instructions here, you may wish to consult the artsackett.com grey paper perl CGI Scripts: Brokenly Installed for further guidance.

Path to the Perl interpreter

In the previous version it was required that the first line of the script, also known as "the shebang line" be verified prior to deployment. This should no longer be necessary.

User configuration

Open redirect.cgi in your favorite text editor (Notepad, vim, emacs, whatever) and near the top you'll find a section that looks like this. This is the only thing you'll want to edit:

# ------------------ USER CONFIGURATION ----------------------
#
my $allow_offsite = 0;        # change to 1 to enable off-site redirection
my $debug = 0;                # ONLY SET TO 1 WHILE DEBUGGING YOUR INSTALLATION!
#
# Notes you don't need to read since you're reading this...
#
# ---------------- END USER CONFIGURATION --------------------

redirect.cgi is now ready to run. If you want to use the cool SSI features of redirect.cgi there's one thing left to do, and that is to create your list of paired URLs and titles for the popup menu. Or create a whole pile of these files -- you're not limited to just one.

Creating a URL/Titles list

This is very straightforward. All you need to do is write some text. If you are going to have only one list, or have one that will be used much more frequently than the others, you might want to name it list.txt which is the default -- you won't have to specify it when calling the script from an SSI directive.

Each entry in the list appears on its own line. First comes the URL, then one or more tabs, then the corresponding title you wish to appear in the popup menu, then the newline (or "carriage return") character that you can't see but is created when you poke the [Enter] key on your keyboard. Comments must be on their own lines, and blank lines are ignored. Yes, it must be a tab character between the URL and the title, and a string of spaces will not work.

NOTE: All of your lists must be within the document root of your web server. redirect.cgi will not attempt to open files outside of it. If for some reason you wish to deny others the ability to read those lists at their URI's, you must configure your web server to deny access to them. (I don't know why you might do this, since the data they contain are visible by visiting the URI's of the documents that include the forms anyway. But live like you want to live!)

Here's a sample:

# Any line that begins with a hash symbol is a comment, as is
   # any line that has only whitespace before the hash symbol.

# Remember, those are tabs in there!

http://www.google.com/        Your Bestest Frenemy
http://www.artsackett.com/    The Guy Who Wrote This
http://www.example.com/       An Example

That's all there is to it. You might want to hang on to the list.txt that came with this package and get the script up and running before you start using your own lists. The more stuff you know should be working, the easier it will be to troubleshoot if things go wrong. (Would you rather spend a few extra minutes setting up, or a lot of extra minutes trying to figure out what's wrong?)

At this point, everything should be configured and ready for installation. A wise choice would be to review all of these steps and explanations, and rely upon the defaults until you know the script is working -- but live like you want to live!

 


 

Installation

Time to put it all on the server. You're going to have to know how to work either a file transfer utility (FTP, scp, etc.) or any provided "control panel" to do this, and know how to change file permissions at the server. What I can tell you about FTP is already written in my grey papers -- if you are uncomfortable with these things, I strongly suggest that you go read about broken Perl CGI scripts and/or FTP before proceeding.

It is assumed that you know where executable CGI applications should be, and from here on out I'm going to call this your cgi-bin directory. This directory has to have its "world" or "other" read and execute bits set in order to allow the server to traverse into it. The usual command is chmod 755 cgi-bin if it is not already in this state. You may be able to do this with your graphical FTP client, if that's what you're using. (I don't stay abreast of these things -- read the documentation ("Help files") that came with the thing.)

Upload the following files to your cgi-bin directory in ASCII mode:

If you don't already have an HTML document written to use for testing, you might want to edit the redirect.shtml page that came with this package, if necessary, globally replacing cgi-bin/ with the path from your public_html or www directory to your cgi-bin directory. Once the file is edited to turn on debug mode, if necessary, upload it to your public_html or www directory, again in ASCII mode.

Now, set the permissions of redirect.cgi to 755 (-rwx-r-xr-x) and all of the other files to 644 (-rw-r--r--), unless the XBitHack is what indicates to the server that redirect.shtml (or the test page you have written) should be parsed, in which case only that file should be set to 744 (-rwxr--r--) or 754 (-rwxr-xr--). You did read my grey papers, didn't you?

At this point, except for writing the SSI directives into your own HTML files if you're going to use them, you should be done with the installation and you'r ready to move on to Operation.

If you find that it doesn't work when you test it, make sure you followed these instructions carefully. If you're getting 500 Internal Server Error turn on debugging and find out why. If that's not it, check your work, and make sure that the assumptions were all correct (you are permitted to run your own executables, they're in the right directory, etc.) and try running a copy of the script with all of it's default states. Reread the grey paper about broken Perl CGI scripts. If your ISP expects you to use cgiwrap or some other CGI wrapper program, read what they have to say about doing that. Good luck!

 


 

Operation

If you're not going to use the SSI features, you have to write your own HTML to use redirect.cgi. You can use either GET or POST at your discretion to submit the form data, and all you have to concern yourself with is that there's no extra whitespace in the URL's you send. Here's a sample HTML snippet:

<form method="GET" action="cgi-bin/redirect.cgi">
    <select name="location">
       <option value="http://www.w3.org">The World Wide Web Consortium
       <option value="http://www.perl.org">Perl rocks!
       </option>
    </select>
    <input type="submit" value=" Go ">
</form>

The only thing you might have to change to make the above snippet work in an HTML document is the path to the script in <action="cgi-bin/redirect.cgi">

All that SSI stuff

If you don't know how to work with Server Side Includes, a good starting place is my grey paper, SSI for the Rest of Us. It will tell you, among other things, how you can include your own HTML markup wherever you want it, even if it's an interface to redirect.cgi that you're not allowing redirect.cgi to create. There are other uses for SSI, of course. If your ISP's online documentation is not enough to tell you if SSI is available to you, the grey paper gives you the tools (a little HTML and instructions for using it) to hack out an answer for yourself.

The simplest way to get redirect.cgi to create your form for you is to rely upon the defaults. If you copied list.txt into the directory alongside redirect.cgi, all you need is this:

<!--#include virtual="cgi-bin/redirect.cgi" -->

Some servers might barf on include virtual, in which case you would use exec cgi instead. Everything else is the same.

What the above SSI directive would get you is a form using the GET method using the contents of list.txt for the items in the popup menu. If you don't want to use the defaults, you pass arguments to redirect.cgi by stacking them onto the directive. First a question mark to separate the command from its arguments, then a list of arguments separated by ampersands (&). So, if we wanted to move the button to the left side of the popup (which I think is ugly), and use a list from otherlist.txt, it would look like this:

<!--#include virtual="cgi-bin/redirect.cgi?button=left&list=otherlist.txt" -->

That's all there is to it. The order of the arguments is unimportant. Anything you don't explicitly alter with an argument in the SSI directive assumes its default value.

The arguments and values redirect.cgi understands are:

 


 

That's it! You should be ready to go. I hope you enjoy using redirect.cgi. If you encounter something that looks like a bug, and especially if you'd like to hire me to do some contract programming for you, you can contact me, Art Sackett, here.

Enjoy!