2 Getting Started with Administering Oracle Web Cache

This chapter describes how to get started with administering Oracle Web Cache. It discusses the main administration tasks.

This chapter includes the following topics:

2.1 About Oracle Web Cache Management Tools

Oracle stores configuration for Oracle Web Cache in the webcache.xml file, located in the following directories:

(UNIX) ORACLE_INSTANCE/<instance_name>/config/WebCache/<webcache_name>
(Windows) ORACLE_INSTANCE\<instance_name>\config\WebCache\<webcache_name>

Oracle offers two tools for managing Oracle Web Cache:

  • Oracle Enterprise Manager Fusion Middleware Control. See Section 2.6.

  • Oracle Web Cache Manager. See Section 2.7.

Use these tools rather than edit the webcache.xml configuration file, to perform all administrative tasks unless a specific procedure requires you to edit a file. Editing a file may cause the settings to be inconsistent and generate problems.

2.2 About Site Configuration

Oracle Web Cache caches and assembles dynamic content for one or more Web sites. When you configure the following properties for Oracle Web Cache, you apply them to all sites or to a particular site:

  • Sessions

  • Security

  • Request filtering

  • Caching rules

  • Access logging

You must create site definition for any named sites. A site definition consists of a host name, port information, and optional URL path prefix about the site and its aliases. Alias information is essential, because many sites are represented by one or more aliases. Oracle Web Cache recognizes and caches requests for a site and its aliases. For example, site www.company.com:80 may have an alias of company.com:80. By specifying this alias, Oracle Web Cache caches the same content from either company.com:80 or www.company.com:80.

When configuring a named site, you can enable compression for a site, permitting Oracle Web Cache to perform automatic compression for that site. You can also configure compression for undefined sites. Oracle Web Cache uses the compression setting for undefined sites for client requests that do not match a defined site. If you prefer to disable compression for all requests, see Section 2.11.3.1.

In addition to configuration for named sites and undefined sites, Oracle Web Cache provides configuration for a default site for client requests without host information. When you install Oracle Web Cache, the default site uses the host name and listening port of the computer on which Oracle HTTP Server was installed.

Because Oracle Web Cache resolves a request first to a site definition, and then to the first matching site-to-origin server mapping, the order in which you configure the site definitions is important.

For example, consider site definitions configured in this order:

www.company.com:80
www.company.com:80/sales

Because www.company.com:80 is a superset of www.company.com:80/sales, Oracle Web Cache matches requests for www.company.com:80/sales to site definition www.company.com:80 rather than www.company.com:80/sales. In addition, Oracle Web Cache uses the site-to-server mapping for www.company.com:80.

To avoid this problem, you would have to configure the site definitions in the following order:

www.company.com:80/sales
www.company.com:80

After you create site definitions, create ordered mappings of sites to origin servers. To avoid requests being mapped to the wrong site, you must be careful in how you order these mappings:

  • Because mappings that use the wildcard * encompass a broader scope, give these mappings a lower priority than other mappings.

  • Because requests are resolved to the first matching mapping, give mappings that contain the optional URL path prefix a higher priority than those mappings without an URL path prefix.

    For example, you should order the following mappings as follows:

    http://www.company.com/portal/page?_pageid=33,4232&_dad=portal

    http://www.company.com/um/traffic_cop?mailid=inbox
http://www.company.com

    If you instead reorder the mappings as follows, the request for URLs http://www.company.com/portal/page?_pageid=33,4232&_dad=portal and http://www.company.com/um/traffic_cop?mailid=inbox do not resolve as expected. Requests for these URLs instead resolve to http://www.company.com because it is listed first:

    http://www.company.com
http://www.company.com/portal/page?_pageid=33,4232&_dad=portal
http://www.company.com/um/traffic_cop?mailid=inbox

For instructions on creating site definitions and site-to-server mappings, see Section 2.11.3 and Section 2.11.4.

2.3 About Resource Limits in Oracle Web Cache Management

As a part of configuration, specify caching and network thresholds to ensure Oracle Web Cache runs efficiently.

Oracle Web Cache provides the following types of configurable thresholds:

2.3.1 Maximum Cache Size

When the maximum cache memory limit is reached, Oracle Web Cache performs garbage collection. During garbage collection, Oracle Web Cache removes stale objects based on popularity and validity. In a cache cluster environment, Oracle Web Cache removes on-demand objects before it removes owned objects.

To avoid swapping objects in and out of the cache, it is crucial to configure enough memory for the cache. Generally, the amount of memory (maximum cache size) for Oracle Web Cache should be set to at least 512 MB.

Your application's memory requirements vary based upon factors, such as object size, number of objects, the number of HTTP headers returned, and whether ESI is present. To get a close approximation on the maximum amount of memory required, you may apply the formula provided below.

Most customers leave this setting to the default which is 500 MB. If want to change the default, perform the following steps to determine the maximum amount of memory required:

  1. Use the following formula to determine an estimate of the maximum memory, in bytes, needed

    1.25*(TotalDocs * ((AvgDocSize/8192+1) *8192 + 16384))

    In the formula:

    • .25 accounts for the run time memory overhead.

    • TotalDocs is the total number of objects you intend to store in the cache.

    • AvgDocSize is the average size of objects, in bytes, you intend to store in the cache. You can determine the average size by viewing the following metrics on the Performance Summary page.

      • Performance of each Site with Summary > site > Cache Size

      • Performance of each Site with Summary > site > Number of Cached

      See Section 8.4 for further information about the Performance Summary page.

    Note:

    Even though you specify that certain objects should be cached, not all of the objects are cached at the same time. Only those objects that have been requested and are valid are stored in the cache. As a result, only a certain percentage of your objects are stored in the cache at any given time. That means that you may not need the maximum memory derived from the preceding formula.

  2. Convert the result to megabytes.

  3. Specify the estimated memory in the Oracle Web Cache configuration. See Section 2.11.5.

  4. Use a simulated load or an actual load to monitor the cache to see how much memory it really uses in practice.

    Remember that the cache is empty when Oracle Web Cache starts. For monitoring to be valid, ensure that the cache is fully populated. That is, ensure that the cache has received enough requests so that a representative number of objects are cached.

    The Performance Summary page of Fusion Middleware Control provides information about the current memory use and the maximum memory use. To access this page:

    1. Navigate to the Web Cache Home page in Fusion Middleware Control. See Section 2.6.2.

    2. From the Web Cache menu, select Monitoring and then Performance Summary.

2.3.2 Maximum Incoming Connections

In addition to the cache size, it is important to specify a reasonable number for the maximum connection limit for the Oracle Web Cache server. The default is 500. If you set a number that is too high, performance can be affected, resulting in slower response time. If you set a number that is too low, Oracle Web Cache serves fewer fewer concurrent requests. You must strike a balance between response time and the number of requests processed concurrently.

To help determine a reasonable number, consider the following factors:

  • The maximum number of clients you intend to serve concurrently at any given time.

  • The average size of a page and the average number of requests for page.

  • Network bandwidth. The amount of data that can be transferred at any one time is limited by the network bandwidth.

  • The percentage of cache misses. If a large percentage of requests are cache misses, the requests are forwarded to the application Web server. Those requests consume additional network bandwidth and result in longer response times.

  • How quickly a page is processed. Use a network monitoring utility, such as ttcp or LoadRunner, to determine how quickly your system processes a page.

  • The cache cluster member capacity, if you have a cache cluster environment. The capacity reflects the number of incoming connections from other cache cluster members. See Section 3.6.3 to configure this setting in Fusion Middleware Control and Section 3.7.1 to configure this setting in Oracle Web Cache Manager.

Use various tools, such as those available with the operating system and with Oracle Web Cache, to help you determine the maximum number of connections. For example, the netstat -a command on UNIX and Windows operating systems enables you to determine the number of established connections; the ttcp utility enables you to determine how fast a page is processed. The Web Cache Home page and the Performance Summary page in Fusion Middleware Control provide statistics on hits and misses. From Web Cache menu, select Home and Monitoring > Performance Summary to access these page.

