CGI

CGI-bin Applications

CGI stands for "Common Gateway Inferface," a fancy name meaning computer programs running on the webserver that can be invoked from a www page at the browser. The "bin" part alludes to the binary executables that result from compiled or assembled programs. It is a bit misleading because cgi's can also be Unix shell scripts or interpreted languages like Perl. CGI scripts need to be saved in ASCII format and uploaded to your server's cgi-bin in ASCII or text format. This is very important.

We don't provide free support for CGI scripts which we did not install on your server. So if you are not already familiar with CGI scripting, you may want to read a book on the subject or find places on the Internet with CGI scripting information. There are many good resources for CGI scripts found on the web. The scripts at Matt's Script Archive found at http://www.worldwidemart.com/scripts/ are very good. Many of our scripts come from here. Another excellent resource is The CGI Resource Index found at http://www.cgi-perl.com/ -- if you are not an expert, look for scripts that are very well documented and come with step-by-step instructions, or contact us for help or installation.

Where to Put CGI-bin Scripts

Put your cgi-bin scripts in the www subdirectory named "cgi-bin". If you have given full POP/FTP/Telnet accounts to other people, each of them will have their own separate cgi-bin inside the main cgi-bin. When they login with their username and password, they will only have access to their own cgi-bin.

Paths to Date, Mail, Perl, etc.

Here are your paths to the common server resources that CGI scripts often require:

Look at the window in your FTP or Telnet client to see whether your site resides on /home/ or /home2/.

Setting Permissions

The following is a simple explanation of file permissions in Unix. To list the access permissions of a file or directory, telnet to your server, then:

cd directoryname

to change the directory until you are either in the directory above the file you are interested in, or above the directory you are checking.

Type: ls -l filename

and you will see what the current permission settings are for that file, along with a bunch of other stuff.

Examples of using chmod:

To change permissions for a file named filename.cgi, you need to chmod the file (change mode). For example, when you type this:

chmod u=rwx,g=rx,o=rx filename.cgi

you've given:
read, execute, and write access to the user (that's you)
read and execute access to the group and
read and execute access to others

Some scripts will tell you to chmod 775 (for example). Doing the above is the same thing as typing chmod 775. You can use either method with our Unix servers. Let me explain:

When using the numeric system, the code for permissions is as follows:

r = 4 w = 2 x = 1 rwx = 7

The first 7 of our chmod775 tells Unix to change the user's permissions to rxw (because r=4 + w=2 + x=1 adds up to 7. The second 7 applies to the group, and the last number 5, refers to others (4+1=5).

When doing an ls -l on the file, telnet always shows the permissions this way:

-rwxr-xr-x

Ignore the first dash, then break up the above into three groups of letters. If there's a dash where a letter should be, it means that there is no permission for those people.

Remember: the first 3 apply to user, the second 3 apply to group, and the third 3 apply to others.

Some FTP clients support changing permissions in a more graphical way. If you have Fetch for the Mac, you have an easy way to change permissions. Go to the file you want to change the permissions on, and highlight it. Under the Remote menu, select Change Permissions. A window will pop up showing the current permissions for the file you had highlighted, as in Figure 3A below. Click on the boxes to change permissions as needed.

Figure 3A

WS_FTP accomplishes the same task as above. Just highlight the file you want to check, and right-click on it. A menu will pop up, then select CHMOD. You will see the window below, as in Figure 3B.

Figure 3B

Appendix

Permission Settings for the scripts provided

Troubleshooting CGI-bin Problems

Below are solutions to some of the more common CGI script problems, in question and answer format.

When I activate my CGI program, I get back a page that says "Internal Server Error. The server encountered an internal error or misconfiguration and was unable to complete your request."

This is generally caused by a problem within the script. Log in via Telnet and test your script in local mode to get a better idea of what the problem is. To do this, go into the directory in which your script is located, then execute the script. To execute the script, you can do it by two ways:

1) Type "perl myscript.pl" (Perl being the language interpreter in this case).

2) Or simply type "myscript.pl" alone, that will work if the first line is well written to indicate the location of Perl.

The first one is useful to see if there's any error IN your script. The second one is useful to test if your "calling line" (the first line of the script) is okay, i.e. if you entered the right location of Perl.

I am being told "File Not Found," or "No Such File or Directory."

Upload your Perl or CGI script in ASCII mode, not binary mode.

