Repository navigation
Installation
There are two ways to install ZNAS:
| Method | Best for |
|---|---|
| ZNAS Appliance (recommended for a dedicated NAS or router) | A machine given over to ZNAS. Flash the image to a USB stick and boot it: no OS to install. Run it from the stick, or move it to an internal SSD or NVMe disk from the web interface in a few clicks (how). Every feature is included and upgrades are signed images, one click in the portal. |
| One-line installer (below) | An existing Debian 13+ or Ubuntu 26.04+ server, or a VM. Adds ZNAS to the system you already run. |
The fastest and best way to install ZNAS. One command installs ZFS (if needed), creates a dedicated zfsnas service account, downloads the latest binary, and registers a systemd service:
sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/macgaver/zfsnas-chezmoi/main/zfsnas-quickinstall-for-debian.sh)"Supports Debian 13+ and Ubuntu 26.04+. Already root? Drop
sudo. Avoidsudo bash <(curl …): under sudo it fails with/dev/fd/63: No such file or directory.
The installer will:
- Update
aptpackage lists - Install
zfsutils-linuxif not present - Create the
zfsnassystem user - Download the latest binary to
/opt/zfsnas/zfsnas - Write
/etc/systemd/system/zfsnas.serviceand enable it - Print the URL to open in your browser
When it finishes, open the setup wizard:
https://<your-server-ip>:8443/setup
Installing into a Proxmox VM with disk passthrough? See Installation — Proxmox VM first, then come back to the setup steps below.
Want a dedicated NAS without installing an OS at all? The USB Appliance boots a ready-made, immutable ZNAS from a USB stick, and can then move itself to an internal disk from the portal.
| Requirement | Minimum |
|---|---|
| OS | Debian 13 or later — recommended; Ubuntu 26.04 LTS also supported |
| Architecture | x86-64 (amd64) |
| Sudo access | Passwordless sudo for ZFS, Samba, NFS, and SMART commands (see Security for the hardened whitelist) |
| Go (source builds only) | 1.22 or later |
Required system packages are detected and installed automatically by the Requisites page — you don't need to prepare anything:
| Package | Purpose |
|---|---|
zfsutils-linux |
zpool and zfs commands |
samba |
SMB file sharing |
nfs-kernel-server |
NFS exports |
smartmontools |
SMART health data |
nvme-cli |
NVMe wearout and temperature |
util-linux |
Disk listing |
Optional features (iSCSI, UPS, disk power management, remote VM backups, MergerFS, virtualization) are installed on demand from Requisites → Optional Features. The S3 server can no longer be installed on new systems; see S3 Object Storage.

When no admin account exists, the portal sends every visitor to /setup (/setup/ works too):
- Create the admin account: username, email and a strong password.
-
Allow this account to log in over SSH (optional; pre-ticked only on the USB Appliance): creates a matching Linux account with the same password and
sudorights (it asks for that password). If a Linux account with that name already exists and ZNAS did not create it, ZNAS leaves it untouched. -
Sign in. The Requisites page lists any missing system package and offers to register the
zfsnassystemd service if the installer didn't. ZFS Pools lets you import existing pools with one click or create new ones (VDEV type, disks, compression, ashift).
Coming from another ZNAS server (installed or USB Appliance)? Click Restore from a ZNAS backup on the setup page instead of creating an account. See Backup & Migration.
The login screen:

curl -Lo zfsnas https://github.com/macgaver/zfsnas-chezmoi/releases/latest/download/zfsnas-chezmoi
chmod +x zfsnas
./zfsnas# Install Go 1.22+ first (https://go.dev/doc/install)
git clone https://github.com/macgaver/zfsnas-chezmoi.git
cd zfsnas-chezmoi
go build -o zfsnas .
./zfsnas| Option | Default | Description |
|---|---|---|
--config <path> |
./config |
Directory for all config JSON files and certificates |
--set-https-port <n> |
— | Save a new HTTPS port to the config and use it from this run |
--debug |
off | Verbose logging |
--dev |
off | Serve the web UI from disk instead of the binary (development) |
--version |
— | Print the version and exit |
All configuration lives in ./config/ (or the path set by --config). Every file is plain JSON (except audit.log) — inspect and back them up with any text editor or cp.
config/
├── config.json # Port, global settings
├── users.json # Portal user accounts
├── shares.json # SMB share definitions
├── nfs-shares.json # NFS export definitions
├── alerts.json # Alert target configurations
├── snapshot-schedules.json # Automated snapshot policies
├── audit.log # Append-only, one JSON line per event
├── certs/ # TLS certificate + key
└── keys/ # ZFS encryption key files
The auto-generated unit (/etc/systemd/system/zfsnas.service):
[Unit]
Description=ZNAS
After=network.target zfs.target
[Service]
User=zfsnas
WorkingDirectory=/opt/zfsnas
ExecStart=/opt/zfsnas/zfsnas
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.targetCommon commands:
sudo systemctl restart zfsnas
sudo systemctl status zfsnas
sudo journalctl -u zfsnas -fGo to Platform → ZFSNAS Instant Update and click Check for Releases. If a newer release is available you can apply it in place — the portal downloads the new binary, replaces itself, and restarts the service. See Platform & Updates.
sudo systemctl stop zfsnas
sudo curl -Lo /opt/zfsnas/zfsnas https://github.com/macgaver/zfsnas-chezmoi/releases/latest/download/zfsnas-chezmoi
sudo chmod +x /opt/zfsnas/zfsnas
sudo systemctl start zfsnasDowngrading to an older version is blocked by the in-portal updater to prevent accidental configuration regressions.
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