Configuring Web Cache | Oracle Application Server 10g: J2EE Deployment and Administration

WC comes with any mid-tier installation option in the event that it will be installed on the same node as the mid- tier origin server (the origin server is the OHS addressed by WC). If you have a separate node allocated just for WC, install the smaller J2EE and WC software on that node because you won't be using any Oracle Portal or Business Intelligence components on that server. In this example, you'll be using the WC components that came with the first standalone J2EE and WC mid-tier installation. It will be installed on the same node as the origin server, however the configuration steps are roughly the same as if you were working on two nodes.

Administrative Tools

WC is configured and managed through the web-based GUI tool WC Manager and through the webcachectl command-line utility. In previous releases of 9iAS (1.0.2 and 9.0.2), WC existed as a separate component and had to be started separately from the other 9iAS components. Starting with the 10g AS (9.0.4) release, WC has been brought under Oracle Process Management Notification (OPMN) control.

For standalone instances that aren't part of a farm or cluster, use the webcachectl utility to start the WC Manager. For instances that are part of a farm or cluster, use the OPMN commands. In this case the command to individually start WC via opmnctl is as follows :

 $ opmnctl startproc ias-component=webcache

This example J2EE installation is currently a standalone instance that isn't integrated with an infrastructure repository). Therefore the correct tool to use to start it is webcachectl . For the standalone instance, to access the WC Manager administration tool you need to first start it with the webcachectl command-line utility.

 $ cd $ORACLE_HOME/webcache/bin $ webcachectl start ************************************************************************** WARNING! With the exception of standalone OracleAS Web Cache installations, direct use of webcachectl within Oracle Application Server is deprecated. Using webcachectl in conjunction with Oracle Process Management and Notification (OPMN) may lead to unexpected behavior (such as OPMN automatically restarting OracleAS Web Cache after it has been shutdown using webcachectl). Please use opmnctl (located at $ORACLE_HOME/opmn/bin/opmnctl) instead. webcachectl may not be shipped with future versions of Oracle Application Server. ************************************************************************** OracleAS Web Cache 9.0.4.0.0 Copyright (c) 1999, 2003, Oracle. All rights reserved. Admin Server now running as process 30983 Admin Server is attempting to start the Cache Server Cache Server now running as process 30988 $

WC runs as two processes, an Admin Server process and a Cache server process. They are shown in the following sample.

Note	The l flag on ps efl isn't present on all OS distributions, so ps ef may be needed.

Web Cache Admin Server

 $ ps -efl  grep 30983 040 S oracle   30983     1  0  75   0    -  4997 schedu 14:02 ? 00:00:00 /u01/app/oracle/product/9.0.4mt1/OraHome1/webcache/bin/webcached -A 040 S oracle   30984 30983  0  75   0    -  4997 schedu 14:02 ? 00:00:00 /u01/app/oracle/product/9.0.4mt1/OraHome1/webcache/bin/webcached -A 000 R oracle   31210  4436  0  76   0    -   428 -      14:05 pts/1 00:00:00 grep 30983 $

Web Cache Server

 $ ps -efl  grep 30988 040 S oracle   30988     1  0  75  0    - 12501 schedu 14:02 ? 00:00:00 /u01/app/oracle/product/9.0.4mt1/OraHome1/webcache/bin/webcached /u01/app/oracle 040 S oracle   30989 30988  0  75  0    - 12501 schedu 14:02 ? 00:00:00 /u01/app/oracle/product/9.0.4mt1/OraHome1/webcache/bin/webcached /u01/app/oracle 000 R oracle   31212  4436  0  76  0    -   428 -      14:05 pts/1 00:00:00 grep 30988 $

By default WC runs as a nonroot process. Therefore, on UNIX and Linux, it cannot be started on a port below 1024 or have more than 1024 processes. This is important for administrators because it means WC cannot listen on the default HTTP port 80 or HTTPS port 443. Additionally, it cannot have more than 1024 concurrent connections (processes). To remedy this potential problem, Oracle provides a shell script ( webcache_setuser.sh ) that changes the setuid permissions on the WC executable ( webcached ) so it can run as root , but can be started by the oracle user . You can see by default that each of the files in $ORACLE_HOME/webcache/bin are owned by oracle:dba , as shown here:

 $ pwd /u01/app/oracle/product/9.0.4mt1/OraHome1/webcache/bin $ ls -l total 3272 -rwxr-x---    1 oracle   dba         37853 Jan 28 07:08 webcachectl -rwxr-x---    1 oracle   dba       3293504 Jan 28 07:08 webcached -rwxr-xr-x    1 oracle   dba          4651 Sep 29 16:37 webcache_setuser.sh $

