Zerobyte Volumes Documentation#

Overview#

Zerobyte volumes represent data sources that can be backed up. They provide an abstraction layer for accessing different types of storage systems (local directories, network shares, cloud storage) that need to be backed up using restic.

Volume Types#

Zerobyte supports six types of volumes:

Note: Mounted remote volumes (NFS, SMB, WebDAV, SFTP, rclone) can expose translated metadata instead of the source system's original ownership and ACL model. Before relying on these volume types for metadata-sensitive backups, read the Mounted Shares, ACLs, and Metadata Fidelity guide to understand how different backends handle permissions and what to expect during restore operations.

1. Directory#

• Direct access to local filesystem paths
• Commonly used for bind-mounted directories from Docker containers
• Does not perform actual mounting - simply verifies the path exists and is a directory
• Configuration: { path: string }

2. NFS (Network File System)#

• Remote network mounts supporting NFS versions 3, 4, and 4.1
• Configuration includes: host, path, version, port, readOnly flag
• Uses Linux mount command with NFS-specific options

3. SMB/CIFS (Windows/Samba Shares)#

• Network shares compatible with Windows file sharing
• Supports both authenticated and guest access
• Configuration: host, share, username (optional), password (optional), domain (optional), mapToContainerUidGid (optional), readOnly flag
• Passwords are escaped for special characters and encrypted before storage
• The mapToContainerUidGid field controls ownership mapping: when true (default), forces all files to appear as owned by the container user/group; when false, uses cifsacl, idsfromsid, and modefromsid options to show server-reported ownership and permissions

4. WebDAV#

• HTTP-based distributed file system access
• Supports both HTTP and HTTPS
• Configuration: url, username (optional), password (optional), readOnly flag
• Credentials stored in /etc/davfs2/secrets

5. Rclone#

• Cloud storage backends via rclone
• Supports any storage backend compatible with rclone
• Configuration: remote (rclone remote name), path, readOnly flag
• Mounts using VFS cache mode "writes" with daemon flag

6. SFTP (SSH File Transfer Protocol)#

• Secure file access over SSH
• Supports both password and private key authentication
• Configuration: host, port, username, password (optional), privateKey (optional), path, readOnly flag, skipHostKeyCheck (optional), knownHosts (optional), allowLegacySshRsa (optional), allowUnsafeSymlinkTargets (optional)
• SSH keys stored in an ephemeral temporary directory to avoid permission issues with certain bind mount configurations
• allowLegacySshRsa enables legacy SSH RSA/SHA1 algorithms for compatibility with older SFTP servers that only offer ssh-rsa host key algorithms (weaker than modern SSH algorithms, should only be enabled for legacy servers)
• allowUnsafeSymlinkTargets preserves absolute and parent-directory symlinks in their original form for backup instead of containing them (requires host key verification - knownHosts must be set and skipHostKeyCheck must be false, default: false)

Volume Architecture#

Backend Interface#

All volume types implement a common VolumeBackend interface with three core operations:

• mount() - Mount the volume
• unmount() - Unmount the volume
• checkHealth() - Verify volume is accessible

Volume Status#

Each volume has one of three status values:

• mounted - Volume is successfully mounted and accessible
• unmounted - Volume is not currently mounted
• error - Volume encountered an error during mount/health check

Volume Creation Modes#

Volumes can be created through two methods:

• Manual Creation: Created through the UI or API by users, stored with provisioningId as null
• Operator Provisioning: Defined in a JSON configuration file loaded at startup via the PROVISIONING_PATH environment variable, stored with a non-null provisioningId and displayed as "managed" in the UI

Database Schema#

Volumes are stored in the volumesTable with fields including:

• id, shortId, name - Identifiers
• provisioningId - Nullable string identifying operator-managed volumes synced from a provisioning file
• type - Volume backend type
• status - Current mount status
• config - Backend-specific configuration (JSON)
• autoRemount - Whether to automatically remount on failure
• lastError, lastHealthCheck - Monitoring data
• organizationId - Multi-tenancy support

How Volume Mounting Works#

Mount Point Management#

Volume mount paths are determined by type:

• Directory volumes: Use the configured path directly (no mounting needed)
• All other volumes: Mount at /var/lib/zerobyte/volumes/{shortId}/_data
  • Base path configurable via ZEROBYTE_VOLUMES_DIR environment variable

Mounting Process#

Directory Backend#

Directory volumes don't perform actual mounting - they simply validate that:

• The path exists
• It is a directory
• It has read access (and write access if not read-only)

NFS Backend#

NFS volumes use the Linux mount command with:

• Type flag: -t nfs
• Options: NFS version, port, and optional read-only flag
• Fallback to -i flag if initial mount fails

SMB Backend#

SMB/CIFS volumes mount using:

• Type flag: -t cifs
• Credential handling with support for guest access or username/password
• Password escaping for special characters (backslashes and commas)
• Ownership mapping controlled by mapToContainerUidGid:
  • When true (default): Uses uid and gid mount options to present all files as owned by the container user/group
  • When false: Uses cifsacl, idsfromsid, and modefromsid options to preserve server-reported ownership and permissions (note: these options may not be supported by all kernels)

WebDAV Backend#

WebDAV volumes mount using:

• Type flag: -t davfs
• Credentials stored in /etc/davfs2/secrets
• Support for both HTTP and HTTPS URLs

Rclone Backend#

Rclone volumes use the rclone mount command with:

• VFS cache mode set to "writes"
• --daemon flag to run in background
• --allow-non-empty and --allow-other flags
• Timeout configurable via SERVER_IDLE_TIMEOUT environment variable (default 300 seconds)

SFTP Backend#

SFTP volumes mount using sshfs with:

• Support for both password and private key authentication
• SSH keys stored in a system-managed temporary directory (rather than a persistent path) to improve compatibility with bind mount setups that don't properly support chmod operations
• Optional allowLegacySshRsa flag to enable legacy SSH RSA/SHA1 algorithms (HostKeyAlgorithms=+ssh-rsa and PubkeyAcceptedAlgorithms=+ssh-rsa) for compatibility with older SFTP servers
• Optional allowUnsafeSymlinkTargets flag to preserve absolute and parent-directory symlinks in their original form. Recent SSHFS versions contain absolute/parent-directory symlinks by default for safer browsing, but this prevents Restic from archiving original symlink metadata. This opt-in option passes the no_contain_symlinks flag to SSHFS for trusted SFTP sources that need exact symlink backup. For security reasons, this option requires host key verification and cannot be used with skipHostKeyCheck or when knownHosts is not configured
• Reconnection settings for reliability

Operation Timeouts#

All mount/unmount operations have configurable timeouts to prevent hanging:

• Default: 5 seconds
• SFTP: 10 seconds (longer due to SSH handshake)
• Rclone: Uses SERVER_IDLE_TIMEOUT configuration (default 300 seconds / 5 minutes), configurable to accommodate slow mount operations

Security Features#

Credential Encryption#

Sensitive credentials are encrypted before storage:

• SMB: password
• WebDAV: password
• SFTP: password and private key

Secret Placeholders#

Credentials support secret placeholders to keep secrets out of the database:

• env://VARIABLE_NAME - Reference environment variable
• file:///path/to/secret - Reference file content

