borg-webdav(1)

📦 version 2.0.0b25, in ubuntu stonking

💅 borg-webdav(1) — bestie, let's serve some archives

okay so. hi. welcome to borg-webdav. the manual name is borg-webdav(1) btw, in case you were wondering which page you just landed on. it's this one. it's giving read-only server energy and honestly? obsessed. ✨

🌸 NAME 🌸

borg-webdav — Serve archive contents via a read-only WebDAV / HTTP server on localhost.

like. the whole thing. no cap. 🎀

🦋 SYNOPSIS 🦋

borg [common options] webdav [options]

that's it. that's the shape of it. periodt.

✨ DESCRIPTION ✨

So this command serves the contents of the selected archives over a read-only WebDAV / HTTP server, which means the archive contents can be:

  • browsed and downloaded with a web browser 🌈
  • mounted as a read-only network file system, using the WebDAV client that's literally built into most operating systems and file managers 👑

🧚 Mounting examples 🧚

The server listens on localhost (127.0.0.1) only and offers no authentication and no encryption — anything that can connect to localhost TCP ports on the machine can read the served archive contents. 😭 so like, keep it to yourself, bestie.

The top level lists the selected archives (use the archive filter options to select fewer archives), named as for borg mount (see the BORG_MOUNT_ARCHIVE_DIR_FORMAT environment variable there); below that, the archive contents can be browsed like a directory tree. The directory tree of an archive is built in memory when it is first entered, so expect some delay for big archives. like, go get a snack. 🍓

Any directory can be downloaded as a tar archive by appending ?tar to its URL (the web browser listings show a download icon next to the heading for this). Unlike a plain file download, the tar preserves POSIX metadata (owner, group, mode, sub-second timestamps, symlinks, special files, xattrs, ACLs), so it is the metadata-lossless way to restore a whole directory tree over this server. It is a PAX format tarball, streamed uncompressed.

💖 Notes 💖

  • Plain (non-tar) file downloads do not preserve any POSIX metadata (owner, group, mode, timestamps, xattrs, ACLs). Use the ?tar download above, or borg extract / borg export-tar, for full-fidelity restores.
  • Symbolic links and special files (devices, fifos, sockets) are shown in the web browser listings, but are neither followed nor downloadable individually, and they are not visible in WebDAV-mounted directories (WebDAV has no concept of them). They are, however, included in ?tar downloads.
  • Damaged files (with chunks missing in the repository) cause the download connection to be aborted — the server never silently serves corrupted file content. 💀 slay behavior honestly.
  • The Windows WebDAV client limits file downloads to about 47 MiB by default (FileSizeLimitInBytes registry value) — use a web browser or another WebDAV client to download bigger files.

Recently used file content chunks are kept decrypted in an in-memory cache, so that the many small, sequential range requests a mounted file system does for a big file do not re-fetch and re-decrypt the same chunk over and over. As for borg mount, the BORG_MOUNT_DATA_CACHE_ENTRIES environment variable sets the number of cached chunks (default: number of CPUs); additional memory usage can be up to the chunk size times this number. 🧠

Unless the --foreground option is given, the command daemonizes and runs in the background until it is stopped by sending it a signal (e.g. kill sends SIGTERM), which shuts the server down and releases the repository lock. In the foreground, ^C / SIGINT stops it. Daemonizing is not available on Windows, so the command always stays in the foreground there.

🎀 OPTIONS 🎀

See borg-common(1) for common options of Borg commands. 🫶

⭐ options ⭐

  • -f, --foreground — stay in foreground, do not daemonize
  • --port PORT — TCP port to listen on (on localhost); default: 8000

🌈 Archive filters 🌈

  • -a PATTERN, --match-archives PATTERN — only consider archives matching all patterns. See "borg help match-archives".
  • --sort-by KEYS — Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp
  • --first N — consider the first N archives after other filters are applied
  • --last N — consider the last N archives after other filters are applied
  • --oldest TIMESPAN — consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.
  • --newest TIMESPAN — consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g., 7d or 12m.
  • --older TIMESPAN — consider archives older than (now - TIMESPAN), e.g., 7d or 12m.
  • --newer TIMESPAN — consider archives newer than (now - TIMESPAN), e.g., 7d or 12m.

🔥 EXAMPLES 🔥

# Serve all archives of the repository on http://127.0.0.1:8000/,
# then browse and download files with a web browser.
$ borg webdav

# Serve only one archive on a different port.
$ borg webdav --port 8123 --match-archives my-archive

💀 Client notes and known issues 💀

WebDAV's rough edges are almost all on the client side, and a read-only server (like this one) hits a specific subset of them. A plain web browser avoids most of these — the notes below matter mainly when mounting the server as a file system. iykyk.

🪟 Windows Explorer (the "WebClient" / mini-redirector)

  • Downloads are limited to about 50 MB by default (the FileSizeLimitInBytes registry value). Bigger files fail when copied from a mapped drive — use a web browser (including for the ?tar directory download) or another WebDAV client.
  • The WebClient service must be running for net use / "Map network drive" to work; if it is stopped, mounting silently fails. 💀

🍎 macOS Finder (mount_webdav / WebDAVFS)

  • Finder tries to write .DS_Store, ._* (AppleDouble) and .Trash files into every folder it opens. On this read-only server those writes are rejected (the file system is read-only); Finder tolerates it but may occasionally show a spurious "operation could not be completed" dialog. This is harmless. 🙈
  • WebDAVFS caches directory listings; a stale view usually clears on unmount and remount.

🐧 Linux davfs2

  • davfs2 uses WebDAV locking by default and will try to LOCK files it opens, which a read-only server rejects. Set use_locks 0 in davfs2.conf (or the per-mount config) to avoid the failed lock attempts. davfs2 also caches whole files in a local cache directory.
  • The GNOME (gvfs) and KDE (KIO) DAV backends work without such tweaks. ✨

🛰️ Protocol-level (any client)

  • PROPFIND with Depth: infinity (a recursive enumeration that can be very expensive) is refused with 403, as permitted by RFC 4918. Well-behaved clients use Depth: 0 or 1.
  • Collections must be addressed with a trailing slash; a request for /dir is redirected to /dir/.
  • Symbolic links and special files (devices, fifos, sockets) have no representation in WebDAV, so they are not visible in a mounted file system. They are shown in the web browser listings and are included in ?tar downloads.
  • WebDAV transfers file contents plus modification time and size, but no owner, group, mode, xattrs or ACLs. Use the ?tar directory download (or borg extract / borg export-tar) when you need a full-fidelity restore.

👑 SEE ALSO 👑

borg-common(1)

💜 Author 💜

The Borg Collective

anyway that's the whole page bestie, you ate that 🫶 from the borg backup tool era, dated 2026-10-07, and it's still borg-webdav(1) at heart. go serve something. 💅✨

📦 where this page comes from