virt-manager: VM creation, hardware panels, and remote control

Commands and XML use generic examples and must be adjusted for the host version and available resources. Network addresses use documentation ranges; choose a nonconflicting private network for an actual deployment. See the relevant sections for the conditions that apply to image modification and device passthrough.

virt-manager (Virtual Machine Manager) is the most mature graphical management tool in the libvirt ecosystem. It is written in Python and built on GTK; check the dependencies of your installed version. It provides a complete GUI for creating, configuring, monitoring, and managing KVM/QEMU virtual machines, and also supports remote management of hypervisors such as Xen and LXC.

How virt-manager relates to libvirt virt-manager is a client that communicates with the libvirtd daemon through the libvirt API. Whether the hypervisor is local or remote, the underlying call chain is libvirt → libvirtd → QEMU/KVM. Understanding this helps when troubleshooting connection failures.

1. A tour of the virt-manager interface#

1.1 Main window layout

After virt-manager starts, the main window has three core areas:

Menu bar functions:

• File: create a VM (Ctrl+N), add a connection, close a connection, or quit
• Edit: Preferences (console scaling mode and statistics polling interval), and Connection Details (host details window)
• View: console scaling (Always/VNC console only/Never) and performance graph type (CPU usage / Memory usage / Disk I/O / Network I/O)

1.2 The Connection Details window

Double-click a connection name or use the Edit menu to open Connection Details, the central panel for managing host resources:

1.3 Overall architecture

graph TD
    subgraph "用户层"
        A[virt-manager GUI]
        B[virsh CLI]
        C[virt-viewer]
    end

    subgraph "API 层"
        D[libvirt API - libvirt.so]
    end

    subgraph "守护进程层"
        E[libvirtd]
        F[virtlogd]
        G[virtlockd]
    end

    subgraph "虚拟化层"
        H[QEMU/KVM]
        I[QEMU Emulator]
    end

    subgraph "内核层"
        J[kvm.ko]
        K[vhost-net / vhost-scsi]
    end

    subgraph "虚拟机"
        L[Guest VM]
    end

    A --> D
    B --> D
    C --> D
    D --> E
    E --> F
    E --> G
    E --> H
    H --> I
    H --> J
    H --> K
    J --> L
    K --> L

Key concept virt-manager does not communicate with QEMU directly. Every operation follows virt-manager → libvirt API → libvirtd → QEMU/KVM, which is why sudo systemctl status libvirtd is the first troubleshooting step.

2. The virtual machine creation wizard#

Open the wizard through File → New Virtual Machine, or the + toolbar button.

2.1 Step 1: choose the installation source

Architecture options:

• x86_64: standard PC architecture, including the q35 and i440fx machine types
• aarch64: 64-bit ARM architecture, such as Raspberry Pi and Kunpeng servers
• Other architectures depend on the qemu-system-* packages installed on the system

2.2 Step 2: detect the OS and choose a variant

virt-manager automatically reads ISO metadata to detect the operating system. If detection succeeds, it fills in the OS variant automatically.

Advantages of choosing manually:

• virt-manager automatically optimizes the default configuration for the OS variant, such as choosing virtio or IDE for the disk bus and selecting a NIC model
• Different variants have different defaults:
  • ubuntu24.04 → defaults to a virtio disk + virtio NIC + QXL graphics
  • win11 → defaults to the Q35 chipset + UEFI + TPM 2.0 + Secure Boot
  • generic → conservative defaults (IDE disk + rtl8139 NIC), with the worst performance

Choose the correct OS variant Selecting Generic or leaving the variant unspecified makes virt-manager use its most conservative default hardware configuration, whose latency still needs measuring. When installing a Linux distribution, select at least the corresponding Linux-family variant.

The search box supports fuzzy matching: ubuntu, win11, rhel9, and debian12.

2.3 Step 3: CPU and memory

vCPU allocation

• The default is 1; the recommended range is 1/2 of the host's physical core count up to that full count
• Topology override (Topology): manually set sockets / cores / threads per socket
  • Total vCPUs = sockets x cores x threads
  • Correct topology is especially important for software licensed per socket, such as some databases

Memory allocation

• Drag the slider or enter a value directly, in MiB or GiB
• Current allocation: memory allocated immediately when the VM starts
• Max allocation: the hotplug limit, requiring guest support for memory hotplug

Suggested configurations by OS

2.4 Step 4: storage configuration

Create a new disk

• Size: enter the required disk capacity in GiB
• Format: qcow2 (QEMU Copy-On-Write v2) is strongly recommended
• Allocation policy:
  • Thin provisioned (the qcow2 default): space grows on demand instead of consuming the full capacity immediately
  • Thick provisioned: allocates all space immediately, suited to I/O-latency-sensitive workloads

