Skip Headers

Oracle® HTTP Server Administrator's Guide 10g Release 3 (10.1.3) B25211-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 8 Configuring and Using mod_oradav

This chapter describes distributed authoring and versioning concepts, and explains how to configure and use the `mod_oradav` module. The `mod_oradav` module enables you to use OraDAV to access content in an Oracle database from a Web browser or a WebDAV client.

Topics discussed are:

- OraDAV Concepts

- OraDAV Architecture

- OraDAV Users

- OraDAV Usage Model

- OraDAV Configuration Parameters

- DAV Directives

- WebDAV Security Considerations

- OraDAV Performance Considerations

- mod_oradav Usage Notes

## 8.1 OraDAV Concepts

The term OraDAV refers to the capabilities available through the `mod_oradav` module. The `mod_oradav` module is an extended implementation of `mod_dav`, which is an implementation of the WebDAV specification. This section explains the following concepts:

- WebDAV

- mod_dav

- mod_oradav

- OraDAV

### 8.1.1 WebDAV

WebDAV is a protocol extension to HTTP 1.1 that supports distributed authoring and versioning. With WebDAV, the Internet becomes a transparent read and write medium, where content can be checked out, edited, and checked in to a URL address.

WebDAV enables collaboration among authors building Web sites. WebDAV also serves as universal read and write access protocol to arbitrary hierarchies of content (not necessarily Web sites). With WebDAV, you can save content to a URL provided by an Internet Service Provider (ISP), and then be able to access and optionally change that content from various devices.

WebDAV was initiated as an Internet Engineering Task Force (IETF) standard. The first phase of WebDAV is specified in RFC 2518, which provides the basic primitives for managing hierarchies of information, locking, reading, writing, and querying properties of a WebDAV document. Subsequent work on WebDAV is ongoing and is focusing on completing issues relating to content management over the Web. This includes WebDAV authentication and authorization (access controls), versioning, bindings, ordered collections, and querying (DAV Advanced Searching and Locating).

Microsoft Web folders is a WebDAV client on Windows 2000 and later versions (using Internet Explorer 5.0 and higher). Office 2000 and Office XP applications and the IIS server support WebDAV, meaning that you can start a Microsoft Office application and specify a URL, edit the content, and save it back to the URL from which it was retrieved. WebDAV also has Java clients (such as DAV Explorer), open source tools (such as Cadaver and Sitecopy), and Apple GUI tools (such as Goliath).

Note: When a WebDAV client first connects to Oracle HTTP Server, you must use the full `ServerName` string (as specified in the `httpd.conf` file) in the URL for the connection. Do not use an abbreviated form of the server name. For example, if the `ServerName` value is `server1.acme.com`, connect to Oracle HTTP Server using the string `http://server1.acme.com:7778`, not an abbreviated form such as `http://server1:7778`. If you use an abbreviated form, the connection might succeed, but `COPY` and `MOVE` operations will fail to execute and generate `BAD_GATEWAY` errors.

### 8.1.2 mod_dav

`mod_dav` is the Apache Software Foundation native implementation of the WebDAV specification.

### 8.1.3 mod_oradav

`mod_oradav` is the Oracle module (an OCI application written in C) that is an extended implementation of `mod_dav`, and is integrated with Oracle HTTP Server. `mod_oradav` performs read/write activity to local files and to Oracle databases. Oracle databases must have an OraDAV driver (a stored procedure package) that `mod_oradav` calls to map WebDAV activity to database activity. Essentially, `mod_oradav` enables WebDAV clients to connect to an Oracle database, read and write content, and query and lock documents in various schemas.

You can configure `mod_oradav` to use an Oracle database using standard Oracle HTTP Server directives. `mod_oradav` can immediately leverage other module code (such as mime_magic) in order to perform content management tasks. Most WebDAV processing activity involves streaming content to and from a content provider; and `mod_oradav` uses OCI streaming logic directly within Oracle HTTP Server.

### 8.1.4 OraDAV

OraDAV refers to the whole set of capabilities that are available through `mod_oradav` to Oracle Application Server users. Some OraDAV-specific terms include:

- Apache OraDAV: Code in the Apache HTTP server that supports file-based DAV access and makes calls to Oracle.

- OraDAV driver API: Set of stored procedure calls that are used by the OraDAV driver to manage content in an Oracle database, providing support for the following WebDAV functions over the Internet: reading and writing documents, locking and unlocking documents, managing (creating, populating, deleting) hierarchies of information, retrieving properties associated with documents, and associating properties with specific documents.

- OraDAV driver: Stored procedure implementation of the OraDAV driver API that executes in Oracle and manages a repository.

## 8.2 OraDAV Architecture

OraDAV fits into an architecture in which `mod_oradav`, within Oracle HTTP Server, provides access to content in one or more schemas in one or more Oracle databases.

A simple form of the architecture is illustrated in Figure 8-1.

Figure 8-1 OraDAV Architecture

Description of "Figure 8-1 OraDAV Architecture"

Figure 8-1 shows a WebDAV client, such as Microsoft Web folders, passing HTTP requests to Oracle HTTP Server. If the request is for content stored in the file system (not in an Oracle database), `mod_oradav` handles the access. If the request is for content stored in an Oracle database, the OraDAV API handles the access.

