DPlaneOS
A ZFS-first storage operating system for homelab and small-office NAS deployments. Single Go daemon, PostgreSQL state, React UI, NixOS appliance. Declarative from the OS down to the dataset.
Click the screenshot for an interactive tour of the UI.
Project status
Read this before you deploy anything.
DPlaneOS is built and maintained by one person (hi, Dan). It runs in my own homelab on roughly 33 TB across 60+ services and has done so reliably for months, which is the entire production deployment base I can point to. If you need vendor support, a roadmap committee, or a phone number to call at 3am, this is not the project for you. Yet.
Feature maturity, honestly:
| Area | Status | Notes |
|---|
| ZFS pool / dataset / snapshot management | Stable | The core. Used daily. |
| SMB, NFS, iSCSI sharing | Stable | Samba + kernel NFS + LIO. |
| Container management (Docker, Compose) | Stable | Including ZFS-clone sandboxes. |
| Hot-swap detection and auto-import | Stable | udev + ZED, exercised regularly. |
| LDAP / Active Directory integration | Beta | Winbind NSS integration shipped in v14.1.0: AD users resolve in ls -l, ACLs, and SMB. |
| OIDC / SSO (Authorization Code + PKCE) | Beta | Keycloak, Authentik, Dex, Entra ID, and any OIDC-compliant provider. |
| Updates with automatic rollback (NixOS generations) | Beta | Proven in a NixOS VM test (good update kept, broken update rolled back); no field updates yet. |
| Live boot (ephemeral, no install needed) | Stable | Trial the software, manage pools, run containers from USB. Full daemon/UI in RAM. Persistence optional via USB. |
| GitOps reconciliation | Beta | Structural sync (pools, datasets, shares, stacks) and capture-from-live both work. Safety rails (block destroy on used data, block pool destroy unconditionally) are well-tested. Edge cases at the property-coverage frontier still surfacing. |
| Out-of-band hardware management (BMC) | Beta | Redfish (iLO 5+, iDRAC 9+), iLO 4 legacy REST, generic IPMI. TOFU TLS certificate pinning. Sensors, event log, power management. |
| Clusters, storage groups, third vote | Experimental | Corosync quorum, shared and replicated storage groups, failover; tested in VM CI, not yet under real load. |
| Shared-SAS HA with SCSI-3 PR fencing | Experimental | Tested on one hardware configuration. Yours will differ. |
| NVMe-oF over TCP | Experimental | Functional, not yet stress-tested. |
If you're considering this for anything beyond a homelab, also read the Threat Model (13 scenarios, known gaps documented) and the Non-ECC RAM Warning.
Bug reports are welcome. So are contributors; the CLA is upfront about copyright assignment, which some people will not be comfortable with. Fair.
How is this possible as a solo project
Reasonable question. The short answer: most of DPlaneOS isn't DPlaneOS.
NixOS does the heavy lifting. The OS, the bootloader, service supervision, the package set, reproducible builds, generation-based rollbacks, firewall, user management, kernel module loading, the whole declarative configuration model. None of that is my code. NixOS already solved it, better than I could in ten lifetimes. DPlaneOS is a NixOS module and a daemon that drives it.
OpenZFS does the storage. Pools, datasets, snapshots, send/receive, encryption, ARC tuning, scrub, resilver, integrity checking, all of it. The daemon shells out to zfs and zpool with allowlisted arguments and parses the output. That's it. The hard storage problems were solved by Sun, then Illumos, then OpenZFS, over twenty years.
The system stack is well-trodden upstream software. PostgreSQL for state, nginx for the edge, Corosync for cluster quorum (as in Proxmox VE), Samba for SMB, the kernel for NFS and LIO/iSCSI, Docker for containers, NUT for UPS, rclone for cloud sync, ZED for ZFS event delivery. Each of these has more engineering hours behind it than I will produce in my career.
The Go dependency tree is deliberately small. Eleven direct dependencies: gorilla/mux, gorilla/websocket, pgx, goose (schema migrations), go-ldap, lego (ACME), creack/pty, google/uuid, golang.org/x/crypto, golang.org/x/sys, go-jose/v4 (OIDC JWS verification). All vendored. The daemon is not a wrapper around a large framework; it's standard library plus narrow, well-understood plumbing.
So what's actually new code?
The seams. ~94k lines of Go that tie the above together coherently: ~550 HTTP routes mapping UI intent to allowlisted exec calls, state persisted in PostgreSQL with goose migrations, a reconciler that compares declared state against observed state and handles drift, an HMAC-chained audit log, ZED events surfaced over WebSocket, updates through NixOS generations with a health check and automatic rollback, storage groups that move between nodes with quorum, epochs and layered fencing (watchdog, multihost, SCSI-3 PR, power), and configuration that merges between nodes per resource. None of this is exotic computer science. All of it is integration work that nobody else had bothered to do under one roof.
The interface. ~43k lines of React 19 / TypeScript: 55 pages and one embedded PTY terminal. Aimed at someone who would rather not memorise zpool flags or hand-edit a Samba config.
The GitOps layer. A declarative state.yaml schema and a bi-directional reconciler that lets you treat a Git repo as the source of truth for the shape of your storage: pools, dataset hierarchy and properties (quota, compression, atime, recordsize, encryption, mountpoint), shares, NFS exports, container stacks, users, replication relationships. You can apply changes from Git to the live system, or capture the live state back into Git. What it does not manage is the data plane itself: dataset contents, snapshots, and zfs send streams stay on ZFS's terms and are backed up out of band. The reconciler is also conservative in the places that matter: pool destruction is always BLOCKED, a dataset is only destroyed when it is provably empty (no files, no snapshots, no children; a volume never), approval or not, and there's an ignore_extraneous flag for partial declarations. A git push cannot wipe data; only metadata and configuration. This is the part I'm proudest of and also the part most likely to have rough edges at the property-coverage frontier.
That's the honest accounting. DPlaneOS exists because NixOS, OpenZFS, PostgreSQL, and a dozen other projects exist. The work I did is the integration layer and the UX. Both are real work, neither is "building a storage OS from scratch," and pretending otherwise would be insulting to the upstream projects this whole thing rests on.
Acknowledgements
DPlaneOS stands on the shoulders of decades of work by people I have never met. A non-exhaustive list of the projects this would not exist without:
The foundation. NixOS and Nixpkgs for the declarative OS model that makes the whole appliance approach feasible. OpenZFS for the filesystem the project is named after and built around. PostgreSQL for state that doesn't lose itself.
The services. nginx, Samba, Corosync, Docker, the Linux kernel's NFS and LIO/iSCSI subsystems, rclone, smartmontools. Each one a project I have used for years and never had cause to regret picking.
The libraries. gorilla/mux and gorilla/websocket, jackc/pgx, go-ldap, go-acme/lego, creack/pty, go-jose/v4. Plus the Go team's golang.org/x/crypto and friends.
The frontend. React, TanStack Router and Query, Zustand, xterm.js, Vite. The Outfit and JetBrains Mono typefaces, plus Material Symbols.
Full license inventory and attribution in NOTICE.md.
Getting Started
Install to disk (permanent):
Try live boot (no installation needed):
- Download the latest live ISO (same releases, look for
-live in filename)
- Flash to USB and boot
- Full D-PlaneOS in RAM, ephemeral state, auto-import existing ZFS pools
- See Live Boot Quick Start
What it does
| Area | Capabilities |
|---|
| Storage | ZFS pools, datasets, scheduled snapshots (every 15 min to monthly) with retention, zfs send replication (raw for encrypted datasets), native encryption, quotas, S.M.A.R.T., POSIX ACLs, file explorer with chunked uploads |
| Hot-swap | udev detects disk add/remove; a returning member of an imported pool is brought back online, an exported pool is re-imported when one of its own disks returns (never a pool from a foreign disk), and the UI suggests vdev replacements |
| Sharing | SMB (with Time Machine via vfs_fruit), NFS, iSCSI, NVMe-oF, configured from the UI |
| Containers | Docker, Compose stacks (also deployed from Git, on push), image update detection and optional auto-update, updates that roll back to the previous images when a service does not come up (ZFS snapshot first), ephemeral ZFS-clone sandboxes, in-browser terminal. Intel VA-API hardware transcoding supported (Jellyfin, Plex). |
| Network | Interface config, bonding, VLANs, routing, DNS, firewall rules by source; every change reverts unless confirmed |
| Identity | Local users, LDAP / AD with Winbind NSS integration (AD users visible in ls -l, ACLs, SMB), OIDC SSO (Authorization Code + PKCE), TOTP 2FA, SCRAM-SHA-512, API tokens |
| Security | RBAC (4 roles, 31 permissions), HMAC audit chain, CSRF protection, firewall, TLS, allowlist-validated exec calls, govulncheck in CI |
| Hardware | BMC management via Redfish (iLO 5+, iDRAC 9+), iLO 4, or IPMI. TOFU TLS certificate pinning. Temperature, fan, power sensors. Power management and event log. |
| Monitoring | Prometheus/OpenMetrics at /metrics: ZFS pool health (4-level), dataset usage/quota, scrub progress, cluster quorum and storage groups, replication status, BMC sensors, build info |
| HA | Optional, off by default. Pair nodes, form a Corosync cluster, add a third vote (QDevice on a Raspberry Pi/VM, a corosync-only voter, another DPlaneOS system, or a third node), and put pools into storage groups that move between nodes with their shares, apps and a floating address. Shared storage (SAS/SATA shelf, SAN) or replicated ZFS; watchdog self-fencing, ZFS multihost, SCSI-3 PR and optional power fencing. |
| System |
Install
Boot the installer ISO. It handles everything.
# Write the ISO to USB (Linux/macOS)
dd if=dplaneos-v*.iso of=/dev/sdX bs=4M status=progress conv=fsync
- Boot the target machine from USB, in UEFI mode (legacy BIOS is not supported).
- The installer starts on the screen and on the serial console. Choose the disk for the system (32 GB or more; it is erased) and set the password of the
admin user. Headless machines: SSH to the installer as root, password dplaneos.
- The installation takes a few minutes and needs no network. Remove the USB drive and reboot.
- Open
http://<your-server-ip>/ and log in as admin with that password.
Download: Latest release. Grab dplaneos-v*-installer-amd64.iso (x86_64) or dplaneos-v*-installer-arm64.iso (aarch64 with UEFI firmware). The live ISOs (-live-) run D-PlaneOS from the USB drive without installing. For a cluster's third vote there are witness images: dplaneos-witness-v*-x86_64.qcow2 / .img.zst (VM or small PC) and dplaneos-witness-v*-rpi-aarch64.img.zst (Raspberry Pi 3/4 SD card); see Choosing a third vote.
Offline / air-gapped: the ISO contains the complete NixOS closure. No internet access needed during installation. Note: the Intel VA-API and OpenCL packages (intel-media-driver, intel-compute-runtime, x86_64 only) are left out of the ISO to keep it small; the first update (Updates page) adds them once the system is online. All core NAS features work immediately from an offline install.
Cosign / provenance: every ISO is signed with cosign and accompanied by an SPDX SBOM. Verify with:
cosign verify-blob --bundle dplaneos-v16.0.0-installer-amd64.iso.bundle \
--certificate-identity-regexp '^https://github.com/4nonX/DPlaneOS/' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
dplaneos-v16.0.0-installer-amd64.iso
Rebuilding from source: nix build .#iso. See nixos/README.md.
Minimum hardware
- 64-bit CPU, x86_64 or aarch64, with UEFI firmware
- 4 GB RAM minimum, 16 GB recommended, more for large pools
- ECC RAM strongly recommended for ZFS; non-ECC is supported but read the warning first
- One disk of 32 GB or more for the system, plus the disks you intend to pool
- Full compatibility list: Hardware Compatibility
Architecture
The runtime is a single Go daemon (dplaned, linked against libzfs) sitting behind nginx, with PostgreSQL for state. The daemon talks to ZFS, Docker, and the kernel via exec.Command with a strict allowlist (no shell, no string interpolation). The frontend is a pre-built React 19 bundle served as static files.
Browser
└── nginx :80/:443 static files (the UI, from the Nix store)
└── proxy /api/ /ws/
└── dplaned (Unix socket) (Go)
├── PostgreSQL /var/lib/dplaneos/pgsql/ (node-local)
├── ZFS kernel module via allowlisted exec
├── Docker socket
└── LDAP/AD optional
| Component | Detail |
|---|
| Frontend | React 19 + TypeScript + Vite, pre-built, no Node.js at runtime |
| Backend | Go daemon, allowlist-validated exec, no shell invocation anywhere in the codebase |
| Database | PostgreSQL 17 (one per node) |
| Auth | SCRAM-SHA-512 (RFC 5802, 100k PBKDF2 iterations), bcrypt (web login over HTTPS), LDAP bind (directory accounts), OIDC Authorization Code + PKCE (SSO accounts), TOTP 2FA, AAL1/AAL2 session assurance levels, CSRF double-submit |
| ZFS events | ZED hook delivers pool fault, scrub, and resilver events in real time |
| BMC | Redfish (iLO 5+, iDRAC 9+), iLO 4 legacy REST, generic IPMI. TOFU TLS fingerprint pinning - no InsecureSkipVerify. |
| Observability | Prometheus/OpenMetrics at /metrics (no auth). ZFS, HA, replication, BMC sensor metrics. govulncheck on every CI run. cosign-signed releases with SPDX SBOMs. |
Deeper reading: Architecture, Design Philosophy, NixOS Rationale.
Key paths
| Item | Path |
|---|
| Daemon binary | dplaned on the PATH (in the Nix store) |
| Daemon socket | /run/dplaneos/dplaned.sock |
| Installed release | /etc/dplaneos-source.json, or dplaned -version |
| System flake | /etc/nixos/flake.nix (written by the daemon) |
| Daemon state | /var/lib/dplaneos/ |
| Database state | /var/lib/dplaneos/pgsql/ |
| Custom container icons | /var/lib/dplaneos/custom_icons/ |
| Logs | /var/log/dplaneos/ |
| ZED hook | /etc/zfs/zed.d/all-dplaneos-notify.sh |
Quick command reference
# Service control
sudo systemctl status dplaned
sudo systemctl restart dplaned
sudo journalctl -u dplaned -f
# Health check
curl --unix-socket /run/dplaneos/dplaned.sock http://localhost/health
# Interactive recovery (locked out, DB issues, ZFS problems)
sudo dplaneos-recovery
# Database access
sudo -u postgres psql dplaneos -c "\dt"
# ZFS
zpool status
zpool import
# Updates: Updates page; manual rebuild through the system flake
sudo nixos-rebuild switch --flake /etc/nixos#dplaneos --impure
Documentation
Installation and operation
| Document | What it covers |
|---|
| Installation Guide | Requirements, ISO install flow, post-install checklist, OTA upgrades |
| NixOS Install Guide | For NixOS beginners: empty hardware to running NAS |
| Administrator Guide | Users, roles, permissions, storage, containers, LDAP/AD, security |
| Fleet | Many nodes in one view; fleet-wide users, groups and settings rolled out canary first; nodes never depend on the manager |
| Git-Driven NAS | Operating DPlaneOS entirely via state.yaml: bootstrap, auto-apply, rollback, PR workflow, HA |
| Backup and Replication | Snapshots, ZFS send/receive, cloud sync, cold tier, rsync, DB backup, recovery |
| High Availability | HA is optional and off by default. Clusters, the third vote (see also Choosing a third vote), storage groups (shared or replicated), protection layers, planned moves and failover |
| Integration Guide | Prometheus scrape config, Active Directory/Winbind, SMB HA behaviour, NVMe-oF client setup, iSCSI ALUA, GitOps/CI, HA timing, Docker hardware transcoding, GPU passthrough |
|
Reference
| Document | What it covers |
|---|
| Features | Complete feature list by category |
| Pitch | Git as control plane: the enterprise and fleet case |
| Design Philosophy | Four core principles, design decisions, tradeoffs |
| Architecture | Three-layer model, persistence, single-node and HA architecture |
| GitOps Reference | state.yaml format, reconciliation engine, drift detection, Capture workflow |
| Changelog | Full version history |
| Port Reference | Every port the system listens on, its service, interface binding, and safe ranges for Docker containers |
| Error Reference | Every HTTP error code the API returns, with cause and fix |
| NixOS Rationale | Why DPlaneOS is NixOS-exclusive |
| Porting Guide | Forking for other Linux distributions: what it takes, what you lose |
|
Hardware
NixOS
Development
| Document | What it covers |
|---|
| Contributing | Dev setup, project structure, coding conventions, security requirements for PRs |
| Codebase Diagram | Mermaid diagrams: system overview, daemon internals, request lifecycle, disk events, auth flow |
| Design System | Frontend design tokens, spacing grid, component patterns, anti-pattern list |
Legal
| Document | What it covers |
|---|
| License | GNU Affero General Public License v3.0 |
| Notice | Third-party components, attributions, and licenses |
| Security Policy | Vulnerability reporting, safe harbour, supported versions |
| Individual CLA | Contributor license agreement for individuals |
| Entity CLA | Contributor license agreement for organisations |
License
DPlaneOS is licensed under the GNU Affero General Public License v3.0.
If you run a modified version of DPlaneOS and let others interact with it over a network, AGPL § 13 requires that you offer them the Corresponding Source. The unmodified source is at github.com/4nonX/DPlaneOS; if you have modified it, you must make your modifications available to your users on equivalent terms.
Third-party components and their licenses are listed in NOTICE.md.
