CGI FAQ for The Cobalt RaQ

Introduction

This FAQ is provided "as is" and we take no responsibility for damages, misconfigurations etc. Do all procedures and actions described in this text on your own risk !

What is a RaQ ?

What is a CGI Script ?

A CGI program can be written in most languages, like C, C++, Perl, Python, or even as shell scripts. One of the most common scripting languages to write CGI scripts is Perl (http://www.perl.com). As most of the CGI programs available on the web are written in Perl, this FAQ is Perl orientated.

What is CGIWRAP ?

How Do I Run CGI/Perl Scripts ?

How to Edit a Perl Script ?

There are many free editors available for Windows users, one of which is

• Arachnophilia Care-Ware (check the Readme for that) by Paul Lutus.
  
• Linux / RaQ On our RaQ, the two included editors are vi (excellent, but hard to learn; try with some dummy files first), and pico, an editor that behaves similarto DOS Edit; it is a fine editor for novice Linux users.
  • If you use pico, it with the -w option (type : pico -w filename) to disable word-wrap. Some scripts will not tolerate word wrap in command sequences.

Perl Syntax

• If you enter an email adress, be sure to mask the '@' with a leading backslash.
  It has to look like that : me\@domain.tld
  
• Do not modify the script unless you know exactly what you`re doing. If the script complains about compilation or syntax errors, check first if you have not deleted one of the following characters :
  • Each command line must end with a ';'
    (error message : compilation error)
  • All brackets must be closed, unintendendly you could have deleted a '}'
    (error message : missing right bracket)

• What are the required paths ?
  • The following variables are the most common ones that you have to insert in a cgi script
    Perl 5 Location (that is always the first line in every perl script):
    #!/usr/bin/perl
    
  • * Sendmail Location :
    /usr/sbin/sendmail
  • Script Url :
    http://domain.tld/scriptname
    or, if you have created a /cgi-bin :
    http://domain.tld/cgi-bin/scriptname
    
  • Full path to main web directory of a website :
    /home/sites/sitename/web
    (it isn`t really, but it`s a link to the real path)
    

• You can insert the standard CGI environment variable instead (note the double quotes):
  $ENV{'DOCUMENT_ROOT'}
• The full path to your cgi-bin directory - if you have one - is:
  "$ENV{'DOCUMENT_ROOT'}/cgi-bin"

How to Upload

• Be sure to upload the script and any text files in ASCII mode. If the program contains graphics (*.gif, *.jpg, etc.) be sure to upload them in BINARY mode. Some FTP clients have an automatic mode function which can eliminate many "cockpit errors."
• Unlike Windows, the RaQ is case sensitive. Unless there is a compelling reason to do otherwise, use only lower case letters for scripts and related filenames.
• Normally you upload the script into the web directory of the site, or into the created /cgi-bin. Connecting to the RaQ by FTP your initial directory is your user directory, so move up to the web directory of the site. In most Windows FTP clients you can set another starting path; insert /web as initial directory.

Whati is a /cgi-bin directoty ?, Where is It ? Do I need One ?

Although cgi scripts can be run from everywhere in the web directory on the Cobalt RaQ`s, many script authors assume the script must run in cgi-bin . It is stronly suggested that scripts be placed in /cgi-bin under /web .

CGI File Permissions

If you don`t already have it, you should consider to buy at least a basic book on Linux.

Instructions for CGI programs available on the net tell you often to set the permissions of the executable program to 755.

• For security reasons, you should first try to give the file the most minimal permissions as possible, so set them first to 700 (RaQs not running CGIWrap may require 705 or 755).
• The cgi-bin directory itself (and directories beneath it) should have 701 or, if that doesn`t work, 711.
• Data or configuration files used by the CGI program may require 600, 604 or 644 (try it in that order).

How DO I Set Permissions for My CGI Script ?

• Get on the shell of your cobalt RaQ, go to the directory where the script is, and type, for example, chmod 700 scriptname to give the file scriptname the permissions 700 (=read, write, execute only for the owner of the file).
• In your FTP client (e.g. CuteFTP or WS-FTP) mark the file(s) or directory, right click on it and select chmod or change attributes. Please read the instructions of your FTP client. For changing the file`s permissions for example to 700, click on the check boxes 'read, write, execute' under owner.

How Do I Run It ?

Interactive programs may require some values (e.g. a form mail processor). The values may be created by a HTML form, containing hidden fields, input fields or both of them. There are two ways to pass values to a CGI program, the GET and the POST method.

Read the instructions provided with the cgi script. Good scripts mention the required method in the documentation or as a comment in the script itself.

• If the script contains a line like
  $data = $ENV{'QUERY_STRING'};, it uses the GET method.
• If it contains a line like
  read(STDIN, $data, $ENV{'CONTENT_LENGTH'});, it uses the POST method.
• If it contains none of the above, most likely the script doesn`t expect values.

If you design a HTML form to call the script, you have to pass the method. A sample form header for the POST method looks like this :
<form action="http://sitename/cgi-bin/scriptname" method="POST">

Another way to pass values to a CGI program is to attach the values directly in the hyperlink without using a form :
http://sitename/cgi-bin/scriptname?&name=arthur&surname=dent&question=what?

• Here '?' is the delimiter to define the start of the values, '&' is the delimiter for the value pairs, the value itself is passed by the string 'value name'='value'.

My Script Doesn't Run. I'm Getting '500 Internal Sever Error', 'File not found or 'CGIWrap error when running CGI Scripts

First, consider the error messages for cgi scripts of the RaQ like a 'general protection fault' in Windows : the reason can be anything, but,  in most cases,  not the one that the error message tries to make you believe.

Double check all the following most common errors :

• Is cgi enabled for the virtual site ? Check it in the admin panel.
• Did you call it by typing the right URL ? Check both the URL and the script
  name for upper/lower case letters.
• Did you upload it to the right directory ?
• If the script expects values : did you use the right method (POST/GET) ?
• In the first line of the script, does the path point to perl ?
• If you edited path variables in the script, are they correct ?
  Normally there is no trailing slash.
• If the script requires sendmail, is the path to sendmail correct ?
• Did you upload the script in ASCII mode ?
• Does the script have the right permissions ?
• Did you upload it as a site user or as a site admin ?
• It still doesn`t work ?
  Check the above points again.

I've Checked ALL the items above at least Three Times, and it Still Doesn't Work !

First, we`ll use the debug function of CGIWrapd, which by default is enabled on the RaQ.
Type the following URL in your browser:
http://sitename/cgiwrapDir/cgiwrapd/scriptname

You should see some environment variables, and at the bottom of the displayed site, the output of the cgi script. Consult that for error messages. Read the output carefully, in most cases it indicates that a required file could not be found or accessed, or a syntax error in the script.

• If you see something like
  Content-type: text/html
  <html>...
  the script has been compiled and works. Most likely the URL calling it normally is incorrect. Check the URL, and call it directly in the browser.
• If you see nothing, or a 'File not found' message, most likely the script name or the URL is not correct, the script has the wrong permissions set, you uploaded it to the wrong directory, or CGI execution is not allowed for that site.
• If that doesn't help, access the Raq using Telnet.
  Go to the /web directory or the /cgi-bin you have created beneath, and run the script on the shell by typing perl -w scriptname | more and examine the output.

  The '-w' parameter tells Perl to create additional warnings about errors or strange constructs. For interpreting the output, refer to the instructions mentioned above. The '| more' makes the screen stop after each page, if the output is greater than one page.

  Another way to debug a perl script is to put the following command in the second line of the perl script after #!/usr/bin/perl
  use CGI::Carp qw(fatalsToBrowser);

  This line tells the browser to output error messages to the browser. After debugging, you should comment out this line by adding a '#' in front of it.

Where Can I Get CGI/Perl Scripts ?

What about Security ?

• DO :
  • Strip out at least HTML tags or verify user entries to prevent malicious code, if you let the script store user entries as HTML pages (guestbooks, classified ads, etc.)
    
  • Do NOT use CGI scripts with built in security issues (system commands, sendmail, open/write/unlink files etc.)

• DON'T :
  • Don't allow directory listing of your /cgi-bin (give it the right permissions, or/and put a blank html file in it).
  • Don't use scripts accepting unverified user input !
  • Don't put data files or configuration files in a directory that can be listed by others; prefer paths beneath your /cgi-bin, or even better, outside your /web directory, and check the permissions !)
  • Don`t let the CGI program store or mail private user data or credit card information to you without encryption !

Where Can I Get More Information ?

• about CGI ?>
  cgiwrap
  http://www.unixtools.org/cgiwrap/

  CGI-Resources.com
  http://www.cgi-resources.com

  Usenet
  comp.infosystems.www.authoring.cgi

• about security ?

  WWW Security FAQ
  http://www.w3.org/Security/Faq/wwwsf4.html
  
  Security Issues When Installing and Customizing Pre-Built Web Scripts
  http://stars.com/Authoring/Scripting/Security/
  
  Perl CGI Programming FAQ
  http://www.perl.com/CPAN-local/doc/FAQs/cgi/perl-cgi-faq.html

• about Perl ?
  Perl Homepage
  http://www.perl.com

• about Cobalt ?
  Cobalt Knowledgebase
  http://www.cobalt.com/support/kb/index.php3

CGI FAQ for The Cobalt RaQ, Version 11 * 02-22-2001 (c) 2001 Thom LaCosta