[svnbook commit] r1316 - branches/1.2-work/src/en/book
sussman
svnbook-dev at red-bean.com
Fri May 20 16:15:40 CDT 2005
Author: sussman
Date: Fri May 20 16:15:39 2005
New Revision: 1316
Modified:
branches/1.2-work/src/en/book/appc.xml
Log:
New appendix C in the 1.2 book branch.
* src/en/book/appc.xml: complete rewrite of autoversioning appendix
for svn 1.2 book.
Modified: branches/1.2-work/src/en/book/appc.xml
==============================================================================
--- branches/1.2-work/src/en/book/appc.xml (original)
+++ branches/1.2-work/src/en/book/appc.xml Fri May 20 16:15:39 2005
@@ -5,7 +5,7 @@
<para>WebDAV is an extension to HTTP, and is growing more and more
popular as a standard for file-sharing. Today's operating
- systems are becoming extremely Web-aware, and many have now
+ systems are becoming extremely Web-aware, and many now have
built-in support for mounting <quote>shares</quote> exported by
WebDAV servers.</para>
@@ -24,32 +24,42 @@
the ideas behind WebDAV. It should lay the foundation for
understanding WebDAV compatibility issues between clients and
servers.</para>
-
+
+ <para>This section provides a very brief overview to the ideas
+ behind WebDAV. It should lay the foundation for understanding
+ WebDAV compatibility issues between clients and servers.</para>
+
<sect2 id="svn-ap-c-sect-1.1">
- <title>Just Plain WebDAV</title>
-
+ <title>Original WebDAV</title>
+
<para>RFC 2518 defines a set of concepts and accompanying
extension methods to HTTP 1.1 that make the web into a more
universal read/write medium. The basic idea is that a
- WebDAV-compliant web server can act like a generic file server;
- clients can mount WebDAV <quote>shares</quote> that behave
- much like NFS or SMB shares.</para>
+ WebDAV-compliant web server can act like a generic file
+ server; clients can mount shared folders that behave much like
+ NFS or SMB filesystems..</para>
- <para>However, it's important to note that RFC 2518 does
- <emphasis>not</emphasis> provide any sort of model for version
- control, despite the <quote>V</quote> in DAV. Basic WebDAV
- clients and servers assume only one version of each file or
- directory exists, and can be repeatedly overwritten.
- <footnote><para>For this reason, some people jokingly refer to
- generic WebDAV clients as <quote>WebDA</quote>
- clients!</para></footnote></para>
-
- <para>Here are the new concepts and methods introduced in basic
+ <para>The tragedy, though, is that the RFC 2518 WebDAV
+ specification does not provide any sort of model for version
+ control, despite the "V" in DAV. Basic WebDAV clients and
+ servers assume only one version of each file or directory
+ exists, and can be repeatedly overwritten.</para>
+
+ <para>Here are the concepts and terms introduced in basic
WebDAV:</para>
<variablelist>
<varlistentry>
+ <term>Resources</term>
+ <listitem>
+ <para> WebDAV lingo refers to any server-side object
+ (that can be described with a URI) as a
+ <firstterm>resource</firstterm>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term>New write methods</term>
<listitem>
<para>Beyond the standard HTTP <literal>PUT</literal>
@@ -59,17 +69,16 @@
rearranging resources.</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>Collections</term>
<listitem>
- <para>This is simply the WebDAV term for a grouping of
- resources (URIs). In most cases, it is analogous to a
- <quote>directory</quote>. You can tell something is a
- collection if it ends with a trailing <quote>/</quote>.
- Whereas file resources can be written or created with a
- <literal>PUT</literal> method, collection resources are
- created with the new <literal>MKCOL</literal>
+ <para>A <firstterm>collection</firstterm> is the WebDAV
+ term for a grouping of resources. In most cases, it
+ is analogous to a directory. Whereas file resources
+ can be written or created with a
+ <literal>PUT</literal> method, collection resources
+ are created with the new <literal>MKCOL</literal>
method.</para>
</listitem>
</varlistentry>
@@ -81,15 +90,16 @@
Subversion—metadata attached to files and
collections. A client can list or retrieve properties
attached to a resource with the new
- <literal>PROPFIND</literal> method, and can change them
- with the <literal>PROPPATCH</literal> method. Some
- properties are wholly created and controlled by users
- (e.g. a property called <quote>color</quote>), and
- others are wholly created and controlled by the WebDAV
- server (e.g. a property that contains the last
+ <literal>PROPFIND</literal> method, and can change
+ them with the <literal>PROPPATCH</literal> method.
+ Some properties are wholly created and controlled by
+ users (e.g. a property called <quote>color</quote>),
+ and others are wholly created and controlled by the
+ WebDAV server (e.g. a property that contains the last
modification time of a file). The former kind are
- called <quote>dead</quote> properties, and the latter
- kind are called <quote>live</quote> properties.</para>
+ called <firstterm>dead properties</firstterm>, and the
+ latter kind are called <firstterm>live
+ properties</firstterm>.</para>
</listitem>
</varlistentry>
@@ -97,538 +107,679 @@
<term>Locking</term>
<listitem>
<para>A WebDAV server may decide to offer a locking
- feature to clients—this part of the specification
- is optional, although most WebDAV servers do offer the
- feature. If present, then clients can use the new
- <literal>LOCK</literal> and <literal>UNLOCK</literal>
- methods to mediate access to a resource. In most cases
- these methods are used to create exclusive write locks
- (as discussed in <xref linkend="svn-ch-2-sect-2.2"/>),
- although shared write locks are also possible.</para>
+ feature to clients—this part of the
+ specification is optional, although most WebDAV
+ servers do offer the feature. If present, then
+ clients can use the new <literal>LOCK</literal> and
+ <literal>UNLOCK</literal> methods to mediate access to
+ a resource. In most cases these methods are used to
+ create exclusive write locks (as discussed in <xref
+ linkend="svn-ch-2-sect-2.2"/>), although shared write
+ locks are also possible in some server
+ implementations.</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>Access control</term>
+ <listitem>
+ <para>A more recent specification (RFC 3744) defines a
+ system for defining access control lists (ACLs) on
+ WebDAV resources. Some clients and servers have begun
+ to implement this feature.</para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
-
+
</sect2>
-
+
<sect2 id="svn-ap-c-sect-1.2">
<title>DeltaV Extensions</title>
-
+
<para>Because RFC 2518 left out versioning concepts, another
- capable group was left with the responsibility of writing RFC
- 3253, which adds versioning to WebDAV. WebDAV/DeltaV clients
- and servers are often called just <quote>DeltaV</quote>
- clients and servers, since DeltaV implies the existence of
- basic WebDAV.</para>
+ committee was left with the responsibility of writing RFC
+ 3253, which adds versioning to WebDAV,
+ a.k.a. <quote>DeltaV</quote>. WebDAV/DeltaV clients and
+ servers are often called just <quote>DeltaV</quote> programs,
+ since DeltaV implies the existence of basic WebDAV.</para>
<para>DeltaV introduces a whole slew of new acronyms, but don't
- be intimidated. The ideas are fairly straightforward. Here
- are the new concepts and methods introduced in DeltaV:</para>
+ be intimidated. The ideas are fairly straightforward:</para>
<variablelist>
-
+
<varlistentry>
<term>Per-resource versioning</term>
<listitem>
- <para>Like CVS and other version-control systems, DeltaV
- assumes that each resource has a potentially infinite
- number of states. A client begins by placing a resource
- under version control using the new
- <literal>VERSION-CONTROL</literal> method. This creates
- a new Version Controlled Resource (VCR). Every time you
- change the VCR (via <literal>PUT</literal>,
- <literal>PROPPATCH</literal>, etc.), a new state of the
- resource is created, called a Version Resource (VR).
- VCRs and VRs are still ordinary web resources, defined
- by URLs. Specific VRs can have human-friendly names as
- well.</para>
+ <para> Like CVS and other version-control systems,
+ DeltaV assumes that each resource has a potentially
+ infinite number of states. A client begins by placing
+ a resource under version control using the new
+ <literal>VERSION-CONTROL</literal> method.</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>Server-side working-copy model</term>
<listitem>
- <para>Some DeltaV servers support the ability to create a
- virtual <quote>workspace</quote> on the server, where
- all of your work is performed. Clients use the
+ <para>Some DeltaV servers support the ability to create
+ a virtual workspace on the server, where all of your
+ work is performed. Clients use the
<literal>MKWORKSPACE</literal> method to create a
- private area, then indicate they want to change specific
- VCRs by <quote>checking them out</quote> into the
- workspace, editing them, and <quote>checking them
- in</quote> again. In HTTP terms, the sequence of
+ private area, then indicate they want to change
+ specific resources by <quote>checking them out</quote>
+ into the workspace, editing them, and <quote>checking
+ them in</quote> again. In HTTP terms, the sequence of
methods would be <literal>CHECKOUT</literal>,
- <literal>PUT</literal>, <literal>CHECKIN</literal>.
- After each <literal>CHECKIN</literal>, a new VR is
- created, and the edited VCR's contents now <quote>point
- to</quote> the latest VR. Each VCR has also has a
- <quote>history</quote> resource which tracks and orders
- its various VR states.</para>
+ <literal>PUT</literal>,
+ <literal>CHECKIN</literal>.</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>Client-side working-copy model</term>
<listitem>
<para>Some DeltaV servers also support the idea that the
- client may have a private working copy full of
- specific VRs. (This is how CVS and Subversion work.)
+ client may have a private working copy on local disk.
When the client wants to commit changes to the server,
it begins by creating a temporary server transaction
- (called an activity) with the
+ (called an <firstterm>activity</firstterm>) with the
<literal>MKACTIVITY</literal> method. The client then
- performs a <literal>CHECKOUT</literal> on each VR it
- wishes to change, which creates a number of temporary
- <quote>working resources</quote> in the activity, that
- can be modified using <literal>PUT</literal> and
- <literal>PROPPATCH</literal> methods. Finally, the
- client performs a <literal>CHECKIN</literal> on each
- working resource, which creates a new VR within each
- VCR, and the entire activity is deleted.</para>
+ performs a <literal>CHECKOUT</literal> on each
+ resource it wishes to change and sends
+ <literal>PUT</literal> requests. Finally, the client
+ performs a <literal>CHECKIN</literal> resource, or
+ sends a <literal>MERGE</literal> request to check in
+ all resources at once.</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>Configurations</term>
<listitem>
<para>DeltaV allows you define flexible collections of
- VCRs called <quote>configurations</quote>, which don't
- necessarily correspond to particular directories. Each VCR's
- contents can be made to point to a specific VR using the
- <literal>UPDATE</literal> method. Once the configuration
- is perfect, the client can create a
- <quote>snapshot</quote> of the whole configuration, called
- a <quote>baseline</quote>. Clients use the
- <literal>CHECKOUT</literal> and <literal>CHECKIN</literal>
- methods to capture specific states of configurations, much
- like they use these methods to create specific VR states
- of VCRs.</para>
+ resources called <quote>configurations</quote>, which
+ don't necessarily correspond to particular
+ directories. A configuration can be made to point to
+ specific versions of files, and then a
+ <quote>baseline</quote> snapshot can be made, much
+ like a tag.</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>Extensibility</term>
<listitem>
<para>DeltaV defines a new method,
<literal>REPORT</literal>, which allows the client and
- server to perform customized data exchanges. The client
- sends a <literal>REPORT</literal> request with a
+ server to perform customized data exchanges. While
+ DeltaV defines a number of standardized history reports
+ that a client can request, the the server is also free
+ to define custom reports. The client sends a
+ <literal>REPORT</literal> request with a
properly-labeled XML body full of custom data; assuming
the server understands the specific report-type, it
- responds with an equally custom XML body. This technique
- is very similar to XML-RPC.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Autoversioning</term>
- <listitem>
- <para>For many, this is the <quote>killer</quote> feature
- of DeltaV. If the DeltaV server supports this feature,
- then basic WebDAV clients (i.e. those unaware of
- versioning) can still write to the server, and the server
- will silently perform versioning anyway. In the simplest
- example, an ignorant <literal>PUT</literal> from a basic
- WebDAV client might be translated by the server as a
- <literal>CHECKOUT</literal>, <literal>PUT</literal>,
- <literal>CHECKIN</literal>.</para>
+ responds with an equally custom XML body. This
+ technique is very similar to XML-RPC.</para>
</listitem>
</varlistentry>
</variablelist>
+
+ </sect2>
- </sect2>
-
</sect1>
-
+
<sect1 id="svn-ap-c-sect-2">
<title>Subversion and DeltaV</title>
-
- <para>So how <quote>compatible</quote> is Subversion with other
- DeltaV software? In two words: not very. At least not yet, not
- in Subversion 1.0.</para>
-
- <para>While libsvn_ra_dav sends DeltaV requests to the server, the
- Subversion client is <emphasis>not</emphasis> a general-purpose
- DeltaV client. In fact, it expects some custom features from
- the server (especially through custom <literal>REPORT</literal>
- requests). Further, mod_dav_svn is <emphasis>not</emphasis> a
- general-purpose DeltaV server. It only implements a strict
- subset of the DeltaV specification. A more general WebDAV or
- DeltaV client may very well be able to interoperate against it,
- but only if that client operates within the narrow confines of
- those features that the server has implemented. The Subversion
- development team plans to address general WebDAV
- interoperability in a future release of Subversion.</para>
- <sect2 id="svn-ap-c-sect-2.1">
- <title>Mapping Subversion to DeltaV</title>
-
- <para>Here is a very <quote>high-level</quote> description of
- how various Subversion client operations use DeltaV. In many
- cases, these explanations are gross oversimplifications. They
- should <emphasis>not</emphasis> be taken as a substitute for
- reading Subversion's source code or talking with its
- developers.</para>
-
- <variablelist>
+ <para>The original WebDAV standard has been widely successful.
+ Every modern computer operating system has a general WebDAV
+ client built-in (details to follow), and a number of popular
+ standalone applications are also able to speak WebDAV —
+ Microsoft Office, Dreamweaver, and Photoshop to name a few. On
+ the server end, the Apache webserver has been able to provide
+ WebDAV services since 1998 and is considered the de-facto
+ open-source standard. There are several other commercial WebDAV
+ servers available, including Microsoft's own IIS.</para>
+
+ <para>DeltaV, unfortunately, has not been so successful. It's
+ very difficult to find any DeltaV clients or servers. The few
+ that do exist are relatively unknown commercial products, and
+ thus it's very difficult to test interoperability. It's not
+ entirely clear as to why DeltaV has remained stagnant. Some
+ argue that the specification is just too complex, others argue
+ that while WebDAV's features have mass appeal (even the least
+ technical users appreciate network file-sharing), version
+ control features aren't interesting or necessary for most users.
+ Finally, some have argued that DeltaV remains unpopular because
+ there's still no open-source server product which implements
+ it.</para>
+
+ <para>When Subversion was still in its design phase, it seemed
+ like a great idea to use Apache httpd as the main network
+ server. It already had a module to provide WebDAV services.
+ DeltaV was a relatively new specification. The hope was that
+ the Subversion server module (mod_dav_svn) would eventually
+ evolve into an open-source DeltaV reference implementation.
+ Unfortunately, DeltaV has a very specific versioning model that
+ doesn't quite line up with Subversion's model. Some concepts
+ were mappable, others were not.</para>
+
+ <para>The upshot is that</para>
+
+ <orderedlist>
+
+ <listitem>
+ <para>The Subversion client is not a fully-implemented DeltaV
+ client.</para>
- <varlistentry>
- <term>svn checkout/list</term>
- <listitem>
- <para>
- Perform a <literal>PROPFIND</literal> of depth 1 on the
- collection to get a list of immediate children. Perform
- a <literal>GET</literal> (and possibly a
- <literal>PROPFIND</literal>) on each child. Recurse
- into collections and repeat.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>svn commit</term>
- <listitem>
- <para>
- Create an activity with <literal>MKACTIVITY</literal>,
- and do a <literal>CHECKOUT</literal> of each changed
- item, followed by a <literal>PUT</literal> of new data.
- Finally, a <literal>MERGE</literal> request causes an
- implicit <literal>CHECKIN</literal> of all working
- resources.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>svn update/switch/status/merge/diff</term>
- <listitem>
- <para>
- Send a custom <literal>REPORT</literal> request that
- describes the mixed-revision (and mixed-URL) state of
- the working copy. The server sends a custom response
- that describes which items need updating and includes
- binary deltas of file contents. Parses the response.
- For updates and switches, install the new data in the
- working copy. For diff and merge commands, compare the
- data to the working copy, possibly applying changes as
- local modifications.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- </sect2>
-
- <sect2 id="svn-ap-c-sect-2.2">
- <title>Autoversioning Support</title>
-
- <para>At the time of writing, the truth is that there are very
- few DeltaV clients in the world; RFC 3253 is still relatively
- new. However users do have access to <quote>generic</quote>
- clients, because almost every modern operating system now has
- an integrated basic WebDAV client. With this in mind,
- Subversion developers realized that if Subversion 1.0 was to
- have <emphasis>any</emphasis> interoperability features,
- support for DeltaV autoversioning would be the best
- approach.</para>
-
- <para>To activate autoversioning in mod_dav_svn, use the
- <literal>SVNAutoversioning</literal> directive within the
- <filename>httpd.conf</filename> <literal>Location</literal>
- block, like so:</para>
+ <para>The client needs certain things from the server that
+ DeltaV cannot provide, and thus is largely dependent on a
+ number of Subversion-specific <literal>REPORT</literal>
+ requests that only mod_dav_svn understands.</para>
+ </listitem>
+
+ <listitem>
+ <para>mod_dav_svn is not a fully-implemented DeltaV server.</para>
+
+ <para>Many portions of the DeltaV specification were irrelevant to
+ Subversion, and thus left unimplemented.</para>
+ </listitem>
- <screen>
-<Location /repos>
- DAV svn
- SVNPath /absolute/path/to/repository
- SVNAutoversioning on
-</Location>
-</screen>
+ </orderedlist>
- <para>Normally, if a generic WebDAV client attempted a
- <literal>PUT</literal> to a path within your repository
- location, mod_dav_svn would outright reject the request. (It
- normally only allows such operations on <quote>working
- resources</quote> within DeltaV <quote>activities</quote>.)
- With <literal>SVNAutoversioning</literal> turned on, however,
- the server interprets the <literal>PUT</literal> request as an
- internal <literal>MKACTIVITY</literal>,
- <literal>CHECKOUT</literal>, <literal>PUT</literal>, and
- <literal>CHECKIN</literal>. A generic log message is
- auto-generated, and a new filesystem revision is
- created.</para>
-
- <para>Because so many operating systems already have integrated
- WebDAV abilities, the use case for this feature borders on
- fantastical: imagine an office of ordinary users running
- Microsoft Windows or Mac OS. Each computer
- <quote>mounts</quote> the Subversion repository, which appears
- to be an ordinary network share. They use the server as they
- always do: open files from the server, edit them, and
- save them back to the server. But in this fantasy, the server
- is automatically versioning everything. Later on, a sysadmin
- can use a Subversion client to search and retrieve all older
- versions.</para>
-
- <para>Is this fantasy real? Not quite. The main snag is that
- Subversion 1.0 has no support whatsoever for the WebDAV
- <literal>LOCK</literal> or <literal>UNLOCK</literal> methods.
- Most operating system DAV clients attempt to
- <literal>LOCK</literal> a resource opened directly from a
- DAV-mounted network share. For now, users may have to copy a
- file from the DAV share to local disk, edit the file, then
- copy it back again. Not ideal autoversioning, but still
- doable.</para>
+ <para>There is still some debate in the developer community as to
+ whether or not it's worthwhile to remedy either of these
+ situations. It's fairly unrealistic to change Subversion's
+ design to match DeltaV, so there's probably no way the client
+ can ever learn to get everything it needs from a general DeltaV
+ server. On the other hand, mod_dav_svn *could* be further
+ developed to implement all of DeltaV, but it's hard to find
+ motivation to do so — here are almost no DeltaV clients to
+ interoperate with.</para>
- </sect2>
+ </sect1>
- <sect2 id="svn-ap-c-sect-2.3">
- <title>The mod_dav_lock Alternative</title>
-
- <para>The mod_dav Apache module is a complex beast: it
- understands and parses all of the WebDAV and DeltaV methods,
- yet it depends on a back-end <quote>provider</quote> to
- access the resources themselves.</para>
-
- <para>In its simplest incarnation, a user can use mod_dav_fs as
- a provider for mod_dav. mod_dav_fs uses the ordinary
- filesystem to store files and directories, and only
- understands vanilla WebDAV methods, not DeltaV.</para>
-
- <para>Subversion, on the other hand, uses mod_dav_svn as a
- provider for mod_dav. mod_dav_svn understands all WebDAV
- methods except <literal>LOCK</literal>, and understands a
- sizable subset of DeltaV methods. It accesses data in the
- Subversion repository, rather than in the real filesystem.
- Subversion 1.0 doesn't support locking, because it would
- actually be quite difficult to implement, since Subversion uses
- the copy-modify-merge model.<footnote><para>Subversion may
- someday develop a reserved-checkout locking model that can
- live peaceably with copy-modify-merge, but it probably won't
- happen soon.</para></footnote></para>
-
- <para>In Apache httpd-2.0, mod_dav supports the
- <literal>LOCK</literal> method by tracking locks in a private
- database, assuming that the provider is willing to accept
- them. In Apache httpd-2.1 or later, however, this locking
- support has been broken into an independent module,
- mod_dav_lock. It allows any mod_dav provider to take
- advantage of the lock database, including mod_dav_svn, even
- though mod_dav_svn doesn't actually understand locking.</para>
-
- <para>Confused yet?</para>
-
- <para>In a nutshell, you can use mod_dav_lock in Apache
- httpd-2.1 (or later) to create the
- <emphasis>illusion</emphasis> that mod_dav_svn is honoring
- <literal>LOCK</literal> requests. Make sure mod_dav_lock is
- either compiled into httpd, or being loaded in your
- <filename>httpd.conf</filename>. Then simply add the
- <literal>DAVGenericLockDB</literal> directive to your
- <literal>Location</literal> like so:</para>
+ <sect1 id="svn-ap-c-sect-3">
+ <title>Autoversioning </title>
+
+ <para>All is not lost. There's still a bright gleam of
+ interoperability around this cloud, one which justifies
+ Subversion's original adoption of WebDAV: it's called
+ autoversioning.</para>
+
+ <para>Autoversioning is an optional feature defined in the DeltaV
+ standard. A typical DeltaV server will reject an ignorant
+ WebDAV client attempting to do a <literal>PUT</literal> to a
+ file that's under version control. To change a
+ version-controlled file, the server expects a series proper
+ versioning requests: something like
+ <literal>MKACTIVITY</literal>, <literal>CHECKOUT</literal>,
+ <literal>PUT</literal>, <literal>CHECKIN</literal>. But if the
+ DeltaV server supports autoversioning, then write-requests from
+ basic WebDAV clients are accepted. The server behaves *as if*
+ the client had issued the proper series of versioning requests,
+ peforming a commit under the hood. In other words, it allows a
+ DeltaV server to interoperate with ordinary WebDAV
+ clients.</para>
+
+ <para>Because so many operating systems already have integrated
+ WebDAV clients, the use case for this feature borders on
+ fantastical: imagine an office of ordinary users running
+ Microsoft Windows or Mac OS. Each user <quote>mounts</quote>
+ the Subversion repository, which appears to be an ordinary
+ network folder. They use the shared folder as they always do:
+ open files, edit them, save them. Meanwhile, the server is
+ automatically versioning everything. Any administrator (or
+ knowledgeable user) can still use a Subversion client to search
+ history and retrieve older versions of data.</para>
+
+ <para>This scenario isn't fiction: it's real and it works, as of
+ Subversion 1.2 and later. To activate autoversioning in
+ mod_dav_svn, use the <literal>SVNAutoversioning</literal>
+ directive within the <filename>httpd.conf</filename> Location
+ block, like so:</para>
<screen>
<Location /repos>
DAV svn
- SVNPath /absolute/path/to/repository
+ SVNPath /path/to/repository
SVNAutoversioning on
- DavGenericLockDB /path/to/store/locks
</Location>
</screen>
- <para>This technique is a risky business; in some sense, the
- mod_dav_svn is now lying to the WebDAV client. It claims to
- accept the <literal>LOCK</literal> request, but in reality the
- lock isn't being enforced at all levels. If a second WebDAV
- client attempts to <literal>LOCK</literal> the same resource,
- then mod_dav_lock will notice and correctly deny the request.
- But there's absolutely nothing preventing an ordinary
- Subversion client from changing the file via a normal
- <command>svn commit</command>! If you use this technique,
- you're giving users the opportunity to stomp on each others'
- changes. In particular, a WebDAV client might accidentally
- overwrite a change committed by a regular Subversion client.</para>
-
- <para>On the other hand, if you set up your environment very
- carefully, you may mitigate the risk. For example, if
- <emphasis>all</emphasis> of your users are working though
- basic WebDAV clients (rather than Subversion clients), then
- things should be fine.</para>
- </sect2>
-
+ <para>When SVNAutoversioning is active, write requests from WebDAV
+ clients result in automatic commits. A generic log message is
+ auto-generated and attached to each revision.</para>
+
+ <para>Before activating this feature, however, understand what
+ you're getting into. WebDAV clients tend to do
+ <emphasis>many</emphasis> write requests, resulting in a huge
+ number of automatically committed revisions. For example, when
+ saving data, many clients will do a <literal>PUT</literal> of a
+ 0-byte file (as a way of reserving a name) followed by another
+ <literal>PUT</literal> with the real filedata. The single
+ file-write results in two separate commits. Also consider that
+ many applications auto-save every few minutes, resulting in even
+ more commits.</para>
+
+ <para>If you have a post-commit hook program that sends email, for
+ example, you may want to disable email generation either
+ altogether, or on certain sections of the repository; it depends
+ on whether you think the influx of emails will still prove to be
+ valuable notifications or not. Also, a smart post-commit hook
+ program can distinguish between a transaction created via
+ autoversioning and one created through a normal <command>svn
+ commit</command>. The trick is to look for a revision property
+ named <literal>svn:autoversioned</literal>. If present, the
+ commit was made by a generic WebDAV client.</para>
+
</sect1>
-
- <sect1 id="svn-ap-c-sect-3">
- <title>Autoversioning Interoperability</title>
- <para>In this section, we'll describe the most common generic
- WebDAV clients (at the time of writing), and how well they
- operate against a mod_dav_svn server using the
- <literal>SVNAutoversioning</literal> directive. RFC 2518 is a
- bit large, and perhaps a bit too flexible. Every WebDAV
- client behaves slightly differently, and creates slightly
- different problems.</para>
-
- <!-- list of subsections goes here. -->
-
- <sect2 id="svn-ap-c-sect-3.1">
- <title>Win32 WebFolders</title>
-
- <para>Windows 98, 2000, and XP have an integrated WebDAV client
- known as <quote>WebFolders</quote>. On Windows 98, the
- feature might need to be explicitly installed; if present, a
- <quote>WebFolders</quote> directory appears directly within My
- Computer. On Windows 2000 and XP, simply open My Network
- Places, and run the Add Network Place icon. When prompted,
- enter the WebDAV URL. The shared folder will appear within My
- Network Places.</para>
+ <sect1 id="svn-ap-c-sect-4">
+ <title>Client Interoperability</title>
- <para>Most write operations work fine against an autoversioning
- mod_dav_svn server, but there are a few problems:</para>
+ <para>In this section, we'll describe the most common WebDAV clients (at
+ the time of writing), and how well they operate against an
+ autoversioning mod_dav_svn server.</para>
- <itemizedlist>
+ <para>All WebDAV clients fall into one of three categories. These
+ categories are the main definers of what users can and cannot
+ do.</para>
- <listitem>
- <para>If a Windows XP computer is a member of an NT Domain,
- then it seems to be unable to connect to the WebDAV share.
- It repeatedly asks for a name and password, even when the
- Apache server isn't issuing an authentication challenge!
- If the machine isn't part of an NT Domain, then the share
- is mounted without a problem.</para>
-
- <para>This problem seems to stem from changes in the way
- Windows XP creates WebFolder shortcuts (
- <filename>.lnk</filename> files). It sometimes replaces
- the URL of the WebDAV share with a Windows
- <quote>UNC</quote> (Universal Naming Convention) path
- instead. This causes Explorer to attempt a connection
- using SMB instead of HTTP.</para>
-
- <para>A workaround for this problem is to create the
- <filename>.lnk</filename> shortcut on a Windows 2000
- computer and then copy this shortcut to the Windows XP
- computer. It would probably also be possible to
- <quote>fix</quote> the shortcut using a HEX editor, if
- one were to reverse-engineer the <filename>.lnk</filename>
- file format.</para>
- </listitem>
+ <variablelist>
+
+ <varlistentry>
+ <term>Standalone application</term>
<listitem>
- <para>A file can't be opened for direct editing from the
- share; it always comes up read-only. The mod_dav_lock
- technique doesn't help, because WebFolders doesn't use the
- <literal>LOCK</literal> method at all. The previously
- mentioned <quote>copy, edit, re-copy</quote> method does
- work, however. The file on the share can be successfully
- overwritten by a locally edited copy.</para>
+ <para>The WebDAV functionality is buried within a single
+ application. For example, Microsoft Word is able to open a
+ file directly from a URL. It locks the file when this
+ happens, and every subsequent <quote>save</quote> command
+ results in a PUT request.</para>
</listitem>
+ </varlistentry>
- </itemizedlist>
-
- </sect2>
+ <varlistentry>
+ <term>File-explorer extension</term>
- <sect2 id="svn-ap-c-sect-3.2">
- <title>Mac OS X</title>
+ <listitem>
+ <para>The WebDAV functionality is an extension to a GUI
+ program that is normally used to browse filesystems,
+ either local or remote. For example, Windows Explorer is
+ able to browse a WebDAV server as a <quote>network
+ place</quote>. Users can drag files to and from the
+ desktop, or can rename, copy, or delete files in the usual
+ way. But because it's only a feature of the
+ file-explorer, the DAV share isn't visible to ordinary
+ applications. All DAV interaction must happen through the
+ explorer interface.</para>
+ </listitem>
+ </varlistentry>
- <para>Apple's OS X operating system has an integrated WebDAV
- client. From the Finder, select the <quote>Connect to
- Server</quote> item from the Go menu. Enter a WebDAV URL,
- and it appears as a disk on the desktop, just like any file
- server.<footnote><para>Unix users can also run <command>mount
- -t webdav URL /mountpoint</command>.</para></footnote></para>
-
- <para>Unfortunately, this client refuses to work against an
- autoversioning mod_dav_svn because of its lack of
- <literal>LOCK</literal> support. Mac OS X discovers the
- missing <literal>LOCK</literal> ability during the initial
- HTTP <literal>OPTIONS</literal> feature exchange, and thus
- decides to mount the Subversion repository as a read-only
- share. After that, no write operations are possible at all.
- In order to mount the repository as a read-write share, you
- <emphasis>must</emphasis> use the mod_dav_lock trick discussed
- previously. Once locking seems to work, the share behaves
- very nicely: files can be opened directly in read/write mode,
- although each save operation will cause the client to do a
- <literal>PUT</literal> to a temporary location, a
- <literal>DELETE</literal> of original file, and a
- <literal>MOVE</literal> of the temporary resource to the
- original filename. That's three new Subversion revisions per
- save!</para>
-
- <para>One more word of warning: OS X's WebDAV client can be
- overly sensitive to HTTP redirects. If you're unable to mount
- the repository at all, you may need to enable the
- <literal>BrowserMatch</literal> directive in your
- <filename>httpd.conf</filename>:</para>
+ <varlistentry>
+ <term>Filesystem implementation</term>
- <screen>
-BrowserMatch "^WebDAVFS/1.[012]" redirect-carefully
-</screen>
+ <listitem>
+ <para>This the best sort of WebDAV client. It's implemented
+ as a low-level filesystem (typically within the operating
+ system's kernel.) This means that the DAV share is
+ mounted like any other network filesystem, similar to
+ mounting an NFS share on Unix, or attaching an SMB share
+ as drive-letter in Windows. As a result, this sort of
+ client provides completely transparent read/write WebDAV
+ access to all programs. Applications aren't even aware
+ that WebDAV requests are happening.</para>
+ </listitem>
+ </varlistentry>
- </sect2>
+ </variablelist>
- <sect2 id="svn-ap-c-sect-3.3">
- <title>Unix: Nautilus 2</title>
+ <para>There are many WebDAV clients, far too many to list. Here
+ we provide some details about our experiences with some of the
+ more popular ones.</para>
+
+ <table id="svn-ap-c-table-1">
+ <title>Common WebDAV Clients</title>
+ <tgroup cols="4">
+ <thead>
+ <row>
+ <entry>DAV Client</entry>
+ <entry>Standalone</entry>
+ <entry>File-explorer</entry>
+ <entry>Filesystem</entry>
+ </row>
+ </thead>
+ <tbody>
+
+ <row>
+ <entry>Windows Webfolders</entry>
+ <entry></entry>
+ <entry>x</entry>
+ <entry>x</entry>
+ </row>
+
+ <row>
+ <entry>WebDrive</entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>x</entry>
+ </row>
+
+ <row>
+ <entry>NetDrive</entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>x</entry>
+ </row>
+
+ <row>
+ <entry>Mac OS X</entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>x</entry>
+ </row>
+
+ <row>
+ <entry>GNOME Nautilus</entry>
+ <entry></entry>
+ <entry>x</entry>
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>KDE Konqueror</entry>
+ <entry></entry>
+ <entry>x</entry>
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>Linux davfs2</entry>
+ <entry></entry>
+ <entry></entry>
+ <entry>x</entry>
+ </row>
+
+ <row>
+ <entry>Cadaver</entry>
+ <entry>x</entry>
+ <entry></entry>
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>DAV Explorer</entry>
+ <entry>x</entry>
+ <entry></entry>
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>Microsoft Office</entry>
+ <entry>x</entry>
+ <entry></entry>
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>Dreamweaver</entry>
+ <entry>x</entry>
+ <entry></entry>
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>Photoshop</entry>
+ <entry>x</entry>
+ <entry></entry>
+ <entry></entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table>
+
+ <sect2 id="svn-ap-c-sect-4.1">
+ <title>Windows Webfolders, WebDrive, Netdrive</title>
+
+ <para>Microsoft was one of the original backers of the WebDAV
+ specification, and first started shipping a client in Windows
+ 98, known as <quote>Webfolders</quote>. This client was also
+ shipped in Windows NT4 and 2000.</para>
+
+ <para>The original Webfolders client was an extension to
+ Explorer, the main GUI program used to browse filesystems. It
+ works well enough. In Windows 98, the feature might need to
+ be explicitly installed if Webfolders aren't already visible
+ inside <quote>My Computer</quote>. In Windows 2000, simply
+ add a new <quote>network place</quote>, enter the URL, and the
+ WebDAV share will pop up for browsing.</para>
+
+ <para>With the release of Windows XP, Microsoft started shipping
+ a new implementation of Webfolders, known as the <quote>WebDAV
+ mini-redirector</quote>. The new implementation is a
+ filesystem-level client, allowing WebDAV shares to be mounted
+ as drive letters. Unfortunately, this implementation is
+ incredibly buggy. The client usually tries to convert http
+ URLs (<literal>http://host/repos</literal>) into UNC share
+ notation (<literal>\\host\repos</literal>); it also often
+ tries to use Windows Domain authentication to respond to
+ basic-auth HTTP challenges, sending usernames as
+ <literal>HOST\username</literal>. These interoperability
+ problems are severe and documented in numerous places around
+ the web, to the frustration of many users. Even Greg Stein,
+ the original author of Apache's WebDAV module, recommends
+ against trying to use XP Webfolders against an Apache
+ server.</para>
+
+ <para>It turns out that the original
+ <quote>Explorer-only</quote> Webfolders implementation isn't
+ dead in XP, it's just buried. It's still possible to find it
+ by using this technique:</para>
- <para>Nautilus is the official file manager/browser for the
- GNOME desktop. Its main home page is at <systemitem
- class="url">http://www.gnome.org/projects/nautilus/</systemitem>.
- By simply typing a WebDAV URL into the Nautilus window,
- the DAV share appears like a local filesystem.</para>
+ <orderedlist>
- <para>In general, Nautilus 2 works reasonably well against an
- autoversioning mod_dav_svn, with the following caveats:</para>
+ <listitem>
+ <para>Go to 'Network Places'.</para>
+ </listitem>
- <itemizedlist>
+ <listitem>
+ <para>Add a new network place.</para>
+ </listitem>
<listitem>
- <para>Any files opened directly from the share are treated
- as read-only. Even the mod_dav_lock trick seems to have
- no effect. It seems that Nautilus never issues the
- <literal>LOCK</literal> method at all. The <quote>copy
- locally, edit, copy back</quote> trick does work, however.
- Unfortunately, Nautilus overwrites the old file by issuing
- a <literal>DELETE</literal> first, which creates an extra
- revision.</para>
+ <para>When prompted, enter the URL of the repository, but
+ <emphasis>include a port number</emphasis> in the URL.
+ For example, <literal>http://host/repos</literal> would be
+ entered as <literal>http://host:80/repos</literal> instead.
+ </para>
</listitem>
<listitem>
- <para>When overwriting or creating a file , Nautilus first
- does a <literal>PUT</literal> of an empty file, then
- overwrites it with a second <literal>PUT</literal>. This
- creates two Subversion filesystem revisions, rather than
- one.</para>
+ <para>Respond to any authentication prompts.</para>
</listitem>
+ </orderedlist>
+
+ <para>There are a number of other rumored workarounds to the
+ problems, but none of them seem to work on all versions and
+ patchlevels of Windows XP. In our tests, only the previous
+ algorithm seems to work consistently on every system. The
+ general consensus of the WebDAV community is:</para>
+
+ <itemizedlist>
<listitem>
- <para>When deleting a collection, it issues an HTTP
- <literal>DELETE</literal> on each individual child instead
- of on the collection itself. This creates a whole bunch of
- new revisions.</para>
+ <para>Avoid the new Webfolders implementation, use the old
+ one.</para>
</listitem>
+ <listitem>
+ <para>If you need real a real filesystem-level client for
+ Windows XP, then use either WebDrive or NetDrive.</para>
+ </listitem>
</itemizedlist>
+ <para>Both WebDrive and NetDrive are excellent commercial
+ products which allows a WebDAV share to be attached as drive
+ letters. We've had nothing but success with these products.
+ At the time of writing, WebDrive can be purchased from South
+ River Technologies (<ulink
+ url="http://www.southrivertech.com"/>). NetDrive ships with
+ Netware, is free of charge, and can be found by searching the
+ web for <quote>netdrive.exe</quote>. (If that sounds odd to
+ you, you're not alone. See this page on Novell's website:
+ <ulink
+ url="http://www.novell.com/coolsolutions/qna/999.html"/>)</para>
+
+ </sect2>
+
+
+ <sect2 id="svn-ap-c-sect-4.2">
+ <title>Mac OS X</title>
+
+ <para>Apple's OS X operating system has an integrated
+ filesystem-level WebDAV client. From the Finder, select the
+ "Connect to Server" item from the Go menu. Enter a WebDAV
+ URL, and it appears as a disk on the desktop, just like any
+ other mounted volume.<footnote><para>From the Darwin terminal,
+ one can also run <literal>mount -t webdav URL
+ /mountpoint</literal></para></footnote>.</para>
+
+ <para>Note that if your mod_dav_svn is older than version 1.2,
+ OS X will refuse to mount the share as read-write; it will
+ appear as read-only. This is because the OS X insists on
+ locking support for read-write shares, and the ability to lock
+ files first appeared in Subversion 1.2.</para>
+
+ <para>One more word of warning: OS X's WebDAV client can
+ sometimes be overly sensitive to HTTP redirects. If OS X is
+ unable to mount the repository at all, you may need to enable
+ the BrowserMatch directive in the Apache server's
+ <filename>httpd.conf</filename>:</para>
+
+ <screen>
+ BrowserMatch "^WebDAVFS/1.[012]" redirect-carefully
+</screen>
+
</sect2>
- <sect2 id="svn-ap-c-sect-3.4">
- <title>Linux davfs2</title>
+
+ <sect2 id="svn-ap-c-sect-4.3">
+ <title>Nautilus, Konqueror</title>
+
+ <para>Nautilus is the official file manager/browser for the
+ GNOME desktop (<ulink url="http://www.gnome.org"/>), and
+ Konqueror is the manager/browser for KDE desktop (<ulink
+ url="http://www.kde.org"/>). Both of these applications have
+ an explorer-level WebDAV client built-in, and operate just
+ fine against an autoversioning repository.</para>
+
+ <para>In GNOME's Nautilus, from the File menu, select
+ <quote>Open location</quote> and enter the URL. The
+ repository should then be displayed like any other
+ filesystem.</para>
+
+ <para>In KDE's Konqueror, you need to use the
+ <literal>webdav://</literal> scheme when entering the URL in
+ the location bar. If you enter an <literal>http://</literal>
+ URL, Konqueror will behave like an ordinary web browser.
+ You'll likely see the generic HTML directory listing produced
+ by mod_dav_svn. By entering
+ <literal>webdav://host/repos</literal> instead of
+ <literal>http://host/repos</literal>, Konqueror becomes a
+ WebDAV client and displays the repository as a
+ filesystem.</para>
+
+ </sect2>
+
+ <sect2 id="svn-ap-c-sect-4.4">
+ <title>Linux davfs2</title>
<para>Linux davfs2 is a filesystem module for the Linux kernel,
- whose development is located at <systemitem
- class="url">http://dav.sourceforge.net/</systemitem>. Once
- installed, a WebDAV network share can be mounted with the
- usual Linux <command>mount</command> command.</para>
-
- <para>The word on the street is that this DAV client doesn't
- work at all with mod_dav_svn's autoversioning. Every single
- attempt to write to the server is preceded by a
- <literal>LOCK</literal> request, which mod_dav_svn doesn't
- support. At this time, there is no data indicating whether
- the use of mod_dav_lock resolves this problem.</para>
+ whose development is located at <ulink
+ url="http://dav.sourceforge.net/"/>. Once installed, a WebDAV
+ network share can be mounted with the usual Linux mount
+ command:</para>
+
+ <screen>
+ mount.davfs http://host/repos /mnt/dav
+</screen>
+
+ </sect2>
+
+ <sect2 id="svn-ap-c-sect-4.5">
+ <title>Cadaver, DAV Explorer</title>
+
+ <para>Cadaver is a bare-bones Unix commandline program for
+ browsing and changing WebDAV shares. Like the Subversion
+ client, it uses the neon HTTP library — not
+ surprisingly, both neon and cadaver are written by the same
+ author. Cadaver is free sofware (GPL license) and is
+ available at <ulink
+ url="http://www.webdav.org/cadaver/"/>.</para>
+
+ <para>Using cadaver is similar to using a commandline FTP
+ program, and thus it's extremely useful for basic WebDAV
+ debugging. It can be used to upload or download files in a
+ pinch, and also to examine properties, copy, move, lock or
+ unlock files:</para>
+
+ <screen>
+ $ cadaver http://host/repos
+ dav:/repos/> ls
+ Listing collection `/repos/': succeeded.
+ Coll: > foobar 0 May 10 16:19
+ > playwright.el 2864 May 4 16:18
+ > proofbypoem.txt 1461 May 5 15:09
+ > westcoast.jpg 66737 May 5 15:09
+
+ dav:/repos/> put README
+ Uploading README to `/repos/README':
+ Progress: [=============================>] 100.0% of 357 bytes succeeded.
+
+ dav:/repos/> get proofbypoem.txt
+ Downloading `/repos/proofbypoem.txt' to proofbypoem.txt:
+ Progress: [=============================>] 100.0% of 1461 bytes succeeded.
+</screen>
+
+ <para>DAV Explorer is another standalone WebDAV client, written
+ in Java. It's under a free Apache-like license and is
+ available at <ulink url="http://www.ics.uci.edu/~webdav/"/>.
+ DAV Explorer does everything cadaver does, but has the
+ advantages of being portable and being more user-friendly GUI
+ application. It's also one of the first clients to support
+ the new WebDAV Access Control Protocol (RFC 3744).</para>
+
+ <para>Of course, DAV Explorer's ACL support is useless in this
+ case, since mod_dav_svn doesn't support it. The fact that
+ both Cadaver and DAV Explorer support some limited DeltaV
+ commands isn't particularly useful either, since they don't
+ allow <literal>MKACTIVITY</literal> requests. But it's not
+ relevant anyway; we're assuming all of these clients are
+ operating against an autoversioning repository.</para>
+
+ </sect2>
+
+ <sect2 id="svn-ap-c-sect-4.6">
+ <title>Microsoft Office, Dreamweaver, Photoshop</title>
+
+ <para>These are large well-known applications that contain
+ integrated WebDAV client functionality. They're able to
+ directly open a URL, save to a URL, and tend to make heavy use
+ of WebDAV locks when editing a file.</para>
+
+ <para>It appears that only the Windows versions of these
+ programs support WebDAV. On Mac OS X, the
+ <quote>File->Open</quote> dialog box doesn't allow one to type
+ a path or URL at all. It's likely that the the WebDAV
+ features were deliberately left out of Macintosh versions of
+ these programs, since OS X already provides such excellent
+ low-level filesystem support for WebDAV.</para>
</sect2>
More information about the svnbook-dev
mailing list