14 Troubleshooting OracleAS Web Cache Configuration

14.1.1 Port Conflicts

During configuration, you configure listening ports from which OracleAS Web Cache receives browser requests. By default, the port is 7777 for HTTP requests. You can configure a port for HTTPS requests.

You also configure listening ports for administration, invalidation, and statistics monitoring requests. By default, the HTTP ports are 4000, 4001, and 4002, respectively. You also configure the advertised port number from which an origin server can receive OracleAS Web Cache requests.

When you start OracleAS Web Cache, a port conflict check is performed. If there is a port conflict, OracleAS Web Cache will fail to start. Port conflicts are reported to the event log file, event_log. The event_log file is located in $ORACLE_HOME/webcache/logs on UNIX and in ORACLE_HOME\webcache\logs on Windows. The following shows an excerpt of event_log with port conflict event messages:

[25/Jun/2003:19:12:40 +0000] [notification 9612] [ecid: -]  OracleAS Web Cache version number: 9.0.4
[25/Jun/2003:19:12:40 +0000] [notification 9403] [ecid: -] Maximum number of file/socket descriptors set to 950.
[25/Jun/2003:19:12:40 +0000] [notification 13002] [ecid: -] Maximum allowed incoming connections are 700
[25/Jun/2003:19:12:40 +0000] [alert 13305] [ecid: -] failed to assign port 7777, bind() error = Address already in use
[25/Jun/2003:19:12:40 +0000] [alert 9707] [ecid: -]  Failed to start the server.
[25/Jun/2003:19:12:40 +0000] [alert 9609] [ecid: -] The server process could not initialize.
[25/Jun/2003:19:12:40 +0000] [notification 9610] [ecid: -]  The server is exiting.

Note that the last message will only appear when the admin server process is started for the first time.

To resolve port conflicts:

1. Use OracleAS Web Cache Manager to resolve the port conflicts.

   Typically, OracleAS Web Cache and the origin server ports are in conflict. Verify the port assigned to OracleAS Web Cache in Listen Ports page (Ports > Listen Ports), and verify the host names and ports assigned to the origin servers in the Origin Servers page (Origin Servers, Sites, and Load Balancing > Origin Servers).

   If multiple instances of OracleAS Web Cache are running on a multihomed host with multiple IP addresses, a port conflict can occur. The IP address for the default HTTP and HTTPS ports is set to ANY. Upon startup, OracleAS Web Cache attempts to bind the ports to all IP addresses. If a port conflict occurs, change ANY to a specific IP address in the Listen Ports page (Ports > Listen Ports).

2. Restart OracleAS Web Cache.

   
   

   See Also: "Starting and Stopping OracleAS Web Cache"

   
   

If the administration port is in conflict, the admin server process will not start and OracleAS Web Cache Manager will not be accessible. The event log will contain messages that resemble the following output:

[25/Jun/2003:19:21:42 +0000] [alert 13305] [ecid: -] failed to assign port 4000, bind() error = Address already in use
[25/Jun/2003:19:21:42 +0000] [alert 9707] [ecid: -]  Failed to start the server.
[25/Jun/2003:19:21:42 +0000] [alert 9609] [ecid: -] The server process could not initialize.
[25/Jun/2003:19:21:42 +0000] [notification 9610] [ecid: -]  The server is exiting.

To resolve this port conflict, modify the webcache.xml file, an internal file that contains the configuration settings, and change the administration port number. The webcache.xml file is located in $ORACLE_HOME/webcache on UNIX and in ORACLE_HOME\webcache on Windows. The following shows an excerpt of the webcache.xml file with the line for the administration port shown in boldface:

...
  <MULTIPORT>
    <LISTEN IPADDR="ANY" PORT="1100" PORTTYPE="NORM"/>
    <LISTEN IPADDR="ANY" PORT="4000" PORTTYPE="ADMINISTRATION"/>
    <LISTEN IPADDR="ANY" PORT="4003" PORTTYPE="INVALIDATION"/>
    <LISTEN IPADDR="ANY" PORT="4002" PORTTYPE="STATISTICS"/>
  </MULTIPORT>
...

14.1.2 The admin Server Process Fails to Start

OracleAS Web Cache Manager does not enforce stringent validation checking. This is especially a problem when the admin server process is shut down after applying invalid configuration changes. In that case, the admin server process will not be able to start up, and the OracleAS Web Cache Manager will become inaccessible. Check the event_log file for startup errors or the Event Viewer on Windows.

