Customer Reviews

Read More

The World's Leader in Virtual Server Technology

CGI - The Common Gateway Interface
pg. 14

• Using CGI on Your virtual server
• Running CGI From Other Directories
• An Introduction to Perl
• The virtual server C/C++ Compilers
• Debugging Techniques for CGI programs

CGI programs are applications that can be run on your virtual server to interact with Web browsers. They take input from Web page forms, manipulate that information, and print output back to a Web page. CGI programs allow you to do powerful, useful things with your Web site—from taking customers’ orders to playing interactive games. Because these programs provide a “gateway” between your virtual server and Web visitors, they are referred to as Common Gateway Interface (CGI) programs.
CGI programs can be written in many different programming languages, including C, C++, and PHP. The most widely used CGI programming language used on the Internet is Perl.
If you are unfamiliar with the CGI standard, or would like to learn more about the Common Gateway Interface, the following URL is an excellent resource:
http://hoohoo.ncsa.uiuc.edu/cgi/

Using CGI on your virtual server
Your virtual server comes pre-configured with a special directory in which you can place your CGI programs. This directory is called cgi-bin, and is located in your ~/www directory. While it is possible for you to configure any directory on your virtual server to allow CGI programs to be used, your ~/www/cgi-bin directory is already configured to do so.
Our technical staff has put together a library of useful, easy to use software programs that we support. While our Support Staff will gladly offer assistance with the programs in this library, they are not prepared to assist you with outside programs or custom written CGIs.
CGI programs can be called directly through a Web browser, or can be called from the action tag of a Web form. For example, when you submit a form via our contact page, the form contents are passed to a CGI program located in our ~/www/cgi-bin directory. This CGI program emails your message to our Support Staff and displays a confirmation page.

Running CGI From Other Directories
Because programs that interact with outside visitors could lead to potential security concerns, your virtual server is limited by default to only allow programs to be executed in the ~/www/cgi-bin directory. However, CGI programs can be run from any subdirectory of your ~/www/htdocs directory, if you configure the directory to allow it.
There are a couple of different ways to enable CGI execution from a specific directory. You can either add a new section to your ~/www/conf/access.conf file, or create/modify an .htaccess file in the directory you wish to make executable.
To enable CGI execution for a directory via the access.conf file, cd to your ~/www/conf directory and edit the access.conf file. Add the following lines to the end of the file, substituting directory_name with the rest of the path to the desired directory:
<Directory /usr/local/etc/httpd/htdocs/directory_name>
Options FollowSymLinks ExecCGI
<Limit GET POST>
order deny,allow
deny from none
allow from all
</Limit>
</Directory>
To enable CGI execution in a directory through the use of an .htaccess file, go to the directory you wish to make executable and create an .htaccess file within that directory (or edit the .htaccess file in the directory if one already exists). Then, add the following lines to your .htaccess file:
Options FollowSymLinks ExecCGI
<Limit GET POST>
order deny,allow
deny from none
allow from all
</Limit>
Besides being placed in a directory that enables CGI execution, a CGI program must possess the correct file permissions. File permissions tell your virtual server whether a file can be read, written to, or allowed to be executed.
To grant execution privileges to a file, you should use the chmod command. First, move into the directory that contains the file. Then, type the following at the command prompt:
chmod 755 filename Enter
The filename should be the name of the file that you wish to make executable.
For more information on the chmod command, type the following at the command prompt:
man chmod Enter
You can type this command from your command prompt at any time.