The OraDAV API provides capabilities that are equivalent to using `mod_oradav` running with a file system. The following HTTP methods are supported by the OraDAV API:

- `COPY`

- `DELETE`

- `MOVE`

- `MKCOL`

- `GET`

- `HEAD`

- `LOCK`

- `PROPFIND`

- `PROPPATCH`

- `PUT`

- `UNLOCK`

The OraDAV API supports shared and exclusive locking, retrieving basic DAV properties, and defining and retrieving server-defined live properties or client-defined dead properties. Set-based operations such as `COPY`, `MOVE`, `DELETE` can be done completely by a single call to an OraDAV driver.

## 8.3 OraDAV Users

The primary direct users of OraDAV are Oracle HTTP Server administrators and database administrators (DBAs) of Oracle databases. End users interact only indirectly with OraDAV through Web browsers or WebDAV client tools.

OraDAV administration involves tasks for a Web master and for a DBA:

- The Web master needs to know how to start and stop Oracle HTTP Server, and how to configure Oracle HTTP Server to direct URL traffic to an OraDAV driver.

- The DBA needs to know how to set up client connectivity to an Oracle database from the system running Oracle HTTP Server, to install and administer the OraDAV driver, and perhaps to tune the content managed by the driver based on physical storage characteristics.

## 8.4 OraDAV Usage Model

OraDAV usage can involve any combination of the following activities:

- Browsing: Read-only activity which uses WebDAV to access content in an Oracle database. Its usage model is that of a typical read-only Web site.

- Restructuring: Deleting, moving, and copying content. Restructuring is usually done infrequently by a restricted set of individuals who have write access to the WebDAV content. Restructuring has the same limitations and complications that one encounters when restructuring a file directory. In some cases, this directory hierarchy is owned and managed by one user. If the directory is shared, the client doing restructuring is given sole access to the hierarchy through WebDAV exclusive locks.

- Editing: Modifying one or a small subset of resources in a hierarchy. Properly designed WebDAV clients take out shared or exclusive locks on such resources to coordinate these activities.

- Property Management: Associating properties and attributes (for example, author) with documents for ease of lookup and for categorization. WebDAV clients assign properties to documents using the `PROPPATCH` directive and retrieve properties using the `PROPFIND` directive.

## 8.5 OraDAV Configuration Parameters

You configure OraDAV mainly through parameters in the `httpd.conf` file, which is used by an Oracle HTTP Server instance when it is initializing. Some configuration parameters are required for all OraDAV drivers, and others are driver-specific.

When Oracle Application Server is installed, all required OraDAV parameters are set with values that are designed to enable Oracle database content to be accessed through a Web browser or WebDAV client. If the default values do not meet your needs, you can later modify the values for required parameters and specify values for optional parameters. The parameters used in `httpd.conf` to support OraDAV configuration start with `DAV` and `DAVParam`. These parameters are specified within a <`Location`> container directive, and they provide:

- A way of configuring how Oracle HTTP Server connects to the database.

- Coarse controls on OraDAV behavior.

The `DAV` parameter indicates that a URL location is DAV-enabled. The `DAV` keyword is followed by one of the following values:

- `On`, which indicates that `mod_oradav` is to use the local file system for content

- `Oracle`, which indicates that `mod_oradav` is to use OraDAV for all content

`DAVParam` parameters are used to specify name-value pairs. The required pairs are those that enable Oracle HTTP Server to connect to an Oracle database. These include the names `OraService`, `OraUser`, and `OraPassword` or `OraAltPassword`.

Example 8-1 shows a configuration for accessing files on the local system. It specifies that the directory `myfiles` under the Web server documents directory (`htdocs` by default) is to be DAV-enabled, along with all directories under `myfiles` in the hierarchy. Note that there must not be any symlinks defined on `myfiles` or any directory under it in the hierarchy.

Example 8-1 Configuration Parameters: File System Access

    <Location /myfiles>
      DAV On
    </Location>

Example 8-2 shows a configuration for accessing content through Oracle Application Server Portal. After OracleAS Portal has been installed in Oracle Application Server, the Oracle HTTP Server configuration file should be populated with a <`Location`> container directive which points to the OracleAS Portal schema. In this example, the location `/portal` will be OraDAV-enabled and will (once populated with the correct values) connect to the OracleAS Portal schema so that users can use WebDAV clients to access OracleAS Portal data.

Example 8-2 Configuration Parameters: Portal Access

    <Location /portal>
      DAV Oracle
      DAVParam ORACONNECT dbhost:dbport:dbsid
      DAVParam ORAUSER portal_schema
      DAVParam ORAPASSWORD portal_schema_password
      DAVParam ORAPACKAGENAME portal_schema.wwdav_api_driver
    </Location>

Each OraDAV driver can use the `DAVParam` mechanism to create its own driver-specific settings. All `DAVParam` name-value pairs are passed to the OraDAV driver. In addition to the OraDAV parameters, you should consider whether to specify certain DAV parameters, such as DAVDepthInfinity.

See Also: "DAV Directives"

Table 8-1 lists each OraDAV parameter, whether it is required or optional, and its default value. ORAGetSource applies only to file system access; the other parameters apply only to OracleAS Portal driver and other (non-file system) access.

