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

Service

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 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 (0) in the obj.conf file to disable output stream buffering. For the magnus.conf file, setting UseOutputStreamSize to zero (0) 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, or query) is executed.

For more information about the UseOutputStreamSize, flushTimer, ChunkedRequestBufferSize, and ChunkedRequestTimeout parameters, see Buffered Streams in the Sun Java System Web Server 6.1 SP9 NSAPI Programmer’s Guide. The UseOutputStreamSize, ChunkedRequestBufferSize, and ChunkedRequestTimeout parameters also have equivalent magnus.conf directives. For more information, see “Chunked Encoding” in the chapter “Syntax and Use of magnus.conf” in the Sun Java System Web Server 6.1 SP9 Administrator’s Configuration File Reference. The obj.conf parameters override the magnus.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)" 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 the Sun Java System Web Server 6.1 SP9 NSAPI Programmer’s Guide.

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

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 file name 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.

Table 4–43 add-footer Parameters

Parameter  

Description  

file

(Optional) Path name to the file containing the footer. Specify either file or uri.

By default, the path name is relative. If the path name is absolute, pass the NSIntAbsFilePath parameter as yes.

uri

(Optional) URI pointing to the resource containing the footer. Specify either file or uri.

NSIntAbsFilePath

(Optional) If the file parameter is specified, the NSIntAbsFilePath parameter determines whether the file name is absolute or relative. The default is relative. Set the value to yes to indicate an absolute file path.

type

(Optional) Common to all Service-class functions.

method

(Optional) Common to all Service-class functions.

query

(Optional) Common to all Service-class functions.

UseOutputStreamSize

(Optional) Common to all Service-class functions.

flushTimer

(Optional) Common to all Service-class functions.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions.

bucket

(Optional) Common to all obj.conf functions.

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/WebServer61/server1/footers/footer1.html" 
NSIntAbsFilePath="yes"

See Also

append-trailer, add-header

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 file name or a URI, thus the header can be dynamically generated.

Parameters

The following table describes parameters for the add-header function.

Table 4–44 add-header Parameters

Parameter  

Description  

file

(Optional) Path name to the file containing the header. Specify either file or uri.

By default, the path name is relative. If the path name is absolute, pass the NSIntAbsFilePath parameter as yes.

uri

(Optional) URI pointing to the resource containing the header. Specify either file or uri.

NSIntAbsFilePath

(Optional) If the file parameter is specified, the NSIntAbsFilePath parameter determines whether the file name is absolute or relative. The default is relative. Set the value to yes to indicate an absolute file path.

type

(Optional) Common to all Service-class functions.

method

(Optional) Common to all Service-class functions.

query

(Optional) Common to all Service-class functions.

UseOutputStreamSize

(Optional) Common to all Service-class functions.

flushTimer

(Optional) Common to all Service-class functions.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions.

bucket

(Optional) Common to all obj.conf functions.

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/WebServer61/server1/headers/header1.html" 
NSIntAbsFilePath="yes"

See Also

add-footer, append-trailer

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.

Table 4–45 append-trailer Parameters

Parameter  

Description  

trailer

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) Time format string for :LASTMOD:. If timefmt is not provided, :LASTMOD: will not be replaced with the time.

type

(Optional) Common to all Service-class functions.

method

(Optional) Common to all Service-class functions.

query

(Optional) Common to all Service-class functions.

UseOutputStreamSize

(Optional) Common to all Service-class functions.

flushTimer

(Optional) Common to all Service-class functions.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions.

bucket

(Optional) Common to all obj.conf functions.

Examples

Service type=text/html method=GET fn=append-trailer
 trailer="<hr><img src=/logo.gif> Copyright 1999"

# Add a trailer with the date in the format: MM/DD/YY 
Service type=text/html method=GET fn=append-trailer timefmt="%D" 
trailer="<HR>File last updated on: :LASTMOD:"

See Also

add-footer, add-header

imagemap

