VM Configuration

• VM Configuration
  • Introduction
  • VM Description
  • vCPU and Virtual Memory
  • Virtual Device Configuration
    • Storage Devices
    • Network Devices
    • Bus Configuration
    • Other Common Devices
  • Configurations Related to the System Architecture
  • Other Common Configuration Items
  • XML Configuration File Example

Introduction

Overview

Libvirt tool uses XML files to describe a VM feature, including the VM name, CPU, memory, disk, NIC, mouse, and keyboard. You can manage a VM by modifying configuration files. This section describes the elements in the XML configuration file to help users configure VMs.

Format

The VM XML configuration file uses domain as the root element, which contains multiple other elements. Some elements in the XML configuration file can contain corresponding attributes and attribute values to describe VM information in detail. Different attributes of the same element are separated by spaces.

The basic format of the XML configuration file is as follows. In the format, label indicates the label name, attribute indicates the attribute, and value indicates the attribute value. Change them based on the site requirements.

<domain type='kvm'>
    <name>VMName</name>
    <memory attribute='value'>8</memory>
    <vcpu>4</vcpu>
    <os>
       <label attribute='value' attribute='value'>
         ...
       </label>
    </os>
    <label attribute='value' attribute='value'>
      ...
    </label>  
</domain>

Process

1. Create an XML configuration file with domain root element.

2. Use the name tag to specify a unique VM name based on the naming rule.

3. Configure system resources such as the virtual CPU (vCPU) and virtual memory.

4. Configure virtual devices.

   1. Configure storage devices.
   2. Configure network devices.
   3. Configure the external bus structure.
   4. Configure external devices such as the mouse.

5. Save the XML configuration file.

VM Description

Overview

This section describes how to configure the VM domain root element and VM name.

Elements

• domain: Root element of a VM XML configuration file, which is used to configure the type of the hypervisor that runs the VM.

  type: Type of a domain in virtualization. In the openEuler virtualization, the attribute value is kvm.

• name: VM name.

  The VM name is a unique character string on the same host. The VM name can contain only digits, letters, and special characters _－:!@#$%^.. The VM name can contain a maximum of 64 characters.

Configuration Example

For example, if the VM name is openEuler, the configuration is as follows:

<domain type='kvm'>
    <name>openEuler</name>
    ...
</domain>

vCPU and Virtual Memory

Overview

This section describes how to configure the vCPU and virtual memory.

Elements

• vcpu: The number of virtual processors.

• memory: The size of the virtual memory.

  unit: The memory unit. The value can be KiB (2¹⁰ bytes), MiB (2²⁰ bytes), GiB (2³⁰ bytes), or TiB (2⁴⁰ bytes).

• cpu: The mode of the virtual processor.

  mode: The mode of the vCPU.

  • host-passthrough: indicates that the architecture and features of the virtual CPU are the same as those of the host.

  • custom: indicates that the architecture and features of the virtual CPU are configured by the cpu element.

  Sub-element topology: A sub-element of the element cpu, used to describe the topology structure of a vCPU mode.

  • The attributes socket, cores, and threads of the sub-element topology describe the number of CPU sockets of a VM, the number of processor cores included in each CPU socket, and the number of threads included in each processor core, respectively. The attribute value is a positive integer, and the product of the three values equals the number of vCPUs.
  • The ARM architecture supports the virtual hyper-threading function. The virtual CPU hot add and the virtual hyper-threading function are mutually exclusive. Sub-element model: A sub-element of the element cpu, used to describe the CPU model when mode is custom.

  Sub-element feature: A sub-element of the element cpu, used to enable/disable a CPU feature when mode is custom. The attribute name describes the name of the CPU feature. And whether enable the CPU feature is controlled by the attribute policy:

  • force: force enable the CPU feature regardless of it being supported by host CPU.

  • require: enable the CPU feature.

  • optional: the CPU feature will be enabled if and only if it is supported by host CPU.

  • disable: disable the CPU feature.

  • forbid: disable the CPU feature and guest creation will fail if the feature is supported by host CPU.

Configuration Example

For example, if the number of vCPUs is 4, the processing mode is host-passthrough, the virtual memory is 8 GiB, the four CPUs are distributed in two CPU sockets, and hyperthreading is not supported, the configuration is as follows:

<domain type='kvm'>
    ...
    <vcpu>4</vcpu>
    <memory unit='GiB'>8</memory>
    <cpu mode='host-passthrough'>
        <topology sockets='2' cores='2' threads='1'/>
    </cpu>
...
</domain>

If the virtual memory is 8 GiB, the number of vCPUs is 4, the processing mode is custom, the CPU model is Kunpeng-920, and pmull is disabled, the configuration is as follows:

<domain type='kvm'>
    ...
    <vcpu>4</vcpu>
    <memory unit='GiB'>8</memory>
    <cpu mode='custom'>
        <model>Kunpeng-920</model>
        <feature policy='disable' name='pmull'/>
    </cpu>
    ...
</domain>

Virtual Device Configuration

The VM XML configuration file uses the devices elements to configure virtual devices, including storage devices, network devices, buses, and mouse devices. This section describes how to configure common virtual devices.

Storage Devices

Overview

This section describes how to configure virtual storage devices, including floppy disks, disks, and CD-ROMs and their storage types.

Elements

The XML configuration file uses the disk element to configure storage devices. Table 1 describes common disk attributes. Table 2 describes common subelements and their attributes.

Table 1 Common attributes of the disk element

Table 2 Common subelements and attributes of the disk element

Configuration Example

After the VM image is prepared according to Preparing a VM Image, you can use the following XML configuration file to configure the virtual disk for the VM.

For example, this example configures two I/O threads for the virtual machine, one for a block disk device, one for an optical disc device, and one for an RBD disk, and the first I/O thread is allocated to the block disk device for use. The backend medium of the disk device is in qcow2 format and is used as the preferred boot disk. Before using an RBD disk, ensure that the qemu-block-rbd driver is installed. Run the following command as the root user to install the driver:

yum install qemu-block-rbd

Configuration example:

<domain type='kvm'>
    ...
    <iothreads>2</iothreads>
    <devices>
        <disk type='file' device='disk'>
     <driver name='qemu' type='qcow2' cache='none' io='native' iothread="1"/>
     <source file='/mnt/openEuler-image.qcow2'/>
     <target dev='vda' bus='virtio'/>
     <boot order='1'/>
 </disk>
 <disk type='file' device='cdrom'>
     <driver name='qemu' type='raw' cache='none' io='native'/>
     <source file='/mnt/openEuler-22.03-LTS-aarch64-dvd.iso'/>
     <target dev='sdb' bus='scsi'/>
     <readonly/>
     <boot order='2'/>
 </disk>
        <disk type='network' device='disk'>
            <driver name='qemu' type='raw' cache='none' />
            <source protocol="rbd" name="rbd/vol2"/>
            <host name="192.168.0.2" port="6789" />
            <target dev='sdc' bus='scsi'/>
            <boot order='3'/>
    </disk>
         ...
    </devices>
</domain>

Network Devices

Overview

The XML configuration file can be used to configure virtual network devices, including the ethernet mode, bridge mode, and vhostuser mode. This section describes how to configure vNICs.

Elements

In the XML configuration file, the element interface is used, and its attribute type indicates the mode of the vNIC. The options are ethernet, bridge, and vhostuser. The following uses the vNIC in bridge mode as an example to describe its subelements and attributes.

Table 1 Common subelements of a vNIC in bridge mode

Configuration Example

• After creating the Linux bridge br0 by referring to Preparing the VM Network, configure a vNIC of the VirtIO type bridged on the br0 bridge. The corresponding XML configuration is as follows:

  <domain type='kvm'>
      ...
      <devices>
          <interface type='bridge'>
       <source bridge='br0'/>
              <model type='virtio'/>
   </interface>
          ...
      </devices>
  </domain>
  

• If an OVS network bridge is created according to Preparing the VM Network, configure a VirtIO vNIC device that uses the vhost driver and has four queues.

  <domain type='kvm'>
      ...
      <devices>
          <interface type='bridge'>
       <source bridge='br0'/>
              <virtualport type='openvswitch'/> 
              <model type='virtio'/>
              <driver name='vhost' queues='4'/> 
   </interface>
          ...
      </devices>
  </domain>
  

Bus Configuration

Overview

The bus is a channel for information communication between components of a computer. An external device needs to be mounted to a corresponding bus, and each device is assigned a unique address (specified by the subelement address). Information exchange with another device or a central processing unit (CPU) is completed through the bus network. Common device buses include the ISA bus, PCI bus, USB bus, SCSI bus, and PCIe bus.