Select an existing disk

Browse existing volumes in a storage pool. Formats such as .qcow2, .raw, and .img can be imported directly.

Disk format comparison

Cache mode

The dangers of unsafe mode unsafe mode ignores every disk-flush request from the guest. This can greatly accelerate installation or initialization, but an unexpected host power loss in production will cause irrecoverable data corruption. Use it only for temporary tests or disposable VMs in CI pipelines.

2.5 Step 5: final review

Network selection

Choosing NAT vs. Bridge NAT is sufficient for development and testing. Choose Bridge mode when other machines on the LAN need to access the VM, for example when hosting a web server.

Customize the configuration

Selecting Customize configuration before install opens the full hardware configuration panel before the first boot. This is essential when you need to:

• Change the UEFI/BIOS firmware type
• Add a TPM (required by Windows 11)
• Switch the disk bus to virtio for better performance
• Add extra NICs or disks

Virtualization type

• kvm: hardware-accelerated virtualization using the CPU's VT-x/AMD-V extensions, with near-bare-metal performance
• qemu: pure software emulation (TCG), extremely slow; use only without hardware virtualization support or for cross-architecture emulation

Use the following commands to confirm that KVM is available:

# 检查 KVM 模块是否加载
lsmod | grep kvm
# 输出示例：
# kvm_amd              155648  0
# kvm                  1089536  1 kvm_amd

# 检查 /dev/kvm 设备权限
ls -la /dev/kvm
# crw-rw---- 1 root kvm 10, 232 ...

# 将当前用户加入 kvm 组
sudo usermod -aG kvm $USER

Firmware type

3. Virtual machine consoles and interaction#

The SPICE agent, guest-agent, and virtio drivers have different responsibilities. Install Windows SPICE guest tools from their corresponding official package; do not assume a fixed path on the virtio-win ISO. Whether a snapshot includes memory depends on the options and VM state. Check current support for UEFI, TPM, VFIO, and external disks; a recovery point listed in the GUI is not a complete backup.

3.1 The SPICE console

SPICE (Simple Protocol for Independent Computing Environments) is the recommended display protocol for QEMU/KVM, offering a significantly better experience than traditional VNC.

SPICE vs. VNC

Console toolbar

After you open a VM console, the top toolbar provides the following functions:

Guest integration (spice-vdagent)

Install the guest-side agent for the full experience:

# Linux guest
sudo apt install spice-vdagent        # Debian/Ubuntu
sudo dnf install spice-vdagent         # Fedora/RHEL
sudo pacman -S spice-vdagent           # Arch

# 验证代理是否运行
systemctl status spice-vdagentd

# Windows guest: 安装 spice-guest-tools（virtio-win ISO 中包含）
# 下载地址: https://www.spice-space.org/download.html
# 或从 virtio-win ISO 安装: E:\guest-agent\spice-guest-tools.exe

Features available after installation:

• Automatic window resizing, with guest resolution following the virt-manager window size
• Bidirectional clipboard sharing for text and images
• Drag-and-drop file transfer between host ↔ guest
• Seamless pointer movement, without pressing Ctrl+Alt to release it

virt-viewer: a lightweight SPICE/VNC client

# 安装
sudo apt install virt-viewer

# 连接到本地 VM（VM 名称来自 virsh list --all）
virt-viewer --connect qemu:///system <vm-name>

# 连接到远程 VM
virt-viewer --connect qemu+ssh://user@host/system <vm-name>

# 直接连接到 SPICE/VNC 端口
remote-viewer spice://localhost:5900

virt-viewer is lighter than virt-manager and suits situations where you only need a console, without management features.

3.2 Snapshot management

A snapshot is not a backup A snapshot records a VM's state at a point in time, including disk and memory. It enables quick rollback but cannot replace a backup. The snapshot chain depends on the original disk image: if the underlying qcow2 file is corrupted, all snapshots become unusable. A real backup requires an independent copy of the disk-image file.

Internal vs. external snapshots

virt-manager uses internal snapshots by default.

Procedure

1. While the VM is running, use VM → Manage Snapshots or the Snapshots toolbar button
2. Click + and enter a name and description; including the date and a description of the state is recommended
3. The created snapshot appears in the list with its name, creation time, and VM state (running/shutoff)
4. Restore: select the target snapshot → click ▶ Run. A running-state snapshot restores to a running VM; a shutoff-state snapshot restores to a shutoff VM
5. Delete: select a snapshot → click 🗑. Deleted snapshots cannot be recovered

Equivalent virsh CLI commands

