Skip to main content
NextcloudVFS mounts a WebDAV server: Nextcloud, ownCloud, Hetzner Storage Share or any other WebDAV endpoint. Its folders and files appear as they are, with their own names and bytes. Set up the URL and app password as in Nextcloud setup.

Install

opendal is an optional peer package that only this mount needs.

Configure

url is the WebDAV URL of the user’s files, such as https://cloud.example.com/remote.php/dav/files/alice/. verifySsl is accepted but not applied: every request verifies the server’s certificate.

Fields

string
required
WebDAV URL of the user’s files, such as https://cloud.example.com/remote.php/dav/files/alice/.
string
Basic Auth user name; unset sends requests without credentials.
string
secret
Basic Auth password; use an app password (Settings → Security) rather than the account password.
boolean
Accepted but not applied: every request verifies the server’s TLS certificate.
number
default:"30"
Seconds one WebDAV request mirage sends itself (copy, checksum, quota, properties, search, the chunks of a large write) may take; reads, other writes and listings go through OpenDAL and its own timeouts.
Fields marked secret are redacted in snapshots.

Authentication

The mount sends username and password as Basic Auth; without them it sends no credentials. Use an app password (Settings, Security in Nextcloud) rather than the account password: it can be revoked on its own. A request the server refuses answers Permission denied.

Layout

/nc/Documents/notes.md is <NEXTCLOUD_URL>/Documents/notes.md on the server.

Behavior

  • Partial reads: reads stream in chunks, and partial reads such as head -c send HTTP Range requests.
  • Writes: a write buffers the whole file before it uploads. cp, mv, rm and mkdir run as WebDAV COPY, MOVE, DELETE and MKCOL.
  • Snapshots: a snapshot keeps the mount’s settings but not the password, so hand the password back when loading it. Files are not checked for changes on replay.

Integration

Nextcloud answers these commands through its own API, so fewer files are read. See Integration.
  • md5sum, sha256sum and the other hash commands: the digest Nextcloud keeps (oc:checksums), when the uploading client set one.
  • find: one recursive listing.
  • du: one recursive listing.
  • ls -R and tree: one recursive listing.

VFS.md

The VFS.md an agent reads with Nextcloud mounted at /<path>. <mode> is the mount’s mode: read, write or exec. The commands shown are those of a write mount.
Virtual FilesystemSupported Unix Commands for VFSUnix commands work on each path as on a local filesystem, as far as the path supports them:Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:Run man <cmd> or <cmd> --help for one command’s usage.