Chapter 3 Using CGI

Common Gateway Interface (CGI) programs run on the server and generate a response to return to the requesting client. CGI programs can be written in various languages, including C, C++, Java, Perl, and shell scripts. CGI programs are invoked through URL.

For more information about CGI, see

http://hoohoo.ncsa.uiuc.edu/cgi/overview.html

Sun Java System Web Server complies with the CGI specification version 1.1.

Since the server starts up a process each time the CGI script or program runs, this is an expensive method of programming the server.

This chapter has the following sections:

• Enabling CGI

• Creating Custom Execution Environments for CGI Programs (UNIX only)

• Adding CGI Programs to the Server

• Setting the Priority of a CGI Program

• Windows CGI and Shell CGI Programs

• Perl CGI Programs

• Global CGI Settings

• CGI Variables

Enabling CGI

Sun Java System Web Server provides two ways to identify CGI programs, which are listed below and described in this section:

• Specifying CGI Directories

• Specifying CGI File Extensions

Specifying CGI Directories

To specify directories that contain CGI programs (and only CGI programs) use the CGI Directory page in the Programs tab of the Class Manager. The server treats all files in these directories as CGI programs.

For each CGI directory, the file obj.conf contains a NameTrans directive that associates the name cgi with each request for a resource in that directory. These directives are automatically added to obj.conf when you specify CGI directories in the Class Manager interface, or you can manually add them to obj.conf if desired.

For example, the following instruction interprets all requests for resources in http://server-name/cgi-local as requests to invoke CGI programs in the directory C:/Sun/Servers/docs/mycgi:

NameTrans fn="pfx2dir" from="/cgi-local" dir="C:/Sun/Servers/docs/mycgi" name="cgi"

The obj.conf file must contain the following named object:

<Object name="cgi">
ObjectType fn="force-type" type="magnus-internal/cgi"
Service fn="send-cgi"
</Object>

Do not remove this object from obj.conf. If you do, the server will not recognize CGI directories, regardless of whether you specify them in the Class Manager interface or manually add more NameTrans directives to obj.conf.

Specifying CGI File Extensions

Use the CGI File Type page in the Programs tab of the Class Manager to instruct the server to treat all files with certain extensions as CGI programs, regardless of which directory they reside in. The default CGI extensions are .cgi, .bat, and.exe.

To change which extensions indicate CGI programs, modify the following line in the mime.types file to specify the desired extensions. Be sure to restart the server after editing mime.types.

type=magnus-internal/cgi exts=cgi,exe,bat

When the server is enabled to treat all files with appropriate extensions as CGI programs, the obj.conf file contains the following Service directive:

Service fn="send-cgi" type="magnus-internal/cgi"

Creating Custom Execution Environments for CGI Programs (UNIX only)

Before you can create a custom execution environment, you must install the suid Cgistub and run it as root:

To create custom execution environments for CGI programs

1. Log in as the superuser.

   su

2. Create the private directory for Cgistub:

   cd server_root/https-instance

   mkdir private

3. Copy Cgistub to the private directory:

   cd private

   cp ../../bin/https/bin/Cgistub .

4. Set the owner of private to the server user:

   chown user .

5. Set the permissions on private:

   chmod 500 .

6. Set the owner of Cgistub to root:

   chown root Cgistub

7. Set the permissions on Cgistub:

   chmod 4711 Cgistub

8. You can give each reference to the send-cgi SAF in obj.conf a user parameter. For example:

   Service fn="send-cgi" user="user"

   You can use variable substitution. For example, in server.xml add a VARS subelement to VS (virtual server) element.

   <VARS user="user"/>

   This lets you write the send-cgi SAF line in obj.conf as follows:

   Service fn="send-cgi" user="$user"

   For more information about send-cgi in the obj.conf file and server.xml, see the Sun Java System Web Server 6.1 SP11 Administrator’s Configuration File Reference.