Table 8-1 OraDAV Parameters

Name | Required/Optional | Default Value
--- | --- | ---
ORAAllowIndexDetails | Optional | `FALSE`
ORAAltPassword | Required. Either ORAPassword or ORAAltPassword must be specified, but not both. | (none)
ORACacheDirectory | Optional | (none)
ORACacheMaxResourceSize | Optional | (none)
ORACachePrunePercent | Optional | 25
ORACacheTotalSize | Optional. ORACacheTotalSize is required if ORACacheDirectory is used; otherwise, do not specify the parameter. | (none)
ORAConnect | Required. ORAService, ORAConnect, or ORAConnectSN must be specified, but no more than one. | (none)
ORAConnectSN | Required. ORAService, ORAConnect, or ORAConnectSN must be specified, but no more than one. | (none)
ORAContainerName | Required | (none)
ORAException | Optional | `NORAISE`
ORAGetSource | Optional | (none)
ORALockExpirationPad | Optional | 0 (seconds)
ORAPackageName | Optional | `ORDSYS.DAV_API_DRIVER`
ORAPassword | Required. Either ORAPassword or ORAAltPassword must be specified, but not both. | (none)
ORARootPrefix | Optional | (none)
ORAService | Required. ORAService, ORAConnect, or ORAConnectSN must be specified, but no more than one. | (none)
ORATraceEvents | Optional | (none)
ORATraceLevel | Optional | 0
ORAUser | Required | (none)

Note: All OraDAV parameters are passed from Oracle HTTP Server to the routines in the `ORAPackageName` package as part of the `context` parameter. Keys are uppercase in Oracle HTTP Server, such as `ORAUSER`, but the values, such as `scott`, are not.

### 8.5.1 ORAAllowIndexDetails

In an Oracle HTTP Server environment that is not OraDAV-enabled, `mod_dav` itself does not respond to HTTP `GET` requests. Instead, normal Oracle HTTP Server mechanisms are used to respond to `GET` requests. However, when all your content is in an Oracle database, normal Oracle HTTP Server mechanisms cannot be used to respond to `GET` requests, and thus OraDAV must respond to `GET` requests.

The `ORAAllowIndexDetails` parameter controls how OraDAV responds when a `GET` request is performed on a DAV collection and no `index.html` file is found in that collection (directory). In a typical Oracle HTTP Server environment, a separate module takes control, automatically generating and returning to the client HTML that represents an "index" of the resources (files) in that collection.

An OraDAV-enabled Oracle HTTP Server performs similar actions when responding to a `GET` request on a collection. A Description column (containing links to more detailed information about each resource) is included in the generated index when `ORAAllowIndexDetails` is set to `TRUE`.

The default is `FALSE`, in which case no Description column appears in the generated index, and if `?details` is used in a URL, it is ignored and the URL contents are returned.

Category | Value
--- | ---
Applies to | Portal driver and other (non-file system) access
Required/Optional | Optional
Values | `TRUE`/`FALSE`
Default | `FALSE`

### 8.5.2 ORAAltPassword

Specifies the password associated with the user specified by the `ORAUser` parameter, but the password is a base-64 encoded character string. The `ORAAltPassword` parameter provides an alternative if you do not want the password to appear in unencoded plain text in that parameter.

Category | Value
--- | ---
Applies to | Portal driver and other (non-file system) access
Required/Optional | Required, unless ORAPassword is specified
Values | (character string)
Default | (none)

If the ORAPassword parameter is not specified, the `ORAAltPassword` parameter is used for the password.

### 8.5.3 ORACacheDirectory

Specifies the directory to use for disk caching operations. If you do not use this parameter, disk caching is not performed for OraDAV operations.

Category | Value
--- | ---
Applies to | Portal driver and other (non-file system) access
Required/Optional | Optional
Values | (character string)
Default | (none)

The specified directory must exist and be readable by Oracle HTTP Server, but cannot be visible to normal `GET` requests. (If the directory is visible to normal `GET` requests, security measures could be bypassed by users accessing the cache directory.)

The directory should not be an NFS-mounted directory, because most UNIX locking mechanisms caution against this. The directory should be located on a file system that supports a "last accessed" time. On Windows systems, this means using NTFS (not FAT) formatted partitions.

Do not use the cache directory for anything other than caching. Any files in the cache directory are subject to deletion.

If you use the `ORACacheDirectory` parameter, you must also use the ORACacheTotalSize parameter.

See Also: "Using Disk Caching with OraDAV"

### 8.5.4 ORACacheMaxResourceSize

Specifies a maximum cacheable resource size for disk caching operations.

Category | Value
--- | ---
Applies to | Portal driver and other (non-file system) access
Required/Optional | Optional
Values | (integer, with optional unit character string)
Default | (none)

Example 8-3 shows how to set ORACacheMaxResourceSize.

Example 8-3 ORACacheMaxResourceSize Parameter

    DAVParam ORACacheMaxResourceSize 1024KB

The setting in Example 8-3 prevents OraDAV from caching any resource larger than one megabyte. The goal is to give Web masters the ability to prevent large media files from dominating the cache. However, be aware that the performance benefit from caching a large file is greater than from caching a small file.

