CGI programming/installation guide

Manic 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 Manic's hosting packages. If you are having problems installing a 3rd-party script, you will need to contact the script developer.

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.

Interested in learning CGI or Perl?

    There are excellent articles and tutorials at WebMonkey.

What script languages are supported?

    Manic 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.tierranet.com/yourname.com/cgi-bin/scriptname.pl
    (where XX is your server number, i.e. www08). All secure servers have tierranet.com in the address unless you have purchased your own secure key.

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`; 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;

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 from your Account Control Panel 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.

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).

Where is my /cgi-t directory?

    The /cgi-t directory is a hidden directory which houses Manic'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 email 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 '@'.

CGI programming/installation -- quick reference

This quick reference provides a brief summary of basic configuration information.

Perl location:
    #!/usr/local/bin/perl
    (perl is version 5.005.02)

Sendmail location:
    /usr/sbin/sendmail
    (use the -t option)
Path to home directory:
    /usr/home/yourname.com
    $ENV{'DOCUMENT_ROOT'}/.. (preferred)
Path to document root:
    /usr/home/yourname.com/htdocs
    $ENV{'DOCUMENT_ROOT'} (preferred)
Path to cgi-bin directory:
    /usr/home/yourname.com/htdocs/cgi-bin
    $ENV{'DOCUMENT_ROOT'}/cgi-bin (preferred)
How to chmod files:
    Use Webby, or FTP

Main | Signup | Hosting | Design | Webmaster Resources | Contact Us!




Copyright © 1996-1998, Manic Design
support@manicdesign.com