Applicable in Service-class directives.

The imagemap function responds to requests for imagemaps. Imagemaps are images that 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.

Table 4–46 imagemap Parameters

Parameter  

Description  

type

(Optional) Common to all Service-class functions.

method

(Optional) Common to all Service-class functions.

query

(Optional) Common to all Service-class functions.

UseOutputStreamSize

(Optional) Common to all Service-class functions.

flushTimer

(Optional) Common to all Service-class functions.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions.

bucket

(Optional) Common to all obj.conf functions.

Example


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 magnus.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, magnus.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, as listed in the following table:

Table 4–47 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.

Table 4–48 index-common Parameters

Parameter  

Description  

header

(Optional) Path (relative to the directory being indexed) and name of a file (HTML or plain text) that is included at the beginning of the directory listing to introduce the contents of the directory. The file is first tried with .html added to the end. If found, it is incorporated near the top of the directory list as HTML. If the file is not found, it is tried without the .html and incorporated as preformatted plain text (bracketed by <PRE> and).

readme

(Optional) Path (relative to the directory being indexed) and name of a file (HTML or plain text) to append to the directory listing. This file might give more information about the contents of the directory, indicate copyrights, authors, or other information. The file is first tried with .html added to the end. If found, it is incorporated at the bottom of the directory list as HTML. If the file is not found, it is tried without the .html and incorporated as preformatted plain text (enclosed by <PRE> and </PRE>).

type

(Optional) Common to all Service-class functions.

method

(Optional) Common to all Service-class functions.

query

(Optional) Common to all Service-class functions.

UseOutputStreamSize

(Optional) Common to all Service-class functions.

flushTimer

(Optional) Common to all Service-class functions.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions.

bucket

(Optional) Common to all obj.conf functions.

Example

Service fn=index-common type=magnus-internal/directory 
method=(GET|HEAD) header=hdr readme=rdme.txt

See Also

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. This function 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.

Table 4–49 index-simple Parameters

Parameter  

Description  

type

(Optional) Common to all Service-class functions.

method

(Optional) Common to all Service-class functions.

query

(Optional) Common to all Service-class functions.

UseOutputStreamSize

(Optional) Common to all Service-class functions.

flushTimer

(Optional) Common to all Service-class functions.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions.

bucket

(Optional) Common to all obj.conf functions.

Example


Service type=magnus-internal/directory fn=index-simple

         

See Also

index-common

key-toosmall

Applicable in Service-class directives.


Note –

This function is provided for backward compatibility only and was deprecated in Sun Java System 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 nonexportable browsers.

Parameters

The following table describes parameters for the key-toosmall function.

Table 4–50 key-toosmall Parameters

Parameter  

Description  

type

(Optional) Common to all Service-class functions.

method

(Optional) Common to all Service-class functions.

query

(Optional) Common to all Service-class functions.

UseOutputStreamSize

(Optional) Common to all Service-class functions.

flushTimer

(Optional) Common to all Service-class functions.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions.

bucket

(Optional) Common to all obj.conf functions.

Example


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

Table 4–51 list-dir Parameters

Parameter  

Description  

type

(Optional) Common to all Service-class functions.

method

(Optional) Common to all Service-class functions.

query

(Optional) Common to all Service-class functions.

UseOutputStreamSize

(Optional) Common to all Service-class functions.

flushTimer

(Optional) Common to all Service-class functions.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions.

bucket

(Optional) Common to all obj.conf functions.

Example


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.

Table 4–52 make-dir Parameters

Parameter  

Description  

type

(Optional) Common to all Service-class functions.

method

(Optional) Common to all Service-class functions.

query

(Optional) Common to all Service-class functions.

UseOutputStreamSize

(Optional) Common to all Service-class functions.

flushTimer

(Optional) Common to all Service-class functions.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions.

bucket

(Optional) Common to all obj.conf functions.

Example


Service fn="make-dir" method="MKDIR"

         

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.