You can specify KB (for kilobytes) or MB (for megabytes) after an integer. If you do not specify a unit after the integer, the default unit is bytes.

See Also: "Using Disk Caching with OraDAV"

### 8.5.5 ORACachePrunePercent

Specifies the percentage of disk cache usage to be freed up when the cache is full. When the disk cache is full, the oldest files in the cache are deleted (pruned) until the cache disk usage is reduced by the `ORACachePrunePercent` value.

Category | Value
--- | ---
Applies to | Portal driver and other (non-file system) access
Required/Optional | Optional
Values | integer (1 to 100)
Default | 25

See Also: "Using Disk Caching with OraDAV"

### 8.5.6 ORACacheTotalSize

Specifies the size of the cache to use for disk caching operations.

Category | Value
--- | ---
Applies to | Portal driver and other (non-file system) access
Required/Optional | Optional, unless ORACacheDirectory is specified
Values | (integer, with optional unit character string, GB or MB) Maximum value is 4GB.
Default | (none)

You can specify MB (for megabytes) or GB (for gigabytes) after an integer, as shown in Example 8-4. If you do not specify a unit after the integer, the default unit is bytes.

Example 8-4 ORACacheTotalSize Parameter

    DAVParam ORACacheTotalSize 1GB

If you use the ORACacheDirectory parameter, you must also use the `ORACacheTotalSize` parameter.

The `ORACacheTotalSize` value should be large enough to hold either a significant fraction of your Web site, or all of your most frequently accessed files plus 25 percent more space. If the value is too small, overall performance degrades because of the extra work of writing BLOB data to the file system and quickly deleting files to make room for newer cache requests.

The actual space utilized by the disk cache might sometimes exceed the `ORACacheTotalSize` value, possibly by as much as the ORACacheMaxResourceSize value. You should also be aware of file system block size issues that could cause the cache to use more disk space than the `ORACacheTotalSize` value.

See Also: "Using Disk Caching with OraDAV"

### 8.5.7 ORAConnect

Specifies the Oracle database to which to connect. The value must be in the following format:

    database-host:database-port:database-sid

Example 8-5 shows how to use the `ORAConnect` parameter.

Category | Value
--- | ---
Applies to | Portal driver and other (non-file system) access
Required/Optional | Required, unless ORAService or ORAConnectSN is specified
Values | (character string)
Default | (none)

Example 8-5 ORAConnect Parameter

    DAVParam ORAConnect my-pc.acme.com:1521:mysid

The `ORAConnect` parameter lets you connect to a database that is not included in the `tnsnames.ora` file.

You must specify one, and no more than one, of the following parameters: `ORAConnect`, ORAService, or ORAConnectSN.

### 8.5.8 ORAConnectSN

Specifies the Oracle database to which to connect. The value must be in the following format:

    database-host:database-port:database-service-name

Category | Value
--- | ---
Applies to | Portal driver and other (non-file system) access
Required/Optional | Required, unless ORAService or ORAConnect is specified
Values | (character string)
Default | (none)

The `ORAConnectSN` parameter lets you connect to a database that is not included in the `tnsnames.ora` file, as shown in Example 8-6.

Example 8-6 ORAConnectSN Parameter

    DAVParam ORAConnectSN my-pc.acme.com:1521:myservice

You must specify one, and no more than one, of the following parameters: ORAService, ORAConnect, or `ORAConnectSN`.

### 8.5.9 ORAContainerName

Within the schema specified by the ORAUser parameter, there must exist a container. The `ORAContainerName` parameter specifies the name of the container to use for the location.

Category | Value
--- | ---
Applies to | Portal driver and other (non-file system) access
Required/Optional | Required
Values | (any valid character string, up to 20 characters)
Default | (none)

### 8.5.10 ORAException

Writes PS/SQL stack dumps into the Oracle HTTP Server log file, error_log, in the event of an exception in the PL/SQL package.

Category | Value
--- | ---
Applies to | Portal driver and other (non-file system) access
Required/Optional | Optional
Values | `NORAISE` or `RAISE`
Default | `NORAISE`

Caution: Use this parameter for debugging problems with PL/SQL packages. However, note that it can use a large amount of disk space and can slow the performance of your system.

### 8.5.11 ORAGetSource

Applies only to file system access. It specifies one or more file extensions to identify types of files that are not to be executed, but rather opened for editing. Include periods (.) with the file extension and use a comma to separate file extensions. For example:

    ".htm, .html, .jsp1, .jsp2"

Category | Value
--- | ---
Applies to | File system access
Required/Optional | Optional
Values | (character string in double quotation marks)
Default | (none)

The `ORAGetSource` parameter lets you open for editing files that are usually executed as a result of a `GET` operation.

Note: Because `.jsp` and `.sqljsp` files are by default opened for editing, you do not need to specify them with the `ORAGetSource` parameter.

### 8.5.12 ORALockExpirationPad

Intended to be used in high-latency network environments, to adjust for the "refresh lock" behavior in Microsoft Office. Microsoft Office attempts to refresh locks on DAV resources just before the lock is set to expire. However, if there is network congestion between the Microsoft Office client and the DAV server, the refresh request might arrive too late, that is, after the lock has expired.

