CGI module

CGI/1.1 support

Overview
The CGI Interface is a popular means of creating dynamic content on the web. Zeus Server fully supports the CGI/1.1 specification. The CGI module is responsible for invoking CGI programs, passing input to them and returning their output.

Reference

Configuration

ACCESS CONTROL

For improved security on a web server hosting many different users' homepages, many people restrict CGI programs to only those in designated directories. This way a webmaster can ensure that only programs that he/she has put into these directories are available to users. Such directories can be setup by the map module.

Alternatively, the CGI module may be configured to execute any file in the documentation tree with the correct MIME type (of application/x-httpd-cgi) as a CGI script. This is generally much more convenient.

Access restrictions can also be placed on SSI <!--#exec cmd="..."> commands. If this option is enabled, and the CGI module is configured to recognize CGIs in the document tree, then exec cmd commands will be processed, otherwise they will be denied.

Select which option is required and click on "Update" to use the new settings.

ENVIRONMENT VARIABLES

CGI programs receive some of their information from environment variables which are set by the CGI module. Additional environment variables can be set from the CGI Configuration page.

Enter the variable name and value into the text fields and click on the "add" button. The new variable will be passed to the CGI program when it is invoked. To delete a set variable, click on the "delete" button.

SANDBOXING

CGI programs run as individual, unique processes, this can result in problems when a CGI script is badly written or receives data different to that it was expecting. In these cases a CGI can claim excessive amounts of system resources. If your server machine is spending most of its time processing CGI programs its HTTP performance will suffer. The situation is compounded with a large number of virtual servers, where a single Virtual Server could be responsible for ninety percent of CGI usage. CGI Sandboxing allows limits to be placed on the amount of resources a Virtual Servers CGI programs can consume.

CGI Sandboxing resource restrictions depend on the implementation of the ulimit system call within the operating system. Some operating systems fully support all options, some only a subset, and some none at all. For more details consult your operating system documentation.

Ulimit Configurables

Max Elapsed time: Sets the maximum elapsed time that a CGI program can run for. After this time it will be stopped, first with a SIGTERM, and then every second after that with a SIGKILL. This configurable is platform independent and is not a function of ulimit.
Max CPU time: Sets the maximum amount of CPU time a process can consume. This provides a means to restrict large CGI process from monopolizing the servers CPU.
Max Address space: Sets the maximum address space for each CGI process. This is the total amount of memory the process can use. Setting a small limit will only allow small CGI programs to be run. Small limits are suitable for sites which have compiled CGI programs, however interpreted CGI scripts will need larger limits.
Max data segment: Sets the maximum data segment for each CGI process. This is the maximum amount of space a process can use for its internal data structures. A small value restricts a badly written CGI program from claiming large amounts of memory.
Can CGI scripts fork(): Determines whether CGI scripts are allowed to fork() to create new processes. This can prevent a problem known as 'fork bombs' where a program forks many times and eventually prevents other programs from being run.

If you intend to use the CGI Sandbox environment you should consult the ulimit(1) man page for your system.

Limiting Number of Concurrent scripts

It is possible to limit the number of concurrent scripts that can be executed at the same time. In a clustered environment, this limit is per machine. If Subservers are turned on then the limit can be applied per Subserver or for the entire Virtual Server.

This setting is independent of the ulimit option that limits the number of processes per cgi user, as that limit only effects programs that are fork()'ed from CGI scripts, not the number of CGI scripts running.

Security Configurables

Additional security limits can be placed on CGI programs, by changing the user id of the invoked CGI processes. Having different CGI users for different Virtual Servers allows different ulimit configuration options to be applied. You can be assured that a CGI process on one virtual server will not interfere with another on a different server. Using individual user id's for each Virtual Servers CGI processes can also assist system monitoring and performance analysis. If ulimit is not implemented in your Operating System, you can still run CGI programs as different users, but will not be able to apply different resource limits.

