|
|
CGI Configuration |
| Table of Contents | |||||||||||||
|
|||||||||||||
| How to upload your CGIs | |||||||||||||
| You will need to upload your CGI program to your server before you can even test to see if it works. To do this, follow the same procedure that you used to upload your home page. That is, use your FTP program. There are also some programs available to test the script on your machine such as WINPERL or MACPERL which is freeware and available from www.shareware.com | |||||||||||||
|
|||||||||||||
|
|||||||||||||
| Setting File Permissions | |||||||||||||
| Q: What are file permissions? | |||||||||||||
|
Files on our system can have different permissions which allow different levels of access to the file by different people. Those people can be classified into three groups, user, group, and other. There are three different file access attributes for each classification of individual, read, write, and execute. You can look at it like this:
Notice the bold letters in the table. R, W and X. These, standing for Read,Write,eXecute, form the three letter abbreviation to describe the allowed access for that particular classification of user. The classifications are in order, User, Group, Other. So a file with permission rwx------ grants full access to the user or owner of the file only, while a file with permission ---rwx--- grants access to a specific group of users, while a file with permissions ------rwx grants access to all other users. This is one of the harder concepts to grasp in Unix file permissions. |
|||||||||||||
| Q: How do I get the numeric format (or mode) of a file based on its permissions? | |||||||||||||
| This letter trio, the rwx, can be specified in numeric format. It's a binary format. | |||||||||||||
|
|||||||||||||
| Setting the permissions for the file is as simple as adding up the numbers. So to set the permissions for a file, you need to specify three numbers. One for the User, one for the Group, and one for Other. Remember, add the numbers. If you want the User to have full permission, then 4+2+1 = 7. If you want the Group to have Read only permission, then the number is 4. If you want all Others to have Read and Execute permissions, then 4+1 = 5. So the mode of the entire file would be 745. The mode (total permissions) of the file is very important. | |||||||||||||
| Q: How do I know what mode to set my CGI to? | |||||||||||||
| Well, now that you know how it works, let's put it to good use. Your CGI isn't going to be executed by a specific user, nor a specific group. It's going to be run by some http daemon on some operating system on some computer. In short, it's going to be run by people accessing your web page. Those people can be anybody. They're the other people. Get it? You need to be concerned with the file permissions for other for your CGI. If it can't be executed by other, then it can't be run as a CGI. Plain and simple. Therefore, any CGIs need to have the other's eXecutable permission set. PERL scripts won't be eXecutable if they can't be read. So unless your CGI is compiled, it also needs to be readable by other. | |||||||||||||
| We will make the entire permission for the CGI 755, so that you, as the user, can still write changes to the file, but group and other will only be able to Read and eXecute it. This applies to most CGIs. But let's say that your CGI needs to write to a file. What then? Well, the CGI is running as other, right? So the file that it's writing to must be writable to by other. You can set the permission for such a file to 777. If you just upload your files to your cgi-local directory, the permissions are set automatically to 755. | |||||||||||||
| Q: How do I set or change the mode of my CGI? | |||||||||||||
|
To actually set the permissions on the file, you need to use an FTP program that supports the changing of file permissions. Both Fetch for Macintosh and WS_FTP for Windows support the changing of permissions of remote files. However, if you don't have one of these programs, and if you have Unix shell access to the file, you can set the file's permissions with the chmod command. The format is: chmod mode filename For example, to set a CGI by the name of script.cgi to have the mode of 755, you would type chmod 755 script.cgi |
|||||||||||||
| Q: How do I set or change the mode of my CGI if I don't have shell access? | |||||||||||||
|
Most of the latest FTP programs allow you to change file permissions. You'll need to look into the features of your specific FTP program to determine whether or not this function is available. Both Fetch for Macintosh and WS_FTP for Windows support the changing of permissions of remote files. WS_FTP program for Windows uses the right mouse button to access the FTP commands. You would choose the SITE command and enter: chmod 755 filename.cgi If your FTP program does not support the changing of file permissions, you need to use a text based FTP client, such as those available on any Windows95/NT or Unix machine. Use the command format: quote site chmod mode filename |
|||||||||||||
| File Naming and Placement Conventions | |||||||||||||
|
Note that some CGI tutorials or scripts will tell you that you need to install the script in the system's cgi-bin directory. This is not the case with SUNNY OASIS. You do not need to keep your CGIs in a special directory of any kind in order for them to be recognized as CGIs, although the cgi-local directory is especially set up for this and will automatically change your file permissions as required. Our server is configured to recognize any file that ends in .cgi as being an executable CGI. Many scripts come with the file extension of .pl. As with many CGI scripts, these are just PERL scripts. However, with the extension of .pl, the script WILL NOT RUN, but will rather just display on the screen as plain text. If your CGI does not already end in .cgi, you can rename it using your FTP program. The equivalent unix script under telnet access would be: mv myscript.pl myscript.cgi This stands for move myscript.pl to myscript.cgi. Or you can rename it on your home machine and re-upload it. |
|||||||||||||
|
If your web page is going to make use of SSI, the filename of the page must end in .shtml. So if the filename is home.htm, then any SSIs in it will not work. For more information on SSI, please visit our SSI page |
|||||||||||||
| Attack of the CTRL-Ms | |||||||||||||
|
|||||||||||||
|
A CTRL-M, or control m, looks like this: ^M. Unix text files and other text files differ from each other slightly. Unix can interpret the Carriage Return/Line Feeds, or CR/LFs, or anywhere you pressed ENTER, in non-Unix text files as a ^M. This is very bad in the world of CGI, especially where PERL is concerned. The PERL interpreter will not be able to properly read your script if it has ^Ms in it. |
|||||||||||||
| Q: How do I prevent Unix from interpreting the CR/LF as a ^M? | |||||||||||||
|
|
|||||||||||||
| How to test your CGIs | |||||||||||||
| If possible, you should try to test your CGI on your own machine before you try it from a web page. If something goes wrong with your script, it can, for example, get stuck in an endless loop and comsume much of the server resources. Better to be safe by testing it first. You can also use the PERL script checker available in your control panel. | |||||||||||||
|
It is not always easy to test your script from a command line. Many scripts will not execute at all if they don't recieve a QUERY_STRING environment variable. In order to test these scripts from the shell, you need telnet access to set a sample QUERY_STRING in the Unix Shell. If you have telnet access, which most accounts do not, type set QUERY_STRING <string>, where <string> is an example of a URL_ENCODED string that might be passed from your form. Most scripts available for download on the net are not typically problematic. In fact, the only scripts that tend to cause problems are those that contain loops. Programming loops are dangerous because careless programmers can make it possible for the loop to never exit. If a loop can never find an exit condition, it will loop forever. Since you can't kill a CGI that's stuck in a loop, the CGI can begin to consume resources, and eventually cause problems. If your CGI uses loops of any kind, make certain there is an exit condition that will eventually satisfy the termination of the loop! |
|||||||||||||
|
|||||||||||||
| Q: How do I test my script from the Unix shell? | |||||||||||||
|
If your script stops on its own, examine its output for errors and proceed with debugging your script. If your script doesn't seem to be stopping, you had better terminate it with the kill command:
|
|||||||||||||