OraDAV periodically looks for locks on resources that have expired and deletes those locks. The `ORALockExpirationPad` parameter can be used to provide some additional ("pad") time between when a lock expires and when that lock is deleted. For example, if `ORALockExpirationPad` is set to 120, OraDAV does not actually delete locks until at least two minutes after the expiration time.

Category | Value
--- | ---
Applies to | Portal driver and other (non-file system) access
Required/Optional | Optional
Values | (number of seconds)
Default | 0

### 8.5.13 ORAPackageName

Identifies the OraDAV driver implementation that is to be called when issuing OraDAV commands. The default is the OraDAV driver, which is the `ORDSYS.DAV_API_DRIVER` package.

Category | Value
--- | ---
Applies to | Portal driver and other (non-file system) access
Required/Optional | Required
Values | (character string)
Default | `ORDSYS.DAV_API_DRIVER`

### 8.5.14 ORAPassword

Specifies the password associated with the user specified by the `ORAUser` parameter.

Category | Value
--- | ---
Applies to | Portal driver and other (non-file system) access
Required/Optional | Required, unless ORAAltPassword is specified
Values | (character string)
Default | (none)

If you do not want to specify the password as an unencoded text string with the `ORAPassword` parameter, you can specify the password as a base-64 encoded string with the ORAAltPassword parameter.

### 8.5.15 ORARootPrefix

Specifies the directory within the database repository to use as the root. If this parameter is specified, WebDAV clients see this directory as the `root` and are not be able to see the repository directories that lead up to it.

Category | Value
--- | ---
Applies to | Portal driver and other (non-file system) access
Required/Optional | Optional
Values | (character string)
Default | (none)

In Example 8-7, assume that the database repository contains the directory `/first/second/third/fourth`, and that `ORARootPrefix` is defined as follows (do not include a trailing slash (/) in the value):

Example 8-7 ORARootPrefix Parameter

    DAVParam ORARootPrefix /first/second

In this case, WebDAV clients will see the `/third` directory and be able to navigate to the `/third/fourth` directory, but will not be able to see or navigate to the `/first` or `/first/second` directories.

### 8.5.16 ORAService

Specifies the Oracle database to which to connect. The specified value must match a SID value in the `tnsnames.ora` file as shown in Example 8-8.

Example 8-8 ORAService Parameter

    DAVParam ORAService mydbsid.mydomain.com

To connect to a database that is not included in the `tnsnames.ora` file, use the ORAConnect parameter. You must specify one, and no more than one, of the following parameters: `ORAService`, ORAConnect, or ORAConnectSN.

Category | Value
--- | ---
Applies to | Portal driver and other (non-file system) access
Required/Optional | Required, unless ORAConnect or ORAConnectSN is specified
Values | (character string matching an entry in the `tnsnames.ora` file)
Default | (none)

### 8.5.17 ORATraceEvents

Specifies types of events to be recorded in the Apache error log for debugging.

Category | Value
--- | ---
Applies to | Portal driver and other (non-file system) access
Required/Optional | Optional
Values | One of the following character strings: `getsource`: Traces GET activity against the file system. `hreftoutf8`: Traces the HREF conversion from the native character set to UTF-8. `request`: Traces DAV requests, responses, and status values handled by mod_oradav.
Default | (none)

Caution: Although this parameter is useful for debugging purposes, it can use a large amount of disk space and can slow the performance of your system.

### 8.5.18 ORATraceLevel

Specifies the level of debugging (trace statements) that will be entered in the Apache error log. The lowest level is 0 (the default), which performs no tracing; the highest level is 4, which performs maximum tracing.

Category | Value
--- | ---
Applies to | Portal driver and other (non-file system) access
Required/Optional | Optional
Values | integer (0 to 4)
Default | 0

The higher the number you set, the more information is written to the error log file.

Caution: Although setting this parameter to a high number is useful for debugging purposes, it can use a large amount of disk space and can slow the performance of your system.

### 8.5.19 ORAUser

Specifies the database user (schema) to use when connecting to the service specified by the `ORAService` parameter.

This user must have the following privileges:

- `CONNECT`

- `RESOURCE`

- `CREATE TABLESPACE`

- `DROP TABLESPACE`

- `CREATE ANY TRIGGER`

  Category | Value
  --- | ---
  Applies to | Portal driver and other (non-file system) access
  Required/Optional | Required
  Values | (character string)
  Default | (none)

## 8.6 DAV Directives

This section describes the following DAV directives that you can set in the `httpd.conf` file:

- DAVDepthInfinity

- DAVLockDB

- DAVMinTimeout

- DAVOraNLS

- DAVOraReadOnly

- Limit

- LimitExcept

- LimitXMLRequestBody

Some of the material in this section is taken or adapted from material written by Greg Stein (`gstein@lyra.org`) and available at the following URL:

`http://www.webdav.org/mod_dav/install.html`

### 8.6.1 DAVDepthInfinity

A `PROPFIND` request with a `Depth:` `Infinity` header can impose a large burden on the server. These kinds of requests could "walk" the entire repository, returning information about each resource found. `mod_dav` builds the response in memory, so these types of requests can consume a lot of memory. (The memory is released at the end of the request, but the peak memory usage can be high.)