The PCIe bus is a typical tree structure and has good scalability. The buses are associated with each other by using a controller. The following uses the PCIe bus as an example to describe how to configure a bus topology for a VM.

NOTE:
The bus configuration is complex. If the device topology does not need to be precisely controlled, the default bus configuration automatically generated by libvirt can be used.

Elements

In the XML configuration of libvirt, each controller element (controller) represents a bus, and one or more controllers or devices can be mounted to one controller depending on the VM architecture. This topic describes common attributes and subelements.

controller: controller element, which indicates a bus.

• Attribute type: bus type, which is mandatory for the controller. The common values are pci, usb, scsi, virtio-serial, fdc, and ccid.

• Attribute index: bus number of the controller (the number starts from 0), which is mandatory for the controller. This attribute can be used in the address element.

• Attribute model: specific model of the controller, which is mandatory for the controller. The available values are related to the value of type. For details about the mapping and description, see Table 1.

• Subelement address: mount location of a device or controller on the bus network.

  • Attribute type: device address type. The common values are pci, usb, or drive. The attribute varies according to the type of the address. For details about the common type attribute value and the corresponding address attribute, see Table 2.

• Subelement model: name of a controller model.

  • Attribute name: name of a controller model, which corresponds to the model attribute in the parent element controller.

Table 1 Mapping between the common values of type and model for the controller.

Table 2 Attributes of the address element in different devices.

Configuration Example

This example shows the topology of a PCIe bus. Three PCIe-Root-Port controllers are mounted to the PCIe root node (BUS 0). The multifunction function is enabled for the first PCIe-Root-Port controller (BUS 1). A PCIe-to-PCI-bridge controller is mounted to the first PCIe-Root-Port controller to form a PCI bus (BUS 3). A virtio-serial device and a USB 2.0 controller are mounted to the PCI bus. A SCSI controller is mounted to the second PCIe-Root-Port controller (BUS 2). No device is mounted to the third PCIe-Root-Port controller (BUS 0). The configuration details are as follows:

<domain type='kvm'>
    ...
    <devices>
        <controller type='pci' index='0' model='pcie-root'/>
 <controller type='pci' index='1' model='pcie-root-port'>
     <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0' multifunction='on'/>
 </controller>
 <controller type='pci' index='2' model='pcie-root-port'>
     <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x1'/>
 </controller>
 <controller type='pci' index='3' model='pcie-to-pci-bridge'>
     <model name='pcie-pci-bridge'/>
     <address type='pci' domain='0x0000' bus='0x01' slot='0x00' function='0x0'/>
 </controller>
 <controller type='pci' index='4' model='pcie-root-port'>
     <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x2'/>
 </controller>
 <controller type='scsi' index='0' model='virtio-scsi'>
     <address type='pci' domain='0x0000' bus='0x02' slot='0x00' function='0x0'/>
 </controller>
 <controller type='virtio-serial' index='0'>
     <address type='pci' domain='0x0000' bus='0x03' slot='0x02' function='0x0'/>
 </controller>
 <controller type='usb' index='0' model='ehci'>
     <address type='pci' domain='0x0000' bus='0x03' slot='0x01' function='0x0'/>
 </controller>
 ...
 </devices>
</domain>

Other Common Devices

Overview

In addition to storage devices and network devices, some external devices need to be specified in the XML configuration file. This section describes how to configure these elements.

Elements

• serial: serial port device

  Attribute type: specifies the serial port type. The common attribute values are pty, tcp, pipe, and file.

• video: media device

  Attribute type: media device type. The common attribute value of the AArch64 architecture is virtio, and that of the x86_64 architecture is vga or cirrus.

  Subelement model: subelement of video, which is used to specify the media device type.

  In the subelement model, if type is set to vga, a Video Graphics Array (VGA) video card is configured. vram indicates the size of the video RAM, in KB by default.

  For example, if a 16 MB VGA video card is configured for an x86_64 VM, configuration in the XML file is as follows. In the example, the value of vram is the size of video RAM, in KB by default.

  <video>
      <model type='vga' vram='16384' heads='1' primary='yes'/>
  </video>
  

• input: output device

  type attribute: specifies the type of the output device. The common attribute values are tablet and keyboard, indicating that the output device is the tablet and keyboard respectively.

  bus: specifies the bus to be mounted. The common attribute value is USB.

• emulator: emulator application path

