10
Troubleshooting Oracle Web Cache Configuration

This chapter describes common configuration problems and debugging techniques for resolving them.

This chapter contains these topics:

• Startup Failures

• Application Web Server Capacity

• Wrong or Older Cached Content

• Load on Oracle Web Cache Computer

• Configuration Changes Made in Oracle Web Cache Manager

Startup Failures

If Oracle Web Cache does not start, it can be because of the following problems:

• Port Conflicts

• Cache Memory

• Privileged Ports

• Greater Than One Thousand Maximum Connections

• Wallet Cannot Be Opened

Port Conflicts

During configuration, you configure a listening port from which Oracle Web Cache receives browser requests. By default, this port is 1100. You also configure listening ports for administration, invalidation, and statistics monitoring requests. By default, these ports are 4000, 4001, and 4002, respectively. In addition to configuring listening ports for Oracle Web Cache, you also configure the advertised port number from which the application Web server(s) can receive Oracle Web Cache requests.

When you start Oracle Web Cache, a port conflict check is performed. If there is a port conflict, Oracle 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:

11/May/2001:11:04:42 -0800 -- Error: A failure occurred ( Address already in use
) when assigning a port ( domain: <NONE>, address: 0.0.0.0, port: 1100). Change
PORT attribute of the LISTEN element in the configuration file to a suitable
unused port.
11/May/2001:11:04:42 -0800 -- Error: Failed to start the server.
11/May/2001:11:04:42 -0800 -- Error: The server could not initialize
11/May/2001:11:04:42 -0800 -- Information: The server is exiting
11/May/2001:11:04:05 -0800 -- Warning: The admin server couldn't start the cache
server, running in admin-only mode.

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 Oracle Web Cache Manager to resolve the port conflicts.

   Typically, the Oracle Web Cache and the application Web server ports are in conflict. Verify the port assigned to Oracle Web Cache at Administering Web Sites > Web Cache Listen Port, and verify the host names and ports assigned to the application Web servers at Administering Web Sites > Application Web Servers.

2. Restart Oracle Web Cache.

   See Also: "Starting and Stopping Oracle Web Cache"

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

11/May/2001:10:56:11 -0800 -- Error: A failure occurred ( Address already in use
) when assigning a port ( domain: <NONE>, address: 0.0.0.0, port: 4000 ). Change
PORT attribute of the LISTEN element in the configuration file to a suitable
unused port.
11/May/2001:10:56:11 -0800 -- Error: Failed to start the server.
11/May/2001:10:56:11 -0800 -- Error: The server could not initialize
11/May/2001:10:56:11 -0800 -- Information: 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:

<?xml version="1.0"?>
<!DOCTYPE CALYPSO SYSTEM "internal:///webcache.dtd">
<CALYPSO>
  <VERSION DTD_VERSION="2.0"/>
  <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>

Cache Memory

Oracle Web Cache preallocates a large memory pool for data storage. When Oracle Web Cache is started, the admin and the cache server processes require 200 MB of memory to start. If there is not enough physical or virtual memory for these processes, the cache server process fails to start and messages that resemble the following output are written to the event log.

10/Oct/2000:10:58:02 -0600 -- Error: Oracle Web Cache Cache failed to initialize
10/Oct/2000:10:58:02 -0600 -- Error: The server could not initialize
10/Oct/2000:10:58:02 -0600 -- Information: The server is exiting
10/Oct/2000:10:58:02 -0600 -- Warning: The admin server couldn't start the cache 
server, running in admin-only mode

To resolve this cache memory issue:

1. Allocate additional memory for the admin and the cache server processes to start.

2. Restart Oracle Web Cache.

   See Also: "Starting and Stopping Oracle Web Cache"

Privileged Ports

Port numbers below 1024 are reserved for use by privileged processes on UNIX. If you want to configure Oracle Web Cache to listen on a port below 1024, such as on port 80, change the ownership of the webcached executable to root and run it as root. By default, the user that performed the installation is the owner of Oracle Web Cache executable.

To configure a privileged port:

1. Start Oracle Web Cache Manager.

   See Also: "Starting Oracle Web Cache Manager"