query-handler

Applicable in Service- and Error-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.

Table 4–53 query-handler Parameters

Parameter  

Description  

path

Full path and file name of the CGI program to run. 

type

(Optional) Common to all Service-class functions.

method

(Optional) Common to all Service-class functions.

query

(Optional) Common to all Service-class functions.

UseOutputStreamSize

(Optional) Common to all Service-class functions.

flushTimer

(Optional) Common to all Service-class functions.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions.

bucket

(Optional) Common to all obj.conf functions.

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

Table 4–54 remove-dir Parameters

Parameter  

Description  

type

(Optional) Common to all Service-class functions.

method

(Optional) Common to all Service-class functions.

query

(Optional) Common to all Service-class functions.

UseOutputStreamSize

(Optional) Common to all Service-class functions.

flushTimer

(Optional) Common to all Service-class functions.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions.

bucket

(Optional) Common to all obj.conf functions.

Example


Service fn="remove-dir" method="RMDIR"

         

delete-file

Applicable in Service-class directives.

The delete-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 delete-file when the request method is DELETE.

Parameters

The following table describes parameters for the delete-file function.

Table 4–55 delete-file Parameters

Parameter  

Description  

type

(Optional) Common to all Service-class functions.

method

(Optional) Common to all Service-class functions.

query

(Optional) Common to all Service-class functions.

UseOutputStreamSize

(Optional) Common to all Service-class functions.

flushTimer

(Optional) Common to all Service-class functions.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions.

bucket

(Optional) Common to all obj.conf functions.

Example


Service fn="delete-file" method="DELETE"

         

remove-filter

Applicable in Input-, Output-, Service-, and Error-class directives.

The remove-filter SAF is used to remove a filter from the filter stack. If the filter has been inserted multiple times, only the topmost instance is removed. In general, it is not necessary to remove filters with remove-filter, as they will be removed automatically at the end of the request.

Returns

Returns REQ_PROCEED if the specified filter was removed successfully, or REQ_NOACTION if the specified filter was not part of the filter stack. Any other return value indicates an error.

Parameters

The following table describes parameters for the remove-filter function.

Table 4–56 remove-filter Parameters

Parameter  

Description  

filter

Specifies the name of the filter to remove. 

type

(Optional) Common to all Service-class functions.

method

(Optional) Common to all Service-class functions.

query

(Optional) Common to all Service-class functions.

UseOutputStreamSize

(Optional) Common to all Service-class functions.

flushTimer

(Optional) Common to all Service-class functions.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions.

bucket

(Optional) Common to all obj.conf functions.

Example


Service fn="remove-filter" filter="http-compression"

         

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. This file 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.

Table 4–57 rename-file Parameters

Parameter  

Description  

type

(Optional) Common to all Service-class functions.

method

(Optional) Common to all Service-class functions.

query

(Optional) Common to all Service-class functions.

UseOutputStreamSize

(Optional) Common to all Service-class functions.

flushTimer

(Optional) Common to all Service-class functions.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions.

bucket

(Optional) Common to all obj.conf functions.

Example


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 more information about the CGI environment variables and their NSAPI equivalents, see the Sun Java System Web Server 6.1 SP9 NSAPI Programmer’s Guide.

For more information about CGI, see the Sun Java System Web Server 6.1 SP9 Administrator’s Guide and the Sun Java System Web Server 6.1 SP9 Programmer’s Guide.

There are three ways to change the timing used to flush the CGI buffer:

Parameters

The following table describes parameters for the send-cgi function.

Table 4–58 send-cgi Parameters

Parameter  

Description  

user

(UNIX only) Specifies the name of the user to execute CGI programs as. 

group

(UNIX only) Specifies the name of the group to execute CGI programs as. 

chroot

(UNIX only) Specifies the directory to chroot to before execution begins. 

dir

(UNIX only) Specifies the directory to chdir to after chroot, but before execution begins. 

rlimit_as

