Sun Java System Web Proxy Server 4.0.2 2005Q4 Configuration File Reference

ObjectType

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 there is more than one ObjectType directive in an object, 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 something else, the first setting is used and the subsequent ones are ignored.

The obj.conf file almost always has an ObjectType directive that calls the type-by-extension function. This function instructs the server to look in a particular file (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-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.
set-basic-auth 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 allows 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.

block-auth-cert

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.

Parameters

None.

block-cache-info

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.

Parameters

None.

block-cipher

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.

Parameters

None.

block-ip

Applicable in ObjectType-class directives.

The block-ip function instructs the proxy server not to forward the client’s IP address to remote servers.

Parameters

None.

block-issuer-dn

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.

Parameter

None.

block-keysize

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.

Parameters

None.

block-proxy-auth

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.

Parameter

None.

block-secret-keysize

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.

Parameters

None.

block-ssl-id

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.

Parameters

None.

block-user-dn

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.

Parameters

None.

cache-enable

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

Syntax

ObjectType fn=cache-enable
     cache-auth=0|1
     query-maxlen=number
     min-size=number
     max-size=number    log-report=feature
     cache-local=0|1

Parameters

The following table describes parameters for the cache-enable function.

Table 5–67 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 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.

Example

The following example of cache-enable allows you to enable caching of objects matching the current resource. This 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 (if present) 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 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 KB to 1 MB.

ObjectType fn=cache-enable
     min-size=2
     max-size=1000

cache-setting

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.

Syntax

ObjectType fn=cache-setting
     max-uncheck=seconds
     lm-factor=factor    connect-mode=always|fast-demo|never
     cover-errors=number

Parameters

The following table describes parameters for the cache-setting function.

Table 5–68 cache-setting parameters


Parameter	Description
`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.
`lm-factor`	(optional)A floating point number representing the factor used in estimating expiration time (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, and the result gives the estimated time the document is likely to remain unchanged. Specifying a value of 0 turns off this function, and then the caching system uses only explicit expiration information (rarely available). Only explicit Expires HTTP headers are used. This value has no effect if max-uncheck is set to 0.
`connect-mode`	Specifies network connectivity and can be set to these values: `always` (default) connects to remote servers when necessary. `fast-demo` connects only if the item isn’t found in the cache. `never` no connection to a remote server is ever made; returns an error if the document is not found in the cache.
`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.
`term-percent`	means to keep retrieving if more than the specified percentage of the document has already been retrieved.

Example

<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
# Disable caching of the current resource
ObjectType fn=cache-setting cache-mode=nothing

force-type

Applicable in ObjectType-class directives.

The force-type function assigns a type to requests that do not already have a MIME type. This 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 there is more than one ObjectType directive in an object, 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 something else, the first setting is used and the subsequent ones are ignored.

Parameters

The following table describes parameters for the force-type function.

Table 5–69 force-type parameters


Parameter	Description
`type`	(Optional) Type assigned to a matching request (the `Content-Type` header).
`enc`	(Optional) Encoding assigned to a matching request (the `Content-Encoding` header).
`lang`	(Optional) Language assigned to a matching request (the `Content-Language` header).
`charset`	(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^TM /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.

Example

ObjectType fn=force-type type=text/plain
ObjectType fn=force-type lang=en_US

forward-auth-cert

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.

Parameters

The following table describes parameters for the forward-auth-cert function.

Table 5–70 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".

forward-cache-info

Applicable in ObjectType-class directives.

The forward-cache-info function instructs the proxy server to forward information about local cache hits to remote servers.

Parameter

The following table describes parameters for the forward-cache-info function.

Table 5–71 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".

forward-cipher

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.

Parameters

The following table describes parameters for the forward-cipher function.

Table 5–72 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`.

forward-ip

Applicable in ObjectType-class directives.

The forward-ip function instructs the proxy server to forward the client’s IP address to remote servers.

Parameters

The following table describes parameters for the forward-ip function.

Table 5–73 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".

forward-issuer-dn

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.

Parameters

The following table describes parameters for the forward-issuer-dn function.

Table 5–74 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".

forward-keysize

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.

Parameters

The following table describes parameters for the forward-keysize function.

Table 5–75 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".

suppress-request-headers

See suppress-request-headers.

forward-proxy-auth

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.

Parameters

None.

forward-secret-keysize

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.

Parameters

The following table describes parameters for the forward-secret-keysize function.

Table 5–76 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".

forward-ssl-id

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.

Parameter

The following table describes parameters for the forward-ssl-id function.

Table 5–77 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".

forward-user-dn

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.

Parameters

The following table describes parameters for the forward-user-dn function.

Table 5–78 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".

http-client-config

Applicable in ObjectType-class directives.

The http-client-config function configures the proxy server’s HTTP client.

Parameters

The following table describes parameters for the http-client-config function.

Table 5–79 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. In general, you should 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.

java-ip-check

Applicable in ObjectType-class directives.

The java-ip-check function allows 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 parameters for the java-ip-check function.

Table 5–80 java-ip-check parameters


Parameter	Description
`status`	Specifies whether Java IP address checking is enabled or not. Possible values are: `on` means that Java IP address checking is enabled and that IP addresses will be forwarded to the client in the form of a document header. `On` is the default setting. `off` means that Java IP address checking is disabled.

match-browser

See match-browser.

set-basic-auth

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.

Parameters

The following table describes parameters for the set-basic-auth function.

Table 5–81 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.

set-default-type

Applicable in ObjectType-class directives.

The set-default-type function allows 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. Note that by placing this function in different objects in obj.conf, you can define different defaults for different parts of the document tree.

Parameters

The following table describes parameters for the set-default-type function.

Table 5–82 set-default-type parameters


Parameter	Description
`enc`	(Optional) Encoding assigned to a matching request (the `Content-Encoding` header).
`lang`	(Optional) Language assigned to a matching request (the `Content-Language` header).
`charset`	(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.

Example

ObjectType fn="set-default-type" charset="iso_8859-1"

set-variable

See set-variable.

shtml-hacktype

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 provides backward compatibility with server-side includes for files with .htm or .html extensions. The function may also check the execute bit for the file on UNIX systems. The use of this function is not recommended.

Parameters

The following table describes parameters for the shtml-hacktype function.

Table 5–83 shtml-hacktype parameters


Parameter	Description
`exec-hack`	(UNIX only, optional) Tells the function to 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.

Example

ObjectType fn=shtml-hacktype exec-hack=true

ssl-client-config

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.

Parameter

The following table describes parameters for the ssl-client-config function.

Table 5–84 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.

type-by-exp

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 is the same as type-by-extension, except you use wildcard patterns for the files or directories specified in the URLs.

Parameters

The following table describes parameters for the type-by-exp function.

Table 5–85 type-by-exp parameters


Parameter	Description
`exp`	Wildcard pattern of paths for which this function is applied.
`type`	(Optional) Type assigned to a matching request (the `Content-Type` header).
`enc`	(Optional) Encoding assigned to a matching request (the `Content-Encoding` header).
`lang`	(Optional) Language assigned to a matching request (the `Content-Language` header).
`charset`	(Optional) is 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.

Example

ObjectType fn=type-by-exp exp=*.test type=application/html

type-by-extension

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

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.

Parameters

The following table describes parameters for the type-by-extension function.

Table 5–86 type-by-extension parameters


Parameter	Description
`bucket`	(Optional) Common to all `obj.conf` functions.

Example

ObjectType fn=type-by-extension

ObjectType

block-auth-cert

Parameters

block-cache-info

Parameters

block-cipher

Parameters

block-ip

Parameters

block-issuer-dn

Parameter

block-keysize

Parameters

block-proxy-auth

Parameter

block-secret-keysize

Parameters

block-ssl-id

Parameters

block-user-dn

Parameters

cache-enable

Syntax

Parameters

Example

cache-setting

Syntax

Parameters

Example

force-type

Parameters

Example

See Also

forward-auth-cert

Parameters

forward-cache-info

Parameter

forward-cipher

Parameters

forward-ip

Parameters

forward-issuer-dn

Parameters

forward-keysize

Parameters

suppress-request-headers

forward-proxy-auth

Parameters

forward-secret-keysize

Parameters

forward-ssl-id

Parameter

forward-user-dn

Parameters

http-client-config

Parameters

java-ip-check

match-browser

set-basic-auth

Parameters

set-default-type

Parameters

Example

set-variable

shtml-hacktype

Parameters

Example

ssl-client-config

Parameter

type-by-exp

Parameters

Example

See Also

type-by-extension

Parameters

Example

See Also