VM Configuration

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, underscores (_), hyphens (-), and colons (:), but cannot contain only digits. 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 (210 bytes), MiB (220 bytes), GiB (230 bytes), or TiB (240 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 hyperthreads included in each processor core, respectively. The attribute value is a positive integer, and a product of the three values is equal to the number of of vCPUs.

    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.

    NOTE:

    The display of user-mode CPU features in VM (e.g. the 'Flags' field of the 'lscpu' command) needs the support of the VM kernel. If you use old kernel in VM, some CPU features may not be displayed.

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

Element

Attribute

Description

Attribute Value and Description

disk

type

Specifies the type of the backend storage medium.

block: block device

file: file device

dir: directory path

device

Specifies the storage medium to be presented to the VM.

disk: disk (default)

floppy: floppy disk

cdrom: CD-ROM

Table 2 Common subelements and attributes of the disk element

Subelement

Subelement Description

Attribute Description

source

Specifies the backend storage medium, which corresponds to the type specified by the type attribute of the disk element.

file: file type. The value is the fully qualified path of the corresponding file.

dev: block type. The value is the fully qualified path of the corresponding host device.

dir: directory type. The value is the fully qualified path of the disk directory.

driver

Details about the specified backend driver

type: disk format type. The value can be raw or qcow2, which must be the same as that of source.

io: disk I/O mode. The options are native and threads.

cache: disk cache mode. The value can be none, writethrough, writeback, or directsync.

iothread: I/O thread allocated to the disk.

target

The bus and device that a disk presents to a VM.

dev: specifies the logical device name of a disk, for example, sd[a-p] for SCSI, SATA, and USB buses and hd[a-d] for IDE disks.

bus: specifies the type of a disk. Common types include scsi, usb, sata, and virtio.

boot

The disk can be used as the boot disk.

order: specifies the disk startup sequence.

readonly

The disk is read-only and cannot be modified by the VM. Generally, it is used together with the CD-ROM drive.

-

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.

In this example, two I/O threads, one block disk device and one CD, are configured for the VM, 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.

<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-20.03-LTS-SP1-aarch64-dvd.iso'/>
	    <target dev='sdb' bus='scsi'/>
	    <readonly/>
	    <boot order='2'/>
	</disk>
         ...
    </devices>
</domain>

Network Device

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

Subelement

Subelement Description

Attribute and Description

mac

The mac address of the vNIC.

address: specifies the mac address. If this parameter is not set, the system automatically generates a mac address.

target

Name of the backend vNIC.

dev: name of the created backend tap device.

source

Specify the backend of the vNIC.

bridge: used together with the bridge mode. The value is the bridge name.

boot

The NIC can be used for remote startup.

order: specifies the startup sequence of NICs.

model

Indicates the type of a vNIC.

type: virtio is usually used for the NIC in bridge mode.

virtualport

Port type

type: If an OVS bridge is used, set this parameter to openvswitch.

driver

Backend driver type

name: driver name. The value is vhost.

queues: the number of NIC queues.

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.

Value of Type

Value of Model

Introduction

pci

pcie-root

PCIe root node, which can be used to mount PCIe devices or controllers.

pcie-root-port

Only one slot can be used to mount a PCIe device or controller.

pcie-to-pci-bridge

PCIe-to-PCI bridge controller, which can be used to mount PCI devices.

usb

ehci

USB 2.0 controller, which can be used to mount USB 2.0 devices.

nec-xhci

USB 3.0 controller, which can be used to mount USB 3.0 devices.

scsi

virtio-scsi

VirtIO SCSI controller, which can be used to mount block devices, such as disks and CD-ROMs.

virtio-serial

virtio-serial

VirtIO serial port controller, which can be used to mount serial port devices, such as a pty serial port.

Table 2 Attributes of the address element in different devices.

Value of Type

Description

Address

pci

The address type is PCI address, indicating the mount location of the device on the PCI bus network.

domain: domain ID of the PCI device.

bus: bus number of the PCI device.

slot: device number of the PCI device.

function: function number of the PCI device.

multifunction: (optional) specifies whether to enable the multifunction function.

usb

The address type is USB address, indicating the location of the device on the USB bus.

bus: bus number of the USB device.

port: port number of the USB device.

drive

The address type is storage device address, indicating the owning disk controller and its position on the bus.

controller: the number of the owning controller.

bus: channel number of the device output.

target: target number of the storage device.

unit: lun number of the storage device.

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

    type attribute: media device type The common attribute value of the AArch 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 tabe 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>

Overview

The XML configuration file contain 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-20.03-LTS-SP1-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>
Rating

search results about are found