Sun Java System Web Server 7.0 Update 8 Developer's Guide

Chapter 3 Using Common Gateway Interface

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 the C, C++, Java, and Perl languages, and as shell scripts. CGI programs are executed through URL invocation.

For information about writing CGI programs, see http://hoohoo.ncsa.uiuc.edu/cgi/overview.html

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

This chapter has the following sections:

Configuring CGI Settings

You can configure the Web Server to recognize and execute 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.

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>


Note –

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 Administration Console or manually add more NameTrans directives to obj.conf.


ProcedureTo Enable CGI

  1. In the Admin Console, Select Common Tasks tab.

  2. Select CGI Directories from the Virtual Server Tasks list.

    The CGI Settings page is displayed.

  3. Select the CGI as file type Enabled option.

ProcedureTo Specify CGI Directories

You can specify a directory that contains only CGI programs. All files are run as programs regardless of the file extensions.

  1. In the Admin Console, Select the Common Tasks tab.

  2. Select CGI Directories from the Virtual Server Tasks list.

    The CGI Directory window is displayed.

  3. Click New.

    The Add CGI Directory window is displayed.

  4. Specify the URI and path where the CGI programs are stored.

    For example, if you type cgi-bin as the URL prefix, then all URLs to these CGI programs have the following structure:

    http://yourserver.domain.com/cgi-bin/


Example 3–1 Using the create-cgi-dir command

To specify the CGI directory by using the create-cgi-dir command:

./wadm create-cgi-dir --user=admin --password-file=admin.pwd --host=serverhost --port=8989 --config=config1 --vs=config1_vs_1 --uri-prefix=/config1_urlprefix --directory=/cgi-dir


Specifying CGI File Extensions

You can configure CGI programs to have the file extensions .cgi, .exe, or .bat. The programs can be located in any directory in or under the document root directory of the virtual server.

By default, the file extensions for CGI programs are .cgi, .exe, and .bat. However, you can change which extensions indicate CGI programs by the following line in the MIME types file:

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

Restart the server after editing mime.types.

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

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

For more information on configuring CGI for your server, see the Configuring CGI Subsystem for Your Server in Sun Java System Web Server 7.0 Update 8 Administrator’s Guide.

Creating Custom Execution Environments for CGI Programs

Creating custom execution environment includes the following steps:

  1. Installing suid and Cgistub

  2. Creating a cgi-bin directory

  3. Specifying a chroot directory for the virtual server

Cgistub enforces the following security restrictions:

ProcedureTo Install the suid and Cgistub Directories

You cannot install the suid Cgistub program on an NFS mount. If you want to use an suid Cgistub, you must install your server instance to a local file system.

  1. Log in as a superuser.

  2. Create the private directory for Cgistub in the install-dir/https-instance/private directory:

    cd install-dir/https-instance

    mkdir private


    Note –

    If you install Cgistub in any other directory, you must specify the path to Cgistub in the init-cgi function in the magnus.conf file. For details, see the Sun Java System Web Server 7.0 Update 8 Administrator’s Configuration File Reference.


  3. Copy Cgistub to the private directory.

    cd private

    cp ../../lib/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. Provide 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, give a virtual-server element the following variable subelement:

    <variable user="user"\>

    This modification to server.xml means, you can write the send-cgi SAF line in the obj.conf as follows:

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

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

  9. Restart the server to apply the changes.

ProcedureTo Create a cgi-bin Directory and Define User and Group

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

Before You Begin

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

  1. Log in as a superuser.

  2. Change to the document root directory for the virtual server.

    cd document-root

  3. Create the cgi-bin directory and set appropriate permissions.


    mkdir cgi-bin
    chown user:group cgi-bin
    chmod 755 cgi-bin
  4. Set the virtual server’s CGI directory, user, and group in one of the following ways.

    • Modify the obj.conf file.

      Use the user and group parameters of the send-cgi Service SAF in the obj.conf file. For detailed instructions, see the Sun Java System Web Server 7.0 Update 8 Administrator’s Configuration File Reference.

    • In the Admin Console,

      1. Select Common Tasks tab. .

      2. Select CGI Directories from the Virtual Server Tasks list

        The CGI Settings window is displayed.

      3. Type the user and the group that can execute CGI programs.

        For more information on CGI directories, see the Sun Java System Web Server 7.0 Update 8 Administrator’s Guide.

    • Use the set-cgi-prop command to define a unique CGI directory, UNIX user and group for a virtual server.

      For example:

      /wadm set-cgi-prop --user=admin --password-file=admin.pwd --host=serverhost --port=8989 --config=config1 user=admin group=group

ProcedureSpecifying a Chroot Directory for a Virtual Server

To further improve security, the CGI scripts must be prevented from accessing data above and outside of the document-root directory.

Before You Begin

