The essentials

Quick reference

One focused task per row. Jump to the related section for complete, working examples.

UseSyntaxExamples
Inspect CPU virtualization flagslscpu | grep -E 'Virtualization|Hypervisor vendor'View examples
Validate the KVM hostsudo virt-host-validate qemuView examples
Show the active libvirt URIvirsh --connect qemu:///system uriView examples
Inspect domain capabilitiesvirsh --connect qemu:///system domcapabilitiesView examples
List every domainvirsh --connect qemu:///system list --allView examples
Inspect domain statevirsh --connect qemu:///system dominfo prod-vmView examples
Export inactive domain XMLvirsh --connect qemu:///system dumpxml --inactive \ prod-vmView examples
Request a graceful shutdownvirsh --connect qemu:///system shutdown prod-vmView examples
Create a qcow2 diskqemu-img create -f qcow2 ./prod-vm.qcow2 80GView examples
Inspect image metadataqemu-img info --backing-chain \ /var/lib/libvirt/images/prod-vm.qcow2View examples
List storage-pool volumesvirsh --connect qemu:///system vol-list default \ --detailsView examples
Map guest disks to sourcesvirsh --connect qemu:///system domblklist prod-vm \ --detailsView examples
Query guest filesystemsvirsh --connect qemu:///system domfsinfo prod-vmView examples
Inspect vCPU placementvirsh --connect qemu:///system vcpuinfo prod-vmView examples
List domain interfacesvirsh --connect qemu:///system domiflist prod-vmView examples
List DHCP leasesvirsh --connect qemu:///system net-dhcp-leases defaultView examples
Inspect network configurationvirsh --connect qemu:///system net-dumpxml defaultView examples
List snapshot ancestryvirsh --connect qemu:///system snapshot-list prod-vm \ --treeView examples
Start a defined live backupvirsh --connect qemu:///system backup-begin prod-vm \ --backupxml /etc/libvirt/backup/prod-vm.xmlView examples
Inspect a block jobvirsh --connect qemu:///system blockjob prod-vm vda \ --info --bytesView examples
Check an offline imageqemu-img check /srv/backups/prod-vm/prod-vm.qcow2View examples
Check destination CPU compatibilityvirsh --connect qemu+ssh://hv2/system \ hypervisor-cpu-compare prod-vm.migratable.xml --error \ --validateView examples
Inspect domain security labelsvirsh --connect qemu:///system dominfo prod-vm | grep -E '^Security'View examples
Read the QEMU domain logsudo journalctl -u 'virtqemud*' --since -30minView examples

KVM supplies Linux kernel virtualization, QEMU emulates virtual hardware, and libvirt models and controls guests, storage, networks, and security policy. Reliable administration begins by proving host acceleration and driver capabilities, then treating domain XML, disk chains, firmware state, and guest data as one managed system. These commands target the local system libvirt connection; confirm the URI, installed versions, distribution packaging, storage topology, and outage plan before making changes.

Step by step

Detailed examples

01

Validate acceleration, permissions, and the exact connection

Hardware virtualization must be exposed by firmware and any outer hypervisor, the KVM kernel modules must match the architecture, and the libvirt QEMU driver must be able to access /dev/kvm. virt-host-validate identifies many common gaps but warnings still require interpretation. qemu:///system and qemu:///session have different daemons, privileges, networks, storage, and domain inventories; always state the URI in automation. Distribution packages may use monolithic libvirtd or modular virtqemud and virtstoraged services, and capability output changes with QEMU, libvirt, kernel, firmware, and machine-type versions.

Collect a read-only host readiness baseline
uname -r
lscpu | grep -E 'Architecture|Virtualization|Hypervisor vendor'
lsmod | grep -E '^kvm'
ls -l /dev/kvm
sudo virt-host-validate qemu
virsh --connect qemu:///system uri
virsh --connect qemu:///system version
virsh --connect qemu:///system domcapabilities > /tmp/domain-capabilities.xml
Back to quick reference ↑
02

Inspect persistent and live state before lifecycle changes

A persistent domain has inactive XML used on the next boot and may also have live XML with hot-plugged or runtime-only differences. Capture both when diagnosing drift. shutdown is an asynchronous request and can fail when the guest cannot respond; wait for a confirmed shut off state before host maintenance or cold copying. destroy is equivalent to pulling power and can corrupt guest filesystems and applications, so reserve it for approved incident recovery. Autostart changes boot behavior and should be coordinated with storage, network, and dependency readiness.

Inventory configuration and request an orderly stop
uri=qemu:///system
vm=prod-vm
virsh --connect "$uri" list --all
virsh --connect "$uri" dominfo "$vm"
virsh --connect "$uri" dumpxml --inactive "$vm" > /tmp/prod-vm.inactive.xml
virsh --connect "$uri" dumpxml "$vm" > /tmp/prod-vm.live.xml
virsh --connect "$uri" shutdown "$vm"
for attempt in 1 2 3 4 5; do
  state=$(virsh --connect "$uri" domstate "$vm")
  printf '%s\n' "$state"
  [ "$state" = 'shut off' ] && break
  sleep 10
