Skip to content

Installation

gitsync edited this page Nov 17, 2026 · 6 revisions

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 one-line installer (recommended)

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. Avoid sudo bash <(curl …): under sudo it fails with /dev/fd/63: No such file or directory.

The installer will:

  1. Update apt package lists
  2. Install zfsutils-linux if not present
  3. Create the zfsnas system user
  4. Download the latest binary to /opt/zfsnas/zfsnas
  5. Write /etc/systemd/system/zfsnas.service and enable it
  6. 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.


System requirements

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.

Requisites — Optional Features


First-run setup

When no admin account exists, the portal sends every visitor to /setup (/setup/ works too):

  1. Create the admin account: username, email and a strong password.
  2. 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 sudo rights (it asks for that password). If a Linux account with that name already exists and ZNAS did not create it, ZNAS leaves it untouched.
  3. Sign in. The Requisites page lists any missing system package and offers to register the zfsnas systemd 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:

Login screen


Alternative install options

Download a release binary

curl -Lo zfsnas https://github.com/macgaver/zfsnas-chezmoi/releases/latest/download/zfsnas-chezmoi
chmod +x zfsnas
./zfsnas

Build from source

# 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

Command-line options

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

Configuration files

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

Systemd service

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.target

Common commands:

sudo systemctl restart zfsnas
sudo systemctl status zfsnas
sudo journalctl -u zfsnas -f

Upgrading

In-portal (recommended)

Go 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.

Manual

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 zfsnas

Downgrading to an older version is blocked by the in-portal updater to prevent accidental configuration regressions.

Clone this wiki locally