Set up the chroot environment. The exact steps required to set up the chroot environment vary by operating system. For instructions, refer your operating system’s documentation, and see the man pages for the ftpd and chroot commands.

Steps required for Solaris versions 2.8 through 10 are described in the following procedure:

  1. Log in as a superuser.

  2. Change to the chroot directory.

    chroot is typically the document-root directory of the virtual server.

    cd chroot

  3. Create tmp in the chroot directory and set appropriate permissions.

    mkdir tmp

    chmod 1777 tmp

  4. Create dev in the chroot directory and set appropriate permissions.

    mkdir dev

    chmod 755 dev

  5. List /dev/tcp, and note the major and minor numbers of the resulting output.

    # ls -lL /dev/tcp

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

    In this example, the major number is 11 and the minor number is 42.

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

    mknod dev/tcp c 11 42

    chmod 666 dev/tcp

  7. Repeat steps 4, 5, and 6 for each of the following devices.


    Note –

    Each device will have a different major and minor number 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, use the following command:

    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, use the following command:

    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 like this example:


        total 14
         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
  13. Set the virtual server’s chroot directory in one of the following ways.

Adding CGI Programs to the Server

To add CGI programs to the server, do one of the following:


Note –

On UNIX platforms, 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 UNIX-only parameter accepts an increment that determines the CGI program’s priority relative to the priority of the server process. Typically, the server is run with a nice value of 0. The nice increment can be between 0 and 19.

0

The CGI program runs at the same priority as the server

19

The CGI program runs at a much lower priority than the server

As with all other CGI variables, the nice value can be configured for each virtual server.


Note –

Do not increase the priority of the CGI program above that of the server by specifying a nice increment of -1.


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

ProcedureTo Configure CGI Properties for a Virtual Server

You can configure CGI variables for a virtual server either using the Admin Console or using the CLI. The following procedure describes the steps:

  1. In the Admin Console, select the Common Tasks tab.

  2. Select CGI Directories from the Virtual Server Tasks list.

    The CGI Settings window is displayed.

  3. Specify the nice value as desired.

  4. Click Save to apply your changes.


Example 3–2 To configure CGI properties for a virtual server by using the set-cgi-prop command:

./wadm set-cgi-prop --user=admin --password-file=admin.pwd --host=serverhost --port=8989 --config=config1 nice=5


Shell CGI Programs

Shell CGI is a text file that contains commands for the Bourne Shell command interpreter. You can use any text editor to create a shell CGI program. Shell CGI programs are typically given the suffix .sh.

For information about installing CGI and shell CGI programs on Windows using the Admin Console, see the Sun Java System Web Server 7.0 Update 8 Administrator’s Guide.

Perl CGI Programs

Web Server 7.0 bundles a Perl interpreter to run CGI programs that are written in the Perl programming language. The Perl interpreter is located at install-dir/lib/perl.

On Windows platform, file associations need to be in place for CGI programs to run. Files with a .pl filename extension need to be associated with the Perl interpreter executable before they can be executed as CGI programs. To create an association for Perl programs to run as CGI programs, perform the following steps:


Note –

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

use warnings;

This section describes the steps to configure the server to execute Perl programs as CGI programs.

ProcedureTo Configure Perl Programs to Execute as CGI Programs

  1. Create a simple Perl program called hello.pl.

    #!<server_root>/lib/perl/perl
    print "Content-type:text/html\n\n";
    print "Hello World!";
  2. Create a directory for this program.

    By convention, this directory is named cgi-bin and is located under the instance configuration directory. For example:


    mkdir /var/opt/SUNWwbsvr7/cgi-bin
  3. Copy the hello.pl file into the /var/opt/SUNWwbsvr7/cgi-bin directory.

  4. In the Admin Console, select the Common Tasks tab.

  5. Select CGI Directories from the Virtual Servers Tasks list.

    The CGI Settings window is displayed.

  6. Click the New button in the CGI Directories section.

    The Add CGI Directories window is displayed.

  7. Type the Prefix and the CGI directory path.

  8. Choose whether the program is a CGI or a ShellCGI program.

    For example:

    On UNIX platforms:

    Prefix: /cgi-bin

    CGI Directory: /var/opt/SUNWwbsvr7/cgi-bin

    On Windows platforms:

    Prefix: \cgi-bin

    CGI Directory: c:\sun\webserver7\cgi-bin


    Note –

    The CGI directory that you specify must have execute permissions.


  9. Click Save to save the changes.

  10. Access the program from a browser window.

    Open a browser window. For example, your server is called acme, and is running on port 2222, you would type http://acme:2222/cgi-bin/hello.pl.

    This example displays the message “Hello World” in the browser window.

Global CGI Settings

You can change the CGI settings globally for all available virtual servers. You can either use the Administration Console or the CLI.