To prevent these types of requests, the `DAVDepthInfinity` directive is provided. It is a simple on/off directive, which can be used on a per-server, per-directory or location basis. If the value is set to `Off`, these types of requests are not allowed. A value of `On` (that is, allowing depth infinity requests) makes it easier for denial of service attacks to occur. However, some clients, such as `sitecopy`, require a `DAVDepthInfinity` value of `On`.

Note: The WebDAV Working Group has stated that it is acceptable for DAV servers to refuse these kinds of requests. Properly written client software should not issue such requests.

### 8.6.2 DAVLockDB

Creates a DAV lock database. To create the DAV lock database, add a `DAVLockDB` directive at the top level of the configuration file (that is, outside a `<Directory>` or `<Location>` container directive). The `DAVLockDB` directive should specify the name of a file that `mod_dav` creates. The directory in which the file is to be created must exist, and Oracle HTTP Server process must have write permission to it.

Note: The directory should not be on an NFS-mounted partition. `mod_dav` uses `flock/fcntl` to manage access to the database. Some operating systems cannot use these operations on an NFS-mounted partition.

In Example 8-9, the DAV lock database is stored in the `ORACLE_HOME``/Apache/var` directory, which must be writable by Oracle HTTP Server process. When `mod_dav` creates the file, it is named `DAVLock`. (Actually, `mod_dav` creates one or more files using this file name plus an extension).

Example 8-9 DAVLockDB Directive

    DAVLockDB ORACLE_HOME/Apache/var/DAVLock

The `DAVLockDB` directive can appear outside any container or within a `<VirtualHost>` specification. It only needs to appear once, and a file extension should not be supplied.

### 8.6.3 DAVMinTimeout

Specifies the minimum lifetime of a lock, in seconds. If a client requests a lock timeout less than the `DAVMinTimeout` value, then the `DAVMinTimeout` value is used and returned instead. For example, Microsoft's Web Folders defaults to a lock timeout of 2 minutes (120 seconds); however, you might decide to specify 10 minutes (600 seconds) instead, to reduce network traffic and the chance that the client might lose a lock due to network latency.

The `DAVMinTimeout` directive is optional, and may be used on a per-server or per-directory or location basis. The `DAVMinTimeout` directive takes a single positive integer. Because this value represents a minimum allowed, setting it to zero (0) disables this feature. The default value for `DAVMinTimeout` is zero.

### 8.6.4 DAVOraNLS

Provides globalization support for access to the local file systems. This directive specifies whether or not the file names in the file system need to go through conversion using the `NLS_LANG` setting. A value of `Off`, the default, means that no conversion is needed. A value of `On` means that the character set for the file system provides for conversion of all possible characters in client requests.

See Also: "Globalization Support Considerations with OraDAV"

### 8.6.5 DAVOraReadOnly

Specifies whether or not WebDAV should be used in a read-only mode by WebDAV clients. A value of `Off`, the default, means that WebDAV clients function normally. A value of `On` prevents WebDAV clients from performing write operations while using WebDAV; however, it does allow read-only activity by Web browsers and WebDAV clients.

### 8.6.6 Limit

The `DAV` and `DAVLockDB` directives are the only two configuration changes necessary to operate a DAV server. However, it is usually best to secure the site to be writable only by specific authorized users. This requires the use of the <`Limit`> directive.

The configuration in Example 8-10 allows only authorized users to manipulate the site. However, it does allow them a bit more freedom than you may like. In particular, they may be able to place an `.htaccess` file into the target directory, altering your server configuration. The server may have already been configured to not read `.htaccess` files, but it is best to make sure. Also, you may want to disallow other options within the DAV-enabled directory, such as CGI, symbolic links or server-side includes.

Example 8-10 Securing a Site by Using the <Limit> Directive

    <Location /mypages>
      DAV On
      <Limit PUT POST DELETE PROPFIND PROPPATCH MKCOL COPY MOVE LOCK UNLOCK>
        Require user greg
      </Limit>
    </Location>

Example 8-11 shows a modified configuration with the additional restrictions placed on it through the addition of `AllowOverride None` and `Options None`:

Example 8-11 Securing Site by Using Additional Restrictions

    <Location /mypages>
      DAV On
      AllowOverride None
      Options None
      <Limit PUT POST DELETE PROPFIND PROPPATCH MKCOL COPY MOVE LOCK UNLOCK>
        Require user greg
      </Limit>
    </Location>
    <Location /mypages>
      DAV On
      AllowOverride None
      Options None
      <Limit PUT POST DELETE PROPFIND PROPPATCH MKCOL COPY MOVE LOCK UNLOCK>
        Require user greg
      </Limit>
    </Location>

### 8.6.7 LimitExcept

Rather than using the <`Limit`> directive and specifying an exhaustive list of HTTP methods to secure, it is also possible to use the <`LimitExcept`> directive, as shown in Example 8-12. This directive applies the access restrictions to all methods except for the methods listed.

Example 8-12 Securing a Site Using the <LimitExcept> Directive

    <Location /mypages>
      DAV On
      AllowOverride None
      Options None
      <LimitExcept GET HEAD OPTIONS>
        require user webadmin
      </LimitExcept>
    </Location>

Choosing to use one or the other is a matter of preference. The <`Limit`> directive is precise and explicit, but the <`LimitExcept`> directive automatically restricts methods that are added in the future.