There are three methods of setting a CGI processes user id. The Zeus Web Server can:

If you allow users to have CGI programs within their home directories the file system option may be useful; however you should ensure that no system wide CGI programs are owned by root.

If you use the Zeus Subserver module to host large numbers of web sites, you can arrange that CGI scripts run as the user id of each individual document root by selecting the 'Use the owner and group of the web site's document root' option.

If no CGI ownership options are configured the CGI process will be owned by the user which Zeus Server runs as. For details of this see the associated documentation

Zeus Server can also make use of the UNIX chroot command to restrict a CGI process to a limited sub section of the file system. This can ensure that a CGI program does not (by design or otherwise) leak sensitive system information from the server machine. If enabled, chroot the CGI program will be started, with the directory it resides in as the root of the file system. This leads to greater security, but also additional administration. CGI programs will often require additional components such as interpreters or shared libraries. You may need to install a minimal root file system within the CGI directory. For more details see the chroot man page.

To take advantage of the CGI Sandbox options, the web server needs to be started initially as root. This is the same requirement for the web server to be able to run web sites on port 80. The web server should still be configured to switch to a non-root user during normal request processing, but the Zeus Web Server progam needs be started as the root user (when running $ZEUSHOME/start-zeus) for CGI Sandboxing options to be available.

Enter the values documented above into the text fields and click on the "update" button to commit the changes. A value of "0" allows no CGI restrictions.

Chroot Jails

If chrooting is enabled, by default CGIs will be chrooted to the directory the CGI lives in. This means any system files required in the chrooted environment have to be installed for each directory in which CGIs are run.

Chroot jails can be defined which allow CGIs to be chrooted to a parent directory of the CGI script. Before a CGI script is chrooted, the server checks if any jail directories are parent directories of the CGI script. If a jail directory is found, the CGI is chrooted to that directory, otherwise it is chrooted to the same directory the CGI lives in. If multiple jail directories match, the longest one is used.

If the directory begins with a '~' then the Web Server interprets the remainder as a regular expression. It will attempt to match the regular expression at the start of the path of the CGI script. If it matches, the matching directory is used as the directory to chroot to.

For example, if the chrootdir was ~/home/[^/]+/ it would match any directory /home/.../

For further information on regular expressions, refer to regex.

Chroot jail directories can also be configured using the Zeus Web Server htaccess module. htaccess settings override the settings in the CGI module.

With the htaccess module, you can configure generic chroot jails of the form '%docroot%/my/path' or '%docroot%/../my/path', which allows you to configure individual private (non-shared) jails for multiple Subserver web sites.

CGI error logging

By default, all errors from CGI scripts (output from stderr) will be output to the Virtual Server error log. In a Subserver environment, this setup means that it is impossible to differentiate between errors from different servers. With this option enabled, it is possible to cause cgi errors to go to different depending on the Subserver that caused them.

%'s in the filename are expanded and then the cgi script will have stderr piped to the resulting file.

Once the maximum size of the error log has been reached, it will be emptied. Setting this value to 0 will disable the truncation of the file.

For example if the filename specified is:

	%r/../logs/cgi-errors.%t
	
and the docroot of the host being accessed is:
	/home/website/main/docroot
      
then the cgi errors will get logged to:
	/home/website/main/logs/cgi-errors.{todays date}
      

Global settings

Global limits on the minimum uid/gid to run a CGI as can be configured for the CGI module. These settings live in the global.cfg configuration file for the web server.
Configuration setting Description Default value
tuning!modules!cgi!minuid <int>
Lowest UID to run a CGI as. Requests to run a CGI with a uid lower than this value are run as defaultuid. 0
tuning!modules!cgi!defaultuid <int>
See minuid. 65534
tuning!modules!cgi!mingid <int>
Lowest GID to run a CGI as. Requests to run a CGI with a gid lower than this value are run as defaultgid. 0
tuning!modules!cgi!defaultgid <int>
See mingid. 65534