Repository navigation
Home
Welcome to the ZNAS documentation — the official guide for installing, configuring, and operating your ZFS NAS server through the ZNAS portal.

ZNAS is a self-hosted NAS management web application. It runs as a single binary with no database, no Docker requirement, and no Node.js runtime. Everything — the backend, the web frontend, and all static assets — is compiled into one executable that you place next to a config/ folder and run.
- Zero runtime dependencies — one binary, cold start under one second
-
No database — config lives in plain JSON files; back up with
cp - HTTPS on first launch — self-signed TLS certificate generated automatically
- Guided setup — create your admin account in the browser; the portal then points you to anything missing and imports or creates your pools
- Optional virtualization — run VMs and containers (Incus) next to your storage, managed from the same portal
- Optional firewall & router — replace your router VM: interfaces and VLANs, rules by country, NAT, gateway failover, DHCP/DNS with ad blocking, WireGuard, intrusion detection, and a live map of who talks to whom
- USB appliance — or skip the OS install entirely: boot a ready-made, immutable NAS from a USB stick, move it to an internal disk from the portal if you like, with one-click signed upgrades
USB appliance: the easiest and most secure. Download the latest image, flash it to a USB stick (8 GB minimum, 32 GB or more on USB 3 or faster recommended), boot your NAS from it, and open the address shown on screen. See USB Appliance. Then keep it on the stick, or install it on an internal disk (32 GB or more) from the web interface: Platform → Where ZNAS runs → Move to an internal disk… (details).
On your own Debian 13+ / Ubuntu 26.04+ server, in one command:
sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/macgaver/zfsnas-chezmoi/main/zfsnas-quickinstall-for-debian.sh)"Already root? Drop
sudo. Avoidsudo bash <(curl …): under sudo it fails with/dev/fd/63: No such file or directory.
Then open https://<your-server-ip>:8443/setup and create your admin account. Full details in Installation.
| Page | Description |
|---|---|
| Installation | One-line installer, manual options, first-run wizard, upgrading |
| Installation — Proxmox VM | Running ZNAS inside a Proxmox VM with disk passthrough |
| USB Appliance | Bootable USB image — flash it, boot it: an immutable NAS with every feature included and one-click upgrades; move it to an internal disk from the portal |
| Page | Description |
|---|---|
| Dashboard & Monitoring | Performance charts, live gauges, activity & events, alerts |
| Physical Disks | Disk inventory, SMART health, temperatures, wearout |
| ZFS Pools | Create/import pools, cache & spares, scrub, ARC, Pool Fixer Wizard |
| Datasets & ZVols | Datasets, block devices, properties, File Browser, TreeMap |
| MergerFS | Union filesystem pooling multiple datasets/paths into one mount |
| Snapshots & Protection | Snapshots, schedules, ZFS replication, filesystem rsync |
| File Sharing — SMB | Samba shares for Windows/macOS/Linux clients |
| File Sharing — NFS | NFS exports for Unix clients |
| iSCSI | Block-level targets backed by ZVols |
| S3 Object Storage | MinIO S3-compatible object server (existing installs; alternatives under evaluation) |
| Capacity Trends | Long-term capacity charts, Folders TreeMap, live Topology map |
| Encryption | ZFS native AES-256-GCM encryption and key management |
| UPS Management | NUT integration, battery widget, shutdown policy |
| Page | Description |
|---|---|
| Virtualization Overview | What it is, enabling it, hardware requirements, sidebar modes |
| VMs & Containers | Create and manage virtual machines and LXC containers |
| Virtual Networking | Bridges, VLANs, and the live network topology map |
| Datastores & VM Backups | Instance storage, backup/restore, remote backup targets |
| InterLink | Link multiple ZNAS servers — remote view, push replication, remote backups |
| Page | Description |
|---|---|
| Firewall & Router | Optional router mode: Local Topo map, interfaces and VLANs, rules by country, NAT, routing with gateway failover and PPPoE, DHCP/DNS with blocklists and Pi-hole-style reports, WireGuard, Dynamic DNS, intrusion detection, and the Traffic & GeoMap |
| Page | Description |
|---|---|
| User Management | Roles, granular permissions, sessions, API keys |
| Settings & Alerts | Portal settings, notification targets, certificates |
| Backup & Migration | Encrypted configuration export / import, moving to new hardware or the USB appliance |
| Security | Sudo hardening, TLS, authentication model, 2FA |
| Platform & Updates | Portal self-update, OS updates, appliance upgrades, web terminal, Requisites |
| Troubleshooting | Common issues and their solutions |
| Page | Description |
|---|---|
| ZFS Basic | ZFS concepts, key properties, commands, learning resources |
- GitHub repository: https://github.com/macgaver/zfsnas-chezmoi
- USB appliance images: https://github.com/macgaver/znas-usb-appliance/releases
-
Default portal URL:
https://<server-ip>:8443 - License: GPLv3
Getting Started
Storage
- Dashboard & Monitoring
- Physical Disks
- ZFS Pools
- Datasets & ZVols
- MergerFS
- Snapshots & Protection
- File Sharing — SMB
- File Sharing — NFS
- iSCSI
- S3 Object Storage
- Capacity Trends
- Encryption
- UPS Management
Virtualization
Networking
Administration
Reference