done
Back to quick reference ↑
03

Treat disk formats, backing chains, and pools as integrity boundaries

Use libvirt storage pools where practical so ownership, SELinux labels, and lifecycle are modeled rather than bypassed. Explicitly declare disk formats: probing an untrusted or guest-writable raw image as another format has had security consequences. qcow2 supports sparse allocation and backing files, but its apparent file size is not its maximum growth and every backing file is part of recovery. Never use qemu-img check, resize, rebase, amend, convert, or snapshot operations on an image opened for writing by a running VM unless the command and storage protocol explicitly support that live operation. Monitor host free space independently of guest free space.

Inventory domain storage and chain dependencies
uri=qemu:///system
vm=prod-vm
virsh --connect "$uri" pool-list --all --details
virsh --connect "$uri" vol-list default --details
virsh --connect "$uri" domblklist "$vm" --details
virsh --connect "$uri" domblkinfo "$vm" vda --human
image=/var/lib/libvirt/images/prod-vm.qcow2
qemu-img info --backing-chain "$image"
df -h -- "$(dirname "$image")"
Prepare and validate a new image before domain attachment
uri=qemu:///system
virsh --connect "$uri" vol-create-as default prod-vm.qcow2 80G --format qcow2
virsh --connect "$uri" pool-refresh default
virsh --connect "$uri" vol-info --pool default prod-vm.qcow2
virsh --connect "$uri" vol-path --pool default prod-vm.qcow2
Back to quick reference ↑
04

Coordinate host operations with the guest operating system

The QEMU guest agent enables filesystem discovery, freeze and thaw, IP reporting, and more accurate shutdown behavior, but only when a virtio channel, the guest package, and its service are configured. Agent access is privileged: raw qemu-agent-command requests can inspect or modify guest state and should be tightly authorized and audited. Freeze filesystems only around a short, guaranteed backup action and always arrange thaw on failure; filesystem quiescence alone does not guarantee application consistency for every database. CPU and memory hotplug also depend on guest support and XML maximums.

Verify guest-agent visibility without modifying the guest
uri=qemu:///system
vm=prod-vm
virsh --connect "$uri" domfsinfo "$vm"
virsh --connect "$uri" domifaddr "$vm" --source agent
virsh --connect "$uri" guestinfo "$vm" --filesystem
virsh --connect "$uri" vcpucount "$vm"
virsh --connect "$uri" dommemstat "$vm"
Back to quick reference ↑
05

Understand virtual network reachability before exposure

The common default libvirt network provides host NAT and DHCP, but exact firewall backends, bridge names, address ranges, and autostart behavior are distribution-defined. A bridge attached to a physical network can expose guests directly and requires upstream switching, firewall, and address-management review. domifaddr may depend on the guest agent, DHCP leases, or ARP observation and is not authoritative in every topology. Editing or restarting a live network can interrupt every attached guest. Back up network XML, avoid overlapping address space, and test DNS and egress failure behavior before production rollout.

Map network policy to a domain interface
uri=qemu:///system
vm=prod-vm
virsh --connect "$uri" net-list --all
virsh --connect "$uri" net-info default
virsh --connect "$uri" net-dumpxml default > /tmp/default-network.xml
virsh --connect "$uri" net-dhcp-leases default
virsh --connect "$uri" domiflist "$vm"
virsh --connect "$uri" domifaddr "$vm" --source agent
Back to quick reference ↑
06

Build backups around an explicit consistency boundary

A VM snapshot is not an independent backup: external snapshots add backing-chain dependencies, and internal snapshots share the same storage failure domain. Live backups should use libvirt's backup and checkpoint APIs, reviewed XML, monitored jobs, sufficient scratch space, and guest or application quiescence. Cold backup is simpler but causes an outage; confirm the VM is fully shut off, inventory every disk plus domain XML and UEFI NVRAM, then copy or convert only inactive images. Multi-disk applications need one coordinated consistency point. Verify checksums and boot a restored copy on an isolated network rather than assuming archive creation equals recovery.

Capture a cold single-disk recovery set
uri=qemu:///system
vm=prod-vm
source_image=/var/lib/libvirt/images/prod-vm.qcow2
backup_dir=/srv/backups/libvirt/prod-vm-2026-08-12
xml=$(mktemp)
trap 'rm -f "$xml"' EXIT
state=$(virsh --connect "$uri" domstate "$vm")
[ "$state" = 'shut off' ] || { printf '%s\n' 'VM must be shut off' >&2; exit 1; }
virsh --connect "$uri" dumpxml --inactive "$vm" > "$xml"
sudo install -d -m 0700 "$backup_dir"
sudo install -m 0600 "$xml" "$backup_dir/prod-vm.xml"
sudo qemu-img convert -p -f qcow2 -O qcow2 "$source_image" "$backup_dir/prod-vm.qcow2"
sudo qemu-img check "$backup_dir/prod-vm.qcow2"
sudo sha256sum "$backup_dir/prod-vm.qcow2" "$backup_dir/prod-vm.xml" | sudo tee "$backup_dir/SHA256SUMS"
Inspect snapshot and backup-job state
uri=qemu:///system
vm=prod-vm
virsh --connect "$uri" snapshot-list "$vm" --tree
virsh --connect "$uri" checkpoint-list "$vm" --tree
virsh --connect "$uri" domblklist "$vm" --details
virsh --connect "$uri" blockjob "$vm" vda --info --bytes
virsh --connect "$uri" domjobinfo "$vm" --completed --keep-completed
Back to quick reference ↑
07

