SHARE

How to Place a CGI File with UNIX

Written By

Jan 4, 2005

10 minute read

Use these to jump around or read it all…

[What You Have To Be Able To Do]
[Section 1: A Place for the CGI]
[Making the CGI Directory]
[Section 2: The CGI and its HTML Document Buddy]
[Altering the HTML Document]
[Altering the CGI Script]
[Section 3: Send Them to Your Server]
[Section 4: “Turn On” CGI-BIN and Script]
[Possible Error Codes]

If you follow this tutorial, you will be guided through the steps to place a guestbook CGI onto your system. The CGI will, hopefully, work just the same as my guestbookCGI, mainly because it’s the same one. That makes sense. I will tell you though, it took me about two weeks to figure all this out. Placing a CGI is an involved process that requires your doing some configuration at the server level. It’s a little scary at first, but stick with me. You’ll get the hang of it soon enough.

This tutorial deals with UNIX servers and UNIX commands for configuration. The vast majority of Internet servers are UNIX-based. If your server does not use UNIX, consult your technician for additional instructions.

What You Have To Be Able To Do
Section 1: A Place for the CGI
Making the CGI Directory
Section 2: The CGI and Its HTML Document Buddy
Altering the HTML Document

What You Have To Be Able To Do

In order to place your own CGI, you must be able to do a few things with your Internet account. You must be able to:

Telnet into the system
Create directories
Change directory modifications

You must be able to do all of the above. If you can’t, you will not be able to install this guestbook CGI. You can either check with your server technician or just try following along. If you are denied any of the above items, the server will tell you soon enough.

Telnet
(Click for a short tutorial regarding telnet)

For those of you who don’t know, “Telnet” is another way to attach to your Internet server. Using telnet you are attaching directly to the server “shell.” This is where you can enter commands that directly affect the UNIX settings.

When you signed up with your Internet Service Provider (ISP) you should have gotten a telnet program. If you didn’t, you still may be in luck. Windows-based computers have telnet programs already installed. In versions 3.x, it’s named “Terminal.” In W95, it’s named “Telnet.” Both can be found under the Accessories section.

Whatever telnet you are using, they all work the same way. Open the program, choose to connect, and type in your WWW address without the http://.

You’re good to go. Keep following along….

Section 1: A Place for the CGI

Okay, here we go. First off, you will need to telnet into your server. Upon connecting, you will be asked for your user name and password. Put them in. Usually you will get a few welcome greeting messages and then a prompt of some sort will pop up. I have worked with seven different servers and the prompt has been different on all seven. It should look something like this:

telnet%

Does that look familiar? If not, don’t worry, you will see the blinking cursor where you will enter information.

Your Public HTML Directory

When you send files over to your server, for them to be seen by the entire Internet community, you send the files to a directory. It has a name. You need to find that name. Most of the time the name is something like “public-html” or “www” or “default.”
For the sake of demonstration, we’ll say the directory’s name is WWW. That’s the shortest name and thus easiest to write a couple hundred more times. Depending on how your system is set up, you will either be in that directory when you telnet in, or you will be one above it. The smart money is that you are one above it. Type this at the prompt:

telnet% ls

(Please note, I am using “telnet% to represent the prompt. Your prompt may look different)

Hit return. You will get back a listing (that’s what “ls” means) of everything in that directory. If you see all the names of your HTML documents that Internet viewers can access, then you are already in the WWW directory. If you see the name of your Internet directory (I called it WWW above), then you are one above the directory. This is probably where most of you are. This is where I want you to be, one above your WWW directory.
You need to get one level above your WWW directory if you’re not already. Do that by typing this at the prompt:

telnet% cd ..(two dots)

“cd” stands for “change directory.” That’s what you just did. Now put in the “ls” command again and you should see your WWW directory.

Making the CGI Directory

This may already have been done for you. You should check that first. If when you typed one of the “ls” commands above you saw a cgi-bin, you need not do this.

Now you will need to create a special directory for your CGIs. No, they cannot sit where all the other files are located. Why will become clear in a moment. I suggest you name the directory you are about to create “cgi-bin” as that is what I am going to call it the rest of the way through this tutorial. Please notice that is a hyphen between the “cgi” and the “bin.” You will make the directory by typing this:

telnet% mkdir cgi-bin

If you get another prompt and no error messages, you did it. This is the first point at which you may be told you do not have the ability to place a CGI.
If you’d like to see your work, type this:

telnet% cd ls

You should see your cgi-bin. However, some servers are set up that as soon as you create a new directory, you are then put into it. I had a school server do this once. It’s actually helpful if you want to place files right away. If you do the list command above and see nothing, you’re probably in the directory you just created. Type this:

telnet% cd ..(those two dots again)

…and then this:

telnet% ls

You should see the new directory “cgi-bin.” Log out of telnet by typing “logout” at the prompt.

Section 2: The CGI and Its HTML Document Buddy

