Oracle Web Cache for Windows NT Release Notes
Release 1.0.2.3.0

************************************************************************
Copyright (C) Oracle Corporation 2000

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.

************************************************************************

TABLE OF CONTENTS

1.0 Release Information

2.0 Configuring Oracle Web Cache

3.0 Oracle Web Cache Limitations

4.0 Netscape Limitations

5.0 Oracle Application Server Limitations

6.0 Oracle Web Cache NT Services

7.0 Oracle Web Cache Default Ports

8.0 Oracle Web Cache Usage Examples

9.0 Latest Information and Patch Downloads

10.0 Known Bugs

11.0 Bugs Fixed in Version 1.0.2.2.0

11.0 Bugs Fixed in Version 1.0.2.3.0


************************************************************************

1.0 Release Information
------------------------

This release of Oracle Web Cache shipping with Oracle9i Application
Server release 1.0.2 on Windows NT is 1.0.2.1. This is the first Windows NT
release of Oracle Web Cache.

2.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:
        a. Point your browser to the following URL:
           http://web_cache_hostname:4000/

        b. When prompted for the administrator user ID and password,
           enter administrator for the user name and the appropriate
           password (NOT to be confused with the NT administrator account).
           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.


3.0 Oracle Web Cache Limitations
--------------------------------

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

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

3.3 Application Web Server Recovery

Oracle Web Cache can support multiple (up to 100) application Web
servers.  If any configured application Web server fails to serve
requests from Oracle Web Cache for several times in a row, the server
will be removed from application Web server load balancing
list. However, Oracle Web Cache will try to detect the recovery of all
failed Web servers periodically.

In this release, it is hard-coded that Oracle Web Cache will remove an
application Web server from load balancing list after 5 consecutive
request failures. Oracle Web Cache will then attempt to detect Web
server recovery every 60 seconds.

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

3.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 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.6 Maximum number of connections

This release of Oracle Web Cache can handle a maximum of 1024
file/socket descriptors. The maximum number of incoming connections
is: [1024 - 20 (for internal file management) - (sum of application
Web server capacity)].

A patch to remove this limitation will be posted to the Oracle
Technology Network Web site soon. See Section 9.0.

4.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. If you plan to support Netscape Navigator for your Web
site, please make sure in your cacheability rules that only cached
HTML file are compressed.


5.0 Oracle Application Server Limitations
-----------------------------------------

5.1 Oracle Web Cache with Oracle Application Server on the
    same computer

NOTE: This limitation applies to Oracle Application Server using the
Oracle Web Listener ONLY. This does not apply to other listeners used
with Oracle Application Server.

5.1.1 Introduction

5.1.1.1 Oracle Web Listener and the Host header

Oracle Application Server, 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 a HTTP error code 400 with the message: "The
request did not specify a valid virtual host".

5.1.1.2 Deployments

This limitation applies to the following deployments:

1) In Oracle Application Server 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.

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

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

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

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

5.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: 5.1.1.3 for how this can be done on computer m1


6.0 Oracle Web Cache Windows NT Services
-------------------------------------------

The installation of Oracle Web Cache installs two Windows NT services,
including:

Oracle<ORACLE_HOME>WebCacheAdmin
Oracle<ORACLE_HOME>WebCache

These services can be managed individually from the Control
Panel's Services window. The webcachectl utility (located in
%ORACLE_HOME%\bin) can also be used to start, stop or query the
status of these services.

The Oracle<ORACLE_HOME>WebCacheAdmin service needs to be running in order
to access the Web Cache Manager.


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
zerver 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\bin\webcachectl start

to start both the admin server and the cache server.

Note: This is the ONLY case where you need to edit the Oracle Web
Cache configuration file directly. Except for this single scenario,
you should NEVER edit any 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 WWW
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,
restart the admin server. After reconfiguring any other
ports, restart the cache server.

To restart the admin server, execute the following
commands:

webcachectl stop
webcachectl start

from your %ORACLE_HOME%\bin directory

8.0 Oracle Web Cache Usage Examples
------------------------------------