Preserve isolation and preflight migration failure modes

Libvirt normally confines QEMU with a dedicated account, cgroups, namespaces, seccomp, and SELinux or AppArmor policy. Prefer modeled domain XML over opaque QEMU command-line passthrough because libvirt cannot automatically authorize hidden host resources. Do not solve access failures by running QEMU as root or disabling confinement. Domain XML, NVRAM, disk images, TPM state, migration channels, and libvirt secret definitions can expose sensitive infrastructure or credentials; restrict backups and logs accordingly. Live migration additionally requires compatible CPUs, machine types, firmware, storage access, networks, QEMU/libvirt features, and enough bandwidth. Libvirt has no general migration dry-run flag: inspect migratable XML, compare the destination hypervisor CPU, validate dependencies separately, define rollback criteria, and retain the known-good source until post-migration validation. A control or data-network outage can pause or fail migration; post-copy failure can require specialized recovery.

Compare capabilities and CPU compatibility
vm=prod-vm
source_uri=qemu:///system
dest_uri=qemu+ssh://hv2/system
virsh --connect "$source_uri" domcapabilities > /tmp/source-capabilities.xml
virsh --connect "$dest_uri" domcapabilities > /tmp/destination-capabilities.xml
virsh --connect "$source_uri" dumpxml --migratable "$vm" > /tmp/prod-vm.migratable.xml
virsh --connect "$dest_uri" hypervisor-cpu-compare /tmp/prod-vm.migratable.xml --error --validate
virsh --connect "$source_uri" domiflist "$vm"
virsh --connect "$source_uri" domblklist "$vm" --details
Inventory confinement without weakening it
vm=prod-vm
virsh --connect qemu:///system dominfo "$vm" | grep -E '^Security'
virsh --connect qemu:///system dumpxml --security-info "$vm" > /tmp/prod-vm.security.xml
ps -eo user,group,label,pid,cmd | grep '[q]emu-system'
sudo ausearch -m AVC,USER_AVC -ts recent 2>/dev/null || true
sudo journalctl -u 'virtqemud*' --since -30min --no-pager
Back to quick reference ↑
08

Diagnose from the control plane down without changing evidence

First confirm URI, daemon health, domain state, job state, disk capacity, storage pool state, networks, logs, and mandatory-access-control denials. A paused guest may indicate I/O errors or exhausted storage rather than a CPU problem. Avoid deleting snapshots, rebasing chains, repairing qcow2, resetting NVRAM, undefining domains, or restarting all libvirt daemons until the dependency graph and recovery path are known. On modular deployments inspect virtqemud and virtstoraged; older systems may report everything through libvirtd. Remote connections add SSH, PKI, firewall, DNS, and clock-skew failure modes.

Collect a bounded virtualization incident snapshot
uri=qemu:///system
vm=prod-vm
virsh --connect "$uri" version
virsh --connect "$uri" domstate "$vm" --reason
virsh --connect "$uri" domjobinfo "$vm"
virsh --connect "$uri" domblkerror "$vm"
virsh --connect "$uri" domblklist "$vm" --details
virsh --connect "$uri" domiflist "$vm"
virsh --connect "$uri" pool-list --all --details
df -h /var/lib/libvirt/images
sudo journalctl -u 'virtqemud*' -u 'virtstoraged*' --since -30min --no-pager
Back to quick reference ↑

Keep exploring

More Linux cheat sheets

Linux · Containers, Virtualization, and Performance16 quick references

cgroup v2 Resource Control Cheat Sheet

Identify cgroup v2, apply CPU, memory, I/O, and task controls with systemd, inspect pressure and limit events, and understand safe hierarchy and delegation rules.

Open cheat sheet
Linux · Containers, Virtualization, and Performance20 quick references

Containers with Podman Cheat Sheet

Run and operate rootless Podman containers with secure defaults, durable storage, health checks, Quadlet services, secrets, updates, and recoverable backups.

Open cheat sheet

Sources and further reading

References

Authoritative documentation used to verify and expand this cheat sheet.

  1. Linux Kernel documentationKVM — Kernel-based Virtual Machine documentationdocs.kernel.org
  2. libvirt projectvirsh(1) — Management user interfacelibvirt.org
  3. libvirt projectvirt-host-validate(1) — Validate host virtualization setuplibvirt.org
  4. libvirt projectDomain XML formatlibvirt.org
  5. libvirt projectLive full disk backuplibvirt.org
  6. libvirt projectSecure usage of libvirtlibvirt.org
  7. libvirt projectQEMU command-line passthrough securitylibvirt.org
  8. QEMU projectQEMU disk image utilityqemu.org

Help us improve

Found a typo or missing example?

Tell us what would make this cheat sheet clearer, more complete, or more useful.

Share feedback