Ada's Introduction to CGI & SSI
This tutorial written by Ada Wittman.
I began studying CGI after a school project on creating a web site for my school. I realized then that CGI is an inescapable part of any cool and interactive web site. You want a message forum for your site? How about a feedback form, or a counter? As I found out, the only way to make these things happen is through CGI scripts. Make no mistake, CGI is not the only language when it comes to making your site cool and interactive (DHTML is another), but it's definitely the most important and one the web can't live without. After looking through this site, you'll have a much better understanding of what CGI is in general, and also how to debug and install your own CGI scripts.
Overview of CGI
So what exactly is CGI? CGI stands for Common Gateway Interface. Any script can be called a CGI script as long as it's installed on the server end. However, the majority of CGI scripts are written in Perl (with C being the next most common). If you want to write your own CGI scripts, you'll need to learn Perl. It is exactly the fact that CGI is installed on the server end that makes it able to do all those amazing things such submit a form, create a guest book or forum, keep track of and rotate your ads etc. The server has the capability to redirect data to any email address, persist data, dynamically serve out different content to the browser, among many other things that the browser alone simply cannot do.
-What do I need to run CGI scripts?
Your web host must allow you access to a CGI-BIN. Most paid web hosts comes equip with a CGI-BIN, but there are only a few free hosts that packs in that same feature to their services.
-Ok, I know I have access to a CGI-BIN...now what?
There are tons of free, quality CGI scripts on the internet, and all you have to do is grab and learn how to install them onto your site. As daunting as installing a CGI script on your server may sound, it's actually quite easy, as I found out. Regardless of the script you're attempting to installing, the process is pretty much the same. I'll walk you through this process right now!
-What are the things I need to know in order to install CGI Scripts?
Let's see... Environmental variables, regular expressions, scalar and array variables, and SSI. Ok, I'm just kidding. The fact is, you don't even need to know any programming to have a complete CGI program up and running on your site. In generally, you only need to know and understand the following, regardless of what CGI script you're trying to install:
- How to use a text editor (such as
Notepad)
Ok, this should be a given to everyone here. But how does a text editor fit in with installing a CGI script? Everything! First and foremost, it's important to understand that CGI scripts are really no different than normal text files (except the former uses a file extension of .pl or .cgi). Both are written in ASCII format, and can be opened and viewed using any text editor. Now, in order to install a CGI script, you'll need to configure it. That's where the text editor comes in. Use it to open and configure your CGI script.
. - The path to the Perl compiler on your
web host
Once opened, all hell breaks lose (just kidding). Take a look at the very first line of the script...it should look something like this:
#!/usr/bin/perl
Don't panic if your first line looks a different than the above...that's perfectly fine. The thing to understand is just what this line of mumbo jumbo is, and what you need to change (if at all) of it. #!/usr/bin/perl refers to the path of the Perl compiler on your server. It always appears as the first line in your perl script. This line needs to refer to the perl compiler on your server. If you're lucky, you won't even need to change a thing, as #!/usr/bin/perl actually correctly refers to the compiler on most servers. Another likely candidate is #!/usr/local/bin/perl. The point here is to find out for sure the path to the Perl compiler on your server. How do you do that? You could find this info on your own by telneting to your server (assuming you have telnet access), and type "whereis perl", or, let your mouth do the work, and simply ask your web host provider: "What's the path to the perl compiler on this darn machine?" Either way works.
. - The path to your site
And while you're grilling your web host provider on where the Perl compiler is, you might as well throw in where your site is as well. Uh? Not the URL of your site (I sure hope you know that), but the path to it from your server's standpoint. Think of it like this. On the WWW, your site's address may be http://mysite.com/index.html. But on your hard drive where your site is stored locally, it may be referenced as file:///c|/mysite/index.html What you have to find out now is the path to your site as seen from the server your site's on point of view. An example would may look something like:
/usr/local/etc/httpd/sites/mysite.com
Please don't try copying the above line and changing a few things in hopes it'll match the path to your own site. Unlike the path to your CGI compiler, the path to a site is completely different from site to site, and yours is a unique string resembling nothing like the above. To find out your site's path in the server, ask your host provider, or check the CGI help section of your web host's site (they usually have such a section).
. - Some other helpful things to know
There are a few other things you may need to know, depending on the CGI program you'll trying to install. Your program may ask you the path of your server's mail program (ie: /usr/lib/sendmail), or your CGI-BIN (ie: /usr/local/etc/httpd/sites/mysite.com/cgi-bin), information you can obtain easily simply by opening your mouth and interrogating your web host provider. Before you do that, however, check the company's web site.
Once you've figured all these things out, it's a matter of opening the cgi file using your text editor, and filling in the blanks whenever the program says so. It may say "change the below to the path of your CGI-BIN." What do you do then? Put in /usr/local/etc/httpd/sites/mysite.com/cgi-bin, or whatever your CGI-BIN's path may be.
-Uploading the script and finalizing the deal
Ok, you're getting dangerously close to successfully getting a CGI script up and running. All that's left now is uploading the script onto your server. The basic idea is to use a FTP program (such as WSFTP) and upload the script(s) into your CGI-BIN directory. There are a few things, however, that you should take note of:
- Always upload CGI scripts in ASCII mode
(Not binary)
By default, your FTP program always uploads files in binary mode. That's fine for most files -except CGI files. CGI files must be uploaded in ASCII format, or don't expect them to work. Your FTP program should allow you to change between binary and ASCII mode (In WSFTP, this option appears at the the bottom of the screen). Always switch to ASCII mode before uploading your CGI scripts.
. - After uploading the script, set it's
permission
You're not quite out of the woods (but almost). After uploading, you need to set it's permission. You see, since a CGI script is installed on the server end, in the wrong hands, it could cause damage to your site and possibility even the server itself. That's why you need to set permissions on your CGI script before they will be allowed to run. Permission can be set directly using your FTP program. In WSFTP, this is how it's done: Right click the CGI script, and select "chmod". Up pops a permission box:
The most common permission settings are chmod 755, and chmod 777. To chmod 755 a CGI file, choose the following settings on the file, and press Ok:
chmod 755
.
To chmod 777 a file, do this instead:
chmod 777
.
Check the documentation inside the script to see whether to chmod 775 or chmod 777 the file. If it asks for some strange permission setting like chmod 664, chmod it 775 anyways. Usually, it doesn't make all that much of a difference.
-Now what?
Ok, you've configured the script, saved the changes, and successfully uploaded the script into the appropriate directory. Now what? Wait for the almighty CGI script to perform it's magic! Ya, in a million years. Depending on the script and it's function, you either have to all it via the browser (by typing in the url to the script, http://mysite.com/cgi-bin/test.pl, for example), or, if it's a form related script, add that URL to the action attribute of the form. Consult the documentation inside that particular script to see exactly what you should do to awaken it.
As you can see, installing and getting CGI script to work for you doesn't exactly require a degree in nuclear science. Anyone can do it!
- Introduction to CGI installation
- Introduction to CGI Programming
- Introduction to SSI