To find examples of how to use Oracle Web Cache, read
%ORACLE_HOME%\webcache\examples\README.examples.


9.0 Latest 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.

10.0 Known Bugs
--------------

Bug Number Description

1575246 Invalidation only works with PREFIX=YES, or in the administration
        "Cache Clean Up" page, with the checkbox "apply to all documents
        matching prefix" checked.

1574075 The statistics pages in the administration GUI contain incorrect
        information. Fields such as number of documents in the cache,
        number of requests per second, and application web server statistics
        are not updated correctly.

1412247 Web Cache cannot cache HTTP multi-part responses to
	accept Range requests.
	See Also: Section 3.1

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 3.2

1416002 Oracle Web Cache Manager has insufficient sanity checking.
	See Also: Section 3.5

1411997 Oracle Web Cache adds white space to certain HTTP headers when
	forwarding requests to application Web Servers.

	For example, the incoming request header:
	Accept-Language: en-us,zh-hk;q=0.5
	is forwarded as:
	Accept-Language: en-us, zh-hk; q=0.5

	This is not a violation of the HTTP specification, which
	allows white space between tokens in a header. See RFC 2616,
	section 2.1, last paragraph titled "implied *LWS". However, an
	application Web server that does not tolerate this extra white space
	may fail.

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
	Web server has reached its capacity, not when it is merely
	unreachable.

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:

	1. Oracle Web Cache balances requests to application Web servers by
	the configured capacities. On average the distribution of load will
	conform to each application Webserver's relative capacity. This is
	indicated by the "Total Requests Served" column in the Health Monitor
	page. Occasionally the concurrent load on some application Webservers may exceed
	the configured maximum capacity. This is indicated by the "Load:max"
	column in the Application Web Server Statistics page.

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

	3. If session-binding (stateful load balancing) is enabled, due to the
	stateful nature of load balancing, each application Web server's individual
	capacity may be violated but the total capacity will not be exceeded.


11.0 Bugs Fixed in Version 1.0.2.2.0
------------------------------------

Bug Number Description

1499009 IP address specified in "Listen Ports" gets reversed.

1508625 After the max connection limit has been reached, Web Cache doesn't
        listen on most ports even if the current connection count drops below
        limit.

1510513 Access logging configuration page in Web Cache Manager layout problem.

1510945 Potential memory access error when a failed application web server
        recovers.

1516977 Web Cache server crashes without explicit command line parameters.


1520719 Each invalidation message causes a file descriptor leak.



12.0 Bugs Fixed in Version 1.0.2.3.0
------------------------------------

The following bugs have FIXED in this version. The Description is
an elaboration of the problem as reported.

Bug Number Description

1581068 When some Uris are configured to be cacheable with only the POST HTTP
	method , "POST" is not  appended to the key, resulting in these documents
	being served out from the cache for other request methods also.

1581045 When a request is made for a cacheable document, if the response from
	the application web server contains a session cookie whose value is
	different from that in the request, web cache does not cache the response.

1569752 When WebCache requests documents from the origin server, it adds a
	trailing white space at the end of the HTTP request line which does not
	conform to RFC 1945.

1581660 The content within the personalized contents i'e within the
	<!-- WEBCACHETAG=  --> and <!-- WEBCACHEEND-->, cannot have hrefs. The
	WebCache parser fails when it has hrefs.

1581630 In case of  cache hits with session/personalized attribute substitution,
	some HTTP response  headers appear in  the begining of the response body.

1581602 In some resonses with many set-cookie response headers, not all of them
	are stripped when cached. This is because calypso until 1.0.2.2.0 has a
	compiled suppport limit of 5 set-cookie headers in each cacheable document.
	This has been increased to 20 now.

1577907 In OS failover, a document header buffer is freed twice resulting in
	core dumps afterwards.

1570942 ClientIP address is not passed to backend webserver.

1530453 When post requests are cacheable, sometimes the post body is not appended
	to the cache document key.

1562818 Default port for Application Web Server is set to 7777 instead of 80, which
        causes a network error to be returned when accessing the Listen port (1100).

1574075 Stats pages show incorrect numbers for NT Port.