• graphics: graphics device

  type attribute: specifies the type of a graphics device. The common attribute value is vnc.

  listen attribute: specifies the IP address to be listened to.

Configuration Example

For example, in the following example, the VM emulator path, pty serial port, VirtIO media device, USB tablet, USB keyboard, and VNC graphics device are configured.

NOTE:
When type of graphics is set to VNC, you are advised to set the passwd attribute, that is, the password for logging in to the VM using VNC.

<domain type='kvm'>
    ...
    <devices>
        <emulator>/usr/libexec/qemu-kvm</emulator>
        <console type='pty'/>
        <video>
            <model type='virtio'/>
        </video>
        <input type='tablet' bus='usb'/>
        <input type='keyboard' bus='usb'/>
        <graphics type='vnc' listen='0.0.0.0' passwd='n8VfjbFK'/>
 ...
 </devices>
</domain>

Configurations Related to the System Architecture

Overview

The XML configuration file contains configurations related to the system architecture, which cover the mainboard, CPU, and some features related to the architecture. This section describes meanings of these configurations.

Elements

• os: defines VM startup parameters.

  Subelement type: specifies the VM type. The attribute arch indicates the architecture type, for example, AArch64. The attribute machine indicates the type of VM chipset. Supported chipset type can be queried by running the qemu-kvm -machine ? command. For example, the AArch64 architecture supports the virt type.

  Subelement loader: specifies the firmware to be loaded, for example, the UEFI file provided by the EDK. The readonly attribute indicates whether the file is read-only. The value can be yes or no. The type attribute indicates the loader type. The common values are rom and pflash.

  Subelement nvram: specifies the path of the nvram file, which is used to store the UEFI startup configuration.

• features: Hypervisor controls some VM CPU/machine features, such as the advanced configuration and power interface (ACPI) and the GICv3 interrupt controller specified by the ARM processor.

Example for AArch64 Architecture

The VM is of the aarch64 type and uses virt chipset. The VM configuration started using UEFI is as follows:

<domain type='kvm'>
    ...
    <os>
        <type arch='aarch64' machine='virt'>hvm</type>
        <loader readonly='yes' type='pflash'>/usr/share/edk2/aarch64/QEMU_EFI-pflash.raw</loader>
        <nvram>/var/lib/libvirt/qemu/nvram/openEulerVM.fd</nvram>
    </os>
    ...
</domain>

Configure ACPI and GIC V3 interrupt controller features for the VM.

<features>
    <acpi/>
    <gic version='3'/>
</features>

Example for x86_64 Architecture

The x86_64 architecture supports both BIOS and UEFI boot modes. If loader is not configured, the default BIOS boot mode is used. The following is a configuration example in which the UEFI boot mode and Q35 chipsets are used.

<domain type='kvm'>
    ...
    <os>
        <type arch='x86_64' machine='q35'>hvm</type>
        <loader type='rom'>/usr/share/edk2/ovmf/OVMF.fd</loader>
    </os>
    ...
</domain>

Other Common Configuration Items

Overview

In addition to system resources and virtual devices, other elements need to be configured in the XML configuration file. This section describes how to configure these elements.

Elements

• iothreads: specifies the number of iothread, which can be used to accelerate storage device performance.

• on_poweroff: action taken when a VM is powered off.

• on_reboot: action taken when a VM is rebooted.

• on_crash: action taken when a VM is on crash.

• clock: indicates the clock type.

  offset attribute: specifies the VM clock synchronization type. The value can be localtime, utc, timezone, or variable.

Configuration Example

Configure two iothread for the VM to accelerate storage device performance.

<iothreads>2</iothreads>

Destroy the VM when it is powered off.

<on_poweroff>destroy</on_poweroff>

Restart the VM.

<on_reboot>restart</on_reboot>

Restart the VM when it is crashed.

<on_crash>restart</on_crash>

The clock uses the utc synchronization mode.

<clock offset='utc'/>

XML Configuration File Example

Overview

This section provides XML configuration files of a basic AArch64 VM and a x86_64 VM as two examples for reference.

Example 1

An XML configuration file of AArch64 VM, which contains basic elements. The following is a configuration example:

<domain type='kvm'>
    <name>openEulerVM</name>
    <memory unit='GiB'>8</memory>
    <vcpu>4</vcpu>
    <os>
 <type arch='aarch64' machine='virt'>hvm</type>
 <loader readonly='yes' type='pflash'>/usr/share/edk2/aarch64/QEMU_EFI-pflash.raw</loader>
 <nvram>/var/lib/libvirt/qemu/nvram/openEulerVM.fd</nvram>
    </os>
    <features>
 <acpi/>
 <gic version='3'/>
    </features>
    <cpu mode='host-passthrough'>
        <topology sockets='2' cores='2' threads='1'/>
    </cpu>
    <iothreads>1</iothreads>
    <clock offset='utc'/>
    <on_poweroff>destroy</on_poweroff>
    <on_reboot>restart</on_reboot>
    <on_crash>restart</on_crash>
    <devices>
 <emulator>/usr/libexec/qemu-kvm</emulator>
 <disk type='file' device='disk'>
     <driver name='qemu' type='qcow2' iothread="1"/>
     <source file='/mnt/openEuler-image.qcow2'/>
     <target dev='vda' bus='virtio'/>
     <boot order='1'/>
 </disk>
 <disk type='file' device='cdrom'>
     <driver name='qemu' type='raw'/>
     <source file='/mnt/openEuler-22.03-LTS-aarch64-dvd.iso'/>
     <readonly/>
     <target dev='sdb' bus='scsi'/>
     <boot order='2'/>
 </disk>
 <interface type='bridge'>
     <source bridge='br0'/>
     <model type='virtio'/>
 </interface>
 <console type='pty'/>
        <video>
           <model type='virtio'/>
        </video>
        <controller type='scsi' index='0' model='virtio-scsi'/>
 <controller type='usb' model='ehci'/>
 <input type='tablet' bus='usb'/>
 <input type='keyboard' bus='usb'/>
 <graphics type='vnc' listen='0.0.0.0' passwd='n8VfjbFK'/>
    </devices>
    <seclabel type='dynamic' model='dac' relabel='yes'/>
</domain>

Example 2

An XML configuration file of x86_64 VM, which contains basic elements and bus elements. The following is a configuration example:

<domain type='kvm'>
  <name>openEulerVM</name>
  <memory unit='KiB'>8388608</memory>
  <currentMemory unit='KiB'>8388608</currentMemory>
  <vcpu placement='static'>4</vcpu>
  <iothreads>1</iothreads>
  <os>
    <type arch='x86_64' machine='pc-i440fx-4.0'>hvm</type>
  </os>
  <features>
    <acpi/>
  </features>
  <cpu mode='host-passthrough' check='none'>
    <topology sockets='2' cores='2' threads='1'/>
  </cpu>
  <clock offset='utc'/>
  <on_poweroff>destroy</on_poweroff>
  <on_reboot>restart</on_reboot>
  <on_crash>restart</on_crash>
  <devices>
    <emulator>/usr/libexec/qemu-kvm</emulator>
    <disk type='file' device='disk'>
      <driver name='qemu' type='qcow2' iothread='1'/>
      <source file='/mnt/openEuler-image.qcow2'/>
      <target dev='vda' bus='virtio'/>
      <boot order='1'/>
      <address type='pci' domain='0x0000' bus='0x00' slot='0x08' function='0x0'/>
    </disk>
    <controller type='scsi' index='0' model='virtio-scsi'>
    </controller>
    <controller type='virtio-serial' index='0'>
    </controller>
    <controller type='usb' index='0' model='ehci'>
    </controller>
    <controller type='sata' index='0'>
    </controller>
    <controller type='pci' index='0' model='pci-root'/>
    <interface type='bridge'>
      <mac address='52:54:00:c1:c4:23'/>
      <source bridge='virbr0'/>
      <model type='virtio'/>
    </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>
    <input type='tablet' bus='usb'>
      <address type='usb' bus='0' port='1'/>
    </input>
    <input type='keyboard' bus='usb'>
      <address type='usb' bus='0' port='2'/>
    </input>
    <input type='mouse' bus='ps2'/>
    <input type='keyboard' bus='ps2'/>
    <graphics type='vnc' port='-1' autoport='yes' listen='0.0.0.0'>
      <listen type='address' address='0.0.0.0'/>
    </graphics>
    <video>
      <model type='vga' vram='16384' heads='1' primary='yes'/>
      <address type='pci' domain='0x0000' bus='0x00' slot='0x02' function='0x0'/>
    </video>
    <memballoon model='virtio'>
    </memballoon>
  </devices>
</domain>