### 8.6.8 LimitXMLRequestBody

`mod_dav` parses XML request bodies into memory. One technique used in denial of service attacks is to send a large request body to a `mod_dav` server. Oracle HTTP Server defines a directive named `LimitRequestBody`, which limits all methods' request bodies. Unfortunately, this is not an effective mechanism for a `mod_dav` server because large `PUT` operations should be allowed.

To limit just the methods that have an XML request body, `mod_dav` provides the `LimitXMLRequestBody` directive. The default for this value is a compile-time constant, which is set to one million (1,000,000) bytes in the standard distribution. Setting the value to zero (0) disables the size limit.

`LimitXMLRequestBody` may be set on a per-server or a per-directory or location basis, and takes a single non-negative integer argument.

## 8.7 WebDAV Security Considerations

Because WebDAV enables read-write capabilities, users on the Internet can write to your Web site or to an Oracle database. A major concern is preventing users from placing an inappropriate file (a "Trojan horse") that can execute on the Web server system. If the WebDAV configuration and authorization is not set up properly, an inappropriate file from the file system can be executed. This problem does not apply to content from an Oracle database, because such content cannot execute in the middle tier.

The HTTP protocol issues `GET` requests both to static and executable files, without differentiation. Oracle HTTP Server executes files based on their location or extension. For example, a shell script (which typically has no file extension) is executed if it is in the `cgi-bin` directory, but is retrieved as a static text file if it is in the `htdocs` directory. On the other hand, a JavaServer Pages (JSP) file, which has a `.jsp` extension, will normally be executed regardless of its location. However, by default, `mod_oradav` prevents a WebDAV-enabled directory from executing a `.jsp` or `.sqljsp` file. For a file with one of these extensions, `mod_oradav` reads the content directly, bypassing any Oracle HTTP Server logic that attempts to execute the file. Files with these extensions are retrieved as having the `text/plain` MIME type and can be edited. You can add to the list of file types that are never to be executed and always retrieved as `text/plain` by using the ORAGetSource parameter.

One way to limit execution of files is to use the Apache `ForceType` directive in a <`Location`> container directive. This forces all content under a location to be retrieved as `text/plain`. However, this simple and sweeping approach may not be what you want in many cases, wherein you want the standard behavior associated with the actual MIME type, for example, for GIF files, to be used.

To decide how to handle these security issues with content on file systems, you should determine what kinds of WebDAV users will have access to the content. WebDAV users typically fall into two categories: Web authors who want to collaborate and manage a Web site, and end users who want to use WebDAV as a public storage area. Because end users should never be able to upload and execute a file, you may want to specify many file extensions with the ORAGetSource parameter or to use the `ForceType` directive for end users.

Be sure to apply the standard Basic or Digest authentication and authorization mechanisms supported by Oracle HTTP Server. Generally, you do this for the default location, such as `dav_public`, in the supplied moddav.conf file. This restricts who can use your system for remote storage, preventing unauthorized users from filling up your disks. You should always apply Oracle HTTP Server authentication and authorization to authors of the Web site.

You should also provide both an execution context and an editing context, so that Web authors, after being properly authenticated and authorized, can edit a JSP file or other executable file and then see how it executes. To do this, create an alias for the directory associated with the execution context, and then DAV-enable the aliased location. For example, assume that you want to be able to execute a script if the URL specifies the `cgi-bin` directory (for example, `http://www.acme.com/cgi-bin/printenv`), but to edit the script if the URL specifies an alias named `edit-cgi-bin` (for example, `http://www.acme.com/edit-cgi-bin/printenv`). In Example 8-13, the configuration file entries achieve this goal, setting up `edit-cgi-bin` as an editing context for content in the `cgi-bin` directory:

Example 8-13 Editing Context

    Alias /edit-cgi-bin /usr/local/apache/cgi-bin
    <Location /edit-cgi-bin>
      DAV On
      ForceType text/plain
    </Location>

## 8.8 OraDAV Performance Considerations

This section provides information that can help you optimize the performance of various kinds of operations. It contains the following topics:

- Using Disk Caching with OraDAV

- Bypassing Oracle Application Server Web Cache for WebDAV Activities

### 8.8.1 Using Disk Caching with OraDAV

Oracle Application Server can use local file system disk caching with data that is retrieved from an Oracle database. Disk caching is designed to improve the performance of HTTP `GET` operations on frequently accessed database data. When data is requested from the database, it is retrieved and is stored in a disk cache on the local file system. If a subsequent request is for the same data and if the data is still in the disk cache, Oracle Application Server checks to see if the data has changed in the database (by examining the `etag` value). If the data has not changed, it is retrieved from the cache, which is more efficient than retrieving a substantial amount of data from the database.

The performance benefit from disk caching is greatest with medium to large-size files (roughly 50 KB and larger). However, with smaller files, the performance benefit is less, and with very small files the performance can be worse with disk caching than without disk caching. For example, if the file `myfile.dat` is requested and if the file size is only 24 bytes, the time required for copying the file from the database to the local system is very small compared to the time required for accessing the database to check if the file has changed. If disk caching is not used, there is no check of the database to see if the file has changed, and the file is copied from the database in all cases.

You can set the following OraDAV parameters to control disk caching for OraDAV operations:

- ORACacheDirectory

- ORACacheTotalSize

- ORACacheMaxResourceSize

- ORACachePrunePercent

If you specify `ORACacheDirectory`, disk caching for OraDAV operations is enabled. In this case, you must also specify a value for `ORACacheTotalSize`, and you can specify values for `ORACacheMaxResourceSize` and `ORACachePrunePercent` parameters. If you do not specify `ORACacheDirectory`, disk caching for OraDAV operations is not enabled, and other disk cache-related parameters are not relevant.

See Also: "OraDAV Configuration Parameters"

### 8.8.2 Bypassing Oracle Application Server Web Cache for WebDAV Activities

Oracle Application Server Web Cache enhances performance for most Web activity, which involves client read-only operations of data on the Web server system. However, OracleAS Web Cache does not cache OraDAV operations, which are designed for read/write capability. Thus, for better performance, WebDAV clients can connect directly to Oracle HTTP Server.

To bypass OracleAS Web Cache for WebDAV clients, you can use port 7778, which is the standard port for Oracle HTTP Server. If you do this, WebDAV clients connect directly to the Web server, resulting in better performance than if OracleAS Web Cache was used.

## 8.9 mod_oradav Usage Notes

This section contains usage notes relating to `mod_oradav`. Some of the information is taken or adapted from material written by Greg Stein (`gstein@lyra.org`) and available at the following URL:

`http://www.webdav.org/mod_dav/install.html`

### 8.9.1 Mapping Containers Under the Root Location

Note the following when mapping containers under the root location:

- Do not map the root itself. That is, do not specify <`Location />`.

- Do not map a container as a subelement in the hierarchy to another container. For example, do not specify the following two containers: `<Location /project1>` and `<Location /project1/project2>`. However, it is acceptable to specify `<Location /project1>` and `<Location /project2>`.

- Do not create any symbolic links to the container or any location under the container in the hierarchy.

### 8.9.2 Globalization Support Considerations with OraDAV

For access to database data, the character set used for client requests, such as in URLs and file names, must be compatible with the character set used for the database. Specifically, if the character set for the database is not the same as for the client requests, the character set for the database must provide for conversion of all possible characters in client requests (and thus must be a superset of the character set for client requests). That is, the character set for the database must not cause replacement characters during the conversion.

When you start Oracle HTTP Server, the `NLS_LANG` environment variable must reflect the character set for client requests. For example, if file names and URLs contain Kanji characters, you can specify `NLS_LANG=JAPANESE_JAPAN.JA16SJIS` (for ShiftJIS characters). In this case, the database character set must be one that accommodates `SJIS` characters, for example, `UTF8`.

For access to the local file system, as opposed to database access, the character set for the file system must be the same as, or compatible with, the character set for URLs embedded in client requests. The character set for the file system must provide for conversion of all possible characters in client requests. The `NLS_LANG` parameter value must represent the character set of both the client and the OraDAV server. You must also specify a value of `On` for the parameter `DAVOraNLS`.

For example, assume that you are using Web folders on a system where the files have ShiftJIS characters and that the file system under `dav_public` is represented by the operating system in the `JAPANESE_JAPAN.JA16SJIS` character sets shown in Figure 8-2.

Figure 8-2 OraDAV Access to File System with ShiftJIS Characters

Description of "Figure 8-2 OraDAV Access to File System with ShiftJIS Characters"

In this case, you must do the following:

1. Set the `NLS_LANG` value to `JAPANESE_JAPAN.JA16SJIS`.

2. Include the following in the `httpd.conf` file:

       <Location /dav_public>
         DAV On
         DAVOraNLS On
       </Location>

   Note: If you use Microsoft Internet Explorer with OraDAV and a multibyte character set, you must disable (uncheck) the Internet option (Internet Options, Advanced tab) `Always send URLs as UTF-8`. (By default, this option is enabled.) The requirement to disable this option applies to both database access and file system access.

### 8.9.3 PROPFIND Security

In the example configurations in the preceding sections on the <`Limit`> and <`LimitExcept`> directives, the `PROPFIND` method was limited, even though it is read-only. This is because the `PROPFIND` method can be used to list all the files in the DAV-enabled directory. For security reasons, it is probably best to protect the list of files from general read access.

An alternative is to limit the `PROPFIND` to a group of people, a set of domains, or a set of hosts, while the methods that modify content are limited to just a few authors. This scenario allows, for example, your company's employees to browse the files on the server, yet only a few people can change them. Anonymous (non-authenticated) visitors cannot browse or modify.

Finally, you can simply omit `PROPFIND` from the limits if your Web server is intended as a general, read-only repository of files. This allows anybody to arbitrarily browse the directories and then to fetch the files.

## 8.10 Backup and Recovery of DAV Files

When $ORACLE_HOME/Apache/oradav/conf/moddav.conf is configured to use file storage, it places the files by default in:

    $ORACLE_HOME/Apache/Apache/htdocs/dav_public

Oracle Application Server Recovery Manager backs up this default location. If you change the location of where the files are stored, and you want Recovery manager to backup the files, you must add the new location to the `config_misc_files.inp` file. For more information, see the Introdution to Backup and Recovery chapter in the Oracle Application Server Administrator's Guide.