(UNIX only) Specifies the maximum CGI program address space in bytes. You can supply both current (soft) and maximum (hard) limits, separated by a comma. The soft limit must be listed first. If only one limit is specified, both limits are set to this value. 

rlimit_core

(UNIX only) Specifies the maximum CGI program core file size. A value of 0 disables writing cores. You can supply both current (soft) and maximum (hard) limits, separated by a comma. The soft limit must be listed first. If only one limit is specified, both limits are set to this value.

rlimit_nofile

(UNIX only) Specifies the maximum number of file descriptors for the CGI program. You can supply both current (soft) and maximum (hard) limits, separated by a comma. The soft limit must be listed first. If only one limit is specified, both limits are set to this value. 

nice

(UNIX only) Accepts an increment that determines the CGI program's priority relative to the server. Typically, the server is running with a nice value of 0 and the nice increment would be between 0 (the CGI program runs at same priority as server) and 19 (the CGI program runs at much lower priority than server). While it is possible to increase the priority of the CGI program above that of the server by specifying a nice increment of -1, this is not recommended.

type

(Optional) Common to all Service-class functions.

method

(Optional) Common to all Service-class functions.

query

(Optional) Common to all Service-class functions.

UseOutputStreamSize

(Optional) Common to all Service-class functions.

flushTimer

(Optional) Common to all Service-class functions.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions.

bucket

(Optional) Common to all obj.conf functions.

Example

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 Java System Web Server 6.1 SP9 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-error

Applicable in Service-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 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.

Table 4–59 send-error Parameters

Parameter  

Description  

path

Specifies the full file system path of an HTML file to send to the client. The file is sent as text/html regardless of its name or actual type. If the file does not exist, the server sends a simple default error page.

type

(Optional) Common to all Service-class functions.

method

(Optional) Common to all Service-class functions.

query

(Optional) Common to all Service-class functions.

UseOutputStreamSize

(Optional) Common to all Service-class functions.

flushTimer

(Optional) Common to all Service-class functions.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions.

bucket

(Optional) Common to all obj.conf functions.

Example


Error fn=send-error code=401 path=/sun/server61/docs/errors/401.html

         

send-file

Applicable in Service-class directives.

The send-file function sends the contents of the requested file to the client. This function 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 that the pattern *~ means “does not match.” For a list of characters that can be used in patterns, see the Sun Java System Web Server 6.1 SP9 NSAPI Programmer’s Guide.

Parameters

The following table describes parameters for the send-file function.

Table 4–60 send-file Parameters

Parameter  

Description  

nocache

(Optional) Prevents the server from caching responses to static file requests. For example, you can specify that files in a particular directory are not to be cached, which is useful for directories where the files change frequently. 

The value you assign to this parameter is ignored. If you do not wish to use this parameter, leave it out. 

type

(Optional) Common to all Service-class functions.

method

(Optional) Common to all Service-class functions.

query

(Optional) Common to all Service-class functions.

UseOutputStreamSize

(Optional) Common to all Service-class functions.

flushTimer

(Optional) Common to all Service-class functions.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions.

bucket

(Optional) Common to all obj.conf functions.

Example


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 the specified portion.

Parameters

The following table describes parameters for the send-range function.

Table 4–61 send-range Parameters

Parameter  

Description  

type

(Optional) Common to all Service-class functions.

method

(Optional) Common to all Service-class functions.

query

(Optional) Common to all Service-class functions.

UseOutputStreamSize

(Optional) Common to all Service-class functions.

flushTimer

(Optional) Common to all Service-class functions.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions.

bucket

(Optional) Common to all obj.conf functions.

Example


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, see the Sun Java System Web Server 6.1 SP9 Administrator’s Guide.

Parameters

The following table describes parameters for the send-shellcgi function.

Table 4–62 send-shellcgi Parameters

Parameter  

Description  

type

(Optional) Common to all Service-class functions.

method

(Optional) Common to all Service-class functions.

