Examine individual changes
From Gentoo Wiki
This page allows you to examine the variables generated by the Abuse Filter for an individual change, and test it against filters.
Variables generated for this change
| Variable | Value |
|---|---|
Edit count of the user (user_editcount) | 439 |
Name of the user account (user_name) | 'Keks24' |
Age of the user account (user_age) | 252417492 |
Page ID (page_id) | 1888 |
Page namespace (page_namespace) | 0 |
Page title (without namespace) (page_title) | 'QEMU' |
Full page title (page_prefixedtitle) | 'QEMU' |
Action (action) | 'edit' |
Edit summary/reason (summary) | '/* USE_EXPAND */ be objective, emphasise keywords, improve wording, add reference to new use_expand syntax' |
Old content model (old_content_model) | 'wikitext' |
New content model (new_content_model) | 'wikitext' |
Old page wikitext, before the edit (old_wikitext) | '<languages />
<translate>
{{InfoBox stack
<!-- there is no {{InfoBox project}}, let us keep it that way. -->
|{{InfoBox homepage|https://www.qemu.org/docs/master/index.html|header=true}}
|{{InfoBox odoc|https://www.qemu.org/docs/master/index.html}}
|{{InfoBox wikipedia|QEMU}}
|{{InfoBox package|app-emulation/qemu}}
|{{InfoBox gitlab|https://gitlab.com/qemu-project/qemu|raw=true}}
|{{InfoBox wiki|https://wiki.qemu.org/Main_Page}}
|{{InfoBox bugs|https://gitlab.com/groups/qemu-project/-/issues}}
<!-- Until "InfoBox irc" improves to take on URI: irc:// URI, comment this out |{{InfoBox irc|irc://irc.oftc.net#qemu}} -->
|{{InfoBox blog|https://www.qemu.org/blog/}}
|{{InfoBox ohloh|qemu}}
}}
</translate>
<translate>
'''QEMU''' ('''Q'''uick '''EMU'''lator) is [[Article description::a generic, open-source hardware emulator and virtualization suite.]]
</translate>
<translate>
== Introduction ==
</translate>
<translate>
QEMU is a ''hardware emulator and virtualization tool'', which runs on a ''host OS platforms''. Inside a virtual machine, QEMU can emulate ''multiple operating systems''; it can also emulate ''embedded systems''.
QEMU supports ''32+ kinds of CPUs''. It emulates ''nearly all'' the opcodes of these CPUs.
QEMU has several plugins: {{c|Accelerator}} is one of them. This plugin allows execution directly by the host CPU. When using an {{c|accelerator}}, QEMU executes CPU instructions the ''fastest''.
QEMU is a [[wikipedia:Hypervisor#Classification|{{c|Type-2 hypervisor}}]], which runs within {{c|user namespace}} and performs virtual hardware emulation.
</translate>
<translate>
* Firstly, QEMU is a {{c|type 2 hypervisor}}.
* QEMU can be paired with {{c|KVM}} to run VMs at ''near-native speed''. This is accomplished by using hardware extensions such as: {{c|Intel VT-x}} or {{c|AMD-V}}.
* It can then emulate {{c|user-level processes}}, which allow applications, compiled for one architecture, to run on a different one.
* There are multiple operating modes: {{c|user-mode emulation}}, {{c|system emulation}}, {{c|KVM hosting}} and {{c|Xen hosting}}.
* QEMU can {{c|save}} and {{c|restore}} the state of virtual machines of all its running programs.
* QEMU virtual machines can interface with many types of physical host hardware, such as, but not limited to, {{c|CD-ROM drives}}, {{c|USB devices}}, {{c|audio interfaces}}, {{c|hard disks}} and {{c|network cards}}.
* Virtual disk image defaults to the {{c|qcow2}} format. This format only uses as much host disk space as the guest OS {{c|grows}} to use. Using the {{c|snapshot method}}, the guest OS can {{c|revert}} back to its desired state in time.
* It does ''not depend'' on graphical output methods on the host system, instead, making use of an integrated {{c|VNC server}} to access the screen of the guest OS.
* QEMU on a host CPU can execute multiple virtual CPUs ''in parallel''.
</translate>
<translate>
QEMU has support for several {{c|accelerator plug-ins}}:
</translate>
<translate>
{| class="table table-striped table-condensed sortable"
|-
! Virtualizer
! Accelerator
! Virtualization type
! Description
! Gentoo package name
|-
|{{c|qemu}}
|{{c|tcg}}
|{{c|full<ref>https://en.wikipedia.org/wiki/Full_virtualization</ref>/software-emulation}}
|QEMU's own {{c|Tiny Code Generator}}. This is the {{c|default}}. More frequently denoted as {{c|qemu}} and not {{c|qemu/tcg}} so often.
|{{package|app-emulation/qemu}}
|-
|{{c|qemu}}
|{{c|hvf}}<ref>https://developer.apple.com/documentation/hypervisor</ref>
|{{c|paravirtualization}}<ref>https://en.wikipedia.org/wiki/Paravirtualization</ref>
|Apple's Hypervisor framework based on {{c|Intel VT}}.
|
|-
|{{c|qemu}}
|{{c|whpx}}<ref>https://github.com/RceNinja/notes/blob/master/notes/build_qemu_with_enabled_hyper-v_acceleration_(whpx)_on_windows.md</ref>
|{{c|hybrid}}
|Microsoft's Windows Hypervisor Platform based on {{c|Intel VT}} or {{c|AMD-V}}.
|
|-
|{{c|qemu}}
|{{c|kvm}}
|{{c|paravirtualization}}<ref>https://en.wikipedia.org/wiki/Paravirtualization</ref>
|Linux {{c|Type-2 Hypervisor}}. This is the common choice for hosts using {{c|amd64}}, {{c|arm64}}, or {{c|mips}}<ref>[https://www.qemu.org/docs/master/system/qemu-cpu-models.html QEMU / KVM CPU model configuration]</ref>. Supports Microsoft Windows.
|{{package|app-emulation/qemu}}
|-
|{{c|qemu}}
|{{c|haxm}}<ref>https://github.com/intel/haxm</ref>'''
|{{c|paravirtualization}}<ref>https://en.wikipedia.org/wiki/Paravirtualization</ref>
|{{c|Intel VT}}, by Intel Corporation.
|
|}
</translate>
<translate>
QEMU, if used in conjunction with an {{c|accelerator}}, becomes a {{c|Type-1 hypervisor}}, which runs in {{c|Kernel namespace}}. This allows a {{c|user namespace program}} access to the{{c| hardware virtualization features}} of various processors. Such an {{c|accelerator}} can be {{c|KVM}} ('''K'''ernel-based '''V'''irtual '''M'''achine) or {{Link|Xen}}.
</translate>
<translate>
If ''no accelerator'' is used, QEMU will run entirely in {{c|user namespace}}, using its ''built-in'' binary translator {{c|TCG (Tiny Code Generator)}}. Using QEMU without an accelerator is ''relatively inefficient and slow''.
</translate>
<translate>
{{Note|This article typically uses {{c|KVM}} as the {{c|accelerator}} of choice, due to its GPL licensing and availability. Without {{c|KVM}}, nearly all commands described here, will still work (unless {{c|KVM-specific}}).}}
</translate>
<translate>
The following sub-articles provide detailed instructions on QEMU {{c|configurations}} and {{c|options}}:
</translate>
<translate>
* {{See also|QEMU/Bridge with Wifi Routing}}
* {{See also|QEMU/KVM IPv6 Support}}
* {{See also|QEMU/Linux guest|Linux guest}}
* {{See also|Virtiofs}}
* {{See also|QEMU/Options|Usage options}}
* {{See also|QEMU/OS2WarpV3 guest|OS2WarpV3 guest}}
* {{See also|QEMU/Windows guest}}
</translate>
<translate>
== Installation ==
</translate>
<translate>
=== BIOS and UEFI firmware ===
</translate>
<translate>
In order to utilize {{c|KVM}}, either {{c|Vt-x}} (<code>vmx</code>) or {{c|AMD-V}} (<code>svm</code>) must be supported by the processor. {{c|Vt-x}} or {{c|AMD-V}} are Intel's and AMD's respective technologies for permitting multiple operating systems to concurrently execute operations on the processors.
</translate>
<translate>
To inspect hardware for virtualization support, issue the following command:
</translate>
{{Cmd|grep --color --extended-regexp "vmx{{!}}svm" "/proc/cpuinfo"}}
<translate>
{{Important|For a period, manufacturers were shipping with virtualization '''turned off''' by default in the system's firmware. Toggling this feature in the firmware may require '''full removal of power''' from the system to take effect. If restarting the system does not work, try '''shutting down, unplugging the system, and pressing the power button in an unplugged state''' to discharge any residual energy from the {{c|power supply unit}} ({{c|PSU}}). Reapply power to the system to verify the configuration.}}
</translate>
<translate>
If {{c|KVM}} support is available, there should be a <code>kvm</code> device listed at {{Path|/dev/kvm}}. This will take effect ''after'' the system has booted to a KVM-enabled kernel.
</translate>
<translate>
=== Kernel ===
</translate>
<translate>
Described below are the basic requirements for {{c|KVM kernel configuration}} for the host OS. A more complete and up-to-date list can be found at the [http://www.linux-kvm.org/page/Tuning_Kernel KVM Tuning Kernel] page.
</translate>
<translate>
{{Note|Different guest (virtualized) OS may require additional kernel options. These are covered in the corresponding {{Link|QEMU|section=#Usage|Usage}} section.}}
</translate>
<translate>
{{KernelBox|title=Enable high resolution timer support (<var>CONFIG_HIGH_RES_TIMERS</var>)|1=
General setup --->
Timers subsystem --->
<*> High Resolution Timer Support
}}
{{Note|This includes support for {{c|ARM64 processors}}.}}
==== Physical CPU processor support - Host ====
If {{c|KVM}} support is not available, insert <var>CONFIG_KVM=y</var> into the {{Path|/usr/src/linux/.config}} and rebuild/reinstall the kernel (and its initramfs image). Come back here after the host is rebooted.
{{KernelBox|title=Enable KVM Support (<var>CONFIG_KVM</var>)|1=
[*] Virtualization --->
<*> Kernel-based Virtual Machine (KVM) support
}}
</translate>
<translate>
{{Note|This includes support for {{c|ARM64 processors}}.}}
</translate>
<translate>
==== Processor Support ====
</translate>
<translate>
{{KernelBox|title=Enable KVM support for Intel processors (<var>CONFIG_KVM_INTEL</var>)|1=
[*] Virtualization --->
<M> KVM for Intel processors support
}}
</translate>
<translate>
{{KernelBox|title=Enable KVM support for AMD processors (<var>CONFIG_KVM_AMD</var>)|1=
[*] Virtualization --->
<M> KVM for AMD processors support
}}
</translate>
<translate>
{{Warning|If ''both'' '''KVM support for Intel processors''' ''and'' '''KVM support for AMD processors''' are set to be built into the kernel (<code>*</code>), an error message will be returned by {{c|kprint}} at early boot. Since the system can only have one processor type: {{c|Intel}} ''or'' {{c|AMD}}. Enabling ''one'' or ''both'' options as ''modules'' (<code>M</code>) will solve this issue.}}
</translate>
<translate>
==== Handling kernel config at CLI ====
</translate>
<translate>
To set the various kernel configuration settings from the command lines, the {{Path|linux/scripts/kconfig/merge_config.sh}} shall be used here:
</translate>
<translate>
'''Mandatory kernel configuration options to set''':
</translate>
{{FileBox|filename=/usr/src/kernel-kconfig-qemu-host.config|1=
CONFIG_VIRTUALIZATION=y
CONFIG_KVM=y
CONFIG_KVM_INTEL=y
CONFIG_KVM_AMD=y
}}
{{RootCmd
|cd "/usr/src/linux"
|"./scripts/kconfig/merge_config.sh" ".config" "/usr/src/kernel-kconfig-qemu-host.config"
}}
<translate>
''Useful'' kernel configuration options to use:
</translate>
{{FileBox|filename=/usr/src/kernel-kconfig-qemu-host-optional.config|1=
CONFIG_VHOST_NET=y
CONFIG_HIGH_RES_TIMER=y
CONFIG_HPET=y
CONFIG_COMPACTION=y
CONFIG_MIGRATION=y
CONFIG_KSM=y
CONFIG_SYSFS=y
CONFIG_PROC_FS=y
CONFIG_TRANSPARENT_HUGEPAGE=y
CONFIG_CGROUPS=y
CONFIG_KVM_HYPERV=y
}}
{{RootCmd
|"./scripts/kconfig/merge_config.sh" ".config" "/usr/src/kernel-kconfig-qemu-host-optional.config"
}}
<translate>
{{Important|Recent {{c|Windows guests}} (at least {{c|Windows 10 22H2}} and up) are '''required''' to set <code>CONFIG_KVM_HYPERV</code> (as per the optional configuration above). If this is '''not''' selected, VMs will fail to provision (or boot) with errors like: <code>Failed to set MSR</code> and <code>Assertion `ret {{=}}{{=}} cpu->kvm_msr_buf->nmsrs' failed</code>.}}
==== Networking ====
</translate>
<translate>
Accelerated networking, '''required''' for <code>vhost-net</code> USE flag (recommend):
</translate>
<translate>
{{KernelBox|title=vhost-net kernel 5.7 and later (<var>CONFIG_VHOST_NET</var>)|1=
Device Drivers --->
[*] VHOST drivers --->
<*> Host kernel accelerator for virtio net
}}
</translate>
<translate>
{{KernelBox|title=vhost-net (before kernel 5.7)|1=
[*] Virtualization --->
<*> Host kernel accelerator for virtio net
}}
</translate>
<translate>
{{KernelBox|title=Optional advanced networking support (<var>CONFIG_NET_CORE</var>, <var>CONFIG_TUN</var>)|1=
Device Drivers --->
[*] Network device support --->
[*] Network core driver support
<*> Universal TUN/TAP device driver support
}}
</translate>
<translate>
Needed for {{c|802.1d Ethernet bridging}}:
</translate>
<translate>
{{KernelBox|title=Enabling 802.1d Ethernet Bridging support (<var>CONFIG_IPV6</var>, <var>CONFIG_BRIDGE</var>)|1=
[*] Networking support --->
Networking options --->
<*> The IPv6 protocol
<*> 802.1d Ethernet Bridging
}}
</translate>
<translate>
==== {{c|Intel VT-g}} (integrated graphics adapter virtualization) ====
</translate>
<translate>
Mediated device passthrough for Intel GPUs ({{c|Broadwell}} to {{c|Comet Lake}})<ref>https://forums.gentoo.org/viewtopic-p-8157704.html</ref>
</translate>
<translate>
{{KernelBox|title=Intel VT-g (<var>CONFIG_VFIO_MDEV</var>, <var>CONFIG_DRM_I915_GVT</var>, <var>CONFIG_DRM_I915_GVT_KVMGT</var>)|1=
Device Drivers --->
<*> VFIO Non-Privileged userspace driver framework
<*> Mediated device driver framework
Graphics Support --->
<*> Intel 8xx/9xx/G3x/G4x/HD Graphics
[*] Enable Intel GVT-g graphics virtualization host support
<*> Enable KVM host support Intel GVT-g graphics virtualization
}}
</translate>
<translate>
=== USE flags ===
</translate>
<translate>
Some packages are aware of the {{USE|qemu}} {{Link|USE flag}}.
</translate>
<translate>
Review the possible USE flags for QEMU:
</translate>
<translate>
{{USEflag|package=app-emulation/qemu}}
</translate>
<translate>
{{Note|More than one USE flag (<code>gtk</code>, <code>ncurses</code>, <code>sdl</code>, or <code>spice</code>) can be enabled for graphical output. If graphics are desired, it is generally recommended to enable more than one graphical USE flag.}}
</translate>
<translate>
{{Note|If {{c|virt-manager}} is going to be used, be sure to enable the <code>usbredir</code> and <code>spice</code> USE flags on the qemu package for correct operation.}}
</translate>
<translate>
==== USE_EXPAND ====
</translate>
<translate>
Additional ebuild configuration frobs are provided as the USE_EXPAND variables <var>QEMU_USER_TARGETS</var> and <var>QEMU_SOFTMMU_TARGETS</var>. See {{Package|app-emulation/qemu}} for a list of all the available targets (there are many; most are very obscure and may be ignored; leaving these variables at their default values will disable almost everything which is probably just fine for most users).
</translate>
<translate>
For each target specified, a qemu executable will be built. A <code>softmmu</code> target is the standard qemu use-case of emulating an entire system (like VirtualBox or VMWare, but with optional support for emulating CPU hardware along with peripherals). <code>user</code> targets execute user-mode code only; the (somewhat shockingly ambitious) purpose of these targets is to "magically" allow importing user-space linux ELF binaries from a different architecture into the native system (like multilib, without the awkward need for a software stack or CPU capable of running it).
</translate>
<translate>
In order to enable <var>QEMU_USER_TARGETS</var> and <var>QEMU_SOFTMMU_TARGETS</var> we can edit the variables globally in {{Path|/etc/portage/make.conf}}, i.e.:
</translate>
{{FileBox|filename=/etc/portage/make.conf|lang=bash|1=
QEMU_SOFTMMU_TARGETS{{=}}"arm x86_64 sparc"
QEMU_USER_TARGETS{{=}}"x86_64"
}}
<translate>
Or, the {{Path|/etc/portage/package.use}} file(s) can be modified. Two equivalent syntaxes are available: traditional USE flag syntax, i.e.:
</translate>
{{FileBox|filename=/etc/portage/package.use|1=
app-emulation/qemu qemu_softmmu_targets_arm qemu_softmmu_targets_x86_64 qemu_softmmu_targets_sparc
app-emulation/qemu qemu_user_targets_x86_64
}}
<translate>
Another alternative is to use the newer [[USE EXPAND|<var>USE_EXPAND</var>-specific syntax]]:
</translate>
{{FileBox|filename=/etc/portage/package.use|1=
app-emulation/qemu QEMU_SOFTMMU_TARGETS: arm x86_64 sparc QEMU_USER_TARGETS: x86_64
}}
<translate>
=== Emerge ===
</translate>
<translate>
After reviewing and adding any desired USE flags, emerge {{Package|app-emulation/qemu}}:
</translate>
{{Emerge|app-emulation/qemu}}
== Configuration ==
The following sub-articles provide detailed instructions on QEMU configurations and options:
* {{Link|QEMU/Options|Usage options}} - Contains common configuration options used with QEMU (graphics/display, networking, RAM, storage, processor, etc).
* {{See also|QEMU/Linux guest}}
* {{See also|QEMU/Windows guest}}
* {{Link|QEMU/OS2WarpV3 guest|OS2WarpV3 guest}} - Describes the configuration steps needed to setup a virtualized OS2WarpVs=3 guest with QEMU.
=== Environment variables ===
* <var>G_MESSAGES_DEBUG</var>
* <var>LISTEN_FDS</var>
* <var>LISTEN_PID</var>
* <var>QEMU_AUDIO_DRV</var>
* <var>QEMU_MODULE_DIR</var>
* <var>XDG_RUNTIME_DIR</var>
=== Files ===
Files that QEMU uses.
==== Single File ====
* {{Path|/etc/libvirt/qemu.conf}} - QEMU configuration file.
* {{Path|/etc/libvirt/qemu-lockd.conf}} - QEMU lock files
* {{Path|/etc/libvirt/qemu-sanlock.conf}} - QEMU SAN lock
* {{Path|/etc/libvirt/qemu/<domain-name>.xml}} - Domain XML setting for a virtual machine or container.
* {{Path|/etc/libvirt/qemu/autostart/<domain-name>.xml}} - Autostart this domain (virtual machine or container).
* {{Path|/etc/libvirt/qemu/networks/<network-name>.xml}} - Network XML setting file for a network connection
* {{Path|/etc/libvirt/qemu/networks/autostart/<network-name>.xml}} - Autostart this network connection.
* {{Path|/var/lib/libvirt/qemu/channel/target/<domain-name>/<socket-file>}} - UNIX socket file for Libvertd daemon API
* {{Path|/var/cache/libvirt/qemu/capabilities/<hash-value>.xml}} - Host OS capabilities in XML format
* {{Path|/var/lib/libvirt/qemu/checkpoint/}}
* {{Path|/var/lib/libvirt/qemu/<domain-9-XXXX>/}} - holds UNIX sockets and AES keys for this domain.
* {{Path|/var/lib/libvirt/qemu/dump/}}
* {{Path|/var/lib/libvirt/qemu/nvram/}}
* {{Path|/var/lib/libvirt/qemu/ram/}}
* {{Path|/var/lib/libvirt/qemu/save/}} - holding directory of hibernation images
* {{Path|/var/lib/libvirt/qemu/snapshot/}} - holding directory of snapshots
* {{Path|/var/run/libvirt/qemu}} - various UNIX socket and PID files for the {{c|libvirtd}} daemon.
==== Image File ====
QEMU supports the following disk image formats:
* QEMU copy-on-write ({{c|.qcow2}}, {{c|.qed}}, {{c|.qcow}}, {{c|.cow}})
* VirtualBox Virtual Disk Image ({{c|.vdi}})
* CD/DVD (ISO-9660) images ({{c|.iso}})
* Raw images ({{c|.img}}), that guest OS can control
* VFAT-16
* VMware Virtual Machine Disk ({{c|.vmdk}})
* Virtual PC Virtual Hard Disk ({{c|.vhd}})
* Parallels disk image ({{c|.hdd}}, {{c|.hds}}) – '''Read-only'''
* Apple macos Universal Disk Image Format ({{c|.dmg}}) – '''Read-only'''
* Bochs – '''Read-only'''
* Linux cloop – '''Read-only'''
<translate>
=== Additional software ===
</translate>
<translate>
User name {{c|qemu}} is required, defined by {{package|acct-user/qemu}} and evoked by {{package|sys-emulator/qemu}} package.
</translate>
<translate>
Group name {{c|qemu}} is required, defined by {{package|acct-group/qemu}} and evoked by {{package|sys-emulator/qemu}} package.
</translate>
<translate>
To connect to the SPICE server of QEMU, a GUI client like {{package|net-misc/spice-gtk}} is required.
</translate>
<translate>
== Usage ==
</translate>
<translate>
QEMU can be used in two ways, with GUI front ends and through the command line. The configuration of QEMU depends on which method is employed:
* GUI (Front-End) - To make life easier, there are multiple user-friendly front ends to QEMU: See {{Link|QEMU/Front-ends|Front-ends}}
* CLI
</translate>
<translate>
=== Invocation ===
</translate>
<translate>
QEMU supports around 34 different CPU architectures. To find the desired architecture, list what is installed.
</translate>
{{Cmd|ls /usr/bin/qemu-system-*|collapse-output=true|output=<pre>
/usr/bin/qemu-system-aarch64 /usr/bin/qemu-system-mips /usr/bin/qemu-system-rx
/usr/bin/qemu-system-alpha /usr/bin/qemu-system-mips64 /usr/bin/qemu-system-s390x
/usr/bin/qemu-system-arm /usr/bin/qemu-system-mips64el /usr/bin/qemu-system-sh4
/usr/bin/qemu-system-avr /usr/bin/qemu-system-mipsel /usr/bin/qemu-system-sh4eb
/usr/bin/qemu-system-cris /usr/bin/qemu-system-nios2 /usr/bin/qemu-system-sparc
/usr/bin/qemu-system-hppa /usr/bin/qemu-system-or1k /usr/bin/qemu-system-sparc64
/usr/bin/qemu-system-i386 /usr/bin/qemu-system-ppc /usr/bin/qemu-system-tricore
/usr/bin/qemu-system-loongarch64 /usr/bin/qemu-system-ppc64 /usr/bin/qemu-system-x86_64
/usr/bin/qemu-system-m68k /usr/bin/qemu-system-ppc64le /usr/bin/qemu-system-x86_64-microvm
/usr/bin/qemu-system-microblaze /usr/bin/qemu-system-riscv32 /usr/bin/qemu-system-xtensa
/usr/bin/qemu-system-microblazeel /usr/bin/qemu-system-riscv64 /usr/bin/qemu-system-xtensaeb
</pre>}}
{{Invocation|qemu-system-x86_64 -help|collapse-output=true|output=<pre>
QEMU emulator version 7.2.9 (Debian 1:7.2+dfsg-7+deb12u5)
Copyright (c) 2003-2022 Fabrice Bellard and the QEMU Project developers
usage: qemu-system-x86_64 [options] [disk_image]
'disk_image' is a raw hard disk image for IDE hard disk 0
Standard options:
-h or -help display this help and exit
-version display version information and exit
-machine [type=]name[,prop[=value][,...]]
selects emulated machine ('-machine help' for list)
property accel=accel1[:accel2[:...]] selects accelerator
supported accelerators are kvm, xen, hax, hvf, nvmm, whpx or tcg (default: tcg)
vmport=on|off|auto controls emulation of vmport (default: auto)
dump-guest-core=on|off include guest memory in a core dump (default=on)
mem-merge=on|off controls memory merge support (default: on)
aes-key-wrap=on|off controls support for AES key wrapping (default=on)
dea-key-wrap=on|off controls support for DEA key wrapping (default=on)
suppress-vmdesc=on|off disables self-describing migration (default=off)
nvdimm=on|off controls NVDIMM support (default=off)
memory-encryption=@var{} memory encryption object to use (default=none)
hmat=on|off controls ACPI HMAT support (default=off)
memory-backend='backend-id' specifies explicitly provided backend for main RAM (default=none)
cxl-fmw.0.targets.0=firsttarget,cxl-fmw.0.targets.1=secondtarget,cxl-fmw.0.size=size[,cxl-fmw.0.interleave-granularity=granularity]
sgx-epc.0.memdev=memid,sgx-epc.0.node=numaid
-cpu cpu select CPU ('-cpu help' for list)
-accel [accel=]accelerator[,prop[=value][,...]]
select accelerator (kvm, xen, hax, hvf, nvmm, whpx or tcg; use 'help' for a list)
igd-passthru=on|off (enable Xen integrated Intel graphics passthrough, default=off)
kernel-irqchip=on|off|split controls accelerated irqchip support (default=on)
kvm-shadow-mem=size of KVM shadow MMU in bytes
split-wx=on|off (enable TCG split w^x mapping)
tb-size=n (TCG translation block cache size)
dirty-ring-size=n (KVM dirty ring GFN count, default 0)
notify-vmexit=run|internal-error|disable,notify-window=n (enable notify VM exit and set notify window, x86 only)
thread=single|multi (enable multi-threaded TCG)
-smp [[cpus=]n][,maxcpus=maxcpus][,sockets=sockets][,dies=dies][,clusters=clusters][,cores=cores][,threads=threads]
set the number of initial CPUs to 'n' [default=1]
maxcpus= maximum number of total CPUs, including
offline CPUs for hotplug, etc
sockets= number of sockets on the machine board
dies= number of dies in one socket
clusters= number of clusters in one die
cores= number of cores in one cluster
threads= number of threads in one core
Note: Different machines may have different subsets of the CPU topology
parameters supported, so the actual meaning of the supported parameters
will vary accordingly. For example, for a machine type that supports a
three-level CPU hierarchy of sockets/cores/threads, the parameters will
sequentially mean as below:
sockets means the number of sockets on the machine board
cores means the number of cores in one socket
threads means the number of threads in one core
For a particular machine type board, an expected CPU topology hierarchy
can be defined through the supported sub-option. Unsupported parameters
can also be provided in addition to the sub-option, but their values
must be set as 1 in the purpose of correct parsing.
-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=node]
-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=node]
-numa dist,src=source,dst=destination,val=distance
-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]
-numa hmat-lb,initiator=node,target=node,hierarchy=memory|first-level|second-level|third-level,data-type=access-latency|read-latency|write-latency[,latency=lat][,bandwidth=bw]
-numa hmat-cache,node-id=node,size=size,level=level[,associativity=none|direct|complex][,policy=none|write-back|write-through][,line=size]
-add-fd fd=fd,set=set[,opaque=opaque]
Add 'fd' to fd 'set'
-set group.id.arg=value
set <arg> parameter for item <id> of type <group>
i.e. -set drive.$id.file=/path/to/image
-global driver.property=value
-global driver=driver,property=property,value=value
set a global default for a driver property
-boot [order=drives][,once=drives][,menu=on|off]
[,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]
'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)
'sp_name': the file's name that would be passed to bios as logo picture, if menu=on
'sp_time': the period that splash picture last if menu=on, unit is ms
'rb_timeout': the timeout before guest reboot when boot failed, unit is ms
-m [size=]megs[,slots=n,maxmem=size]
configure guest RAM
size: initial amount of guest memory
slots: number of hotplug slots (default: none)
maxmem: maximum amount of guest memory (default: none)
NOTE: Some architectures might enforce a specific granularity
-mem-path FILE provide backing storage for guest RAM
-mem-prealloc preallocate guest memory (use with -mem-path)
-k language use keyboard layout (for example 'fr' for French)
-audio-help show -audiodev equivalent of the currently specified audio settings
-audio [driver=]driver,model=value[,prop[=value][,...]]
specifies the audio backend and device to use;
apart from 'model', options are the same as for -audiodev.
use '-audio model=help' to show possible devices.
-audiodev [driver=]driver,id=id[,prop[=value][,...]]
specifies the audio backend to use
Use ``-audiodev help`` to list the available drivers
id= identifier of the backend
timer-period= timer period in microseconds
in|out.mixing-engine= use mixing engine to mix streams inside QEMU
in|out.fixed-settings= use fixed settings for host audio
in|out.frequency= frequency to use with fixed settings
in|out.channels= number of channels to use with fixed settings
in|out.format= sample format to use with fixed settings
valid values: s8, s16, s32, u8, u16, u32, f32
in|out.voices= number of voices to use
in|out.buffer-length= length of buffer in microseconds
-audiodev none,id=id,[,prop[=value][,...]]
dummy driver that discards all output
-audiodev alsa,id=id[,prop[=value][,...]]
in|out.dev= name of the audio device to use
in|out.period-length= length of period in microseconds
in|out.try-poll= attempt to use poll mode
threshold= threshold (in microseconds) when playback starts
-audiodev oss,id=id[,prop[=value][,...]]
in|out.dev= path of the audio device to use
in|out.buffer-count= number of buffers
in|out.try-poll= attempt to use poll mode
try-mmap= try using memory mapped access
exclusive= open device in exclusive mode
dsp-policy= set timing policy (0..10), -1 to use fragment mode
-audiodev pa,id=id[,prop[=value][,...]]
server= PulseAudio server address
in|out.name= source/sink device name
in|out.latency= desired latency in microseconds
-audiodev sdl,id=id[,prop[=value][,...]]
in|out.buffer-count= number of buffers
-audiodev sndio,id=id[,prop[=value][,...]]
-audiodev spice,id=id[,prop[=value][,...]]
-audiodev dbus,id=id[,prop[=value][,...]]
-audiodev wav,id=id[,prop[=value][,...]]
path= path of wav file to record
-device driver[,prop[=value][,...]]
add device (based on driver)
prop=value,... sets driver properties
use '-device help' to print all possible drivers
use '-device driver,help' to print all possible properties
-name string1[,process=string2][,debug-threads=on|off]
set the name of the guest
string1 sets the window title and string2 the process name
When debug-threads is enabled, individual threads are given a separate name
NOTE: The thread names are for debugging and not a stable API.
-uuid %08x-%04x-%04x-%04x-%012x
specify machine UUID
Block device options:
-fda/-fdb file use 'file' as floppy disk 0/1 image
-hda/-hdb file use 'file' as hard disk 0/1 image
-hdc/-hdd file use 'file' as hard disk 2/3 image
-cdrom file use 'file' as CD-ROM image
-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]
[,cache.direct=on|off][,cache.no-flush=on|off]
[,read-only=on|off][,auto-read-only=on|off]
[,force-share=on|off][,detect-zeroes=on|off|unmap]
[,driver specific parameters...]
configure a block backend
-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]
[,cache=writethrough|writeback|none|directsync|unsafe][,format=f]
[,snapshot=on|off][,rerror=ignore|stop|report]
[,werror=ignore|stop|report|enospc][,id=name]
[,aio=threads|native|io_uring]
[,readonly=on|off][,copy-on-read=on|off]
[,discard=ignore|unmap][,detect-zeroes=on|off|unmap]
[[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]
[[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]
[[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]
[[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]
[[,iops_size=is]]
[[,group=g]]
use 'file' as a drive image
-mtdblock file use 'file' as on-board Flash memory image
-sd file use 'file' as SecureDigital card image
-snapshot write to temporary files instead of disk image files
-fsdev local,id=id,path=path,security_model=mapped-xattr|mapped-file|passthrough|none
[,writeout=immediate][,readonly=on][,fmode=fmode][,dmode=dmode]
[[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]
[[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]
[[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]
[[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]
[[,throttling.iops-size=is]]
-fsdev proxy,id=id,socket=socket[,writeout=immediate][,readonly=on]
-fsdev proxy,id=id,sock_fd=sock_fd[,writeout=immediate][,readonly=on]
-fsdev synth,id=id
-virtfs local,path=path,mount_tag=tag,security_model=mapped-xattr|mapped-file|passthrough|none
[,id=id][,writeout=immediate][,readonly=on][,fmode=fmode][,dmode=dmode][,multidevs=remap|forbid|warn]
-virtfs proxy,mount_tag=tag,socket=socket[,id=id][,writeout=immediate][,readonly=on]
-virtfs proxy,mount_tag=tag,sock_fd=sock_fd[,id=id][,writeout=immediate][,readonly=on]
-virtfs synth,mount_tag=tag[,id=id][,readonly=on]
-iscsi [user=user][,password=password]
[,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE
[,initiator-name=initiator-iqn][,id=target-iqn]
[,timeout=timeout]
iSCSI session parameters
USB convenience options:
-usb enable on-board USB host controller (if not enabled by default)
-usbdevice name add the host or guest USB device 'name'
Display options:
-display spice-app[,gl=on|off]
-display sdl[,gl=on|core|es|off][,grab-mod=<mod>][,show-cursor=on|off]
[,window-close=on|off]
-display gtk[,full-screen=on|off][,gl=on|off][,grab-on-hover=on|off]
[,show-tabs=on|off][,show-cursor=on|off][,window-close=on|off]
[,show-menubar=on|off]
-display vnc=<display>[,<optargs>]
-display curses[,charset=<encoding>]
-display egl-headless[,rendernode=<file>]
-display dbus[,addr=<dbusaddr>]
[,gl=on|core|es|off][,rendernode=<file>]
-display none
select display backend type
The default display is equivalent to
"-display gtk"
-nographic disable graphical output and redirect serial I/Os to console
-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]
[,x509-key-file=<file>][,x509-key-password=<file>]
[,x509-cert-file=<file>][,x509-cacert-file=<file>]
[,x509-dh-key-file=<file>][,addr=addr]
[,ipv4=on|off][,ipv6=on|off][,unix=on|off]
[,tls-ciphers=<list>]
[,tls-channel=[main|display|cursor|inputs|record|playback]]
[,plaintext-channel=[main|display|cursor|inputs|record|playback]]
[,sasl=on|off][,disable-ticketing=on|off]
[,password=<string>][,password-secret=<secret-id>]
[,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]
[,jpeg-wan-compression=[auto|never|always]]
[,zlib-glz-wan-compression=[auto|never|always]]
[,streaming-video=[off|all|filter]][,disable-copy-paste=on|off]
[,disable-agent-file-xfer=on|off][,agent-mouse=[on|off]]
[,playback-compression=[on|off]][,seamless-migration=[on|off]]
[,gl=[on|off]][,rendernode=<file>]
enable spice
at least one of {port, tls-port} is mandatory
-portrait rotate graphical output 90 deg left (only PXA LCD)
-rotate <deg> rotate graphical output some deg left (only PXA LCD)
-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]
select video card type
-full-screen start in full screen
-vnc <display> shorthand for -display vnc=<display>
i386 target only:
-win2k-hack use it when installing Windows 2000 to avoid a disk full bug
-no-fd-bootchk disable boot signature checking for floppy disks
-no-acpi disable ACPI
-no-hpet disable HPET
-acpitable [sig=str][,rev=n][,oem_id=str][,oem_table_id=str][,oem_rev=n][,asl_compiler_id=str][,asl_compiler_rev=n][,{data|file}=file1[:file2]...]
ACPI table description
-smbios file=binary
load SMBIOS entry from binary file
-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]
[,uefi=on|off]
specify SMBIOS type 0 fields
-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]
[,uuid=uuid][,sku=str][,family=str]
specify SMBIOS type 1 fields
-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]
[,asset=str][,location=str]
specify SMBIOS type 2 fields
-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]
[,sku=str]
specify SMBIOS type 3 fields
-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]
[,asset=str][,part=str][,max-speed=%d][,current-speed=%d]
[,processor-id=%d]
specify SMBIOS type 4 fields
-smbios type=8[,external_reference=str][,internal_reference=str][,connector_type=%d][,port_type=%d]
specify SMBIOS type 8 fields
-smbios type=11[,value=str][,path=filename]
specify SMBIOS type 11 fields
-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]
[,asset=str][,part=str][,speed=%d]
specify SMBIOS type 17 fields
-smbios type=41[,designation=str][,kind=str][,instance=%d][,pcidev=str]
specify SMBIOS type 41 fields
Network options:
-netdev user,id=str[,ipv4=on|off][,net=addr[/mask]][,host=addr]
[,ipv6=on|off][,ipv6-net=addr[/int]][,ipv6-host=addr]
[,restrict=on|off][,hostname=host][,dhcpstart=addr]
[,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,domainname=domain]
[,tftp=dir][,tftp-server-name=name][,bootfile=f][,hostfwd=rule][,guestfwd=rule][,smb=dir[,smbserver=addr]]
configure a user mode network backend with ID 'str',
its DHCP server and optional services
-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]
[,br=bridge][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]
[,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]
[,poll-us=n]
configure a host TAP network backend with ID 'str'
connected to a bridge (default=br0)
use network scripts 'file' (default=/etc/qemu-ifup)
to configure it and 'dfile' (default=/etc/qemu-ifdown)
to deconfigure it
use '[down]script=no' to disable script execution
use network helper 'helper' (default=/usr/lib/qemu/qemu-bridge-helper) to
configure it
use 'fd=h' to connect to an already opened TAP interface
use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces
use 'sndbuf=nbytes' to limit the size of the send buffer (the
default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')
use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag
use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition
use vhost=on to enable experimental in kernel accelerator
(only has effect for virtio guests which use MSIX)
use vhostforce=on to force vhost on for non-MSIX virtio guests
use 'vhostfd=h' to connect to an already opened vhost net device
use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices
use 'queues=n' to specify the number of queues to be created for multiqueue TAP
use 'poll-us=n' to specify the maximum number of microseconds that could be
spent on busy polling for vhost net
-netdev bridge,id=str[,br=bridge][,helper=helper]
configure a host TAP network backend with ID 'str' that is
connected to a bridge (default=br0)
using the program 'helper (default=/usr/lib/qemu/qemu-bridge-helper)
-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]
[,rxsession=rxsession],txsession=txsession[,ipv6=on|off][,udp=on|off]
[,cookie64=on|off][,counter][,pincounter][,txcookie=txcookie]
[,rxcookie=rxcookie][,offset=offset]
configure a network backend with ID 'str' connected to
an Ethernet over L2TPv3 pseudowire.
Linux kernel 3.3+ as well as most routers can talk
L2TPv3. This transport allows connecting a VM to a VM,
VM to a router and even VM to Host. It is a nearly-universal
standard (RFC3931). Note - this implementation uses static
pre-configured tunnels (same as the Linux kernel).
use 'src=' to specify source address
use 'dst=' to specify destination address
use 'udp=on' to specify udp encapsulation
use 'srcport=' to specify source udp port
use 'dstport=' to specify destination udp port
use 'ipv6=on' to force v6
L2TPv3 uses cookies to prevent misconfiguration as
well as a weak security measure
use 'rxcookie=0x012345678' to specify a rxcookie
use 'txcookie=0x012345678' to specify a txcookie
use 'cookie64=on' to set cookie size to 64 bit, otherwise 32
use 'counter=off' to force a 'cut-down' L2TPv3 with no counter
use 'pincounter=on' to work around broken counter handling in peer
use 'offset=X' to add an extra offset between header and data
-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]
configure a network backend to connect to another network
using a socket connection
-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]
configure a network backend to connect to a multicast maddr and port
use 'localaddr=addr' to specify the host address to send packets from
-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]
configure a network backend to connect to another network
using an UDP tunnel
-netdev stream,id=str[,server=on|off],addr.type=inet,addr.host=host,addr.port=port[,to=maxport][,numeric=on|off][,keep-alive=on|off][,mptcp=on|off][,addr.ipv4=on|off][,addr.ipv6=on|off]
-netdev stream,id=str[,server=on|off],addr.type=unix,addr.path=path[,abstract=on|off][,tight=on|off]
-netdev stream,id=str[,server=on|off],addr.type=fd,addr.str=file-descriptor
configure a network backend to connect to another network
using a socket connection in stream mode.
-netdev dgram,id=str,remote.type=inet,remote.host=maddr,remote.port=port[,local.type=inet,local.host=addr]
-netdev dgram,id=str,remote.type=inet,remote.host=maddr,remote.port=port[,local.type=fd,local.str=file-descriptor]
configure a network backend to connect to a multicast maddr and port
use ``local.host=addr`` to specify the host address to send packets from
-netdev dgram,id=str,local.type=inet,local.host=addr,local.port=port[,remote.type=inet,remote.host=addr,remote.port=port]
-netdev dgram,id=str,local.type=unix,local.path=path[,remote.type=unix,remote.path=path]
-netdev dgram,id=str,local.type=fd,local.str=file-descriptor
configure a network backend to connect to another network
using an UDP tunnel
-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]
configure a network backend to connect to port 'n' of a vde switch
running on host and listening for incoming connections on 'socketpath'.
Use group 'groupname' and mode 'octalmode' to change default
ownership and permissions for communication port.
-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]
configure a vhost-user network, backed by a chardev 'dev'
-netdev vhost-vdpa,id=str[,vhostdev=/path/to/dev][,vhostfd=h]
configure a vhost-vdpa network,Establish a vhost-vdpa netdev
use 'vhostdev=/path/to/dev' to open a vhost vdpa device
use 'vhostfd=h' to connect to an already opened vhost vdpa device
-netdev hubport,id=str,hubid=n[,netdev=nd]
configure a hub port on the hub with ID 'n'
-nic [tap|bridge|user|l2tpv3|vde|vhost-user|socket][,option][,...][mac=macaddr]
initialize an on-board / default host NIC (using MAC address
macaddr) and connect it to the given host network backend
-nic none use it alone to have zero network devices (the default is to
provided a 'user' network connection)
-net nic[,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]
configure or create an on-board (or machine default) NIC and
connect it to hub 0 (please use -nic unless you need a hub)
-net [user|tap|bridge|vde|socket][,option][,option][,...]
old way to initialize a host network interface
(use the -netdev option if possible instead)
Character device options:
-chardev help
-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4=on|off][,ipv6=on|off][,nodelay=on|off]
[,server=on|off][,wait=on|off][,telnet=on|off][,websocket=on|off][,reconnect=seconds][,mux=on|off]
[,logfile=PATH][,logappend=on|off][,tls-creds=ID][,tls-authz=ID] (tcp)
-chardev socket,id=id,path=path[,server=on|off][,wait=on|off][,telnet=on|off][,websocket=on|off][,reconnect=seconds]
[,mux=on|off][,logfile=PATH][,logappend=on|off][,abstract=on|off][,tight=on|off] (unix)
-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]
[,localport=localport][,ipv4=on|off][,ipv6=on|off][,mux=on|off]
[,logfile=PATH][,logappend=on|off]
-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]
[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]
-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]
-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]
-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]
TPM device options:
-tpmdev passthrough,id=id[,path=path][,cancel-path=path]
use path to provide path to a character device; default is /dev/tpm0
use cancel-path to provide path to TPM's cancel sysfs entry; if
not provided it will be searched for in /sys/class/misc/tpm?/device
-tpmdev emulator,id=id,chardev=dev
configure the TPM device using chardev backend
Boot Image or Kernel specific:
-bios file set the filename for the BIOS
-pflash file use 'file' as a parallel flash image
-kernel bzImage use 'bzImage' as kernel image
-append cmdline use 'cmdline' as kernel command line
-initrd file use 'file' as initial ram disk
-dtb file use 'file' as device tree image
Debug/Expert options:
-compat [deprecated-input=accept|reject|crash][,deprecated-output=accept|hide]
Policy for handling deprecated management interfaces
-compat [unstable-input=accept|reject|crash][,unstable-output=accept|hide]
Policy for handling unstable management interfaces
-fw_cfg [name=]<name>,file=<file>
add named fw_cfg entry with contents from file
-fw_cfg [name=]<name>,string=<str>
add named fw_cfg entry with contents from string
-serial dev redirect the serial port to char device 'dev'
-parallel dev redirect the parallel port to char device 'dev'
-monitor dev redirect the monitor to char device 'dev'
-qmp dev like -monitor but opens in 'control' mode
-qmp-pretty dev like -qmp but uses pretty JSON formatting
-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]
-debugcon dev redirect the debug console to char device 'dev'
-pidfile file write PID to 'file'
-singlestep always run in singlestep mode
--preconfig pause QEMU before machine is initialized (experimental)
-S freeze CPU at startup (use 'c' to start execution)
-overcommit [mem-lock=on|off][cpu-pm=on|off]
run qemu with overcommit hints
mem-lock=on|off controls memory lock support (default: off)
cpu-pm=on|off controls cpu power management (default: off)
-gdb dev accept gdb connection on 'dev'. (QEMU defaults to starting
the guest without waiting for gdb to connect; use -S too
if you want it to not start execution.)
-s shorthand for -gdb tcp::1234
-d item1,... enable logging of specified items (use '-d help' for a list of log items)
-D logfile output log to logfile (default stderr)
-dfilter range,.. filter debug output to range of addresses (useful for -d cpu,exec,etc..)
-seed number seed the pseudo-random number generator
-L path set the directory for the BIOS, VGA BIOS and keymaps
-enable-kvm enable KVM full virtualization support
-xen-domid id specify xen guest domain id
-xen-attach attach to existing xen domain
libxl will use this when starting QEMU
-xen-domid-restrict restrict set of available xen operations
to specified domain id. (Does not affect
xenpv machine type).
-no-reboot exit instead of rebooting
-no-shutdown stop before shutdown
-action reboot=reset|shutdown
action when guest reboots [default=reset]
-action shutdown=poweroff|pause
action when guest shuts down [default=poweroff]
-action panic=pause|shutdown|exit-failure|none
action when guest panics [default=shutdown]
-action watchdog=reset|shutdown|poweroff|inject-nmi|pause|debug|none
action when watchdog fires [default=reset]
-loadvm [tag|id]
start right away with a saved state (loadvm in monitor)
-daemonize daemonize QEMU after initializing
-option-rom rom load a file, rom, into the option ROM space
-rtc [base=utc|localtime|<datetime>][,clock=host|rt|vm][,driftfix=none|slew]
set the RTC base and clock, enable drift fix for clock ticks (x86 only)
-icount [shift=N|auto][,align=on|off][,sleep=on|off][,rr=record|replay,rrfile=<filename>[,rrsnapshot=<snapshot>]]
enable virtual instruction counter with 2^N clock ticks per
instruction, enable aligning the host and virtual clocks
or disable real time cpu sleeping, and optionally enable
record-and-replay mode
-watchdog-action reset|shutdown|poweroff|inject-nmi|pause|debug|none
action when watchdog fires [default=reset]
-echr chr set terminal escape character instead of ctrl-a
-incoming tcp:[host]:port[,to=maxport][,ipv4=on|off][,ipv6=on|off]
-incoming rdma:host:port[,ipv4=on|off][,ipv6=on|off]
-incoming unix:socketpath
prepare for incoming migration, listen on
specified protocol and socket address
-incoming fd:fd
-incoming exec:cmdline
accept incoming migration on given file descriptor
or from given external command
-incoming defer
wait for the URI to be specified via migrate_incoming
-only-migratable allow only migratable devices
-nodefaults don't create default devices
-chroot dir chroot to dir just before starting the VM
-runas user change to user id user just before starting the VM
user can be numeric uid:gid instead
-sandbox on[,obsolete=allow|deny][,elevateprivileges=allow|deny|children]
[,spawn=allow|deny][,resourcecontrol=allow|deny]
Enable seccomp mode 2 system call filter (default 'off').
use 'obsolete' to allow obsolete system calls that are provided
by the kernel, but typically no longer used by modern
C library implementations.
use 'elevateprivileges' to allow or deny the QEMU process ability
to elevate privileges using set*uid|gid system calls.
The value 'children' will deny set*uid|gid system calls for
main QEMU process but will allow forks and execves to run unprivileged
use 'spawn' to avoid QEMU to spawn new threads or processes by
blocking *fork and execve
use 'resourcecontrol' to disable process affinity and schedular priority
-readconfig <file>
read config file
-no-user-config
do not load default user-provided config files at startup
-trace [[enable=]<pattern>][,events=<file>][,file=<file>]
specify tracing options
-plugin [file=]<file>[,<argname>=<argvalue>]
load a plugin
-async-teardown enable asynchronous teardown
-msg [timestamp[=on|off]][,guest-name=[on|off]]
control error message format
timestamp=on enables timestamps (default: off)
guest-name=on enables guest name prefix but only if
-name guest option is set (default: off)
-dump-vmstate <file>
Output vmstate information in JSON format to file.
Use the scripts/vmstate-static-checker.py file to
check for possible regressions in migration code
by comparing two such vmstate dumps.
-enable-sync-profile
enable synchronization profiling
Generic object creation:
-object TYPENAME[,PROP1=VALUE1,...]
create a new object of type TYPENAME setting properties
in the order they are specified. Note that the 'id'
property must be set. These objects are placed in the
'/objects' path.
During emulation, the following keys are useful:
ctrl-alt-f toggle full screen
ctrl-alt-n switch to virtual console 'n'
ctrl-alt toggle mouse and keyboard grab
When using -nographic, press 'ctrl-a h' to get some help.
See <https://qemu.org/contribute/report-a-bug> for how to report bugs.
More information on the QEMU project at <https://qemu.org>.
</pre>}}
<translate>
=== Permissions ===
</translate>
<translate>
In order to run a KVM-accelerated virtual machine without logging in as root, add normal users to the {{c|kvm}} group. Replace <code><username></code> in the example command below with the appropriate user(s):
</translate>
{{RootCmd|gpasswd -a larry kvm}}
<translate>
=== Creation of a disk image ===
</translate>
<translate>
To create a {{c|raw disk image}} with {{c|4 GiB}} size:
</translate>
{{Cmd|qemu-img create -f raw "/home/larry/qemu/my-systems-disk-image.img" 4G|collapse-output=false|output=<pre>
Formatting 'my-systems-disk-image.img', fmt=raw size=4294967296
</pre>}}
{{Cmd|ls -lh|collapse-output=false|output=<pre>
total 4
-rw-r--r-- 1 larry larry 4.0G Apr 12 11:23 my-systems-disk-image.img
</pre>}}
<translate>
To create a {{c|raw disk image}} with {{c|copy-on-write disabled}}:
</translate>
{{Cmd|qemu-img create -f raw "/home/larry/qemu/my-systems-disk-image.img" -o nocow{{=}}on 4G|collapse-output=false|output=<pre>
Formatting 'my-systems-disk-image.img', fmt=raw size=4294967296 nocow=on
</pre>}}
{{Cmd|ls -lh|collapse-output=false|output=<pre>
total 4
-rw-r--r-- 1 larry larry 4.0G Apr 12 11:23 my-systems-disk-image.img
</pre>}}
<translate>
The option {{c|nocow}} is also a file attribute, which can be determined via the command {{c|lsattr}}<ref>https://www.qemu.org/docs/master/system/qemu-block-drivers.html#cmdoption-qcow2-arg-nocow</ref>.
</translate>
<translate>
The following will create a {{c|qcow2 disk image}} (useful, if your filesystem does not support {{c|sparse files}}):
</translate>
{{Cmd|qemu-img create -f qcow2 "/home/larry/qemu/my-systems-disk-image.qcow2" 4G|collapse-output=false|output=<pre>
Formatting 'my-systems-disk-image.qcow2', fmt=qcow2 cluster_size=65536 extended_l2=off compression_type=zlib size=4294967296 lazy_refcounts=off refcount_bits=16
</pre>}}
{{Cmd|ls -l|collapse-output=false|output=<pre>
total 196K
-rw-r--r-- 1 larry larry 193K Apr 12 11:30 my-systems-disk-image.qcow2
</pre>}}
<translate>
=== Preparation of a bootable disk image from scratch ===
</translate>
<translate>
A system can be copied {{c|onto a disk image,}} when not using a cdrom installation medium.
By default, {{c|qemu}} uses a {{c|bios-firmware}} to boot the system.
The disk can be prepared with a {{c|msdos disk label}} and a {{c|gap}} between the {{c|end}} of the 512-byte-MBR (Master Boot Record) and the {{c|start}} of the first partition.
The gap is needed for boot loaders like {{c|grub}}, which place {{c|boot-code}} within this gap.
The following example uses the {{c|raw disk image}}, which was created {{Link|QEMU|section=#Creation_of_a_disk_image|above}}.
</translate>
<translate>
A raw disk image can be prepared by {{c|attaching}} it as a {{c|loop device}}:
</translate>
{{RootCmd|losetup --find --partscan --show "/home/larry/qemu/my-systems-disk-image.img"|collapse-output=false|output=<pre>
/dev/loop0
</pre>}}
<translate>
* The parameter <code>--find</code> finds the first unused {{c|loop device}}.
* The parameter <code>--partscan</code> forces the {{c|Kernel}} to scan the {{c|partition table}} on the {{c|newly created loop device}}, where the '''default sector size of 512 bytes''' is assumed.
* The parameter <code>--show</code> displays the name of the {{c|assigned loop device}}, if the parameter <code>--find</code> is used.
</translate>
<translate>
Attached {{c|loop devices}} can be listed with the follwing command:
</translate>
{{RootCmd|losetup --list|collapse-output=false|output=<pre>
NAME SIZELIMIT OFFSET AUTOCLEAR RO BACK-FILE DIO LOG-SEC
/dev/loop0 0 0 0 0 /home/larry/qemu/my-systems-disk-image.img 0 512
</pre>}}
<translate>
Then, the {{c|loop device}} can be {{c|formatted}} like a normal disk.
Print the {{c|partition table}}:
</translate>
{{RootCmd|parted "/dev/loop0" "unit mib print"|collapse-output=true|output=<pre>
Error: /dev/loop0: unrecognised disk label
Model: Loopback device (loopback)
Disk /dev/loop0: 4096MiB
Sector size (logical/physical): 512B/512B
Partition Table: unknown
Disk Flags:
</pre>}}
<translate>
Create a new {{c|partition table (msdos disk label)}}:
{{Warning|Make absolutely sure to select the correct {{c|loop device}}, since this may '''overwrite an existing partition table'''; resulting in '''data loss''', if the '''overwritten partition table''' cannot be recovered.}}
</translate>
{{RootCmd|parted "/dev/loop0" "mklabel msdos"|collapse-output=false|output=<pre>
Information: You may need to update /etc/fstab.
</pre>}}
The returned information can be ignored, since an entry in the configuration file {{Path|/etc/fstab}} is not needed.
{{c|parted}} now indicates, that the {{c|Partition Table}} is {{c|msdos}}:
{{RootCmd|parted "/dev/loop0" "unit mib print"|collapse-output=true|output=<pre>
Model: Loopback device (loopback)
Disk /dev/loop0: 4096MiB
Sector size (logical/physical): 512B/512B
Partition Table: msdos
Disk Flags:
Number Start End Size Type File system Flags
</pre>}}
<translate>
Create an {{c|ext4 partition}} with an {{c|offset}} of {{c|2 MiB}}:
</translate>
{{RootCmd|parted "/dev/loop0" "mkpart primary ext4 2MiB -1"}}
The parameter <code>-1</code> represents the {{c|last sector}} of the partition.
The {{c|first partition}} has been successfully created:
{{RootCmd|parted "/dev/loop0" "unit mib print"|collapse-output=true|output=<pre>
Model: Loopback device (loopback)
Disk /dev/loop0: 4096MiB
Sector size (logical/physical): 512B/512B
Partition Table: msdos
Disk Flags:
Number Start End Size Type File system Flags
1 2.00MiB 4095MiB 4093MiB primary
</pre>}}
This will also {{c|attach}} a new {{c|loop device}} at {{Path|/dev/loop0p1}}:
{{RootCmd|ls -l "/dev/loop0"*|collapse-output=false|output=<pre>
brw-rw---- 1 root disk 7, 0 Apr 12 12:33 /dev/loop0
brw-rw---- 1 root disk 259, 0 Apr 12 12:33 /dev/loop0p1
</pre>}}
<translate>
Set the {{c|boot flag}}:
</translate>
{{RootCmd|parted "/dev/loop0" set 1 boot on}}
All {{c|partition flags}} can be found in the column {{c|Flags}}:
{{RootCmd|parted "/dev/loop0" "unit mib print"|collapse-output=true|output=<pre>
Model: Loopback device (loopback)
Disk /dev/loop0: 4096MiB
Sector size (logical/physical): 512B/512B
Partition Table: msdos
Disk Flags:
Number Start End Size Type File system Flags
1 2.00MiB 4095MiB 4093MiB primary boot
</pre>}}
<translate>
Create the {{c|ext4 filesystem}}, which was declared via {{c|parted}} earlier:
{{Warning|Make absolutely sure to select the correct {{c|loop device}}, since this may '''overwrite an existing partition'''; resulting in '''data loss''', if the '''overwritten partition''' cannot be recovered.}}
</translate>
{{RootCmd|mkfs.ext4 "/dev/loop0p1"|collapse-output=true|output=<pre>
mke2fs 1.47.2 (1-Jan-2025)
Discarding device blocks: done
Creating filesystem with 1047808 4k blocks and 262144 inodes
Filesystem UUID: 0e344af7-6f7b-4d27-8238-89d46a5920d6
Superblock backups stored on blocks:
32768, 98304, 163840, 229376, 294912, 819200, 884736
Allocating group tables: done
Writing inode tables: done
Creating journal (16384 blocks): done
Writing superblocks and filesystem accounting information: done
</pre>}}
<translate>
Mount it at {{Path|/mnt/}}:
</translate>
{{RootCmd|mount "/dev/loop0p1" "/mnt/"}}
{{RootCmd|df --human-readable --print-type "/mnt/"|collapse-output=false|output=<pre>
Filesystem Type Size Used Avail Use% Mounted on
/dev/loop0p1 ext4 3.9G 24K 3.7G 1% /mnt
</pre>}}
<translate>
Create the directories {{Path|/mnt/boot/grub}}, which will be used by {{c|grub}} later:
</translate>
{{RootCmd|mkdir --parents --verbose "/mnt/boot/grub"|collapse-output=false|output=<pre>
mkdir: created directory '/mnt/boot'
mkdir: created directory '/mnt/boot/grub'
</pre>}}
<translate>
Install {{c|grub}} on the {{c|loop device}} and advice it to install its files to {{Path|/mnt/boot/grub/}}:
</translate>
{{RootCmd|grub-install --target{{=}}"i386-pc" --boot-directory{{=}}"/mnt/boot/" "/dev/loop0"}}
{{RootCmd|tree -F "/mnt/boot/grub/"|collapse-output=true|output=<pre>
/mnt/boot/grub/
├── fonts/
│ └── unicode.pf2
├── grubenv
├── i386-pc/
│ ├── acpi.mod
│ ├── adler32.mod
│ ├── affs.mod
│ ├── afs.mod
│ ├── afsplitter.mod
│ ├── ahci.mod
│ ├── all_video.mod
│ ├── aout.mod
│ ├── archelp.mod
│ ├── ata.mod
[...]
</pre>}}
<translate>
{{c|Unmount}} the filesystem and {{c|detach}} the {{c|loop device}}:
</translate>
{{RootCmd|umount "/mnt/"}}
{{RootCmd|losetup --detach "/dev/loop0"}}
<translate>
If the {{c|loop device}} is still {{c|busy}} - for example, processes are still accessing {{Path|/mnt/}} - no error will be returned. This can be {{c|verified}} and {{c|solved}} with the following commands:
</translate>
{{RootCmd|losetup --list|collapse-output=false|output=<pre>
NAME SIZELIMIT OFFSET AUTOCLEAR RO BACK-FILE DIO LOG-SEC
/dev/loop0 0 0 0 0 /home/larry/qemu/my-systems-disk-image.img 0 512
</pre>}}
{{RootCmd|lsof {{!}} grep "/mnt"|collapse-output=false|output=<pre>
sleep 31813 root cwd DIR 259,0 4096 131074 /mnt/boot/grub
</pre>}}
{{RootCmd|kill -SIGTERM 31813}}
<translate>
This is sufficient to boot into a {{c|grub2 boot prompt}}. This is can be used as the {{c|basis for a bootable system}}.
</translate>
<translate>
=== CPU selection ===
</translate>
<translate>
QEMU CPU selections have additional support for "[[QEMU/Front-ends|accelerators]]," like '''kvm''' (Kernel Virtual Machine) or '''tcg''' (Tiny Code Generator) or '''Xen''' (wikip[https://de.wikipedia.org/wiki/Xen]).
</translate>
<translate>
The accelerator can usually only "accelerate" the features that are available on the host CPU.
So the selection of the CPU affects the performance.
</translate>
<translate>
To get a list of CPUs:
</translate>
{{Cmd|qemu-system-x86_64 -cpu help|collapse-output=true|output=<pre>
Available CPUs:
x86 486 (alias configured by machine type)
x86 486-v1
x86 Broadwell (alias configured by machine type)
x86 Broadwell-IBRS (alias of Broadwell-v3)
x86 Broadwell-noTSX (alias of Broadwell-v2)
x86 Broadwell-noTSX-IBRS (alias of Broadwell-v4)
x86 Broadwell-v1 Intel Core Processor (Broadwell)
x86 Broadwell-v2 Intel Core Processor (Broadwell, no TSX)
x86 Broadwell-v3 Intel Core Processor (Broadwell, IBRS)
x86 Broadwell-v4 Intel Core Processor (Broadwell, no TSX, IBRS)
x86 Cascadelake-Server (alias configured by machine type)
x86 Cascadelake-Server-noTSX (alias of Cascadelake-Server-v3)
x86 Cascadelake-Server-v1 Intel Xeon Processor (Cascadelake)
x86 Cascadelake-Server-v2 Intel Xeon Processor (Cascadelake) [ARCH_CAPABILITIES]
x86 Cascadelake-Server-v3 Intel Xeon Processor (Cascadelake) [ARCH_CAPABILITIES, no TSX]
x86 Cascadelake-Server-v4 Intel Xeon Processor (Cascadelake) [ARCH_CAPABILITIES, no TSX]
x86 Cascadelake-Server-v5 Intel Xeon Processor (Cascadelake) [ARCH_CAPABILITIES, EPT switching, XSAVES, no TSX]
x86 Conroe (alias configured by machine type)
x86 Conroe-v1 Intel Celeron_4x0 (Conroe/Merom Class Core 2)
x86 Cooperlake (alias configured by machine type)
x86 Cooperlake-v1 Intel Xeon Processor (Cooperlake)
x86 Cooperlake-v2 Intel Xeon Processor (Cooperlake) [XSAVES]
x86 Denverton (alias configured by machine type)
x86 Denverton-v1 Intel Atom Processor (Denverton)
x86 Denverton-v2 Intel Atom Processor (Denverton) [no MPX, no MONITOR]
x86 Denverton-v3 Intel Atom Processor (Denverton) [XSAVES, no MPX, no MONITOR]
x86 Dhyana (alias configured by machine type)
x86 Dhyana-v1 Hygon Dhyana Processor
x86 Dhyana-v2 Hygon Dhyana Processor [XSAVES]
x86 EPYC (alias configured by machine type)
x86 EPYC-IBPB (alias of EPYC-v2)
x86 EPYC-Milan (alias configured by machine type)
x86 EPYC-Milan-v1 AMD EPYC-Milan Processor
x86 EPYC-Rome (alias configured by machine type)
x86 EPYC-Rome-v1 AMD EPYC-Rome Processor
x86 EPYC-Rome-v2 AMD EPYC-Rome Processor
x86 EPYC-v1 AMD EPYC Processor
x86 EPYC-v2 AMD EPYC Processor (with IBPB)
x86 EPYC-v3 AMD EPYC Processor
x86 Haswell (alias configured by machine type)
x86 Haswell-IBRS (alias of Haswell-v3)
x86 Haswell-noTSX (alias of Haswell-v2)
x86 Haswell-noTSX-IBRS (alias of Haswell-v4)
x86 Haswell-v1 Intel Core Processor (Haswell)
x86 Haswell-v2 Intel Core Processor (Haswell, no TSX)
x86 Haswell-v3 Intel Core Processor (Haswell, IBRS)
x86 Haswell-v4 Intel Core Processor (Haswell, no TSX, IBRS)
x86 Icelake-Server (alias configured by machine type)
x86 Icelake-Server-noTSX (alias of Icelake-Server-v2)
x86 Icelake-Server-v1 Intel Xeon Processor (Icelake)
x86 Icelake-Server-v2 Intel Xeon Processor (Icelake) [no TSX]
x86 Icelake-Server-v3 Intel Xeon Processor (Icelake)
x86 Icelake-Server-v4 Intel Xeon Processor (Icelake)
x86 Icelake-Server-v5 Intel Xeon Processor (Icelake) [XSAVES]
x86 Icelake-Server-v6 Intel Xeon Processor (Icelake) [5-level EPT]
x86 IvyBridge (alias configured by machine type)
x86 IvyBridge-IBRS (alias of IvyBridge-v2)
x86 IvyBridge-v1 Intel Xeon E3-12xx v2 (Ivy Bridge)
x86 IvyBridge-v2 Intel Xeon E3-12xx v2 (Ivy Bridge, IBRS)
x86 KnightsMill (alias configured by machine type)
x86 KnightsMill-v1 Intel Xeon Phi Processor (Knights Mill)
x86 Nehalem (alias configured by machine type)
x86 Nehalem-IBRS (alias of Nehalem-v2)
x86 Nehalem-v1 Intel Core i7 9xx (Nehalem Class Core i7)
x86 Nehalem-v2 Intel Core i7 9xx (Nehalem Core i7, IBRS update)
x86 Opteron_G1 (alias configured by machine type)
x86 Opteron_G1-v1 AMD Opteron 240 (Gen 1 Class Opteron)
x86 Opteron_G2 (alias configured by machine type)
x86 Opteron_G2-v1 AMD Opteron 22xx (Gen 2 Class Opteron)
x86 Opteron_G3 (alias configured by machine type)
x86 Opteron_G3-v1 AMD Opteron 23xx (Gen 3 Class Opteron)
x86 Opteron_G4 (alias configured by machine type)
x86 Opteron_G4-v1 AMD Opteron 62xx class CPU
x86 Opteron_G5 (alias configured by machine type)
x86 Opteron_G5-v1 AMD Opteron 63xx class CPU
x86 Penryn (alias configured by machine type)
x86 Penryn-v1 Intel Core 2 Duo P9xxx (Penryn Class Core 2)
x86 SandyBridge (alias configured by machine type)
x86 SandyBridge-IBRS (alias of SandyBridge-v2)
x86 SandyBridge-v1 Intel Xeon E312xx (Sandy Bridge)
x86 SandyBridge-v2 Intel Xeon E312xx (Sandy Bridge, IBRS update)
x86 Skylake-Client (alias configured by machine type)
x86 Skylake-Client-IBRS (alias of Skylake-Client-v2)
x86 Skylake-Client-noTSX-IBRS (alias of Skylake-Client-v3)
x86 Skylake-Client-v1 Intel Core Processor (Skylake)
x86 Skylake-Client-v2 Intel Core Processor (Skylake, IBRS)
x86 Skylake-Client-v3 Intel Core Processor (Skylake, IBRS, no TSX)
x86 Skylake-Client-v4 Intel Core Processor (Skylake, IBRS, no TSX) [IBRS, XSAVES, no TSX]
x86 Skylake-Server (alias configured by machine type)
x86 Skylake-Server-IBRS (alias of Skylake-Server-v2)
x86 Skylake-Server-noTSX-IBRS (alias of Skylake-Server-v3)
x86 Skylake-Server-v1 Intel Xeon Processor (Skylake)
x86 Skylake-Server-v2 Intel Xeon Processor (Skylake, IBRS)
x86 Skylake-Server-v3 Intel Xeon Processor (Skylake, IBRS, no TSX)
x86 Skylake-Server-v4 Intel Xeon Processor (Skylake, IBRS, no TSX)
x86 Skylake-Server-v5 Intel Xeon Processor (Skylake, IBRS, no TSX) [IBRS, XSAVES, EPT switching, no TSX]
x86 Snowridge (alias configured by machine type)
x86 Snowridge-v1 Intel Atom Processor (SnowRidge)
x86 Snowridge-v2 Intel Atom Processor (Snowridge, no MPX)
x86 Snowridge-v3 Intel Atom Processor (Snowridge, no MPX) [XSAVES, no MPX]
x86 Snowridge-v4 Intel Atom Processor (Snowridge, no MPX) [no split lock detect, no core-capability]
x86 Westmere (alias configured by machine type)
x86 Westmere-IBRS (alias of Westmere-v2)
x86 Westmere-v1 Westmere E56xx/L56xx/X56xx (Nehalem-C)
x86 Westmere-v2 Westmere E56xx/L56xx/X56xx (IBRS update)
x86 athlon (alias configured by machine type)
x86 athlon-v1 QEMU Virtual CPU version 2.5+
x86 core2duo (alias configured by machine type)
x86 core2duo-v1 Intel(R) Core(TM)2 Duo CPU T7700 @ 2.40GHz
x86 coreduo (alias configured by machine type)
x86 coreduo-v1 Genuine Intel(R) CPU T2600 @ 2.16GHz
x86 kvm32 (alias configured by machine type)
x86 kvm32-v1 Common 32-bit KVM processor
x86 kvm64 (alias configured by machine type)
x86 kvm64-v1 Common KVM processor
x86 n270 (alias configured by machine type)
x86 n270-v1 Intel(R) Atom(TM) CPU N270 @ 1.60GHz
x86 pentium (alias configured by machine type)
x86 pentium-v1
x86 pentium2 (alias configured by machine type)
x86 pentium2-v1
x86 pentium3 (alias configured by machine type)
x86 pentium3-v1
x86 phenom (alias configured by machine type)
x86 phenom-v1 AMD Phenom(tm) 9550 Quad-Core Processor
x86 qemu32 (alias configured by machine type)
x86 qemu32-v1 QEMU Virtual CPU version 2.5+
x86 qemu64 (alias configured by machine type)
x86 qemu64-v1 QEMU Virtual CPU version 2.5+
x86 base base CPU model type with no features enabled
x86 host processor with all supported host features
x86 max Enables all features supported by the accelerator in the current host
Recognized CPUID flags:
3dnow 3dnowext 3dnowprefetch abm ace2 ace2-en acpi adx aes amd-no-ssb
amd-ssbd amd-stibp amx-bf16 amx-int8 amx-tile apic arat arch-capabilities
arch-lbr avic avx avx-vnni avx2 avx512-4fmaps avx512-4vnniw avx512-bf16
avx512-fp16 avx512-vp2intersect avx512-vpopcntdq avx512bitalg avx512bw
avx512cd avx512dq avx512er avx512f avx512ifma avx512pf avx512vbmi
avx512vbmi2 avx512vl avx512vnni bmi1 bmi2 bus-lock-detect cid cldemote
clflush clflushopt clwb clzero cmov cmp-legacy core-capability cr8legacy
cx16 cx8 dca de decodeassists ds ds-cpl dtes64 erms est extapic f16c
flushbyasid fma fma4 fpu fsgsbase fsrm full-width-write fxsr fxsr-opt
gfni hle ht hypervisor ia64 ibpb ibrs ibrs-all ibs intel-pt intel-pt-lip
invpcid invtsc kvm-asyncpf kvm-asyncpf-int kvm-hint-dedicated kvm-mmu
kvm-msi-ext-dest-id kvm-nopiodelay kvm-poll-control kvm-pv-eoi kvm-pv-ipi
kvm-pv-sched-yield kvm-pv-tlb-flush kvm-pv-unhalt kvm-steal-time kvmclock
kvmclock kvmclock-stable-bit la57 lahf-lm lbrv lm lwp mca mce md-clear
mds-no misalignsse mmx mmxext monitor movbe movdir64b movdiri mpx msr
mtrr nodeid-msr npt nrip-save nx osvw pae pat pause-filter pbe pcid
pclmulqdq pcommit pdcm pdpe1gb perfctr-core perfctr-nb pfthreshold pge
phe phe-en pks pku pmm pmm-en pn pni popcnt pschange-mc-no pse pse36
rdctl-no rdpid rdrand rdseed rdtscp rsba rtm sep serialize sgx sgx-debug
sgx-exinfo sgx-kss sgx-mode64 sgx-provisionkey sgx-tokenkey sgx1 sgx2
sgxlc sha-ni skinit skip-l1dfl-vmentry smap smep smx spec-ctrl
split-lock-detect ss ssb-no ssbd sse sse2 sse4.1 sse4.2 sse4a ssse3 stibp
svm svm-lock svme-addr-chk syscall taa-no tbm tce tm tm2 topoext tsc
tsc-adjust tsc-deadline tsc-scale tsx-ctrl tsx-ldtrk umip v-vmsave-vmload
vaes vgif virt-ssbd vmcb-clean vme vmx vmx-activity-hlt
vmx-activity-shutdown vmx-activity-wait-sipi vmx-apicv-register
vmx-apicv-vid vmx-apicv-x2apic vmx-apicv-xapic vmx-cr3-load-noexit
vmx-cr3-store-noexit vmx-cr8-load-exit vmx-cr8-store-exit vmx-desc-exit
vmx-encls-exit vmx-entry-ia32e-mode vmx-entry-load-bndcfgs
vmx-entry-load-efer vmx-entry-load-pat vmx-entry-load-perf-global-ctrl
vmx-entry-load-pkrs vmx-entry-load-rtit-ctl vmx-entry-noload-debugctl
vmx-ept vmx-ept-1gb vmx-ept-2mb vmx-ept-advanced-exitinfo
vmx-ept-execonly vmx-eptad vmx-eptp-switching vmx-exit-ack-intr
vmx-exit-clear-bndcfgs vmx-exit-clear-rtit-ctl vmx-exit-load-efer
vmx-exit-load-pat vmx-exit-load-perf-global-ctrl vmx-exit-load-pkrs
vmx-exit-nosave-debugctl vmx-exit-save-efer vmx-exit-save-pat
vmx-exit-save-preemption-timer vmx-flexpriority vmx-hlt-exit vmx-ins-outs
vmx-intr-exit vmx-invept vmx-invept-all-context vmx-invept-single-context
vmx-invept-single-context vmx-invept-single-context-noglobals
vmx-invlpg-exit vmx-invpcid-exit vmx-invvpid vmx-invvpid-all-context
vmx-invvpid-single-addr vmx-io-bitmap vmx-io-exit vmx-monitor-exit
vmx-movdr-exit vmx-msr-bitmap vmx-mtf vmx-mwait-exit vmx-nmi-exit
vmx-page-walk-4 vmx-page-walk-5 vmx-pause-exit vmx-ple vmx-pml
vmx-posted-intr vmx-preemption-timer vmx-rdpmc-exit vmx-rdrand-exit
vmx-rdseed-exit vmx-rdtsc-exit vmx-rdtscp-exit vmx-secondary-ctls
vmx-shadow-vmcs vmx-store-lma vmx-true-ctls vmx-tsc-offset
vmx-tsc-scaling vmx-unrestricted-guest vmx-vintr-pending vmx-vmfunc
vmx-vmwrite-vmexit-fields vmx-vnmi vmx-vnmi-pending vmx-vpid
vmx-wbinvd-exit vmx-xsaves vmx-zero-len-inject vpclmulqdq waitpkg
wbnoinvd wdt x2apic xcrypt xcrypt-en xfd xgetbv1 xop xsave xsavec
xsaveerptr xsaveopt xsaves xstore xstore-en xtpr
</pre>}}
<translate>
Show the available accelerators:
</translate>
{{Cmd|qemu-system-x86_64 -accel help|collapse-output=true|output=<pre>
Accelerators supported in QEMU binary:
tcg
kvm
hvf
whpx
haxm
</pre>}}
<translate>
=== Starting QEMU ===
</translate>
<translate>
This is how to start a virtual machine with the same feature set as the host CPU, a raw disk image and {{c|2 GB}} of RAM.
By default, a {{c|VNC server}} is started that runs '''without password protection''' and listens on the {{c|loop interface}}.
QEMU is advised to {{c|listen on a local UNIX socket}} with the following command:
</translate>
{{Cmd|qemu-system-x86_64 -vnc "unix:/run/user/$(id --user)/qemu-vnc.sock" -enable-kvm -cpu host -drive "file{{=}}/home/larry/qemu/my-systems-disk-image.img,format{{=}}raw" -m 2G}}
<translate>
{{Warning|'''Set the file permissions appropriately''' to protect the {{c|VNC server}} from unauthorized access! If the virtual machine is started with the parameter <code>-vnc :0</code>, it will listen on {{c|port 5900}} (first display) '''on all interfaces without password protection!'''}}
{{Note|A {{c|CD-ROM installation}} or {{c|boot medium}} can be added via the parameter <code>-cdrom</code>. For example: <code>-cdrom filename.iso</code>}}
</translate>
=== Connecting to the virtual machine via VNC ===
In order to connect to the {{c|VNC server}}, the command {{c|vncviewer}}, which comes from the package {{Package|net-misc/tigervnc}}, can be used:
{{Cmd|vncviewer "/run/user/$(id --user)/qemu-vnc.sock"|collapse-output=true|output=<pre>
TigerVNC viewer v1.15.0
Built on: 2025-05-13 12:30
Copyright (C) 1999-2025 TigerVNC team and many others (see README.rst)
See https://www.tigervnc.org for information on TigerVNC.
Tue May 13 14:44:36 2025
DecodeManager: Detected 4 CPU core(s)
DecodeManager: Creating 4 decoder thread(s)
CConn: Connected to socket /run/user/1000/qemu-vnc.sock
CConnection: Server supports RFB protocol version 3.8
CConnection: Using RFB protocol version 3.8
CConnection: Choosing security type None(1)
CConn: Using pixel format depth 24 (32bpp) little-endian rgb888
CConn: SetDesktopSize failed: 3
</pre>}}
This will open a separate window, where one gets greeted with a {{c|GRUB shell}}, which was installed via <code>grub-install</code> {{Link|QEMU|section=#Preparation_of_a_bootable_disk_image_from_scratch|earlier}}:
[[File:Qemu_minimal_vm_with_grub2.png|500px]]
<translate>
== Troubleshooting ==
</translate>
=== qemu-system-x86_64: CPU model 'host' requires KVM or HVF ===
When trying to start a virtual machine, using the parameter <code>-cpu host</code>, one may encounter the following error:
{{CodeBox|title=CPU model 'host' requires KVM or HVF|1=
qemu-system-x86_64: CPU model 'host' requires KVM or HVF
}}
In order to fix this, use the parameter <code>-enable-kvm</code>, which will enable {{c|KVM full virtualization support}}:
{{Cmd|qemu-system-x86_64 -cpu host -enable-kvm [...]}}
<translate>
=== "kvm: already loaded the other module" ===
</translate>
<translate>
Sometimes during the early boot splash, the error message "kvm: already loaded the other module" can be seen. This message indicates both the Intel and the AMD kernel virtual machine settings have been enabled in the kernel. To fix this, enable it as a module or disable either the Intel ''or'' AMD KVM option specific to the system's processor in the kernel configuration. For example, if the system has an Intel processor, enable the Intel KVM, and then make sure the AMD KVM is set as a module (M) or is disabled (N). The relevant options to enable or disable can be found in the kernel's {{Path|.config}} file via the <var>CONFIG_KVM_INTEL</var> and <var>CONFIG_KVM_AMD</var> variables or in the configuration section above.
</translate>
<translate>
=== Creating TUN/TAP device - No such file or directory ===
</translate>
<translate>
Sometimes this error can occur if TUN/TAP support cannot be found in the kernel. To solve this, try loading the driver:
</translate>
<translate>
{{RootCmd|modprobe tun}}
</translate>
<translate>
If that works, add this to a file in {{Path|/etc/modules-load.d/}} to load on startup:
</translate>
<translate>
{{FileBox|filename=/etc/modules-load.d/qemu-modules.conf|1=tun}}
</translate>
<translate>
=== Configuration does not support video model 'qxl' ===
</translate>
<translate>
This is usually the case if QEMU is not built with the <code>spice</code> USE flag. To resolve this issue, try to build QEMU {{Link|Handbook:AMD64/Working/USE#Declaring_USE_flags_for_individual_packages|with the correct USE flag}}.
</translate>
<translate>
First add <code>spice</code> to via a [[:/etc/portage/package.use|package.use]] file:
</translate>
<translate>
{{FileBox|filename=/etc/portage/package.use/qemu|1=
app-emulation/qemu spice
}}
</translate>
<translate>
Then rebuild the package:
</translate>
<translate>
{{Emerge|app-emulation/qemu}}
</translate>
<translate>
=== My qemu has kvm support on some guest architectures ===
</translate>
<translate>
KVM works only for the same architecture. An ARM64 host cannot handle x86_64 instructions.
</translate>
<translate>
=== Invalid context errors on SELinux systems ===
</translate>
<translate>
By default, Libvirt generates a random SELinux MCS label for the QEMU process when it is started. If the loaded SELinux policy does not support MCS categories, the resulting security context will be invalid:
</translate>
<translate>
{{CodeBox|title=SELinux error from virt-manager|1=
Error starting domain: unable to set socket security context 'system_u:system_r:svirt_t:s0:c123,c456': Invalid argument
}}
</translate>
<translate>
{{CodeBox|title=SELinux error from the kernel|1=
kernel: SELinux: Context system_u:object_r:svirt_image_t:s0:c123,c456 is not valid (left unmapped).
}}
</translate>
<translate>
The solution is either to switch to one of the policy types which supports MCS categories or manually set the virtual machine's security labels, without MCS categories:
</translate>
<translate>
{{CodeBox|title=Libvirt domain XML with manually specified seclabel fields|lang=xml|1=
<domain type="kvm">
<name>fedora</name>
...
<devices>
<disk type="file" device="disk">
<driver name="qemu" type="qcow2"/>
<<nowiki>source</nowiki> file="/var/lib/libvirt/images/fedora.qcow2">
<seclabel model='selinux' relabel='yes'>
<label>system_u:object_r:svirt_image_t</label>
</seclabel>
</<nowiki>source</nowiki>>
<target dev="vda" bus="virtio"/>
<address type="pci" domain="0x0000" bus="0x04" slot="0x00" function="0x0"/>
</disk>
...
<seclabel type='static' model='selinux' relabel='yes'>
<label>system_u:system_r:svirt_t</label>
</seclabel>
</domain>
}}
</translate>
<translate>
=== Static-user and LTO ===
GCC will use a huge amount of RAM when LTO is enabled on the system if any of the <var>ppc64</var> options are enabled while using the <code>static-user</code> flag; because of this, it is recommended to disable LTO while compiling in this configuration or use {{Link|LLVM/Clang|Clang}} {{Link|LLVM/Clang|if LTO is required.}} See {{Bug|883419}}
</translate>
<translate>
=== lto1: internal compiler error: original not compressed with zstd ===
</translate>
<translate>
This is caused by a mismatch of GCC used to compile zlib and glib to the one being used to compile qemu, this can be fixed by rebuilding both before compiling qemu again.
{{Emerge|sys-libs/zlib dev-libs/glib}}
</translate>
<translate>
=== Windows guests fail to provision, boot, or Blue Screen of Death (BSOD) on startup ===
</translate>
<translate>
For optimal performance, it is recommended that modern Windows guests be run under a kernel with <code>CONFIG_KVM_HYPERV</code> enabled. As an additional benefit, if this option is not enabled, on some hardware, VMs will fail to provision, to boot, or present with a BSOD.
The technical reasons for this are as follows: later versions of Windows, when running as virtual machines, sometimes attempt to access hardware registers (specifically, Model Specific Registers or MSRs) that are not actually defined for the emulated processor within the virtual environment. This is often due to how Windows interacts with hardware, a driver trying to be overly clever, or even bugs within the operating system itself. While these MSR accesses might be valid on physical processors, the virtualized environment presented by KVM may not support them.
KVM's default behavior is to attempt to emulate these MSR accesses, but when encountering an undefined register, it reports an "invalid instruction" error to the virtual Windows instance. This error is often fatal, resulting in a BSOD and halting the virtual machine.
{{Tip|<code>unhandled rdmsr</code> or <code>unhandled wrmsr</code> messages in the system logs of the host indicate attempts to access undefined MSRs. Failures may also be more obvious, like <code>failed to set MSR</code> and <code>Assertion `ret {{=}}{{=}} cpu->kvm_msr_buf->nmsrs' failed</code> from <code>qemu-system-*</code>.}}
An alternative is passing the option <code>kvm.ignore_msrs=1</code> on the kernel command line or as an option to the KVM module:
{{FileBox|filename=/etc/modprobe.d/kvm.conf|1=options kvm ignore_msrs=1}}
The <code>ignore_msrs</code> option instructs KVM to ignore any attempts by the virtual Windows machine to access these undefined MSRs. Instead of generating an error and causing a BSOD, KVM silently bypasses the problematic instruction. This allows Windows to continue running, albeit potentially with some minor performance implications or masked underlying issues.
{{Tip|While <code>ignore_msrs</code> can be a quick fix for BSODs related to MSR access (not all BSODs are!), it is likely that this can be addressed properly by enabling the appropriate kernel option, as documented above.<br/><br/>This option should only need to be set if there are still undefined MSRs (and if there ''are'' it's probably a bug that needs to be reported to the software vendor or KVM/QEMU upstream).}}
</translate>
<translate>
== Removal ==
</translate>
There may be image files left behind after the removal of the QEMU package.
<translate>
=== Unmerge ===
</translate>
{{Unmerge|app-emulation/qemu}}
<translate>
== See also ==
</translate>
<translate>
* {{See also|Comparison of virtual machines}}
* {{See also|Fast Virtio VM}}
* {{See also|GPU passthrough with virt-manager, QEMU, and KVM}}
* {{See also|QEMU with Open vSwitch network}}
* {{See also|Virtualization}}
* {{See also|QEMU/Front-ends}}
* {{See also|Libvirt|libvirt}}
* {{See also|Libvirt/QEMU_networking|libvirt/QEMU networking}}
* {{See also|Libvirt/QEMU_guest|libvirt/QEMU guest}}
* {{See also|Virt-manager|Virt-manager}}
* {{See also|Virt-manager/QEMU_guest|virt-manager/QEMU guest}}
* {{See also|QEMU/Linux guest|QEMU/Linux guest}}
* {{See also|QEMU/Bridge with Wifi Routing|QEMU/Bridge with Wifi Routing}}
* {{See also|Category:QEMU Guests}}
* {{See also|Remote_desktop}}
</translate>
<translate>
== External resources ==
</translate>
<translate>
* https://www.linux-kvm.org/page/KvmOnGentoo - The Gentoo article on the KVM wiki
* https://wiki.qemu.org/Main_Page - The Official QEMU wiki
</translate>
== {{Anchor|References}} References ==
{{reflist}}
<translate>
[[Category:GUI software]]
[[Category:Virtualization]]
[[Category:QEMU]]
[[Category:Command line tools]]
[[Category:Emulation]]
</translate>' |
New page wikitext, after the edit (new_wikitext) | '<languages />
<translate>
{{InfoBox stack
<!-- there is no {{InfoBox project}}, let us keep it that way. -->
|{{InfoBox homepage|https://www.qemu.org/docs/master/index.html|header=true}}
|{{InfoBox odoc|https://www.qemu.org/docs/master/index.html}}
|{{InfoBox wikipedia|QEMU}}
|{{InfoBox package|app-emulation/qemu}}
|{{InfoBox gitlab|https://gitlab.com/qemu-project/qemu|raw=true}}
|{{InfoBox wiki|https://wiki.qemu.org/Main_Page}}
|{{InfoBox bugs|https://gitlab.com/groups/qemu-project/-/issues}}
<!-- Until "InfoBox irc" improves to take on URI: irc:// URI, comment this out |{{InfoBox irc|irc://irc.oftc.net#qemu}} -->
|{{InfoBox blog|https://www.qemu.org/blog/}}
|{{InfoBox ohloh|qemu}}
}}
</translate>
<translate>
'''QEMU''' ('''Q'''uick '''EMU'''lator) is [[Article description::a generic, open-source hardware emulator and virtualization suite.]]
</translate>
<translate>
== Introduction ==
</translate>
<translate>
QEMU is a ''hardware emulator and virtualization tool'', which runs on a ''host OS platforms''. Inside a virtual machine, QEMU can emulate ''multiple operating systems''; it can also emulate ''embedded systems''.
QEMU supports ''32+ kinds of CPUs''. It emulates ''nearly all'' the opcodes of these CPUs.
QEMU has several plugins: {{c|Accelerator}} is one of them. This plugin allows execution directly by the host CPU. When using an {{c|accelerator}}, QEMU executes CPU instructions the ''fastest''.
QEMU is a [[wikipedia:Hypervisor#Classification|{{c|Type-2 hypervisor}}]], which runs within {{c|user namespace}} and performs virtual hardware emulation.
</translate>
<translate>
* Firstly, QEMU is a {{c|type 2 hypervisor}}.
* QEMU can be paired with {{c|KVM}} to run VMs at ''near-native speed''. This is accomplished by using hardware extensions such as: {{c|Intel VT-x}} or {{c|AMD-V}}.
* It can then emulate {{c|user-level processes}}, which allow applications, compiled for one architecture, to run on a different one.
* There are multiple operating modes: {{c|user-mode emulation}}, {{c|system emulation}}, {{c|KVM hosting}} and {{c|Xen hosting}}.
* QEMU can {{c|save}} and {{c|restore}} the state of virtual machines of all its running programs.
* QEMU virtual machines can interface with many types of physical host hardware, such as, but not limited to, {{c|CD-ROM drives}}, {{c|USB devices}}, {{c|audio interfaces}}, {{c|hard disks}} and {{c|network cards}}.
* Virtual disk image defaults to the {{c|qcow2}} format. This format only uses as much host disk space as the guest OS {{c|grows}} to use. Using the {{c|snapshot method}}, the guest OS can {{c|revert}} back to its desired state in time.
* It does ''not depend'' on graphical output methods on the host system, instead, making use of an integrated {{c|VNC server}} to access the screen of the guest OS.
* QEMU on a host CPU can execute multiple virtual CPUs ''in parallel''.
</translate>
<translate>
QEMU has support for several {{c|accelerator plug-ins}}:
</translate>
<translate>
{| class="table table-striped table-condensed sortable"
|-
! Virtualizer
! Accelerator
! Virtualization type
! Description
! Gentoo package name
|-
|{{c|qemu}}
|{{c|tcg}}
|{{c|full<ref>https://en.wikipedia.org/wiki/Full_virtualization</ref>/software-emulation}}
|QEMU's own {{c|Tiny Code Generator}}. This is the {{c|default}}. More frequently denoted as {{c|qemu}} and not {{c|qemu/tcg}} so often.
|{{package|app-emulation/qemu}}
|-
|{{c|qemu}}
|{{c|hvf}}<ref>https://developer.apple.com/documentation/hypervisor</ref>
|{{c|paravirtualization}}<ref>https://en.wikipedia.org/wiki/Paravirtualization</ref>
|Apple's Hypervisor framework based on {{c|Intel VT}}.
|
|-
|{{c|qemu}}
|{{c|whpx}}<ref>https://github.com/RceNinja/notes/blob/master/notes/build_qemu_with_enabled_hyper-v_acceleration_(whpx)_on_windows.md</ref>
|{{c|hybrid}}
|Microsoft's Windows Hypervisor Platform based on {{c|Intel VT}} or {{c|AMD-V}}.
|
|-
|{{c|qemu}}
|{{c|kvm}}
|{{c|paravirtualization}}<ref>https://en.wikipedia.org/wiki/Paravirtualization</ref>
|Linux {{c|Type-2 Hypervisor}}. This is the common choice for hosts using {{c|amd64}}, {{c|arm64}}, or {{c|mips}}<ref>[https://www.qemu.org/docs/master/system/qemu-cpu-models.html QEMU / KVM CPU model configuration]</ref>. Supports Microsoft Windows.
|{{package|app-emulation/qemu}}
|-
|{{c|qemu}}
|{{c|haxm}}<ref>https://github.com/intel/haxm</ref>'''
|{{c|paravirtualization}}<ref>https://en.wikipedia.org/wiki/Paravirtualization</ref>
|{{c|Intel VT}}, by Intel Corporation.
|
|}
</translate>
<translate>
QEMU, if used in conjunction with an {{c|accelerator}}, becomes a {{c|Type-1 hypervisor}}, which runs in {{c|Kernel namespace}}. This allows a {{c|user namespace program}} access to the{{c| hardware virtualization features}} of various processors. Such an {{c|accelerator}} can be {{c|KVM}} ('''K'''ernel-based '''V'''irtual '''M'''achine) or {{Link|Xen}}.
</translate>
<translate>
If ''no accelerator'' is used, QEMU will run entirely in {{c|user namespace}}, using its ''built-in'' binary translator {{c|TCG (Tiny Code Generator)}}. Using QEMU without an accelerator is ''relatively inefficient and slow''.
</translate>
<translate>
{{Note|This article typically uses {{c|KVM}} as the {{c|accelerator}} of choice, due to its GPL licensing and availability. Without {{c|KVM}}, nearly all commands described here, will still work (unless {{c|KVM-specific}}).}}
</translate>
<translate>
The following sub-articles provide detailed instructions on QEMU {{c|configurations}} and {{c|options}}:
</translate>
<translate>
* {{See also|QEMU/Bridge with Wifi Routing}}
* {{See also|QEMU/KVM IPv6 Support}}
* {{See also|QEMU/Linux guest|Linux guest}}
* {{See also|Virtiofs}}
* {{See also|QEMU/Options|Usage options}}
* {{See also|QEMU/OS2WarpV3 guest|OS2WarpV3 guest}}
* {{See also|QEMU/Windows guest}}
</translate>
<translate>
== Installation ==
</translate>
<translate>
=== BIOS and UEFI firmware ===
</translate>
<translate>
In order to utilize {{c|KVM}}, either {{c|Vt-x}} (<code>vmx</code>) or {{c|AMD-V}} (<code>svm</code>) must be supported by the processor. {{c|Vt-x}} or {{c|AMD-V}} are Intel's and AMD's respective technologies for permitting multiple operating systems to concurrently execute operations on the processors.
</translate>
<translate>
To inspect hardware for virtualization support, issue the following command:
</translate>
{{Cmd|grep --color --extended-regexp "vmx{{!}}svm" "/proc/cpuinfo"}}
<translate>
{{Important|For a period, manufacturers were shipping with virtualization '''turned off''' by default in the system's firmware. Toggling this feature in the firmware may require '''full removal of power''' from the system to take effect. If restarting the system does not work, try '''shutting down, unplugging the system, and pressing the power button in an unplugged state''' to discharge any residual energy from the {{c|power supply unit}} ({{c|PSU}}). Reapply power to the system to verify the configuration.}}
</translate>
<translate>
If {{c|KVM}} support is available, there should be a <code>kvm</code> device listed at {{Path|/dev/kvm}}. This will take effect ''after'' the system has booted to a KVM-enabled kernel.
</translate>
<translate>
=== Kernel ===
</translate>
<translate>
Described below are the basic requirements for {{c|KVM kernel configuration}} for the host OS. A more complete and up-to-date list can be found at the [http://www.linux-kvm.org/page/Tuning_Kernel KVM Tuning Kernel] page.
</translate>
<translate>
{{Note|Different guest (virtualized) OS may require additional kernel options. These are covered in the corresponding {{Link|QEMU|section=#Usage|Usage}} section.}}
</translate>
<translate>
{{KernelBox|title=Enable high resolution timer support (<var>CONFIG_HIGH_RES_TIMERS</var>)|1=
General setup --->
Timers subsystem --->
<*> High Resolution Timer Support
}}
{{Note|This includes support for {{c|ARM64 processors}}.}}
==== Physical CPU processor support - Host ====
If {{c|KVM}} support is not available, insert <var>CONFIG_KVM=y</var> into the {{Path|/usr/src/linux/.config}} and rebuild/reinstall the kernel (and its initramfs image). Come back here after the host is rebooted.
{{KernelBox|title=Enable KVM Support (<var>CONFIG_KVM</var>)|1=
[*] Virtualization --->
<*> Kernel-based Virtual Machine (KVM) support
}}
</translate>
<translate>
{{Note|This includes support for {{c|ARM64 processors}}.}}
</translate>
<translate>
==== Processor Support ====
</translate>
<translate>
{{KernelBox|title=Enable KVM support for Intel processors (<var>CONFIG_KVM_INTEL</var>)|1=
[*] Virtualization --->
<M> KVM for Intel processors support
}}
</translate>
<translate>
{{KernelBox|title=Enable KVM support for AMD processors (<var>CONFIG_KVM_AMD</var>)|1=
[*] Virtualization --->
<M> KVM for AMD processors support
}}
</translate>
<translate>
{{Warning|If ''both'' '''KVM support for Intel processors''' ''and'' '''KVM support for AMD processors''' are set to be built into the kernel (<code>*</code>), an error message will be returned by {{c|kprint}} at early boot. Since the system can only have one processor type: {{c|Intel}} ''or'' {{c|AMD}}. Enabling ''one'' or ''both'' options as ''modules'' (<code>M</code>) will solve this issue.}}
</translate>
<translate>
==== Handling kernel config at CLI ====
</translate>
<translate>
To set the various kernel configuration settings from the command lines, the {{Path|linux/scripts/kconfig/merge_config.sh}} shall be used here:
</translate>
<translate>
'''Mandatory kernel configuration options to set''':
</translate>
{{FileBox|filename=/usr/src/kernel-kconfig-qemu-host.config|1=
CONFIG_VIRTUALIZATION=y
CONFIG_KVM=y
CONFIG_KVM_INTEL=y
CONFIG_KVM_AMD=y
}}
{{RootCmd
|cd "/usr/src/linux"
|"./scripts/kconfig/merge_config.sh" ".config" "/usr/src/kernel-kconfig-qemu-host.config"
}}
<translate>
''Useful'' kernel configuration options to use:
</translate>
{{FileBox|filename=/usr/src/kernel-kconfig-qemu-host-optional.config|1=
CONFIG_VHOST_NET=y
CONFIG_HIGH_RES_TIMER=y
CONFIG_HPET=y
CONFIG_COMPACTION=y
CONFIG_MIGRATION=y
CONFIG_KSM=y
CONFIG_SYSFS=y
CONFIG_PROC_FS=y
CONFIG_TRANSPARENT_HUGEPAGE=y
CONFIG_CGROUPS=y
CONFIG_KVM_HYPERV=y
}}
{{RootCmd
|"./scripts/kconfig/merge_config.sh" ".config" "/usr/src/kernel-kconfig-qemu-host-optional.config"
}}
<translate>
{{Important|Recent {{c|Windows guests}} (at least {{c|Windows 10 22H2}} and up) are '''required''' to set <code>CONFIG_KVM_HYPERV</code> (as per the optional configuration above). If this is '''not''' selected, VMs will fail to provision (or boot) with errors like: <code>Failed to set MSR</code> and <code>Assertion `ret {{=}}{{=}} cpu->kvm_msr_buf->nmsrs' failed</code>.}}
==== Networking ====
</translate>
<translate>
Accelerated networking, '''required''' for <code>vhost-net</code> USE flag (recommend):
</translate>
<translate>
{{KernelBox|title=vhost-net kernel 5.7 and later (<var>CONFIG_VHOST_NET</var>)|1=
Device Drivers --->
[*] VHOST drivers --->
<*> Host kernel accelerator for virtio net
}}
</translate>
<translate>
{{KernelBox|title=vhost-net (before kernel 5.7)|1=
[*] Virtualization --->
<*> Host kernel accelerator for virtio net
}}
</translate>
<translate>
{{KernelBox|title=Optional advanced networking support (<var>CONFIG_NET_CORE</var>, <var>CONFIG_TUN</var>)|1=
Device Drivers --->
[*] Network device support --->
[*] Network core driver support
<*> Universal TUN/TAP device driver support
}}
</translate>
<translate>
Needed for {{c|802.1d Ethernet bridging}}:
</translate>
<translate>
{{KernelBox|title=Enabling 802.1d Ethernet Bridging support (<var>CONFIG_IPV6</var>, <var>CONFIG_BRIDGE</var>)|1=
[*] Networking support --->
Networking options --->
<*> The IPv6 protocol
<*> 802.1d Ethernet Bridging
}}
</translate>
<translate>
==== {{c|Intel VT-g}} (integrated graphics adapter virtualization) ====
</translate>
<translate>
Mediated device passthrough for Intel GPUs ({{c|Broadwell}} to {{c|Comet Lake}})<ref>https://forums.gentoo.org/viewtopic-p-8157704.html</ref>
</translate>
<translate>
{{KernelBox|title=Intel VT-g (<var>CONFIG_VFIO_MDEV</var>, <var>CONFIG_DRM_I915_GVT</var>, <var>CONFIG_DRM_I915_GVT_KVMGT</var>)|1=
Device Drivers --->
<*> VFIO Non-Privileged userspace driver framework
<*> Mediated device driver framework
Graphics Support --->
<*> Intel 8xx/9xx/G3x/G4x/HD Graphics
[*] Enable Intel GVT-g graphics virtualization host support
<*> Enable KVM host support Intel GVT-g graphics virtualization
}}
</translate>
<translate>
=== USE flags ===
</translate>
<translate>
Some packages are aware of the {{USE|qemu}} {{Link|USE flag}}.
</translate>
<translate>
Review the possible USE flags for QEMU:
</translate>
<translate>
{{USEflag|package=app-emulation/qemu}}
</translate>
<translate>
{{Note|More than one USE flag (<code>gtk</code>, <code>ncurses</code>, <code>sdl</code>, or <code>spice</code>) can be enabled for graphical output. If graphics are desired, it is generally recommended to enable more than one graphical USE flag.}}
</translate>
<translate>
{{Note|If {{c|virt-manager}} is going to be used, be sure to enable the <code>usbredir</code> and <code>spice</code> USE flags on the qemu package for correct operation.}}
</translate>
<translate>
==== USE_EXPAND ====
</translate>
<translate>
Additional ebuild configuration are provided as the ''USE_EXPAND'' variables <var>QEMU_USER_TARGETS</var> and <var>QEMU_SOFTMMU_TARGETS</var>. See {{Package|app-emulation/qemu}} for a list of all the available targets (there are many; most are very obscure and may be ignored; leaving these variables at their default values ''will disable almost everything'', which is probably just fine for most users).
</translate>
<translate>
For each target specified, a <code>qemu</code> executable will be built. A <code>softmmu</code> target is the standard qemu use-case of emulating an entire system (like {{c|VirtualBox}} or {{c|VMWare}}, but with optional support for emulating CPU hardware along with peripherals). <code>user</code> targets execute user-mode code only; the (somewhat ambitious) purpose of these targets, is to "magically" allow importing {{c|user namespace Linux ELF binaries}} from a different architecture into the native system (like {{c|multilib}}, without the need for a {{c|software stack}} or CPU capable of running it).
</translate>
<translate>
In order to enable <var>QEMU_USER_TARGETS</var> and <var>QEMU_SOFTMMU_TARGETS</var>, one can set the variables globally in {{Path|/etc/portage/make.conf}}:
</translate>
{{FileBox|filename=/etc/portage/make.conf|lang=bash|1=
QEMU_SOFTMMU_TARGETS{{=}}"arm x86_64 sparc"
QEMU_USER_TARGETS{{=}}"x86_64"
}}
{{Warning|Setting the ''USE flags'' globally in {{Path|/etc/portage/make.conf}} is discouraged, because of possible ordering issues in {{c|Portage}}.<ref>https://wiki.gentoo.org/wiki//etc/portage/make.conf#USE_EXPAND</ref>}}
<translate>
Files in the directory {{Path|/etc/portage/package.use}} can be added. There are two equivalent syntaxes available:
One is the traditional ''USE flag'' syntax:
</translate>
{{FileBox|filename=/etc/portage/package.use/qemu|1=
app-emulation/qemu qemu_softmmu_targets_arm qemu_softmmu_targets_x86_64 qemu_softmmu_targets_sparc
app-emulation/qemu qemu_user_targets_x86_64
}}
<translate>
And the other, preferred one, is the {{Link|/etc/portage/make.conf|section=#USE_EXPAND|<var>USE_EXPAND</var>}} syntax:
</translate>
{{FileBox|filename=/etc/portage/package.use/qemu|1=
app-emulation/qemu QEMU_SOFTMMU_TARGETS: arm x86_64 sparc QEMU_USER_TARGETS: x86_64
}}
<translate>
=== Emerge ===
</translate>
<translate>
After reviewing and adding any desired USE flags, emerge {{Package|app-emulation/qemu}}:
</translate>
{{Emerge|app-emulation/qemu}}
== Configuration ==
The following sub-articles provide detailed instructions on QEMU configurations and options:
* {{Link|QEMU/Options|Usage options}} - Contains common configuration options used with QEMU (graphics/display, networking, RAM, storage, processor, etc).
* {{See also|QEMU/Linux guest}}
* {{See also|QEMU/Windows guest}}
* {{Link|QEMU/OS2WarpV3 guest|OS2WarpV3 guest}} - Describes the configuration steps needed to setup a virtualized OS2WarpVs=3 guest with QEMU.
=== Environment variables ===
* <var>G_MESSAGES_DEBUG</var>
* <var>LISTEN_FDS</var>
* <var>LISTEN_PID</var>
* <var>QEMU_AUDIO_DRV</var>
* <var>QEMU_MODULE_DIR</var>
* <var>XDG_RUNTIME_DIR</var>
=== Files ===
Files that QEMU uses.
==== Single File ====
* {{Path|/etc/libvirt/qemu.conf}} - QEMU configuration file.
* {{Path|/etc/libvirt/qemu-lockd.conf}} - QEMU lock files
* {{Path|/etc/libvirt/qemu-sanlock.conf}} - QEMU SAN lock
* {{Path|/etc/libvirt/qemu/<domain-name>.xml}} - Domain XML setting for a virtual machine or container.
* {{Path|/etc/libvirt/qemu/autostart/<domain-name>.xml}} - Autostart this domain (virtual machine or container).
* {{Path|/etc/libvirt/qemu/networks/<network-name>.xml}} - Network XML setting file for a network connection
* {{Path|/etc/libvirt/qemu/networks/autostart/<network-name>.xml}} - Autostart this network connection.
* {{Path|/var/lib/libvirt/qemu/channel/target/<domain-name>/<socket-file>}} - UNIX socket file for Libvertd daemon API
* {{Path|/var/cache/libvirt/qemu/capabilities/<hash-value>.xml}} - Host OS capabilities in XML format
* {{Path|/var/lib/libvirt/qemu/checkpoint/}}
* {{Path|/var/lib/libvirt/qemu/<domain-9-XXXX>/}} - holds UNIX sockets and AES keys for this domain.
* {{Path|/var/lib/libvirt/qemu/dump/}}
* {{Path|/var/lib/libvirt/qemu/nvram/}}
* {{Path|/var/lib/libvirt/qemu/ram/}}
* {{Path|/var/lib/libvirt/qemu/save/}} - holding directory of hibernation images
* {{Path|/var/lib/libvirt/qemu/snapshot/}} - holding directory of snapshots
* {{Path|/var/run/libvirt/qemu}} - various UNIX socket and PID files for the {{c|libvirtd}} daemon.
==== Image File ====
QEMU supports the following disk image formats:
* QEMU copy-on-write ({{c|.qcow2}}, {{c|.qed}}, {{c|.qcow}}, {{c|.cow}})
* VirtualBox Virtual Disk Image ({{c|.vdi}})
* CD/DVD (ISO-9660) images ({{c|.iso}})
* Raw images ({{c|.img}}), that guest OS can control
* VFAT-16
* VMware Virtual Machine Disk ({{c|.vmdk}})
* Virtual PC Virtual Hard Disk ({{c|.vhd}})
* Parallels disk image ({{c|.hdd}}, {{c|.hds}}) – '''Read-only'''
* Apple macos Universal Disk Image Format ({{c|.dmg}}) – '''Read-only'''
* Bochs – '''Read-only'''
* Linux cloop – '''Read-only'''
<translate>
=== Additional software ===
</translate>
<translate>
User name {{c|qemu}} is required, defined by {{package|acct-user/qemu}} and evoked by {{package|sys-emulator/qemu}} package.
</translate>
<translate>
Group name {{c|qemu}} is required, defined by {{package|acct-group/qemu}} and evoked by {{package|sys-emulator/qemu}} package.
</translate>
<translate>
To connect to the SPICE server of QEMU, a GUI client like {{package|net-misc/spice-gtk}} is required.
</translate>
<translate>
== Usage ==
</translate>
<translate>
QEMU can be used in two ways, with GUI front ends and through the command line. The configuration of QEMU depends on which method is employed:
* GUI (Front-End) - To make life easier, there are multiple user-friendly front ends to QEMU: See {{Link|QEMU/Front-ends|Front-ends}}
* CLI
</translate>
<translate>
=== Invocation ===
</translate>
<translate>
QEMU supports around 34 different CPU architectures. To find the desired architecture, list what is installed.
</translate>
{{Cmd|ls /usr/bin/qemu-system-*|collapse-output=true|output=<pre>
/usr/bin/qemu-system-aarch64 /usr/bin/qemu-system-mips /usr/bin/qemu-system-rx
/usr/bin/qemu-system-alpha /usr/bin/qemu-system-mips64 /usr/bin/qemu-system-s390x
/usr/bin/qemu-system-arm /usr/bin/qemu-system-mips64el /usr/bin/qemu-system-sh4
/usr/bin/qemu-system-avr /usr/bin/qemu-system-mipsel /usr/bin/qemu-system-sh4eb
/usr/bin/qemu-system-cris /usr/bin/qemu-system-nios2 /usr/bin/qemu-system-sparc
/usr/bin/qemu-system-hppa /usr/bin/qemu-system-or1k /usr/bin/qemu-system-sparc64
/usr/bin/qemu-system-i386 /usr/bin/qemu-system-ppc /usr/bin/qemu-system-tricore
/usr/bin/qemu-system-loongarch64 /usr/bin/qemu-system-ppc64 /usr/bin/qemu-system-x86_64
/usr/bin/qemu-system-m68k /usr/bin/qemu-system-ppc64le /usr/bin/qemu-system-x86_64-microvm
/usr/bin/qemu-system-microblaze /usr/bin/qemu-system-riscv32 /usr/bin/qemu-system-xtensa
/usr/bin/qemu-system-microblazeel /usr/bin/qemu-system-riscv64 /usr/bin/qemu-system-xtensaeb
</pre>}}
{{Invocation|qemu-system-x86_64 -help|collapse-output=true|output=<pre>
QEMU emulator version 7.2.9 (Debian 1:7.2+dfsg-7+deb12u5)
Copyright (c) 2003-2022 Fabrice Bellard and the QEMU Project developers
usage: qemu-system-x86_64 [options] [disk_image]
'disk_image' is a raw hard disk image for IDE hard disk 0
Standard options:
-h or -help display this help and exit
-version display version information and exit
-machine [type=]name[,prop[=value][,...]]
selects emulated machine ('-machine help' for list)
property accel=accel1[:accel2[:...]] selects accelerator
supported accelerators are kvm, xen, hax, hvf, nvmm, whpx or tcg (default: tcg)
vmport=on|off|auto controls emulation of vmport (default: auto)
dump-guest-core=on|off include guest memory in a core dump (default=on)
mem-merge=on|off controls memory merge support (default: on)
aes-key-wrap=on|off controls support for AES key wrapping (default=on)
dea-key-wrap=on|off controls support for DEA key wrapping (default=on)
suppress-vmdesc=on|off disables self-describing migration (default=off)
nvdimm=on|off controls NVDIMM support (default=off)
memory-encryption=@var{} memory encryption object to use (default=none)
hmat=on|off controls ACPI HMAT support (default=off)
memory-backend='backend-id' specifies explicitly provided backend for main RAM (default=none)
cxl-fmw.0.targets.0=firsttarget,cxl-fmw.0.targets.1=secondtarget,cxl-fmw.0.size=size[,cxl-fmw.0.interleave-granularity=granularity]
sgx-epc.0.memdev=memid,sgx-epc.0.node=numaid
-cpu cpu select CPU ('-cpu help' for list)
-accel [accel=]accelerator[,prop[=value][,...]]
select accelerator (kvm, xen, hax, hvf, nvmm, whpx or tcg; use 'help' for a list)
igd-passthru=on|off (enable Xen integrated Intel graphics passthrough, default=off)
kernel-irqchip=on|off|split controls accelerated irqchip support (default=on)
kvm-shadow-mem=size of KVM shadow MMU in bytes
split-wx=on|off (enable TCG split w^x mapping)
tb-size=n (TCG translation block cache size)
dirty-ring-size=n (KVM dirty ring GFN count, default 0)
notify-vmexit=run|internal-error|disable,notify-window=n (enable notify VM exit and set notify window, x86 only)
thread=single|multi (enable multi-threaded TCG)
-smp [[cpus=]n][,maxcpus=maxcpus][,sockets=sockets][,dies=dies][,clusters=clusters][,cores=cores][,threads=threads]
set the number of initial CPUs to 'n' [default=1]
maxcpus= maximum number of total CPUs, including
offline CPUs for hotplug, etc
sockets= number of sockets on the machine board
dies= number of dies in one socket
clusters= number of clusters in one die
cores= number of cores in one cluster
threads= number of threads in one core
Note: Different machines may have different subsets of the CPU topology
parameters supported, so the actual meaning of the supported parameters
will vary accordingly. For example, for a machine type that supports a
three-level CPU hierarchy of sockets/cores/threads, the parameters will
sequentially mean as below:
sockets means the number of sockets on the machine board
cores means the number of cores in one socket
threads means the number of threads in one core
For a particular machine type board, an expected CPU topology hierarchy
can be defined through the supported sub-option. Unsupported parameters
can also be provided in addition to the sub-option, but their values
must be set as 1 in the purpose of correct parsing.
-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=node]
-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=node]
-numa dist,src=source,dst=destination,val=distance
-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]
-numa hmat-lb,initiator=node,target=node,hierarchy=memory|first-level|second-level|third-level,data-type=access-latency|read-latency|write-latency[,latency=lat][,bandwidth=bw]
-numa hmat-cache,node-id=node,size=size,level=level[,associativity=none|direct|complex][,policy=none|write-back|write-through][,line=size]
-add-fd fd=fd,set=set[,opaque=opaque]
Add 'fd' to fd 'set'
-set group.id.arg=value
set <arg> parameter for item <id> of type <group>
i.e. -set drive.$id.file=/path/to/image
-global driver.property=value
-global driver=driver,property=property,value=value
set a global default for a driver property
-boot [order=drives][,once=drives][,menu=on|off]
[,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]
'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)
'sp_name': the file's name that would be passed to bios as logo picture, if menu=on
'sp_time': the period that splash picture last if menu=on, unit is ms
'rb_timeout': the timeout before guest reboot when boot failed, unit is ms
-m [size=]megs[,slots=n,maxmem=size]
configure guest RAM
size: initial amount of guest memory
slots: number of hotplug slots (default: none)
maxmem: maximum amount of guest memory (default: none)
NOTE: Some architectures might enforce a specific granularity
-mem-path FILE provide backing storage for guest RAM
-mem-prealloc preallocate guest memory (use with -mem-path)
-k language use keyboard layout (for example 'fr' for French)
-audio-help show -audiodev equivalent of the currently specified audio settings
-audio [driver=]driver,model=value[,prop[=value][,...]]
specifies the audio backend and device to use;
apart from 'model', options are the same as for -audiodev.
use '-audio model=help' to show possible devices.
-audiodev [driver=]driver,id=id[,prop[=value][,...]]
specifies the audio backend to use
Use ``-audiodev help`` to list the available drivers
id= identifier of the backend
timer-period= timer period in microseconds
in|out.mixing-engine= use mixing engine to mix streams inside QEMU
in|out.fixed-settings= use fixed settings for host audio
in|out.frequency= frequency to use with fixed settings
in|out.channels= number of channels to use with fixed settings
in|out.format= sample format to use with fixed settings
valid values: s8, s16, s32, u8, u16, u32, f32
in|out.voices= number of voices to use
in|out.buffer-length= length of buffer in microseconds
-audiodev none,id=id,[,prop[=value][,...]]
dummy driver that discards all output
-audiodev alsa,id=id[,prop[=value][,...]]
in|out.dev= name of the audio device to use
in|out.period-length= length of period in microseconds
in|out.try-poll= attempt to use poll mode
threshold= threshold (in microseconds) when playback starts
-audiodev oss,id=id[,prop[=value][,...]]
in|out.dev= path of the audio device to use
in|out.buffer-count= number of buffers
in|out.try-poll= attempt to use poll mode
try-mmap= try using memory mapped access
exclusive= open device in exclusive mode
dsp-policy= set timing policy (0..10), -1 to use fragment mode
-audiodev pa,id=id[,prop[=value][,...]]
server= PulseAudio server address
in|out.name= source/sink device name
in|out.latency= desired latency in microseconds
-audiodev sdl,id=id[,prop[=value][,...]]
in|out.buffer-count= number of buffers
-audiodev sndio,id=id[,prop[=value][,...]]
-audiodev spice,id=id[,prop[=value][,...]]
-audiodev dbus,id=id[,prop[=value][,...]]
-audiodev wav,id=id[,prop[=value][,...]]
path= path of wav file to record
-device driver[,prop[=value][,...]]
add device (based on driver)
prop=value,... sets driver properties
use '-device help' to print all possible drivers
use '-device driver,help' to print all possible properties
-name string1[,process=string2][,debug-threads=on|off]
set the name of the guest
string1 sets the window title and string2 the process name
When debug-threads is enabled, individual threads are given a separate name
NOTE: The thread names are for debugging and not a stable API.
-uuid %08x-%04x-%04x-%04x-%012x
specify machine UUID
Block device options:
-fda/-fdb file use 'file' as floppy disk 0/1 image
-hda/-hdb file use 'file' as hard disk 0/1 image
-hdc/-hdd file use 'file' as hard disk 2/3 image
-cdrom file use 'file' as CD-ROM image
-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]
[,cache.direct=on|off][,cache.no-flush=on|off]
[,read-only=on|off][,auto-read-only=on|off]
[,force-share=on|off][,detect-zeroes=on|off|unmap]
[,driver specific parameters...]
configure a block backend
-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]
[,cache=writethrough|writeback|none|directsync|unsafe][,format=f]
[,snapshot=on|off][,rerror=ignore|stop|report]
[,werror=ignore|stop|report|enospc][,id=name]
[,aio=threads|native|io_uring]
[,readonly=on|off][,copy-on-read=on|off]
[,discard=ignore|unmap][,detect-zeroes=on|off|unmap]
[[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]
[[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]
[[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]
[[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]
[[,iops_size=is]]
[[,group=g]]
use 'file' as a drive image
-mtdblock file use 'file' as on-board Flash memory image
-sd file use 'file' as SecureDigital card image
-snapshot write to temporary files instead of disk image files
-fsdev local,id=id,path=path,security_model=mapped-xattr|mapped-file|passthrough|none
[,writeout=immediate][,readonly=on][,fmode=fmode][,dmode=dmode]
[[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]
[[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]
[[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]
[[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]
[[,throttling.iops-size=is]]
-fsdev proxy,id=id,socket=socket[,writeout=immediate][,readonly=on]
-fsdev proxy,id=id,sock_fd=sock_fd[,writeout=immediate][,readonly=on]
-fsdev synth,id=id
-virtfs local,path=path,mount_tag=tag,security_model=mapped-xattr|mapped-file|passthrough|none
[,id=id][,writeout=immediate][,readonly=on][,fmode=fmode][,dmode=dmode][,multidevs=remap|forbid|warn]
-virtfs proxy,mount_tag=tag,socket=socket[,id=id][,writeout=immediate][,readonly=on]
-virtfs proxy,mount_tag=tag,sock_fd=sock_fd[,id=id][,writeout=immediate][,readonly=on]
-virtfs synth,mount_tag=tag[,id=id][,readonly=on]
-iscsi [user=user][,password=password]
[,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE
[,initiator-name=initiator-iqn][,id=target-iqn]
[,timeout=timeout]
iSCSI session parameters
USB convenience options:
-usb enable on-board USB host controller (if not enabled by default)
-usbdevice name add the host or guest USB device 'name'
Display options:
-display spice-app[,gl=on|off]
-display sdl[,gl=on|core|es|off][,grab-mod=<mod>][,show-cursor=on|off]
[,window-close=on|off]
-display gtk[,full-screen=on|off][,gl=on|off][,grab-on-hover=on|off]
[,show-tabs=on|off][,show-cursor=on|off][,window-close=on|off]
[,show-menubar=on|off]
-display vnc=<display>[,<optargs>]
-display curses[,charset=<encoding>]
-display egl-headless[,rendernode=<file>]
-display dbus[,addr=<dbusaddr>]
[,gl=on|core|es|off][,rendernode=<file>]
-display none
select display backend type
The default display is equivalent to
"-display gtk"
-nographic disable graphical output and redirect serial I/Os to console
-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]
[,x509-key-file=<file>][,x509-key-password=<file>]
[,x509-cert-file=<file>][,x509-cacert-file=<file>]
[,x509-dh-key-file=<file>][,addr=addr]
[,ipv4=on|off][,ipv6=on|off][,unix=on|off]
[,tls-ciphers=<list>]
[,tls-channel=[main|display|cursor|inputs|record|playback]]
[,plaintext-channel=[main|display|cursor|inputs|record|playback]]
[,sasl=on|off][,disable-ticketing=on|off]
[,password=<string>][,password-secret=<secret-id>]
[,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]
[,jpeg-wan-compression=[auto|never|always]]
[,zlib-glz-wan-compression=[auto|never|always]]
[,streaming-video=[off|all|filter]][,disable-copy-paste=on|off]
[,disable-agent-file-xfer=on|off][,agent-mouse=[on|off]]
[,playback-compression=[on|off]][,seamless-migration=[on|off]]
[,gl=[on|off]][,rendernode=<file>]
enable spice
at least one of {port, tls-port} is mandatory
-portrait rotate graphical output 90 deg left (only PXA LCD)
-rotate <deg> rotate graphical output some deg left (only PXA LCD)
-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]
select video card type
-full-screen start in full screen
-vnc <display> shorthand for -display vnc=<display>
i386 target only:
-win2k-hack use it when installing Windows 2000 to avoid a disk full bug
-no-fd-bootchk disable boot signature checking for floppy disks
-no-acpi disable ACPI
-no-hpet disable HPET
-acpitable [sig=str][,rev=n][,oem_id=str][,oem_table_id=str][,oem_rev=n][,asl_compiler_id=str][,asl_compiler_rev=n][,{data|file}=file1[:file2]...]
ACPI table description
-smbios file=binary
load SMBIOS entry from binary file
-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]
[,uefi=on|off]
specify SMBIOS type 0 fields
-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]
[,uuid=uuid][,sku=str][,family=str]
specify SMBIOS type 1 fields
-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]
[,asset=str][,location=str]
specify SMBIOS type 2 fields
-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]
[,sku=str]
specify SMBIOS type 3 fields
-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]
[,asset=str][,part=str][,max-speed=%d][,current-speed=%d]
[,processor-id=%d]
specify SMBIOS type 4 fields
-smbios type=8[,external_reference=str][,internal_reference=str][,connector_type=%d][,port_type=%d]
specify SMBIOS type 8 fields
-smbios type=11[,value=str][,path=filename]
specify SMBIOS type 11 fields
-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]
[,asset=str][,part=str][,speed=%d]
specify SMBIOS type 17 fields
-smbios type=41[,designation=str][,kind=str][,instance=%d][,pcidev=str]
specify SMBIOS type 41 fields
Network options:
-netdev user,id=str[,ipv4=on|off][,net=addr[/mask]][,host=addr]
[,ipv6=on|off][,ipv6-net=addr[/int]][,ipv6-host=addr]
[,restrict=on|off][,hostname=host][,dhcpstart=addr]
[,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,domainname=domain]
[,tftp=dir][,tftp-server-name=name][,bootfile=f][,hostfwd=rule][,guestfwd=rule][,smb=dir[,smbserver=addr]]
configure a user mode network backend with ID 'str',
its DHCP server and optional services
-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]
[,br=bridge][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]
[,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]
[,poll-us=n]
configure a host TAP network backend with ID 'str'
connected to a bridge (default=br0)
use network scripts 'file' (default=/etc/qemu-ifup)
to configure it and 'dfile' (default=/etc/qemu-ifdown)
to deconfigure it
use '[down]script=no' to disable script execution
use network helper 'helper' (default=/usr/lib/qemu/qemu-bridge-helper) to
configure it
use 'fd=h' to connect to an already opened TAP interface
use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces
use 'sndbuf=nbytes' to limit the size of the send buffer (the
default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')
use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag
use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition
use vhost=on to enable experimental in kernel accelerator
(only has effect for virtio guests which use MSIX)
use vhostforce=on to force vhost on for non-MSIX virtio guests
use 'vhostfd=h' to connect to an already opened vhost net device
use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices
use 'queues=n' to specify the number of queues to be created for multiqueue TAP
use 'poll-us=n' to specify the maximum number of microseconds that could be
spent on busy polling for vhost net
-netdev bridge,id=str[,br=bridge][,helper=helper]
configure a host TAP network backend with ID 'str' that is
connected to a bridge (default=br0)
using the program 'helper (default=/usr/lib/qemu/qemu-bridge-helper)
-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]
[,rxsession=rxsession],txsession=txsession[,ipv6=on|off][,udp=on|off]
[,cookie64=on|off][,counter][,pincounter][,txcookie=txcookie]
[,rxcookie=rxcookie][,offset=offset]
configure a network backend with ID 'str' connected to
an Ethernet over L2TPv3 pseudowire.
Linux kernel 3.3+ as well as most routers can talk
L2TPv3. This transport allows connecting a VM to a VM,
VM to a router and even VM to Host. It is a nearly-universal
standard (RFC3931). Note - this implementation uses static
pre-configured tunnels (same as the Linux kernel).
use 'src=' to specify source address
use 'dst=' to specify destination address
use 'udp=on' to specify udp encapsulation
use 'srcport=' to specify source udp port
use 'dstport=' to specify destination udp port
use 'ipv6=on' to force v6
L2TPv3 uses cookies to prevent misconfiguration as
well as a weak security measure
use 'rxcookie=0x012345678' to specify a rxcookie
use 'txcookie=0x012345678' to specify a txcookie
use 'cookie64=on' to set cookie size to 64 bit, otherwise 32
use 'counter=off' to force a 'cut-down' L2TPv3 with no counter
use 'pincounter=on' to work around broken counter handling in peer
use 'offset=X' to add an extra offset between header and data
-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]
configure a network backend to connect to another network
using a socket connection
-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]
configure a network backend to connect to a multicast maddr and port
use 'localaddr=addr' to specify the host address to send packets from
-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]
configure a network backend to connect to another network
using an UDP tunnel
-netdev stream,id=str[,server=on|off],addr.type=inet,addr.host=host,addr.port=port[,to=maxport][,numeric=on|off][,keep-alive=on|off][,mptcp=on|off][,addr.ipv4=on|off][,addr.ipv6=on|off]
-netdev stream,id=str[,server=on|off],addr.type=unix,addr.path=path[,abstract=on|off][,tight=on|off]
-netdev stream,id=str[,server=on|off],addr.type=fd,addr.str=file-descriptor
configure a network backend to connect to another network
using a socket connection in stream mode.
-netdev dgram,id=str,remote.type=inet,remote.host=maddr,remote.port=port[,local.type=inet,local.host=addr]
-netdev dgram,id=str,remote.type=inet,remote.host=maddr,remote.port=port[,local.type=fd,local.str=file-descriptor]
configure a network backend to connect to a multicast maddr and port
use ``local.host=addr`` to specify the host address to send packets from
-netdev dgram,id=str,local.type=inet,local.host=addr,local.port=port[,remote.type=inet,remote.host=addr,remote.port=port]
-netdev dgram,id=str,local.type=unix,local.path=path[,remote.type=unix,remote.path=path]
-netdev dgram,id=str,local.type=fd,local.str=file-descriptor
configure a network backend to connect to another network
using an UDP tunnel
-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]
configure a network backend to connect to port 'n' of a vde switch
running on host and listening for incoming connections on 'socketpath'.
Use group 'groupname' and mode 'octalmode' to change default
ownership and permissions for communication port.
-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]
configure a vhost-user network, backed by a chardev 'dev'
-netdev vhost-vdpa,id=str[,vhostdev=/path/to/dev][,vhostfd=h]
configure a vhost-vdpa network,Establish a vhost-vdpa netdev
use 'vhostdev=/path/to/dev' to open a vhost vdpa device
use 'vhostfd=h' to connect to an already opened vhost vdpa device
-netdev hubport,id=str,hubid=n[,netdev=nd]
configure a hub port on the hub with ID 'n'
-nic [tap|bridge|user|l2tpv3|vde|vhost-user|socket][,option][,...][mac=macaddr]
initialize an on-board / default host NIC (using MAC address
macaddr) and connect it to the given host network backend
-nic none use it alone to have zero network devices (the default is to
provided a 'user' network connection)
-net nic[,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]
configure or create an on-board (or machine default) NIC and
connect it to hub 0 (please use -nic unless you need a hub)
-net [user|tap|bridge|vde|socket][,option][,option][,...]
old way to initialize a host network interface
(use the -netdev option if possible instead)
Character device options:
-chardev help
-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4=on|off][,ipv6=on|off][,nodelay=on|off]
[,server=on|off][,wait=on|off][,telnet=on|off][,websocket=on|off][,reconnect=seconds][,mux=on|off]
[,logfile=PATH][,logappend=on|off][,tls-creds=ID][,tls-authz=ID] (tcp)
-chardev socket,id=id,path=path[,server=on|off][,wait=on|off][,telnet=on|off][,websocket=on|off][,reconnect=seconds]
[,mux=on|off][,logfile=PATH][,logappend=on|off][,abstract=on|off][,tight=on|off] (unix)
-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]
[,localport=localport][,ipv4=on|off][,ipv6=on|off][,mux=on|off]
[,logfile=PATH][,logappend=on|off]
-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]
[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]
-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]
-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]
-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]
TPM device options:
-tpmdev passthrough,id=id[,path=path][,cancel-path=path]
use path to provide path to a character device; default is /dev/tpm0
use cancel-path to provide path to TPM's cancel sysfs entry; if
not provided it will be searched for in /sys/class/misc/tpm?/device
-tpmdev emulator,id=id,chardev=dev
configure the TPM device using chardev backend
Boot Image or Kernel specific:
-bios file set the filename for the BIOS
-pflash file use 'file' as a parallel flash image
-kernel bzImage use 'bzImage' as kernel image
-append cmdline use 'cmdline' as kernel command line
-initrd file use 'file' as initial ram disk
-dtb file use 'file' as device tree image
Debug/Expert options:
-compat [deprecated-input=accept|reject|crash][,deprecated-output=accept|hide]
Policy for handling deprecated management interfaces
-compat [unstable-input=accept|reject|crash][,unstable-output=accept|hide]
Policy for handling unstable management interfaces
-fw_cfg [name=]<name>,file=<file>
add named fw_cfg entry with contents from file
-fw_cfg [name=]<name>,string=<str>
add named fw_cfg entry with contents from string
-serial dev redirect the serial port to char device 'dev'
-parallel dev redirect the parallel port to char device 'dev'
-monitor dev redirect the monitor to char device 'dev'
-qmp dev like -monitor but opens in 'control' mode
-qmp-pretty dev like -qmp but uses pretty JSON formatting
-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]
-debugcon dev redirect the debug console to char device 'dev'
-pidfile file write PID to 'file'
-singlestep always run in singlestep mode
--preconfig pause QEMU before machine is initialized (experimental)
-S freeze CPU at startup (use 'c' to start execution)
-overcommit [mem-lock=on|off][cpu-pm=on|off]
run qemu with overcommit hints
mem-lock=on|off controls memory lock support (default: off)
cpu-pm=on|off controls cpu power management (default: off)
-gdb dev accept gdb connection on 'dev'. (QEMU defaults to starting
the guest without waiting for gdb to connect; use -S too
if you want it to not start execution.)
-s shorthand for -gdb tcp::1234
-d item1,... enable logging of specified items (use '-d help' for a list of log items)
-D logfile output log to logfile (default stderr)
-dfilter range,.. filter debug output to range of addresses (useful for -d cpu,exec,etc..)
-seed number seed the pseudo-random number generator
-L path set the directory for the BIOS, VGA BIOS and keymaps
-enable-kvm enable KVM full virtualization support
-xen-domid id specify xen guest domain id
-xen-attach attach to existing xen domain
libxl will use this when starting QEMU
-xen-domid-restrict restrict set of available xen operations
to specified domain id. (Does not affect
xenpv machine type).
-no-reboot exit instead of rebooting
-no-shutdown stop before shutdown
-action reboot=reset|shutdown
action when guest reboots [default=reset]
-action shutdown=poweroff|pause
action when guest shuts down [default=poweroff]
-action panic=pause|shutdown|exit-failure|none
action when guest panics [default=shutdown]
-action watchdog=reset|shutdown|poweroff|inject-nmi|pause|debug|none
action when watchdog fires [default=reset]
-loadvm [tag|id]
start right away with a saved state (loadvm in monitor)
-daemonize daemonize QEMU after initializing
-option-rom rom load a file, rom, into the option ROM space
-rtc [base=utc|localtime|<datetime>][,clock=host|rt|vm][,driftfix=none|slew]
set the RTC base and clock, enable drift fix for clock ticks (x86 only)
-icount [shift=N|auto][,align=on|off][,sleep=on|off][,rr=record|replay,rrfile=<filename>[,rrsnapshot=<snapshot>]]
enable virtual instruction counter with 2^N clock ticks per
instruction, enable aligning the host and virtual clocks
or disable real time cpu sleeping, and optionally enable
record-and-replay mode
-watchdog-action reset|shutdown|poweroff|inject-nmi|pause|debug|none
action when watchdog fires [default=reset]
-echr chr set terminal escape character instead of ctrl-a
-incoming tcp:[host]:port[,to=maxport][,ipv4=on|off][,ipv6=on|off]
-incoming rdma:host:port[,ipv4=on|off][,ipv6=on|off]
-incoming unix:socketpath
prepare for incoming migration, listen on
specified protocol and socket address
-incoming fd:fd
-incoming exec:cmdline
accept incoming migration on given file descriptor
or from given external command
-incoming defer
wait for the URI to be specified via migrate_incoming
-only-migratable allow only migratable devices
-nodefaults don't create default devices
-chroot dir chroot to dir just before starting the VM
-runas user change to user id user just before starting the VM
user can be numeric uid:gid instead
-sandbox on[,obsolete=allow|deny][,elevateprivileges=allow|deny|children]
[,spawn=allow|deny][,resourcecontrol=allow|deny]
Enable seccomp mode 2 system call filter (default 'off').
use 'obsolete' to allow obsolete system calls that are provided
by the kernel, but typically no longer used by modern
C library implementations.
use 'elevateprivileges' to allow or deny the QEMU process ability
to elevate privileges using set*uid|gid system calls.
The value 'children' will deny set*uid|gid system calls for
main QEMU process but will allow forks and execves to run unprivileged
use 'spawn' to avoid QEMU to spawn new threads or processes by
blocking *fork and execve
use 'resourcecontrol' to disable process affinity and schedular priority
-readconfig <file>
read config file
-no-user-config
do not load default user-provided config files at startup
-trace [[enable=]<pattern>][,events=<file>][,file=<file>]
specify tracing options
-plugin [file=]<file>[,<argname>=<argvalue>]
load a plugin
-async-teardown enable asynchronous teardown
-msg [timestamp[=on|off]][,guest-name=[on|off]]
control error message format
timestamp=on enables timestamps (default: off)
guest-name=on enables guest name prefix but only if
-name guest option is set (default: off)
-dump-vmstate <file>
Output vmstate information in JSON format to file.
Use the scripts/vmstate-static-checker.py file to
check for possible regressions in migration code
by comparing two such vmstate dumps.
-enable-sync-profile
enable synchronization profiling
Generic object creation:
-object TYPENAME[,PROP1=VALUE1,...]
create a new object of type TYPENAME setting properties
in the order they are specified. Note that the 'id'
property must be set. These objects are placed in the
'/objects' path.
During emulation, the following keys are useful:
ctrl-alt-f toggle full screen
ctrl-alt-n switch to virtual console 'n'
ctrl-alt toggle mouse and keyboard grab
When using -nographic, press 'ctrl-a h' to get some help.
See <https://qemu.org/contribute/report-a-bug> for how to report bugs.
More information on the QEMU project at <https://qemu.org>.
</pre>}}
<translate>
=== Permissions ===
</translate>
<translate>
In order to run a KVM-accelerated virtual machine without logging in as root, add normal users to the {{c|kvm}} group. Replace <code><username></code> in the example command below with the appropriate user(s):
</translate>
{{RootCmd|gpasswd -a larry kvm}}
<translate>
=== Creation of a disk image ===
</translate>
<translate>
To create a {{c|raw disk image}} with {{c|4 GiB}} size:
</translate>
{{Cmd|qemu-img create -f raw "/home/larry/qemu/my-systems-disk-image.img" 4G|collapse-output=false|output=<pre>
Formatting 'my-systems-disk-image.img', fmt=raw size=4294967296
</pre>}}
{{Cmd|ls -lh|collapse-output=false|output=<pre>
total 4
-rw-r--r-- 1 larry larry 4.0G Apr 12 11:23 my-systems-disk-image.img
</pre>}}
<translate>
To create a {{c|raw disk image}} with {{c|copy-on-write disabled}}:
</translate>
{{Cmd|qemu-img create -f raw "/home/larry/qemu/my-systems-disk-image.img" -o nocow{{=}}on 4G|collapse-output=false|output=<pre>
Formatting 'my-systems-disk-image.img', fmt=raw size=4294967296 nocow=on
</pre>}}
{{Cmd|ls -lh|collapse-output=false|output=<pre>
total 4
-rw-r--r-- 1 larry larry 4.0G Apr 12 11:23 my-systems-disk-image.img
</pre>}}
<translate>
The option {{c|nocow}} is also a file attribute, which can be determined via the command {{c|lsattr}}<ref>https://www.qemu.org/docs/master/system/qemu-block-drivers.html#cmdoption-qcow2-arg-nocow</ref>.
</translate>
<translate>
The following will create a {{c|qcow2 disk image}} (useful, if your filesystem does not support {{c|sparse files}}):
</translate>
{{Cmd|qemu-img create -f qcow2 "/home/larry/qemu/my-systems-disk-image.qcow2" 4G|collapse-output=false|output=<pre>
Formatting 'my-systems-disk-image.qcow2', fmt=qcow2 cluster_size=65536 extended_l2=off compression_type=zlib size=4294967296 lazy_refcounts=off refcount_bits=16
</pre>}}
{{Cmd|ls -l|collapse-output=false|output=<pre>
total 196K
-rw-r--r-- 1 larry larry 193K Apr 12 11:30 my-systems-disk-image.qcow2
</pre>}}
<translate>
=== Preparation of a bootable disk image from scratch ===
</translate>
<translate>
A system can be copied {{c|onto a disk image,}} when not using a cdrom installation medium.
By default, {{c|qemu}} uses a {{c|bios-firmware}} to boot the system.
The disk can be prepared with a {{c|msdos disk label}} and a {{c|gap}} between the {{c|end}} of the 512-byte-MBR (Master Boot Record) and the {{c|start}} of the first partition.
The gap is needed for boot loaders like {{c|grub}}, which place {{c|boot-code}} within this gap.
The following example uses the {{c|raw disk image}}, which was created {{Link|QEMU|section=#Creation_of_a_disk_image|above}}.
</translate>
<translate>
A raw disk image can be prepared by {{c|attaching}} it as a {{c|loop device}}:
</translate>
{{RootCmd|losetup --find --partscan --show "/home/larry/qemu/my-systems-disk-image.img"|collapse-output=false|output=<pre>
/dev/loop0
</pre>}}
<translate>
* The parameter <code>--find</code> finds the first unused {{c|loop device}}.
* The parameter <code>--partscan</code> forces the {{c|Kernel}} to scan the {{c|partition table}} on the {{c|newly created loop device}}, where the '''default sector size of 512 bytes''' is assumed.
* The parameter <code>--show</code> displays the name of the {{c|assigned loop device}}, if the parameter <code>--find</code> is used.
</translate>
<translate>
Attached {{c|loop devices}} can be listed with the follwing command:
</translate>
{{RootCmd|losetup --list|collapse-output=false|output=<pre>
NAME SIZELIMIT OFFSET AUTOCLEAR RO BACK-FILE DIO LOG-SEC
/dev/loop0 0 0 0 0 /home/larry/qemu/my-systems-disk-image.img 0 512
</pre>}}
<translate>
Then, the {{c|loop device}} can be {{c|formatted}} like a normal disk.
Print the {{c|partition table}}:
</translate>
{{RootCmd|parted "/dev/loop0" "unit mib print"|collapse-output=true|output=<pre>
Error: /dev/loop0: unrecognised disk label
Model: Loopback device (loopback)
Disk /dev/loop0: 4096MiB
Sector size (logical/physical): 512B/512B
Partition Table: unknown
Disk Flags:
</pre>}}
<translate>
Create a new {{c|partition table (msdos disk label)}}:
{{Warning|Make absolutely sure to select the correct {{c|loop device}}, since this may '''overwrite an existing partition table'''; resulting in '''data loss''', if the '''overwritten partition table''' cannot be recovered.}}
</translate>
{{RootCmd|parted "/dev/loop0" "mklabel msdos"|collapse-output=false|output=<pre>
Information: You may need to update /etc/fstab.
</pre>}}
The returned information can be ignored, since an entry in the configuration file {{Path|/etc/fstab}} is not needed.
{{c|parted}} now indicates, that the {{c|Partition Table}} is {{c|msdos}}:
{{RootCmd|parted "/dev/loop0" "unit mib print"|collapse-output=true|output=<pre>
Model: Loopback device (loopback)
Disk /dev/loop0: 4096MiB
Sector size (logical/physical): 512B/512B
Partition Table: msdos
Disk Flags:
Number Start End Size Type File system Flags
</pre>}}
<translate>
Create an {{c|ext4 partition}} with an {{c|offset}} of {{c|2 MiB}}:
</translate>
{{RootCmd|parted "/dev/loop0" "mkpart primary ext4 2MiB -1"}}
The parameter <code>-1</code> represents the {{c|last sector}} of the partition.
The {{c|first partition}} has been successfully created:
{{RootCmd|parted "/dev/loop0" "unit mib print"|collapse-output=true|output=<pre>
Model: Loopback device (loopback)
Disk /dev/loop0: 4096MiB
Sector size (logical/physical): 512B/512B
Partition Table: msdos
Disk Flags:
Number Start End Size Type File system Flags
1 2.00MiB 4095MiB 4093MiB primary
</pre>}}
This will also {{c|attach}} a new {{c|loop device}} at {{Path|/dev/loop0p1}}:
{{RootCmd|ls -l "/dev/loop0"*|collapse-output=false|output=<pre>
brw-rw---- 1 root disk 7, 0 Apr 12 12:33 /dev/loop0
brw-rw---- 1 root disk 259, 0 Apr 12 12:33 /dev/loop0p1
</pre>}}
<translate>
Set the {{c|boot flag}}:
</translate>
{{RootCmd|parted "/dev/loop0" set 1 boot on}}
All {{c|partition flags}} can be found in the column {{c|Flags}}:
{{RootCmd|parted "/dev/loop0" "unit mib print"|collapse-output=true|output=<pre>
Model: Loopback device (loopback)
Disk /dev/loop0: 4096MiB
Sector size (logical/physical): 512B/512B
Partition Table: msdos
Disk Flags:
Number Start End Size Type File system Flags
1 2.00MiB 4095MiB 4093MiB primary boot
</pre>}}
<translate>
Create the {{c|ext4 filesystem}}, which was declared via {{c|parted}} earlier:
{{Warning|Make absolutely sure to select the correct {{c|loop device}}, since this may '''overwrite an existing partition'''; resulting in '''data loss''', if the '''overwritten partition''' cannot be recovered.}}
</translate>
{{RootCmd|mkfs.ext4 "/dev/loop0p1"|collapse-output=true|output=<pre>
mke2fs 1.47.2 (1-Jan-2025)
Discarding device blocks: done
Creating filesystem with 1047808 4k blocks and 262144 inodes
Filesystem UUID: 0e344af7-6f7b-4d27-8238-89d46a5920d6
Superblock backups stored on blocks:
32768, 98304, 163840, 229376, 294912, 819200, 884736
Allocating group tables: done
Writing inode tables: done
Creating journal (16384 blocks): done
Writing superblocks and filesystem accounting information: done
</pre>}}
<translate>
Mount it at {{Path|/mnt/}}:
</translate>
{{RootCmd|mount "/dev/loop0p1" "/mnt/"}}
{{RootCmd|df --human-readable --print-type "/mnt/"|collapse-output=false|output=<pre>
Filesystem Type Size Used Avail Use% Mounted on
/dev/loop0p1 ext4 3.9G 24K 3.7G 1% /mnt
</pre>}}
<translate>
Create the directories {{Path|/mnt/boot/grub}}, which will be used by {{c|grub}} later:
</translate>
{{RootCmd|mkdir --parents --verbose "/mnt/boot/grub"|collapse-output=false|output=<pre>
mkdir: created directory '/mnt/boot'
mkdir: created directory '/mnt/boot/grub'
</pre>}}
<translate>
Install {{c|grub}} on the {{c|loop device}} and advice it to install its files to {{Path|/mnt/boot/grub/}}:
</translate>
{{RootCmd|grub-install --target{{=}}"i386-pc" --boot-directory{{=}}"/mnt/boot/" "/dev/loop0"}}
{{RootCmd|tree -F "/mnt/boot/grub/"|collapse-output=true|output=<pre>
/mnt/boot/grub/
├── fonts/
│ └── unicode.pf2
├── grubenv
├── i386-pc/
│ ├── acpi.mod
│ ├── adler32.mod
│ ├── affs.mod
│ ├── afs.mod
│ ├── afsplitter.mod
│ ├── ahci.mod
│ ├── all_video.mod
│ ├── aout.mod
│ ├── archelp.mod
│ ├── ata.mod
[...]
</pre>}}
<translate>
{{c|Unmount}} the filesystem and {{c|detach}} the {{c|loop device}}:
</translate>
{{RootCmd|umount "/mnt/"}}
{{RootCmd|losetup --detach "/dev/loop0"}}
<translate>
If the {{c|loop device}} is still {{c|busy}} - for example, processes are still accessing {{Path|/mnt/}} - no error will be returned. This can be {{c|verified}} and {{c|solved}} with the following commands:
</translate>
{{RootCmd|losetup --list|collapse-output=false|output=<pre>
NAME SIZELIMIT OFFSET AUTOCLEAR RO BACK-FILE DIO LOG-SEC
/dev/loop0 0 0 0 0 /home/larry/qemu/my-systems-disk-image.img 0 512
</pre>}}
{{RootCmd|lsof {{!}} grep "/mnt"|collapse-output=false|output=<pre>
sleep 31813 root cwd DIR 259,0 4096 131074 /mnt/boot/grub
</pre>}}
{{RootCmd|kill -SIGTERM 31813}}
<translate>
This is sufficient to boot into a {{c|grub2 boot prompt}}. This is can be used as the {{c|basis for a bootable system}}.
</translate>
<translate>
=== CPU selection ===
</translate>
<translate>
QEMU CPU selections have additional support for "[[QEMU/Front-ends|accelerators]]," like '''kvm''' (Kernel Virtual Machine) or '''tcg''' (Tiny Code Generator) or '''Xen''' (wikip[https://de.wikipedia.org/wiki/Xen]).
</translate>
<translate>
The accelerator can usually only "accelerate" the features that are available on the host CPU.
So the selection of the CPU affects the performance.
</translate>
<translate>
To get a list of CPUs:
</translate>
{{Cmd|qemu-system-x86_64 -cpu help|collapse-output=true|output=<pre>
Available CPUs:
x86 486 (alias configured by machine type)
x86 486-v1
x86 Broadwell (alias configured by machine type)
x86 Broadwell-IBRS (alias of Broadwell-v3)
x86 Broadwell-noTSX (alias of Broadwell-v2)
x86 Broadwell-noTSX-IBRS (alias of Broadwell-v4)
x86 Broadwell-v1 Intel Core Processor (Broadwell)
x86 Broadwell-v2 Intel Core Processor (Broadwell, no TSX)
x86 Broadwell-v3 Intel Core Processor (Broadwell, IBRS)
x86 Broadwell-v4 Intel Core Processor (Broadwell, no TSX, IBRS)
x86 Cascadelake-Server (alias configured by machine type)
x86 Cascadelake-Server-noTSX (alias of Cascadelake-Server-v3)
x86 Cascadelake-Server-v1 Intel Xeon Processor (Cascadelake)
x86 Cascadelake-Server-v2 Intel Xeon Processor (Cascadelake) [ARCH_CAPABILITIES]
x86 Cascadelake-Server-v3 Intel Xeon Processor (Cascadelake) [ARCH_CAPABILITIES, no TSX]
x86 Cascadelake-Server-v4 Intel Xeon Processor (Cascadelake) [ARCH_CAPABILITIES, no TSX]
x86 Cascadelake-Server-v5 Intel Xeon Processor (Cascadelake) [ARCH_CAPABILITIES, EPT switching, XSAVES, no TSX]
x86 Conroe (alias configured by machine type)
x86 Conroe-v1 Intel Celeron_4x0 (Conroe/Merom Class Core 2)
x86 Cooperlake (alias configured by machine type)
x86 Cooperlake-v1 Intel Xeon Processor (Cooperlake)
x86 Cooperlake-v2 Intel Xeon Processor (Cooperlake) [XSAVES]
x86 Denverton (alias configured by machine type)
x86 Denverton-v1 Intel Atom Processor (Denverton)
x86 Denverton-v2 Intel Atom Processor (Denverton) [no MPX, no MONITOR]
x86 Denverton-v3 Intel Atom Processor (Denverton) [XSAVES, no MPX, no MONITOR]
x86 Dhyana (alias configured by machine type)
x86 Dhyana-v1 Hygon Dhyana Processor
x86 Dhyana-v2 Hygon Dhyana Processor [XSAVES]
x86 EPYC (alias configured by machine type)
x86 EPYC-IBPB (alias of EPYC-v2)
x86 EPYC-Milan (alias configured by machine type)
x86 EPYC-Milan-v1 AMD EPYC-Milan Processor
x86 EPYC-Rome (alias configured by machine type)
x86 EPYC-Rome-v1 AMD EPYC-Rome Processor
x86 EPYC-Rome-v2 AMD EPYC-Rome Processor
x86 EPYC-v1 AMD EPYC Processor
x86 EPYC-v2 AMD EPYC Processor (with IBPB)
x86 EPYC-v3 AMD EPYC Processor
x86 Haswell (alias configured by machine type)
x86 Haswell-IBRS (alias of Haswell-v3)
x86 Haswell-noTSX (alias of Haswell-v2)
x86 Haswell-noTSX-IBRS (alias of Haswell-v4)
x86 Haswell-v1 Intel Core Processor (Haswell)
x86 Haswell-v2 Intel Core Processor (Haswell, no TSX)
x86 Haswell-v3 Intel Core Processor (Haswell, IBRS)
x86 Haswell-v4 Intel Core Processor (Haswell, no TSX, IBRS)
x86 Icelake-Server (alias configured by machine type)
x86 Icelake-Server-noTSX (alias of Icelake-Server-v2)
x86 Icelake-Server-v1 Intel Xeon Processor (Icelake)
x86 Icelake-Server-v2 Intel Xeon Processor (Icelake) [no TSX]
x86 Icelake-Server-v3 Intel Xeon Processor (Icelake)
x86 Icelake-Server-v4 Intel Xeon Processor (Icelake)
x86 Icelake-Server-v5 Intel Xeon Processor (Icelake) [XSAVES]
x86 Icelake-Server-v6 Intel Xeon Processor (Icelake) [5-level EPT]
x86 IvyBridge (alias configured by machine type)
x86 IvyBridge-IBRS (alias of IvyBridge-v2)
x86 IvyBridge-v1 Intel Xeon E3-12xx v2 (Ivy Bridge)
x86 IvyBridge-v2 Intel Xeon E3-12xx v2 (Ivy Bridge, IBRS)
x86 KnightsMill (alias configured by machine type)
x86 KnightsMill-v1 Intel Xeon Phi Processor (Knights Mill)
x86 Nehalem (alias configured by machine type)
x86 Nehalem-IBRS (alias of Nehalem-v2)
x86 Nehalem-v1 Intel Core i7 9xx (Nehalem Class Core i7)
x86 Nehalem-v2 Intel Core i7 9xx (Nehalem Core i7, IBRS update)
x86 Opteron_G1 (alias configured by machine type)
x86 Opteron_G1-v1 AMD Opteron 240 (Gen 1 Class Opteron)
x86 Opteron_G2 (alias configured by machine type)
x86 Opteron_G2-v1 AMD Opteron 22xx (Gen 2 Class Opteron)
x86 Opteron_G3 (alias configured by machine type)
x86 Opteron_G3-v1 AMD Opteron 23xx (Gen 3 Class Opteron)
x86 Opteron_G4 (alias configured by machine type)
x86 Opteron_G4-v1 AMD Opteron 62xx class CPU
x86 Opteron_G5 (alias configured by machine type)
x86 Opteron_G5-v1 AMD Opteron 63xx class CPU
x86 Penryn (alias configured by machine type)
x86 Penryn-v1 Intel Core 2 Duo P9xxx (Penryn Class Core 2)
x86 SandyBridge (alias configured by machine type)
x86 SandyBridge-IBRS (alias of SandyBridge-v2)
x86 SandyBridge-v1 Intel Xeon E312xx (Sandy Bridge)
x86 SandyBridge-v2 Intel Xeon E312xx (Sandy Bridge, IBRS update)
x86 Skylake-Client (alias configured by machine type)
x86 Skylake-Client-IBRS (alias of Skylake-Client-v2)
x86 Skylake-Client-noTSX-IBRS (alias of Skylake-Client-v3)
x86 Skylake-Client-v1 Intel Core Processor (Skylake)
x86 Skylake-Client-v2 Intel Core Processor (Skylake, IBRS)
x86 Skylake-Client-v3 Intel Core Processor (Skylake, IBRS, no TSX)
x86 Skylake-Client-v4 Intel Core Processor (Skylake, IBRS, no TSX) [IBRS, XSAVES, no TSX]
x86 Skylake-Server (alias configured by machine type)
x86 Skylake-Server-IBRS (alias of Skylake-Server-v2)
x86 Skylake-Server-noTSX-IBRS (alias of Skylake-Server-v3)
x86 Skylake-Server-v1 Intel Xeon Processor (Skylake)
x86 Skylake-Server-v2 Intel Xeon Processor (Skylake, IBRS)
x86 Skylake-Server-v3 Intel Xeon Processor (Skylake, IBRS, no TSX)
x86 Skylake-Server-v4 Intel Xeon Processor (Skylake, IBRS, no TSX)
x86 Skylake-Server-v5 Intel Xeon Processor (Skylake, IBRS, no TSX) [IBRS, XSAVES, EPT switching, no TSX]
x86 Snowridge (alias configured by machine type)
x86 Snowridge-v1 Intel Atom Processor (SnowRidge)
x86 Snowridge-v2 Intel Atom Processor (Snowridge, no MPX)
x86 Snowridge-v3 Intel Atom Processor (Snowridge, no MPX) [XSAVES, no MPX]
x86 Snowridge-v4 Intel Atom Processor (Snowridge, no MPX) [no split lock detect, no core-capability]
x86 Westmere (alias configured by machine type)
x86 Westmere-IBRS (alias of Westmere-v2)
x86 Westmere-v1 Westmere E56xx/L56xx/X56xx (Nehalem-C)
x86 Westmere-v2 Westmere E56xx/L56xx/X56xx (IBRS update)
x86 athlon (alias configured by machine type)
x86 athlon-v1 QEMU Virtual CPU version 2.5+
x86 core2duo (alias configured by machine type)
x86 core2duo-v1 Intel(R) Core(TM)2 Duo CPU T7700 @ 2.40GHz
x86 coreduo (alias configured by machine type)
x86 coreduo-v1 Genuine Intel(R) CPU T2600 @ 2.16GHz
x86 kvm32 (alias configured by machine type)
x86 kvm32-v1 Common 32-bit KVM processor
x86 kvm64 (alias configured by machine type)
x86 kvm64-v1 Common KVM processor
x86 n270 (alias configured by machine type)
x86 n270-v1 Intel(R) Atom(TM) CPU N270 @ 1.60GHz
x86 pentium (alias configured by machine type)
x86 pentium-v1
x86 pentium2 (alias configured by machine type)
x86 pentium2-v1
x86 pentium3 (alias configured by machine type)
x86 pentium3-v1
x86 phenom (alias configured by machine type)
x86 phenom-v1 AMD Phenom(tm) 9550 Quad-Core Processor
x86 qemu32 (alias configured by machine type)
x86 qemu32-v1 QEMU Virtual CPU version 2.5+
x86 qemu64 (alias configured by machine type)
x86 qemu64-v1 QEMU Virtual CPU version 2.5+
x86 base base CPU model type with no features enabled
x86 host processor with all supported host features
x86 max Enables all features supported by the accelerator in the current host
Recognized CPUID flags:
3dnow 3dnowext 3dnowprefetch abm ace2 ace2-en acpi adx aes amd-no-ssb
amd-ssbd amd-stibp amx-bf16 amx-int8 amx-tile apic arat arch-capabilities
arch-lbr avic avx avx-vnni avx2 avx512-4fmaps avx512-4vnniw avx512-bf16
avx512-fp16 avx512-vp2intersect avx512-vpopcntdq avx512bitalg avx512bw
avx512cd avx512dq avx512er avx512f avx512ifma avx512pf avx512vbmi
avx512vbmi2 avx512vl avx512vnni bmi1 bmi2 bus-lock-detect cid cldemote
clflush clflushopt clwb clzero cmov cmp-legacy core-capability cr8legacy
cx16 cx8 dca de decodeassists ds ds-cpl dtes64 erms est extapic f16c
flushbyasid fma fma4 fpu fsgsbase fsrm full-width-write fxsr fxsr-opt
gfni hle ht hypervisor ia64 ibpb ibrs ibrs-all ibs intel-pt intel-pt-lip
invpcid invtsc kvm-asyncpf kvm-asyncpf-int kvm-hint-dedicated kvm-mmu
kvm-msi-ext-dest-id kvm-nopiodelay kvm-poll-control kvm-pv-eoi kvm-pv-ipi
kvm-pv-sched-yield kvm-pv-tlb-flush kvm-pv-unhalt kvm-steal-time kvmclock
kvmclock kvmclock-stable-bit la57 lahf-lm lbrv lm lwp mca mce md-clear
mds-no misalignsse mmx mmxext monitor movbe movdir64b movdiri mpx msr
mtrr nodeid-msr npt nrip-save nx osvw pae pat pause-filter pbe pcid
pclmulqdq pcommit pdcm pdpe1gb perfctr-core perfctr-nb pfthreshold pge
phe phe-en pks pku pmm pmm-en pn pni popcnt pschange-mc-no pse pse36
rdctl-no rdpid rdrand rdseed rdtscp rsba rtm sep serialize sgx sgx-debug
sgx-exinfo sgx-kss sgx-mode64 sgx-provisionkey sgx-tokenkey sgx1 sgx2
sgxlc sha-ni skinit skip-l1dfl-vmentry smap smep smx spec-ctrl
split-lock-detect ss ssb-no ssbd sse sse2 sse4.1 sse4.2 sse4a ssse3 stibp
svm svm-lock svme-addr-chk syscall taa-no tbm tce tm tm2 topoext tsc
tsc-adjust tsc-deadline tsc-scale tsx-ctrl tsx-ldtrk umip v-vmsave-vmload
vaes vgif virt-ssbd vmcb-clean vme vmx vmx-activity-hlt
vmx-activity-shutdown vmx-activity-wait-sipi vmx-apicv-register
vmx-apicv-vid vmx-apicv-x2apic vmx-apicv-xapic vmx-cr3-load-noexit
vmx-cr3-store-noexit vmx-cr8-load-exit vmx-cr8-store-exit vmx-desc-exit
vmx-encls-exit vmx-entry-ia32e-mode vmx-entry-load-bndcfgs
vmx-entry-load-efer vmx-entry-load-pat vmx-entry-load-perf-global-ctrl
vmx-entry-load-pkrs vmx-entry-load-rtit-ctl vmx-entry-noload-debugctl
vmx-ept vmx-ept-1gb vmx-ept-2mb vmx-ept-advanced-exitinfo
vmx-ept-execonly vmx-eptad vmx-eptp-switching vmx-exit-ack-intr
vmx-exit-clear-bndcfgs vmx-exit-clear-rtit-ctl vmx-exit-load-efer
vmx-exit-load-pat vmx-exit-load-perf-global-ctrl vmx-exit-load-pkrs
vmx-exit-nosave-debugctl vmx-exit-save-efer vmx-exit-save-pat
vmx-exit-save-preemption-timer vmx-flexpriority vmx-hlt-exit vmx-ins-outs
vmx-intr-exit vmx-invept vmx-invept-all-context vmx-invept-single-context
vmx-invept-single-context vmx-invept-single-context-noglobals
vmx-invlpg-exit vmx-invpcid-exit vmx-invvpid vmx-invvpid-all-context
vmx-invvpid-single-addr vmx-io-bitmap vmx-io-exit vmx-monitor-exit
vmx-movdr-exit vmx-msr-bitmap vmx-mtf vmx-mwait-exit vmx-nmi-exit
vmx-page-walk-4 vmx-page-walk-5 vmx-pause-exit vmx-ple vmx-pml
vmx-posted-intr vmx-preemption-timer vmx-rdpmc-exit vmx-rdrand-exit
vmx-rdseed-exit vmx-rdtsc-exit vmx-rdtscp-exit vmx-secondary-ctls
vmx-shadow-vmcs vmx-store-lma vmx-true-ctls vmx-tsc-offset
vmx-tsc-scaling vmx-unrestricted-guest vmx-vintr-pending vmx-vmfunc
vmx-vmwrite-vmexit-fields vmx-vnmi vmx-vnmi-pending vmx-vpid
vmx-wbinvd-exit vmx-xsaves vmx-zero-len-inject vpclmulqdq waitpkg
wbnoinvd wdt x2apic xcrypt xcrypt-en xfd xgetbv1 xop xsave xsavec
xsaveerptr xsaveopt xsaves xstore xstore-en xtpr
</pre>}}
<translate>
Show the available accelerators:
</translate>
{{Cmd|qemu-system-x86_64 -accel help|collapse-output=true|output=<pre>
Accelerators supported in QEMU binary:
tcg
kvm
hvf
whpx
haxm
</pre>}}
<translate>
=== Starting QEMU ===
</translate>
<translate>
This is how to start a virtual machine with the same feature set as the host CPU, a raw disk image and {{c|2 GB}} of RAM.
By default, a {{c|VNC server}} is started that runs '''without password protection''' and listens on the {{c|loop interface}}.
QEMU is advised to {{c|listen on a local UNIX socket}} with the following command:
</translate>
{{Cmd|qemu-system-x86_64 -vnc "unix:/run/user/$(id --user)/qemu-vnc.sock" -enable-kvm -cpu host -drive "file{{=}}/home/larry/qemu/my-systems-disk-image.img,format{{=}}raw" -m 2G}}
<translate>
{{Warning|'''Set the file permissions appropriately''' to protect the {{c|VNC server}} from unauthorized access! If the virtual machine is started with the parameter <code>-vnc :0</code>, it will listen on {{c|port 5900}} (first display) '''on all interfaces without password protection!'''}}
{{Note|A {{c|CD-ROM installation}} or {{c|boot medium}} can be added via the parameter <code>-cdrom</code>. For example: <code>-cdrom filename.iso</code>}}
</translate>
=== Connecting to the virtual machine via VNC ===
In order to connect to the {{c|VNC server}}, the command {{c|vncviewer}}, which comes from the package {{Package|net-misc/tigervnc}}, can be used:
{{Cmd|vncviewer "/run/user/$(id --user)/qemu-vnc.sock"|collapse-output=true|output=<pre>
TigerVNC viewer v1.15.0
Built on: 2025-05-13 12:30
Copyright (C) 1999-2025 TigerVNC team and many others (see README.rst)
See https://www.tigervnc.org for information on TigerVNC.
Tue May 13 14:44:36 2025
DecodeManager: Detected 4 CPU core(s)
DecodeManager: Creating 4 decoder thread(s)
CConn: Connected to socket /run/user/1000/qemu-vnc.sock
CConnection: Server supports RFB protocol version 3.8
CConnection: Using RFB protocol version 3.8
CConnection: Choosing security type None(1)
CConn: Using pixel format depth 24 (32bpp) little-endian rgb888
CConn: SetDesktopSize failed: 3
</pre>}}
This will open a separate window, where one gets greeted with a {{c|GRUB shell}}, which was installed via <code>grub-install</code> {{Link|QEMU|section=#Preparation_of_a_bootable_disk_image_from_scratch|earlier}}:
[[File:Qemu_minimal_vm_with_grub2.png|500px]]
<translate>
== Troubleshooting ==
</translate>
=== qemu-system-x86_64: CPU model 'host' requires KVM or HVF ===
When trying to start a virtual machine, using the parameter <code>-cpu host</code>, one may encounter the following error:
{{CodeBox|title=CPU model 'host' requires KVM or HVF|1=
qemu-system-x86_64: CPU model 'host' requires KVM or HVF
}}
In order to fix this, use the parameter <code>-enable-kvm</code>, which will enable {{c|KVM full virtualization support}}:
{{Cmd|qemu-system-x86_64 -cpu host -enable-kvm [...]}}
<translate>
=== "kvm: already loaded the other module" ===
</translate>
<translate>
Sometimes during the early boot splash, the error message "kvm: already loaded the other module" can be seen. This message indicates both the Intel and the AMD kernel virtual machine settings have been enabled in the kernel. To fix this, enable it as a module or disable either the Intel ''or'' AMD KVM option specific to the system's processor in the kernel configuration. For example, if the system has an Intel processor, enable the Intel KVM, and then make sure the AMD KVM is set as a module (M) or is disabled (N). The relevant options to enable or disable can be found in the kernel's {{Path|.config}} file via the <var>CONFIG_KVM_INTEL</var> and <var>CONFIG_KVM_AMD</var> variables or in the configuration section above.
</translate>
<translate>
=== Creating TUN/TAP device - No such file or directory ===
</translate>
<translate>
Sometimes this error can occur if TUN/TAP support cannot be found in the kernel. To solve this, try loading the driver:
</translate>
<translate>
{{RootCmd|modprobe tun}}
</translate>
<translate>
If that works, add this to a file in {{Path|/etc/modules-load.d/}} to load on startup:
</translate>
<translate>
{{FileBox|filename=/etc/modules-load.d/qemu-modules.conf|1=tun}}
</translate>
<translate>
=== Configuration does not support video model 'qxl' ===
</translate>
<translate>
This is usually the case if QEMU is not built with the <code>spice</code> USE flag. To resolve this issue, try to build QEMU {{Link|Handbook:AMD64/Working/USE#Declaring_USE_flags_for_individual_packages|with the correct USE flag}}.
</translate>
<translate>
First add <code>spice</code> to via a [[:/etc/portage/package.use|package.use]] file:
</translate>
<translate>
{{FileBox|filename=/etc/portage/package.use/qemu|1=
app-emulation/qemu spice
}}
</translate>
<translate>
Then rebuild the package:
</translate>
<translate>
{{Emerge|app-emulation/qemu}}
</translate>
<translate>
=== My qemu has kvm support on some guest architectures ===
</translate>
<translate>
KVM works only for the same architecture. An ARM64 host cannot handle x86_64 instructions.
</translate>
<translate>
=== Invalid context errors on SELinux systems ===
</translate>
<translate>
By default, Libvirt generates a random SELinux MCS label for the QEMU process when it is started. If the loaded SELinux policy does not support MCS categories, the resulting security context will be invalid:
</translate>
<translate>
{{CodeBox|title=SELinux error from virt-manager|1=
Error starting domain: unable to set socket security context 'system_u:system_r:svirt_t:s0:c123,c456': Invalid argument
}}
</translate>
<translate>
{{CodeBox|title=SELinux error from the kernel|1=
kernel: SELinux: Context system_u:object_r:svirt_image_t:s0:c123,c456 is not valid (left unmapped).
}}
</translate>
<translate>
The solution is either to switch to one of the policy types which supports MCS categories or manually set the virtual machine's security labels, without MCS categories:
</translate>
<translate>
{{CodeBox|title=Libvirt domain XML with manually specified seclabel fields|lang=xml|1=
<domain type="kvm">
<name>fedora</name>
...
<devices>
<disk type="file" device="disk">
<driver name="qemu" type="qcow2"/>
<<nowiki>source</nowiki> file="/var/lib/libvirt/images/fedora.qcow2">
<seclabel model='selinux' relabel='yes'>
<label>system_u:object_r:svirt_image_t</label>
</seclabel>
</<nowiki>source</nowiki>>
<target dev="vda" bus="virtio"/>
<address type="pci" domain="0x0000" bus="0x04" slot="0x00" function="0x0"/>
</disk>
...
<seclabel type='static' model='selinux' relabel='yes'>
<label>system_u:system_r:svirt_t</label>
</seclabel>
</domain>
}}
</translate>
<translate>
=== Static-user and LTO ===
GCC will use a huge amount of RAM when LTO is enabled on the system if any of the <var>ppc64</var> options are enabled while using the <code>static-user</code> flag; because of this, it is recommended to disable LTO while compiling in this configuration or use {{Link|LLVM/Clang|Clang}} {{Link|LLVM/Clang|if LTO is required.}} See {{Bug|883419}}
</translate>
<translate>
=== lto1: internal compiler error: original not compressed with zstd ===
</translate>
<translate>
This is caused by a mismatch of GCC used to compile zlib and glib to the one being used to compile qemu, this can be fixed by rebuilding both before compiling qemu again.
{{Emerge|sys-libs/zlib dev-libs/glib}}
</translate>
<translate>
=== Windows guests fail to provision, boot, or Blue Screen of Death (BSOD) on startup ===
</translate>
<translate>
For optimal performance, it is recommended that modern Windows guests be run under a kernel with <code>CONFIG_KVM_HYPERV</code> enabled. As an additional benefit, if this option is not enabled, on some hardware, VMs will fail to provision, to boot, or present with a BSOD.
The technical reasons for this are as follows: later versions of Windows, when running as virtual machines, sometimes attempt to access hardware registers (specifically, Model Specific Registers or MSRs) that are not actually defined for the emulated processor within the virtual environment. This is often due to how Windows interacts with hardware, a driver trying to be overly clever, or even bugs within the operating system itself. While these MSR accesses might be valid on physical processors, the virtualized environment presented by KVM may not support them.
KVM's default behavior is to attempt to emulate these MSR accesses, but when encountering an undefined register, it reports an "invalid instruction" error to the virtual Windows instance. This error is often fatal, resulting in a BSOD and halting the virtual machine.
{{Tip|<code>unhandled rdmsr</code> or <code>unhandled wrmsr</code> messages in the system logs of the host indicate attempts to access undefined MSRs. Failures may also be more obvious, like <code>failed to set MSR</code> and <code>Assertion `ret {{=}}{{=}} cpu->kvm_msr_buf->nmsrs' failed</code> from <code>qemu-system-*</code>.}}
An alternative is passing the option <code>kvm.ignore_msrs=1</code> on the kernel command line or as an option to the KVM module:
{{FileBox|filename=/etc/modprobe.d/kvm.conf|1=options kvm ignore_msrs=1}}
The <code>ignore_msrs</code> option instructs KVM to ignore any attempts by the virtual Windows machine to access these undefined MSRs. Instead of generating an error and causing a BSOD, KVM silently bypasses the problematic instruction. This allows Windows to continue running, albeit potentially with some minor performance implications or masked underlying issues.
{{Tip|While <code>ignore_msrs</code> can be a quick fix for BSODs related to MSR access (not all BSODs are!), it is likely that this can be addressed properly by enabling the appropriate kernel option, as documented above.<br/><br/>This option should only need to be set if there are still undefined MSRs (and if there ''are'' it's probably a bug that needs to be reported to the software vendor or KVM/QEMU upstream).}}
</translate>
<translate>
== Removal ==
</translate>
There may be image files left behind after the removal of the QEMU package.
<translate>
=== Unmerge ===
</translate>
{{Unmerge|app-emulation/qemu}}
<translate>
== See also ==
</translate>
<translate>
* {{See also|Comparison of virtual machines}}
* {{See also|Fast Virtio VM}}
* {{See also|GPU passthrough with virt-manager, QEMU, and KVM}}
* {{See also|QEMU with Open vSwitch network}}
* {{See also|Virtualization}}
* {{See also|QEMU/Front-ends}}
* {{See also|Libvirt|libvirt}}
* {{See also|Libvirt/QEMU_networking|libvirt/QEMU networking}}
* {{See also|Libvirt/QEMU_guest|libvirt/QEMU guest}}
* {{See also|Virt-manager|Virt-manager}}
* {{See also|Virt-manager/QEMU_guest|virt-manager/QEMU guest}}
* {{See also|QEMU/Linux guest|QEMU/Linux guest}}
* {{See also|QEMU/Bridge with Wifi Routing|QEMU/Bridge with Wifi Routing}}
* {{See also|Category:QEMU Guests}}
* {{See also|Remote_desktop}}
</translate>
<translate>
== External resources ==
</translate>
<translate>
* https://www.linux-kvm.org/page/KvmOnGentoo - The Gentoo article on the KVM wiki
* https://wiki.qemu.org/Main_Page - The Official QEMU wiki
</translate>
== {{Anchor|References}} References ==
{{reflist}}
<translate>
[[Category:GUI software]]
[[Category:Virtualization]]
[[Category:QEMU]]
[[Category:Command line tools]]
[[Category:Emulation]]
</translate>' |
Unified diff of changes made by edit (edit_diff) | '@@ -353,13 +353,13 @@
<translate>
-Additional ebuild configuration frobs are provided as the USE_EXPAND variables <var>QEMU_USER_TARGETS</var> and <var>QEMU_SOFTMMU_TARGETS</var>. See {{Package|app-emulation/qemu}} for a list of all the available targets (there are many; most are very obscure and may be ignored; leaving these variables at their default values will disable almost everything which is probably just fine for most users).
+Additional ebuild configuration are provided as the ''USE_EXPAND'' variables <var>QEMU_USER_TARGETS</var> and <var>QEMU_SOFTMMU_TARGETS</var>. See {{Package|app-emulation/qemu}} for a list of all the available targets (there are many; most are very obscure and may be ignored; leaving these variables at their default values ''will disable almost everything'', which is probably just fine for most users).
</translate>
<translate>
-For each target specified, a qemu executable will be built. A <code>softmmu</code> target is the standard qemu use-case of emulating an entire system (like VirtualBox or VMWare, but with optional support for emulating CPU hardware along with peripherals). <code>user</code> targets execute user-mode code only; the (somewhat shockingly ambitious) purpose of these targets is to "magically" allow importing user-space linux ELF binaries from a different architecture into the native system (like multilib, without the awkward need for a software stack or CPU capable of running it).
+For each target specified, a <code>qemu</code> executable will be built. A <code>softmmu</code> target is the standard qemu use-case of emulating an entire system (like {{c|VirtualBox}} or {{c|VMWare}}, but with optional support for emulating CPU hardware along with peripherals). <code>user</code> targets execute user-mode code only; the (somewhat ambitious) purpose of these targets, is to "magically" allow importing {{c|user namespace Linux ELF binaries}} from a different architecture into the native system (like {{c|multilib}}, without the need for a {{c|software stack}} or CPU capable of running it).
</translate>
<translate>
-In order to enable <var>QEMU_USER_TARGETS</var> and <var>QEMU_SOFTMMU_TARGETS</var> we can edit the variables globally in {{Path|/etc/portage/make.conf}}, i.e.:
+In order to enable <var>QEMU_USER_TARGETS</var> and <var>QEMU_SOFTMMU_TARGETS</var>, one can set the variables globally in {{Path|/etc/portage/make.conf}}:
</translate>
@@ -369,23 +369,24 @@
}}
+{{Warning|Setting the ''USE flags'' globally in {{Path|/etc/portage/make.conf}} is discouraged, because of possible ordering issues in {{c|Portage}}.<ref>https://wiki.gentoo.org/wiki//etc/portage/make.conf#USE_EXPAND</ref>}}
<translate>
-Or, the {{Path|/etc/portage/package.use}} file(s) can be modified. Two equivalent syntaxes are available: traditional USE flag syntax, i.e.:
+Files in the directory {{Path|/etc/portage/package.use}} can be added. There are two equivalent syntaxes available:
+
+One is the traditional ''USE flag'' syntax:
</translate>
-{{FileBox|filename=/etc/portage/package.use|1=
+{{FileBox|filename=/etc/portage/package.use/qemu|1=
app-emulation/qemu qemu_softmmu_targets_arm qemu_softmmu_targets_x86_64 qemu_softmmu_targets_sparc
app-emulation/qemu qemu_user_targets_x86_64
}}
-
<translate>
-Another alternative is to use the newer [[USE EXPAND|<var>USE_EXPAND</var>-specific syntax]]:
+And the other, preferred one, is the {{Link|/etc/portage/make.conf|section=#USE_EXPAND|<var>USE_EXPAND</var>}} syntax:
</translate>
-{{FileBox|filename=/etc/portage/package.use|1=
+{{FileBox|filename=/etc/portage/package.use/qemu|1=
app-emulation/qemu QEMU_SOFTMMU_TARGETS: arm x86_64 sparc QEMU_USER_TARGETS: x86_64
}}
-
<translate>
' |
Old page size (old_size) | 87757 |
Lines added in edit (added_lines) | [
0 => 'Additional ebuild configuration are provided as the ''USE_EXPAND'' variables <var>QEMU_USER_TARGETS</var> and <var>QEMU_SOFTMMU_TARGETS</var>. See {{Package|app-emulation/qemu}} for a list of all the available targets (there are many; most are very obscure and may be ignored; leaving these variables at their default values ''will disable almost everything'', which is probably just fine for most users).',
1 => 'For each target specified, a <code>qemu</code> executable will be built. A <code>softmmu</code> target is the standard qemu use-case of emulating an entire system (like {{c|VirtualBox}} or {{c|VMWare}}, but with optional support for emulating CPU hardware along with peripherals). <code>user</code> targets execute user-mode code only; the (somewhat ambitious) purpose of these targets, is to "magically" allow importing {{c|user namespace Linux ELF binaries}} from a different architecture into the native system (like {{c|multilib}}, without the need for a {{c|software stack}} or CPU capable of running it).',
2 => 'In order to enable <var>QEMU_USER_TARGETS</var> and <var>QEMU_SOFTMMU_TARGETS</var>, one can set the variables globally in {{Path|/etc/portage/make.conf}}:',
3 => '{{Warning|Setting the ''USE flags'' globally in {{Path|/etc/portage/make.conf}} is discouraged, because of possible ordering issues in {{c|Portage}}.<ref>https://wiki.gentoo.org/wiki//etc/portage/make.conf#USE_EXPAND</ref>}}',
4 => 'Files in the directory {{Path|/etc/portage/package.use}} can be added. There are two equivalent syntaxes available: ',
5 => '',
6 => 'One is the traditional ''USE flag'' syntax:',
7 => '{{FileBox|filename=/etc/portage/package.use/qemu|1=',
8 => 'And the other, preferred one, is the {{Link|/etc/portage/make.conf|section=#USE_EXPAND|<var>USE_EXPAND</var>}} syntax:',
9 => '{{FileBox|filename=/etc/portage/package.use/qemu|1='
] |
Lines removed in edit (removed_lines) | [
0 => 'Additional ebuild configuration frobs are provided as the USE_EXPAND variables <var>QEMU_USER_TARGETS</var> and <var>QEMU_SOFTMMU_TARGETS</var>. See {{Package|app-emulation/qemu}} for a list of all the available targets (there are many; most are very obscure and may be ignored; leaving these variables at their default values will disable almost everything which is probably just fine for most users).',
1 => 'For each target specified, a qemu executable will be built. A <code>softmmu</code> target is the standard qemu use-case of emulating an entire system (like VirtualBox or VMWare, but with optional support for emulating CPU hardware along with peripherals). <code>user</code> targets execute user-mode code only; the (somewhat shockingly ambitious) purpose of these targets is to "magically" allow importing user-space linux ELF binaries from a different architecture into the native system (like multilib, without the awkward need for a software stack or CPU capable of running it).',
2 => 'In order to enable <var>QEMU_USER_TARGETS</var> and <var>QEMU_SOFTMMU_TARGETS</var> we can edit the variables globally in {{Path|/etc/portage/make.conf}}, i.e.:',
3 => 'Or, the {{Path|/etc/portage/package.use}} file(s) can be modified. Two equivalent syntaxes are available: traditional USE flag syntax, i.e.:',
4 => '{{FileBox|filename=/etc/portage/package.use|1=',
5 => '',
6 => 'Another alternative is to use the newer [[USE EXPAND|<var>USE_EXPAND</var>-specific syntax]]:',
7 => '{{FileBox|filename=/etc/portage/package.use|1=',
8 => ''
] |
New page text, stripped of any markup (new_text) | '
Resources
Home
Official documentation
Wikipedia
Package information
GitLab
Official project wiki
Bugs (upstream)
Blog
Open Hub
QEMU (Quick EMUlator) is a generic, open-source hardware emulator and virtualization suite.
Contents
1 Introduction
2 Installation
2.1 BIOS and UEFI firmware
2.2 Kernel
2.2.1 Physical CPU processor support - Host
2.2.2 Processor Support
2.2.3 Handling kernel config at CLI
2.2.4 Networking
2.2.5 Intel VT-g (integrated graphics adapter virtualization)
2.3 USE flags
2.3.1 USE_EXPAND
2.4 Emerge
3 Configuration
3.1 Environment variables
3.2 Files
3.2.1 Single File
3.2.2 Image File
3.3 Additional software
4 Usage
4.1 Invocation
4.2 Permissions
4.3 Creation of a disk image
4.4 Preparation of a bootable disk image from scratch
4.5 CPU selection
4.6 Starting QEMU
4.7 Connecting to the virtual machine via VNC
5 Troubleshooting
5.1 qemu-system-x86_64: CPU model 'host' requires KVM or HVF
5.2 "kvm: already loaded the other module"
5.3 Creating TUN/TAP device - No such file or directory
5.4 Configuration does not support video model 'qxl'
5.5 My qemu has kvm support on some guest architectures
5.6 Invalid context errors on SELinux systems
5.7 Static-user and LTO
5.8 lto1: internal compiler error: original not compressed with zstd
5.9 Windows guests fail to provision, boot, or Blue Screen of Death (BSOD) on startup
6 Removal
6.1 Unmerge
7 See also
8 External resources
9 References
Introduction[edit]
QEMU is a hardware emulator and virtualization tool, which runs on a host OS platforms. Inside a virtual machine, QEMU can emulate multiple operating systems; it can also emulate embedded systems.
QEMU supports 32+ kinds of CPUs. It emulates nearly all the opcodes of these CPUs.
QEMU has several plugins: Accelerator is one of them. This plugin allows execution directly by the host CPU. When using an accelerator, QEMU executes CPU instructions the fastest.
QEMU is a Type-2 hypervisor, which runs within user namespace and performs virtual hardware emulation.
Firstly, QEMU is a type 2 hypervisor.
QEMU can be paired with KVM to run VMs at near-native speed. This is accomplished by using hardware extensions such as: Intel VT-x or AMD-V.
It can then emulate user-level processes, which allow applications, compiled for one architecture, to run on a different one.
There are multiple operating modes: user-mode emulation, system emulation, KVM hosting and Xen hosting.
QEMU can save and restore the state of virtual machines of all its running programs.
QEMU virtual machines can interface with many types of physical host hardware, such as, but not limited to, CD-ROM drives, USB devices, audio interfaces, hard disks and network cards.
Virtual disk image defaults to the qcow2 format. This format only uses as much host disk space as the guest OS grows to use. Using the snapshot method, the guest OS can revert back to its desired state in time.
It does not depend on graphical output methods on the host system, instead, making use of an integrated VNC server to access the screen of the guest OS.
QEMU on a host CPU can execute multiple virtual CPUs in parallel.
QEMU has support for several accelerator plug-ins:
Virtualizer
Accelerator
Virtualization type
Description
Gentoo package name
qemu
tcg
full[1]/software-emulation
QEMU's own Tiny Code Generator. This is the default. More frequently denoted as qemu and not qemu/tcg so often.
app-emulation/qemu
qemu
hvf[2]
paravirtualization[3]
Apple's Hypervisor framework based on Intel VT.
qemu
whpx[4]
hybrid
Microsoft's Windows Hypervisor Platform based on Intel VT or AMD-V.
qemu
kvm
paravirtualization[5]
Linux Type-2 Hypervisor. This is the common choice for hosts using amd64, arm64, or mips[6]. Supports Microsoft Windows.
app-emulation/qemu
qemu
haxm[7]
paravirtualization[8]
Intel VT, by Intel Corporation.
QEMU, if used in conjunction with an accelerator, becomes a Type-1 hypervisor, which runs in Kernel namespace. This allows a user namespace program access to the hardware virtualization features of various processors. Such an accelerator can be KVM (Kernel-based Virtual Machine) or Xen.
If no accelerator is used, QEMU will run entirely in user namespace, using its built-in binary translator TCG (Tiny Code Generator). Using QEMU without an accelerator is relatively inefficient and slow.
NoteThis article typically uses KVM as the accelerator of choice, due to its GPL licensing and availability. Without KVM, nearly all commands described here, will still work (unless KVM-specific).
The following sub-articles provide detailed instructions on QEMU configurations and options:
QEMU/Bridge with Wifi Routing
QEMU/KVM IPv6 Support — describes IPv6 support in QEMU/KVM.
QEMU/Linux guest — describes the setup of a Gentoo Linux guest in QEMU using Gentoo bootable media.
Virtiofs — a shared file system that lets virtual machines access a directory tree on the host
QEMU/Options — describes some of the options useful for configuring QEMU virtual machines.
QEMU/OS2WarpV3 guest
QEMU/Windows guest — setup of a Windows guest using QEMU
Installation[edit]
BIOS and UEFI firmware[edit]
In order to utilize KVM, either Vt-x (vmx) or AMD-V (svm) must be supported by the processor. Vt-x or AMD-V are Intel's and AMD's respective technologies for permitting multiple operating systems to concurrently execute operations on the processors.
To inspect hardware for virtualization support, issue the following command:
user $grep --color --extended-regexp "vmx|svm" "/proc/cpuinfo"
ImportantFor a period, manufacturers were shipping with virtualization turned off by default in the system's firmware. Toggling this feature in the firmware may require full removal of power from the system to take effect. If restarting the system does not work, try shutting down, unplugging the system, and pressing the power button in an unplugged state to discharge any residual energy from the power supply unit (PSU). Reapply power to the system to verify the configuration.
If KVM support is available, there should be a kvm device listed at /dev/kvm. This will take effect after the system has booted to a KVM-enabled kernel.
Kernel[edit]
Described below are the basic requirements for KVM kernel configuration for the host OS. A more complete and up-to-date list can be found at the KVM Tuning Kernel page.
NoteDifferent guest (virtualized) OS may require additional kernel options. These are covered in the corresponding Usage section.
KERNEL Enable high resolution timer support (CONFIG_HIGH_RES_TIMERS) General setup --->
Timers subsystem --->
<*> High Resolution Timer Support
NoteThis includes support for ARM64 processors.
Physical CPU processor support - Host[edit]
If KVM support is not available, insert CONFIG_KVM=y into the /usr/src/linux/.config and rebuild/reinstall the kernel (and its initramfs image). Come back here after the host is rebooted.
KERNEL Enable KVM Support (CONFIG_KVM) [*] Virtualization --->
<*> Kernel-based Virtual Machine (KVM) support
NoteThis includes support for ARM64 processors.
Processor Support[edit]
KERNEL Enable KVM support for Intel processors (CONFIG_KVM_INTEL) [*] Virtualization --->
<M> KVM for Intel processors support
KERNEL Enable KVM support for AMD processors (CONFIG_KVM_AMD) [*] Virtualization --->
<M> KVM for AMD processors support
WarningIf both KVM support for Intel processors and KVM support for AMD processors are set to be built into the kernel (*), an error message will be returned by kprint at early boot. Since the system can only have one processor type: Intel or AMD. Enabling one or both options as modules (M) will solve this issue.
Handling kernel config at CLI[edit]
To set the various kernel configuration settings from the command lines, the linux/scripts/kconfig/merge_config.sh shall be used here:
Mandatory kernel configuration options to set:
FILE /usr/src/kernel-kconfig-qemu-host.config CONFIG_VIRTUALIZATION=y
CONFIG_KVM=y
CONFIG_KVM_INTEL=y
CONFIG_KVM_AMD=y
root #cd "/usr/src/linux"
root #"./scripts/kconfig/merge_config.sh" ".config" "/usr/src/kernel-kconfig-qemu-host.config"
Useful kernel configuration options to use:
FILE /usr/src/kernel-kconfig-qemu-host-optional.config CONFIG_VHOST_NET=y
CONFIG_HIGH_RES_TIMER=y
CONFIG_HPET=y
CONFIG_COMPACTION=y
CONFIG_MIGRATION=y
CONFIG_KSM=y
CONFIG_SYSFS=y
CONFIG_PROC_FS=y
CONFIG_TRANSPARENT_HUGEPAGE=y
CONFIG_CGROUPS=y
CONFIG_KVM_HYPERV=y
root #"./scripts/kconfig/merge_config.sh" ".config" "/usr/src/kernel-kconfig-qemu-host-optional.config"
ImportantRecent Windows guests (at least Windows 10 22H2 and up) are required to set CONFIG_KVM_HYPERV (as per the optional configuration above). If this is not selected, VMs will fail to provision (or boot) with errors like: Failed to set MSR and Assertion `ret == cpu->kvm_msr_buf->nmsrs' failed.
Networking[edit]
Accelerated networking, required for vhost-net USE flag (recommend):
KERNEL vhost-net kernel 5.7 and later (CONFIG_VHOST_NET) Device Drivers --->
[*] VHOST drivers --->
<*> Host kernel accelerator for virtio net
KERNEL vhost-net (before kernel 5.7) [*] Virtualization --->
<*> Host kernel accelerator for virtio net
KERNEL Optional advanced networking support (CONFIG_NET_CORE, CONFIG_TUN) Device Drivers --->
[*] Network device support --->
[*] Network core driver support
<*> Universal TUN/TAP device driver support
Needed for 802.1d Ethernet bridging:
KERNEL Enabling 802.1d Ethernet Bridging support (CONFIG_IPV6, CONFIG_BRIDGE) [*] Networking support --->
Networking options --->
<*> The IPv6 protocol
<*> 802.1d Ethernet Bridging
Intel VT-g (integrated graphics adapter virtualization)[edit]
Mediated device passthrough for Intel GPUs (Broadwell to Comet Lake)[9]
KERNEL Intel VT-g (CONFIG_VFIO_MDEV, CONFIG_DRM_I915_GVT, CONFIG_DRM_I915_GVT_KVMGT) Device Drivers --->
<*> VFIO Non-Privileged userspace driver framework
<*> Mediated device driver framework
Graphics Support --->
<*> Intel 8xx/9xx/G3x/G4x/HD Graphics
[*] Enable Intel GVT-g graphics virtualization host support
<*> Enable KVM host support Intel GVT-g graphics virtualization
USE flags[edit]
Some packages are aware of the qemu USE flag.
Review the possible USE flags for QEMU:
USE flags for
app-emulation/qemu
QEMU + Kernel-based Virtual Machine userland tools
+aio
Enables support for Linux's Async IO
+curl
Support ISOs / -cdrom directives via HTTP or HTTPS.
+doc
Add extra documentation (API, Javadoc, etc). It is recommended to enable per package instead of globally
+fdt
Enables firmware device tree support
+filecaps
Use Linux file capabilities to control privilege rather than set*id (this is orthogonal to USE=caps which uses capabilities at runtime e.g. libcap)
+gnutls
Enable TLS support for the VNC console server. For 1.4 and newer this also enables WebSocket support. For 2.0 through 2.3 also enables disk quorum support.
+jpeg
Enable jpeg image support for the VNC console server
+oss
Add support for OSS (Open Sound System)
+pin-upstream-blobs
Pin the versions of BIOS firmware to the version included in the upstream release. This is needed to sanely support migration/suspend/resume/snapshotting/etc... of instances. When the blobs are different, random corruption/bugs/crashes/etc... may be observed.
+png
Enable png image support for the VNC console server
+seccomp
Enable seccomp (secure computing mode) to perform system call filtering at runtime to increase security of programs
+slirp
Enable TCP/IP in hypervisor via net-libs/libslirp
+vhost-net
Enable accelerated networking using vhost-net, see https://www.linux-kvm.org/page/VhostNet
+vnc
Enable VNC (remote desktop viewer) support
X
Add support for X11
accessibility
Adds support for braille displays using brltty
alsa
Enable alsa output for sound emulation
bpf
Enable eBPF support for RSS implementation.
bzip2
Enable bzip2 compression support
capstone
Enable disassembly support with dev-libs/capstone
debug
Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Backtraces
fuse
Enables FUSE block device export
glusterfs
Enables GlusterFS cluster fileystem via sys-cluster/glusterfs
gtk
Add support for x11-libs/gtk+ (The GIMP Toolkit)
infiniband
Enable Infiniband RDMA transport support
io-uring
Enable the use of io_uring for efficient asynchronous IO and system requests
iscsi
Enable direct iSCSI support via net-libs/libiscsi instead of indirectly via the Linux block layer that sys-block/open-iscsi does.
jack
Add support for the JACK Audio Connection Kit
jemalloc
Use dev-libs/jemalloc for memory management
keyutils
Support Linux keyrings via sys-apps/keyutils
lzo
Enable support for lzo compression
multipath
Enable multipath persistent reservation passthrough via sys-fs/multipath-tools.
ncurses
Enable the ncurses-based console
nfs
Enable NFS support
nls
Add Native Language Support (using gettext - GNU locale utilities)
numa
Enable NUMA support
opengl
Add support for OpenGL (3D graphics)
pam
Add support for PAM (Pluggable Authentication Modules) - DANGEROUS to arbitrarily flip
pipewire
Enable pipewire output for sound emulation
plugins
Enable qemu plugin API via shared library loading.
pulseaudio
Enable pulseaudio output for sound emulation
python
Add optional support/bindings for the Python language
rbd
Enable rados block device backend support, see https://docs.ceph.com/en/mimic/rbd/qemu-rbd/
sasl
Add support for the Simple Authentication and Security Layer
sdl
Enable the SDL-based console
sdl-image
SDL Image support for icons
selinux
!!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
smartcard
Enable smartcard support
snappy
Enable support for Snappy compression (as implemented in app-arch/snappy)
spice
Enable Spice protocol support via app-emulation/spice
ssh
Enable SSH based block device support via net-libs/libssh2
static
Build the User and Software MMU (system) targets as well as tools as static binaries
static-user
Build the User targets as static binaries
systemtap
Enable SystemTap/DTrace tracing
test
Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
udev
Enable virtual/udev integration (device discovery, power and storage device support, etc)
usb
Enable USB passthrough via dev-libs/libusb
usbredir
Use sys-apps/usbredir to redirect USB devices to another machine over TCP
vde
Enable VDE-based networking
virgl
Enable experimental Virgil 3d (virtual software GPU)
virtfs
Enable VirtFS via virtio-9p-pci / fsdev. See https://wiki.qemu.org/Documentation/9psetup
vte
Enable terminal support (x11-libs/vte) in the GTK+ interface
wayland
Enable dev-libs/wayland backend
xattr
Add support for getting and setting POSIX extended attributes, through sys-apps/attr. Requisite for the virtfs backend.
xdp
Enable support for XDP through net-libs/xdp-tools
xen
Enables support for Xen backends
zstd
Enable support for ZSTD compression
Data provided by the Gentoo Package Database
·
Last update: 2025-05-07 18:40
More information about USE flags
NoteMore than one USE flag (gtk, ncurses, sdl, or spice) can be enabled for graphical output. If graphics are desired, it is generally recommended to enable more than one graphical USE flag.
NoteIf virt-manager is going to be used, be sure to enable the usbredir and spice USE flags on the qemu package for correct operation.
USE_EXPAND[edit]
Additional ebuild configuration are provided as the USE_EXPAND variables QEMU_USER_TARGETS and QEMU_SOFTMMU_TARGETS. See app-emulation/qemu for a list of all the available targets (there are many; most are very obscure and may be ignored; leaving these variables at their default values will disable almost everything, which is probably just fine for most users).
For each target specified, a qemu executable will be built. A softmmu target is the standard qemu use-case of emulating an entire system (like VirtualBox or VMWare, but with optional support for emulating CPU hardware along with peripherals). user targets execute user-mode code only; the (somewhat ambitious) purpose of these targets, is to "magically" allow importing user namespace Linux ELF binaries from a different architecture into the native system (like multilib, without the need for a software stack or CPU capable of running it).
In order to enable QEMU_USER_TARGETS and QEMU_SOFTMMU_TARGETS, one can set the variables globally in /etc/portage/make.conf:
FILE /etc/portage/make.conf QEMU_SOFTMMU_TARGETS="arm x86_64 sparc"
QEMU_USER_TARGETS="x86_64"
WarningSetting the USE flags globally in /etc/portage/make.conf is discouraged, because of possible ordering issues in Portage.[10]
Files in the directory /etc/portage/package.use can be added. There are two equivalent syntaxes available:
One is the traditional USE flag syntax:
FILE /etc/portage/package.use/qemu app-emulation/qemu qemu_softmmu_targets_arm qemu_softmmu_targets_x86_64 qemu_softmmu_targets_sparc
app-emulation/qemu qemu_user_targets_x86_64
And the other, preferred one, is the USE_EXPAND syntax:
FILE /etc/portage/package.use/qemu app-emulation/qemu QEMU_SOFTMMU_TARGETS: arm x86_64 sparc QEMU_USER_TARGETS: x86_64
Emerge[edit]
After reviewing and adding any desired USE flags, emerge app-emulation/qemu:
root #emerge --ask app-emulation/qemu
Configuration[edit]
The following sub-articles provide detailed instructions on QEMU configurations and options:
Usage options - Contains common configuration options used with QEMU (graphics/display, networking, RAM, storage, processor, etc).
QEMU/Linux guest — describes the setup of a Gentoo Linux guest in QEMU using Gentoo bootable media.
QEMU/Windows guest — setup of a Windows guest using QEMU
OS2WarpV3 guest - Describes the configuration steps needed to setup a virtualized OS2WarpVs=3 guest with QEMU.
Environment variables[edit]
G_MESSAGES_DEBUG
LISTEN_FDS
LISTEN_PID
QEMU_AUDIO_DRV
QEMU_MODULE_DIR
XDG_RUNTIME_DIR
Files[edit]
Files that QEMU uses.
Single File[edit]
/etc/libvirt/qemu.conf - QEMU configuration file.
/etc/libvirt/qemu-lockd.conf - QEMU lock files
/etc/libvirt/qemu-sanlock.conf - QEMU SAN lock
/etc/libvirt/qemu/<domain-name>.xml - Domain XML setting for a virtual machine or container.
/etc/libvirt/qemu/autostart/<domain-name>.xml - Autostart this domain (virtual machine or container).
/etc/libvirt/qemu/networks/<network-name>.xml - Network XML setting file for a network connection
/etc/libvirt/qemu/networks/autostart/<network-name>.xml - Autostart this network connection.
/var/lib/libvirt/qemu/channel/target/<domain-name>/<socket-file> - UNIX socket file for Libvertd daemon API
/var/cache/libvirt/qemu/capabilities/<hash-value>.xml - Host OS capabilities in XML format
/var/lib/libvirt/qemu/checkpoint/
/var/lib/libvirt/qemu/<domain-9-XXXX>/ - holds UNIX sockets and AES keys for this domain.
/var/lib/libvirt/qemu/dump/
/var/lib/libvirt/qemu/nvram/
/var/lib/libvirt/qemu/ram/
/var/lib/libvirt/qemu/save/ - holding directory of hibernation images
/var/lib/libvirt/qemu/snapshot/ - holding directory of snapshots
/var/run/libvirt/qemu - various UNIX socket and PID files for the libvirtd daemon.
Image File[edit]
QEMU supports the following disk image formats:
QEMU copy-on-write (.qcow2, .qed, .qcow, .cow)
VirtualBox Virtual Disk Image (.vdi)
CD/DVD (ISO-9660) images (.iso)
Raw images (.img), that guest OS can control
VFAT-16
VMware Virtual Machine Disk (.vmdk)
Virtual PC Virtual Hard Disk (.vhd)
Parallels disk image (.hdd, .hds) – Read-only
Apple macos Universal Disk Image Format (.dmg) – Read-only
Bochs – Read-only
Linux cloop – Read-only
Additional software[edit]
User name qemu is required, defined by acct-user/qemu and evoked by sys-emulator/qemu package.
Group name qemu is required, defined by acct-group/qemu and evoked by sys-emulator/qemu package.
To connect to the SPICE server of QEMU, a GUI client like net-misc/spice-gtk is required.
Usage[edit]
QEMU can be used in two ways, with GUI front ends and through the command line. The configuration of QEMU depends on which method is employed:
GUI (Front-End) - To make life easier, there are multiple user-friendly front ends to QEMU: See Front-ends
CLI
Invocation[edit]
QEMU supports around 34 different CPU architectures. To find the desired architecture, list what is installed.
user $ls /usr/bin/qemu-system-*/usr/bin/qemu-system-aarch64 /usr/bin/qemu-system-mips /usr/bin/qemu-system-rx
/usr/bin/qemu-system-alpha /usr/bin/qemu-system-mips64 /usr/bin/qemu-system-s390x
/usr/bin/qemu-system-arm /usr/bin/qemu-system-mips64el /usr/bin/qemu-system-sh4
/usr/bin/qemu-system-avr /usr/bin/qemu-system-mipsel /usr/bin/qemu-system-sh4eb
/usr/bin/qemu-system-cris /usr/bin/qemu-system-nios2 /usr/bin/qemu-system-sparc
/usr/bin/qemu-system-hppa /usr/bin/qemu-system-or1k /usr/bin/qemu-system-sparc64
/usr/bin/qemu-system-i386 /usr/bin/qemu-system-ppc /usr/bin/qemu-system-tricore
/usr/bin/qemu-system-loongarch64 /usr/bin/qemu-system-ppc64 /usr/bin/qemu-system-x86_64
/usr/bin/qemu-system-m68k /usr/bin/qemu-system-ppc64le /usr/bin/qemu-system-x86_64-microvm
/usr/bin/qemu-system-microblaze /usr/bin/qemu-system-riscv32 /usr/bin/qemu-system-xtensa
/usr/bin/qemu-system-microblazeel /usr/bin/qemu-system-riscv64 /usr/bin/qemu-system-xtensaeb
user $qemu-system-x86_64 -helpQEMU emulator version 7.2.9 (Debian 1:7.2+dfsg-7+deb12u5)
Copyright (c) 2003-2022 Fabrice Bellard and the QEMU Project developers
usage: qemu-system-x86_64 [options] [disk_image]
'disk_image' is a raw hard disk image for IDE hard disk 0
Standard options:
-h or -help display this help and exit
-version display version information and exit
-machine [type=]name[,prop[=value][,...]]
selects emulated machine ('-machine help' for list)
property accel=accel1[:accel2[:...]] selects accelerator
supported accelerators are kvm, xen, hax, hvf, nvmm, whpx or tcg (default: tcg)
vmport=on|off|auto controls emulation of vmport (default: auto)
dump-guest-core=on|off include guest memory in a core dump (default=on)
mem-merge=on|off controls memory merge support (default: on)
aes-key-wrap=on|off controls support for AES key wrapping (default=on)
dea-key-wrap=on|off controls support for DEA key wrapping (default=on)
suppress-vmdesc=on|off disables self-describing migration (default=off)
nvdimm=on|off controls NVDIMM support (default=off)
memory-encryption=@var{} memory encryption object to use (default=none)
hmat=on|off controls ACPI HMAT support (default=off)
memory-backend='backend-id' specifies explicitly provided backend for main RAM (default=none)
cxl-fmw.0.targets.0=firsttarget,cxl-fmw.0.targets.1=secondtarget,cxl-fmw.0.size=size[,cxl-fmw.0.interleave-granularity=granularity]
sgx-epc.0.memdev=memid,sgx-epc.0.node=numaid
-cpu cpu select CPU ('-cpu help' for list)
-accel [accel=]accelerator[,prop[=value][,...]]
select accelerator (kvm, xen, hax, hvf, nvmm, whpx or tcg; use 'help' for a list)
igd-passthru=on|off (enable Xen integrated Intel graphics passthrough, default=off)
kernel-irqchip=on|off|split controls accelerated irqchip support (default=on)
kvm-shadow-mem=size of KVM shadow MMU in bytes
split-wx=on|off (enable TCG split w^x mapping)
tb-size=n (TCG translation block cache size)
dirty-ring-size=n (KVM dirty ring GFN count, default 0)
notify-vmexit=run|internal-error|disable,notify-window=n (enable notify VM exit and set notify window, x86 only)
thread=single|multi (enable multi-threaded TCG)
-smp [[cpus=]n][,maxcpus=maxcpus][,sockets=sockets][,dies=dies][,clusters=clusters][,cores=cores][,threads=threads]
set the number of initial CPUs to 'n' [default=1]
maxcpus= maximum number of total CPUs, including
offline CPUs for hotplug, etc
sockets= number of sockets on the machine board
dies= number of dies in one socket
clusters= number of clusters in one die
cores= number of cores in one cluster
threads= number of threads in one core
Note: Different machines may have different subsets of the CPU topology
parameters supported, so the actual meaning of the supported parameters
will vary accordingly. For example, for a machine type that supports a
three-level CPU hierarchy of sockets/cores/threads, the parameters will
sequentially mean as below:
sockets means the number of sockets on the machine board
cores means the number of cores in one socket
threads means the number of threads in one core
For a particular machine type board, an expected CPU topology hierarchy
can be defined through the supported sub-option. Unsupported parameters
can also be provided in addition to the sub-option, but their values
must be set as 1 in the purpose of correct parsing.
-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=node]
-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=node]
-numa dist,src=source,dst=destination,val=distance
-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]
-numa hmat-lb,initiator=node,target=node,hierarchy=memory|first-level|second-level|third-level,data-type=access-latency|read-latency|write-latency[,latency=lat][,bandwidth=bw]
-numa hmat-cache,node-id=node,size=size,level=level[,associativity=none|direct|complex][,policy=none|write-back|write-through][,line=size]
-add-fd fd=fd,set=set[,opaque=opaque]
Add 'fd' to fd 'set'
-set group.id.arg=value
set <arg> parameter for item <id> of type <group>
i.e. -set drive.$id.file=/path/to/image
-global driver.property=value
-global driver=driver,property=property,value=value
set a global default for a driver property
-boot [order=drives][,once=drives][,menu=on|off]
[,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]
'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)
'sp_name': the file's name that would be passed to bios as logo picture, if menu=on
'sp_time': the period that splash picture last if menu=on, unit is ms
'rb_timeout': the timeout before guest reboot when boot failed, unit is ms
-m [size=]megs[,slots=n,maxmem=size]
configure guest RAM
size: initial amount of guest memory
slots: number of hotplug slots (default: none)
maxmem: maximum amount of guest memory (default: none)
NOTE: Some architectures might enforce a specific granularity
-mem-path FILE provide backing storage for guest RAM
-mem-prealloc preallocate guest memory (use with -mem-path)
-k language use keyboard layout (for example 'fr' for French)
-audio-help show -audiodev equivalent of the currently specified audio settings
-audio [driver=]driver,model=value[,prop[=value][,...]]
specifies the audio backend and device to use;
apart from 'model', options are the same as for -audiodev.
use '-audio model=help' to show possible devices.
-audiodev [driver=]driver,id=id[,prop[=value][,...]]
specifies the audio backend to use
Use ``-audiodev help`` to list the available drivers
id= identifier of the backend
timer-period= timer period in microseconds
in|out.mixing-engine= use mixing engine to mix streams inside QEMU
in|out.fixed-settings= use fixed settings for host audio
in|out.frequency= frequency to use with fixed settings
in|out.channels= number of channels to use with fixed settings
in|out.format= sample format to use with fixed settings
valid values: s8, s16, s32, u8, u16, u32, f32
in|out.voices= number of voices to use
in|out.buffer-length= length of buffer in microseconds
-audiodev none,id=id,[,prop[=value][,...]]
dummy driver that discards all output
-audiodev alsa,id=id[,prop[=value][,...]]
in|out.dev= name of the audio device to use
in|out.period-length= length of period in microseconds
in|out.try-poll= attempt to use poll mode
threshold= threshold (in microseconds) when playback starts
-audiodev oss,id=id[,prop[=value][,...]]
in|out.dev= path of the audio device to use
in|out.buffer-count= number of buffers
in|out.try-poll= attempt to use poll mode
try-mmap= try using memory mapped access
exclusive= open device in exclusive mode
dsp-policy= set timing policy (0..10), -1 to use fragment mode
-audiodev pa,id=id[,prop[=value][,...]]
server= PulseAudio server address
in|out.name= source/sink device name
in|out.latency= desired latency in microseconds
-audiodev sdl,id=id[,prop[=value][,...]]
in|out.buffer-count= number of buffers
-audiodev sndio,id=id[,prop[=value][,...]]
-audiodev spice,id=id[,prop[=value][,...]]
-audiodev dbus,id=id[,prop[=value][,...]]
-audiodev wav,id=id[,prop[=value][,...]]
path= path of wav file to record
-device driver[,prop[=value][,...]]
add device (based on driver)
prop=value,... sets driver properties
use '-device help' to print all possible drivers
use '-device driver,help' to print all possible properties
-name string1[,process=string2][,debug-threads=on|off]
set the name of the guest
string1 sets the window title and string2 the process name
When debug-threads is enabled, individual threads are given a separate name
NOTE: The thread names are for debugging and not a stable API.
-uuid %08x-%04x-%04x-%04x-%012x
specify machine UUID
Block device options:
-fda/-fdb file use 'file' as floppy disk 0/1 image
-hda/-hdb file use 'file' as hard disk 0/1 image
-hdc/-hdd file use 'file' as hard disk 2/3 image
-cdrom file use 'file' as CD-ROM image
-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]
[,cache.direct=on|off][,cache.no-flush=on|off]
[,read-only=on|off][,auto-read-only=on|off]
[,force-share=on|off][,detect-zeroes=on|off|unmap]
[,driver specific parameters...]
configure a block backend
-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]
[,cache=writethrough|writeback|none|directsync|unsafe][,format=f]
[,snapshot=on|off][,rerror=ignore|stop|report]
[,werror=ignore|stop|report|enospc][,id=name]
[,aio=threads|native|io_uring]
[,readonly=on|off][,copy-on-read=on|off]
[,discard=ignore|unmap][,detect-zeroes=on|off|unmap]
[[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]
[[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]
[[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]
[[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]
[[,iops_size=is]]
[[,group=g]]
use 'file' as a drive image
-mtdblock file use 'file' as on-board Flash memory image
-sd file use 'file' as SecureDigital card image
-snapshot write to temporary files instead of disk image files
-fsdev local,id=id,path=path,security_model=mapped-xattr|mapped-file|passthrough|none
[,writeout=immediate][,readonly=on][,fmode=fmode][,dmode=dmode]
[[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]
[[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]
[[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]
[[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]
[[,throttling.iops-size=is]]
-fsdev proxy,id=id,socket=socket[,writeout=immediate][,readonly=on]
-fsdev proxy,id=id,sock_fd=sock_fd[,writeout=immediate][,readonly=on]
-fsdev synth,id=id
-virtfs local,path=path,mount_tag=tag,security_model=mapped-xattr|mapped-file|passthrough|none
[,id=id][,writeout=immediate][,readonly=on][,fmode=fmode][,dmode=dmode][,multidevs=remap|forbid|warn]
-virtfs proxy,mount_tag=tag,socket=socket[,id=id][,writeout=immediate][,readonly=on]
-virtfs proxy,mount_tag=tag,sock_fd=sock_fd[,id=id][,writeout=immediate][,readonly=on]
-virtfs synth,mount_tag=tag[,id=id][,readonly=on]
-iscsi [user=user][,password=password]
[,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE
[,initiator-name=initiator-iqn][,id=target-iqn]
[,timeout=timeout]
iSCSI session parameters
USB convenience options:
-usb enable on-board USB host controller (if not enabled by default)
-usbdevice name add the host or guest USB device 'name'
Display options:
-display spice-app[,gl=on|off]
-display sdl[,gl=on|core|es|off][,grab-mod=<mod>][,show-cursor=on|off]
[,window-close=on|off]
-display gtk[,full-screen=on|off][,gl=on|off][,grab-on-hover=on|off]
[,show-tabs=on|off][,show-cursor=on|off][,window-close=on|off]
[,show-menubar=on|off]
-display vnc=<display>[,<optargs>]
-display curses[,charset=<encoding>]
-display egl-headless[,rendernode=<file>]
-display dbus[,addr=<dbusaddr>]
[,gl=on|core|es|off][,rendernode=<file>]
-display none
select display backend type
The default display is equivalent to
"-display gtk"
-nographic disable graphical output and redirect serial I/Os to console
-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]
[,x509-key-file=<file>][,x509-key-password=<file>]
[,x509-cert-file=<file>][,x509-cacert-file=<file>]
[,x509-dh-key-file=<file>][,addr=addr]
[,ipv4=on|off][,ipv6=on|off][,unix=on|off]
[,tls-ciphers=<list>]
[,tls-channel=[main|display|cursor|inputs|record|playback]]
[,plaintext-channel=[main|display|cursor|inputs|record|playback]]
[,sasl=on|off][,disable-ticketing=on|off]
[,password=<string>][,password-secret=<secret-id>]
[,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]
[,jpeg-wan-compression=[auto|never|always]]
[,zlib-glz-wan-compression=[auto|never|always]]
[,streaming-video=[off|all|filter]][,disable-copy-paste=on|off]
[,disable-agent-file-xfer=on|off][,agent-mouse=[on|off]]
[,playback-compression=[on|off]][,seamless-migration=[on|off]]
[,gl=[on|off]][,rendernode=<file>]
enable spice
at least one of {port, tls-port} is mandatory
-portrait rotate graphical output 90 deg left (only PXA LCD)
-rotate <deg> rotate graphical output some deg left (only PXA LCD)
-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]
select video card type
-full-screen start in full screen
-vnc <display> shorthand for -display vnc=<display>
i386 target only:
-win2k-hack use it when installing Windows 2000 to avoid a disk full bug
-no-fd-bootchk disable boot signature checking for floppy disks
-no-acpi disable ACPI
-no-hpet disable HPET
-acpitable [sig=str][,rev=n][,oem_id=str][,oem_table_id=str][,oem_rev=n][,asl_compiler_id=str][,asl_compiler_rev=n][,{data|file}=file1[:file2]...]
ACPI table description
-smbios file=binary
load SMBIOS entry from binary file
-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]
[,uefi=on|off]
specify SMBIOS type 0 fields
-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]
[,uuid=uuid][,sku=str][,family=str]
specify SMBIOS type 1 fields
-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]
[,asset=str][,location=str]
specify SMBIOS type 2 fields
-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]
[,sku=str]
specify SMBIOS type 3 fields
-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]
[,asset=str][,part=str][,max-speed=%d][,current-speed=%d]
[,processor-id=%d]
specify SMBIOS type 4 fields
-smbios type=8[,external_reference=str][,internal_reference=str][,connector_type=%d][,port_type=%d]
specify SMBIOS type 8 fields
-smbios type=11[,value=str][,path=filename]
specify SMBIOS type 11 fields
-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]
[,asset=str][,part=str][,speed=%d]
specify SMBIOS type 17 fields
-smbios type=41[,designation=str][,kind=str][,instance=%d][,pcidev=str]
specify SMBIOS type 41 fields
Network options:
-netdev user,id=str[,ipv4=on|off][,net=addr[/mask]][,host=addr]
[,ipv6=on|off][,ipv6-net=addr[/int]][,ipv6-host=addr]
[,restrict=on|off][,hostname=host][,dhcpstart=addr]
[,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,domainname=domain]
[,tftp=dir][,tftp-server-name=name][,bootfile=f][,hostfwd=rule][,guestfwd=rule][,smb=dir[,smbserver=addr]]
configure a user mode network backend with ID 'str',
its DHCP server and optional services
-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]
[,br=bridge][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]
[,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]
[,poll-us=n]
configure a host TAP network backend with ID 'str'
connected to a bridge (default=br0)
use network scripts 'file' (default=/etc/qemu-ifup)
to configure it and 'dfile' (default=/etc/qemu-ifdown)
to deconfigure it
use '[down]script=no' to disable script execution
use network helper 'helper' (default=/usr/lib/qemu/qemu-bridge-helper) to
configure it
use 'fd=h' to connect to an already opened TAP interface
use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces
use 'sndbuf=nbytes' to limit the size of the send buffer (the
default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')
use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag
use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition
use vhost=on to enable experimental in kernel accelerator
(only has effect for virtio guests which use MSIX)
use vhostforce=on to force vhost on for non-MSIX virtio guests
use 'vhostfd=h' to connect to an already opened vhost net device
use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices
use 'queues=n' to specify the number of queues to be created for multiqueue TAP
use 'poll-us=n' to specify the maximum number of microseconds that could be
spent on busy polling for vhost net
-netdev bridge,id=str[,br=bridge][,helper=helper]
configure a host TAP network backend with ID 'str' that is
connected to a bridge (default=br0)
using the program 'helper (default=/usr/lib/qemu/qemu-bridge-helper)
-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]
[,rxsession=rxsession],txsession=txsession[,ipv6=on|off][,udp=on|off]
[,cookie64=on|off][,counter][,pincounter][,txcookie=txcookie]
[,rxcookie=rxcookie][,offset=offset]
configure a network backend with ID 'str' connected to
an Ethernet over L2TPv3 pseudowire.
Linux kernel 3.3+ as well as most routers can talk
L2TPv3. This transport allows connecting a VM to a VM,
VM to a router and even VM to Host. It is a nearly-universal
standard (RFC3931). Note - this implementation uses static
pre-configured tunnels (same as the Linux kernel).
use 'src=' to specify source address
use 'dst=' to specify destination address
use 'udp=on' to specify udp encapsulation
use 'srcport=' to specify source udp port
use 'dstport=' to specify destination udp port
use 'ipv6=on' to force v6
L2TPv3 uses cookies to prevent misconfiguration as
well as a weak security measure
use 'rxcookie=0x012345678' to specify a rxcookie
use 'txcookie=0x012345678' to specify a txcookie
use 'cookie64=on' to set cookie size to 64 bit, otherwise 32
use 'counter=off' to force a 'cut-down' L2TPv3 with no counter
use 'pincounter=on' to work around broken counter handling in peer
use 'offset=X' to add an extra offset between header and data
-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]
configure a network backend to connect to another network
using a socket connection
-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]
configure a network backend to connect to a multicast maddr and port
use 'localaddr=addr' to specify the host address to send packets from
-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]
configure a network backend to connect to another network
using an UDP tunnel
-netdev stream,id=str[,server=on|off],addr.type=inet,addr.host=host,addr.port=port[,to=maxport][,numeric=on|off][,keep-alive=on|off][,mptcp=on|off][,addr.ipv4=on|off][,addr.ipv6=on|off]
-netdev stream,id=str[,server=on|off],addr.type=unix,addr.path=path[,abstract=on|off][,tight=on|off]
-netdev stream,id=str[,server=on|off],addr.type=fd,addr.str=file-descriptor
configure a network backend to connect to another network
using a socket connection in stream mode.
-netdev dgram,id=str,remote.type=inet,remote.host=maddr,remote.port=port[,local.type=inet,local.host=addr]
-netdev dgram,id=str,remote.type=inet,remote.host=maddr,remote.port=port[,local.type=fd,local.str=file-descriptor]
configure a network backend to connect to a multicast maddr and port
use ``local.host=addr`` to specify the host address to send packets from
-netdev dgram,id=str,local.type=inet,local.host=addr,local.port=port[,remote.type=inet,remote.host=addr,remote.port=port]
-netdev dgram,id=str,local.type=unix,local.path=path[,remote.type=unix,remote.path=path]
-netdev dgram,id=str,local.type=fd,local.str=file-descriptor
configure a network backend to connect to another network
using an UDP tunnel
-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]
configure a network backend to connect to port 'n' of a vde switch
running on host and listening for incoming connections on 'socketpath'.
Use group 'groupname' and mode 'octalmode' to change default
ownership and permissions for communication port.
-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]
configure a vhost-user network, backed by a chardev 'dev'
-netdev vhost-vdpa,id=str[,vhostdev=/path/to/dev][,vhostfd=h]
configure a vhost-vdpa network,Establish a vhost-vdpa netdev
use 'vhostdev=/path/to/dev' to open a vhost vdpa device
use 'vhostfd=h' to connect to an already opened vhost vdpa device
-netdev hubport,id=str,hubid=n[,netdev=nd]
configure a hub port on the hub with ID 'n'
-nic [tap|bridge|user|l2tpv3|vde|vhost-user|socket][,option][,...][mac=macaddr]
initialize an on-board / default host NIC (using MAC address
macaddr) and connect it to the given host network backend
-nic none use it alone to have zero network devices (the default is to
provided a 'user' network connection)
-net nic[,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]
configure or create an on-board (or machine default) NIC and
connect it to hub 0 (please use -nic unless you need a hub)
-net [user|tap|bridge|vde|socket][,option][,option][,...]
old way to initialize a host network interface
(use the -netdev option if possible instead)
Character device options:
-chardev help
-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4=on|off][,ipv6=on|off][,nodelay=on|off]
[,server=on|off][,wait=on|off][,telnet=on|off][,websocket=on|off][,reconnect=seconds][,mux=on|off]
[,logfile=PATH][,logappend=on|off][,tls-creds=ID][,tls-authz=ID] (tcp)
-chardev socket,id=id,path=path[,server=on|off][,wait=on|off][,telnet=on|off][,websocket=on|off][,reconnect=seconds]
[,mux=on|off][,logfile=PATH][,logappend=on|off][,abstract=on|off][,tight=on|off] (unix)
-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]
[,localport=localport][,ipv4=on|off][,ipv6=on|off][,mux=on|off]
[,logfile=PATH][,logappend=on|off]
-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]
[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]
-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]
-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]
-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]
TPM device options:
-tpmdev passthrough,id=id[,path=path][,cancel-path=path]
use path to provide path to a character device; default is /dev/tpm0
use cancel-path to provide path to TPM's cancel sysfs entry; if
not provided it will be searched for in /sys/class/misc/tpm?/device
-tpmdev emulator,id=id,chardev=dev
configure the TPM device using chardev backend
Boot Image or Kernel specific:
-bios file set the filename for the BIOS
-pflash file use 'file' as a parallel flash image
-kernel bzImage use 'bzImage' as kernel image
-append cmdline use 'cmdline' as kernel command line
-initrd file use 'file' as initial ram disk
-dtb file use 'file' as device tree image
Debug/Expert options:
-compat [deprecated-input=accept|reject|crash][,deprecated-output=accept|hide]
Policy for handling deprecated management interfaces
-compat [unstable-input=accept|reject|crash][,unstable-output=accept|hide]
Policy for handling unstable management interfaces
-fw_cfg [name=]<name>,file=<file>
add named fw_cfg entry with contents from file
-fw_cfg [name=]<name>,string=<str>
add named fw_cfg entry with contents from string
-serial dev redirect the serial port to char device 'dev'
-parallel dev redirect the parallel port to char device 'dev'
-monitor dev redirect the monitor to char device 'dev'
-qmp dev like -monitor but opens in 'control' mode
-qmp-pretty dev like -qmp but uses pretty JSON formatting
-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]
-debugcon dev redirect the debug console to char device 'dev'
-pidfile file write PID to 'file'
-singlestep always run in singlestep mode
--preconfig pause QEMU before machine is initialized (experimental)
-S freeze CPU at startup (use 'c' to start execution)
-overcommit [mem-lock=on|off][cpu-pm=on|off]
run qemu with overcommit hints
mem-lock=on|off controls memory lock support (default: off)
cpu-pm=on|off controls cpu power management (default: off)
-gdb dev accept gdb connection on 'dev'. (QEMU defaults to starting
the guest without waiting for gdb to connect; use -S too
if you want it to not start execution.)
-s shorthand for -gdb tcp::1234
-d item1,... enable logging of specified items (use '-d help' for a list of log items)
-D logfile output log to logfile (default stderr)
-dfilter range,.. filter debug output to range of addresses (useful for -d cpu,exec,etc..)
-seed number seed the pseudo-random number generator
-L path set the directory for the BIOS, VGA BIOS and keymaps
-enable-kvm enable KVM full virtualization support
-xen-domid id specify xen guest domain id
-xen-attach attach to existing xen domain
libxl will use this when starting QEMU
-xen-domid-restrict restrict set of available xen operations
to specified domain id. (Does not affect
xenpv machine type).
-no-reboot exit instead of rebooting
-no-shutdown stop before shutdown
-action reboot=reset|shutdown
action when guest reboots [default=reset]
-action shutdown=poweroff|pause
action when guest shuts down [default=poweroff]
-action panic=pause|shutdown|exit-failure|none
action when guest panics [default=shutdown]
-action watchdog=reset|shutdown|poweroff|inject-nmi|pause|debug|none
action when watchdog fires [default=reset]
-loadvm [tag|id]
start right away with a saved state (loadvm in monitor)
-daemonize daemonize QEMU after initializing
-option-rom rom load a file, rom, into the option ROM space
-rtc [base=utc|localtime|<datetime>][,clock=host|rt|vm][,driftfix=none|slew]
set the RTC base and clock, enable drift fix for clock ticks (x86 only)
-icount [shift=N|auto][,align=on|off][,sleep=on|off][,rr=record|replay,rrfile=<filename>[,rrsnapshot=<snapshot>]]
enable virtual instruction counter with 2^N clock ticks per
instruction, enable aligning the host and virtual clocks
or disable real time cpu sleeping, and optionally enable
record-and-replay mode
-watchdog-action reset|shutdown|poweroff|inject-nmi|pause|debug|none
action when watchdog fires [default=reset]
-echr chr set terminal escape character instead of ctrl-a
-incoming tcp:[host]:port[,to=maxport][,ipv4=on|off][,ipv6=on|off]
-incoming rdma:host:port[,ipv4=on|off][,ipv6=on|off]
-incoming unix:socketpath
prepare for incoming migration, listen on
specified protocol and socket address
-incoming fd:fd
-incoming exec:cmdline
accept incoming migration on given file descriptor
or from given external command
-incoming defer
wait for the URI to be specified via migrate_incoming
-only-migratable allow only migratable devices
-nodefaults don't create default devices
-chroot dir chroot to dir just before starting the VM
-runas user change to user id user just before starting the VM
user can be numeric uid:gid instead
-sandbox on[,obsolete=allow|deny][,elevateprivileges=allow|deny|children]
[,spawn=allow|deny][,resourcecontrol=allow|deny]
Enable seccomp mode 2 system call filter (default 'off').
use 'obsolete' to allow obsolete system calls that are provided
by the kernel, but typically no longer used by modern
C library implementations.
use 'elevateprivileges' to allow or deny the QEMU process ability
to elevate privileges using set*uid|gid system calls.
The value 'children' will deny set*uid|gid system calls for
main QEMU process but will allow forks and execves to run unprivileged
use 'spawn' to avoid QEMU to spawn new threads or processes by
blocking *fork and execve
use 'resourcecontrol' to disable process affinity and schedular priority
-readconfig <file>
read config file
-no-user-config
do not load default user-provided config files at startup
-trace [[enable=]<pattern>][,events=<file>][,file=<file>]
specify tracing options
-plugin [file=]<file>[,<argname>=<argvalue>]
load a plugin
-async-teardown enable asynchronous teardown
-msg [timestamp[=on|off]][,guest-name=[on|off]]
control error message format
timestamp=on enables timestamps (default: off)
guest-name=on enables guest name prefix but only if
-name guest option is set (default: off)
-dump-vmstate <file>
Output vmstate information in JSON format to file.
Use the scripts/vmstate-static-checker.py file to
check for possible regressions in migration code
by comparing two such vmstate dumps.
-enable-sync-profile
enable synchronization profiling
Generic object creation:
-object TYPENAME[,PROP1=VALUE1,...]
create a new object of type TYPENAME setting properties
in the order they are specified. Note that the 'id'
property must be set. These objects are placed in the
'/objects' path.
During emulation, the following keys are useful:
ctrl-alt-f toggle full screen
ctrl-alt-n switch to virtual console 'n'
ctrl-alt toggle mouse and keyboard grab
When using -nographic, press 'ctrl-a h' to get some help.
See <https://qemu.org/contribute/report-a-bug> for how to report bugs.
More information on the QEMU project at <https://qemu.org>.
Permissions[edit]
In order to run a KVM-accelerated virtual machine without logging in as root, add normal users to the kvm group. Replace <username> in the example command below with the appropriate user(s):
root #gpasswd -a larry kvm
Creation of a disk image[edit]
To create a raw disk image with 4 GiB size:
user $qemu-img create -f raw "/home/larry/qemu/my-systems-disk-image.img" 4GFormatting 'my-systems-disk-image.img', fmt=raw size=4294967296
user $ls -lhtotal 4
-rw-r--r-- 1 larry larry 4.0G Apr 12 11:23 my-systems-disk-image.img
To create a raw disk image with copy-on-write disabled:
user $qemu-img create -f raw "/home/larry/qemu/my-systems-disk-image.img" -o nocow=on 4GFormatting 'my-systems-disk-image.img', fmt=raw size=4294967296 nocow=on
user $ls -lhtotal 4
-rw-r--r-- 1 larry larry 4.0G Apr 12 11:23 my-systems-disk-image.img
The option nocow is also a file attribute, which can be determined via the command lsattr[11].
The following will create a qcow2 disk image (useful, if your filesystem does not support sparse files):
user $qemu-img create -f qcow2 "/home/larry/qemu/my-systems-disk-image.qcow2" 4GFormatting 'my-systems-disk-image.qcow2', fmt=qcow2 cluster_size=65536 extended_l2=off compression_type=zlib size=4294967296 lazy_refcounts=off refcount_bits=16
user $ls -ltotal 196K
-rw-r--r-- 1 larry larry 193K Apr 12 11:30 my-systems-disk-image.qcow2
Preparation of a bootable disk image from scratch[edit]
A system can be copied onto a disk image, when not using a cdrom installation medium.
By default, qemu uses a bios-firmware to boot the system.
The disk can be prepared with a msdos disk label and a gap between the end of the 512-byte-MBR (Master Boot Record) and the start of the first partition.
The gap is needed for boot loaders like grub, which place boot-code within this gap.
The following example uses the raw disk image, which was created above.
A raw disk image can be prepared by attaching it as a loop device:
root #losetup --find --partscan --show "/home/larry/qemu/my-systems-disk-image.img"/dev/loop0
The parameter --find finds the first unused loop device.
The parameter --partscan forces the Kernel to scan the partition table on the newly created loop device, where the default sector size of 512 bytes is assumed.
The parameter --show displays the name of the assigned loop device, if the parameter --find is used.
Attached loop devices can be listed with the follwing command:
root #losetup --listNAME SIZELIMIT OFFSET AUTOCLEAR RO BACK-FILE DIO LOG-SEC
/dev/loop0 0 0 0 0 /home/larry/qemu/my-systems-disk-image.img 0 512
Then, the loop device can be formatted like a normal disk.
Print the partition table:
root #parted "/dev/loop0" "unit mib print"Error: /dev/loop0: unrecognised disk label
Model: Loopback device (loopback)
Disk /dev/loop0: 4096MiB
Sector size (logical/physical): 512B/512B
Partition Table: unknown
Disk Flags:
Create a new partition table (msdos disk label):
WarningMake absolutely sure to select the correct loop device, since this may overwrite an existing partition table; resulting in data loss, if the overwritten partition table cannot be recovered.
root #parted "/dev/loop0" "mklabel msdos"Information: You may need to update /etc/fstab.
The returned information can be ignored, since an entry in the configuration file /etc/fstab is not needed.
parted now indicates, that the Partition Table is msdos:
root #parted "/dev/loop0" "unit mib print"Model: Loopback device (loopback)
Disk /dev/loop0: 4096MiB
Sector size (logical/physical): 512B/512B
Partition Table: msdos
Disk Flags:
Number Start End Size Type File system Flags
Create an ext4 partition with an offset of 2 MiB:
root #parted "/dev/loop0" "mkpart primary ext4 2MiB -1"
The parameter -1 represents the last sector of the partition.
The first partition has been successfully created:
root #parted "/dev/loop0" "unit mib print"Model: Loopback device (loopback)
Disk /dev/loop0: 4096MiB
Sector size (logical/physical): 512B/512B
Partition Table: msdos
Disk Flags:
Number Start End Size Type File system Flags
1 2.00MiB 4095MiB 4093MiB primary
This will also attach a new loop device at /dev/loop0p1:
root #ls -l "/dev/loop0"*brw-rw---- 1 root disk 7, 0 Apr 12 12:33 /dev/loop0
brw-rw---- 1 root disk 259, 0 Apr 12 12:33 /dev/loop0p1
Set the boot flag:
root #parted "/dev/loop0" set 1 boot on
All partition flags can be found in the column Flags:
root #parted "/dev/loop0" "unit mib print"Model: Loopback device (loopback)
Disk /dev/loop0: 4096MiB
Sector size (logical/physical): 512B/512B
Partition Table: msdos
Disk Flags:
Number Start End Size Type File system Flags
1 2.00MiB 4095MiB 4093MiB primary boot
Create the ext4 filesystem, which was declared via parted earlier:
WarningMake absolutely sure to select the correct loop device, since this may overwrite an existing partition; resulting in data loss, if the overwritten partition cannot be recovered.
root #mkfs.ext4 "/dev/loop0p1"mke2fs 1.47.2 (1-Jan-2025)
Discarding device blocks: done
Creating filesystem with 1047808 4k blocks and 262144 inodes
Filesystem UUID: 0e344af7-6f7b-4d27-8238-89d46a5920d6
Superblock backups stored on blocks:
32768, 98304, 163840, 229376, 294912, 819200, 884736
Allocating group tables: done
Writing inode tables: done
Creating journal (16384 blocks): done
Writing superblocks and filesystem accounting information: done
Mount it at /mnt/:
root #mount "/dev/loop0p1" "/mnt/"
root #df --human-readable --print-type "/mnt/"Filesystem Type Size Used Avail Use% Mounted on
/dev/loop0p1 ext4 3.9G 24K 3.7G 1% /mnt
Create the directories /mnt/boot/grub, which will be used by grub later:
root #mkdir --parents --verbose "/mnt/boot/grub"mkdir: created directory '/mnt/boot'
mkdir: created directory '/mnt/boot/grub'
Install grub on the loop device and advice it to install its files to /mnt/boot/grub/:
root #grub-install --target="i386-pc" --boot-directory="/mnt/boot/" "/dev/loop0"
root #tree -F "/mnt/boot/grub/"/mnt/boot/grub/
├── fonts/
│   └── unicode.pf2
├── grubenv
├── i386-pc/
│   ├── acpi.mod
│   ├── adler32.mod
│   ├── affs.mod
│   ├── afs.mod
│   ├── afsplitter.mod
│   ├── ahci.mod
│   ├── all_video.mod
│   ├── aout.mod
│   ├── archelp.mod
│   ├── ata.mod
[...]
Unmount the filesystem and detach the loop device:
root #umount "/mnt/"
root #losetup --detach "/dev/loop0"
If the loop device is still busy - for example, processes are still accessing /mnt/ - no error will be returned. This can be verified and solved with the following commands:
root #losetup --listNAME SIZELIMIT OFFSET AUTOCLEAR RO BACK-FILE DIO LOG-SEC
/dev/loop0 0 0 0 0 /home/larry/qemu/my-systems-disk-image.img 0 512
root #lsof | grep "/mnt"sleep 31813 root cwd DIR 259,0 4096 131074 /mnt/boot/grub
root #kill -SIGTERM 31813
This is sufficient to boot into a grub2 boot prompt. This is can be used as the basis for a bootable system.
CPU selection[edit]
QEMU CPU selections have additional support for "accelerators," like kvm (Kernel Virtual Machine) or tcg (Tiny Code Generator) or Xen (wikip[1]).
The accelerator can usually only "accelerate" the features that are available on the host CPU.
So the selection of the CPU affects the performance.
To get a list of CPUs:
user $qemu-system-x86_64 -cpu helpAvailable CPUs:
x86 486 (alias configured by machine type)
x86 486-v1
x86 Broadwell (alias configured by machine type)
x86 Broadwell-IBRS (alias of Broadwell-v3)
x86 Broadwell-noTSX (alias of Broadwell-v2)
x86 Broadwell-noTSX-IBRS (alias of Broadwell-v4)
x86 Broadwell-v1 Intel Core Processor (Broadwell)
x86 Broadwell-v2 Intel Core Processor (Broadwell, no TSX)
x86 Broadwell-v3 Intel Core Processor (Broadwell, IBRS)
x86 Broadwell-v4 Intel Core Processor (Broadwell, no TSX, IBRS)
x86 Cascadelake-Server (alias configured by machine type)
x86 Cascadelake-Server-noTSX (alias of Cascadelake-Server-v3)
x86 Cascadelake-Server-v1 Intel Xeon Processor (Cascadelake)
x86 Cascadelake-Server-v2 Intel Xeon Processor (Cascadelake) [ARCH_CAPABILITIES]
x86 Cascadelake-Server-v3 Intel Xeon Processor (Cascadelake) [ARCH_CAPABILITIES, no TSX]
x86 Cascadelake-Server-v4 Intel Xeon Processor (Cascadelake) [ARCH_CAPABILITIES, no TSX]
x86 Cascadelake-Server-v5 Intel Xeon Processor (Cascadelake) [ARCH_CAPABILITIES, EPT switching, XSAVES, no TSX]
x86 Conroe (alias configured by machine type)
x86 Conroe-v1 Intel Celeron_4x0 (Conroe/Merom Class Core 2)
x86 Cooperlake (alias configured by machine type)
x86 Cooperlake-v1 Intel Xeon Processor (Cooperlake)
x86 Cooperlake-v2 Intel Xeon Processor (Cooperlake) [XSAVES]
x86 Denverton (alias configured by machine type)
x86 Denverton-v1 Intel Atom Processor (Denverton)
x86 Denverton-v2 Intel Atom Processor (Denverton) [no MPX, no MONITOR]
x86 Denverton-v3 Intel Atom Processor (Denverton) [XSAVES, no MPX, no MONITOR]
x86 Dhyana (alias configured by machine type)
x86 Dhyana-v1 Hygon Dhyana Processor
x86 Dhyana-v2 Hygon Dhyana Processor [XSAVES]
x86 EPYC (alias configured by machine type)
x86 EPYC-IBPB (alias of EPYC-v2)
x86 EPYC-Milan (alias configured by machine type)
x86 EPYC-Milan-v1 AMD EPYC-Milan Processor
x86 EPYC-Rome (alias configured by machine type)
x86 EPYC-Rome-v1 AMD EPYC-Rome Processor
x86 EPYC-Rome-v2 AMD EPYC-Rome Processor
x86 EPYC-v1 AMD EPYC Processor
x86 EPYC-v2 AMD EPYC Processor (with IBPB)
x86 EPYC-v3 AMD EPYC Processor
x86 Haswell (alias configured by machine type)
x86 Haswell-IBRS (alias of Haswell-v3)
x86 Haswell-noTSX (alias of Haswell-v2)
x86 Haswell-noTSX-IBRS (alias of Haswell-v4)
x86 Haswell-v1 Intel Core Processor (Haswell)
x86 Haswell-v2 Intel Core Processor (Haswell, no TSX)
x86 Haswell-v3 Intel Core Processor (Haswell, IBRS)
x86 Haswell-v4 Intel Core Processor (Haswell, no TSX, IBRS)
x86 Icelake-Server (alias configured by machine type)
x86 Icelake-Server-noTSX (alias of Icelake-Server-v2)
x86 Icelake-Server-v1 Intel Xeon Processor (Icelake)
x86 Icelake-Server-v2 Intel Xeon Processor (Icelake) [no TSX]
x86 Icelake-Server-v3 Intel Xeon Processor (Icelake)
x86 Icelake-Server-v4 Intel Xeon Processor (Icelake)
x86 Icelake-Server-v5 Intel Xeon Processor (Icelake) [XSAVES]
x86 Icelake-Server-v6 Intel Xeon Processor (Icelake) [5-level EPT]
x86 IvyBridge (alias configured by machine type)
x86 IvyBridge-IBRS (alias of IvyBridge-v2)
x86 IvyBridge-v1 Intel Xeon E3-12xx v2 (Ivy Bridge)
x86 IvyBridge-v2 Intel Xeon E3-12xx v2 (Ivy Bridge, IBRS)
x86 KnightsMill (alias configured by machine type)
x86 KnightsMill-v1 Intel Xeon Phi Processor (Knights Mill)
x86 Nehalem (alias configured by machine type)
x86 Nehalem-IBRS (alias of Nehalem-v2)
x86 Nehalem-v1 Intel Core i7 9xx (Nehalem Class Core i7)
x86 Nehalem-v2 Intel Core i7 9xx (Nehalem Core i7, IBRS update)
x86 Opteron_G1 (alias configured by machine type)
x86 Opteron_G1-v1 AMD Opteron 240 (Gen 1 Class Opteron)
x86 Opteron_G2 (alias configured by machine type)
x86 Opteron_G2-v1 AMD Opteron 22xx (Gen 2 Class Opteron)
x86 Opteron_G3 (alias configured by machine type)
x86 Opteron_G3-v1 AMD Opteron 23xx (Gen 3 Class Opteron)
x86 Opteron_G4 (alias configured by machine type)
x86 Opteron_G4-v1 AMD Opteron 62xx class CPU
x86 Opteron_G5 (alias configured by machine type)
x86 Opteron_G5-v1 AMD Opteron 63xx class CPU
x86 Penryn (alias configured by machine type)
x86 Penryn-v1 Intel Core 2 Duo P9xxx (Penryn Class Core 2)
x86 SandyBridge (alias configured by machine type)
x86 SandyBridge-IBRS (alias of SandyBridge-v2)
x86 SandyBridge-v1 Intel Xeon E312xx (Sandy Bridge)
x86 SandyBridge-v2 Intel Xeon E312xx (Sandy Bridge, IBRS update)
x86 Skylake-Client (alias configured by machine type)
x86 Skylake-Client-IBRS (alias of Skylake-Client-v2)
x86 Skylake-Client-noTSX-IBRS (alias of Skylake-Client-v3)
x86 Skylake-Client-v1 Intel Core Processor (Skylake)
x86 Skylake-Client-v2 Intel Core Processor (Skylake, IBRS)
x86 Skylake-Client-v3 Intel Core Processor (Skylake, IBRS, no TSX)
x86 Skylake-Client-v4 Intel Core Processor (Skylake, IBRS, no TSX) [IBRS, XSAVES, no TSX]
x86 Skylake-Server (alias configured by machine type)
x86 Skylake-Server-IBRS (alias of Skylake-Server-v2)
x86 Skylake-Server-noTSX-IBRS (alias of Skylake-Server-v3)
x86 Skylake-Server-v1 Intel Xeon Processor (Skylake)
x86 Skylake-Server-v2 Intel Xeon Processor (Skylake, IBRS)
x86 Skylake-Server-v3 Intel Xeon Processor (Skylake, IBRS, no TSX)
x86 Skylake-Server-v4 Intel Xeon Processor (Skylake, IBRS, no TSX)
x86 Skylake-Server-v5 Intel Xeon Processor (Skylake, IBRS, no TSX) [IBRS, XSAVES, EPT switching, no TSX]
x86 Snowridge (alias configured by machine type)
x86 Snowridge-v1 Intel Atom Processor (SnowRidge)
x86 Snowridge-v2 Intel Atom Processor (Snowridge, no MPX)
x86 Snowridge-v3 Intel Atom Processor (Snowridge, no MPX) [XSAVES, no MPX]
x86 Snowridge-v4 Intel Atom Processor (Snowridge, no MPX) [no split lock detect, no core-capability]
x86 Westmere (alias configured by machine type)
x86 Westmere-IBRS (alias of Westmere-v2)
x86 Westmere-v1 Westmere E56xx/L56xx/X56xx (Nehalem-C)
x86 Westmere-v2 Westmere E56xx/L56xx/X56xx (IBRS update)
x86 athlon (alias configured by machine type)
x86 athlon-v1 QEMU Virtual CPU version 2.5+
x86 core2duo (alias configured by machine type)
x86 core2duo-v1 Intel(R) Core(TM)2 Duo CPU T7700 @ 2.40GHz
x86 coreduo (alias configured by machine type)
x86 coreduo-v1 Genuine Intel(R) CPU T2600 @ 2.16GHz
x86 kvm32 (alias configured by machine type)
x86 kvm32-v1 Common 32-bit KVM processor
x86 kvm64 (alias configured by machine type)
x86 kvm64-v1 Common KVM processor
x86 n270 (alias configured by machine type)
x86 n270-v1 Intel(R) Atom(TM) CPU N270 @ 1.60GHz
x86 pentium (alias configured by machine type)
x86 pentium-v1
x86 pentium2 (alias configured by machine type)
x86 pentium2-v1
x86 pentium3 (alias configured by machine type)
x86 pentium3-v1
x86 phenom (alias configured by machine type)
x86 phenom-v1 AMD Phenom(tm) 9550 Quad-Core Processor
x86 qemu32 (alias configured by machine type)
x86 qemu32-v1 QEMU Virtual CPU version 2.5+
x86 qemu64 (alias configured by machine type)
x86 qemu64-v1 QEMU Virtual CPU version 2.5+
x86 base base CPU model type with no features enabled
x86 host processor with all supported host features
x86 max Enables all features supported by the accelerator in the current host
Recognized CPUID flags:
3dnow 3dnowext 3dnowprefetch abm ace2 ace2-en acpi adx aes amd-no-ssb
amd-ssbd amd-stibp amx-bf16 amx-int8 amx-tile apic arat arch-capabilities
arch-lbr avic avx avx-vnni avx2 avx512-4fmaps avx512-4vnniw avx512-bf16
avx512-fp16 avx512-vp2intersect avx512-vpopcntdq avx512bitalg avx512bw
avx512cd avx512dq avx512er avx512f avx512ifma avx512pf avx512vbmi
avx512vbmi2 avx512vl avx512vnni bmi1 bmi2 bus-lock-detect cid cldemote
clflush clflushopt clwb clzero cmov cmp-legacy core-capability cr8legacy
cx16 cx8 dca de decodeassists ds ds-cpl dtes64 erms est extapic f16c
flushbyasid fma fma4 fpu fsgsbase fsrm full-width-write fxsr fxsr-opt
gfni hle ht hypervisor ia64 ibpb ibrs ibrs-all ibs intel-pt intel-pt-lip
invpcid invtsc kvm-asyncpf kvm-asyncpf-int kvm-hint-dedicated kvm-mmu
kvm-msi-ext-dest-id kvm-nopiodelay kvm-poll-control kvm-pv-eoi kvm-pv-ipi
kvm-pv-sched-yield kvm-pv-tlb-flush kvm-pv-unhalt kvm-steal-time kvmclock
kvmclock kvmclock-stable-bit la57 lahf-lm lbrv lm lwp mca mce md-clear
mds-no misalignsse mmx mmxext monitor movbe movdir64b movdiri mpx msr
mtrr nodeid-msr npt nrip-save nx osvw pae pat pause-filter pbe pcid
pclmulqdq pcommit pdcm pdpe1gb perfctr-core perfctr-nb pfthreshold pge
phe phe-en pks pku pmm pmm-en pn pni popcnt pschange-mc-no pse pse36
rdctl-no rdpid rdrand rdseed rdtscp rsba rtm sep serialize sgx sgx-debug
sgx-exinfo sgx-kss sgx-mode64 sgx-provisionkey sgx-tokenkey sgx1 sgx2
sgxlc sha-ni skinit skip-l1dfl-vmentry smap smep smx spec-ctrl
split-lock-detect ss ssb-no ssbd sse sse2 sse4.1 sse4.2 sse4a ssse3 stibp
svm svm-lock svme-addr-chk syscall taa-no tbm tce tm tm2 topoext tsc
tsc-adjust tsc-deadline tsc-scale tsx-ctrl tsx-ldtrk umip v-vmsave-vmload
vaes vgif virt-ssbd vmcb-clean vme vmx vmx-activity-hlt
vmx-activity-shutdown vmx-activity-wait-sipi vmx-apicv-register
vmx-apicv-vid vmx-apicv-x2apic vmx-apicv-xapic vmx-cr3-load-noexit
vmx-cr3-store-noexit vmx-cr8-load-exit vmx-cr8-store-exit vmx-desc-exit
vmx-encls-exit vmx-entry-ia32e-mode vmx-entry-load-bndcfgs
vmx-entry-load-efer vmx-entry-load-pat vmx-entry-load-perf-global-ctrl
vmx-entry-load-pkrs vmx-entry-load-rtit-ctl vmx-entry-noload-debugctl
vmx-ept vmx-ept-1gb vmx-ept-2mb vmx-ept-advanced-exitinfo
vmx-ept-execonly vmx-eptad vmx-eptp-switching vmx-exit-ack-intr
vmx-exit-clear-bndcfgs vmx-exit-clear-rtit-ctl vmx-exit-load-efer
vmx-exit-load-pat vmx-exit-load-perf-global-ctrl vmx-exit-load-pkrs
vmx-exit-nosave-debugctl vmx-exit-save-efer vmx-exit-save-pat
vmx-exit-save-preemption-timer vmx-flexpriority vmx-hlt-exit vmx-ins-outs
vmx-intr-exit vmx-invept vmx-invept-all-context vmx-invept-single-context
vmx-invept-single-context vmx-invept-single-context-noglobals
vmx-invlpg-exit vmx-invpcid-exit vmx-invvpid vmx-invvpid-all-context
vmx-invvpid-single-addr vmx-io-bitmap vmx-io-exit vmx-monitor-exit
vmx-movdr-exit vmx-msr-bitmap vmx-mtf vmx-mwait-exit vmx-nmi-exit
vmx-page-walk-4 vmx-page-walk-5 vmx-pause-exit vmx-ple vmx-pml
vmx-posted-intr vmx-preemption-timer vmx-rdpmc-exit vmx-rdrand-exit
vmx-rdseed-exit vmx-rdtsc-exit vmx-rdtscp-exit vmx-secondary-ctls
vmx-shadow-vmcs vmx-store-lma vmx-true-ctls vmx-tsc-offset
vmx-tsc-scaling vmx-unrestricted-guest vmx-vintr-pending vmx-vmfunc
vmx-vmwrite-vmexit-fields vmx-vnmi vmx-vnmi-pending vmx-vpid
vmx-wbinvd-exit vmx-xsaves vmx-zero-len-inject vpclmulqdq waitpkg
wbnoinvd wdt x2apic xcrypt xcrypt-en xfd xgetbv1 xop xsave xsavec
xsaveerptr xsaveopt xsaves xstore xstore-en xtpr
Show the available accelerators:
user $qemu-system-x86_64 -accel helpAccelerators supported in QEMU binary:
tcg
kvm
hvf
whpx
haxm
Starting QEMU[edit]
This is how to start a virtual machine with the same feature set as the host CPU, a raw disk image and 2 GB of RAM.
By default, a VNC server is started that runs without password protection and listens on the loop interface.
QEMU is advised to listen on a local UNIX socket with the following command:
user $qemu-system-x86_64 -vnc "unix:/run/user/$(id --user)/qemu-vnc.sock" -enable-kvm -cpu host -drive "file=/home/larry/qemu/my-systems-disk-image.img,format=raw" -m 2G
WarningSet the file permissions appropriately to protect the VNC server from unauthorized access! If the virtual machine is started with the parameter -vnc :0, it will listen on port 5900 (first display) on all interfaces without password protection!
NoteA CD-ROM installation or boot medium can be added via the parameter -cdrom. For example: -cdrom filename.iso
Connecting to the virtual machine via VNC[edit]
In order to connect to the VNC server, the command vncviewer, which comes from the package net-misc/tigervnc, can be used:
user $vncviewer "/run/user/$(id --user)/qemu-vnc.sock"TigerVNC viewer v1.15.0
Built on: 2025-05-13 12:30
Copyright (C) 1999-2025 TigerVNC team and many others (see README.rst)
See https://www.tigervnc.org for information on TigerVNC.
Tue May 13 14:44:36 2025
DecodeManager: Detected 4 CPU core(s)
DecodeManager: Creating 4 decoder thread(s)
CConn: Connected to socket /run/user/1000/qemu-vnc.sock
CConnection: Server supports RFB protocol version 3.8
CConnection: Using RFB protocol version 3.8
CConnection: Choosing security type None(1)
CConn: Using pixel format depth 24 (32bpp) little-endian rgb888
CConn: SetDesktopSize failed: 3
This will open a separate window, where one gets greeted with a GRUB shell, which was installed via grub-install earlier:
Troubleshooting[edit]
qemu-system-x86_64: CPU model 'host' requires KVM or HVF[edit]
When trying to start a virtual machine, using the parameter -cpu host, one may encounter the following error:
CODE CPU model 'host' requires KVM or HVF qemu-system-x86_64: CPU model 'host' requires KVM or HVF
In order to fix this, use the parameter -enable-kvm, which will enable KVM full virtualization support:
user $qemu-system-x86_64 -cpu host -enable-kvm [...]
"kvm: already loaded the other module"[edit]
Sometimes during the early boot splash, the error message "kvm: already loaded the other module" can be seen. This message indicates both the Intel and the AMD kernel virtual machine settings have been enabled in the kernel. To fix this, enable it as a module or disable either the Intel or AMD KVM option specific to the system's processor in the kernel configuration. For example, if the system has an Intel processor, enable the Intel KVM, and then make sure the AMD KVM is set as a module (M) or is disabled (N). The relevant options to enable or disable can be found in the kernel's .config file via the CONFIG_KVM_INTEL and CONFIG_KVM_AMD variables or in the configuration section above.
Creating TUN/TAP device - No such file or directory[edit]
Sometimes this error can occur if TUN/TAP support cannot be found in the kernel. To solve this, try loading the driver:
root #modprobe tun
If that works, add this to a file in /etc/modules-load.d/ to load on startup:
FILE /etc/modules-load.d/qemu-modules.conf tun
Configuration does not support video model 'qxl'[edit]
This is usually the case if QEMU is not built with the spice USE flag. To resolve this issue, try to build QEMU with the correct USE flag.
First add spice to via a package.use file:
FILE /etc/portage/package.use/qemu app-emulation/qemu spice
Then rebuild the package:
root #emerge --ask app-emulation/qemu
My qemu has kvm support on some guest architectures[edit]
KVM works only for the same architecture. An ARM64 host cannot handle x86_64 instructions.
Invalid context errors on SELinux systems[edit]
By default, Libvirt generates a random SELinux MCS label for the QEMU process when it is started. If the loaded SELinux policy does not support MCS categories, the resulting security context will be invalid:
CODE SELinux error from virt-manager Error starting domain: unable to set socket security context 'system_u:system_r:svirt_t:s0:c123,c456': Invalid argument
CODE SELinux error from the kernel kernel: SELinux: Context system_u:object_r:svirt_image_t:s0:c123,c456 is not valid (left unmapped).
The solution is either to switch to one of the policy types which supports MCS categories or manually set the virtual machine's security labels, without MCS categories:
CODE Libvirt domain XML with manually specified seclabel fields <domain type="kvm">
<name>fedora</name>
...
<devices>
<disk type="file" device="disk">
<driver name="qemu" type="qcow2"/>
<source file="/var/lib/libvirt/images/fedora.qcow2">
<seclabel model='selinux' relabel='yes'>
<label>system_u:object_r:svirt_image_t</label>
</seclabel>
</source>
<target dev="vda" bus="virtio"/>
<address type="pci" domain="0x0000" bus="0x04" slot="0x00" function="0x0"/>
</disk>
...
<seclabel type='static' model='selinux' relabel='yes'>
<label>system_u:system_r:svirt_t</label>
</seclabel>
</domain>
Static-user and LTO[edit]
GCC will use a huge amount of RAM when LTO is enabled on the system if any of the ppc64 options are enabled while using the static-user flag; because of this, it is recommended to disable LTO while compiling in this configuration or use Clang if LTO is required. See bug #883419
lto1: internal compiler error: original not compressed with zstd[edit]
This is caused by a mismatch of GCC used to compile zlib and glib to the one being used to compile qemu, this can be fixed by rebuilding both before compiling qemu again.
root #emerge --ask sys-libs/zlib dev-libs/glib
Windows guests fail to provision, boot, or Blue Screen of Death (BSOD) on startup[edit]
For optimal performance, it is recommended that modern Windows guests be run under a kernel with CONFIG_KVM_HYPERV enabled. As an additional benefit, if this option is not enabled, on some hardware, VMs will fail to provision, to boot, or present with a BSOD.
The technical reasons for this are as follows: later versions of Windows, when running as virtual machines, sometimes attempt to access hardware registers (specifically, Model Specific Registers or MSRs) that are not actually defined for the emulated processor within the virtual environment. This is often due to how Windows interacts with hardware, a driver trying to be overly clever, or even bugs within the operating system itself. While these MSR accesses might be valid on physical processors, the virtualized environment presented by KVM may not support them.
KVM's default behavior is to attempt to emulate these MSR accesses, but when encountering an undefined register, it reports an "invalid instruction" error to the virtual Windows instance. This error is often fatal, resulting in a BSOD and halting the virtual machine.
Tipunhandled rdmsr or unhandled wrmsr messages in the system logs of the host indicate attempts to access undefined MSRs. Failures may also be more obvious, like failed to set MSR and Assertion `ret == cpu->kvm_msr_buf->nmsrs' failed from qemu-system-*.
An alternative is passing the option kvm.ignore_msrs=1 on the kernel command line or as an option to the KVM module:
FILE /etc/modprobe.d/kvm.conf options kvm ignore_msrs=1
The ignore_msrs option instructs KVM to ignore any attempts by the virtual Windows machine to access these undefined MSRs. Instead of generating an error and causing a BSOD, KVM silently bypasses the problematic instruction. This allows Windows to continue running, albeit potentially with some minor performance implications or masked underlying issues.
TipWhile ignore_msrs can be a quick fix for BSODs related to MSR access (not all BSODs are!), it is likely that this can be addressed properly by enabling the appropriate kernel option, as documented above.This option should only need to be set if there are still undefined MSRs (and if there are it's probably a bug that needs to be reported to the software vendor or KVM/QEMU upstream).
Removal[edit]
There may be image files left behind after the removal of the QEMU package.
Unmerge[edit]
root #emerge --ask --depclean --verbose app-emulation/qemu
See also[edit]
Comparison of virtual machines — compares the features of several platform virtual machines.
Fast Virtio VM — explains a way to build a blazing fast Gentoo VM under KVM using Virtio and mdev.
GPU passthrough with virt-manager, QEMU, and KVM — directly present an internal PCI GPU as-is for direct use by a virtual machine
QEMU with Open vSwitch network
Virtualization — the concept and technique that permits running software in an environment separate from a computer operating system.
QEMU/Front-ends — facilitate VM management and use
Libvirt — a virtualization management toolkit
Libvirt/QEMU_networking — details the setup of Gentoo networking by Libvirt for use by guest containers and QEMU-based virtual machines.
Libvirt/QEMU_guest — creation of a guest domain (virtual machine, VM), running inside a QEMU hypervisor, using tools found in libvirt package.
Virt-manager — lightweight GUI application designed for managing virtual machines and containers via the libvirt API.
Virt-manager/QEMU_guest — creation of a guest virtual machine (VM) running inside a QEMU hypervisor using just the virt-manager GUI tool.
QEMU/Linux guest — describes the setup of a Gentoo Linux guest in QEMU using Gentoo bootable media.
QEMU/Bridge with Wifi Routing
Category:QEMU Guests
Remote_desktop — a guide to remote desktop software on Gentoo
External resources[edit]
https://www.linux-kvm.org/page/KvmOnGentoo - The Gentoo article on the KVM wiki
https://wiki.qemu.org/Main_Page - The Official QEMU wiki
References[edit]
↑ https://en.wikipedia.org/wiki/Full_virtualization
↑ https://developer.apple.com/documentation/hypervisor
↑ https://en.wikipedia.org/wiki/Paravirtualization
↑ https://github.com/RceNinja/notes/blob/master/notes/build_qemu_with_enabled_hyper-v_acceleration_(whpx)_on_windows.md
↑ https://en.wikipedia.org/wiki/Paravirtualization
↑ QEMU / KVM CPU model configuration
↑ https://github.com/intel/haxm
↑ https://en.wikipedia.org/wiki/Paravirtualization
↑ https://forums.gentoo.org/viewtopic-p-8157704.html
↑ https://wiki.gentoo.org/wiki//etc/portage/make.conf#USE_EXPAND
↑ https://www.qemu.org/docs/master/system/qemu-block-drivers.html#cmdoption-qcow2-arg-nocow' |
Parsed HTML source of the new revision (new_html) | '<div class="mw-parser-output"><p><br />
</p>
<div id="infobox-stack" class="list-group" style="width: 25em; float: right; clear: right; font-size: 90%; margin-left: 1em;">
<div class="list-group-item text-center" style="padding-top: 3px; padding-bottom: 3px; background-color: #463C65; color: white;"><b>Resources</b></div>
<div id="infobox" class="list-group-item" style="display: flex; align-items: center; padding: 5px; min-height: 3em;"><span style="display: inline-block; width: 3em; overflow: hidden; text-align: center;"><span class="fa fa-home fa-fw fa-2x"></span></span><span><a rel="nofollow" class="external text" href="https://www.qemu.org/docs/master/index.html">Home</a></span></div>
<div id="infobox" class="list-group-item" style="display: flex; align-items: center; padding: 5px; min-height: 3em;"><span style="display: inline-block; width: 3em; overflow: hidden; text-align: center;"><span class="fa fa-file-text fa-fw fa-2x"></span></span><span><a rel="nofollow" class="external text" href="https://www.qemu.org/docs/master/index.html">Official documentation</a></span></div>
<div id="infobox" class="list-group-item" style="display: flex; align-items: center; padding: 5px; min-height: 3em;"><span style="display: inline-block; width: 3em; overflow: hidden; text-align: center;"><span class="fa fa-wikipedia-w fa-fw fa-2x"></span></span><span><a href="https://en.wikipedia.org/wiki/QEMU" class="extiw" title="wikipedia:QEMU">Wikipedia</a></span></div>
<div id="infobox" class="list-group-item" style="display: flex; align-items: center; padding: 5px; min-height: 3em;"><span style="display: inline-block; width: 3em; overflow: hidden; text-align: center;"><span class="fa fa-hdd-o fa-fw fa-2x"></span></span><span><a rel="nofollow" class="external text" href="https://packages.gentoo.org/packages/app-emulation/qemu">Package information</a></span></div>
<div id="infobox" class="list-group-item" style="display: flex; align-items: center; padding: 5px; min-height: 3em;"><span style="display: inline-block; width: 3em; overflow: hidden; text-align: center;"><span class="fa fa-gitlab fa-fw fa-2x"></span></span><span><a rel="nofollow" class="external text" href="https://gitlab.com/qemu-project/qemu">GitLab</a></span></div>
<div id="infobox" class="list-group-item" style="display: flex; align-items: center; padding: 5px; min-height: 3em;"><span style="display: inline-block; width: 3em; overflow: hidden; text-align: center;"><span class="fa fa-wikipedia-w fa-fw fa-2x"></span></span><span><a rel="nofollow" class="external text" href="https://wiki.qemu.org/Main_Page">Official project wiki</a></span></div>
<div id="infobox" class="list-group-item" style="display: flex; align-items: center; padding: 5px; min-height: 3em;"><span style="display: inline-block; width: 3em; overflow: hidden; text-align: center;"><span class="fa fa-bug fa-fw fa-2x"></span></span><span><a rel="nofollow" class="external text" href="https://gitlab.com/groups/qemu-project/-/issues">Bugs (upstream)</a></span></div>
<div id="infobox" class="list-group-item" style="display: flex; align-items: center; padding: 5px; min-height: 3em;"><span style="display: inline-block; width: 3em; overflow: hidden; text-align: center;"><span class="fa fa-rss fa-fw fa-2x"></span></span><span><a rel="nofollow" class="external text" href="https://www.qemu.org/blog/">Blog</a></span></div>
<div id="infobox" class="list-group-item" style="display: flex; align-items: center; padding: 5px; min-height: 3em;"><span style="display: inline-block; width: 3em; overflow: hidden; text-align: center;"><img alt="Ohloh Logo" src="/images/thumb/c/c1/Ohloh-logo.png/30px-Ohloh-logo.png" decoding="async" width="30" height="30" srcset="/images/c/c1/Ohloh-logo.png 1.5x" /></span><span><a rel="nofollow" class="external text" href="https://www.openhub.net/p/qemu">Open Hub</a></span></div>
</div>
<p><b>QEMU</b> (<b>Q</b>uick <b>EMU</b>lator) is a generic, open-source hardware emulator and virtualization suite.
</p>
<div id="toc" class="toc" role="navigation" aria-labelledby="mw-toc-heading"><input type="checkbox" role="button" id="toctogglecheckbox" class="toctogglecheckbox" style="display:none" /><div class="toctitle" lang="en" dir="ltr"><h2 id="mw-toc-heading">Contents</h2><span class="toctogglespan"><label class="toctogglelabel" for="toctogglecheckbox"></label></span></div>
<ul>
<li class="toclevel-1 tocsection-1"><a href="#Introduction"><span class="tocnumber">1</span> <span class="toctext">Introduction</span></a></li>
<li class="toclevel-1 tocsection-2"><a href="#Installation"><span class="tocnumber">2</span> <span class="toctext">Installation</span></a>
<ul>
<li class="toclevel-2 tocsection-3"><a href="#BIOS_and_UEFI_firmware"><span class="tocnumber">2.1</span> <span class="toctext">BIOS and UEFI firmware</span></a></li>
<li class="toclevel-2 tocsection-4"><a href="#Kernel"><span class="tocnumber">2.2</span> <span class="toctext">Kernel</span></a>
<ul>
<li class="toclevel-3 tocsection-5"><a href="#Physical_CPU_processor_support_-_Host"><span class="tocnumber">2.2.1</span> <span class="toctext">Physical CPU processor support - Host</span></a></li>
<li class="toclevel-3 tocsection-6"><a href="#Processor_Support"><span class="tocnumber">2.2.2</span> <span class="toctext">Processor Support</span></a></li>
<li class="toclevel-3 tocsection-7"><a href="#Handling_kernel_config_at_CLI"><span class="tocnumber">2.2.3</span> <span class="toctext">Handling kernel config at CLI</span></a></li>
<li class="toclevel-3 tocsection-8"><a href="#Networking"><span class="tocnumber">2.2.4</span> <span class="toctext">Networking</span></a></li>
<li class="toclevel-3 tocsection-9"><a href="#Intel_VT-g_.28integrated_graphics_adapter_virtualization.29"><span class="tocnumber">2.2.5</span> <span class="toctext"><span>Intel VT-g</span> (integrated graphics adapter virtualization)</span></a></li>
</ul>
</li>
<li class="toclevel-2 tocsection-10"><a href="#USE_flags"><span class="tocnumber">2.3</span> <span class="toctext">USE flags</span></a>
<ul>
<li class="toclevel-3 tocsection-11"><a href="#USE_EXPAND"><span class="tocnumber">2.3.1</span> <span class="toctext">USE_EXPAND</span></a></li>
</ul>
</li>
<li class="toclevel-2 tocsection-12"><a href="#Emerge"><span class="tocnumber">2.4</span> <span class="toctext">Emerge</span></a></li>
</ul>
</li>
<li class="toclevel-1 tocsection-13"><a href="#Configuration"><span class="tocnumber">3</span> <span class="toctext">Configuration</span></a>
<ul>
<li class="toclevel-2 tocsection-14"><a href="#Environment_variables"><span class="tocnumber">3.1</span> <span class="toctext">Environment variables</span></a></li>
<li class="toclevel-2 tocsection-15"><a href="#Files"><span class="tocnumber">3.2</span> <span class="toctext">Files</span></a>
<ul>
<li class="toclevel-3 tocsection-16"><a href="#Single_File"><span class="tocnumber">3.2.1</span> <span class="toctext">Single File</span></a></li>
<li class="toclevel-3 tocsection-17"><a href="#Image_File"><span class="tocnumber">3.2.2</span> <span class="toctext">Image File</span></a></li>
</ul>
</li>
<li class="toclevel-2 tocsection-18"><a href="#Additional_software"><span class="tocnumber">3.3</span> <span class="toctext">Additional software</span></a></li>
</ul>
</li>
<li class="toclevel-1 tocsection-19"><a href="#Usage"><span class="tocnumber">4</span> <span class="toctext">Usage</span></a>
<ul>
<li class="toclevel-2 tocsection-20"><a href="#Invocation"><span class="tocnumber">4.1</span> <span class="toctext">Invocation</span></a></li>
<li class="toclevel-2 tocsection-21"><a href="#Permissions"><span class="tocnumber">4.2</span> <span class="toctext">Permissions</span></a></li>
<li class="toclevel-2 tocsection-22"><a href="#Creation_of_a_disk_image"><span class="tocnumber">4.3</span> <span class="toctext">Creation of a disk image</span></a></li>
<li class="toclevel-2 tocsection-23"><a href="#Preparation_of_a_bootable_disk_image_from_scratch"><span class="tocnumber">4.4</span> <span class="toctext">Preparation of a bootable disk image from scratch</span></a></li>
<li class="toclevel-2 tocsection-24"><a href="#CPU_selection"><span class="tocnumber">4.5</span> <span class="toctext">CPU selection</span></a></li>
<li class="toclevel-2 tocsection-25"><a href="#Starting_QEMU"><span class="tocnumber">4.6</span> <span class="toctext">Starting QEMU</span></a></li>
<li class="toclevel-2 tocsection-26"><a href="#Connecting_to_the_virtual_machine_via_VNC"><span class="tocnumber">4.7</span> <span class="toctext">Connecting to the virtual machine via VNC</span></a></li>
</ul>
</li>
<li class="toclevel-1 tocsection-27"><a href="#Troubleshooting"><span class="tocnumber">5</span> <span class="toctext">Troubleshooting</span></a>
<ul>
<li class="toclevel-2 tocsection-28"><a href="#qemu-system-x86_64:_CPU_model_.27host.27_requires_KVM_or_HVF"><span class="tocnumber">5.1</span> <span class="toctext">qemu-system-x86_64: CPU model 'host' requires KVM or HVF</span></a></li>
<li class="toclevel-2 tocsection-29"><a href="#.22kvm:_already_loaded_the_other_module.22"><span class="tocnumber">5.2</span> <span class="toctext">"kvm: already loaded the other module"</span></a></li>
<li class="toclevel-2 tocsection-30"><a href="#Creating_TUN.2FTAP_device_-_No_such_file_or_directory"><span class="tocnumber">5.3</span> <span class="toctext">Creating TUN/TAP device - No such file or directory</span></a></li>
<li class="toclevel-2 tocsection-31"><a href="#Configuration_does_not_support_video_model_.27qxl.27"><span class="tocnumber">5.4</span> <span class="toctext">Configuration does not support video model 'qxl'</span></a></li>
<li class="toclevel-2 tocsection-32"><a href="#My_qemu_has_kvm_support_on_some_guest_architectures"><span class="tocnumber">5.5</span> <span class="toctext">My qemu has kvm support on some guest architectures</span></a></li>
<li class="toclevel-2 tocsection-33"><a href="#Invalid_context_errors_on_SELinux_systems"><span class="tocnumber">5.6</span> <span class="toctext">Invalid context errors on SELinux systems</span></a></li>
<li class="toclevel-2 tocsection-34"><a href="#Static-user_and_LTO"><span class="tocnumber">5.7</span> <span class="toctext">Static-user and LTO</span></a></li>
<li class="toclevel-2 tocsection-35"><a href="#lto1:_internal_compiler_error:_original_not_compressed_with_zstd"><span class="tocnumber">5.8</span> <span class="toctext">lto1: internal compiler error: original not compressed with zstd</span></a></li>
<li class="toclevel-2 tocsection-36"><a href="#Windows_guests_fail_to_provision.2C_boot.2C_or_Blue_Screen_of_Death_.28BSOD.29_on_startup"><span class="tocnumber">5.9</span> <span class="toctext">Windows guests fail to provision, boot, or Blue Screen of Death (BSOD) on startup</span></a></li>
</ul>
</li>
<li class="toclevel-1 tocsection-37"><a href="#Removal"><span class="tocnumber">6</span> <span class="toctext">Removal</span></a>
<ul>
<li class="toclevel-2 tocsection-38"><a href="#Unmerge"><span class="tocnumber">6.1</span> <span class="toctext">Unmerge</span></a></li>
</ul>
</li>
<li class="toclevel-1 tocsection-39"><a href="#See_also"><span class="tocnumber">7</span> <span class="toctext">See also</span></a></li>
<li class="toclevel-1 tocsection-40"><a href="#External_resources"><span class="tocnumber">8</span> <span class="toctext">External resources</span></a></li>
<li class="toclevel-1 tocsection-41"><a href="#References"><span class="tocnumber">9</span> <span class="toctext">References</span></a></li>
</ul>
</div>
<h2><span class="mw-headline" id="Introduction">Introduction</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=1" title="Edit section: Introduction">edit</a><span class="mw-editsection-bracket">]</span></span></h2>
<p>QEMU is a <i>hardware emulator and virtualization tool</i>, which runs on a <i>host OS platforms</i>. Inside a virtual machine, QEMU can emulate <i>multiple operating systems</i>; it can also emulate <i>embedded systems</i>.
</p><p>QEMU supports <i>32+ kinds of CPUs</i>. It emulates <i>nearly all</i> the opcodes of these CPUs.
</p><p>QEMU has several plugins: <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">Accelerator</span> is one of them. This plugin allows execution directly by the host CPU. When using an <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">accelerator</span>, QEMU executes CPU instructions the <i>fastest</i>.
</p><p>QEMU is a <a href="https://en.wikipedia.org/wiki/Hypervisor#Classification" class="extiw" title="wikipedia:Hypervisor"><span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">Type-2 hypervisor</span></a>, which runs within <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">user namespace</span> and performs virtual hardware emulation.
</p>
<ul><li>Firstly, QEMU is a <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">type 2 hypervisor</span>.</li>
<li>QEMU can be paired with <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">KVM</span> to run VMs at <i>near-native speed</i>. This is accomplished by using hardware extensions such as: <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">Intel VT-x</span> or <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">AMD-V</span>.</li>
<li>It can then emulate <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">user-level processes</span>, which allow applications, compiled for one architecture, to run on a different one.</li>
<li>There are multiple operating modes: <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">user-mode emulation</span>, <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">system emulation</span>, <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">KVM hosting</span> and <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">Xen hosting</span>.</li>
<li>QEMU can <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">save</span> and <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">restore</span> the state of virtual machines of all its running programs.</li>
<li>QEMU virtual machines can interface with many types of physical host hardware, such as, but not limited to, <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">CD-ROM drives</span>, <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">USB devices</span>, <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">audio interfaces</span>, <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">hard disks</span> and <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">network cards</span>.</li>
<li>Virtual disk image defaults to the <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">qcow2</span> format. This format only uses as much host disk space as the guest OS <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">grows</span> to use. Using the <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">snapshot method</span>, the guest OS can <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">revert</span> back to its desired state in time.</li>
<li>It does <i>not depend</i> on graphical output methods on the host system, instead, making use of an integrated <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">VNC server</span> to access the screen of the guest OS.</li>
<li>QEMU on a host CPU can execute multiple virtual CPUs <i>in parallel</i>.</li></ul>
<p><br />
QEMU has support for several <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">accelerator plug-ins</span>:
</p>
<table class="table table-striped table-condensed sortable">
<tbody><tr>
<th>Virtualizer
</th>
<th>Accelerator
</th>
<th>Virtualization type
</th>
<th>Description
</th>
<th>Gentoo package name
</th></tr>
<tr>
<td><span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">qemu</span>
</td>
<td><span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">tcg</span>
</td>
<td><span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">full<sup id="cite_ref-1" class="reference"><a href="#cite_note-1">[1]</a></sup>/software-emulation</span>
</td>
<td>QEMU's own <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">Tiny Code Generator</span>. This is the <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">default</span>. More frequently denoted as <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">qemu</span> and not <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">qemu/tcg</span> so often.
</td>
<td><span style="white-space: nowrap;" class="plainlinks" title="External link to https://packages.gentoo.org for the app-emulation/qemu package."><a rel="nofollow" class="external text" href="https://packages.gentoo.org/packages/app-emulation/qemu"><span style="font-family: monospace; font-size: 95%; color: MidnightBlue;">app-emulation/qemu</span></a><span style="color: grey; margin-left: 0.1em; font-size: 70%;" class="fa fa-hdd-o fa-fw"></span></span>
</td></tr>
<tr>
<td><span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">qemu</span>
</td>
<td><span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">hvf</span><sup id="cite_ref-2" class="reference"><a href="#cite_note-2">[2]</a></sup>
</td>
<td><span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">paravirtualization</span><sup id="cite_ref-3" class="reference"><a href="#cite_note-3">[3]</a></sup>
</td>
<td>Apple's Hypervisor framework based on <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">Intel VT</span>.
</td>
<td>
</td></tr>
<tr>
<td><span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">qemu</span>
</td>
<td><span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">whpx</span><sup id="cite_ref-4" class="reference"><a href="#cite_note-4">[4]</a></sup>
</td>
<td><span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">hybrid</span>
</td>
<td>Microsoft's Windows Hypervisor Platform based on <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">Intel VT</span> or <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">AMD-V</span>.
</td>
<td>
</td></tr>
<tr>
<td><span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">qemu</span>
</td>
<td><span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">kvm</span>
</td>
<td><span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">paravirtualization</span><sup id="cite_ref-5" class="reference"><a href="#cite_note-5">[5]</a></sup>
</td>
<td>Linux <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">Type-2 Hypervisor</span>. This is the common choice for hosts using <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">amd64</span>, <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">arm64</span>, or <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">mips</span><sup id="cite_ref-6" class="reference"><a href="#cite_note-6">[6]</a></sup>. Supports Microsoft Windows.
</td>
<td><span style="white-space: nowrap;" class="plainlinks" title="External link to https://packages.gentoo.org for the app-emulation/qemu package."><a rel="nofollow" class="external text" href="https://packages.gentoo.org/packages/app-emulation/qemu"><span style="font-family: monospace; font-size: 95%; color: MidnightBlue;">app-emulation/qemu</span></a><span style="color: grey; margin-left: 0.1em; font-size: 70%;" class="fa fa-hdd-o fa-fw"></span></span>
</td></tr>
<tr>
<td><span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">qemu</span>
</td>
<td><span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">haxm</span><sup id="cite_ref-7" class="reference"><a href="#cite_note-7">[7]</a></sup><b></b>
</td>
<td><span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">paravirtualization</span><sup id="cite_ref-8" class="reference"><a href="#cite_note-8">[8]</a></sup>
</td>
<td><span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">Intel VT</span>, by Intel Corporation.
</td>
<td>
</td></tr></tbody></table>
<p>QEMU, if used in conjunction with an <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">accelerator</span>, becomes a <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">Type-1 hypervisor</span>, which runs in <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">Kernel namespace</span>. This allows a <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">user namespace program</span> access to the<span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator"> hardware virtualization features</span> of various processors. Such an <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">accelerator</span> can be <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">KVM</span> (<b>K</b>ernel-based <b>V</b>irtual <b>M</b>achine) or <a href="/wiki/Xen" title="Xen">Xen</a>.
</p><p>If <i>no accelerator</i> is used, QEMU will run entirely in <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">user namespace</span>, using its <i>built-in</i> binary translator <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">TCG (Tiny Code Generator)</span>. Using QEMU without an accelerator is <i>relatively inefficient and slow</i>.
</p>
<div class="alert alert-info gw-box" style="padding-top: 8px; padding-bottom: 8px;"><strong><i class="fa fa-sticky-note-o fa-rotate-180"></i> Note</strong><br />This article typically uses <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">KVM</span> as the <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">accelerator</span> of choice, due to its GPL licensing and availability. Without <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">KVM</span>, nearly all commands described here, will still work (unless <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">KVM-specific</span>).</div>
<p>The following sub-articles provide detailed instructions on QEMU <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">configurations</span> and <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">options</span>:
</p>
<ul><li><a href="/wiki/QEMU/Bridge_with_Wifi_Routing" title="QEMU/Bridge with Wifi Routing">QEMU/Bridge with Wifi Routing</a></li>
<li><a href="/wiki/QEMU/KVM_IPv6_Support" title="QEMU/KVM IPv6 Support">QEMU/KVM IPv6 Support</a> — describes IPv6 support in QEMU/KVM.</li>
<li><a href="/wiki/QEMU/Linux_guest" title="QEMU/Linux guest">QEMU/Linux guest</a> — describes the setup of a Gentoo Linux guest in <a class="mw-selflink selflink">QEMU</a> using Gentoo bootable media.</li>
<li><a href="/wiki/Virtiofs" title="Virtiofs">Virtiofs</a> — a shared file system that lets virtual machines access a directory tree on the host</li>
<li><a href="/wiki/QEMU/Options" title="QEMU/Options">QEMU/Options</a> — describes some of the options useful for configuring <a class="mw-selflink selflink">QEMU</a> virtual machines.</li>
<li><a href="/wiki/QEMU/OS2WarpV3_guest" title="QEMU/OS2WarpV3 guest">QEMU/OS2WarpV3 guest</a></li>
<li><a href="/wiki/QEMU/Windows_guest" title="QEMU/Windows guest">QEMU/Windows guest</a> — setup of a Windows guest using <a class="mw-selflink selflink">QEMU</a></li></ul>
<p><br />
</p>
<h2><span class="mw-headline" id="Installation">Installation</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=2" title="Edit section: Installation">edit</a><span class="mw-editsection-bracket">]</span></span></h2>
<h3><span class="mw-headline" id="BIOS_and_UEFI_firmware">BIOS and UEFI firmware</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=3" title="Edit section: BIOS and UEFI firmware">edit</a><span class="mw-editsection-bracket">]</span></span></h3>
<p>In order to utilize <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">KVM</span>, either <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">Vt-x</span> (<code>vmx</code>) or <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">AMD-V</span> (<code>svm</code>) must be supported by the processor. <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">Vt-x</span> or <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">AMD-V</span> are Intel's and AMD's respective technologies for permitting multiple operating systems to concurrently execute operations on the processors.
</p><p>To inspect hardware for virtualization support, issue the following command:
</p>
<div class="cmd-box"><div><code style="color: #4E9A06; user-select: none; font-weight: bold;">user <span style="color:royalblue;">$</span></code><code>grep --color --extended-regexp "vmx|svm" "/proc/cpuinfo"</code></div></div>
<div class="alert alert-warning gw-box" style="padding-top: 8px; padding-bottom: 8px;"><strong><i class="fa fa-exclamation-circle"></i> Important</strong><br />For a period, manufacturers were shipping with virtualization <b>turned off</b> by default in the system's firmware. Toggling this feature in the firmware may require <b>full removal of power</b> from the system to take effect. If restarting the system does not work, try <b>shutting down, unplugging the system, and pressing the power button in an unplugged state</b> to discharge any residual energy from the <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">power supply unit</span> (<span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">PSU</span>). Reapply power to the system to verify the configuration.</div>
<p>If <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">KVM</span> support is available, there should be a <code>kvm</code> device listed at <span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">/dev/kvm</span>. This will take effect <i>after</i> the system has booted to a KVM-enabled kernel.
</p><p><br />
</p>
<h3><span class="mw-headline" id="Kernel">Kernel</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=4" title="Edit section: Kernel">edit</a><span class="mw-editsection-bracket">]</span></span></h3>
<p>Described below are the basic requirements for <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">KVM kernel configuration</span> for the host OS. A more complete and up-to-date list can be found at the <a rel="nofollow" class="external text" href="http://www.linux-kvm.org/page/Tuning_Kernel">KVM Tuning Kernel</a> page.
</p>
<div class="alert alert-info gw-box" style="padding-top: 8px; padding-bottom: 8px;"><strong><i class="fa fa-sticky-note-o fa-rotate-180"></i> Note</strong><br />Different guest (virtualized) OS may require additional kernel options. These are covered in the corresponding <a href="/wiki/QEMU#Usage" title="QEMU">Usage</a> section.</div>
<div class="box-caption"><span class="label" style="margin-right: .5em; background-color: #4E9A06">KERNEL</span> <strong>Enable high resolution timer support (<var>CONFIG_HIGH_RES_TIMERS</var>)</strong></div> <div class="mw-highlight mw-highlight-lang-text mw-content-ltr" dir="ltr"><pre><span></span>General setup --->
Timers subsystem --->
<*> High Resolution Timer Support
</pre></div>
<div class="alert alert-info gw-box" style="padding-top: 8px; padding-bottom: 8px;"><strong><i class="fa fa-sticky-note-o fa-rotate-180"></i> Note</strong><br />This includes support for <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">ARM64 processors</span>.</div>
<h4><span class="mw-headline" id="Physical_CPU_processor_support_-_Host">Physical CPU processor support - Host</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=5" title="Edit section: Physical CPU processor support - Host">edit</a><span class="mw-editsection-bracket">]</span></span></h4>
<p>If <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">KVM</span> support is not available, insert <var>CONFIG_KVM=y</var> into the <span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">/usr/src/linux/.config</span> and rebuild/reinstall the kernel (and its initramfs image). Come back here after the host is rebooted.
</p>
<div class="box-caption"><span class="label" style="margin-right: .5em; background-color: #4E9A06">KERNEL</span> <strong>Enable KVM Support (<var>CONFIG_KVM</var>)</strong></div> <div class="mw-highlight mw-highlight-lang-text mw-content-ltr" dir="ltr"><pre><span></span>[*] Virtualization --->
<*> Kernel-based Virtual Machine (KVM) support
</pre></div>
<div class="alert alert-info gw-box" style="padding-top: 8px; padding-bottom: 8px;"><strong><i class="fa fa-sticky-note-o fa-rotate-180"></i> Note</strong><br />This includes support for <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">ARM64 processors</span>.</div>
<h4><span class="mw-headline" id="Processor_Support">Processor Support</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=6" title="Edit section: Processor Support">edit</a><span class="mw-editsection-bracket">]</span></span></h4>
<div class="box-caption"><span class="label" style="margin-right: .5em; background-color: #4E9A06">KERNEL</span> <strong>Enable KVM support for Intel processors (<var>CONFIG_KVM_INTEL</var>)</strong></div> <div class="mw-highlight mw-highlight-lang-text mw-content-ltr" dir="ltr"><pre><span></span>[*] Virtualization --->
<M> KVM for Intel processors support
</pre></div>
<div class="box-caption"><span class="label" style="margin-right: .5em; background-color: #4E9A06">KERNEL</span> <strong>Enable KVM support for AMD processors (<var>CONFIG_KVM_AMD</var>)</strong></div> <div class="mw-highlight mw-highlight-lang-text mw-content-ltr" dir="ltr"><pre><span></span>[*] Virtualization --->
<M> KVM for AMD processors support
</pre></div>
<div class="alert alert-danger gw-box" style="padding-top: 8px; padding-bottom: 8px;"><strong><i class="fa fa-exclamation-triangle"></i> Warning</strong><br />If <i>both</i> <b>KVM support for Intel processors</b> <i>and</i> <b>KVM support for AMD processors</b> are set to be built into the kernel (<code>*</code>), an error message will be returned by <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">kprint</span> at early boot. Since the system can only have one processor type: <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">Intel</span> <i>or</i> <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">AMD</span>. Enabling <i>one</i> or <i>both</i> options as <i>modules</i> (<code>M</code>) will solve this issue.</div>
<h4><span class="mw-headline" id="Handling_kernel_config_at_CLI">Handling kernel config at CLI</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=7" title="Edit section: Handling kernel config at CLI">edit</a><span class="mw-editsection-bracket">]</span></span></h4>
<p>To set the various kernel configuration settings from the command lines, the <span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">linux/scripts/kconfig/merge_config.sh</span> shall be used here:
</p><p><b>Mandatory kernel configuration options to set</b>:
</p>
<div class="box-caption"><span class="label" style="margin-right: .5em; background-color: #54487A">FILE</span> <strong><code style="border: none; background: none; color: #54487A; margin-right: .5em;">/usr/src/kernel-kconfig-qemu-host.config</code></strong><strong></strong></div> <div class="mw-highlight mw-highlight-lang-text mw-content-ltr" dir="ltr"><pre><span></span>CONFIG_VIRTUALIZATION=y
CONFIG_KVM=y
CONFIG_KVM_INTEL=y
CONFIG_KVM_AMD=y
</pre></div>
<div class="cmd-box"><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>cd "/usr/src/linux"
</code></div><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>"./scripts/kconfig/merge_config.sh" ".config" "/usr/src/kernel-kconfig-qemu-host.config"
</code></div></div>
<p><i>Useful</i> kernel configuration options to use:
</p>
<div class="box-caption"><span class="label" style="margin-right: .5em; background-color: #54487A">FILE</span> <strong><code style="border: none; background: none; color: #54487A; margin-right: .5em;">/usr/src/kernel-kconfig-qemu-host-optional.config</code></strong><strong></strong></div> <div class="mw-highlight mw-highlight-lang-text mw-content-ltr" dir="ltr"><pre><span></span>CONFIG_VHOST_NET=y
CONFIG_HIGH_RES_TIMER=y
CONFIG_HPET=y
CONFIG_COMPACTION=y
CONFIG_MIGRATION=y
CONFIG_KSM=y
CONFIG_SYSFS=y
CONFIG_PROC_FS=y
CONFIG_TRANSPARENT_HUGEPAGE=y
CONFIG_CGROUPS=y
CONFIG_KVM_HYPERV=y
</pre></div>
<div class="cmd-box"><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>"./scripts/kconfig/merge_config.sh" ".config" "/usr/src/kernel-kconfig-qemu-host-optional.config"
</code></div></div>
<div class="alert alert-warning gw-box" style="padding-top: 8px; padding-bottom: 8px;"><strong><i class="fa fa-exclamation-circle"></i> Important</strong><br />Recent <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">Windows guests</span> (at least <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">Windows 10 22H2</span> and up) are <b>required</b> to set <code>CONFIG_KVM_HYPERV</code> (as per the optional configuration above). If this is <b>not</b> selected, VMs will fail to provision (or boot) with errors like: <code>Failed to set MSR</code> and <code>Assertion `ret == cpu->kvm_msr_buf->nmsrs' failed</code>.</div>
<h4><span class="mw-headline" id="Networking">Networking</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=8" title="Edit section: Networking">edit</a><span class="mw-editsection-bracket">]</span></span></h4>
<p>Accelerated networking, <b>required</b> for <code>vhost-net</code> USE flag (recommend):
</p>
<div class="box-caption"><span class="label" style="margin-right: .5em; background-color: #4E9A06">KERNEL</span> <strong>vhost-net kernel 5.7 and later (<var>CONFIG_VHOST_NET</var>)</strong></div> <div class="mw-highlight mw-highlight-lang-text mw-content-ltr" dir="ltr"><pre><span></span>Device Drivers --->
[*] VHOST drivers --->
<*> Host kernel accelerator for virtio net
</pre></div>
<div class="box-caption"><span class="label" style="margin-right: .5em; background-color: #4E9A06">KERNEL</span> <strong>vhost-net (before kernel 5.7)</strong></div> <div class="mw-highlight mw-highlight-lang-text mw-content-ltr" dir="ltr"><pre><span></span>[*] Virtualization --->
<*> Host kernel accelerator for virtio net
</pre></div>
<div class="box-caption"><span class="label" style="margin-right: .5em; background-color: #4E9A06">KERNEL</span> <strong>Optional advanced networking support (<var>CONFIG_NET_CORE</var>, <var>CONFIG_TUN</var>)</strong></div> <div class="mw-highlight mw-highlight-lang-text mw-content-ltr" dir="ltr"><pre><span></span>Device Drivers --->
[*] Network device support --->
[*] Network core driver support
<*> Universal TUN/TAP device driver support
</pre></div>
<p>Needed for <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">802.1d Ethernet bridging</span>:
</p>
<div class="box-caption"><span class="label" style="margin-right: .5em; background-color: #4E9A06">KERNEL</span> <strong>Enabling 802.1d Ethernet Bridging support (<var>CONFIG_IPV6</var>, <var>CONFIG_BRIDGE</var>)</strong></div> <div class="mw-highlight mw-highlight-lang-text mw-content-ltr" dir="ltr"><pre><span></span>[*] Networking support --->
Networking options --->
<*> The IPv6 protocol
<*> 802.1d Ethernet Bridging
</pre></div>
<h4><span id="Intel_VT-g_(integrated_graphics_adapter_virtualization)"></span><span class="mw-headline" id="Intel_VT-g_.28integrated_graphics_adapter_virtualization.29"><span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">Intel VT-g</span> (integrated graphics adapter virtualization)</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=9" title="Edit section: Intel VT-g (integrated graphics adapter virtualization)">edit</a><span class="mw-editsection-bracket">]</span></span></h4>
<p>Mediated device passthrough for Intel GPUs (<span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">Broadwell</span> to <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">Comet Lake</span>)<sup id="cite_ref-9" class="reference"><a href="#cite_note-9">[9]</a></sup>
</p>
<div class="box-caption"><span class="label" style="margin-right: .5em; background-color: #4E9A06">KERNEL</span> <strong>Intel VT-g (<var>CONFIG_VFIO_MDEV</var>, <var>CONFIG_DRM_I915_GVT</var>, <var>CONFIG_DRM_I915_GVT_KVMGT</var>)</strong></div> <div class="mw-highlight mw-highlight-lang-text mw-content-ltr" dir="ltr"><pre><span></span>Device Drivers --->
<*> VFIO Non-Privileged userspace driver framework
<*> Mediated device driver framework
Graphics Support --->
<*> Intel 8xx/9xx/G3x/G4x/HD Graphics
[*] Enable Intel GVT-g graphics virtualization host support
<*> Enable KVM host support Intel GVT-g graphics virtualization
</pre></div>
<p><br />
</p>
<h3><span class="mw-headline" id="USE_flags">USE flags</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=10" title="Edit section: USE flags">edit</a><span class="mw-editsection-bracket">]</span></span></h3>
<p>Some packages are aware of the <span style="font-family: monospace; font-size: 95%; color: MidnightBlue; white-space: nowrap;" class="plainlinks" title="External link to https://packages.gentoo.org for the qemu USE Flag."><a rel="nofollow" class="external text" href="https://packages.gentoo.org/useflags/qemu"><span style="color: MidnightBlue;">qemu</span></a><a href="/wiki/USE_flag" title="USE flag"><span style="color: grey; margin-left: 0.1em; font-size: 70% !important;" class="fa fa-flag-o fa-fw"></span></a></span> <a href="/wiki/USE_flag" title="USE flag">USE flag</a>.
</p><p>Review the possible USE flags for QEMU:
</p><p class="mw-empty-elt"> </p><div class="panel panel-default gp-panel">
<div class="panel-heading gp-panel-heading">
<h3 class="panel-title">
<span class="text-muted">USE flags for</span>
<a href="https://packages.gentoo.org/packages/app-emulation/qemu">app-emulation/qemu</a>
<small><span class="fa fa-external-link-square"></span></small>
<small class="gp-pkg-desc">QEMU + Kernel-based Virtual Machine userland tools</small>
</h3>
</div>
<div class="table-responsive gp-useflag-table-container">
<table class="table gp-useflag-table"> <tbody><tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/+aio">+aio</a></code>
</td>
<td>
Enables support for Linux's Async IO
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/+curl">+curl</a></code>
</td>
<td>
Support ISOs / -cdrom directives via HTTP or HTTPS.
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/+doc">+doc</a></code>
</td>
<td>
Add extra documentation (API, Javadoc, etc). It is recommended to enable per package instead of globally
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/+fdt">+fdt</a></code>
</td>
<td>
Enables firmware device tree support
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/+filecaps">+filecaps</a></code>
</td>
<td>
Use Linux file capabilities to control privilege rather than set*id (this is orthogonal to USE=caps which uses capabilities at runtime e.g. libcap)
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/+gnutls">+gnutls</a></code>
</td>
<td>
Enable TLS support for the VNC console server. For 1.4 and newer this also enables WebSocket support. For 2.0 through 2.3 also enables disk quorum support.
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/+jpeg">+jpeg</a></code>
</td>
<td>
Enable jpeg image support for the VNC console server
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/+oss">+oss</a></code>
</td>
<td>
Add support for OSS (Open Sound System)
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/+pin-upstream-blobs">+pin-upstream-blobs</a></code>
</td>
<td>
Pin the versions of BIOS firmware to the version included in the upstream release. This is needed to sanely support migration/suspend/resume/snapshotting/etc... of instances. When the blobs are different, random corruption/bugs/crashes/etc... may be observed.
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/+png">+png</a></code>
</td>
<td>
Enable png image support for the VNC console server
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/+seccomp">+seccomp</a></code>
</td>
<td>
Enable seccomp (secure computing mode) to perform system call filtering at runtime to increase security of programs
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/+slirp">+slirp</a></code>
</td>
<td>
Enable TCP/IP in hypervisor via net-libs/libslirp
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/+vhost-net">+vhost-net</a></code>
</td>
<td>
Enable accelerated networking using vhost-net, see https://www.linux-kvm.org/page/VhostNet
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/+vnc">+vnc</a></code>
</td>
<td>
Enable VNC (remote desktop viewer) support
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/X">X</a></code>
</td>
<td>
Add support for X11
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/accessibility">accessibility</a></code>
</td>
<td>
Adds support for braille displays using brltty
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/alsa">alsa</a></code>
</td>
<td>
Enable alsa output for sound emulation
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/bpf">bpf</a></code>
</td>
<td>
Enable eBPF support for RSS implementation.
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/bzip2">bzip2</a></code>
</td>
<td>
Enable bzip2 compression support
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/capstone">capstone</a></code>
</td>
<td>
Enable disassembly support with dev-libs/capstone
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/debug">debug</a></code>
</td>
<td>
Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Backtraces
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/fuse">fuse</a></code>
</td>
<td>
Enables FUSE block device export
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/glusterfs">glusterfs</a></code>
</td>
<td>
Enables GlusterFS cluster fileystem via sys-cluster/glusterfs
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/gtk">gtk</a></code>
</td>
<td>
Add support for x11-libs/gtk+ (The GIMP Toolkit)
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/infiniband">infiniband</a></code>
</td>
<td>
Enable Infiniband RDMA transport support
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/io-uring">io-uring</a></code>
</td>
<td>
Enable the use of io_uring for efficient asynchronous IO and system requests
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/iscsi">iscsi</a></code>
</td>
<td>
Enable direct iSCSI support via net-libs/libiscsi instead of indirectly via the Linux block layer that sys-block/open-iscsi does.
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/jack">jack</a></code>
</td>
<td>
Add support for the JACK Audio Connection Kit
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/jemalloc">jemalloc</a></code>
</td>
<td>
Use dev-libs/jemalloc for memory management
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/keyutils">keyutils</a></code>
</td>
<td>
Support Linux keyrings via sys-apps/keyutils
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/lzo">lzo</a></code>
</td>
<td>
Enable support for lzo compression
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/multipath">multipath</a></code>
</td>
<td>
Enable multipath persistent reservation passthrough via sys-fs/multipath-tools.
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/ncurses">ncurses</a></code>
</td>
<td>
Enable the ncurses-based console
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/nfs">nfs</a></code>
</td>
<td>
Enable NFS support
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/nls">nls</a></code>
</td>
<td>
Add Native Language Support (using gettext - GNU locale utilities)
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/numa">numa</a></code>
</td>
<td>
Enable NUMA support
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/opengl">opengl</a></code>
</td>
<td>
Add support for OpenGL (3D graphics)
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/pam">pam</a></code>
</td>
<td>
Add support for PAM (Pluggable Authentication Modules) - DANGEROUS to arbitrarily flip
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/pipewire">pipewire</a></code>
</td>
<td>
Enable pipewire output for sound emulation
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/plugins">plugins</a></code>
</td>
<td>
Enable qemu plugin API via shared library loading.
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/pulseaudio">pulseaudio</a></code>
</td>
<td>
Enable pulseaudio output for sound emulation
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/python">python</a></code>
</td>
<td>
Add optional support/bindings for the Python language
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/rbd">rbd</a></code>
</td>
<td>
Enable rados block device backend support, see https://docs.ceph.com/en/mimic/rbd/qemu-rbd/
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/sasl">sasl</a></code>
</td>
<td>
Add support for the Simple Authentication and Security Layer
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/sdl">sdl</a></code>
</td>
<td>
Enable the SDL-based console
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/sdl-image">sdl-image</a></code>
</td>
<td>
SDL Image support for icons
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/selinux">selinux</a></code>
</td>
<td>
!!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/smartcard">smartcard</a></code>
</td>
<td>
Enable smartcard support
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/snappy">snappy</a></code>
</td>
<td>
Enable support for Snappy compression (as implemented in app-arch/snappy)
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/spice">spice</a></code>
</td>
<td>
Enable Spice protocol support via app-emulation/spice
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/ssh">ssh</a></code>
</td>
<td>
Enable SSH based block device support via net-libs/libssh2
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/static">static</a></code>
</td>
<td>
Build the User and Software MMU (system) targets as well as tools as static binaries
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/static-user">static-user</a></code>
</td>
<td>
Build the User targets as static binaries
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/systemtap">systemtap</a></code>
</td>
<td>
Enable SystemTap/DTrace tracing
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/test">test</a></code>
</td>
<td>
Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/udev">udev</a></code>
</td>
<td>
Enable virtual/udev integration (device discovery, power and storage device support, etc)
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/usb">usb</a></code>
</td>
<td>
Enable USB passthrough via dev-libs/libusb
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/usbredir">usbredir</a></code>
</td>
<td>
Use sys-apps/usbredir to redirect USB devices to another machine over TCP
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/vde">vde</a></code>
</td>
<td>
Enable VDE-based networking
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/virgl">virgl</a></code>
</td>
<td>
Enable experimental Virgil 3d (virtual software GPU)
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/virtfs">virtfs</a></code>
</td>
<td>
Enable VirtFS via virtio-9p-pci / fsdev. See https://wiki.qemu.org/Documentation/9psetup
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/vte">vte</a></code>
</td>
<td>
Enable terminal support (x11-libs/vte) in the GTK+ interface
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/wayland">wayland</a></code>
</td>
<td>
Enable dev-libs/wayland backend
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/xattr">xattr</a></code>
</td>
<td>
Add support for getting and setting POSIX extended attributes, through sys-apps/attr. Requisite for the virtfs backend.
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/xdp">xdp</a></code>
</td>
<td>
Enable support for XDP through net-libs/xdp-tools
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/xen">xen</a></code>
</td>
<td>
Enables support for Xen backends
</td>
</tr> <tr>
<td>
<code><a href="https://packages.gentoo.org/useflags/zstd">zstd</a></code>
</td>
<td>
Enable support for ZSTD compression
</td>
</tr> </tbody></table>
</div>
<div class="panel-footer gp-panel-footer">
<small class="pull-right">
Data provided by the <a href="https://packages.gentoo.org">Gentoo Package Database</a>
·
Last update: 2025-05-07 18:40
</small>
<small>
<a href="/wiki/Handbook:AMD64/Working/USE">More information about USE flags</a>
</small>
</div>
</div>
<p class="mw-empty-elt"></p>
<div class="alert alert-info gw-box" style="padding-top: 8px; padding-bottom: 8px;"><strong><i class="fa fa-sticky-note-o fa-rotate-180"></i> Note</strong><br />More than one USE flag (<code>gtk</code>, <code>ncurses</code>, <code>sdl</code>, or <code>spice</code>) can be enabled for graphical output. If graphics are desired, it is generally recommended to enable more than one graphical USE flag.</div>
<div class="alert alert-info gw-box" style="padding-top: 8px; padding-bottom: 8px;"><strong><i class="fa fa-sticky-note-o fa-rotate-180"></i> Note</strong><br />If <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">virt-manager</span> is going to be used, be sure to enable the <code>usbredir</code> and <code>spice</code> USE flags on the qemu package for correct operation.</div>
<h4><span class="mw-headline" id="USE_EXPAND">USE_EXPAND</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=11" title="Edit section: USE EXPAND">edit</a><span class="mw-editsection-bracket">]</span></span></h4>
<p>Additional ebuild configuration are provided as the <i>USE_EXPAND</i> variables <var>QEMU_USER_TARGETS</var> and <var>QEMU_SOFTMMU_TARGETS</var>. See <span style="white-space: nowrap;" class="plainlinks" title="External link to https://packages.gentoo.org for the app-emulation/qemu package."><a rel="nofollow" class="external text" href="https://packages.gentoo.org/packages/app-emulation/qemu"><span style="font-family: monospace; font-size: 95%; color: MidnightBlue;">app-emulation/qemu</span></a><span style="color: grey; margin-left: 0.1em; font-size: 70%;" class="fa fa-hdd-o fa-fw"></span></span> for a list of all the available targets (there are many; most are very obscure and may be ignored; leaving these variables at their default values <i>will disable almost everything</i>, which is probably just fine for most users).
</p><p>For each target specified, a <code>qemu</code> executable will be built. A <code>softmmu</code> target is the standard qemu use-case of emulating an entire system (like <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">VirtualBox</span> or <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">VMWare</span>, but with optional support for emulating CPU hardware along with peripherals). <code>user</code> targets execute user-mode code only; the (somewhat ambitious) purpose of these targets, is to "magically" allow importing <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">user namespace Linux ELF binaries</span> from a different architecture into the native system (like <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">multilib</span>, without the need for a <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">software stack</span> or CPU capable of running it).
</p><p>In order to enable <var>QEMU_USER_TARGETS</var> and <var>QEMU_SOFTMMU_TARGETS</var>, one can set the variables globally in <span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">/etc/portage/make.conf</span>:
</p>
<div class="box-caption"><span class="label" style="margin-right: .5em; background-color: #54487A">FILE</span> <strong><code style="border: none; background: none; color: #54487A; margin-right: .5em;">/etc/portage/make.conf</code></strong><strong></strong></div> <div class="mw-highlight mw-highlight-lang-bash mw-content-ltr" dir="ltr"><pre><span></span><span class="nv">QEMU_SOFTMMU_TARGETS</span><span class="o">=</span><span class="s2">"arm x86_64 sparc"</span>
<span class="nv">QEMU_USER_TARGETS</span><span class="o">=</span><span class="s2">"x86_64"</span>
</pre></div>
<div class="alert alert-danger gw-box" style="padding-top: 8px; padding-bottom: 8px;"><strong><i class="fa fa-exclamation-triangle"></i> Warning</strong><br />Setting the <i>USE flags</i> globally in <span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">/etc/portage/make.conf</span> is discouraged, because of possible ordering issues in <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">Portage</span>.<sup id="cite_ref-10" class="reference"><a href="#cite_note-10">[10]</a></sup></div>
<p>Files in the directory <span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">/etc/portage/package.use</span> can be added. There are two equivalent syntaxes available:
</p><p>One is the traditional <i>USE flag</i> syntax:
</p>
<div class="box-caption"><span class="label" style="margin-right: .5em; background-color: #54487A">FILE</span> <strong><code style="border: none; background: none; color: #54487A; margin-right: .5em;">/etc/portage/package.use/qemu</code></strong><strong></strong></div> <div class="mw-highlight mw-highlight-lang-text mw-content-ltr" dir="ltr"><pre><span></span>app-emulation/qemu qemu_softmmu_targets_arm qemu_softmmu_targets_x86_64 qemu_softmmu_targets_sparc
app-emulation/qemu qemu_user_targets_x86_64
</pre></div>
<p>And the other, preferred one, is the <a href="/wiki//etc/portage/make.conf#USE_EXPAND" title="/etc/portage/make.conf"><var>USE_EXPAND</var></a> syntax:
</p>
<div class="box-caption"><span class="label" style="margin-right: .5em; background-color: #54487A">FILE</span> <strong><code style="border: none; background: none; color: #54487A; margin-right: .5em;">/etc/portage/package.use/qemu</code></strong><strong></strong></div> <div class="mw-highlight mw-highlight-lang-text mw-content-ltr" dir="ltr"><pre><span></span>app-emulation/qemu QEMU_SOFTMMU_TARGETS: arm x86_64 sparc QEMU_USER_TARGETS: x86_64
</pre></div>
<p><br />
</p>
<h3><span class="mw-headline" id="Emerge">Emerge</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=12" title="Edit section: Emerge">edit</a><span class="mw-editsection-bracket">]</span></span></h3>
<p>After reviewing and adding any desired USE flags, emerge <span style="white-space: nowrap;" class="plainlinks" title="External link to https://packages.gentoo.org for the app-emulation/qemu package."><a rel="nofollow" class="external text" href="https://packages.gentoo.org/packages/app-emulation/qemu"><span style="font-family: monospace; font-size: 95%; color: MidnightBlue;">app-emulation/qemu</span></a><span style="color: grey; margin-left: 0.1em; font-size: 70%;" class="fa fa-hdd-o fa-fw"></span></span>:
</p>
<div class="cmd-box"><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>emerge --ask app-emulation/qemu</code></div></div>
<p><br />
</p>
<h2><span class="mw-headline" id="Configuration">Configuration</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=13" title="Edit section: Configuration">edit</a><span class="mw-editsection-bracket">]</span></span></h2>
<p>The following sub-articles provide detailed instructions on QEMU configurations and options:
</p>
<ul><li><a href="/wiki/QEMU/Options" title="QEMU/Options">Usage options</a> - Contains common configuration options used with QEMU (graphics/display, networking, RAM, storage, processor, etc).</li>
<li><a href="/wiki/QEMU/Linux_guest" title="QEMU/Linux guest">QEMU/Linux guest</a> — describes the setup of a Gentoo Linux guest in <a class="mw-selflink selflink">QEMU</a> using Gentoo bootable media.</li>
<li><a href="/wiki/QEMU/Windows_guest" title="QEMU/Windows guest">QEMU/Windows guest</a> — setup of a Windows guest using <a class="mw-selflink selflink">QEMU</a></li>
<li><a href="/wiki/QEMU/OS2WarpV3_guest" title="QEMU/OS2WarpV3 guest">OS2WarpV3 guest</a> - Describes the configuration steps needed to setup a virtualized OS2WarpVs=3 guest with QEMU.</li></ul>
<h3><span class="mw-headline" id="Environment_variables">Environment variables</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=14" title="Edit section: Environment variables">edit</a><span class="mw-editsection-bracket">]</span></span></h3>
<ul><li><var>G_MESSAGES_DEBUG</var></li>
<li><var>LISTEN_FDS</var></li>
<li><var>LISTEN_PID</var></li>
<li><var>QEMU_AUDIO_DRV</var></li>
<li><var>QEMU_MODULE_DIR</var></li>
<li><var>XDG_RUNTIME_DIR</var></li></ul>
<h3><span class="mw-headline" id="Files">Files</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=15" title="Edit section: Files">edit</a><span class="mw-editsection-bracket">]</span></span></h3>
<p>Files that QEMU uses.
</p>
<h4><span class="mw-headline" id="Single_File">Single File</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=16" title="Edit section: Single File">edit</a><span class="mw-editsection-bracket">]</span></span></h4>
<ul><li><span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">/etc/libvirt/qemu.conf</span> - QEMU configuration file.</li>
<li><span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">/etc/libvirt/qemu-lockd.conf</span> - QEMU lock files</li>
<li><span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">/etc/libvirt/qemu-sanlock.conf</span> - QEMU SAN lock</li>
<li><span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">/etc/libvirt/qemu/<domain-name>.xml</span> - Domain XML setting for a virtual machine or container.</li>
<li><span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">/etc/libvirt/qemu/autostart/<domain-name>.xml</span> - Autostart this domain (virtual machine or container).</li>
<li><span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">/etc/libvirt/qemu/networks/<network-name>.xml</span> - Network XML setting file for a network connection</li>
<li><span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">/etc/libvirt/qemu/networks/autostart/<network-name>.xml</span> - Autostart this network connection.</li>
<li><span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">/var/lib/libvirt/qemu/channel/target/<domain-name>/<socket-file></span> - UNIX socket file for Libvertd daemon API</li>
<li><span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">/var/cache/libvirt/qemu/capabilities/<hash-value>.xml</span> - Host OS capabilities in XML format</li>
<li><span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">/var/lib/libvirt/qemu/checkpoint/</span></li>
<li><span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">/var/lib/libvirt/qemu/<domain-9-XXXX>/</span> - holds UNIX sockets and AES keys for this domain.</li>
<li><span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">/var/lib/libvirt/qemu/dump/</span></li>
<li><span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">/var/lib/libvirt/qemu/nvram/</span></li>
<li><span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">/var/lib/libvirt/qemu/ram/</span></li>
<li><span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">/var/lib/libvirt/qemu/save/</span> - holding directory of hibernation images</li>
<li><span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">/var/lib/libvirt/qemu/snapshot/</span> - holding directory of snapshots</li>
<li><span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">/var/run/libvirt/qemu</span> - various UNIX socket and PID files for the <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">libvirtd</span> daemon.</li></ul>
<h4><span class="mw-headline" id="Image_File">Image File</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=17" title="Edit section: Image File">edit</a><span class="mw-editsection-bracket">]</span></span></h4>
<p>QEMU supports the following disk image formats:
</p>
<ul><li>QEMU copy-on-write (<span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">.qcow2</span>, <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">.qed</span>, <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">.qcow</span>, <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">.cow</span>)</li>
<li>VirtualBox Virtual Disk Image (<span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">.vdi</span>)</li>
<li>CD/DVD (ISO-9660) images (<span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">.iso</span>)</li>
<li>Raw images (<span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">.img</span>), that guest OS can control</li>
<li>VFAT-16</li>
<li>VMware Virtual Machine Disk (<span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">.vmdk</span>)</li>
<li>Virtual PC Virtual Hard Disk (<span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">.vhd</span>)</li>
<li>Parallels disk image (<span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">.hdd</span>, <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">.hds</span>) – <b>Read-only</b></li>
<li>Apple macos Universal Disk Image Format (<span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">.dmg</span>) – <b>Read-only</b></li>
<li>Bochs – <b>Read-only</b></li>
<li>Linux cloop – <b>Read-only</b></li></ul>
<p><br />
</p>
<h3><span class="mw-headline" id="Additional_software">Additional software</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=18" title="Edit section: Additional software">edit</a><span class="mw-editsection-bracket">]</span></span></h3>
<p>User name <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">qemu</span> is required, defined by <span style="white-space: nowrap;" class="plainlinks" title="External link to https://packages.gentoo.org for the acct-user/qemu package."><a rel="nofollow" class="external text" href="https://packages.gentoo.org/packages/acct-user/qemu"><span style="font-family: monospace; font-size: 95%; color: MidnightBlue;">acct-user/qemu</span></a><span style="color: grey; margin-left: 0.1em; font-size: 70%;" class="fa fa-hdd-o fa-fw"></span></span> and evoked by <span style="white-space: nowrap;" class="plainlinks" title="External link to https://packages.gentoo.org for the sys-emulator/qemu package."><a rel="nofollow" class="external text" href="https://packages.gentoo.org/packages/sys-emulator/qemu"><span style="font-family: monospace; font-size: 95%; color: MidnightBlue;">sys-emulator/qemu</span></a><span style="color: grey; margin-left: 0.1em; font-size: 70%;" class="fa fa-hdd-o fa-fw"></span></span> package.
</p><p>Group name <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">qemu</span> is required, defined by <span style="white-space: nowrap;" class="plainlinks" title="External link to https://packages.gentoo.org for the acct-group/qemu package."><a rel="nofollow" class="external text" href="https://packages.gentoo.org/packages/acct-group/qemu"><span style="font-family: monospace; font-size: 95%; color: MidnightBlue;">acct-group/qemu</span></a><span style="color: grey; margin-left: 0.1em; font-size: 70%;" class="fa fa-hdd-o fa-fw"></span></span> and evoked by <span style="white-space: nowrap;" class="plainlinks" title="External link to https://packages.gentoo.org for the sys-emulator/qemu package."><a rel="nofollow" class="external text" href="https://packages.gentoo.org/packages/sys-emulator/qemu"><span style="font-family: monospace; font-size: 95%; color: MidnightBlue;">sys-emulator/qemu</span></a><span style="color: grey; margin-left: 0.1em; font-size: 70%;" class="fa fa-hdd-o fa-fw"></span></span> package.
</p><p><br />
To connect to the SPICE server of QEMU, a GUI client like <span style="white-space: nowrap;" class="plainlinks" title="External link to https://packages.gentoo.org for the net-misc/spice-gtk package."><a rel="nofollow" class="external text" href="https://packages.gentoo.org/packages/net-misc/spice-gtk"><span style="font-family: monospace; font-size: 95%; color: MidnightBlue;">net-misc/spice-gtk</span></a><span style="color: grey; margin-left: 0.1em; font-size: 70%;" class="fa fa-hdd-o fa-fw"></span></span> is required.
</p><p><br />
</p>
<h2><span class="mw-headline" id="Usage">Usage</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=19" title="Edit section: Usage">edit</a><span class="mw-editsection-bracket">]</span></span></h2>
<p>QEMU can be used in two ways, with GUI front ends and through the command line. The configuration of QEMU depends on which method is employed:
</p>
<ul><li>GUI (Front-End) - To make life easier, there are multiple user-friendly front ends to QEMU: See <a href="/wiki/QEMU/Front-ends" title="QEMU/Front-ends">Front-ends</a></li>
<li>CLI</li></ul>
<h3><span class="mw-headline" id="Invocation">Invocation</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=20" title="Edit section: Invocation">edit</a><span class="mw-editsection-bracket">]</span></span></h3>
<p>QEMU supports around 34 different CPU architectures. To find the desired architecture, list what is installed.
</p>
<div class="cmd-box"><div><code style="color: #4E9A06; user-select: none; font-weight: bold;">user <span style="color:royalblue;">$</span></code><code>ls /usr/bin/qemu-system-*</code></div><span class="mw-collapsible mw-collapsed"><pre>/usr/bin/qemu-system-aarch64 /usr/bin/qemu-system-mips /usr/bin/qemu-system-rx
/usr/bin/qemu-system-alpha /usr/bin/qemu-system-mips64 /usr/bin/qemu-system-s390x
/usr/bin/qemu-system-arm /usr/bin/qemu-system-mips64el /usr/bin/qemu-system-sh4
/usr/bin/qemu-system-avr /usr/bin/qemu-system-mipsel /usr/bin/qemu-system-sh4eb
/usr/bin/qemu-system-cris /usr/bin/qemu-system-nios2 /usr/bin/qemu-system-sparc
/usr/bin/qemu-system-hppa /usr/bin/qemu-system-or1k /usr/bin/qemu-system-sparc64
/usr/bin/qemu-system-i386 /usr/bin/qemu-system-ppc /usr/bin/qemu-system-tricore
/usr/bin/qemu-system-loongarch64 /usr/bin/qemu-system-ppc64 /usr/bin/qemu-system-x86_64
/usr/bin/qemu-system-m68k /usr/bin/qemu-system-ppc64le /usr/bin/qemu-system-x86_64-microvm
/usr/bin/qemu-system-microblaze /usr/bin/qemu-system-riscv32 /usr/bin/qemu-system-xtensa
/usr/bin/qemu-system-microblazeel /usr/bin/qemu-system-riscv64 /usr/bin/qemu-system-xtensaeb
</pre></span></div>
<div class="cmd-box"><div><code style="color: #4E9A06; user-select: none; font-weight: bold;">user <span style="color:royalblue;">$</span></code><code>qemu-system-x86_64 -help</code></div><span class="mw-collapsible mw-collapsed"><pre>QEMU emulator version 7.2.9 (Debian 1:7.2+dfsg-7+deb12u5)
Copyright (c) 2003-2022 Fabrice Bellard and the QEMU Project developers
usage: qemu-system-x86_64 [options] [disk_image]
'disk_image' is a raw hard disk image for IDE hard disk 0
Standard options:
-h or -help display this help and exit
-version display version information and exit
-machine [type=]name[,prop[=value][,...]]
selects emulated machine ('-machine help' for list)
property accel=accel1[:accel2[:...]] selects accelerator
supported accelerators are kvm, xen, hax, hvf, nvmm, whpx or tcg (default: tcg)
vmport=on|off|auto controls emulation of vmport (default: auto)
dump-guest-core=on|off include guest memory in a core dump (default=on)
mem-merge=on|off controls memory merge support (default: on)
aes-key-wrap=on|off controls support for AES key wrapping (default=on)
dea-key-wrap=on|off controls support for DEA key wrapping (default=on)
suppress-vmdesc=on|off disables self-describing migration (default=off)
nvdimm=on|off controls NVDIMM support (default=off)
memory-encryption=@var{} memory encryption object to use (default=none)
hmat=on|off controls ACPI HMAT support (default=off)
memory-backend='backend-id' specifies explicitly provided backend for main RAM (default=none)
cxl-fmw.0.targets.0=firsttarget,cxl-fmw.0.targets.1=secondtarget,cxl-fmw.0.size=size[,cxl-fmw.0.interleave-granularity=granularity]
sgx-epc.0.memdev=memid,sgx-epc.0.node=numaid
-cpu cpu select CPU ('-cpu help' for list)
-accel [accel=]accelerator[,prop[=value][,...]]
select accelerator (kvm, xen, hax, hvf, nvmm, whpx or tcg; use 'help' for a list)
igd-passthru=on|off (enable Xen integrated Intel graphics passthrough, default=off)
kernel-irqchip=on|off|split controls accelerated irqchip support (default=on)
kvm-shadow-mem=size of KVM shadow MMU in bytes
split-wx=on|off (enable TCG split w^x mapping)
tb-size=n (TCG translation block cache size)
dirty-ring-size=n (KVM dirty ring GFN count, default 0)
notify-vmexit=run|internal-error|disable,notify-window=n (enable notify VM exit and set notify window, x86 only)
thread=single|multi (enable multi-threaded TCG)
-smp [[cpus=]n][,maxcpus=maxcpus][,sockets=sockets][,dies=dies][,clusters=clusters][,cores=cores][,threads=threads]
set the number of initial CPUs to 'n' [default=1]
maxcpus= maximum number of total CPUs, including
offline CPUs for hotplug, etc
sockets= number of sockets on the machine board
dies= number of dies in one socket
clusters= number of clusters in one die
cores= number of cores in one cluster
threads= number of threads in one core
Note: Different machines may have different subsets of the CPU topology
parameters supported, so the actual meaning of the supported parameters
will vary accordingly. For example, for a machine type that supports a
three-level CPU hierarchy of sockets/cores/threads, the parameters will
sequentially mean as below:
sockets means the number of sockets on the machine board
cores means the number of cores in one socket
threads means the number of threads in one core
For a particular machine type board, an expected CPU topology hierarchy
can be defined through the supported sub-option. Unsupported parameters
can also be provided in addition to the sub-option, but their values
must be set as 1 in the purpose of correct parsing.
-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=node]
-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=node]
-numa dist,src=source,dst=destination,val=distance
-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]
-numa hmat-lb,initiator=node,target=node,hierarchy=memory|first-level|second-level|third-level,data-type=access-latency|read-latency|write-latency[,latency=lat][,bandwidth=bw]
-numa hmat-cache,node-id=node,size=size,level=level[,associativity=none|direct|complex][,policy=none|write-back|write-through][,line=size]
-add-fd fd=fd,set=set[,opaque=opaque]
Add 'fd' to fd 'set'
-set group.id.arg=value
set <arg> parameter for item <id> of type <group>
i.e. -set drive.$id.file=/path/to/image
-global driver.property=value
-global driver=driver,property=property,value=value
set a global default for a driver property
-boot [order=drives][,once=drives][,menu=on|off]
[,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]
'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)
'sp_name': the file's name that would be passed to bios as logo picture, if menu=on
'sp_time': the period that splash picture last if menu=on, unit is ms
'rb_timeout': the timeout before guest reboot when boot failed, unit is ms
-m [size=]megs[,slots=n,maxmem=size]
configure guest RAM
size: initial amount of guest memory
slots: number of hotplug slots (default: none)
maxmem: maximum amount of guest memory (default: none)
NOTE: Some architectures might enforce a specific granularity
-mem-path FILE provide backing storage for guest RAM
-mem-prealloc preallocate guest memory (use with -mem-path)
-k language use keyboard layout (for example 'fr' for French)
-audio-help show -audiodev equivalent of the currently specified audio settings
-audio [driver=]driver,model=value[,prop[=value][,...]]
specifies the audio backend and device to use;
apart from 'model', options are the same as for -audiodev.
use '-audio model=help' to show possible devices.
-audiodev [driver=]driver,id=id[,prop[=value][,...]]
specifies the audio backend to use
Use ``-audiodev help`` to list the available drivers
id= identifier of the backend
timer-period= timer period in microseconds
in|out.mixing-engine= use mixing engine to mix streams inside QEMU
in|out.fixed-settings= use fixed settings for host audio
in|out.frequency= frequency to use with fixed settings
in|out.channels= number of channels to use with fixed settings
in|out.format= sample format to use with fixed settings
valid values: s8, s16, s32, u8, u16, u32, f32
in|out.voices= number of voices to use
in|out.buffer-length= length of buffer in microseconds
-audiodev none,id=id,[,prop[=value][,...]]
dummy driver that discards all output
-audiodev alsa,id=id[,prop[=value][,...]]
in|out.dev= name of the audio device to use
in|out.period-length= length of period in microseconds
in|out.try-poll= attempt to use poll mode
threshold= threshold (in microseconds) when playback starts
-audiodev oss,id=id[,prop[=value][,...]]
in|out.dev= path of the audio device to use
in|out.buffer-count= number of buffers
in|out.try-poll= attempt to use poll mode
try-mmap= try using memory mapped access
exclusive= open device in exclusive mode
dsp-policy= set timing policy (0..10), -1 to use fragment mode
-audiodev pa,id=id[,prop[=value][,...]]
server= PulseAudio server address
in|out.name= source/sink device name
in|out.latency= desired latency in microseconds
-audiodev sdl,id=id[,prop[=value][,...]]
in|out.buffer-count= number of buffers
-audiodev sndio,id=id[,prop[=value][,...]]
-audiodev spice,id=id[,prop[=value][,...]]
-audiodev dbus,id=id[,prop[=value][,...]]
-audiodev wav,id=id[,prop[=value][,...]]
path= path of wav file to record
-device driver[,prop[=value][,...]]
add device (based on driver)
prop=value,... sets driver properties
use '-device help' to print all possible drivers
use '-device driver,help' to print all possible properties
-name string1[,process=string2][,debug-threads=on|off]
set the name of the guest
string1 sets the window title and string2 the process name
When debug-threads is enabled, individual threads are given a separate name
NOTE: The thread names are for debugging and not a stable API.
-uuid %08x-%04x-%04x-%04x-%012x
specify machine UUID
Block device options:
-fda/-fdb file use 'file' as floppy disk 0/1 image
-hda/-hdb file use 'file' as hard disk 0/1 image
-hdc/-hdd file use 'file' as hard disk 2/3 image
-cdrom file use 'file' as CD-ROM image
-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]
[,cache.direct=on|off][,cache.no-flush=on|off]
[,read-only=on|off][,auto-read-only=on|off]
[,force-share=on|off][,detect-zeroes=on|off|unmap]
[,driver specific parameters...]
configure a block backend
-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]
[,cache=writethrough|writeback|none|directsync|unsafe][,format=f]
[,snapshot=on|off][,rerror=ignore|stop|report]
[,werror=ignore|stop|report|enospc][,id=name]
[,aio=threads|native|io_uring]
[,readonly=on|off][,copy-on-read=on|off]
[,discard=ignore|unmap][,detect-zeroes=on|off|unmap]
[[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]
[[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]
[[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]
[[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]
[[,iops_size=is]]
[[,group=g]]
use 'file' as a drive image
-mtdblock file use 'file' as on-board Flash memory image
-sd file use 'file' as SecureDigital card image
-snapshot write to temporary files instead of disk image files
-fsdev local,id=id,path=path,security_model=mapped-xattr|mapped-file|passthrough|none
[,writeout=immediate][,readonly=on][,fmode=fmode][,dmode=dmode]
[[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]
[[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]
[[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]
[[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]
[[,throttling.iops-size=is]]
-fsdev proxy,id=id,socket=socket[,writeout=immediate][,readonly=on]
-fsdev proxy,id=id,sock_fd=sock_fd[,writeout=immediate][,readonly=on]
-fsdev synth,id=id
-virtfs local,path=path,mount_tag=tag,security_model=mapped-xattr|mapped-file|passthrough|none
[,id=id][,writeout=immediate][,readonly=on][,fmode=fmode][,dmode=dmode][,multidevs=remap|forbid|warn]
-virtfs proxy,mount_tag=tag,socket=socket[,id=id][,writeout=immediate][,readonly=on]
-virtfs proxy,mount_tag=tag,sock_fd=sock_fd[,id=id][,writeout=immediate][,readonly=on]
-virtfs synth,mount_tag=tag[,id=id][,readonly=on]
-iscsi [user=user][,password=password]
[,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE
[,initiator-name=initiator-iqn][,id=target-iqn]
[,timeout=timeout]
iSCSI session parameters
USB convenience options:
-usb enable on-board USB host controller (if not enabled by default)
-usbdevice name add the host or guest USB device 'name'
Display options:
-display spice-app[,gl=on|off]
-display sdl[,gl=on|core|es|off][,grab-mod=<mod>][,show-cursor=on|off]
[,window-close=on|off]
-display gtk[,full-screen=on|off][,gl=on|off][,grab-on-hover=on|off]
[,show-tabs=on|off][,show-cursor=on|off][,window-close=on|off]
[,show-menubar=on|off]
-display vnc=<display>[,<optargs>]
-display curses[,charset=<encoding>]
-display egl-headless[,rendernode=<file>]
-display dbus[,addr=<dbusaddr>]
[,gl=on|core|es|off][,rendernode=<file>]
-display none
select display backend type
The default display is equivalent to
"-display gtk"
-nographic disable graphical output and redirect serial I/Os to console
-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]
[,x509-key-file=<file>][,x509-key-password=<file>]
[,x509-cert-file=<file>][,x509-cacert-file=<file>]
[,x509-dh-key-file=<file>][,addr=addr]
[,ipv4=on|off][,ipv6=on|off][,unix=on|off]
[,tls-ciphers=<list>]
[,tls-channel=[main|display|cursor|inputs|record|playback]]
[,plaintext-channel=[main|display|cursor|inputs|record|playback]]
[,sasl=on|off][,disable-ticketing=on|off]
[,password=<string>][,password-secret=<secret-id>]
[,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]
[,jpeg-wan-compression=[auto|never|always]]
[,zlib-glz-wan-compression=[auto|never|always]]
[,streaming-video=[off|all|filter]][,disable-copy-paste=on|off]
[,disable-agent-file-xfer=on|off][,agent-mouse=[on|off]]
[,playback-compression=[on|off]][,seamless-migration=[on|off]]
[,gl=[on|off]][,rendernode=<file>]
enable spice
at least one of {port, tls-port} is mandatory
-portrait rotate graphical output 90 deg left (only PXA LCD)
-rotate <deg> rotate graphical output some deg left (only PXA LCD)
-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]
select video card type
-full-screen start in full screen
-vnc <display> shorthand for -display vnc=<display>
i386 target only:
-win2k-hack use it when installing Windows 2000 to avoid a disk full bug
-no-fd-bootchk disable boot signature checking for floppy disks
-no-acpi disable ACPI
-no-hpet disable HPET
-acpitable [sig=str][,rev=n][,oem_id=str][,oem_table_id=str][,oem_rev=n][,asl_compiler_id=str][,asl_compiler_rev=n][,{data|file}=file1[:file2]...]
ACPI table description
-smbios file=binary
load SMBIOS entry from binary file
-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]
[,uefi=on|off]
specify SMBIOS type 0 fields
-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]
[,uuid=uuid][,sku=str][,family=str]
specify SMBIOS type 1 fields
-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]
[,asset=str][,location=str]
specify SMBIOS type 2 fields
-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]
[,sku=str]
specify SMBIOS type 3 fields
-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]
[,asset=str][,part=str][,max-speed=%d][,current-speed=%d]
[,processor-id=%d]
specify SMBIOS type 4 fields
-smbios type=8[,external_reference=str][,internal_reference=str][,connector_type=%d][,port_type=%d]
specify SMBIOS type 8 fields
-smbios type=11[,value=str][,path=filename]
specify SMBIOS type 11 fields
-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]
[,asset=str][,part=str][,speed=%d]
specify SMBIOS type 17 fields
-smbios type=41[,designation=str][,kind=str][,instance=%d][,pcidev=str]
specify SMBIOS type 41 fields
Network options:
-netdev user,id=str[,ipv4=on|off][,net=addr[/mask]][,host=addr]
[,ipv6=on|off][,ipv6-net=addr[/int]][,ipv6-host=addr]
[,restrict=on|off][,hostname=host][,dhcpstart=addr]
[,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,domainname=domain]
[,tftp=dir][,tftp-server-name=name][,bootfile=f][,hostfwd=rule][,guestfwd=rule][,smb=dir[,smbserver=addr]]
configure a user mode network backend with ID 'str',
its DHCP server and optional services
-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]
[,br=bridge][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]
[,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]
[,poll-us=n]
configure a host TAP network backend with ID 'str'
connected to a bridge (default=br0)
use network scripts 'file' (default=/etc/qemu-ifup)
to configure it and 'dfile' (default=/etc/qemu-ifdown)
to deconfigure it
use '[down]script=no' to disable script execution
use network helper 'helper' (default=/usr/lib/qemu/qemu-bridge-helper) to
configure it
use 'fd=h' to connect to an already opened TAP interface
use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces
use 'sndbuf=nbytes' to limit the size of the send buffer (the
default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')
use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag
use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition
use vhost=on to enable experimental in kernel accelerator
(only has effect for virtio guests which use MSIX)
use vhostforce=on to force vhost on for non-MSIX virtio guests
use 'vhostfd=h' to connect to an already opened vhost net device
use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices
use 'queues=n' to specify the number of queues to be created for multiqueue TAP
use 'poll-us=n' to specify the maximum number of microseconds that could be
spent on busy polling for vhost net
-netdev bridge,id=str[,br=bridge][,helper=helper]
configure a host TAP network backend with ID 'str' that is
connected to a bridge (default=br0)
using the program 'helper (default=/usr/lib/qemu/qemu-bridge-helper)
-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]
[,rxsession=rxsession],txsession=txsession[,ipv6=on|off][,udp=on|off]
[,cookie64=on|off][,counter][,pincounter][,txcookie=txcookie]
[,rxcookie=rxcookie][,offset=offset]
configure a network backend with ID 'str' connected to
an Ethernet over L2TPv3 pseudowire.
Linux kernel 3.3+ as well as most routers can talk
L2TPv3. This transport allows connecting a VM to a VM,
VM to a router and even VM to Host. It is a nearly-universal
standard (RFC3931). Note - this implementation uses static
pre-configured tunnels (same as the Linux kernel).
use 'src=' to specify source address
use 'dst=' to specify destination address
use 'udp=on' to specify udp encapsulation
use 'srcport=' to specify source udp port
use 'dstport=' to specify destination udp port
use 'ipv6=on' to force v6
L2TPv3 uses cookies to prevent misconfiguration as
well as a weak security measure
use 'rxcookie=0x012345678' to specify a rxcookie
use 'txcookie=0x012345678' to specify a txcookie
use 'cookie64=on' to set cookie size to 64 bit, otherwise 32
use 'counter=off' to force a 'cut-down' L2TPv3 with no counter
use 'pincounter=on' to work around broken counter handling in peer
use 'offset=X' to add an extra offset between header and data
-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]
configure a network backend to connect to another network
using a socket connection
-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]
configure a network backend to connect to a multicast maddr and port
use 'localaddr=addr' to specify the host address to send packets from
-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]
configure a network backend to connect to another network
using an UDP tunnel
-netdev stream,id=str[,server=on|off],addr.type=inet,addr.host=host,addr.port=port[,to=maxport][,numeric=on|off][,keep-alive=on|off][,mptcp=on|off][,addr.ipv4=on|off][,addr.ipv6=on|off]
-netdev stream,id=str[,server=on|off],addr.type=unix,addr.path=path[,abstract=on|off][,tight=on|off]
-netdev stream,id=str[,server=on|off],addr.type=fd,addr.str=file-descriptor
configure a network backend to connect to another network
using a socket connection in stream mode.
-netdev dgram,id=str,remote.type=inet,remote.host=maddr,remote.port=port[,local.type=inet,local.host=addr]
-netdev dgram,id=str,remote.type=inet,remote.host=maddr,remote.port=port[,local.type=fd,local.str=file-descriptor]
configure a network backend to connect to a multicast maddr and port
use ``local.host=addr`` to specify the host address to send packets from
-netdev dgram,id=str,local.type=inet,local.host=addr,local.port=port[,remote.type=inet,remote.host=addr,remote.port=port]
-netdev dgram,id=str,local.type=unix,local.path=path[,remote.type=unix,remote.path=path]
-netdev dgram,id=str,local.type=fd,local.str=file-descriptor
configure a network backend to connect to another network
using an UDP tunnel
-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]
configure a network backend to connect to port 'n' of a vde switch
running on host and listening for incoming connections on 'socketpath'.
Use group 'groupname' and mode 'octalmode' to change default
ownership and permissions for communication port.
-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]
configure a vhost-user network, backed by a chardev 'dev'
-netdev vhost-vdpa,id=str[,vhostdev=/path/to/dev][,vhostfd=h]
configure a vhost-vdpa network,Establish a vhost-vdpa netdev
use 'vhostdev=/path/to/dev' to open a vhost vdpa device
use 'vhostfd=h' to connect to an already opened vhost vdpa device
-netdev hubport,id=str,hubid=n[,netdev=nd]
configure a hub port on the hub with ID 'n'
-nic [tap|bridge|user|l2tpv3|vde|vhost-user|socket][,option][,...][mac=macaddr]
initialize an on-board / default host NIC (using MAC address
macaddr) and connect it to the given host network backend
-nic none use it alone to have zero network devices (the default is to
provided a 'user' network connection)
-net nic[,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]
configure or create an on-board (or machine default) NIC and
connect it to hub 0 (please use -nic unless you need a hub)
-net [user|tap|bridge|vde|socket][,option][,option][,...]
old way to initialize a host network interface
(use the -netdev option if possible instead)
Character device options:
-chardev help
-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4=on|off][,ipv6=on|off][,nodelay=on|off]
[,server=on|off][,wait=on|off][,telnet=on|off][,websocket=on|off][,reconnect=seconds][,mux=on|off]
[,logfile=PATH][,logappend=on|off][,tls-creds=ID][,tls-authz=ID] (tcp)
-chardev socket,id=id,path=path[,server=on|off][,wait=on|off][,telnet=on|off][,websocket=on|off][,reconnect=seconds]
[,mux=on|off][,logfile=PATH][,logappend=on|off][,abstract=on|off][,tight=on|off] (unix)
-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]
[,localport=localport][,ipv4=on|off][,ipv6=on|off][,mux=on|off]
[,logfile=PATH][,logappend=on|off]
-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]
[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]
-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]
-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]
-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]
-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]
TPM device options:
-tpmdev passthrough,id=id[,path=path][,cancel-path=path]
use path to provide path to a character device; default is /dev/tpm0
use cancel-path to provide path to TPM's cancel sysfs entry; if
not provided it will be searched for in /sys/class/misc/tpm?/device
-tpmdev emulator,id=id,chardev=dev
configure the TPM device using chardev backend
Boot Image or Kernel specific:
-bios file set the filename for the BIOS
-pflash file use 'file' as a parallel flash image
-kernel bzImage use 'bzImage' as kernel image
-append cmdline use 'cmdline' as kernel command line
-initrd file use 'file' as initial ram disk
-dtb file use 'file' as device tree image
Debug/Expert options:
-compat [deprecated-input=accept|reject|crash][,deprecated-output=accept|hide]
Policy for handling deprecated management interfaces
-compat [unstable-input=accept|reject|crash][,unstable-output=accept|hide]
Policy for handling unstable management interfaces
-fw_cfg [name=]<name>,file=<file>
add named fw_cfg entry with contents from file
-fw_cfg [name=]<name>,string=<str>
add named fw_cfg entry with contents from string
-serial dev redirect the serial port to char device 'dev'
-parallel dev redirect the parallel port to char device 'dev'
-monitor dev redirect the monitor to char device 'dev'
-qmp dev like -monitor but opens in 'control' mode
-qmp-pretty dev like -qmp but uses pretty JSON formatting
-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]
-debugcon dev redirect the debug console to char device 'dev'
-pidfile file write PID to 'file'
-singlestep always run in singlestep mode
--preconfig pause QEMU before machine is initialized (experimental)
-S freeze CPU at startup (use 'c' to start execution)
-overcommit [mem-lock=on|off][cpu-pm=on|off]
run qemu with overcommit hints
mem-lock=on|off controls memory lock support (default: off)
cpu-pm=on|off controls cpu power management (default: off)
-gdb dev accept gdb connection on 'dev'. (QEMU defaults to starting
the guest without waiting for gdb to connect; use -S too
if you want it to not start execution.)
-s shorthand for -gdb tcp::1234
-d item1,... enable logging of specified items (use '-d help' for a list of log items)
-D logfile output log to logfile (default stderr)
-dfilter range,.. filter debug output to range of addresses (useful for -d cpu,exec,etc..)
-seed number seed the pseudo-random number generator
-L path set the directory for the BIOS, VGA BIOS and keymaps
-enable-kvm enable KVM full virtualization support
-xen-domid id specify xen guest domain id
-xen-attach attach to existing xen domain
libxl will use this when starting QEMU
-xen-domid-restrict restrict set of available xen operations
to specified domain id. (Does not affect
xenpv machine type).
-no-reboot exit instead of rebooting
-no-shutdown stop before shutdown
-action reboot=reset|shutdown
action when guest reboots [default=reset]
-action shutdown=poweroff|pause
action when guest shuts down [default=poweroff]
-action panic=pause|shutdown|exit-failure|none
action when guest panics [default=shutdown]
-action watchdog=reset|shutdown|poweroff|inject-nmi|pause|debug|none
action when watchdog fires [default=reset]
-loadvm [tag|id]
start right away with a saved state (loadvm in monitor)
-daemonize daemonize QEMU after initializing
-option-rom rom load a file, rom, into the option ROM space
-rtc [base=utc|localtime|<datetime>][,clock=host|rt|vm][,driftfix=none|slew]
set the RTC base and clock, enable drift fix for clock ticks (x86 only)
-icount [shift=N|auto][,align=on|off][,sleep=on|off][,rr=record|replay,rrfile=<filename>[,rrsnapshot=<snapshot>]]
enable virtual instruction counter with 2^N clock ticks per
instruction, enable aligning the host and virtual clocks
or disable real time cpu sleeping, and optionally enable
record-and-replay mode
-watchdog-action reset|shutdown|poweroff|inject-nmi|pause|debug|none
action when watchdog fires [default=reset]
-echr chr set terminal escape character instead of ctrl-a
-incoming tcp:[host]:port[,to=maxport][,ipv4=on|off][,ipv6=on|off]
-incoming rdma:host:port[,ipv4=on|off][,ipv6=on|off]
-incoming unix:socketpath
prepare for incoming migration, listen on
specified protocol and socket address
-incoming fd:fd
-incoming exec:cmdline
accept incoming migration on given file descriptor
or from given external command
-incoming defer
wait for the URI to be specified via migrate_incoming
-only-migratable allow only migratable devices
-nodefaults don't create default devices
-chroot dir chroot to dir just before starting the VM
-runas user change to user id user just before starting the VM
user can be numeric uid:gid instead
-sandbox on[,obsolete=allow|deny][,elevateprivileges=allow|deny|children]
[,spawn=allow|deny][,resourcecontrol=allow|deny]
Enable seccomp mode 2 system call filter (default 'off').
use 'obsolete' to allow obsolete system calls that are provided
by the kernel, but typically no longer used by modern
C library implementations.
use 'elevateprivileges' to allow or deny the QEMU process ability
to elevate privileges using set*uid|gid system calls.
The value 'children' will deny set*uid|gid system calls for
main QEMU process but will allow forks and execves to run unprivileged
use 'spawn' to avoid QEMU to spawn new threads or processes by
blocking *fork and execve
use 'resourcecontrol' to disable process affinity and schedular priority
-readconfig <file>
read config file
-no-user-config
do not load default user-provided config files at startup
-trace [[enable=]<pattern>][,events=<file>][,file=<file>]
specify tracing options
-plugin [file=]<file>[,<argname>=<argvalue>]
load a plugin
-async-teardown enable asynchronous teardown
-msg [timestamp[=on|off]][,guest-name=[on|off]]
control error message format
timestamp=on enables timestamps (default: off)
guest-name=on enables guest name prefix but only if
-name guest option is set (default: off)
-dump-vmstate <file>
Output vmstate information in JSON format to file.
Use the scripts/vmstate-static-checker.py file to
check for possible regressions in migration code
by comparing two such vmstate dumps.
-enable-sync-profile
enable synchronization profiling
Generic object creation:
-object TYPENAME[,PROP1=VALUE1,...]
create a new object of type TYPENAME setting properties
in the order they are specified. Note that the 'id'
property must be set. These objects are placed in the
'/objects' path.
During emulation, the following keys are useful:
ctrl-alt-f toggle full screen
ctrl-alt-n switch to virtual console 'n'
ctrl-alt toggle mouse and keyboard grab
When using -nographic, press 'ctrl-a h' to get some help.
See <https://qemu.org/contribute/report-a-bug> for how to report bugs.
More information on the QEMU project at <https://qemu.org>.
</pre></span></div>
<h3><span class="mw-headline" id="Permissions">Permissions</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=21" title="Edit section: Permissions">edit</a><span class="mw-editsection-bracket">]</span></span></h3>
<p>In order to run a KVM-accelerated virtual machine without logging in as root, add normal users to the <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">kvm</span> group. Replace <code><username></code> in the example command below with the appropriate user(s):
</p>
<div class="cmd-box"><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>gpasswd -a larry kvm</code></div></div>
<p><br />
</p>
<h3><span class="mw-headline" id="Creation_of_a_disk_image">Creation of a disk image</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=22" title="Edit section: Creation of a disk image">edit</a><span class="mw-editsection-bracket">]</span></span></h3>
<p>To create a <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">raw disk image</span> with <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">4 GiB</span> size:
</p>
<div class="cmd-box"><div><code style="color: #4E9A06; user-select: none; font-weight: bold;">user <span style="color:royalblue;">$</span></code><code>qemu-img create -f raw "/home/larry/qemu/my-systems-disk-image.img" 4G</code></div><pre>Formatting 'my-systems-disk-image.img', fmt=raw size=4294967296
</pre></div>
<div class="cmd-box"><div><code style="color: #4E9A06; user-select: none; font-weight: bold;">user <span style="color:royalblue;">$</span></code><code>ls -lh</code></div><pre>total 4
-rw-r--r-- 1 larry larry 4.0G Apr 12 11:23 my-systems-disk-image.img
</pre></div>
<p>To create a <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">raw disk image</span> with <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">copy-on-write disabled</span>:
</p>
<div class="cmd-box"><div><code style="color: #4E9A06; user-select: none; font-weight: bold;">user <span style="color:royalblue;">$</span></code><code>qemu-img create -f raw "/home/larry/qemu/my-systems-disk-image.img" -o nocow=on 4G</code></div><pre>Formatting 'my-systems-disk-image.img', fmt=raw size=4294967296 nocow=on
</pre></div>
<div class="cmd-box"><div><code style="color: #4E9A06; user-select: none; font-weight: bold;">user <span style="color:royalblue;">$</span></code><code>ls -lh</code></div><pre>total 4
-rw-r--r-- 1 larry larry 4.0G Apr 12 11:23 my-systems-disk-image.img
</pre></div>
<p>The option <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">nocow</span> is also a file attribute, which can be determined via the command <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">lsattr</span><sup id="cite_ref-11" class="reference"><a href="#cite_note-11">[11]</a></sup>.
</p><p>The following will create a <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">qcow2 disk image</span> (useful, if your filesystem does not support <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">sparse files</span>):
</p>
<div class="cmd-box"><div><code style="color: #4E9A06; user-select: none; font-weight: bold;">user <span style="color:royalblue;">$</span></code><code>qemu-img create -f qcow2 "/home/larry/qemu/my-systems-disk-image.qcow2" 4G</code></div><pre>Formatting 'my-systems-disk-image.qcow2', fmt=qcow2 cluster_size=65536 extended_l2=off compression_type=zlib size=4294967296 lazy_refcounts=off refcount_bits=16
</pre></div>
<div class="cmd-box"><div><code style="color: #4E9A06; user-select: none; font-weight: bold;">user <span style="color:royalblue;">$</span></code><code>ls -l</code></div><pre>total 196K
-rw-r--r-- 1 larry larry 193K Apr 12 11:30 my-systems-disk-image.qcow2
</pre></div>
<p><br />
</p>
<h3><span class="mw-headline" id="Preparation_of_a_bootable_disk_image_from_scratch">Preparation of a bootable disk image from scratch</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=23" title="Edit section: Preparation of a bootable disk image from scratch">edit</a><span class="mw-editsection-bracket">]</span></span></h3>
<p>A system can be copied <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">onto a disk image,</span> when not using a cdrom installation medium.
</p><p>By default, <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">qemu</span> uses a <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">bios-firmware</span> to boot the system.
</p><p>The disk can be prepared with a <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">msdos disk label</span> and a <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">gap</span> between the <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">end</span> of the 512-byte-MBR (Master Boot Record) and the <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">start</span> of the first partition.
The gap is needed for boot loaders like <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">grub</span>, which place <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">boot-code</span> within this gap.
</p><p>The following example uses the <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">raw disk image</span>, which was created <a href="/wiki/QEMU#Creation_of_a_disk_image" title="QEMU">above</a>.
</p><p>A raw disk image can be prepared by <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">attaching</span> it as a <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">loop device</span>:
</p>
<div class="cmd-box"><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>losetup --find --partscan --show "/home/larry/qemu/my-systems-disk-image.img"</code></div><pre>/dev/loop0
</pre></div>
<ul><li>The parameter <code>--find</code> finds the first unused <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">loop device</span>.</li>
<li>The parameter <code>--partscan</code> forces the <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">Kernel</span> to scan the <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">partition table</span> on the <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">newly created loop device</span>, where the <b>default sector size of 512 bytes</b> is assumed.</li>
<li>The parameter <code>--show</code> displays the name of the <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">assigned loop device</span>, if the parameter <code>--find</code> is used.</li></ul>
<p>Attached <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">loop devices</span> can be listed with the follwing command:
</p>
<div class="cmd-box"><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>losetup --list</code></div><pre>NAME SIZELIMIT OFFSET AUTOCLEAR RO BACK-FILE DIO LOG-SEC
/dev/loop0 0 0 0 0 /home/larry/qemu/my-systems-disk-image.img 0 512
</pre></div>
<p>Then, the <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">loop device</span> can be <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">formatted</span> like a normal disk.
</p><p>Print the <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">partition table</span>:
</p>
<div class="cmd-box"><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>parted "/dev/loop0" "unit mib print"</code></div><span class="mw-collapsible mw-collapsed"><pre>Error: /dev/loop0: unrecognised disk label
Model: Loopback device (loopback)
Disk /dev/loop0: 4096MiB
Sector size (logical/physical): 512B/512B
Partition Table: unknown
Disk Flags:
</pre></span></div>
<p>Create a new <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">partition table (msdos disk label)</span>:
</p>
<div class="alert alert-danger gw-box" style="padding-top: 8px; padding-bottom: 8px;"><strong><i class="fa fa-exclamation-triangle"></i> Warning</strong><br />Make absolutely sure to select the correct <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">loop device</span>, since this may <b>overwrite an existing partition table</b>; resulting in <b>data loss</b>, if the <b>overwritten partition table</b> cannot be recovered.</div>
<div class="cmd-box"><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>parted "/dev/loop0" "mklabel msdos"</code></div><pre>Information: You may need to update /etc/fstab.
</pre></div>
<p>The returned information can be ignored, since an entry in the configuration file <span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">/etc/fstab</span> is not needed.
</p><p><span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">parted</span> now indicates, that the <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">Partition Table</span> is <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">msdos</span>:
</p>
<div class="cmd-box"><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>parted "/dev/loop0" "unit mib print"</code></div><span class="mw-collapsible mw-collapsed"><pre>Model: Loopback device (loopback)
Disk /dev/loop0: 4096MiB
Sector size (logical/physical): 512B/512B
Partition Table: msdos
Disk Flags:
Number Start End Size Type File system Flags
</pre></span></div>
<p>Create an <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">ext4 partition</span> with an <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">offset</span> of <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">2 MiB</span>:
</p>
<div class="cmd-box"><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>parted "/dev/loop0" "mkpart primary ext4 2MiB -1"</code></div></div>
<p>The parameter <code>-1</code> represents the <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">last sector</span> of the partition.
</p><p>The <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">first partition</span> has been successfully created:
</p>
<div class="cmd-box"><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>parted "/dev/loop0" "unit mib print"</code></div><span class="mw-collapsible mw-collapsed"><pre>Model: Loopback device (loopback)
Disk /dev/loop0: 4096MiB
Sector size (logical/physical): 512B/512B
Partition Table: msdos
Disk Flags:
Number Start End Size Type File system Flags
1 2.00MiB 4095MiB 4093MiB primary
</pre></span></div>
<p>This will also <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">attach</span> a new <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">loop device</span> at <span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">/dev/loop0p1</span>:
</p>
<div class="cmd-box"><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>ls -l "/dev/loop0"*</code></div><pre>brw-rw---- 1 root disk 7, 0 Apr 12 12:33 /dev/loop0
brw-rw---- 1 root disk 259, 0 Apr 12 12:33 /dev/loop0p1
</pre></div>
<p>Set the <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">boot flag</span>:
</p>
<div class="cmd-box"><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>parted "/dev/loop0" set 1 boot on</code></div></div>
<p>All <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">partition flags</span> can be found in the column <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">Flags</span>:
</p>
<div class="cmd-box"><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>parted "/dev/loop0" "unit mib print"</code></div><span class="mw-collapsible mw-collapsed"><pre>Model: Loopback device (loopback)
Disk /dev/loop0: 4096MiB
Sector size (logical/physical): 512B/512B
Partition Table: msdos
Disk Flags:
Number Start End Size Type File system Flags
1 2.00MiB 4095MiB 4093MiB primary boot
</pre></span></div>
<p>Create the <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">ext4 filesystem</span>, which was declared via <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">parted</span> earlier:
</p>
<div class="alert alert-danger gw-box" style="padding-top: 8px; padding-bottom: 8px;"><strong><i class="fa fa-exclamation-triangle"></i> Warning</strong><br />Make absolutely sure to select the correct <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">loop device</span>, since this may <b>overwrite an existing partition</b>; resulting in <b>data loss</b>, if the <b>overwritten partition</b> cannot be recovered.</div>
<div class="cmd-box"><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>mkfs.ext4 "/dev/loop0p1"</code></div><span class="mw-collapsible mw-collapsed"><pre>mke2fs 1.47.2 (1-Jan-2025)
Discarding device blocks: done
Creating filesystem with 1047808 4k blocks and 262144 inodes
Filesystem UUID: 0e344af7-6f7b-4d27-8238-89d46a5920d6
Superblock backups stored on blocks:
32768, 98304, 163840, 229376, 294912, 819200, 884736
Allocating group tables: done
Writing inode tables: done
Creating journal (16384 blocks): done
Writing superblocks and filesystem accounting information: done
</pre></span></div>
<p>Mount it at <span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">/mnt/</span>:
</p>
<div class="cmd-box"><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>mount "/dev/loop0p1" "/mnt/"</code></div></div>
<div class="cmd-box"><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>df --human-readable --print-type "/mnt/"</code></div><pre>Filesystem Type Size Used Avail Use% Mounted on
/dev/loop0p1 ext4 3.9G 24K 3.7G 1% /mnt
</pre></div>
<p>Create the directories <span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">/mnt/boot/grub</span>, which will be used by <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">grub</span> later:
</p>
<div class="cmd-box"><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>mkdir --parents --verbose "/mnt/boot/grub"</code></div><pre>mkdir: created directory '/mnt/boot'
mkdir: created directory '/mnt/boot/grub'
</pre></div>
<p>Install <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">grub</span> on the <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">loop device</span> and advice it to install its files to <span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">/mnt/boot/grub/</span>:
</p>
<div class="cmd-box"><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>grub-install --target="i386-pc" --boot-directory="/mnt/boot/" "/dev/loop0"</code></div></div>
<div class="cmd-box"><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>tree -F "/mnt/boot/grub/"</code></div><span class="mw-collapsible mw-collapsed"><pre>/mnt/boot/grub/
├── fonts/
│   └── unicode.pf2
├── grubenv
├── i386-pc/
│   ├── acpi.mod
│   ├── adler32.mod
│   ├── affs.mod
│   ├── afs.mod
│   ├── afsplitter.mod
│   ├── ahci.mod
│   ├── all_video.mod
│   ├── aout.mod
│   ├── archelp.mod
│   ├── ata.mod
[...]
</pre></span></div>
<p><span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">Unmount</span> the filesystem and <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">detach</span> the <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">loop device</span>:
</p>
<div class="cmd-box"><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>umount "/mnt/"</code></div></div>
<div class="cmd-box"><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>losetup --detach "/dev/loop0"</code></div></div>
<p>If the <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">loop device</span> is still <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">busy</span> - for example, processes are still accessing <span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">/mnt/</span> - no error will be returned. This can be <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">verified</span> and <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">solved</span> with the following commands:
</p>
<div class="cmd-box"><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>losetup --list</code></div><pre>NAME SIZELIMIT OFFSET AUTOCLEAR RO BACK-FILE DIO LOG-SEC
/dev/loop0 0 0 0 0 /home/larry/qemu/my-systems-disk-image.img 0 512
</pre></div>
<div class="cmd-box"><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>lsof | grep "/mnt"</code></div><pre>sleep 31813 root cwd DIR 259,0 4096 131074 /mnt/boot/grub
</pre></div>
<div class="cmd-box"><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>kill -SIGTERM 31813</code></div></div>
<p>This is sufficient to boot into a <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">grub2 boot prompt</span>. This is can be used as the <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">basis for a bootable system</span>.
</p><p><br />
</p>
<h3><span class="mw-headline" id="CPU_selection">CPU selection</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=24" title="Edit section: CPU selection">edit</a><span class="mw-editsection-bracket">]</span></span></h3>
<p>QEMU CPU selections have additional support for "<a href="/wiki/QEMU/Front-ends" title="QEMU/Front-ends">accelerators</a>," like <b>kvm</b> (Kernel Virtual Machine) or <b>tcg</b> (Tiny Code Generator) or <b>Xen</b> (wikip<a rel="nofollow" class="external autonumber" href="https://de.wikipedia.org/wiki/Xen">[1]</a>).
</p><p>The accelerator can usually only "accelerate" the features that are available on the host CPU.
So the selection of the CPU affects the performance.
</p><p>To get a list of CPUs:
</p>
<div class="cmd-box"><div><code style="color: #4E9A06; user-select: none; font-weight: bold;">user <span style="color:royalblue;">$</span></code><code>qemu-system-x86_64 -cpu help</code></div><span class="mw-collapsible mw-collapsed"><pre>Available CPUs:
x86 486 (alias configured by machine type)
x86 486-v1
x86 Broadwell (alias configured by machine type)
x86 Broadwell-IBRS (alias of Broadwell-v3)
x86 Broadwell-noTSX (alias of Broadwell-v2)
x86 Broadwell-noTSX-IBRS (alias of Broadwell-v4)
x86 Broadwell-v1 Intel Core Processor (Broadwell)
x86 Broadwell-v2 Intel Core Processor (Broadwell, no TSX)
x86 Broadwell-v3 Intel Core Processor (Broadwell, IBRS)
x86 Broadwell-v4 Intel Core Processor (Broadwell, no TSX, IBRS)
x86 Cascadelake-Server (alias configured by machine type)
x86 Cascadelake-Server-noTSX (alias of Cascadelake-Server-v3)
x86 Cascadelake-Server-v1 Intel Xeon Processor (Cascadelake)
x86 Cascadelake-Server-v2 Intel Xeon Processor (Cascadelake) [ARCH_CAPABILITIES]
x86 Cascadelake-Server-v3 Intel Xeon Processor (Cascadelake) [ARCH_CAPABILITIES, no TSX]
x86 Cascadelake-Server-v4 Intel Xeon Processor (Cascadelake) [ARCH_CAPABILITIES, no TSX]
x86 Cascadelake-Server-v5 Intel Xeon Processor (Cascadelake) [ARCH_CAPABILITIES, EPT switching, XSAVES, no TSX]
x86 Conroe (alias configured by machine type)
x86 Conroe-v1 Intel Celeron_4x0 (Conroe/Merom Class Core 2)
x86 Cooperlake (alias configured by machine type)
x86 Cooperlake-v1 Intel Xeon Processor (Cooperlake)
x86 Cooperlake-v2 Intel Xeon Processor (Cooperlake) [XSAVES]
x86 Denverton (alias configured by machine type)
x86 Denverton-v1 Intel Atom Processor (Denverton)
x86 Denverton-v2 Intel Atom Processor (Denverton) [no MPX, no MONITOR]
x86 Denverton-v3 Intel Atom Processor (Denverton) [XSAVES, no MPX, no MONITOR]
x86 Dhyana (alias configured by machine type)
x86 Dhyana-v1 Hygon Dhyana Processor
x86 Dhyana-v2 Hygon Dhyana Processor [XSAVES]
x86 EPYC (alias configured by machine type)
x86 EPYC-IBPB (alias of EPYC-v2)
x86 EPYC-Milan (alias configured by machine type)
x86 EPYC-Milan-v1 AMD EPYC-Milan Processor
x86 EPYC-Rome (alias configured by machine type)
x86 EPYC-Rome-v1 AMD EPYC-Rome Processor
x86 EPYC-Rome-v2 AMD EPYC-Rome Processor
x86 EPYC-v1 AMD EPYC Processor
x86 EPYC-v2 AMD EPYC Processor (with IBPB)
x86 EPYC-v3 AMD EPYC Processor
x86 Haswell (alias configured by machine type)
x86 Haswell-IBRS (alias of Haswell-v3)
x86 Haswell-noTSX (alias of Haswell-v2)
x86 Haswell-noTSX-IBRS (alias of Haswell-v4)
x86 Haswell-v1 Intel Core Processor (Haswell)
x86 Haswell-v2 Intel Core Processor (Haswell, no TSX)
x86 Haswell-v3 Intel Core Processor (Haswell, IBRS)
x86 Haswell-v4 Intel Core Processor (Haswell, no TSX, IBRS)
x86 Icelake-Server (alias configured by machine type)
x86 Icelake-Server-noTSX (alias of Icelake-Server-v2)
x86 Icelake-Server-v1 Intel Xeon Processor (Icelake)
x86 Icelake-Server-v2 Intel Xeon Processor (Icelake) [no TSX]
x86 Icelake-Server-v3 Intel Xeon Processor (Icelake)
x86 Icelake-Server-v4 Intel Xeon Processor (Icelake)
x86 Icelake-Server-v5 Intel Xeon Processor (Icelake) [XSAVES]
x86 Icelake-Server-v6 Intel Xeon Processor (Icelake) [5-level EPT]
x86 IvyBridge (alias configured by machine type)
x86 IvyBridge-IBRS (alias of IvyBridge-v2)
x86 IvyBridge-v1 Intel Xeon E3-12xx v2 (Ivy Bridge)
x86 IvyBridge-v2 Intel Xeon E3-12xx v2 (Ivy Bridge, IBRS)
x86 KnightsMill (alias configured by machine type)
x86 KnightsMill-v1 Intel Xeon Phi Processor (Knights Mill)
x86 Nehalem (alias configured by machine type)
x86 Nehalem-IBRS (alias of Nehalem-v2)
x86 Nehalem-v1 Intel Core i7 9xx (Nehalem Class Core i7)
x86 Nehalem-v2 Intel Core i7 9xx (Nehalem Core i7, IBRS update)
x86 Opteron_G1 (alias configured by machine type)
x86 Opteron_G1-v1 AMD Opteron 240 (Gen 1 Class Opteron)
x86 Opteron_G2 (alias configured by machine type)
x86 Opteron_G2-v1 AMD Opteron 22xx (Gen 2 Class Opteron)
x86 Opteron_G3 (alias configured by machine type)
x86 Opteron_G3-v1 AMD Opteron 23xx (Gen 3 Class Opteron)
x86 Opteron_G4 (alias configured by machine type)
x86 Opteron_G4-v1 AMD Opteron 62xx class CPU
x86 Opteron_G5 (alias configured by machine type)
x86 Opteron_G5-v1 AMD Opteron 63xx class CPU
x86 Penryn (alias configured by machine type)
x86 Penryn-v1 Intel Core 2 Duo P9xxx (Penryn Class Core 2)
x86 SandyBridge (alias configured by machine type)
x86 SandyBridge-IBRS (alias of SandyBridge-v2)
x86 SandyBridge-v1 Intel Xeon E312xx (Sandy Bridge)
x86 SandyBridge-v2 Intel Xeon E312xx (Sandy Bridge, IBRS update)
x86 Skylake-Client (alias configured by machine type)
x86 Skylake-Client-IBRS (alias of Skylake-Client-v2)
x86 Skylake-Client-noTSX-IBRS (alias of Skylake-Client-v3)
x86 Skylake-Client-v1 Intel Core Processor (Skylake)
x86 Skylake-Client-v2 Intel Core Processor (Skylake, IBRS)
x86 Skylake-Client-v3 Intel Core Processor (Skylake, IBRS, no TSX)
x86 Skylake-Client-v4 Intel Core Processor (Skylake, IBRS, no TSX) [IBRS, XSAVES, no TSX]
x86 Skylake-Server (alias configured by machine type)
x86 Skylake-Server-IBRS (alias of Skylake-Server-v2)
x86 Skylake-Server-noTSX-IBRS (alias of Skylake-Server-v3)
x86 Skylake-Server-v1 Intel Xeon Processor (Skylake)
x86 Skylake-Server-v2 Intel Xeon Processor (Skylake, IBRS)
x86 Skylake-Server-v3 Intel Xeon Processor (Skylake, IBRS, no TSX)
x86 Skylake-Server-v4 Intel Xeon Processor (Skylake, IBRS, no TSX)
x86 Skylake-Server-v5 Intel Xeon Processor (Skylake, IBRS, no TSX) [IBRS, XSAVES, EPT switching, no TSX]
x86 Snowridge (alias configured by machine type)
x86 Snowridge-v1 Intel Atom Processor (SnowRidge)
x86 Snowridge-v2 Intel Atom Processor (Snowridge, no MPX)
x86 Snowridge-v3 Intel Atom Processor (Snowridge, no MPX) [XSAVES, no MPX]
x86 Snowridge-v4 Intel Atom Processor (Snowridge, no MPX) [no split lock detect, no core-capability]
x86 Westmere (alias configured by machine type)
x86 Westmere-IBRS (alias of Westmere-v2)
x86 Westmere-v1 Westmere E56xx/L56xx/X56xx (Nehalem-C)
x86 Westmere-v2 Westmere E56xx/L56xx/X56xx (IBRS update)
x86 athlon (alias configured by machine type)
x86 athlon-v1 QEMU Virtual CPU version 2.5+
x86 core2duo (alias configured by machine type)
x86 core2duo-v1 Intel(R) Core(TM)2 Duo CPU T7700 @ 2.40GHz
x86 coreduo (alias configured by machine type)
x86 coreduo-v1 Genuine Intel(R) CPU T2600 @ 2.16GHz
x86 kvm32 (alias configured by machine type)
x86 kvm32-v1 Common 32-bit KVM processor
x86 kvm64 (alias configured by machine type)
x86 kvm64-v1 Common KVM processor
x86 n270 (alias configured by machine type)
x86 n270-v1 Intel(R) Atom(TM) CPU N270 @ 1.60GHz
x86 pentium (alias configured by machine type)
x86 pentium-v1
x86 pentium2 (alias configured by machine type)
x86 pentium2-v1
x86 pentium3 (alias configured by machine type)
x86 pentium3-v1
x86 phenom (alias configured by machine type)
x86 phenom-v1 AMD Phenom(tm) 9550 Quad-Core Processor
x86 qemu32 (alias configured by machine type)
x86 qemu32-v1 QEMU Virtual CPU version 2.5+
x86 qemu64 (alias configured by machine type)
x86 qemu64-v1 QEMU Virtual CPU version 2.5+
x86 base base CPU model type with no features enabled
x86 host processor with all supported host features
x86 max Enables all features supported by the accelerator in the current host
Recognized CPUID flags:
3dnow 3dnowext 3dnowprefetch abm ace2 ace2-en acpi adx aes amd-no-ssb
amd-ssbd amd-stibp amx-bf16 amx-int8 amx-tile apic arat arch-capabilities
arch-lbr avic avx avx-vnni avx2 avx512-4fmaps avx512-4vnniw avx512-bf16
avx512-fp16 avx512-vp2intersect avx512-vpopcntdq avx512bitalg avx512bw
avx512cd avx512dq avx512er avx512f avx512ifma avx512pf avx512vbmi
avx512vbmi2 avx512vl avx512vnni bmi1 bmi2 bus-lock-detect cid cldemote
clflush clflushopt clwb clzero cmov cmp-legacy core-capability cr8legacy
cx16 cx8 dca de decodeassists ds ds-cpl dtes64 erms est extapic f16c
flushbyasid fma fma4 fpu fsgsbase fsrm full-width-write fxsr fxsr-opt
gfni hle ht hypervisor ia64 ibpb ibrs ibrs-all ibs intel-pt intel-pt-lip
invpcid invtsc kvm-asyncpf kvm-asyncpf-int kvm-hint-dedicated kvm-mmu
kvm-msi-ext-dest-id kvm-nopiodelay kvm-poll-control kvm-pv-eoi kvm-pv-ipi
kvm-pv-sched-yield kvm-pv-tlb-flush kvm-pv-unhalt kvm-steal-time kvmclock
kvmclock kvmclock-stable-bit la57 lahf-lm lbrv lm lwp mca mce md-clear
mds-no misalignsse mmx mmxext monitor movbe movdir64b movdiri mpx msr
mtrr nodeid-msr npt nrip-save nx osvw pae pat pause-filter pbe pcid
pclmulqdq pcommit pdcm pdpe1gb perfctr-core perfctr-nb pfthreshold pge
phe phe-en pks pku pmm pmm-en pn pni popcnt pschange-mc-no pse pse36
rdctl-no rdpid rdrand rdseed rdtscp rsba rtm sep serialize sgx sgx-debug
sgx-exinfo sgx-kss sgx-mode64 sgx-provisionkey sgx-tokenkey sgx1 sgx2
sgxlc sha-ni skinit skip-l1dfl-vmentry smap smep smx spec-ctrl
split-lock-detect ss ssb-no ssbd sse sse2 sse4.1 sse4.2 sse4a ssse3 stibp
svm svm-lock svme-addr-chk syscall taa-no tbm tce tm tm2 topoext tsc
tsc-adjust tsc-deadline tsc-scale tsx-ctrl tsx-ldtrk umip v-vmsave-vmload
vaes vgif virt-ssbd vmcb-clean vme vmx vmx-activity-hlt
vmx-activity-shutdown vmx-activity-wait-sipi vmx-apicv-register
vmx-apicv-vid vmx-apicv-x2apic vmx-apicv-xapic vmx-cr3-load-noexit
vmx-cr3-store-noexit vmx-cr8-load-exit vmx-cr8-store-exit vmx-desc-exit
vmx-encls-exit vmx-entry-ia32e-mode vmx-entry-load-bndcfgs
vmx-entry-load-efer vmx-entry-load-pat vmx-entry-load-perf-global-ctrl
vmx-entry-load-pkrs vmx-entry-load-rtit-ctl vmx-entry-noload-debugctl
vmx-ept vmx-ept-1gb vmx-ept-2mb vmx-ept-advanced-exitinfo
vmx-ept-execonly vmx-eptad vmx-eptp-switching vmx-exit-ack-intr
vmx-exit-clear-bndcfgs vmx-exit-clear-rtit-ctl vmx-exit-load-efer
vmx-exit-load-pat vmx-exit-load-perf-global-ctrl vmx-exit-load-pkrs
vmx-exit-nosave-debugctl vmx-exit-save-efer vmx-exit-save-pat
vmx-exit-save-preemption-timer vmx-flexpriority vmx-hlt-exit vmx-ins-outs
vmx-intr-exit vmx-invept vmx-invept-all-context vmx-invept-single-context
vmx-invept-single-context vmx-invept-single-context-noglobals
vmx-invlpg-exit vmx-invpcid-exit vmx-invvpid vmx-invvpid-all-context
vmx-invvpid-single-addr vmx-io-bitmap vmx-io-exit vmx-monitor-exit
vmx-movdr-exit vmx-msr-bitmap vmx-mtf vmx-mwait-exit vmx-nmi-exit
vmx-page-walk-4 vmx-page-walk-5 vmx-pause-exit vmx-ple vmx-pml
vmx-posted-intr vmx-preemption-timer vmx-rdpmc-exit vmx-rdrand-exit
vmx-rdseed-exit vmx-rdtsc-exit vmx-rdtscp-exit vmx-secondary-ctls
vmx-shadow-vmcs vmx-store-lma vmx-true-ctls vmx-tsc-offset
vmx-tsc-scaling vmx-unrestricted-guest vmx-vintr-pending vmx-vmfunc
vmx-vmwrite-vmexit-fields vmx-vnmi vmx-vnmi-pending vmx-vpid
vmx-wbinvd-exit vmx-xsaves vmx-zero-len-inject vpclmulqdq waitpkg
wbnoinvd wdt x2apic xcrypt xcrypt-en xfd xgetbv1 xop xsave xsavec
xsaveerptr xsaveopt xsaves xstore xstore-en xtpr
</pre></span></div>
<p>Show the available accelerators:
</p>
<div class="cmd-box"><div><code style="color: #4E9A06; user-select: none; font-weight: bold;">user <span style="color:royalblue;">$</span></code><code>qemu-system-x86_64 -accel help</code></div><span class="mw-collapsible mw-collapsed"><pre>Accelerators supported in QEMU binary:
tcg
kvm
hvf
whpx
haxm
</pre></span></div>
<p><br />
</p>
<h3><span class="mw-headline" id="Starting_QEMU">Starting QEMU</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=25" title="Edit section: Starting QEMU">edit</a><span class="mw-editsection-bracket">]</span></span></h3>
<p>This is how to start a virtual machine with the same feature set as the host CPU, a raw disk image and <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">2 GB</span> of RAM.
By default, a <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">VNC server</span> is started that runs <b>without password protection</b> and listens on the <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">loop interface</span>.
QEMU is advised to <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">listen on a local UNIX socket</span> with the following command:
</p>
<div class="cmd-box"><div><code style="color: #4E9A06; user-select: none; font-weight: bold;">user <span style="color:royalblue;">$</span></code><code>qemu-system-x86_64 -vnc "unix:/run/user/$(id --user)/qemu-vnc.sock" -enable-kvm -cpu host -drive "file=/home/larry/qemu/my-systems-disk-image.img,format=raw" -m 2G</code></div></div>
<div class="alert alert-danger gw-box" style="padding-top: 8px; padding-bottom: 8px;"><strong><i class="fa fa-exclamation-triangle"></i> Warning</strong><br /><b>Set the file permissions appropriately</b> to protect the <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">VNC server</span> from unauthorized access! If the virtual machine is started with the parameter <code>-vnc :0</code>, it will listen on <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">port 5900</span> (first display) <b>on all interfaces without password protection!</b></div>
<div class="alert alert-info gw-box" style="padding-top: 8px; padding-bottom: 8px;"><strong><i class="fa fa-sticky-note-o fa-rotate-180"></i> Note</strong><br />A <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">CD-ROM installation</span> or <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">boot medium</span> can be added via the parameter <code>-cdrom</code>. For example: <code>-cdrom filename.iso</code></div>
<h3><span class="mw-headline" id="Connecting_to_the_virtual_machine_via_VNC">Connecting to the virtual machine via VNC</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=26" title="Edit section: Connecting to the virtual machine via VNC">edit</a><span class="mw-editsection-bracket">]</span></span></h3>
<p>In order to connect to the <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">VNC server</span>, the command <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">vncviewer</span>, which comes from the package <span style="white-space: nowrap;" class="plainlinks" title="External link to https://packages.gentoo.org for the net-misc/tigervnc package."><a rel="nofollow" class="external text" href="https://packages.gentoo.org/packages/net-misc/tigervnc"><span style="font-family: monospace; font-size: 95%; color: MidnightBlue;">net-misc/tigervnc</span></a><span style="color: grey; margin-left: 0.1em; font-size: 70%;" class="fa fa-hdd-o fa-fw"></span></span>, can be used:
</p>
<div class="cmd-box"><div><code style="color: #4E9A06; user-select: none; font-weight: bold;">user <span style="color:royalblue;">$</span></code><code>vncviewer "/run/user/$(id --user)/qemu-vnc.sock"</code></div><span class="mw-collapsible mw-collapsed"><pre>TigerVNC viewer v1.15.0
Built on: 2025-05-13 12:30
Copyright (C) 1999-2025 TigerVNC team and many others (see README.rst)
See https://www.tigervnc.org for information on TigerVNC.
Tue May 13 14:44:36 2025
DecodeManager: Detected 4 CPU core(s)
DecodeManager: Creating 4 decoder thread(s)
CConn: Connected to socket /run/user/1000/qemu-vnc.sock
CConnection: Server supports RFB protocol version 3.8
CConnection: Using RFB protocol version 3.8
CConnection: Choosing security type None(1)
CConn: Using pixel format depth 24 (32bpp) little-endian rgb888
CConn: SetDesktopSize failed: 3
</pre></span></div>
<p>This will open a separate window, where one gets greeted with a <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">GRUB shell</span>, which was installed via <code>grub-install</code> <a href="/wiki/QEMU#Preparation_of_a_bootable_disk_image_from_scratch" title="QEMU">earlier</a>:
</p><p><a href="/wiki/File:Qemu_minimal_vm_with_grub2.png" class="image"><img alt="Qemu minimal vm with grub2.png" src="/images/thumb/7/77/Qemu_minimal_vm_with_grub2.png/500px-Qemu_minimal_vm_with_grub2.png" decoding="async" width="500" height="302" srcset="/images/thumb/7/77/Qemu_minimal_vm_with_grub2.png/750px-Qemu_minimal_vm_with_grub2.png 1.5x, /images/7/77/Qemu_minimal_vm_with_grub2.png 2x" /></a>
</p><p><br />
</p>
<h2><span class="mw-headline" id="Troubleshooting">Troubleshooting</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=27" title="Edit section: Troubleshooting">edit</a><span class="mw-editsection-bracket">]</span></span></h2>
<h3><span id="qemu-system-x86_64:_CPU_model_'host'_requires_KVM_or_HVF"></span><span class="mw-headline" id="qemu-system-x86_64:_CPU_model_.27host.27_requires_KVM_or_HVF">qemu-system-x86_64: CPU model 'host' requires KVM or HVF</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=28" title="Edit section: qemu-system-x86 64: CPU model 'host' requires KVM or HVF">edit</a><span class="mw-editsection-bracket">]</span></span></h3>
<p>When trying to start a virtual machine, using the parameter <code>-cpu host</code>, one may encounter the following error:
</p>
<div class="gw-box"><div class="box-caption"><span class="label" style="margin-right: .5em; background-color: #204A87">CODE</span> <strong>CPU model 'host' requires KVM or HVF</strong></div> <div class="mw-highlight mw-highlight-lang-text mw-content-ltr" dir="ltr"><pre><span></span>qemu-system-x86_64: CPU model 'host' requires KVM or HVF
</pre></div></div>
<p>In order to fix this, use the parameter <code>-enable-kvm</code>, which will enable <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">KVM full virtualization support</span>:
</p>
<div class="cmd-box"><div><code style="color: #4E9A06; user-select: none; font-weight: bold;">user <span style="color:royalblue;">$</span></code><code>qemu-system-x86_64 -cpu host -enable-kvm [...]</code></div></div>
<h3><span id=""kvm:_already_loaded_the_other_module""></span><span class="mw-headline" id=".22kvm:_already_loaded_the_other_module.22">"kvm: already loaded the other module"</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=29" title="Edit section: "kvm: already loaded the other module"">edit</a><span class="mw-editsection-bracket">]</span></span></h3>
<p>Sometimes during the early boot splash, the error message "kvm: already loaded the other module" can be seen. This message indicates both the Intel and the AMD kernel virtual machine settings have been enabled in the kernel. To fix this, enable it as a module or disable either the Intel <i>or</i> AMD KVM option specific to the system's processor in the kernel configuration. For example, if the system has an Intel processor, enable the Intel KVM, and then make sure the AMD KVM is set as a module (M) or is disabled (N). The relevant options to enable or disable can be found in the kernel's <span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">.config</span> file via the <var>CONFIG_KVM_INTEL</var> and <var>CONFIG_KVM_AMD</var> variables or in the configuration section above.
</p>
<h3><span id="Creating_TUN/TAP_device_-_No_such_file_or_directory"></span><span class="mw-headline" id="Creating_TUN.2FTAP_device_-_No_such_file_or_directory">Creating TUN/TAP device - No such file or directory</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=30" title="Edit section: Creating TUN/TAP device - No such file or directory">edit</a><span class="mw-editsection-bracket">]</span></span></h3>
<p>Sometimes this error can occur if TUN/TAP support cannot be found in the kernel. To solve this, try loading the driver:
</p>
<div class="cmd-box"><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>modprobe tun</code></div></div>
<p>If that works, add this to a file in <span style="font-family: monospace; font-size: 95%; color: #3c763d; font-weight: 600;">/etc/modules-load.d/</span> to load on startup:
</p>
<div class="box-caption"><span class="label" style="margin-right: .5em; background-color: #54487A">FILE</span> <strong><code style="border: none; background: none; color: #54487A; margin-right: .5em;">/etc/modules-load.d/qemu-modules.conf</code></strong><strong></strong></div> <div class="mw-highlight mw-highlight-lang-text mw-content-ltr" dir="ltr"><pre><span></span>tun
</pre></div>
<h3><span id="Configuration_does_not_support_video_model_'qxl'"></span><span class="mw-headline" id="Configuration_does_not_support_video_model_.27qxl.27">Configuration does not support video model 'qxl'</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=31" title="Edit section: Configuration does not support video model 'qxl'">edit</a><span class="mw-editsection-bracket">]</span></span></h3>
<p>This is usually the case if QEMU is not built with the <code>spice</code> USE flag. To resolve this issue, try to build QEMU <a href="/wiki/Handbook:AMD64/Working/USE#Declaring_USE_flags_for_individual_packages" title="Handbook:AMD64/Working/USE">with the correct USE flag</a>.
</p><p>First add <code>spice</code> to via a <a href="/wiki//etc/portage/package.use" title="/etc/portage/package.use">package.use</a> file:
</p>
<div class="box-caption"><span class="label" style="margin-right: .5em; background-color: #54487A">FILE</span> <strong><code style="border: none; background: none; color: #54487A; margin-right: .5em;">/etc/portage/package.use/qemu</code></strong><strong></strong></div> <div class="mw-highlight mw-highlight-lang-text mw-content-ltr" dir="ltr"><pre><span></span>app-emulation/qemu spice
</pre></div>
<p>Then rebuild the package:
</p>
<div class="cmd-box"><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>emerge --ask app-emulation/qemu</code></div></div>
<h3><span class="mw-headline" id="My_qemu_has_kvm_support_on_some_guest_architectures">My qemu has kvm support on some guest architectures</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=32" title="Edit section: My qemu has kvm support on some guest architectures">edit</a><span class="mw-editsection-bracket">]</span></span></h3>
<p>KVM works only for the same architecture. An ARM64 host cannot handle x86_64 instructions.
</p>
<h3><span class="mw-headline" id="Invalid_context_errors_on_SELinux_systems">Invalid context errors on SELinux systems</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=33" title="Edit section: Invalid context errors on SELinux systems">edit</a><span class="mw-editsection-bracket">]</span></span></h3>
<p>By default, Libvirt generates a random SELinux MCS label for the QEMU process when it is started. If the loaded SELinux policy does not support MCS categories, the resulting security context will be invalid:
</p>
<div class="gw-box"><div class="box-caption"><span class="label" style="margin-right: .5em; background-color: #204A87">CODE</span> <strong>SELinux error from virt-manager</strong></div> <div class="mw-highlight mw-highlight-lang-text mw-content-ltr" dir="ltr"><pre><span></span>Error starting domain: unable to set socket security context 'system_u:system_r:svirt_t:s0:c123,c456': Invalid argument
</pre></div></div>
<div class="gw-box"><div class="box-caption"><span class="label" style="margin-right: .5em; background-color: #204A87">CODE</span> <strong>SELinux error from the kernel</strong></div> <div class="mw-highlight mw-highlight-lang-text mw-content-ltr" dir="ltr"><pre><span></span>kernel: SELinux: Context system_u:object_r:svirt_image_t:s0:c123,c456 is not valid (left unmapped).
</pre></div></div>
<p>The solution is either to switch to one of the policy types which supports MCS categories or manually set the virtual machine's security labels, without MCS categories:
</p>
<div class="gw-box"><div class="box-caption"><span class="label" style="margin-right: .5em; background-color: #204A87">CODE</span> <strong>Libvirt domain XML with manually specified seclabel fields</strong></div> <div class="mw-highlight mw-highlight-lang-xml mw-content-ltr" dir="ltr"><pre><span></span><span class="nt"><domain</span><span class="w"> </span><span class="na">type=</span><span class="s">"kvm"</span><span class="nt">></span>
<span class="w"> </span><span class="nt"><name></span>fedora<span class="nt"></name></span>
<span class="w"> </span>...
<span class="w"> </span><span class="nt"><devices></span>
<span class="w"> </span><span class="nt"><disk</span><span class="w"> </span><span class="na">type=</span><span class="s">"file"</span><span class="w"> </span><span class="na">device=</span><span class="s">"disk"</span><span class="nt">></span>
<span class="w"> </span><span class="nt"><driver</span><span class="w"> </span><span class="na">name=</span><span class="s">"qemu"</span><span class="w"> </span><span class="na">type=</span><span class="s">"qcow2"</span><span class="nt">/></span>
<span class="w"> </span><span class="nt"><source</span><span class="w"> </span><span class="na">file=</span><span class="s">"/var/lib/libvirt/images/fedora.qcow2"</span><span class="nt">></span>
<span class="w"> </span><span class="nt"><seclabel</span><span class="w"> </span><span class="na">model=</span><span class="s">'selinux'</span><span class="w"> </span><span class="na">relabel=</span><span class="s">'yes'</span><span class="nt">></span>
<span class="w"> </span><span class="nt"><label></span>system_u:object_r:svirt_image_t<span class="nt"></label></span>
<span class="w"> </span><span class="nt"></seclabel></span>
<span class="w"> </span><span class="nt"></source></span>
<span class="w"> </span><span class="nt"><target</span><span class="w"> </span><span class="na">dev=</span><span class="s">"vda"</span><span class="w"> </span><span class="na">bus=</span><span class="s">"virtio"</span><span class="nt">/></span>
<span class="w"> </span><span class="nt"><address</span><span class="w"> </span><span class="na">type=</span><span class="s">"pci"</span><span class="w"> </span><span class="na">domain=</span><span class="s">"0x0000"</span><span class="w"> </span><span class="na">bus=</span><span class="s">"0x04"</span><span class="w"> </span><span class="na">slot=</span><span class="s">"0x00"</span><span class="w"> </span><span class="na">function=</span><span class="s">"0x0"</span><span class="nt">/></span>
<span class="w"> </span><span class="nt"></disk></span>
<span class="w"> </span>...
<span class="w"> </span><span class="nt"><seclabel</span><span class="w"> </span><span class="na">type=</span><span class="s">'static'</span><span class="w"> </span><span class="na">model=</span><span class="s">'selinux'</span><span class="w"> </span><span class="na">relabel=</span><span class="s">'yes'</span><span class="nt">></span>
<span class="w"> </span><span class="nt"><label></span>system_u:system_r:svirt_t<span class="nt"></label></span>
<span class="w"> </span><span class="nt"></seclabel></span>
<span class="nt"></domain></span>
</pre></div></div>
<h3><span class="mw-headline" id="Static-user_and_LTO">Static-user and LTO</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=34" title="Edit section: Static-user and LTO">edit</a><span class="mw-editsection-bracket">]</span></span></h3>
<p>GCC will use a huge amount of RAM when LTO is enabled on the system if any of the <var>ppc64</var> options are enabled while using the <code>static-user</code> flag; because of this, it is recommended to disable LTO while compiling in this configuration or use <a href="/wiki/LLVM/Clang" title="LLVM/Clang">Clang</a> <a href="/wiki/LLVM/Clang" title="LLVM/Clang">if LTO is required.</a> See <span class="plainlinks" style="color: MidnightBlue; font-family: monospace; font-size: 95%;" title="External link to https://bugs.gentoo.org."><a rel="nofollow" class="external text" href="https://bugs.gentoo.org/show_bug.cgi?id=883419"><span style="color: MidnightBlue;">bug #883419</span></a><span style="color: grey; margin-left: 0.1em; font-size: 70%;" class="fa fa-bug fa-fw"></span></span>
</p><p><br />
</p>
<h3><span class="mw-headline" id="lto1:_internal_compiler_error:_original_not_compressed_with_zstd">lto1: internal compiler error: original not compressed with zstd</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=35" title="Edit section: lto1: internal compiler error: original not compressed with zstd">edit</a><span class="mw-editsection-bracket">]</span></span></h3>
<p>This is caused by a mismatch of GCC used to compile zlib and glib to the one being used to compile qemu, this can be fixed by rebuilding both before compiling qemu again.
</p>
<div class="cmd-box"><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>emerge --ask sys-libs/zlib dev-libs/glib</code></div></div>
<h3><span id="Windows_guests_fail_to_provision,_boot,_or_Blue_Screen_of_Death_(BSOD)_on_startup"></span><span class="mw-headline" id="Windows_guests_fail_to_provision.2C_boot.2C_or_Blue_Screen_of_Death_.28BSOD.29_on_startup">Windows guests fail to provision, boot, or Blue Screen of Death (BSOD) on startup</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=36" title="Edit section: Windows guests fail to provision, boot, or Blue Screen of Death (BSOD) on startup">edit</a><span class="mw-editsection-bracket">]</span></span></h3>
<p>For optimal performance, it is recommended that modern Windows guests be run under a kernel with <code>CONFIG_KVM_HYPERV</code> enabled. As an additional benefit, if this option is not enabled, on some hardware, VMs will fail to provision, to boot, or present with a BSOD.
</p><p>The technical reasons for this are as follows: later versions of Windows, when running as virtual machines, sometimes attempt to access hardware registers (specifically, Model Specific Registers or MSRs) that are not actually defined for the emulated processor within the virtual environment. This is often due to how Windows interacts with hardware, a driver trying to be overly clever, or even bugs within the operating system itself. While these MSR accesses might be valid on physical processors, the virtualized environment presented by KVM may not support them.
</p><p>KVM's default behavior is to attempt to emulate these MSR accesses, but when encountering an undefined register, it reports an "invalid instruction" error to the virtual Windows instance. This error is often fatal, resulting in a BSOD and halting the virtual machine.
</p>
<div class="alert alert-success gw-box" style="padding-top: 8px; padding-bottom: 8px;"><strong><i class="fa fa-check-circle"></i> Tip</strong><br /><code>unhandled rdmsr</code> or <code>unhandled wrmsr</code> messages in the system logs of the host indicate attempts to access undefined MSRs. Failures may also be more obvious, like <code>failed to set MSR</code> and <code>Assertion `ret == cpu->kvm_msr_buf->nmsrs' failed</code> from <code>qemu-system-*</code>.</div>
<p>An alternative is passing the option <code>kvm.ignore_msrs=1</code> on the kernel command line or as an option to the KVM module:
</p>
<div class="box-caption"><span class="label" style="margin-right: .5em; background-color: #54487A">FILE</span> <strong><code style="border: none; background: none; color: #54487A; margin-right: .5em;">/etc/modprobe.d/kvm.conf</code></strong><strong></strong></div> <div class="mw-highlight mw-highlight-lang-text mw-content-ltr" dir="ltr"><pre><span></span>options kvm ignore_msrs=1
</pre></div>
<p>The <code>ignore_msrs</code> option instructs KVM to ignore any attempts by the virtual Windows machine to access these undefined MSRs. Instead of generating an error and causing a BSOD, KVM silently bypasses the problematic instruction. This allows Windows to continue running, albeit potentially with some minor performance implications or masked underlying issues.
</p>
<div class="alert alert-success gw-box" style="padding-top: 8px; padding-bottom: 8px;"><strong><i class="fa fa-check-circle"></i> Tip</strong><br />While <code>ignore_msrs</code> can be a quick fix for BSODs related to MSR access (not all BSODs are!), it is likely that this can be addressed properly by enabling the appropriate kernel option, as documented above.<br /><br />This option should only need to be set if there are still undefined MSRs (and if there <i>are</i> it's probably a bug that needs to be reported to the software vendor or KVM/QEMU upstream).</div>
<p><br />
</p>
<h2><span class="mw-headline" id="Removal">Removal</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=37" title="Edit section: Removal">edit</a><span class="mw-editsection-bracket">]</span></span></h2>
<p>There may be image files left behind after the removal of the QEMU package.
</p>
<h3><span class="mw-headline" id="Unmerge">Unmerge</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=38" title="Edit section: Unmerge">edit</a><span class="mw-editsection-bracket">]</span></span></h3>
<div class="cmd-box"><div><code style="color: #ef2929; user-select: none; font-weight: bold;">root <span style="color:royalblue;">#</span></code><code>emerge --ask --depclean --verbose app-emulation/qemu</code></div></div>
<p><br />
</p>
<h2><span class="mw-headline" id="See_also">See also</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=39" title="Edit section: See also">edit</a><span class="mw-editsection-bracket">]</span></span></h2>
<ul><li><a href="/wiki/Comparison_of_virtual_machines" title="Comparison of virtual machines">Comparison of virtual machines</a> — compares the features of several platform virtual machines.</li>
<li><a href="/wiki/Fast_Virtio_VM" title="Fast Virtio VM">Fast Virtio VM</a> — explains a way to build a blazing fast Gentoo VM under <a class="mw-selflink selflink">KVM</a> using Virtio and mdev.</li>
<li><a href="/wiki/GPU_passthrough_with_virt-manager,_QEMU,_and_KVM" title="GPU passthrough with virt-manager, QEMU, and KVM">GPU passthrough with virt-manager, QEMU, and KVM</a> — directly present an internal PCI GPU as-is for direct use by a virtual machine</li>
<li><a href="/wiki/QEMU_with_Open_vSwitch_network" title="QEMU with Open vSwitch network">QEMU with Open vSwitch network</a></li>
<li><a href="/wiki/Virtualization" title="Virtualization">Virtualization</a> — the concept and technique that permits running software in an environment separate from a computer operating system.</li>
<li><a href="/wiki/QEMU/Front-ends" title="QEMU/Front-ends">QEMU/Front-ends</a> — facilitate VM management and use</li>
<li><a href="/wiki/Libvirt" title="Libvirt">Libvirt</a> — a virtualization management toolkit</li>
<li><a href="/wiki/Libvirt/QEMU_networking" title="Libvirt/QEMU networking">Libvirt/QEMU_networking</a> — details the setup of Gentoo networking by <a href="/wiki/Libvirt" title="Libvirt">Libvirt</a> for use by guest containers and <a class="mw-selflink selflink">QEMU</a>-based virtual machines.</li>
<li><a href="/wiki/Libvirt/QEMU_guest" title="Libvirt/QEMU guest">Libvirt/QEMU_guest</a> — creation of a guest domain (virtual machine, VM), running inside a QEMU hypervisor, using tools found in <span style="white-space: nowrap;" class="plainlinks" title="External link to https://packages.gentoo.org for the libvirt package."><a rel="nofollow" class="external text" href="https://packages.gentoo.org/packages/libvirt"><span style="font-family: monospace; font-size: 95%; color: MidnightBlue;">libvirt</span></a><span style="color: grey; margin-left: 0.1em; font-size: 70%;" class="fa fa-hdd-o fa-fw"></span></span> package.</li>
<li><a href="/wiki/Virt-manager" title="Virt-manager">Virt-manager</a> — lightweight GUI application designed for managing virtual machines and containers via the <a href="/wiki/Libvirt" title="Libvirt">libvirt</a> API.</li>
<li><a href="/wiki/Virt-manager/QEMU_guest" title="Virt-manager/QEMU guest">Virt-manager/QEMU_guest</a> — creation of a guest virtual machine (VM) running inside a QEMU hypervisor using just the <span style="font-family: monospace; font-size: 95%; font-weight: bold;" class="tripleclick-separator">virt-manager</span> GUI tool.</li>
<li><a href="/wiki/QEMU/Linux_guest" title="QEMU/Linux guest">QEMU/Linux guest</a> — describes the setup of a Gentoo Linux guest in <a class="mw-selflink selflink">QEMU</a> using Gentoo bootable media.</li>
<li><a href="/wiki/QEMU/Bridge_with_Wifi_Routing" title="QEMU/Bridge with Wifi Routing">QEMU/Bridge with Wifi Routing</a></li>
<li><a href="/wiki/Category:QEMU_Guests" title="Category:QEMU Guests">Category:QEMU Guests</a></li>
<li><a href="/wiki/Remote_desktop" title="Remote desktop">Remote_desktop</a> — a guide to <b><a href="https://en.wikipedia.org/wiki/Remote_desktop_software" class="extiw" title="wikipedia:Remote desktop software">remote desktop</a></b> software on Gentoo</li></ul>
<p><br />
</p>
<h2><span class="mw-headline" id="External_resources">External resources</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=40" title="Edit section: External resources">edit</a><span class="mw-editsection-bracket">]</span></span></h2>
<ul><li><a rel="nofollow" class="external free" href="https://www.linux-kvm.org/page/KvmOnGentoo">https://www.linux-kvm.org/page/KvmOnGentoo</a> - The Gentoo article on the KVM wiki</li>
<li><a rel="nofollow" class="external free" href="https://wiki.qemu.org/Main_Page">https://wiki.qemu.org/Main_Page</a> - The Official QEMU wiki</li></ul>
<h2><span class="mw-headline" id="References"><span class="anchor" id="References"></span> References</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span><a href="/index.php?title=QEMU&action=edit&section=41" title="Edit section: References">edit</a><span class="mw-editsection-bracket">]</span></span></h2>
<div class="reflist" style="list-style-type: decimal;">
<div class="mw-references-wrap mw-references-columns"><ol class="references">
<li id="cite_note-1"><span class="mw-cite-backlink"><a href="#cite_ref-1">↑</a></span> <span class="reference-text"><a rel="nofollow" class="external free" href="https://en.wikipedia.org/wiki/Full_virtualization">https://en.wikipedia.org/wiki/Full_virtualization</a></span>
</li>
<li id="cite_note-2"><span class="mw-cite-backlink"><a href="#cite_ref-2">↑</a></span> <span class="reference-text"><a rel="nofollow" class="external free" href="https://developer.apple.com/documentation/hypervisor">https://developer.apple.com/documentation/hypervisor</a></span>
</li>
<li id="cite_note-3"><span class="mw-cite-backlink"><a href="#cite_ref-3">↑</a></span> <span class="reference-text"><a rel="nofollow" class="external free" href="https://en.wikipedia.org/wiki/Paravirtualization">https://en.wikipedia.org/wiki/Paravirtualization</a></span>
</li>
<li id="cite_note-4"><span class="mw-cite-backlink"><a href="#cite_ref-4">↑</a></span> <span class="reference-text"><a rel="nofollow" class="external free" href="https://github.com/RceNinja/notes/blob/master/notes/build_qemu_with_enabled_hyper-v_acceleration_(whpx)_on_windows.md">https://github.com/RceNinja/notes/blob/master/notes/build_qemu_with_enabled_hyper-v_acceleration_(whpx)_on_windows.md</a></span>
</li>
<li id="cite_note-5"><span class="mw-cite-backlink"><a href="#cite_ref-5">↑</a></span> <span class="reference-text"><a rel="nofollow" class="external free" href="https://en.wikipedia.org/wiki/Paravirtualization">https://en.wikipedia.org/wiki/Paravirtualization</a></span>
</li>
<li id="cite_note-6"><span class="mw-cite-backlink"><a href="#cite_ref-6">↑</a></span> <span class="reference-text"><a rel="nofollow" class="external text" href="https://www.qemu.org/docs/master/system/qemu-cpu-models.html">QEMU / KVM CPU model configuration</a></span>
</li>
<li id="cite_note-7"><span class="mw-cite-backlink"><a href="#cite_ref-7">↑</a></span> <span class="reference-text"><a rel="nofollow" class="external free" href="https://github.com/intel/haxm">https://github.com/intel/haxm</a></span>
</li>
<li id="cite_note-8"><span class="mw-cite-backlink"><a href="#cite_ref-8">↑</a></span> <span class="reference-text"><a rel="nofollow" class="external free" href="https://en.wikipedia.org/wiki/Paravirtualization">https://en.wikipedia.org/wiki/Paravirtualization</a></span>
</li>
<li id="cite_note-9"><span class="mw-cite-backlink"><a href="#cite_ref-9">↑</a></span> <span class="reference-text"><a rel="nofollow" class="external free" href="https://forums.gentoo.org/viewtopic-p-8157704.html">https://forums.gentoo.org/viewtopic-p-8157704.html</a></span>
</li>
<li id="cite_note-10"><span class="mw-cite-backlink"><a href="#cite_ref-10">↑</a></span> <span class="reference-text"><a rel="nofollow" class="external free" href="https://wiki.gentoo.org/wiki//etc/portage/make.conf#USE_EXPAND">https://wiki.gentoo.org/wiki//etc/portage/make.conf#USE_EXPAND</a></span>
</li>
<li id="cite_note-11"><span class="mw-cite-backlink"><a href="#cite_ref-11">↑</a></span> <span class="reference-text"><a rel="nofollow" class="external free" href="https://www.qemu.org/docs/master/system/qemu-block-drivers.html#cmdoption-qcow2-arg-nocow">https://www.qemu.org/docs/master/system/qemu-block-drivers.html#cmdoption-qcow2-arg-nocow</a></span>
</li>
</ol></div></div>
' |
Unix timestamp of change (timestamp) | 1747513324 |