To solve this problem:

• If you want to retain the configuration changes you made, send the webcache.xml file to Oracle Support Services to troubleshoot the invalid configuration entry.

• If you want to restore configuration to a previous configuration, run the webcachectl reset command to restore to the previous version of the configuration. The opmnctl utility does not provide a reset command.

14.1.3 Mismatched Oracle Home Definitions

If the definition of Oracle home in the webcache.xml configuration file is different than the definition of Oracle home in your environment, OracleAS Web Cache may fail to start.

On UNIX, you may see the following alert message in the event log:

No matching CACHE element found in webcache.xml for current host name 
(webcache-host) and ORACLE_HOME (Oracle_home).

On Windows, you may see the following message:

The description for Event ID ( 1 ) in Source ( Oracle-Web-Cache ) cannot be
found. The local computer may not have the necessary registry information or
message DLL files to display messages from a remote computer. The following 
information is part of the event: Cannot open log files because NULL socket
indicates problem.

During installation, the Oracle home is written to the ORACLEHOME attribute of the CACHE NAME element. in the webcache.xml file. The Oracle home is specified with the $ORACLE_HOME environment variable on UNIX and the ORACLE_HOME parameter located at HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE in the Windows registry.

If there is a mismatch, modify either the ORACLEHOME attribute in the webcache.xml file or the Oracle home environment setting. (In a cluster environment, there is more than one CACHE NAME element in the webcache.xml file, one for each cluster member. Be sure to modify the correct element.)

14.1.4 Privileged Ports

Port numbers less than 1024 are reserved for use by privileged processes on UNIX. If you want to configure OracleAS Web Cache to listen on a port less than 1024, such as on port 80, then the webcached executable must run as the root user.

If webcached is not run as root, the cache server process fails to start and messages similar to the following output are written to the event log file:

[25/Jun/2003:19:27:04 +0000] [notification 9612] [ecid: -]  OracleAS Web Cache version number: 9.0.4
[25/Jun/2003:19:27:04 +0000] [notification 9403] [ecid: -] Maximum number of file/socket descriptors set to 950.
[25/Jun/2003:19:27:04 +0000] [notification 13002] [ecid: -] Maximum allowed incoming connections are 700
[25/Jun/2003:19:27:04 +0000] [alert 13305] [ecid: -] failed to assign port 80, bind() error = Permission denied
[25/Jun/2003:19:27:04 +0000] [alert 9707] [ecid: -]  Failed to start the server.
[25/Jun/2003:19:27:04 +0000] [alert 9609] [ecid: -] The server process could not initialize.
[25/Jun/2003:19:27:04 +0000] [notification 9610] [ecid: -]  The server is exiting.

14.1.5 Greater Than One Thousand Maximum Connections

For OracleAS Web Cache to support more than 1,024 connections on UNIX, the webcached executable must run with the root privilege.

If webcached cannot run with the root privilege, the cache server process fails to start and messages that resemble the following output are written to the event log file:

[25/Jun/2003:19:30:48 +0000] [notification 9612] [ecid: -]  OracleAS Web Cache version number: 9.0.4
[25/Jun/2003:19:30:48 +0000] [alert 9604] [ecid: -] Could not increase the number of file/socket descriptors to 2250. 
[25/Jun/2003:19:30:48 +0000] [alert 9707] [ecid: -]  Failed to start the server.

14.1.6 Wallet Cannot Be Opened

When OracleAS Web Cache is unable to open a wallet, messages similar to the following output are written to the event log file:

[25/Jun/2003:19:35:00 +0000] [warning 11917] [ecid: -] SSL wallet Wallet file /etc/ORACLE/WALLETS/janedoe/ewallet.p12 does not exist
[25/Jun/2003:19:35:00 +0000] [warning 11919] [ecid: -] SSL wallet Autologin file /etc/ORACLE/WALLETS/janedoe/cwallet.sso does not exist -  Wallet does not appear to be autologin wallet.
[25/Jun/2003:19:35:00 +0000] [warning 11922] [ecid: -] Wallet wallet fails to open at location /etc/ORACLE/WALLETS/janedoe, NZERROR 28759, as user janedoe
[25/Jun/2003:19:35:00 +0000] [alert 9609] [ecid: -] The server process could not initialize.
[25/Jun/2003:19:35:00 +0000] [notification 9610] [ecid: -]  The server is exiting.

To resolve this error, perform the following procedure:

1. Ensure that the wallet directory exists:

   • /etc/ORACLE/WALLETS/user_name on UNIX

   • %USERPROFILE%\ORACLE\WALLETS on Windows

2. Ensure that the auto-login file cwallet.sso and wallet file ewallet.p12 exist.

   If these files do not exist, then an auto-login wallet does not exist. In this case, create the wallet and enable auto-login.

   
   

   See Also: "Task 1: Create Wallets"

   
   

3. Ensure that Oracle Wallet Manager can open the wallet.

   If Oracle Wallet Manager cannot open the wallet, then the wallet is corrupt. In this case, re-create the wallet.

   
   

   See Also: "Task 1: Create Wallets"

   
   

Restart OracleAS Web Cache with the following command:

opmnctl restartproc ias-component=WebCache

Then, recheck the event log for wallet errors.

14.3.1 Template Syntax Error Example

Consider a template named exlusion.html that contains syntax for a nonexistent ESI tag named <esi:exclude>:

<html><body> 
Simple inclusion test.
<esi:exclude src="/cgi-bin/esi-headers.sh?/esi/fragment1.html"/ 
</body></html> 

The response returned to the browser follows:

<HTML><HEAD><TITLE>Unsupported ESI feature</TITLE></HEAD> 
<BODY>Some ESI features on this page are not supported. 
</BODY></HTML> 

The following shows an event log excerpt that indicates a problem with the <esi:exlude> keyword:

[24/Mar/2003:16:02:12 -0500] [detail] [ecid: 25732665668,0] [client: 127.0.0.1] [host: www.company.com:80] [url: /cgi-bin/esi-headers.sh?/esi/exclusion.html] 
[24/Mar/2003:16:02:12 -0500] [error 12086] [ecid: 25732665668,0] ESI syntax error. Unrecognized keyword exclude is at line 2. 
[24/Mar/2003:16:02:12 -0500] [warning 11064] [ecid: 25732665668,0] ESI document
 www.company.com:80/cgi-bin/esi-headers.sh?/esi/exclusion.html parsing error 

14.3.2 Fragment Syntax Error Example

Consider a template named inclusion_exclusion.html that contains the following syntax for including fragment exlusion1.html. Notice that HTML does not contain any ESI exception handling tags or attributes.

<html><body> 
Simple inclusion test.
<esi:include src="/cgi-bin/esi-headers.sh?/esi/frag_exclusion.html"/> 
</body></html> 

Fragment frag_exclusion.html contains syntax for a nonexistent ESI tag named <esi:exclude>:

<esi:exclude src="/cgi-bin/esi-headers.sh?/esi/fragment1.html"/ 

The response returned to the browser follows:

<HTML><HEAD><TITLE>ESI Processing Exception</TITLE></HEAD> 
<BODY>The page caused an ESI processing exception. 
</BODY></HTML> 

The following shows an event log excerpt that indicates a problem with the <esi:exlude> keyword. As a result of this error and the fact that the ESI in the template does not specify any alternative fragment to serve, the browser is served an ESI exception.

[24/Mar/2003:16:10:40 -0500] [detail] [ecid: 25733186204,0] [client: 127.0.0.1] [host: www.company.com:80] [url: /cgi-bin/esi-headers.sh?/esi/inclusion_exclusion.html] 
[24/Mar/2003:16:10:40 -0500] [error 12086] [ecid: 25733186204,0] ESI syntax error. Unrecognized keyword exclude is at line 2. 
[24/Mar/2003:16:10:40 -0500] [warning 11064] [ecid: 25733186204,0] ESI document www.company.com:80/cgi-bin/esi-headers.sh?/esi/frag_exclusion.html parsing error 
[24/Mar/2003:16:10:40 -0500] [warning 12009] [ecid: 25733186204,0] Incorrect ESI fragment exception in ESI template www.company.com:80/cgi-bin/esi-headers.sh?/esi/inclusion_exclusion.html, fragment www.company.com:80/cgi-bin/esi-headers.sh?/esi/frag_exclusion.html 
[24/Mar/2003:16:10:40 -0500] [error 12012] [ecid: 25733186204,0] No exception handler is defined in template www.company.com:80/cgi-bin/esi-headers.sh?/esi/inclusion_exclusion.html:. 
[24/Mar/2003:16:10:40 -0500] [error 11368] [ecid: 25733186204,0] ESI exception error response is returned. 

14.3.3 Fragment Syntax Error with Exception Handling Example

