WEB SITE HOSTING

CGI programming/installation guide


Most CAMEX VI accounts include a custom /cgi-bin directory which can be used to install 3rd party or custom-developed CGI scripts. The preferred scripting language is Perl 5; compiled C is also supported.

Please note: CGI programming/installation support is not included with CAMEX VI's hosting packages. If you are having problems installing a 3rd party script, and are unable to obtain assistance from the script developer, please choose one of our CGI support options below.

You may wish to use a script from our script library. These scripts are known to work on our accounts. However, support is not provided for the installation of these scripts. If you are not familiar with CGI, your may wish to try Miva, which is included free with all accounts.

What script languages are supported?

CAMEX VI provides the ability to run custom CGI scripts written in many interpreted languages, the most common of which is Perl 5. Compiled C is also permitted.

Our Perl is version 5.005.02. Our compiler is gcc 2.7.2.1.

We strongly recommend that scripts be written in Perl 5. Perl is the widely-accepted standard for CGI development, and is our language of choice. Scripts written in other interpretive languages (i.e. sh, tcl) may function correctly, but their use is discouraged.

What server operating system will my scripts be running on?

Your scripts will be running on FreeBSD 3.x. This operating system supports ELF binaries. The webserver is a slightly modified version of Apache 1.3.3, which uses the standard CGI/1.1 interface. WinCGI is not supported.

Where do I place my CGI scripts?

CGI scripts should be placed in the /cgi-bin directory within your document root.

What is the URL that corresponds to my /cgi-bin directory?

Your scripts will appear in your /cgi-bin directory. For example: http://www.yourname.com/cgi-bin/scriptname.pl

To access your CGI scripts through the secure server, use URLs of the form: https://wwwXX.camexvi.com/yourname.com/cgi-bin/scriptname.pl
(where XX is your server number, i.e. www08).

What are my paths?

Your actual home directory path is of the form "/drive/home/username" (i.e. /usr/home/yourname.com).

It is possible that your absolute, or physical, pathname may change from time to time (with advance notice). Seasoned programmers interested in making their code as portable as possible should use the DOCUMENT_ROOT environment variable:



Home directory	Absolute path (not recommended): /usr/home/yourname.com Recommended path: $ENV{'DOCUMENT_ROOT'}/.. Seasoned approach: $homedir = $ENV{'DOCUMENT_ROOT'}; $homedir =~ s/\/htdocs$// || die;
Document root	Absolute path (not recommended): /usr/home/yourname.com/htdocs Recommended path: $ENV{'DOCUMENT_ROOT'}
CGI-BIN directory	Absolute path (not recommended): /usr/home/yourname.com/htdocs/cgi-bin Recommended path: $ENV{'DOCUMENT_ROOT'}/cgi-bin

Where is perl located?

Perl is found at /usr/local/bin/perl. Perl scripts should begin with the following line:

#!/usr/local/bin/perl

This is Perl 5.005.02. When developing on your local system, run perl -v to verify that you are using the correct Perl version.

Where is sendmail located?

Sendmail is located at /usr/sbin/sendmail. This is the standard location on BSD-based unix platforms. You are highly encouraged to use sendmail's "-t" option which provides enhanced security and functionality. The following code fragment demonstrates the use of sendmail within a perl script:

$to_addr = "you\@yourname.com"; $from_addr = "them\@theirname.com"; $subject = "My message subject"; $message_body = <<EOT; Place your message body here. Place your message body here. Place your message body 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;


There is a security hole in the common "|/usr/sbin/sendmail $recipient" invocation

What other system utilities, like sendmail, can be used?

Many system utilities have Perl counterparts. To increase the performance of your CGI script, trying using the following Perl code instead of using system calls or backticks (C has many of the same utilities as Perl; consult your favorite C manual for more information):

	System call	Preferred method
date	$mydate = `/bin/date`;	$mydate = localtime;
grep	@results = `grep $string $filename`;	$/ = "__END__"; open FILE, "$filename"; $file = <FILE>; close FILE; @results = grep($string, $file);
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;

Do I need to chmod my files? How do I chmod my files?

All CGI scripts must be "chmodded" in order to be executable by the webserver. This can be done either with an FTP client (such as CuteFTP or WS_FTP), or using Webby. Typically, executable file permissions should be set to 0755:

user: read, write, execute group: read, execute other: read, execute


Typically, data file permissions should be set to 0660:

user: read, write group: read, write other: none




To determine the current permissions of a file, view the file in your FTP client, or in Webby. When installing 3rd party CGI scripts, please carefully follow the installation instructions, making sure to "chmod" the appropriate files and directories.

PLEASE NOTE: CGI scripts may not be group or world-writable. Your CGI script will not function correctly if you "chmod" it as group or world-writable.

Can I install CGI scripts outside of my /cgi-bin directory?