Do not set the value to an arbitrarily high value, because Oracle Web Cache sets aside some resources for each connection, which could adversely affect performance. For many UNIX systems, 5000 is usually a reasonable number.

To specify the maximum number of incoming connections, see Section 2.11.5.

Connections on UNIX

On most UNIX platforms, each client connection requires a separate file descriptor. Oracle Web Cache tries to reserve the maximum number of file descriptors (Max_File_Desc) when it starts. If the Oracle Web Cache webcached executable is run as root, you can increase this number. For example, on Sun Solaris, you can increase the maximum number of file descriptors by setting the rlim_fd_max parameter. If the webcached executable is not run with the root privilege, Oracle Web Cache fails to start.

On most UNIX platforms, each client connection requires a separate file descriptor. The Oracle Web Cache server attempts to reserve the maximum number of file descriptors when it starts. If you have root privileges, you can increase this number. For example, for the LINUX Red Hat Operating System you can increase the maximum number of file descriptors by modifying Oracle Web Cache users file descriptors limits in /etc/security/limits.conf.

For example to allow the user WC_USER to have 4092 connections, in the /etc/security/limits.conf file add the following entries:

WC_User       soft    nofile            4092
WC_User       hard    nofile            4092

Make sure the parameter fs.file-max is set to 65k in the /etc/sysctl.conf. On Solaris Operating System you can increase the maximum number of file descriptors by setting the rlim_fd_max parameter. If webcached is not run as root, the Oracle Web Cache server logs an error message and fails to start.

For instructions on changing the webcached executable to run with the root privilege, see Section 5.9.

For more information, see:

Connections on Windows

On Windows operating systems, the number of file handles as well as socket handles is limited only by available kernel resources, more precisely, by the size of paged and non-paged pools. However, the number of active TCP/IP connections is restricted by the number of TCP ports the system can open.

The default maximum number of TCP ports is set to 5000 by the operating system. Of those, 1024 are reserved by the kernel. You can modify the maximum number of ports by editing the Windows registry. Windows operating systems allow up to 65534 ports.

To change the default, you must add a new value to the following registry key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters

Add a new value, specifying the following:

  • Value Name: MaxUserPort

  • Value Type: DWORD

  • Value Data: 65534

  • Valid Range: 5000 to 65534

On Windows operating systems, Oracle Web Cache does not attempt to reserve file handles or to check that the number of current maximum incoming connections is less than the number of TCP ports.

2.3.3 Maximum Cached Object Size

To conserve system resources, you can limit the size of objects that are cached, even if the objects meet other caching rules.

If you specify a maximum cached object size, the cache only stores objects that are not larger than a specified size and that match the caching rules. Oracle Web Cache does not cache objects larger than the specified size, even if they match caching rules. The default is 100 KB. For upgraded caches, the default is that no limit is specified.

If you have objects that are larger than the maximum cached object size and those objects are requested frequently, consider increasing the limit. When you specify a value of 0, Oracle Web Cache does not cache any objects, effectively turning off caching.

To specify the size of single cached object, see Section 2.11.5.

2.3.4 Network Timeouts

Oracle Web Cache enables you to specify settings for the following timeouts:

  • Keep-Alive Timeout: The keep-alive timeout is the time limit for the client to process a request from Oracle Web Cache. After Oracle Web Cache sends a response to a client, the connection is left open for five seconds, which is typically enough time for the client to process the response from Oracle Web Cache. If the network between the client and Oracle Web Cache is slow, consider increasing the keep-alive timeout.

  • Client Send: Specifies the allowed time for Oracle Web Cache to finish a send operation to the client.

  • Client Receive: Specifies the allowed for Oracle Web Cache to wait for a receive operation to complete from the client.

  • Origin Server Send: Specifies the time allowed for the Oracle Web Cache to finish a send operation to the origin server.

  • Origin Server Receive: Specifies the time allowed for the origin server to generate and start sending a response to Oracle Web Cache.

  • Origin Server Connect: Specifies the time allowed for Oracle Web Cache to complete connection establishment to an origin server. If an origin server has multiple IP addresses (for example., IPv4 and IPv6) that will be retried, the timeout refers to connecting to one origin server IP address. If the origin server cannot generate a response within that time, Oracle Web Cache drops the connection and sends a network error page to the client. If applications require a shorter timeout, adjust the timeout.

To specify the timeouts, see Section 2.11.5.

2.4 About Oracle Web Cache Ports

Ports are dynamically assigned to many components when they are provisioned. The port numbers stay the same after the provisioning unless they are manually changed.

Oracle Web Cache uses a HTTP or a HTTPS listening port to receive requests. In addition to a listening port, Oracle Web Cache also receives administration, invalidation, and statistics monitoring requests on specific HTTP or HTTPS listening ports.

http://web_cache_hostname:http_port 
https://web_cache_hostname:https_port

To configure port settings, see Section 2.11.1.

2.5 About IP Addresses

Oracle Web Cache supports both IP version 4 and version 6 addresses.

The following examples show IP version 4 addresses:

  • 138.1.16.102 specifies an IP address.

  • 138.1.16.102/255.255.0.0 specifies an IP address and subnet mask, 138.1.any.any. The zeros in the mask mean that any value is OK. This address is equivalent to 138.1.0.0/255.255.0.0 or 138.1.*.*.

  • 138.1.16.102/16 is another way to specify the previous example. It means that only the high 16 bits matter.

You must use the wildcard for an entire field. Therefore, you cannot use a wildcard to specify something like 138.128.0.0/255.128.0.0. In this example, the high 9 bits need to be checked. 138.128*.*.* is not allowed. 138.*.*.* would check only the high 8 bits, and the other 3 8-bit fields could have any value.

The following examples show IP version 6 addresses:

  • FE80:0:0:0:205:2FF:FE71:2594 specifies an IP address.

  • FE80:0:0:0:205:0:0:0/FFFF:FFFF:FFFF:FFFF:FFFF:0:0:0 specifies an IP address and subnet mask. Here the high 16*5 = 80 bits, where 16*5 is 16 bits from each FFFF * 5 fields of FFFF, need to be checked for a match. If you prefer to use a wildcard, you can specify the same address as FE80:0:0:0:205:*:*:*.

  • FE80:0:0:0:205:0:0:0/80 is another way to specify the previous example. It also specifies to check the high 80 bits.

You must use the wildcard for an entire field.

2.6 Getting Started with Managing Oracle Web Cache with Oracle Enterprise Manager Fusion Middleware Control

Oracle Enterprise Manager Fusion Middleware Control enables you to manage Oracle Fusion Middleware components in a farm, including Oracle Web Cache.

A farm is a collection of components managed by Fusion Middleware Control. It can contain Oracle WebLogic Server domains, one Administration Server, one or more Managed Servers, and the Oracle Fusion Middleware components that are installed, configured, and running in the domain.

From Fusion Middleware Control, you can configure the following:

  • Properties for the cache, including origin servers, sites, resource limits, passwords, sessions, and cookies

  • Event logging and access logging

  • Multiple caches into one cache cluster for shared configuration, scalability, and high availability

  • Request filtering to block invalid or illegal HTTP requests

  • Caching rules and expiration policies

Oracle Web Cache Manager provides additional configuration areas. See Section 2.7 for more information about using Oracle Web Cache Manager.

You can also monitor performance statistics and perform operational tasks, such as starting and stopping a cache, synchronizing configuration among cache cluster members using Fusion Middleware Control.

This section covers the following topics:

For general information about Fusion Middleware Control, see the Oracle Fusion Middleware Administrator's Guide.

2.6.1 Logging into Fusion Middleware Control

