| Oracle® Containers for J2EE Configuration and Administration Guide 10g (10.1.3.1.0) Part Number B28950-01 |
|
|
View PDF |
| Oracle® Containers for J2EE Configuration and Administration Guide 10g (10.1.3.1.0) Part Number B28950-01 |
|
|
View PDF |
This chapter explains how additional Web sites can be configured in an OC4J standalone environment to provide access to Web applications deployed into the OC4J instance. It also explains how to configure and enable a secure Web site utilizing Secure Socket Layer (SSL) communication between the client and OC4J using HTTPS.
The following sections are included:
In the context of OC4J, Web requests sent to applications deployed to an OC4J instance are received by a Web site, a listener configured to accept requests on a specific protocol and port (or range of ports). Every Web module deployed into an OC4J instance must be bound to a Web site through which it will be accessed. This binding is typically performed as part of the application deployment process.
A default Web site is created in each OC4J instance upon installation. The configuration for the default Web site is defined in a configuration file, default-web-site.xml, installed by default in the ORACLE_HOME/j2ee/instance/config directory. See "Configuring Web Site Connection Data" to gain an understanding of Web site configuration.
Standalone OC4J
In a standalone OC4J configuration, the default Web site is configured to receive HTTP requests directly on a specific port, which is 8888 by default. The site can alternatively be configured to receive secure HTTPS requests.
Single OPMN-managed OC4J instance
In a single OPMN-managed OC4J installation, the default Web site can be similarly configured to receive HTTP or HTTPS requests directly. A specific listener port can be specified in default-web-site.xml, or a range of ports can be set in the OPMN configuration file (opmn.xml). See "Configuring Web Site Data in OPMN-Managed OC4J Instances" for details.
Multiple OPMN-managed OC4J instances
In a cluster of two or more OPMN-managed OC4J instances, the default Web site is configured to receive requests forwarded from Oracle HTTP Server via through Apache JServ Protocol (AJP).
The site can alternatively be configured to receive secure AJPS requests. A specific listener port can be specified, or a range of ports can be set in the OPMN configuration file. See "Configuring Web Site Data in OPMN-Managed OC4J Instances" for details on OPMN configuration.
|
Note: In the current release, an OC4J instance supports only one AJP Web site at a time. |
In addition to the default site, new Web sites can be configured on each OC4J instance, as needed. (A Web site cannot listen on more than one protocol.) Reasons for creating a new Web site might include:
Separate management and general Web access
By default, the Application Server Control Console application is accessed via the /em context through the default Web site. However, you can create a new Web site specifically for the Application Server Control Console application to separate management access from general application access, if desired.
Utilizing secure and nonsecure Web sites
You can configure the default Web site to utilize SSL to create secure connections, or can create an additional site and bind it to Web applications that require a secure connection.
See "Creating a New Web Site in OC4J" for instructions on creating and configuring additional Web sites.
The protocoal and listener ports used by a Web site are configured differently in standalone OC4J and Oracle Application Server environments, as these topics describe:
In a standalone OC4J installation, the protocol and listener ports used by a Web site must be explicitly defined in the corresponding *-web-site.xml configuration file. See "Creating the Web Site Configuration File" for a overview of these files.
The default Web site is configured to listen for requests received via the HTTP protocol on port 8888 by default.
In an Oracle Application Server installation, in which Oracle Process Manager and Notification Server (OPMN) is used to manage OC4J instances, OPMN can be used to manage Web site protocol and port configuration efficiently.
When OPMN is started, it selects a port value starting at the bottom of the specified range and increments the value by 1 until a free port is found. Allowing OPMN to select from a range of ports in this manner avoids potential conflicts among OC4J processes.
You can change the OC4J port ranges either through the Application Server Control Console or manually, in the opmn.xml file, as the following topics describe:
To change port ranges in the Application Server Control Console:
From the Cluster Topology page, click Runtime Ports.
Click the Configure Port icon for the port you want to change.
In the Ports section of the Server Properties page, change the port range for the port you want to change.
Click Apply.
Navigate to the Cluster Topology page, select the OC4J instance that you modified, and click Restart.
Click Yes on the confirmation page.
In this model, the protocol a Web site will use is specified within a <port> element defined for the Web site in opmn.xml, the OPMN configuration file. A range of listener ports the Web site will use can also be specified within this element.
|
Note: Theopmnctl command-line tool provides a command that you can use to update the <port> element for a specific Web site defined in the opmn.xml file for an OC4J instance.
See "Configuring Web Sites with opmnctl" for usage details. |
The protocol and port values specified in opmn.xml override any corresponding values set in the corresponding Web site configuration file. Using OPMN to manage Web site protocol and port settings is not required in an Oracle Application Server environment. You can opt to not set these values in opmn.xml and instead set the values directly in the appropriate Web site configuration file.
The <port> element is defined in the opmn.xml configuration file, which is located in the ORACLE_HOME/opmn/conf directory. The syntax of the element follows:
<port id="webSiteName" protocol="http|https|ajp|ajps" range="startPort-endPort"/>
Table 13-1 describes the attributes of the <port> element.
Table 13-1 Attributes of the <port> Element
| Attribute | Description |
|---|---|
|
|
Required. Defines the name of the Web site, which is the name of the Web site configuration file minus the |
|
protocol |
Optional. Specifies the protocol the Web site will receive requests through. Valid values are:
If either |
|
|
Optional. Specifies the start and end ports for the range of ports available for assignment by OPMN. The default listener port ranges used are:
|
All <port> elements defining connection protocols are set in the <process-type> element defining the OC4J instance. The <process-type> element is a subelement of the <ias-component> element, in which the id attribute equals default_group.
For example, the <port> element in the following example configures the default Web site on the OC4J home instance to listen for AJP requests on ports 12501 through 12600.
<ias-component id="default_group">
<process-type id="home" module-id="OC4J" status="enabled">
...
<port id="default-web-site" protocol="ajp" range="12501-12600"/>
<port id="rmi" range="12401-12500">
<port id="jms" range="12601-12700">
<process-set id="default" numprocs="1"/>
</process-type>
</ias-component>
|
Note: Theopmn.xml file must be reloaded for changes made to take effect. Run the following command on the affected node to reload opmn.xml:
opmnctl reload This command will not affect OPMN-managed components, including Oracle HTTP Server, OC4J, and deployed applications. |
The OPMN command-line tool, opmnctl, provides a config port command which allows you to specify, update or delete a Web site configuration defined in opmn.xml.
The opmnctl tool is installed in the ORACLE_HOME/opmn/bin directory on each node. The tool must be run individually on each node, and will update only the opmn.xml file on that node.
Inserting or Updating Web Site Configuration Data in opnm.xml
The update command sets the specified data in a new or existing <port> element. The syntax is as follows:
opmnctl config port update ias-component=componentName process-type=instanceName portid=webSiteName [range=startPort-endPort] [protocol=<http|https|ajp|ajps>]>
The following command modifies the default Web site for an OC4J instance that is currently configured to listen for HTTP requests to receive and respond to Apache JServ Protocol requests from Oracle HTTP Server.
opmnctl config port update ias-component=default_group process-type=home portid=default-web-site protocol=ajp opmnctl reload
The opmnctl reload command is invoked to reload the updated opmn.xml file into the OC4J runtime.
Deleting Web Site Configuration Data from opnm.xml
The delete command removes the <port> element defined for the specified Web site. The syntax is as follows:
opmnctl config port delete ias-component=componentName process-type=instanceName portid=webSiteName
For example, the following removes the <port> element defined for the default Web site from opmn.xml:
opmnctl config port update ias-component=default_group process-type=home
portid=default-web-site
opmnctl reload
Table 13-2 below describes the options that can be set on the opmnctl config port command line.
Table 13-2 opmnctl config port Options
| Option | Description |
|---|---|
|
|
Set to |
|
|
Set to the identifier of the OC4J instance to update; for example, |
|
|
Set to the name of the Web site, which is the name of the Web site configuration file minus the |
|
|
Specifies the protocol the Web site will receive requests through. Valid only for the
If either |
|
|
Set the start and end ports for the range of ports available for assignment by OPMN. Valid only for the The default port ranges are:
You can specify a single port instead of a range. |
Bringing a new Web site to life in an OC4J instance is essentially a two- or optionally three-step process:
Create the XML configuration file for the Web site within the OC4J installed directory structure.
Add a reference to the new Web site configuration file in server.xml, the OC4J configuration file.
For OPMN-managed OC4J instances, add a <port> element defining the Web site's protocol and port ranges to opmn.xml.
Once these steps are completed, the Web site will be available for binding with applications. The following topics provide details on Web site configuration.
The key information defined in a Web site configuration file includes the following:
The Web context for each application bound to the site, which is appended to the URL used to access the site (for example, /em).
The protocol the site uses. In an OPMN-managed environment, this value will be overridden by the protocol specified in opmn.xml.
The port the site listens on. In an OPMN-managed environment, this value will be overridden by the port range specified in opmn.xml.
The location of the access log file, which tracks user access to the site.
The most straightforward way to create a new configuration file is to make a copy of the default Web site configuration file, default-web-site.xml, which is located in the ORACLE_HOME/j2ee/instance/config directory. Name the file according to the following convention:
webSiteName-web-site.xml
The typical configuration file includes a root <web-site> element containing attributes that specify the following:
host: The host for this Web site, as either a DNS host name or an IP address. If a server has multiple IP addresses, you can use the ALL setting to listen to all the IP addresses.
port: The Web site listener port.
display-name: The for-display name of the Web site.
virtual-hosts: Any additional domains bound to this Web site.
The <web-site> element also typically contains the following subelements:
A <default-web-app> element defining the Web application accessed by default through the Web site. When a single application is bound to the Web site - such as Application Server Control Console - specify the application within this element.
One or more <web-app> sub-elements for each Web module bound to the Web site. These elements are added by OC4J when each application is bound to the Web site; however, they can be added to the file manually if desired. At a minimum, each <web-app> element has the following:
An application attribute to specify the name of the J2EE application to which the Web module belongs (the same as the EAR file name without the .ear extension)
A name attribute to specify the name of the Web module (the same as the WAR file name without the .war extension)
A root attribute to specify the context path on this Web site to which the Web module is to be bound
An <access-log> element specifying the log file to which requests sent to the site are logged
As an example, assume that you will create a configuration file named ascontrol-web-site.xml, which defines a Web site that will be used exclusively to provide management access to Application Server Control Console. The root <web-site> element within this file will contain all of the required configuration data, as follows:
<web-site xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://xmlns.oracle.com/oracleas/schema/
web-site-10_0.xsd" port="1810"
display-name="Application Server Control Web Site">
<default-web-app application="ascontrol" name="ascontrol" access-log="true" />
<access-log path="../log/ascontrol-web-access.log" />
</web-site>
For details on the structure of this element, see the <web-site> element description.
|
Note: If you are creating a Web site exclusively for use by Application Server Control Console, as illustrated in this example, you must also update the Launch Application Server Control link on the OC4J home page, accessed throughORACLE_HOME/j2ee/, with the correct URL. |
The location of every Web site configuration file must be referenced in a <web-site> element in server.xml, the OC4J configuration file located in the J2EE_HOME/config directory. Applications will not be able to bind to the Web site unless this declaration exists in server.xml.
Each <web-site> element specifies the path and file name for the corresponding Web site XML file, as in the following sample server.xml entries:
<application-server ... >
<web-site path="./default-web-site.xml" />
<web-site path="./ascontrol-web-site.xml" />
</application-server>
In this example, the locations of all of the Web site configuration files are relative to the location of server.xml.
|
Note: If OC4J polling is disabled, OC4J must be restarted for changes toserver.xml to take effect. |
In an Oracle Application Server installation, in which Oracle Process Manager and Notification Server (OPMN) is used to manage OC4J instances, OPMN can be used to efficiently manage Web site protocol and port configuration.
Use the opmnctl config port command to add a new <port> element for the Web site to the OC4J instance definition in opmn.xml. The following example sets the protocol (HTTP) and port (1810) for the ascontrol Web site:
opmnctl config port update ias-component="default_group" id="ascontrol-web-site" protocol="http" range="1810"
The example command adds the new <port> element to the OC4J home instance definition in the opmn.xml file on the host machine. This OC4J instance is now configured with two Web sites: the default site and the new ascontrol site.
<ias-component id="default_group">
<process-type id="home" module-id="OC4J" status="enabled">
...
<port id="default-web-site" protocol="ajp" range="12501-12600"/>
<port id="ascontrol-web-site" protocol="http" range="1810"/>
<port id="rmi" range="12401-12500">
<port id="jms" range="12601-12700">
<process-set id="default" numprocs="1"/>
</process-type>
</ias-component>
Sharing a Web application implies the sharing of everything that makes up the application, including sessions, servlet instances, and context values.
A typical use for this mode is to share a Web application between an HTTP site and an HTTPS site on the same context path - essentially binding the application to the two different Web sites. This results in improved performance because only sensitive information is encrypted as needed, rather than requiring that all information in a request be encrypted.
Another benefit is that the cookie, rather than the SSL certificate, is used to track the session. The SSL certificate uses 50 KB to store each certificate when tracking it, which sometimes results in an out-of-memory problem for the session before the session times out. This could possibly make the Web application less secure, but might be necessary to work around issues such as SSL session timeouts not being properly supported in some browsers.
You can set an application as shared by setting the shared attribute of the <web-app> element to true in the *-web-site.xml file defining each Web site to which the application is bound. This attribute is false by default.
For example, the sample petstore application is shared between both the default OC4J Web site, which listens on port 8888, and a new secure Web site listening on port 4443 by adding or modifying the following <web-app> elements in each Web site configuration file. This configuration will enable the application to accept both HTTP and HTTPS connections.
The <web-app> entry in default-web-site.xml follows:
<web-site xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://xmlns.oracle.com/oracleas/schema/
web-site-10_0.xsd" port="8888" display-name="OC4J 10g (10.1.3) HTTP Web Site">
<web-app application="petstore" name="petstore" load-on-startup="true"
root="/petstore" shared="true" access-log="true"/>
<access-log path="../log/http-web-access.log" />
</web-site>
The similar entry in secure-web-site.xml follows:
<web-site xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://xmlns.oracle.com/oracleas/schema/ web-site-10_0.xsd" port="4443" secure ="true" display-name="My Secure Web Site"> <web-app application="petstore" name="petstore" load-on-startup="true" root="/petstore" shared="true" access-log="true/> <access-log path="../log/secure-web-access.log" /> <ssl-config keystore="../../server.keystore" keystore-password="welcome" provider="com.sun.net.ssl.internal.ssl.Provider" /> </web-site>
You can set the cookie domain to a specific value. This causes the domain to be set to the specified value at the time a cookie is created, resulting in a cookie that can be sent by a Web browser to any Web site within the domain.
If the domain is not specified, the browser defaults to the domain of the fully qualified server name, such as site1.acme.com. In this case, the browser would not be able to forward the cookie to site2.acme.com. However, if the cookie domain is explicitly set to acme.com, the cookie could be sent to either server.
Set the cookie-domain attribute in the <session-tracking> element in the J2EE standard orion-web.xml file for the application. The cookie-domain attribute contains the DNS domain with at least two components of the domain name provided. For example:
<session-tracking cookie-domain=".oracle.com" />
OC4J supports Secure Socket Layer (SSL) communication between the client and OC4J using HTTPS and AJPS. You can modify the configuration file for the default Web site to utilize SSL to create secure connections, or can create an additional site and bind it to Web applications requiring a secure connection.
For details on SSL keys and certificates, see the Oracle Containers for J2EE Security Guide.
This section covers the following topics
Specify the appropriate SSL settings under the <web-site> element, as illustrated in the following example.
<web-site xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://xmlns.oracle.com/oracleas/schema/ web-site-10_0.xsd" port="4443" secure="true" display-name="My Secure Web Site"> <access-log path="../log/secure-web-access.log" /> <ssl-config keystore="../../server.keystore" keystore-password="welcome" provider="com.sun.net.ssl.internal.ssl.Provider" /> </web-site>
Note the additions to <web-site>, shown in bold:
Add a secure attribute with the value set to true. Setting secure="true" specifies that the HTTP protocol is to use an SSL socket.
Set the port attribute to an available port. The default for SSL ports is 443; in the example above, the port attribute is set to 4443.
Add the <ssl-config> element. This element is required whenever the secure flag is set to true. This element takes the following attributes and elements:
The optional factory attribute is used to specify the third-party SSLServerSocketFactory implementation to use if the application is not using JSSE.
If the application uses a third-party SSLServerSocketFactory implementation, you can use <property> subelements of <ssl-config> to send parameters to the factory.
|
Note: Thefactory attribute and its parameters are deprecated in OC4J 10g (10.1.3.1.0). |
The keystore and keystore-password attributes specify the directory path and password for the keystore. The specified keystore must contain the certificates of any clients that are authorized to connect to OC4J through HTTPS. The value of keystore can indicate either an absolute or relative directory path and includes the file name.
The optional provider attribute can be used to specify a security provider to use.
By default, the Sun Microsystems implementation - com.sun.net.ssl.internal.ssl.Provider - is used. (Although the example shows the default implementation, it is implicit and does not need to be specified.)
One or more <property> elements containing parameters to pass to the SSLServerSocketFactory. Each element contains a name attribute and a value attribute, enabling you to specify parameters as name and value pairs.
|
Note: Parameters for theSSLServerSocketFactory are deprecated in OC4J 10g (10.1.3.1.0). |
When the Web site configuration file is ready, add a <web-site> element referencing server.xml, the OC4J configuration file located in the J2EE_HOME/config directory. Applications will not be able to bind to the Web site unless this notation exists in server.xml. For example:
<application-server ... >
<web-site path="./default-web-site.xml" />
<web-site path="./mycustom-web-site.xml" />
<web-site path="./secure-web-site.xml" />
</application-server>
When configuration is complete, OC4J listens for SSL HTTP requests on one port and non-SSL HTTP requests on another. You can disable either SSL requests or non-SSL requests by commenting out the appropriate *-web-site.xml in the server.xml configuration file.
<!-- <web-site path="./secure-web-site.xml" /> commented out to remove SSL -->
For more information about elements and attributes of the <web-site>, <web-app>, and <session-tracking> elements, see Oracle Containers for J2EE Servlet Developer's Guide.
You can require that clients be authenticated by the server by setting the needs-client-auth attribute of the <ssl-config> element to true. For example:
<web-site ... secure="true" ... > <ssl-config keystore="../../server.keystore" keystore-password="welcome" needs-client-auth="true" /> </web-site>
This step sets up a mode where OC4J accepts or rejects a client entity for secure communication, depending on its identity. The needs-client-auth attribute instructs OC4J to request the client certificate chain upon connection. If the root certificate of the client is recognized, then the client is accepted.
The keystore specified in the <ssl-config> element must contain the certificates of any clients that are authorized to connect to OC4J through HTTPS.
OC4J supports a client-authentication mode, in which the server explicitly requests authentication from the client before the server will communicate with the client. In this case, the client must have its own certificate. The client authenticates itself by sending a certificate and a certificate chain that ends with a root certificate. OC4J can be configured to accept only root certificates from a specified list in establishing a chain of trust back to the client.
A certificate that OC4J trusts is called a trust point. This is the first certificate that OC4J encounters in the chain from the client that matches one in its own keystore. There are three ways to configure trust:
The client certificate is in the keystore.
One of the intermediate certificate authority certificates in the client's chain is in the keystore.
The root certificate authority certificate in the client's chain is in the keystore.
OC4J verifies that the entire certificate chain up to and including the trust point is valid to prevent any forged certificates.
If you request client authentication with the needs-client-auth attribute, perform the following:
Decide which of the certificates in the client's chain is to be your trust point. Ensure that you either have control of the issue of certificates using this trust point or that you trust the certificate authority as an issuer.
Import the intermediate or root certificate in the server keystore as a trust point for authentication of the client certificate.
If you do not want OC4J to have access to certain trust points, make sure that these trust points are not in the keystore.
Execute the preceding steps to create the client certificate, which includes the intermediate or root certificate installed in the server. If you wish to trust another certificate authority, obtain a certificate from that authority.
Save the certificate in a file on the client.
Provide the certificate on the client initiation of the HTTPS connection.
If the client is a browser, set the certificate in the client browser security area.
If the client is a Java client, you must programmatically present the client certificate and the certificate chain when initiating the HTTPS connection.
A Web site is available by default once it has been configured on an OC4J instance. However, Application Server Control Console provides the ability to stop and start inidividual Web sites through the Administration>J2EE Websites pages. These pages also display the configuration for each Web site, and provide access to the Web modules bound to each site.
|
Note: Because the Application Server Control Console usesascontrol-web-site, you cannot stop it through the user interface. |
Click the Administration link in the Application Server Control Console.
Click the J2EE Websites icon under Administration Tasks>Properties. The Web sites configured on the OC4J instance are listed on the page displayed.
Click the name of the desired Web site.
OC4J provides the ability to generate an access log for each Web site, which records requests submitted by clients to the Web site.
Access logs can be generated as either text-based log files or as Oracle Diagnostic Logging (ODL) files, which are generated in XML format that is viewable through Application Server Control Console. Only one type of access logging may be configured for a Web site.
Access logging is configured for a Web site in the Web site configuration file (*-web-site.xml) using either the <access-log> or <odl-access-log> element. If neither element is included in the configuration file, access logs are not generated for the Web site.
This section covers the following topics:
Text-based access logging is configured through the <access-log> subelement of the root <web-site> element in the corresponding Web site's configuration file (*-web-site.xml).
|
Note: It is important to monitor text-based access log files, as this logging format does not support log rotation. If left unchecked, access-log files will continue to grow and can overrun the disk. |
This <access-log> element has the following attributes:
path: Specifies the path and filename of the access log. This is the only required attribute; specifying it alone will cause access logs to be generated.
The path must be relative to the ORACLE_HOME/j2ee/instance/config directory to enable the log to be viewed through Application Server Control Console, as illustrated by the following entry in default-web-site.xml:
<access-log path="../log/default-web-access.log" />
format: Specifies one or more of several supported variables that result in information being prepended to log entries. Supported variables are $time, $request, $ip, $host, $path, $size, $method, $protocol, $user, $status, $referer, $agent, $cookie, $header, and $mime. Between variables, you can type in any separator characters that you want to appear between values in the log message. The default setting is as follows:
"$ip - $user - [$time] '$request' $status $size"
This default configuration results in log messages such as the following, with the second message wrapping around to a second line:
148.87.1.180 - - [17/Nov/2004:10:23:18 -0800] 'GET / HTTP/1.1' 200 2929 148.87.1.180 - - [17/Nov/2004:10:23:53 -0800] 'GET /webservices/statefulTest HTTP/1.1' 200 301
In this example, the user is null, the time is in brackets (as specified in the format setting), the request is in single quotation marks (as specified), and the status and size in the first message are 200 and 2929, respectively.
split: Specifies how often to begin a new access log. Supported values are none (equivalent to never, which is the default value), hour, day, week, and month. If split is specified, the suffix attribute (documented in the following text) can be used to specify timestamp data to append to the file name.
suffix: Specifies timestamp information to append to the base file name of the logs if the split attribute is specified.
The default suffix value is -yyyy-mm-dd.
As an example, assume the following <access-log> element with split specified, using the default suffix value:
<access-log path="../log/mysite-web-access.log" split="day" />
The log file generated will be named as follows:
mysite-web-access-2004-11-17.log
The format used is that of java.text.SimpleDateFormat, and symbols used in suffix settings are according to the symbology of that class. Characters are case-sensitive, as described in the SimpleDateFormat documentation. For information about SimpleDateFormat and the format symbols it uses, refer to the current Sun Microsystems Javadoc at the following location:
http://java.sun.com/j2se/
The following entry in default-web-site.xml will generate a file named default-web-access.log file:
<web-site> ... <access-log path="../log/default-web-access.log" /> </web-site>
The files will be generated in the following locations, depending on your OC4J installation.
Standalone OC4J:
Log files will be generated in ORACLE_HOME/j2ee/home/log/.
Oracle Application Server:
Files will be generated in an OC4J instance- specific directory named ORACLE_HOME/j2ee/instance/application-deployments/log/instance_default_group_1.
Access log text files can be viewed by clicking the Logs link in the Web-based Application Server Control Console. ODL log files are identified in the Log Files page by the .log extension.
Click the Logs link at the bottom of any Application Server Control Console page.
Expand OC4J.
Expand <instanceName>. The default instance name is home.
In the ODL framework, log files are formatted as XML documents. A key benefit of ODL access logging is that unlike text-based logging, log file rotation is supported.
ODL access logging is configured through the <odl-access-log> subelement of the root <web-site> element in a Web site's configuration file. This element has the following attributes, all of which are required:
path: The path to the directory where the log.xml files for the Web site will be generated.
The path must be relative to the *-web-site.xml configuration file to enable the log files to be viewed through Application Server Control Console.
For easier management, include the name of the Web site in the path.
max-file-size: The maximum size, in kilobytes, that an individual log file is allowed to grow to. When this limit is reached, a new log file is generated.
max-directory-size: Sets the maximum size, in kilobytes, allowed for the log file directory. When this limit is exceeded, log files are purged, beginning with the oldest files.
New files named log.xml are generated within the directory specified in the path attribute until the maximum directory size is reached. Each log file is equal to or less than the maximum size specified in the attributes.
For example, the following entry in default-web-site.xml will cause log.xml files to be generated. It will also set log files to a maximum of 1,000 KB and the directory maximum to 10,000 KB in a /default-web-access directory within ORACLE_HOME/j2ee/home/log/.
<web-site>
...
<odl-access-log path="../log/default-web-access/" max-file-size="1000"
max-directory-size="10000" />
</web-site>
The files will be generated in the following locations, depending on your OC4J installation.
Standalone OC4J:
Log files will be generated in ORACLE_HOME/j2ee/home/log/default-web-access/.
Oracle Application Server:
Files will be generated in an OC4J instance-specific directory named ORACLE_HOME/j2ee/instance/application-deployments/log/instance_default_group_1/default-web-access.
For more information about ODL access logging, see "Managing ODL Log Files".
ODL-formatted log files can be viewed by clicking the Logs link in the Web-based Application Server Control Console, allowing administrators to aggregate and view the logging output generated by all components and applications running within OC4J from one centralized location.
ODL log files are identified in the Log Files page by the .xml extension.
Click the Logs link at the bottom of any Application Server Control Console page.
Expand OC4J.
Expand <instanceName>. In both standalone OC4J and OAS, the default instance name is home.
Expand the Default Web Site node.
Expand Diagnostic Message Logs.
If either the <access-log> or <odl-access-log> element is defined in a Web site configuration file, access logging is not enabled by default for the Web modules within applications bound to the Web site. As of OC4J 10g 10.1.3.1.0, the default value of the access-log attribute of any application-specific <web-app> elements in the configuration file is false.
However, it is possible to enable access logging for a specific module by setting the access-log attribute to true for the module.
It may be desirable to leave access logging disabled in situations where a Web module submits such a massive number of requests that text-based access log files will quickly become bloated. If access-log is set to true in the Web site configuration file or for the module, you can disable access logging for the module by setting its access-log attribute to false.
For example, the following entry in default-web-site.xml disables access logging for the default application's DMS Web component, but enables text-based access logging for the admin_web module:
<web-site ...> <web-app application="default" name="dms0" root="/dmsoc4j" access-log="false" /> <web-app application="default" name="admin_web" root="/adminoc4j" /> <access-log path="../log/http-web-access.log" access-log="true" /> </web-site>