Although not recommended, you may manually add the following line to the .htaccess file in your document root directory:

AddType application/x-httpd-cgi pl cgi (etc.)

Where PL and cgi are file types to treat as executable CGI programs. This will cause the webserver to execute any PL or .cgi file on your site as if it were in your /cgi-bin.

A better solution is to use META REFRESH or SSI to redirect/include scripts from your /cgi-bin.

 

Why am I getting an "internal server error"?

The webserver displays an "internal server error" (or error 500) when your script has not generated the proper CGI header. This error is rather generic, and can be caused by several factors:

If using Perl, you may have uploaded your file in binary mode instead of ASCII mode. Make sure you use ASCII mode when transferring files using your FTP client.

TIP: You can configure most FTP clients to automatically recognize certain extensions (i.e. "PL") as being ASCII. Consult your FTP client manual for more information.


Your script may not be syntactically correct (it may not compile). If you're using Perl, try using our syntax checker to find errors in your script. If you do not see "syntax OK", then there is a syntax error in your script.

TIP: If you are developing your own Perl scripts, download Perl Win32 for your system, and develop your scripts locally. This will assist you in debugging, and will allow you to execute your scripts from the command line.


Your script may not be executable. Check the permissions on your script (see "chmodding", above). Make sure that it is executable, and that it is not group or world-writable.

Your program may be dying before it prints out a proper CGI header. Check your error log for clues to help you identify the problem with the script.

If you're uploading a binary executable, make sure that it is in a FreeBSD-compatible binary format. FreeBSD can not execute Windows binaries (.exe files)

The webserver may be killing your script if it exceeds specific CGI resource limits. 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 webserver. Per-process limits are shown here:

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

Make sure your script is actually outputting a proper CGI header. In Perl, try adding the following code to the top of your script:

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

Don't use "die". Print out a meaningful header and error message, then exit. The "die" command writes to STDERR instead of STDOUT.

If you're still unable to get your CGI script working, please try one of our CGI support options, below.

When I visit my CGI script's URL, why do I see the actual code instead of the script in execution?

Make sure you have placed the CGI script in your /cgi-bin directory. For compiled languages, remember to compile the script before execution (don't point your browser at myfile.c, for example).

How do I compile my C code?

You are free to upload precompiled C binaries at any time. If you need CAMEX VI to compile a C program into an executable, please e-mail us with the exact location of the C source (it must reside on your account). If the program consists of more than one source file, you must provide a BSD-compatible Makefile.

Two complementary compiles are provided to each account. Contact us for the pricing structure for additional compiles.

Where is my /cgi-t directory?

The /cgi-t directory is a hidden directory which houses CAMEX VI's freeCGI scripts. These scripts are pre-installed, and use web-based administration instead of actual script manipulation. Accounts are welcome to use both custom CGI and freeCGI scripts.

How do I use SSI in conjunction with my custom CGI script?

Server-side includes can "include" the output of your CGI script using the following code, embedded in an .shtml file:

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


For more information on SSI, please visit our SSI documentation.

Can I use file locking?

The use of file locking is permitted. Please note, however, that the webserver will automatically kill any process which has been waiting on a file lock for a certain amount of time (typically several seconds). The webserver will respond with an "internal server error" in such a situation. The following code fragment illustrates the use of file locking:

$LOCK_EX = 2; $LOCK_UN = 8; sub lock {     flock MBOX, $LOCK_EX;     # and, in case someone appended     # while we were waiting...     seek MBOX, 0, 2; } sub unlock {     flock MBOX, $LOCK_UN; } open MBOX, ">>myfile.txt"; lock(); print MBOX "message\n"; unlock();

What is the preferred method for generating a random number?

The following code fragment should be used:

srand( time() ^ ($$ + ($$ << 15)) );

which is "more random" than the typical srand( time ^ $$ ).

Why is Perl complaining about a "Literal @ now requires backslash"?

The '@' character, found in e-mail addresses, is an array symbol in Perl. If Perl is complaining about a stray '@', you most likely need to "backslash" it, by entering '\@' instead of '@'.

My script is not working. Can CAMEX VI debug my code?

Due to the vast number of complexities involved, CGI programming/installation/configuration support is not free. However, you may be interested in one of the following support options:

Troubleshooting
Try troubleshooting your script using the troubleshooting tips found above.

Contact the developer
In most cases, the script developer will be able to assist you in the initial installation and configuration of your script. Try to provide as much information as possible, including the URL to this document, and a detailed description of the problem you are having. Don't forget to consult any FAQs or README files before contacting the developer!

$150 CGI configure
If, after installing your Perl script, you can't get past the configuration stage, e-mail us with the location of the script and we will configure it for you for a flat fee of $150. If we are unable to configure the script, you won't be billed.