To run the script and change the permissions, first shut down the WC processes, then execute the webcache_setuser.sh as the root user with $ORACLE_HOME set correctly, as follows:

 $ su root Password: [root@mike bin]# id uid=0(root) gid=0(root) groups=0(root),1(bin),2(daemon),3(sys),4(adm),6(disk),10(wheel) [root@mike bin]# ./webcache_setuser.sh setroot oracle setroot task completed successfully. [root@mike bin]# ls -l total 3272 -rwxr-x---    1 oracle   dba         37853 Jan 28 07:08 webcachectl -rwsr-x---    1 root     dba       3293504 Jan 28 07:08 webcached -rwxr-xr-x    1 oracle   dba          4651 Sep 29 16:37 webcache_setuser.sh [root@mike bin]#

As you can see, the script has changed the setuid execute permissions on webcached so that it can run as root even though it's started by oracle . Switch users back to the oracle account and then run the webcachectl start to restart the WC processes.

Note

A common UNIX/Linux question is "Do the rules of changing setuid permissions on executables also apply to OHS (Apache)?" The answer is "Yes!" If you need to run OHS (Apache) on port 80 or 443, you need to change the setuid .apachectl executable to run as root . Although this is specified in the 10g AS Installation and Configuration Guide, it's a step many people initially overlook. If you forget to do this and then attempt to start up OHS, you'll see "Permission denied : make_sock : could not bind to address X port 80/443" type errors in the OHS error_log file. To make this setting, do the following:

 $ cd $ORACLE_HOME/Apache/Apache/bin $ su root Password: [root@mike bin]# chown root .apachectl [root@mike bin]# chmod 6750 .apachectl       [root@mike bin]# ls -al .apachectl -rwsr-s---    1 root     dba         17547 Nov 23 10:46 .apachectl [root@mike bin]#

Notice that we modified "dot" .apachectl , not just apachectl . Once this change is made, OHS can be configured to listen on ports 80 or 443.

Once the WC processes are up, you can access the WC Manager tool via the default port 4000 with the following URL: http://mike.wessler. name :4000/ .

The opening banner page is shown in Figure 19-3.

Figure 19-3: Web Cache admin banner page

This page is the banner page for WC. It contains links to documentation, an "Is Web Cache Working" demo and, most importantly, the login link into the administration page. You can run the "Is Web Cache Working" demo to verify that WC is indeed running and to load some initial performance statistics into the tool. The administrative login link is located on the top right of the page.

Clicking the link presents a login box. The default username is administrator and the password is whatever the ias_admin password is.

The login page can be accessed directly at http://mike.wessler.name:4000/webcacheadmin .

After entering the administrator username and password, you're presented with the page shown in Figure 19-4.

Figure 19-4: Web Cache Manager page for Cache Operations

By default, your login opens the Cache Operations page, which is the first page listed in the left frame. From this page you can start, stop, or restart WC server processes.

The WC Manager tool is composed of a frame of options on the left and the resulting pages on the right. The following administration categories are available in the left frame, as follows:

Operations. Administrative actions such as starting and stopping, invalidating content, and log file management.
Monitoring. View performance metrics for WC, origin servers, and most popular content.
Properties. Security and runtime parameter settings for WC; it contains several useful settings.
Logging and Diagnostics. Contains additional monitoring and log file management settings.
Ports. Used to configure listening, administration, and invalidation ports and protocols.
Origin Servers, Sites, and Load Balancing. Key pages for configuring WC to origin server mapping, load balancing, error pages, and session binding.
Rules for Caching, Personalization, and Compression. Establishes rules for caching and compression.
Rule Association. Used to associate multiple compression, expiration, and caching rules with policies.

Figure 19-4 only shows part some of the administrative options available. Figure 19-5 shows the remaining options available.

Figure 19-5: Remaining Web Cache admin page options

