Service

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.

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 appends a footer
specified by a file name or URL to an HTML file.

add-header prepends a header
specified by a file name or URL to an HTML file.

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

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.

See Also

add-header

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.

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.

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.

See Also

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.

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

Example

See Also

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.

Example

See Also

key-toosmall

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.

Example

list-dir

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.

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.

Examples

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.

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.

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.

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.

Force Sun Java System Web Server to flush its buffer by forcing
spaces into the buffer in the CGI script.

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.

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.

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.

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.

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.

Example

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.