libvirt/domain

From Gentoo Wiki
Jump to:navigation Jump to:search

A domain represents a virtualized instance within the libvirtd library/package/API. This instance could be a virtual machine, a container, or any other virtualized environment managed by libvirt.

Available software

Tools that exist to interact, maintain, and configure the domain file:

Domain file

The format of a domain configuration file is XML.

File name of the domain configuration file is user-definable and accepted by UNIX-like filesystem.

File type of the domain configuration file is .xml.

Domain location

The domain file is stored in the:

  • /etc/libvirt/qemu directory for session-defined (user) VMs.
  • /var/lib/libvirt directory for system-defined (root) VMs.

Example

Libvirt/QEMU guest, virt-manager, or virt-install creates the domain file.

The virt-install is done by executing:

host-platform-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

to create this default domain configuration file.

Important
There is no other way to starts new Libvirt domain XML file other than to use the virt-install, virt-manager or copy from another domain XML file. virsh itself cannot initialize or seed an XML file. In a strict Gentoo way, only virt-manager is available (see Virt-manager/QEMU guest for creating a new domain file).

Lifecycle of domain

For overview relation graph of tools that work with the domain file, see below:

Libvirt domain XML-format file


For more domain interactions, see Libvirt Virtual Machine Lifecycle[1].

File format

The actual default domain XML file is:

FILE /etc/libvirt/qemu/gentoo-vm.xml
<domain type='kvm'>
  <name>gentoo-2</name>
  <uuid>e171ac3a-17a6-46ab-94a3-ba5ef25d4427</uuid>
  <metadata>
    <libosinfo:libosinfo xmlns:libosinfo="http://libosinfo.org/xmlns/libvirt/domain/1.0">
      <libosinfo:os id="http://gentoo.org/gentoo/rolling"/>
    </libosinfo:libosinfo>
  </metadata>
  <memory unit='KiB'>524288</memory>
  <currentMemory unit='KiB'>524288</currentMemory>
  <vcpu placement='static'>1</vcpu>
  <os>
    <type arch='x86_64' machine='pc-q35-7.2'>hvm</type>
    <boot dev='hd'/>
  </os>
  <features>
    <acpi/>
    <apic/>
    <vmport state='off'/>
  </features>
  <cpu mode='host-passthrough' check='none' migratable='on'/>
  <clock offset='utc'>
    <timer name='rtc' tickpolicy='catchup'/>
    <timer name='pit' tickpolicy='delay'/>
    <timer name='hpet' present='no'/>
  </clock>
  <on_poweroff>destroy</on_poweroff>
  <on_reboot>restart</on_reboot>
  <on_crash>destroy</on_crash>
  <pm>
    <suspend-to-mem enabled='no'/>
    <suspend-to-disk enabled='no'/>
  </pm>
  <devices>
    <emulator>/usr/bin/qemu-system-x86_64</emulator>
    <disk type='file' device='disk'>
      <driver name='qemu' type='qcow2' discard='unmap'/>
      <source file='/var/lib/libvirt/images/gentoo-2.qcow2'/>
      <target dev='vda' bus='virtio'/>
      <address type='pci' domain='0x0000' bus='0x04' slot='0x00' function='0x0'/>
    </disk>
    <disk type='file' device='cdrom'>
      <driver name='qemu' type='raw'/>
      <target dev='sda' bus='sata'/>
      <readonly/>
      <address type='drive' controller='0' bus='0' target='0' unit='0'/>
    </disk>
    <controller type='usb' index='0' model='qemu-xhci' ports='15'>
      <address type='pci' domain='0x0000' bus='0x02' slot='0x00' function='0x0'/>
    </controller>
    <controller type='pci' index='0' model='pcie-root'/>
    <controller type='pci' index='1' model='pcie-root-port'>
      <model name='pcie-root-port'/>
      <target chassis='1' port='0x10'/>
      <address type='pci' domain='0x0000' bus='0x00' slot='0x02' function='0x0' multifunction='on'/>
    </controller>
    <controller type='pci' index='2' model='pcie-root-port'>
      <model name='pcie-root-port'/>
      <target chassis='2' port='0x11'/>
      <address type='pci' domain='0x0000' bus='0x00' slot='0x02' function='0x1'/>
    </controller>
    <controller type='pci' index='3' model='pcie-root-port'>
      <model name='pcie-root-port'/>
      <target chassis='3' port='0x12'/>
      <address type='pci' domain='0x0000' bus='0x00' slot='0x02' function='0x2'/>
    </controller>
    <controller type='pci' index='4' model='pcie-root-port'>
      <model name='pcie-root-port'/>
      <target chassis='4' port='0x13'/>
      <address type='pci' domain='0x0000' bus='0x00' slot='0x02' function='0x3'/>
    </controller>
    <controller type='pci' index='5' model='pcie-root-port'>
      <model name='pcie-root-port'/>
      <target chassis='5' port='0x14'/>
      <address type='pci' domain='0x0000' bus='0x00' slot='0x02' function='0x4'/>
    </controller>
    <controller type='pci' index='6' model='pcie-root-port'>
      <model name='pcie-root-port'/>
      <target chassis='6' port='0x15'/>
      <address type='pci' domain='0x0000' bus='0x00' slot='0x02' function='0x5'/>
    </controller>
    <controller type='pci' index='7' model='pcie-root-port'>
      <model name='pcie-root-port'/>
      <target chassis='7' port='0x16'/>
      <address type='pci' domain='0x0000' bus='0x00' slot='0x02' function='0x6'/>
    </controller>
    <controller type='pci' index='8' model='pcie-root-port'>
      <model name='pcie-root-port'/>
      <target chassis='8' port='0x17'/>
      <address type='pci' domain='0x0000' bus='0x00' slot='0x02' function='0x7'/>
    </controller>
    <controller type='pci' index='9' model='pcie-root-port'>
      <model name='pcie-root-port'/>
      <target chassis='9' port='0x18'/>
      <address type='pci' domain='0x0000' bus='0x00' slot='0x03' function='0x0' multifunction='on'/>
    </controller>
    <controller type='pci' index='10' model='pcie-root-port'>
      <model name='pcie-root-port'/>
      <target chassis='10' port='0x19'/>
      <address type='pci' domain='0x0000' bus='0x00' slot='0x03' function='0x1'/>
    </controller>
    <controller type='pci' index='11' model='pcie-root-port'>
      <model name='pcie-root-port'/>
      <target chassis='11' port='0x1a'/>
      <address type='pci' domain='0x0000' bus='0x00' slot='0x03' function='0x2'/>
    </controller>
    <controller type='pci' index='12' model='pcie-root-port'>
      <model name='pcie-root-port'/>
      <target chassis='12' port='0x1b'/>
      <address type='pci' domain='0x0000' bus='0x00' slot='0x03' function='0x3'/>
    </controller>
    <controller type='pci' index='13' model='pcie-root-port'>
      <model name='pcie-root-port'/>
      <target chassis='13' port='0x1c'/>
      <address type='pci' domain='0x0000' bus='0x00' slot='0x03' function='0x4'/>
    </controller>
    <controller type='pci' index='14' model='pcie-root-port'>
      <model name='pcie-root-port'/>
      <target chassis='14' port='0x1d'/>
      <address type='pci' domain='0x0000' bus='0x00' slot='0x03' function='0x5'/>
    </controller>
    <controller type='sata' index='0'>
      <address type='pci' domain='0x0000' bus='0x00' slot='0x1f' function='0x2'/>
    </controller>
    <controller type='virtio-serial' index='0'>
      <address type='pci' domain='0x0000' bus='0x03' slot='0x00' function='0x0'/>
    </controller>
    <interface type='network'>
      <mac address='52:54:00:87:e4:d0'/>
      <source network='default'/>
      <model type='virtio'/>
      <address type='pci' domain='0x0000' bus='0x01' slot='0x00' function='0x0'/>
    </interface>
    <serial type='pty'>
      <target type='isa-serial' port='0'>
        <model name='isa-serial'/>
      </target>
    </serial>
    <console type='pty'>
      <target type='serial' port='0'/>
    </console>
    <channel type='unix'>
      <target type='virtio' name='org.qemu.guest_agent.0'/>
      <address type='virtio-serial' controller='0' bus='0' port='1'/>
    </channel>
    <channel type='spicevmc'>
      <target type='virtio' name='com.redhat.spice.0'/>
      <address type='virtio-serial' controller='0' bus='0' port='2'/>
    </channel>
    <input type='tablet' bus='usb'>
      <address type='usb' bus='0' port='1'/>
    </input>
    <input type='mouse' bus='ps2'/>
    <input type='keyboard' bus='ps2'/>
    <graphics type='spice' autoport='yes'>
      <listen type='address'/>
      <image compression='off'/>
    </graphics>
    <sound model='ich9'>
      <address type='pci' domain='0x0000' bus='0x00' slot='0x1b' function='0x0'/>
    </sound>
    <audio id='1' type='spice'/>
    <video>
      <model type='qxl' ram='65536' vram='65536' vgamem='16384' heads='1' primary='yes'/>
      <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0'/>
    </video>
    <redirdev bus='usb' type='spicevmc'>
      <address type='usb' bus='0' port='2'/>
    </redirdev>
    <redirdev bus='usb' type='spicevmc'>
      <address type='usb' bus='0' port='3'/>
    </redirdev>
    <memballoon model='virtio'>
      <address type='pci' domain='0x0000' bus='0x05' slot='0x00' function='0x0'/>
    </memballoon>
    <rng model='virtio'>
      <backend model='random'>/dev/urandom</backend>
      <address type='pci' domain='0x0000' bus='0x06' slot='0x00' function='0x0'/>
    </rng>
  </devices>