query

(Optional) Common to all Service-class functions.

UseOutputStreamSize

(Optional) Common to all Service-class functions.

flushTimer

(Optional) Common to all Service-class functions.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions.

bucket

(Optional) Common to all obj.conf functions

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, see Sun Java System Web Server 6.1 SP9 Administrator’s Guide.

Parameters

The following table describes parameters for the send-wincgi function.

Table 4–63 send-wincgi Parameters

Parameter  

Description  

type

(Optional) Common to all Service-class functions.

method

(Optional) Common to all Service-class functions.

query

(Optional) Common to all Service-class functions.

UseOutputStreamSize

(Optional) Common to all Service-class functions.

flushTimer

(Optional) Common to all Service-class functions.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions.

bucket

(Optional) Common to all obj.conf functions.

Examples


Service fn=send-wincgi
Service type=magnus-internal/cgi fn=send-wincgi

         

service-dav

Applicable in Service-class directives.

The service-dav function services a request to a WebDAV-enabled URI. In response to a request for a WebDAV resource, the service-dav function services the static content and restarts the request with the sourceuri for dynamic content. The sourceuri is identified by the magnus-internal setting. If no sourceuri is defined for dynamic content, an HTTP error message is returned.

Requests to WebDAV resources are authenticated and authorized by the AuthTrans and PathCheck NSAPI stages, respectively. By default, all access to sourceuri are restricted by the PathCheck entry in the dav object.

OPTIONS on a WebDAV-enabled URI are always handled by the default object's service-dav directive. Therefore, the OPTIONS method is not included in the service-dav directive of the dav object.

In response to an OPTIONS request to a WebDAV-enabled URI (or sourceuri), the service-dav function in the default object adds the necessary DAV headers and returns control to the core server, which then services the request.

For more information on access control for WebDAV resources, see the Sun Java System Web Server 6.1 SP9 Administrator’s Guide.

Parameters

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

Table 4–64 service-dav Parameters

Parameter  

Description  

method

(Optional) Common to all Service-class functions.

bucket

(Optional) Common to all obj.conf functions.

Examples

<Object name="default">
.... 
Service method="(OPTIONS|PUT|DELETE|COPY|MOVE|PROPFIND|PROPPATCH|LOCK|UN
LOCK|MKCOL)" fn="service-dav"
</Object>
<Object name="dav"> 
PathCheck fn="check-acl" acl="dav-src" 
Service fn="service-dav" 
method="(PUT|DELETE|COPY|MOVE|PROPFIND|PROPPATCH|LOCK|UNLOCK|MKC
OL)" 
</Object>

See Also

stats-xml

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://server_id:port/.perf

Parameters

The following table describes parameters for the service-dump function.

Table 4–65 service-dump Parameters

Parameter  

Description  

type

Must be perf for this function.

method

(Optional) Common to all Service-class functions.

query

(Optional) Common to all Service-class functions.

UseOutputStreamSize

(Optional) Common to all Service-class functions.

flushTimer

(Optional) Common to all Service-class functions.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions.

bucket

(Optional) Common to all obj.conf functions.

Examples

<Object name=default>
NameTrans fn="assign-name" from="/.perf" name="perf"
...
</Object>

<Object name=perf>
Service fn="service-dump"
</Object>

See Also

stats-xml

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.

Table 4–66 service-j2ee Parameters

Parameter  

Description  

type

(Optional) Common to all Service-class functions.

method

(Optional) Common to all Service-class functions.

query

(Optional) Common to all Service-class functions.

UseOutputStreamSize

(Optional) Common to all Service-class functions.

flushTimer

(Optional) Common to all Service-class functions.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions.

bucket

(Optional) Common to all obj.conf functions.

Examples


<Object name=default>
NameTrans fn="ntrans-j2ee" name="j2ee"
...
</Object>

<Object name=j2ee>
Service fn="service-j2ee"
</Object>

         

See Also

