Skip Headers

Oracle® Containers for J2EE Configuration and Administration Guide 10g Release 3 (10.1.3) Part No. B14432-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 13 Managing Web Sites in OC4J

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:

- What Is a Web Site in OC4J?

- Configuring Web Site Connection Data

- Creating a New Web Site in OC4J

- Configuring a Secure Web Site in OC4J

- Starting/Stopping Web Sites

- Configuring Web Site Access Logging

## What Is a Web Site in OC4J?

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/home/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 (OHS) via the 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.

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.

## Configuring Web Site Connection Data

Key differences exist in how the protocol and listener ports used by a Web site is managed in standalone OC4J versus Oracle Application Server environments.

- Configuring Web Site Data in a Standalone OC4J Installation

- Configuring Web Site Data in OPMN-Managed OC4J Instances

### Configuring Web Site Data in a Standalone OC4J Installation

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.

### Configuring Web Site Data in OPMN-Managed OC4J Instances

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.

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: The `opmnctl` 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.

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.

Note that the protocol and port values specified in `opmn.xml` override any corresponding values set in the corresponding Web site configuration file. Note that 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 is as follows:

    <port id="webSiteName" protocol="http|https|ajp|ajps"  range="startPort-endPort"/>

Table 13-1 below describes the attributes of the `<port>` element.

Table 13-1 Attributes of the <port> Element

Attribute | Description
--- | ---
`id` | Required. Defines the name of the Web site, which is the name of the Web site configuration file minus the `.xml` extension.
protocol | Optional. Specifies the protocol the Web site will receive requests through. Valid values are: `http` `https` `ajp` `ajps` Note that if either `https` or `ajps` is specified, the value of the secure attribute of the root `<web-site>` element in the `*-web-site.xml` configuration file defined for the Web site will be overridden.
`range` | Optional. Specifies the start and end ports for the range of ports available for assignment by OPMN. The default listener port ranges used are: HTTP: `8888-8987` AJP: `12501-12600`

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, where the `id` attribute equals `OC4J`.

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="OC4J">
      <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: The `opmn.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
Note that this command will not affect OPMN-managed components, including OHS, OC4J and deployed applications.

#### Configuring Web Sites with opmnctl

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=OC4J process-type=home
       portid=default-web-site protocol=ajp

    opmnctl reload

Note that 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=OC4J 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
--- | ---
`ias-component` | Set to `OC4J` to update the OC4J configuration in `opmn.xml`.
`process-type` | Set to the identifier of the OC4J instance to update; for example, `home`. This value matches the value of the `id` attribute in the `<process-type>` subelement of `<ias-component>` in `opmn.xml`.
`portid` | Set to the name of the Web site, which is the name of the Web site configuration file minus the `.xml` extension.
`protocol` | Specifies the protocol the Web site will receive requests through. Valid only for the `update` operation. Valid values are: `http` `https` `ajp` `ajps` Note that if either `https` or `ajps` is specified, the value of the secure attribute of the root `<web-site>` element in the `*-web-site.xml` configuration file defined for the Web site will be overridden.
`range` | Set the start and end ports for the range of ports available for assignment by OPMN. Valid only for the `update` operation. The default port ranges are: HTTP: `8888-8987` AJP: `12501-12600` Note that a single port can be specified instead of a range.

## Creating a New Web Site in OC4J

Bringing a new Web site to life in an OC4J instance is essentially a two- or optionally three-step process:

1. Create the XML configuration file for the Web site within the OC4J installed directory structure.

2. Add a reference to the new Web site configuration file in `server.xml`, the OC4J configuration file.

3. 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.

- Creating the Web Site Configuration File

- Referencing the Web Site Configuration File in server.xml

- Defining the Web Site Connection Data in opmn.xml

- Sharing Web Applications Between Web Sites

- Specifying the Cookie Domain

### Creating the Web Site Configuration File

Note: This discussion provides instructions on configuring a Web site using XML configuration files. Web sites can also be created in standalone OC4J installations using the `admin.jar` command-line utility. See "Managing Web Sites" for instructions.

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. Note that 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_HOMEj2ee/home/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:

- `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 that requests sent to the site are logged to

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 shown below:

    <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 path="../log/ascontrol-web-access.log" />
    </web-site>

See the <web-site> element description for details on the structure of this element.

Note: If you are creating a Web site exclusively for use by Application Server Control Console, as illustrated in this example, note that you must also update the Launch Application Server Control link on OC4J home page, accessed via `ORACLE_HOME``/j2ee/`, with the correct URL.

### Referencing the Web Site Configuration File in server.xml

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. Note that 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 to `server.xml` to take effect.

