CGI Programming Guide

A private "cgi-bin" directory is provided with all FastVirtual web hosting plans. 3rd-party, or custom developed scripts should be uploaded to this directory. Perl 5 is the preferred CGI scripting language, although compiled C is also supported.

You are also welcome to use scripts from our range of Web Tools. These are preinstalled, and can be easily configured from your account control panel.

If you are not familiar with CGI, and our range of web tools do not meet your needs, you may wish to try developing your own script using Miva, which is easier to learn than Perl and is fully supported by FastVirtual.

If you are having trouble installing your script, please see our CGI Support Options.

Which CGI script languages does FastVirtual support?

FastVirtual supports many interpreted programming languages. The most widely used is Perl 5. Compiled C is also supported.

• FastVirtual uses Perl version 5.008006
• The compiler is GCC 2.95.4 20020320 [FreeBSD]

Perl 5 is commonly accepted the standard for CGI development on the Web, and is our preferred programming language. Scripts developed in other languages, such as sh and tcl, will likely function correctly, but Perl remains our preference; particularly for support reasons.

Which operating system and web server does FastVirtual use?

• FastVirtual uses FreeBSD 4.11-RELEASE-p25. ELF binaries are supported.
• Our web server is a modified version of Apache 1.3.33 (UNIX), with standard CGI/1.1 interface. FastVirtual does not support WinCGI.

Where should I upload my CGI scripts?

You should upload your CGI scripts to the "cgi-bin" directory. This directory is located in your document root.

What is the actual URL of my "cgi-bin" directory?

Scripts in your "cgi-bin" directory are available at the same location on your domain via URL:

http://www.yourdomain.com/cgi-bin/yourscript.cgi

The URL is the same for scripts you wish to access via your secure server:

https://www.yourdomain.com/cgi-bin/yourscript.cgi

What paths should I use to the various directories?

The physical path to your home directory is "/drive/home/username". The absolute path is "/usr/home/yourdomain.com".

As there is no guarantee that the physical or absolute path names will always remain as above, and in the interest of making your code as portable as possible (i.e. not dependent on the configuration of any single web server), it is wise to use the the DOCUMENT_ROOT variable in place of absolute paths.

Description	Path
Home directory:	Absolute path: /usr/home/yourdomain.com Recommended path: $ENV{'DOCUMENT_ROOT'}/.. Standards-compliant approach: $homedir = $ENV{'DOCUMENT_ROOT'}; $homedir =~ s/\/htdocs$// || die;
Document root:	Absolute path: /usr/home/yourdomain.com/htdocs Recommended path: $ENV{'DOCUMENT_ROOT'}
"cgi-bin" directory:	Absolute path: /usr/home/yourdomain.com/htdocs/cgi-bin Recommended path: $ENV{'DOCUMENT_ROOT'}/cgi-bin

How should I specify the location of Perl?

Perl is located at "/usr/local/bin/perl". The first line of all Perl scripts should always be:

#!/usr/local/bin/perl

FastVirtual uses Perl 5.008006. When developing your scripts, you should run "perl -v" to confirm you are using the same version.

How should I specify the location of sendmail?

Sendmail can be found at "/usr/sbin/sendmail". On BSD-based UNIX platforms this is the default location. FastVirtual strongly recommends that you use the "-t" option (i.e. "sendmail -t"), as this provides additional security and functionality.

A typical Perl script might use sendmail as follows:

$to_addr = 'you\@yourdomain.com';
$from_addr = 'them\@theirdomain.com';
$subject = 'Message subject';

$message_body = <<EOT;
Type your message content here.
EOT

open MAIL, "|/usr/sbin/sendmail -t";
print MAIL "To: $to_addr\n";
print MAIL "From: $from_addr\n";
print MAIL "Subject: $subject\n";
print MAIL "\n"; print MAIL "$message_body\n";
close MAIL;