To view the Oracle Web Cache pages:

  1. To display Fusion Middleware Control, you enter the Fusion Middleware Control URL, which includes the name of the host and the port number assigned to Fusion Middleware Control during the installation. The following shows the format of the URL

    http://hostname.domain:port/em

    The port number is the number of the Administration Server of Oracle WebLogic Server. By default, the port number is 7001.

  2. Enter the Oracle Fusion Middleware administrator user name and password and click Login.

    The default user name for the administrator user is weblogic. The password is the one you supplied during the installation of Oracle Fusion Middleware.

2.6.2 Navigating to Oracle Web Cache Administration Pages

To navigate to Oracle Web Cache administration tasks:

  1. From the navigation pane, expand the farm and then the Web Tier installation type, and select Oracle Web Cache component.

    Description of nav.gif follows
    Description of the illustration nav.gif

    The Web Cache home page displays. See Section 2.6.3 for further information about the contents of the home page.

  2. Select the Web Cache menu.

    Description of wc_menu.gif follows
    Description of the illustration wc_menu.gif

    The Web Cache menu displays the following options described in Table 2-1

    Table 2-1 Web Cache Menu Options

    Element Description

    Home

    This option displays the Web Cache Home page. See Section 2.6.3 for further information about the contents of this page.

    Monitoring

    This option displays the following options:

    • Performance Summary: This option enables you to view performance metrics for Oracle Web Cache. See Section 8.4 for further information.

    • Popular Requests: This option enables you to view the most popular requests for determining if the caching rules are caching the correct objects. See Section 8.6 for further information.

    Control

    This option provides options for starting, stopping, and restarting Oracle Web Cache. See Section 2.13.2 for further information.

    Logs

    The View Log Message option displays the Log Messages page for viewing the contents of event log files. See Section 9.7 for further information.

    Port Usage

    This option display the ports in use. See Section 2.11.1 for more information.

    Administration

    This option displays the following options:

    • Caching Rules: This option enables you to configure caching rules. See Chapter 6, "Caching and Compressing Content," for more information.

    • Request Filters: This option enables you to configure request filters for protecting against common HTTP request attacks. See Chapter 4, "Configuring Request Filtering," for more information.

    • Expiration: This option enables you to specify expiration policies. See Section 6.7 for more information.

    • Sites: This option enables you to configure the Web sites for which Oracle Web Cache caches content. See Section 2.11.3 for more information.

    • Origin Servers: This option enables you to configure to configure application Web servers or proxy servers to which Oracle Web Cache sends cache misses. See Section 2.11.4 for more information.

    • Cluster: This option enables you to configure a cache cluster. See Section 3.6 for more information.

    • Passwords: This option enables you to configure security options for Oracle Web Cache. See Chapter 5, "Configuring Security," for more information.

    • Access Logs: This option enables you to configure settings for Oracle Web Cache access logs. See Chapter 9, "Logging," for more information.

    • Event Logs: This option enables you to configure settings for Oracle Web Cache event logs. See Chapter 9, "Logging," for more information.

    • Resource Limits: This option enables you to configure cache thresholds for Oracle Web Cache. See Section 2.11.5 for more information.

    • Passwords: This option enables you to configure security options for Oracle Web Cache. See Chapter 5, "Configuring Security," for more information.

    • Session Configuration: This option enables you to create session definitions for:

      - Specifying how session requests are served by the cache

      - Enabling session binding, whereby a user session for a particular site is bound to an origin server to maintain state for a period

      - Substituting session information in session-encoded URLs

      See Section 2.12 for more information.

    • Multi-Version Cookies: This option enables you to specify cookie values for multiple-version URLs. See Section 6.5.1 for more information.

    • Ports Configuration: This option enables you to configure ports for Oracle Web Cache. See Section 2.11.1 for more information.

    Security

    This option displays the following options:

    General Information

    This option displays general details about the instance.

2.6.3 Understanding Statistics on the Web Cache Home Page

The Web Cache Home page provides general information about the selected cache system component, as well as the supported sites and origin server.

You can also use this page as a starting point for monitoring and administering Oracle Web Cache. Figure 2-1 shows a portion of the Web Cache Home page.

Figure 2-1 Web Cache Home Page

Description of Figure 2-1 follows
Description of "Figure 2-1 Web Cache Home Page"

This page contains the following statistical regions:

Response and Load Region

Table 2-2 describes the performance-monitoring statistics in the Response and Load region.

Table 2-2 Response and Load Statistics

Statistic Description

Request Processing Time

This metric specifies the average number of milliseconds used to process requests.

Request Throughput

This metric specifies the average number of requests served for each second.

CPU and Memory Usage Region

Table 2-3 describes the performance-monitoring statistics in the Response and Load region.

Table 2-3 CPU and Memory Usage Statistics

Statistic Description

CPU Usage

This metric specifies the percentage of the CPU that is being used for Oracle Web Cache. As traffic increases, CPU utilization increases.

Memory Usage

This metric specifies the total memory used by the Oracle Web Cache component.

Performance Region

Table 2-4 describes the performance-monitoring statistics in the Origin Servers region.

Table 2-4 Performance Statistics

Statistic Description

Open Connections

This metric specifies the current number of incoming open connections to the Oracle Web Cache server.

Requests Served

This metric specifies the accumulated number of requests that Oracle Web Cache has served since it was started.

Hit Rate

This metric specifies the percentage of requests resolved by cache content.

Cached Objects

This metric specifies the total number of objects stored in the cache.

Cache Size

This metric specifies the size, in megabytes, of the objects currently stored in the cache. For a cache cluster member, this number is an aggregate of the owned and on-demand objects.

Requests Denied by Request Filtering

This metric specifies the accumulated number of requests denied by request filters.

Any nonzero number may be an indication of an attack on the site or an issue with the configuration of request filters.

Bytes Saved by Compression

This metric specifies the accumulated number of bytes that would be sent to clients if in-cache compression is disabled.

Error Pages Served

This metric specifies the accumulated number of error pages that Oracle Web Cache served to Web browsers since the cache was started.

Origin Servers Region

Table 2-5 describes the performance-monitoring statistics in the Origin Servers region.

Table 2-5 Origin Server Statistics

Statistic Description

Server

This metric displays the name of the origin server.

Current Status

This metric displays the status of the origin server when Oracle Web Cache last attempted to communicate with that origin server. (Oracle Web Cache attempts to reach the origin server only for specific purposes, such as retrieving responses for a cache miss.)

Up Time (%)

This metric is the up time is from the perspective of Oracle Web Cache. It is an approximation of the origin server's uptime. The accuracy is based on how long Web Cache has been up and how often Oracle Web Cache sends requests to that origin server.

Requests

This metric category provides the following metrics:

  • Total: This metric specifies the accumulated number of requests that the origin server has processed.

  • Errors: This metric specifies the number of errors encountered from this origin server by Oracle Web Cache. These errors may include:

    - Oracle Web Cache failed to connect to the origin server.

    - There was an error transmitting the request or receiving the response to or from the origin server

    - There was an HTTP 500 class response from the origin server.

  • Average Response Time The metric specifies the average time the origin server has taken to process and reply to requests which it has received from this Oracle Web Cache.

Capacity

This metric category provides the following metrics:

  • Current Load: The metric specifies the current number of connections from Oracle Web Cache that the origin server has open.

  • Maximum Load: The metric specifies the maximum number of connections that the origin server has had open simultaneously.

  • Configured: The metric specifies the capacity set for the server in the Origin Servers page.

Note: If the value for the Maximum Load metric is close to the Configured metric, then increase the capacity in the Origin Servers page. See Section 2.11.2.

2.6.4 Using the Fusion Middleware Control Help

The Oracle Enterprise Manager Help command on the Help menu provides users with access to task-related or conceptual information relating to the current Fusion Middleware Control page. In addition, you can click a Help icon on some pages, where further explanation of page elements is necessary.

There is also a search feature, allowing you to search the help and selected Oracle Fusion Middleware documents that are included with the online help system. The help guides you to specific, context-sensitive information in these documents.

2.7 Getting Started with Managing Oracle Web Cache with Oracle Web Cache Manager

