netizenOS VM Setup Guide

This guide covers setting up a local QEMU/KVM virtualization environment on a Debian-based host to run netizenOS images.

---

Prerequisites

• Debian-based Linux Distribution ¹
• Supported CPU architecture: AMD, Intel, RISC-V, MIPS, and ARM
• Virtualization support
• Packages for KVM/QEMU and Libvirt daemon installed
• Python 3.8 or greater
• Python3 libvirt binding via python3-libvirt and other Linux python packages for virt-lightning
• Running libvirtd with system (not session) access via qemu:///system handle.
• Default storage directories exist and have the proper permissions
• Ansible

CPU Virtualization Support

Your CPU must support hardware virtualization. Verify this before proceeding:

grep -c '(vmx\|svm)' /proc/cpuinfo

A result greater than 0 confirms virtualization is supported. If you get 0, check your BIOS/UEFI settings and ensure virtualization is enabled — it is sometimes disabled by default.

• Intel CPUs: look for VT-x or VMX in BIOS settings
• AMD CPUs: look for AMD-V or SVM in BIOS settings

Checking all of this may be cumbersome, so we have created a utility in Python to verify if all of these are set up properly. The script must be run as root using sudo.

sudo python precheck.py

You should see the following output when everything is installed correctly:

=== Neticenters Testing Infrastructure Check ===
✓ Debian-based Linux distribution with apt detected
✓ Supported CPU architecture detected: x86
✓ AMD CPU supporting AMD-V
✓ Python 3.8 or greater is installed
✓ Required libvirt packages are installed
✓ Successfully connected to libvirt daemon at qemu:///system
✓ All virt-lightning requirements are installed
✓ All virt-lightning directories are properly configured
✓ virt-lightning is installed

✓ All checks passed for neticenters testing and development.

---

Installation

Install libvirt-daemon-system which sets up a complete local QEMU/KVM hypervisor in one step, including the libvirt daemon, client tools, QEMU drivers, and KVM dependencies:

sudo apt update
sudo apt install libvirt-daemon-system

This installs and enables:

• libvirt-daemon — the core libvirt daemon
• libvirt-clients — CLI tools including virsh
• libvirt-daemon-driver-qemu — QEMU/KVM driver
• qemu-system — QEMU system emulator
• ovmf — UEFI firmware for VMs

Also install virt-install for creating VMs and virt-viewer for graphical console access:

sudo apt install virtinst virt-viewer

---

User Group Membership

Your user must belong to both the libvirt and kvm groups to manage VMs without sudo.

sudo usermod -aG libvirt,kvm,libvirt-qemu $USER

Log out and back in for group membership to take effect, then verify:

groups

You should see both libvirt and kvm in the output.

---

Directory Permissions

The libvirt image storage directory must be accessible to members of the libvirt group. Verify the current permissions:

sudo ls -lah /var/lib/libvirt/

Expected permissions:

Directory	Owner	Group	Mode
/var/lib/libvirt/	root	root	drwxr-xr-x
/var/lib/libvirt/images/	root	libvirt	drwxrwx--x
/var/lib/libvirt/qemu/	libvirt-qemu	kvm	drwxr-x---

If the images/ directory is not owned by the libvirt group, fix it:

sudo chown root:libvirt /var/lib/libvirt/images
sudo chmod 775 /var/lib/libvirt/images

The qemu/ directory is managed by libvirt itself and should not be modified manually.

---

Default Network

libvirt ships with a default NAT network (192.168.122.0/24) that provides connectivity for VMs. Check whether it is running:

virsh net-list --all

Expected output when active:

 Name      State    Autostart   Persistent
--------------------------------------------
 default   active   yes         yes

If the default network is inactive, start it and enable autostart:

virsh net-start default
virsh net-autostart default

If the default network is not defined at all:

virsh net-define /usr/share/libvirt/networks/default.xml
virsh net-start default
virsh net-autostart default

---

Copying the netizenOS Image

Copy your built netizenOS image to the libvirt image pool:

cp netizenOS-amd64.img /var/lib/libvirt/images/

---

Creating and Booting the VM

Use virt-install to define and start the VM. netizenOS requires UEFI boot without Secure Boot — passing the OVMF firmware paths explicitly ensures the correct firmware is used, as the default OVMF variant selected by --boot uefi includes Secure Boot which will reject the unsigned netizenOS bootloader.

sudo virt-install \
  --name netizenOS \
  --memory 2048 \
  --vcpus 2 \
  --disk path=/var/lib/libvirt/images/netizenOS-amd64.img,format=raw,bus=virtio \
  --import \
  --os-variant debian13 \
  --network network=default \
  --graphics none \
  --console pty,target_type=serial \
  --boot loader=/usr/share/OVMF/OVMF_CODE.fd,loader.readonly=yes,loader.type=pflash,nvram.template=/usr/share/OVMF/OVMF_VARS.fd,loader_secure=no

Parameter Notes

Parameter	Purpose
--import	Boot from existing disk image, skip installer
--os-variant debian13	Optimizes virtual hardware for Debian 13 (Trixie)
bus=virtio	Presents disk as a virtio device, required for UEFI to locate the bootloader
OVMF_CODE.fd	Non-Secure Boot UEFI firmware
OVMF_VARS.fd	Matching UEFI variable store
loader_secure=no	Explicitly disables Secure Boot

The --graphics none disables the SPICE display entirely and --console pty,target_type=serial connects your terminal directly to the serial console we set up in the image. You should see the full boot output stream directly in your terminal and land at the login prompt without needing virt-viewer.

Why Non-Secure Boot

netizenOS ships an unsigned GRUB bootloader. Secure Boot requires bootloaders to be signed with a trusted key — unsigned bootloaders are silently rejected, resulting in a "no bootable device" error at startup. Non-Secure Boot UEFI is standard practice for custom and community OS projects. Secure Boot support is planned for a future production mode release.

---

Connecting to the VM

Open a graphical console:

virt-viewer netizenOS

Or connect via the serial console:

virsh console netizenOS

To detach from the serial console without stopping the VM press Ctrl+].

---

Managing the VM

Check VM status:

virsh list --all

Stop the VM gracefully:

virsh shutdown netizenOS

Force stop:

virsh destroy netizenOS

Remove the VM definition (does not delete the disk image):

virsh undefine netizenOS --nvram

The --nvram flag removes the UEFI variable store alongside the VM definition. Omitting it will leave an orphaned NVRAM file in /var/lib/libvirt/qemu/nvram/.

---

1. We require a Debian-based Linux distribution to simplify verification of libraries by only assuming apt and other system calls to verify system state. This will only be used for the build distributions and may include other Linux distributions moving forward. ↩︎