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