User:Egberts/Drafts/Libvirt/QEMU guest

From Gentoo Wiki
Jump to:navigation Jump to:search

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.

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

Note
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

Note
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.
Warning
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)

Note
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>
Warning
`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.
  • 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