granicus.if.org Git - apache/blob - docs/manual/mod/mod_dav.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $Revision: 1.11 $ -->
   5
   6 <!--
   7  Copyright 2002-2004 The Apache Software Foundation
   8
   9  Licensed under the Apache License, Version 2.0 (the "License");
  10  you may not use this file except in compliance with the License.
  11  You may obtain a copy of the License at
  12
  13      http://www.apache.org/licenses/LICENSE-2.0
  14
  15  Unless required by applicable law or agreed to in writing, software
  16  distributed under the License is distributed on an "AS IS" BASIS,
  17  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18  See the License for the specific language governing permissions and
  19  limitations under the License.
  20 -->
  21
  22 <modulesynopsis metafile="mod_dav.xml.meta">
  23
  24 <name>mod_dav</name>
  25 <description>Distributed Authoring and Versioning
  26 (<a href="http://www.webdav.org/">WebDAV</a>) functionality</description>
  27 <status>Extension</status>
  28 <sourcefile>mod_dav.c</sourcefile>
  29 <identifier>dav_module</identifier>
  30
  31 <summary>
  32     <p>This module provides class 1 and class 2 <a
  33     href="http://www.webdav.org">WebDAV</a> ('Web-based Distributed
  34     Authoring and Versioning') functionality for Apache. This
  35     extension to the HTTP protocol allows creating, moving,
  36     copying, and deleting resources and collections on a remote web
  37     server.</p>
  38 </summary>
  39 <seealso><directive module="mod_dav_fs">DavLockDB</directive></seealso>
  40 <seealso><directive module="core">LimitXMLRequestBody</directive></seealso>
  41 <seealso><a href="http://www.webdav.org">WebDAV Resources</a></seealso>
  42
  43 <section id="example"><title>Enabling WebDAV</title>
  44     <p>To enable <module>mod_dav</module>, add the following to a
  45     container in your <code>httpd.conf</code> file:</p>
  46
  47     <example>Dav On</example>
  48
  49     <p>This enables the DAV file system provider, which is implemented
  50     by the <module>mod_dav_fs</module> module. Therefore, that module
  51     must be compiled into the server or loaded at runtime using the
  52     <directive module="mod_so">LoadModule</directive> directive.</p>
  53
  54     <p>In addition, a location for the DAV lock database must be
  55     specified in the global section of your <code>httpd.conf</code>
  56     file using the <directive module="mod_dav_fs">DavLockDB</directive>
  57     directive:</p>
  58
  59     <example>
  60       DavLockDB /usr/local/apache2/var/DavLock
  61     </example>
  62
  63     <p>The directory containing the lock database file must be
  64     writable by the <directive module="mpm_common">User</directive>
  65     and <directive module="mpm_common" >Group</directive> under which
  66     Apache is running.</p>
  67
  68     <p>You may wish to add a <directive module="core" type="section"
  69     >Limit</directive> clause inside the <directive module="core"
  70     type="section">Location</directive> directive to limit access to
  71     DAV-enabled locations. If you want to set the maximum amount of
  72     bytes that a DAV client can send at one request, you have to use
  73     the <directive module="core">LimitXMLRequestBody</directive>
  74     directive. The "normal" <directive module="core"
  75     >LimitRequestBody</directive> directive has no effect on DAV
  76     requests.</p>
  77
  78     <example><title>Full Example</title>
  79       DavLockDB /usr/local/apache2/var/DavLock<br />
  80       <br />
  81        &lt;Location /foo&gt;<br />
  82        <indent>
  83          Dav On<br />
  84          <br />
  85          AuthType Basic<br />
  86          AuthName DAV<br />
  87          AuthUserFile user.passwd<br />
  88          <br />
  89          &lt;LimitExcept GET OPTIONS&gt;<br />
  90          <indent>
  91            require user admin<br />
  92          </indent>
  93          &lt;/LimitExcept&gt;<br />
  94        </indent>
  95        &lt;/Location&gt;<br />
  96     </example>
  97
  98    <p><module>mod_dav</module> is a descendent of Greg Stein's <a
  99    href="http://www.webdav.org/mod_dav/">mod_dav for Apache 1.3</a>.  More
 100    information about the module is available from that site.</p>
 101 </section>
 102
 103 <section id="security"><title>Security Issues</title>
 104
 105     <p>Since DAV access methods allow remote clients to manipulate
 106     files on the server, you must take particular care to assure that
 107     your server is secure before enabling <module>mod_dav</module>.</p>
 108
 109     <p>Any location on the server where DAV is enabled should be
 110     protected by authentication.  The use of HTTP Basic Authentication
 111     is not recommended. You should use at least HTTP Digest
 112     Authentication, which is provided by the
 113     <module>mod_auth_digest</module> module. Nearly all WebDAV clients
 114     support this authentication method. An alternative is Basic
 115     Authentication over an <a href="../ssl/">SSL</a> enabled
 116     connection.</p>
 117
 118     <p>In order for <module>mod_dav</module> to manage files, it must
 119     be able to write to the directories and files under its control
 120     using the <directive module="mpm_common">User</directive> and
 121     <directive module="mpm_common">Group</directive> under which
 122     Apache is running.  New files created will also be owned by this
 123     <directive module="mpm_common">User</directive> and <directive
 124     module="mpm_common">Group</directive>.  For this reason, it is
 125     important to control access to this account.  The DAV repository
 126     is considered private to Apache; modifying files outside of Apache
 127     (for example using FTP or filesystem-level tools) should not be
 128     allowed.</p>
 129
 130     <p><module>mod_dav</module> may be subject to various kinds of
 131     denial-of-service attacks.  The <directive
 132     module="core">LimitXMLRequestBody</directive> directive can be
 133     used to limit the amount of memory consumed in parsing large DAV
 134     requests.  The <directive
 135     module="mod_dav">DavDepthInfinity</directive> directive can be
 136     used to prevent <code>PROPFIND</code> requests on a very large
 137     repository from consuming large amounts of memory.  Another
 138     possible denial-of-service attack involves a client simply filling
 139     up all available disk space with many large files.  There is no
 140     direct way to prevent this in Apache, so you should avoid giving
 141     DAV access to untrusted users.</p>
 142 </section>
 143
 144 <section id="complex"><title>Complex Configurations</title>
 145
 146     <p>One common request is to use <module>mod_dav</module> to
 147     manipulate dynamic files (PHP scripts, CGI scripts, etc).  This is
 148     difficult because a <code>GET</code> request will always run the
 149     script, rather than downloading its contents.  One way to avoid
 150     this is to map two different URLs to the content, one of which
 151     will run the script, and one of which will allow it to be
 152     downloaded and manipulated with DAV.</p>
 153
 154 <example>
 155 Alias /phparea /home/gstein/php_files<br />
 156 Alias /php-source /home/gstein/php_files<br />
 157 &lt;Location /php-source&gt;
 158 <indent>
 159     DAV On<br />
 160     ForceType text/plain<br />
 161 </indent>
 162 &lt;/Location&gt;
 163 </example>
 164
 165     <p>With this setup, <code>http://example.com/phparea</code> can be
 166     used to access the output of the PHP scripts, and
 167     <code>http://example.com/php-source</code> can be used with a DAV
 168     client to manipulate them.</p>
 169 </section>
 170
 171 <directivesynopsis>
 172 <name>Dav</name>
 173 <description>Enable WebDAV HTTP methods</description>
 174 <syntax>Dav On|Off|<var>provider-name</var></syntax>
 175 <default>Dav Off</default>
 176 <contextlist><context>directory</context></contextlist>
 177
 178 <usage>
 179     <p>Use the <directive>Dav</directive> directive to enable the
 180     WebDAV HTTP methods for the given container:</p>
 181
 182     <example>
 183       &lt;Location /foo&gt;<br />
 184       <indent>
 185         Dav On<br />
 186       </indent>
 187       &lt;/Location&gt;
 188     </example>
 189
 190     <p>The value <code>On</code> is actually an alias for the default
 191     provider <code>filesystem</code> which is served by the <module
 192     >mod_dav_fs</module> module. Note, that once you have DAV enabled
 193     for some location, it <em>cannot</em> be disabled for sublocations.
 194     For a complete configuration example have a look at the <a
 195     href="#example">section above</a>.</p>
 196
 197     <note type="warning">
 198       Do not enable WebDAV until you have secured your server. Otherwise
 199       everyone will be able to distribute files on your system.
 200     </note>
 201 </usage>
 202 </directivesynopsis>
 203
 204 <directivesynopsis>
 205 <name>DavMinTimeout</name>
 206 <description>Minimum amount of time the server holds a lock on
 207 a DAV resource</description>
 208 <syntax>DavMinTimeout <var>seconds</var></syntax>
 209 <default>DavMinTimeout 0</default>
 210 <contextlist><context>server config</context><context>virtual host</context>
 211 <context>directory</context></contextlist>
 212
 213 <usage>
 214     <p>When a client requests a DAV resource lock, it can also
 215     specify a time when the lock will be automatically removed by
 216     the server. This value is only a request, and the server can
 217     ignore it or inform the client of an arbitrary value.</p>
 218
 219     <p>Use the <directive>DavMinTimeout</directive> directive to specify, in
 220     seconds, the minimum lock timeout to return to a client.
 221     Microsoft Web Folders defaults to a timeout of 120 seconds; the
 222     <directive>DavMinTimeout</directive> can override this to a higher value
 223     (like 600 seconds) to reduce the chance of the client losing
 224     the lock due to network latency.</p>
 225
 226     <example><title>Example</title>
 227       &lt;Location /MSWord&gt;<br />
 228       <indent>
 229         DavMinTimeout 600<br />
 230       </indent>
 231       &lt;/Location&gt;
 232     </example>
 233 </usage>
 234 </directivesynopsis>
 235
 236 <directivesynopsis>
 237 <name>DavDepthInfinity</name>
 238 <description>Allow PROPFIND, Depth: Infinity requests</description>
 239 <syntax>DavDepthInfinity on|off</syntax>
 240 <default>DavDepthInfinity off</default>
 241 <contextlist><context>server config</context><context>virtual host</context>
 242 <context>directory</context></contextlist>
 243
 244 <usage>
 245     <p>Use the <directive>DavDepthInfinity</directive> directive to
 246     allow the processing of <code>PROPFIND</code> requests containing the
 247     header 'Depth: Infinity'. Because this type of request could constitute
 248     a denial-of-service attack, by default it is not allowed.</p>
 249 </usage>
 250 </directivesynopsis>
 251
 252 </modulesynopsis>
 253
 254