| Sun ONE Web Server 6.1 Programmer's Guide |
Chapter 3
Using CGICommon 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 invoked through URL invocation.
A wealth of information about writing CGI programs is available. A good starting point is “The Common Gateway Interface” at:
http://hoohoo.ncsa.uiuc.edu/cgi/overview.html
Sun ONE Web Server complies with the version 1.1 CGI specification.
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 CGISun ONE Web Server provides two ways to identify CGI programs, which are listed below and described in this section:
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 never 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 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 (UNIX only)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, give a VS (virtual server) element the following VARS subelement:
<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 ONE Web Server 6.1 Administrator’s Configuration File Reference.
- Restart the server to put the changes into effect.
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.
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
To prevent a virtual server’s CGI programs from interfering with other users, these programs should be stored in a unique directory and execute 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.
Next, follow these steps to create a cgi-bin directory for the virtual server:
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 ONE Web Server 6.1 Administrator’s Configuration File Reference).
- Enter this information using the Settings page in the Preferences tab of the Virtual Server Manager (see the Sun ONE Web Server 6.1 Administrator’s Guide).
Specifying a Chroot Directory for a Virtual Server
To further improve security, these CGI scripts should be prevented from accessing data above and outside of 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 often a 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:
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 usrNow you can set the virtual server’s chroot directory in one of these ways:
- Use the chroot parameter of the send-cgi Service SAF in the obj.conf file (see the Sun ONE Web Server 6.1 Administrator’s Configuration File Reference).
- Enter this information using the Settings page in the Preferences tab of the Virtual Server Manager (see the Sun ONE Web Server 6.1 Administrator’s Guide).
Adding CGI Programs to the ServerTo add CGI programs to Sun ONE Web Server, just do one of the following:
For UNIX, make sure the program file has execute permissions set.
Setting the Priority of a CGI ProgramThe 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 server. Typically, 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 ONE Web Server 6.1 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. This can be overridden by setting the value for an individual virtual server, as described below.
To configure CGI variables for a virtual server:
The value overrides any value set at the class level.
Windows CGI and Shell CGI ProgramsFor information about installing CGI and shell CGI programs on Windows using the Class Manager interface, see the Sun ONE Web Server 6.1 Administrator’s Guide.
Perl CGI ProgramsYou cannot run CGIs using Perl 5.6.x with the -w flag. Instead, include the following code in the file:
use warnings;
Global CGI SettingsTo change global CGI settings:
- 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, 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 the magnus.conf file in the Sun ONE Web Server 6.1 Administrator's Configuration File Reference.
CGI VariablesIn addition to the standard CGI variables, you can use the Sun ONE 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 ONE Web Server CGI variables. The left column lists the variable, and the right column provides a description.
