WebDAV - rejetto/hfs GitHub Wiki

This page is focused on getting WebDAV working reliably with real clients (especially Windows Explorer and macOS Finder).

Who this is for:

  • HFS admins configuring WebDAV access.
  • Users connecting with Explorer/Finder/WebDAV clients.

Recommended defaults

For mixed access scenarios (anonymous + protected resources) we suggest to keep "webdav force login" on, and create a "guest" account with basic permissions.

Why: Some clients (notably Windows Explorer) can otherwise browse as anonymous even after you provided credentials, and see the wrong list. Forcing auth avoids inconsistent directory views.

Quick setup checklist

  1. Use HTTPS if possible.
  2. Keep force_webdav_login: true unless you have a clear reason not to.
  3. Map users to a path that has the permissions they need.
  4. If users must upload/replace files, ensure permissions allow upload and deletion.

Client-specific behavior

Windows Explorer (MiniRedir)

  • Explorer can fail with generic messages when the mapped path is not writable for the current account.
  • This is often a path/permissions issue, not a server bug.

Typical symptom:

  • "The folder you entered does not appear to be valid" (wizard)
  • "The file cannot be accessed by the system" (write attempt)

What to check first:

  1. Credentials cache on Windows.
  2. WebClient service status.
  3. Whether the mapped path is actually writable for that account.

macOS Finder / mount_webdav

  • Finder generally handles the initial auth challenge well.
  • CLI (mount_webdav) is useful for deterministic tests:
mount_webdav -i http://SERVER/PATH/ /tmp/webdav-test

Permissions guidance for WebDAV writes

To avoid confusing save behavior and duplicate-style outcomes:

  • If a user can upload to a WebDAV folder, also grant delete/overwrite-related rights where appropriate.
  • Keep folder-level permissions consistent with the expected workflow (create/edit/rename/delete).

Practical rule:

  • Read-only path -> users should expect read-only behavior.
  • Read-write path -> map users directly there for authoring workflows.

Troubleshooting flow (Windows)

Use this order:

  1. Clear existing mappings and cached credentials:
net use * /delete /y
cmdkey /list

If needed, remove target credentials:

cmdkey /delete:192.168.0.40
  1. Ensure WebClient is running:
sc query WebClient
sc stop WebClient
sc start WebClient
  1. Compare Explorer vs CLI:
net use * http://SERVER/ /user:USERNAME PASSWORD
net use * http://SERVER/upload-path/ /user:USERNAME PASSWORD

If CLI works but Explorer wizard fails, issue is usually Explorer-side behavior/state.

BasicAuthLevel (Windows)

Registry path: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WebClient\Parameters\BasicAuthLevel

Values:

  • 0: Basic disabled
  • 1: Basic allowed only on HTTPS (Microsoft default)
  • 2: Basic allowed on HTTP and HTTPS

Use 2 only if you must support plain HTTP. Prefer HTTPS.

Check:

reg query HKLM\SYSTEM\CurrentControlSet\Services\WebClient\Parameters /v BasicAuthLevel

Set:

reg add HKLM\SYSTEM\CurrentControlSet\Services\WebClient\Parameters /v BasicAuthLevel /t REG_DWORD /d 2 /f
sc stop WebClient
sc start WebClient

Known interoperability notes

  • Apache, copyparty, and HFS all show client-dependent behavior when mapping read-only vs write-enabled paths.
  • A generic write failure on a read-only mapping is expected behavior.
  • The key reliability lever for mixed anonymous/protected trees is forcing login for WebDAV clients.

FAQ

Should we expose two endpoints (anonymous and authenticated)?

Usually not necessary. Start with force_webdav_login: true and verify client behavior.

Is webdav_initial_auth enough by itself?

Only in some scenarios. If Explorer must always get account-aware listing, force_webdav_login: true is the safer default.

Is this an HFS-only problem?

No. Similar client quirks appear with other WebDAV servers too.

References