2. Configure the privileged port:
   1. In the navigator pane, select Administering Web Sites > Oracle Web Cache Listen Ports.

      The Oracle Web Cache Listen Ports page appears in the right pane.

   2. In the Oracle Web Cache Listen Ports page, choose Add.

      The Edit/Create Web Cache Listen Ports page dialog box appears.

   3. In the Oracle Web Cache IP Address field, enter the IP address of the computer running Oracle Web Cache.

   4. In the Oracle Web Cache Listening Port field, enter the listening port from which Oracle Web Cache will receive Web browser requests for the Web site. Ensure this port number is not already in use.

   5. Choose Submit.

3. Change the process identify of the webcached executable.

   If Oracle Web Cache was installed by the root user, change the user ID and group ID to the desired running process identify for Oracle Web Cache. The webcached executable will still be owned by root, but it will take on the new process identify once the privileged port is opened.

   If Oracle Web Cache was installed by a non-root user, you may want to change the user ID and group ID to a different user and group ID, such as nobody/nobody.

   To change the process identity:

   1. In the navigator pane, select Administering Oracle Web Cache > Process Identity.

      The Process Identity page appears in the right pane.

   2. In the Process Identity page, choose Change IDs.

      The Change Process Identity dialog box appears.

   3. Enter the new user in the New User ID field and the group ID of the user in the New Group ID field.

   4. Choose Submit.

4. In the Oracle Web Cache Manager main window, choose Apply Changes.

5. If not already owned by root, change the ownership of the webcached executable to root.
   1. Exit from Oracle Web Cache Manager, stop Oracle Web Cache, and log out of the computer.

      See Also: "Starting and Stopping Oracle Web Cache"

   2. Log back in as root.

   3. Change the ownership of the executable webcached to root.

6. Change the group of the executable webcached to the group ID you configured in Step 3.

7. Add set-user ID permission to the webcached executable.

8. Log out of the computer, and re-login as the user configured in the Process Identify page.

9. Start Oracle Web Cache.

   When Oracle Web Cache starts, it listens on the privileged port with the new process identity.

   See Also: Operating system documentation for information about changing ownership

Greater Than One Thousand Maximum Connections

See Also: "Task 4: Set Resource Limits"

As long as the executable webcached is owned by root, Oracle Web Cache can support more than 1,000 connections on UNIX. The number of connections is specified in the Current Maximum incoming connections field of the Resource Limit page (Administering Oracle Web Cache > Resource Limits) of Oracle Web Cache Manager.

If webcached is not owned by root, then the cache server process fails to start and messages that resemble the following output are written to the event log:

20/Apr/2001:18:18:24 -0800 -- Error: Could not increase number of file/socket 
descriptors to 10220.

20/Apr/2001:18:18:24 -0800 -- Error: Failed to start the server.

To change the ownership of the webcached executable to root:

1. Stop Oracle Web Cache, and then log out of the computer.

   See Also: "Starting and Stopping Oracle Web Cache"

2. Log back in as root.

3. Change the ownership of the executable webcached to root.

4. Add set-user ID permission to the webcached executable.

5. Log out of the computer, and re-login as the user configured in the Process Identify page (Administering Oracle Web Cache > Process Identity).

6. Start Oracle Web Cache.

   When Oracle Web Cache starts, it will listen on the privileged port with the new process identity.

   See Also: Operating system documentation for information about changing ownership

Wallet Cannot Be Opened

If Oracle Web Cache is unable to open a wallet, messages that resembles the following output are written to the event log:

14/Sep/2001:13:16:14 -0700 -- Information: The server is exiting
14/Sep/2001:13:16:14 -0700 -- Information: OracleOraHome81WebCacheMon stopping
14/Sep/2001:13:16:24 -0800 -- Error: Oracle Wallet Failed to open at location 
System Default Location. Only Auto Login Wallets Supported.
14/Sep/2001:13:16:24 -0800 -- Error: The server could not initialize
14/Sep/2001:13:16:24 -0800 -- Information: The server is exiting
14/Sep/2001:13:16:24 -0800 -- Error: Cannot open log files because NULL socket 
indicates problem

To resolve this error, perform the procedure that follows. At the end of each step, restart Oracle Web Cache with the webcachectl start command, and recheck the event_log file for the "Oracle Wallet Failed..." error.

1. Follow the "Enabling Wallets to Open on Windows" to ensure that the wallet can be opened at startup.

2. Ensure that the wallet directory exists:
   • /etc/ORACLE/WALLETS/user_name on UNIX

   • %USERPROFILE%\ORACLE\WALLETS on Windows NT and Windows 2000

