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.pl Version 0.9, the first public release.
This document describes the configuration, installation, and operation of Art Sackett's Redirection Perl Script redirect.pl, and is applicable to Version 0.9, the first public release.
If you have no experience with installing Perl scripts for CGI applications, this might be a troublesome process for you, especially if you are not experienced with the operating system of the server. That portion of this document is written specifically for those performing an installation on a server running a Unix (it's many variants) 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 the relies upon default behavior. Once redirect.pl 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 at 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.pl is straightforward and relatively easy.
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 a floppy. 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 it's instructions. Otherwise:
That's all there is to it.
The configuration of redirect.pl 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
If you are not sure of the path to the Perl interpreter on the target system (the server you will be installing to), or whether or not the required module CGI.pm is installed, the best course of action is to establish a telnet connection and query the target system. Briefly, these are the steps to take assuming a Unix operating system is running the server:
Using your favorite text editor, open the file redirect.cgi that you extracted from the archive. (You may wish to create a backup copy first.) The very first line of the script reads #!/usr/bin/perl. If the path to the Perl interpreter on the target system is not /usr/bin/perl, edit this line to reflect that actual path (as was determined earlier with which perl). The shebang (#!) must remain in place. Do not add any whitespace to this entry unless your ISP or server administrator indicates that it is necessary.
At this point, if you are happy with the default configuration, you are done. I highly recommend that you continue reading this documentation, though -- some of the configuration that is available to you has not been presented elsewhere.
User configuration
Further down in the script, you will find a section that looks like this:
# ------------------ USER CONFIGURATION ---------------------- # $paranoid = 0; # default = 0 $debug = 0; # ONLY SET TO 1 WHILE DEBUGGING YOUR INSTALLATION! $reflist = 'ref_list.txt'; # Change if needed -- make sure the path is right. # ---------------- END USER CONFIGURATION --------------------
The descriptions of these options, and instructions for configuring them, follow. Please note that the semicolons and quote marks are not yours to edit unless you relish the idea of debugging a broken script.
(A "referring URL" is the URL of the document whose output is calling your script. If you have a form on, for example, http://www.your_isp.com/~myself/redirect.html, when the visitor clicks the submit button, the referring URL is http://www.your_isp.com/~myself/redirect.html.)
You might want to leave this option turned off until after you have the script installed and working -- if things go wrong, it will be easier to isolate the cause if you know that this function cannot be at fault. You can turn it on later when everything else is working.
This is a plain text file listing the allowed referring URLs based upon the value set by the visitor's browser. It consists of one entry per line, with no intervening whitespace, terminated by a newline (carriage return -- use your [Enter] key). The entries are partial initial patterns that must not contain the protocol portion of the URL (e.g. http://) which is assumed by the script to be either http:// or ftp://. (Any other value is rejected, period.)
Being a partial initial pattern, the referring URLs need only match as far as the end of a given entry. This is convenient, but it may also be used to expose your script to unintended use. Imagine an entry of www all alone on a line -- most of the web can now use your script. Your patterns must be long enough to isolate those URLs that you intend to allow while excluding all others.
Example:
# This is a comment line. It is ignored. So are blank lines. www.artsackett.com/grey_papers # everything in grey_papers and it's subs www.artsackett.com/freebies # and in freebies and it's subdirectories #www.artsackett.com # OOPS! everything in the domain!
This simple file limits access to those referring URL's indicating that the calling page was served from my freebies or grey_papers directories. Any other pages served from my domain are automatically excluded, except in the rare case that the browser didn't report the referring URL. (Brief discussion of this later.) Because the overly-permissive last line is commented out, it will have no effect.
In normal operation, if redirect.pl detects a referring URL that was not explicitly allowed by virtue of matching an entry in the accepted referrers list (if used) or by having been served by the same server redirect.pl is installed on, it simply exits without telling the user anything at all. With $debug = 1; any time a referring URL is rejected, an informational message will be returned to the user explaining why the referring URL was rejected and what you might do to correct this if it was unintentional.
Okay, that's it. redirect.pl is configured for processing the outputs of forms that pass it URLs. If you want to use the cool SSI features of redirect.pl, though, 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 it's 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 line, 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.
Here's a sample:
# Remember, those are tabs in there! http://www.yayhoo.com Redneck Search Engine http://www.autavisitya.com Relatives Who Never Leave http://www.microstupid.com Crashy Buggy Software
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 will have been 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!
Time to put it all on the server. You're going to have to know how to work FTP to do this, and how to change file permissions at the server. What I can tell you about it 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 it's "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.html 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. Remember: if you call it /cgi-bin/ you are referring to the system's cgi-bin directory, not your user cgi-bin directory. You probably do not want to do that. Once the file is edited, 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--). 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. Point your browser at whatever page you're using to test with, and it should all be working. Of course, if you chose not to install the URLs/Titles list(s) because you are not going to use the SSI features, the SSI will be broken. If nothing else is broken, you're done. Enjoy!
What? Something's broken? Make sure you followed these instructions carefully. If you're getting Referring URL denied 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!
If you're not going to use the SSI features, you have to write your own HTML to use redirect.pl. 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">One Camel that's not being shot at!
</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">
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.pl that you're not allowing redirect.pl 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.pl to create your form for you is to rely upon the defaults. If you copied list.txt into the directory alongside redirect.pl, all you need is this:
<!--#include virtual="cgi-bin/redirect.pl" -->
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.pl by stacking them onto the directive. First a question mark to separate the command from it's 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.pl?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 it'd default value.
The arguments and values redirect.pl understands are:
That's it! You should be ready to go. I hope you enjoy using redirect.pl. I don't ask for anything in return, but if you want to I would appreciate a post card, especially if it has a picture of where you live. My mailing address is peppered all over my commercial site at Art Sackett Professional Web Design. If you see Liz Knuth in your travels of the internet, be nice to her -- she is the one who motivated me to do this.
So, how'd I do, Liz?