Sun Java System Web Server 6.1 SP10 Administrator's Configuration File Reference

PathCheck

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 is executed in order.

The following PathCheck-class functions are described in detail in this section:

check-acl

Applicable in PathCheck-class directives.

The check-acl function specifies an access control list (ACL) to check whether the client is allowed to access the requested resource. An ACL 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 perform user authentication if required by the specified ACL, and also update the access control state. Because the server caches the ACLs returned by the check-acl function, do no use check-acl inside a Client tag or container.

Parameters

The following table describes parameters for the check-acl function.

Table 4–18 check-acl Parameters

Parameter  

Description  

acl

Name of an access control list. 

path

(Optional) Wildcard pattern that specifies the path for which to apply the ACL. 

bucket

(Optional) Common to all obj.conf functions.

Example


PathCheck fn=check-acl acl="*HRonly*"

         

find-compressed

Applicable in PathCheck-class directives.

The find-compressed function checks if a compressed version of the requested file is available. If the following conditions are met, find-compressed changes the path to point to the compressed file:

Parameters

The following table describes parameters for the find-compressed function.

Table 4–19 find-compressed Parameters

Parameter  

Description  

check-age

Specifies whether to check if the compressed version is older than the noncompressed version. Possible values are yes and no.

  • If set to yes, the compressed version will not be selected if it is older than the noncompressed version.

  • If set to no, the compressed version will always be selected, even if it is older than the noncompressed version.

    By default, the value is set to yes.

vary

Specifies whether to insert a Vary: Accept-Encoding header. Possible values are yes or no.

  • If set to yes, a Vary: Accept-Encoding header is always inserted when a compressed version of a file is selected.

  • If set to no, a Vary: Accept-Encoding header is never inserted.

    By default, the value is set to yes.

bucket

(Optional) Common to all obj.conf functions.

Example

<Object name="default">
NameTrans fn="assign-name" from="*.html" name="find-compressed"
...
</Object>
<Object name="find-compressed">
PathCheck fn="find-compressed"
</Object>

See Also

http-compression

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 if the path exists.

Parameters

The following table describes parameters for the deny-existence function.

Table 4–20 deny-existence Parameters

Parameter  

Description  

path

(Optional) Wildcard pattern of the file system path to hide. If the path does not match, the function does nothing and returns REQ_NOACTION. If the path is not provided, it is assumed to match.

bong-file

(Optional) Specifies a file to send rather than responding with the “not found” message. It is a full file system path. 

bucket

(Optional) Common to all obj.conf functions.

Examples


PathCheck fn=deny-existence path=/usr/sun/server61/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.

Table 4–21 find-index Parameters

Parameter  

Description  

index-names

Comma-separated list of index file names to look for. Use spaces only if they are part of a file name. Do not include spaces before or after the commas. This list is case-sensitive if the file system is case-sensitive. 

bucket

(Optional) Common to all obj.conf functions.

Example


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.

Table 4–22 find-links Parameters

Parameter  

Description  

disable

Character string of links to disable: 

  • h is hard links

  • s is soft links

  • o allows symbolic links from user home directories only if the user owns the target of the link

dir

Directory to begin checking. If you specify an absolute path, any request to that path and its subdirectories is checked for symbolic links. If you specify a partial path, any request containing that partial path is checked for symbolic links. For example, if you use /user/ and a request comes in for some/user/directory, then that directory is checked for symbolic links.

checkFileExistence

Checks linked file for existence and aborts request with 403 (forbidden) if this check fails.

bucket

(Optional) Common to all obj.conf functions.

Examples


PathCheck fn=find-links disable=sh dir=/foreign-dir
PathCheck fn=find-links disable=so dir=public_html

         

See Also

unix-home

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.

Table 4–23 find-pathinfo Parameters

Parameter  

Description  

bucket

