Repository navigation
USB Appliance
The ZNAS USB Appliance turns any x86-64 machine into a dedicated ZFS NAS without installing an operating system: flash the image to a USB stick, boot from it, and open the portal. It is the easiest and most secure way to run ZNAS.
Once it runs, you can keep it on the stick or move it to an internal disk (SSD or NVMe) from the portal in a few clicks: no OS installer, no command line. See Moving to an internal disk.

- Immutable OS. A minimal Ubuntu 26.04 LTS runs read-only, loaded into RAM from a compressed image, so the system cannot drift or be tampered with. Reboot and it is exactly as shipped.
- Your settings live apart from the OS, on their own partition of the stick, and survive every upgrade.
- Everything included. Every feature is pre-installed in the image: virtualization (VMs, containers, Compose), the Firewall & router, iSCSI, UPS, disk power management, MergerFS, S3 object storage, remote VM backups. Nothing is downloaded at setup time; you only configure what you use.
- One-click platform upgrades. New images are signed, then downloaded, verified and written by the portal itself (see Upgrading).
- No OS disk needed. All your drives stay free for your pools.
It is a different install path from the one-command installer in Installation, which adds ZNAS to an existing Debian/Ubuntu server.
| Minimum | Recommended | |
|---|---|---|
| USB stick | 8 GB | 32 GB or more, USB 3 or faster. Boot and upgrades read and write ~1.5 GB on the stick, so a fast stick boots and upgrades noticeably quicker |
| Machine | x86-64 (amd64) | |
| RAM | 4 GB | More with ZFS (the ARC uses free RAM) and with virtualization |
| Firmware | UEFI or legacy BIOS | UEFI with Secure Boot works as is (signed Canonical boot chain), no need to disable it |
The stick must stay plugged in while the NAS runs: it holds your settings. To free the USB port, move ZNAS to an internal disk of 32 GB or more.
Download the latest image from the ZNAS USB Appliance releases. Each release has three files:
| File | What it is |
|---|---|
znas-usb-appliance-v26-04-1-3.iso |
The image to flash |
….iso.sha256 |
Checksum to verify the download |
….iso.sig |
Signature, checked by the portal before it installs an upgrade |
The version reads Ubuntu release – appliance build: 26.04.1-3 is the third appliance build on Ubuntu 26.04.1.
Flashing erases everything on the stick.
- balenaEtcher (Windows, macOS, Linux): select the ISO, select the stick, flash.
- Rufus (Windows): select the ISO and choose DD image mode when asked. Its default "ISO image" mode rearranges the files and breaks the appliance's layout.
- dd (Linux, macOS):
sha256sum -c znas-usb-appliance-v26-04-1-3.iso.sha256
sudo dd if=znas-usb-appliance-v26-04-1-3.iso of=/dev/sdX bs=4M conv=fsync status=progressReplace
/dev/sdXwith the whole stick (not a partition like/dev/sdX1, and not your system disk). Check withlsblkfirst.
Do not use Ventoy or any tool that boots an ISO from a file. The appliance owns the whole stick: it creates its settings partition in the free space after the image.
-
Boot the machine from the stick. The boot menu offers:
Entry When to use it ZNAS System (USB appliance) – load OS to RAM (default) Normal use. The OS is copied into RAM, so it runs at RAM speed and the stick is free to be upgraded in place. Keep the stick plugged in. ZNAS System (USB appliance) – run from stick Machines short on RAM. The OS is read from the stick; in-place upgrades are not possible in this mode (flash a new image from another PC instead). ZNAS System (safe graphics) Hardware where the normal boot shows no picture. ZNAS System - load OS to RAM, Realtek vendor NIC driver Older PCs whose Realtek network card (RTL8111/8168, RTL8125) drops its link or gets no connection with the standard driver. Needs Secure Boot off. To keep it on every boot, create /persist/.zfsnas-persist/realtek-vendorand reboot. -
On the first boot the appliance creates its settings partition (
ZFSNAS-PERSIST) in the free space of the stick. -
The console shows the portal address, for example
https://192.168.1.50:8443/setup. Open it from another computer. -
Create your admin account. On the appliance, Allow this account to log in over SSH is ticked by default: it creates a matching Linux account with the same password and
sudorights (it asks for that password). -
Sign in, then import your existing ZFS pools or create new ones from ZFS Pools.
Moving from an installed ZNAS server? Instead of step 4, click Restore from a ZNAS backup on the setup page: your users, shares, settings, pools and VMs come back as they were. See Backup & Migration.
Root SSH stays locked until you set a root password or key in Settings → SSH access.
When you log in on the console or over SSH, a banner shows the appliance release, Ubuntu version, kernel, portal version and address. vi (vim.tiny) is available for quick edits.
Features come with the image, so Requisites → Optional Features only shows each one as Enabled. Nothing can be added or removed there, and the UPS menu is the only one available (to re-detect the UPS or hide its widget):