3. Ensure that wallet files cwallet.sso and ewallet.der exist.

   If these files do not exist, then the wallet does not exist.

   If these files do exist, then the wallet user may not match Oracle Web Cache user. Continue to Step 4.

4. Locate the <WALLET> line in the webcache.xml file:

   <?xml version="1.0"?>
   <!DOCTYPE CALYPSO SYSTEM "internal:///webcache.dtd">
   <CALYPSO>
     <VERSION DTD_VERSION="2.0"/>
     <MULTIPORT>
       <LISTEN IPADDR="ANY" PORT="1100" PORTTYPE="NORM"/>
       <LISTEN IPADDR="ANY" PORT="1101" PORTTYPE="NORM" 
   SSLENABLED="SSLV3_V2H"/>
       <LISTEN IPADDR="ANY" PORT="4000" PORTTYPE="ADMINISTRATION"/>
       <LISTEN IPADDR="ANY" PORT="4001" PORTTYPE="INVALIDATION"/>
       <LISTEN IPADDR="ANY" PORT="4002" PORTTYPE="STATISTICS"/>
     </MULTIPORT>
     <WALLET>file:C:\oracle\ora81\webcache\wallets\client</WALLET>
   

   Add a PASSWORD attribute to the <WALLET> element as follows:

   <WALLET PASSWORD="password">wallet_location</WALLET>
   

   The following example shows a wallet password of oracle:

   <WALLET 
   PASSWORD="oracle">file:C:\oracle\ora81\webcache\wallets\client</WALLET>
   
   

5. Confirm that the following conditions do not apply:
   • The user that saved the wallet does not match the user that starts the webcached and webcachectl executables.

     Change the user name of wallet to match the user that starts the webcached and webcachectl executables.

   • The wallet was copied from one computer to another.

     Create the wallet on the computer with the Oracle Wallet Manager.

   See Also: "Task 3: Specify Web Site Settings" for instructions on setting the user ID of the Oracle Web Cache executables "Creating a Wallet" for instructions on creating the wallet

6. 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, recreate the wallet.

   See Also: "Creating a Wallet"

Application Web Server Capacity

If an application Web server has reached capacity, then the following error message appears when accessing pages of a Web site:

The application Web server is busy. Possible reach capacity.

This error indicates that the application Web server has reached capacity--that is, the number of concurrent connections has been exceeded. To resolve this problem, you can either:

• Increase capacity

  In the Administering Oracle Web Cache > Resource Limits page of Oracle Web Cache Manager, check the value of the Current Maximum incoming connections field. This field provides the currently configured capacity. If the capacity can be adjusted, increase it.

  See Also: "Task 3: Specify Web Site Settings"

• Evaluate the caching rules to determine if additional content can be cached

  See Also: Chapter 6, "Creating Rules for Cached Content"

Wrong or Older Cached Content

If Oracle Web Cache is serving wrong or older content, perform these steps:

1. Check the correctness of rules.

2. Check the precedence, or order, of rules.

   See Also: Chapter 6, "Creating Rules for Cached Content"

3. Validate caching rules by analyzing the content of the access log file, access_log, and the event log file, event_log. If verbose logging is turned on in the event log, then error messages about the cacheability rules will be reported.

   See Also: "Configuring Event Logs" for further information about turning on verbose logging

Load on Oracle Web Cache Computer

On UNIX operating systems, the top and uptime utilities report a higher than expected average load when the Oracle Web Cache computer is idle. This occurs because Oracle Web Cache performs light maintenance work, even when it is idle. During idle mode, the following effect occurs:

• The uptime load--the average kernel scheduler queue length--is going to be longer. Oracle Web Cache increases the average queue length (uptime output) by roughly 1.

• The CPU load is still low because the work Oracle Web Cache performs is minimal.

Configuration Changes Made in Oracle Web Cache Manager

Configuration changes made in Oracle Web Cache Manager require the following steps:

1. In the Oracle Web Cache Manager main window, choose Apply Changes.

2. Stop, and then restart Oracle Web Cache.

If these steps are not followed, configuration changes will not take effect.

The currently displayed status message in Oracle Web Cache Manager informs you if one of these steps needs to be performed.

See Also: "Starting and Stopping Oracle Web Cache" "Status Messages" for further information about status message in Oracle Web Cache Manager

Note: When you stop Oracle Web Cache, all objects are cleared from the cache. In addition, all statistics are cleared.