</domain>


Usage

Validate domain

To validate the domain file, execute:

host-platform-root#virt-xml-validate /etc/libvirt/qemu/gentoo.xml
/etc/libvirt/qemu/gentoo.xml validates

List domains (virtual machines)

To list all registered domains (VMs), execute:

host-platform-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:

host-platform-root#virsh list
 Id   Name       State
---------------------------
 4    gentoo     running
 5    gentoo-2   running

Starting a domain

To start a domain, execute:

host-platform-root#virsh start <domain-name>


To enabling autostart, execute:



host-platform-root#virsh autostart <domain-name>


Viewing the console of a domain


There are two different ways to view the console/display of a domain:



  • thru virt-viewer over SPICE/TCP network protocol
    • 

  • thru virt-manager viewport over UNIX socket







Console by virt-manager


See virt-manager for GUI-based viewing of VM's console.



Console by virt-viewer


To use the virt-viewer in starting VM from the shell, execute:



host-platform$virt-viewer --connect=qemu:///session --domain-name gentoo-2 


To just display the window but not start the VM yet, execute:



host-platform$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 domain:

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



host-platform-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



host-platform-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.



host-platform-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 domain from the list of VMs maintained by libvirtd, its usage syntax is:



host-platform-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 a virtual machine from the list of domains, and and delete all images files related to this domain's storage(s), execute:



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

  • Libvirt — a virtualization management toolkit.
    • 

  • Libvirt/QEMU_guest — creation of a guest domain (virtual machine, VM), running inside a QEMU hypervisor, using tools found in libvirt package.
    • 

  • Virt-manager — desktop user interface for management of virtual machines and containers through the libvirt library
    • 

  • QEMU/Linux guest — describes the setup of a Gentoo Linux guest in QEMU using Gentoo bootable media.


External resources



References




    

  1. ↑ Libvirt.org Wiki; Libvirt Virtual Machine Lifecycle, Retrieved on March 22, 2025

    2. 








Retrieved from "https://wiki.gentoo.org/index.php?title=Libvirt/domain&oldid=1358990"