9. Restart the server to update the changes into effect.

   ---

   Note –

   Installing Cgistub in the server_root/https-instance/private directory is recommended. If you install it anywhere else, you must specify the path to Cgistub in the init-cgi function in magnus.conf. For details, see the Sun Java System Web Server 6.1 SP11 NSAPI Programmer’s Guide.

   ---

   ---

   Note –

   It is not possible to install the suid Cgistub program on an NFS mount, you install your server instance to a local file system.

   ---

   Cgistub enforces the following security restrictions:

   • The user the CGI program executes as must have a uid of 100 or greater. This prevents anyone from using Cgistub to obtain root access.

   • The CGI program must be owned by the user it is executed as and must not be writable by anyone other than its owner. This makes it difficult for anyone to remotely execute programs.

   • Cgistub creates its UNIX listen socket with 0700 permissions.

   ---

   Note –

   Socket permissions are not respected on a number of UNIX variants, including current versions of SunOS/Solaris. To prevent a malicious user from exploiting Cgistub, change the server’s temporary directory (using the magnus.conf TempDir directive) to a directory accessible only to the server user.

   ---

   After you have installed Cgistub you can create custom execution environments by doing the following, as described in this section:

   • Specifying a Unique CGI Directory and UNIX User and Group for a Virtual Server

   • Specifying a Chroot Directory for a Virtual Server

Specifying a Unique CGI Directory and UNIX User and Group for a Virtual Server

To prevent CGI programs of the virtual server from interfering with other users, these programs should be stored in a unique directory and executed with the permissions of a unique UNIX user and group.

First, create the UNIX user and group. The exact steps required to create a user and group vary by operating system. For instructions, consult your operating system's documentation.

To create a cgi-bin directory for the virtual server

1. Log in as the superuser.

   su

2. Change to the virtual server directory.

   cd vs_dir

3. Create the cgi-bin directory.

   mkdir cgi-bin

   chown user:group cgi-bin

   chmod 755 cgi-bin

   Now you can set the virtual server’s CGI directory, user, and group in one of these ways:

   • Use the dir, user, and group parameters of the send-cgi Service SAF in the obj.conf file, see the Sun Java System Web Server 6.1 SP11 Administrator’s Configuration File Reference.

   • Enter this information using the Settings page in the Preferences tab of the Virtual Server Manager, see the Sun Java System Web Server 6.1 SP11 Administrator’s Guide.

Specifying a Chroot Directory for a Virtual Server

To further improve security, these CGI scripts should be prevented from accessing data outside the virtual server directory.

First, set up the chroot environment. The exact steps required to set up the chroot environment vary by operating system. For instructions, consult your operating system’s documentation. The man pages for ftpd and chroot are good place to start.

These are the steps required for Solaris versions 2.6 through 8

To specify a Chroot Directory for a Virtual Server

1. Log in as the superuser.

   su

2. Change to the chroot directory. This is typically the vs_dir directory mentioned in the previous section.

   cd chroot

3. Create tmp in the chroot directory:

   mkdir tmp

   chmod 1777 tmp

4. Create dev in the chroot directory:

   mkdir dev

   chmod 755 dev

5. List /dev/tcp, and note the major and minor numbers of the resulting output. In this example, the major number is 11 and the minor number is 42:

   ls -lL /dev/tcp

   crw-rw-rw- 1 root sys 11, 42 Apr 9 1998 /dev/tcp

6. Create the tcp device using the major and minor numbers:

   mknod dev/tcp c 11 42

   chmod 666 dev/tcp

7. Repeat steps 5 and 6 for each of the following devices each device will have a different major and minor combination:

   /dev/udp /dev/ip /dev/kmem /dev/kstat /dev/ksyms /dev/mem /dev/null /dev/stderr /dev/stdin /dev/stdout /dev/ticotsord /dev/zero

