Skip to ContentSun and Oracle Channel Sun How to Buy Log In

Sun Java System Web Server 7.0 Developer's Guide

Contained Within

Sun Java System Web Server 7.0

Find More Documentation

Featured Support Resources

Download this book in PDF (702 KB)

Previous: 2. Server-parsed HTML Tags

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 various languages, including C, C++, Java, Perl, 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.

This section discusses the following topics:

Enabling CGI

Using the Admin Console:

Select Common Tasks tab > CGI Directories from the Virtual Server Tasks list.

The CGI Settings page is displayed.

Select the CGI as file type Enabled box.

Specifying CGI Directories

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

Using the Admin Console:
1. Select Common Tasks tab > CGI Directories from the Virtual Server Tasks list.
  
  The CGI Directory window is displayed.
2. Click New.
  
  The Add CGI Directory window is displayed.
3. Specify the URI and path where the CGI programs are stored.
  
  For example, if you enter cgi-bin as the URL prefix, then all URLs to these CGI programs have the following structure:
  
  http://yourserver.domain.com/cgi-bin/

Using the Command-Line Interface (CLI):
1. You can also specify the CGI directory using the create-cgi-dir command.
  
  The syntax of the command is as follows:
  
  create-cgi-dir [--user|-u admin-user] [--password-file|-w admin-pswd-file] [--host|-h admin-host] [--port|-p admin-port] [--no-ssl|-N] [--echo|-e] [--rcfile|-R rcfile] [--no-prompt|-Q] [--verbose|-v] --config|-c name --vs|-s name [--shell-cgi=boolean] --uri-prefix|-r prefix --directory|-d dir
  
  Example:
  
  ./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

Changes to the `obj.conf` File

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.

Specifying CGI File Extensions

You can associate the file types for CGI programs. That is, you can configure the 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 modifying the MIME types file.

Modify the following line in the mime.types file to specify the desired extensions.
```
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"
```

Creating Custom Execution Environments for CGI Programs

Creating custom execution environment includes the following steps:

Installing suid and Cgistub
Creating a cgi-bin directory
Specifying a chroot directory for virtual server

To Install `suid` and `Cgistub` Directories

Create the private directory for Cgistub:

cd install_dir/https-instance

mkdir private

Note –
Installing Cgistub in the install_dir/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 7.0 Administrator’s Configuration File Reference.

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

Copy Cgistub to the private directory:

cd private

cp ../../lib/Cgistub.

Set the owner of private to the server user:

chown user .

Set the permissions on private:

chmod 500.

Set the owner of Cgistub to root:

chown root Cgistub

Set the permissions on Cgistub:

chmod 4711 Cgistub

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, give a virtual-server element the following variable subelement:

<variable user="user"\>

This modification to the server.xml allows you to 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 and , see the Sun Java System Web Server 7.0 Administrator’s Configuration File Reference.

Restart the server to apply the changes.

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 covertly inject and then 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 Sun operating systems/Solaris. To prevent a malicious user from exploiting Cgistub, ensure that the server's temporary directory is set (using the server.xml temp-path element) to a directory accessible only to the server user.

To 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 systems' documentation.

Change to the document root directory for the virtual server.

cd document-root

Create the cgi-bin directory and set appropriate permissions.
1. mkdir cgi-bin
2. chown user:group cgi-bin
3. chmod 755 cgi-bin

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 Administrator’s Configuration File Reference.
- Use the Admin Console.
  1. Select Common Tasks tab > CGI Directories from the Virtual Server Tasks list.
    
    The CGI Settings window is displayed.
  2. Enter the user and the group who can execute CGI programs.
    
    For more information on CGI directory, see the Sun Java System Web Server 7.0 Administrator’s Guide.
- Use the set-cgi-prop command to define a unique CGI directory, UNIX user and group for a virtual server.
  
  The syntax of the command is:
  
  ./wadm set-cgi-prop [--user|-u admin-user] [--password-file|-w admin-pswd-file] [--host|-h admin-host] [--port|-p admin-port] [--no-ssl|-N] [--echo|-e] [--rcfile|-R rcfile] [--no-prompt|-Q] [--verbose|-v] --config|-c name [--vs|-s name] (propertyname=value)
  
  For example:
  
  /wadm set-cgi-prop --user=admin --password-file=admin.pwd --host=serverhost --port=8989 --config=config1 user=admin group=group

Specifying 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. The man pages for ftpd and chroot are often a good place to start.

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

Change to the chroot directory.

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

cd chroot

Create tmp in the chroot directory and set appropriate permissions.

mkdir tmp

chmod 1777 tmp

Create dev in the chroot directory and set appropriate permissions.

mkdir dev

chmod 755 dev

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.

Create the tcp device using the major and minor numbers.

mknod dev/tcp c 11 42

chmod 666 dev/tcp

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

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

