KVM and libvirt overview¶

KVM (Kernel-based Virtual Machine) turns the Linux kernel into a hypervisor. Together with QEMU for device emulation and libvirt for management, it gives you full virtual machines with near-native CPU performance on any host whose processor has hardware virtualization extensions (Intel VT-x or AMD-V).

This page explains how the pieces fit together, the concepts you need before touching a command, how to choose between the common options, and where to find the detailed how-to for each task. Every other page in this section is linked from here.

Contents¶

• The stack
• Core concepts
• Documentation map
• Typical workflows
• Decision guides
• Task index
• Command cheat sheet
• Rules of thumb and common pitfalls
• kvm-adm: one CLI for all of it
• Glossary
• Scope and further reading

The stack¶

  You:  virsh   virt-install   virt-manager   Cockpit   kvm-adm
              \        |            |            |        /
               +-------+------------+------------+-------+
                                    |
                            libvirt (libvirtd or the modular virtqemud/virtnetworkd/... daemons)
                     domains, networks, storage pools, snapshots, secrets
                                    |
                          QEMU process (one per running VM)
                      device emulation: virtio disk/net, serial, VNC/SPICE
                                    |
                     KVM kernel modules (kvm + kvm_intel or kvm_amd)  ->  /dev/kvm
                                    |
                          CPU virtualization extensions (VT-x / AMD-V)

Newer distributions may split libvirt into per-driver daemons (virtqemud, virtnetworkd, virtstoraged) instead of a single libvirtd; the commands in these docs work the same way against either. virsh version confirms that you can reach the daemon.

Core concepts¶

Domains¶

libvirt calls a VM a domain. A domain is defined (persistent XML config, survives reboots of the host) and either running or shut off. A domain can also be transient (running but not defined; it disappears when stopped).

• The XML holds the CPU count, memory, disks, NICs, console and everything else. View it with virsh dumpxml vm01, change it with virsh edit vm01. See Manage VMs.
• virsh destroy stops a domain immediately (like pulling the power cord). It does not delete anything. virsh undefine removes the definition, and with --remove-all-storage the disks. See Delete a VM.
• Many changes have --config (persistent, applies on next boot) and --live (running VM only) variants. Use both to change a running VM and keep the change. See Change resources.

Connection URIs: system versus session¶

The two URIs see different sets of VMs. If virsh list --all looks empty, check which URI you are on (virsh uri). See Host setup.

Storage: images, volumes, pools¶

• A disk image is a file (usually qcow2 or raw) that the guest sees as a block device (vda, vdb, ...).
• A storage pool is a place libvirt keeps images, most simply a directory. default is normally /var/lib/libvirt/images. See Storage pools.
• qcow2 gives you snapshots, thin provisioning and backing files; raw is fastest and simplest. See qcow2 vs raw.
• Use the virtio bus for disks and NICs. It is far faster than emulated IDE/e1000 hardware and is supported out of the box by modern Linux guests.

Networking¶

• default NAT network (virbr0): guests get private addresses via libvirt's dnsmasq and reach the outside through the host. Easy, but the LAN cannot reach the guests directly.
• Bridge (br0): guests join the physical LAN with their own addresses. Needs host network configuration. See Bridged networking.
• Every NIC has a MAC address. libvirt generates one from the 52:54:00 prefix; if you set one manually, make sure it does not match the host's (Troubleshooting).

Consoles and the guest agent¶

