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.

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

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

• timeout

  (Optional) Used by the FTP and connect proxy to determine the value of connection timeout.

If an object contains more than one Service-class function, the first one matching the optional wildcard parameters (method, and query) is executed.

By default, the server sends the requested file to the client by calling the send-file function.

Service method="(GET|HEAD)" 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. For a list of characters that can be used in patterns, see the Oracle iPlanet Web Proxy Server 4.0.14 NSAPI Developer’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.

• append-trailer appends text to the end of an HTML file.

• deny-service prevents access to the requested resource.

• imagemap handles server-side image maps.

• index-common generates a formatted 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.

• match-browser matches specific strings in the User-Agent string supplied by the browser, and then modifies the behavior of Proxy Server based upon the results by setting values for specified variables.

• proxy-retrieve retrieves a document from a remote server and returns it to the client. If this function manages caching if it is enabled.

• query-handler handles the HTML ISINDEX tag.

• remove-dir deletes an empty directory.

• remove-file deletes a file.

• remove-filter removes a refilter from the filter stack.

• rename-file renames a file.

• send-error sends an HTML file to the client in place of a specific HTTP response status.

• 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. This function is applicable only to the Administration Server.

• service-trace services TRACE requests.

• set-variable enables you to change server settings based upon conditional information in a request, and to manipulate variables in parameter blocks by using specific commands.

• shtml_send parses an HTML file for server-parsed HTML commands.

• stats-xml creates a performance report in XML format.

• 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 file name or a URI. The footer therefore, 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.

Examples

Service method=GET fn=add-footer file=
	"footers/footer1.html"
Service method=GET fn=add-footer 
	file="D:/Sun/Server1/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.

Examples

Service method=GET fn=add-header file="headers/header1.html"
Service method=GET fn=add-footer 
	file="D:/Sun/Server61/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 function 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 extra path information appears after the file name in the URL, or if the file cannot be opened for read-only access.

Parameters

The following table describes the parameters specific to the append-trailer function.

Examples

Service 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 method=GET fn=append-trailer timefmt="%D" 
	trailer="<HR>File last updated on: :LASTMOD:"

See Also

add-footer, add-header

deny-service

See deny-service.

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 the URL associated with each area is stored in a mapping file.

Parameters

The imagemap function has no specific parameters.

Example

Service method=(GET|HEAD) fn=imagemap

index-common

Applicable in Service-class directives.

The index-common function generates a formatted 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. The listing might also include a header or readme file.

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

Parameters

The following table describes the parameters specific to the index-common function.

Example

Service fn=index-common 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. 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 index-simple function has no specific parameters.

Example

Service fn=index-simple

See Also

index-common

key-toosmall

Applicable in Service-class directives.

This function 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 key-toosmall function has no specific parameters.

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 size mtime

The name field is the name of the file or directory. It is relative to the directory being indexed. It is URL-encoded, so any character might be represented by %xx, where xx is the hexadecimal representation of the character’s ASCII number.

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 list-dir function has no specific parameters.

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 fmake-dir function has no specific parameters.

Example

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

match-browser

See match-browser.

proxy-retrieve

The proxy-retrieve function retrieves a document from a remote server and returns it to the client. It manages caching if it is enabled. The proxy-retrieve function also enables to you configure the proxy to allow or block arbitrary methods.

Syntax

Service fn=proxy-retrieve
     method=GET|HEAD|POST|INDEX|CONNECT...
    allow|block=<List-of-comma-separated-methods>

Parameters

method lets you specify a retrieval method.

allow configures the proxy to allow specified arbitrary methods.

block configures the proxy to block specified arbitrary methods.

allow takes precedence over block.

Examples

# Normal proxy retrieve
 Service fn=proxy-retrieve
# Proxy retrieve with POST method disabled
Service fn=proxy-retrieve
     method=(POST)
# Proxy retrieve allows methods FOO and BAR to pass through
Service fn=proxy-retrieve
     allow="FOO,BAR"
# Proxy retrieve blocks methods MKCOL,DELETE,LOCK,UNLOCK
Service fn=proxy-retrieve
     block="MKCOL,DELETE,LOCK,UNLOCK"

query-handler

Applicable in Service- and Error-class directives.

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 the path parameter which is specific to the query-handler function.

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 not have any 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 remove-dir function has no specification parameter.

Example

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 remove-file function has no specification parameter.

Example

Service fn="remove-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, you do not have 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 the filter parameters which is specific to 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. The function 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 rename-file function has no specification parameter.

Example

Service fn="rename-file" method="MOVE"

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. The server can therefore present an explanatory 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 the path parameter, which is specific to the send-error function.

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)" fn="send-file"

This directive is invoked if the method of the request is GET, HEAD, or POST.

Parameters

The following table describes the nocache parameter, which is specific to the send-file function.

Example

Service 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) 
	fn=send-file...</Object><Object name="myname">
	Service method=(GET|HEAD) 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.

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 enables you to run CGI applications using the file associations set in Windows. For information about shell CGI programs, see Oracle iPlanet Web Proxy Server 4.0.14 NSAPI Developer’s Guide.

Parameters

The send-shellcgi function has no specification parameter.

Examples

Service 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 Oracle iPlanet Web Proxy Server 4.0.14 NSAPI Developer’s Guide.

Parameters

The send-wincgi function has no specification parameter.

Examples

Service fn=send-wincgi

service-dump

Applicable in Service-class directives.

The service-dump function creates a performance report based on collected performance bucket data. For more information, see Bucket Parameter.

The report is at the following URl:

http://server_id:port/.perf

Parameters

The following table describes the parameter, which is specific to the service-dump function.

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

This function is applicable only to the Administration Server.

Applicable in Service-class directives.

The service-j2ee function services requests made to Java web applications.

Parameters

The service-j2ee function has no specification parameter.

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 typically used to diagnose problems with web proxy servers located between a web client and web server.

Parameters

The service_trace function has no specification parameter.

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 scans an HTML document, for embedded commands. These commands might 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 or libShtml.dll on Windows) is loaded.

Parameters

The following table describes the parameters specifies to the shtml_send function.

Example

Service 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 a NameTrans function to direct requests to the stats-xml function. See the examples below.

The report is generated at the URL:

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

The associated DTD file is located at the URL:

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

Parameters

The stats-xml function.

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 upload-file function.

Example

Service fn=upload-file