Skip to content
gitsync edited this page Nov 17, 2026 · 10 revisions

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

ZNAS Performance dashboard

What is ZNAS?

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

Two ways to run ZNAS

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. Avoid sudo 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.

Documentation

Getting started

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

Storage — the NAS core

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

Virtualization

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

Networking

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

Administration

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

Reference

Page Description
ZFS Basic ZFS concepts, key properties, commands, learning resources

Quick links

Clone this wiki locally