|
| Sun ONE Application Server 7 Developer's Guide to NSAPI |
Predefined SAFs and the Request Handling ProcessThis module describes the standard directives and pre-defined Server Application Functions (SAFs) that are used in the obj.conf file to give instructions to the server.
Each SAF has its own arguments, which are passed to it by a directive in obj.conf. Every SAF is also passed additional arguments that contain information about the request (such as what resource was requested and what kind of client requested it) and any other server variables created or modified by SAFs called by previously invoked directives. Each SAF may examine, modify, or create server variables. Each SAF returns a result code that tells the server whether it succeeded, did nothing, or failed.
For a discussion of the use and syntax of obj.conf, see the module, "Syntax and Use of obj.conf."
For a list of Init (initialization) SAFs, see "SAFs in the init.conf File."
This module includes functions that are part of the core functionality of Sun ONE Application Server. It does not include functions that are available only if additional components, such as server-parsed HTML, are enabled.
This module contains a section for each directive which lists all the pre-defined Server Application Functions that can be used with that directive.
The directives are:
- AuthTrans Stage
- NameTrans Stage
- PathCheck Stage
- ObjectType Stage
- Service Stage
- AddLog Stage
- Error Stage
For an alphabetical list of pre-defined SAFs, see "Alphabetical List of Pre-defined SAFs."
The following table lists the SAFs that can be used with each directive. The left column lists the directives, and the right column lists the SAFs for each directive.
The bucket Parameter
The following performance buckets are predefined in Sun ONE Application Server:
- The default-bucket records statistics for the functions not associated with any user-defined or built-in bucket.
- The all-requests bucket records.perf statistics for all SAFs, including those in the default-bucket.
You can define additional performance buckets in the init.conf file (see the perf-init and define-perf-bucket functions).
You can measure the performance of any SAF in obj.conf by adding a bucket=bucket-name parameter to the function, for example bucket=cache-bucket.
To list the performance statistics, use the service-dump Service function.
As an alternative, you can use the stats-init function to generate performance statistics.
For more information about performance buckets, see the Sun ONE Application Server Performance Tuning, Sizing, and Scaling Guide.
AuthTrans Stage
AuthTrans stands for Authorization Translation. AuthTrans directives give the server instructions for checking authorization before allowing a client to access resources. AuthTrans directives work in conjunction with PathCheck directives. Generally, an AuthTrans function checks if the username and password associated with the request are acceptable, but it does not allow or deny access to the request -- it leaves that to a PathCheck function.
The server handles the authorization of client users in two steps.
- AuthTrans Stage - validates authorization information sent by the client in the Authorization header.
- PathCheck Stage - checks that the authorized user is allowed access to the requested resource.
The authorization process is split into two steps so that multiple authorization schemes can be easily incorporated, as well as providing the flexibility to have resources that record authorization information but do not require it.
AuthTrans functions get the username and password from the headers associated with the request. When a client initially makes a request, the username and password are unknown so the AuthTrans functions and PathCheck functions work together to reject the request, since they can't validate the username and password. When the client receives the rejection, its usual response is to pop up a dialog box asking for the username and password to enter the appropriate realm, and then the client submits the request again, this time including the username and password in the headers.
If there is more than one AuthTrans directive in obj.conf, each function is executed in order until one succeeds in authorizing the user.
The following AuthTrans-class functions are described in detail in this section:
- auth-passthrough inspects an incoming HTTP (web) request for client information encoded by a service-passthrough function running on an intermediate server.
- basic-auth calls a custom function to verify user name and password. Optionally determines the user's group.
- basic-ncsa verifies user name and password against an NCSA-style or system DBM database. Optionally determines the user's group.
- get-sslid retrieves a string that is unique to the current SSL session and stores it as the ssl-id variable in the Session->client parameter block.
- qos-handler handles the current quality of service statistics.
auth-passthrough
Applicable in AuthTrans-class directives.
The auth-passthrough function inspects an incoming HTTP (web) request for client information encoded by a service-passthrough function running on an intermediate server. The client information includes:
- The IP address from which the request originated.
- The SSL key size used by the originating client.
- The SSL client certificate presented by the originating client.
When auth-passthrough detects encoded client information, it treats the request as if it had arrived directly from the originating client instead of via an intermediate server running service-passthrough.
The auth-passthrough function is optional on the server instance that receives the request forwarded by service-passthrough.
Since auth-passthrough makes it possible to override information that may be used for authentication (for example, the IP address of the original request), it is important that only trusted clients and servers be allowed to connect to a server running auth-passthrough. As a minimal precaution, only servers behind a corporate firewall should run auth-passthrough; no Internet-accessible server should run auth-passthrough. Further, if this information about the originating client is not required, auth-passthrough should not be used.
Parameters
The following table describes parameters for the auth-passthrough function. The left column lists the parameter name, and the right column describes what the parameter does.
auth-passthrough parameters
Parameter
Description
optional, common to all obj.conf functions
Examples
AuthTrans fn=auth-passthrough
See Also
init-passthrough, check-passthrough, service-passthrough
basic-auth
Applicable in AuthTrans-class directives.
The basic-auth function calls a custom function to verify authorization information sent by the client. The Authorization header is sent as part of the basic server authorization scheme.
This function is usually used in conjunction with the PathCheck-class function require-auth.
Parameters
The following table describes parameters for the basic-auth function. The left column lists the parameter name, and the right column describes what the parameter does.
basic-auth parameters
Parameter
Description
auth-type
specifies the type of authorization to be used. This should always be basic.
userdb
(optional) specifies the full path and file name of the user database to be used for user verification. This parameter will be passed to the user function.
userfn
is the name of the user custom function to verify authorization. This function must have been previously loaded with load-modules. It has the same interface as all the SAFs, but it is called with the user name (user), password (pw), user database (userdb), and group database (groupdb) if supplied, in the pb parameter. The user function should check the name and password using the database and return REQ_NOACTION if they are not valid. It should return REQ_PROCEED if the name and password are valid. The basic-auth function will then add auth-type, auth-user (user), auth-db (userdb), and auth-password (pw, Windows only) to the rq->vars pblock.
groupdb
(optional) specifies the full path and file name of the user database. This parameter will be passed to the group function.
groupfn
(optional) is the name of the group custom function that must have been previously loaded with load-modules. It has the same interface as all the SAFs, but it is called with the user name (user), password (pw), user database (userdb), and group database (groupdb) in the pb parameter. It also has access to the auth-type, auth-user (user), auth-db (userdb), and auth-password (pw, Windows only) parameters in the rq->vars pblock. The group function should determine the user's group using the group database, add it to rq->vars as auth-group, and return REQ_PROCEED if found. It should return REQ_NOACTION if the user's group is not found.
optional, common to all obj.conf functions
Examples
in init.conf:
Init fn=load-modules shlib=/path/to/mycustomauth.so funcs=hardcoded_auth
in obj.conf:
AuthTrans fn=basic-auth auth-type=basic userfn=hardcoded_auth
PathCheck fn=require-auth auth-type=basic realm="Marketing Plans"
See Also
basic-ncsa
Applicable in AuthTrans-class directives.
The basic-ncsa function verifies authorization information sent by the client against a database. The Authorization header is sent as part of the basic server authorization scheme.
This function is usually used in conjunction with the PathCheck-class function require-auth.
Parameters
The following table describes parameters for the basic-ncsa function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
See Also
get-sslid
Applicable in AuthTrans-class directives.
Note This function is provided for backward compatibility only. The functionality of get-sslid has been incorporated into the standard processing of an SSL connection.
The get-sslid function retrieves a string that is unique to the current SSL session, and stores it as the ssl-id variable in the Session->client parameter block.
If the variable ssl-id is present when a CGI is invoked, it is passed to the CGI as the HTTPS_SESSIONID environment variable.
The get-sslid function has no parameters and always returns REQ_NOACTION. It has no effect if SSL is not enabled.
Parameters
The following table describes parameters for the get-sslid function. The left column lists the parameter name, and the right column describes what the parameter does.
get-sslid parameters
Parameter
Description
optional, common to all obj.conf functions
qos-handler
Applicable in AuthTrans-class directives.
The qos-handler function examines the current quality of service statistics for the virtual server, virtual server class, and global server, logs the statistics, and enforces the QOS parameters by returning an error. This must be the first AuthTrans function configured in the default object in order to work properly.
For more information, see the Sun ONE Application Server Performance Tuning, Sizing, and Scaling Guide.
Parameters
The following table describes parameters for the qos-handler function. The left column lists the parameter name, and the right column describes what the parameter does.
qos-handler parameters
Parameter
Description
optional, common to all obj.conf functions
Example
AuthTrans fn=qos-handler
See Also
NameTrans Stage
NameTrans stands for Name Translation. NameTrans directives translate virtual URLs to physical directories on your server. For example, the URL
http://www.test.com/some/file.html
could be translated to the full file-system path
/usr/Sun/AppServer7/domains/domain1/server1/docs/some/file.html
NameTrans directives should appear in the default object. If there is more than one NameTrans directive in an object, the server executes each one in order until one succeeds.
The following NameTrans-class functions are described in detail in this section:
- assign-name tells the server to process directives in a named object.
- document-root translates a URL into a file system path by replacing the http://host_name/ part of the requested resource with the document root directory.
- home-page translates a request for the server's root home page (/) to a specific file.
- ntrans-j2ee determines whether a request maps to a Java web application context.
- pfx2dir translates any URL beginning with a given prefix to a file system directory and optionally enables directives in an additional named object.
- redirect redirects the client to a different URL.
- strip-params removes embedded semicolon-delimited parameters from the path.
- unix-home translates a URL to a specified directory within a user's home directory.
assign-name
Applicable in NameTrans-class directives.
The assign-name function specifies the name of an object in obj.conf that matches the current request. The server then processes the directives in the named object in preference to the ones in the default object.
For example, consider the following directive in the default object:
NameTrans fn=assign-name name=personnel from=/personnel
Let's suppose the server receives a request for http://hostname/personnel. After processing this NameTrans directive, the server looks for an object named personnel in obj.conf, and continues by processing the directives in the personnel object.
The assign-name function always returns REQ_NOACTION.
Parameters
The following table describes parameters for the assign-name function. The left column lists the parameter name, and the right column describes what the parameter does.
Example
document-root
Applicable in NameTrans-class directives.
The document-root function specifies the root document directory for the server. If the physical path has not been set by a previous NameTrans function, the http://hostname/ part of the path is replace by the physical pathname for the document root.
When the server receives a request for http://hostname/somepath/somefile, the document-root function replaces http://hostname/ with the value of its root parameter. For example, if the document root directory is /usr/Sun/AppServer7/domains/domain1/server1/docs, then when the server receives a request for http://hostname/a/b/file.html, the document-root function translates the pathname for the requested resource to:
/usr/Sun/AppServer7/domains/domain1/server1/docs/a/b/file.html
This function always returns REQ_PROCEED. NameTrans directives listed after this will never be called, so be sure that the directive that invokes document-root is the last NameTrans directive.
There can be only one root document directory. To specify additional document directories, use the pfx2dir function to set up additional path name translations.
Parameters
The following table describes parameters for the document-root function. The left column lists the parameter name, and the right column describes what the parameter does.
document-root parameters
Parameter
Description
root
is the file system path to the server's root document directory.
optional, common to all obj.conf functions
Examples
NameTrans fn=document-root root=/usr/Sun/AppServer7/domains/domain1/server1/docs
NameTrans fn=document-root root=$docroot
See also
home-page
Applicable in NameTrans-class directives.
The home-page function specifies the home page for your server. Whenever a client requests the server's home page (/), they'll get the document specified.
Parameters
The following table describes parameters for the home-page function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
NameTrans fn="home-page" path="homepage.html"
NameTrans fn="home-page" path="/httpd/docs/home.html"
ntrans-j2ee
Applicable in NameTrans-class directives.
The ntrans-j2ee function determines whether a request maps to a Java web application context.
Parameters
The following table describes parameters for the ntrans-j2ee function. The left column lists the parameter name, and the right column describes what the parameter does.
ntrans-j2ee parameters
Parameter
Description
name
is a named object in obj.conf whose directives are applied to requests made to Java web applications.
optional, common to all obj.conf functions
Examples
NameTrans fn="ntrans-j2ee" name="j2ee"
See Also
init-j2ee, service-j2ee, error-j2ee
pfx2dir
Applicable in NameTrans-class directives.
The pfx2dir function replaces a directory prefix in the requested URL with a real directory name. It also optionally allows you to specify the name of an object that matches the current request. (See the discussion of assign-name for details of using named objects.)
Parameters
The following table describes parameters for the pfx2dir function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
In the first example, the URL http://hostname/cgi-bin/resource (such as http://x.y.z/cgi-bin/test.cgi) is translated to the physical pathname /httpd/cgi-local/resource, (such as /httpd/cgi-local/test.cgi) and the server also starts processing the directives in the object named cgi.
NameTrans fn=pfx2dir from=/cgi-bin dir=/httpd/cgi-local name=cgi
In the second example, the URL http://hostname/icons/resource (such as http://x.y.z/icons/happy/smiley.gif) is translated to the physical pathname /users/nikki/images/resource, (such as /users/nikki/images/smiley.gif)
NameTrans fn=pfx2dir from=/icons/happy dir=/users/nikki/images
The third example shows the use of the find-pathinfo-forward parameter. The URL http://hostname/cgi-bin/resource is translated to the physical pathname /export/home/cgi-bin/resource.
NameTrans fn="pfx2dir" find-pathinfo-forward="" from="/cgi-bin" dir="/export/home/cgi-bin" name="cgi"
redirect
Applicable in NameTrans-class directives.
The redirect function lets you change URLs and send the updated URL to the client. When a client accesses your server with an old path, the server treats the request as a request for the new URL.
Parameters
The following table describes parameters for the redirect function. The left column lists the parameter name, and the right column describes what the parameter does.
redirect parameters
Parameter
Description
from
specifies the prefix of the requested URI to match.
url
(maybe optional) specifies a complete URL to return to the client. If you use this parameter, don't use url-prefix (and vice-versa).
url-prefix
(maybe optional) is the new URL prefix to return to the client. The from prefix is simply replaced by this URL prefix. If you use this parameter, don't use url (and vice-versa).
escape
(optional) is a flag which tells the server to util_uri_escape the URL before sending it. It should be yes or no. The default is yes. For more information about util_uri_escape, see "NSAPI Function Reference."
optional, common to all obj.conf functions
Examples
In the first example, any request for http://hostname/whatever is translated to a request for http://tmpserver/whatever.
NameTrans fn=redirect from=/ url-prefix=http://tmpserver
In the second example, any request for http://hostname/toopopular/whatever is translated to a request for http://bigger/better/stronger/morepopular/whatever.
NameTrans fn=redirect from=/toopopular url=http://bigger/better/stronger/morepopular
strip-params
Applicable in NameTrans-class directives.
The strip-params function removes embedded semicolon-delimited parameters from the path. For example, a URI of /dir1;param1/dir2 would become a path of /dir1/dir2. When used, the strip-params function should be the first NameTrans directive listed.
Parameters
The following table describes parameters for the strip-params function. The left column lists the parameter name, and the right column describes what the parameter does.
strip-params parameters
Parameter
Description
optional, common to all obj.conf functions
Example
NameTrans fn=strip-params
unix-home
Applicable in NameTrans-class directives.
UNIX Only. The unix-home function translates user names (typically of the form ~username) into the user's home directory on the server's UNIX machine. You specify a URL prefix that signals user directories. Any request that begins with the prefix is translated to the user's home directory.
You specify the list of users with either the /etc/passwd file or a file with a similar structure. Each line in the file should have this structure (elements in the passwd file that are not needed are indicated with *):
username:*:*:groupid:*:homedir:*
If you want the server to scan the password file only once at startup, use the Init-class function init-uhome in init.conf.
Parameters
The following table describes parameters for the unix-home function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
NameTrans fn=unix-home from=/~ subdir=public_html
NameTrans fn=unix-home from /~ pwfile=/mydir/passwd subdir=public_html
See Also
PathCheck Stage
PathCheck directives check the local file system path that is returned after the NameTrans step. The path is checked for things such as CGI path information and for dangerous elements such as /./and /../ and //, and then any access restriction is applied.
If there is more than one PathCheck directive, each of the functions are executed in order.
The following PathCheck-class functions are described in detail in this section:
- check-acl checks an access control list for authorization.
- deny-existence indicates that a resource was not found.
- find-index locates a default file when a directory is requested.
- find-links denies access to directories with certain file system links
- find-pathinfo locates extra path info beyond the file name for the PATH_INFO CGI environment variable.
- get-client-cert gets the authenticated client certificate from the SSL3 session.
- load-config finds and loads extra configuration information from a file in the requested path
- nt-uri-clean denies access to requests with unsafe path names by indicating that access to the requested resource is forbidden.
- ntcgicheck looks for a CGI file with a specified extension.
- require-auth denies access to unauthorized users or groups.
- set-virtual-index specifies a virtual index for a directory.
- ssl-check checks the secret keysize.
- ssl-logout invalidates the current SSL session in the server's SSL session cache.
- unix-uri-clean denies access to requests with unsafe path names by indicating that access to the requested resource is forbidden.
check-acl
Applicable in PathCheck-class directives.
The check-acl function specifies an Access Control List (ACL) to use to check whether the client is allowed to access the requested resource. An access control list contains information about who is or is not allowed to access a resource, and under what conditions access is allowed.
Regardless of the order of PathCheck directives in the object, check-acl functions are executed first. They cause user authentication to be performed, if required by the specified ACL, and will also update the access control state.
Parameters
The following table describes parameters for the check-acl function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
PathCheck fn=check-acl acl="*HRonly*"
deny-existence
Applicable in PathCheck-class directives.
The deny-existence function sends a "not found" message when a client tries to access a specified path. The server sends "not found" instead of "forbidden," so the user cannot tell whether the path exists or not.
Parameters
The following table describes parameters for the deny-existence function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
PathCheck fn=deny-existence path=/usr/Sun/AppServer7/domains/domain1/server1/docs/private
PathCheck fn=deny-existence bong-file=/svr/msg/go-away.html
find-index
Applicable in PathCheck-class directives.
The find-index function investigates whether the requested path is a directory. If it is, the function searches for an index file in the directory, and then changes the path to point to the index file. If no index file is found, the server generates a directory listing.
Note that if the file obj.conf has a NameTrans directive that calls home-page, and the requested directory is the root directory, then the home page rather than the index page, is returned to the client.
The find-index function does nothing if there is a query string, if the HTTP method is not GET, or if the path is that of a valid file.
Parameters
The following table describes parameters for the find-index function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
PathCheck fn=find-index index-names=index.html,home.html
find-links
Applicable in PathCheck-class directives.
UNIX Only. The find-links function searches the current path for symbolic or hard links to other directories or file systems. If any are found, an error is returned. This function is normally used for directories that are not trusted (such as user home directories). It prevents someone from pointing to information that should not be made public.
Parameters
The following table describes parameters for the find-links function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
PathCheck fn=find-links disable=sh dir=/foreign-dir
PathCheck fn=find-links disable=so dir=public_html
See Also
find-pathinfo
Applicable in PathCheck-class directives.
The find-pathinfo function finds any extra path information after the file name in the URL and stores it for use in the CGI environment variable PATH_INFO.
Parameters
The following table describes parameters for the find-pathinfo function. The left column lists the parameter name, and the right column describes what the parameter does.
find-pathinfo parameters
Parameter
Description
optional, common to all obj.conf functions
Examples
PathCheck fn=find-pathinfo
PathCheck fn=find-pathinfo find-pathinfo-forward=""
get-client-cert
Applicable in PathCheck-class directives.
The get-client-cert function gets the authenticated client certificate from the SSL3 session. It can apply to all HTTP methods, or only to those that match a specified pattern. It only works when SSL is enabled on the server.
If the certificate is present or obtained from the SSL3 session, the function returns REQ_NOACTION, allowing the request to proceed, otherwise it returns REQ_ABORTED and sets the protocol status to 403 FORBIDDEN, causing the request to fail and the client to be given the FORBIDDEN status.
Parameters
The following table describes parameters for the get-client-cert function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
load-config
Applicable in PathCheck-class directives.
The load-config function searches for configuration files in document directories and adds the file's contents to the server's existing configuration. These configuration files (also known as dynamic configuration files) specify additional access control information for the requested resource. Depending on the rules in the dynamic configuration files, the server might or might not allow the client to access the requested resource.
Each directive that invokes load-config is associated with a base directory, which is either stated explicitly through the basedir parameter or derived from the root directory for the requested resource. The base directory determines two things:
- the top-most directory for which requests will invoke this call to the load-config function.
For example, if the base directory is D:/Sun/AppServer7/domains/domain1/server1/docs/nikki/, then only requests for resources in this directory or its subdirectories (and their subdirectories and so on) trigger the search for dynamic configuration files. A request for the resource D:/Sun/AppServer7/domains/domain1/server1/docs/somefile.html does not trigger the search in this case, since the requested resource is in a parent directory of the base directory.
- the top-most directory in which the server looks for dynamic configuration files to apply to the requested resource.
If the base directory is D:/Sun/AppServer7/domains/domain1/server1/docs/nikki/, the server starts its search for dynamic configuration files in this directory. It may or may not also search subdirectories (but never parent directories) depending on other factors.
If you manually add PathCheck directives that invoke load-config to the file obj.conf, put them in additional objects (created with the <OBJECT> tag) rather than putting them in the default object. Use the ppath attribute of the OBJECT tag to specify the partial pathname for the resources to be affected by the access rules in the dynamic configuration file. The partial pathname can be any pathname that matches a pattern, which can include wildcard characters.
For example, the following <OBJECT> tag specifies that requests for resources in the directory D:/Sun/AppServer7/domains/domain1/server1/docs are subject to the access rules in the file my.nsconfig.
<Object ppath="D:/Sun/AppServer7/domains/domain1/server1/docs/*">
PathCheck fn="load-config" file="my.nsconfig" descend=1 basedir="D:/Sun/AppServer7/domains/domain1/server1/docs"
</Object>
The load-config function returns REQ_PROCEED if configuration files were loaded, REQ_ABORTED on error, or REQ_NOACTION when no files are loaded.
Parameters
The following table describes parameters for the load-config function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
In this example, whenever the server receives a request for any resource containing the substring secret that resides in D:/Sun/AppServer7/domains/domain1/server1/docs/nikki/ or a subdirectory thereof, it searches for a configuration file called checkaccess.nsconfig.
The server starts the search in the directory D:/Sun/AppServer7/domains/domain1/server1/docs/nikki, and searches subdirectories too. It loads each instance of checkaccess.nsconfig that it finds, applying the access control rules contained therein to determine whether the client is allowed to access the requested resource or not.
<Object ppath="*secret*">
PathCheck fn="load-config" file="checkaccess.nsconfig" basedir="D:/Sun/AppServer7/domains/domain1/server1/docs/nikki" descend="1"
</Object>nt-uri-clean
Applicable in PathCheck-class directives.
Windows Only. The nt-uri-clean function denies access to any resource whose physical path contains \.\, \..\ or \\ (these are potential security problems).
Parameters
The following table describes parameters for the nt-uri-clean function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
PathCheck fn=nt-uri-clean
See Also
ntcgicheck
Applicable in PathCheck-class directives.
Windows Only. The ntcgicheck function specifies the file name extension to be added to any file name that does not have an extension, or to be substituted for any file name that has the extension .cgi.
Parameters
The following table describes parameters for the ntcgicheck function. The left column lists the parameter name, and the right column describes what the parameter does.
ntcgicheck parameters
Parameter
Description
extension
is the replacement file extension.
optional, common to all obj.conf functions
Examples
PathCheck fn=ntcgicheck extension=pl
See Also
init-cgi, send-cgi, send-wincgi, send-shellcgi
require-auth
Applicable in PathCheck-class directives.
The require-auth function allows access to resources only if the user or group is authorized. Before this function is called, an authorization function (such as basic-auth) must be called in an AuthTrans directive.
If a user was authorized in an AuthTrans directive, and the auth-user parameter is provided, then the user's name must match the auth-user wildcard value. Also, if the auth-group parameter is provided, the authorized user must belong to an authorized group which must match the auth-user wildcard value.
Parameters
The following table describes parameters for the require-auth function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
PathCheck fn=require-auth auth-type=basic realm="Marketing Plans" auth-group=mktg auth-user=(jdoe|johnd|janed)
See Also
set-virtual-index
Applicable in PathCheck-class directives.
The set-virtual-index function specifies a virtual index for a directory, which determines the URL forwarding. The index can refer to a servlet in its own namespace, for example.
REQ_NOACTION is returned if none of the URIs listed in the from parameter match the current URI. REQ_ABORTED is returned if the file specified by the virtual-index parameter is missing or if the current URI cannot be found. REQ_RESTART is returned if the current URI matches any one of the URIs mentioned in the from parameter or if there is no from parameter.
Parameters
The following table describes parameters for the set-virtual-index function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
# MyLWApp is a LiveWire application
PathCheck fn=set-virtual-index virtual-index=MyLWAppssl-check
Applicable in PathCheck-class directives.
If a restriction is selected that is not consistent with the current cipher settings under Security Preferences, this function opens a popup dialog which warns that ciphers with larger secret keysizes need to be enabled. This function is designed to be used together with a Client tag to limit access of certain directories to non-exportable browsers.
The function returns REQ_NOACTION if SSL is not enabled, or if the secret-keysize parameter is not specified. If the secret keysize for the current session is less than the specified secret-keysize and the bong-file parameter is not specified, the function returns REQ_ABORTED with a status of PROTOCOL_FORBIDDEN. If the bong file is specified, the function returns REQ_PROCEED, and the path variable is set to the bong filename. Also, when a keysize restriction is not met, the SSL session cache entry for the current session is invalidated, so that a full SSL handshake will occur the next time the same client connects to the server.
Requests that use ssl-check are not cacheable in the accelerator file cache if ssl-check returns something other than REQ_NOACTION.
Parameters
The following table describes parameters for the ssl-check function. The left column lists the parameter name, and the right column describes what the parameter does.
ssl-logout
Applicable in PathCheck-class directives.
ssl-logout invalidates the current SSL session in the server's SSL session cache. This does not affect the current request, but the next time the client connects, a new SSL session will be created. If SSL is enabled, this function returns REQ_PROCEED after invalidating the session cache entry. If SSL is not enabled, it returns REQ_NOACTION.
Parameters
The following table describes parameters for the ssl-logout function. The left column lists the parameter name, and the right column describes what the parameter does.
ssl-logout parameters
Parameter
Description
optional, common to all obj.conf functions
unix-uri-clean
Applicable in PathCheck-class directives.
UNIX Only. The unix-uri-clean function denies access to any resource whose physical path contains /./, /../ or // (these are potential security problems).
Parameters
The following table describes parameters for the unix-uri-clean function. The left column lists the parameter name, and the right column describes what the parameter does.
unix-uri-clean parameters
Parameter
Description
dotdirok
If present, "//" sequences are allowed.
optional, common to all obj.conf functions
Examples
PathCheck fn=unix-uri-clean
See Also
ObjectType Stage
ObjectType directives determine the MIME type of the file to send to the client in response to a request. MIME attributes currently sent are type, encoding, and language. The MIME type sent to the client as the value of the content-type header.
ObjectType directives also set the type parameter, which is used by Service directives to determine how to process the request according to what kind of content is being requested.
If there is more than one ObjectType directive in an object, all the directives are applied in the order they appear. If a directive sets an attribute and later directives try to set that attribute to something else, the first setting is used and the subsequent ones ignored.
The obj.conf file almost always has an ObjectType directive that calls the type-by-extension function. This function instructs the server to look in a particular file (the MIME types file) to deduce the content type from the extension of the requested resource.
The following ObjectType-class functions are described in detail in this section:
- check-passthrough checks to see if the requested resource is available on the local server.
- force-type sets the content-type header for the response to a specific type.
- set-default-type allows you to define a default charset, content-encoding, and content-language for the response being sent back to the client.
- shtml-hacktype requests that .htm and .html files are parsed for server-parsed html commands.
- type-by-exp sets the content-type header for the response based on the requested path.
- type-by-extension sets the content-type header for the response based on the files extension and the MIME types database.
check-passthrough
Applicable in ObjectType-class directives.
The check-passthrough function checks to see if the requested resource (for example, the HTML document or GIF image) is available on the local server. If the requested resource does not exist locally, check-passthrough sets the type to indicate that the request should be passed to another server for processing by service-passthrough.
Parameters
The following table describes parameters for the check-passthrough function. The left column lists the parameter name, and the right column describes what the parameter does.
Example
ObjectType fn="check-passthrough"
See Also
init-passthrough, auth-passthrough, service-passthrough
force-type
Applicable in ObjectType-class directives.
The force-type function assigns a type to requests that do not already have a MIME type. This is used to specify a default object type.
Make sure that the directive that calls this function comes last in the list of ObjectType directives so that all other ObjectType directives have a chance to set the MIME type first. If there is more than one ObjectType directive in an object, all the directives are applied in the order they appear. If a directive sets an attribute and later directives try to set that attribute to something else, the first setting is used and the subsequent ones ignored.
Parameters
The following table describes parameters for the force-type function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
ObjectType fn=force-type type=text/plain
ObjectType fn=force-type lang=en_US
See Also
type-by-extension, type-by-exp
set-default-type
Applicable in ObjectType-class directives.
This function allows you to define a default charset, content-encoding, and content-language for the response being sent back to the client.
If the charset, content-encoding, and content-language have not been set for a response, then just before the headers are sent the defaults defined by set-default-type are used. Note that by placing this function in different objects in obj.conf, you can define different defaults for different parts of the document tree.
Parameters
The following table describes parameters for the set-default-type function. The left column lists the parameter name, and the right column describes what the parameter does.
Example
ObjectType fn="set-default-type" charset="iso_8859-1"
shtml-hacktype
Applicable in ObjectType-class directives.
The shtml-hacktype function changes the content-type of any .htm or .html file to magnus-internal/parsed-html and returns REQ_PROCEED. This provides backward compatibility with server-side includes for files with .htm or .html extensions. The function may also check the execute bit for the file on UNIX systems. The use of this function is not recommended.
Parameters
The following table describes parameters for the shtml-hacktype function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
ObjectType fn=shtml-hacktype exec-hack=true
type-by-exp
Applicable in ObjectType-class directives.
The type-by-exp function matches the current path with a wildcard expression. If the two match, the type parameter information is applied to the file. This is the same as type-by-extension, except you use wildcard patterns for the files or directories specified in the URLs.
Parameters
The following table describes parameters for the type-by-exp function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
ObjectType fn=type-by-exp exp=*.test type=application/html
See Also
type-by-extension
Applicable in ObjectType-class directives.
This function instructs the server to look in a table of MIME type mappings to find the MIME type of the requested resource according to the extension of the requested resource. The MIME type is added to the content-type header sent back to the client.
The table of MIME type mappings is created by a MIME element in the server.xml file, which loads a MIME types file or list and creates the mappings. For more information about server.xml and MIME types files, see the Sun ONE Application Server Administrator's Configuration File Reference.
For example, the following two lines are part of a MIME types file:
type=text/html exts=htm,html
type=text/plain exts=txtIf the extension of the requested resource is htm or html, the type-by-extension file sets the type to text/html. If the extension is .txt, the function sets the type to text/plain.
Parameters
The following table describes parameters for the type-by-extension function. The left column lists the parameter name, and the right column describes what the parameter does.
type-by-extension parameters
Parameter
Description
optional, common to all obj.conf functions
Examples
ObjectType fn=type-by-extension
See Also
Service Stage
The Service class of functions sends the response data to the client.
Every Service directive has the following optional parameters to determine whether the function is executed. All the optional parameters must match the current request for the function to be executed.
- type
(optional) specifies a wildcard pattern of MIME types for which this function will be executed. The magnus-internal/* MIME types are used only to select a Service function to execute.
- method
(optional) specifies a wildcard pattern of HTTP methods for which this function will be executed. Common HTTP methods are GET, HEAD, and POST.
- query
(optional) specifies a wildcard pattern of query strings for which this function will be executed.
- UseOutputStreamSize
(optional) determines the default output stream buffer size, in bytes, for data sent to the client. If this parameter is not specified, the default is 8192 bytes.
Note The UseOutputStreamSize parameter can be set to zero in the obj.conf file to disable output stream buffering. For the init.conf file, setting UseOutputStreamSize to zero has no effect.
- flushTimer
(optional) determines the maximum number of milliseconds between write operations in which buffering is enabled. If the interval between subsequent write operations is greater than the flushTimer value for an application, further buffering is disabled. This is necessary for status monitoring CGI applications that run continuously and generate periodic status update reports. If this parameter is not specified, the default is 3000 milliseconds.
- ChunkedRequestBufferSize
(optional) determines the default buffer size, in bytes, for "un-chunking" request data. If this parameter is not specified, the default is 8192 bytes.
- ChunkedRequestTimeout
(optional) determines the default timeout, in seconds, for "un-chunking" request data. If this parameter is not specified, the default is 60 seconds.
If there is more than one Service-class function, the first one matching the optional wildcard parameters (type, method, and query) is executed.
For more information about the UseOutputStreamSize, flushTimer, ChunkedRequestBufferSize, and ChunkedRequestTimeout parameters, see "Buffered Streams". The UseOutputStreamSize, ChunkedRequestBufferSize, and ChunkedRequestTimeout parameters also have equivalent init.conf directives; see the Sun ONE Application Server Administrator's Configuration File Reference. The obj.conf parameters override the init.conf directives.
By default, the server sends the requested file to the client by calling the send-file function. The directive that sets the default is:
Service method="(GET|HEAD|POST)" type="*~magnus-internal/*" fn="send-file"
This directive usually comes last in the set of Service-class directives to give all other Service directives a chance to be invoked. This directive is invoked if the method of the request is GET, HEAD, or POST, and the type does not start with magnus-internal/. Note here that the pattern *~ means "does not match." For a list of characters that can be used in patterns, see "Wildcard Patterns."
The following Service-class functions are described in detail in this section:
- add-footer appends a footer specified by a filename or URL to a an HTML file.
- add-header prepends a header specified by a filename or URL to an HTML file.
- append-trailer appends text to the end of an HTML file.
- imagemap handles server-side image maps.
- index-common generates a fancy list of the files and directories in a requested directory.
- index-simple generates a simple list of files and directories in a requested directory.
- key-toosmall indicates to the client that the provided certificate key size is too small to accept.
- list-dir lists the contents of a directory.
- make-dir creates a directory.
- query-handler handles the HTML ISINDEX tag.
- remove-dir deletes an empty directory.
- remove-file deletes a file.
- rename-file renames a file.
- send-cgi sets up environment variables, launches a CGI program, and sends the response to the client.
- send-file sends a local file to the client.
- send-range sends a range of bytes of a file to the client.
- send-shellcgi sets up environment variables, launches a shell CGI program, and sends the response to the client.
- send-wincgi sets up environment variables, launches a WinCGI program, and sends the response to the client.
- service-dump creates a performance report based on collected performance bucket data.
- service-j2ee services requests made to Java web applications.
- service-passthrough forwards a request to another server for processing.
- shtml_send parses an HTML file for server-parsed html commands.
- upload-file uploads and saves a file.
add-footer
Applicable in Service-class directives.
This function appends a footer to an HTML file that is sent to the client. The footer is specified either as a filename or a URI -- thus the footer can be dynamically generated. To specify static text as a footer, use the append-trailer function.
Parameters
The following table describes parameters for the add-footer function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
Service type=text/html method=GET fn=add-footer file="footers/footer1.html"
Service type=text/html method=GET fn=add-footer file="D:/Sun/AppServer7/domains/domain1/server1/footers/footer1.html" NSIntAbsFilePath="yes"
See Also
add-header
Applicable in Service-class directives.
This function prepends a header to an HTML file that is sent to the client. The header is specified either as a filename or a URI -- thus the header can be dynamically generated.
Parameters
The following table describes parameters for the add-header function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
Service type=text/html method=GET fn=add-header file="headers/header1.html"
Service type=text/html method=GET fn=add-footer file="D:/Sun/AppServer7/domains/domain1/server1/headers/header1.html" NSIntAbsFilePath="yes"
See Also
append-trailer
Applicable in Service-class directives.
The append-trailer function sends an HTML file and appends text to the end. It only appends text to HTML files. This is typically used for author information and copyright text. The date the file was last modified can be inserted.
Returns REQ_ABORTED if a required parameter is missing, if there is extra path information after the file name in the URL, or if the file cannot be opened for read-only access.
Parameters
The following table describes parameters for the append-trailer function. The left column lists the parameter name, and the right column describes what the parameter does.
append-trailer parameters
Parameter
Description
trailer
is the text to append to HTML documents. The string is unescaped with util_uri_unescape before being sent. The text can contain HTML tags and can be up to 512 characters long after unescaping and inserting the date.
If you use the string :LASTMOD:, which is replaced by the date the file was last modified; you must also specify a time format with timefmt.
timefmt
(optional) is a time format string for :LASTMOD:. For details about time formats refer to "Time Formats." If timefmt is not provided, :LASTMOD: will not be replaced with the time.
optional, common to all Service-class functions
optional, common to all Service-class functions
optional, common to all Service-class functions
optional, common to all Service-class functions
optional, common to all Service-class functions
optional, common to all Service-class functions
optional, common to all Service-class functions
optional, common to all obj.conf functions
Examples
See Also
imagemap
Applicable in Service-class directives.
The imagemap function responds to requests for imagemaps. Imagemaps are images which are divided into multiple areas that each have an associated URL. The information about which URL is associated with which area is stored in a mapping file.
Parameters
The following table describes parameters for the imagemap function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
Service type=magnus-internal/imagemap method=(GET|HEAD) fn=imagemap
index-common
Applicable in Service-class directives.
The index-common function generates a fancy (or common) list of files in the requested directory. The list is sorted alphabetically. Files beginning with a period (.) are not displayed. Each item appears as an HTML link. This function displays more information than index-simple including the size, date last modified, and an icon for each file. It may also include a header and/or readme file into the listing.
The Init-class function cindex-init in init.conf specifies the format for the index list, including where to look for the images.
If obj.conf contains a call to index-common in the Service stage, init.conf must initialize fancy (or common) indexing by invoking cindex-init during the Init stage.
Indexing occurs when the requested resource is a directory that does not contain an index file or a home page, or no index file or home page has been specified by the functions find-index or home-page.
The icons displayed are .gif files dependent on the content-type of the file.
The following table describes which icon is displayed based on the content-type of the file. The left column lists the content-type values, and the right column lists the .gif files for the displayed icons.
content-type icons
Content Type
Icon
"text/*"
text.gif
"image/*"
image.gif
"audio/*"
sound.gif
"video/*"
movie.gif
"application/octet-stream"
binary.gif
directory
menu.gif
all others
unknown.gif
Parameters
The following table describes parameters for the index-common function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
Service fn=index-common type=magnus-internal/directory method=(GET|HEAD) header=hdr readme=rdme.txt
See Also
cindex-init, index-simple, find-index, home-page
index-simple
Applicable in Service-class directives.
The index-simple function generates a simple index of the files in the requested directory. It scans a directory and returns an HTML page to the browser displaying a bulleted list of the files and directories in the directory. The list is sorted alphabetically. Files beginning with a period (.) are not displayed. Each item appears as an HTML link.
Indexing occurs when the requested resource is a directory that does not contain either an index file or a home page, or no index file or home page has been specified by the functions find-index or home-page.
Parameters
The following table describes parameters for the index-simple function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
Service type=magnus-internal/directory fn=index-simple
See Also
key-toosmall
Applicable in Service-class directives.
Note This function is provided for backward compatibility only and was deprecated in iPlanet Web Server 4.x. It is replaced by the PathCheck-class SAF ssl-check.
The key-toosmall function returns a message to the client specifying that the secret key size for SSL communications is too small. This function is designed to be used together with a Client tag to limit access of certain directories to non-exportable browsers.
Parameters
The following table describes parameters for the key-toosmall function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
<Object ppath=/mydocs/secret/*>
Service fn=key-toosmall
</Object>list-dir
Applicable in Service-class directives.
The list-dir function returns a sequence of text lines to the client in response to a request whose method is INDEX. The format of the returned lines is:
name type size mimetype
The name field is the name of the file or directory. It is relative to the directory being indexed. It is URL-encoded, that is, any character might be represented by %xx, where xx is the hexadecimal representation of the character's ASCII number.
The type field is a MIME type such as text/html. Directories will be of type directory. A file for which the server doesn't have a type will be of type unknown.
The size field is the size of the file, in bytes.
The mtime field is the numerical representation of the date of last modification of the file. The number is the number of seconds since the epoch (Jan. 1, 1970 00:00 UTC) since the last modification of the file.
When remote file manipulation is enabled in the server, the obj.conf file contains a Service-class function that calls list-dir for requests whose method is INDEX.
Parameters
The following table describes parameters for the list-dir function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
Service fn=list-dir method="INDEX"
make-dir
Applicable in Service-class directives.
The make-dir function creates a directory when the client sends a request whose method is MKDIR. The function can fail if the server can't write to that directory.
When remote file manipulation is enabled in the server, the obj.conf file contains a Service-class function that invokes make-dir when the request method is MKDIR.
Parameters
The following table describes parameters for the make-dir function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
Service fn="make-dir" method="MKDIR"
query-handler
Applicable in Service-class directives.
Note This function is provided for backward compatibility only and is used mainly to support the obsolete ISINDEX tag. If possible, use an HTML form instead.
The query-handler function runs a CGI program instead of referencing the path requested.
Parameters
The following table describes parameters for the query-handler function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
Service query=* fn=query-handler path=/http/cgi/do-grep
Service query=* fn=query-handler path=/http/cgi/proc-info
remove-dir
Applicable in Service-class directives.
The remove-dir function removes a directory when the client sends an request whose method is RMDIR. The directory must be empty (have no files in it). The function will fail if the directory is not empty or if the server doesn't have the privileges to remove the directory.
When remote file manipulation is enabled in the server, the obj.conf file contains a Service-class function that invokes remove-dir when the request method is RMDIR.
Parameters
The following table describes parameters for the remove-dir function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
Service fn="remove-dir" method="RMDIR"
remove-file
Applicable in Service-class directives.
The remove-file function deletes a file when the client sends a request whose method is DELETE. It deletes the file indicated by the URL if the user is authorized and the server has the needed file system privileges.
When remote file manipulation is enabled in the server, the obj.conf file contains a Service-class function that invokes remove-file when the request method is DELETE.
Parameters
The following table describes parameters for the remove-file function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
Service fn="remove-file" method="DELETE"
rename-file
Applicable in Service-class directives.
The rename-file function renames a file when the client sends a request with a New-URL header whose method is MOVE. It renames the file indicated by the URL to New-URL within the same directory if the user is authorized and the server has the needed file system privileges.
When remote file manipulation is enabled in the server, the obj.conf file contains a Service-class function that invokes rename-file when the request method is MOVE.
Parameters
The following table describes parameters for the rename-file function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
Service fn="rename-file" method="MOVE"
send-cgi
Applicable in Service-class directives.
The send-cgi function sets up the CGI environment variables, runs a file as a CGI program in a new process, and sends the results to the client.
For details about the CGI environment variables and their NSAPI equivalents, refer to "CGI to NSAPI Conversion".For additional information about CGI, see the Sun ONE Application Server Administrator's Guide and the Sun ONE Application Server Developer's Guide to Web Applications.
You can change the timing used to flush the CGI buffer in these ways:
- Adjust the interval between flushes using the flushTimer parameter
- Adjust the buffer size using the UseOutputStreamSize parameter
- Force Sun ONE Application Server to flush its buffer by forcing spaces into the buffer in the CGI script
For more information about flushTimer and UseOutputStreamSize, see "Buffered Streams".
Parameters
The following table describes parameters for the send-cgi function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
The following example uses variables defined in the server.xml file for the send-cgi parameters. For more information about defining variables, see the Sun ONE Application Server Administrator's Configuration File Reference.
<Object name="default">
...
NameTrans fn="pfx2dir" from="/cgi-bin" dir="/home/foo.com/public_html/cgi-bin" name="cgi"
...
</Object>
<Object name="cgi">
ObjectType fn="force-type" type="magnus-internal/cgi"
Service fn="send-cgi" user="$user" group="$group" dir="$dir" chroot="$chroot" nice="$nice"
</Object>
send-file
Applicable in Service-class directives.
The send-file function sends the contents of the requested file to the client. It provides the content-type, content-length, and last-modified headers.
Most requests are handled by this function using the following directive (which usually comes last in the list of Service-class directives in the default object so that it acts as a default)
Service method="(GET|HEAD|POST)" type="*~magnus-internal/*" fn="send-file"
This directive is invoked if the method of the request is GET, HEAD, or POST, and the type does not start with magnus-internal/. Note here that the pattern *~ means "does not match." For a list of characters that can be used in patterns, see "Wildcard Patterns."
Parameters
The following table describes parameters for the send-file function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
Service type="*~magnus-internal/*" method="(GET|HEAD)" fn="send-file"
In the following example, the server does not cache static files from /export/somedir/ when requested by the URL prefix /myurl.
<Object name=default>
...
NameTrans fn="pfx2dir" from="/myurl" dir="/export/mydir", name="myname"
...
Service method=(GET|HEAD|POST) type=*~magnus-internal/* fn=send-file
...
</Object>
<Object name="myname">
Service method=(GET|HEAD) type=*~magnus-internal/* fn=send-file nocache=""
</Object>
send-range
Applicable in Service-class directives.
When the client requests a portion of a document, by specifying HTTP byte ranges, the send-range function returns that portion.
Parameters
The following table describes parameters for the send-range function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
Service fn=send-range
send-shellcgi
Applicable in Service-class directives.
Windows only. The send-shellcgi function runs a file as a shell CGI program and sends the results to the client. Shell CGI is a server configuration that lets you run CGI applications using the file associations set in Windows. For information about shell CGI programs, consult the Sun ONE Application Server Administrator's Guide.
Parameters
The following table describes parameters for the send-shellcgi function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
Service fn=send-shellcgi
Service type=magnus-internal/cgi fn=send-shellcgi
send-wincgi
Applicable in Service-class directives.
Windows only. The send-wincgi function runs a file as a Windows CGI program and sends the results to the client. For information about Windows CGI programs, consult the Sun ONE Application Server Administrator's Guide.
Parameters
The following table describes parameters for the send-wincgi function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
Service fn=send-wincgi
Service type=magnus-internal/cgi fn=send-wincgi
service-dump
Applicable in Service-class directives.
The service-dump function creates a performance report based on collected performance bucket data (see "The bucket Parameter").
To read the report, point the browser here:
http://host_name:port/.perf
Parameters
The following table describes parameters for the service-dump function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
<Object name=default>
NameTrans fn="assign-name" from="/.perf" name="perf"
...
</Object>
<Object name=perf>
Service fn="service-dump"
</Object>See Also
service-j2ee
Applicable in Service-class directives.
The service-j2ee function services requests made to Java web applications.
Parameters
The following table describes parameters for the service-j2ee function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
<Object name=default>
NameTrans fn="ntrans-j2ee" name="j2ee"
...
</Object>
<Object name=j2ee>
Service fn="service-j2ee"
</Object>See Also
init-j2ee, ntrans-j2ee, error-j2ee
service-passthrough
Applicable in Service-class directives.
The service-passthrough function forwards a request to another server for processing. This function can be configured to use SSL or non-SSL (HTTPS or HTTP) connections to the remote server independently of the type of connection the original request arrived on.
The service-passthrough function encodes information about the originating client that may be decoded by an auth-passthrough function running on the remote server. Use of auth-passthrough is optional.
When multiple remote servers are configured, service-passthrough chooses a single remote server from the list on a request-by-request basis.
Parameters
The following table describes parameters for the service-passthrough function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
Here is a stand-alone example of the service-passthrough function:
Service fn="service-passthrough" servers="http://server1 http://server2"
A service-passthrough function is typically used in combination with other directives in the obj.conf configuration file as follows:
This example forwards any request for the web application deployed at the URI /webapp1 to one of the backend application servers at IP addresses 192.168.1.100 and 192.168.1.101. If the backend application server is down, the local HTML file badgateway.html is displayed instead.
If you want the server running service-passthrough to serve files it has access to and forward only those requests it cannot satisfy to the backend application servers, change the ObjectType line as follows:
ObjectType fn="check-passthrough" type="magnus-internal/passthrough"
See Also
init-passthrough, auth-passthrough, check-passthrough, assign-name, force-type, deny-existence
shtml_send
Applicable in Service-class directives.
The shtml_send function parses an HTML document, scanning for embedded commands. These commands may provide information from the server, include the contents of other files, or execute a CGI program. The shtml_send function is only available when the Shtml plugin (libShtml.so on UNIX libShtml.dll on Windows) is loaded. Refer to the Sun ONE Application Server Developer's Guide to Web Applications for server-parsed HTML commands.
Parameters
The following table describes parameters for the shtml_send function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
Service type=magnus-internal/shtml_send method=(GET|HEAD) fn=shtml_send
upload-file
Applicable in Service-class directives.
The upload-file function uploads and saves a new file when the client sends a request whose method is PUT if the user is authorized and the server has the needed file system privileges.
When remote file manipulation is enabled in the server, the obj.conf file contains a Service-class function that invokes upload-file when the request method is PUT.
Parameters
The following table describes parameters for the upload-file function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
Service fn=upload-file
AddLog Stage
After the server has responded to the request, the AddLog directives are executed to record information about the transaction.
If there is more than one AddLog directive, all are executed.
The following AddLog-class functions are described in detail in this section:
- common-log records information about the request in the common log format.
- flex-log records information about the request in a flexible, configurable format.
- record-useragent records the client's ip address and user-agent header.
common-log
Applicable in AddLog-class directives.
This function records request-specific data in the common log format (used by most HTTP servers). There is a log analyzer in the /extras/log_anly directory for Sun ONE Application Server.
The common log must have been initialized previously by the init-clf function. For information about rotating logs, see flex-rotate-init.
There are also a number of free statistics generators for the common log format.
Parameters
The following table describes parameters for the common-log function. The left column lists the parameter name, and the right column describes what the parameter does.
common-log parameters
Parameter
Description
name
(optional) gives the name of a log file, which must have been given as a parameter to the init-clf function in init.conf. If no name is given, the entry is recorded in the global log file.
iponly
(optional) instructs the server to log the IP address of the remote client rather than looking up and logging the DNS name. This will improve performance if DNS is off in the init.conf file. The value of iponly has no significance, as long as it exists; you may use iponly=1.
optional, common to all obj.conf functions
Examples
# Log all accesses to the global log file
AddLog fn=common-log
# Log accesses from outside our subnet (198.93.5.*) to
# nonlocallog
<Client ip="*~198.93.5.*">
AddLog fn=common-log name=nonlocallog
</Client>
See Also
flex-init, init-clf, record-useragent, flex-log, flex-rotate-init
flex-log
Applicable in AddLog-class directives.
This function records request-specific data in a flexible log format. It may also record requests in the common log format. There is a log analyzer in the /extras/flexanlg directory for Sun ONE Application Server.
There are also a number of free statistics generators for the common log format.
The log format is specified by the flex-init function call. For information about rotating logs, see flex-rotate-init.
Parameters
The following table describes parameters for the flex-log function. The left column lists the parameter name, and the right column describes what the parameter does.
flex-log parameters
Parameter
Description
name
(optional) gives the name of a log file, which must have been given as a parameter to the flex-init function in init.conf. If no name is given, the entry is recorded in the global log file.
iponly
(optional) instructs the server to log the IP address of the remote client rather than looking up and logging the DNS name. This will improve performance if DNS is off in the init.conf file. The value of iponly has no significance, as long as it exists; you may use iponly=1.
optional, common to all obj.conf functions
Examples
# Log all accesses to the global log file
AddLog fn=flex-log
# Log accesses from outside our subnet (198.93.5.*) to
# nonlocallog
<Client ip="*~198.93.5.*">
AddLog fn=flex-log name=nonlocallog
</Client>
See Also
flex-init, init-clf, common-log, record-useragent, flex-rotate-init
record-useragent
Applicable in AddLog-class directives.
The record-useragent function records the IP address of the client, followed by its User-Agent HTTP header. This indicates what version of the client was used for this transaction. For information about rotating logs, see flex-rotate-init.
Parameters
The following table describes parameters for the record-useragent function. The left column lists the parameter name, and the right column describes what the parameter does.
record-useragent parameters
Parameter
Description
name
(optional) gives the name of a log file, which must have been given as a parameter to the init-clf function in init.conf. If no name is given, the entry is recorded in the global log file.
optional, common to all obj.conf functions
Examples
# Record the client ip address and user-agent to browserlog
AddLog fn=record-useragent name=browserlogSee Also
flex-init, init-clf, common-log, flex-log, flex-rotate-init
Error Stage
If a server application function results in an error, it sets the HTTP response status code and returns the value REQ_ABORTED. When this happens, the server stops processing the request. Instead, it searches for an Error directive matching the HTTP response status code or its associated reason phrase, and executes the directive's function. If the server does not find a matching Error directive, it returns the response status code to the client.
The following Error-class functions are described in detail in this section:
- error-j2ee handles errors that occur during execution of J2EE applications and modules deployed to the Sun ONE Application Server.
- send-error sends an HTML file to the client in place of a specific HTTP response status.
- qos-error returns an error page stating which quality of service limits caused the error and what the value of the QOS statistic was.
error-j2ee
Applicable in Error-class directives.
The error-j2ee function handles errors that occur during execution of web applications deployed to the Sun ONE Application Server individually or as part of full J2EE applications.
Parameters
The following table describes parameters for the error-j2ee function. The left column lists the parameter name, and the right column describes what the parameter does.
error-j2ee parameters
Parameter
Description
optional, common to all obj.conf functions
See Also
init-j2ee, ntrans-j2ee, service-j2ee
send-error
Applicable in Error-class directives.
The send-error function sends an HTML file to the client in place of a specific HTTP response status. This allows the server to present a friendly message describing the problem. The HTML page may contain images and links to the server's home page or other pages.
Parameters
The following table describes parameters for the send-error function. The left column lists the parameter name, and the right column describes what the parameter does.
Example
Error fn=send-error code=401 path=/Sun/AppServer7/domains/domain1/server1/docs/errors/401.html
qos-error
Applicable in Error-class directives.
The qos-error function returns an error page stating which quality of service limits caused the error and what the value of the QOS statistic was.
For more information, see the performance module of the Sun ONE Application Server Administrator's Guide.
Parameters
The following table describes parameters for the qos-error function. The left column lists the parameter name, and the right column describes what the parameter does.
Examples
Error fn=qos-error code=503
See Also