CGI: Introduction to the Common Gateway Interface (CGI)

Gateways

A gateway is a mechanism that allows a Web server to run a program or script on the local server and send the output to a Web browser. For example, you could use a gateway program to: let a user access a database program through your browser; let a user obtain the output from a UNIX command (e.g., finger), compute some data right then and there and then display it to the user. You also use gateway programs to receive the information a user has typed into a fill-out form.

The Common Gateway Interface

The Common Gateway Interface (CGI) is the mechanism for communicating between your gateway and your Web server.

In the case of CGI scripts used to receive fill-out form input, Web browsers send values entered into the fields to the httpd server. The httpd server accepts the input, starts up the gateway and hands the input to the gateway via the CGI. The field values are passed to the gateway either via environment variables (called the GET method) or using standard input (called the POST method). The gateway may then parse the input and processes it. It may generate HTML output, which is returned to the httpd server to pass to the client or it may save the data in a file or email to someone.

However, CGIs do not have to take any input at all. For example, the date script does not accept any input.

The gateway can be a script or program written in C/C++, Perl, the C Shell, Bourne Shell, just about *anything*, as long as it's an executable command.

Example gateway programs written by ECN staff are email-form and pagecount. email-form takes user input, pagecount does not require input (directly from the user), except when asked to generate statistics.

Define CGI Files In Your .htaccess File

You will need to create a .htaccess file in your ~/public-web directory. Go into your ~/public-web directory and, using an editor (vi, emacs), make a file called .htaccess.

The file must contain the following lines:

	Options ExecCGI 
	AddType application/x-httpd-cgi .cgi

The .cgi can be whatever you want the extension to be for your scripts. The other line must be typed in exactly as shown above. The AddType application/x-httpd-cgi is the line which defines what files will be run as "scripts". This is like telling httpd - when you see a file that ends in .whatever, run it as a script. So for example you may want all your script files to be .script. To do this, create a .htaccess file like:

~/public-web/.htaccess:

	Options ExecCGI
	AddType application/x-httpd-cgi .script

After you have set up your .htaccess file, save the file and exit your editor.

NOTE: your .htaccess file MUST end in a new line, otherwise it will not process correctly. And you can have only one "Options" line. All the options (such as Includes, FollowSymlinks, etc..) must be on this one line.

In your HTML document you will refer to your script file as:

	<a href="foo.script">

Where Must My Scripts Be Located?

Your scripts must be in your public-web directory (~/public-web) or a directory below it.

Note to webmasters: scripts can also run under DocumentRoot (/var/www/htdocs).

Some users may want to create a bin directory in ~/public-web and put scripts under here. Your scripts must end in whatever was defined in your .htaccess file.

Examples:

	~/public-web/foo.cgi 
	~/public-web/bin/foo.cgi
	~/public-web/bin/scripts/foo.cgi

In your HTML document you will refer to your scripts like this:

If your script is located in ~/public-web/foo.cgi:

	<a href="foo.cgi">Foo Script</a>

If your script is located in ~/public-web/bin/foo.cgi:

	<a href="/~login/bin/foo.cgi">Foo Script</a>

NOTE: if calling a script from a subdirectory of public-web (like the above example), it must be referred as "/~login/subdirectory/..".

Format of CGI Script Files

The communication between the browser and the httpd program is such that the browser will display the data that httpd gives it. So httpd will tell the browser, this is a HTML file or a plain file or a GIF, then the browser handles the data accordingly, depending on what is defined in the first line of the cgi-script. The CGI program can return plain text, an image, an audio file, etc..

• Your script must be written in the same shell or program that you define in the first line of the script file. For example, if you define the script to be:

  	#!/bin/sh
  

  Then the file must be written in Bourne shell (sh). If you define the first line to be:

  	#!/usr/unsup/bin/tcsh -f
  

  Then the file must be written in the TC shell (tcsh), etc..

• CGI gateways that generate web output are required to preface the output to stdout with a Content-type line, followed by a blank line, then followed by the data. For example, if you don't want to generate HTML output:

  	echo Content-type: text/plain
  	echo ""
  

  if you do want to generate HTML output:

  	echo Content-type: text/html
  	echo ""
  

The echo Content-type line must be followed by a blank line. So these must be the first two lines of output from the script. The content-type can be any legal type; e.g., you could have

	#!/bin/sh
	echo Content-type: image/gif
	echo ""
	cat foo.gif
	exit 0

The gateway does not have to generate HTML. It could return the URL of another file, indicating to the browser that it should get the file. This is called URL redirection. It can also return plain text, an image, an audio file, whatever.

If you want the gateway to generate a text file, you do not need quotations marks. If you want the gateway to generate HTML, then you must enclose your HTML tags in single or double quotes. That is because the > and < signs will be misinterpreted if not enclosed in quotes. We recommend you use use single quotes as opposed to double quotes.

We recommend this because if you have a URL in your script (URLs contain double quotes) and you surround your tags also in double quotes, the gateway will get confused. You can remedy this by inserting a backslash (\) before every double quote in the URL or just use single quotes which will eliminate this problem all together.

Example of a finger script

To reference your finger script, in your HTML document, you would have a line like this in a document in ~/public-web/:

For the finger information of the debweb computer, <a href="finger.cgi">click here</a>

The link would then call the following "finger.cgi" script: ~debweb/public-web/finger.cgi:

	#!/bin/sh
	
	echo Content-type: text/html
	echo ""
	echo '<HTML>'
	echo '<BODY>'
	echo '<PRE>'
	/usr/local/bin/finger -p debweb
	echo '</PRE>'
	echo '</BODY>'
	echo '</HTML>'

	exit 0

**** End of Example ****

The gateway can also return the URL of another file, telling the browser to get that file. This is called URL redirection. CGI gateways using URL redirection write the following line to stdout:

	Location: URL

This line too, must be followed by a blank line.

How to Set Up URL Redirection

1. Create a CGI script that outputs:

	Location: URL
	<blank line>

2. In your document put:

	<a href="yourscript.cgi">find me</a>

When the user clicks on the link, it will invoke the script, which will output the URL. The browser will go to the URL, just as if it were what was in the HREF itself.

For Example:

This is what your URL redirection script will look like:

	~debweb/public-web/foo.cgi:

        #!/bin/sh

        echo Location: http://harbor.ecn.purdue.edu/~debweb/
        echo ""
        exit 0

Note:you do not need quotes in this file.

This is how you will refer to it in your HTML document:

	~/public-web/foo.html:

	<title>Test</title>
	To view my homepage, <a href="foo.cgi">try this!</a>

If you click on the "try this!" link, it will invoke the "foo" script, and your browser will connect to my home page, just as if the foo.html file actually contained:

	<title>Test</title>
	To view my homepage, <a href="http://harbor.ecn.purdue.edu/
	~debweb/">try this!</a>

Permissions

Remember your public-web directory must be mode 755 and your scripts also must be 755. In other words, your public-web and your scripts must be:

	read, write executable		by owner
	read, executable		by group and other (world)

To change mode permissions on your file(s):

	% chmod 755 filename

OR

	% chmod go+rx filename

Additional Information

The Common Gateway Interface (NCSA)
CGI Script Output (NCSA)
Decoding Forms with CGI (NCSA)