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:
Sun Java System Web Server provides two ways to identify CGI programs, which are listed below and described in this section:
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.
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"
Before you can create a custom execution environment, you must install the suid Cgistub and run it as root:
Log in as the superuser.
su
Create the private directory for Cgistub:
cd server_root/https-instance
mkdir private
Copy Cgistub to the private directory:
cd private
cp ../../bin/https/bin/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 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 SP9 Administrator’s Configuration File Reference.
Restart the server to update the changes into effect.
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 SP9 NSAPI Programmer’s Guide.
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.
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:
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.
Log in as the superuser.
su
Change to the virtual server directory.
cd vs_dir
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 SP9 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 SP9 Administrator’s Guide.
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
Log in as the superuser.
su
Change to the chroot directory. This is typically the vs_dir directory mentioned in the previous section.
cd chroot
Create tmp in the chroot directory:
mkdir tmp
chmod 1777 tmp
Create dev in the chroot directory:
mkdir dev
chmod 755 dev
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
Create the tcp device using the major and minor numbers:
mknod dev/tcp c 11 42
chmod 666 dev/tcp
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
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:
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
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
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:
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 SP9 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 SP9 Administrator’s Guide.
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.
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 SP9 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.
Access the Class Manager, and then click Manage Virtual Servers on the Virtual Servers tab.
Select a virtual server, click Manage, and then click Settings.
Specify the nice value as desired, and then click OK to apply your changes.
The value overrides any value set at the class level.
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 SP9 Administrator’s Guide.
You cannot run CGIs using Perl 5.6.x with the -w flag. Instead, include the following code in the file:
use warnings;
Access the Server Manager, and click the Magnus Editor page.
Select CGI Settings from the drop-down list, and then click Manage.
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.
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 SP9 Administrator’s Configuration File Reference.
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.
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) |
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 client certificate |
CLIENT_CERT_VALIDITY_EXIRES |
Expiration date of the client certificate |
CLIENT_CERT_EXTENSION_xxx |
Certificate extension, where xxx is the name of the extension |
REVOCATION_METHOD |
Name of the certificate revocation method if exists |
REVOCATION_STATUS |
Status of certificate revocation if it exists |