Most problems encountered while installing Hazel really aren't her fault--they result from a lack of knowledge about how things work. Ignorance is curable, and this page is but one cup of knowledge we plan to pour into your brainpain.
CGI stands for "Common Gateway Interface." It isn't a programming language itself, but a protocol which defines how programs communicates with a web server, and thus your browser. Programs thusly written are commonly called "CGI."
The sections below point out some common mistakes associated with uploading and configuring a CGI program on your server.
Most uploads are done using an "FTP" program. FTP stands for File Transfer Protocol. It does what it says, and has been around since long before the web. FTP attempts to be smart by providing an "ASCII" mode for uploading files. In this mode, it converts files between the formats used on the sending and receiving operating system. ASCII mode should only be used when you're uploading a text file. If you upload a binary file (such as the hazel.cgi file itself, or images) in text mode, it will be corrupted on the receiving end.
- Upload all interpreted scripts (Perl scripts, anything that appears as readable text in a text editor) in "ASCII" (or "text") mode.
- Upload Hazel herself and all binary programs (look like gibberish in a text editor) in BINARY or RAW (Mac Fetch) mode. Never upload anything in MacBinary mode.
File "Modes" and Permissions
On Unix, each file has a set of "modes" or "permissions" which define who can read it, write it, and run it. Unix breaks all users into three groups-- the single user who owns a file ("user"), people in the file's group ("group"), and everyone else ("other").
Make sure your CGI is executable (it can be executed, or "run") by the webserver. This usually involves either (a) setting the file mode to 755, or (b) clicking the "readable" and "executable" boxes on your FTP program so that all of user, group, and other can read and execute the file.
On an NT server, there's usually no concept of permissions from an FTP interface. All file mode changes must be done from the console, so you'll need to ask your administrator to set things straight.
Browser Prompt to Download Hazel.cgi?
If you're trying to hit your newly uploaded Hazel and your browser prompts you to download it, then your web server doesn't know it's a CGI program. Instead of executing it and displaying the output to your browser, it's just trying to dump the file itself as if it were an image or other data file.
The problem is that you've either uploaded it into the wrong place, or it otherwise needs something done to make the server recognize it as a CGI. If you have a cgi-bin directory, it probably goes there. Setting it executable and giving it the .cgi extension are other indicators, done here by default.
If you're on an NT server, you'll need to ask your administrator where to put your CGI files.
The Magic Perl Line
For Perl scripts on a Unix system, you must be sure the first line of the script points to the location of Perl on that system. It is usually a line such as "#!/usr/bin/perl" (common on Linux and BSD systems) or "#!/usr/local/bin/perl" (common on proprietary Unix such as Solaris and HPUX). Perl can be anywhere. Use our included hello-hazel.cgi script to find out, or ask your sysadmin.
Other interpreted scripts may also need a first line pointing to a program which will interpret and execute their commands. hello-hazel.cgi is the only Hazel script which would require an alternate interpreter, and it uses /bin/sh, unbiquitous on all Unix-based systems.
Yes, the `#' is usually for commenting out a line, and it still is in the case of interpreted scripts, inasmuch as the interpreter itself (such as the Perl executable program) will ignore the line. However, a Unix-based "kernel" (which handles running all programs) recognizes the first line of a script which also begins with "#!" as specifying an interpreter for that file. It then simply passes that entire file to the specified program, which subsequently ignores that first line as a comment. Ta-da!
Windows NT systems do not use such a "magic line." Most NT web servers associate files just as NT itself does: by their file extensions. If you're on an NT system and your script isn't running, try exchanging a ".cgi" for a ".pl", or vice versa. Executable programs must always end in ".exe".
On some NT web servers, where a CGI is located determines what's supposed to interpret it. You may have a cgi-scripts or somesuch directory. Contact your NT admin if you're having trouble.
Hazel will not work with nonstandard CGI API such as "WinCGI" or "ISAPI".
Running CGI As Your User-ID
Alright, boys and girls--this one is really important. Modern operating systems allow multiple users to run programs at any given time. To ensure that one person's program can't go stomping over someone else's data, each runs with the permissions of a certain user-id.
When you're running a CGI program which writes sensitive information, you want it to run as your user-id, so nobody else can read what it writes. Particularly with an e-commerce program such as Hazel, even shopper names and addresses are sensitive data you don't want just anyone snooping over.
There is a school of thought amongst some system administrators that it's good to run all CGI programs as an unprivileged user. On Unix this phantom dummy is called "nobody". On NT it's often something like "IUSR_FOO", where FOO is the machine's name. His name isn't important. What matters for the purposes of this discussion is that when all CGI run as "nobody", he might as well be "everybody", since everyone else running CGI on your shared server has read/write access to your files!
That isn't good. In fact, it's very bad.
When you upload files to your webserver, they're usually owned by your user-id. That's fine, and it means you can protect them against snooping by others. Unfortunately, if your server is running as "nobody", then your CGI programs can't read those files! If "nobody" needs to read it, then you'll have to force it to work by setting the files to be read/write/execute by everybody!
You realize that's not a good solution, right? It should be obvious that making a file readable, writable and whateverable by everyone else on your server is not a good idea. Even on the outrageous chance that you share a server only with people you'd trust with your mother's life--what if someone manages to get their password? Now that person has your files, too.
The proper solution to this problem is to get your system administrator to fix your server so that your CGI programs run as your user-id. If you ask them to do this and they refuse, find another host. We endorse several excellent ISP who we've confirmed do things "the right way."
If your ISP is attentive and says they'll look into it, help them along by giving them some information! Here are two good programs which can be used to make CGI run as the domain's user-id:
- CGIWrap: http://www.umr.edu/~ftpserv/pub/cgi/cgiwrap/ or http://www.unixtools.org/cgiwrap/.
- SUEXEC: http://www.apache.org/docs/suexec.html
SUEXEC is included with recent Apache installations. Running CGI as the domain owner's user-id is often as simple as adding `User USERID' and `Group GROUPID' lines to the VirtualHost block for a particular server.
Another (often simpler) Unix solution is to `setuid' the hazel.cgi so that it always runs as its owner. The Unix command to do so is `chmod 4755 hazel.cgi'. Of course, the file should be owned by your user-id! Set as such, the operating system will switch to the owner's identity before running the file, and thus run with your permissions.
You should never setuid a file owned by root! Your web server should not be running as root, and HTML and CGI files should not be owned by root. It's bad practice and can lead to big trouble if you don't know what you're doing.
On Windows NT, you can set your specific website to run with the permissions of your user account instead of the "IUSR_FOO" "nobody" account.
Problems Specific to NT Servers
If an NT server is properly configured, it'll be a joy to use from the user's standpoint. If it isn't, well, there isn't much you alone can do about it. You'll have to call your NT Administrator and get him to fix things. This section details some common NT problems and how we've gone about getting the persons responsible to fix them.
If you're not using a Microsoft (NT, 2000) web server, you're finished with this section. The notes below are applicable only to Microsoft servers. If you're one of the proud few who run your website on a Unix server, you're finished with this page--go home!
These instructions are useful only if you are at the console of an NT server, with the machine right there in front of you. This is something for your web server admin to do. You can't do it remotely!
Setting Up CGI On a Microsoft Server
Here's a walkthrough of setting up CGI for a web server running on Microsoft's Internet Information Server. This was current when we wrote it, but the menu clickpath may have changed since. Hopefully it'll give you an idea of where to go and what to do.
- Go to Start -> Programs -> Microsoft Internet Server -> Internet Service Manager.
- Right-click on your web server and choose "Service Properties".
- Select the "Directories" tab.
- Click the "Add" button.
- In the "Directory" text field, enter the full path to your uploaded hazel.exe. Remember that directory, as you'll need it later.
- In the "Alias" text field, enter a single word for that directory. We'll call it "hazel" for the sake of this example. What you use will become part of the URL to your hazel.exe. Assuming your domain is example.com, the path would be "http://example.com/hazel/hazel.exe".
- Click the "Execute" checkbox within the Access section, indicating to the web server that files in this directory are to be executed and their output served to the browser. (Otherwise, people who hit your hazel.exe will be prompted to download the file itself!)
- Click "OK". You'll notice your new directory in the Directories listing.
- Click "OK" to close the Internet Service Manager.
Perl Setup Notes for Windows NT
First step: install the latest Perl version from ActiveState (http://www.activestate.com/). They call it "ActivePerl." The installer should handle everything!
Unlike Unix, NT doesn't look at the first line of a script for what should interpret it. Instead, NT associates extensions with certain programs. So, ".pl" or ".cgi" should be associated with your PERL.EXE executable in the Web Server configuration.
To find out what NT thinks it should use to run files with a certain extension, follow these steps:
- From inside the Microsoft Management Console (MMC), right-click on your website and choose Properties.
- Under the Home Directory tab, there should be a Configuration button. Click it and you should be in an Application Configuration dialog box with Application Mappings listed.
- The mapping for Perl should list ".pl" in the extensions column and something like "C:\ActivePerl\bin\Perl.exe %s %s" in the Executable Path column. The actual path to Perl may differ--what's important is that it calls PERL.EXE (not a .DLL!) and that "%s %s" follows it.
Missing Perl Output
Some older versions of the Microsoft Internet Information Server would not allow Perl to capture the output from another command. This problem manifests itself either as a CGI script producing no output (resulting in a Server Error for incomplete or malformed headers), or a "Document contains no data" error. You should upgrade to the latest service packs and releases of your NT kernel, your web server, and your Perl installation.
If you're running IIS version 3, you might be able to fix the problem with a little hack to the NT registry. Run REGEDT32.EXE and locate the \SYSTEM\CurrentControlSet\Services\W3SVC\Parameters subkey in the HKEY_LOCAL_MACHINE subtree.
If you don't see the following name in the list of values, click "Add Value" on the "Edit" menu to add it with the following parameters:Value Name: CreateProcessWithNewConsole Data Type: REG_DWORD Data Value = 1
If that doesn't fix things, maybe there's another problem. Sorry, but we're out of ideas!
HZML & HAM
CGI and You