When I test my Perl script in local mode (by Telnet), I have the following error: "Literal @domain now requires backslash at myscript.pl line 3, within string. Execution of myscript.pl aborted due to compilation errors."

This is caused by a misinterpretation by Perl. You see, the "@" sign has a special meaning in Perl; it identifies an array (a table of elements). Since it cannot find the array named domain, it generates an error. You should place a backslash (\) before the "@" symbol to tell Perl to see it as a regular symbol, as in an email address.

I am getting the message "POST not implemented."

You are probably using the wrong reference for cgiemail. Use the reference /cgi-bin/cgiemail/mail.txt. Another possibility is that you are pointing to a cgi-bin script that you have not put in your cgi-bin directory. In general, this message really means that the web server is not recognizing the cgi-bin script you are calling as a program. It thinks it is a regular text file.

It's saying I don't have permission to access /

This error message means that you are missing your index.htm file. Note that files that start with a "." are hidden files. To see them, type ls -al. If you wish to FTP this file in, go to the home/yourdomain directory.

SSI (Server Side Includes)

In order for your SSI to work, the web page must have either .sht or .shtml extensions. Sample SSI:
<!--#exec cgi="/cgi-bin/count.cgi"-->
Please note that the url must be relative as shown above. Following would not work:
<!--#exec.cgi="http://youractualdomain.com/cgi-bin/count.cgi"-->
All directives to the server are formatted as SGML comments within the document. This is in case the document should ever find itself in the client's hands unparsed. Each directive has the following format:
<!--#command tag1="value1" tag2="value2" -->
Each command takes different arguments, most only accept one tag at a time. Here is a breakdown of the commands and their associated tags:

• config
  The config directive controls various aspects of the file parsing. There are two valid tags:
  • errmsg controls what message is sent back to the client if an error includes while parsing the document. When an error occurs, it is logged in the server's error log.
  • timefmt gives the server a new format to use when providing dates. This is a string compatible with the strftime library call under most versions of UNIX.
  • sizefmt determines the formatting to be used when displaying the size of a file. Valid choices are bytes, for a formatted byte count (formatted as 1,234,567), or abbrev for an abbreviated version displaying the number of kilobytes or megabytes the file occupies.
• include
  include will insert the text of a document into the parsed document. Any included file is subject to the usual access control. This command accepts two tags:
  • virtual gives a virtual path to a document on the server. You must access a normal file this way, you cannot access a CGI script in this fashion. You can, however, access another parsed document.
  • file gives a pathname relative to the current directory. ../ cannot be used in this pathname, nor can absolute paths be used. As above, you can send other parsed documents, but you cannot send CGI scripts.
• echo prints the value of one of the include variables (defined below). Any dates are printed subject to the currently configured timefmt. The only valid tag to this command is var, whose value is the name of the variable you wish to echo.
• fsize prints the size of the specified file. Valid tags are the same as with the include command. The resulting format of this command is subject to the sizefmt parameter to the config command.
• flastmod prints the last modification date of the specified file, subject to the formatting preference given by the timefmt parameter to config. Valid tags are the same as with the include command.
• exec executes a given shell command or CGI script. It must be activated to be used. Valid tags are:
  • cmd will execute the given string using /bin/sh. All of the variables defined below are defined, and can be used in the command.
  • cgi will execute the given virtual path to a CGI script and include its output. The server does not perform error checking to make sure your script didn't output horrible things like a GIF, so be careful. It will, however, interpret any URL Location: header and translate it into an HTML anchor.

• DOCUMENT_NAME: The current filename.
• DOCUMENT_URI: The virtual path to this document (such as /docs/tutorials/foo.shtml).
• QUERY_STRING_UNESCAPED: The unescaped version of any search query the client sent, with all shell-special characters escaped with \.
• DATE_LOCAL: The current date, local time zone. Subject to the timefmt parameter to the config command.
• DATE_GMT: Same as DATE_LOCAL but in Greenwich mean time.
• LAST_MODIFIED: The last modification date of the current document. Subject to timefmt like the others.

MajorCool

MajorCool is a web-based interface to Majordomo allowing users to add and delete themselves from lists and manage lists that they own.

To access this program please enter http://domain.com/cgi-bin/majorcool into your browser.

Should you require help using the program please hit the "Help" button at the bottom of the main page. The program is pretty self-explanatory with just 3 buttons at the top:

