Home - Reference

Common Gateway Interface Setup

Prerequisites

In order to have a site enabled with CGI support, a few things are required. You must have a valid account with commercial grade web hosting. Personal web sites do not qualify. Apache must be notified via .htaccess about your intentions. .htaccess must have world readable permissions for the web server to detect any server side web site settings. The CGI must be executable. Your user account must have ownership of any CGI executables in the cgi-bin directory.

Your directory for cgi-bin depends upon the name of your web site. For example, if your web site is www.surfthe.us, your cgi-bin is located in /var/www/hosts/www.surfthe.us/cgi-bin/. Files in this directory must be owned by you, and executable to run. They need not provide permissions for others (e.g., chmod o=) symlinks are ignored. You are encouraged to copy the CGI into your cgi-bin if processing your content requires an Action directive in .htaccess.

Step by step setup for PHP4.

Before we start, a few conventions used in this section will be discussed. emphasis such as www.example.com require you to put your site name there. This setup assumes a very generic setup. Most people will want to edit and customize the configuration files after the essentials are up and running.

Some copy and paste operations in an ssh window will require you to hit CTRL+D to end the input after reaching EOF. If so, your clipboard and/or terminal emulator is to blame. You will need to edit the files after creating them. (eg, with vi, vim, zile, ed, emacs etc)

Eventually this will all be automated via a hosting controller. For the mean time, you'll need to login via ssh and perform these commands. (we suggest PuTTY)

1. Change the current directory to your site hosting space.
   
   cd /var/www/hosts/www.example.com/
2. Make a directory called cgi-bin.
   
   mkdir cgi-bin
3. Modify permissions on the cgi-bin directory.
   
   chmod 711 cgi-bin
4. Change into the new directory.
   
   cd cgi-bin
5. Copy the default php.ini here (note the space and period after php.ini).
   
   cp /etc/php4/cgi/php.ini .
6. Copy php4 here (watch that last period).
   
   cp /usr/lib/cgi-bin/php4 .
7. Change directory into the document root.
   
   cd ../docroot
8. Verify your current working directory.
   
   pwd
   should print:
   
   /var/www/hosts/www.example.com/docroot
9. Create (if not already present) a .htaccess file.
   
   cat -- >> .htaccess <<EOF
   
   #DirectoryIndex notifies Apache to serve these files first by default.
   #e.g. www.example.com/foo/ -> www.example.com/foo/index.html
   #This occurs on directory ^ requests.
   DirectoryIndex index.php index.html index.htm index.txt
   
   #The webserver will seek for files from left to right until it matches one.
   #If no match is made, access will be denied. (unless you enabled virtual
   #directory listings)
   
   #AddType tells Apache files with these extensions belong to a mime type.
   AddType application/x-httpd-php .php .php3
   
   #Action tells Apache to use a handler (your CGI) for a
   #specific mime type (application/x-httpd-php)
   Action application/x-httpd-php /cgi-bin/php4
   
   EOF
10. Create a phpinfo test script.
    
    cat -- >> phpinfo.php <<EOF
    <?PHP
    phpinfo();
    ?>
    EOF
11. Check your web page at http://www.example.com/phpinfo.php.
12. You may also notice that your php file only has read and write permissions for the owner, and nothing else. This excludes anyone but you from modifying or reading the file. When updating files, you should always check to see if sensitive scripts with database passwords have sane permissions. This will prevent anyone from misusing your site or databases.
    
    ls -l phpinfo.php
    should produce:
    
    -rw------- 1 user group 20 Oct 6 18:30 phpinfo.php
    If you need further assistance with permissions and secuirty, you may contact us for the current consulting rates, or read up on a *NIX primer.

.htaccess

This file allows apache to dynamically adjust to your configuration. Directives control what changes occur. Improperly configured .htaccess files can cause "500 - Internal Server Error" on your sites.

Directives

A more exhaustive reference for apache directives can be located on the apache foundation web site at http://www.apache.org/.

Directory Index

mod_dir.html#directoryindex

DirectoryIndex index.php index.php3 index.html index.txt

AddType

mod_mime.html#addtype

AddType application/x-httpd-php .php .php3
AddType application/x-httpd-php-source .phps

Action

mod_actions.html#action

Action application/x-httpd-php /cgi-bin/php

ErrorDocument

mod/core.html#errordocument

ErrorDocument 404 /missing.html

Error 403 - Forbidden

This error will occur in at least these situations:

On static content

• On static content, permissions do not allow everyone to read the file. (the web server is a separate user in this instance)
• On static content, permissions to access the file through the directory structure, as the web server don't allow it. (world search permissions, or +x is required on each directory leading to the content)

On dynamic content

• The CGI binary is not executable.
• The perl script is not formatted with unix line feeds.
  • vim -c "set ff=unix" -c "wq" file.pl
    This will reformat file.pl to use unix line feeds. Sometimes PuTTY will emit harmless charaters on the screen. You can ignore that.
• The path to the CGI binary does not have world search permissions (chmod o+x)
  Typical output will be: You don't have permission to access /cgi-bin/php4/some.php on this server.
• The .htaccess file(s) are setup incorrectly.

500 - Internal Server Error

This error can be caused by an improperly configured .htaccess file, or a misbehaved CGI executable. Check the log files for additional information.

Log files

Log files for your web site are stored in a location unique to your site name. If for example, your web site was www.somesite.com, your log files are stored in /var/log/apache-ssl/somesite.com/ where www-error.log keeps any error messages.

user@server1:/var/log/apache-ssl/example.com$ ls -oA
total 76
-rw-r--r-- 1 root 51517 Nov 8 16:24 www-combined.log
-rw-r--r-- 1 root 3471  Nov 8 00:47 www-error.log
-rw-r--r-- 1 root 14344 Nov 8 16:24 www-referer.log

PERL

Perl is located at /usr/bin/perl

PHP.INI

Check the include_path, log_errors, and error_log values to start. Proper use of the log_errors and error_log will allow you to log errors to a log file, instead of in the browser where possibly sensitive information may be revealed.

Top