ProcedureTo Change Global CGI Settings

  1. In the Admin Console, Click the Configuration tab.

    List of available configurations is displayed.

    For more information on the set-cgi-prop command, see the Sun Java System Web Server 7.0 Update 8 CLI Reference Manual.

  2. Select a configuration from the list.

  3. Select Performance tab > CGI subtab.

    The CGI Settings window is displayed.

  4. Specify the values for the following settings:

    CGI Timeout Settings:

    • Timeout (CGIExpirationTimeout) Specifies the time in seconds after which the server terminates a long-running CGI program.

    • Idle Timeout(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.

    CGI Stub Process Settings:

    • Timeout Time in seconds after which an unused CGI stub process is terminated.

    • CGI Stub Excecutable Controls the number of processes that are started by default. The first CGIStub process is not started until a CGI program has been accessed. The default value is 2. If you have a init-cgi directive in the magnus.conf file, the minimum number of CGIStub processes are created at startup. this setting controls the number of processes that are started by default.

    • Minimum Stub Size Controls the maximum number of CGIStub processes the server can create. This setting is the maximum concurrent CGIStub processes in execution, not the maximum number of pending requests. The value must be less than the Maximum Stub Size.

    • Maximum Stub Size Controls the maximum number of CGIStub processes the server can create. This setting is the maximum concurrent CGIStub processes in execution, not the maximum number of pending requests.

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

  5. Click Save to apply your changes.


Example 3–3 To change global CGI settings by using the set-cgi-prop command:

./wadm set-cgi-prop --user=admin --password-file=admin.pwd --host=serverhost --port=8989 --config=config1 timeout=10 max-cgistubs=20 idle-timeout=600 min-cgistubs=10 cgistub-idle-timeout=60 cgistub-path=../../lib/Cgistub

For more information about the set-cgi-prop command, see the Sun Java System Web Server 7.0 Update 8 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 CGI variables.

Table 3–1 CGI Variables

Variable  

Description  

SERVER_URL

URL of the server that the client requested 

HTTP_xxx

An incoming HTTP request header, where xxx is the name of the header

HTTPS

ON if the server is in secure mode, otherwise OFF

HTTPS_KEYSIZE

Keysize of the SSL handshake (available if the server is in secure mode) 

HTTPS_SECRETKEYSIZE

Keysize of the secret part of the SSL handshake (available if the server is in secure mode) 

HTTPS_SESSIONID

Session ID for the connection (available if the server is in secure mode) 

CLIENT_CERT

Certificate the client provided (binary DER format) 

CLIENT_CERT_SUBJECT_DN

Distinguished Name of the subject of the client certificate 

CLIENT_CERT_SUBJECT_OU

Organization Unit of the subject of the client certificate 

CLIENT_CERT_SUBJECT_O

Organization of the subject of the client certificate 

CLIENT_CERT_SUBJECT_C

Country of the subject of the client certificate 

CLIENT_CERT_SUBJECT_L

Location of the subject of the client certificate 

CLIENT_CERT_SUBJECT_ST

State of the subject of the client certificate 

CLIENT_CERT_SUBJECT_E

Email address of the subject of the client certificate 

CLIENT_CERT_SUBJECT_UID

UID part of the CN of the subject of the client certificate 

CLIENT_CERT_ISSUER_DN

Distinguished Name of the issuer of the client certificate 

CLIENT_CERT_ISSUER_OU

Organization Unit of the issuer of the client certificate 

CLIENT_CERT_ISSUER_O

Organization of the issuer of the client certificate 

CLIENT_CERT_ISSUER_C

Country of the issuer of the client certificate 

CLIENT_CERT_ISSUER_L

Location of the issuer of the client certificate 

CLIENT_CERT_ISSUER_ST

State of the issuer of the client certificate 

CLIENT_CERT_ISSUER_E

Email address of the issuer of the client certificate 

CLIENT_CERT_ISSUER_UID

UID part of the CN of the issuer of the client certificate 

CLIENT_CERT_VALIDITY_START

Start date of the certificate 

CLIENT_CERT_VALIDITY_EXIRES

Expiration date of the certificate 

CLIENT_CERT_EXTENSION_xxx

Certificate extension, where xxx is the name of the extension

REVOCATION_METHOD

Name of the certificate revocation method if it exists 

REVOCATION_STATUS

Status of certificate revocation if it exists 

FastCGI

FastCGI is an enhancement to the CGI, which is a standard for interfacing external applications with Web Servers. Like CGI, FastCGI applications run in separate, isolated processes. The FastCGI plug-in enables Web Server to safely work with popular third-party dynamic content generation technologies such as Perl and Python in a scalable way.

For information on creating FastCGI applications, see the Appendix B, FastCGI Plug-in, in Sun Java System Web Server 7.0 Update 8 Administrator’s Guide.