SkillAgentSearch skills...

Zfdash

ZFS Management GUI & Web UI for Linux, macOS and FreeBSD. Provides both Desktop GUI and Web UI interfaces. Simplifies common ZFS administration tasks for pools, datasets, volumes, and snapshots, including creation, destruction, property editing, snapshots, rollback, and encryption management.

GenerateConvertImprove

Install / Use

/learn @ad4mts/Zfdash
About this skill

Quality Score

0/100

Supported Platforms

Universal

README

ZfDash - Modern ZFS Management GUI & Web UI Interface

Version License: GPL v3 Platform

🆕 New in v2.0.0: Full Backup & Replication system with Agent-to-Agent, Local, SSH, and File export modes — plus Agent Mode for multi-host ZFS management from a single Control Center!

A powerful, user-friendly ZFS pool, dataset, and snapshot management tool with both Desktop GUI and Web UI interfaces.

ZfDash simplifies ZFS administration on Linux, macOS, and FreeBSD through intuitive graphical interfaces. Built with Python and featuring a secure daemon architecture, it provides comprehensive ZFS management capabilities without requiring command-line expertise.

🚀 Quick Start

One-line installation (Linux only):

curl -sSL https://raw.githubusercontent.com/ad4mts/zfdash/main/get-zfdash.sh | bash

Default Web UI: http://127.0.0.1:5001 (Login: admin/admin - CHANGE IMMEDIATELY!)

Updating: Run the installer again or check for updates from the Help menu.

Table of Contents

✨ Features

  • 🔒 Secure backend daemon (Polkit/pkexec) & pipe/socket communication.
  • 💻 Desktop GUI (PySide6) & 🌐 Web UI (Flask/Waitress) with secure login (Flask-Login, PBKDF2).
  • 📊 Pool Management: View status, Create (various vdevs), Destroy, Import, Export, Scrub, Clear errors, Edit structure (Add/Remove/Attach/Detach/Replace/etc.), Force option.
  • 🌳 Dataset/Volume Management: Tree view, Create/Destroy (recursive), Rename, View/Edit properties, Inherit, Promote, Mount/Unmount.
  • 📸 Snapshot Management: View, Create (recursive), Delete, Rollback, Clone.
  • 💾 Backup & Replication: Agent-to-Agent, Local, SSH, and File export with job tracking, resume support, and automatic incremental base detection.
  • 🔐 Encryption Support: Create encrypted datasets, View status, Manage keys (Load/Unload/Change).
  • 🔑 Password Vault: Securely store agent credentials with auto-lock on logout.
  • 📜 Utilities: Optional command logging.

📸 Screenshots

Web UI:

ZfDash Web UI Screenshot 1 ZfDash Web UI Screenshot 2

Desktop GUI:

ZfDash GUI Screenshot 1

⚙️ Requirements

  • Supported Platforms: Linux (x86_64 and ARM64).
  • Experimental Support: macOS and FreeBSD have experimental support when running from source using uv (Method 2). Requires sudo and preferably --socket mode. Note: FreeBSD only supports Web UI (no GUI). All features are expected to work.
  • ZFS installed and configured (Tested with zfs-2.3.1. zfs and zpool commands must be executable by root).
  • Python 3 (Developed/Tested with 3.10-3.13).

🚀 Installation & Running

Default WebUI: http://127.0.0.1:5001, Login: admin/admin (CHANGE IMMEDIATELY!)

Method 1: Pre-Built Release (Linux x86_64 and ARM64 only)

Run this command to automatically download and install/update to the latest version for your system:

curl -sSL https://raw.githubusercontent.com/ad4mts/zfdash/main/get-zfdash.sh | bash
  • Launch GUI: App Menu/zfdash, Launch Web UI: zfdash --web [--host <ip>] [--port <num>], Help: zfdash --help
  • Uninstall: sudo /opt/zfdash/uninstall.sh (Note: Installer usually makes this executable)

Or download the latest release tar for your system and run install.sh.

Method 2: Run From Source with uv (Linux, macOS, FreeBSD)

Linux:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/ad4mts/zfdash && cd zfdash

# Run Web UI
uv run src/main.py --web

# Or run GUI
uv run src/main.py

macOS/FreeBSD (Experimental):

Requirements: sudo installed and configured (macOS has this by default)

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/ad4mts/zfdash && cd zfdash

# Run Web UI (recommended: use --socket mode for better compatibility)
uv run src/main.py --web --socket
# It will prompt you for sudo to launch the daemon

# Or run GUI (macOS only, not supported on FreeBSD)
uv run src/main.py --socket

Notes:

  • The --socket mode uses Unix sockets instead of pipes for daemon communication (more reliable on BSD-based systems)
  • Please report issues if you test on these platforms. See: uv run src/main.py --help for all options.
  • Troubleshooting: If the daemon won't start due to Polkit/policy issues, copy the packaged policy into the system actions directory:
sudo cp src/data/policies/org.zfsgui.pkexec.daemon.launch.policy /usr/share/polkit-1/actions/
sudo chown root:root /usr/share/polkit-1/actions/org.zfsgui.pkexec.daemon.launch.policy
sudo chmod 644 /usr/share/polkit-1/actions/org.zfsgui.pkexec.daemon.launch.policy

Then retry.

Method 3: Build From Source (Desktop/Manual WebUI)

  1. git clone https://github.com/ad4mts/zfdash && cd zfdash
  2. chmod +x build.sh
  3. ./build.sh (Automatically installs uv and builds)
  4. chmod +x install.sh
  5. sudo ./install.sh
  6. Launch/Uninstall: See Method 1.

Method 4: Docker (Web UI Only - Linux x86_64 and ARM64)

Running ZfDash in a privileged Docker container.

🐳 Docker Usage

This is the recommended method for deploying the ZfDash Web UI.

1. Pull the Image from a Registry

The image is available on both Docker Hub and GitHub Container Registry (GHCR). Docker Hub is the recommended source.

  • From Docker Hub (Recommended):

    sudo docker pull ad4mts/zfdash:latest

  • From GitHub Container Registry (Alternative):

    sudo docker pull ghcr.io/ad4mts/zfdash:latest

2. Run the Container

This command starts the container and uses Docker named volumes (zfdash_config and zfdash_data) to safely persist your application's configuration and data.

sudo docker run -d --name zfdash \
  --privileged \
  --network=host \
  --device=/dev/zfs:/dev/zfs \
  -v zfdash_config:/root/.config/ZfDash \
  -v zfdash_data:/opt/zfdash/data \
  -v /etc:/host-etc:ro \
  -v /dev/disk:/dev/disk:ro \
  -v /run/udev:/run/udev:ro \
  -v ~/.ssh:/root/.ssh:ro \
  -p 5001:5001 \
  --restart unless-stopped \
  ad4mts/zfdash:latest

A Docker Compose stack is also included. To use that instead of the above Docker command:

sudo docker compose up -d

You can then access the Web UI at http://localhost:5001.

Stopping and removing the container, if deployed with the Docker command:

sudo docker stop zfdash
sudo docker rm zfdash

Or if deployed with Docker Compose (add -v to remove the volumes as well):

sudo docker compose down

HostID Compatibility Note: ZFS pools store the system hostid they were created on. To prevent hostid mismatch errors, the container syncs with the host's /etc/hostid via the -v /etc:/host-etc:ro mount (already included in compose files). This works across all distributions, handling missing hostid files gracefully.

Security Note

The Docker container runs with --privileged mode, which grants the application (both the Web UI and the backend daemon) root-level access to the host system. This is currently required for ZFS management operations.

This configuration is suitable for trusted local networks and home lab settings. Do not expose this container directly to the public internet.

Future Roadmap:

  • Splitting the application into two containers: a privileged daemon container and an unprivileged Web UI container communicating via secure socket IPC.
  • Alternatively, implementing s6-overlay with s6-setuidgid to drop privileges for the Web UI process within the single container.

Method 5: Web UI Systemd Service (Headless/Server)

Note: Polkit < 0.106 is not supported for now (i.e., older distros).

  1. Install ZfDash via Method 1 or 3 first.
  2. cd install_service
  3. chmod +x install_web_service.sh
  4. sudo ./install_web_service.sh (Follow prompts for setup)
  5. Control: sudo systemctl [start|stop|status|enable|disable] zfdash-web
  6. Access: http://<server-ip>:5001 (or configured port/host)
  7. Uninstall Service: cd install_service && chmod +x uninstall_web_service.sh && sudo ./uninstall_web_service.sh

💡 Usage Tutorial

  • Launch: Follow installation steps. For Web UI, log in (admin/admin) and CHANGE PASSWORD IMMEDIATELY via the user menu.
  • Navigation: The left pane shows the ZFS object tree. The right pane shows details/actions for the selected object via tabs (Properties, Snapshots, etc.). The top bar/menu has global actions (Refresh 🔄, Create, Import) & Web UI user menu.
  • Common Tasks: Select an object in the tree, then use the right pane tabs or top bar/menu buttons. Examples: Check Pool Status/Properties tabs for health/usage. Use the Snapshots tab to create/delete/rollback/clone. Use the top bar/menu to create datasets. Use the Encryption tab to manage keys.
  • Remember: Destructive actions are irreversible. Double-check selections & keep backups!

🔗 Agent Mode

Agent Mode allows you to manage ZFS on remote hosts from a single ZfDash Control Center. Run an a

ad4mts

View profile

View on GitHub
GitHub Stars182
CategoryDevelopment
Updated2d ago
Forks12
ad4mts/zfdash

Languages

Python

Security Score

95/100

Audited on Mar 25, 2026

No findings