Getting CGI to work correctly

CGI scripts are scripts that can be run remotely (for example, via a website), and include such things as webcounters, bulletin-board software, formfilling, and so on. This qref is intended to help you get an already-written script to run as a CGI script.

It takes a fair amount of work to get a CGI script to run: not only must the script be free of errors, but there are numerous configurations that must be set. The reason for these blocks is that an unsafe CGI script can wreak havoc on the system in the hands of a devious (or just naive) user. A correctly- configured CGI script will not modify anything it is not allowed to modify. The following is a step-by-step guide to making and running a simple CGI script.

1. First, write the script itself. This can be in just about any language, but Perl or PHP are common. Instructions on how to write a script are language-dependent, and beyond the scope of this qref (this guide provides a starting point). However, the most basic concept is that the script should print (to standard out) the appropriate content that you want the user's web browser to see. It is important to include the Content-Type as the first thing printed (example: Content-Type: text/html; charset=ISO-8859-1), or your script will work fine on the command line, but fail mysteriously from a web browser. Most languages have libraries, modules, or whatever that will do this for you — be sure to use them!
2. The second element is that the server must know how to run the script. If you've written this CGI script in an interpreted language (like Perl, PHP, or Python), you need to be sure to instruct the web server how to run your script. (If you're using a compiled script, odds are you have advanced beyond the need for this tutorial, or you're doing something wrong). This is done by putting a special first line at the top of the file. Here's how:
   1. You need to find out exactly where the interpreter is located. To do this, use the command

      which interpreter

      Most likely, it will be in /usr/local/bin.
   2. Make the first line of your script be

      #!/path/to/interpreter

      Any command-line arguments may be included, there, too.
   To take a concrete example, let's say we've written our CGI in Perl. which perl tells us that Perl is located at /usr/local/bin/perl. We want to be secure, so we'll have Perl assume that incoming data is tainted (with the -T switch), and we'll enable warnings with -w. So, the first line of our script will be:

   #!/usr/local/bin/perl -w -T

3. There's another level of security for CGI scripts that we need. This level exists on the server side. By placing the script and all the files that it modifies in a special directory, the server ensures that no critical files can be modified by it.

   Depending on what the script does, you may or may not want to put any files it modifies in your public_html directory. For example, if your script makes webpages that you will want to reference later, then those pages should be somewhere under public_html. However, if you're collecting any information that should be kept private, don't keep it under the public_html directory, because it will be readable to anyone who knows where to look.

4. Put your script (for example, helloworld.cgi) in a directory in your public_html directory (the classic directory name is cgi-bin). Create a file called .htaccess and put the following lines in it:

   Options +ExecCGI
   SetHandler cgi-script
   

   Put the .htaccess file in the same directory as the script. This allows all of the files in the directory to be executed as CGI scripts. If you don't want all of the files in the directory to be treated as CGI scripts, but instead want to be able to mark them using a filename extension (such as .cgi, .pl, .php, etc.) then use AddHandler cgi-script .ext instead of the SetHandler directive.
5. To actually run the script from one of your web pages, you'll need to modify the code for that page. Essentially, any place where you put a URL into the HTML, you can place a CGI link instead. So to link to a CGI-generated page, use code like this:

   <a href="cgi-bin/helloworld.cgi">Click me!</a>
   

   CGI scripts can also create images, and so on. Remember to make certain that your script and the .htaccess file are both world-executable, or else none of this will work.

Summary:

Options +ExecCGI
SetHandler cgi-script

Troubleshooting

Check permissions on your directories. Your home directory needs to be executable by "other" (chmod o+x ~). Your public_html directory needs to be world-readable and world-executable, plus it cannot be writable by anyone but you. The directory containing your CGI scripts must also be world-readable and world-executable, and not writable by anyone but you. The same goes for you .htaccess file and the actual CGI scripts.