Oracle Web Cache Administration and Deployment Guide Release 1.0.2.3 Part Number A86722-03 |
|
This chapter explains how to perform administrative tasks to Oracle Web Cache. It contains these topics:
Anytime Oracle Web Cache's configuration is modified, Oracle Web Cache must be stopped and restarted. To start and stop Oracle Web Cache, use either Oracle Web Cache Manager or the webcachectl
utility.
When you start Oracle Web Cache from the webcachectl
utility, the admin
server process for the administrative interface and the cache
server process for the actual cache are started. The Oracle Web Cache Manager starts only the cache
server process. To initialize Oracle Web Cache for the first time, use the webcachectl
utility to start both processes.
Use Oracle Web Cache Manager... | Use the webcachectl Utility... |
---|---|
To start the
|
To start Oracle Web Cache:
To stop Oracle Web Cache, from the command line, enter:
The following message appears:
|
On Windows NT, Oracle Web Cache can also be started through the Control Panel:
admin
server.
cache
server.
Invalidation messages are sent to Oracle Web Cache to an invalidation listening port through HTTP POST
messages. The invalidation messages identify the documents to be invalidated.
This section contains the following invalidation-related topics:
By default, Oracle Web Cache listens for invalidation requests at port 4001.
To change the default port number:
Invalidation messages are HTTP POST
message written in Extensible Markup Language (XML) syntax. The contents of the XML message body tells the cache which URLs to mark as invalid. As shown in Figure 8-1, invalidation messages can be sent using one of the following methods:
telnet
This section describes how to send invalidation messages using one of the following methods:
When you send an invalidation message with a HTTP POST
message, you specify the host name of Oracle Web Cache, the invalidation listening port number, and the invalidation message.
For example, if you were using telnet
, you would send an invalidation message using the following procedure:
telnet webcache_host invalidation_port
POST
message header and authenticate the user invalidator using Base64 encoding string with the following syntax.
POST /x-oracle-cache-invalidate http/1.0|1 Authorization: BASIC <base64 encryption of invalidator:invalidator_password
> content-length:#bytes
An example of Authorization: BASIC <
base64 encryption of invalidator:invalidator_password
>
follows:
Authorization: BASIC aW52YWxpZGF0b3I6YWRtaW4=
In this example, aW52YWxpZGF0b3I6YWRtaW4=
is "invalidator:admin
" encoded.
See Also:
"Task 2: Modify Security Settings" for further information about changing the invalidation password |
<?xml version="1.0"?> <!DOCTYPE INVALIDATION SYSTEM "internal:///invalidation.dtd"> <INVALIDATION> <URL EXP="URL" PREFIX="YES|NO"> <VALIDITY LEVEL="validity" REFRESHTIME="seconds"/> <COOKIE NAME="cookie_name" VALUE="value" NONEXIST="YES|NO"/> <HEADER NAME="HTTP_request_header" VALUE="value"/> </URL> </INVALIDATION>
Table 8-1 Invalidation Message Syntax
Invalidation responses are returned in the following format:
<?xml version="1.0"?> <!DOCTYPE INVALIDATIONRESULT [ <!ELEMENT INVALIDATIONRESULT (URL+)> <!ELEMENT URL EMPTY> <!ATTLIST URL EXPR CDATA #REQUIRED ID CDATA #REQUIRED STATUS CDATA #REQUIRED NUMINV CDATA #REQUIRED > ]> <INVALIDATIONRESULT> <URL EXPR="URL" ID="ID" STATUS="status" NUMINV="number"> </INVALIDATIONRESULT>
Table 8-2 Invalidation Response Syntax
Oracle Web Cache Manager provides an easy-to-use interface for invalidating cached objects. Under the covers, the message mechanics are much like the telnet
example. The advantage of using Oracle Web Cache Manager is that the administrator is isolated from the intricacies of the HTTP and XML formats, and consequently, there is less chance for error. The administrator need only specify which objects to invalidate and how invalid those objects should be
To invalidate documents with Oracle Web Cache Manager:
The Cache Cleanup page appears in the right pane.
Database triggers are procedures that are stored in the database and activated ("fired") when specific conditions occur, such as adding a row to a table. You can use triggers to send invalidation messages. To this do, use the UTL_TCP
Oracle supplied package to send invalidation messages through database triggers.
Many Web sites use scripts for uploading new content to databases and file systems. A large online book retailer, for instance, might run a PERL script once a day in order to bulk load new book listings and price changes into its catalog database. The retailer would want the price changes and availability listings to be reflected in the item views and search results currently cached in Oracle Web Cache. To achieve this, the PERL script can be modified such that when the bulk loading operation has completed, the script will send an invalidation message to the cache invalidating all catalog views and search results. (Note that the invalidation message need not list every individual search page or item view that might be effected by the data change.) The performance assurance feature of Oracle Web Cache enables administrators to use broad brush strokes when invalidating content, making it safe to invalidate all catalog content even if only a fraction of that content has changed.
Invalidation messages can also originate from a Web site's underlying application logic or from the content management application used to design Web pages. Oracle Web Cache ships with invalidation Java source that you can link with your applications for automatically generating invalidation messages.
These examples require utilizing the POST
method which also requires sending the number of bytes (or characters) in the content_length:
#bytes
portion of the header. Please note that one carriage return is required after the content_length:
#bytes
line and before the XML message or BODY
information.
Invalidation message:
<?xml version="1.0" ?> <!DOCTYPE INVALIDATION SYSTEM "internal:///invalidation.dtd"> <INVALIDATION> <URL EXP="/images/logo.gif" PREFIX="NO"> <VALIDITY LEVEL="1"/> </URL> </INVALIDATION>
Invalidation response:
<?xml version="1.0"?> <!DOCTYPE INVALIDATIONRESULT [ <!ELEMENT INVALIDATIONRESULT (URL+)> <!ELEMENT URL EMPTY> <!ATTLIST URL EXPR CDATA #REQUIRED ID CDATA #REQUIRED STATUS CDATA #REQUIRED NUMINV CDATA #REQUIRED > ]> <INVALIDATIONRESULT> <URL EXPR="/images/logo.gif" ID="1" STATUS="SUCCESS" NUMINV="1"> </INVALIDATIONRESULT>
Invalidation message:
<?xml version="1.0"?> <!DOCTYPE INVALIDATION SYSTEM "internal:///invalidation.dtd"> <INVALIDATION> <URL EXP="/images/" PREFIX="YES"> <VALIDITY LEVEL="1" REFRESHTIME="60"/> </URL> </INVALIDATION>
Invalidation response:
<?xml version="1.0"?> <!DOCTYPE INVALIDATIONRESULT [ <!ELEMENT INVALIDATIONRESULT (URL+)> <!ELEMENT URL EMPTY> <!ATTLIST URL EXPR CDATA #REQUIRED ID CDATA #REQUIRED STATUS CDATA #REQUIRED NUMINV CDATA #REQUIRED > ]> <INVALIDATIONRESULT> <URL EXPR="/images/" ID="1" STATUS="SUCCESS" NUMINV="125"> </INVALIDATIONRESULT>
Invalidation message:
<?xml version="1.0"?> <!DOCTYPE INVALIDATION SYSTEM "internal:///invalidation.dtd"> <INVALIDATION> <URL EXP="/" PREFIX="YES"> <VALIDITY LEVEL="0"/> </URL> </INVALIDATION>
Invalidation response:
<?xml version="1.0"?> <!DOCTYPE INVALIDATIONRESULT [ <!ELEMENT INVALIDATIONRESULT (URL+)> <!ELEMENT URL EMPTY> <!ATTLIST URL EXPR CDATA #REQUIRED ID CDATA #REQUIRED STATUS CDATA #REQUIRED NUMINV CDATA #REQUIRED > ]> <INVALIDATIONRESULT> <URL EXPR="/" ID="1" STATUS="SUCCESS" NUMINV="5347"> </INVALIDATIONRESULT>
Oracle Web Cache events and errors are stored in an event log. The event log can help you determine what documents or objects have been inserted into the cache. It can also identify listening port conflicts or startup and shutdown issues. The event log has a file name of event_log
and is stored in $ORACLE_HOME/webcache/logs
on UNIX and ORACLE_HOME
\webcache\logs
on Windows NT.
Events are formatted into the following fields:
Timestamp Information/Warning/Error Message
Figure 8-2 shows an event log excerpt with successful startup entries.
19/Sep/2000:10:20:56 -0500 -- Information: Max Connect Count exceeds compile time limit - defaulting to connect limit: ( 854 ) 19/Sep/2000:10:20:57 -0500 -- Information: Listening on ADMINISTRATION port 5000 address 0.0.0.0 19/Sep/2000:10:20:57 -0500 -- Information: The admin server started successfully 19/Sep/2000:10:20:57 -0500 -- Information: Max Connect Count exceeds compile time limit - defaulting to connect limit: ( 854 ) 19/Sep/2000:10:20:57 -0500 -- Information: Listening on NORM port 1100 address 0.0.0.0 19/Sep/2000:10:20:57 -0500 -- Information: Listening on INVALIDATION port 5001 address 0.0.0.0 19/Sep/2000:10:20:57 -0500 -- Information: Listening on STATISTICS port 5002 address 0.0.0.0 19/Sep/2000:10:20:58 -0500 -- Information: The cache server started successfully 19/Sep/2000:10:20:58 -0500 -- Information: The cache server is started by the admin server at startup
Figure 8-3 shows an event log excerpt with unsuccessful startup events. Oracle Web Cache is unable to listen on port 1100, because it is already in use. This can occur if Oracle Web Cache is already running and listening on that port or another application is using that port.
14/Sep/2000:16:37:41 -0800 -- Error: A failure occurred ( Address already in use ) when assigning a port ( domain: <NONE>, address: 0.0.0.0, port: 1100 ). Change PORT attribute of the LISTEN element in the configuration file to a suitable unused port. 14/Sep/2000:16:37:41 -0800 -- Error: Failed to start the server. 14/Sep/2000:16:37:41 -0800 -- Error: The server could not initialize 14/Sep/2000:16:37:41 -0800 -- Information: The server is exiting
Figure 8-4 shows an event log excerpt with an event associated with an invalidation request for the removal of document personal.htm
.
30/Sep/2000:22:52:52 -0500 -- Information: <Invalidation>1 URLs with prefix personal.htm have been successfully invalidated.
Figure 8-5 shows an event log excerpt with an XML invalidation message error. In this example, Oracle Web Cache is unable to parse the message.
Example: Errors in the XML parsing. Note: The configuration files and invalidation files use XML files. 19/Sep/2000:10:55:26 -0500 -- Error: Invalidation XML Buffer cannot be parsed. 19/Sep/2000:10:55:26 -0500 -- Error: XML parsing error.
Figure 8-6 shows an event log excerpt with typical shutdown entries.
14/Sep/2000:11:16:55 -0700 -- Information: SIGTERM caught - program will shut down once all connections are complete. 14/Sep/2000:11:16:55 -0800 -- Information: SIGTERM caught - program will shut down once all connections are complete. 14/Sep/2000:11:16:55 -0700 -- Information: The server is exiting 14/Sep/2000:11:16:55 -0800 -- Information: The server is exiting
To list just the errors in the event log, use grep
on UNIX. For example:
grep " Error:" error*
To list the errors by the current day, enter grep " Error:" event_log "dd/mon/yyyy"
. For example:
grep " Error:" event_log | grep "19/Sep/2000"
To list errors by the current day and hour, enter grep " Error:" event_log "dd/mon/yyyy:hh"
.
To establish event log configuration settings:
The Event Logging page appears in the right pane.
The Change Options for Event Logging dialog box appears.
Each Web site that Oracle Web Cache supports has its own access log. An access log contains information about the HTTP requests sent to Oracle Web Cache for a Web site. The access log has a file name of access_log
and is stored by default in $ORACLE_HOME/webcache/logs
on UNIX and ORACLE_HOME
\webcache\logs
on Windows NT. Note that Oracle Web Cache uses buffered logging for the access log, that is, it writes to the access log after the buffer is full.
You can configure the content of the access log file by defining the fields to appear for each HTTP request event. These fields are a part of the Extended LogFile Format (XLF), which is a superset of the Common LogFile Format (CLF).
Table 8-3 lists the XLF fields you can select.
Field | Description |
---|---|
|
Information about the user agent originating the request |
|
Allows the client to specify the address (URI) of the resource from which the Request-URI was obtained |
|
Username if the request contained an attempt to authenticate |
|
Content-length of the transferred document |
|
Date at which the transaction completed |
|
Time at which the transaction completed |
|
Amount of time taken (in seconds) for transaction to complete |
|
Client's IP address and port |
|
Oracle Web Cache's IP address and port |
|
Oracle Web Cache-to-client HTTP request method ( |
|
Oracle Web Cache-to-client HTTP status code:
See Also: |
|
Client-to-Oracle Web Cache URI |
|
Client-to-Oracle Web Cache stem portion of URI, omitting the query |
|
Client-to-Oracle Web Cache query portion of URI, omitting the stem |
|
|
If no fields are specified, then the following default CLF fields are used in the access log file:
c-ip cauth-id [clf-date] "request line" sc-status bytes
Figure 8-7 shows an example access log using the default CLF fields:
c-ip cauth-id [clf-date] "request line" sc-status bytes
The "request line"
is represented by the "GET ...HTTP/1.0"
portion of the request. The "request line"
enables you to determine what is being accessed and the following sc_status
, or HTTP status code, reports if the request was successfully completed.
138.2.213.146 - - [19/Sep/2000:10:27:42 -0500] "GET /~ssandrew/personal.htm HTTP/1.0" 200 2438 138.2.213.146 - - [19/Sep/2000:10:27:54 -0500] "GET /~ssandrew/personal.htm?UserName=Bob HTTP/1.0" 200 2438 138.2.213.146 - - [19/Sep/2000:10:47:30 -0500] "GET /~ssandrew/count.sh HTTP/1.0" 403 289 138.2.213.146 - - [19/Sep/2000:10:47:34 -0500] "GET /~ssandrew/sbin/count.sh HTTP/1.0" 200 321 138.2.213.146 - - [19/Sep/2000:10:47:41 -0500] "GET /sbin/count.sh HTTP/1.0" 200 321 138.2.213.146 - - [19/Sep/2000:11:34:23 -0500] "GET /cache.htm HTTP/1.0" 200 250 138.2.213.146 - - [19/Sep/2000:11:38:23 -0500] "GET /cache.htm HTTP/1.0" 304 0 138.2.213.146 - - [19/Sep/2000:11:38:48 -0500] "GET /cache.htm HTTP/1.0" 304 0 206.223.27.37 - - [19/Sep/2000:15:14:29 -0500] "GET /~ssandrew/personal.htm?UserName=Joe HTTP/1.0" 200 2438 206.223.27.37 - - [19/Sep/2000:15:17:12 -0500] "GET /~ssandrew/personal.htm?UserName=Shehzaad HTTP/1.0" 200 438 144.25.223.39 - - [19/Sep/2000:15:30:34 -0500] "GET /htdocs/coelist.html HTTP/1.0" 200 4219 144.25.223.39 - - [19/Sep/2000:15:30:34 -0500] "GET /images/redheaderbanner.gif HTTP/1.0" 200 1226 138.2.213.146 - - [19/Sep/2000:10:49:44 -0500] "GET /pls/coe/find_via_post HTTP/1.0" 200 1119 138.2.213.146 - - [19/Sep/2000:10:49:44 -0500] "GET /ows-img/chalk.jpg HTTP/1.0" 404 284 130.35.35.21 - - [20/Sep/2000:00:36:35 -0500] "GET /images/support.jpg HTTP/1.0" 206 3106 130.35.35.21 - - [20/Sep/2000:00:36:35 -0500] "GET /images/ani_coe.gif HTTP/1.0" 206 73118
Figure 8-8 shows an access log excerpt in which there are two Web browser reloads, followed by two shift reloads, and two more reloads.
138.2.213.146 - - [19/Sep/2000:11:04:24 -0500] "GET /cache.htm HTTP/1.0" 200 250 138.2.213.146 - - [19/Sep/2000:11:04:26 -0500] "GET /cache.htm HTTP/1.0" 200 250 138.2.213.146 - - [19/Sep/2000:11:29:24 -0500] "GET /cache.htm HTTP/1.0" 304 0 138.2.213.146 - - [19/Sep/2000:11:29:25 -0500] "GET /cache.htm HTTP/1.0" 304 0 138.2.213.146 - - [19/Sep/2000:11:29:30 -0500] "GET /cache.htm HTTP/1.0" 200 250 138.2.213.146 - - [19/Sep/2000:11:29:35 -0500] "GET /cache.htm HTTP/1.0" 200 250
Figure 8-9 shows an access log excerpt in which a browser requested the wrong path. This is indicated by HTTP status code 403. The browser then requested the correct path. This is indicated by HTTP status code 200.
38.2.213.146 - - [19/Sep/2000:10:47:30 -0500] "GET /~ssandrew/count.sh HTTP/1.0" 403 289 138.2.213.146 - - [19/Sep/2000:10:47:34 -0500] "GET /~ssandrew/sbin/count.sh HTTP/1.0" 200 321
Figure 8-10 shows an access log excerpt in which a Oracle Web Cache cannot find any objects matching the requested URL /ows-img/chalk.jpg
. This indicated by HTTP status code 404.
138.2.213.146 - - [19/Sep/2000:10:49:44 -0500] "GET /pls/coe/find_via_post HTTP/1.0" 200 1119 138.2.213.146 - - [19/Sep/2000:10:49:44 -0500] "GET /ows-img/chalk.jpg HTTP/1.0" 404 284
Figure 8-11 shows an access log excerpt in which the first entry shows a Web browser request for /cache.htm
being successfully completed. The second and third entries return a HTTP status code of 304, indicating that document has not been modified and does not need to be returned again.
138.2.213.146 - - [19/Sep/2000:11:34:23 -0500] "GET /cache.htm HTTP/1.0" 200 250 138.2.213.146 - - [19/Sep/2000:11:38:23 -0500] "GET /cache.htm HTTP/1.0" 304 0 138.2.213.146 - - [19/Sep/2000:11:38:48 -0500] "GET /cache.htm HTTP/1.0" 304 0
To enable access logging:
The Access Logs page appears in the right pane.
The Change Options for Access Logs dialog box appears.
access_log.
yyyymmdd
and write new log information to access_log
. If you have a high-volume site, increase the frequency.
To disable access logging:
The Access Logs page appears in the right pane.
The Change Options for Access Logs dialog box appears.
|
![]() Copyright © 1996-2001 Oracle Corporation. All Rights Reserved. |
|