Your First CGI Script

Learn how to write a simple CGI script, then upload it to your server and test it, with this easy-to-follow tutorial.

In this tutorial we're going to show you how to write a very simple CGI script. We'll also show you how to upload the script to your server, and get the script running.

Once you've mastered the technique of uploading this CGI script, you can use the same technique to install other CGI scripts too!

A nice simple script

The CGI script we're going to write will display a simple HTML page containing the text "Hello, world!". Although this is a very simple example, we'll be showing you some important concepts along the way.

You'll probably want to create this CGI script as you're reading the tutorial. A CGI script is simply a plain text file, so you can create the script using any text editor.

If you're using Windows, you can use Notepad or WordPad (you'll find these in the Accessories menu). Mac users can use text editors such as TextEdit or TextWrangler.

Fire up your text editor now, and then you can enter the script as you go along!

The path to Perl

As Perl is an interpreted language, every Perl CGI script needs to contain the location of the Perl interpreter on the server. This is so that the server can find the Perl interpreter when it's trying to run the Perl script. The Perl interpreter is the program that reads your Perl script and carries out the commands in the script.

Usually, you specify the location of the Perl interpreter (often called the "path to Perl") on the first line of the script, as follows:


#!/usr/bin/perl

In the above example, the Perl interpreter is called perl, and it can be found in the directory /usr/bin/. (If you're used to Windows, then note that this is the UNIX directory format; it's similar to, for example, C:\Program Files\ on Windows.)

Usually, the Perl interpreter on the server can be found at /usr/bin/perl, so this is a pretty safe bet in most cases. However, it's worth checking with your Web hosting company if you're not sure of the correct path. Other common paths include:


/usr/sbin/perl
/usr/local/bin/perl
/usr/bin/perl5
/usr/local/bin/perl5

Note for Windows servers

Perl on Windows doesn't need to look at the first line of the Perl script to find the Perl interpreter, so you can miss this line out if you're running on Windows. Often it's a good idea to just leave the "#!/usr/bin/perl" in though, so your script will work if you move it to a non-Windows server at some point!

The Content-type header

Before displaying our Web page to the visitor, we need to tell the visitor's browser what type of content we are sending them. We do this using the Content-type HTTP header.

HTTP headers are simply lines of text that are sent to the browser before the main content. The browser doesn't display these headers, but reads them in order to work out what to do with the content, or how to display it.

The Content-type header is nearly always the first thing that your CGI script should output, so we'll output it now in our script.

To output stuff in Perl, we use the print statement. Anything printed by the print statement will be sent, via the server, to the visitor's browser.

So here's the next line of our Perl script:


print "Content-type: text/html\n\n";

With this line, we're telling Perl to send the Content-type header to the browser. The content type we're specifying is "text/html", which means the content is of type "text", and subtype "HTML".

At the end of the line you'll notice the "\n\n". The characters "\n" tell Perl to print a new line (like pressing the "Enter" key in a word processor). There should always be 2 newlines between the HTTP headers and the main content, which is why we print "\n\n" after the header.

Printing the page

Finally, we can print out the actual HTML that makes up our simple Web page. We do this with the following lines of Perl:


print <<END_HTML;
<html>
<head></head>
<body>Hello, World!</body>
</html>
END_HTML

The first line, "print <<END_HTML", tells Perl to print out everything that follows until it finds the line beginning with END_HTML. This is an easy way to print out lots of lines at once.

The finished script

Your finished script should look like this:


#!/usr/bin/perl

print "Content-type: text/html\n\n";

print <<END_HTML;
<html>
<head></head>
<body>Hello, World!</body>
</html>
END_HTML

Save your script to a file on your PC - call it something like hello.cgi.

Uploading the script

Now we're ready to upload our CGI script to our Web server and test it.

You upload CGI scripts in the same way that you upload your Web pages and images. Usually you'll use FTP to do this. If you're not familiar with FTP, you may like to read our FTP tutorials first, then come back to this section.

There is usually a special folder within your Web site for storing CGI scripts. The server knows that any files in this folder are to be treated as CGI scripts, and executed, rather than displayed as if they were Web pages.

This folder is usually called cgi-bin or cgi-local. If you can't see a folder with this (or a similar) name, then you may just be able to put CGI scripts anywhere in your website - check with your hosting company.

Using your FTP software, connect to your server, change to your cgi-bin or cgi-local folder, and upload the hello.cgi file to this folder.

It is very important that you upload your file in ASCII mode (sometimes called text mode). This is because text file formats differ between Windows, Mac and Unix computers, so you may run into problems if you upload, say, a CGI script written on a Windows PC to a UNIX web server!

Setting permissions

Once you've uploaded your new CGI script, you need to give the file execute permission. This is so that the Web server can run the script. For general information on file permissions, check out our Understanding Permissions tutorial.

Using your FTP software, set the permissions of your CGI script to 755 (or rwxr-xr-x). This will allow your script to be executed by your web server.

Note for Windows servers

If your web server runs on Windows, then you probably don't need to set permissions using your FTP software (in fact it probably won't let you). If you uploaded the file to your cgi-bin folder then it will probably be given the correct permissions automatically. If not, then ask your Web hosting company for advice - you may have a Web-based control panel for your server that lets you set the correct permissions.

Testing the script

You're now ready to test your CGI script! In your browser's address bar, type the URL of your CGI script. This will be the main URL of your site, followed by the path to your CGI script, e.g. cgi-bin/hello.cgi.

For example, if your site's main URL was http://www.elated.com/, then the URL of your CGI script might be:

http://www.elated.com/cgi-bin/hello.cgi

Once you've entered the script's URL in the address bar, press the Enter key. If all goes well, your script should run and then produce the following output in the browser window:


Hello, World!

If it does, then congratulations! You've just created and installed your very own CGI script!

If you get the dreaded Internal Server Error message, don't panic! It's probably a simple problem. Make sure your path to Perl is correct, and that you uploaded your file in ASCII format and set the correct permissions, as described above. If you still have problems, check that your script doesn't have any typos in, and that it looks exactly like the version in our "The finished script" section above.

If your script still doesn't work, there may be some configuration problem with your server - ask your web hosting company's technical support staff for help.

Follow Elated

Related articles

Responses to this article

There are no responses yet.

Post a response

Want to add a comment, or ask a question about this article? Post a response.

To post responses you need to be a member. Not a member yet? Signing up is free, easy and only takes a minute. Sign up now.

Top of Page