Oracle Web Cache Release Notes
Release 2.0.0.0.0
Copyright (C) Oracle Corporation 2001
This software/documentation contains proprietary information of Oracle
Corporation. It is provided under a license agreement containing restrictions
on use and disclosure and is also protected by copyright law. Reverse engineering
of the software is prohibited.
If this software/documentation is delivered to a U.S. Government Agency
of the Department of Defense, then it is delivered with Restricted Rights
and the following legend is applicable:
RESTRICTED RIGHTS LEGEND:
Use, duplication, or disclosure by the Government is subject to restrictions
as set forth in subparagraph (c)(1)(ii) of DFARS 252.227-7013, Rights in
Technical Data and Computer Software (October 1988).
If this software/documentation is delivered to a U.S. Government Agency
not within the Department of Defense, then it is delivered with "Restricted
Rights," as defined in FAR 52.227-14, Rights in Data -General, including
Alternate III (June 1987).
Oracle Corporation, 500 Oracle Parkway, Redwood City, CA 94065.
The information in this document is subject to change without notice.
If you find any problems in the documentation, please report them to us
in writing. Oracle Corporation does not warrant that this document is error
free.
Oracle is a registered trademark of Oracle Corporation, Redwood City,
California.
All trade names referenced are the service mark, trademark, or registered
trademark of the respective manufacturer.
BEFORE YOU BEGIN
Be sure to check the following sites to see if there are patches
available for Oracle Web Cache on your OS platform:
-
http://otn.oracle.com/products/ias
and/or
-
http://metalink.oracle.com/
TABLE OF CONTENTS
-
1.0 Configuring Oracle Web Cache
-
2.0 Oracle Web Cache Limitations
-
3.0 Netscape Limitations
-
4.0 Oracle Application Server (OAS) Limitations
-
5.0 Connection Limitations
-
6.0 TCP Tuning
-
7.0 Oracle Web Cache Default Ports
-
8.0 Default Session/Personalized Attribute Values
-
9.0 Oracle Web Cache Usage Examples
-
10.0 How to Configure Oracle Web Cache to Listen on Port < 1024
-
11.0 Undocumented New Features
-
12.0 Known Bugs
-
13.0 Where to Find More Information and Patch Downloads
1.0 Configuring Oracle Web Cache
To start initial Oracle Web Cache configuration:
-
If not currently logged on to the Oracle Web Cache computer, log in with
the user ID of the user that performed the installation.
-
Start Oracle Web Cache. From the command line, enter: webcachectl start
-
Start Oracle Web Cache Manager:
-
Point your browser to the following URL: http://web_cache_hostname:4000/
-
When prompted for the administrator user ID and password, enter "administrator"
for the user name and the appropriate password. The first time you log
in, the password is "administrator".
See Also: Oracle Web Cache Administration and Deployment Guide (available
at http://otn.oracle.com/products/ias) for complete configuration coverage.
Note: Oracle Web Cache uses two configuration files: webcache.xml and
internal.xml. These configuration files should NEVER be edited. Editing
of these configuration is not supported and may cause problems in Oracle
Web Cache. (See sections 7.1, 8.0, and 11.3 for exceptions).
2.0 Oracle Web Cache Limitations
2.1 HTTP Range Requests and Multi-Part Responses
Certain HTTP browsers will send Range headers in HTTP requests. In response
to requests of this type, an Application Web Server may respond with a
multi-part document or a document in its entirety.
In this release, Oracle Web Cache cannot cache HTTP multi-part responses
to HTTP Range requests. If the application Web servers that Oracle
Web Cache sends HTTP requests to return certain documents in multi-part
format, configure these documents as non-cacheable through the Administering
Web Sites > Cacheability Rules section of the Oracle Web Cache Manager
interface.
For example, certain browsers send Range requests for PDF documents;
therefore, the cacheability rules for all PDF documents should be set non-cacheable.
2.2 Personalized Pages
When configuring cacheability rules, you can optionally enable Oracle Web
Cache to replace personalized information in a cached document with user-specific
personalized information in HTTP requests. This way, one cached personalized
page can be reused for any user, improving performance significantly.
In enabling this personalization feature, you can enable Oracle Web
Cache to look for personalized information in special tags in the HTTP
response or in all HTML links (often known as HREF) in the HTTP response.
In this release, Oracle Web Cache looks for personalized information in
both the special tags and in the HREF HTML
links. Therefore, while editing/creating a cacheability rule, if you
select YES in the Personalized Pages section, the selection in the subsection
should always be "pages contain HREFs that are session encoded URLs." Selection
of the other option, "pages do not contain HREFs that are session encoded
URLs" is ignored. All personalized pages are always parsed for session-encoded
URLs.
2.3 Default Buffer Sizes
Oracle Web Cache uses buffered logging. The default buffer size is 2 KB.
The default document buffer block size is 32 KB.
The default document header buffer block size is 4 KB.
These default sizes should be sufficient for most deployment. If you
need to change any of these default sizes, please contact Oracle Support
Services or consultants.
2.5 Insufficient Input Checking in Oracle Web Cache Manager
The Oracle Web Cache Manager does not enforce the same level of consistency
checking upon receiving configuration input that Oracle Web Cache does
upon starting up. Therefore, there may be instances where configuration
changes are accepted by the Oracle Web Cache Manager, but Oracle Web Cache
does not start up with the resulting
configuration.
This is especially a problem when the Admin server itself is shut down
(using webcachectl stop) after applying bad configuration changes. In that
case, the Oracle Admin Server itself will not be able to start up, and
the Oracle Web Cache Manager will become inaccessible. The workaround is:
# webcachectl repair
This will restore the previous version of the configuration.
3.0 Netscape Limitations
Oracle Web Cache can optionally compress a cached document so that serving
subsequent HTTP requests requires less network bandwidth. However,
certain versions of the Netscape Navigator browsers do not support compressed
JavaScripts and other non-HTML documents. This version of Oracle
Web Cache supports the ability to specify compression for non-Netscape
browsers.
4.0 Oracle Application Server (OAS) Limitations
NOTE: OAS is NOT the same product as Oracle9i Application Server.
4.1 Oracle Web Cache with OAS on the Same Computer
NOTE: This limitation applies to OAS using the Oracle Web Listener ONLY.
This does not apply to other listeners used with OAS.
4.1.1 Introduction
4.1.1.1 Oracle Web Listener and the Host header
OAS, when used specifically with the Oracle Web Listener, strictly enforces
virtual-host checking using the "Host" header, that is sent by almost all
browsers. The Host header contains the string "<hostname>:<port>"
where "<hostname> and <port> are as entered in the location bar of
the browser, even if the <hostname> in the location bar is an IP address.
If the Oracle Web Listener receives a Host header that does NOT match an
entry in the Host Name and Port columns of the "Network" section of the
configuration (corresponding to the [Multiport] section in the sv*.cfg
configuration file for the listener), it returns an HTTP error code 400
with the message: "The request did not specify a valid virtual host".
4.1.1.2 Deployments
This limitation applies to the following deployments:
-
In OAS 4.x, this is strictly enforced for HTTP/1.1 requests only. For HTTP/1.0
requests, only the hostname has to match an entry in the Network section.
The port number in the Host header does not matter.
-
Oracle Web Listener, as shipped with Oracle Web Application Server 3.0
enforces this strictly for all HTTP requests, that is HTTP/1.0 and HTTP/1.1.
4.1.1.3 Entries for Network
In order to make an Oracle Web Listener recognize and accept a Host header,
a corresponding entry must be added to the "Network" section for that listener.
When you add an entry with hostname h1 and port p1, h1 is ONLY used to
match incoming Host headers and does not otherwise affect the operation
of the listener. In fact, h1 does not even need
to be a DNS host name of the computer. However, p1 is used as a port
that the Oracle Web Listener tries to listen on. Hence there should be
no other process on the computer listening on port p1.
4.1.2 Oracle Web Cache Behavior
Oracle Web Cache does NOT change the Host header that it receives as part
of a request when relaying that request to the Application Web Server.
If you set up Oracle Web Cache to listen on port 1100 on a computer
with DNS hostname m1 and the Application Web Server is on computer m2 on
port 80, and you use a browser to access http://m1:1100/, the Host header
received by Oracle Web Cache is "Host: m1:1100". This is exactly the Host
header that will be received by the Application Web Server.
4.1.3 What Restrictions Does This Imply?
If you are using Oracle Application Server with the Oracle Web Listener
as your application Web server, this means that the host header sent to
Oracle Web Cache MUST be recognized by the Oracle Web Listener, that is,
there must be a corresponding entry in the "Network" section.
4.1.3.1 Restriction In Browser Testing Mode
If you are using Oracle Web Cache's host name and port in your browser
directly, and if Oracle Web Cache and the Oracle Web Listener are on the
SAME COMPUTER, the Oracle Web Listener will need to accept Oracle Web Cache's
host name and port number in the Host header, and for that to happen Oracle
Web Cache's port number will need to appear in the Network section of the
Listeners configuration. This would mean that both Oracle Web Cache and
the Oracle Web Listener will try to listen on that port, which is not possible.
See Also: Section 4.1.1.3
Hence in testing mode, when you are using your browser to directly connect
to Oracle Web Cache, then Oracle Web Cache and the Oracle Web Listener,
cannot be on the same computer.
4.1.3.2 Restriction and Solution In Deployment mode
In order to deploy Oracle Web Cache and the Oracle Web Listener on the
same computer, there has to be a port-translating switch between the browser
and Oracle Web Cache that translates the port number to which the browser
connects to Oracle Web Cache's listening port.
For example, assume that Oracle Web Cache is listening on port 1100
on computer m1.aaa.com, and Oracle Web Listener is the application Web
server listening on port 80 on the same computer m1.aaa.com. In this example,
the user enters http://www.aaa.com/ in the browser. The browser will attempt
to connect to port 80 on www.aaa.com. www.aaa.com
should be resolved via DNS to your switch, which should redirect requests
for www.aaa.com on port 80 to computer m1 on port 1100. Note that the host
header will be: "Host: www.aaa.com:80". Oracle Web Cache will forward requests
as needed to computer m1 port 80 i.e. the Oracle Web Listener. For the
Oracle Web Listener to accept this Host header,
you will need to have added an entry to Network containing Host Name
www.aaa.com and Port 80.
See Also: 4.1.1.3 for how this can be done on computer m1
5.0 Connection Limitations
5.1 Unix
On most UNIX platforms there is a hard limit to how
many file descriptors a process can open. This number is normally 1024
but is configurable. To be able to change this default to a
higher one, you have to be root or run the process as root. The other way
is to set the setuid bit for the process to root. The procedure for
doing this is the same as listed below in section 10.0 "How to Configure
Oracle Web Cache to Listen on Port <1024".
In this release, Oracle Web Cache calculates the
maximum number of file descriptors to be used by using the following simple
formula:
-
Max number of file descriptors to be used =
Current Maximum Incoming Connections (specified in the webcache.xml through
the Web Cache Manager interface) + sum of Capacity for
all the configured origin Web Server instances + 20 (reserved
for internal use).
Based on the above formula the Web Cache server tries
to reserve this many file descriptors at startup time. In case it
fails to do so, it doesn't default to a lower value but logs an error message
and fails to start. In case the Web Cache server fails to start because
the number of file descriptors required is more that 1024, either run it
as root or setuid the execuable to root.
Also, always set the "Current Maximum Incoming
Connections" in Web Cache Manager to reflect correctly the maximum number
of clients you intend to serve concurrently at any given time. The
value should not be set to an arbitrary high value, as Web Cache sets aside
some resources for each and the performance would be adversely affected.
5.2 Windows
Windows NT Server and Windows 2000 -- information forthcoming.
Oracle Web Cache is not designed to run on Windows NT Workstation.
6.0 TCP Tuning
If you want Oracle Web Cache to handle large number of concurrent HTTP
requests, you may need to tune your operating system's TCP settings, such
as the maximum TCP connection queue length.
See Also:
http://www.rvs.uni-hannover.de/people/voeckler/tune/EN/tune.html for
information about how to tune Solaris 2.x TCP parameters.
In particular, if you run stress tests against Oracle Web Cache and
continuously open more TCP connections from one client computer to Oracle
Web Cache, you may experience periodic oscillation of throughput. This
is usually caused by TCP connection TIME_WAIT in your operating system.
In real world deployments, this is not an issue since it is unlikely that
a single client will generate a huge number of connections.
In case of denial of service attack, availability problems usually arise
in the network layer in your operating system. For example, if one client
generates large number of connections, TCP connection problems generally
arise in your operating system.
The following is an example shell script that sets some of the TCP parameters
for Solaris 2.x:
#!/usr/bin/bash -x
/usr/sbin/ndd -set /dev/tcp tcp_conn_req_max_q 10240 /usr/sbin/ndd
-set /dev/tcp tcp_conn_req_max_q0 10240 /usr/sbin/ndd -set /dev/tcp
tcp_xmit_hiwat 32768 /usr/sbin/ndd -set /dev/tcp tcp_recv_hiwat 32768
/usr/sbin/ndd -set /dev/tcp tcp_time_wait_interval 1000
7.0 Oracle Web Cache Default Ports
During installation, Oracle Web Cache is configured to use the following
default TCP ports:
-
Administration: 4000
-
HTTP request: 1100
-
Invalidation: 4001
-
Statistics: 4002
-
Application Web Server: localhost:7777
At the end of installation, Oracle Web Cache will attempt to start. Depending
on your environment (port conflicts, file/directory permissions, and so
on), Oracle Web Cache Admin Server and/or Cache Server may fail to start.
If the Admin Server could not start because the default administration
port is already in use by other running applications, you need to change
the administration port in $ORACLE_HOME/webcache/webcache.xml. Find the
line
<LISTEN IPADDR="ANY" PORT="4000" PORTTYPE="ADMINISTRATION"/>
and change "4000" to an unused port (such as "3999"). Then run
$ORACLE_HOME/webcache/bin/webcachectl start
to start the Admin Server and the Cache Server.
Note: This is one of the rare cases where you may need to edit the Oracle
Web Cache configuration file directly. Since this is an automatically
generated and processed file, you must be very careful in making this change.
In general, you should avoid hand-editing any Oracle Web Cache configuration
files.
If the Admin Server is started but the Cache Server could not start,
point your browser http://<hostname>:<admin port>/ to reconfigure
the Cache Server, and then start the Cache Server from the HTML administration
page.
If any of the above port settings conflict with existing settings in
the installed computer, please reconfigure through http://<hostname
of the installed computer>:<administration port>/. For example, if Oracle
Web Cache is installed on a computer named server1, then you can reconfigure
through http://server1:4000/.
Please note that after reconfiguring the administration port, you must
restart Oracle Web Cache Admin Server. After reconfiguring any other ports,
you must restart Oracle Web Cache Cache Server.
To restart the Admin Server under Unix, execute the following commands:
-
$ORACLE_HOME/webcache/bin/webcachectl stop
-
$ORACLE_HOME/webcache/bin/webcachectl start
8.0 Default Session/Personalized Attribute Values
When sending any HTTP response for a request from the cache (a.k.a. a cache
hit), if this response object has session-encoded URLs in the body
(e.g., HTML links with session values in the URL) or personalized attributes
(e.g., a login user's name or his/her address info) and if the subsititution
for any of these session values/personalized attributes does not exist
in the request, Oracle Web Cache 1.0.2.2.0 and earlier versions then consider
this request a cache miss, thus will not use the cached object and request
a response from the backend application web server. Since release 1.0.2.3.0,
Oracle Web Cache will, in this situtation, subsititute as much as possible
and leave missing personalized attribute/session values empty. Therefore
this request is now a cache hit. If you want to disable this feature, that
is, require all necessary personalized attribute/session values to exist
in the request for itto be a cache hit, then you must define those personalized
attributes/sessions as sessions and then define session-related caching
rules for such requests. In the session-related caching rule, specifiy
the response to be cacheable only if the request contains a session value.
9.0 Oracle Web Cache Usage Examples
To find examples of how to use Oracle Web Cache, read:
-
$ORACLE_HOME/webcache/examples/README.examples.
10.0 How to Configure Oracle Web Cache to Listen on Port < 1024
On most Unix platforms, a process without root privilege cannot listen
on ports < 1024. If you want to configure Oracle Web Cache to listen
on port <1024 such as the usual port 80 and you do not want Oracle Web
Cache to keep running with root privilege, follow the following steps:
-
Through the Web Cache Manager, change process identity to the desired running
process identity, such as nobody/nobody; change Oracle Web Cache listening
port to the desired port, such as 80;
-
log in as root;
-
change the owner of the executable 'webcached' to root;
$ chown root /opt/oracle/webcache/bin/webcached
-
change the group of the executable 'webcached' to the group id of the desired
running process identity, such as nobody:
$ chgrp <groupid> /opt/oracle/webcache/bin/webcached
-
add set-user-id permission to the executable 'webcached';
$ chmod u+s /opt/oracle/webcache/bin/webcached
-
exit from root;
-
start Oracle Web Cache through webcachectl. Oracle Web Cache should be
listening on the desired port with the desired process identity (nobody/nobody).
$ /opt/oracle/webcache/bin/webcachectl start
Note that NOT running Oracle Web Cache as root will limit the number of
connection handles that Oracle Web Cache can use to the operating system's
hard-coded file descriptor limit. See Also: Section 5.0.
11.0 Undocumented New Features
This section describes new features which are not described in the Oracle
Web Cache Administration and Deployment Guide.
11.1 Listing the Top 100 Objects in the Cache
With Oracle Web Cache, you can view a list of the top 100 most popular
objects in the cache. To view the top 100 objects, take the following steps:
-
Start Oracle Web Cache Manager.
-
In your browser, enter the following URL:
-
http://web_cache_hostname:Admin_Port/webcacheadmin?SCREEN_ID=CGA.Top100&ACTION=Show
Oracle Web Cache Manager displays the Top 100 Objects screen, which lists
the top 100 objects in the cache since the cache was last started.
The columns in the display have the following meaning:
-
Rank: A ranking, from 1 to 100, based on the score of the object. A rank
of "1" represents the object with the highest score; that is, the most
popular object.
-
Object Name: The URL of the object. The URL may contain additional descriptive
information, such as cookie or session information.
-
Score: The popularity of the object, which is determined by:
-
The number of times the documentation has been requested since being placed
in the cache
-
The number of recent requests for the document
-
Size: The size of the object. The size is represented in bytes, kilobytes
(K), or megabytes (M).
11.2 Listing the Contents of the Cache
With Oracle Web Cache Manager, you can generate a list of the URLs of all
of the objects currently in the cache. This is helpful in verifying that
the cacheability rules that you have specified are caching the objects
that you want cached.
Note that to maintain the performance of your web cache, Oracle Corporation
recommends that you perform this operation during non-peak hours. While
writing the list of URLs to the text file, performance may degrade somewhat.
When you generate a list of the contents of the cache, Oracle Web Cache
Manager writes the URLs to a text file. To generate the list, take the
following steps:
-
Start Oracle Web Cache Manager.
-
In your browser, enter the following URL:
-
http://web_cache_hostname:Admin_Port/webcacheadmin?SCREEN_ID=CGA.CacheDump&ACTION=Show
-
Oracle Web Cache Manager displays the Cache Contents page. This page lists
the file to which it will write the URLs. By default, the file is written
to the Oracle Web Cache log directory and is named webcache_contents.txt.
-
Click Submit.
Oracle Web Cache writes the list of URLs to the text file. Each time you
generate the list, Oracle Web Cache appends the data to the existing file.
It lists the date that the data was appended to the file, followed by the
URLs of the objects currently cached. The following example shows an excerpt
of the webcache_contents.txt file:
Cache Contents at Wed Apr 11 11:47:03 2001
/images/lnav/lnav_products.gif
/images/rnav/rnav_red_line_1.gif
/images/bullets_and_symbols/blk_line_bullet_10.gif
.
.
.
Cache Contents at Wed Apr 11 13:01:24 2001
/images/white_spacer_xp.gif
/images/white_spacer.gif
/images/miniappsnet.gif
.
.
.
11.3 Cache Watchdog
Oracle Web Cache has two major components: the admin server process and
the cache server process. The admin server handles administrative tasks
and the cache server handles caching and HTTP requests. Oracle Web Cache
also provides a watchdog process to check that the cache process is running.
If it is not, the watchdog process starts the cache.
When you start the Oracle Web Cache admin server process, that process
starts the watchdog process. The watchdog process polls the cache server
at specified intervals. It does this by sending requests to a specified
URL. If it cannot connect to the cache server or if the cache server does
not respond within a specified time, the watchdog process restarts the
cache server.
You can configure the following attributes for the watchdog process:
-
ENABLE: Enables the watchdog process. Accepted values are:
The
default value is NO.
-
PINGINTERVAL: The interval, in seconds, that Oracle Web Cache will poll
the cache server. The default value is 5 seconds.
-
PINGTIMEOUT: The time, in seconds, that the watchdog process will wait
for a response from the cache server. The default value is 5 seconds.
-
PINGURL: The URL that the watchdog process will use to poll the cache server.
Use a URL that you can guarantee is in the cache server. The default is
"/".
(Note: If the cache server is not configured with a valid Application Web
Server, then watchdog pinging will fail every time, causing error output
in the event log. To stop this, either configure valid Application Web
Servers, or stop the cache server through the administration page [http://
<hostname>:<admin port>/] )
For this release, you must edit the webcache.xml file to change the
default values. The file is located in the following directory:
-
For UNIX: $ORACLE_HOME/webcache
-
For Windows NT: Oracle_home\webcache
Use the following format to specify the values for the watchdog process
attributes:
<WATCHDOG [ENABLE =value] [PINGINTERVAL =value] [PINGTIMEOUT =value]
[PINGURL =value] />
In the format, note the following syntax rules:
-
The attribute names and the value for ENABLE must be in upper case.
-
Each value must be enclosed in double quotation marks (").
-
No spaces are allowed in the quoted values or between the quotation marks
and the value.
-
No spaces are allowed between the open angle bracket (<) and the element
name, WATCHDOG.
-
No spaces are allowed between the slash (/) and the close angle bracket
(>) at the end of the element.
-
Except as noted in this list, whitespace (including tabs and newlines)
is allowed. For example, the following is valid:
<WATCHDOG
PINGINTERVAL
= "5"
ENABLE =
"YES" />
-
The attributes can be listed in any order.
-
The WATCHDOG element must be the last element in the webcache.xml file.
For example, to specify that the watchdog process poll the cache every
8 seconds and wait 10 seconds for the cache to respond, you
use the following line in the webcache.xml file:
<WATCHDOG ENABLE="YES" PINGINTERVAL="8" PINGTIMEOUT="10" PINGURL="/"
/>
12.0 Known Bugs
Bug Number / Description
-
1283804
-
Oracle Web Cache does not serve documents with a validity level greater
than zero when the Application Web Server is down. Oracle Web Cache only
serves stale documents (that is, documents with a validity between 1 and
9) when an Application Web Server has reached its capacity, not when it
is merely unreachable.
-
1412233
-
Parsing for personalized attributes is not separated from session-encoded
URLs. There is no way for a user to specify that a particular response
document should JUST be parsed for personalized tags or JUST for session
information encoded in HREFs in the response body.
-
See Also: Section 2.2
-
1412247
-
Web Cache cannot cache HTTP multi-part responses to accept Range requests.
-
See Also: Section 2.1
-
1416002
-
Oracle Web Cache Manager has insufficient sanity checking.
-
See Also: Section 2.5
-
1419774
-
Application Web Server load may exceed configured capacity when Oracle
Web Cache uses MORE THAN ONE Application Web Server. This may happen in
three different scenarios:
-
Oracle Web Cache balances requests to Application Web Servers by the configured
capacities. On average the distribution of load will conform to each Application
Web Server's relative capacity. This is indicated by the "Total Requests
Served" column in the Health Monitor page. Occasionally the concurrent
load on some Web servers may exceed the configured maximum capacity. This
is indicated by the "Load:max" column in the Application Web Server Statistics
page.
-
If an Application Web Server is down, its load may be distributed over
the other Application Web Servers and this may raise the load on these
remaining Application Web Servers over their configured capacity. But the
total load on all Application Web Servers will not exceed the sum of the
configured capacities.
-
If session-binding (stateful load balancing) is enabled, due to the stateful
nature of load balancing, each Web server's individual capacity may be
violated but the total capacity will not be exceeded.
-
1747522
-
There is no way to tell Web Cache that specified documents should only
be served in response to HTTPS requests. In other words, the same
document can be accessed using both HTTP and HTTPS.
-
1749448
-
Web Cache hangs after removal invalidation of all documents.
-
1749561
-
Access Log directory must end in "/" to work correctly.
13.0 Where to find more information and patch downloads
To find more information, online documentation, latest news, and patch
downloads of Oracle Web Cache, visit
-
http://otn.oracle.com/products/ias
and/or
-
http://metalink.oracle.com