User:Egberts/Drafts/Libvirt/QEMU guest
This article details the creation of a guest virtual machine (VM), running inside a QEMU hypervisor, using tools found in libvirt package.
CLI tools like virt-install and virsh commands are detailed here, as well as in Libvirt.
For creation of the virtual machine using a GUI tool, see virt-manager/QEMU guest.
Installation
Creation of a virtual machine entails the following stages for a new domain:
- Boot ROM
- Bootloader Manager
- OS
- Network
- Passthru devices (optional)
Initialize domain file
First step is to get an XML-format file as the new domain's configuration file.
root #
virt-install --osinfo gentoo --cdrom ~/Downloads/livegui-amd64-20250216T164837Z.iso
Using default --name gentoo-2 Using gentoo default --memory 512 Using gentoo default --disk size=5 Starting install... Allocating 'gentoo-2.qcow2' | 0 B 00:00:00 ... Creating domain... | 0 B 00:00:00 Running graphical console command: virt-viewer --connect qemu:///system --wait gentoo-2
Domain configuration file are stored in /etc/libvirt/qemu/gentoo-2.xml.
See Libvirt/domain for all tools that interact with this domain configuration file.
Configuration
domain configuration file
Create the domain configuration file:
The non-working example gives a default of:
root #
virt-install --osinfo gentoo --cdrom ~/Downloads/livegui-amd64-20250216T164837Z.iso
Using default --name gentoo-2 Using gentoo default --memory 512 Using gentoo default --disk size=5 Starting install... Allocating 'gentoo-2.qcow2' | 0 B 00:00:00 ... Creating domain... | 0 B 00:00:00 Running graphical console command: virt-viewer --connect qemu:///system --wait gentoo-2
Boot ROM
Bootloader ROM is the very first piece of software to run after a domain's CPU has been powered on or after a reset.
Start Address
For x86 32-bit architecture, the starting program counter (PC) address is 0xFFFFFFF0. For x86_64/amd64 architecture, starting PC address if 0x0000000000000000. PowerPC is 0xFFF00100. RISC-V is 0x80000000. Memory type at starting PC address is usually read-only or in ROM/PROM/EPROM/EEPROM/UEFI.
This Bootloader ROM setting cannot be changed once set. Not even `virt-xml` CLI command will let you change this. So, plan ahead.
To enable BIOS menu, add menu=on to the --bios option:
user $
virt-install ... --boot bios,menu=on ...
To enable bootloader menu, add menu=on to the --boot option:
user $
virt-install ... --boot bios,menu=on ...
UEFI
UEFI boot is the default for virt-install.
To disable UEFI completely, use --boot uefi=off:
user $
virt-install ... --boot uefi=off ...
To explicitly enable UEFI, use --boot uefi.
Custom UEFI
Custom UEFI are provided by ovfm. UEFI bootloader image and support files are located in Libvirt boot image directory.
Custom UEFI bootloaders and module image files are in the /var/share/OVMF directory.
To use a custom UEFI bootloader and/or module image file(s), place the copy of the file(s) into the Libvirt boot image directory.
root #
cp my_ovmf_boot_image.fd /var/share/OVMF/
To use the custom UEFI boot image file, add following option to virt-install:
root #
virt-install ... --bios ...
EFI stubs go into the /efi/EFI subdirectories.
Use efibootmgr to manage the boot entries in UEFI.
BIOS
To enable BIOS, use --boot bios:
user $
virt-install ... --boot bios ...
To enable BIOS menu, use -bios.
user $
virt-install ... -bios ...
Custom BIOS
BIOS image files are located in /var/lib/libvirt/boot directory. Custom UEFI are also found in /var/share/OVMF provided by ovfm.
To use a custom boot file, place the copy of custom boot image file into the Libvirt boot image directory.
root #
cp my_bios_image.fd /var/lib/libvirt/boot/
To use the custom boot image file, add following option to virt-install:
root #
virt-install ... --bios ...
user $
virt-install ... -bios ...
Depending on the CPU architecture selected, QEMU provides several types of ROM images to provide for your OS/Boot ROM needs before starting its first instruction via CPU program counter (PC) into this virtual machine's emulation.
Bootloader Manager
In desktop/workstation, bootloader manager makes upgrade of operating systems easiest.
Embedded system often opt to skimp on bootloader manager and boot directly into the operating system. However, many embedded system will provide a thin-shim of a bootloader for ease of upgrading of CMOS/Flash/EEPROM.
{{Note|The menu selector is not the same scope between a BIOS {{{1}}} and a Bootloader {{{1}}}.
Creating a domain (virtual machine)
XML editing used to be done using older virt-xml-edit tool, now it is virsh edit.
app-emulation/virt-manager includes virt-installer
. Therefore, with only app-emulation/libvirt the VM xml must be created first, then either imported with virsh edit /path/to/vm.xml
or virsh define /path/to/vm.xml
root #
virsh define gentoo-vm.xml
Domain 'gentoo' defined from gentoo-vm.xml
Additional software
Guest Linux OS requires sys-power/acpid for proper handling of guest shutdown that are initiated by the host OS using libvirt.
Installing a new domain
Decide on a name for this virtual machine (--name gentoo-2).
Locate the path to your ISO boot image file (--cdrom <your_Gentoo_livecdrom.iso>).
Determine how much guest virtual memory to have (--memory 384 for 384 MiB).
Allocate how much disk space to set aside for this virtual machine (--disk size=2 for 2 GiB in default location).
Make it a fully-virtualized machine (--hvm or -v).
Then execute:
user $
virt-install --name gentoo-2 --memory 384 --disk size=2 --cdrom <your_Gentoo_cdrom.iso> --hvm
Usage
List domains (virtual machines)
To list all registered domains (VMs), execute:
root #
virsh list --all
Id Name State --------------------------- 4 gentoo running 5 gentoo-2 running - debian11 shut off
Name column shows the domain names.
To list all (default) active domains, execute:
root #
virsh list
Id Name State --------------------------- 4 gentoo running 5 gentoo-2 running
Starting a domain
To start a domain (virtual machine), execute:
root #
virsh start <domain-name>
To enabling autostart, execute:
root #
virsh autostart <domain-name>
Viewing the console of a domain
There are two different ways to view a virtual machine's console/display:
- thru virt-viewer over SPICE/TCP network protocol
- thru virt-manager viewport over UNIX socket
Console by virt-manager
See Virt-manager/QEMU_guest for GUI-based viewing of VM's console.
Console by virt-viewer
To use the virt-viewer in starting VM from the shell, execute:
user $
virt-viewer --connect=qemu:///session --domain-name gentoo-2
To just display the window but not start the VM yet, execute:
user $
virt-viewer --connect=qemu:///session --wait --domain-name gentoo-2
Shutdown an active domain
Shutdown of a domain is done using one of the following:
- From the host platform:
- In host shell, execute virsh shutdown
- In virt-manager main menu bar using Virtual Machine -> Shutdown
- From within the guest virtual machine:
- From the shell, shutdown -h -t 0
- From the window manager, Start -> Shutdown icon
From the host OS (outside the guest OS) CLI, the usage syntax to perform a domain (VM) shutdown is:
root #
virsh shutdown --help
NAME shutdown - gracefully shutdown a domain SYNOPSIS shutdown <domain> [--mode <string>] DESCRIPTION Run shutdown in the target domain. OPTIONS [--domain] <string> domain name, id or uuid --mode <string> shutdown mode: acpi|agent|initctl|signal|paravirt
root #
virsh shutdown <domain>|<vm-id>|<uuid>
Hard shutdown, similar to pulling the power cord on a physical machine. This type of shutdown lets the machine abruptly interrupts any state that the operation system has been maintaining.
root #
virsh destroy <domain>|<vm-id>|<uuid>
`destroy` is different than `undefine`; one is to power-down a virtual machine from running in an abrupt manner (no state machine will be saved); the other is to remove from the list of domain and, as an optional step, from its hard drive via `--remove-all-storage` option
Delete and destroy a domain
For removing a virtual machine from the list of VM maintained by libvirtd, its usage syntax is:
root #
virsh undefine --help
NAME undefine - undefine a domain SYNOPSIS undefine <domain> [--managed-save] [--storage <string>] [--remove-all-storage] [--delete-storage-volume-snapshots] [--wipe-storage] [--snapshots-metadata] [--checkpoints-metadata] [--nvram] [--keep-nvram] [--tpm] [--keep-tpm] DESCRIPTION Undefine an inactive domain, or convert persistent to transient. OPTIONS [--domain] <string> domain name, id or uuid --managed-save remove domain managed state file --storage <string> remove associated storage volumes (comma separated list of targets or source paths) (see domblklist) --remove-all-storage remove all associated storage volumes (use with caution) --delete-storage-volume-snapshots delete snapshots associated with volume(s), requires --remove-all-storage (must be supported by storage driver) --wipe-storage wipe data on the removed volumes --snapshots-metadata remove all domain snapshot metadata (vm must be inactive) --checkpoints-metadata remove all domain checkpoint metadata (vm must be inactive) --nvram remove nvram file --keep-nvram keep nvram file --tpm remove TPM state --keep-tpm keep TPM state
To completely remove the virtual machine from the list of domains, and and delete all images files related to this domain's storage(s), execute:
root #
virsh undefine --remove-all-storage <domain>
Domain 'gentoo-2' has been undefined Volume 'vda'(/var/lib/libvirt/images/gentoo-2.qcow2) removed.
See also
- QEMU — a generic, open-source hardware emulator and virtualization suite.
- QEMU/Linux guest — describes the setup of a Gentoo Linux guest in QEMU using Gentoo bootable media.
- Libvirt — a virtualization management toolkit.
- Libvirt/QEMU_networking — details the setup of Gentoo networking by Libvirt for use by guest containers and QEMU-based virtual machines.
- Virt-manager — desktop user interface for management of virtual machines and containers through the libvirt library
- Virt-manager/QEMU_guest — creation of a guest virtual machine (VM) running inside a QEMU hypervisor using just the virt-manager GUI tool.
External resources
- Libvirt Domain XML Format - Detailed description of a Domain XML format file.
- file:///usr/share/doc/libvirt-doc/ - Documentation for libvirt (via app-emulation/libvirt).
- andreaskaris.github.io/blog - Libvirt UEFI without SecureBoot