1. BROWSE-
You can search for lists that contain a certain email address or contain a specific string in their names. You can also get info on any list such as the owner's email address, the info file that is sent to new subscribers, etc. You can even see the entire list of subscribers for each list. All of this part is completely public, you don't need any password.

2. MODIFY-
Here is where a list owner can enter their admin password to change anything about the list: add or delete subscribers, change the config file, change the description and info file associated with the list, etc. However they cannot delete the list entirely, or create new lists, or rename any lists.

3. PREFS-
This is no big deal, just controls the onscreen display of MajorCool such as changing the layout of the features.

Your first PHP-enabled page

First to view the current version of PHP which is installed on your domain or to see the most common settings please direct your browser to http://www.youractualdomain.com/phpinfo.php

Create a file named hello.php and in it put the following lines:

<html><head><title>PHP Test</title></head>
<body><?php echo "Hello World<p>"; ?></body></html>

The colours you see are just a visual aid to make it easier to see the PHP tags and the different parts of a PHP expression. Note also that this is not like a CGI script. The file does not need to be executable or special in any way. Think of it as a normal HTML file which happens to have a set of special tags available to you that do a lot of interesting things.

This program is extremely simple and you really didn't need to use PHP to create a page like this. All it does is display: Hello World

If you tried this example and it didn't output anything, chances are that the server you are on does not have PHP enabled. Ask your administrator to enable it for you.

The point of the example is to show the special PHP tag format. In this example we used . You may jump in and out of PHP mode in an HTML file like this all you want.

Something Useful

Let's do something a bit more useful now. We are going to check what sort of browser the person viewing the page is using. In order to do that we check the user agent string that the browser sends as part of its request. This information is stored in a variable. Variables always start with a dollar-sign in PHP. The variable we are interested in is $HTTP_USER_AGENT. To display this variable we can simply do:

<?php echo $HTTP_USER_AGENT; ?>

For the browser that you are using right now to view this page, this displays:

Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0; DigExt)

There are many other variables that are automatically set by your web server. You can get a complete list of them by creating a file that looks like this:

<?php phpinfo(); ?> Then load up this file in your browser and you will see a page full of information about PHP along with a list of all the variables available to you.

You can put multiple PHP statements inside a PHP tag and create little blocks of code that do more than just a single echo. For example, if we wanted to check for Internet Explorer we could do something like this:

<?php
if(strstr($HTTP_USER_AGENT,"MSIE")) {
echo "You are using Internet Explorer<br>";
}
?>

Here we introduce a couple of new concepts. We have an "if" statement. If you are familiar with the basic syntax used by the C language this should look logical to you. If you don't know enough C or some other language where the syntax used above is used, you should probably pick up any introductory C book and read the first couple of chapters. All the tricky string and memory manipulation issues you have to deal with in C have been eliminated in PHP, but the basic syntax remains.

The second concept we introduced was the strstr() function call. strstr() is a function built into PHP which searches a string for another string. In this case we are looking for "MSIE" inside $HTTP_USER_AGENT. If the string is found the function returns true and if it isn't, it returns false. If it returns true the following statement is executed.

We can take this a step further and show how you can jump in and out of PHP mode even in the middle of a PHP block:

<?php
if(strstr($HTTP_USER_AGENT,"MSIE")) {
?>
<center><b>You are using Internet Explorer</b></center>
<?
} else {
?>
<center><b>You are not using Internet Explorer</b></center>
}
?>

Instead of using a PHP echo statement to output something, we jumped out of PHP mode and just sent straight HTML. The important and powerful point to note here is that the logical flow of the script remain intact. Only one of the HTML blocks will end up getting sent to the viewer. Running this script right now results in:

You are using Internet Explorer

Dealing with Forms

One of the most powerful features of PHP is the way it handles HTML forms. The basic concept that is important to understand is that any form element in a form will automatically result in a variable with the same name as the element being created on the target page. This probably sounds confusing, so here is a simple example. Assume you have a page with a form like this on it:

<form action="action.php" method="post">
Your name: <input type="text" name="name">
You age: <input type="text" name="age">
<input type="submit"></form>

There is nothing special about this form. It is a straight HTML form with no special tags of any kind. When the user fills in this form and hits the submit button, the action.php page is called. In this file you would have something like this:

Hi <?php echo $name; ?>.
You are <?php echo $age; ?> years old.


It should be obvious what this does. There is nothing more to it. The $name and $age variables are automatically set for you by PHP.