Note: The common "|/usr/sbin/sendmail $recipient" method for invoking sendmail contains a security hole, and is strongly discouraged.

What system utilities can I use in my Perl scripts?

Perl provides many efficient system utilities. Consider using the following Perl commands as opposed to system calls or backticks, as this will improve your script's performance.

Command	Standard System Call	Perl Method
date	$mydate = `/bin/date`;	$mydate = localtime;
grep	@results = `grep $string $filename`;	open FILE, "$filename"; @lines = <FILE>; close FILE; @results = grep($string, @lines);
ls	@files = `ls -la $path`;	opendir(DIR, $path); @files = readdir(DIR); closedir(DIR);
mkdir	system("mkdir $dir");	mkdir $dir, 0777;
mv	system("mv $oldname $newname");	rename $oldname, $newname;
rm	system("rm $file");	unlink $file;
rmdir	system("rmdir $dir");	rmdir $dir;

Note: C has similar utilities to Perl. Check your favorite C resource for details.

Do I need to change (chmod) file permissions? How do I change file permissions?

File permissions for CGI scripts should be changed to be executable by the web server. You can do this by using an FTP program (i.e. CuteFTP), or by using Webby, FastVirtual's online file editor.

The server utility for specifying/changing file permissions is called "chmod". This should be listed as an option in your FTP program.

File permissions for executable files should be set to 0755:

Type	Permissions
USER	read, write, execute
GROUP	read, execute
OTHER	read, execute

File permissions for data files should be set to 0660:

Type	Permissions
USER	read, write
GROUP	read, write
OTHER	none

If you wish to install a 3rd-party script, please be sure to follow the instructions provided by the developer. Particularly, ensure you set the correct permissions on the applicable directories and files.

Note: FastVirtual does not support group-writable or world-writable permissions.

Do my CGI scripts have to be in the "cgi-bin" directory?

The web server expects to find CGI scripts in the "cgi-bin" directory. FastVirtual does not recommend placing your scripts outside of this directory.

This unsupported method may work: Place following entry in your .htaccess file:

AddType application/x-httpd-cgi pl cgi

Although this may work, it is not efficient, and FastVirtual does not provide support for problems that may result from this configuration change.

The recommended approach is to use META Refresh or Server Side Includes to redirect to, or include output from scripts located in your "cgi-bin" directory.

Which Perl modules are available?

Please see our list of currently installed Perl Modules. The list is periodically updated, so may not contain recent additions.

My script is generating an internal server error. What could be causing this?

An internal server error is returned by the server when your script fails to generate the correct CGI header. This is a non-specific error, so there are several possible causes:

If your script was written in Perl, this may have been uploaded as a binary file. Perl files should be uploaded in ASCII mode, so you may need to add .pl (or .cgi) extensions as ASCII file types to your FTP software.

Your script may contain errors. If your script was written in Perl, run your script through our syntax checker, available through your account control panel. The syntax checker will identify any errors or typos and allow you to fix them.

If you are writing your own scripts in Perl, download Perl Win32. This will allow you to execute your scripts from the command prompt, which will help you debug your code before uploading to your domain.

You may not have set correct permissions for your script files.

Your script could be dying before it prints a correct CGI header. Your error logs may assist you in identifying the problem.

If your script is a binary executable (i.e. compiled C), please check to ensure it is in a FreeBSD-compatible binary format. Windows binaries (.exe files) cannot execute on FreeBSD.

Your script may be exceeding CGI resource limits, so may have been killed by the server. This applies to scripts that use large amounts of memory or CPU cycles, stay in execution too long, or erroneous scripts that fall into a loop.

Scripts which fall into an endless loop, use large amounts of memory, use large numbers of CPU cycles, or stay in execution too long are subject to being killed by the web server. Per-process limits are as follows:

Resource	Limit
CPU time:	60 seconds
Memory usage:	16 MB
Concurrent CGI processes:	16 (per account)

