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 ":" where " and are as entered in the location bar of the browser, even if the 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: OracleWebCacheAdmin OracleWebCache 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 OracleWebCacheAdmin 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 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://:/ 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://:/. 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 and , 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.