An Introduction to Perl
Perl is a scripting language that is widely used on the Internet to create CGI programs. Perl programs are actually text files that are parsed, or run through, by a program called an interpreter. The Perl interpreter is located in the ~/usr/bin directory of your virtual server. This section provides a simple example of a Perl-based CGI.
The following example prints a friendly message to a user’s Web browser. While this example may not be particularly useful, it does serve as an example of how Perl works on your virtual server.
First, login to your virtual server. To ensure that you have the most recent version of the Perl interpreter installed on your virtual server, type the following at the command prompt:
vinstall perl5 Enter
Now, move into the ~/www/cgi-bin directory by typing:
cd ~/www/cgi-bin Enter
Use the pico editor to write the first simple Perl program. Type:
pico example.pl Enter
The pico editor opens a new file called example.pl.
Now, carefully type (or paste) the following lines into the file, including all punctuation and quotes:
#!/usr/bin/perl5
print "Content-type: text/html\n\n";
print "<html>\n";
print "This is my first Perl program!\n";
print "</html>\n";
Now, save the file and exit the pico editor by pressing Ctrl+X, Y, Enter.
Before you can test this sample program, you must change the permissions on the file so that the program can execute. To do so, type:
chmod 755 example.pl Enter
Now, test the program by typing:
virtual perl5 /www/cgi-bin/example.pl Enter
The following output should appear:
Content-type: text/html
<html>
This is my first Perl Program!
</html>
If this is what you see, then you’ve done it right!
Now, try calling this program through your Web browser by going to the following URL, where yourdomain.com is the domain name of your virtual server:
http://www.yourdomain.com/cgi-bin/example.pl
You should see the following in your Web browser:
This is my first Perl Program!
For more information on Perl, type the following from your command prompt:
man perl Enter
You can also consult the many Perl references available online, or wherever computer books are sold.

The virtual server C/C++ Compilers
If you program in C or C++, you can compile your source code into executable CGI programs using the commands gcc or g++.
The following is an example of how to create a simple C-based CGI:
From your command prompt, move into your ~/www/cgi-bin directory by typing the following:
cd ~/www/cgi-bin Enter
Now, open the pico editor by typing:
pico test.c Enter
The pico editor opens and displays an empty file on the screen. Type the following into the editor:
#include <stdio.h>

void main (void)
{
  printf("Content-type: text/html\n\n");
  printf("<HTML><HEAD><TITLE>Test </TITLE></HEAD><BODY>");
  printf("Testing 1,2,3<BR><BR>" );
  printf("</BODY></HTML>\n\n");
}
Press Ctrl+X, Y, Enter to return to the command prompt. You’ve just created a text file containing the C source code for a very simple CGI. Now, compile this source code into an executable CGI program by typing the following:
gcc test.c -o test.cgi Enter
If you typed everything correctly, your command prompt will return. If you made a mistake somewhere along the line, you’ll need to go back and retrace your steps.
Now, test out your CGI by typing the following command:
./test.cgi Enter
You should see the following:
Content-type: text/html

<HTML><HEAD><TITLE>Test</TITLE></HEAD><BODY>Testing 1,2,3<BR><BR></BODY></HTML>
If that’s what you see, then your compile was successful. The final test will be to access this CGI through your Web browser. Try calling this program through your Web browser by pointing it to http://www.yourdomain.com/cgi-bin/test.cgi, where yourdomain.com is the domain name of your virtual server. You should see the following in your Web browser:
Testing 1,2,3
If you see this, you’ve had your first successful encounter with the C compilers found on your virtual server. When using the C compilers that are available on your virtual server, it is important to note that many of the UNIX C libraries are slightly different than the ones you may be familiar with. Therefore, if you can’t find a given function in a specific library, it may be located in a different library. To find the library file that contains a specific C function, type
man function Enter
The function should be the name of the function you would like to use. More information on the gcc compilers is available by typing the following from your command prompt:
man gcc Enter

Debugging Techniques for CGI programs
When writing your own CGI programs, or using a CGI program written by someone else, it’s not uncommon for you to encounter small difficulties. Although the support staff cannot provide programming consulting or debug your CGI programs, we would like to offer a few tips that will assist you in debugging them yourself.
One of the best tools for identifying and debugging CGI programs is your error log. This file keeps track of all of the errors encountered on your Web server. To view the last few lines of your error log at any time, type the following at your command prompt after encountering an error on your Web site:
tail ~/www/logs/error_log Enter
Examining the error log of your virtual server can be very helpful in debugging your CGI program.
Another thing to check for is to make sure that you have made the CGI file executable by using the chmod command. Over 90% of all CGI problems submitted to our Technical Support department are caused by a file not being given proper execute permissions with the chmod command.