For provisioned volumes, secret references are resolved at startup time and the resolved values are encrypted before database storage. File-based secrets (file://...) are restricted to the /run/secrets directory and must be a single filename without path separators.

Volume Management Operations#

The volume service provides these operations:

• Create: Create volume, encrypt credentials, auto-mount (manual volumes only)
• Mount: Execute backend-specific mount operation
• Unmount: Execute unmount and clean up mount point
• Health Check: Verify volume accessibility
• Update: Update configuration (unmounts/remounts if config changes)
• List Files: Browse files in mounted volumes with pagination

Provisioned volumes are synced automatically at startup and appear alongside manually created volumes in the UI. They are marked with a "Managed" badge and controlled via the provisioning configuration file.

Configuration Examples#

NFS Volume#

NFS configuration schema:

{
  "backend": "nfs",
  "server": "192.168.1.100",
  "exportPath": "/export/backups",
  "port": 2049,
  "version": "4",
  "readOnly": false
}

SMB/CIFS Volume#

SMB configuration schema:

{
  "backend": "smb",
  "server": "192.168.1.200",
  "share": "backups",
  "username": "backup_user",
  "password": "env://SMB_PASSWORD",
  "domain": "WORKGROUP",
  "vers": "3.0",
  "port": 445,
  "mapToContainerUidGid": false,
  "readOnly": false
}

Note: The mapToContainerUidGid field defaults to true if omitted. When set to false, the mount uses cifsacl, idsfromsid, and modefromsid options to show server-reported ownership and permissions. See the Mounted Shares, ACLs, and Metadata Fidelity guide for details on how this affects permission fidelity.

Directory Volume#

Directory configuration schema:

{
  "backend": "directory",
  "path": "/mydata",
  "readOnly": false
}

WebDAV Volume#

WebDAV configuration schema:

{
  "backend": "webdav",
  "server": "cloud.example.com",
  "path": "/remote.php/webdav",
  "username": "user",
  "password": "file://webdav_secret",
  "port": 443,
  "ssl": true,
  "readOnly": false
}

Rclone Volume#

Rclone configuration schema:

{
  "backend": "rclone",
  "remote": "s3-backup",
  "path": "/backups",
  "readOnly": false
}

SFTP Volume#

SFTP configuration schema:

{
  "backend": "sftp",
  "host": "sftp.example.com",
  "port": 22,
  "username": "backup",
  "privateKey": "file://ssh_key",
  "path": "/data",
  "skipHostKeyCheck": true,
  "allowLegacySshRsa": false,
  "allowUnsafeSymlinkTargets": false,
  "readOnly": false
}

Note: The allowLegacySshRsa field defaults to false if omitted. When set to true, it enables legacy SSH RSA/SHA1 algorithms (ssh-rsa) for compatibility with older SFTP servers. This option is weaker than modern SSH algorithms and should only be enabled for legacy servers that require it.

The allowUnsafeSymlinkTargets field defaults to false if omitted. When set to true, it preserves absolute and parent-directory symlinks in their original form for backup instead of containing them. This requires host key verification (knownHosts must be set and skipHostKeyCheck must be false). Only enable this for trusted SFTP servers that need exact symlink backup.

Docker Setup Requirements#

Remote Mount Support#

For NFS, SMB, WebDAV, and SFTP volumes, the container requires elevated privileges:

services:
  zerobyte:
    image: ghcr.io/nicotsx/zerobyte:v0.38
    cap_add:
      - SYS_ADMIN
    devices:
      - /dev/fuse:/dev/fuse
    volumes:
      - /var/lib/zerobyte:/var/lib/zerobyte

Directory Bind-Mount#

For directory volumes, bind-mount the host directory into the container:

services:
  zerobyte:
    image: ghcr.io/nicotsx/zerobyte:v0.38
    volumes:
      - /var/lib/zerobyte:/var/lib/zerobyte
      - /path/on/host:/mydata

Rclone Config Mount#

For rclone volumes, mount your rclone configuration directory:

services:
  zerobyte:
    image: ghcr.io/nicotsx/zerobyte:v0.38
    volumes:
      - /var/lib/zerobyte:/var/lib/zerobyte
      - ~/.config/rclone:/root/.config/rclone:ro

Provisioned Resources#

For operator-managed volumes and repositories, mount a provisioning file:

services:
  zerobyte:
    image: ghcr.io/nicotsx/zerobyte:v0.38
    environment:
      - PROVISIONING_PATH=/etc/zerobyte/provisioning.json
    volumes:
      - /var/lib/zerobyte:/var/lib/zerobyte
      - ./provisioning.json:/etc/zerobyte/provisioning.json:ro
    secrets:
      - aws_secret_access_key

secrets:
  aws_secret_access_key:
    file: ./secrets/aws_secret_access_key

The provisioning file defines volumes and repositories with env:// or file:// secret references. See the provisioned-resources example for complete setup instructions.

Schema Validation#

Volume configurations use zod for runtime validation. Each backend type has specific required and optional fields defined in the schema, ensuring configurations are validated before mounting.