Caddy WebDAV Configuration: Subpath Mounting and Access Control

Nite included in Tutorials and Caddy Tutorial

2026-04-28 About 500 words 3 minutes

Contents

What is WebDAV

WebDAV (Web Distributed Authoring and Versioning) is an extension of the HTTP protocol that allows clients to upload, download, delete, move, and copy files via HTTP. Simply put: mount a remote filesystem over HTTP.

KDE Dolphin, Windows Explorer, and macOS Finder can mount WebDAV as a network drive natively - no extra client software needed.

Plugin Installation

The caddy-webdav plugin is included in the custom build. WebDAV needs to coexist with file_server, so adjust route priority in the global options:

{
    order webdav before file_server
}

This tells Caddy to let the webdav directive handle requests first, falling back to file_server for anything WebDAV can’t process. Without this line, file_server intercepts all requests, and WebDAV’s PROPFIND, MKCOL, and other methods never fire.

Basic Configuration

test.example.com {
    route {
        reverse_proxy 127.0.0.1:5002
    }

    route /dav/* {
        basic_auth {
            username xxx
        }
        webdav {
            root /path/to/webdav_dir
            prefix /dav
        }
    }
}

Configuration Breakdown

route blocks: Using route instead of declaring directives directly in the site block gives you control over execution order. The main service (reverse_proxy) and WebDAV use separate route blocks and don’t interfere with each other.

/dav/* path matching: WebDAV is only active under the /dav/ path, leaving the main site untouched. Users visiting https://test.example.com/ see the main app; visiting https://test.example.com/dav/ enters file management.

basic_auth: WebDAV exposes read-write access to the filesystem - authentication is mandatory. Here we use Caddy’s built-in basic_auth with bcrypt password hashes.

webdav block:

root: The filesystem root directory exposed by WebDAV
prefix: Tells the WebDAV handler that the /dav URL prefix maps to the root directory. When a client requests /dav/test.txt, the actual file accessed is /path/to/webdav_dir/test.txt

Generating bcrypt Passwords

basic_auth requires bcrypt-format password hashes. Caddy includes caddy hash-password:

caddy hash-password --plaintext "your-password"

# Output example:
# $2a$14$... (example hash — generate your own with caddy hash-password)

Caddy’s bcrypt uses cost 14 (2^14 iterations), which is slower but more secure than the default 10. Copy the generated hash directly into your Caddyfile.

Important Notes

Access Control

basic_auth in Caddy operates at the site level - once authenticated, a user can access all protected paths. Caddy itself doesn’t provide fine-grained file-level permissions. But if you have a fixed set of users, you can isolate WebDAV root directories per user like this:

test.example.com {
    route {
        reverse_proxy 127.0.0.1:5002
    }

    route /dav/* {
        basic_auth {
            user1 pass1
            user2 pass2
        }
        webdav {
            root /path/to/webdav_dir/{http.auth.user.id}
            prefix /dav
        }
    }
}

Upload Size Limit

When uploading large files via WebDAV, make sure Caddy’s request_body limit is large enough:

webdav.example.com {
    request_body {
        max_size 10000MB
    }
    webdav {
        root /srv/data
    }
}

Caddy’s default request body limit is 10MB - large uploads will fail with 413 Request Entity Too Large.

HTTPS Required

WebDAV transmits authentication credentials, so HTTPS is mandatory. With Caddy, HTTPS is the default behavior - no extra configuration needed.