Skip to content

USB Appliance

gitsync edited this page Nov 17, 2026 · 2 revisions

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.

USB Appliance Upgrades card

What it is

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


What you need

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.


Getting the image

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.


Creating the USB stick

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=progress

Replace /dev/sdX with the whole stick (not a partition like /dev/sdX1, and not your system disk). Check with lsblk first.

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.


First boot

  1. 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-vendor and reboot.
  2. On the first boot the appliance creates its settings partition (ZFSNAS-PERSIST) in the free space of the stick.

  3. The console shows the portal address, for example https://192.168.1.50:8443/setup. Open it from another computer.

  4. 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 sudo rights (it asks for that password).

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

Optional Features on the appliance

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):

Optional Features on the appliance


Networking out of the box

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 vmbr0 and 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.

Setting a static IP

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.


What persists

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 /etc directly) do not persist. Make changes through the portal.


Moving to an internal disk

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.

What you need

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

How it works

  1. Go to Platform. The Where ZNAS runs card shows the medium ZNAS started from. Click Move to an internal disk….

    Move ZNAS to an internal disk

  2. 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).

  3. Pick the disk. Each disk shows its size, model and what is on it now; disks that can't be used say why.

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

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

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

After the move

Where ZNAS runs

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

Upgrading

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)

From the portal (recommended)

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:

  1. Download (blue). When you have a ZFS pool, the image is downloaded there (.znas-appliance-tmp at 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.
  2. Verify signature (purple). The image must be signed with the ZNAS key built into the portal; anything else is refused.
  3. 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.

From another computer

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=progress

Your settings survive: the appliance finds its settings partition again on the next boot.

From the appliance's command line

Booted with load OS to RAM, as root:

zfsnas-upgrade-image /path/to/znas-usb-appliance-v26-04-1-4.iso

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


First boot: automatic portal update

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.


Troubleshooting

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.

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.


Building your own image

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.

Clone this wiki locally