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:

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), readOnly flag
• Passwords are escaped for special characters and encrypted before storage

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
• SSH keys stored in /var/lib/zerobyte/ssh/

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)

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 /var/lib/zerobyte/ssh/
• 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,
  "readOnly": false
}

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,
  "readOnly": false
}

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:latest
    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:latest
    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:latest
    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:latest
    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.