9 Configuring mod_oradav

This chapter describes distributed authoring and versioning (DAV) concepts, and explains how to configure OraDAV using the mod_oradav module. The mod_oradav module enables you to use OraDAV to access content in files from a Web browser or a WebDAV client.

This chapter includes the following sections:

9.1 Introduction to the mod_oradav Module

The mod_oradav module is an extended implementation of the Apache implementation of the WebDAV specification. The mod_oradav module is an OCI application written in C and is integrated with Oracle HTTP Server. The mod_oradav module enables WebDAV clients to connect to files, read and write content, and query and lock documents.

This section includes the following subsections:

9.1.1 WebDAV

WebDAV is a protocol extension to HTTP 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 access and optionally change that content from various devices.

Note:

When a WebDAV client first connects to Oracle HTTP Server, it must use the full ServerName string in the URL for the connection. Do not use an abbreviated form of the server name.

For example, if the server name value is server1.example.com, then connect to Oracle HTTP Server using the string http://server1.example.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 run, and generate BAD_GATEWAY errors.

9.1.2 OraDAV

OraDAV refers to the set of capabilities available through the mod_oradav module to Oracle Fusion Middleware users. Some OraDAV-specific terms include:

  • OraDAV: Code in the Oracle HTTP Server that supports file-based DAV access. Apache DAV directives can be used with OraDAV.

    See Also:

    For more information about DAV directives, see the article written by Greg Stein (gstein@lyra.org) available at

    http://www.webdav.org/mod_dav/install.html#apache

  • OraDAV API: Stored procedure calls that are used by the OraDAV driver to provide support for the following WebDAV functions over the Internet:

    • Reading and writing documents

    • Locking and unlocking documents

    • Managing, such as creating, populating, and deleting, hierarchies of information

    • Retrieving properties associated with documents

    • Associating properties with specific documents

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

The primary users of OraDAV are Oracle HTTP Server Web administrators and content editors. End users interact only indirectly with OraDAV through Web browsers or WebDAV client tools. OraDAV interaction requires the following proficiency:

  • The Web administrator 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 content editors need to know how to connect to the server, and upload and retrieve files.

9.1.3 OraDAV Architecture

The mod_oradav module, which includes OraDAV, is part of the Oracle HTTP Server architecture. A simple form of the architecture is illustrated in Figure 9-1.

Figure 9-1 OraDAV Architecture

Description of Figure 9-1 follows
Description of "Figure 9-1 OraDAV Architecture"

Figure 9-1 shows a WebDAV client, such as Web folders, passing HTTP requests to Oracle HTTP Server. If the request is for content stored in the file system, the mod_oradav module handles the access. If the request is for content stored in Oracle Portal, the OraDAV API handles the access.

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

  • COPY: Copies files within a Web site folder.

  • DELETE: Deletes files within a Web site folder.

  • MOVE: Moves files within a Web site folder.

  • MKCOL: Makes a new directory.

  • GET: Retrieves a file from the server. This method is not supported by Oracle Web Cache.

  • PUT: Puts a file back to the server. This method is not supported by Oracle Web Cache.

  • HEAD: Gets the header content of a file without retrieving the file.

  • LOCK: Locks a file when the file is checked out. This method is not supported by Oracle Web Cache.

  • UNLOCK: Unlocks a file after check in. This method is not supported by Oracle Web Cache.

  • PROPFIND: Gets properties defined for a file.

  • PROPPATCH: Sets the properties for a file.

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

9.1.4 OraDAV Usage Model

OraDAV usage can involve any combination of the following activities:

  • Browsing: Read-only activity which uses WebDAV to access content on the file server. Its usage model is typical of a read-only Web site.

    The DAVOraReadOnly directive specifies whether or not WebDAV should be used in a read-only mode by WebDAV clients. A value of Off specifies that WebDAV clients function normally. A value of On prevents WebDAV clients from performing write operations while using WebDAV. It does allow read-only activity by Web browsers and WebDAV clients. The default is Off.

  • 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, then 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 use 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.

9.1.5 PROPFIND Security

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 to fetch the files.

9.2 Configuring mod_oradav

Use the Advanced Server Configuration page of Fusion Middleware Control to configure the mod_oradav module.

This section includes the following subsections:

9.2.1 OraDAV Configuration Parameters

When Oracle Fusion Middleware is installed, all required OraDAV parameters are set to their default values. If the default values do not meet your needs, you can modify the values for required parameters and specify values for optional parameters. The OraDAV parameters in the mod_oradav.conf file start with "DAV" and "DAVParam".

Note:

To configure the parameters use Fusion Middleware Control. Do not edit the mod_oradav.conf file directly. Doing so may harm your installation.

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

  • On – indicates that mod_oradav is to use the local file system for content.

  • Oracle – indicates that mod_oradav is to use OraDAV for all content.

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

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 additional DAV parameters, such as DavMinTimeout.