Sounds like a new movie doesn’t it? Below are links to two items. The CGI and the HTML document that will use it. Grab them both. They are in text form so they should display as just text. Some browsers will display the HTML document as a form, though. If that happens, just download it.

Here is the CGI script
Here is the HTML document

You will need to save the CGI script as “gb.cgi” or with whatever suffix your server requires. Some servers use “.pl.” You will need to save the HTML document as “gb.html.” Save them both as “source” so they keep their shape.

Altering the HTML Document

You will need to make a few changes to the HTML document so it knows where the CGI is located. Look at this line:

This is the line that attaches the output of this form to the CGI. You will need to change that line so that the output is directed at the new cgi-bin you created in Section 1. This is fairly easy. What you do is take your full WWWeb address and add the new cgi-bin, a slash, and then the name of the CGI file. For instance:

Your address is:
http://www.server.com/~fred

The Action statement above would read:
http://www.server.com/~fred/cgi-bin/gb.cgi

Get it?

You are now done with altering the HTML document. Remember that these two documents were written for each other. They work together. You can change the text or add graphics to the HTML document, but you cannot change the FORM commands at all. If you attempt to add a third text box or another radio button, it won’t work.

Altering the CGI Script

You are concerned about two things here: The path to PERL and the path to Sendmail.

The path to PERL is the very top line. It looks like this:

#!/usr/bin/perl

Contact your server technician and ask him/her the path to PERL. You see, the CGI does not work all by itself. It requires the PERL program to run correctly. This first line is telling the CGI script where the PERL program is on the server. Yes, your server will have PERL.
Basically what happens is that the guestbook information is sent to the CGI. The CGI and the information is loaded into the PERL program, or “shell.” The data is manipulated then returned to your mailbox.

How the mail gets to your mailbox is the Sendmail question. Look at the CGI script about 20 lines down. The line reads:

open(MESSAGE,”| /usr/lib/sendmail -t”);

That is the path that the server will use in order to find a little program that will send the mail. It needs to be correct to your server.

For the most part, these paths will be correct. Most servers are set up basically the same way, so you may not need to change anything. Then again, you may need to change them both.

Section 3: Send Them To Your Server

You will now need to use your FTP program. Attach to your site like you would any other time you were going to transfer files. Send the HTML document in where the other HTML documents are. Do not put the HTML document and the CGI in the same directory. They will not work that way. Remember you made a path to the CGI? That’s because you will place the CGI in the cgi-bin directory.
Depending on how your FTP is set up, you should see the cgi-bin directory in your window as you are transferring the HTML document. Click on the cgi-bin directory to open it, and send the CGI.

SEND THE CGI SCRIPT AS ASCII

Yes, that’s correct. Send it as ascii text. Do not send it as binary. It is written to be sent as ascii text. There. I said it three times so you know it’s not a typo. Log out of the FTP program.

Section 4: “Turn On” the CGI-BIN and Script

Step One

Log back into your server using telnet. Again, get to the directory that contains your HTML documents. Follow the steps in Section 1 if you need to. Type this:

telnet% chmod a+xr cgi-bin

“CHMOD” stands for “Change Modification.” If you get no errors, you did it. You have told the server that this specific directory will contain CGI executable files. Don’t log out yet. There is still one more step. But first….

Possible Error Codes

cgi-bin not found
You are in the wrong place. Make sure you’re in the directory one above your cgi-bin. You should be able to do an “ls” commands and see the cgi-bin sitting there.
access not allowed (or words to that effect)
That means you may not have the ability to turn on the directory. Try the command above again, except this time substitute the number 775 for the a+xr. You may be allowed to do that. If you still get an error, you need to request permission to do chmod commands from your home computer.

Step Two

Open up your cgi-bin directory by typing:

telnet% cd cgi-bin

Turn on the CGI itself by typing:

telnet% chmod a+xr gb.cgi

You may get the error codes above again. Make sure you’re in the correct place. You should be able to do another “ls” command and see the CGI file. Try replacing the a+rw with the number 775 if it doesn’t allow you to change the modification.

Log out of telnet.

That Should Do It

If all the paths are correct and you have “turned on” all the correct files, you should be able to open your browser, log in to the guestbook HTML document, and run the CGI.
You might get a service error first time through. Read it. It will tell you the problem. The most common problems are that it cannot find PERL, it cannot find a file due to incorrect paths or file names, or your server doesn’t support “POST” capabilities. The first two can be repaired. The third cannot without contacting your server technician.

Good luck! Please understand that placing a CGI is very difficult and there are only about a million little things that can go wrong along the way. Take your time, go slow, and make sure the paths and file names are correct. It took me two weeks to get this working. See if you can beat my record.

One More Option (ASP)

Everybody loves putting together a great guestbook, and through the use of ASP, you can get that all-important secondary page that pops up right after the user submits. But more than that, you get to configure the thank-you page to include the user’s name and other responses depending on what the user entered into the guestbook form. Want to try it? Go here!