Virtualization

LXC containers and virtual machines with Incus: images, ISO library, resources, network, shares, snapshots and console.

Requirements

• The installer installs the package incus (Debian 13) together with ovmf (UEFI firmware for VMs). Bunkerbox talks to Incus only through the REST API on /var/lib/incus/unix.socket; only the console uses the incus program.
• A ZFS pool for the instances, ideally the SSD pool apps.
• For addresses from your home network: the LAN bridge br0 (see Network). Without the bridge only the NAT network and "No network" are available.
• VMs need hardware virtualization (Intel VT-x or AMD-V enabled in the BIOS).

Setup

The first time you open Virtualization, the card Set up virtualization appears:

Field	Meaning
Dataset for instances	e.g. apps/incus. The dataset must not exist yet; Incus creates it and manages one dataset or volume per instance below it (storage pool bunkerbox, driver zfs).
Dataset for the ISO library	e.g. apps/iso. Created (mountpoint /apps/iso) or, if it exists, adopted.

The Incus NAT network incusbr0 is created as well (private IPv4/IPv6 addresses, internet through the host). Parts that already exist stay unchanged; if Incus already has a ZFS storage pool (e.g. from incus admin init), that one is used. The ISO setting lives in data/virtualization-state.json (600), everything else in Incus itself.

Instances

The list shows name, type (LXC or VM), status, resources, network and addresses of every instance and refreshes every 10 s (every 2 s while an operation runs). An instance whose image is still downloading appears with a progress bar; if the creation fails, it stays visible with the error message for 15 minutes.

Action	Effect
Start	starts the instance
Stop	clean shutdown, fails after 60 s
Restart	reboots the system in the instance
Force stop	turns it off immediately, like pulling the plug
Delete	type the name; a running instance is turned off first. Instance, disk and snapshots are deleted, mounted directories are not touched.

Operations run in the background; at most one per instance. While an operation runs (e.g. an image download), Bunkerbox refuses updates.

New instance

• Type: container (LXC, uses the host kernel, Linux only) or virtual machine (QEMU with UEFI).
• Name: letters, digits and -, starting with a letter, not ending with -, at most 63 characters; also the host name. new is reserved.
• Source:
  • Image from images.linuxcontainers.org (Debian, Ubuntu, Alpine, Arch, Fedora, Rocky ...). The list is reloaded every 6 h and only shows images available for the selected type and the host architecture. Other image servers are not allowed.
  • ISO from the library (VMs only): empty disk, the ISO is attached read-only with boot priority. The installation runs in the text console. Afterwards remove the ISO under Settings, otherwise the VM boots the installer again. UEFI Secure Boot can be turned off for ISOs without a signed boot loader.
• Resources: vCPUs (at most the host's CPU threads), memory and disk in GiB. Empty fields mean no limit for containers; VMs get the Incus defaults (1 vCPU, 1 GiB) when left empty.
• Network: LAN bridge (own address from the router, reachable in the home network), NAT network (incusbr0, outgoing only) or No network.
• Start after creation and Start automatically at boot (boot.autostart).

Instances are created without Incus profiles; root disk (root), network card (eth0) and ISO (install-iso) are devices of the instance itself.

Settings

Resources, network, autostart, description and, for VMs, the attached ISO can be changed later. The disk can only grow. Some changes only take effect after a restart (e.g. memory of a running VM); Incus reports what it cannot change live as an error.

Share directories

Host directories are mounted into the instance as Incus devices of type disk, optionally read-only.

• Allowed are directories below a share, a mounted dataset or /appdata. Excluded are /appdata itself, /appdata/bunkerbox and the actual install and data directory of Bunkerbox (credentials, also when BUNKERBOX_HOME or BUNKERBOX_DATA_DIR point elsewhere) as well as the datasets of the instance pool. The path must not contain a symbolic link.
• System directories such as /etc, /usr, /proc and /var itself cannot be the target inside the instance.
• Containers mount the directory as an idmapped mount (shift=true): files show their real owners inside, and root in the container can write there like root on the host. Mount it read-only for foreign or untrusted containers.
• VMs mount the directory through virtiofs; the Incus agent in the VM mounts it automatically (included in the images).

Snapshots

Snapshots are ZFS snapshots of the instance (disk state without memory). Without a name a snapshot is called snap-<date>-<time>. Restoring and deleting require the typed snapshot name; restoring loses every change since the snapshot.

Console

The Console tab opens a terminal in the browser (WebSocket channel incus-console, the same technique as the terminal):

Type	Command	Note
Shell	incus exec <name> -- /bin/sh -c ...	Root shell (bash, otherwise sh). For VMs only with a running Incus agent.
Text console	incus console <name> --type console	Serial console, e.g. for boot messages and text installers.

At most 8 consoles can be open at the same time. Every session appears in the audit log (terminal.open/terminal.close with target incus-console:<name>). There is no graphical console (VGA/SPICE), so installers with a graphical interface cannot be used. Debian and Ubuntu offer a text or serial installer.

ISO library

The ISO library card lists the .iso files in the directory of the ISO dataset and the VMs they are attached to.

• Upload ISO sends the file in 8 MiB pieces so every request stays below the size limit of the access check. The file is written as .upload-<id>.part (600) and only appears under its name after the last piece; existing files are never overwritten. A cancelled upload is deleted, an abandoned one after an hour without data. At most 64 GiB per file; free space is checked first. Bunkerbox refuses updates during an upload.
• File names: letters, digits, ., _, + and -, ending in .iso.
• ISOs can also be copied into the directory over SMB when it is shared.
• Deleting requires the typed file name and is refused while a VM has the ISO attached.

Backup

The appdata backup (Backup) can shut instances down before the ZFS snapshot and start them again afterwards. As data dataset, virtualization reports the dataset of the storage pool (e.g. apps/incus).

Troubleshooting

• systemctl status incus and journalctl -u incus show the state of the service.
• incus list, incus info <name> --show-log and incus config show <name> --expanded show what Incus knows about an instance.
• If a VM does not start, hardware virtualization (/dev/kvm) is often missing, or the ISO needs Secure Boot turned off.