This chapter describes the standard directives and predefined Server Application Functions (SAFs) that are used in the obj.conf file to give instructions to the server.
This chapter describes functions that are part of the core functionality of the Sun Java System Web Proxy Server. It does not include functions that are available only if additional components, such as server-parsed HTML, are enabled.
This chapter covers the following stages:
Each SAF has its own arguments, which are passed to it by a directive in obj.conf. Every SAF is also passed additional arguments that contain information about the request (such as what resource was requested and what kind of client requested it), and any other server variables created or modified by SAFs called by previously invoked directives. Each SAF may examine, modify, or create server variables. Each SAF returns a result code that tells the server whether it succeeded, did nothing, or failed.
For an alphabetical list of predefined SAFs, see Appendix D, List of Predefined SAFs.
The following table lists the SAFs that can be used with each directive.
Table 5–1 Available Server Application Functions (SAFs) per Directive
Directive |
Server Application Functions |
---|---|
The following performance buckets are predefined in the Sun Java System Web Proxy Server:
The default-bucket records statistics for the functions not associated with any user-defined or built-in bucket.
The all-requests bucket records .perf statistics for all NSAPI SAFs, including SAFs in the default-bucket.
You can define additional performance buckets in the magnus.conf file. For more information, see the descriptions of the perf-init and define-perf-bucket functions.
You can measure the performance of any SAF in obj.conf by adding a bucket=bucket-name parameter to the function, for example, bucket=cache-bucket.
To list the performance statistics, use the service-dump Service function.
As an alternative, you can use the stats-xml Service function to generate performance statistics. Use of buckets is optional.
For more information about performance buckets, see Sun Java System Web Proxy Server 4.0.11 Administration Guide.
The Init functions load and initialize server modules and plug-ins, and initialize log files.
Init fn=function-name [parm1=value1]...[parmN=valueN]
function-name identifies the server initialization function to call. These functions shouldn’t be called more than once.
parm=value pairs are values for function-specific parameters. The number of parameters depends on the function you use. The order of the parameters doesn’t matter. The functions of the Init directive listed here are described in detail in the following sections that follow.
define-perf-bucket - Creates a performance bucket.
flex-init - Initializes the flex-log flexible access logging feature
flex-rotate-init - Enables rotation for flexible logs.
host-dns-cache-init - Caches host names of the origin servers.
icp-init - Initializes the ICP feature.
init-clf - Initializes the Common Log File subsystem.
init-filter-order - Controls the position of specific filters within filter stacks.
init-j2ee - Initializes the Java subsystem. This function is applicable only to the Administration Server.
init-proxy - Initializes the networking code used by the proxy.
init-uhome - Loads user home directory information.
init-url-filter - Specifies one or more filter files of URLs. A filter file is a file that contains a list of URLs.
ip-dns-cache-init - Configures DNS caching.
load-modules - Instructs the server to load functions from a shared object file.
load-types - Maps file extensions to MIME types.
nt-console-init - Enables the Windows console, which is the command-line shell that displays standard output and error streams.
pa-init-parent-array - Initializes a parent array member and specifies information about the PAT file for the parent array of which it is a member.
pa-init-proxy-array - Initializes a proxy array member and specifies information about the PAT file for the array of which it is a member.
perf-init - Enables system performance measurement through performance buckets.
pool-init - Configures pooled memory allocation.
register-http-method - Enables you to extend the HTTP protocol by registering new HTTP methods.
stats-init - Enables reporting of performance statistics in XML format.
suppress-request-headers - Configures the proxy server to remove outgoing headers from the request.
thread-pool-init - Configures an additional thread pool.
tune-cache - Enables you to tune the performance of your proxy server’s cache.
tune-proxy - Enables you to tune the performance of your proxy server.You should not change the default settings.
um-define-junction - Defines a URL Mapping that will be enforced by the "URL Mapping" layer.
um-init - Initializes the URL Mapping module.
um-load-parser-config - Loads a parser configuration into memory.
Applicable in Init-class directives.
The define-perf-bucket function creates a performance bucket that you can use to measure the performance of SAFs in obj.conf.
The following table describes parameters for the define-perf-bucket function.
Table 5–2 define-perf-bucket Parameters
Parameter |
Description |
---|---|
name |
Name for the bucket (for example, cgi-bucket) |
Description of what the bucket measures (for example, CGI Stats) |
Init fn=“define-perf-bucket” name=“cgi-bucket” description=“CGI Stats”
Applicable in Init-class directives.
The flex-init function opens the named log file to be used for flexible logging and establishes a record format for it. The log format is recorded in the first line of the log file. You cannot change the log format while the log file is in use by the server.
The flex-log function, which is applicable in AddLog-class directives, writes entries into the log file during the AddLog stage of the request-handling process.
The log file stays open until the server is shut down or restarted, at which time all logs are closed and reopened.
If the server has AddLog-stage directives that call flex-log, the flexible log file must be initialized by flex-init during server initialization.
You may specify multiple log file names in the same flex-init function call. Use multiple AddLog directives with the flex-log function to log transactions to each log file.
The flex-init function may be called more than once. Each new log file name and format is added to the list of log files.
If you move, remove, or change the currently active log file without shutting down or restarting the server, client accesses might not be recorded. To save or backup the currently active log file, rename the file and then restart the server. The server first looks for the log file by name, and if it doesn’t find that name, it creates a new file. The renamed original log file is left for you to use.
For information on rotating log files, see flex-rotate-init.
The flex-init function has three parameters: one that names the log file, one that specifies the format of each record in that file, and one that specifies the logging mode.
The following table describes parameters for the flex-init function.
Table 5–3 flex-init Parameters
Parameter |
Description |
---|---|
The name of the parameter is the name of the log file. The value of the parameter specifies either the full path to the log file or a file name relative to the server’s logs directory. For example: access="/usr/netscape/server4/https-servername/logs/access"mylogfile = "log1" The log file name is a parameter to the flex-log function, which is applicable in AddLog-class directives. |
|
Specifies the size of the global log buffer. The default is 8192. |
|
Specifies the number of buffers for a given log file. The default value is determined by the server. Access log entries can be logged in strict chronological order by using a single buffer per log file. Add buffers-per-file="1" to the Init fn="flex-log-init" line in magnus.conf. This setting ensures that requests are logged in chronological order. This approach results in decreased performance when the server is under heavy load. |
|
format.logFileName |
Specifies the format of each log entry in the log file. For information about the format, see the “More on Log Format” section below. |
no-format-str.access |
Specifies whether to include the format string in the log file. You can choose yes or no. If you are using the Proxy Server's log analyzer, you should include a format string. If you are using a third-party analyzer, you may not want to include a format string in your log file. |
The flex-init function recognizes anything contained between percent signs (%) as the name portion of a name-value pair stored in a parameter block in the server. (The one exception to this rule is the %SYSDATE% component, which delivers the current system date.) %SYSDATE% is formatted using the time format %d/%b/%Y:%H:%M:%S plus the offset from GMT.
Any additional text is treated as literal text, so you can add to the line to make it more readable. Typical components of the formatting parameter are listed in the following flex-init. Components that contain spaces should be bounded by escaped quotation marks (\\”).
If no format parameter is specified for a log file, the common log format is used:
"%Ses->client.ip% - %Req->vars.auth-user% [%SYSDATE%] \\"%Req->reqpb.clf-request%\\" %Req->srvhdrs.clf-status% %Req->srvhdrs.content-length%"
You can now log cookies by logging the Req->headers.cookie.name component.
In the following table, the components that are enclosed in escaped double quotation marks (\\”) are the ones that could potentially resolve to values that contains spaces.
Table 5–4 Typical Components of flex-init Formatting
Flex-log Option |
Component |
---|---|
Client host name (unless iponly is specified in flex-log or DNS name is not available) or IP address |
%Ses->client.ip% |
Client DNS name |
%Ses->client.dns% |
System date |
%SYSDATE% |
Status |
%Req->srvhdrs.clf-status% |
Response content length |
%Req->srvhdrs.content-length% |
Response content type |
%Req->srvhdrs.content-type% |
Referer header |
\\"%Req->headers.referer%\\" |
User-agent header |
\\"%Req->headers.user-agent%\\" |
HTTP method |
%Req->reqpb.method% |
HTTP URI |
%Req->reqpb.uri% |
HTTP query string |
%Req->reqpb.query% |
HTTP protocol version |
%Req->reqpb.protocol% |
DNS Time |
%Req->vars.xfer-time-dns% Time required for Proxy to complete a DNS lookup and to attempt to connect to the server. |
Connect Wait Time |
%Req->vars.xfer-time-cwait% Time required for Proxy to establish a TCP/IP connection to the server and send a request. |
Full Wait Time |
%Req->vars.xfer-time-fwait% Time that elapses between the moment the proxy establishes a connection to a server and the moment that it receives its last packet of response. |
Initial Wait Time |
%Req->vars.xfer-time-iwait% Time for Proxy to receive the first packet of response from the server after the proxy sends its request. |
Accept header |
%Req->headers.accept% |
Date header |
%Req->headers.date% |
If-Modified-Since header |
%Req->headers.if-modified-since% |
Authorization header |
%Req->headers.authorization% |
Any header value |
%Req->headers.headername% |
Name of authorized user |
%Req->vars.auth-user% |
Value of a cookie |
%Req->headers.cookie.name% |
Value of any variable in Req->vars |
%Req->vars.varname% |
Duration |
%duration% Time in microseconds that the server spent handling the request. Statistics must be enabled for the server instance before %duration% can be used. For information about enabling statistics, see the Sun Java System Web Proxy Server 4.0.11 Administration Guide. |
The first example below initializes flexible logging into the file <install-root><instance-directory>/logs/access.
This example shows the default format, which corresponds to the Common Log Format (CLF).
The first six elements of any log should always be in this format, because a number of log analyzers expect matching output.
Init fn="flex-init" access="$accesslog" format.access="%Ses->client.ip% - %Req->vars.auth-user% [%SYSDATE%] ’%Req->reqpb.clf-request%’ %Req->srvhdrs.clf-status% %Req->srvhdrs.content-length%" |
This example will record the following items:
IP or host name, followed by the three characters “ - ”
User name, followed by the two characters “ [”
System date, followed by the two characters “] ”
Full HTTP request in quotes, followed by a single space
HTTP result status in quotes, followed by a single space
Content length
The second example initializes flexible logging into the file <install-root><instance-directory>/logs/extended.
Init fn=flex-init extended="<install-root><instance-directory> /logs/extended" format.extended="%Ses->client.ip% - %Req->vars.auth-user % [%SYSDATE%] \\"%Req->reqpb.clf-request%\\" %Req->srvhdrs.clf-status% %Req->srvhdrs.content-length% %Req->headers.referer% \\"%Req->headers.user-agent%\\" %Req->reqpb.method% %Req->reqpb.uri% %Req->reqpb.query% %Req->reqpb.protocol%" |
The third example shows how logging can be tuned to prevent request handling threads from making blocking calls when writing to log files Instead you can delegate these calls to the log flush thread.
Doubling the default size of the buffer-size and num-buffers parameters and lowering the value of the LogFlushInterval directive in magnus.conf to 4 seconds frees the request-handling threads to quickly write the log data.
Init fn=flex-init buffer-size=16384 num-buffers=2000 access=" /<install-root><instance-directory>/logs/access" format.access="%Ses->client.ip% - %Req->vars.auth-user% [%SYSDATE%] \\"%Req->reqpb.clf-request%\\" %Req->srvhdrs.clf-status% %Req->srvhdrs.content-length%" |
Applicable in Init-class directives.
The flex-rotate-init function configures log rotation for all log files on the server, including error logs and the common-log, flex-log, and record-useragent AddLog SAFs. Call this function in the Init section of magnus.conf before calling flex-init. The flex-rotate-init function enables you to specify a time interval for rotating log files. At the specified time interval, the server moves the log file to a file whose name indicates the time of the move. The log functions in the AddLog stage in obj.conf then start logging entries in a new log file. The server does not need to be shut down while the log files are being rotated.
The server keeps all rotated log files so clean them up as necessary to free disk space.
By default, log rotation is disabled.
The following table describes parameters for the flex-rotate-init function.
Table 5–5 flex-rotate-init Parameters
Parameter |
Description |
---|---|
Indicates the time to start rotation. This value is a four-digit string indicating the time in 24-hour format. For example, 0900 indicates 9 a.m., while 1800 indicates 9 p.m. |
|
Indicates the number of minutes to elapse between each log rotation. |
|
(Optional) Determines whether common-log, flex-log, and record-useragent logs are rotated (AddLog SAFs). Values are yes (the default), and no. |
|
(Optional) Determines whether error logs are rotated. Values are yes (the default), and no. |
|
(Optional) Specifies the file name of a user-supplied program to execute following log file rotation. The program is passed the post-rotation name of the rotated log file as its parameter. |
This example enables log rotation, starting at midnight and occurring every hour.
Init fn=flex-rotate-init rotate-start=2400 rotate-interval=60 |
Applicable in Init-class directives.
The host-dns-cache-init function is used to cache host names of the origin servers. If DNS lookup are caches, then when the server gets a request from the client servers, it caches the server’s host name information.
The following table describes parameters for the dns-cache-init function.
Table 5–6 host-dns-cache-init parameters
Parameter |
Description |
---|---|
(Optional) Specifies how many entries are contained in the cache. Acceptable values are 32 to 32768. The default value is 1024. |
|
(Optional) Specifies how long in seconds before a cache entry should expire. Acceptable values are 1 to 31536000 (1 year). The default value is 1200 seconds (20 minutes). |
|
negative-dns-cache |
Enables or disables the caching of invalid host names. The default value is yes. |
Init fn=“host-dns-cache-init” cache-size=“2140” expire=“600”
Applicable in Init-class directives.
The icp-init function enables and initializes ICP. ICP (Internet Cache Protocol) is an object location protocol that enables caches to communicate with one another. Caches can use ICP to send queries and replies about the existence of cached URLs and about the best locations from which to retrieve those URLs.
Init fn=icp-init config_file=file name status=on|off
The following table describes parameters for the icp-init function.
Table 5–7 icp-init parameters
Init fn=icp-init config_file=icp.conf status=on |
Applicable in Init-class directives.
The init-clf function opens the named log files to be used for common logging. The common-log function writes entries into the log files during the AddLog stage of the request-handling process. The log files stay open until the server is shut down, at which time the log files are closed or the server is restarted. If the server is restarted the log files are closed and reopened.
If the server has an AddLog-stage directive that calls common-log, common log files must be initialized by init-clf during initialization.
If this function is called more than once, the new call will replace log file names from all previous calls.
If you move, remove, or change the log file without shutting down or restarting the server, client accesses might not be recorded. To save or backup a log file, rename the file and for UNIX, send the -HUP signal. Then restart the server. The server first looks for the log file by name. If the server does not find the file, it creates a new one (the renamed original log file is left for you to use).
For information on rotating log files, see flex-rotate-init.
The following table describes the parameters for the init-clf function.
Table 5–8 init-clf Parameters
Parameter |
Description |
---|---|
The name of the parameter is the name of the log file. The value of the parameter specifies either the full path to the log file or a file name relative to the server’s logs directory. For example:Ini access="/usr/netscape/server4/https-servername/logs/access"mylogfile = "log1" The log file name is a parameter to the common-log function, which is applicable in AddLog-class directives. |
Init fn=init-clf access=/usr/netscape/server4/https-boots/logs/access Init fn=init-clf templog=/tmp/mytemplog templog2=/tmp/mytemplog2 |
Applicable in Init-class directives.
The init-filter-order Init SAF can be used to control the position of specific filters within filter stacks. For example, init-filter-order can be used to ensure that a filter that converts outgoing XML to XHTML is inserted above a filter that converts outgoing XHTML to HTML.
Filters that appear higher in the filter stack are given an earlier opportunity to process outgoing data. Filters that appear lower in the filter stack are given an earlier opportunity to process incoming data.
Filter developers use the filter_create function to define the filter’s position in the filter stack. For example, filters that translate content from XML to HTML are placed higher in the filter stack than filters that compress data for transmission. init-filter-order can be used to override the position defined by the filter developer.
When two or more filters are defined to occupy the same position in the filter stack, filters that were inserted later will appear higher than filters that were inserted earlier. The order of Input fn="insert-filter" and Output fn="insert-filter" directives in obj.conf becomes important. For example, consider two filters, xhtml-to-html and xml-to-xhtml, which convert XHTML to HTML and XML to XHTML, respectively. Because both filters transform data from one format to another, they may be defined to occupy the same position in the filter stack. To transform XML documents to XHTML and then to HTML before sending the data to the client, Output fn="insert-filter" directives in obj.conf would appear in the following order:
Output fn="insert-filter" filter="xhtml-to-html" Output fn="insert-filter" filter="xml-to-xhtml"
Administrators should use the order of Input fn="insert-filter" and Output fn="insert-filter" directives in obj.conf to control the position of filters in the filter stack. init-filter-order should only be used to address specific filter interoperability problems.
The load-module SAFs that create the filters should be called before init-filter-order attempts to order them.
The following table describes the parameter for the init-filter-order function.
Table 5–9 init-filter-order Parameters
Parameter |
Description |
---|---|
Comma-separated list of filters in the order they should appear within a filter stack, listed from highest to lowest. |
Init fn="init-filter-order" filters="xml-to-xhtml,xhtml-to-html, http-compression" |
This function is applicable only to the Administration Server in Init-class directives..
The init-j2ee function initializes the Java subsystem.
This function requires a LateInit=yes parameter.
Init fn="load-modules" shlib="install_dir/lib/libj2eeplugin.so" funcs="init-j2ee,ntrans-j2ee,service-j2ee,error-j2ee" shlib_flags="(global|now)" Init fn="init-j2ee" LateInit=yes |
Applicable in Init-class directives.
The init-proxy function initializes the Proxy Server’ s internal settings. This function is called during the initialization of the Proxy Server, but it should also be specified in the obj.conf to ensure that the values are initialized properly.
Init fn=init-proxy timeout=<seconds> timeout-2=seconds
The following table describes parameters for the init-proxy function.
Table 5–10 init-proxy Parameters
Parameter |
Description |
---|---|
timeout |
The number of seconds of delay allowed between consecutive network packets received from the remote server. If the delay exceeds the timeout, the connection is dropped. The default is 120 seconds (2 minutes). This value is not the maximum time allowed for an entire transaction, but the delay between the packets. For example, the entire transaction can last 15 minutes, as long as at least one packet of data is received before each timeout period. |
timeout-2 (timeout after interrupt) |
The timeout after interrupt value indicates how much time the Proxy Server has to continue writing a cache file after a client has aborted the transaction. In other words, if the Proxy Server has almost finished caching a document and the client aborts the connection, the server can continue caching the document until it reaches the timeout after interrupt value. The highest recommended timeout after interrupt value is 5 minutes. The default value is 15 seconds. |
Init fn=init-proxy timeout=120 |
Applicable in Init-class directives.
UNIX Only. The init-uhome function loads information about the system’s user home directories into internal hash tables. This process increases memory usage slightly, but improves performance for servers that have significant traffic to home directories.
The following table describes the parameter for the init-uhome function.
Table 5–11 init-uhome parameters
Parameter |
Description |
---|---|
(Optional) Specifies the full file system path to a file other than /etc/passwd. If file name is not provided, the default UNIX path (/etc/passwd) is used. |
Init fn=init-uhome Init fn=init-uhome pwfile=/etc/passwd-http |
Applicable in Init-class directives.
The init-url-filter function specifies one or more filter files of URLs. A filter file is a file that contains a list of URLs.
You can pass one or more parameters to this SAF and associate each parameter to a filter file of URLs. These parameter names may be used later in url-filter SAF to either allow or deny these filter files of URLs.
PathCheck fn="init-url-filter" filt1="/path/to/filter/file1" filt2="/path/to/filter/file2" filt3="/path/to/filter/file3" etc... |
Applicable in Init-class directives.
The ip-dns-cache-init function specifies that DNS lookups should be cached when DNS lookups are enabled. If DNS lookups are cached, then when the server gets a client’s host name information, it stores that information in the DNS cache. If the server requires information about the client in the future, the information is available in the DNS cache.
You may specify the size of the DNS cache and the time it takes before a cache entry becomes invalid. The DNS cache can contain 32 to 32768 entries. The default value is 1024 entries. Values for the time before a cache entry expires, specified in seconds can range from 1 second to 1 year. The default value is 1200 seconds (20 minutes).
The following table describes parameters for the ip-dns-cache-init function.
Table 5–12 ip-dns-cache-init Parameters
Parameter |
Description |
---|---|
(Optional) Specifies how many entries are contained in the cache. Acceptable values are 32 to 32768. The default value is 1024. |
|
(Optional) Specifies the remaining time in seconds before a cache entry expires. Acceptable values are 1 to 31536000 (1 year); the default is 1200 seconds (20 minutes). |
Init fn=“ip-dns-cache-init” cache-size=“2140” expire=“600”
Applicable in Init-class directives.
The load-modules function loads a shared library or dynamic-link library (DLL) into the server code. Specified functions from the library can then be executed from any subsequent directives. Use this function to load new plug-ins or SAFs.
If you define your own SAFs, load them by using the load-modules function and specifying the shared library or DLL to load.
The following table describes parameters for the load-modules function.
Table 5–13 load-modules Parameters
Parameter |
Description |
---|---|
Specifies either the full path to the shared library or DLL, or a file name relative to the server configuration directory. |
|
Comma-separated list of the names of the functions in the shared library or DLL to be made available for use by other Init directives or by Service directives in obj.conf. The list should not contain any spaces. The dash (-) character may be used in place of the underscore (_) character in function names. |
|
(Optional) Specifies which threading model to use. no causes the routines in the library to use user-level threading. yes enables kernel-level threading. The default is yes. |
|
Name of a custom thread pool, as specified in thread-pool-init. |
Init fn=load-modules shlib="C:/mysrvfns/corpfns.dll" funcs="moveit" Init fn=load-modules shlib="/mysrvfns/corpfns.so" funcs="myinit,myservice"Init fn=myinit |
Applicable in Init-class directives.
The load-types function scans a file that provide map filename extensions to MIME types. MIME types are essential to enable network navigation software to distinguish between file types. See Chapter 6, MIME Types for more information.
Calling this function is crucial if you use Web Proxy Server Manager online forms or the FTP proxying capability.
Init fn=load-types mime-types="mime.types"
This function loads the MIME type the mime.types file from the configuration directory, that contains the same directory magnus.conf and obj.conf. This function call is mandatory and in practice is always as shown in the syntax.
The following table describes the parameter for the load-types function.
Table 5–14 load-types Parameters
Parameter |
Description |
---|---|
mime-types |
Specifies either the full path to the global MIME types file or a filename relative to the server configuration directory. The proxy server comes with a default file called mime.types. |
Optional parameter to a file with the same format as the global MIME types file. This parameter is used to maintain types that are applicable only to your server. |
Example
Init fn=load-types mime-types=mime.types Init fn=load-types mime-types=/tp/mime.types \\ local-types=local.types
Applicable in Init-class directives.
The nt-console-init function enables the Windows console, which is the command-line shell that displays standard output and error streams.
The following table describes the parameter for the nt-console-init function.
Table 5–15 nt-console-init Parameters
Parameter |
Description |
---|---|
Directs error messages to the Windows console. The required and only value is console. |
|
Directs output to the Windows console. The required and only value is console. |
Init fn="nt-console-init" stdout=console stderr=console |
Applicable in Init-class directives.
The pa-init-parent-array function initializes a parent array member and specifies information about the PAT file for the parent array of which it is a member.
The load modules directive should come before the pa-init-proxy-array function in the obj.conf file.
Init fn=pa-init-parent-array set-status-fn=pa-set-member-status poll="yes|no" file="absolute filename" pollhost="host name" pollport="port number" pollhdrs="absolute filename" pollurl="url" status="on|off"
The following table describes the parameter for the pa-init-parent-array function.
Table 5–16 pa-init-parent-array Parameters
The following example indicates that the member should not poll for the PAT file. This example would apply to a master proxy.
Init fn=pa-init-parent-array poll="no" file="c:/netscape/server/bin/proxy/pa1.pat"
The following example specifies that the member should poll for a PAT file. This member is not the master proxy.
Init fn=pa-init-parent-array poll="yes" file="c:/netscape/server/bin/proxy/pa2.pat" pollhost="proxy1" pollport="8080" pollhdrs="c:/netscape/server/proxy-name/parray/pa2.hdr" status="on" set-status-fn=set-member-status pollurl="/pat"
Applicable in Init-class directives.
The pa-init-proxy-array function initializes a proxy array member and specifies information about the PAT file for the array of which it is a member.
The load modules directive should come before the pa-init-proxy-array function in the obj.conf file.
Init fn=pa-init-proxy-array set-status-fn=pa-set-member-status poll="yes|no" file="absolute filename" pollhost="host name" pollport="port number" pollhdrs="absolute filename" pollurl="url" status="on|off"
The following table describes the parameter for the pa-init-proxy-array function.
Table 5–17 pa-init-proxy-array Parameters
Example
The following example tells the member not to poll for the PAT file. This example would apply to a master proxy.
Init fn=pa-init-proxy-array poll="no" file="c:/netscape/server/bin/proxy/pa1.pat"
The following example specifies that the member should poll for a PAT file. This member is not the master proxy.
Init fn=pa-init-proxy-array poll="yes" file="c:/netscape/server/bin/proxy/pa2.pat" pollhost="proxy1" pollport="8080" pollhdrs="c:/netscape/server/proxy-name/parray/pa2.hdr" status="on" set-status-fn=set-member-status pollurl="/pat"
Applicable in Init-class directives.
The perf-init function enables system performance measurement through performance buckets.
The following table describes the parameter for the perf-init function.
Table 5–18 perf-init parameters
Parameter |
Description |
---|---|
Flag to disable the use of system performance measurement via performance buckets. Should have a value of true or false. Default value is true. |
Init fn=perf-init disable=false |
Applicable in Init-class directives.
The pool-init function changes the default values of pooled memory settings. The size of the free block list may be changed or pooled memory may be entirely disabled.
Memory allocation pools enable the server to run significantly faster. If you are programming with the NSAPI, note that MALLOC, REALLOC, CALLOC, STRDUP, and FREE work slightly differently if pooled memory is disabled. If pooling is enabled, the server automatically cleans up all memory allocated by these routines when each request completes. In most cases, this process will improve performance and prevent memory leaks. If pooling is disabled, all memory is global and no clean-up is required.
For persistent memory allocation, add the prefix PERM_ to the name of each routine (PERM_MALLOC, PERM_REALLOC, PERM_CALLOC, PERM_STRDUP, and PERM_FREE).
Any memory you allocate from Init-class functions will be allocated as persistent memory even if you use MALLOC. The server cleans up only the memory that is allocated while processing a request. Because Init-class functions are run before processing any requests, their memory is allocated globally.
The following table describes the parameter for the pool-init function.
Table 5–19 pool-init Parameters
Parameter |
Description |
---|---|
(Optional) Maximum size in bytes of free block list. Can not be greater than 1048576. |
|
disable |
(Optional) Flag to disable the use of pooled memory. Must have a value of true or false. Default value is false. |
Init fn=pool-init disable=true |
Applicable in Init-class directives.
This function enables you to extend the HTTP protocol by registering new HTTP methods. You do not need to register the default HTTP methods.
Upon accepting a connection, the server checks whether the method it received is registered. If the server does not recognize the method, it returns a “501 Method Not Implemented” error message.
The following table describes the parameter for the register-http-method function.
Table 5–20 register-http-method Parameters
Parameter |
Description |
---|---|
Comma-separated list of the names of the methods you are registering. |
The following example shows the use of register-http-method and a Service function for one of the methods.
Init fn="register-http-method" methods="MY_METHOD1,MY_METHOD2" Service fn="MyHandler" method="MY_METHOD1" |
Applicable in Init-class directives.
The stats-init function enables reporting of performance statistics in XML format. The report is generated by the stats-xml function in obj.conf.
The following table describes parameters for the stats-init function.
Table 5–21 stats-init parameters
Parameter |
Description |
---|---|
Period in seconds between statistics updates within the server. Set higher for better performance, or lower for more frequent updates. The minimum value is 1. The default value is 5. |
|
Enables NSAPI performance profiling using buckets if set to yes. This profiling can also be enabled through the perf-init Init SAF. The default is no, which results in slightly better server performance. |
Init fn="stats-init" update-interval="5" virtual-servers="2000" profiling="yes" |
Applicable in Init-class and ObjectType-class directives.
If you specify this function at the Init stage, it applies to the entire proxy for all the requests.
If you specify this function at the ObjectType stage, you can control suppressing outgoing headers functionality for different objects in the obj.conf file.
The suppress-request-headers function configures the proxy server to remove outgoing headers from the request. This function accepts one or more hdr parameters through which you can specify multiple headers that you want to suppress.
For example, you might want to prevent the from and Cookie headers from being sent because the information reveals the user’s credentials.
The following table describes the parameter for the suppress-request-headers function.
Table 5–22 suppress-request-headers Parameters
Parameter |
Description |
---|---|
hdr |
Name of the HTTP request header to be suppressed. |
Init fn="suppress-request-headers" hdr="from" hdr="Cookie" |
Applicable in Init-class directives.
The thread-pool-init function creates a new pool of user threads. A pool must be declared before it is used. To specify that a plug-in should use the new pool, specify the pool parameter when loading the plug-in with the Init-class function load-modules.
You can create a custom thread pool if a plug-in is not thread-aware. You can set the maximum number of threads in the pool to 1.
The older parameter NativeThread=yes always engages one default native pool, called NativePool.
The native pool on UNIX is normally not engaged, because all threads are OS-level threads. Using native pools on UNIX might introduce a small performance overhead because the pools require an additional context switch. However, the pool can be used to localize the jvm.stickyAttach effect or for other purposes, such as resource control and management, or to emulate single-threaded behavior for plug-ins.
On Windows, the default native pool is always being used. The Sun Java System Web Proxy Server uses fibers (user-scheduled threads) for initial request processing. Using custom additional pools on Windows introduces no additional overhead.
In addition, native thread pool parameters can be added to the magnus.conf file for convenience.
The following table describes the Parameters for the thread-pool-init function.
Table 5–23 thread-pool-init Parameters
Parameter |
Description |
---|---|
name |
Name of the thread pool. |
Maximum number of threads in the pool. |
|
Minimum number of threads in the pool. |
|
Size of the queue for the pool. If all threads in the pool are busy, further request-handling threads that require a thread from the pool wait in the pool queue. The number of request-handling threads that can wait in the queue is limited by the queue size. If the queue is full, the next request-handling thread that tries to access/denied the queue is therefore, the request is turned down, and the request-handling thread remains free to handle another request instead of becoming locked up in the queue. |
|
Stack size of each thread in the native (kernel) thread pool. |
Init fn=thread-pool-init name="my-custom-pool" maxthreads=5 minthreads=1 queuesize=200Init fn=load-modules shlib="C:/mydir/myplugin.dll" funcs="tracker" pool="my-custom-pool" |
Applicable in Init-class directives.
The tune-cache function enables you to tune the performance of your proxy server’s cache. Do not change the default settings unless directed to do so by Sun Technical Support.
Init fn=tune-cache byte-ranges
The following table describes the parameter for the tune-cache function.
Table 5–24 tune-cache Parameters
Parameter |
Description |
---|---|
byte-ranges |
Determines whether the proxy is allowed to generate byte-range responses from the cache. By default, this feature is disabled. |
Init fn=tune-cache byte-ranges=off |
Applicable in Init-class directives.
The tune-proxy function enables you to tune the performance of your proxy server.You should not change the default settings.
Init fn=tune-proxy ftp-listing-width=number
The following table describes the parameter for the tune-proxy function.
Table 5–25 tune-cache parameters
Parameter |
Description |
---|---|
Increasing the width of FTP listings allows longer file names and thus reduces file name truncation. The default width is 80 characters. |
Init fn=tune-proxy ftp-listing-width=80 |
Applicable in Init-class directive.
The um-define-junction function defines a URL Mapping or junction which will be enforced by the URL Mapping layer.
Junction definitions take two forms: junction definitions and junction mappings. A junction definition defines the overall settings for a junction. A junction mapping defines additional URL mappings that also apply to a given junction definition. They inherit all settings of the parent junction's definition, but they allow other URL mappings that are appropriate to a given junction to be associated with it. This becomes important for cookie management, as cookies from one junction will not be passed to another one.
Init fn="um-define-junction"
The following table describe parameters for the um-define-junction function.
The following parameters apply to both junction definitions and junction mappings.
Table 5–26 um-define-junction parameters
Parameter |
Description |
---|---|
jct-name |
The name of the junction. In the case of junction definitions, this name must be unique. In the case of junction mappings, this must be the name of an existing junction. |
fe-uri-prefix |
The front-end URI prefix that is to be associated with this junction definition or mapping. It must begin and end with a '/' character. |
be-url-prefix |
The back-end URL prefix that is to be associated with this junction definition or mapping. This is the back-end URL that will connect to the back-end application server. It must be of the form http[s]://*/*. |
The following parameters apply only to junction mappings.
Table 5–27 Junction mapping parameters
Parameter |
Description |
---|---|
junction-mapping |
If this is set to yes, then this definition is taken to be a junction mapping. |
The following parameters apply only to junction definitions.
Table 5–28 Junction definition parameters
Parameter |
Description |
---|---|
parser-config |
Specifies the parser configuration used for this junction. If not specified, the default parser configuration (the first parser configuration listed in obj.conf) is used. |
passthru-cookies |
Specifies a comma-separated list of cookie names is passed through to the junction without translation. This parameter is a junction-specific version of the global-passthru-cookies parameter of the load-modules function. |
has-javascript |
If set to yes, then JavaScript rewriting is enabled for all JavaScript content. Otherwise, JavaScript is passed without rewriting. |
onload-handler |
If set to yes, then a special bit of code is inserted into each request to this junction, which will set a cookie specifying the name of the junction. This cookie's name is defined in the jct-cookie-name of the load-modules function. By default, the cookie's name is um_jct. |
base-tag-handler |
If set to yes, then <base> tags receives special handling. Use care when combining this parameter with has-javascript, as the parser may mistake a static string value for a relative URL. Default value is no. |
rewrite-events |
If set to no, then event attributes within HTML tags are not rewritten. Default value is yes. This parameter operates independently of has-javascript, but is only relevant if has-javascript is set to no. |
redirect-without-trailing-slash |
If set to yes, then requests that match fe-uri-prefix without the trailing slash is immediately redirected to fe-uri-prefix with the trailing slash. |
add-headers |
Specifies a static list of headers to be added to all requests within this junction. |
lookup-equiv-hosts |
Equivalent host are strings that appear in the host part of a URL, which also represent the back-end server. By default, a new junction adds the back-end server's IP addresses to this list. Setting this option to 'no' prevents this behavior. |
add-equiv-hosts |
Specifies a comma-delimited list of additional host names (and/or IP addresses) that are considered to be equivalent to this junction's host name. The host part of be-url-prefix is implicit, and does not need to be added. |
output-buffer-size |
Enables (or disables) output buffering. The proxy server employs HTTP chunking to send data to the client when it does not know the size of the content to be sent. Because the URL Mapping layer can send data in many small chunks, this can create a lot of CPU overhead on the proxy server machine. To alleviate this, URL Mapping offers its own output buffering so that data is sent to the client in fewer, larger chunks. To enable this, set output-buffer-size to a nonzero value. |
references-other-jcts |
If set to yes, the other junctions are searched when trying to rewrite URLs for this junction. Use care when employing this option, as searching other junctions can be time-consuming in a configuration that contains many junctions. |
use-template |
If set to yes, and name is not set, then requests that match this junction is also assigned an object name that matches the junction's name. This allows additional directives to be executed only for this junction. |
name |
If set, then this overrides the object name for this junction. It implies use-template=yes. |
Junction definition:
Init fn="um-define-junction" jct-name="myJunction" fe-uri-prefix="/myj/" be-url-prefix="http://appserver.company.com/someApplication/" |
Junction mapping:
Init fn="um-define-junction" jct-name="myJunction" fe-uri-prefix="/someApplication/cgi-bin/" be-url-prefix="http://appserver.company.com/someApplication/cgi-bin" junction-mapping="yes" |
Applicable in Init-class directives.
This parameter is mandatory. It must appear only once in the obj.conf file and before other URL Mapping-related directives.
The following describes parameters for the um-init function:
Table 5–29 um-init parameters
Parameter |
Description |
---|---|
global-passthru-cookies |
Specifies a comma-delimited list of cookies that is always passed through to the back-end applications. If a cookie's name is followed by a '|' character, then the cookie's name is changed to the name following the '|' character. |
jct-cookie-name |
Sets the name of the cookie that stores the last-used back-end URL's name. By default, this parameter is set to um_jct. |
jct-cookie-prefix |
When cookies are set by applications within defined URL mappings, their names are prefixed by this string, followed by the name of the URL Mapping, followed by a '_' character. This setting tells the URL Mapping which cookies to pass to the back-end server on a given request. |
jct-cookie-domain |
If specified, the URL Mapping cookie (specified in jct-cookie-name) is set in this domain. Otherwise, the domain for the cookie is not set. You do not have to use this parameter. |
default-output-buffer-size |
Sets the default output buffer size for URL Mappings that does not explicitly set output-buffer-size (See output-buffer-size in Table 5–28). If not specified, then output buffering is disabled by default. |
Init fn=um-init |
Applicable in Init-class directive.
Parser configurations are text files that contain the names of tag attributes and tag events whose URLs are to be rewritten. It also contains strings that are considered to be illegal in URLs.
Each line of the parser configuration starts with either a tag name, or the string **illegal.
If the line starts with a tag name, the rest of the line is a space-separated list of attribute names that will be searched for URLs.
If the tag name is prefixed with a '*' character, then the rest of the line is a space-separated list of the event names that will be searched for URLs.
If an attribute or event name is prefixed with a '*' character, then the URL Mapping feature always attempts to rewrite URLs within that attribute or event as absolute URLs. Otherwise, the URLs are rewritten in the same form that they were specified (relative, server-relative, or absolute).
If the first word of the line is the string **illegal, then the rest of the line contains a space-separated list of strings that, if they are contained within a URL, are considered to be illegal. If a URL containing any of these strings is encountered, then the URL is replaced with the string ***ILLEGAL_URL***.
All strings in this file are case-insensitive. Any lines that begin with a '#' character are considered to be comments, and are ignored. Blank lines are ignored.
Init fn="um-load-parser-config"
The following table describes parameters in the um-load-parser-config function.
Table 5–30 um-load-parser-config parameters
Parameter |
Description |
---|---|
file |
Specifies the location of the parser configuration file. |
config-name |
Specifies the name that is associated with this parser configuration. This setting is only necessary if you have multiple parser configurations in your obj.conf. If not specified, the configuration is assigned a name equal to the value of the file. |
Init fn="um-load-parser-config" file="/opt/SUNWproxy/proxy-server1/conf/proxy.cfg" |
The following table lists the Init functions available in the obj.conf file:
Table 5–31 Init Functions
Function/Parameter |
Allowed Values |
Default Value |
Description |
---|---|---|---|
Creates a performance bucket. You can use this parameter to measure the performance of SAFs in obj.conf. This function only works if the perf-init function is enabled. |
|||
A name for the bucket, for example, cgi-bucket. |
|||
A description of what the bucket measures, for example, CGI Stats. |
|||
Configures DNS caching. |
|||
32 to 32768 (32K) |
1024 |
(optional) Specifies how many entries are contained in the cache. |
|
1 to 31536000 seconds (1 year) |
1200 seconds (20 minutes) |
(optional) Specifies how long in seconds before a cache entry expires. |
|
Initializes the flexible logging system. |
|||
logFileName |
A path or file name |
The full path to the log file or a file name relative to the server’s logs directory. In this example, the log file name is access and the path is /logdir/access: access="/logdir/access" |
|
Specifies the format of each log entry in the log file. |
|||
true, on, yes, or 1;false, off, no, or 0 |
Turns on relaxed logging, which skips logging components that normally block static page acceleration if static page acceleration is enabled. |
||
Number of bytes |
8192 |
Specifies the size of the global log buffer. |
|
The lower bound is 1. Files must contain at least one buffer. The upper bound is dictated by the number of buffers that exist. The upper bound on the number of buffers that exist can be defined by the num-buffers parameter. |
Determined by the server |
Specifies the number of buffers for a given log file. |
|
1000 |
Specifies the maximum number of logging buffers to use. |
||
thread-buffer-size |
Number of bytes |
8192 (8 KB) |
Specifies the size of the per thread log buffer. |
Enables rotation for logs. |
|||
A 4-digit string indicating the time in 24-hour format |
Indicates the time to start rotation. For example, 0900 indicates 9 a.m. while 1800 indicates 9 p.m. |
||
Number of minutes |
|
Indicates the number of minutes to elapse between each log rotation. |
|
yes, no |
yes |
(optional) Determines whether common-log, flex-log, and record-useragent logs are rotated. For more information, see the Sun Java System Web Proxy Server 4.0.11 NSAPI Developer’s Guide. |
|
yes, no |
yes |
(optional) Determines whether error logs are rotated. |
|
A path |
(optional) Specifies the file name of a user-supplied program to execute after following log file rotation. The program passes the post-rotation name of the rotated log file as its parameter. |
||
Changes the default settings for CGI programs. |
|||
Number of seconds |
300 |
(optional) specifies how many seconds the server waits for CGI output before terminating the script. |
|
(optional) Specifies the path to the CGI stub binary. If not specified, iPlanet Web Server looks in the following directories, in the following order, relative to the server instance’s config directory: ../private/Cgistub, then ../../bin/https/bin/Cgistub. For information about installing an suid Cgistub, see the Sun Java System Web Proxy Server 4.0.11 NSAPI Developer’s Guide. |
|||
env-variable |
(optional) Specifies the name and value for an environment variable that the server places into the environment for the CGI. |
||
Initializes the Common Log subsystem. |
|||
logFileName |
A path or file name |
Specifies either the full path to the log file or a file name relative to the server’s logs directory. |
|
Loads user home directory information. |
|||
(optional) Specifies the full file system path to a file other than /etc/passwd. If not provided, the default UNIX path (/etc/passwd) is used. |
|||
Loads shared libraries into the server. |
|||
Specifies either the full path to the shared library or dynamic link library, or specifies a file name relative to the server configuration directory. |
|||
A comma separated list with no spaces |
A list of the names of the functions in the shared library or dynamic link library to be made available for use by other Init or Service directives. The dash (-) character can be used in place of the underscore (_) character in function names. |
||
yes, no |
yes |
(optional) Specifies which threading model to use. no causes the routines in the library to use user-level threading. yes enables kernel-level threading. |
|
|
The name of a custom thread pool, as specified in thread-pool-init. |
||
Enables the NT console, which is the command-line shell that displays standard output and error streams. |
|||
console |
Directs error messages to the NT console. |
||
console |
Directs output to the NT console. |
||
Enables system performance measurement via performance buckets. |
|||
disable |
true, false |
true |
Disables the function when true. |
Configures pooled memory allocation. |
|||
1048576 bytes or less |
(optional) Maximum size in bytes of free block list. |
||
true, false |
false |
(optional) Flag to disable the use of pooled memory if true. |
|
Enables you to extend the HTTP protocol by registering new HTTP methods. |
|||
methods |
A comma-separated list |
Names of the methods you are registering. |
|
Enables reporting of performance statistics in XML format. |
|||
yes, no |
no |
Enables NSAPI performance profiling using buckets. This setting can also be enabled through perf-init. |
|
1 or greater |
5 |
The period in seconds between statistics updates within the server. |
|
1 or greater |
1000 |
The maximum number of virtual servers for which statistics are tracked. This number should be set higher than the number of virtual servers configured. |
|
Configures an additional thread pool. |
|||
Name of the thread pool. |
|||
Maximum number of threads in the pool. |
|||
Minimum number of threads in the pool. |
|||
Number of bytes |
Size of the queue for the pool. |
||
Number of bytes |
Stack size of each thread in the native (kernel) thread pool. |
||
tune-cache |
Enables you to tune the performance of your proxy server's cache. |
||
byte-ranges |
Determines whether the proxy can generate byte-range responses from the cache. |
||
tune-proxy |
Enables you to tune the performance of your proxy server. Do not change the default settings. |
||
ftp-listing-width |
80 characters |
Increasing the width of FTP listings allows longer file names and thus reduces file name truncation. |
|
um-define-junction |
Defines a URL Mapping that will be enforced by the "URL Mapping" layer. |
||
jct-name |
The name of the junction. |
||
fe-uri-prefix |
The front-end URI prefix that is associated with this junction definition or mapping. |
||
be-url-prefix |
The back-end URL prefix that is associated with this junction definition or mapping. |
||
junction-mapping |
yes |
A junction mapping. |
|
parser-config |
Specifies the parser configuration that is used for this junction. |
||
passthru-cookies |
Specifies a comma-separated list of cookie names that is passed through to the junction without translation. |
||
has-javascript |
yes |
Enables JavaScript rewriting for all JavaScript content. |
|
onload-handler |
um_jct |
Inserts special bit of code into each request to this junction. |
|
base-tag-handler |
no |
<base> tags receive special handling |
|
rewrite-events |
yes |
Rewrite event attributes within HTML tags |
|
redirect-without-trailing-slash |
Requests that match fe-uri-prefix without the trailing slash are immediately redirected to fe-uri-prefix with the trailing slash. |
||
add-headers |
Specifies a static list of headers to be added to all requests within this junction. |
||
lookup-equiv-hosts |
no |
Prevent a new junction from adding the back-end server's IP addresses to this list. |
|
add-equiv-hosts |
Specifies a comma-delimited list of additional host names (and/or IP addresses) that are considered to be equivalent to this junction's host name. |
||
output-buffer-size |
Enables (or disables) output buffering. To enable this, set output-buffer-size to a nonzero value. |
||
references-other-jcts |
Searches other junctions while trying to rewrite URLs for this junction. |
||
use-template |
Assigns an object name (which matches the junction's name) to requests that match this junction. |
||
name |
Overrides the object name for this junction. |
||
um-init |
Initializes the URL Mapping module. |
||
global-passthru-cookies |
Specifies a comma-delimited list of cookies that are always passed through to the back-end applications. |
||
jct-cookie-name |
um_jct |
Sets the name of the cookie that stores the last-used back-end URL's name. |
|
jct-cookie-prefix |
Informs the URL Mapping layer which cookies to pass to the back-end server on a given request. |
||
jct-cookie-domain |
Sets the URL Mapping cookie in specified domain. |
||
default-output-buffer-size |
Sets the default output buffer size for URL Mappings that do not explicitly set output-buffer-size. |
||
um-load-parser-config |
Loads a parser configuration into memory. |
||
file |
Specifies the location of the parser configuration file. |
||
config-name |
Specifies the name associated with this parser configuration. |
AuthTrans stands for Authorization Translation. AuthTrans directives give the server instructions for checking authorization before allowing a client to access resources. AuthTrans directives work in conjunction with PathCheck directives. The AuthTrans function checks whether the user name and password associated with the request are acceptable. However, this function does not allow or deny access to the request. Access is handled by the PathCheck function.
The server handles the authorization of client users in two steps:
AuthTrans validates authorization information sent by the client in the Authorization header.
PathCheck checks that the authorized user is allowed access to the requested resource.
The authorization process is split into two steps so that multiple authorization schemes can be easily incorporated. This scheme also provides the flexibility to have resources that record authorization information but do not require it.
AuthTrans functions get the user name and password from the headers associated with the request. When a client initially makes a request, the user name and password are unknown so the AuthTrans functions and PathCheck functions work together to reject the request, because they cannot validate the user name and password. When the client receives the rejection, its usual response is to present a dialog box asking for the user name and password to enter the appropriate realm. The client submits the request again, this time including the user name and password in the headers.
If more than one AuthTrans directive is present in obj.conf, each function is executed in order until one succeeds in authorizing the user.
The following AuthTrans-class functions are described in detail in this section:
basic-auth calls a custom function to verify user name and password. Optionally determines the user’s group.
basic-ncsa verifies user name and password against an NCSA-style or system DBM database. Optionally determines the user’s group.
get-sslid retrieves a string that is unique to the current SSL session and stores it as the ssl-id variable in the Session->client parameter block.
match-browser matches specific strings in the User-Agent string supplied by the browser, and then modifies the behavior of the Sun Java System Web Proxy Server based upon the results by setting values for specified variables.
proxy-auth translates authorization information provided through the basic proxy authorization scheme.
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.
Applicable in AuthTrans-class directives.
The basic-auth function calls a custom function to verify authorization information sent by the client. The Authorization header is sent as part of the basic server authorization scheme.
This function is usually used in conjunction with the PathCheck-class function require-auth.
The following table describes the parameter for the basic-auth function.
Table 5–32 basic-auth parameters
Parameter |
Description |
---|---|
Specifies the type of authorization to be used. Set this value to basic. |
|
(Optional) Specifies the full path and file name of the user database to be used for user verification. This parameter is passed to the user function. |
|
Name of the user custom function to verify authorization. This function must have been previously loaded with load-modules. It has the same interface as all of the SAFs, but it is called with the user name (user), password (pw), user database (userdb), and group database (groupdb) if supplied, in the pb parameter. The user function checks the name and password using the database and return REQ_NOACTION if they are not valid. The user function returns REQ_PROCEED if the name and password are valid. The basic-auth function then adds auth-type, auth-user (user), auth-db (userdb), and auth-password (pw, Windows only) to the rq->vars pblock. |
|
(Optional) Specifies the full path and file name of the user database. This parameter is passed to the group function. |
|
(Optional) Name of the group custom function that must have been previously loaded with load-modules. It has the same interface as all of the SAFs, but it is called with the user name (user), password (pw), user database (userdb), and group database (groupdb) in the pb parameter. It also has access to the auth-type, auth-user (user), auth-db (userdb), and auth-password (pw, Windows only) parameters in the rq->vars pblock. The group function determines the user’s group using the group database, add it to rq->vars as auth-group, and return REQ_PROCEED if found. It returns REQ_NOACTION if the user’s group is not found. |
|
bucket |
(Optional) Common to all obj.conffunctions. |
In magnus.conf:
Init fn=load-modules shlib=/path/to/mycustomauth.so funcs=hardcoded_auth |
In obj.conf:
AuthTrans fn=basic-auth auth-type=basic userfn=hardcoded_authPathCheck fn=require-auth auth-type=basic realm="Marketing Plans" |
Applicable in AuthTrans-class directives.
The basic-ncsa function verifies authorization information sent by the client against a database. The Authorization header is sent as part of the basic server authorization scheme.
This function is usually used in conjunction with the PathCheck-class function require-auth.
The following table describes the parameter for the basic-ncsa function.
Table 5–33 basic-ncsa Parameters
Parameter |
Description |
---|---|
Specifies the type of authorization to be used. Set this value to basic. |
|
(Optional) Specifies the full path and base file name of the user database in the server’s native format. The native format is a system DBM file, which is a hashed file format that provides instantaneous access to large number of users. If you use this parameter, don’t use the userfile parameter as well. |
|
(Optional) Specifies the full path name of the user database in the NCSA-style HTTPD user file format. This format consists of lines using the format name:password, where password is encrypted. If you use this parameter, don’t use dbm. |
|
(Optional) Specifies the NCSA-style HTTPD group file to be used. Each line of a group file consists of group:user1 user2. userN where each user is separated by spaces. |
|
bucket |
(Optional) Common to all obj.conf functions. |
AuthTrans fn=basic-ncsa auth-type=basic dbm=/sun/server61/userdb/rsPathCheck fn=require-auth auth-type=basic realm="Marketing Plans"AuthTrans fn=basic-ncsa auth-type=basic userfile=/sun/server61/.htpasswd grpfile=/sun/server61/.grpfilePathCheck fn=require-auth auth-type=basic realm="Marketing Plans" |
Applicable in AuthTrans-class directives.
This function is provided for backward compatibility only. The functionality of get-sslid has been incorporated into the standard processing of an SSL connection.
The get-sslid function retrieves a string that is unique to the current SSL session, and stores it as the ssl-id variable in the Session->client parameter block.
If the variable ssl-id is present when a CGI is invoked, it is passed to the CGI as the HTTPS_SESSIONID environment variable.
The get-sslid function has no parameters and always returns REQ_NOACTION. It has no effect if SSL is not enabled.
The following table describes the parameter for the get-sslid function.
Table 5–34 get-sslid Parameters
Parameter |
Description |
---|---|
bucket |
(Optional) Common to all obj.conf functions. |
Applicable in all stage directives.
The match-browser SAF matches specific strings in the User-Agent string supplied by the browser match-browser then modifies the behavior of the Sun Java System Web Proxy Server based upon the results by setting values for specified variables.
stage fn="match-browser" browser="string" name="value" [name="value" ...]
The following table describes the parameter values for the match-browser function.
Table 5–35 match-browser Parameter Values
Value |
Description |
---|---|
stage |
Stage directive used in obj.conf processing (NameTrans, PathCheck, and so on). The match-browser function is applicable in all stage directives. |
string |
Wildcard pattern to compare against the User-Agent header, for example, "*Mozilla*". |
name |
Variable to be changed. The match-browser SAF indirectly invokes the set-variable SAF. For a list of valid variables, see set-variable. |
value |
New value for the specified variable. |
The following AuthTrans directive instructs the Sun Java System Web Proxy Server to when the browser’s User-Agent header contains the string Broken or broken:
Not send the SSL3 and TLS close_notify packet (see set-variable).
Not honor requests for HTTP Keep-Alive (see set-variable).
Use the HTTP/1.0 protocol rather than HTTP/1.1 (see set-variable).
AuthTrans fn="match-browser" browser="*[Bb]roken*" ssl-unclean-shutdown="true" keep-alive="disabled" http-downgrade="1.0" |
The following table describes the variables used in the example.
Table 5–36 Description of variables
Applicable in AuthTrans-class directives.
The proxy-auth function of the AuthTrans directive translates authorization information provided through the basic proxy authorization scheme. This scheme is similar to the HTTP authorization scheme but doesn’t interfere with it, so using proxy authorization doesn’t block the ability to authenticate to the remote server.
This function is usually used with the PathCheck fn=require-proxy-auth function.
AuthTrans fn=proxy-auth auth-type=basic dbm=full path name AuthTrans fn=proxy-auth auth-type=basic userfile=full path name grpfile=full path name
The following table describes the parameter values for the proxy-auth function.
Table 5–37 proxy-auth Parameter Values
Value |
Description |
---|---|
auth-type |
Specifies the type of authorization to be used. Set the type to “basic” unless you are running a UNIX proxy and are going to use your own function to perform authentication. |
dbm |
Specifies the full path and base file name of the user database in the server’s native format. The native format is a system DBM file, which is a hashed file format allowing instantaneous access to large number of users. If you use this parameter, don’t use the userfile parameter. |
userfile |
Specifies the full path name of the user database in the NCSA-style httpd user file format. This format consists of name:password lines where password is encrypted. If you use this parameter, do not use dbm. |
grpfile |
(optional)Specifies the NCSA-style httpd group file to be used. Each line of a group file consists of group:user1 user2...userN, where each user is separated by spaces. |
A UNIX example:
AuthTrans fn=proxy-auth auth-type=basic dbm=/usr/ns-home/proxy-EXAMPLE/userdb/rs A Windows NT example: AuthTrans fn=proxy-auth auth-type=basic userfile=\\netscape\\server \\proxy-EXAMPLE\\.htpasswd grpfile=\\netscape\\server \\proxy-EXAMPLE\\.grpfile |
You can have a user-provided function perform authentication by passing the user-fn parameter to the proxy-auth function.
AuthTrans fn=proxy-auth auth-type=basic user-fn=your function userdb=full path name
The following table describes the parameter values for the user provided proxy-auth function.
Table 5–38 user provided proxy-auth parameter values
Value |
Description |
---|---|
user-fn |
Specifies the name of the user-provided function that to be used to perform authentication in place of the built-in authentication. If authentication succeeds, the function returns REQ-PROCEED and if authentication fails, it returns REQ-NOACTION. |
userdb |
Specifies the full path and base file name of the user database in the server’s native format. The native format is a system DBM file, which is a hashed file format allowing instantaneous access to large numbers of users. |
Applicable in all stage directives.
The set-variable function enables you to change server settings based upon conditional information in a request. It can also be used to manipulate variables in parameter blocks with the following commands:
insert-pblock="name=value"
Adds a new value to the specified pblock.
set-pblock="name=value"
Sets a new value in the specified pblock, replacing any existing values with the same name.
remove-pblock="name"
Removes all values with the given name from the specified pblock.
For more information about parameter blocks, see Sun Java System Web Proxy Server 4.0.11 NSAPI Developer’s Guide.
stage fn="set-variable" [{insert|set|remove}-pblock="name=value" ...][name="value" ...]
The following table describes parameter values for the set-variable function.
Table 5–39 set-variable parameter values
Value |
Description |
---|---|
pblock |
One of the following Session/Request parameter block names:
|
name |
The variable to set. |
value |
The string assigned to the variable specified by name. |
The following table lists variables supported by the set-variable SAF.
Table 5–40 Supported set-variable Variables
Parameter |
Description |
---|---|
abort |
A value of true indicates the result code should be set to REQ_ABORTED. Setting the result code to REQ_ABORTED will abort the current request and send an error to the browser. |
error |
Sets the error code to be returned in the event of an aborted browser request. |
escape |
A Boolean value signifying whether a URL should be escaped using util_uri_escape. For information about util_uri_escape, see the “NSAPI Function Reference” chapter of Sun Java System Web Proxy Server 4.0.11 NSAPI Developer’s Guide. |
find-pathinfo-forward |
Path information after the file name in a URI. See find-pathinfo. |
http-downgrade |
HTTP version number (for example, 1.0). |
http-upgrade |
HTTP version number (for example, 1.0). |
keep-alive |
A Boolean value that establishes whether a keep-alive request from a browser will be honored. |
name |
Specifies an additional named object in the obj.conf file whose directives will be applied to this request. See also assign-name. |
noaction |
A value of true indicates the result code should be set to REQ_NOACTION. For AuthTrans, NameTrans, Service, and Error stage SAFs, setting the result code to REQ_NOACTION indicates that subsequent SAFs in that stage should be allowed to execute. |
nostat |
Causes the server not to perform the stat() function for a URL when possible. See also assign-name. |
senthdrs |
A Boolean value that indicates whether HTTP response headers have been sent to the client. |
ssl-unclean-shutdown |
A Boolean value that can be used to alter the way SSL3 connections are closed. As this behavior violates the SSL3 RFCs, only use this value with great caution if you know that you are experiencing problems with SSL3 shutdowns. |
stop |
A value of true indicates the result code should be set to REQ_PROCEED. For AuthTrans, NameTrans, Service, and Error stage SAFs, setting the result code to REQ_PROCEED indicates that no further SAFs in that stage should be allowed to execute. |
url |
Redirect requests to a specified URL. |
To deny HTTP keep-alive requests for a specific server class while still honoring keep-alive requests for the other classes, add this AuthTrans directive to the obj.conf for the server class, and set the variable keep-alive to disabled:
AuthTrans fn="set-variable" keep-alive="disabled"
To cause that same server class to use HTTP/1.0 while the rest of the server classes use HTTP/1.1, the AuthTrans directive would be:
AuthTrans fn="set-variable" keep-alive="disabled" http-downgrade="true"
To insert an HTTP header into each response, add a NameTrans directive to obj.conf, using the insert-pblock command and specifying srvhdrs as your Session/Request parameter block.
For example, to insert the HTTP header P3P, you would add the following line to each request:
NameTrans fn="set-variable" insert-srvhdrs="P3P"
To terminate processing a request based upon certain URIs, use a <Client> tag to specify the URIs and an AuthTrans directive that sets the variable abort to true when a match is found. Your <Client> tag would be comparable to the following:
<Client uri="*(system32|root.exe)*">AuthTrans fn="set-variable" abort="true"</Client>
NameTrans stands for Name Translation. NameTrans directives translate virtual URLs to physical directories on your server. For example, the URL
http://www.test.com/some/file.html
could be translated to the full file system path
/usr/Sun/WebServer61/server1/docs/some/file.html
NameTrans directives should appear in the default object. If an object contains more than one NameTrans directive, the server executes each directive in order until one succeeds.
The following NameTrans-class functions are described in detail in this section
assign-name tells the server to process directives in a named object.
document-root translates a URL into a file system path by replacing the http://server-name/ part of the requested resource with the document root directory.
home-page translates a request for the server’s root home page (/) to a specific file.
map looks for a certain URL prefix in the URL that the client is requesting.
match-browser matches specific strings in the User-Agent string supplied by the browser, and then modifies the behavior of the Sun Java System Web Proxy Server based upon the results by setting values for specified variables.
ntrans-j2ee determines whether a request maps to a -based web application context. Based on Java technology this function is applicable only to the Administration Server.
pac-map maps proxy-relative URLs to local files that are delivered to clients who request configuration.
pat-map maps proxy-relative URLs to local files that are delivered to proxies that request configuration.
pfx2dir translates any URL beginning with a given prefix to a file system directory and optionally enables directives in an additional named object.
redirect redirects the client to a different URL.
regexp-map allows a regular expression map.
reverse-map rewrites HTTP response headers when the proxy server is functioning as a reverse proxy.
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.
strip-params removes embedded semicolon-delimited parameters from the path.
um-ntrans identifies an inbound request as being related to a junction (or not).
unix-home translates a URL to a specified directory within a user’s home directory.
Applicable in NameTrans-class directives.
The assign-name function specifies the name of an object in obj.conf that matches the current request. The server then processes the directives in the named object in preference to the ones in the default object.
For example, consider the following directive in the default object:
NameTrans fn=assign-name name=personnel from=/personnel
Suppose the server receives a request for http://server-name/personnel. After processing this NameTrans directive, the server looks for an object named personnel in obj.conf, and continues by processing the directives in the personnel object.
The assign-name function always returns REQ_NOACTION.
The following table describes the parameters for the assign-name function.
Table 5–41 assign-name parameters
Parameter |
Description |
---|---|
Wildcard pattern that specifies the path to be affected. |
|
name |
Specifies an additional named object in obj.conf whose directives are applied to this request. |
(Optional) Makes the server look for the PATHINFO forward in the path after the ntrans-base instead of backward from the end of path as the server function assign-name does by default. The value you assign to this parameter is ignored. If you do not want to use this parameter, do not include it. The find-pathinfo-forward parameter is ignored if the ntrans-base parameter is not set in rq->vars. By default, ntrans-base is set. This feature can improve performance for certain URLs by reducing the number of stats performed. |
|
(Optional) Prevents the server from performing a stat on a specified URL whenever possible. The effect of nostat="virtual-path" in the NameTrans function assign-name is that the server assumes that a stat on the specified virtual-path will fail. Therefore, use nostat only when the path of the virtual-path does not exist on the system, for example, for NSAPI plug-in URLs, to improve performance by avoiding unnecessary stats on those URLs. When the default PathCheck server functions are used, the server does not stat for the paths /ntrans-base/virtual-path and /ntrans-base/virtual-path/* if ntrans-base is set (the default condition); it does not stat for the URLs /virtual-path and /virtual-path/* if ntrans-base is not set. |
|
bucket |
(Optional) Common to all obj.conf functions. |
# This NameTrans directive is in the default object. NameTrans fn=assign-name name=personnel from=/a/b/c/pers... <Object name=personnel>...additional directives..</Object> NameTrans fn="assign-name" from="/perf" find-pathinfo-forward="" name="perf" NameTrans fn="assign-name" from="/nsfc" nostat="/nsfc" name="nsfc" |
Applicable in NameTrans-class directives.
The document-root function specifies the root document directory for the server. If the physical path has not been set by a previous NameTrans function, the http://server-name/ part of the path is replaced by the physical path name for the document root.
When the server receives a request for http://server-name/somepath/somefile, the document-root function replaces http://server-name/ with the value of its root parameter. For example, if the document root directory is /usr/sun/webserver61/server1/docs, then when the server receives a request for http://server-name/a/b/file.html, the document-root function translates the path name for the requested resource to /usr/sun/webserver61/server1/docs/a/b/file.html.
This function always returns REQ_PROCEED. NameTrans directives listed after this response are never called, so be sure that the directive that invokes document-root is the last NameTrans directive.
You can declare only one root document directory. To specify additional document directories, use the pfx2dir function to set up additional path name translations.
The following table describes parameters for the document-root function.
Table 5–42 document-root parameters
Parameter |
Description |
---|---|
File system path to the server’s root document directory |
|
bucket |
(Optional) Common to all obj.conf functions |
NameTrans fn=document-root root=/usr/sun/webserver61/server1/docsNameTrans fn=document-root root=$docroot |
Applicable in NameTrans-class directives.
The home-page function specifies the home page for your server. This page is displayed whenever a client requests the server’s home page (/).
The following table describes parameters for the home-page function.
Table 5–43 home-page parameters
Parameter |
Description |
---|---|
Path and name of the home page file. A path that starts with a slash (/) and is assumed to be a full path to a file. This function sets the server’s path variable and returns REQ_PROCEED. Relative paths are appended to the URI and the function returns REQ_NOACTION and then continues on to the other NameTrans directives. |
|
bucket |
(Optional) Common to all obj.conf functions. |
NameTrans fn="home-page" path="/path/to/file.html" NameTrans fn="home-page" path="/path/to/$id/file.html" |
Applicable in NameTrans-class directives.
The map function looks for a certain URL prefix in the URL that the client is requesting. If map finds the prefix, it replaces the prefix with the mirror site prefix. Note that the trailing slashes in URL cause “Not Found” errors.
NameTrans fn=map from="source site prefix" to="destination site prefix" name="named object"
The following table describes parameters for the map function.
Table 5–44 map Parameters
Parameter |
Description |
---|---|
from |
The prefix to be mapped to the mirror site. |
to |
The mirror site prefix. |
name |
(optional) the object from which to derive the configuration for this mirror site. |
rewrite-host |
(optional) Indicates whether the Host HTTP request header is rewritten to match the host specified by the to parameter. In a reverse proxy configuration where the proxy server and origin server service the same set of virtual servers, you may want to specify rewrite-host="false". The default is true, meaning that the Host HTTP request header is rewritten. |
Example
# Map site http://home.netscape.com/ to mirror site http://mirror.com NameTrans fn=map from="http://home.netscape.com" to="http://mirror.com" |
See match-browser.
This function is applicable only to the Administration Server. It is applicable in NameTrans-class directives.
The ntrans-j2ee function determines whether a request maps to a Java web application context.
The following table describes parameters for the ntrans-j2ee function.
Table 5–45 ntrans-j2ee parameters
Parameter |
Description |
---|---|
name |
Named object in obj.conf whose directives are applied to requests made to Java web applications |
bucket |
(Optional) Common to all obj.conf functions |
NameTrans fn="ntrans-j2ee" name="j2ee" |
Applicable in NameTrans-class directives.
The pac-map function maps proxy-relative URLs to local files that are delivered to clients who request configuration.
NameTrans fn=pac-map from=URL to=prefix name=named object
The following table describes parameters for the pac-map function.
Table 5–46 pac-map parameters
Parameter |
Description |
---|---|
The proxy URL to be mapped. |
|
to |
The local file to be mapped to. |
name |
(optional) The object (template) from which to derive configuration. |
Example
NameTrans fn=pac-map from=http://proxy.mysite.com/pac to=<install-root><instance-directory>pac/proxy.pac name=file |
Applicable in NameTrans-class directives.
The pat-map function maps proxy-relative URLs to local files that are delivered to proxies who request configuration.
Syntax
NameTrans fn=pat-map from=URL to=prefix name=named object
Parameters
The following table describes parameters for the pat-map function.
Table 5–47 pat-map parameters
Parameter |
Description |
---|---|
from |
The proxy URL to be mapped. |
to |
The local file to be mapped to. |
name |
(optional) The object (template) from which to derive configuration. |
Example
NameTrans fn=pat-map from=http://proxy.mysite.com/pac to=<install-root><instance-directory>pac/proxy.pac name=file |
Applicable in NameTrans-class directives.
The pfx2dir function replaces a directory prefix in the requested URL with a real directory name. It also optionally enables you to specify the name of an object that matches the current request. See the discussion of assign-name for details of using named objects.
The following table describes parameters for the pfx2dir function.
Table 5–48 pfx2dir parameters
Parameter |
Description |
---|---|
from |
URI prefix to convert. Do not insert a trailing slash (/). |
Local file system directory path that the prefix is converted to. Do not insert a trailing slash (/). |
|
(Optional) Specifies an additional named object in obj.conf whose directives will be applied to this request. |
|
(Optional) Makes the server look for the PATHINFO forward in the path after the ntrans-base instead of backward from the end of path as the server function find-pathinfo does by default. The value you assign to this parameter is ignored. If you do not want to use this parameter, do not include it. The find-pathinfo-forward parameter is ignored if the ntrans-base parameter is not set in rq->vars when the server function find-pathinfo is called. By default, ntrans-base is set. This feature can improve performance for certain URLs by reducing the number of stats performed in the server function find-pathinfo. On Windows, this feature can also be used to prevent the PATHINFO from the server URL normalization process (changing ’\\’ to ’/’) when the PathCheck server function find-pathinfo is used. Some double-byte characters have hexadecimal values that may be parsed as URL separator characters such as \\ or ~. Using the find-pathinfo-forward parameter can sometimes prevent incorrect parsing of URLs containing double-byte characters. |
|
bucket |
(Optional) Common to all obj.conf functions. |
In the first example, the URL http://server-name/cgi-bin/resource (such as http://x.y.z/cgi-bin/test.cgi) is translated to the physical path name /httpd/cgi-local/resource (such as /httpd/cgi-local/test.cgi), and the server also starts processing the directives in the object named cgi.
NameTrans fn=pfx2dir from=/cgi-bin dir=/httpd/cgi-local name=cgi |
In the second example, the URL http://server-name/icons/resource (such as http://x.y.z/icons/happy/smiley.gif) is translated to the physical path name /users/nikki/images/resource (such as /users/nikki/images/smiley.gif).
NameTrans fn=pfx2dir from=/icons/happy dir=/users/nikki/images |
The third example shows the use of the find-pathinfo-forward parameter. The URL http://server-name/cgi-bin/resource is translated to the physical path name /export/home/cgi-bin/resource.
NameTrans fn="pfx2dir" find-pathinfo-forward="" from="/cgi-bin" dir="/export/home/cgi-bin" name="cgi" |
Applicable in NameTrans-class directives.
The redirect function enables you to change URLs and send the updated URL to the client. When a client accesses your server with an old path, the server treats the request as a request for the new URL.
The following table describes parameters for the redirect function.
Table 5–49 redirect parameters
Parameter |
Description |
---|---|
from |
Specifies the prefix of the requested URI to match. |
url specifies a complete URL to return to the client. url-prefix specifies the new URL prefix to return to the client. The from prefix is simply replaced by this URL prefix. You cannot use these parameters together. |
|
(Optional) Flag that tells the server to util_uri_escape the URL before sending it. It should be yes or no. The default is yes. For more information about util_uri_escape, see Sun Java System Web Proxy Server 4.0.11 NSAPI Developer’s Guide. |
|
bucket |
(Optional) Common to all obj.conf functions. |
In the first example, any request for http://server-name/string is translated to a request for http://tmpserver/string.
NameTrans fn=redirect from=/ url-prefix=http://tmpserver |
In the second example, any request for http://server-name/toopopular/string is translated to a request for http://bigger/better/stronger/morepopular/string.
NameTrans fn=redirect from=/toopopular url=http://bigger/better/stronger/morepopular |
Applicable in NameTrans-class directives.
The regexp-map is similar to the map function. While the map function looks for an exact match of a URL prefix, regexp-map allows a regular expression match.
The following table describes parameters for the regexp-map function.
Table 5–50 regexp-map parameters
Parameter |
Description |
---|---|
from |
A regular expression for the prefix to be mapped to the mirror site. |
to |
The mirror site prefix. |
name |
(Optional) A named object from which to derive the configuration for the mirror site. |
rewrite-host |
(Optional) Indicates whether the Host HTTP request header is rewritten to match the host specified by the parameter. In a reverse proxy configuration where the proxy server and origin server service the same set of virtual servers, you may wish to specify rewrite-host="false". The default is "true", meaning that the Host HTTP request header is rewritten. |
Applicable in NameTrans-class directives.
The reverse-map function is used to rewrite HTTP response headers when the proxy server is functioning as a reverse proxy. reverse-map looks for the URL prefix specified by the from parameter in certain response headers. If the from prefix matches the beginning of the response header value, reverse-map replaces the matching portion with the to prefix.
The following table describes parameters for the reverse-map function.
Table 5–51 reverse-map parameters
Parameter |
Description |
---|---|
from |
URL prefix to be rewritten. |
to |
URL prefix that will be substituted in place of the from prefix. |
rewrite-location |
(Optional) Boolean that indicates whether the Location HTTP response header should be rewritten. The default is true, meaning the Location header is rewritten. |
rewrite-content-location |
(Optional) Boolean that indicates whether the content-location HTTP response header should be rewritten. The default is true, meaning the Content-location header is rewritten. |
rewrite-headername |
(Optional) Boolean that indicates whether the headername HTTP response header should be rewritten, where headername is a user-defined header name. With the exception of the Location and Content-location headers, the default is false, meaning the headername header is not rewritten. |
rewrite-set-cookie |
Takes a boolean value and is set to true by default. Enables or disables cookie rewriting, which involves rewriting the domain and path parameters of the set-cookie headers. |
cookiepath-from |
Specifies the target value of the path parameter. |
cookiepath-to |
If the value of the path parameter matches the value of cookiepath-from, it will be rewritten to the value of cookiepath-to. |
See set-variable.
Applicable in NameTrans-class directives.
The strip-params function removes embedded semicolon-delimited parameters from the path. For example, a URI of /dir1;param1/dir2 would become a path of /dir1/dir2. When used, the strip-params function should be the first NameTrans directive listed.
The following table describes the parameter for the strip-params function.
Table 5–52 strip-params Parameters
Parameter |
Description |
---|---|
bucket |
(Optional) Common to all obj.conf functions |
NameTrans fn=strip-params
Applicable in NameTrans-class directives.
The um-ntrans function determines if an inbound request is related to a junction or not. It also rewrites inbound cookies, adds headers, and does any rewriting when necessary, before the request is sent to the back-end server.
If a request cannot be mapped to a junction, it is passed through without modification.
This directive must appear exactly once in obj.conf, typically inside the default object.
Nametrans fn="um-ntrans" |
Applicable in NameTrans-class directives.
UNIX Only. The unix-home function translates user names typically of the form ~username into the user’s home directory on the server’s UNIX machine. You specify a URL prefix that signals user directories. Any request that begins with the prefix is translated to the user’s home directory.
You specify the list of users with either the /etc/passwd file or a file with a similar structure. Each line in the file should have this structure. Elements in the passwd file that are not needed are indicated with *:
username:*:*:groupid:*:homedir:*
If you want the server to scan the password file only once at startup, use the Init-class function init-uhome in magnus.conf.
The following table describes the parameters for the unix-home function.
Table 5–53 unix-home Parameters
Parameter |
Description |
---|---|
Subdirectory within the home directory that contains the user's web documents. |
|
(Optional) Full path and file name of the password file if it is different from /etc/passwd. |
|
(Optional) Specifies an additional named object whose directives will be applied to this request. |
|
bucket |
(Optional) Common to all obj.conf functions. |
NameTrans fn=unix-home from=/~ subdir=public_html NameTrans fn=unix-home from /~ pwfile=/mydir/passwd subdir=public_html |
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 object contains 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:
block-multipart-posts - Blocks all multipart form file uploads when configured without any parameters.
check-acl - Checks an access control list for authorization.
deny-existence - Indicates that a resource was not found.
deny-service - Sends a “Proxy Denies Access” error when a client tries to access a specific path.
find-index - Locates a default file when a directory is requested.
find-links - Denies access to directories with certain file system links.
find-pathinfo - Locates extra path info beyond the file name for the PATH_INFO CGI environment variable.
get-client-cert - Gets the authenticated client certificate from the SSL3 session.
load-config - Finds and loads extra configuration information from a file in the requested path.
match-browser - Matches specific strings in the User-Agent string supplied by the browser, and then modifies the behavior of the Sun Java System Web Proxy Server based upon the results by setting values for specified variables.
nt-uri-clean - Denies access to requests with unsafe path names by sending not found error.
ntcgicheck - Checks for a CGI file with a specified extension.
require-auth - Denies access to unauthorized users or groups.
require-proxy-auth - Makes sure that users are authenticated and triggers a password pop-up window.
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.
set-virtual-index - Specifies a virtual index for a directory.
ssl-check - Checks the secret keysize.
ssl-logout - Invalidates the current SSL session in the server’s SSL session cache.
unix-uri-clean - Denies access to requests with unsafe path names by sending not found error.
url-check - Checks the validity of URL syntax.
url-filter - Allows or denies URL patterns.
user-agent-check - Restricts access to the proxy server based on the type and version of the client’s web browser.
Applicable in PathCheck-class directives.
The block-multipart-posts function blocks all multipart form file uploads when configured without any parameters. This can also be used to block requests based on specific content type, user-agent, or HTTP method using content-type, user-agent and method parameters.
The following table describes parameters for the block-multipart-posts function.
Table 5–54 block-multipart-posts Parameters
Parameter |
Description |
---|---|
content-type |
(Optional) Regular expression of the content type to be blocked |
user-agent |
(Optional) Regular expression of the user agent to be blocked |
method |
(Optional) Regular expression matching the HTTP request method to be blocked |
PathCheck fn="block-multipart-posts" user-agent="Mozilla/.*" method="(POST|PUT)" |
Applicable in PathCheck-class directives.
The check-acl function specifies an access control list (ACL) to use to check whether the client is allowed to access the requested resource. An access control list contains information about who is 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. These functions cause user authentication to be performed, if required by the specified ACL, and will also update the access control state.
The following table describes parameters for the check-acl function.
Table 5–55 check-acl Parameters
Parameter |
Description |
---|---|
Name of an access control list |
|
path |
(Optional) Wildcard pattern that specifies the path to which to apply the ACL. |
bucket |
(Optional) Common to all obj.conf functions |
PathCheck fn=check-acl acl="*HRonly*" |
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.
The following table describes the parameters for the deny-existence function.
Table 5–56 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. |
(Optional) A full file system path that specifies a file to send rather than responding with the “not found” message. |
|
bucket |
(Optional) Common to all obj.conf functions. |
PathCheck fn=deny-existence path=/usr/sun/server61/docs/private PathCheck fn=deny-existence bong-file=/svr/msg/go-away.html |
Applicable in PathCheck-class directives and Service-class directives.
The deny-service function sends a “Proxy Denies Access” error when a client tries to access a specific path. If this directive appears in a client region, the directive performs access control on the specified clients.
The proxy specifically denies clients instead of specifically allowing them access to documents. The default object is used when a client doesn’t match any client region in objects. Because the default object uses the deny-service function, no one is allowed access by default.
PathCheck fn=deny-service path=.*someexpression.*
The following table describes the parameter for the deny-service function.
Table 5–57 deny-service parameters
Parameter |
Description |
---|---|
path |
A regular expression representing the path to check. Not specifying this parameter is equivalent to specifying *. URLs matching the expression are denied access to the proxy server. |
Example
<Object ppath="http://sun/.*"> # Deny servicing proxy requests for fun GIFs PathCheck fn=deny-service path=.*fun.*.gif # Make sure nobody except Sun employees can use the object # inside which this is placed. <Client dns=*~.*.sun.com> PathCheck fn=deny-service </Client> </Object> |
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:
A compressed version is available
The compressed version is at least as recent as the noncompressed version
The client supports compression
Not all clients support compression. The find-compressed function enables you to use a single URL for both the compressed and noncompressed versions of a file. The version of the file that is selected is based on the individual client's capabilities.
A compressed version of a file must have the same file name as the noncompressed version but with a .gz suffix. For example, the compressed version of a file named /httpd/docs/index.html would be named /httpd/docs/index.html.gz. To compress files, you can use the freely available gzip program.
Because compressed files are sent as is to the client, you should not compress files such as SHTML pages, CGI programs, or pages created with Java Server PagesTM (JSPTM) technology that need to be interpreted by the server. To compress the dynamic content generated by these types of files, use the http-compression filter.
The find-compressed function does nothing if the HTTP method is not GET or HEAD.
The following table describes parameters for the find-compressed function.
Table 5–58 find-compressed parameters
Parameter |
Description |
---|---|
check-age |
Specifies whether to check if the compressed version is older than the noncompressed version. Possible values are yesand no.
|
vary |
Specifies whether to insert a Vary: Accept-Encoding header. Possible values are yesor no.
|
bucket |
(Optional) Common to all obj.conf functions. |
<Object name="default">NameTrans fn="assign-name" from="*.html" name="find-compressed"...</Object><Object name="find-compressed"> PathCheck fn="find-compressed"</Object> |
http-compression
Applicable in PathCheck-class directives.
The find-index function investigates whether the requested path is a directory. If the path is directory, 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.
If the obj.conf file contains 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.
The following table describes parameters for the find-index function.
Table 5–59 find-index parameters
Parameter |
Description |
---|---|
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 casesensitive if the file system is casesensitive. |
|
bucket |
(Optional) Common to all obj.conf functions. |
PathCheck fn=find-index index-names=index.html,home.html |
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. The function prevents someone from pointing to information that should not be made public.
The following table describes parameters for the find-links function.
Table 5–60 find-links Parameters
Parameter |
Description |
---|---|
disable |
Character string of links to disable: |
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. |
|
Checks linked file for existence and aborts request with 403 (forbidden) if this check fails. |
|
bucket |
(Optional) Common to all obj.conf functions. |
PathCheck fn=find-links disable=sh dir=/foreign-dir PathCheck fn=find-links disable=so dir=public_html |
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.
The following table describes parameters for the find-pathinfo function.
Table 5–61 find-pathinfo parameters
Parameter |
Description |
---|---|
bucket |
(Optional) Common to all obj.conf functions |
PathCheck fn=find-pathinfo PathCheck fn=find-pathinfo find-pathinfo-forward="" |
Applicable in PathCheck-class directives.
The get-client-cert function gets the authenticated client certificate from the SSL3 session. The function can apply to all HTTP methods, or only to those that match a specified pattern. The function 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, the function 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.
The following table describes parameters for the get-client-cert function.
Table 5–62 get-client-cert Parameters
Parameter |
Description |
---|---|
Controls whether to try to get the certificate or just test for its presence. If dorequest is absent, the default value is 0.
|
|
Controls whether failure to get a client certificate will abort the HTTP request. If require is absent, the default value is 1.
|
|
(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. |
# 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" |
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 determines whether to allow the client to access the requested resource.
Each directive that invokes load-config is associated with a base directory, which is either stated explicitly through the basedir parameter or derived from the root directory for the requested resource. The base directory determines two things:
The topmost directory for which requests will invoke this call to the load-config function.
For example, if the base directory is D:/sun/server1/docs/nikki/, then only requests for resources in this directory or its subdirectories and their subdirectories trigger the search for dynamic configuration files. A request for the resource D:/sun/server1/docs/somefile.html does not trigger the search in this case because the requested resource is in a parent directory of the base directory.
The topmost directory in which the server looks for dynamic configuration files to apply to the requested resource.
If the base directory is D:/sun/server1/docs/nikki/, the server starts its search for dynamic configuration files in this directory. It may or may not also search subdirectories (but never parent directories), depending on other factors.
When you enable dynamic configuration files through the Server Manager interface, the system writes additional objects with ppath parameters into the obj.conf file. If you manually add directives that invoke load-config to the default object rather than putting them in separate objects, the Server Manager interface might not reflect your changes.
If you manually add PathCheck directives that invoke load-config to the file obj.conf, put them in additional objects created with the <OBJECT> tag rather than putting them in the default object. Use the ppath attribute of the OBJECT tag to specify the partial path name for the resources to be affected by the access rules in the dynamic configuration file. The partial path name can be any path name that matches a pattern, which can include wildcard characters.
For example, the following <OBJECT> tag specifies that requests for resources in the directory D:/sun/proxy4/docs are subject to the access rules in the file my.nsconfig.
<Object ppath="D:/sun/server1/docs/*">PathCheck fn="load-config" file="my.nsconfig" descend=1 basedir="D:/sun/server1/docs" </Object> |
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. 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.
The following table describes parameters for the load-config function.
Table 5–63 load-config parameters
Parameter |
Description |
---|---|
(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. |
|
(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. |
|
(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. |
|
(Optional) Specifies base directory. This directory is the highest-level directory for which requests will invoke the load-config function. It 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. |
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 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 and applies the access control rules contained in each instance 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> |
See match-browser.
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).
The following table describes parameters for the nt-uri-clean function.
Table 5–64 nt-uri-clean Parameters
Parameter |
Description |
---|---|
If present, allows tilde (~) characters in URIs. This setting 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. |
|
If present, “//” sequences are allowed. |
|
bucket |
(Optional) Common to all obj.conf functions. |
PathCheck fn=nt-uri-clean |
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.
The following table describes parameters for the ntcgicheck function.
Table 5–65 ntcgicheck Parameters
Parameter |
Description |
---|---|
The replacement file extension |
|
bucket |
(Optional) Common to all obj.conf functions |
PathCheck fn=ntcgicheck extension=pl |
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.
The following table describes parameters for the require-auth function.
Table 5–66 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. |
Type of HTTP authorization used. This value must match the auth-type from the previous authorization function in AuthTrans. Currently, basic is the only authorization type defined. |
|
String sent to the browser indicating the secure area or realm for which a user name and password are requested. |
|
(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. |
|
(Optional) Specifies a wildcard list of groups that are allowed access. |
|
bucket |
(Optional) Common to all obj.conf functions. |
PathCheck fn=require-auth auth-type=basic realm="Marketing Plans" auth-group=mktg auth-user=(jdoe|johnd|janed) |
Applicable in PathCheck-class directives.
The require-proxy-auth function is a PathCheck function that makes sure that users are authenticated and triggers a password pop-up window.
PathCheck fn=require-proxy-auth auth-type=basic realm=name auth-group=group auth-users=name
The following table describes parameters for the require-proxy-auth function.
Table 5–67 require-proxy-auth Parameters
Parameter |
Description |
---|---|
auth-type |
Specifies the type of authorization to be used. Set the type to basic unless you are running a UNIX proxy and are going to use your own function to perform authentication. |
realm |
A string (enclosed in double-quotation marks) sent to the client application so users can see the objects for which they need authorization for. |
auth-user |
(optional) Specifies a list of users who get access. The list is enclosed in parentheses with each user name separated by the pipe | symbol. |
auth-group |
(optional) Specifies a list of groups that get access. Groups are listed in the password-type file. |
PathCheck fn=require-auth auth-type=basic realm="Marketing Plans" auth-group=mktg auth-users=(jdoe|johnd|janed) |
See set-variable.
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 ONE 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 no from parameter is specified.
The following table describes parameters for the set-virtual-index function.
Table 5–68 set-virtual-index Parameters
Parameter |
Description |
---|---|
URI of the content generator that acts as an index for the URI the user enters. |
|
(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. |
# MyLWApp is a LiveWire applicationPathCheck fn=set-virtual-index virtual-index=MyLWApp |
Applicable in PathCheck-class directives.
If a restriction is selected that is not consistent with the current cipher settings under Security Preferences, this function displays a warning that ciphers with larger secret key sizes 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 key size 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 key size 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 a value other than REQ_NOACTION.
The following table describes parameters for the ssl-check function.
Table 5–69 ssl-check parameters
Parameter |
Description |
---|---|
(Optional) Minimum number of bits required in the secret key |
|
(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 |
Applicable in PathCheck-class directives.
The ssl-logout function invalidates the current SSL session in the server’s SSL session cache. This function 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, the function returns REQ_NOACTION.
The following table describes the parameter for the ssl-logout function.
Table 5–70 ssl-logout parameters
Parameter |
Description |
---|---|
bucket |
(Optional) Common to all obj.conf functions |
Applicable in PathCheck-class directives.
UNIX Only. The unix-uri-clean function denies access to any resource whose physical path contains /./, /../ or //, which are potential security problems.
The following table describes the parameter for the unix-uri-clean function.
Table 5–71 unix-uri-clean parameters
Parameter |
Description |
---|---|
If present, “//” sequences are allowed |
|
bucket |
(Optional) Common to all obj.conf functions |
PathCheck fn=unix-uri-clean |
Applicable in PathCheck-class directives.
The url-check function checks the validity of URL syntax.
Applicable in PathCheck-class directives.
The url-filter can be used to allow or deny URL patterns. You can use either regular expressions of URL patterns or names of filter files of URLs as values for allow and deny parameters. The value names here refers to parameter names that were associated with filter files of URLs through init-url-filter SAF.
The following table describes the parameter for the url-filter function.
Table 5–72 url-filter Parameters
Parameter |
Description |
---|---|
allow |
Regular expression matching a URL pattern or name of a filter of URLs |
deny |
Regular expression matching a URL pattern or name of a filter of URLs |
bong-file |
Absolute path the custom error file (text or HTML) to be returned to the client |
PathCheck fn="url-filter" allow="filt1" deny=".*://.*.iplanet.com/.*" |
Applicable in PathCheck-class directives.
The user-agent-check can be used to restrict access to the proxy server based on the type and version of the client’s web browser. A regular expression to match the user-agent header sent from the client is passed as a parameter to this function.
The following table describes the parameter for the user-agent-check function.
Table 5–73 user-agent-check parameters
Parameter |
Description |
---|---|
ua |
Regular expression matching the user-agent header sent from the client to the proxy server |
PathCheck fn = "user-agent-check" ua="Mozilla/.*" |
ObjectType directives determine the MIME type of the file to send to the client in response to a request. MIME attributes currently sent are type, encoding, and language. The MIME type is sent to the client as the value of the Content-Type header.
ObjectType directives also set the type parameter, which is used by Service directives to determine how to process the request according to what kind of content is being requested.
If an object contains more than one ObjectType directive, all of the directives are applied in the order they appear. If a directive sets an attribute and later directives try to set that attribute to another value , the first setting is used and the subsequent settings are ignored.
The obj.conf file has an ObjectType directive that calls the type-by-extension function. This function instructs the server to look in the MIME types file to deduce the content type from the extension of the requested resource.
The following ObjectType-class functions are described in detail in this section:
block-auth-cert instructs the proxy server not to forward the client’s SSL/TLS certificate to remote servers.
block-cache-info instructs the proxy server not to forward information about local cache hits to remote servers.
block-cipher instructs the proxy server to forward the name of the client’s SSL/TLS cipher suite to remote servers.
block-ip instructs the proxy server not to forward the client’s IP address to remote servers.
block-issuer-dn instructs the proxy server not to forward the distinguished name of the issuer of the client’s SSL/TLS certificate to remote servers.
block-keysize instructs the proxy server not to forward the size of the client’s SSL/TLS key to remote servers.
block-proxy-auth instructs the proxy server not to forward the client’s proxy authentication credentials.
block-secret-keysize instructs the proxy server not to forward the size of the client’s SSL/TLS secret key to remote servers.
block-ssl-id instructs the proxy server not to forward the client’s SSL/TLS session ID to remote servers.
block-user-dn instructs the proxy server not to forward the distinguished name of the subject of the client’s SSL/TLS certificate to remote servers.
cache-disable disables cache.
cache-enable tells the proxy that an object is cacheable, based on specific criteria.
cache-setting sets parameters used for cache control.
force-type sets the Content-Type header for the response to a specific type.
forward-auth-cert instructs the proxy server to forward the client’s SSL/TLS certificate to remote servers.
forward-cache-info instructs the proxy server to forward information about local cache hits to remote servers.
forward-cipher instructs the proxy server to forward the name of the client’s SSL/TLS cipher suite to remote servers.
forward-ip instructs the proxy server to forward the client’s IP address to remote servers.
forward-issuer-dn instructs the proxy server to forward the distinguished name of the issuer of the client’s SSL/TLS certificate to remote servers.
forward-keysize instructs the proxy server to forward the size of the client’s SSL/TLS key to remote servers.
forward-proxy-auth instructs the proxy server to forward the client’s proxy authentication credentials
forward-secret-keysize instructs the proxy server to forward the size of the client’s SSL/TLS secret key to remote servers.
forward-ssl-id instructs the proxy server to forward the client’s SSL/TLS session ID to remote servers.
forward-user-dn instructs the proxy server to forward the distinguished name of the subject of the client’s SSL/TLS certificate to remote servers.
http-client-config configures the proxy server’s HTTP client.
java-ip-check allows clients to query the proxy server for the IP address used to reroute a resource.
match-browser matches specific strings in the User-Agent string supplied by the browser, and then modifies the behavior of Sun Java System Web Proxy Server based upon the results by setting values for specified variables.
set-basic-auth sets the HTTP basic authentication credentials used by the proxy server when it sends an HTTP request.
set-default-type enables you to define a default charset, content-encoding, and content-language for the response being sent back to the client.
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-hacktype requests that .htm and .html files are parsed for server-parsed HTML commands.
ssl-client-config configures options used when the proxy server connects to a remote server using SSL/TLS.
suppress-request-headers configures the proxy server to remove outgoing headers from the request.
type-by-exp sets the Content-Type header for the response based on the requested path.
type-by-extension sets the Content-Type header for the response based on the file’s extension and the MIME types database.
Applicable in ObjectType-class directives.
The block-auth-cert function instructs the proxy server not to forward the client’s SSL/TLS certificate to remote servers.
None.
Applicable in ObjectType-class directives.
The block-cache-info function instructs the proxy server not to forward information about local cache hits to remote servers.
None.
Applicable in ObjectType-class directives.
The block-cipher function instructs the proxy server to forward the name of the client’s SSL/TLS cipher suite to remote servers.
None.
Applicable in ObjectType-class directives.
The block-ip function instructs the proxy server not to forward the client’s IP address to remote servers.
None.
Applicable in ObjectType-class directives.
The block-issuer-dn function instructs the proxy server not to forward the distinguished name of the issuer of the client’s SSL/TLS certificate to remote servers.
None.
Applicable in ObjectType-class directives.
The block-keysize function instructs the proxy server not to forward the size of the client’s SSL/TLS key to remote servers.
None.
Applicable in ObjectType-class directives.
The block-proxy-auth function instructs the proxy server not to forward the client’s proxy authentication credentials, that is, the client’s Proxy-authorization HTTP request header, to remote servers.
None.
Applicable in ObjectType-class directives.
The block-secret-keysize function instructs the proxy server not to forward the size of the client’s SSL/TLS secret key to remote servers.
None.
Applicable in ObjectType-class directives.
The block-ssl-id function instructs the proxy server not to forward the client’s SSL/TLS session ID to remote servers.
None.
Applicable in ObjectType-class directives.
The block-user-dn function instructs the proxy server not to forward the distinguished name of the subject of the client’s SSL/TLS certificate to remote servers.
None.
Applicable in ObjectType-class directives.
The cache-disable function disables cache. It replaces the cache-enable function when cache is disabled through the administration interface.
ObjectType fn=cache-disable
None.
Applicable in ObjectType-class directives.
The cache_enable function tells the proxy that an object is cacheable, based on specific criteria. As an example, if the function appears in the object <Object ppath="http://.*">, then all the HTTP documents are considered cacheable, as long as other conditions for an object to be cacheable are met.
ObjectType fn=cache-enable cache-auth=0|1 query-maxlen=number min-size=number max-size=number log-report=feature cache-local=0|1
The following table describes the parameter for the cache-enable function.
Table 5–74 cache-enable Parameters
Parameter |
Description |
---|---|
cache-enable |
Tells the proxy that an object is cacheable. As an example, if it appears in the object <Object ppath="http://.*">, then all HTTP documents are considered cacheable as long as other conditions for an object to be cacheable are met. |
cache-auth |
Specifies whether to cache items that require authentication. If set to 1, pages that require authentication can be cached also. If not specified, defaults to 0. |
query-maxlen |
Specifies the number of characters in the query string the “?string” part at the end of the URL that are still cacheable. The same queries are rarely repeated exactly in the same form by more than one user, and so caching them is often not desirable. That’s why the default is 0. |
min-size |
The minimum size, in kilobytes, of any document to be cached. The benefits of caching are greatest with the largest documents. For this reason, some people prefer to cache only larger documents. |
max-size |
The maximum size in kilobytes of any document to be cached. This setting allows users to limit the maximum size of cached documents, so no single document can take up too much space. |
log-report |
Used to control the feature that reports local cache accesses back to the origin server so that content providers get their true access logs. |
cache-local |
Used to enable local host caching, that is, URLs without fully qualified domain names, in the proxy. If set to 1, local hosts are cached. If not specified, it defaults to 0, and local hosts are not cached. |
The following example of cache-enable allows you to enable caching of objects matching the current resource. This function applies to normal, non-query, non-authenticated documents of any size. The proxy requires that the document carries either last-modified or expires headers or both, and that the content-type reported by the origin server is accurate.
ObjectType fn=cache-enable
The example below is like the first example, but it also caches documents that require user authentication, and it caches queries up to five characters long. The cache-auth=1 indicates that an up-to-date check is always required for documents that need user authentication. This function forces authentication again.
ObjectType fn=cache-enable cache-auth=1 query-maxlen=5
The example below is also like the first example, except that it limits the size of cache files to a range of 2 Kbytes to 1 Mbytes.
ObjectType fn=cache-enable min-size=2 max-size=1000
Applicable in ObjectType-class directives.
cache-setting is an ObjectType function that sets parameters used for cache control.
This function is used to explicitly cache or not cache a resource, create an object for that resource, and set the caching parameters for the object.
ObjectType fn=cache-setting max-uncheck=seconds lm-factor=factor connect-mode=always|fast-demo|never cover-errors=number
The following table describes the parameter for the cache-setting function.
Table 5–75 cache-setting Parameters
Parameter |
Description |
---|---|
connect-mode |
Specifies network connectivity and can be set to these values:
|
cover-errors |
If present and greater than 0, returns a document from the cache if the remote server is down and an up-to-date check cannot be made. The value specified is the maximum number of seconds since the last up-to-date check; if more time has elapsed, an error is returned. Using this feature involves the risk of getting stale data from the cache while the remote server is down. Setting this value to 0, or not specifying it (default) causes an error to be returned if the remote server is unavailable. |
ignore-no-cache |
If present and greater than 0, a pragma: no-cache header from the remote server is ignored and the response is cached. The default value is 0. This behavior violates the HTTP standard. |
ignore-no-store |
If present and greater than 0, a Cache-control: no-store header from the remote server is ignored and the response is cached. The default value is 0. This behavior violates the HTTP standard. |
ignore-private |
If present and greater than 0, a Cache-control: private header from the remote server is ignored and the response is cached. The default value is 0. This behavior violates the HTTP standard. |
ignore-reload |
If present and greater than 0, a pragma: no-cache or cache-control: no-cache header from the client is ignored and the request is served from the cache. The default value is 0. This behavior violates the HTTP standard. |
lm-factor |
(optional)A floating-point number representing the factor used in estimating expiration time, which is how long a document might be up to date based on the time it was last modified. The time elapsed since the last modification is multiplied by this factor. The result gives the estimated time the document is likely to remain unchanged. Specifying a value of 0 turns off this function. The caching system then uses only explicit expiration information which is rarely available. Only explicit Expires HTTP headers are used. This value has no effect if max-uncheck is set to 0. |
max-uncheck |
(Optional) Is the maximum time in seconds allowed between consecutive up-to-date checks. If set to 0 (default), a check is made every time the document is accessed, and the lm-factor has no effect. |
min-uncheck |
Is the minimum time in seconds allowed between consecutive up-to-date checks of a cached document. The default value is 0. This behavior violates the HTTP standard. |
override-expire |
If present and greater than 0, min-uncheck is enforced over the value of an Expires:header. The default value is 0. This behavior violates the HTTP standard. |
override-lastmod |
If present and greater than 0, min-uncheck is enforced over the value of a Last-modified header. The default value is 0. This behavior violates the HTTP standard. |
reload-into-ims |
If present and greater than 0, reload request from clients are converted into conditional GET requests with an If-modified-since header. The default value is 1. This behavior violates the HTTP standard. |
require-expires |
If present and greater than 0, a response without an Expires header will not be cached. The default value is 1. This behavior violates the HTTP standard. |
term-percent |
Indicates that the server should keep retrieving data if more than the specified percentage of the document has already been retrieved. |
without-lastmod |
If present and greater than 0, the absence of a Last-modified header is ignored and the response cached. The default value is 0. This behavior violates the HTTP standard. |
<Object ppath="http://.*"> ObjectType fn=cache-enable ObjectType fn=cache-setting max-uncheck="7200" ObjectType fn=cache-setting lm-factor="0.020" ObjectType fn=cache-setting connect-mode="fast-demo" ObjectType fn=cache-setting cover-errors="3600" Service fn=proxy-retrieve </Object> # Force check every time ObjectType fn=cache-setting max-uncheck=0 # Check every 30 minutes, or sooner if changed less than # 6 hours ago (factor 0.1; last change 1 hour ago would # give 6-minute maximum check interval). ObjectType fn=cache-setting max-uncheck=1800 lm-factor=0.1 |
Applicable in ObjectType-class directives.
The force-type function assigns a type to requests that do not already have a MIME type. This function is used to specify a default object type.
Make sure that the directive that calls this function comes last in the list of ObjectType directives, so that all other ObjectType directives have a chance to set the MIME type first. If an object contains more than one ObjectType directive all of the directives are applied in the order they appear. If a directive sets an attribute and later directives try to set that attribute to a different value, the first setting is used and the subsequent settings are ignored.
The following table describes the parameter for the force-type function.
Table 5–76 force-type parameters
Parameter |
Description |
---|---|
(Optional) Type assigned to a matching request (the Content-Type header). |
|
(Optional) Encoding assigned to a matching request (the Content-Encoding header). |
|
(Optional) Language assigned to a matching request (the Content-Language header). |
|
(Optional) Character set for the magnus-charset parameter in rq->srvhdrs. If the browser sent the Accept-Charset header or its User-Agent is MozillaTM /1.1 or newer, then append “; charset=charset” to content-type, where charset is the value of the magnus-charset parameter in rq->srvhdrs. |
|
bucket |
(Optional) Common to all obj.conf functions. |
ObjectType fn=force-type type=text/plain ObjectType fn=force-type lang=en_US |
type-by-extension, type-by-exp
Applicable in ObjectType-class directives.
The forward-auth-cert function instructs the proxy server to forward the client’s SSL/TLS certificate to remote servers.
The following table describes the parameter for the forward-auth-cert function.
Table 5–77 forward-auth-cert Parameters
Parameter |
Description |
---|---|
hdr |
(Optional) Name of the HTTP request header used to communicate the client’s DER-encoded SSL/TLS certificate in Base64 encoding. The default is Proxy-auth-cert. |
Applicable in ObjectType-class directives.
The forward-cache-info function instructs the proxy server to forward information about local cache hits to remote servers.
The following table describes the parameter for the forward-cache-info function.
Table 5–78 forward-cache-info Parameters
Parameter |
Description |
---|---|
hdr |
(Optional) Name of the HTTP request header used to communicate information about local cache hits. The default is Cache-info. |
Applicable in ObjectType-class directives.
The forward-cipher function instructs the proxy server to forward the name of the client’s SSL/TLS cipher suite to remote servers.
The following table describes the parameter for the forward-cipher function.
Table 5–79 forward-cipher Parameters
Parameter |
Description |
---|---|
hdr |
(Optional) Name of the HTTP request header used to communicate the name of the client’s SSL/TLS cipher suite. The default is Proxy-cipher. |
Applicable in ObjectType-class directives.
The forward-ip function instructs the proxy server to forward the client’s IP address to remote servers.
The following table describes the parameter for the forward-ip function.
Table 5–80 forward-ip Parameters
Parameter |
Description |
---|---|
hdr |
(Optional) Name of the HTTP request header used to communicate the client’s IP address. The default is Client-ip. |
Applicable in ObjectType-class directives.
The forward-issuer-dn function instructs the proxy server to forward the distinguished name of the issuer of the client’s SSL/TLS certificate to remote servers.
The following table describes the parameter for the forward-issuer-dn function.
Table 5–81 forward-issuer-dn
Parameter |
Description |
---|---|
hdr |
(Optional) Name of the HTTP request header used to communicate the distinguished name of the issuer of the client’s SSL/TLS certificate. The default is Proxy-issuer-dn. |
Applicable in ObjectType-class directives.
The forward-keysize function instructs the proxy server to forward the size of the client’s SSL/TLS key to remote servers.
The following table describes the parameter for the forward-keysize function.
Table 5–82 forward-keysize
Parameter |
Description |
---|---|
hdr |
(Optional) Name of the HTTP request header used to communicate the size of the client’s SSL/TLS key. The default is Proxy-keysize. |
Applicable in ObjectType-class directives.
The forward-proxy-auth instructs the proxy server to forward the client’s proxy authentication credentials, that is, the client’s Proxy-authorization HTTP request header, to remote servers.
None.
Applicable in ObjectType-class directives.
The forward-secret-keysize function instructs the proxy server to forward the size of the client’s SSL/TLS secret key to remote servers.
The following table describes the parameter for the forward-secret-keysize function.
Table 5–83 forward-secret-keysize Parameters
Parameter |
Description |
---|---|
hdr |
(Optional) Name of the HTTP request header used to communicate the size of the client’s SSL/TLS secret key. The default is Proxy-secret-keysize. |
Applicable in ObjectType-class directives.
The forward-ssl-id function instructs the proxy server to forward the client’s SSL/TLS session ID to remote servers.
The following table describes the parameter for the forward-ssl-id function.
Table 5–84 forward-ssl-id Parameters
Parameter |
Description |
---|---|
hdr |
(Optional) Name of the HTTP request header used to communicate the client’s SSL/TLS session ID. The default is Proxy-ssl-id. |
Applicable in ObjectType-class directives.
The forward-user-dn function instructs the proxy server to forward the distinguished name of the subject of the client’s SSL/TLS certificate to remote servers.
The following table describes the parameter for the forward-user-dn function.
Table 5–85 forward-user-dn Parameters
Parameter |
Descrioption |
---|---|
hdr |
(Optional) Name of the HTTP request header used to communicate the distinguished name of the subject of the client’s SSL/TLS certificate. The default is Proxy-user-dn. |
Applicable in ObjectType-class directives.
The http-client-config function configures the proxy server’s HTTP client.
The following table describes the parameter for the http-client-config function.
Table 5–86 http-client-config Parameters
Parameter |
Description |
---|---|
keep-alive |
(Optional) Boolean that indicates whether the HTTP client should attempt to use persistent connections. The default is true. |
keep-alive-timeout |
(Optional) The maximum number of seconds to keep a persistent connection open. The default is 29. |
always-use-keep-alive |
(Optional) Boolean that indicates whether the HTTP client can reuse existing persistent connections for all types of requests. The default is false, meaning persistent connections will not be reused for non-GET requests nor for requests with a body. |
protocol |
(Optional) HTTP protocol version string. By default, the HTTP client uses either "HTTP/1.0" or "HTTP/1.1" based on the contents of the HTTP request. Do not use the protocol parameter unless you encounter specific protocol interoperability problems. |
proxy-agent |
(Optional) Value of the Proxy-agent HTTP request header. The default is a string that contains the proxy server product name and version. |
Applicable in ObjectType-class directives.
The java-ip-check function enables clients to query the proxy server for the IP address used to reroute a resource. Because DNS spoofing often occurs with Java applets, this feature enables clients to see the true IP address of the origin server. When this feature is enabled, the proxy server attaches a header containing the IP address that was used for connecting to the destination origin server.
Syntax
ObjectType fn=java-ip-check status=on|off
Parameters
The following table describes the parameter for the java-ip-check function.
Table 5–87 java-ip-check Parameters
Parameter |
Description |
---|---|
status |
Specifies whether Java IP address checking is enabled. Possible values are:
|
See match-browser.
Applicable in ObjectType-class directives.
The set-basic-auth function sets the HTTP basic authentication credentials used by the proxy server when it sends an HTTP request. set-basic-auth can be used to authenticate to a remote origin server or proxy server.
The following table describes the parameter for the set-basic-auth function.
Table 5–88 set-basic-auth Parameters
Parameter |
Description |
---|---|
user |
To authenticate user |
password |
The user’s password |
hdr |
(Optional) Name of the HTTP request header used to communicate the credentials |
Applicable in ObjectType-class directives.
The set-default-type function enables you to define a default charset, content-encoding, and content-language for the response being sent back to the client.
If the charset, content-encoding, and content-language have not been set for a response, then just before the headers are sent the defaults defined by set-default-type are used. By placing this function in different objects in obj.conf, you can define different defaults for different parts of the document tree.
The following table describes the parameter for the set-default-type function.
Table 5–89 set-default-type Parameters
Parameter |
Description |
---|---|
(Optional) Encoding assigned to a matching request (the Content-Encoding header). |
|
(Optional) Language assigned to a matching request (the Content-Language header). |
|
(Optional) Character set for the magnus-charset parameter in rq->srvhdrs. If the browser sent the Accept-Charset header or its User-agent is Mozilla/1.1 or newer, then append “; charset=charset” to content-type, where charset is the value of the magnus-charset parameter in rq->srvhdrs. |
|
bucket |
(Optional) Common to all obj.conf functions. |
ObjectType fn="set-default-type" charset="iso_8859-1" |
See set-variable.
Applicable in ObjectType-class directives.
The shtml-hacktype function changes the Content-Type of any .htm or .html file to magnus-internal/parsed-html and returns REQ_PROCEED. This function provides backward compatibility with server-side includes for files with .htm or .html extensions. The function can also check the execute bit for the file on UNIX systems. The use of this function is not recommended.
The following table describes the parameter for the shtml-hacktype function.
Table 5–90 shtml-hacktype Parameters
Parameter |
Description |
---|---|
(UNIX only, optional) Indicates that the function should change the content-type only if the execute bit is enabled. The value of the parameter is not important; it need only be provided. You may use exec-hack=true. |
|
bucket |
(Optional) Common to all obj.conf functions. |
ObjectType fn=shtml-hacktype exec-hack=true |
Applicable in ObjectType-class directives.
The ssl-client-config function configures options used when the proxy server connects to a remote server using SSL/TLS.
The following table describes the parameter for the ssl-client-config function.
Table 5–91 ssl-client-config Parameters
Parameter |
Description |
---|---|
client-cert-nickname |
(Optional) Nickname of the client certificate to present to the remote server. The default is not to present a client certificate. |
validate-server-cert |
(Optional) Boolean that indicates whether the proxy server validates the certificate presented by the remote server. The default is false, meaning the proxy server will accept any certificate. |
Applicable in ObjectType-class directives.
The type-by-exp function matches the current path with a wildcard expression. If the two match, the type parameter information is applied to the file. This function is the same as type-by-extension except that you use wildcard patterns for the files or directories specified in the URLs.
The following table describes the parameter for the type-by-exp function.
Table 5–92 type-by-exp Parameters
Parameter |
Description |
---|---|
Wildcard pattern of paths for which this function is applied. |
|
(Optional) Type assigned to a matching request (the Content-Type header). |
|
(Optional) Encoding assigned to a matching request (the Content-Encoding header). |
|
(Optional) Language assigned to a matching request (the Content-Language header). |
|
(Optional) The character set for the magnus-charset parameter in rq->srvhdrs. If the browser sent the Accept-Charset header or its User-Agent is Mozilla/1.1 or newer, then append “; charset=charset” to content-type, where charset is the value of the magnus-charset parameter in rq->srvhdrs. |
|
bucket |
(Optional) Common to all obj.conf functions. |
ObjectType fn=type-by-exp exp=*.test type=application/html |
Applicable in ObjectType-class directives.
The type-by-extension function instructs the server to look in a table of MIME type mappings to find the MIME type of the requested resource according to the extension of the requested resource. The MIME type is added to the Content-Type header sent back to the client.
The table of MIME type mappings is created by a MIME element in the server.xml file, which loads a MIME types file or list and creates the mappings. For more information about server.xml , see Chapter 2, Server Configuration Elements in the server.xml file.
For example, the following two lines are part of a MIME types file:
type=text/html exts=htm,htmltype=text/plain exts=txt |
If the extension of the requested resource is htm or html, the type-by-extension file sets the type to text/html. If the extension is .txt, the function sets the type to text/plain.
The following table describes the parameter for the type-by-extension function.
Table 5–93 type-by-extension Parameters
Parameter |
Description |
---|---|
bucket |
(Optional) Common to all obj.conf functions. |
ObjectType fn=type-by-extension |
All Input directives are executed when the server or a plug-in first attempts to read entity body data from the client.
The Input stage enables you to select filters that will process incoming request data read by the Service step.
NSAPI filters in Sun Java System Web Proxy Server 4 enable a function to intercept (and potentially modify) the content presented to or generated by another function.
You can add NSAPI filters that process incoming data by invoking the insert-filter SAF in the Input stage of the request-handling process. The Input directives are executed at most once per request.
You can also define the appropriate position of a specific filter within the filter stack. For example, filters that translate content from XML to HTML are placed higher in the filter stack than filters that compress data for transmission. You can use the filter_create function to define the filter’s position in the filter stack, and the init-filter-order to override the defined position.
When two or more filters are defined to occupy the same position in the filter stack, filters that were inserted later will appear higher than filters that were inserted earlier. The order of Input fn="insert-filter" and Output fn="insert-filter" directives in obj.conf is important.
The following Input-class functions are described in detail in this section:
insert-filter adds a filter to the filter stack to process incoming data.
match-browser matches specific strings in the User-Agent string supplied by the browser, and then modifies the behavior of the Sun Java System Web Proxy Server based upon the results by setting values for specified variables.
remove-filter removes a filter from the filter stack.
sed-request applies the sed edit commands to an incoming request entity body.
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.
Applicable in Input-class directives.
The insert-filter SAF is used to add a filter to the filter stack to process incoming (client-to-server) data.
The order of Input fn="insert-filter" and Output fn="insert-filter" directives can be important.
Returns REQ_PROCEED if the specified filter was inserted successfully or REQ_NOACTION if the specified filter was not inserted because it was not required. Any other return value indicates an error.
The following table describes the parameter for the insert-filter function.
Table 5–94 insert-filter Parameters
Parameter |
Description |
---|---|
Specifies the name of the filter to insert. |
|
bucket |
(Optional) Common to all obj.conf functions. |
Input fn="insert-filter" filter="http-decompression" |
See match-browser.
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. You do not have to remove filters with remove-filter because they will be removed automatically at the end of the request.
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.
The following table describes the parameter for the remove-filter function.
Table 5–95 remove-filter Parameters
Parameter |
Description |
---|---|
filter |
Specifies the name of the filter to remove. |
bucket |
(Optional) Common to all obj.conf functions. |
Input fn="remove-filter" filter="http-compression" |
The sed-request filter applies the sed edit commands to an incoming request entity body, for example, an uploaded file or submitted form.
The following table shows the sed-request parameters:
Table 5–96 sed-request Parameters
Parameter |
Description |
---|---|
Specifies a sed command script. When multiple sed parameters are provided, the sed edit commands are evaluated in the order they appear. |
The following obj.conf code instructs sed-request to encode any (<) and (>) characters posted in an HTML form:
Input fn="insert-filter" method="POST" filter="sed-request" sed="s/</\\</g" sed="s/%3c/\\</g" sed="s/%3C/\\</g" sed="s/>/\\>/g" sed="s/%3e/\\>/g" sed="s/%3E/\\>/g"
Because POST bodies are usually URL-encoded, it is important to check for URL-encoded forms when editing POST bodies. %3C is the URL-encoded form of (<) and %3E is the URL-encoded form of (>).
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.
All Output directives are executed when the server or a plug-in first attempts to write entity body data from the client.
The Output stage enables you to select filters that will process outgoing data.
You can add NSAPI filters that process outcoming data by invoking the insert-filter SAF in the Output stage of the request-handling process. The Output directives are executed at most once per request.
You can define the appropriate position of a specific filter within the filter stack. For example, filters that translate content from XML to HTML are placed higher in the filter stack than filters that compress data for transmission. You can use the filter_create function to define the filter’s position in the filter stack, and the init-filter-order to override the defined position.
When two or more filters are defined to occupy the same position in the filter stack, filters that were inserted later will appear higher than filters that were inserted earlier.
The following Output-class functions are described in detail in this section:
content-rewrite rewrites the string in the document that is being sent to the client.
insert-filter adds a filter to the filter stack to process outgoing data.
match-browser matches specific strings in the User-Agent string supplied by the browser, and then modifies the behavior of the Sun Java System Web Proxy Server based upon the results by setting values for specified variables.
remove-filter removes a filter from the filter stack.
sed-response applies the sed edit commands to an outgoing response entity body.
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.
The content-rewrite function rewrites the string in the document that is being sent to the client.
When a document is sent by the proxy server, the content-rewrite function is invoked if it has been configured and would replace the from string/url to destination string/url before sending the response to the client.
The patterns are strings that would be replaced in the outgoing document. The pattern can be either a URL with absolute or relative links, or any text string such as the server name and the like.
Output fn="insert-filter" filter="content-rewrite" type="text/html" from="<sourcepattern>" to="<destpattern>"
The following table describes the parameter for the content-rewrite function.
Table 5–97 content-rewrite Parameters
Parameter |
Description |
---|---|
filter |
Specifies the name of the filter to be executed. |
type |
Indicates the content-type on which this filter is applied, for example, text, html, and so on. |
Output fn="insert-filter" type="text/*" filter="content-rewrite" from="iPlanet" to="Sun ONE (now called) Sun Java System Web Server" |
Applicable in Output-class directives.
The insert-filter SAF is used to add the content rewriting engine to the filter stack to process outgoing server-to-client data.
This directive should appear in the http://.* and https://.* objects inside of the obj.conf file.
The insert-filter SAF will result in rewriting if the request had been associated with a filter by um-ntrans (See um-ntrans).
The order of Input fn="insert-filter" and Output fn="insert-filter" directives can be important.
Returns REQ_PROCEED if the specified filter was inserted successfully, or REQ_NOACTION if the specified filter was not inserted because it was not required. Any other return value indicates an error.
The following table describes the parameter for the insert-filter function.
Table 5–98 insert-filter parameters
Parameter |
Description |
---|---|
filter |
Specifies the name of the filter to insert. Must be set to "um-output". |
bucket |
(Optional) Common to all obj.conf functions. |
type |
Specifies the MIME types to which the filter will be applied. It can be omitted, as the filter makes its own choices about what types of content to filter. If it is provided, it should be set to "*". |
Output fn="insert-filter" filter="um-output" |
See match-browser.
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. You do not have to remove filters with remove-filter, as they will be removed automatically at the end of the request.
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.
The following table describes the parameter for the remove-filter function.
Table 5–99 remove-filter Parameters
Parameter |
Description |
---|---|
filter |
Specifies the name of the filter to remove. |
bucket |
(Optional) Common to all obj.conf functions. |
Output fn="remove-filter" filter="http-compression" |
The sed-response filter applies sed edit commands to an outgoing response entity body, for example, an HTML file or output from a Servlet.
The following table describes parameter for the sed-response filter
Table 5–100 sed-response Parameter
Parameter |
Description |
---|---|
Specifies a sed command script. When multiple sed parameters are provided, the sed edit commands are evaluated in the order they appear. |
The following obj.conf code instructs sed-response to rewrite any occurrence of http://127.0.0.1/ in an HTML response to http://server.example.com/:
Output fn="insert-filter" type="text/html" filter="sed-response" sed="s|http://127.0.0.1/|http://server.example.com/|g"
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.
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.
(Optional) Specifies a wildcard pattern of HTTP methods for which this function will be executed. Common HTTP methods are GET, HEAD, and POST.
(Optional) Specifies a wildcard pattern of query strings for which this function will be executed.
(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.
(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.
(Optional) Determines the default buffer size, in bytes, for “un-chunking” request data. If this parameter is not specified, the default is 8192 bytes.
(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 Sun Java System Web Proxy Server 4.0.11 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 the Sun Java System Web 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.
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.
The following table describes parameters for the add-footer function.
Table 5–101 add-footer Parameters
Parameter |
Description |
---|---|
(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. |
|
(Optional) URI pointing to the resource containing the footer. Specify either file or uri. |
|
(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. |
|
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. |
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" |
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.
The following table describes parameters for the add-header function.
Table 5–102 add-header parameters
Parameter |
Description |
---|---|
(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. |
|
(Optional) URI pointing to the resource containing the header. Specify either file or uri. |
|
(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. |
|
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. |
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" |
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.
The following table describes the parameters specific to the append-trailer function.
Table 5–103 append-trailer Parameters
Parameter |
Description |
---|---|
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. |
|
(Optional) Time format string for :LASTMOD:. If timefmt is not provided, :LASTMOD: will not be replaced with the time. |
|
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. |
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 deny-service.
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.
The imagemap function has no specific parameters.
Table 5–104 imagemap Parameters
Parameter |
Description |
---|---|
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. |
Service method=(GET|HEAD) fn=imagemap |
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
Table 5–105 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 |
The following table describes the parameters specific to the index-common function.
Table 5–106 index-common parameters
Parameter |
Description |
---|---|
(Optional) Path relative to the directory being indexed and name of an HTML or plain file 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 that name is found, the file is incorporated near the top of the directory list as HTML. If the file name is not found, it is tried without the .html and incorporated as preformatted plain text bracketed by <PRE> and </PRE> tags. |
|
(Optional) Path relative to the directory being indexed and name of an HTML or plain text file to append to the directory listing. This file might give more information about the contents of the directory, or indicate copyrights, authors, or other information. The file is first tried with .html added to the end. If that name is found, the file is incorporated at the bottom of the directory list as HTML. If the file name is not found, it is tried without the .html and incorporated as preformatted plain text bracketed by <PRE> and </PRE> tags. |
|
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. |
Service fn=index-common method=(GET|HEAD) header=hdr readme=rdme.txt |
index-simple, find-index, home-page
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.
The index-simple function has no specific parameters.
Table 5–107 index-simple Parameters
Parameter |
Description |
---|---|
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. |
Service fn=index-simple |
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.
The key-toosmall function has no specific parameters.
Table 5–108 key-toosmall Parameters
Parameter |
Description |
---|---|
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. |
<Object ppath=/mydocs/secret/*>Service fn=key-toosmall</Object> |
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.
The list-dir function has no specific parameters.
Table 5–109 list-dir Parameters
Parameter |
Description |
---|---|
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. |
Service fn=list-dir method="INDEX" |
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.
The fmake-dir function has no specific parameters.
Table 5–110 make-dir Parameters
Parameter |
Description |
---|---|
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. |
Service fn="make-dir" method="MKDIR" |
See match-browser.
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.
Service fn=proxy-retrieve method=GET|HEAD|POST|INDEX|CONNECT... allow|block=<List-of-comma-separated-methods>
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.
# 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" |
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.
The following table describes the path parameter which is specific to the query-handler function.
Table 5–111 query-handler parameters
Parameter |
Description |
---|---|
path |
Full path and file name of the CGI program to run. |
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. |
Service query=* fn=query-handler path=/http/cgi/do-grep Service query=* fn=query-handler path=/http/cgi/proc-info |
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.
The remove-dir function has no specification parameter.
Table 5–112 remove-dir Parameters
Parameter |
Description |
---|---|
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. |
Service fn="remove-dir" method="RMDIR" |
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.
The remove-file function has no specification parameter.
Table 5–113 remove-file Parameters
Parameter |
Description |
---|---|
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. |
Service fn="remove-file" method="DELETE" |
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 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.
The following table describes the filter parameters which is specific to the remove-filter function.
Table 5–114 remove-filter Parameters
Parameter |
Description |
---|---|
filter |
Specifies the name of the filter to remove. |
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. |
Service fn="remove-filter" filter="http-compression" |
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.
The rename-file function has no specification parameter.
Table 5–115 rename-file Parameters
Parameter |
Description |
---|---|
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. |
Service fn="rename-file" method="MOVE" |
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.
The following table describes the path parameter, which is specific to the send-error function.
Table 5–116 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. |
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. |
Error fn=send-error code=401 path=/sun/server61/docs/errors/401.html |
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.
The following table describes the nocache parameter, which is specific to the send-file function.
Table 5–117 send-file parameters
Parameter |
Description |
---|---|
(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 want to use this parameter, do not include it. |
|
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. |
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> |
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.
The following table describes parameters for the send-range function.
Table 5–118 send-range parameters
Parameter |
Description |
---|---|
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. |
Service fn=send-range |
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 Sun Java System Web Proxy Server 4.0.11 NSAPI Developer’s Guide.
The send-shellcgi function has no specification parameter.
Table 5–119 send-shellcgi Parameters
Parameter |
Description |
---|---|
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 |
Service fn=send-shellcgi |
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 Proxy Server 4.0.11 NSAPI Developer’s Guide.
The send-wincgi function has no specification parameter.
Table 5–120 send-wincgi Parameters
Parameter |
Description |
---|---|
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. |
Service fn=send-wincgi |
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
The following table describes the parameter, which is specific to the service-dump function.
Table 5–121 service-dump Parameters
Parameter |
Description |
---|---|
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. |
<Object name=default>NameTrans fn="assign-name" from="/.perf" name="perf"...</Object><Object name=perf>Service fn="service-dump"</Object> |
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.
The service-j2ee function has no specification parameter.
Table 5–122 service-j2ee Parameters
Parameter |
Description |
---|---|
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. |
<Object name=default> NameTrans fn="ntrans-j2ee" name="j2ee" ... </Object> <Object name=j2ee> Service fn="service-j2ee" </Object> |
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.
The service_trace function has no specification parameter.
Table 5–123 service-trace Parameters
Parameter |
Description |
---|---|
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. |
<Object name="default"> ... Service method="TRACE" fn="service-trace" ... </Object> |
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.
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.
The following table describes the parameters specifies to the shtml_send function.
Table 5–124 shtml-send Parameters
Parameter |
Description |
---|---|
Maximum depth of include nesting allowed. The default value is 10. |
|
(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. |
|
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. |
Service method=(GET|HEAD) fn=shtml_send |
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
The stats-xml function.
Table 5–125 stats-xml Parameters
Parameter |
Description |
---|---|
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. |
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> |
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.
The upload-file function.
Table 5–126 upload-file Parameters
Parameter |
Description |
---|---|
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. |
Service fn=upload-file |
After the server has responded to the request, the AddLog directives are executed to record information about the transaction.
If an object contains more than one AddLog directive, all are executed.
The following AddLog-class functions are described in detail in this section:
common-log records information about the request in the common log format.
flex-log records information about the request in a flexible, configurable format.
match-browser matches specific strings in the User-Agent string supplied by the browser, and then modifies the behavior of the Sun Java System Web Proxy Server based upon the results by setting values for specified variables.
record-useragent records the client’s IP address and User-Agent header.
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.
Applicable in AddLog-class directives.
The common-log function records request-specific data in the common log format used by most HTTP servers. A log analyzer is locatedin the /extras/log_anly directory for Proxy Server.
The common log must have been initialized previously by the init-clf function. For information about rotating logs, see flex-rotate-init in the Sun Java System Web Proxy Server 4.0.11 NSAPI Developer’s Guide.
There are also a number of free statistics generators for the common log format.
The following table describes parameters for the common-log function.
Table 5–127 common-log Parameters
Parameter |
Description |
---|---|
name |
(Optional) Provides the name of a log file which must have been given as a parameter to the init-clf function in magnus.conf. If no name is given, the entry is recorded in the global log file. |
(Optional) Instructs the server to log the IP address of the remote client rather than looking up and logging the DNS name. This function improves performance if DNS is off in the magnus.conf file. The value of iponly has no significance, and merely must be present, for example, iponly=1. |
|
bucket |
(Optional) Common to all obj.conf functions. |
# Log all accesses to the global log file AddLog fn=common-log # Log accesses from outside our subnet (198.93.5.*) to nonlocallog <Client ip="*~198.93.5.*"> AddLog fn=common-log name=nonlocallog</Client> |
Applicable in AddLog-class directives.
The flex-log function records request-specific data in a flexible log format. This function may also record requests in the common log format. A log analyzer is located in the /extras/flexanlg directory for the Sun Java System Web Proxy Server.
There are also a number of free statistics generators for the common log format.
The log format is specified by the flex-init function call. For information about rotating logs, see flex-rotate-init in the Sun Java System Web Proxy Server 4.0.11 NSAPI Developer’s Guide.
The following table describes parameters for the flex-log function.
Table 5–128 flex-log Parameters
Parameter |
Description |
---|---|
(Optional) Provides the name of a log file, which must have been given as a parameter to the flex-init function in magnus.conf. If no name is given, the entry is recorded in the global log file. |
|
(Optional) Instructs the server to log the IP address of the remote client rather than looking up and logging the DNS name. This function improves performance if DNS is off in the magnus.conf file. The value of iponly has no significance, and merely must br present, for example, iponly=1. |
|
bucket |
(Optional) Common to all obj.conf functions. |
Specifies the number of buffers for a given log file. The default value is determined by the server. Access log entries can be logged in chronological order by using a single buffer per log file. Add buffers-per-file=1 to the Init fn=flex-init line in magnus.conf. This setting ensures that requests are logged in chronological order. This approach results in decreased performance when the server is under heavy load. |
# Log all accesses to the global log file AddLog fn=flex-log # Log accesses from outside our subnet (198.93.5.*) to nonlocallog <Client ip="*~198.93.5.*"> AddLog fn=flex-log name=nonlocallog</Client> |
See match-browser.
Applicable in AddLog-class directives.
The record-useragent function records the IP address of the client, followed by its User-Agent HTTP header. This value indicates what version of the client was used for this transaction.
The following table describes parameters for the record-useragent function.
Table 5–129 record-useragent Parameters
Parameter |
Description |
---|---|
name |
(Optional) Provides the name of a log file, which must have been given as a parameter to the init-clf function in magnus.conf. If no name is given, the entry is recorded in the global log file. |
bucket |
(Optional) Common to all obj.conf functions. |
# Record the client ip address and user-agent to browserlogAddLog fn=record-useragent name=browserlog |
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.
If a Server Application Function results in an error, it sets the HTTP response status code and returns the value REQ_ABORTED. The server then stops processing the request. Instead, the server searches for an Error directive matching the HTTP response status code or its associated reason phrase, and executes the directive’s function. If the server does not find a matching Error directive, it returns the response status code to the client.
The following Error-class functions are described in detail in this section:
error-j2ee handles errors that occur during execution of the Java 2 Platform Enterprise Edition (J2EETM platform) applications and modules deployed to the Sun Java System Web Proxy Server. This function is applicable only to the Administration Server.
match-browser matches specific strings in the User-Agent string supplied by the browser, and then modifies the behavior of the Sun Java System Web Proxy Server based upon the results by setting values for specified variables.
query-handler runs a CGI program instead of referencing the path requested.
remove-filter removes a filter from the filter stack.
send-error sends an HTML file to the client in place of a specific HTTP response status.
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.
This function is applicable only to the Administration Server.
Applicable in Error-class directives.
The error-j2ee function handles errors that occur during execution of web applications deployed to the Sun Java System Web Proxy Server individually or as part of full J2EE applications.
The following table describes the parameter for the error-j2ee function.
Table 5–130 error-j2ee Parameters
Parameter |
Description |
---|---|
bucket |
(Optional) Common to all obj.conf functions. |
See match-browser.
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.
The following table describes parameters for the query-handler function.
Table 5–131 query-handler Parameters
Parameter |
Description |
---|---|
path |
Full path and file name of the CGI program to run. |
(Optional) Text of one of the reason strings such as “Unauthorized” or “Forbidden”. The string is not case sensitive. |
|
(Optional) Three-digit number representing the HTTP response status code, such as 401 or 403. This number can be any HTTP response status code or reason phrase according to the HTTP specification. The common HTTP response status codes and reason strings are:
|
|
bucket |
(Optional) Common to all obj.conf functions. |
Error query=* fn=query-handler path=/http/cgi/do-grep Error query=* fn=query-handler path=/http/cgi/proc-info |
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 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.
The following table describes parameters for the remove-filter function.
Table 5–132 remove-filter Parameters
Parameter |
Description |
---|---|
filter |
Specifies the name of the filter to remove. |
bucket |
(Optional) Common to all obj.conf functions. |
Error fn="remove-filter" filter="http-compression" |
Applicable in Error-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.
The send-error function can be used to configure messages from the proxy server only and does not work for configuring messages in place of HTTP responses from web server.
The following table describes parameters for the send-error function.
Table 5–133 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. |
(Optional) Text of one of the reason strings such as “Unauthorized” or “Forbidden”. The string is not case sensitive. |
|
(Optional) Three-digit number representing the HTTP response status code, such as 401 or 403. This number can be any HTTP response status code or reason phrase according to the HTTP specification. The common HTTP response status codes and reason strings are:
|
|
bucket |
(Optional) Common to all obj.conf functions. |
Error fn=send-error code=401 path=/sun/server61/docs/errors/401.html |
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.
The Connect directive calls the connect function you specify.
Connect fn=your-connect-function
Only the first applicable Connect function is called, starting from the most restrictive object. Occasionally you might want to call multiple functions until a connection is established. The function returns REQ_NOACTION if the next function should be called. If the function fails to connect, the return value is REQ_ABORT. If the function connects successfully, the connected socket descriptor will be returned.
The Connect function must have this prototype:
int your_connect_function(pblock *pb, Session *sn, Request *rq);
Connect receives its destination host name and port number from:
pblock_findval (“connect-host”, rq->vars) atoi (pblock_findval (“connect-port”, rq->vars))
The host can be in a numeric IP address format.
To use the NSAPI custom DNS class functions to resolve the host name, make a call to this function:
struct hostent *servact_gethostbyname(char *host name, Session *sn, Request *rq);
This example uses the native connect mechanism to establish the connection:
#include "base/session.h" #include "frame/req.h" #include <ctype.h> #include <sys/types.h> #include <sys/socket.h> #include <netinet/in.h> #include <netdb.h> int my_connect_func(pblock *pb, Session *sn, Request *rq) { struct sockaddr_in sa; int sd; memset(&sa, 0, sizeof(sa)); sa.sin_family = AF_INET; sa.sin_port = htons(atoi (pblock_findval (“connect-port”, rq->vars))); /* host name resolution */ if (isdigit(*pblock_findval (“connect-host”, rq->vars))) sa.sin_addr.s_addr = inet_addr(rq->host); else { struct hostent *hp = servact_gethostbyname(pblock_findval (“connect-host”, rq->vars), sn, rq)); if (!hp) return REQ_ABORTED; /* can’t resolv */ memcpy(&sa.sin_addr, hp->h_addr, hp->h_lenght); } /* create the socket and connect */ sd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP); if (sd == -1) return REQ_ABORTED; /* can’t create socket */ if (connect(sd, (struct sockaddr *)&sa, sizeof(sa)) == -1) { close(sd); return REQ_ABORTED; /* can’t connect */ } return sd; /* ok */ } |
The DNS directive calls either the dns-config built-in function or a DNS function that you specify.
Syntax
DNS fn=dns-config local-domain-levels=<n>
local-domain-levels specifies the number of levels of subdomains that the local network has. The default is 1.
The Web Proxy Server optimizes DNS lookups by reducing the time spent resolving hosts that are fully qualified domain names but which DNS would by default still try to resolve relative to the local domain.
For example, from the netscape.com domain, suppose you try to access the host www.xyzzy.com. At first, DNS will try to resolve:
www.xyzzy.com.netscape.com
and only after that the real fully qualified domain name:
www.xyzzy.com
If the local domain has subdomains, such as corp.netscape.com, DNS would try two additional lookups:
www.xyzzy.com.corp.netscape.com www.xyzzy.com.netscape.com
To avoid these extra DNS lookups, you can instruct the proxy to treat host names that are not local as remote. The proxy should instruct DNS not to resolve the name relative to the current domain.
If the local network has no subdomains, set the value to 0. Only if the host name has no domain (no dots in the host name) the name will be resolved relative to the local domain. Otherwise, DNS should always resolve the name as an absolute, fully qualified domain name.
If the local network has one level of subdomains, set the value to 1. Host names that include two or more dots will be treated as fully qualified domain names.
An example of one level of subdomains would be the netscape.com domain, with subdomains:
corp.netscape.com engr.netscape.com mktg.netscape.com
Hosts without a dot, such as the step host are resolved with respect to the current domain, for example, engr.netscape.com. In this situation, the dns-config function will try this name:
step.engr.netscape.com
If you are on corp.netscape.com domain but the destination host step is on the engr subdomain, you can type
step.engr
instead of having to specify the fully qualified domain name:
step.engr.netscape.com
You define this DNS-class function.
Syntax
DNS fn=your-dns-function
Only the first applicable DNS function is called, starting from the most restrictive object. In the rare case that you need to call multiple DNS functions, the function can return REQ_NOACTION.
The DNS function must have this prototype:
int your_dns_function(pblock *pb, Session *sn, Request *rq);
To get the host name use:
pblock_findval("dns-host", rq->vars)
and set the host entry using the new NSAPI function
dns_set_hostent
The struct hostent * will not be freed by the caller but will be treated as a pointer to a static area, as with the gethostbyname call. Keep a pointer in a static variable in the custom DNS function and on the next call either use the same struct hostent or free it before allocating a new one.
The DNS function returns REQ_PROCEED if it is successful, and REQ_NOACTION if the next DNS function (or gethostbyname, if no other applicable DNS class functions exist) should be called instead. Any other return value is treated as failure to resolve the host name.
This example uses the normal gethostbyname call to resolve the host name:
#include <nsapi.h> int my_dns_func(pblock *pb, Session *sn, Request *rq) { char *host = pblock_findval("dns-host", rq->vars); struct hostent *hostent; hostent = gethostbyname(host); // replace with custom DNS implementation dns_set_hostent(hostent, sn, rq); return REQ_PROCEED; } |
The Filter directive runs an external command and then pipes the data through the external command before processing that data in the proxy by using the pre-filter function.
Syntax
Filter fn="pre-filter" path="/your/filter/prog"
The Filter directive performs these tasks:
Runs the program /your/filter/prog as a separate process.
Establishes pipes between the proxy and the external program.
Writes the response data from the remote server to the stdin of the external program.
Reads the stdout of the program as if it were the response generated by the server.
This process is equivalent to this command:
Filter fn="pre-filter" path="/your/filter/prog" headers="stdin"
The following Filter functions are described in detail in this section:
Applicable in Filter-class directives.
filter-ct can be used to block response content that matches a certain MIME type.
The following table describes the parameter for the filter-ct function.
Table 5–134 filter-ct Parameters
Parameter |
Description |
---|---|
regexp |
Regular expression of the mime type to be filtered. |
Filter fn="filter-ct" regexp="(application/octet-stream)" |
Applicable in Filter-class directives.
filter-html can be used to filter out HTML tags from the response content before sending it to the client.
The following table describes parameters for the filter-html function.
Table 5–135 filter-html Parameters
Parameter |
Description |
---|---|
start |
HTML start tag |
end |
HTML end tag |
Filter fn="filter-html" start="APPLET" end="APPLET" |
Applicable in Filter-class directives.
pre-filter is used to run external filter programs before returning response content to the client.
The following table describes the parameter for the pre-filter function.
Table 5–136 pre-filter Parameters
Parameter |
Description |
---|---|
path |
absolute path to external filter program. |
Filter fn="pre-filter" path="/your/filter/prog"
The Route directive specifies information about where the proxy server should route requests.
Applicable in Route-class directives.
The icp-route function tells the proxy server to use ICP to determine the best source for a requested object whenever the local proxy does not have the object.
Route fn=icp-route redirect=yes|no
The following table describes the parameter for the icp-route function.
Table 5–137 icp-route Parameters
Parameter |
Description |
---|---|
redirect |
Specifies whether the proxy server will send a redirect message back to the client telling it where to get the object.
|
Applicable in Route-class directives.
The pa-enforce-internal-routing function enables internal routing through a proxy array. Internal routing occurs when a non PAC-enabled client routes requests through a proxy array.
Route fn="pa_enforce_internal_routing" redirect="yes|no"
The following table describes the parameter for the pa-enforce-internal-routing function.
Table 5–138 pa-enforce-internal-routing parameters
Parameter |
Description |
---|---|
redirect |
Specifies whether clients requests will be redirected. Redirecting means that if a member of a proxy array receives a request that it should not service, it tells the client which proxy to contact for that request. |
Applicable in Route-class directives.
The pa-set-parent-route function sets a route to a parent array.
Route fn="pa_set_parent_route"
Applicable in Route-class directives.
The set-proxy-server function directs the proxy server to connect to another proxy for retrieving the current resource. It also sets the address and port number of the proxy server to be used.
Route fn=set-proxy-server server=URL of other proxy server host name=otherhost name port=number
The following table describes parameters for the set-proxy-server function.
Table 5–139 set-proxy-server Parameters
Parameter |
Description |
---|---|
server |
URL of the other proxy server. If multiple server parameters are given, the proxy server will distribute load among the specified proxy servers. For compatibility with earlier releases, hostname and port may be specified instead of server. |
host name |
The name of the host on which the other proxy server is running. |
port |
The port number of the remote proxy server. |
Route fn=set-proxy-server host name=proxy.netscape.com port=8080 |
Applicable in Route-class directives.
The set-origin-server function enables you to distributed load across a set of homogeneous HTTP origin servers by controlling which origin server the proxy server sends a request to.
The following table describes parameters for the set-origin-server function.
Table 5–140 set-origin-server Parameters
Parameter |
Description |
---|---|
server |
URL of an origin server. If multiple server parameters are given, the proxy server will distribute load among the specified origin servers. |
sticky-cookie |
(Optional) Name of a cookie that, when present in a response, will cause subsequent requests to "stick" to that origin server. The default is JSESSIONID. |
sticky-param |
(Optional) Name of a URI parameter to inspect for route information. When the URI parameter is present in a request URI and its value contains a colon, ’:’, followed by a route ID, the request will "stick" to the origin server identified by that route ID. The default is jsessionid. |
route-hdr |
(Optional) Name of the HTTP request header used to communicate route IDs to origin servers. set-origin-server associates each origin server named by a server parameter with a unique route ID. Origin servers may encode this route ID in the URI parameter named by the sticky-param parameter to cause subsequent requests to "stick" to them. The default is Proxy-jroute. |
route-cookie |
(Optional) Name of the cookie generated by the proxy server when it encounters a sticky-cookie cookie in a response. The route-cookie cookie stores a route ID that enables the proxy server to direct subsequent requests back to the same origin server. The default is JROUTE. |
rewrite-host |
(Optional) Boolean that indicates whether the Host HTTP request header is rewritten to match the host specified by the server parameter. The default is false, meaning the Host header is not rewritten. |
rewrite-location |
(Optional) Boolean that indicates whether Location HTTP response headers that match the server parameter should be rewritten. The default is true, meaning matching Location headers are rewritten. |
rewrite-content-location |
(Optional) Boolean that indicates whether Content-location HTTP response headers that match the server parameter should be rewritten. The default is true, meaning matching Content-location headers are rewritten. |
rewrite-headername |
(Optional) Boolean that indicates whether headername HTTP response headers that match the server parameter should be rewritten, where headername is a user-defined header name. With the exception of the Location and Content-location headers, the default is false, meaning the headername header is not rewritten. |
Applicable in Route-class directives.
The set-socks-server directs the proxy server to connect to a SOCKS server for retrieving the current resource. It also sets the address and port number of the SOCKS server to be used.
Route fn=set-socks-server host name=sockshost name port=number
The following table describes parameters for the set-socks-server function.
Table 5–141 set-socks-server Parameters
Parameter |
Description |
---|---|
host name |
The name of the host on which the SOCKS server runs. |
port |
The port on which the SOCKS server listens. |
ObjectType fn=set-socks-server host name=socks.netscape.com port=1080 |
Applicable in Route-class directives.
The unset-proxy-server function tells the proxy server not to connect to another proxy server to retrieve the current resource. This function nullifies the settings of any less specific set-proxy-server functions.
Route fn=unset-proxy-server
Applicable in Route-class directives.
The unset-socks-server function tells the proxy server not to connect to a SOCKS server to retrieve the current resource. This function nullifies the settings of any less specific set-socks-server functions.
Route fn=unset-socks-server