ntrans-j2ee, error-j2ee

service-trace

Applicable in Service-class directives.

The service-trace function services TRACE requests. TRACE requests are used to diagnose problems with web proxy servers located between a web client and web server.

Parameters

The following table describes parameters for the service_trace function.

Table 4–67 service-trace Parameters

Parameter  

Description  

type

(Optional) Common to all Service-class functions.

method

(Optional) Common to all Service-class functions.

UseOutputStreamSize

(Optional) Common to all Service-class functions.

flushTimer

(Optional) Common to all Service-class functions.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions.

query

(Optional) Common to all Service-class functions.

bucket

(Optional) Common to all obj.conf functions.

Example


<Object name="default">
...
Service method="TRACE" fn="service-trace"
...
</Object>

         

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.

shtml_send

Applicable in Service-class directives.

The shtml_send function parses an HTML document and scans 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 plug-in (libShtml.so on UNIX libShtml.dll on Windows) is loaded. See the Sun Java System Web Server 6.1 SP9 Programmer’s Guide for server-parsed HTML commands.

Parameters

The following table describes parameters for the shtml_send function.

Table 4–68 shtml-send Parameters

Parameter  

Description  

ShtmlMaxDepth

Maximum depth of include nesting allowed. The default value is 10.

addCgiInitVars

(UNIX only) If present and equal to yes (the default is no), adds the environment variables defined in the init-cgi SAF to the environment of any command executed through the SHTML exec tag.

type

(Optional) Common to all Service-class functions.

method

(Optional) Common to all Service-class functions.

 

(Optional) Common to all Service-class functions.

UseOutputStreamSize

(Optional) Common to all Service-class functions.

flushTimer

(Optional) Common to all Service-class functions.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions.

bucket

(Optional) Common to all obj.conf functions.

Example


Service type=magnus-internal/shtml_send method=(GET|HEAD) fn=shtml_send

         

stats-xml

Applicable in Service-class directives.

The stats-xml function creates a performance report in XML format. If performance buckets have been defined, this performance report includes them.

However, you do need to initialize this function using the stats-init function in magnus.conf, then use the NameTrans function to direct requests to the stats-xml function. See the examples below.

The report is generated here:

http://server_id:port/stats-xml/iwsstats.xml

The associated DTD file is here:

http://server_id:port/stats-xml/iwsstats.dtd

For more information about the format of the iwsstats.xml file, see the Sun Java System Web Server 6.1 SP9 Performance Tuning, Sizing, and Scaling Guide

Parameters

The following table describes parameters for the stats-xml function.

Table 4–69 stats-xml Parameters

Parameter  

Description  

type

(Optional) Common to all Service-class functions.

method

(Optional) Common to all Service-class functions.

query

(Optional) Common to all Service-class functions.

UseOutputStreamSize

(Optional) Common to all Service-class functions.

flushTimer

(Optional) Common to all Service-class functions.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions.

bucket

(Optional) Common to all obj.conf functions.

Examples

In magnus.conf:


Init fn="stats-init" update-interval="5" virtual-servers="2000" profiling="yes"

         

In obj.conf:


<Object name="default">
...
NameTrans fn="assign-name" from="/stats-xml/*" name="stats-xml"
...
</Object>
...
<Object name="stats-xml">
Service fn="stats-xml"
</Object>

         

See Also

service-dump

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.

Table 4–70 upload-file Parameters

Parameter  

Description  

type

(Optional) Common to all Service-class functions.

method

(Optional) Common to all Service-class functions.

query

(Optional) Common to all Service-class functions.

UseOutputStreamSize

(Optional) Common to all Service-class functions.

flushTimer

(Optional) Common to all Service-class functions.

ChunkedRequestBufferSize

(Optional) Common to all Service-class functions.

ChunkedRequestTimeout

(Optional) Common to all Service-class functions.

bucket

(Optional) Common to all obj.conf functions.

Example


Service fn=upload-file