On first boot the appliance configures itself from the hardware it finds:
- every network port with a cable plugged in becomes a bridge (
vmbr0,vmbr1, …) and the bridge takes the DHCP lease - ports with no link stay on plain DHCP, so plugging a cable in later works
- VMs and containers attach straight to
vmbr0and sit on your LAN, with no extra setup
If bridging fails to get an address, the appliance falls back to plain DHCP about a minute into the boot, so the portal stays reachable. The configuration is generated once: a static IP you set later from the portal is never overwritten.
The appliance also creates one NAT network per connected port (host-nat, host-nat2, …) for guests that should sit behind NAT rather than on your LAN. The Networking table shows which port each one uses.
In Virtualization → Networking, set the address on the bridge (vmbr0), not on the port inside it (enp5s0). Use the bridge's ⋮ menu:
- Edit IP settings…: switch between DHCP and static, set address, gateway and DNS.
- Apply now: applies the change without rebooting. If you are connected through that bridge, reopen the portal on the new address.
Give only one interface a gateway; the portal warns you if you set a second one. See Virtual Networking.
The OS image is read-only, but everything you configure through the portal is saved on the settings partition and survives reboots, power loss and upgrades:
- portal settings, users, TLS certificates and history
- network configuration (including static IPs), hostname, timezone
- SSH host keys, root password and the Linux accounts the portal creates
- SMB shares and users, NFS exports, iSCSI targets, UPS configuration
- the Incus (VMs and containers) database
- ZFS pool import identity, so your pools come back on every boot
Logs and temporary files deliberately stay in RAM, which keeps write wear off the stick.
Changes made by hand over SSH to system files (for example editing
/etcdirectly) do not persist. Make changes through the portal.
Run the appliance from an internal SSD or NVMe drive instead of the USB stick, from the web interface. Nothing changes in how it works: the same signed image is written to the disk, ZNAS still runs from memory, your settings live on their own partition, and upgrades still come as signed images, now written to the internal disk.
It is a good fit for machines with a spare internal drive: it boots faster, frees the USB port and avoids a USB stick wearing out.
- A disk of 32 GB or more that you can erase. The wizard does not offer the disk ZNAS runs from, disks in a ZFS pool, mounted, or in a RAID or LVM volume, or another ZNAS stick.
- UEFI firmware for an NVMe drive (machines in legacy BIOS mode usually can't start from NVMe). Disks that only support 4K sectors can't be used.
- To be logged in to this server directly: the move erases a disk, so it can't be started through InterLink.
-
Go to Platform. The Where ZNAS runs card shows the medium ZNAS started from. Click Move to an internal disk….

-
The first step shows the layout of the disk: ZNAS OS (0–8 GB), Settings (8–16 GB) and, if you want, a ZFS pool zpool-1 on the rest of the disk. Export a backup now saves your settings before you go on (see Backup & Migration).
-
Pick the disk. Each disk shows its size, model and what is on it now; disks that can't be used say why.
-
Choose whether to create a ZFS pool on the rest of the disk (from 16 GB to the end), and its name. Without a pool, the settings partition takes the whole rest of the disk.
-
Confirm with your password (and your 2FA code if you use one).
ZNAS then copies the system to the disk, copies your settings, and creates the pool. Running VMs and containers are stopped during the copy, and the portal restarts. The card follows each step and has the log.
- When the card says ZNAS is on ‹disk›. Remove the USB stick, then restart, do so. The machine now starts from the internal disk.
Settings changed between the move and the restart are not kept: they were copied when the move ran.
ZNAS and the new pool share one disk: if that disk fails, both are lost. Your settings can come back from a backup file; the data on the pool can't. Keep important data on a redundant pool.

- Where ZNAS runs shows the internal disk, its model and size, and the pool on it.
- If the old stick is still plugged in, the card says so: ZNAS doesn't use it any more and you can remove it. The stick is marked as retired, so booting it by mistake shows a message instead of an old copy of your settings.
- If the firmware still starts from another ZNAS disk first, the card warns you to fix the boot order.
- Upgrades from Platform → USB Appliance Upgrades now write the new image to the internal disk, keeping your settings and the pool.
The appliance has two things that update separately:
| What | How | Where |
|---|---|---|
| The appliance image (Ubuntu + all features) | Upgrade from the portal | Platform → USB Appliance Upgrades |
| The ZNAS portal | The regular portal update | Platform → ZFSNAS Instant Update (Platform & Updates) |
Platform → USB Appliance Upgrades shows your appliance release and kernel, and checks GitHub for a newer image. When one is available, Upgrade Appliance offers two choices:
- Stage the Upgrade: download, verify and write the new image now; it takes effect at your next reboot.
- Upgrade Now & Reboot: the appliance reboots into the new image as soon as it is written. Shares, VMs and containers are shut down and come back with it.
The progress bar has three sections:
-
Download (blue). When you have a ZFS pool, the image is downloaded there (
.znas-appliance-tmpat the pool's root) instead of onto the stick: faster, and it spares the stick. The stick is used only when no pool is available. - Verify signature (purple). The image must be signed with the ZNAS key built into the portal; anything else is refused.
- Write to USB stick (red). Only the image part of the stick is rewritten; your settings partition is not touched. Rebooting from the portal is blocked until the write finishes. Do not unplug the stick or power off during this step.
After the reboot the appliance finds its settings partition again, and the card shows the new release.
The upgrade needs the default load OS to RAM boot entry. If the appliance was started with run from stick, the Upgrade button is greyed out: reboot with the default entry first.
Flash the newer image over the same stick with dd, adding conv=notrunc so only the image part is written:
sudo dd if=znas-usb-appliance-v26-04-1-4.iso of=/dev/sdX bs=4M conv=notrunc,fsync status=progressYour settings survive: the appliance finds its settings partition again on the next boot.
Booted with load OS to RAM, as root:
zfsnas-upgrade-image /path/to/znas-usb-appliance-v26-04-1-4.isoIt checks the image's .sha256 (next to it), refuses to run when the OS is being read from the stick, and refuses an image large enough to reach your settings partition.
The image contains the portal version that was current when it was built. On the first boot only, if the appliance can reach the internet, it installs the latest portal release, after verifying its signature. With no internet it tries again on the next boot; after one successful check, portal updates follow the normal update schedule. Details: journalctl -u zfsnas | grep firstboot-update.
| Symptom | Cause | Fix |
|---|---|---|
| Red banner: "running without persistence" | The stick is too small or the settings partition could not be created or mounted | Settings will not survive a reboot. Use a larger stick. |
| Amber banner after a reflash | The new image overlapped the old settings partition | The appliance starts fresh; restore your settings from a backup. |
| Upgrade Appliance is greyed out | The appliance booted with run from stick | Reboot and let the default load OS to RAM entry start. |
| Upgrade refused: signature | The downloaded image is not signed with the ZNAS key | Nothing was written. Check the release, or try again later. |
| A reboot stops at "Please remove the installation medium, then press ENTER" | Only on images older than 26.04.1-3 running an older portal |
Press Enter on the console once, then upgrade: current images and portals no longer stop there. |
| GRUB doesn't boot | Very old BIOS firmware | Try UEFI mode, a firmware update, or another machine. |
| The machine boots but no portal appears | Usually no network address (cable, DHCP) | The console shows the portal address or a "no network address yet" hint. On a headless box use the serial console. |
Every boot entry enables a serial console at 115200 8N1 on the first serial port. On a headless machine with a serial header or BMC/IPMI serial-over-LAN, attach to it to watch the whole boot, including the settings-partition line:
zfsnas-persist: persistence active (adopted) on /dev/sda4
fresh means a new settings partition was created, adopted means an existing one was found (for example after an upgrade), and degraded means the appliance is running without persistence.
The build scripts are in the repository's usbimage/ folder, with a step-by-step HOW-TO-BUILD-ISO.md. Appliances only install upgrades signed with the project's key, so a self-built image is for flashing directly.
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