Sun ONE Web Server 6.1 Administrator's Guide |
Chapter 19
Web Publishing with WebDAVSun ONE Web Server 6.1 supports WebDAV or Web-based Distributed Authoring and Versioning, an emerging standard in Web-based collaboration. WebDAV is an extension to the HTTP/1.1 protocol that allows clients to perform remote web content authoring operations.
This chapter describes how you can use WebDAV on Sun ONE Web Server 6.1. It contains the following sections:
About WebDAVWebDAV is an extension of the HTTP/1.1 protocol, and adds new HTTP methods and headers that provide authoring support for Web resources of any type, not only HTML and XML but also, text, graphics, spreadsheets, and all other formats.
Some of the tasks you can accomplish using WebDAV are:
- Properties (meta-data) manipulation. You can create, remove and query information about web pages, such as their authors and creation date using the WebDAV methods PROPFIND and PROPPATCH.
- Collection and resource management. You can create sets of documents and retrieve a hierarchical membership listing (similar to a directory listing in a file system) using the WebDAV methods GET, PUT, DELETE, and MKCOL.
- Locking. You can use WebDAV to keep more than one person from working on a document at the same time. The use of mutually exclusive or shared locks using the WebDAV methods LOCK and UNLOCK, helps to prevent the “lost updates” (overwriting of changes) problem.
- Namespace operations. You can use WebDAV to instruct the server to copy and move Web resources using the WebDAV methods COPY and MOVE.
WebDAV support in Sun ONE Web Server 6.1 provides the following features:
Common WebDAV TerminologyThis section outlines the common terms you will encounter as you work with WebDAV.
URI. A URI (Uniform Resource Identifier) is a file identifier that provides an additional layer of security by using an abbreviated URL. The first part of the URL is substituted with a URL mapping that hides the file’s full physical pathname from the user.
Source URI. The term, source URI, refers to the URI at which a resource’s source can be accessed. To understand the concept of source URI, consider the following example:
A JSP page, foo.jsp, is located at the URI /docs/date.jsp. This page contains HTML markup and Java code which, when executed, prints today's date on the client's browser. When the server receives a GET request for foo.jsp from a client, before serving the page it executes the Java code. What the client receives is not foo.jsp as it resides on the server but instead a dynamically generated page that displays the current date.
If you were to create a source URI, say /publish/docs, and map it to the /docs directory containing foo.jsp, then a request for /publish/docs/foo.jsp would be a request for the source code of the /docs/foo.jsp JSP page. In this case, the server would serve the page without executing the Java code. The client would receive the unprocessed page exactly as stored on disk.
A request for the source URI is thus a request for the source of the resource.
Collection. A WebDAV collection is a resource or a set of resources that are enabled for WebDAV operations. A collection contains a set of URIs, termed member URIs, which identify member resources that are WebDAV-enabled.
Member URI. A URI which is a member of the set of URIs inside a collection.
Internal Member URI. A Member URI that is immediately relative to the URI of the collection. For example, if the resource with the URL http://info.sun.com/resources/info is WebDAV-enabled and if the resource with the URL http://info.sun.com/resources/ is also WebDAV-enabled, then the resource with the URL http://info.sun.com/resources/ is a collection and contains http://info.sun.com/resources/info as an internal member.
Property. A name/value pair that contains descriptive information about a resource. Properties are used for efficient discovery and management of resources. For example, a 'creationdate' property might allow for the indexing of all resources by the date on which the resources were created, and an 'author' property, for indexing by author name.
Live Property. A property that is enforced by the server. For example, the live getcontentlength property has as its value, the length of the entity returned by a GET request, which is automatically calculated by the server. Live properties include the following:
Dead Property. A property that is not enforced by the server. The server only records the value of a dead property; the client is responsible for maintaining its consistency.
Sun ONE Web Server 6.1 supports the following live properties:
- creationdate
- displayname
- getcontentlanguage
- getcontentlength
- getcontenttype
- gettag
- getlastmodified
- lockdiscovery
- resourcetype
- supportedlock
- executable
Locking. The ability to lock a resource provides a mechanism to guarantee that one user will not modify a resource while it is being edited by another. Locking prevents overwrite conflicts and resolves the "lost updates" problem.
Sun ONE Web Server supports two types of locking: shared and exclusive.
New HTTP Headers. WebDAV works by extending the HTTP/1.1 protocol. It defines new HTTP headers by which clients can communicate requests for WebDAV resources. These headers are:
New HTTP Methods. WebDAV introduces several new HTTP methods that instruct WebDAV-enabled servers how to handle requests. These methods are used in addition to existing HTTP methods such as GET, PUT, and DELETE to carry out WebDAV transactions. The new HTTP methods are briefly described below:
- COPY. Used to copy resources. Copying collections uses the Depth: header while the Destination: header specifies the target. The COPY method also uses the Overwrite: header, as appropriate.
- MOVE. Used to move resources. Moving collections uses the Depth: header while the Destination: header specifies the target. The MOVE method also uses the Overwrite: header, as appropriate.
- MKCOL. Used to create a new collection. This method is used to avoid overloading the PUT method.
- PROPPATCH. Used to set, change, or delete properties on a single resource.
- PROPFIND. Used to fetch one or more properties belonging to one or more resources. When a client submits a PROPFIND request on a collection to the server, the request may include a Depth: header with a value of 0, 1, or infinity.
- 0. Specifies that the properties of the collection at the specified URI will be fetched.
- 1. Specifies that the properties of the collection and resources immediately under the specified URI will be fetched.
- infinity. Specifies that the properties of the collection and all member URIs it contains will be fetched. Be aware that because a request with infinite depth would crawl the entire collection, it could impose a large burden on the server.
- LOCK. Adds locks on resources. Uses the Lock-Token: header.
- UNLOCK. Removes locks from resources. Uses the Lock-Token: header.
Using WebDAVA complete WebDAV transaction involves a WebDAV-enabled server, such as Sun ONE Web Server 6.1, that can service requests for WebDAV resources, as well as a WebDAV-enabled client such as AdobeŽ GoLiveŽ or MacromediaŽ DreamWeaverŽ that supports WebDAV-enabled Web publishing requests.
On the server-side, you need to enable and configure Sun ONE Web Server 6.1 to be able to service WebDAV requests.
To configure Sun ONE Web Server 6.1 to use WebDAV, the following steps are needed:
Enabling WebDAVWhen you install Sun ONE Web Server 6.1, WebDAV is disabled by default.
In order to enable WebDAV at the collection level, you need to also enable WebDAV at the server instance level and the virtual server class level.
Note
The attributes specified on a collection override attribute values set at the virtual server level.
The different levels at which you can enable WebDAV are described in the following sections:
Enabling WebDAV for the Server Instance
You can use the Administration Server to enable WebDAV for the entire server. When you do so, the following directive is added to the magnus.conf file that loads the WebDAV plugin:
Init fn="load-modules" shlib="/s1ws6.1/lib/libdavplugin.so" funcs="init-dav,ntrans-dav,pcheck-dav,service-dav"
shlib_flags="(global|now)"
Init fn="init-dav" LateInit=yes
The init-dav Init function initializes and registers the WebDAV subsystem.
To enable WebDAV globally, perform the following tasks:
- Access the Server Manager of the server you want to enable WebDAV for.
- Click the Enable/Disable WebDAV link on the Preferences tab.
- Check the Enable WebDAV Globally checkbox.
Enabling WebDAV for the Instance
- Click Apply.
- Click the Apply Changes button to restart the server
or
click Load Configuration Files to dynamically apply your changes.
Enabling WebDAV for a Virtual Server Class
To enable WebDAV for a particular virtual server class:
When you enable WebDAV for a virtual server class, the associated obj.conf file is updated with the following entries:
Enabling WebDAV for a Collection
If you have added one or more WebDAV collections to a virtual server, you can choose to disable and enable them at any time. For information on how you can do so, see "Editing a WebDAV Collection".
Creating a WebDAV CollectionA WebDAV collection is a resource or a set of resources that are enabled for WebDAV operations. These operations include web publishing and collaborative authoring, namespace management, and metadata management.
To add a WebDAV collection to a virtual server, perform the following tasks:
- Make sure that WebDAV is enabled for the server instance and for the virtual server class. For more information, see "Enabling WebDAV for the Server Instance" and "Enabling WebDAV for a Virtual Server Class".
- Access the virtual server you want to manage and click the WebDAV tab.
- In the Add DAV Collection page, enter the following information:
- URI (required). The URI by which the content is accessed.
- Source URI (optional). The URI by which the source is accessed.
Note
If you plan to publish dynamic content such as CGI or SHTML, you must have a source URI configured.
For an explanation of the term source URI, see Common WebDAV Terminology.
- Lock Database (optional). The directory where the locking database will be maintained. The default value is server-instance/lock-db/vs-id.
- Minimum Lock Timeout (optional). The minimum lifetime of a lock in seconds. The default value is 0. For more information, see Minimum Lock Timeout.
- Limit XML Request Body (optional). The maximum size of the XML content in the body of the request. Restrict the size to prevent the possibility of Denial of Service (DOS) attacks.
- Maximum Property Depth (optional). The depth of the PROPFIND request.
- Enabled (optional). Enables WebDAV functionality for the collection.
- Click OK.
Note
- When you use the Administration server to add a collection, the server does not automatically create a directory for the collection on the filesystem. It is the responsibility of the administrator to ensure that a directory corresponding to the collection is created on the filesystem.
- On UNIX systems, if you have installed the Web Server as root (superuser), and are running the server as a different user, ensure that the user you are running the server as has read and write permissions on the directories corresponding to the WebDAV collections you create.
Editing a WebDAV CollectionYou can edit the attributes of an existing DAV collection, for example to configure access control on the collection.
To edit an existing WebDAV collection, perform the following tasks:
- Access the virtual server on which the collection exists and click the WebDAV tab.
- In the Edit DAV Collections page, modify the following information:
- Delete. Allows you to or delete a collection.
- URI. Displays the URI by which the content is accessed.
- Enabled. Indicates whether WebDAV is enabled (true) or disabled (false).
- Edit Collection. Click this button to configure the following:
- URI (required). The URI by which the content is accessed.
- Source URI (optional). The URI by which the source is accessed.
- Lock Database (optional). The directory where the locking database will be maintained.
- Minimum Lock Timeout (optional). The minimum lifetime of a lock in seconds. For more information, see Minimum Lock Timeout.
- Limit XML Request Body (optional). The maximum size of the XML content in the body of the request.
- Maximum Property Depth (optional). The depth of the PROPFIND request.
- 0 applies only to the specified resource.
- 1 applies to the specified resource and the next level of resources it contains.
- infinity applies to the specified resource and all the resources it contains.
- Edit ACL. Click this to set up access control restrictions for this collection or URI.
Configuring WebDAVYou might want to configure WebDAV for several reasons: for example, to tune server performance, to eliminate security risks, or to provide for conflict-free remote authoring.
To suit your configuration requirements, you can change the minimum amount of time the server holds a lock on a WebDAV resource, the depth of the PROPFIND request on a collection, and the maximum size of the XML content allowed in the body of a request, and so on.
Default WebDAV attributes can be configured at the virtual server level for all collections under a virtual server. The values configured here correspond to the DAV element in the server.xml file.
WebDAV attributes can also be configured at a collection level and override any virtual-server -level attributes configured for the collection. The attribute values configured at the collection level correspond to the DAVCOLLECTION element in the server.xml file.
Configuring WebDAV at the Virtual Server Level
To configure WebDAV functionality for the virtual server, you need to edit the attributes of the DAV object. You can do this either by using the Administration Server or by manually editing the server.xml file.
The following table describes the attributes of the DAV object you can configure:
Table 1 Attributes of the DAV object
Attribute
Description
enabled
Specifies if WebDAV functionality is enabled for this virtual server.
This is an optional attribute. The default value is true.
Possible values are true and false.
lockdb
Specifies the directory where the locking database will be maintained.
This is an optional attribute.
minlocktimeout
Specifies the minimum lifetime of a lock in seconds. This value indicates the amount of time that an element will be locked before the lock is automatically removed. For more information, see Minimum Lock Timeout.
This is an optional attribute.
maxxmlrequestbodysize
Specifies the maximum size of the XML content in the body of the request.
This is an optional attribute. The default value is 8K.
Restrict the size to prevent the possibility of Denial of service (DOS) attacks.
maxpropdepth
Specifies the depth of the PROPFIND request.
This is an optional parameter. The default value is 0.
Prevent excessive memory consumption by restricting the size of this parameter.
Configuring WebDAV at the URI Level
To configure WebDAV functionality at the URI level, you need to edit the attributes of the DAVCOLLECTION object in the server.xml file.
The following table describes the attributes of the DAVCOLLECTION object that you can configure:
Table 2 Attributes of the DAVCOLLECTION object
Attribute
Description
enabled
Specifies if DAV functionality is enabled for this collection.
This is an optional attribute.
Possible values are true and false. The default value is true.
uri
Specifies the URI by which the content is accessed.
This is a required attribute.
sourceuri
Specifies the URI by which the source is accessed. For more information, see Common WebDAV Terminology and Using Source URI and Translate:f Header on a WebDAV-Enabled Server.
This is an optional attribute.
If the sourceuri is not specified, the default behavior is to deny access to the source of any dynamic content in the collection.
You can specify the same URI for both uri and sourceuri, in which case the server will always returns the source of dynamic content. This may be useful if you use a separate, secured virtual server for publishing.
lockdb
Specifies the directory where the locking database will be maintained.
This is an optional attribute.
minlocktimeout
Specifies the minimum lifetime of a lock in seconds. This value indicates the amount of time that an element will be locked before the lock is automatically removed. For more information, see Minimum Lock Timeout.
This is an optional attribute.
maxxmlrequestbodysize
Specifies the maximum size of the XML content in the body of the request.
This is an optional attribute.
Restrict the size to prevent the possibility of Denial of Service (DOS) attacks.
maxpropdepth
Specifies the depth of the PROPFIND request, which lists the member resources of a collection.
This is an optional parameter.
Prevent excessive memory consumption by restricting the size of this parameter.
Using Source URI and Translate:f Header on a WebDAV-Enabled ServerWebDAV methods operate on the source of a resource or a collection. HTTP methods such as GET and PUT are overloaded by the WebDAV protocol and therefore, a request with these methods can either be a request to the source of the resource or a request to the content (output) of the resource.
Microsoft and many other WebDAV vendors have addressed this problem by sending a Translate:f header with the request to inform the server that the request is for the source. In order to be interoperable with the popular WebDAV client Microsoft WebFolders, Sun ONE Web Server 6.1 recognizes the Translate:f header as a request to the source of the resource. To accommodate clients that do not send the Translate:f header, Sun ONE Web Server 6.1 defines a source URI. See Common WebDAV Terminology for a more detailed explanation of the term source URI.
For a WebDAV-enabled collection, the request to the URI retrieves the content (output) of the resource and a request to the source URI retrieves the source of the resource. A request to the URI with a Translate:f header is treated as a request to the source URI.
Note that by default all access to the source of a resource is denied by the dav-src ACL with the following declaration in the server instance-specific ACL file:
deny (all) user = "anyone";
An user can enable access to the source to a user by adding access rights to the source URI. For more information on adding URI-specific ACLs, please see Enabling Access Control for WebDAV.
Locking and Unlocking ResourcesSun ONE Web Server allows the server administrator to lock a resource so as to serialize access to that resource. Using a lock, a user accessing a particular resource is reassured that another user will not modify the same resource. In this way, the "lost updates" problem is resolved as multiple users share resources on the server. The lock database maintained by the server keeps track of the lock tokens issued and in use by clients.
Sun ONE Web Server 6.1 supports the opaquelocktoken URI scheme, which is designed to be unique across all resources for all time. This uses the Universal Unique Identifier (UUID) mechanism, as described in ISO-11578.
Sun ONE Web Server 6.1 recognizes two types of locking mechanisms:
Exclusive Locks
An exclusive lock is a lock that grants access to a resource to only a single user. Another user can access the same resource only after the exclusive lock on the resource is removed.
Exclusive locking sometimes proves to be too rigid and expensive a mechanism for locking resources. For example, in the event of a program crash or the lock owner forgetting to unlock the resource, a lock timeout or the administrator’s intervention would be required to remove the exclusive lock.
Shared Locks
A shared lock allows multiple users to receive a lock to a resource. Hence any user with appropriate access can get the lock.
When using shared locks, lock owners may use any other communication channel to coordinate their work. The intent of a shared lock is to let collaborators know who else may be working on a resource.
Lock Management
Sun ONE Web Server 6.1 provides a lock management feature which allows you to view all outstanding locks, their type, the resources they hold, the duration of the lock and so on.
To use lock management, do the following:
Minimum Lock Timeout
You can control locking by configuring the value of the minlocktimeout attribute of the DAV or DAVCOLLECTION objects in the server.xml file. The minlocktimeout attribute specifies the minimum lifetime of a lock in seconds. This value indicates the amount of time that an element will be locked before the lock is automatically removed.
This is an optional attribute. If the value is set to -1, the lock will never expire. Setting the value to 0 allows all the resources in the collection to be locked with the Timeout header specified in the request.
If no Timeout header is specified, then the resource is locked with infinite timeout. If a request has a Timeout header set to the value Infinite, then also, the resource is locked with infinite timeout.
If the request for a WebDAV resource has a Timeout header value that is equal to or greater than the minlocktimeout value specified in server.xml, then the resource is locked for the period of time specified in the request.
However, if the request has a Timeout header value that is lower than the minlocktimeout value specified in server.xml, then the resource is locked with the minlocktimeout value specified in server.xml.
The following table illustrates how Sun ONE Web Server handles locking requests:
Table 3 How Sun ONE Web Server handles locking requests
If Timeout header value in Request is set to:
The resource is:
Infinite
Locked with timeout set to -1 (infinite)
None
Locked with timeout set to -1 (infinite)
Second-xxx
or
Example of a Lock Request
This example illustrates a request for an exclusive write lock on the resource /col1/myfile.html with a timeout of 500 seconds.
LOCK /col1/myfile.html HTTP/1.1
Host: sun
Content-Type: text/xml; charset=”utf-8”
Content-Length: 259
Timeout: Second-500
<?xml version=”1.0” encoding=”utf-8” ?>
<d:lockinfo xmlns:d=”DAV:”>
<d:locktype><d:write/></d:locktype>
<d:lockscope><d:exclusive/></d:lockscope>
<d:owner>
<d:href>http://info.sun.com/resources/info.html</d:href>
</d:owner>
</d:lockinfo>
Enabling Access Control for WebDAVYou can control who accesses WebDAV-enabled documents and directories and what operations different users or different groups of users can perform upon the files. You can also completely prohibit access to a file or folder or you can restrict access to certain authenticated users.
If the default access control (ACL) that governs your server is not restrictive or flexible enough for your needs, you can use the Restrict Access function (choose Server Preferences and click the Restrict Access link) to create an ACL that is more appropriate for restricting access to WebDAV-enabled resources.
WebDAV requests are authenticated and authorized by the AuthTrans and PathCheck NSAPI stages respectively. In the following example, an access control rule is defined that denies write and delete access to the collection /catalog to all except a user named "joe":
acl "uri=/catalog/*";
deny(all)
user="anyone";
allow (read,list,execute,info)
user = "all";
allow(write,delete)
user="joe";
For more details, refer to Editing a WebDAV Collection.
Restricting Access on WebDAV-Enabled Resources
Access control for a WebDAV collection is specified using native ACL files. Every WebDAV method requires a particular access right to a WebDAV-enabled resource. For example, if a WebDAV-enabled file is to be shared by concurrent users, in order to lock or unlock the resource for concurrency control, a write permission to the resource is required.
The following table below summarizes the rights required for WebDAV methods.
Table 19-4 Rights required for WebDAV
DAV Methods
Access Rights Needed
DELETE
delete
PROPFIND
read
PROPPATCH
write
LOCK/UNLOCK
write
MKCOL
write
COPY(src,dst)
src - read
dst - write
MOVE(src,dst)
src - delete
dst - write
GET on request-uri
read
GET on request-uri
Translate:f
read
PUT on request-uri
write
PUT on request-uri
Translate:f
write
Security ConsiderationsWhen you use WebDAV, keep in mind the following security considerations:
- Ensure that a WebDAV-enabled server process has read/write permissions to the file systems that need to be controlled.
- For security reasons, you may wish to configure WebDAV-enabled virtual servers on a different listen socket, one that has restricted access and uses SSL to encrypt transmitted data. See Using Certificates and Keys for more information on using SSL.
- Prevent Denial of Service (DOS) attacks by restricting the size of the XML content in the request body. By default, the size is restricted to 8K.
- Because Basic authentication uses cleartext to transmit authentication details, unless your connection is secure, use Digest rather than Basic authentication to authenticate WebDAV clients.
- Because PROPFIND requests run the potential risk of unwanted access to server contents, use access control techniques to secure WebDAV-enabled resources.
- WebDAV, through its source URI facility, can potentially expose URIs containing sensitive information such as script resources. You should be aware of the risks of allowing the remote authoring of scripts, and should limit read and write access to source resources to authorized users only.
- Prevent excessive memory consumption by restricting the depth of PROPFIND requests. By default, the depth is restricted to 0.