Release Notes for Sun Java System Web Server 6.1 Add-Ons |
Release Notes for Sun Java System Web Server 6.1 Add-Ons
FastCGI Plugin 1.0Version 6.1
Part Number 819-1809
March 2005
These release notes contain important information available at the time of release of Sun Java System Web Server 6.1 FastCGI Plugin, including information about server application functions (SAFs), installation, configuration, technical notes, and pointers to additional resources. Review the release notes prior to installing and configuring your software, and then periodically thereafter for the most up-to-date information.
Complete Sun Java System Web Server 6.1 documentation can be found at the following location:
http://docs.sun.com/db/prod/s1websrv#hicThese release notes contain the following sections:
IntroductionFastCGI (http://www.fastcgi.com) is an open extension to CGI (Common Gateway Interface), which is a standard for interfacing external applications with web servers. Like CGI, FastCGI applications run in separate, isolated processes. Some of the FastCGI's advantages are as follows:
- Performance - FastCGI processes are persistent; they are reused to handle multiple requests. This solves the CGI performance problem of creating new processes for each request.
- Support for distributed computing - FastCGI provides the ability to run applications remotely, which is useful for distributing load.
- Process Isolation - A FastCGI application cannot crash or corrupt the core server or other applications.
The FastCGI Plugin allows the Sun Java System Web Server to safely work with popular third party dynamic content generation technologies (PHP, Perl, Python, etc.) in a scalable way.
The FastCGI Plugin implements the client side of the FastCGI protocol. This protocol allows producers of dynamic content (and content engines) to implement a common, scalable API that can be utilized by many web servers.
Server Application Functions (SAFs)The FastCGI Plugin provides the following Server Application Functions (SAFs):
The various parameters and "error-reason" strings for the FastCGI SAFs are described in the following sections:
auth-fastcgi
The
auth-fastcgi
Service Application Function (SAF) is used in a PathCheck directive. This SAF is used to specify a the FastCGI server application to be used for authorization.The
auth-fastcgi
PathCheck SAF sends the request to the specified "Authorizer" FastCGI application. If the application has returned a status code of "200", the authorization has succeeded and the Web Server proceeds with request execution. Otherwise, the response that was sent by the FastCGI application is sent back to the User-Agent.The
auth-fastcgi
SAF is optional and should only be used to forward the requests to an authorizer FastCGI application.The parameters accepted by
auth-fastcgi
SAF, are available at: FastCGI SAF Paramters.The following
obj.conf
code example demonstrates the use ofauth-fastcgi
:
PathCheck fn="auth-fastcgi" app-path="/foo/bin/php" bind-path="fooUDS"
On the first request to the
auth-fastcgi
, FastCGI plugin creates the FastCGI authorizer application processes and sends the request for evaluation.
responder-fastcgi
The
responder-fastcgi
Server Application Function (SAF) forwards a request to a FastCGI application that acts as a "Responder", for further processing.responder-fastcgi
sends the request data to the listener onto which theapp-path
application processes are listening. Once the application responds to the request,service-fastcgi
will process the response headers before sending them back to the User-Agent.The list of parameters accepted by
responder-fastcgi
SAF, are available at: FastCGI SAF Paramters.The following
obj.conf
code example demonstrates the use ofresponder-fastcgi
:
Service fn="responder-fastcgi" app-path="/foo/bin/perl" bind-path="fooPerl"
The
filter-fastcgi
filter-fastcgi
Server Application Function (SAF) forwards a request to a FastCGI application that acts as a "Filter", for further processing. A filter application receives the information associated with an HTTP request, plus additional data from a file stored on the server, and generates a "filtered" version of the data stream as the response.
filter-fastcgi
sends the request data in FastCGI record format to the application specified byapp-path
. Once the application responds to the request,filter-fastcgi
will process the response headers before sending them to the User-Agent.The list of parameters accepted by
filter-fastcgi
SAF, are available at: FastCGI SAF Paramters.The following
obj.conf
code example demonstrates the use offilter-fastcgi
:
Service type="magnus-internal/perl" fn="filter-fastcgi" app-path="/foo/bin/perl" bind-path="fooPerl"
The
error-fastcgi
error-fastcgi
Server Application Function (SAF) is called when the FastCGI plugin encounters an error. This is used to display a specified page or URL.The list of parameters accepted by
error-fastcgi
SAF, are available at: FastCGI SAF Paramters.The following
obj.conf
snippet demonstrates the use oferror-fastcgi
:
Error fn="error-fastcgi" error-reason="Fastcgi Connection Error" error-url="http://www.foo.com/errorPage1.html"
FastCGI SAF Parameters
FastCGI Plugin SAFs--"auth-fastcgi
" and "responder-fastcgi
"--both accept the following parameters unless otherwise mentioned explicitly:Note that parameters
chroot
,user
,group
andnice
are applicable to only Unix platforms. On Windows platforms, these parameters are ignored.
app-path
- (Optional) FastCGI server application path which would process the request. The functionality is dependent on the value of the "bind-path
" as follows:
- If only "
app-path
" is specified, the plugin will create FastCGI server applications, which will listen to Unix Domain Sockets created by the Plugin.- If both "
app-path
" and "bind-path
" are specified, the plugin will create FastCGI server applications, which will listen to the TCP/IP address and port value specified in "bind-path
" or Unix Domain Sockets created by the FastCGI Plugin.- If only "
bind-path
" is specified, the Plugin will directly communicate with the FastCGI server application.- If "
app-path
" and "bind-path
" both are not specified, then the Plugin will log an error message.
bind-path
- (Optional) Can be a Unix Domain Socket (UDS) name or of the form "host:port
". The description of "app-path
" parameter explains the usage of "bind-path
" parameter. Note that the UDS name is applicable only on Unix platforms; on Windows platforms,bind-path
must be specified as "host:port
".min-procs
- (Optional) Integer specifying the minimum number of FastCGI application processes to be created. Defaults to 1.max-procs
- (Optional) Integer specifying the maximum number of FastCGI application processes that could be created at any time. It should be equal to or greater thanmin-procs
. Defaults to 1.chroot
- (Optional) Used to set the root directory of thechroot
jail that the FastCGI server application runs in. Defaults to the server's root directory.user
- (Optional) Specifies the user ID the FastCGI server application runs as. Defaults to server's user ID.group
- (Optional) The FastCGI server application would be running under the specified group. Defaults to server's group.nice
- (Optional) Specifies thenice
/priority
value of FastCGI server application processes.listen-queue
- (Optional) Integer specifying the listen queue size for the socket. Defaults to 20.app-env
- (Optional) Value pairs which will be passed as environment variables to the FastCGI server application process. Multiple "app-env
" parameters are allowed. The format for multipleapp-env
parameters is:app-env="name=value" app-env="name=value"....
reuse-connection
- (Optional) Boolean value that determines if connections to FastCGI server applications are reused.False
(0
,false
,no
) indicates that the connections to FastCGI server applications are closed after each request.True
(1
,true
,yes
) indicates that existing connections are reused for new requests. See alsoconnection-timeout
.connection-timeout
- (Optional) If "reuse-connection
" is1 True
, then this value specifies the timeout value in seconds for the pooled connections. If a connection is idle for the specified amount period of time, then the Plugin will close the connection. See alsoreuse-connection
.resp-timeout
- (Optional) Integer representing the FastCGI server response timeout in seconds. If there is no response from the FastCGI server application within the specified period of time, the request will be discarded.restart-interval
- (Optional) Integer representing the time interval (in minutes) after which the FastCGI server application will be restarted. Defaults to 60 minutes (1 hour).req-retry
- (Optional) Integer representing the number of times the Plugin should resend the request when the FastCGI server application rejects the request.The
error-fastcgi
Server Application Function (SAF) accepts the following parameters:
error-url
- Specifies the page, URI or URL to be displayed in case of if a failure or error occurs. The value of this parameter can be an absolute path, a path relative to docroot, or an URL or URI.error-reason
- (Optional) String representing the FastCGI protocol error. This is used to differentiate error URLs to be displayed, in case of any plugin errors.FastCGI SAF Error Reason Strings
Here is the list of valid "error-reason" strings:
- "Missing Parameters" : Whenever app-path and bind-path are not specified.
- "Stub Start Error" : Unable to start the stub for various reasons like fork failure, bind error, listen error.
- "Stub Connection Failure" : client socket creation or connect failure.
- "No Permission" : stub executable has no exec permission, stat failure, and so on.
- "Stub Request Handling Error" : unable to send the request to stub, received invalid/no response from the stub for a request, and so on.
- "Set Parameter Failure" : when set user, group, chroot, nice (and so on) fail.
- "Invalid user and/or group" : when user /group is invalid.
- "Invalid Parameters" : when invalid nice value is specified.
- "Server Process Creation Failure" : application fork failure, application exec failure, bind error, listen error, and so on.
- "Fastcgi Protocol Error" : invlid record version, invalid record type, unkown role, and so on.
- "Internal Error" : unable to open the file to be sent to the filter application, any other unknown errors.
Installing the FastCGI PluginThe FastCGI Plugin is available for use with the Sun Java System Web Server 6.1 SP4 or later Service Packs.
This section includes the following topics:
- Package Contents
- Installing on Solaris, Linux, HP-UX and AIX using tar Packaging
- Installing on Windows
- Installing on Solaris Using SVr4 Packaging
- Installing on Linux using RPM Packaging
Package Contents
The contents of the platform specific packages are:Solaris, Linux, AIX:
- plugins/fastcgi/README
- plugins/fastcgi/libfastcgi.so
- plugins/fastcgi/Fastcgistub
HP-UX:
- plugins/fastcgi/README
- plugins/fastcgi/libfastcgi.sl
- plugins/fastcgi/Fastcgistub
Windows:
- plugins\fastcgi\README
- plugins\fastcgi\fastcgi.dll
- plugins\fastcgi\Fastcgistub.exe
The FastCGI plugin is packaged as a tarball, a zip file, an SVR4 package, and an rpm package.
Installing on Solaris, Linux, HP-UX and AIX Using tar Packaging
$ gzip -d sun-webserver61-fastcgi-{sol|lin|hpux|aix}.tar.gz
;; Uncompress the tar archive,
;; where {sol|lin|hpux|aix} reflects
;; the operating system
;; environment the library will
;; be used
$ tar xvf sun-webserver61-fastcgi-{sol|lin|hpux|aix}.tar
Please refer to "Configuring the FastCGI Plugin."
;; Extract the tar archive
Installing on Windows
$ unzip sun-webserver61-fastcgi-win.zip
;; Uncompress the ZIP archive
Please refer to "Configuring the FastCGI Plugin."
Installing on Solaris Using SVr4 Packaging
$ su
;; root access is required to install
;; SVr4 packages
$ cd <path/to/package>
;; Change directory to where the package
;; is located
# pkgadd -d .
;; Install SUNWwbsvr-fastcgi.pkg package
NOTE: This will place the shared object and README in:
/opt/SUNWwbsvr/plugins/fastcgi
Please refer to "Configuring the FastCGI Plugin."
Installing on Linux using RPM Packaging
$ su
;; root access is required to
;; install RPM packages
$ cd <path/to/package>
;; Change directory to where
;; the package is located
# rpm -iUvh sun-webserver-fastcgi.rpm
;; Install
;; sun-webserver-fastcgi.rpm
;; packageNOTE: This will place the shared object and README in
/opt/sun/webserver/plugins/fastcgi
Please refer to "Configuring the FastCGI Plugin."
Configuring the FastCGI PluginThe FastCGI plugin is configured via the existing magnus.conf and obj.conf Web Server configuration files as documented in the following subsections.
magnus.conf
The existing load-modules SAF is used to load the FastCGI plugin shared object. The shared object filename varies by platform as follows:
- libfastcgi.so (Solaris, Linux, AIX)
- libfastcgi.sl (HP-UX)
- fastcgi.dll (Windows)
The following magnus.conf code example demonstrates the use of load-modules to load the FastCGI plugin:
Init fn="load-modules" shlib="/opt/SUNWwbsvr/plugins/fastcgi/libfastcgi.so"
obj.conf
The FastCGI plugin introduces the following SAFs that can be referenced in obj.conf:
- auth-fastcgi
- responder-fastcgi
- filter-fastcgi
- error-fastcgi
For example, the following obj.conf code example configures the server to forward requests in the /fcgi/php and /fcgi/perl URI space to fcgi.php and fcgi.perl respectively, which in turn is configured to pass the requests to FastCGI module for further processing.
<Object name="default">
NameTrans fn="assign-name"
from="/fcgi/php(|/*)"
name="fcgi.php"
NameTrans fn="assign-name"
from="/fcgi/perl(|/*)"
name="fcgi.perl"
...
Service type="magnus-internal/perl" fn="filter-fastcgi"\
<other parameters required for running Filter FastCGI processes>
....
</Object>
<Object name="fcgi.php">
PathCheck fn="auth-fastcgi" <other parameters required for running Authorizer FastCGI processes>
Service fn="responder-fastcgi" <other parameters required for running Responder FastCGI processes>
</Object>
<Object name="fcgi.perl">
PathCheck fn="auth-fastcgi" <other parameters required for running Authorizer FastCGI processes>
Service type="magnus-internal/perl" fn="responder-fastcgi" <other parameters required for running Responder FastCGI processes>
Error fn="error-fastcgi" error-reason="Fastcgi Connection Error" error-url="http://www.foo.com/errorPage1.html"
</Object>
.
.
.
Note that FastCGI SAFs can be invoked in different ways as mentioned above; that is, defining different Objects for different URL patterns or mapping them to different MIME types.
Known ProblemsThis section includes the known problems with the Sun Java System Web Server 6.1 FastCGI Plugin.
How to Report Problems and Provide FeedbackIf you have problems with Sun Java System Web Server 6.1 FastCGI Plugin, contact Sun customer support using one of the following mechanisms:
- Sun Software Support services online at
http://www.sun.com/service/sunone/software- The telephone dispatch number associated with your maintenance contract
So that we can best assist you in resolving problems, please have the following information available when you contact support:
- Description of the problem, including the situation where the problem occurs and its impact on your operation
- Machine type, operating system version, and product version, including any patches and other software that might be affecting the problem
- Detailed steps on the methods you have used to reproduce the problem
- Any error logs or core dumps
Sun Welcomes Your Comments
Sun is interested in improving its documentation and welcomes your comments and suggestions. Send your comments to Sun using the "Send comments" link at: http://docs.sun.com/
Please include identifying information with your comments, such as the book’s part number and title.
Additional Sun ResourcesUseful Sun ONE information can be found at the following locations:
- Documentation for Sun Java System Web Server 6.1 and Service Packs
http://docs.sun.com/db/coll/S1_websvr61_en- Sun ONE Software Products and Service
http://www.sun.com/software- Sun ONE Developer Information
http://sunonedev.sun.com- Sun Developer Support Services
http://www.sun.com/developers/support- Sun ONE Software Support Services
http://www.sun.com/service/sunone/software- Sun Support and Training Services
http://www.sun.com/supportraining- Sun ONE Consulting and Professional Services
http://www.sun.com/service/sunps/sunone
Copyright � 2005 Sun Microsystems, Inc. All rights reserved. Sun Microsystems, Inc. has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without limitation, these intellectual property rights may include one or more of the U.S. patents listed at http://www.sun.com/patents and one or more additional patents or pending patent applications in the U.S. and in other countries. SUN PROPRIETARY/CONFIDENTIAL. U.S. Government Rights - Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supplements. Use is subject to license terms. This distribution may include materials developed by third parties. Portions may be derived from Berkeley BSD systems, licensed from U. of CA. Sun, Sun Microsystems, the Sun logo, Java and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the U.S. and other countries.
Copyright � 2005 Sun Microsystems, Inc. Tous droits r�serv�s. Sun Microsystems, Inc. d�tient les droits de propri�t� intellectuels relatifs � la technologie incorpor�e dans le produit qui est d�crit dans ce document. En particulier, et ce sans limitation, ces droits de propri�t� intellectuelle peuvent inclure un ou plusieurs des brevets am�ricains list�s � l'adresse http://www.sun.com/patents et et un ou des brevets des applications de brevet en attente aux Etats - Unis et dans les autres pays. Propri�t� de SUN/CONFIDENTIEL. L'utilisation est soumise aux termes du contrat de licence. Cette distribution peut comprendre des composants d�velopp�s par des tierces parties. Des parties de ce produit pourront �tre d�riv�es des syst�mes Berkeley BSD licenci�s par l'Universit� de Californie. Sun, Sun Microsystems, le logo Sun, Java et Solaris sont des marques de fabrique ou des marques d�pos�es de Sun Microsystems, Inc. aux Etats-Unis et dans d'autres pays. Toutes les marques SPARC sont utilis�es sous licence et sont des marques de fabrique ou des marques d�pos�es de SPARC International, Inc. aux Etats-Unis et dans d'autres pays.