Example 9-1 shows the syntax to configure access to files on the local system. It specifies that the directory dav_portal under the Web server documents directory is to be DAV-enabled, along with all directories under dav_portal in the hierarchy. There must not be any symlinks defined on the dav_portal directory or any of its subdirectories.

Example 9-1 Configuring File System Access

<Location /dav_portal>
  DAV On
</Location>

The following recommendations should be considered when mapping containers under the root location:

  • Do not map the root itself. For example, do not specify <Location / > in the mod_oradav.conf file.

  • Do not map a container as a subelement in the hierarchy to another container. For example, do not specify the containers <Location /project1> and <Location /project1/project2>. 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.

The OraDAV parameters are described in the following sections:

9.2.1.1 ORAAllowIndexDetails

In an Oracle HTTP Server environment that is not OraDAV-enabled, mod_dav does not respond to HTTP GET requests. Instead, normal Oracle HTTP Server mechanisms are used to 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 the 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. If ?details is used in a URL, it is ignored and the URL contents are returned.

9.2.1.2 ORAAltPassword

Specifies the password for the user specified by the ORAUser parameter. The OraAltPassword uses a base-64 encoded character string. This parameter provides an alternative if you do not want the password to appear in unencoded plain text with the ORAUser parameter.

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

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

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 be located on a file system that supports a last accessed time. On Microsoft 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.

9.2.1.4 ORACacheMaxResourceSize

Specifies the maximum cacheable resource size for disk caching operations. You can specify KB (for kilobytes) or MB (for megabytes) after an integer. If you do not specify a unit after the integer, then the default unit is bytes.

This parameter enables Web administrators to prevent large media files from dominating the cache. The performance benefit of caching a large file is greater than from caching a small file.

Example 9-2 shows an example for ORACacheMaxResourceSize.

Example 9-2 ORACacheMaxResourceSize Parameter

DAVParam ORACacheMaxResourceSize 1024KB

The setting in Example 9-2 prevents OraDAV from caching any resource larger than 1 MB.

9.2.1.5 ORACachePrunePercent

Specifies the percentage of disk cache usage to be freed when the cache is full. When the disk cache is full, the oldest files in the cache are deleted until the cache disk usage is reduced by the ORACachePrunePercent value. The default value is 25.

9.2.1.6 ORACacheTotalSize

Specifies the size of the cache to use for disk caching operations. You can specify MB (for megabytes) or GB (for gigabytes) after an integer. If you do not specify a unit after the integer, the default unit is bytes.

Example 9-3 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 amount of your Web site, or all of the 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 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.

9.2.1.7 ORAConnect

Specifies the Oracle database to connect to. The ORAConnect parameter lets you connect to a database that is not included in the tnsnames.ora file. The value must use the following format:

database_host:database_port:database_sid

Example 9-4 shows an example:

Example 9-4 ORAConnect Parameter

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

To connect to an Oracle database, you must specify one, and no more than one, of the parameters ORAConnect, ORAConnectSN, or ORAService. To connect to a database included in the tnsnames.ora file, use the ORAService parameter.

9.2.1.8 ORAConnectSN

Specifies the Oracle database to connect to. The ORAConnectSN parameter lets you connect to a database that is not included in the tnsnames.ora file. The value for this parameter is a character string.The value must use the following format:

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

To connect to an Oracle database, you must specify one, and no more than one, of the parameters ORAConnect, or ORAService. To connect to a database included in the tnsnames.ora file, use the ORAService parameter.

9.2.1.9 ORAContainerName

Within the database user (schema) specified by the ORAUser parameter, there must exist a container, which is a set of PL/SQ packages and database tables that allow the storage of files in the database within a hierarchical structure. The ORAContainerName parameter specifies the name of the container to use for the location. The value for this parameter is a character string, up to 20 characters. For example, <Location/project1>.

9.2.1.10 ORAException

Writes PL/SQL stack dumps in the Oracle HTTP Server log file, error_log, in the event of an exception in the PL/SQL package. The values are RAISE or NORAISE. Default value is NORAISE.

Note:

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.

9.2.1.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 run, but rather opened for editing. Include periods (.) with the file extension and use a comma to separate file extensions. The value for this parameter is enclosed within double quotation marks. For example:

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

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

Note:

The .jsp and .sqljsp files are by default opened for editing; you do not need to specify them in the ORAGetSource parameter.

9.2.1.12 ORALockExpirationPad

Intended to be used in high-latency network environments to adjust the refresh lock behavior in Microsoft Office. Microsoft Office attempts to refresh locks on DAV resources just before the lock is set to expire. If there is network congestion between the Microsoft Office client and the DAV server, the refresh request might arrive after the lock has expired. The value is the number of seconds. The default value is 0.

OraDAV periodically looks for locks on resources that have expired and deletes those locks. The ORALockExpirationPad parameter can be used to provide some additional 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 for at least two minutes after the expiration time.

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