# 创建快照
virsh snapshot-create-as <vm-name> <snapshot-name> \
    --description "Before upgrading kernel"

# 列出快照
virsh snapshot-list <vm-name>

# 查看快照详情
virsh snapshot-info <vm-name> --snapshotname <snapshot-name>

# 恢复到快照
virsh snapshot-revert <vm-name> --snapshotname <snapshot-name>

# 删除快照
virsh snapshot-delete <vm-name> --snapshotname <snapshot-name>

3.3 VM cloning

Cloning creates a complete, independent copy of an existing VM.

Procedure

1. Make sure the source VM is shut down; virt-manager requires this for cloning
2. Right-click the VM → Clone...
3. Enter the new VM name and select a storage path
4. Cloning automatically generates:
   • A new UUID
   • A new MAC address to avoid network conflicts
   • A new disk image: an independent copy that does not affect the source VM

Equivalent virsh CLI commands

# 使用 virt-clone 克隆 VM
virt-clone \
    --original <source-vm-name> \
    --name <new-vm-name> \
    --file /var/lib/libvirt/images/<new-vm-name>.qcow2 \
    --auto-clone

Typical use cases

• Template VMs: create a cleanly installed VM as a template and clone it whenever you need a new environment
• Safe testing: test potentially destructive operations, such as kernel upgrades or configuration changes, on the clone without affecting the original VM if they fail
• Batch deployment: combine cloning with cloud-init to produce multiple identical base VMs

Preparation for cloning First clone a powered-off template, then use virt-sysprep on the offline copy to clean identity information such as SSH host keys, machine-id, and networking. Do not clean the source VM directly if it is in use or must be preserved. For Windows, TPM/NVRAM, and encrypted state, use a template workflow supported by the guest.

4. The hardware configuration panel in detail#

Panel settings are configuration choices, not performance guarantees. CPU topology must match the vCPU count. host-model does not guarantee live-migration compatibility across heterogeneous hosts; even with identical CPU models, host-passthrough requires checks of microcode, machine type, QEMU, and devices. Memory current/max settings differ from the hotplug maxMemory/slots settings, and hotplug also requires guest support. raw images can be sparse files; legacy qcow2 AES is not a modern encryption scheme. Multiqueue virtio-net requires compatible guest drivers and settings such as ethtool configuration.

With the VM shut down, open the hardware configuration panel through View → Details, or the i toolbar icon. This is virt-manager's most powerful area.

4.1 CPU configuration

Choosing a CPU model

# 查看宿主机 CPU 支持的模型列表
virsh domcapabilities | xmllint --xpath '//cpu/mode[@name="custom"]/model' - | head -20

CPU topology

# virsh 设置 CPU 拓扑示例（1 socket x 4 cores x 2 threads = 8 vCPU）
virsh edit <vm-name>

<cpu mode="host-passthrough">
  <topology sockets="1" dies="1" cores="4" threads="2"/>
</cpu>

CPU pinning (vCPU affinity)

Bind vCPU threads to specific physical CPU cores on the host to reduce cache invalidation and context switches:

<cputune>
  <vcpupin vcpu="0" cpuset="2"/>
  <vcpupin vcpu="1" cpuset="3"/>
  <vcpupin vcpu="2" cpuset="4"/>
  <vcpupin vcpu="3" cpuset="5"/>
</cputune>

CPU pinning recommendations On a NUMA server, pin a VM's vCPUs to cores on the same NUMA node to avoid the latency penalty of cross-NUMA memory access. Combine this with numatune for further performance improvements.

4.2 Memory configuration

Allocation policy

• Current allocation: memory actually allocated when the VM starts
• Max allocation: the maximum memory size reachable through memory hotplug
• Select "Set max allocation and use hugepages" to use huge pages; the host must be configured in advance

Hugepages configuration

Huge pages improve the performance of memory-intensive VMs by reducing TLB (Translation Lookaside Buffer) misses:

# 宿主机配置 hugepages（例如分配 2048 个 2MB 页面 = 4GB）
echo 2048 | sudo tee /proc/sys/vm/nr_hugepages

# 或在 sysctl 中永久配置
echo "vm.nr_hugepages = 2048" | sudo tee -a /etc/sysctl.conf

# 验证配置
grep Huge /proc/meminfo
# HugePages_Total:    2048
# Hugepagesize:       2048 kB

# 在 libvirt 中使用 hugepages
virsh edit <vm-name>

<memoryBacking>
  <hugepages/>
</memoryBacking>

4.3 Disk configuration

Disk bus comparison

Cache modes in detail

