eekim.com > Publications > CGI Developer's Guide > Chapter 2

Chapter 2: The Basics (01)

<Next | Table of Contents | Previous> (02)

Installing and Running your CGI Programs (03)

This section digresses briefly from CGI programming and talks about configuring your Web server to use CGI and installing and running your programs. You learn a few different servers for different platforms here in some detail, but you will want to consult your server documentation for the best instructions. (04)

All servers require space for the server files and space for the HTML documents. In this book, the server area is called ServerRoot and the document area is called DocumentRoot. On UNIX machines, the ServerRoot is typically in /usr/local/etc/httpd/ and the DocumentRoot is typically in /usr/local/etc/httpd/htdocs/. This is by no means necessarily true on your system, however, so make sure you replace all references to ServerRoot and DocumentRoot with your own ServerRoot and DocumentRoot. (05)

When you access files using your Web browser, you specify the file in the URL relative to the DocumentRoot. For example, if you have the file /usr/local/etc/httpd/htdocs/index.html on your machine mymachine.org, you would access that file with the following URL: (06)


http://mymachine.org/index.html    (07)

Configuring Your Server for CGI (08)

Most Web servers are preconfigured to use CGI programs. There are generally two things that tell a server whether a file is a CGI application or not: (09)

A designated directory. Some servers enable you to specify that all files in a designated directory (usually, by default, called cgi-bin) are CGI. (010)
Filename extensions. Many servers are preconfigured to interpret all files ending in .cgi as CGI. (011)

The designated directory method is somewhat of a historical relic (the earliest servers used this as their sole method for determining which files were CGI programs), but it has several advantages. (012)

It keeps CGI programs centralized, preventing your other directories from becoming cluttered. (013)
You are not restricted to any specific filename extension, so you can name files whatever you want. Some servers enable you to designate several different directories as CGI directories. (014)
It also gives you greater control over who can write CGI. For example, if you maintain a system with several users, and you don't want them to use their own CGI scripts without first auditing the programs for security reasons, you can designate only those files in a restricted, centralized directory as CGI. Users will then have to give you the CGI programs to install, and you can audit the code first to make sure there are no major security problems with the program. (015)

Indicating CGI by filename extension can be useful because of its flexibility. You are not restricted to one single directory for CGI programs. Most servers can be configured to recognize CGI by filename extension, although not all of them are configured this way by default. (016)

CAUTION (017)

Remember that there are important security considerations you need to remember when you are configuring your server for CGI. Some hints will be discussed here, but make sure to read Chapter 9, "Security," for more details on CGI security. (018)

Installing CGI on UNIX Servers (019)