Check your script's CGI header to ensure this being generated correctly. If your script is written in Perl, add this code to the beginning of your script:

#!/usr/local/bin/perl
print "Content-type: text/plain ";
select(STDOUT);
$| = 1;
open(STDERR, ">&STDOUT");
print "Script execution is starting now...";

You should not use "die", as this writes to STDERR and not STDOUT. Instead, print out a proper header and error message, and then exit.

If you've followed these instructions and still can't get your script to work, you may be interested in our CGI Support Options.

My browser displays the source code. Why isn't my CGI script executing?

In order for the server to execute your CGI script, it needs to be uploaded to your "cgi-bin" directory (or a subdirectory thereof). If your script is located elsewhere on your site, then the script won't execute and you will only see the code.

For scripts that need to be compiled, be sure to compile your script before attempting to execute it. If you attempt to execute a source file (i.e. "myscript.c"), you will only see the code.

How can I compile my C source file into an executable?

You may upload your precompiled C executables whenever you wish. If you want FastVirtual to compile your C source file, please upload the file to your account and send us the filename and location. If your script requires more than one source file, you will also need to upload a BSD-compatible makefile.

FastVirtual provides two complimentary compiles for each account. If you require additional compiles, please see CGI Support Options below for pricing information.

I can't find the "cgi-t" directory. Where is it located?

This is an internal directory that is used for FastVirtual's web tools and other complementary scripts. The directory is hidden and cannot be accessed. All scripts that are proceeded by "cgi-t/" are preinstalled and can be configured via your account control panel. You are welcome to use our complementary scripts, as well as your own custom CGI scripts.

How can I include output from a CGI script in a web page? Can I use Server Side Includes (SSI) to do this?

Yes, you can use Server Side Includes to include CGI script output in your web pages. Your page needs to end with a ".shtml" extension, which tells the server to look for SSI instructions. SSI will not work on a ".html" page.

Simply include the following code on the .shtml page where you want the script output to appear (where "myscript.cgi" is the name of your script):

<!--#include virtual="/cgi-bin/myscript.cgi" -->

More information about SSI, including details of all supported variables, can be found in our Server Side Includes Guide.

Am I permitted to use file locking?

Yes, you may use file locking. However, you should note that the server will kill any process that has been on a file lock for more than a few seconds. In this situation, the server will return an internal server error.

A typical Perl script might use file locking as follows:

$LOCK_EX = 2;
$LOCK_UN = 8;

sub lock {
     flock MBOX, $LOCK_EX;
     # in case someone appended while we are waiting...
     seek MBOX, 0, 2;
}

sub unlock {
     flock MBOX, $LOCK_UN;
}

open MBOX, ">>myfile.txt";
lock();
print MBOX "message\n";
unlock();

What is the best way to generate a random number in Perl?

Use the "rand" function. Perl calls "srand" with a "good" seed the first time you call rand, even if you haven't called "srand" yourself.

Perl states that a "literal @ now requires a backslash". What does this mean?

In Perl, the "@" character is actually an array symbol, so you need to precede this with a backslash like so: "\@".

How can I get CGI support from FastVirtual?

Before proceeding further, make sure you have checked your script using the above troubleshooting tips.

The script developer may help you install and configure your script. Make sure you describe the problem in detail, and include the URL of this page. Before you contact the developer, make sure you read through any readme files that were included with your script.

Due to the numerous complexities involved in CGI development, CGI support is subject to charges. FastVirtual provides the following CGI support options:

Script Configuration Service - If you've installed your Perl script, but are having trouble configuring it, we can configure your script for you. Send us the name and location of the script, together with your configuration requirements, and we will complete the configuration for a one-time fee of $70.00. If we cannot complete the configuration, you will not be billed.

Custom Development Service - If you need to develop a custom Perl script, our development team is ready to help. Standard CGI programming is billed at $150.00 per hour. Systems-level development is billed at higher rates. Please contact us for a detailed quote.