(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.

Table 4–24 get-client-cert Parameters

Parameter  

Description  

dorequest

Controls whether to actually try to get the certificate, or just test for its presence. If dorequest is absent, the default value is 0.

  • 1 tells the function to redo the SSL3 handshake to get a client certificate, if the server does not already have the client certificate. This typically causes the client to present a dialog box to the user to select a client certificate. The server may already have the client certificate if it was requested on the initial handshake, or if a cached SSL session has been resumed.

  • 0 tells the function not to redo the SSL3 handshake if the server does not already have the client certificate.

    If a certificate is obtained from the client and verified successfully by the server, the ASCII base64 encoding of the DER-encoded X.509 certificate is placed in the parameter auth-cert in the Request->vars pblock, and the function returns REQ_PROCEED, allowing the request to proceed.

require

Controls whether failure to get a client certificate will abort the HTTP request. If require is absent, the default value is 1.

  • 1 tells the function to abort the HTTP request if the client certificate is not present after dorequest is handled. In this case, the HTTP status is set to PROTOCOL_FORBIDDEN, and the function returns REQ_ABORTED.

  • 0 tells the function to return REQ_NOACTION if the client certificate is not present after dorequest is handled.

method

(Optional) Specifies a wildcard pattern for the HTTP methods for which the function will be applied. If method is absent, the function is applied to all requests.

bucket

(Optional) Common to all obj.conf functions.

Example

# Get the client certificate from the session. 
# If a certificate is not already associated with the
# session, request one.
# The request fails if the client does not present a 
# valid certificate.PathCheck fn="get-client-cert" dorequest="1"

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 may or may 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:

<Object ppath="D:/sun/server61/docs/*">
PathCheck fn="load-config" file="my.nsconfig" descend=1 
basedir="D:/sun/server61/docs" 
</Object>

Note –

If the ppath resolves to a resource or directory that is higher in the directory tree (or is in a different branch of the tree) than the base directory, the load-config function is not invoked. This is because the base directory specifies the highest-level directory for which requests will invoke the load-config function.


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.

Table 4–25 load-config Parameters

Parameter  

Description  

file

(Optional) Name of the dynamic configuration file containing the access rules to be applied to the requested resource. If not provided, the file name is assumed to be .nsconfig.

disable-types

(Optional) Specifies a wildcard pattern of types to disable for the base directory, such as magnus-internal/cgi. Requests for resources matching these types are aborted.

descend

(Optional) If present, specifies that the server should search in subdirectories of this directory for dynamic configuration files. For example, descend=1 specifies that the server should search subdirectories. No descend parameter specifies that the function should search only the base directory.

basedir

(Optional) Specifies base directory. This is the highest-level directory for which requests will invoke the load-config function, and is also the directory where the server starts searching for configuration files.

If basedir is not specified, the base directory is assumed to be the root directory that results from translating the requested resource’s URL to a physical path name. For example, if the request is for http://server-name/a/b/file.html, the physical file name would be /document-root/a/b/file.html.

bucket

(Optional) Common to all obj.conf functions.

Examples

In this example, whenever the server receives a request for any resource containing the substring secret that resides in D:/Sun/WebServer61/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/WebServer61/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.

<Object ppath="*secret*"> 
PathCheck fn="load-config" file="checkaccess.nsconfig" 
basedir="D:/Sun/WebServer61/server1/docs/nikki" descend="1" 
</Object>

match-browser

Applicable in all stage directives. The match-browser SAF matches specific strings in the User-Agent string supplied by the browser, and then modifies the behavior of Sun Java System Web Server based upon the results by setting values for specified variables. See match-browser.

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.

Table 4–26 nt-uri-clean Parameters

Parameter  

Description  

tildeok

If present, allows tilde (~) characters in URIs. This is a potential security risk on the Windows platform, where longfi~1.htm might reference longfilename.htm but does not go through the proper ACL checking. If present, “// sequences are allowed.

dotdirok

If present, “// sequences are allowed.

bucket

(Optional) Common to all obj.conf functions.

Example


PathCheck fn=nt-uri-clean

         

See Also

unix-uri-clean

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.

Table 4–27 ntcgicheck Parameters

Parameter  

Description  

extension

The replacement file extension. 

bucket

(Optional) Common to all obj.conf functions.

Example


PathCheck fn=ntcgicheck extension=pl

         

See Also

send-cgi, send-wincgi, send-shellcgi

pcheck-dav

Applicable in PathCheck-class directives.

The pcheck-dav function inserts a DAV-specific service function as the first service function if the Translate:f header is present, DAV is enabled for the request uri, and a corresponding source uri for the request uri exists. During the Service stage, this inserted service function restarts the request if necessary; otherwise, REQ_NOACTION is returned.

Parameters

The following table describes parameters for the pcheck-dav function.

Table 4–28 pcheck-dav Parameters

Parameter  

Description  

bucket

(Optional) Common to all obj.conf functions.

See Also

ntrans-dav, service-dav

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.

Table 4–29 require-auth Parameters

Parameter  

Description  

path

(Optional) Wildcard local file system path on which this function should operate. If no path is provided, the function applies to all paths. 

auth-type

Type of HTTP authorization used, and must match the auth-type from the previous authorization function in AuthTrans. Currently, basic is the only authorization type defined.

realm

String sent to the browser indicating the secure area (or realm) for which a user name and password are requested. 

auth-user

(Optional) Specifies a wildcard list of users who are allowed access. If this parameter is not provided, any user authorized by the authorization function is allowed access. 

auth-group

(Optional) Specifies a wildcard list of groups that are allowed access. 

bucket

(Optional) Common to all obj.conf functions.

Example

PathCheck fn=require-auth auth-type=basic realm="Marketing Plans" 
auth-group=mktg auth-user=(jdoe|johnd|janed)

See Also

basic-auth, basic-ncsa

set-variable

Applicable in all stage directives. The set-variable SAF enables you to change server settings based upon conditional information in a request, and to manipulate variables in parameter blocks by using specific commands. See set-variable.

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 LiveWire application, a servlet in its own namespace, a Sun™ Java System Application Server applogic, and so on.

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.

Table 4–30 set-virtual-index Parameters

Parameter  

Description  

virtual-index

URI of the content generator that acts as an index for the URI the user enters. 

from

(Optional) Comma-separated list of URIs for which this virtual-index is applicable. If from is not specified, the virtual-index always applies.

bucket

(Optional) Common to all obj.conf functions.

Example


# MyLWApp is a LiveWire applicationPathCheck fn=set-virtual-index virtual-index=MyLWApp

         

ssl-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 warning 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 nonexportable 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 file name. 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.

Table 4–31 ssl-check Parameters

Parameter  

Description  

secret-keysize

(Optional) Minimum number of bits required in the secret key. 

bong-file

(Optional) Name of a file (not a URI) to be served if the restriction is not met. 

bucket

(Optional) Common to all obj.conf functions.

ssl-logout

Applicable in PathCheck-class directives.

The ssl-logout function 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.

Table 4–32 ssl-logout Parameters

Parameter  

Description  

bucket

(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.

Table 4–33 unix-uri-clean Parameters

Parameter  

Description  

dotdirok

If present, “// sequences are allowed.

bucket

(Optional) Common to all obj.conf functions.

Example


PathCheck fn=unix-uri-clean

         

See Also

nt-uri-clean