graph LR
    subgraph "Guest VM"
        A[应用程序]
        B[Guest Page Cache]
        C[Guest 磁盘驱动]
    end

    subgraph "QEMU"
        D[QEMU 块层]
        E[Cache Mode Decision]
    end

    subgraph "Host"
        F[Host Page Cache]
        G[O_DIRECT bypass]
        H[物理磁盘]
    end

    A --> B --> C --> D --> E
    E -->|writeback / writethrough| F --> H
    E -->|none / directsync| G --> H

IO Mode

Discard mode (TRIM/Discard support)

• unmap: passes guest TRIM/Discard commands through to the host filesystem to release unused blocks; for qcow2 files, this can reduce actual disk usage

# 在 guest 中手动执行 TRIM（需要 guest 和宿主机都支持 discard）
sudo fstrim -a

4.4 Network configuration

NIC model comparison

Network source types

graph TD
    A[VM 虚拟网卡]
    B[NAT - virbr0]
    C[Bridge - br0]
    D[Macvtap - VEPA/Bridge]
    E[SR-IOV VF]
    F[Host Only]

    B --> G[宿主机 iptables/nftables NAT]
    G --> H[物理网络]
    C --> H
    D --> H
    E --> H
    F --> I[仅宿主机内部]

Bridge network configuration

# 创建 Linux bridge（使用 NetworkManager）
nmcli connection add type bridge ifname br0
nmcli connection add type ethernet slave-type bridge con-name bridge-br0 \
    ifname eth0 master br0
nmcli connection up br0

# 或使用 systemd-networkd

# /etc/systemd/network/br0.netdev
[NetDev]
Name=br0
Kind=bridge

# /etc/systemd/network/br0.network
[Match]
Name=br0
[Network]
DHCP=yes

Multiqueue virtio-net

Multiqueue suits network workloads that can be processed in parallel. Benefits depend on the guest CPUs, queue settings, and backend, and must be measured:

<interface type="network">
  <model type="virtio"/>
  <driver name="vhost" queues="4"/>
</interface>

Queue-count recommendation Set queues to the VM's vCPU count so each vCPU can handle a separate network queue. Requires a guest kernel version >= 3.8 with MQ veth support.

4.5 Graphics configuration

Enable 3D acceleration

<graphics type="spice">
  <listen type="none"/>
  <gl enable="yes" rendernode="/dev/dri/<RENDER_NODE>"/>
</graphics>
<video>
  <model type="virtio" heads="1" primary="yes">
    <acceleration accel3d="yes"/>
  </model>
</video>

Host requirements:

• Mesa drivers + OpenGL support (glxinfo | grep "OpenGL renderer")
• /dev/dri/renderD128 exists and the user has permission to access it

4.6 Other devices

USB controllers

TPM (Trusted Platform Module)

Installing Windows 11 requires TPM 2.0 configuration:

<tpm model="tpm-crb">
  <backend type="emulator" version="2.0"/>
</tpm>

Install swtpm on the host:

sudo apt install swtpm swtpm-tools    # Debian/Ubuntu
sudo dnf install swtpm                 # Fedora

RNG (random number generator)

Provide the guest with a high-quality entropy source to accelerate cryptographic operations and SSH host-key generation:

<rng model="virtio">
  <backend model="random">/dev/urandom</backend>
</rng>

Watchdog

Automatically take action when the guest stops responding:

<watchdog model="i6300esb" action="reset"/>

Virtiofs (filesystem passthrough)

The domain also needs shared memory accessible to vhost-user, for example <memoryBacking><source type="memfd"/><access mode="shared"/></memoryBacking>. Restrict the shared directory's scope and check UID/GID mappings, permissions, and SELinux/AppArmor; do not share the entire home directory. Before mounting inside the guest, run mkdir -p /mnt/share.

virt-manager's GUI support for virtiofs is limited, so it is usually configured through virsh or by editing the XML directly:

<filesystem type="mount" accessmode="passthrough">
  <driver type="virtiofs"/>
  <source dir="/path/to/host/dir"/>
  <target dir="mount_tag"/>
</filesystem>

# guest 中挂载
sudo mount -t virtiofs mount_tag /mnt/share

Advantages of virtiofs viriofs offers significant performance advantages over 9p/virtio-9p and Samba/NFS because it is based on FUSE and passes file operations directly through shared memory, avoiding protocol-conversion overhead. The Linux guest virtiofs driver has been available since 5.4. The host requires matching QEMU, virtiofsd, and libvirt support; checking only the host kernel version is insufficient.

5. Managing remote connections#

