Oracle® iPlanet Web Proxy Server Release Notes Release 4.0.28 E18782-14 |
|
|
PDF · Mobi · ePub |
The Oracle iPlanet Web Proxy Server 4.0 documentation is provided in a number of ways:
Manuals - You can view the Oracle iPlanet Web Proxy Server 4.0 manuals and release notes in HTML and in printable PDF formats.
Online help - Click the Help button in the graphical interface to search a context-sensitive help window.
Oracle iPlanet Web Proxy Server 4.0.14 is the last release for which the entire documentation set for Oracle iPlanet Web Proxy Server 4.0 was updated. Subsequent to the 4.0.14 release, updates and corrections to Oracle iPlanet Web Proxy Server 4.0 documentation are provided in this Release Notes document; see Section 3.2, "Corrections and Updates to 4.0 Documentation."
This chapter contains the following sections:
The Oracle iPlanet Web Proxy Server 4.0 documentation is available at:
http://docs.oracle.com/cd/E21692_01/index.htm
Table 3-1 Oracle iPlanet Web Proxy Server 4.0.14 Documentation Set
The following sections describe corrections and updates to Oracle iPlanet Web Proxy Server 4.0.14 documentation:
Section 3.2.1, "Clarification About JRE Information in the Certification Matrix"
Section 3.2.3, "%Req->vars.xfer-time% Option of the flex-init Function"
Section 3.2.4, "clf-request-leading-whitespace Parameter of the flex-log SAF"
Section 3.2.5, "New Parameters of the um-define-junction SAF"
Section 3.2.6, "Clarification About Unit of Time Used for the%duration% Log Option"
Section 3.2.7, "Clarification About the Need to Explicitly Select New Directory Services"
Section 3.2.9, "Date and Time Parameters of the <Client> Tag"
Section 3.2.10, "Information About Parameters of the http-client-config SAF"
Section 3.2.12, "lookup-ipv6-first Parameter of the dns-config SAF"
Section 3.2.13, "regexp-redirect Function of the NameTrans Directive"
Section 3.2.14, "status-code and status-desc Parameters of the send-error SAF"
Section 3.2.16, "Description for Cache Finish Status in the Access Log File"
Section 3.2.17, "maxrequestsperconnection parameter is supported for the LS Element"
Section 3.2.19, "Specifying IP Address in ACL Configurations"
Section 3.2.22, "Regarding In-memory File Cache in Oracle iPlanet Web Proxy Server"
Section 3.2.24, "Information About the forward-auth-user SAF"
Section 3.2.25, "Information About New Attributes of FILECACHE Element"
Section 3.2.26, "Information About the blockingaccept Parameter"
Section 3.2.27, "Information About the timeout Property for dbswitch.conf Configuration File"
Section 3.2.29, "Information about the NetWriteTimeout magnus.conf Parameter"
Section 3.2.30, "Information about the New Parameter enable-ipv6 for Internal dns-lookup"
Section 3.2.31, "New SAF host-dns-cache-config to Control DNS Cache Behavior"
Section 3.2.32, "Information about the -P option of the flexanlg command"
Section 3.2.34, "Compressed Content Cannot be Rewritten by Content URL Rewriting"
Section 3.2.35, "Change in the cbuild command from Proxy Server 4.0.5"
Section 3.2.36, "keep-alive-timeout-absolute Parameter of the http-client-config SAF"
Section 3.2.37, "Information about the sleepinterval server.xml Parameter"
The Oracle iPlanet Web Proxy Server 4.0.14+ Certification Matrix currently (as of April 2011) shows only 1.6.0_19 as the certified JRE version.
Note the following:
4.0.13 and earlier releases of Oracle iPlanet Web Server are certified on (and include) JRE 5.
4.0.14, 4.0.15, and 4.0.16 are certified on both JRE 5 and JRE 6, but only JRE 5 is included with these releases.
4.0.17+: Certified on (and include) only JRE 6.
The "Setting Cache Capacity" section of the Oracle iPlanet Web Proxy Server 4.0.13 Administration Guide mentions that the cache capacity can be up to a maximum of 32 GB.
Starting from the 4.0.10 release, the maximum cache capacity that can be configured through the administration interface is 128 GB.
Note:
You can manually configure the cache capacity to any value higher than 128 GB (no upper limit) by editing theserver.xml
configuration file. But if you opt for the manual configuration route and want to set the cache capacity to a value that is less than 128 GB, then only the following values are allowed: 125, 250, 500, 1000, 2000, 4000, 8000, 16000, 32000, 64000, 128000.In the "Log Format" section of the Oracle iPlanet Web Proxy Server 4.0.14 Configuration File Reference, Table 5-4 lists the available flexible logging options. The %Req->vars.xfer-time%
option is missing from the list.
The%Req->vars.xfer-time%
option can be used to log the transfer time (in seconds).
Oracle iPlanet Web Proxy Server 4.0.16 supports a new parameter, clf-request-leading-whitespace
, for the flex-log
SAF of the AddLog
directive. The following table provides information about the new parameter.
Parameter | Description |
---|---|
clf-request-leading-whitespace |
(Optional) A boolean value indicating whether leading newlines in request lines should be removed before printing to the server access log.
The default value is Example: AddLog fn="flex-log" name="access" clf-request-leading-whitespace="no" |
For information about the other parameters of the flex-log
SAF, see the "flex-log" section of the Oracle iPlanet Web Proxy Server 4.0.14 Configuration File Reference.
Table 3-2 lists new parameters added for the um-define-junction
SAF of the Init
directive since the 4.0.14 release. Note that these parameters are not documented in the Oracle iPlanet Web Proxy Server 4.0.14 Configuration File Reference.
Table 3-2 New Parameters of the um-define-junction SAF
Parameter | Added in Release | Description |
---|---|---|
|
4.0.21 |
(Optional) Example usage:
Init fn="um-define-junction" jct-name="/test/" fe-uri-prefix="/test/"
be-url-prefix="http://eas97.in.oracle.com:17124/" secure-cookie="1"
onload-handler="yes"
Example output: Set-cookie: um__/test/_name=test; path=/; secure <script>document.cookie = "um_jct=/test/; path=/; secure";</script> |
|
4.0.16 |
(Optional) These parameters can be used to specify the target and destination values for rewriting the |
|
4.0.16 |
(Optional) If this parameter is set to The default value is |
|
4.0.16 |
(Optional) This parameter can be used to insert a |
|
4.0.16 |
(Optional) These parameters can be used to specify the target and destination values for rewriting the |
|
4.0.15 |
(Optional) A regular expression matched against the names of JavaScript variables when the |
According to the "Log Format" section of the Oracle iPlanet Web Proxy Server 4.0.14 Configuration File Reference, the%duration%
option indicates the time the server spent handling the request in microseconds.
Note the following clarification:
On Solaris and AIX, the server calculates and records the time in microseconds.
However, on Windows, HP-UX, and Linux, the server calculates the time in milliseconds and records it in microseconds.
The "Configuring Directory Services" section of the Oracle iPlanet Web Proxy Server 4.0.14 Administration Guide describes how to create a directory service. Note that if you want to use the new directory service with a specific proxy server instance, you must select it as described in the "Selecting Directory Services" section.
The admin.conf
file, located in the install-dir/proxyadmserv/config
directory, is an internal configuration file that Oracle iPlanet Web Proxy Server maintains. Do not modify this file.
Oracle iPlanet Web Proxy Server 4.0.15 supports several new parameters for the <Client>
tag, as described in the following table.
Parameter | Description |
---|---|
date-start and date-end |
These two parameters specify the start date and end date, respectively, for a time interval. They take values of the format of the UNIX date command, excluding the time zone specification. Additionally, the weekday portion of the date command format is optional. |
day-start and day-end |
These two parameters specify the start day number and end day number, respectively, for a day interval in a month. They take values in the range 1 through 31. |
month-start and month-end |
These two parameters specify the start month and end month, respectively, for a month interval in a year. They take the values Jan , Feb , Mar , Apr , May , Jun , Jul , Aug , Sep , Oct , Nov , and Dec . |
time-start and time-end |
These two parameters specify the start time and end time, respectively, for a time interval in a day. They take values of the form hour:minute:second on a 24-hour clock. |
weekday-start and weekday-end |
These two parameters specify the start day and end day, respectively, for a day interval in a week. They take the values Sun , Mon , Tue , Wed , Thu , Fri , and Sat . |
Examples
This example specifies a time interval of every Tuesday through Friday from 9:00 AM through 5:00 PM:
<Client weekday-start="Tue" weekday-end="Fri" time-start="09:00:00" time-end="17:00:00">
This example specifies a time interval of the first through the fifteenth of every month from 12:00 AM through 4:00 AM:
<Client day-start="1" day-end="15" time-start="00:00:00" time-end="04:00:00">
Table 3-3 lists the parameters of the http-client-config
SAF that existed in 4.0.14 or earlier releases, but are not documented in the Oracle iPlanet Web Proxy Server 4.0.14 Configuration File Reference at http://docs.oracle.com/cd/E21692_01/821-1883/aebjw/index.html
.
Table 3-3 Parameters of the http-client-config SAF
Parameter | Description |
---|---|
|
(Optional) This boolean parameter indicates whether a request body that arrives in a TCP packet separate from the request header should be forwarded to the origin server. The default value is false, meaning that request bodies arriving in TCP packets separate from their request headers are not forwarded to the origin server. |
|
(Optional) When this boolean parameter is enabled, the proxy server runs the Error stage when the origin server returns an error status (HTTP status code of 400 or above). By default, this parameter is disabled. |
|
(Optional) This parameter specifies the timeout period in seconds. It is used by the HTTP client while transferring data between clients and origin servers. The default value is 300 seconds. |
Oracle iPlanet Web Proxy Server 4.0.15 supports a new tag in the obj.conf
file. This tag, <Include>
, includes the content of another file in the obj.conf
file, effectively enabling you to divide the content of obj.conf
across several files to make management of your configuration easier.
The syntax of the <Include>
tag is:
<Include>
filename
</Include>
filename is the name of the file to be included in the obj.conf
file where the <Include>
tag occurs.
When using the <Include>
tag, keep these points in mind:
The <Include>
tag can be used outside the context of <Object>
. For example, you could put all the Init
directives in a file and then include that file at the start of the obj.conf.
file.
An included file can contain other included files; that is, an included file can itself contain an <Include>
tag.
An included file cannot cross <Object>
boundaries; that is, included file cannot end one object and start another.
Oracle iPlanet Web Proxy Server 4.0.15 supports a new parameter, lookup-ipv6-first
, for the dns-config
SAF of the DNS
directive. The following table provides information about this new parameter.
Parameter | Description |
---|---|
lookup-ipv6-first |
(Optional) A Boolean operator that specifies whether to look up IPv6 or IPv4 addresses first. The default value is false , meaning that IPv4 addresses are looked up first. |
The section "NameTrans" in Oracle iPlanet Web Proxy Server 4.0.14 Configuration File Reference does not include information about the regexp-redirect
function. Information about this function follows.
The regexp-redirect
function is applicable in NameTrans
-class directives.
The regexp-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 regexp-redirect
function.
Parameter | Description |
---|---|
from |
A regular expression for the prefix of the requested URL to match. |
url /url-prefix |
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. |
escape |
(Optional) A Flag that tells the server to use the util_uri_escape action on the URL before sending it. It should be yes or no . The default is yes .
For more information about |
bucket |
(Optional) This is common to all obj.conf functions. |
Oracle iPlanet Web Proxy Server 4.0.15 supports two new parameters for the send-error
SAF of the Service
and Error
directives. The following table provides information about these new parameters.
Parameter | Description |
---|---|
status-code |
(Optional) Specifies a status code to be set in the HTTP response. It differs from the code parameter in that code specifies which error code triggers execution of the send-error SAF, while status-code specifies a status code to be set in the response generated by the send-error SAF. |
status-desc |
(Optional) Specifies a reason string for the status code. |
Table 3-4 lists directives added to the magnus.conf
file. Note that these directives are not documented in "Syntax and Use of the magnus.conf
File" in Oracle iPlanet Web Proxy Server 4.0.14 Configuration File Reference.
Table 3-4 magnus.conf
Directives
Parameters | Valid Values | Description |
---|---|---|
|
Any number of seconds |
(Added in 4.0.14) Specify how frequently (in seconds) Oracle iPlanet Web Proxy Server checks the channel pool for stale or closed connections. This value is used when |
|
|
(Added in 4.0.14) Cause Oracle iPlanet Web Proxy Server to actively check the channel pool for stale or closed connections every |
|
|
(Added in 4.0.14) Cause Oracle iPlanet Web Proxy Server to validate channels in the channel pool before reusing them. The default value is |
|
|
(Added in 4.0.12) Specify the size of the FTP connection pool. The default value is 256. |
|
|
(Added in 4.0.12) Specify the life of the connection in seconds, that the FTP connection remain unused in the pool before the monitor thread closes it. The default value is |
|
|
(Added in 4.0.12) Specify the boolean value to monitor the FTP thread functionality. The default is |
|
|
(Added in 4.0.12) Specify an integer value. If set to If set to |
|
|
(Added in 4.0.12) Specify an integer value in seconds, after which the pool connections are monitored. The default value is |
|
Takes a Boolean value. |
(Added in 4.0.12) If set to |
|
Takes an integer argument. |
(Added in 4.0.12) Specify the interval at which the |
|
Takes a boolean value. |
(Added in 4.0.12) Revalidate the connection if set to |
|
Takes an integer value. |
(Added in 4.0.15) Specify the interval, in seconds, at which Oracle iPlanet Web Proxy Server checks performance of the gateways marked as offline by the routing subsystem. The default value is |
You can configure the Cache Finish Status
option by turning it ON
to record information about each status in the Access Log
file. Table 3-5 lists each of the Cache Finish Status and its description.
Status | Description |
---|---|
WRITTEN |
A new cache file is created |
ABORTED |
The response could not be cached because of invalid |
UP-TO-DATE |
The proxy receives a confirmation from the remote server that the proxy cache entry is updated and it may not be refreshed. |
NO-CHECK |
The remote server was not contacted for the request from the cache. |
REFRESHED |
The existing cache file was refreshed by the new contents from the origin server. |
MUST-NOT-CACHE |
The remote server response indicates that the response must not be cached. |
DO-NOT-CACHE |
The document received from the remote server is not cached by the proxy. |
Oracle iPlanet Web Proxy Server 4.0.18 supports a new parameter called maxrequestsperconnection
for the LS element in the server.xml
file. The following table provides information about this new parameter.
Parameter | Description |
---|---|
maxrequestsperconnection |
(optional) the number of requests allowed through a single connection. The default value is "0", which indicates that there is no limit. |
For more information about configuring the listener, see:
http://docs.oracle.com/cd/E19438-01/821-1883/aebbt/index.html
The virt-map
SAF is used to implement Virtual Multihosting. The virt-map
SAF uses the request's Host:
header to map a URI to a server URL. The corresponding reverse mapping is automatically inserted by virt-map
SAF.
Parameter | Description |
---|---|
host-regex |
Specifies a regular expression which is compared with the request's Host: header value. The virtual mapping is not applied in case of a mismatch. |
from-prefix |
Specifies the URI prefix to be mapped. |
to-prefix |
Specifies the URL prefix to which the request should be mapped. |
For more information about Virtual Multihosting, see:
http://docs.oracle.com/cd/E21692_01/821-1882/adypx/index.html
While specifying IP addresses in ACL configurations, a netmask can be used together with an IP address. The IP address and netmask must be separated by a '+' character.
Example:
allow (read,execute,info)
(user = "anyone")
and
(ip = "10.12.171.97+255.255.255.0");
For more information about ACL configurations, see:
http://docs.oracle.com/cd/E21692_01/821-1882/adyhq/index.html
After manually generating a PAC file, you are not required to restart the proxy server.
For more information about generating a PAC file from a PAT file, see:
http://docs.oracle.com/cd/E21692_01/821-1882/adyow/index.html
If GC (Garbage Collection) is disabled, or if the partition size happens to increase while GC is temporarily inactive, it is possible that the cache partition size can exceed the value specified in the maxsize
parameter.
For more information about cache elements, see:
http://docs.oracle.com/cd/E21692_01/821-1883/aebcl/index.html
Information pertaining to in-memory file cache is provided below:
The in-memory file cache is enabled only if the disk cache is enabled.
The in-memory file cache in Proxy server is used to cache the contents of frequently used disk cache files in memory.
The in-memory file cache configuration has a parameter named maxage
, which, however, is currently not enforced. It is to avoid HTTP violations by serving aged/invalid content.
The contents of in-memory file cache closely follow that of the disk cache. If a disk file is updated, the disk file in-memory version gets updated during the next request.
For more information about in-memory file cache configuration, see:
http://docs.oracle.com/cd/E21692_01/821-1883/aebcm/index.html
Note the following about proxy arrays.
Once you create a proxy array, but before generating a PAC file from your PAT file, proxy array must be explicitly enabled using the Configure System Preferences page in the administration GUI.
While configuring a non-master proxy array member, the URL field should be set to http://MasterProxy/pat
where MasterProxy is the FQDN of the master proxy. Ensure that the master proxy is configured to have a pat mapping which maps /pat
to the master proxy's pat file.
For more information about proxy arrays, see:
http://docs.oracle.com/cd/E21692_01/821-1882/6nmr9g0ap/index.html
As a fix for bug 13693179, a new SAF forward-auth-user
is introduced in Oracle iPlanet Web Proxy Server 4.0.19. This SAF is applicable for ObjectType
directives.
The forward-auth-user
SAF instructs the proxy server to forward the authenticated user name to remote servers. The SAF takes an optional parameter, hdr
, which specifies the name of the HTTP request header used to communicate the authenticated user name. The default value of the hdr
parameter is Proxy-auth-user
.
The following is the syntax of the forward-auth-user
SAF:
ObjectType fn="forward-auth-user" [hdr="request_header"]
request_header
is the name of the HTTP request header that should be used to communicate the authenticated user name to the servers in the back end.
As a fix for bugs 13700698 and 13700670, the attributes listed in Table 3-6 are introduced in Oracle iPlanet Web Proxy Server 4.0.19 for the FILECACHE
element in the server.xml configuration file.
Table 3-6 New Attributes Introduced in 4.0.19 for the FILECACHE Element
Attribute | Default | Description |
---|---|---|
|
This attribute specifies a limit (in bytes) for the total size of files created in the file cache's temporary directory. |
|
|
|
If this attribute is set to |
For information about the other attributes of the FILECACHE
element, see the Oracle iPlanet Web Proxy Server 4.0.14 Configuration File Reference at:
http://docs.oracle.com/cd/E21692_01/821-1883/aebcm/index.html
The fix for bug 13905244 introduces a new parameter blockingaccept
to the <LS> element in server.xml
configuration file.
This is a boolean parameter, and is set to false
by default. If set to true
, the listen socket will be of blocking nature.
However, client end points will continue to be non-blocking.
The fix for bug 13989967 introduces a property, timeout
, for LDAP configurations in the dbswitch.conf
configuration file. The timeout property specifies the duration (in seconds) after which LDAP operations should time out. The property is disabled by default; that is, by default, LDAP operations do not time out.
The following example shows the usage of the timeout
property in the dbswitch.conf
configuration file.
ldap://ldaphost:ldapport/dc%3D... default:binddn cn=Directory Manager default:encoded bindpw cGFzc3dvcmQ= default:timeout 30
In this example, the timeout
property is set to 30 seconds.
In Oracle iPlanet Web Proxy Server 4.0.14 Administration Guide, the section titled Creating a Filter File of URLs has the following example:
The information mentioned in the example is not valid for filtering access to example.com
.
The correct URL filter to access example.com
is .*://.*\.example\.com/.*
Replace netscape.com
with example.com
.
The Web Proxy Server's http filter implements a magnus.conf
parameter NetWriteTimeout
that will enable timeout on write operations to clients.
The NetWriteTimeout magnus.conf
parameter takes an integer value which specifies the client write timeout in seconds, and is disabled by default.
Oracle iPlanet Web Proxy Server 4.0.21 introduces a new parameter enable-ipv6
for internal dns-lookup
. This parameter takes a boolean value and is false by default. Setting it to true will enable lookup of IPv6 DNS records.
Example:
DNS fn="dns-lookup" server="…" enable-ipv6="true"
Note:
enable-ipv6
for internal dns-lookup
functionality is disabled on Windows.Oracle iPlanet Web Proxy Server 4.0.21 introduces a new SAF host-dns-cache-config
to control DNS cache behavior. This can be used to modify per-request DNS cache behavior. host-dns-cache-config
SAF takes the following parameters:
Parameter | Description |
---|---|
enabled |
This is a boolean parameter and is "true" by default. When disabled, DNS cache is not used. |
host-regex |
Takes a regular expression as value, and can be used to apply host-dns-cache-config settings only to requests whose Host: header matches the provided value. |
ttl |
Accepts an integer value that specifies the "time to live" in seconds for DNS cache entries. |
You can disable or enable DNS cache, or apply a specific ttl
.
Examples:
The following directive disables DNS cache for requests to backends with name of the pattern "backend.*"
:
ObjectType dns-cache-config host-regex="backend.*" enabled="false"
The following directive enforces a specific ttl
for 10 seconds on cached DNS entries to backend hostnames of the format "backend.*"
:
ObjectType dns-cache-config host-regex="backend.*" ttl="10"
"Working With the Log Analyzer", in Oracle iPlanet Web Proxy Server 4.0.14 Administration Guide, at: http://docs.oracle.com/cd/E21692_01/821-1882/adyjv/index.html
, describes the -P
option of the flexanlg
command.
The following is the description of the -P
option:
The -P
option enables generation of data related to the proxy-specific components like data related to client,proxy, cache, remote and matrix like cache hits, total remote connections, date retrieved from remote, data written to cache, and so on.
The Generate Report link in the Administration Server interface uses the command flexanlg
with -P
specified.
The error page for HTTP 407
changes when you upgrade to Oracle iPlanet Web Proxy Server 4.0.10 or higher versions.
Before upgrading, you see the following message on the HTTP 407
error page:
Proxy Authentication Required An error has occurred
After upgrading to version 4.0.10 or higher, you see the following message that is more informative and specific:
Proxy Authentication Required Proper authorization is required for this area. Either your browser dose not perform autorization, or your authorization has failed.
The section "Content URL Rewriting" in Oracle iPlanet Web Proxy Server 4.0.14 Administration Guide at http://docs.oracle.com/cd/E21692_01/821-1882/adypf/index.html
, describes how to configure content URL rewriting.
Note that compressed content cannot be rewritten by content URL rewriting.
The following is the difference in cache creation by the cbuild
command when you upgrade from 4.0.4 to 4.0.5 or higher versions:
In Proxy Server 4.0.4 you can create a cache partition in an existing directory.
In Proxy Server 4.0.5 you cannot create a cache partition in an existing directory. When you try to create a cache partition in an existing directory, the following message is logged:
./cbuild -d /<install-directory>/<instance-name>/config -c /<install-directory>/<instance-name>/cache -n 4 Uninitialized partition /<install-directory>/<instance-name>/cache already exists
Note:
As a consequence to fix for bug 14703102, starting from 4.0.21 release, thecbuild
command will accept an existing empty directory as target location for a new partition.Oracle iPlanet Web Proxy Server 4.0.22 supports a new parameter, keep-alive-timeout-absolute
, for the http-client-config
SAF. The following table provides information about this new parameter.
Parameter | Description |
---|---|
keep-alive-timeout |
Accepts an integer argument that specifies, in seconds, the absolute maximum life span of a pooled connection. |
The sleepinterval
attribute of the GC (Garbage Collection) element in server.xml
specifies the time, in seconds, the GC thread sleeps before waking up and inspecting the configured partitions to check if garbage collection should be initiated.
The default value for this parameter is 45 seconds. Hence if sleepinterval
is set to its default value of 45 seconds, the GC thread would wake up every 45 seconds and inspect the configured partitions.
After the sleepinterval
parameter is modified or set, the server must be restarted for the changes to take effect.
Oracle iPlanet Web Proxy Server 4.0.22 supports a new parameter, SOCKS5_CONNECT_TIMEOUT
, which has been added to the socks5.conf
file. The following table provides information about this new parameter.
Parameter | Description |
---|---|
SOCKS5_CONNECT_TIMEOUT |
Accepts an integer value that specifies the "timeout" in seconds for a connection attempt. |
The Oracle web site provides information about the following additional resources: