What is a CGI script?
A CGI script is a program you create that allows you to generate dynamic WWW pages, i.e. pages that can look different each time they are opened. The content may depend on the current time, the contents of various files, the address of the computer from which the page is visited, etc.
How to create a CGI script
A CGI script is any (server-side) executable file (but usually a script - hence the name) that, when run, outputs the HTTP header of a page (not to be confused with the HTML header) and then its actual content to standard output. This can be classic HTML text, but can also be any other type of data.
The script should generate at least the header
Content-Type: followed by a blank line that indicates the end of the header. An example of a simple CGI script written in the shell
#!/bin/bash echo "Content-Type: text/html" echo echo "<body>" echo "my first example page \o/" echo "<pre>" date echo "</pre>" echo "</body>"
/bin/bash is the full path to the interpreter that should run the script on the server. It can be Bash, Perl, PHP or anything else. Beware, however, if you write your pages and scripts in editors or on systems that also store the
CR character (Ctrl-M, ^M) at the end of lines - typically Windows programs. Then what you would be looking for is not the
bash program in the
/bin directory, but some kind of
bash^M program, which of course doesn't exist.
Content-Type: is in this case
text/html, which for a WWW server means that the CGI script generates an HTML page. If the script were generating, say, an image,
Content-Type would be, say,
The CGI script must be executable on Aise. For the WWW server to recognize that it is a CGI script, the script must have a .cgi extension.
User CGI scripts available under /~xlogin/
The CGI script must be executable by the owner, which you ensure with the command:
chmod u+x ~/public_html/script.cgi
If it is not a binary program, but actually a script, you also need to set the owner read permission.
Scripts are executed using the
suexec mechanism, which allows the script to be executed under the identity of the owner. It also checks some security conditions. The basics are: the script must belong to the user that is listed in the URL (
https://www.fi.muni.cz/~xlogin/) and to the group that this user has as primary (can be found with the command
id). Neither the script nor the parent directory must be write-enabled for the group and others. Suexec logs its activity to the file
/var/log/httpd-user/suexec. In case of unmet security conditions, you can find the specific cause of the failure here.
CGI scripts stored outside the /~xlogin/ tree
These CGI scripts must be executable (permissions
setfacl -m u:apachefi:r-x script.cgi. Runnable CGI scripts run under the identity of the user
apachefi, and the behaviour of the script must therefore be adapted to this. Typically, for example, this user can only write to the
Special variables in CGI scripts, working with parameters in URLs
The WWW server sets several new variables that you can work with in a CGI script. You can find out which ones they are by following the example given in the section
on debugging CGI scripts. Specifically, if you pass parameters to a CGI script (using the GET method), they will be available in the
QUERY_STRING variable. In a shell CGI script, the processing of parameters might look like this:
#!/bin/bash . /packages/run.64/bashlib-0.4/bin echo Content-type: text/plain echo HOST=$(param host) /usr/bin/host $HOST
This program will store the value of the parameter
host in the variable
HOST. So if you call the program using the URL
https://www.fi.muni.cz/~xlogin/this_script.cgi?host=aisa, its output will be the output of
host aisa. (See bashlib for more on
If you pass parameters using the
POST method, the data is passed to the standard CGI script input.
CGI scripts and security
It is important to note that if a CGI script is invoked in the
/~xlogin/ subtree , it
runs under your identity. Therefore, if you make a security mistake in the script, your data on the server may be lost/altered or your identity may be otherwise compromised. Therefore, always check your script thoroughly before publishing it, and expect that someone may try to check the robustness and resilience of your script on their own. This is especially true for parameter handling.
Also keep in mind that the examples given on this page are illustrative (albeit functional) and may not be written securely. Before you start writing CGI scripts, it is recommended that you read up on the subject on the web.
Debugging CGI scriptsWe recommend that you first try running the CGI script from the command line directly on Aise. Here you can catch e.g. interpreter error messages. It is very likely that after running under the user
apachefithe script will not have some environment variables set (typically
LD_LIBRARY_PATH, ...). For example, the following code will tell you the current state of the variables when the CGI script is running:
#!/bin/bash echo "Content-type: text/plain" echo set
Debugging Perl scripts:
use CGI, which allows you to debug scripts on the command line, including parameters.
use CGI::Carp qw(fatalsToBrowser), which will display error messages to the browser.
Debugging shell scripts:
- Just after the initial
#!/bin/bash), add the line
exec 2>/home/xlogin/public_html/stderr.log, which redirects the error output to a file.
- If you are using modules, you need to initialize them first. See the page about modules for more details.
What to do if it still doesn't work:
- Reread this page.
- Double-check that you have the correct access rights on the
~/public_htmldirectory and nested (see the page on user HTML pages for details.
- Double-check that the CGI script has the extension
- Recheck the access rights on the CGI script and its relevant environment.
- Try running the CGI script again manually on Aise from the command line.
- If the script works on the command line but not when accessed via the WWW, look in the WWW server logs for a possible cause. Where are the logs stored?
- Consult with more experienced colleagues.
- Consult with administrators.