TLCHost.Net
Tender Loving Care Hosting
Raq

Support
Home
Web Hosting
FrontPage
Virtual Site Help
Use Policy
Contact Us

CGI FAQ for The Cobalt RaQ


Introduction

This FAQ is intended as a practical CGI introduction for Webmasters hosting pages on a Cobalt RaQ Server. The original version was based on a RaQ 3i. The FAQ is intended to act as a simple CGI Troubleshooting aid.

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 ?

A RaQ is a Server Appliance produced by Cobalt Networks.

What is a CGI Script ?

CGI is the 'common gateway interface'. It can exchange data with a program running on the server to provide mail forms, guestbooks, databases etc. The programs that run on the server are often scripts, plain text files that contain several commands to be executed.

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 ?

CGIWrap is a gateway program that allows general users to use CGI scripts and HTML forms without compromising the security of the http server. Scripts are run with the permissions of the user who owns the script. In addition, several security checks are performed on the script, which will not be executed if any checks fail. CGIWrap is used via a URL in an HTML document. As distributed, cgiwrap is configured to run user scripts which are located in the ~/public_html/cgi-bin/ directory. The Cobalt RaQs run a customized version of CGIWrap that allows cgi scripts to be run from any location.
(Taken from http://www.unixtools.org/cgiwrap/)

How Do I Run CGI/Perl Scripts ?

You will, in most cases, have to edit variables within the script, upload it to your web directory, assign the correct permissions, and run it.

How to Edit a Perl Script ?

If you have to edit the script, it is important to choose an editor that does NOT insert a carriage return at the end of the line. Do NOT use Notepad. You could use Wordpad (disable word wrap).

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 ?

On most servers, cgi scripts are allowed to be run only from a special directory beneath the web directory called /cgi-bin, or /cgi-local.

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

Under Unix, permissions are set by a number. A higher number means more permissions. The first number defines the rights for the owner of the file, the second his group, and the third all others. To learn more about permissions, read the chmod manpage. Use Telnet to access your server and type man chmod; navigate with cursor keys and the space bar, exit the man page by typing q.

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 ?

There are two (main) ways to change permissions of a file :
  • 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 ?

CGI programs are mostly called by a hyperlink from within a HTML page. Another way are Server Side Includes (SSI) , mostly used for non-interactive programs (e.g. hit counters).

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 !

OK, we'll do some more debugging (and in 90% of all cases you'll note that it's one of the above errors, so did you check them really ?)

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 ?

A very good starting point is http://www.cgi-resources.com , where you can find zillions of (user rated) CGI programs, documentation and more.

What about Security ?

Only a few basic things :
  • 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 ?

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

Original Material entitled Installing, running and debugging Perl CGI scripts on a Cobalt RaQ - Version 1.0 * 15-06-2000, last updated : 27-07-2000 (c) 2000 H.P. Stroebel

Back to Top Top

All material © 2001, Padrone. Inc. "TLCHost," "Tender Loving Care Hosting," are trademarks of Padrone, Inc. All rights reserved.