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:

TABLE OF CONTENTS


 

1.0 Configuring Oracle Web Cache


To start initial Oracle Web Cache configuration:

  1. If not currently logged on to the Oracle Web Cache computer, log in with the user ID of the user that performed the installation.
  2. Start Oracle Web Cache. From the command line, enter: webcachectl start
  3. Start Oracle Web Cache Manager:
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:
  1. 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.
  2. 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:

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


 

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:
 

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:
  1. 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;
  2. log in as root;
  3. change the owner of the executable 'webcached' to root;

    4. $ chown root /opt/oracle/webcache/bin/webcached
  4. change the group of the executable 'webcached' to the group id of the desired running process identity, such as nobody:

    5. $ chgrp <groupid> /opt/oracle/webcache/bin/webcached
  5. add set-user-id permission to the executable 'webcached';

    6. $ chmod u+s /opt/oracle/webcache/bin/webcached
  6. exit from root;
  7. start Oracle Web Cache through webcachectl. Oracle Web Cache should be listening on the desired port with the desired process identity (nobody/nobody).

    8. $ /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: 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:

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:

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:

            The default value is NO. (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:

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:

         <WATCHDOG
                PINGINTERVAL           =        "5"
                ENABLE     =
                  "YES"       /> 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


 

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