8. Set permissions on the devices in dev in the chroot directory:

   chmod 666 dev/*

9. Create and populate lib and usr/lib in the chroot directory:

   mkdir usr

   mkdir usr/lib

   ln -s /usr/lib

   ln /usr/lib/* usr/lib

   You can ignore the messages this command generates.

   If the /usr/lib directory is on a different file system, replace the last command with the following:

   cp -rf /usr/lib/* usr/lib

10. Create and populate bin and usr/bin in the chroot directory:

    mkdir usr/bin

    ln -s /usr/bin

    ln /usr/bin/* usr/bin

    You can ignore the messages this command generates.

    If the /usr/bin directory is on a different file system, replace the last command with the following:

    cp -rf /usr/bin/* usr/bin

11. Create and populate etc in the chroot directory:

    mkdir etc

    ln /etc/passwd /etc/group /etc/netconfig etc

12. Test the chroot environment:

    chroot chroot bin/ls -l

    The output should look something like this:

    lrwxrwxrwx   1 root   other   8 Jan 13 03:32 bin -> /usr/bin
    drwxr-xr-x   2 user    group   512 Jan 13 03:42 cgi-bin
    drwxr-xr-x   2 root   other   512 Jan 13 03:28 dev
    drwxr-xr-x   2 user    group   512 Jan 13 03:26 docs
    drwxr-xr-x   2 root   other   512 Jan 13 03:33 etc
    lrwxrwxrwx   1 root   other   8 Jan 13 03:30 lib -> /usr/lib
    drwxr-xr-x   4 root   other   512 Jan 13 03:32 usr

    Now you can set the chroot directory of the virtual server in one of these ways:

    • Use the chroot parameter of the send-cgi Service SAF in the obj.conf file, see the Sun Java System Web Server 6.1 SP11 Administrator’s Configuration File Reference.

    • Enter this information using the Settings page in the Preferences tab of the Virtual Server Manager, see the Sun Java System Web Server 6.1 SP11 Administrator’s Guide.

Adding CGI Programs to the Server

To add CGI programs to Sun Java System Web Server, do one of the following:

• Drop the program file in a CGI directory (if there are any).

• Give it a file name that the server recognizes as a CGI program and put it in any directory at or below the document root (if CGI file type recognition has been activated).

  For UNIX, make sure the program file has execute permissions set.

Setting the Priority of a CGI Program

The priority of a CGI program can be set using the nice parameter of the send-cgi function. This is a UNIX-only parameter and accepts an increment that determines priority of the CGI program relative to the server. The server is run with a nice value of 0 and the nice increment would be between 0 (the CGI program runs at same priority as server) and 19 (the CGI program runs at much lower priority than server). As with all other CGI variables, this can be configured per class or per virtual server.

For more information about send-cgi, see the Sun Java System Web Server 6.1 SP11 Administrator’s Configuration File Reference.

To configure CGI variables for a class:

• Access the Class Manager, click CGI Settings on the Virtual Server tab, and then specify the nice value as desired before clicking OK and applying your changes.

• Access the Server Manager, click the Virtual Server Class tab, and then click Edit Classes. Click Advanced, and specify the nice value as desired before clicking OK and applying your changes.

  All virtual servers in the specified class will inherit the value from the class. You can override this by setting the value for an individual virtual server, as described below.

To configure CGI variables for a virtual server

1. Access the Class Manager, and then click Manage Virtual Servers on the Virtual Servers tab.

2. Select a virtual server, click Manage, and then click Settings.

3. Specify the nice value as desired, and then click OK to apply your changes.

   The value overrides any value set at the class level.

Windows CGI and Shell CGI Programs

For information about installing CGI and shell CGI programs on Windows using the Class Manager interface, see the Sun Java System Web Server 6.1 SP11 Administrator’s Guide.

Perl CGI Programs

You cannot run CGIs using Perl 5.6.x with the -w flag. Instead, include the following code in the file:

use warnings;

Global CGI Settings

To change global CGI settings

1. Access the Server Manager, and click the Magnus Editor page.

2. Select CGI Settings from the drop-down list, and then click Manage.

3. In the Magnus Editor, specify values for the following settings:

   • MinCGIStubs. Controls the number of processes that are started by default. Note that if you have an init-cgi directive in the magnus.conf file, the minimum number of CGIStub processes are spawned at startup. The value must be less than the MaxCGIStubs value.

   • CGIExpirationTimeout. Specifies the maximum time in seconds that CGI processes are allowed to run before being killed.

   • CGIStubIdleTimeout. Causes the server to kill any CGIStub processes that have been idle for the number of seconds set by this directive. Once the number of processes is at MinCGIStubs, the server does not kill any more processes.

   • MaxCGIStubs. Controls the maximum number of CGIStub processes the server can spawn. This is the maximum concurrent CGIStub processes in execution and not the maximum number of pending requests.

4. Click OK and apply your changes.

   For more information about these global CGI settings, see the description of magnus.conf file in the Sun Java System Web Server 6.1 SP11 Administrator’s Configuration File Reference.

CGI Variables

In addition to the standard CGI variables, you can use the Sun Java System Web Server CGI variables in CGI programs to access information about the client certificate if the server is running in secure mode. The CLIENT_CERT and REVOCATION variables are available only when client certificate-based authentication is enabled.

The following table lists the Sun Java System Web Server CGI variables. The left column lists the variable, and the right column provides a description.