borg webdav

borg [common options] webdav [options]

options
	-f, --foreground	stay in foreground, do not daemonize
	--port PORT	TCP port to listen on (on localhost); default: 8000
Common options
Archive filters — Archive filters can be applied to repository targets.
	-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.

Description

This command serves the contents of the selected archives via a read-only WebDAV / HTTP server, so the archive contents can be:

• browsed and downloaded with a web browser,

• mounted as a read-only network file system, using the WebDAV client built into most operating systems and file managers.

Mounting examples:

• Windows Explorer: “Map network drive” -> http://localhost:8000/ (or on the command line: net use Z: http://localhost:8000/).

• macOS Finder: “Go > Connect to Server” (Cmd-K) -> http://localhost:8000.

• GNOME Files / KDE Dolphin: open dav://localhost:8000/.

• Linux kernel mount: mount -t davfs http://localhost:8000/ /mnt/point (needs the davfs2 package).

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.

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.

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.

• 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.

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.

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.