• The serial console (virsh console) works over SSH with no GUI and needs console=ttyS0 on the guest kernel command line. The installer arguments in Create VMs set that up.
• VNC/SPICE graphical consoles suit Windows and desktop guests (virt-viewer, virt-manager).
• qemu-guest-agent, installed inside the guest, lets the host ask the VM for its IP addresses (virsh domifaddr --source agent) and quiesce filesystems. It is the most reliable way to find the address of a bridged guest (Find a VM's IP address).

Snapshots and templates¶

• Snapshots (internal qcow2) capture disk state, optionally memory, and let you roll back. They live inside the image file, so they are not backups. See Snapshots.
• Templates: build a base image once (or fetch one with virt-builder), clean it with virt-sysprep, then clone it. See Offline image tools and Clone.

Documentation map¶

Typical workflows¶

1. Build a hypervisor¶

1. Check the hardware and install packages: Host setup.
2. Add your user to the libvirt group (permissions).
3. Decide on networking. Either use the default NAT network or configure a bridge: Networking.
4. Decide where images live (Storage pools); if that is not /var/lib/libvirt/images, apply the SELinux labelling.
5. Verify: virt-host-validate qemu, virsh net-list --all, virsh pool-list --all (or kvm-adm host doctor).

2. Create the first VM¶

1. Pick an install method with the decision guide below.
2. Look up the --os-variant (osinfo-query os | grep -i debian).
3. Run virt-install as shown in Create VMs.
4. Find its address (Find a VM's IP address) and connect over SSH.
5. Install qemu-guest-agent in the guest and enable autostart if the VM should come back after host reboots (Manage VMs).

3. Day-2 operations¶

Decision guides¶

System or session¶

Use qemu:///system unless you have a specific reason not to. It supports bridges, autostart at boot and shared storage. Use qemu:///session for throwaway VMs on a workstation where you do not have root.

NAT or bridge¶

qcow2 or raw¶

Pick qcow2 for almost everything: snapshots, thin provisioning, backing files and compression are worth the small overhead. Pick raw only for the last bit of I/O performance or when the storage layer already provides snapshots (LVM, ZFS, Ceph). Details: qcow2 vs raw.

Install method¶

Resize online or offline¶

Either way the partition and filesystem inside the guest still need growing: Resize a disk. Growing is routine; shrinking is risky and should be avoided.

Snapshot or backup¶

A snapshot is a quick rollback point stored in the same file as the disk. It protects against a bad upgrade, not against losing the file or the host. For real backups copy the image (or use qemu-img convert to a compressed copy) to different storage while the VM is shut off or after quiescing it with the guest agent.

Task index¶

Command cheat sheet¶

The five commands that cover most of the work, each with its kvm-adm equivalent (see kvm-adm for all of them).

Rules of thumb and common pitfalls¶

1. destroy is not delete. It powers the VM off. Deleting is undefine, with --remove-all-storage to remove disks (Delete a VM).
2. blockresize takes the new total size, not an increment, whereas qemu-img resize +N adds (Resize a disk).
3. A resized disk is not a resized filesystem. Grow the partition, then LVM (partition first, then pvresize), then the filesystem. A reboot alone does nothing.
4. Attach qcow2 files with --subdriver qcow2, otherwise libvirt treats them as raw (Add or remove a disk).
5. Use virsh edit, not the files in /etc/libvirt/qemu/. libvirt regenerates them, and edit validates your changes.
6. Memory and vCPU changes with --config apply on next boot. Maximum memory can only be changed with the VM shut off (Change resources).
7. Never let a guest share the host's MAC address. Symptom: guest has no network (Troubleshooting).
8. Offline image tools need a shut-off VM. Two guests writing one image corrupts it (Offline image tools).
9. Snapshots are not backups. They live in the same file as the disk (Snapshots).
10. Custom image directories need SELinux labels, and ISOs in a home directory need an ACL for the qemu user (Host setup).
11. Take an XML backup before hand-editing (virsh dumpxml vm01 > vm01.xml.bak), and validate with virt-xml-validate.
12. Test destructive commands with kvm-adm --dry-run before running them for real.

kvm-adm: one CLI for all of it¶

kvm-adm is a Rust command-line tool that folds the commands in these documents into one binary, with sensible defaults from ~/.kvm-adm.conf:

kvm-adm host doctor                                    # check the host
kvm-adm create web01 -l rhel-9.iso --kickstart http://192.0.2.50:8000/ks.cfg
kvm-adm ip web01                                       # guest agent, then lease, then ARP
kvm-adm disk add web01 50G                             # create, attach with the right driver
kvm-adm disk resize web01 vda 80G                      # online or offline, prints guest steps
kvm-adm snap create web01 before-upgrade
kvm-adm -n delete web01                                # dry run: shows what would be removed

It calls the real tools underneath, so the manual pages here always apply. Full reference: kvm-adm.

Glossary¶

Scope and further reading¶

These pages cover single-host KVM administration from the command line. They do not cover live migration, clustering (oVirt, Proxmox, OpenStack), GPU or PCI passthrough, or libvirt's SR-IOV networking. Upstream documentation:

• KVM project: https://www.linux-kvm.org/page/Main_Page
• libvirt: https://libvirt.org/docs.html and the domain XML format at https://libvirt.org/formatdomain.html
• libguestfs: https://libguestfs.org
• QEMU qemu-img: https://www.qemu.org/docs/master/tools/qemu-img.html