CGI Programming

CGI scripts

If you wish to do CGI programming there are some restrictions imposed for security reasons. They must be put in /cgi/home/USERNAME.

To create a CGI script, you must create a marker for it in your public_html directory. The marker is just an empty file.

The CGI script must have exactly the same name as the marker but with /cgi added onto the front of the path. If the marker's name is /home/john/public_html/fancy.cgi, then the CGI scripts name is /cgi/home/john/public_html/fancy.cgi.

For example:

cd $HOME cd public_html touch fancy.cgi cd /cgi/$HOME mkdir public_html cd public_html vi fancy.cgi chmod +x fancy.cgi

CGI scripts must be named something.cgi.

While your script is running, it will only have access to files that are under /cgi. Only a subset of the programs available on Idiom are available on /cgi. In particular, sendmail is missing. There is a simple sendmail replacement on /cgi though in /cgi/usr/sbin/sendmail.

We recommend writing your CGI program in perl5. See man CGI for CGI-related perl functions. If you need to send email from your CGI, then see man Net::SMTP. For general perl reference, see:

• Tom C's Perl Home Page
• The Perl Institute
• The perldoc command.

If you are going to write more than a few CGI scripts, it may make sense to put your web pages in /cgi and then make a link to them:

cd /cgi/$HOME cd public_html mkdir shared cd cd public_html ln -s /cgi/$HOME/public_html/shared .

If you have a virtual host, then put your scripts in /cgi/home/USERNAME/www.YOUR-DOMAIN. Put your touch files in /home/USERNAME/www.YOUR-DOMAIN. The URL for your cgi scripts will be http://www.YOUR-DOMAIN/SCRIPT.cgi

Although it is not recommended, if you wish to use the uncgi program, version 1.8 is installed. You must make a touch (see above) for uncgi.cgi, but not for the programs that it calls. To use it, go to the directory that your script will be in and give the following command:

ln -s /usr/local/bin/uncgi.cgi .

No-parse-header scripts

No parse-header scripts are just like CGI scripts except they are named something.nph instead of something.cgi.

Symbolic Links

Using symbolic links (similar to Mac aliases and Windows shortcuts), one directory can become a synonym for another. To avoid the hassle of making marker files (see above), make a symblic link from your home directory to /cgi: mkdir -p /cgi/$HOME/public_html/cgi mkdir $HOME/public_html ln -s /cgi/$HOME/public_html/cgi $HOME/public_html ls -l $HOME/public_html/cgi

Put all your cgi pages in $HOME/public_html/cgi (which is now the same thing as /cgi/$HOME/public_html/cgi). If you are using another.idiom.com, then a similar link (for your whole public_html) is already in place.

Testing CGI scripts -- cgishell

The chroot()ed environment that CGI scripts run in can be hard to understand from the outside.

To test CGI scripts by hand from the inside of the chroot()ed environment, use the cgishell command.

Cgishell can be found at /usr/local/bin/cgishell. It starts a shell inside the /cgi directory.

CGI scripts, the old way

If you wish to do CGI programming there are some restrictions imposed for security reasons. Your CGI scripts must be written in perl5. They must be put in /cgi/user-cgi/LOGIN. Some features of perl are not going to work in your CGI scripts: globbing and system "invocation with redirection or metachars". Further, your perl program will be running with perl's taint checks turned on. User CGI programs run in a chroot(2)ed environment: you will only be able to access files that are in /cgi.

The URL for your CGI scripts is http://www.idiom.com/user-cgi/LOGIN/SCRIPT-NAME

There is one benefit of this setup: better information when your program bombs. In your script, don't output anything until the very last line. Save it in a buffer. Save another buffer filled with debug information. If you exit with die then the die message, and the variable $elog will be displayed.

The CGI.pm module is available for CGI programming.

If you need to send email from a CGI script, the Net::SMTP.pm module is a good approach.

No-Parse-Header CGI scripts, the old way

NPH scripts are accommodated just like CGI scripts, but the URL to use is http://www.idiom.com/user-nph/LOGIN/SCRIPT-NAME. The script need not be named nph-.