chmod 666 dev/*

Create and populate lib and usr/lib in the chroot directory:
1. mkdir usr
2. mkdir usr/lib
3. ln -s /usr/lib
4. 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

Create and populate bin and usr/bin in the chroot directory:
1. mkdir usr/bin
2. ln -s /usr/bin
3. 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

Create and populate etc in the chroot directory.

mkdir etc

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

Test the chroot environment.

chroot chroot bin/ls -l

The output should look something like this:

    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

Set the virtual server’s chroot directory in one of the following ways:
- Modify the obj.conf file.
  
  Use the chroot parameter of the send-cgi Service SAF in the obj.conf file. For detailed instructions, see the Sun Java System Web Server 7.0 Administrator’s Configuration File Reference.
- Use the Admin Console.
  1. Select Common Tasks tab > CGI Directories from the Virtual Server Tasks list.
    
    The CGI Settings window is displayed.
  2. Enter the Chroot directory.
    
    For detailed instructions, see the Sun Java System Web Server 7.0 Administrator’s Guide.
- Use the set-cgi-prop command.
  
  Example: ./wadm set-cgi-prop --user=admin --password-file=admin.pwd --host=serverhost --port=8989 --config=config1 chroot=vs_dir
  
  For information on the set-cgi-prop command, see the Sun Java System Web Server 7.0 Administrator’s Configuration File Reference.

Adding CGI Programs to the Server

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

Store 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).

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 is a UNIX-only parameter and 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 and the nice increment can be between 0 and 19.

0: The CGI program runs at the same priority as 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 per virtual server.

Note –

While it is possible to increase the priority of the CGI program above that of the server by specifying a nice increment of -1, Sun does not recommended you to do so.

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

To 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:

Configure CGI variables.

Using the Admin Console:
1. Select Common Tasks tab > CGI Directories from the Virtual Server Tasks list.
  
  The CGI Settings window is displayed.
2. Specify the nice value as desired.
3. Click Save to apply your changes.

Using the set-cgi-prop command.

Example:

./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 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:

Open a command-line window from start-> run -> cmd.
Create an association for Perl programs.
- C:\>assoc .pl=perl
- C:\>ftype perl="c:\WS7\lib\perl\perl.exe" "%1"

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.

To Configure Perl Programs to Execute as CGI Programs

Create a simple Perl program called hello.pl.
1. Use a text editor to create a file called hello.pl and copy the following lines into it:
```
#!install_dir/lib/perl/perl
print "Content-type:text/html\n\n";
print "Hello World!";
```

Create a directory for this program. By convention, this directory is named as the cgi-bin directory though you can name it whatever you like.

It is recommended that you create the cgi-bin directory under the instance configuration directory. For example:
mkdir /var/opt/SUNWwbsvr7/cgi-bin

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

Select Common Tasks tab > CGI Directories from the Virtual Servers Tasks list.

The CGI Settings window is displayed.

Click the New button in the CGI Directories section.

The Add CGI Directories window is displayed.

Enter the Prefix and the CGI Directory path. 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 you specified must have execute permissions.

Click Save to save the changes. Access the program from a browser window.

Open a browser window. If your server is called acme, running on port 2222), type http://acme:2222/cgi-bin/hello.pl.

Displays the message “Hello World” on 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.

To Change Global CGI Settings

You can use either the Admin Console or the CLI to change the global CGI settings:

Using the Admin Console:
1. Click the Configuration tab.
  
  List of available configurations is displayed.
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 spawned at startup. Controls the number of processes that are started by default.
  - Minimum Stub Size Controls the maximum number of CGIStub processes the server can spawn. This 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 spawn. This 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 Administrator’s Configuration File Reference.
5. Click Save to apply your changes.

Using the set-cgi-prop command.

Example:

./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 on the set-cgi-prop command, see the Sun Java System Web Server 7.0 CLI Reference Manual.

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.

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`	E-mail 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`	E-mail 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. FastCGI plug-in allows 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 FastCGI Plug-in chapter in the Sun Java System Web Server 7.0 Administrator’s Guide.

Previous: 2. Server-parsed HTML Tags

Contained Within

Find More Documentation

Featured Support Resources

Chapter 3 Using Common Gateway Interface

Configuring CGI Settings

Enabling CGI

Specifying CGI Directories

Changes to the obj.conf File

Specifying CGI File Extensions

See Also

Creating Custom Execution Environments for CGI Programs

To Install suid and Cgistub Directories

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

Before You Begin

Specifying a Chroot Directory for a Virtual Server

Before You Begin

Adding CGI Programs to the Server

Setting the Priority of a CGI Program

To Configure CGI Properties for a Virtual Server

Shell CGI Programs

Perl CGI Programs

To Configure Perl Programs to Execute as CGI Programs

Global CGI Settings

To Change Global CGI Settings

CGI Variables

FastCGI

Changes to the `obj.conf` File

To Install `suid` and `Cgistub` Directories

To Create a `cgi-bin` Directory and Define User and Group

Specifying a `Chroot` Directory for a Virtual Server