Do not expose unauthenticated libvirt TCP, VNC, or SPICE listeners. Prefer restricting direct display connections to localhost or an SSH tunnel. SPICE OpenGL/virgl usually requires a local Unix socket; do not combine GL configuration fragments with arbitrary remote TCP SPICE examples. TLS must include peer verification and authorization. Monolithic configuration-file examples do not automatically apply to modular daemons or socket activation.

One of virt-manager's key strengths is managing VMs across multiple hosts from one interface. All operations use libvirt's remote-connection capabilities.

5.1 Add a remote connection

1. File → Add Connection...
2. Configuration parameters:

3. Click Connect

5.2 libvirt URI syntax

A virt-manager connection string is fundamentally a libvirt URI:

协议+传输://用户@主机/模式

5.3 SSH key configuration

SSH agent/public-key authentication is usually convenient for GUI use. Whether password and passphrase prompts work depends on askpass/agent integration; do not assume that GUI authentication is impossible. First verify the SSH host key and remote account permissions:

# 生成密钥对（如果还没有）
ssh-keygen -t ed25519 -C "virt-manager-remote"

# 复制公钥到远程主机
ssh-copy-id user@server.example.com

# 验证免密登录
ssh user@server.example.com "virsh list --all"

# 检查同一个远程账号对 system libvirt 的权限
ssh user@server.example.com "virsh -c qemu:///system list --all"
# 权限应由宿主组/polkit/socket 策略授予。
# 仅给 sudo virsh NOPASSWD 不会授权 GUI 的远程 libvirt 通道。

5.4 Remote SPICE display tunnels

When managing a remote VM, SPICE traffic travels through an SSH tunnel:

# 手动建立 SSH 隧道（将远程 SPICE 端口转发到本地）
ssh -L 5900:localhost:5900 -L 5901:localhost:5901 user@server.example.com

# 然后在本地的 virt-viewer 中连接
remote-viewer spice://localhost:5900

When connected over SSH, virt-manager automatically handles SPICE/VNC tunnel setup; no manual steps are needed.

5.5 Secure TLS connections in production

For multi-user production environments, TLS certificate authentication is recommended instead of SSH:

# 在远程宿主机上配置 TLS
# 1. 生成 CA 证书
# 2. 签发服务器证书
# 3. 签发客户端证书
# 4. 配置 /etc/libvirt/libvirtd.conf：
#    listen_tls = 1
#    tls_port = "16514"
#    key_file = "/etc/pki/libvirt/private/serverkey.pem"
#    cert_file = "/etc/pki/libvirt/servercert.pem"
#    ca_file = "/etc/pki/libvirt/cacert.pem"
# 5. 重启 libvirtd: systemctl restart libvirtd

# 客户端连接
virt-manager -c "qemu+tls://server/system"

System vs. session connections VMs managed through qemu:///system (system mode) appear in sudo virsh list --all; the identity under which QEMU runs depends on the host configuration. VMs managed through qemu:///session (session mode) run as the current user without sudo, but have limited functionality, such as being unable to use bridged networking. The actual default connection depends on the version, packaging, and existing user settings. Check the connection URI first.

6. Common problems and troubleshooting#

6.1 virt-manager cannot connect to libvirtd

# 问题：启动 virt-manager 时提示 "Unable to connect to libvirt qemu:///system"
# 排查步骤：

# 1. 确认 libvirtd 是否运行
sudo systemctl status libvirtd

# 2. 启动 libvirtd
sudo systemctl enable --now libvirtd

# 3. 确认当前用户在 libvirt 组中
groups $USER | grep libvirt
sudo usermod -aG libvirt $USER
# 重新登录后生效

# 4. 确认 virtlogd.socket 正常
sudo systemctl status virtlogd.socket

6.2 KVM unavailable: permission problems

# 问题：VM 启动失败，提示 KVM not available

# 检查 /dev/kvm 权限
ls -la /dev/kvm

# 修复权限（临时）
id -nG
# 不将 /dev/kvm 开放为世界可写；检查 kvm 组、udev 与授权策略

# 修复权限（永久，推荐）
sudo usermod -aG kvm $USER
# 重新登录

# 验证 KVM 可用
virsh capabilities | grep -A2 kvm

6.3 Performance problems

# 1. 确认使用 virtio 而不是 IDE/e1000
virsh dumpxml <vm-name> | grep -E "<disk|<interface"

# 2. 确认使用 KVM 加速而非 QEMU 模拟（查看 VM 详情页 Performance 标签）
# 在 virt-manager GUI 中：VM → View → Details → Overview → Hypervisor 应显示 "kvm"

# 3. 检查 CPU 是否支持硬件虚拟化
egrep -c '(vmx|svm)' /proc/cpuinfo  # > 0 表示支持