Consider the same inclusion_exclusion.html template that contains the following syntax for including fragment frag_exclusion.html or alternative fragment fragment1.html. When the exlusion1.html fragment specified cannot be fetched, the fragment1.html fragment specified with the alt attribute is served in its place.

<html><body> 
Simple inclusion test.
<esi:include src="/cgi-bin/esi-headers.sh?/esi/frag_exclusion.html" alt="/esi/fragment1.html"/> 
</body></html> 

Fragment frag_exclusion.html contains syntax for a nonexistent ESI tag named <esi:exclude>:

Simple inclusion succeeded.
<esi:exclude src="/cgi-bin/esi-headers.sh?/esi/fragment1.html"/> 

Therefore, fragment fragment1.html is used instead of frag_exclusion.html as the fragment:

Simple inclusion succeeded.

The response returned to the browser follows:

<html><body> 
Simple inclusion test. Simple inclusion succeeded. 
</body></html> 

The following shows an event log excerpt that indicates a problem with the <esi:exlude> keyword. Because of the exception handling, the browser is served the alternative fragment instead of an ESI exception.

[24/Mar/2003:16:14:41 -0500] [detail] [ecid: 25733432444,0] [client: 127.0.0.1]
 [host: www.company.com:80] [url: /cgi-bin/esi-headers.sh?/esi/inclusion_exclusion.html] 
[24/Mar/2003:16:14:41 -0500] [error 12086] [ecid: 25733432444,0] ESI syntax error. Unrecognized keyword exclude is at line 2.
[24/Mar/2003:16:14:41 -0500] [warning 11064] [ecid: 25733432444,0] ESI document www.company.com:80/cgi-bin/esi-headers.sh?/esi/frag_exclusion.html parsing error 
[24/Mar/2003:16:14:41 -0500] [warning 12009] [ecid: 25733432444,0] Incorrect ESI
 fragment exception in ESI template www.company.com:80/cgi-bin/esi-headers.sh?/
esi/inclusion_exclusion.html, fragment www.company.com:80/cgi-bin/esi-headers.sh?/esi/frag_exclusion.html 

In addition to analyzing the event log for the sequence of events, you can also view the diagnostic and event log results in the HTML response. The following shows the HTML response when the string +wcdebug is appended is the URL. The template diagnostic information, TU;max-age=30+60;age=0, means the following:

• T means this page is composed an ESI template.

• U means this request resulted in an update of stale document.

• max-age=30+60 means that the document is to expire in 30 seconds from population and to be removed from the cache 60 seconds from the expiration. This provides a total of 90 seconds from population.

• age=0 in age means that 0 seconds have passed since population of the cache, meaning there are 30 seconds to expiration and 60 seconds to removal.

The fragment diagnostic information, FM;max-age=30+0;age=0, means the following:

• F means this page is an ESI fragment.

• U means this request resulted in a cache miss.

• max-age=30+0 means that the document is to expire in 30 seconds from population and to be removed from the cache 0 seconds from the expiration. This provides a total of 30 seconds from population.

• age=0 in age means that 0 seconds have passed since population of the cache, meaning there are 30 seconds to expiration and removal.

Web Cache Debug Info: Web Cache Debug Info: TU;max-age=30+60;age=0 
Simple inclusion test: Web Cache Debug Info: Web Cache Debug Info: TU;max-age=30+60;age=0 
Web Cache Debug Info: FM;max-age=30+0;age=0 

[EVENTLOG] 
[24/Mar/2003:16:17:23 -0500] [detail] [ecid: 25733598670,0] [client: 127.0.0.1] [host: www.company.com:80] [url: /cgi-bin/esi-headers.sh?/esi/inclusion_exclusion.html] 
[24/Mar/2003:16:17:23 -0500] [error 12086] [ecid: 25733598670,0] ESI syntax error. Unrecognized keyword exclude is at line 2. 
[24/Mar/2003:16:17:23 -0500] [warning 11064] [ecid: 25733598670,0] ESI document www.company.com:80/cgi-bin/esi-headers.sh?/esi/frag_exclusion.html parsing error 
[24/Mar/2003:16:17:23 -0500] [warning 12009] [ecid: 25733598670,0] Incorrect ESI
 fragment exception in ESI template www.company.com:80/cgi-bin/esi-headers.sh?/
esi/inclusion_exclusion.html, fragment www.company.com:80/cgi-bin/esi-headers.sh?/esi/frag_exclusion.html 
Simple inclusion succeeded.