How do I write a CGI script?

For more details on CGI scripting than you ever wanted to know, check out Google Directory's CGI section.

For all things PHP-related, visit http://www.php.net

Okay, I have a script I want to run. Where do I put it, and how do I access it?

While PHP and SHTML files can be served from anywhere under your public_html directory, CGI scripts and executables themselves must be placed under your public_html/cgi-bin directory, or they will not run, without extra provisions being made.

For example, if you create a script called /home/YourUserName/public_html/cgi-bin/test, you can run this script using the URL: http://cgi.cse.unsw.edu.au/~YourUserName/cgi-bin/test

Make sure that your script is executable! (ie. chmod +x test.pl)

If you really need to run a CGI program outside of your cgi-bin directory, you can enable it with the following .htaccess directive:

The actual processing of dynamic content is handled not by www.cse.unsw.edu.au itself, but rather by cgi.cse.unsw.edu.au - a DNS pointer to a pair of load-sharing CGI servers. Where possible, links to dynamic content should point directly to cgi.cse rather than www.cse, however some fairly smart URL handling should redirect most requests automatically.

Help! It doesn't work!

First up, the most common CGI/PHP errors boil down to permissions issues. Here are the minimum permissions needed in order for everything to work:

• Static files (html/txt/jpg etc) are handled by www.cse, which runs as the w3serv user. These files therefore either need to be owned by the w3serv user/group, or to be set other-readable (mode o+r, or 644).
• Directories do not need to be readable by w3serv, but they do need to be executable by that user (mode o+x, or 601). Note that the entire chain of directories leading to your content, whether static or dynamic, from public_html downwards, need to be set mode o+x. Take for example the file public_html/foo/bar/somefile.php. If public_html, foo or bar are not accessible by the w3serv user, the file will not be accessible.
• Dynamic content (PHP scripts, SHTML pages and CGI programs) need to be owned by the user in whose home directory they reside. This means that /home/someuser/public_html/cgi-bin/test.pl must be owned by someuser. Files owned by anotheruser will fail to run. In the case of group-owned directories (such as class/project accounts), this is obviously a problem. To address this, use the priv takeover command to change ownership of the files to the group account. If you use this command, ensure that you enable group-write access, as you will lose owner access to the files when the ownership changes. The target group must be a member of the GroupCGI class - contact System Support to have this added.
• All dynamic content is executed by the user that owns the home directory. If you wouldn't have permission to run the program yourself, (or any programs that it in turn executes) from a shell, then it won't work on the CGI server, either.
• PHP and SHTML files need to be readable by the owner, but do not need to be executable (mode ug+r or 600).
• CGI programs, in addition to residing under public_html/cgi-bin, must be executable by yourself (mode ug+rx, or 700)

How do I access files in my home directory?

Short answer: you can't.

Long answer: Because CGI scripts are by their very nature designed to be executed by the general public, we consider them to be inherently untrusted. Even the most innocuous-looking script could have exploitable security flaws that could result in loss or leakage of sensitive information, or compromise the security of your account, if given access to all of your files. To prevent this, the CGI servers are set up so that they can only access files under your public_html directory.

Your public_html directory is accessible via /web/YourUserName - this is the filesystem path you should use to access data files etc. in your scripts. This path is available on all CSG-linux machines, allowing you to use and test your scripts from the command line without having to reconfigure them.

It still doesn't work properly! How can I see debug information?

CGI programs on our servers are handled by a program called CGIwrap, which provides a secure, controlled setuid environment for CGI execution, along with a handy debugging facility.

To debug a script, set the handler for your script to be the one with debugging. This is best explained with an example. Say you need help debugging http://cgi.cse.unsw.edu.au/~YourUserName/cgi-bin/somedir/problem.cgi. You should create a .htaccess (note leading period) file in the same directory, with text like: This tells the webserver to use the debugging-enabled cgiwrap instead of the usual one.

Note that the .htaccess file must be made readable by the webserver by using chmod 644 .htaccess.

I'm getting CGIWrap errors, how do I fix them?

The other common-but-cryptic CGIWrap error message is Script does not have same UID (Script does not have same UID), which basically means that the file is not owned by the owner of the home directory in which it resides - and thus needs to be chown'ed (usually using priv takeover) before it will run.

What about security?

For a very comprehensive introduction to this somewhat fraught subject, see the WWW Security FAQ.

For details on restricting web access to specific users / hosts / etc, see Restricting Web Access

Writing insecure server-side applications is all too easy, and an awful lot of the pre-built scripts freely available on the web have glaring security shortcomings. To ensure that security is not compromised by ill-considered (or even malicious!) programs, we have placed a number of security restrictions on CGI processes.

By restricting access to user home directories, running scripts as the file owner, and requiring that file ownership match the home directory, and preventing excess resource usage, we can effectively prevent badly-written, insecure, exploited, or even malicious programs from adversely affecting our systems to any great degree.

This doesn't mean that you shouldn't keep a defensive-coding attitude, though. Some useful security tips include:

• Ensure that your scripts are not world-readable, especially where they contain sensitive information such as database passwords
• Where appropriate, restrict access with .htaccess files - consider restricting access to specific users/classes/groups, restricting access to on-campus machines, etc.
• Wherever sensitive information is involved, including any kind of password authentication, please use SSL for greater security.

Error Messages

You may also want to check out the World Wide Web or Creating Website pages.