9.2.1.14 ORAPassword

Specifies the password for the user specified by the ORAUser parameter.

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.

9.2.1.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. Do not include a trailing slash (/) in the value.

In Example 9-5, assume that the database repository contains the directory /first/second/third/fourth.

Example 9-5 ORARootPrefix Parameter

DAVParam ORARootPrefix /first/second

WebDAV clients can view the /third directory and can navigate to the /third/fourth directory, but will not be able to view or navigate to the /first or /first/second directories.

9.2.1.16 ORAService

Specifies the Oracle database to connect to. The specified value must match a SID value in the tnsnames.ora file.

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

9.2.1.17 ORATraceEvents

Specifies the types of events to be recorded in the Oracle HTTP Server error log for debugging. The value for this parameter is one of the following:

  • 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

Note:

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.

9.2.1.18 ORATraceLevel

Specifies the level of debugging (trace statements) that will be entered in the Oracle HTTP Server error log. The lowest level is 0 (the default), which performs no tracing. The highest level is 4, which performs maximum tracing. The value for this parameter is an integer between 0 and 4.

The higher the number for the debugging level, the more information is written to the error log file.

Note:

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.

9.2.1.19 ORAUser

Specifies the database user (schema) to use when connecting to the service specified by the ORAConnect, ORAConnectSN, or ORAService parameter.

This user must have the following privileges:

  • CONNECT

  • RESOURCE

  • CREATE TABLESPACE

  • DROP TABLESPACE

  • CREATE ANY TRIGGER

9.2.2 Using Fusion Middleware Control to Configure mod_oradav

On the Advanced Server Configuration page of Fusion Middleware Control, you can enter parameters within a <Location> container directive in the mod_oradav.conf file. The <Location> container directive specifies the DAV-enabled URL. The DAV keyword is followed by the parameter On, which instructs mod_dav to use the local file system for content.

The following example specifies that the directory myfiles under the Web server documents directory (htdocs by default) to be DAV-enabled, along with all directories under myfiles in the hierarchy. There must not be any symbolic links defined on the myfiles directory or any of its subdirectories.

<Location /myfiles>
   DAV On
</Location>

9.3 WebDAV Security Considerations

Because WebDAV enables read/write capabilities, Internet users can write to your Web site or to an Oracle repository. A major concern is preventing users from placing an inappropriate file, such as a Trojan horse, that can run 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 run. However, mod_oradav is disabled by default in new installations of Oracle HTTP Server so that your system is secure out-of-the-box.

See Also:

Apache Module mod_dav Security Issues in the Apache Server documentation.

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 mod_oradav.conf file. This restricts who can use your system for remote storage, preventing unauthorized users from filling up your disks.

In addition, 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 runs. To do this, create an alias for the directory associated with the execution context, and then DAV-enable the aliased location.

9.4 OraDAV Performance Considerations

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

9.4.1 Using Disk Caching with OraDAV

The performance benefit from disk caching is greatest with medium to large-size files (approximately 50 KB and larger). 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 server to the local system is very small compared to the time required for accessing the server to check if the file has changed. If disk caching is not used, there is no check of the server to see if the file has changed, and the file is copied 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. 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.

9.4.2 Bypassing Oracle Web Cache for WebDAV Activities

Oracle Web Cache enhances performance for most Web activity that involves client read-only operations of data on the Web server system. Oracle Web Cache does not cache OraDAV operations for GET, PUT, LOCK and UNLOCK, which are designed for read/write capability. For better performance, WebDAV clients can connect directly to Oracle HTTP Server.

To bypass Oracle Web Cache for WebDAV clients, you can send requests directly to the Oracle HTTP Server listen port, which is set in the httpd.conf file. By doing this, WebDAV clients will connect directly to Oracle HTTP Server, resulting in better performance than if Oracle Web Cache is used.

9.5 Globalization Support Considerations with OraDAV

The DAVOraUseNLSLang directive 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 specifies that no conversion is needed. A value of On specifies that the character set for the file system provides for conversion of all possible characters in client requests. The default is Off.

For access to the local file system, 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 DAVOraUseNLSLang.

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 9-2.

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

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

You must do the following:

  1. Set the NLS_LANG value to JAPANESE_JAPAN.JA16SJIS.

  2. Include the following in the mod_oradav.conf file:

    <Location /dav_public>
      DAV On
      DAVOraUseNLSLang On
    </Location>
    

    Note:

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

9.6 Location of DAV Files

When the ORACLE_HOME/ohs/cas/templates/default/moduleconf/mod_oradav.conf file is configured to use file storage, it places the files by default in:

ORACLE_INSTANCE/config/OHS/<ohs_name>/moduleconf

Oracle Fusion Middleware Backup and Recovery Service backs up this default location. If you change the location where the files are stored, and you want Oracle Fusion Middleware Backup and Recovery Service to backup the files, then you must register the new location.