8 Setup and Configuration

Task 1: Start OracleAS Web Cache

To start OracleAS Web Cache to begin the initial configuration:

1. If not currently logged on to the OracleAS Web Cache computer, log in with the user ID of the user that performed the installation.

2. Start both the admin and cache server processes:

   • The admin server process manages the administrative interface.

   • The cache server process manages the cache.

   Use opmnctl or webcachectl (for standalone installations) to start the processes:

   opmnctl startproc ias-component=WebCache
   
   

   webcachectl start
   

Task 2: Modify Security Settings

When OracleAS Web Cache is installed, it is set up with passwords for administration and invalidation requests. In addition, the computer on which you installed OracleAS Web Cache is the default trusted host.

To change the security settings in Application Server Control Console, navigate to Web Cache Home page > Administration tab > Properties > Web Cache > Security.

To change the security settings in OracleAS Web Cache Manager:

1. Change the password for the OracleAS Web Cache usernames, administrator and invalidator.

   You can perform configuration and operational tasks with either the Application Server Control Console administrator, ias_admin, or the OracleAS Web Cache administrator, administrator, accounts. Before you begin configuration, change the default administrator password to a secure password.

   You can send invalidation requests with the invalidator username.

   By default, the passwords for these users is the password you supplied during installation for the administrator username. In a cache cluster, the password for all cluster members must be the same.

   1. In the navigator frame, select Properties > Security.

      The Security page appears.

   2. Under Administration User, click Change Administration Password or Change Invalidation Password under the Invalidation User.

   3. When prompted, enter the old password in the Old Password field and a new password, in the New Password and Confirm New Password fields.

   4. Click Submit.

      
      

      See Also: "Classes of Users and Their Privileges" for further information about the administrator role

      
      

   The passwords for the administrator and invalidator users have these restrictions:

   • Passwords must be between 5 and 30 characters.

   • At least one of the characters must be a number.

   • Passwords can contain only alphanumeric and underscore (_) characters.

   • Passwords must begin with an alphabetic character. Passwords cannot begin with a number, the underscore (_), the dollar sign ($), or the number sign (#).

   • Passwords cannot be Oracle reserved words. The Oracle Database SQL Reference lists the reserved words. You can find this guide on Oracle Technology Network: http://www.oracle.com/technology/documentation/index.html

     
     

     See Also: "Classes of Users and Their Privileges" for further information about the different administrative roles Section 7.3.3, "Portal Web Cache Settings" in Oracle Application Server Portal Configuration Guide for information about additional settings required for OracleAS Portal configurations

     
     

2. Optionally, change the trusted subnet or trusted host from which administration, invalidation, and statistics monitoring requests can take place.

   By default, the computer on which you installed OracleAS Web Cache is the trusted host.

   1. In the Security page, click Change Trusted Subnets under the Current Trusted Subnets.

      The Change Trusted Subnets dialog box appears.

   2. Select one of the following options:

      All subnets: Allows requests from all computers in all the subnets in the network.

      This machine only: Allows requests from only this computer.

      Enter list of IP addresses: Allows requests from all IP addresses you enter in a comma-delimited list. You can enter IP addresses in one of the following formats:

      • Complete IP address in dot notation, including the network number, subnet address, and unique host number

        Example: 10.1.2.3

      • Network/netmask pair for subnet restriction through masking

        Example: 10.1.0.0/255.255.0.0 allows all the hosts in the 10.1 subnet access.

      • Network/nnn Classless Inter-Domain Routing (CIDR) specification to require nnn bits from high end to match

        Example: 10.1.0.0/16 allows all the hosts in the 10.1 subnet access. This example is similar to the network/netmask example, except the netmask consists of nnn high-order 1 bits.

        
        

        Note: Sometimes requests come through a proxy server. If the proxy server is not covered by the trusted subnet settings, the requests will fail.

        
        

   3. Click Submit.

3. Optionally, change the user ID and group ID for the OracleAS Web Cache processes on UNIX.

   By default, the user that performed the installation is the owner of OracleAS Web Cache processes. This user can execute opmnctl commands. Users that belong to the same group ID of the user that performed installation can also execute opmnctl commands.

   If the current opmnctl user does not match the configured user in the Process Identity page, the OracleAS Web Cache webcached executable must run as root. If the webcached executable is not able to run as root, error events are reported to the event log file, and OracleAS Web Cache fails to start.

   
   

   See Also: "Running webcached with Root Privilege" for instructions on changing the webcached executable to run as root

   
   

   To change the user ID and group ID for the OracleAS Web Cache processes on UNIX:

   1. In the navigator frame, select Properties > Process Identity.

      The Process Identity page appears.

   2. Select the cache for which you want to modify settings, and then click Change IDs.

      The Change Process Identity dialog box appears.

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

   4. Click Submit.

   5. Use the webcache_setuser.sh script as follows to change file and directory ownership:

      webcache_setuser.sh setidentity <user_ID> 
      
      

      where <user_ID> is the user you specified in the User ID field of the Process Identity page.

      The setidentity command changes the ownership of the following files and directories to the new user ID:

      • $ORACLE_HOME/webcache

      • $ORACLE_HOME/webcache/internal.xml

      • $ORACLE_HOME/webcache/webcache.xml

      • $ORACLE_HOME/webcache/webcache.xml.bak

      • $ORACLE_HOME/webcache/.webcache_tmp.xml.tmp

      • $ORACLE_HOME/webcache/logs/event_log_files

      • $ORACLE_HOME/webcache/logs/access_log_files

   
   

   See Also: "Script for Setting File Permissions on UNIX" for further information about the webcache_setuser.sh script

   
   

If you change the administrator password or the trusted subnets in the Security page or any of the settings in the Process Identity page, then, after applying changes, restart both the cache server process and admin server process with the Oracle Process Manager and Notification (OPMN) Server utility command opmnctl restartproc ias-component=WebCache or the webcachectl utility command webcachectl restart (for standalone installations). You cannot use the Restart option in the Cache Operations page to restart the admin server process. Until the admin server process is restarted, you cannot submit invalidation requests from the Basic Content Invalidation or Advanced Content Invalidation pages.

Task 3: Configure Auto-Restart Settings

OracleAS Web Cache provides an auto-restart mechanism that checks that the cache server process is running and automatically restarts the cache server process if it is not running.

If auto-restart is enabled, the auto-restart mechanism restarts the cache server if it stops. By default, auto-restart is enabled.

To change the auto-restart settings in Application Server Control Console, navigate to Web Cache Home page > Administration tab > Properties > Web Cache > Auto-Restart.

To specify the settings for auto-restart in OracleAS Web Cache Manager:

1. In the navigator frame, select Properties > Auto-Restart.

   The Auto-Restart page appears.

2. To change the default settings, click Edit.

   The Edit Auto-Restart dialog box is displayed.

3. If auto-restart is not enabled, in the Enabled field, select Yes.

4. You can specify that the auto-restart mechanism polls (pings) the OracleAS Web Cache cache server at specified intervals. It does this by sending requests to a specified URL. If it cannot connect to the cache server or if the cache server does not respond within a specified time, the auto-restart mechanism restarts the cache server process.

   Note that the auto-restart mechanism will restart the cache server if it has failed, whether or not you enable pinging. However, if you enable pinging, the auto-restart mechanism will attempt to restart the cache if it receives network errors in response to its ping attempts.

   If you do not want the auto-start mechanism to actively ping the cache server, disable pinging by selecting No in the Pinging Enabled field.

   To enable pinging:

   1. In the Pinging Enabled field, select Yes.

   2. In the Failover Threshold field, enter the number of consecutive failed requests before the auto-restart mechanism considers the cache server to have failed. Only network errors, including timeout errors, are counted as failed requests.

      The default is three failures.

      For each failed request, OracleAS Web Cache increments the failure counter. When a request is successfully processed by the cache server, OracleAS Web Cache resets the failure counter.

      When the failover threshold is met, the auto-restart mechanism starts the cache server.

      
      

      Note: The threshold applies only to network errors and timeouts. If the cache server process is not running, the auto-restart mechanism immediately restarts the cache server.

      
      

   3. In the Ping URL field, enter the URL that the auto-restart mechanism will use to poll the cache server.

      You must use a URL that is cacheable and is guaranteed to be stored in the cache. The default is /_oracle_http_server_webcache_static_.html, which is stored in the cache. If your environment uses a hardware load balancer with pinging capability, then configure the load balancer with this ping URL to ping each OracleAS Web Cache server on a periodic basis.

   4. In the Ping Interval field, enter the time, in seconds, between attempts by the auto-restart mechanism to poll the cache server.

      The default value is 15 seconds.

   5. In the Ping Timeout field, enter the time, in seconds, that the auto-restart mechanism will wait for a response from the cache server.

      The default value is 30 seconds.

5. Click Submit.

Task 4: Configure Network Time Outs

After OracleAS 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 OracleAS Web Cache. If the network between the client and OracleAS Web Cache is slow, consider increasing the timeout. Likewise, there is a 3600 second network timeout between OracleAS Web Cache and the origin server. If the origin server is unable to generate a response within that time, OracleAS Web Cache drops the connection and sends a network error page to the client. If applications require a shorter timeout, adjust the timeout.

To modify the default network timeouts from the Application Server Control Console, navigate to Web Cache Home page > Administration tab > Properties > Web Cache > Resource Limits and Timeouts.

To modify the default network timeouts from OracleAS Web Cache Manager:

1. In the navigator frame, select Properties > Network Timeouts.

   The Network Timeouts page appears.

2. In the Network Timeouts page, select the cache, and then click Edit.

   The Edit Network Timeouts dialog box appears.

3. In the Keep-Alive Timeout field, enter the time, in seconds, for OracleAS Web Cache to keep a connection open to the client after it has returned a response.

   If the timeout is set to 0, the connection to the client is not kept open. In addition, OracleAS Web Cache sends the following response-header field in the response:

   Connection: Close
   
   

4. In the Origin Server Timeout field, enter the time, in seconds, for the origin server to generate a response to OracleAS Web Cache. If the origin server is unable to generate a response within that time, OracleAS Web Cache drops the connection and sends a network error page to the client.

5. Click Submit.

   
   

   See Also: "Task 6: Modify ssl.conf for Keep-Alive Connections" for further information about configuring the Oracle HTTP Server to maintain keep-alive connections from OracleAS Web Cache for Internet Explorer browsers "Browser Displaying a Page Not Displayed Error" for further information about the keep-alive limitations with Internet Explorer browsers

   
   

Task 5: Set Resource Limits

To set resource limits for OracleAS Web Cache, configure the following attributes:

• Cache Memory

• Connection Limit

• Maximum Size of Single Cached Object

Max_File_Desc = Curr_Max_Conn + Total_WS_Capacity + Outgoing_Cluster_Conn + 100

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters

Task 6: Configure OracleAS Web Cache with Listening Ports for Client Requests

By default, OracleAS Web Cache listens with the HTTP protocol on port 7777 on UNIX and port 80 on Windows. If this port is in use, the installation procedure attempts to assign another port number from a range of 7777 to 7877.

You can add ports, if necessary. For example, it may be necessary to add an additional listening port if you want to assign OracleAS Web Cache a port that an origin server was previously listening on.

You can add a port and specify the HTTPS protocol to accept HTTPS client requests on that port.

This section contains the following topics:

• Adding a Listening Port

• Changing Site Configuration

• Configuring Other Oracle Application Server Components with the Listening Port

Task 7: Provide Directives to Oracle HTTP Server

At installation time, Oracle HTTP Server sets the httpd.conf file with the following directives that impact OracleAS Web Cache:

• Port=web_cache_port specifies the OracleAS Web Cache listening ports, enabling dynamically created URLs to be redirected to OracleAS Web Cache.

• Listen=Oracle_HTTP_Server_port specifies the HTTP port obtained by Oracle HTTP Server.

• ServerName specifies the host name of Oracle HTTP Server.

• UseCanonicalName On instructs Oracle HTTP Server to use the host names and port values set in the ServerName and Port directives when redirecting a URL.

For example:

##
## httpd.conf -- Apache HTTP server configuration file
##
...
Port 7777
Listen 7778
...
ServerName http_server_name
...
UseCanonicalName On
....

If you decide to disable OracleAS Web Cache, then the Oracle HTTP Server administrator must modify the value of the Port directive to the same value set for the Listen directive. For example:

##
## httpd.conf -- Apache HTTP server configuration file
##
...
Port 7778
Listen 7778
...
ServerName http_server_name
...
UseCanonicalName On
....

If OracleAS Web Cache is deployed on a separate computer from the Oracle HTTP Server, then the Oracle HTTP Server administrator must create a <VirtualHost> container directive in httpd.conf for each site hosted by OracleAS Web Cache. This configuration enables Oracle HTTP Server to redirect URLs to OracleAS Web Cache. The following example shows httpd.conf modified to direct requests for www.1st.company.com and www.2nd.company.com to OracleAS Web Cache, which is listening on port 7777:

##
## httpd.conf -- Apache HTTP server configuration file
##
...
Port 7777
Listen 7778
...
ServerName  http_server_name
...
UseCanonicalName On
...
<VirtualHost *:*>
    ServerName www.1stcompany.com
    Port 80
    ...
</VirtualHost>
<VirtualHost *:*>
    ServerName www.2ndcompany.com
    Port 80
    ...
</VirtualHost>
...

The httpd.conf file resides in $ORACLE_HOME/Apache/Apache/conf/httpd.conf on UNIX or ORACLE_HOME\Apache\Apache\conf\httpd.conf on Windows.

Task 8: Configure OracleAS Web Cache with Operations Ports

In addition to receiving HTTP and HTTPS client requests, OracleAS 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 

By default, OracleAS Web Cache listens with the HTTP protocol to receive these requests. The installation procedure assigns port numbers ranging from 9400 to 9499. Default HTTP port numbers are as follows:

• 9400 for administration requests

• 9401 for invalidation requests

• 9402 for statistics monitoring requests

  
  

  Note: Requests to the administration port must originate from a trusted host or a host on a trusted subnet. Trusted hosts and subnets are defined in the Security page (Properties > Security). See "Task 2: Modify Security Settings" for further information. By default, the administration, invalidation, or statistics monitoring ports are configured for HTTP basic authentication. The passwords for the administrator and the invalidator accounts can be decoded when they are sniffed out of the HTTP traffic. To avoid breach of security information for unprotected and insecure networks, modify the protocol to HTTPS to ensure that the passwords for these requests are secure. Perform the procedure that follows.

  
  

This section contains the following topics:

• Modifying Operations Ports

• Configuring Other Oracle Application Server Components with Operations Ports

• Starting the admin Server Process After an Administration Port Change

• Starting the cache Server Process After an Invalidation or Statistics Port Change

opmnctl restartproc ias-component=WebCache process-type=WebCacheAdmin

webcachectl restartadm 

Internal error: can't connect to OracleAS Web Cache Invalidation Listening Port 

Failure obtaining statistics from Web Cache cache server:  error in connect.
Please check that the cache server is up and running. 

Task 9: Configure Origin Server, Load Balancing, and Failover Settings

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

By default, the listening port and host name of the Oracle HTTP Server are configured. When OracleAS Web Cache is installed, Oracle HTTP Server has a default listening HTTP port of 7778 during the first installation sequence.

OracleAS Web Cache only forwards requests to a configured origin server if the server is mapped to a Web site. If you are configuring load balancing for a site, then create one site-to-server mapping that maps all the applicable origin servers to the site.

To configure OracleAS Web Cache with origin server information from Application Server Control Console, navigate to Web Cache Home page > Administration tab > Properties > Application > Origin Servers.

To configure OracleAS Web Cache with origin server information from OracleAS Web Cache Manager:

1. In the navigator frame, select Origin Servers, Sites, and Load Balancing > Origin Servers.

   The Origin Servers page appears.

2. Click Add in the Application Web Servers or Proxy Servers section.

   The Add Application Web Server or Proxy Server dialog box appears.

3. In the Hostname field, enter the host name of the origin server.

4. In the Port field, enter the listening port from which the origin server will receive OracleAS Web Cache requests.

   
   

   Note: OracleAS 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 port that will need to be proxied.

   
   

5. In the Routing field, select ENABLED to permit OracleAS Web Cache to route requests to the origin server or DISABLED to only serve requests from cache.

   Oracle recommends selecting DISABLED if temporary maintenance of an origin server is needed.

   OracleAS 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 a routing of DISABLED, OracleAS Web Cache serves a network error page to clients.

   
   

   See Also: "Configure Error Pages"

   
   

6. In the Capacity field, 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 backend database reaches full capacity.

   In a cache cluster, OracleAS 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
   
   

7. In the Failover Threshold field, enter the number of allowed continuous read/write failures with an origin server on established connections.

   The default is five request/response failures.

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

   When the threshold is met, OracleAS Web Cache considers the origin server down and performs automatic failover of the origin servers. If an origin server fails at any time after OracleAS Web Cache has started to send a request, then OracleAS Web Cache increments the failure counter. The failure counter is reset in the event of 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 less than 100, or is one of the following messages: 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, or 504 Gateway Timeout.

   After the threshold is met, OracleAS Web Cache considers the server down and uses other servers for future requests. OracleAS Web Cache starts polling the down server, by sending requests to the URL specified in the Ping URL field. When OracleAS 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, OracleAS Web Cache considers the server up again and uses it for future requests.

   
   

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

   
   

8. In the Ping URL field, enter the URL that OracleAS Web Cache will use 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.

   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. The default is "/".

9. In the Ping Interval (seconds) field, enter the time, in seconds, that OracleAS Web Cache will poll an origin server that has reached its failover threshold.

   The default is 10 seconds.

10. From the Protocol list, select either HTTP to send HTTP requests on the port or HTTPS to send HTTPS requests on the port.

    
    

    See Also: "Secure Sockets Layer (SSL)"

    
    

11. Click Submit.

12. If you selected HTTPS as the listening protocol, specify the location of the wallet for OracleAS Web Cache communication to the origin server (Origin Servers, Sites, and Load Balancing > Origin Server Wallet).

    
    

    See Also: "Task 4: Configure HTTPS Port and Wallet Location for the Origin Server" for information about configuring the wallet

    
    

Task 10: Configure Web Site Settings

For OracleAS Web Cache to act as a virtual server for one or more Web sites, configure OracleAS Web Cache with information about the Web site. To configure settings for a Web site, perform the following tasks:

• Creating Site Definitions

• Configure Error Pages

• Bind a Session to an Origin Server

Creating Site Definitions

The installation process creates a default site definition that uses the host name and listening port of the computer on which Oracle HTTP Server was installed. OracleAS Web Cache forwards requests without host information to this site.

You need to 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. OracleAS 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, OracleAS Web Cache caches the same content from either company.com:80 or www.company.com:80. If a request includes a site alias that is not configured, OracleAS Web Cache sends the request to the default site.

The following sections show examples of site definitions and explain how to configure new site definitions:

• Default Site Example

• Virtual Host Site Examples

• ESI Provider Site Example

• Creating New Site Definitions

Default Site Example

For those requests that do not include a Host request-header field, OracleAS Web Cache sends the request to the default site. The default site, established during installation, uses the host name and listening port of the computer on which Oracle HTTP Server was installed. Figure 8-1 shows an example of a default site definition from the Sites page of Application Server Control Console (Web Cache Home page > Administration tab > Properties > Application > Sites).

The rules for the default site are as follows:

• The site definition in the Named Sites Definitions section maps HTTP requests to the origin server host-server:7778. If you select to edit this definition, you can view the ESI content policy from the Advanced tab. The ESI content policy is set to Unrestricted, which instructs OracleAS Web Cache to serve site content, as well as assemble ESI include fragments.

• The first mapping *.80 in the Server Mapping for Unnamed Site uses a * wildcard host name to map all other virtual site names to the origin server. The ESI content policy is set to Exclude Fragments, which restricts OracleAS Web Cache from fetching ESI content from any sites other than the sites specified in the first rule.

• The second mapping *.* in the Server Mapping for Unnamed Site uses a * wildcard host name to map all other virtual site names to the origin server and a * wildcard port number to map the site name to multiple port numbers. The ESI content policy is set to Exclude Fragments, which restricts OracleAS Web Cache from fetching ESI content from any sites other than the sites specified in the first two rules.

Figure 8-1 Default Site Definitions

Description of "Figure 8-1 Default Site Definitions"

Note: If you modify the name of the default site, you must also modify the ServerName directive in the httpd.conf file. See "Task 7: Provide Directives to Oracle HTTP Server".

Virtual Host Site Examples

Figure 8-2 shows how you would configure a virtual host site named www.company.com:80 without ESI content from the Sites page of Application Server Control Console (Web Cache Home page > Administration tab > Properties > Application > Sites).

The site definition in the Named Sites Definitions section maps HTTP requests to site www.company.com:80 and and site alias company.com:80 to origin server host-server:7778. The ESI content policy is set to Exclude Fragments, which restricts OracleAS Web Cache from fetching ESI content from host-server:7778 for this site.

Figure 8-2 Example: Site Settings for a Virtual Host Site

Description of "Figure 8-2 Example: Site Settings for a Virtual Host Site"

Figure 8-3 shows how you would configure a virtual host site named www.1st.company.com:80 and www.2nd.company.com with ESI content from the Sites page of Application Server Control Console (Web Cache Home page > Administration tab > Properties > Application > Sites).

The rules are as follows:

• The site definitions in the Named Sites Definitions section map HTTP requests to sites www.1st.company.com:80 and www.2nd.company.com:80 and respective aliases 1st.company.com and 2nd.company.com to origin server host-server:7778. The ESI content policy is set to Unrestricted, which enables OracleAS Web Cache to serve site content, as well as assemble ESI include fragments.

• The mapping www.*.company.com:80 in the Server Mapping for Unnamed Site uses a * wildcard host name to map sites matching www.*.company.com to origin server host-server:7778. The ESI content policy is set to Unrestricted.

Figure 8-3 Example: Site Settings for Multiple Virtual Host Sites

Description of "Figure 8-3 Example: Site Settings for Multiple Virtual Host Sites"

ESI Provider Site Example

Figure 8-4 shows how you would configure ESI provider sites named www.providersite1.com:80 and www.providersite2.com from the Sites page of Application Server Control Console (Web Cache Home page > Administration tab > Properties > Application > Sites).

The site definitions in the Named Sites Definitions section specify how to map HTTP requests to sites www.providersite1.com:80 and www.providersite2.com:80 and respective aliases providersite1.com and providersite2.com. Requests to www.providersite1.com map to proxy-host:80. There is no origin server specified for www.providersite2.com, because the proxy server is not known. Instead, DNS will be used to resolve the site name to the appropriate server. The ESI content policy is set to Fragments Only, which restricts OracleAS Web Cache from using this mapping for any content that is not ESI.

Figure 8-4 Example: Site Settings for Multiple ESI Provider Sites

Description of "Figure 8-4 Example: Site Settings for Multiple ESI Provider Sites"

Creating New Site Definitions

If the default site definition is not adequate for your configuration, create additional site definitions.

To create new site definitions from Application Server Control Console, navigate to Web Cache Home page > Administration tab > Properties > Application > Sites.

See Also: "Configuring Site Properties for a Named Site" or "Configuring Site Properties for an Unnamed Site" in Enterprise Manager Online Help for instructions

Using OracleAS Web Cache Manager, you can either discover site and alias information from Oracle HTTP Server, or you can manually create definitions. Oracle recommends using the site discovery feature to initially create the necessary definitions. After discovery is complete, you can manually create additional site definitions. Application Server Control Console does not support site discovery.

See Also: Help for the Site Definitions page in OracleAS Web Cache Manager Online Help for instructions on using the site discovery feature

To create new site definitions from OracleAS Web Cache Manager:

1. In the navigator frame, select Origin Servers, Sites, and Load Balancing > Site Definitions.

   The Site Definitions page appears.

   
   

   Note: It may not be possible to specify a site definition for an external ESI provider site. If an ESI request is made to a provider that does not match any application Web server mapping, then OracleAS Web Cache uses Domain Name System (DNS) to resolve the site name. Note that this will not work if there is a firewall between the cache and the ESI provider. In that case, you must provide a proxy server mapping that directs the request to the appropriate proxy. Undefined ESI provider sites disable the following OracleAS Web Cache features: — Performance assurance heuristics — Origin server features, such as surge protection, load balancing, failover, and session binding It is not possible to configure only ESI provider sites. In a configuration with ESI provider sites, at least one virtual host site definition must exist for ESI template pages.

   
   

2. Specify the site information:

   1. In the Site Definitions page, click Add Site.

      The Add Site dialog box appears.

   2. In the Host Name field, enter the site host name, for example, www.company.com. To enable OracleAS Web Cache to match requests to this site, do not add protocol information (http:// or https://) to the host name.

      
      

      Note: Do not use the wildcard * in the Host Name field to represent multiple sites.

      
      

   3. Optionally, in the URL Path Prefix field, enter the path prefix of the URLs to distinguish this site from another site that shares the same host name. Ensure the prefix starts with "/" to distinguish from another site that shares the same host name. Do not include the file name or embedded URL parameters in the prefix.

      The prefix is excluded in matching requests to the site.

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

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

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

      While the first URL shows an email 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. Requests are matched for www.company.com, not www.company.com/portal and www.company.com/um.

   4. In the Port Number field, enter the port number from which the Web site is listening for incoming HTTP requests.

      The port number should be the port used in client requests.

      In a configuration in which the OracleAS Web Cache listen port is the same as the logical site port, changing the OracleAS Web Cache listen port requires you to also change the logical site port in both the Site Definitions and Site-to-Server Mapping pages.

   5. In the HTTPS Only Prefix field, enter the URL prefix for which only HTTPS requests will be served. If you must restrict all traffic to HTTPS, enter "/ " for the entire site.

   6. In the URL Parameter to Ignore field, specify site-specific embedded URL or POST body parameters to ignore.

      By configuring OracleAS Web Cache to ignore the value of embedded URL or POST body parameters, you enable OracleAS Web Cache to serve one cached object to multiple sessions requesting the same page. OracleAS Web Cache caches the response to the first request and serves subsequent requests for the page from its cache.

      If you prefer instead to set a global parameter to apply to all sites, click Global URL Parameters to Ignore from the main Site Definitions page.

      
      

      See Also: Excluding the Value of Embedded URL or POST Body Parameters for an overview and an example scenario Configuring OracleAS Web Cache to Exclude the Value of Embedded URL or POST Body Parameters for instructions on setting global parameters

      
      

   7. In the Client-Side Certificate field, select Required or Not Required to specify that OracleAS Web Cache require or not require client-side certificates from client browsers.

      A client-side certificate is a method for verifying the identity of the client. It binds information about the client user to the user's public key and must be digitally signed by a trusted CA.

   8. In the Default Site field, select Yes to specify the site as the default site, or select No to specify this site as a nondefault site.

      If you select Yes for a site, another site that previously had the Yes setting will change to No.

      If the default site includes a URL path prefix, the prefix is excluded in matching requests to the site. For example, if you specify a default site of www.company.com and a URL path prefix of /portal, requests are matched for www.company.com, not www.company.com/portal.

      
      

      See Also: "Default Site Example" for information about how the default site is used

      
      

   9. In the Create Alias from Site Name with/without www field, select either Yes or No.

      • Select Yes to use the site name as a site alias.

        For example, if the site domain name is company.com, a site alias of www.company.com will be used. If the site domain name is www.company.com, a site alias of company.com will be used.

      • Select No if you do not want to use the site name as a site alias.

3. If the site uses additional aliases, map the site to those aliases.

   
   

   Important: To ensure requests are directed to the correct site, specify all possible variations of the site name. If a request includes a site alias that is not configured, OracleAS Web Cache sends the request to the default site.

   
   

   1. In the Site Definitions page, select a site, and then click Add Alias.

      The Add Alias for Site dialog box appears.

   2. In the Host Name field, enter the site alias name, such as company.com.

      
      

      Note: Do not use the wildcard * in the Host Name field to represent multiple aliases.

      
      

   3. In the Port Number field, enter the HTTP or HTTPS port number from which the alias is listening for incoming HTTP requests.

      The port number should be the port used in client requests.

4. Click Submit.

To map sites to origin servers from Application Server Control Console, navigate to Web Cache Home page > Administration tab > Properties > Application > Sites.

See Also: "Configuring Site Properties for a Named Site" in Enterprise Manager Online Help for instructions

To map sites to origin servers from OracleAS Web Cache Manager, take the following steps:

1. In the navigator frame, select Origin Servers, Sites, and Load Balancing > Site-to-Server Mapping.

   The Site-to-Server Mapping page appears.

2. Click Create if no mappings exist. If mappings already exist, select a mapping, and then click Insert Above or Insert Below.

   The Create Site-to-Server Mapping or Edit/Add Site-to-Server Mapping dialog box appears.

3. In the Edit Site Name section, select one of the following options:

   • Enter Site Name to enter the site name, such as www.company.com or *.company.com, as well as the HTTP or HTTPS port number from which the site is listening for incoming requests.

   • Select from Site definitions to select a site definition created in the Site Definitions page.

     
     

     Note: You can use the wildcard * in the Host Name 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 undefined ESI provider sites outside a firewall and accessible by a proxy server. For example, * can be used to map to proxy server proxy-host. You can use the wildcard * in the Port Number 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 "Task 9: Configure Origin Server, Load Balancing, and Failover Settings". This option does not enable you to create a site definition. You must create a site definition in the Site Definitions page.

     
     

4. In the Select either application Web servers or proxy servers to which this Site is mapped, select one of the following options:

   • Select Application Web Servers to select application Web servers specified in the Origin Servers page

   • Select Proxy Servers to select proxy servers specified in the Origin Servers page

     
     

     Note: If you configured multiple origin servers in "Task 9: Configure Origin Server, Load Balancing, and Failover Settings" 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 will not occur in the intended manner.

     
     

5. In the Exclude section, select one of the following options to restrict OracleAS Web Cache access to the origin servers for the sites specified in Edit Site Name.

   • Exclude Fragments restricts OracleAS Web Cache from using this mapping for ESI fragments. Select this option if the site is a virtual host site that does not provide ESI content.

   • Fragments Only restricts OracleAS Web Cache from using this mapping for any content that is not an ESI fragment. Select this option if the site is an ESI provider site.

   • Unrestricted does not enforce any OracleAS Web Cache restrictions. Select this option if the site is a virtual host site that supports ESI.

   For example, one mapping entry that uses Exclude Fragments does not mean that OracleAS Web Cache is not allowed to assemble ESI content from other origin servers.

6. Click Submit.

7. After you create the mappings, order them. For each request, the first matching mapping is used.

   In the Site-to-Server Mapping page, select a mapping, and then click Move Up or Move Down to order the mappings. Note the following:

   • 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 will never be reached. Requests for these URLs will 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
     

   
   

   Note: If the protocol used in the src attribute of an <esi:include> tag attribute does not match the protocol specified in the Site-to-Server Mapping page, then OracleAS Web Cache uses the protocol configured for the origin server in the Site-to-Server Mapping page. OracleAS Web Cache also reports the following warning message to the event log: ESI include fragment protocol does not match origin server protocol: Origin Server Protocol=protocol URL=URL For example, if the template page is configured with <esi:include src="https://www.company.com/gifs/frag1.gif"/> and the Site-to-Server Mapping specifies HTTP for the origin server, then http://www.company.com/gifs/frag1.gif is used and the following message appears in the event log: [25/Jul/2005:19:30:48 +0000] [warning 11250] [ecid: -] ESI include fragment protocol does not match origin server protocol: Origin Server Protocol=http URL=https://www.company.com/gifs/frag1.gif

   
   

Task 11: Specify Caching Rules

Specify the URLs containing the objects you want OracleAS Web Cache to cache.

Task 12: Restart OracleAS Web Cache

After you configure OracleAS Web Cache, restart OracleAS Web Cache. To restart OracleAS Web Cache, use one of the following tools:

• For an Oracle Application Server installation, use either the Application Server Control Console or the command-line opmnctl utility.

  Both these tools enable you to restart the cache or admin server process, or both.

• For a standalone installation of OracleAS Web Cache, use either OracleAS Web Cache Manager or the command-line webcachectl utility.

  OracleAS Web Cache Manager enables you to restart only the cache server process; webcachectl enables you to restart the cache or admin server processes, or both.

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

• Administration port properties

• Password for the administrator account

• Trusted subnets

• User and group ID information

OracleAS Web Cache Solely as a Software Load Balancer or Reverse Proxy

You can configure a special mode of OracleAS Web Cache that enables you to use OracleAS Web Cache solely as a software load balancer of HTTP traffic or reverse proxy to origin servers. This mode does not cache any content or provide support for the following features:

• Compression: OracleAS Web Cache ignores all compression settings.

• ESI: OracleAS Web Cache does not assemble ESI content.

• Cache hierarchies: If you plan to configure two caches in a cache hierarchy, then you should not configure one of the caches as a load balancer.

• Full cache cluster support: If you configure a cache cluster, OracleAS Web Cache automatically assigns a capacity of 0 to all cluster members, even if you configure other capacity values. When capacity is set to 0 for all cluster members, no requests will be forwarded between cluster members. However, you can still propagate the configuration and OracleAS Web Cache can automatically propagate invalidation requests to cluster members

• End-user performance monitoring: OracleAS Web Cache does not monitor the response time of your applications.

You can deploy a single OracleAS Web Cache server as a load balancer. However, this deployment makes the OracleAS Web Cache server a single point of failure for your application. You can instead configure a cache cluster with multiple OracleAS Web Cache servers in conjunction with operating system load balancing capabilities. Take note of the capacity changes mentioned earlier in this section.

In this mode, you can configure OracleAS Web Cache to load balance HTTP traffic in front of an application using ESI or in front of another OracleAS Web Cache. The OracleAS Web Cache load balancer does not process ESI content or participate in hierarchical caching. For example, a typical OracleAS Portal deployment has a built-in OracleAS Web Cache used for ESI assembly. For these configurations, do not configure the OracleAS Web Cache used for ESI assembly as a load balancer.

If you require other OracleAS Web Cache features, such as caching or compression support, do not configure this mode. Instead, configure a hardware load balancer or operating system load balancing support, and use the load balancing feature to manage requests to origin servers.

To configure a single OracleAS Web Cache server as a software load balancer:

1. Download an Automated Release Update (ARU) for bug 4569559.

   You can download ARUs from OracleMetalink:

   http://metalink.oracle.com

2. Follow the instructions provided in the Readme for the patch.

3. Create a backup copy of the internal.xml file. This file is located in the $ORACLE_HOME/webcache directory on UNIX and ORACLE_HOME\webcache directory on Windows.

4. Use a text editor to open the internal.xml file.

5. Locate the CALYPSOINTERNALPARAMS element.

   ...
     <CALYPSOINTERNALPARAMS>
       <HEURISTICS CATELMFACTOR="0.0"/> 
       <CACHE/>
       <SEARCHKEY/>
       <INVALIDATION/>
       <MEMORYMANAGER/>
       <PPC/> 
       <MISCELLANEOUS/> 
       <OEMPERFTOOL/>  
     </CALYPSOINTERNALPARAMS> 
   ...
   
   

6. Add the LOADBALANCE subelement directly after the OEMPERFTOOL subelement as follows:

   ...
     <CALYPSOINTERNALPARAMS>
       <HEURISTICS CATELMFACTOR="0.0"/> 
       <CACHE/>
       <SEARCHKEY/>
       <INVALIDATION/>
       <MEMORYMANAGER/>
       <PPC/> 
       <MISCELLANEOUS/> 
       <OEMPERFTOOL/>  
       <LOADBALANCE ON="YES"/>  
     </CALYPSOINTERNALPARAMS> 
   ...
   
   

7. Save internal.xml.

8. Restart OracleAS Web Cache with the following command:

   opmnctl restartproc ias-component=WebCache
   
   

9. Verify OracleAS Web Cache is running in the load balancer mode from the OracleAS Web Cache Manager by verifying the following status message displays beneath the Apply Changes and Cancel Changes buttons:

   Web Cache running in Load Balancer Mode with current configuration
   
   

   Application Server Control Console does not provide an equivalent verification status.

10. Ensure the auto-restart mechanism is enabled, as described in "Task 3: Configure Auto-Restart Settings".

11. Configure origin servers, as described in "Task 9: Configure Origin Server, Load Balancing, and Failover Settings".

12. Create site definitions and map them to the origin servers, as described in "Task 10: Configure Web Site Settings".

13. If your application deployment requires session stickiness, enable session binding. See "Bind a Session to an Origin Server".

    Applications using OracleAS Single Sign-On and Oracle Delegated Administration Services, for example, require session binding.

    If the application that requires session stickiness is an OC4J application, then configure session binding using the JSESSIONID cookie.

Consider the topology depicted in Figure 8-5.

Figure 8-5 Deploying OracleAS Web Cache as a Load Balancer

Description of "Figure 8-5 Deploying OracleAS Web Cache as a Load Balancer"

To configure this topology:

1. Assign the name of the hardware load balancer to OracleAS Web Cache.

2. Register the IP address of the OracleAS Web Cache server webche-host with www.app1.company.com.

3. Configure the OracleAS Web Cache server with the following:

   1. Receive HTTP and HTTPS requests on designated listening ports.

   2. Send HTTP and HTTPS requests to application Web servers app1-host1 and app1-host2 on designated listening ports.

   3. Map virtual host site definition for www.app1.company.com mapped to app1-host1 and app1-host2.

Operating System Load Balancing Support

Certain operating systems provide load balancing support, which can increase the availability of OracleAS Web Cache, particularly in cache clusters.

When the operating system detects a failure of one of the caches, automatic IP takeover is used to distribute the load to the remaining caches in the cluster configuration. Because requests are sent to the virtual IP address, not to a specific host, requests can be served even if one of the hosts is unreachable.

In addition, some operating systems provide load balancing for incoming requests. You can configure the operating system to balance the load of incoming requests across caches on multiple nodes.

A network load balancer does not provide all the features, such as firewall or ping URL mechanisms, that a hardware load balancer may provide, but if those needs are already met, you could consider using a network load balancer.

The following section, "Configuring Microsoft Network Load Balancing" describes how to configure a network load balancer on one operating system. Refer to your operating system documentation for more information.

http://www.microsoft.com

Ensuring That ClientIP Headers Are Valid

A client, such as a browser, can send information about its IP address in a header in a request. However, because a client could use a false IP address in the header, allowing a cache to forward that information to another cache or to the origin server can be a potential security problem. By default, OracleAS Web Cache removes any IP header information forwarded from a client and replaces it with a header that contains the correct IP address of the client. (In this case, a client can be a browser or another cache in a hierarchy.)

In a cache hierarchy, OracleAS Web Cache must be able to preserve the information that is forwarded from one cache to another in the hierarchy or from a cache to the origin server.

To configure these settings in Application Server Control Console, navigate to Web Cache Home page > Administration tab > Properties > Web Cache > Security.

To configure these settings in OracleAS Web Cache Manager:

1. In the navigator frame, select Properties > Security.

2. In the Special Security Header Configuration section of the Security page, check the value of the Accept client IP addresses encoded in ClientIP headers field.

   If the value is NO, OracleAS Web Cache removes any ClientIP request-header forwarded from the client and replaces it with a header that contains the correct IP address.

   If the value is YES, OracleAS Web Cache accepts the header received from the client and can forward it to another cache or the origin server.

3. If the settings do not match the following information, click Edit and change the settings in the Special Security Header Configuration dialog box:

   • For a simple configuration, the value should be NO.

   • In a cache cluster, the value should be NO for all cluster members.

   • In an ESI hierarchy, for the subscriber cache, the value should be NO.

   • In an ESI hierarchy, for the provider cache, the value should be YES.

     Because the provider cache received the header from the subscriber cache, it can safely forward it to the origin server.

   • In a distributed cache hierarchy, for the remote cache, the value should be NO.

   • In a distributed cache hierarchy, for a central cache that receives requests only from other caches, the value should be YES.

     If the central cache receives requests from both browsers and other caches in the hierarchy, OracleAS Web Cache cannot distinguish which is a browser and which is another cache. In this case, if you specify YES, a false IP address could potentially be forwarded from a browser. However, correct information would be forwarded from another cache. If you specify NO, a false IP address could not be forwarded from a browser. However, the information forwarded from another cache would contain the IP address of the cache, not of the original client.

4. Click Submit, and then click Apply Changes.

Configuring HTTP Request Header Limits

By default, OracleAS Web Cache provides the following limits for HTTP request header field:

• 819000 bytes for the total sum of all HTTP request header fields in requests

  Oracle recommends setting the header size to a lower value than the default to ensure security and prevent denial-of-service attacks from malicious clients.

  If the length of the request is larger than the allowed limit, OracleAS Web Cache sends an error to the client and reports the error 11356 to the event log:

  Total request header length exceeds configured maximum. A forbidden error response is returned to the client.
  
  

• 8152 bytes for an individual HTTP request header field

  Oracle recommends setting the individual header size based on how large an application sets HTTP requests header fields.

  If the length of the request is larger than the allowed limit, OracleAS Web Cache sends an error to the client and reports the error 11355 to the event log:

  Single request header length exceeds configured maximum. A forbidden error response is returned to the client.
  
  

To modify the default header limits in Application Server Control Console, navigate to Web Cache Home page > Administration tab > Properties > Web Cache > Security.

To modify the default header limits in OracleAS Web Cache Manager:

1. In the navigator frame, select Properties > Security.

   The Security page appears.

2. In the HTTP Request Header Limits section of the Security page, click Edit.

   The HTTP Request Header Limits dialog box appears.

3. In the Maximum combined header size in bytes field, specify the total sum of all HTTP request header fields in requests. Specify a limit of at least 4096 bytes (4 KB).

4. In the Maximum individual header size in bytes field, specify the allowed length limit of an individual HTTP request header fields. Specify a limit of at least 256 bytes.

5. Click Submit, and then click Apply Changes.

Running webcached with Root Privilege

On UNIX, you must configure webcached to run with root privilege in the following cases:

• Privileged port numbers less than 1024 are being used for OracleAS Web Cache listening ports.

• There are more than 1,024 file descriptors being used for connections to OracleAS Web Cache.

• The current opmnctl or webcachectl user does not match the configured process identity user in the Security page (Web Cache Home page > Administration tab > Properties > Application > Origin Servers) of Application Server Control Console or the Process Identity page (Properties > Process Identity) of OracleAS Web Cache Manager.

This section contains the following topics:

• Configuring Root Privilege for Privileged Ports and More than 1,024 File Descriptors

• Configuring Root Privilege for the Current User

• Reverting Permissions Back to Installation State