QEMU System Emulation User’s Guide

This manual is the overall guide for users using QEMU for full system emulation (as opposed to user-mode emulation). This includes working with hypervisors such as KVM, Xen, Hax or Hypervisor.Framework.

Contents:

• Quick Start
• Invocation
  • Standard options
  • Block device options
  • USB options
  • Display options
  • i386 target only
  • Network options
  • Character device options
  • TPM device options
  • Linux/Multiboot boot specific
  • Debug/Expert options
  • Generic object creation
  • Device URL Syntax
• Keys in the graphical frontends
• Keys in the character backend multiplexer
• QEMU Monitor
  • Commands
  • Integer expressions
• Disk Images
  • Quick start for disk image creation
  • Snapshot mode
  • VM snapshots
  • Disk image file formats
  • Read-only formats
  • Using host drives
    • Linux
    • Windows
    • Mac OS X
  • Virtual FAT disk images
  • NBD access
  • Sheepdog disk images
  • iSCSI LUNs
  • GlusterFS disk images
  • Secure Shell (ssh) disk images
  • NVMe disk images
  • Disk image file locking
• Network emulation
  • Using TAP network interfaces
    • Linux host
    • Windows host
  • Using the user mode network stack
  • Hubs
  • Connecting emulated networks between QEMU instances
• USB emulation
  • Connecting USB devices
  • Using host USB devices on a Linux host
• Inter-VM Shared Memory device
  • Migration with ivshmem
  • ivshmem and hugepages
• Direct Linux Boot
• VNC security
  • Without passwords
  • With passwords
  • With x509 certificates
  • With x509 certificates and client verification
  • With x509 certificates, client verification and passwords
  • With SASL authentication
  • With x509 certificates and SASL authentication
  • Configuring SASL mechanisms
• TLS setup for network services
  • Setup the Certificate Authority
  • Issuing server certificates
  • Issuing client certificates
  • TLS x509 credential configuration
  • TLS Pre-Shared Keys (PSK)
• GDB usage
• Managed start up options
• QEMU System Emulator Targets
  • x86 (PC) System emulator
    • Peripherals
    • Recommendations for KVM CPU model configuration on x86 hosts
    • Syntax for configuring CPU models
    • OS requirements
  • PowerPC System emulator
  • Sparc32 System emulator
  • Sparc64 System emulator
  • MIPS System emulator
    • Supported CPU model configurations on MIPS hosts
    • nanoMIPS System emulator
  • ARM System emulator
  • ColdFire System emulator
  • Xtensa System emulator
• Security
  • Overview
  • Security Requirements
    • Virtualization Use Case
    • Non-virtualization Use Case
  • Architecture
    • Guest Isolation
    • Principle of Least Privilege
    • Isolation mechanisms
  • Sensitive configurations
    • Monitor console (QMP and HMP)
• Adjunct Processor (AP) Device
  • Introduction
  • AP Architectural Overview
  • Start Interpretive Execution (SIE) Instruction
    • Example 1: Valid configuration
    • Example 2: Valid configuration
    • Example 3: Invalid configuration
  • AP Matrix Configuration on Linux Host
    • Binding AP devices to device drivers
    • Configuring an AP matrix for a linux guest
    • Starting a Linux Guest Configured with an AP Matrix
    • Hot plug a vfio-ap device into a running guest
    • Hot unplug a vfio-ap device from a running guest
  • Example: Configure AP Matrices for Three Linux Guests
  • Limitations
• Deprecated features
  • System emulator command line arguments
    • -machine enforce-config-section=on|off (since 3.1)
    • -no-kvm (since 1.3.0)
    • -usbdevice (since 2.10.0)
    • -drive file=json:{...{'driver':'file'}} (since 3.0)
    • -net ...,name=name (since 3.1)
    • -smp (invalid topologies) (since 3.1)
    • -vnc acl (since 4.0.0)
    • QEMU_AUDIO_ environment variables and -audio-help (since 4.0)
    • Creating sound card devices and vnc without audiodev= property (since 4.2)
    • -mon ...,control=readline,pretty=on|off (since 4.1)
    • -realtime (since 4.1)
    • -numa node,mem=size (since 4.1)
    • -numa node (without memory specified) (since 4.1)
    • -mem-path fallback to RAM (since 4.1)
    • RISC-V -bios (since 4.1)
    • -tb-size option (since 5.0)
    • -show-cursor option (since 5.0)
  • QEMU Machine Protocol (QMP) commands
    • change (since 2.5.0)
    • migrate_set_downtime and migrate_set_speed (since 2.8.0)
    • migrate-set-cache-size and query-migrate-cache-size (since 2.11.0)
    • query-block result field dirty-bitmaps[i].status (since 4.0)
    • query-block result field dirty-bitmaps (Since 4.2)
    • query-cpus (since 2.12.0)
    • query-cpus-fast arch output member (since 3.0.0)
    • cpu-add (since 4.0)
    • query-events (since 4.0)
    • chardev client socket with wait option (since 4.0)
  • Human Monitor Protocol (HMP) commands
    • The hub_id parameter of hostfwd_add / hostfwd_remove (since 3.1)
    • cpu-add (since 4.0)
    • acl_show, acl_reset, acl_policy, acl_add, acl_remove (since 4.0.0)
  • Guest Emulator ISAs
    • RISC-V ISA privledge specification version 1.09.1 (since 4.1)
  • System emulator CPUS
    • RISC-V ISA CPUs (since 4.1)
    • RISC-V ISA CPUs (since 4.1)
  • System emulator devices
    • ide-drive (since 4.2)
    • scsi-disk (since 4.2)
  • System emulator machines
    • mips r4k platform (since 5.0)
    • pc-1.0, pc-1.1, pc-1.2 and pc-1.3 (since 5.0)
    • spike_v1.9.1 and spike_v1.10 (since 4.1)
  • Device options
    • Emulated device options
    • Block device options
  • Related binaries
    • qemu-img convert -n -o (since 4.2.0)
  • Backwards compatibility
    • Runnability guarantee of CPU models (since 4.1.0)
• Recently removed features
  • QEMU Machine Protocol (QMP) commands
    • block-dirty-bitmap-add “autoload” parameter (since 4.2.0)
  • Related binaries
    • qemu-nbd --partition (removed in 5.0.0)
• Supported build platforms
  • Linux OS
  • Windows
  • macOS
  • FreeBSD
  • NetBSD
  • OpenBSD
• License