Oracle Web Cache Manager is a graphical user interface tool that provides configuration capabilities for the following areas not provided by Fusion Middleware Control:

  • Invalidation

  • Advanced options for request filters

  • Network thresholds for Oracle Web Cache

  • Advanced security options

  • Invalidation

  • Diagnostics features

  • Error pages to be served by Oracle Web Cache

This section introduces you to the features of Oracle Web Cache Manager. This section contains these topics:

2.7.1 Starting Oracle Web Cache Manager

To start Oracle Web Cache Manager:

  1. Configure a secure password for the Oracle Web Cache administrator with the monitor account. You use the password for the monitor account to log in to Oracle Web Cache Manager. See Section 5.2 to set a secure password.

  2. Start the admin server process with the following command:

    opmnctl startproc ias-component=WebCache process-type=WebCache-admin

    WebCache-admin represents the admin server process.

  3. Determine the port for the admin server process. See Section 2.11.1.

  4. Point your browser to the following URL:

    http://web_cache_hostname:admin_port/webcacheadmin

    See Section 2.11.1.2 to determine the port.

  5. Enter the Oracle Web Cache administrator user name, administrator and the password you set in Step 1.

2.7.2 Navigating Oracle Web Cache Manager

The Oracle Web Cache Manager interface includes:

  • Top frame containing Apply Changes and Cancel Changes buttons and Oracle Web Cache status message

  • Navigator frame with configuration and monitoring menu items

  • Right frame with property sheet for selected menu item

Figure 2-2 shows the Oracle Web Cache Manager interface.

Figure 2-2 Oracle Web Cache Manager Interface

Description of Figure 2-2 follows
Description of "Figure 2-2 Oracle Web Cache Manager Interface"

The interface contains the following features:

  • The Home link directs you to a welcome page.

  • Navigation Pane provides a graphical tree view of configuration, administration, and performance monitoring capabilities for Oracle Web Cache and its supported Web sites.

  • Content Pane shows the property sheet for the selected option from the navigation pane.

  • The Apply Changes button applies submitted static and dynamic configuration changes to Oracle Web Cache; the Cancel Changes button cancels submitted static and dynamic configuration changes to Oracle Web Cache.

  • Status Message provide the following possible status messages:

    • Web Cache running with current configuration: This message appears if Oracle Web Cache is running with an up-to-date configuration.

    • Web Cache running in Routing Only mode with current configuration: This message appears if Oracle Web Cache is running with an up-to-date configuration.

    • Press "Apply Changes" to commit your modifications: This message appears if Submit has been selected in some dialog box, but the Apply Changes button has not been chosen.

    • Restart Web Cache to make configuration changes take effect: This message appears if Oracle Web Cache is running with an older version of the configuration. This can happen when static configuration changes have been applied to webcache.xml, but Oracle Web Cache was not restarted.

    • Dynamic Changes Applied. Restart Not Needed: This message appears if one or more dynamic configuration changes were applied, which do not require a restart of Oracle Web Cache.

    • Retrieve configuration from remote cache: This message appears if the cache has been recently upgraded to the current version of Oracle Web Cache but the configuration has not been copied to the local cache configuration file.

The navigator frame contains the following major categories described in Table 2-1. Additional categories and options are available, but Fusion Middleware Control provides the preferred functionality in these areas.

Table 2-6 Web Cache Manager Navigation Pane Options

Category Description

Operations

This category contains the following options:

  • Cache Operations: This option displays the Cache Operations page for starting, stopping, or restarting the cache server process. See Section 2.7.3 for further information.

  • Basic Content Invalidation: and Advanced Content Invalidation: These options enable you to invalidate content in the cache. See Section 7.7.2.1 for further information.

  • On-Demand Log File Rollover: This option enables you to immediately roll over event and access logs. See Section 9.8 for further information.

Filtering

The preferred method for configuring request filters is using Fusion Middleware Control, as described in Chapter 4, "Configuring Request Filtering." Use the Request Filters option in Oracle Web Cache Manager to copy rules and revert configuration settings, as described in Section 4.14.

Properties

This category contains the following options:

  • Security: This option provides advanced security options. See Chapter 5 for further information.

  • Network Timeouts: This option enables you to configure the network setting for connections. See Section 2.11.5 for further information.

Logging and Diagnostics

This category contains the following option:

  • Diagnostics: This option enables diagnostics information to display in the HTML response body of an object. See Section 8.8 for further information.

2.7.3 Understanding the Cache Operations Page

The Cache Operations page of Oracle Web Cache Manager (Operations > Cache Operations) provides information about the status of a cache and what operations are needed. From this page, you can start, stop, or restart a cache.

If the cache is part of a cache cluster, all caches in the cluster are listed on the Cache Operations page. In addition to starting, stopping, and restarting a cache, you can propagate the configuration to other cluster members from this page. You can perform the operations on a selected cache or on all caches in the cluster. To minimize disruption in your Web site, you can specify an interval to stagger the times that the operations begin on the caches.

2.8 Getting Started with Managing Oracle Web Cache with Oracle Process Manager and Notification (OPMN)

Oracle Process Manager and Notification (OPMN) Server manages Oracle Web Cache processes, including the admin server process and cache server process:

  • The admin server process transfers the contents of the webcache.xml configuration file between the Oracle Web Cache instance and the Oracle WebLogic Server environment where Fusion Middleware Control is running.

  • The cache server process manages the cache.

OPMN provides the opmnctl command. The command is located in the following directory:

(UNIX) ORACLE_INSTANCE/bin/
(Windows) ORACLE_INSTANCE\bin

To get started with OPMN, use the opmnctl command to query the status of the components in your installation and obtain a list of all the ports in use:

opmnctl status -l

Then, you use OPMN to control Oracle Web Cache. The following shows the format of the opmnctl commands:

opmnctl command [parameter=value] [parameter=value]

Table 2-7 shows the commands of the opmnctl utility that are applicable to Oracle Web Cache.

Table 2-7 Commands of the opmnctl Utility

Command Description

startproc

Starts the specified process or component.

stopproc

Stops the specified process or component. If used to stop the cache server process, this command also clears the cache of all content and all statistics. It waits for all currently accepted requests to be served, or until the user-specified timeout, before stopping the cache.

To stop the specified process immediately, use the WCShutdown=abort parameter shown in Table 2-8.

restartproc

Stops, then restarts the specified process or component.

startall

Starts all processes controlled by OPMN.

stopall

Stops all processes controlled by OPMN.

status

Shows the status of the processes controlled by OPMN. For more information about the options for the status command, at the command line, enter:

opmnctl status -help

Table 2-8 shows the parameters for the opmnctl utility. It also shows the valid values that are applicable for Oracle Web Cache. Unless otherwise noted, you can use any parameter with any command, except for status, listed in Table 2-7.

Table 2-8 Parameters for the opmnctl Utility

Parameter Valid Values Description

ias-component=component_name

Oracle Web Cache instance name

Takes the specified action for the Oracle Web Cache admin server process and cache server process. For example, the following command starts both the Oracle Web Cache admin server and cache server processes on system component webache1:

opmnctl startproc ias-component=webcache1

You must always specify this parameter to administer any Oracle Web Cache process.

process-type=value

WebCache

WebCache-admin

Takes the specified action for the process specified in the value:

  • WebCache: The cache server process

  • WebCache-admin: The admin server process

The parameter ias-component=component_name must precede this parameter. For example, the following command starts only the cache server process for Oracle Web Cache webcache1:

opmnctl startproc ias-component=webcache1 process-type=WebCache

WCShutdown=value

abort

Used only with the stopproc command. Aborts (immediately stops) the specified process or component. Note the following differences between a normal shutdown and an abort shutdown:

During an normal shutdown, Oracle Web Cache does not accept any new connections, but it satisfies the request for connections that were made before receiving the stopproc command. After the requests are satisfied, the cache shuts down.

During an abort shutdown, Oracle Web Cache does not accept any new connections. In addition, it drops all existing connections, even if the requests have not been satisfied. Then, the cache shuts down.