### Defining the Web Site Connection Data in opmn.xml

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="home" 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="OC4J">
      <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 Web Applications Between Web Sites

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 the application is bound to. 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`:

    <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 path="../log/http-web-access.log" />
    </web-site>

The similar entry in `secure-web-site.xml`:

    <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 path="../log/secure-web-access.log" />
      <ssl-config factory="com.evermind.ssl.JSSESSLServerSocketFactory"
        keystore="../../server.keystore" keystore-password="welcome"
        provider="com.sun.net.ssl.internal.ssl.Provider" />
    </web-site>

### Specifying the Cookie Domain

Note that you can optionally 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" />

Note: If the domain is set to `acme.com`, the cookie will not actually be sent to `acme.com`. In this case, `acme.com` must be redirected at the Web server level to `www.acme.com` to enable cookies to be shared among all subdomains of `acme.com`. The domain cookies will be redirected to should have at least two dots for `org/com/edu/mil/net` domains and three for other domains; for example, `www.acme.com`.

## Configuring a Secure Web Site in OC4J

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

- Creating the Secure Web Site Configuration File

Note: This discussion provides instructions on configuring a secure Web site using XML configuration files. Secure Web sites can also be created using the `admin.jar` command -line utility. See "Managing Web Sites" for instructions on creating Web sites using `admin.jar`.

### Creating the Secure Web Site Configuration File

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 factory="com.evermind.ssl.JSSESSLServerSocketFactory"
        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 `SSLSecureSocketFactory` implementation to use if the application is not using JSSE.

    The Oracle implementation - `com.evermind.ssl.JSSESSLServerSocketFactory` - is used by default. (Note that although the default implementation is shown in the example, it is implicit and does not need to be specified.)

    If the application uses a third-party SSLServerSocketFactory implementation, you can use `<property>` subelements of `<ssl-config>` to send parameters to the factory.

  - 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. (Note that although the default implementation is shown in the example, it is implicit and does not need to be specified.)

  - One or more <property> elements containing parameters to pass to the `SSLSecureSocketFactory`. Each element contains a `name` attribute and a `value` attribute, enabling you to specify parameters as name/value pairs.

When the Web site configuration file is ready, add a `<web-site>` element referencing it to `server.xml`, the OC4J configuration file located in the `J2EE_HOME``/config` directory. Note that 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 the XML Appendix in the Oracle Containers for J2EE Servlet Developer's Guide.

#### Requiring Client Authentication

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 factory="com.evermind.ssl.JSSESSLServerSocketFactory"   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.

#### Requesting Client Authentication with OC4J

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:

1. 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.

2. Import the intermediate or root certificate in the server keystore as a trust point for authentication of the client certificate.

3. If you do not want OC4J to have access to certain trust points, make sure that these trust points are not in the keystore.

4. 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.

5. Save the certificate in a file on the client.

6. Provide the certificate on the client initiation of the HTTPS connection.

   1. If the client is a browser, set the certificate in the client browser security area.

   2. If the client is a Java client, you must programmatically present the client certificate and the certificate chain when initiating the HTTPS connection.

## Starting/Stopping Web Sites

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: Note that the `ascontrol-web-site`, used by Application Server Control Console, cannot be stopped via the user interface.

1. Click the Administration link in the Application Server Control Console.

2. Click the J2EE Websites icon under Administration Tasks>Properties. The Web sites configured on the OC4J server instance are listed on the page displayed.

3. Click the name of the desired Web site.

## Configuring Web Site Access Logging

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:

- Configuring Text-Based Access Logging

- Viewing Text Access Log Files

- Configuring ODL Access Logging

- Viewing ODL Access Log Files

- Enabling/Disabling Access Logging for a Web Module/Application

### Configuring Text-Based Access Logging

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 `j2ee/home/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-quotes (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), `"hour"`, `"day"`, `"week"`, and `"month"`. Note that if `split` is specified, the `suffix` attribute (documented below) 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` setting 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_name``/application-deployments/log/``instance_name``_default_group_1/`.

### Viewing Text Access Log Files

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.

1. Click the Logs link at the bottom of any Application Server Control Console page.

2. Expand OC4J.

3. Expand <instanceName>. The default instance name is `home`.

### Configuring ODL Access Logging

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 1000 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_name``/application-deployments/log/``instance_name``_default_group_1/default-web-access`.

### Viewing ODL Access 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.

1. Click the Logs link at the bottom of any Application Server Control Console page.

2. Expand OC4J.

3. Expand <instanceName>. In both standalone OC4J and OAS, the default instance name is `home`.

4. Expand the Default Web Site node.

5. Expand Diagnostic Message Logs.

### Enabling/Disabling Access Logging for a Web Module/Application

If either the `<access-log>` or `<odl-access-log>` element is defined in a Web site configuration file, access logging is enabled by default for all Web modules within applications bound to the Web site.

However, it is possible to disable access logging for a specific module by setting the `access-log` attribute of the application-specific `<web-app>` element in the configuration file to `false`. This may be desirable in situations where a Web module submits such a massive number of requests that text-based access log files will quickly become bloated.

For example, the following entry in `default-web-site.xml` disables access logging for the `default` application's DMS Web component, but leaves text-based access logging for the `admin_web` module enabled:

    <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" />
    </web-site>