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:
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>
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.
In the Admin Console, Select Common Tasks tab.
Select CGI Directories from the Virtual Server Tasks list.
The CGI Settings page is displayed.
Select the CGI as file type Enabled option.
You can specify a directory that contains only CGI programs. All files are run as programs regardless of the file extensions.
In the Admin Console, Select the Common Tasks tab.
Select CGI Directories from the Virtual Server Tasks list.
The CGI Directory window is displayed.
Click New.
The Add CGI Directory window is displayed.
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/
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
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 5 Administrator’s Guide.
Creating custom execution environment includes the following steps:
Installing suid and Cgistub
Creating a cgi-bin directory
Specifying a chroot directory for the virtual server
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.
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.
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.
Log in as a superuser.
Create the private directory for Cgistub in the install-dir/https-instance/private directory:
cd install-dir/https-instance
mkdir private
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 5 Administrator’s Configuration File Reference.
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
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 5 Administrator’s Configuration File Reference.
Restart the server to apply the changes.
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.
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.
Log in as a superuser.
Change to the document root directory for the virtual server.
cd document-root
Create the cgi-bin directory and set appropriate permissions.
mkdir cgi-bin chown user:group cgi-bin 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 Update 5 Administrator’s Configuration File Reference.
In the Admin Console,
Select Common Tasks tab. .
Select CGI Directories from the Virtual Server Tasks list
The CGI Settings window is displayed.
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 5 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
To further improve security, the CGI scripts must be prevented from accessing data above and outside of the document-root directory.
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:
Log in as a superuser.
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.
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.
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
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
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 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 |
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 Update 5 Administrator’s Configuration File Reference.
Use the Admin Console.
Select the Common Tasks tab.
Select CGI Directories from the Virtual Server Tasks list.
The CGI Settings window is displayed.
Enter the Chroot directory.
For detailed instructions, see the Sun Java System Web Server 7.0 Update 5 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 Update 5 Administrator’s Configuration File Reference.
To add CGI programs to the server, do one of the following:
Store the program file in a CGI directory (if any exist).
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 directory if CGI file type recognition has been activated.
On UNIX platforms, 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 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.
The CGI program runs at the same priority as the server
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.
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 5 Administrator’s Configuration File Reference.
You can configure CGI variables for a virtual server either using the Admin Console or using the CLI. The following procedure describes the steps:
In the Admin Console, select the Common Tasks tab.
Select CGI Directories from the Virtual Server Tasks list.
The CGI Settings window is displayed.
Specify the nice value as desired.
Click Save to apply your changes.
./wadm set-cgi-prop --user=admin --password-file=admin.pwd --host=serverhost --port=8989 --config=config1 nice=5
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 5 Administrator’s Guide.
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:
In a command-line window, type the following commands:.
C:\>assoc .pl=perl C:\>ftype perl="c:\WS7\lib\perl\perl.exe" "%1" |
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.
Create a simple Perl program called hello.pl.
#!<server_root>/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 cgi-bin and is located 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.
In the Admin Console, select the Common Tasks tab.
Select 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.
Type 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
The CGI directory that you specify must have execute permissions.
Click Save to save the changes.
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.
You can change the CGI settings globally for all available virtual servers. You can either use the Administration Console or the CLI.
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 5 CLI Reference Manual.
Select a configuration from the list.
Select Performance tab > CGI subtab.
The CGI Settings window is displayed.
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 5 Administrator’s Configuration File Reference.
Click Save to apply your changes.
./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 5 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 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) |
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 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 5 Administrator’s Guide.