The parameter ias-component=component_name must precede this parameter.

For additional information about using OPMN and its supported commands, see Oracle Fusion Middleware Oracle Process Manager and Notification Server Administrator's Guide.

2.9 Basic Tasks for Configuring and Managing Oracle Web Cache

When you configure an environment with Oracle Web Cache, you first ensure the Oracle Web Cache component is added to the installation. If it is not, add the Oracle Web Cache component to the configuration.

The following provides a summary of the steps to configure and manage a basic Oracle Web Cache:

  1. Add Oracle Web Cache system component to an environment. See Section 2.10.

    To create a cache cluster, see Section 3.6.

  2. Specify properties for an Oracle Web Cache instance after it is added to an installation. See Section 2.11.

  3. Configure secure passwords for Oracle Web Cache. See Section 5.2

  4. Configure session definitions for session-related properties. See Section 2.12.

  5. Configure access and event logs. See Chapter 9, "Logging."

  6. Configure request filtering. See Chapter 4, "Configuring Request Filtering."

  7. Configure and monitor caching rules. See Section 6.6.

  8. Invalidate content. See Chapter 7, "Invalidating Content."

2.10 Adding an Oracle Web Cache System Component to an Environment

For an Oracle Web Tier or an Oracle Portal, Forms, Reports and Discoverer installation in which Oracle Web Cache was not selected, you can easily add an Oracle Web Cache system component, because the Oracle Universal Installer installs the necessary software.

To add an Oracle Web Cache system component to an installation:

  1. From the command line, go the following directory:

    (UNIX) ORACLE_INSTANCE/bin
(Windows) ORACLE_INSTANCE\bin

  2. Create the Oracle Web Cache system component:

    createcomponent -componentType WebCache -oracleHome ORACLE_HOME -oracleInstance ORACLE_INSTANCE -componentName component_name

    For example to create an Oracle Web Cache system component named webcache2, you would enter syntax similar to the following:

    createcomponent -componentType WebCache -oracleHome /scratch/webtier -oracleInstance /scratch/instances/instance1 -componentName webcache2

  3. Configure caching rules. See Section 6.6.

  4. Navigate to the Web Cache Home page in Fusion Middleware Control. See Section 2.6.2.

  5. View the Origin Servers section to ensure requests for the origin server are going through the Oracle Web Cache.

2.11 Specifying Properties for an Oracle Web Cache System Component

To establish properties for an Oracle Web Cache system component, perform the following tasks:

2.11.1 Task 1: Configure Port Configuration for Oracle Web Cache

Oracle Web Cache uses a HTTP or HTTPS listening port to received requests. You can add listening ports, if necessary. For example, it may be necessary to add a listening port to assign Oracle Web Cache a port that an origin server was previously listening on.

In addition to a listening port, Oracle Web Cache also receives requests for the admin server process, invalidation, and statistics monitoring requests on specific HTTP or HTTPS listening ports. You can modify these operation ports.

This section contains the following topics related to port configuration for Oracle Web Cache:

2.11.1.1 Verifying Port Configuration for Oracle Web Cache with Fusion Middleware Control

To determine ports in use by Oracle Web Cache with Fusion Middleware Control:

  1. Navigate to the Web Cache Home page in Fusion Middleware Control. See Section 2.6.2.

  2. From the Web Cache menu, select Administration > Port Usage.

    The Ports Usage page displays.

    Description of ports.gif follows
    Description of the illustration ports.gif

    In this example:

    • Port 7785 is the HTTPS listening port for Oracle Web Cache.

    • Port 7786 is the HTTP listening port for the admin server process.

    • Port 7787 is the HTTP listening port for statistics monitoring requests.

    • Port 7788 is the HTTP listening port for invalidation requests.

    • Port 7789 is the HTTP listening port for Oracle Web Cache.

2.11.1.2 Verifying Port Configuration for Oracle Web Cache with OPMN

To determine ports in use by Oracle Web Cache with OPMN:

(UNIX) ORACLE_INSTANCE/bin/opmnctl status -l
(Windows) ORACLE_INSTANCE\bin\opmnctl status -l
Processes in Instance: instance1
---------------------------------+--------------------+---------+----------+------------+----------+-----------+------
ias-component                    | process-type       |     pid | status   |        uid |  memused |    uptime | ports
---------------------------------+--------------------+---------+----------+------------+----------+-----------+------
webcache1                        | WebCache-admin     |   11244 | Alive    |  458185369 |    45852 | 180:27:00 | http_admin:7786
webcache1                        | WebCache           |   11243 | Alive    |  458185368 |    72540 | 180:27:00 | http_stat:7787,http_invalidation:7788,https_listen:7789,http_listen:7785
ohs1                             | OHS                |    6077 | Alive    |  458185358 |   349220 | 180:48:14 | https:9999,https:4443,http:7777

In this example:

  • Port 7785 is the HTTP listening port for Oracle Web Cache, represented by http_listen.

  • Port 7786 is the HTTP listening port for the admin server process, represented by WebCache-admin

  • Port 7787 is the HTTP listening port for statistics monitoring requests, represented by http_stat.

  • Port 7788 is the HTTP listening port for invalidation requests, represented by http_invalidation.

  • Port 7789 is the HTTP listening port for Oracle Web Cache, represented by https_listen.

2.11.1.3 Adding an Oracle Web Cache Listening Port

You can add listening ports, if necessary. For example, it may be necessary to add listening port to assign Oracle Web Cache a port that an origin server was previously listening on. If want to configure an HTTPS port, see Section 5.4.2.

To add an HTTP listening port:

  1. Navigate to the Web Cache Home page in Fusion Middleware Control. See Section 2.6.2.

  2. From the Web Cache menu, select Administration > Ports Configuration.

    The Ports Configuration page displays.

  3. Click Create.

    The Create Port page appears.

  4. From the Port Type list, select NORM.

  5. In the IP Address field, specify the computer running Oracle Web Cache:

    • IP version 4 address written in a 32-bit dotted decimal notation or an IP version 6 address written in a 128-bit notation. See Section 2.5.

    • A host name that resolves to an IP address of the computer running Oracle Web Cache. If you do not want to rely on Domain Name System (DNS) to resolve the host name, use a different name resolution mechanism, such as the UNIX etc/hosts file.

    • ANY to represent any IP address

  6. In the Port field, enter the listening port from which Oracle Web Cache receives client requests for the Web site.

    Ensure that this port number is not already in use.

    Port numbers less than 1024 are reserved for use by privileged processes on UNIX. To configure Oracle Web Cache to listen on a port less than 1024, such as on port 80, run the Oracle Web Cache webcached executable with the root privilege. If the webcached executable is not run as root, Oracle Web Cache fails to start.

    See Section 5.9 for instructions on changing the webcached executable to run as root.

  7. If you are changing the listening port from an HTTP port to an HTTPS port, see Section 5.4.2 to configure SSL settings.

  8. Click OK.

2.11.1.4 Modifying Oracle Web Cache Operation Ports

To modify ports from which Oracle Web Cache receives administration, invalidation, or statistics monitoring requests:

  1. Navigate to the Web Cache Home page in Fusion Middleware Control. See Section 2.6.2.

  2. From the Web Cache menu, select Administration > Ports Configuration.

    The Ports Configuration page displays.

  3. Select the port you want to modify and click Edit.

    The Edit Port page appears.

  4. In the Endpoint Attributes section, from the Port Type list, select ADMINISTRATION, INVALIDATION, or STATISTICS.

  5. In the IP Address field, specify the computer running Oracle Web Cache:

    • IP version 4 address written in a 32-bit dotted decimal notation or an IP version 6 address written in a 128-bit notation. See Section 2.5.

    • A host name that resolves to an IP address of the computer running Oracle Web Cache. If you do not want to rely on Domain Name System (DNS) to resolve the host name, use a different name resolution mechanism, such as the UNIX etc/hosts file.

    • ANY to represent any IP address

  6. In the Port field, enter the listening port from which Oracle Web Cache receives client requests for the Web site.

    Ensure that this port number is not already in use.

    Port numbers less than 1024 are reserved for use by privileged processes on UNIX. To configure Oracle Web Cache to listen on a port less than 1024, such as on port 80, run the Oracle Web Cache webcached executable with the root privilege. If the webcached executable is not run as root, Oracle Web Cache fails to start.

    See Section 5.9 for instructions on changing the webcached executable to run as root.

  7. If you are changing a port from an HTTP port to an HTTPS port, see Section 5.5.1 to configure SSL settings.

  8. Click OK.