No matter how your UNIX server is configured, you need to take a few steps to make sure your CGI applications run properly. Your Web server will normally be running as a non-existent user (that is, the UNIX user nobody, an account which has no file access rights, and can't be logged into). Consequently, compiled CGI applications should be world-executable and CGI scripts (written in Perl, Bourne shell, or another scripting language) should be both world-executable and world-readable. (020)

TIP (021)

To make your files world-readable and executable, use the following UNIX command, where filename is the name of the file: (022)


chmod 755 filename    (023)

If you are using a scripting language such as Perl or Tcl, make sure you specify the full path of your interpreter in the first line of your script. For example, a Perl script using perl in the /usr/local/bin directory should begin with the following line: (024)


#!/usr/local/bin/perl    (025)

CAUTION (026)

Never put your interpreter (the perl or Tcl wish binary) in your /cgi-bin directory. This creates a security hazard on your system. More details are available in Chapter 9. (027)

Some Common UNIX Servers (028)

The NCSA and Apache Web servers have similar configuration files because the Apache server was originally based on the NCSA code. By default, they are configured to think any file in the cgi-bin directory (located by default in ServerRoot) is a CGI program. To change the location of your cgi-bin directory, you can edit the conf/srm.conf configuration file. The format for configuring this directory is: (029)


ScriptAlias fakedirectoryname realdirectoryname    (030)

where fakedirectoryname is the fake directory name (/cgi-bin) and realdirectoryname is the complete path where the CGI programs are actually stored. You can configure more than one ScriptAlias by adding more ScriptAlias lines. (031)

The default configuration is sufficient for most people's needs. You should edit the line in the srm.conf file anyway to specify the correct realdirectoryname. If, for example, your CGI programs are located in /usr/local/etc/httpd/cgi-bin, the ScriptAlias line in your srm.conf file should resemble the following: (032)


ScriptAlias /cgi-bin/ /usr/local/etc/httpd/cgi-bin/    (033)

To access or reference your CGI programs located in this directory, you would use the following URL: (034)


http://hostname/cgi-bin/programname    (035)

where hostname is the host name of your Web server and programname is the name of your CGI. For example, suppose you copied the hello.cgi program into your cgi-bin directory (for example, /usr/local/etc/httpd/cgi-bin) on your Web server called www.company.com. To access your CGI, use the following URL: (036)


http://www.company.com/cgi-bin/hello.cgi    (037)

If you want to configure either the NCSA or Apache server to recognize any file with the extension .cgi as CGI, you need to edit two configuration files. First, in the srm.conf file, uncomment the following line: (038)


AddType application/x-httpd-cgi .cgi    (039)

This will associate the CGI MIME type with the extension .cgi. Now, you need to modify your access.conf file to enable CGIs to be executed in any directory. To do this, add the ExecCGI option to the Options line. It will probably look something like the following line: (040)


Option Indexes FollowSymLinks ExecCGI    (041)

Now, any file with the extension .cgi is considered CGI; access it as you would access any file on your server. (042)

The CERN server is configured in a similar fashion as the NCSA and Apache servers. Instead of ScriptAlias, the CERN server uses the command Exec. For example, in the httpd.conf file, you will see the line: (043)


Exec /cgi-bin/* /usr/local/etc/httpd/cgi-bin/*    (044)

Other UNIX servers are configurable in a similar fashion; check your server's documentation for more details. (045)

Installing CGI on Windows (046)

Most of the servers available for Windows 3.1, Windows 95, and Windows NT are configured using the file extension method for CGI recognition. Generally, reconfiguring your Windows-based server simply requires running the server's configuration program and making the appropriate changes. (047)

Configuring your server to correctly run scripts (such as Perl) is sometimes tricky. With DOS or Windows, you cannot specify the interpreter on the first line of the script like you can with UNIX. Some servers are preconfigured to associate certain filename extensions with an interpreter. For example, many Windows web servers will assume that files ending in .pl are Perl scripts. (048)

If your server does not do this type of file association, you can define a wrapper batch file that calls both the interpreter and the script. As with the UNIX server, don't install the interpreter in either the cgi-bin directory or in any Web-accessible directories. (049)

Installing CGI on the Macintosh (050)

The two most established server options for the Macintosh are StarNine's WebStar and its MacHTTP predecessor. Both recognize CGIs by looking at the filename's extension. (051)

MacHTTP understands two different extensions: .cgi and .acgi, which stands for asynchronous CGI. Regular CGI programs installed on the Macintosh (with the .cgi extension) will keep the Web server busy until the CGI is finished running, forcing the server to put all other requests on hold. Asynchronous CGI, on the other hand, will enable the server to accept requests even while running. (052)

The Macintosh CGI developer using either of these Web servers should simply use the .acgi extension rather than the .cgi extension whenever possible. This should work with most CGI programs; if it doesn't seem to work, rename the program back to .cgi. (053)

Running Your CGI (054)

After you've installed your CGI, there are several ways to run it. If your CGI is an output-only program, such as the Hello, world! program, then you can run it by simply accessing its URL. (055)

Most programs are run as the back end to an HTML form. Before you learn how to get information from these forms, first read a brief introduction to how to create these forms. (056)

<Next | Table of Contents | Previous> (057)