The left frame shows the remaining administrative options starting with Ports. As you can see in the right frame, WC is currently set to listen on port 7778 for any IP address on the node (we'll show how to change this a little later in the chapter).

In the following sections we'll examine common configuration steps using the WC Manager tool.

Configuration Steps

WC comes preconfigured after installation for the WC server to direct requests to the OHS, which came with the installation. This means the OHS server installed with the WC product is the default origin server. By default, WC listens on port 7778 and directs cache miss requests to the OHS listening on port 7777. This represents a site-to-server mapping of the following: Client to WC (Port 7778) to OHS (Port 7777). In effect, the following URLs will both yield the same result: http://mike.wessler.name:7777/j2ee/servlet/HelloWorldServlet and http://mike.wessler.name:7778/j2ee/servlet/HelloWorldServlet .

The difference is that the first request on port 7777 went directly to OHS while the second request to port 7778 went initially to WC and was then passed to OHS.

There are three pages under the Origin Servers, Sites, and Load Balancing section that are used to establish this mapping relationship: Origin Servers, Site Definitions, and Site-to-Server Mapping.

Origin Server

The Origin Server page is where each "receiving" OHS server is defined. These are the servers that are available for WC to pass the requests resulting in cache misses to for processing. In Figure 19-6 you can see that a single default origin server has been defined.

Figure 19-6: Origin Servers admin page

In Figure 19-6 you can see that one OHS server on the node mike.wessler.name is listening on port 7777 for HTTP connections. The 100 in the Capacity column indicates that 100 percent of all requests will be sent to this origin server. The Capacity parameter is more useful when managing multiple origin servers in a cluster (for example, Server A gets 40 percent, Server B gets 60 percent). The setting of 5 for the Failover Threshold column and the 10 seconds in the Ping Interval (seconds) column indicates that WC will ping this server every 10 seconds and if it gets a negative response five times in a row, it considers the server to be down and fails over to the other node. You'll work more with this page in Chapter 21.

Site Definitions

The Site Definitions page is where the URLs and ports that WC is listening on are defined. From this page you configure WC to listen on a specific set of ports and URLs. The default setting is shown in Figure 19-7.

Figure 19-7: Site Definitions admin page

In Figure 19-7, you can see that WC is listening on port 7778 for HTTP on mike.wessler.name . Additionally, no aliases have been created for this entry. From this screen you could create a new entry for WC to listen on for a different port. Keep in mind that you are not creating a new OHS virtual host with this, but an equivalent within WC.

In Figure 19-8 you can edit the WC site definition for wc-test.name to be listening on port 7778 (WC default port).

Figure 19-8: Add Site Definition for wc-test.name

In the previous figure, we added a new site definition wc-test.name and specified for it to listen on port 7778 for HTTP. We also specified an alias for www.wc-test.name . This essentially creates a "virtual host" for WC to listen on. Of course your DNS server has to be updated to resolve this new address. Additionally, if you wanted it to listen on a different port you would need to configure WC for that port using the Listen Ports link.

To make these changes be saved, click the Apply Changes button at the top right of the WC Manager screen. Then restart WC for the changes to take effect. This can be done via the Restart button in the Cache Operations screen.

Once the WC server is restarted you can see that the following configuration changes have been made for wc-test.name in Figure 19-9.

Figure 19-9: New Site Definition for wc-test.name

At this point WC is listening on wc-test.name on port 7778, but the following URL will not yet work: http://wc-test.name:7778/j2ee/servlet/HelloWorldServlet .

The reason is that although WC is listening, it doesn't have a mapping of wc-test.name on port 7778 to the origin server. This mapping needs to be established in the next step.

Server-to-Site Mapping

To create an association between a WC site and an origin server, you must access the Server-to-Site Mapping page. Within it, you can associate the new wc-test.name site to the existing origin server. The default settings are shown in Figure 19-10.

Figure 19-10: Site-to-Server Mapping page

In Figure 19-10, there are three site-to-server mappings to the mike.wessler.name origin server on port 7777. To add a mapping for wc-test.name , click the Insert Below button and then fill in the values as shown in Figure 19-11.

Figure 19-11: Adding a Site-to-Server Mapping for wc-test.name

In Figure 19-11 we manually added wc-test.name to use port 7778 via the Enter Site Name field and also (for demonstration purposes) selected the same site from the Site Definitions drop-down box. Since there's only one origin server defined, we checked that check box next to mike.wessler.name 7777 HTTP. For the Exclude drop-down box, we selected Unrestricted. Next you must select Apply Changes and then restart WC.

The final settings for the Site-to-Server Mapping page are shown in Figure 19-12.

Figure 19-12: Adding a site-to-server mapping for wc-test.name

You now have the following mapping in place: client to WC ( wc-test.name 7778) to OHS ( mike.wessler.name 7777). Once WC has been restarted with these changes, the following URL will work: http://wc-test.name:7778/j2ee/servlet/HelloWorldServlet .

The wc-test.name will receive the request on port 7778 and pass it on to the origin server OHS if cached content isn't found.

Configuration Properties

Under the Properties administrative frame, there are several pages that are of special interest after the basic configuration has occurred. They are

Security. Changing passwords.
Auto-Start. Automatic restart by OPMN.
Network Timeouts. KeepAlive and OriginServerTimeout
Resource Limits. Size of memory cache.
Clustering. WC servers can themselves be clustered. This provides additional WC servers for processing and fault tolerance. This isn't the same as clustering mid-tier instances and isn't needed if you only need to cluster mid-tier instances.

We'll examine these configuration pages in greater detail in the following sections.

Security

Passwords for the invalidator and administrator accounts can be changed via the Security page shown in Figure 19-13.

Figure 19-13: Changing passwords on the Security page

Additionally, within this page you can determine which subnets and IP addresses WC should trust to accept administrative or invalidation commands. Additionally, you can change the HTTP request header size limits and deny client SSL certificates.

Auto-Start

Once WC is running you can set options to have it automatically restarted if it fails. Additionally, you can specify if and how often it's tested (via network pings ) before it's considered to be down and a restart occurs. These settings are shown in Figure 19-14.

Figure 19-14: Configuring an automatic restart with the Auto-Start page

Because you've configured your site to use WC and have distributed the URL to your users, it's important that WC isn't down. If it is, users will not be able to connect to the WC URL even though your OHS server may be up. For additional redundancy, you can configure additional WC servers via WC clustering.

Network Timeouts

Just as OHS has KeepAlive and Timeout directives, WC has similar parameters. These settings are shown in Figure 19-15.

Figure 19-15: Network Timeouts page

KeepAlive determines how long, after a client receives a response, its connection to WC stays open . Since most connections to a web page incur multiple requests from the web server, it makes sense to keep the connection established rather than suffering the overhead of tearing down and reestablishing new network connections for each request. The default value is 5 seconds, but based on previous experience we normally increase this to 15 seconds.

Origin Server Timeout is roughly analogous to the OHS (Apache) directive Timeout . It's how long the WC server will wait for a response from the origin server after submitting a request. During this time, WC is waiting while the origin OHS is running a process to generate a response. After this period is exceeded, the user receives a network apology page. The contents of the page can be altered by the administrator to be more descriptive.

The default setting for the Origin Server Timeout is 3,600 seconds (60 minutes). That value seems a bit high to me because if it takes 60 minutes to run an online request, perhaps it should instead be executed in a noninteractive batch mode. At a minimum it should be reviewed from a tuning perspective. We would consider 15 minutes (900 seconds) more reasonable, but it really depends on the application and workload.

Resource Limits

WC stores its cached objects in memory for optimum performance. Similar in some respects to the shared pool in Oracle databases, you can configure the size of the cache and also the maximum size of any cached object. You can see the default settings in Figure 19-16.

Figure 19-16: Cache memory with Resource Limits page

In Figure 19-16 you can see that the maximum size for memory within WC is 500 MB. It doesn't allocate all 500 MB on startup; rather it allocates 50 MB initially and grows as needed. These values can be changed by clicking the Edit button.

Setting the Maximum Incoming Connections column to 700 specifies that no more than 700 simultaneous connections can connect to WC. The Max Cached Object Size (KB) column indicates that no cached object (PDF for example) can exceed 100 KB. Objects exceeding this size will still be delivered to the client, but they will not be cached. If you find that a lot of content exceeds this limit, then WC isn't being effectively used, and you should either adjust the settings or reevaluate whether WC is really needed.