2.11.2 Task 2: Specify Origin Server Settings

Configure Oracle Web Cache with the application Web servers or proxy servers to which it sends cache misses. Typically, Oracle Web Cache uses application Web servers for internal sites and proxy servers for external sites outside a firewall.

If Oracle HTTP Server was installed, the installation process creates a default origin server based on the host name and listening port of Oracle HTTP Server.

Oracle Web Cache only forwards requests to a configured origin server if the origin server is mapped to a Web site.

When you configure multiple origin servers, ensure the host and port settings are not identical. If you configure origin servers with duplicate host and port settings, both the cache server and admin server processes fail to start.

To configure Oracle Web Cache with origin server information:

  1. Navigate to the Web Cache Home page in Fusion Middleware Control. See Section 2.6.2.

  2. From the Web Cache menu, select Administration and then Origin Servers.

    The Origin Servers page displays.

  3. Click Create.

    The Create Origin Server page displays.

  4. Configure the Host, Port, Capacity, Protocol, and Routing Enabled settings for each origin server to send Oracle Web Cache requests using the descriptions in Table 2-9.

  5. For configurations with multiple origin servers, specify how you want to HTTP distribute requests Oracle Web Cache sent to other origin servers when there is a failure in the Failover section using the descriptions in Table 2-9.

  6. Specify these settings if these origin server is a proxy server in the Proxy Web Server section using the descriptions in Table 2-9.

  7. Click OK to apply changes and return to the Origin Servers page. It is not necessary to click Apply in the Origin Servers page to apply this change.

Table 2-9 Create Origin Server

Element Description

Host

Enter the host name of the origin server.

Port

Enter the listening port from which the origin server receives Oracle Web Cache requests.

Note: Oracle Web Cache must listen on the same port as the application Web server being proxied. When configuring proxy servers, ensure there is a corresponding listening port for every proxied port.

Capacity

Enter the maximum number of concurrent connections that the origin server can accept.

You determine this number by load testing the origin server until it runs out of CPU, responds slowly, or until a back-end database reaches full capacity.

In a cache cluster, Oracle Web Cache ensures that the total number of connections from all cluster members to the origin server does not exceed the capacity. Each cluster member is allowed a percentage of the maximum connections, using the following formula:

connections_from_each_cluster_member = capacity / number_of_cluster_members

Protocol

Select either HTTP to send HTTP requests on the port or HTTPS to send HTTPS requests on the port.

Routing Enabled

Click to permit Oracle Web Cache to route requests to the origin server or leave unchecked to only serve requests from cache.

Oracle recommends not selecting this option if temporary maintenance of an origin server is needed.

Oracle Web Cache tries to route a request matching a particular site to all origin servers mapped to that site. If all of the origin servers have Routing Enabled not selected, Oracle Web Cache serves a network error page to clients. See Section 2.11.6 for further information about configuring error pages.

Failover Threshold

Enter the number of allowed continuous read and write failures with an origin server on established connections.

The default is five request and response failures.

If any connection failure occurs, Oracle Web Cache immediately considers an origin server down.

When the threshold is met, Oracle Web Cache considers the origin server down and performs automatic failover of the origin servers. If an origin server fails at any time after Oracle Web Cache has started to send a request, then Oracle Web Cache increments the failure counter. The failure counter is reset if there is a successful server response. A request is considered failed if:

  • There are any network errors other than connection failure errors.

  • The HTTP response status code is something other than 1xx, 2xx, 3xx, 4xx, 501 Not Implemented, and 505 HTTP Version Not Supported.

After the threshold is met, Oracle Web Cache considers the server down and uses other servers for future requests. Oracle Web Cache starts polling the down server, by sending requests to the URL specified in the Ping URL field. When Oracle Web Cache receives a successful response from the server without any network errors and the HTTP response code is not less than 100, or not equal to 500, 502, 503, 504, Oracle Web Cache considers the server up again and uses it for future requests.

Notes:

  • The threshold does not apply if Oracle Web Cache cannot connect to an origin server. In this case, Oracle Web Cache immediately considers the server down and does not use it for future requests. If there are other origin servers, Oracle Web Cache retries the request to another origin server. If there no servers configured, Oracle Web Cache returns an error.

  • The failover to another origin server does not apply if there is only one origin server left.

Ping URL

Enter the URL that Oracle Web Cache uses to poll an origin server that has reached its failover threshold:

  • For an application Web Server, enter either a relative or a fully qualified URL that includes the domain name, or site name, representing the virtual host of the application Web server.

  • For a proxy server, enter a fully qualified URL that includes the domain name, or site name, representing the virtual host of the origin server behind the proxy server.

The default value is:

/

Rather than using a static URL, Oracle recommends using a URL that checks the health of the application logic on the origin server and returns the appropriate HTTP 200 or 500 status codes.

Ping Frequency (seconds)

Enter the time, in seconds, that Oracle Web Cache uses to poll an origin server that has reached its failover threshold.

The default is 10 seconds.

Proxy Web Server

Click to treat this origin server as a proxy server.

Username

Enter the user name for the proxy server administrator.

Password

Enter the password of the proxy server administrator

Confirm Password

Reenter the password for the proxy server administrator.

2.11.3 Task 3: Specify Site Definitions

For Oracle Web Cache to act as a virtual server for one or more Web sites, configure Oracle Web Cache with information about the named Web sites. For an overview of site configuration, see Section 2.2.

To create site definitions:

  1. Navigate to the Web Cache Home page in Fusion Middleware Control. See Section 2.6.2.

  2. From the Web Cache menu, select Administration and then Sites.

    The Sites page displays.

  3. From the Site Definitions section, click Create.

    The Create Site page displays.

  4. In the Create section, configure the elements using the descriptions in Table 2-10.

  5. In the Aliases section, specify all the possible aliases for the site to ensure requests are directed to the correct site. An alias specifies the host and port in which browsers use to connect to the site.

    1. Click Create to create an alias.

    2. Configure the Host and Port fields using the descriptions in Table 2-10.

  6. Click OK to apply changes and return to the Sites page. It is not necessary to click Apply in the Sites page to apply this change.

  7. Repeat Steps 3 to 6 for each additional site.

  8. In the Sites page, use the Move Up and Move Down icons to order the definitions.

    Oracle Web Cache resolves an incoming request first to a site definition, and then to the first matching site-to-origin server mapping. See Section 2.2 for more information about how Oracle Web Cache uses the order of site definitions and site-to-server mappings to match requests.

  9. Click Apply to apply the move change.

Table 2-10 Create Site Page

Element Description

Host

