CGI

From DreamHost
Jump to: navigation, search

Overview

Common Gateway Interface (CGI) is an important World Wide Web technology that enables a client web browser to request data from a program executed on the web server. CGI specifies a standard for passing request data between a web server and the program used to service that request. CGI scripts are often preferred by web developers because of their speed and their minimal resource requirements. CGI scripts on DreamHost can be written in all of the languages commonly used with CGI (Perl, Python, Ruby, even shell scripts), and as long as you have an interpreter for that language to compile.

Running a CGI script at DreamHost

To run, copy the script to a web-accessible directory (e.g., /home/username/example.com/cgi-bin). You don't have to put your CGI scripts in a cgi-bin directory, as CGI scripts can run from any directory within your domain on DreamHost. The server understands several file extensions (e.g., .pl), but if you see the source code of your script instead of the result of its execution, try using the generic extension .cgi.

If you get a "500 Internal Server Error", you may need to change the permissions of the file:

$ chmod 755 script.cgi

Running a CGI script without a .cgi extension

If you wish to install a CGI script without the .cgi extension, simply use a <Files> directive in your .htaccess. For example, if you wish to have a cgi-bin directory, create a file named .htaccess inside of it, and then insert the following:

<Files *>
  SetHandler cgi-script
</Files>

Once you add this directive, all files within the directory will run as CGI scripts.

Examples of CGI Scripts

Perl

#!/usr/bin/perl

use strict;
use CGI;

my $q = CGI->new;
print $q->header();
print "Hello, world!";

Python

#!/usr/bin/python

print "Content-type: text/html"
print
print "Hello, world!"

Ruby

#!/usr/bin/ruby

require 'cgi'

cgi = CGI.new
cgi.out{ 'Hello, world!' }

Shell Script

#!/bin/sh

echo "Content-type: text/html"
echo
echo "Hello, world!"

Troubleshooting

If you find your .cgi script throws an error, first check the section above titled 'Running a CGI script at DreamHost'. You can also check your site's error log file. View the following article for details:

Debugging CGIs

The best way to debug any CGI is to run it directly on the server. Log into your server via SSH. Then run it using the following command:

./cgi_name.cgi

Your terminal will return whatever is meant to be sent to the user's web browser.

You will often receive a message stating the general problem and the line number it occurs on. Usually it is best to fix the first error that comes up, as that will often help with errors that occur further down the script.

Carriage returns in Perl scripts

Perl scripts in particular will occasionally mention a problem caused by carriage returns within the script. Perl has problems executing files with carriage returns, which are usually caused by scripts being edited in many Mac or Windows PC based text editors (which natively use carriage returns to mark line endings).

You should only use a text editor that gives you an option to save with 'Unix-style' line endings. Notepad++ is a good choice:

What if I don't want .pl, .py, or .cgi files to run as CGI scripts?

If you'd rather have .pl, .py, or .cgi files displayed in the browser rather than executed as scripts, simply create a .htaccess file in the relevant directory with the following content:

RemoveHandler cgi-script .pl .py .cgi

If you're using SSH to connect you can create the .htaccess file by running the following command:

echo "RemoveHandler cgi-script .pl .py .cgi" > .htaccess

Good resources for Perl CGI scripters

Perl is by far the most common language used to write CGI scripts. A fairly easy learning curve, coupled with tons of freely available source code, make it a perfect choice for the beginning (and advanced) web coder. One of its greatest strengths is that the language was written with text processing in mind. Given that the web is almost nothing but text, it's a perfect match.

You can download the latest version of Perl at the official Perl site: http://www.perl.com

This site also contains a lot of great general information about writing Perl and Perl CGI scripts. There are also numerous online tutorials and books available to help you get started.

The sites below offer numerous scripts that you can use with a CGI-enabled Dreamhost account. Some are better than others, so you should shop around before deciding on a given script.

suEXEC

suEXEC is enabled for all DreamHost users and cannot be disabled. Because of this, some features, such as the SetEnv directive in .htaccess files, won't work as expected. See the suEXEC page for workarounds and more details.

See also