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

Configure

url is the WebDAV URL of the user’s files, such as https://cloud.example.com/remote.php/dav/files/alice/. verify_ssl=False turns off the TLS check only for some requests; reads, most writes and listings always verify the certificate.

Fields

str
required
WebDAV URL of the user’s files, such as https://cloud.example.com/remote.php/dav/files/alice/.
str
Basic Auth user name; unset sends requests without credentials.
str
secret
Basic Auth password; use an app password (Settings → Security) rather than the account password.
bool
default:"True"
Verify the server’s TLS certificate on the WebDAV requests mirage sends itself (copy, checksum, quota, properties, search, the chunks of a large write); reads, other writes and listings go through OpenDAL, which always verifies.
int
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.