In the Create Site section, enter the site pattern, such as www.company.com. To enable Oracle Web Cache to match requests to this site, do not add protocol information (http:// or https://) to the host name.

In the Aliases section, enter the alias name for the site, such as company.com. To enable Oracle Web Cache to match requests to this alias, do not add protocol information (http:// or https://) to the host name.

Note: Do not use the wildcard * to represent multiple sites.

Port

Enter the HTTP or HTTPS port number from which Oracle Web Cache is listening for incoming requests.

URL Prefix

To distinguish sites that share the same host name, enter the path prefix of the URLs. Ensure the prefix starts with "/". Do not include the file name or embedded URL parameters in the prefix.

For example, the following URLs share the same site name, but belong to two entirely differently applications potentially hosted on entirely different computers:

http://www.company.com/portal/page?_pageid=33,4232&_dad=portal

http://www.company.com/um/traffic_cop?mailid=inbox

These URLs are from completely different applications hosted on the same or different origin server. While the first URL shows an mail user a front page after login, the second URL displays an inbox. If the site host name is defined as www.company.com, then you specify the prefixes as /portal and /um to distinguish the sites.

Default Site

Click this option to make this site the default site Oracle Web Cache uses to forward requests without host information.

Compression

Click to instruct Oracle Web Cache to serve cacheable and non-cacheable content compressed to browsers. Not selecting this option means you are instructing Oracle Web Cache to not serve compressed content for this site.

See Section 1.2.5 to understand when Oracle Web Cache automatically disables compression.

You can disable compression for requests that do not match any site using Oracle Web Cache Manager. See Section 2.11.3.1.

2.11.3.1 Disabling Compression for All Responses

You can disable Oracle Web Cache from compressing all responses.

  1. For named sites, deselect the Compression option in the Create Site page in Fusion Middleware Control, as described in Section 2.11.3.

  2. For undefined sites for requests that do not match any site, use Oracle Web Cache Manager and perform the following tasks:

    1. From Oracle Web Cache Manager, in the navigator frame, select Origin Servers, Sites, and Load Balancing > Site Definitions. See Section 2.7.2.

      The Site Definitions page displays.

    2. Select the Undefined Sites row, and then click Show/Edit Selected.

      The Show/Edit Undefined Sites Definition dialog displays.

    3. For the Site-Wide Compression element, click No.

    4. Click Submit.

    5. Click Apply Changes.

    6. Restart Oracle Web Cache. See Section 2.13.

2.11.4 Task 4: Map Site Definitions to Origin Servers

After you specify site definitions, you create ordered mappings of sites to origin servers. For an overview of site configuration, see Section 2.2.

If Oracle HTTP Server was installed, the installation process creates a default site-to-server mapping based on the host name and listening port of Oracle HTTP Server.

If you configured multiple origin servers in Section 2.11.2 for load balancing, then create one site-to-server mapping that maps all the applicable origin servers to the site. In that site-to-server mapping, select all the origin servers that apply for the site. If you split the origin servers among multiple site-to-server mappings, load balancing for the site does not occur in the intended manner.

To map sites to origin servers:

  1. Navigate to the Web Cache Home page in Fusion Middleware Control. See Section 2.6.2.

  2. From the Web Cache menu, select Administration and then Sites.

    The Sites page displays.

  3. From the Site-to-Server Mapping section, click Create.

    The Create Site-to-Server Mapping page displays.

  4. Configure the Host Pattern, Port Pattern, and Prefix elements:

    1. In the Host Pattern field, enter the site pattern, such as www.company.com. To enable Oracle Web Cache to match requests to this site, do not add protocol information (http:// or https://) to the host name.

      You can use the wildcard * in the Host Pattern field in the following ways:

      - Map multiple site names to one or more application Web server or proxy servers. For example, *.company.com can be used to match sites site1.company.com and site2.company.com.

      - Route cache misses to sites outside a firewall and accessible by a proxy server. For example, * can be used to map to proxy server proxy-host.

    2. In the Port Pattern field, enter the HTTP or HTTPS port number for the Web site from which Oracle Web Cache is listening for incoming requests.

      You can use the wildcard * in the Port Pattern field to map the same site name with different port numbers to the same origin servers. If the origin servers are proxy servers, ensure they were configured to listen on the same port as the application Web server being proxied, as described in Section 2.11.2.

  5. In the Origin Servers section, select the origin servers.

    If you select multiple origin servers, the servers must be of the same type and use the same protocol on their listening port (HTTP or HTTPS). For example, you cannot have a mix of application Web servers and proxy servers.

  6. Click OK to apply changes and return to the Sites page. It is not necessary to click Apply in the Sites page to apply this change.

  7. Repeat Steps 3 to 6 for each additional mapping.

  8. In the Sites page, use the Move Up and Move Down features to order the mappings.

    Oracle Web Cache resolves an incoming request first to a site definition, and then to the first matching site-to-origin server mapping. See Section 2.2 for more information about how Oracle Web Cache uses the order of site definitions and site-to-server mappings to match requests..

2.11.5 Task 5: Set Resource Limits and Network Thresholds

For more information about resource limits, see Section 2.3.

To specify caching and network thresholds for Oracle Web Cache:

  1. Specify caching thresholds:

    1. Navigate to the Web Cache Home page in Fusion Middleware Control. See Section 2.6.2.

    2. From the Web Cache menu, select Administration and then Resource Limits.

      The Resource Limits page displays.

    3. In the Maximum Cached Object Size field, specify a maximum size of objects to be stored in the cache in kilobytes (KB).

      For more information about the value to enter, see Section 2.3.3

    4. For each cache, in the Maximum Cache Size field, enter the amount of memory the Oracle Web Cache requires in megabytes (MB).

      For more information about the value to enter, see Section 2.3.1.

    5. In the Maximum Incoming Connections field, enter the maximum number of incoming connections to Oracle Web Cache.

      For more information about the value to enter, see Section 2.3.2.

    6. Click Apply.

  2. For all the caches, modify the network timeouts:

    1. From Oracle Web Cache Manager, select Properties > Network Timeouts. See Section 2.7.2.

    2. From the For Cache list, select a specific cache.

    3. Select a timeout type and click Edit Selected. For more information about the timeouts, see Section 2.3.4.

    4. In the Edit dialog for the threshold, modify the value for the Duration field or select Use Default to use the default value.

      For the keep-alive timeout, if you set the value to 0, the connection to the client is not kept open. In addition, Oracle Web Cache sends the following response-header field in the response:

      Connection: Close

      For more information about the value to enter, see Section 2.3.4.

    5. Select option Use for all caches in the cluster to apply the duration to all caches; deselect the option to apply the change to current cache only.

    6. Click Submit.

    7. Click Apply Changes.

      You can always revert to the default values. In the Network Timeouts page, click Use Defaults, and then click Apply Changes to apply changes.

2.11.6 Task 6: Configure Error Pages

For situations in which there is a network communication error, site busy error, or ESI <esi:include> error, applications serve error pages. Rather than burden the origin server with this task, you can configure these pages to be served from Oracle Web Cache.

To configure Oracle Web Cache to serve error pages for a site:

  1. Create error pages and place them in the following directory locations:

    (UNIX) ORACLE_INSTANCE/<instance_name>/config/WebCache/<webcache_name>/files
(Windows) ORACLE_INSTANCE\<instance_name>\config\WebCache\<webcache_name>\files

    The default settings are as follows:

    • For network errors, the default setting is set to network_error.html. This error page is served when there is a network problem while connecting, sending, or receiving a response from an origin server for a cache-miss request.

    • For site busy errors, the default setting is set to busy_error.html. This page is served when origin server capacity is reached.

    • For ESI default fragments, the default setting is set to esi_fragment_error.txt. This page is served when Oracle Web Cache cannot fetch the src specified in an <esi:include> tag and the alt attribute, onerror attribute, or the try |attempt |except block are either not present or fail.

    For a production environment, modify the defaults or create entirely new error pages to be consistent with other error pages for the site.

  2. From Oracle Web Cache Manager, in the navigator frame, select Origin Servers, Sites, and Load Balancing > Error Pages.

    The Error Pages page appears.

  3. Select either Default Pages or a site name in the table, and then click Edit.

    The Edit Error Pages dialog box appears.

  4. In the Network Error Page field, enter the file name of the error page delivered for network communication problems between Oracle Web Cache and the Web site.

    If you are using the default network_error.html page, leave the field as is.

  5. In the Site Busy Page field, enter the file name of the error page delivered when a Web site is saturated with requests.

    If you are using the default busy_error.html page, leave the field as is.

  6. In the ESI Default Fragment field, enter the file name of the page delivered when Oracle Web Cache cannot retrieve an HTML fragment for an <esi:include> tag.

    If you are not using <esi:include> tags for partial page caching or you want to use only ESI language elements for exceptions, do not enter a value.

  7. Click Apply Changes.

    If you selected Default Pages, Oracle Web Cache applies the new settings to all defined sites with the default page setting. However, Oracle Web Cache does not apply the new setting to undefined sites. If you selected a specific site in Step 3, Oracle Web Cache applies the new settings to the specific site.

2.11.7 Task 7: Restart Oracle Web Cache

See Section 2.13 for instructions on restarting Oracle Web Cache.

2.12 Creating Session Definitions

You create session definitions for the following features:

  • Specify how session requests are served by the cache

  • Enable session binding, whereby a user session for a particular site is bound to an origin server to maintain state for a period.

  • Substitute session information in session-encoded URLs

When you enable these features, you must select a session definition.

To create a session definition:

  1. Navigate to the Web Cache Home page in Fusion Middleware Control. See Section 2.6.2.

  2. From the Web Cache menu, select Administration, and then Session Configuration.

    The Session Configuration page displays.

  3. From the Site list, select the specific site for which you want to apply this session definition. To create a global session definition that can be applied to any site, select Global.

    See Section 2.11.3 to specify additional sites.

  4. In the Session Definitions section, click Create.

    A new row in the table appears.

  5. In the Session Name field, enter an easy-to-remember unique name for the session.

  6. Enter the cookie name in the Cookie Name field and the embedded URL parameter in the URL Post Body Parameters field.

    If you enter both a cookie name and an embedded URL parameter, keep in mind that both must be used to support the same session. If they support different sessions, create separate session definitions.

    Note:

    When a cookie expires, the client browser removes the cookie and subsequent requests for the object are directed to the origin server. To avoid pages from being served past the client session expiration time, ensure that the session cookie expires before the application Web server expires the client session.

  7. In the URL Post Body Parameters field, enter the embedded URL parameter or POST body parameter containing the session information.

  8. In the Default Value field, enter the default string for Oracle Web Cache to use for the cookie or embedded URL parameter value. Oracle Web Cache uses the default string for those requests without the cookie or parameter information. For these requests, Oracle Web Cache substitutes the session ID information with the default string. The default string defaults to default.

  9. Click Apply to apply changes

  10. Restart Oracle Web Cache. See Section 2.13.

For more information about Oracle Web Cache properties requiring session definitions, see:

2.13 Starting and Stopping Oracle Web Cache

Most configuration changes are static. When you apply static changes, you must restart Oracle Web Cache to apply changes.

However, Oracle Web Cache recognizes some changes as dynamic. Oracle Web Cache Manager provides dynamic configuration for the following features:

  • Request filtering in both Fusion Middleware Control and Oracle Web Cache Manager

  • Setting buffering and verbosity detail level in the Event Logs page (Logging and Diagnostics > Event Logs) in Oracle Web Cache Manager

  • Setting buffering in the Access Logs page (Logging and Diagnostics > Access Logs) in Oracle Web Cache Manager

  • Enabling and disabling of diagnostics information in the HTML response body of an object in the Diagnostics page (Logging and Diagnostics > Diagnostics) in Oracle Web Cache Manager

  • Setting routing to origin servers in the Origin Servers page (Origin Servers, Sites, and Load Balancing > Origin Servers) in Fusion Middleware Control

Anytime the Oracle Web Cache configuration is statically modified, you must stop and restart Oracle Web Cache processes:

  • The admin server process manages the administrative interface.

  • The cache server process manages the cache.

The cache server binary is managed by the webcached executable, and the admin server binary webcachea. These executable reside in the following directories:

(UNIX) ORACLE_HOME/webache/bin
(Windows) ORACLE_HOME\bin

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

After you configure Oracle Web Cache, restart Oracle Web Cache. To restart Oracle Web Cache, use these tools:

  • Use Fusion Middleware Control or opmnctl command-line tool to restart the cache or admin server processes.

  • Use Oracle Web Cache Manager to restart the cache server process.

You must restart both the cache server and admin server processes if you modified any of these configuration settings:

2.13.1 Starting and Stopping Using opmnctl

To start, stop, or restart the Oracle Web Cache processes with opmnctl:

  1. Determine the status of Oracle Web Cache. From the command line, enter:

    (UNIX) ORACLE_INSTANCE/bin/opmnctl status 
(Windows) ORACLE_INSTANCE\bin\opmnctl status

    OPMN generates a list of the running processes. The following message indicates that the Oracle Web Cache admin server (WebCache-admin) and the cache server (WebCache) are already running:

    opmnctl status -l
Processes in Instance: instance1
---------------------------------+--------------------+---------+----------+------------+----------+-----------+------
ias-component                    | process-type       |     pid | status   |        uid |  memused |    uptime | ports
---------------------------------+--------------------+---------+----------+------------+----------+-----------+------
webcache1                        | WebCache-admin     |   11244 | Alive    |  458185369 |    45852 | 180:27:00 | http_admin:7786
webcache1                        | WebCache           |   11243 | Alive    |  458185368 |    72540 | 180:27:00 | http_stat:7787,http_invalidation:7788,https_listen:7789,http_listen:7785
ohs1                             | OHS                |    6077 | Alive    |  458185358 |   349220 | 180:48:14 | https:9999,https:4443,http:7777

  2. To start, stop, or restart both the admin server (WebCache-admin) and the cache server (WebCache) processes, from the command line, enter:

    opmnctl startproc|stopproc|restartproc ias-component=component_name

    To individually start, stop, or restart the admin server (WebCache-admin) and the cache server (WebCache) processes, from the command line, enter:

    opmnctl startproc|stopproc|restartproc ias-component=component_name process-type=WebCache-admin

opmnctl startproc|stopproc|restartproc ias-component=component_name process-type=WebCache

    For more information about opmnctl for Oracle Web Cache, see the following:

2.13.2 Starting and Stopping Using the Fusion Middleware Control

To start, stop, or restart Oracle Web Cache from Fusion Middleware Control:

  1. Start Fusion Middleware Control. See Section 2.6.1.

  2. From the navigation pane, expand the farm and then the Web Tier installation type.

  3. Select the Oracle Web Cache component, such as webcache1.

  4. View the target name to determine the status of the cache:

    Description of home_status.gif follows
    Description of the illustration home_status.gif

    The arrow reflects the up or down status of the cache server process, not the admin server process.

    A green up arrow means the following:

    • The cache server is running, but the admin server process is not running.

    • Both the cache server and admin server process are running.

    A red down arrow means the following:

    • The cache server is not running, but the admin server process is running.

    • Both the cache server and admin server process are not running.

    If the admin server process is down, the context pane for the configuration pages displays an error, indicating that configuration is unavailable because the admin server process is down.

  5. From the Web Cache menu, choose Control, then Start Up, Shut Down, or Restart.

    These commands start, stop, or restart both processes, if they have the same up or down status. If the two processes have different up and down statuses, then Fusion Middleware Control starts, stops, or restarts the appropriate process. For example, if the cache server process is running, but the admin server process is not and you choose Start Up, then only the admin server is started.

2.13.3 Starting and Stopping Using Oracle Web Cache Manager

Oracle Web Cache Manager enables you to start and stop the cache server process. You must use Fusion Middleware Control or opmnctl to start, stop, or restart the admin server process.

To start, stop, or restart the cache server process with Oracle Web Cache Manager:

  1. Start Oracle Web Cache Manager. See Section 2.7.1.

  2. In the navigator frame, select Operations > Cache Operations. See Section 2.7.2.

    The Cache Operations page appears in the right pane.

  3. Select the cache, and then click Start, Stop, or Restart.

To perform the operation on one cache in a cache cluster:

Select one cache, choose Selected Cache from the Operate On field, and then click Start, Stop, or Restart.

To perform the operation on all caches in a cache cluster:

Choose All Caches from the Operate On field, and then click Start, Stop, or Restart.