docs:
* Convert qemu-doc from Texinfo to rST -----BEGIN PGP SIGNATURE----- iQJNBAABCAA3FiEE4aXFk81BneKOgxXPPCUl7RQ2DN4FAl5iLx8ZHHBldGVyLm1h eWRlbGxAbGluYXJvLm9yZwAKCRA8JSXtFDYM3nPLD/91Z1uCXz64MGGfgdje5+Ur 4BFG1qPjL2Q9vcECK9LuF1gHnlBBDE8GCB6XyBBSIdGHJWHr3+a8ztbbuH6zesXx kUmGzLB1hXN/IZRHCWp41e+nUiymlJMzht5P42tzFHeakjWdb9kOfqouvZJRpyug jJahjAuXgbLeToLWj/2Klf//o/stzzf7g3mn1QbO5KnCsDLiJqCxjI+jFfc2sgsP GOZiMM4ReusnJgPPvElAg+VQiw4JWA/joNPh+KGNj9aASv+fWzmswcNzoyG8sVzU k5Wi2FTMwLINlWIGlWM6CfTelDuEito98mc1BEMdu5IGjrd+gi6UMW9k/c0tAetJ 3LHXmF7+1zWsQOeKmBcQZrmG+767ebNlKt3w5brk5EbXdnknuG1PHekopHB9I2nD OkJEvJ60PyMbbGxQ6M4xsA4bI51aWc5rQb+l5mSp1HWhRL4MMxO5QB7t3wCPZ2ln BSvX0nln2O9K1AzCaI0twU7mByaWrFeo77qlwkLqA72r04LDKnpUXlMb+nNm6+yf YrtkCbu70AaeAJLsDZMXNLNriraO4SoFyYtUuHux0DBi/ckmiaH3hXJMQZxsjdqq /Qt7kqxaxt3ZStONSANbjxO4bwbb3027uSAOTa1fvh96Pcht0ak0+cDADWNS8GOZ e09u3rwyhaEzR68gFQXuqw== =GGb7 -----END PGP SIGNATURE----- Merge remote-tracking branch 'remotes/pmaydell/tags/pull-docs-20200306' into staging docs: * Convert qemu-doc from Texinfo to rST # gpg: Signature made Fri 06 Mar 2020 11:08:15 GMT # gpg: using RSA key E1A5C593CD419DE28E8315CF3C2525ED14360CDE # gpg: issuer "peter.maydell@linaro.org" # gpg: Good signature from "Peter Maydell <peter.maydell@linaro.org>" [ultimate] # gpg: aka "Peter Maydell <pmaydell@gmail.com>" [ultimate] # gpg: aka "Peter Maydell <pmaydell@chiark.greenend.org.uk>" [ultimate] # Primary key fingerprint: E1A5 C593 CD41 9DE2 8E83 15CF 3C25 25ED 1436 0CDE * remotes/pmaydell/tags/pull-docs-20200306: (33 commits) *.hx: Remove all the STEXI/ETEXI blocks docs: Remove old texinfo sources docs: Stop building qemu-doc ui/cocoa.m: Update documentation file and pathname docs: Generate qemu.1 manpage with Sphinx docs: Split out sections for the manpage into .rst.inc files qemu-options.hx: Fix up the autogenerated rST qemu-options.hx: Add rST documentation fragments scripts/hxtool-conv: Archive script used in qemu-options.hx conversion docs: Roll -prom-env and -g target-specific info into qemu-options.hx docs: Roll semihosting option information into qemu-options.hx doc/scripts/hxtool.py: Strip trailing ':' from DEFHEADING/ARCHHEADING hmp-commands-info.hx: Add rST documentation fragments hmp-commands.hx: Add rST documentation fragments docs/system: convert Texinfo documentation to rST docs/system: convert the documentation of deprecated features to rST. docs/system: convert managed startup to rST. docs/system: Convert security.texi to rST format docs/system: Convert qemu-cpu-models.texi to rST docs: Create defs.rst.inc as a place to define substitutions ... Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
This commit is contained in:
commit
f4c4357fbf
3
.gitignore
vendored
3
.gitignore
vendored
|
@ -46,9 +46,6 @@
|
|||
!/qapi/qapi-visit-core.c
|
||||
/qapi/qapi-visit.[ch]
|
||||
/qapi/qapi-doc.texi
|
||||
/qemu-doc.html
|
||||
/qemu-doc.info
|
||||
/qemu-doc.txt
|
||||
/qemu-edid
|
||||
/qemu-img
|
||||
/qemu-nbd
|
||||
|
|
|
@ -215,6 +215,7 @@ S: Maintained
|
|||
F: target/mips/
|
||||
F: default-configs/*mips*
|
||||
F: disas/*mips*
|
||||
F: docs/system/cpu-models-mips.rst.inc
|
||||
F: hw/intc/mips_gic.c
|
||||
F: hw/mips/
|
||||
F: hw/misc/mips_*
|
||||
|
@ -319,7 +320,7 @@ F: tests/tcg/i386/
|
|||
F: tests/tcg/x86_64/
|
||||
F: hw/i386/
|
||||
F: disas/i386.c
|
||||
F: docs/qemu-cpu-models.texi
|
||||
F: docs/system/cpu-models-x86.rst.inc
|
||||
T: git https://github.com/ehabkost/qemu.git x86-next
|
||||
|
||||
Xtensa TCG CPUs
|
||||
|
@ -2233,7 +2234,7 @@ M: Stefan Hajnoczi <stefanha@redhat.com>
|
|||
S: Maintained
|
||||
F: trace/
|
||||
F: trace-events
|
||||
F: qemu-option-trace.texi
|
||||
F: docs/qemu-option-trace.rst.inc
|
||||
F: scripts/tracetool.py
|
||||
F: scripts/tracetool/
|
||||
F: scripts/qemu-trace-stap*
|
||||
|
@ -2803,7 +2804,7 @@ F: contrib/gitdm/*
|
|||
|
||||
Incompatible changes
|
||||
R: libvir-list@redhat.com
|
||||
F: qemu-deprecated.texi
|
||||
F: docs/system/deprecated.rst
|
||||
|
||||
Build System
|
||||
------------
|
||||
|
|
47
Makefile
47
Makefile
|
@ -344,7 +344,7 @@ MANUAL_BUILDDIR := docs
|
|||
endif
|
||||
|
||||
ifdef BUILD_DOCS
|
||||
DOCS=qemu-doc.html qemu-doc.txt qemu.1
|
||||
DOCS+=$(MANUAL_BUILDDIR)/system/qemu.1
|
||||
DOCS+=$(MANUAL_BUILDDIR)/tools/qemu-img.1
|
||||
DOCS+=$(MANUAL_BUILDDIR)/tools/qemu-nbd.8
|
||||
DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-ga.8
|
||||
|
@ -354,7 +354,7 @@ endif
|
|||
DOCS+=$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7
|
||||
DOCS+=docs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt docs/interop/qemu-qmp-ref.7
|
||||
DOCS+=docs/interop/qemu-ga-ref.html docs/interop/qemu-ga-ref.txt docs/interop/qemu-ga-ref.7
|
||||
DOCS+=docs/qemu-cpu-models.7
|
||||
DOCS+=$(MANUAL_BUILDDIR)/system/qemu-cpu-models.7
|
||||
DOCS+=$(MANUAL_BUILDDIR)/index.html
|
||||
ifdef CONFIG_VIRTFS
|
||||
DOCS+=$(MANUAL_BUILDDIR)/tools/virtfs-proxy-helper.1
|
||||
|
@ -767,10 +767,6 @@ distclean: clean
|
|||
rm -f $(SUBDIR_DEVICES_MAK)
|
||||
rm -f po/*.mo tests/qemu-iotests/common.env
|
||||
rm -f roms/seabios/config.mak roms/vgabios/config.mak
|
||||
rm -f qemu-doc.info qemu-doc.aux qemu-doc.cp qemu-doc.cps
|
||||
rm -f qemu-doc.fn qemu-doc.fns qemu-doc.info qemu-doc.ky qemu-doc.kys
|
||||
rm -f qemu-doc.log qemu-doc.pdf qemu-doc.pg qemu-doc.toc qemu-doc.tp
|
||||
rm -f qemu-doc.vr qemu-doc.txt
|
||||
rm -f qemu-plugins-ld.symbols qemu-plugins-ld64.symbols
|
||||
rm -f config.log
|
||||
rm -f linux-headers/asm
|
||||
|
@ -780,13 +776,13 @@ distclean: clean
|
|||
rm -f docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt
|
||||
rm -f docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf
|
||||
rm -f docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html
|
||||
rm -f docs/qemu-cpu-models.7
|
||||
rm -rf .doctrees
|
||||
$(call clean-manual,devel)
|
||||
$(call clean-manual,interop)
|
||||
$(call clean-manual,specs)
|
||||
$(call clean-manual,system)
|
||||
$(call clean-manual,tools)
|
||||
$(call clean-manual,user)
|
||||
for d in $(TARGET_DIRS); do \
|
||||
rm -rf $$d || exit 1 ; \
|
||||
done
|
||||
|
@ -845,21 +841,20 @@ install-sphinxdocs: sphinxdocs
|
|||
$(call install-manual,specs)
|
||||
$(call install-manual,system)
|
||||
$(call install-manual,tools)
|
||||
$(call install-manual,user)
|
||||
|
||||
install-doc: $(DOCS) install-sphinxdocs
|
||||
$(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)"
|
||||
$(INSTALL_DATA) $(MANUAL_BUILDDIR)/index.html "$(DESTDIR)$(qemu_docdir)"
|
||||
$(INSTALL_DATA) qemu-doc.html "$(DESTDIR)$(qemu_docdir)"
|
||||
$(INSTALL_DATA) qemu-doc.txt "$(DESTDIR)$(qemu_docdir)"
|
||||
$(INSTALL_DATA) docs/interop/qemu-qmp-ref.html "$(DESTDIR)$(qemu_docdir)"
|
||||
$(INSTALL_DATA) docs/interop/qemu-qmp-ref.txt "$(DESTDIR)$(qemu_docdir)"
|
||||
ifdef CONFIG_POSIX
|
||||
$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1"
|
||||
$(INSTALL_DATA) qemu.1 "$(DESTDIR)$(mandir)/man1"
|
||||
$(INSTALL_DATA) $(MANUAL_BUILDDIR)/system/qemu.1 "$(DESTDIR)$(mandir)/man1"
|
||||
$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man7"
|
||||
$(INSTALL_DATA) docs/interop/qemu-qmp-ref.7 "$(DESTDIR)$(mandir)/man7"
|
||||
$(INSTALL_DATA) $(MANUAL_BUILDDIR)/system/qemu-block-drivers.7 "$(DESTDIR)$(mandir)/man7"
|
||||
$(INSTALL_DATA) docs/qemu-cpu-models.7 "$(DESTDIR)$(mandir)/man7"
|
||||
$(INSTALL_DATA) $(MANUAL_BUILDDIR)/system/qemu-cpu-models.7 "$(DESTDIR)$(mandir)/man7"
|
||||
ifeq ($(CONFIG_TOOLS),y)
|
||||
$(INSTALL_DATA) $(MANUAL_BUILDDIR)/tools/qemu-img.1 "$(DESTDIR)$(mandir)/man1"
|
||||
$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man8"
|
||||
|
@ -1039,7 +1034,8 @@ sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html \
|
|||
$(MANUAL_BUILDDIR)/interop/index.html \
|
||||
$(MANUAL_BUILDDIR)/specs/index.html \
|
||||
$(MANUAL_BUILDDIR)/system/index.html \
|
||||
$(MANUAL_BUILDDIR)/tools/index.html
|
||||
$(MANUAL_BUILDDIR)/tools/index.html \
|
||||
$(MANUAL_BUILDDIR)/user/index.html
|
||||
|
||||
# Canned command to build a single manual
|
||||
# Arguments: $1 = manual name, $2 = Sphinx builder ('html' or 'man')
|
||||
|
@ -1049,6 +1045,7 @@ sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html \
|
|||
build-manual = $(call quiet-command,CONFDIR="$(qemu_confdir)" $(SPHINX_BUILD) $(if $(V),,-q) -W -b $2 -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1-$2 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1")
|
||||
# We assume all RST files in the manual's directory are used in it
|
||||
manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) \
|
||||
$(SRC_PATH)/docs/defs.rst.inc \
|
||||
$(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py
|
||||
# Macro to write out the rule and dependencies for building manpages
|
||||
# Usage: $(call define-manpage-rule,manualname,manpage1 manpage2...[,extradeps])
|
||||
|
@ -1068,15 +1065,18 @@ $(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop)
|
|||
$(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs)
|
||||
$(call build-manual,specs,html)
|
||||
|
||||
$(MANUAL_BUILDDIR)/system/index.html: $(call manual-deps,system)
|
||||
$(MANUAL_BUILDDIR)/system/index.html: $(call manual-deps,system) $(SRC_PATH)/hmp-commands.hx $(SRC_PATH)/hmp-commands-info.hx $(SRC_PATH)/qemu-options.hx
|
||||
$(call build-manual,system,html)
|
||||
|
||||
$(MANUAL_BUILDDIR)/tools/index.html: $(call manual-deps,tools) $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/docs/qemu-option-trace.rst.inc
|
||||
$(call build-manual,tools,html)
|
||||
|
||||
$(MANUAL_BUILDDIR)/user/index.html: $(call manual-deps,user)
|
||||
$(call build-manual,user,html)
|
||||
|
||||
$(call define-manpage-rule,interop,qemu-ga.8)
|
||||
|
||||
$(call define-manpage-rule,system,qemu-block-drivers.7)
|
||||
$(call define-manpage-rule,system,qemu.1 qemu-block-drivers.7 qemu-cpu-models.7)
|
||||
|
||||
$(call define-manpage-rule,tools,\
|
||||
qemu-img.1 qemu-nbd.8 qemu-trace-stap.1\
|
||||
|
@ -1103,21 +1103,10 @@ docs/interop/qemu-qmp-qapi.texi: qapi/qapi-doc.texi
|
|||
docs/interop/qemu-ga-qapi.texi: qga/qapi-generated/qga-qapi-doc.texi
|
||||
@cp -p $< $@
|
||||
|
||||
qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi qemu-monitor-info.texi
|
||||
qemu.1: qemu-option-trace.texi
|
||||
docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi
|
||||
|
||||
html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html sphinxdocs
|
||||
info: qemu-doc.info docs/interop/qemu-qmp-ref.info docs/interop/qemu-ga-ref.info
|
||||
pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf
|
||||
txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt
|
||||
|
||||
qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \
|
||||
qemu-options.texi \
|
||||
qemu-tech.texi qemu-option-trace.texi \
|
||||
qemu-deprecated.texi qemu-monitor.texi \
|
||||
qemu-monitor-info.texi \
|
||||
docs/qemu-cpu-models.texi docs/security.texi
|
||||
html: docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html sphinxdocs
|
||||
info: docs/interop/qemu-qmp-ref.info docs/interop/qemu-ga-ref.info
|
||||
pdf: docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf
|
||||
txt: docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt
|
||||
|
||||
docs/interop/qemu-ga-ref.dvi docs/interop/qemu-ga-ref.html \
|
||||
docs/interop/qemu-ga-ref.info docs/interop/qemu-ga-ref.pdf \
|
||||
|
|
|
@ -132,6 +132,12 @@ suppress_warnings = ["ref.option"]
|
|||
# style document building; our Makefile always sets the variable.
|
||||
confdir = os.getenv('CONFDIR', "/etc/qemu")
|
||||
rst_epilog = ".. |CONFDIR| replace:: ``" + confdir + "``\n"
|
||||
# We slurp in the defs.rst.inc and literally include it into rst_epilog,
|
||||
# because Sphinx's include:: directive doesn't work with absolute paths
|
||||
# and there isn't any one single relative path that will work for all
|
||||
# documents and for both via-make and direct sphinx-build invocation.
|
||||
with open(os.path.join(qemu_docdir, 'defs.rst.inc')) as f:
|
||||
rst_epilog += f.read()
|
||||
|
||||
# -- Options for HTML output ----------------------------------------------
|
||||
|
||||
|
|
15
docs/defs.rst.inc
Normal file
15
docs/defs.rst.inc
Normal file
|
@ -0,0 +1,15 @@
|
|||
..
|
||||
Generally useful rST substitution definitions. This is included for
|
||||
all rST files as part of the epilogue by docs/conf.py. conf.py
|
||||
also defines some dynamically generated substitutions like CONFDIR.
|
||||
|
||||
Note that |qemu_system| and |qemu_system_x86| are intended to be
|
||||
used inside a parsed-literal block: the definition must not include
|
||||
extra literal formatting with ``..``: this works in the HTML output
|
||||
but the manpages will end up misrendered with following normal text
|
||||
incorrectly in boldface.
|
||||
|
||||
.. |qemu_system| replace:: qemu-system-x86_64
|
||||
.. |qemu_system_x86| replace:: qemu_system-x86_64
|
||||
.. |I2C| replace:: I\ :sup:`2`\ C
|
||||
.. |I2S| replace:: I\ :sup:`2`\ S
|
|
@ -7,13 +7,13 @@
|
|||
<body>
|
||||
<h1>QEMU @@VERSION@@ Documentation</h1>
|
||||
<ul>
|
||||
<li><a href="qemu-doc.html">User Documentation</a></li>
|
||||
<li><a href="qemu-qmp-ref.html">QMP Reference Manual</a></li>
|
||||
<li><a href="qemu-ga-ref.html">Guest Agent Protocol Reference</a></li>
|
||||
<li><a href="interop/index.html">System Emulation Management and Interoperability Guide</a></li>
|
||||
<li><a href="specs/index.html">System Emulation Guest Hardware Specifications</a></li>
|
||||
<li><a href="system/index.html">System Emulation User's Guide</a></li>
|
||||
<li><a href="tools/index.html">Tools Guide</a></li>
|
||||
<li><a href="user/index.html">User Mode Emulation User's Guide</a></li>
|
||||
</ul>
|
||||
</body>
|
||||
</html>
|
||||
|
|
|
@ -15,3 +15,4 @@ Welcome to QEMU's documentation!
|
|||
specs/index
|
||||
system/index
|
||||
tools/index
|
||||
user/index
|
||||
|
|
|
@ -1,677 +0,0 @@
|
|||
@c man begin SYNOPSIS
|
||||
QEMU / KVM CPU model configuration
|
||||
@c man end
|
||||
|
||||
@set qemu_system_x86 qemu-system-x86_64
|
||||
|
||||
@c man begin DESCRIPTION
|
||||
|
||||
@menu
|
||||
* recommendations_cpu_models_x86:: Recommendations for KVM CPU model configuration on x86 hosts
|
||||
* recommendations_cpu_models_MIPS:: Supported CPU model configurations on MIPS hosts
|
||||
* cpu_model_syntax_apps:: Syntax for configuring CPU models
|
||||
@end menu
|
||||
|
||||
QEMU / KVM virtualization supports two ways to configure CPU models
|
||||
|
||||
@table @option
|
||||
|
||||
@item Host passthrough
|
||||
|
||||
This passes the host CPU model features, model, stepping, exactly to the
|
||||
guest. Note that KVM may filter out some host CPU model features if they
|
||||
cannot be supported with virtualization. Live migration is unsafe when
|
||||
this mode is used as libvirt / QEMU cannot guarantee a stable CPU is
|
||||
exposed to the guest across hosts. This is the recommended CPU to use,
|
||||
provided live migration is not required.
|
||||
|
||||
@item Named model
|
||||
|
||||
QEMU comes with a number of predefined named CPU models, that typically
|
||||
refer to specific generations of hardware released by Intel and AMD.
|
||||
These allow the guest VMs to have a degree of isolation from the host CPU,
|
||||
allowing greater flexibility in live migrating between hosts with differing
|
||||
hardware.
|
||||
@end table
|
||||
|
||||
In both cases, it is possible to optionally add or remove individual CPU
|
||||
features, to alter what is presented to the guest by default.
|
||||
|
||||
Libvirt supports a third way to configure CPU models known as "Host model".
|
||||
This uses the QEMU "Named model" feature, automatically picking a CPU model
|
||||
that is similar the host CPU, and then adding extra features to approximate
|
||||
the host model as closely as possible. This does not guarantee the CPU family,
|
||||
stepping, etc will precisely match the host CPU, as they would with "Host
|
||||
passthrough", but gives much of the benefit of passthrough, while making
|
||||
live migration safe.
|
||||
|
||||
@node recommendations_cpu_models_x86
|
||||
@subsection Recommendations for KVM CPU model configuration on x86 hosts
|
||||
|
||||
The information that follows provides recommendations for configuring
|
||||
CPU models on x86 hosts. The goals are to maximise performance, while
|
||||
protecting guest OS against various CPU hardware flaws, and optionally
|
||||
enabling live migration between hosts with heterogeneous CPU models.
|
||||
|
||||
@menu
|
||||
* preferred_cpu_models_intel_x86:: Preferred CPU models for Intel x86 hosts
|
||||
* important_cpu_features_intel_x86:: Important CPU features for Intel x86 hosts
|
||||
* preferred_cpu_models_amd_x86:: Preferred CPU models for AMD x86 hosts
|
||||
* important_cpu_features_amd_x86:: Important CPU features for AMD x86 hosts
|
||||
* default_cpu_models_x86:: Default x86 CPU models
|
||||
* other_non_recommended_cpu_models_x86:: Other non-recommended x86 CPUs
|
||||
@end menu
|
||||
|
||||
@node preferred_cpu_models_intel_x86
|
||||
@subsubsection Preferred CPU models for Intel x86 hosts
|
||||
|
||||
The following CPU models are preferred for use on Intel hosts. Administrators /
|
||||
applications are recommended to use the CPU model that matches the generation
|
||||
of the host CPUs in use. In a deployment with a mixture of host CPU models
|
||||
between machines, if live migration compatibility is required, use the newest
|
||||
CPU model that is compatible across all desired hosts.
|
||||
|
||||
@table @option
|
||||
@item @code{Skylake-Server}
|
||||
@item @code{Skylake-Server-IBRS}
|
||||
|
||||
Intel Xeon Processor (Skylake, 2016)
|
||||
|
||||
|
||||
@item @code{Skylake-Client}
|
||||
@item @code{Skylake-Client-IBRS}
|
||||
|
||||
Intel Core Processor (Skylake, 2015)
|
||||
|
||||
|
||||
@item @code{Broadwell}
|
||||
@item @code{Broadwell-IBRS}
|
||||
@item @code{Broadwell-noTSX}
|
||||
@item @code{Broadwell-noTSX-IBRS}
|
||||
|
||||
Intel Core Processor (Broadwell, 2014)
|
||||
|
||||
|
||||
@item @code{Haswell}
|
||||
@item @code{Haswell-IBRS}
|
||||
@item @code{Haswell-noTSX}
|
||||
@item @code{Haswell-noTSX-IBRS}
|
||||
|
||||
Intel Core Processor (Haswell, 2013)
|
||||
|
||||
|
||||
@item @code{IvyBridge}
|
||||
@item @code{IvyBridge-IBRS}
|
||||
|
||||
Intel Xeon E3-12xx v2 (Ivy Bridge, 2012)
|
||||
|
||||
|
||||
@item @code{SandyBridge}
|
||||
@item @code{SandyBridge-IBRS}
|
||||
|
||||
Intel Xeon E312xx (Sandy Bridge, 2011)
|
||||
|
||||
|
||||
@item @code{Westmere}
|
||||
@item @code{Westmere-IBRS}
|
||||
|
||||
Westmere E56xx/L56xx/X56xx (Nehalem-C, 2010)
|
||||
|
||||
|
||||
@item @code{Nehalem}
|
||||
@item @code{Nehalem-IBRS}
|
||||
|
||||
Intel Core i7 9xx (Nehalem Class Core i7, 2008)
|
||||
|
||||
|
||||
@item @code{Penryn}
|
||||
|
||||
Intel Core 2 Duo P9xxx (Penryn Class Core 2, 2007)
|
||||
|
||||
|
||||
@item @code{Conroe}
|
||||
|
||||
Intel Celeron_4x0 (Conroe/Merom Class Core 2, 2006)
|
||||
|
||||
@end table
|
||||
|
||||
@node important_cpu_features_intel_x86
|
||||
@subsubsection Important CPU features for Intel x86 hosts
|
||||
|
||||
The following are important CPU features that should be used on Intel x86
|
||||
hosts, when available in the host CPU. Some of them require explicit
|
||||
configuration to enable, as they are not included by default in some, or all,
|
||||
of the named CPU models listed above. In general all of these features are
|
||||
included if using "Host passthrough" or "Host model".
|
||||
|
||||
|
||||
@table @option
|
||||
|
||||
@item @code{pcid}
|
||||
|
||||
Recommended to mitigate the cost of the Meltdown (CVE-2017-5754) fix
|
||||
|
||||
Included by default in Haswell, Broadwell & Skylake Intel CPU models.
|
||||
|
||||
Should be explicitly turned on for Westmere, SandyBridge, and IvyBridge
|
||||
Intel CPU models. Note that some desktop/mobile Westmere CPUs cannot
|
||||
support this feature.
|
||||
|
||||
|
||||
@item @code{spec-ctrl}
|
||||
|
||||
Required to enable the Spectre v2 (CVE-2017-5715) fix.
|
||||
|
||||
Included by default in Intel CPU models with -IBRS suffix.
|
||||
|
||||
Must be explicitly turned on for Intel CPU models without -IBRS suffix.
|
||||
|
||||
Requires the host CPU microcode to support this feature before it
|
||||
can be used for guest CPUs.
|
||||
|
||||
|
||||
@item @code{stibp}
|
||||
|
||||
Required to enable stronger Spectre v2 (CVE-2017-5715) fixes in some
|
||||
operating systems.
|
||||
|
||||
Must be explicitly turned on for all Intel CPU models.
|
||||
|
||||
Requires the host CPU microcode to support this feature before it
|
||||
can be used for guest CPUs.
|
||||
|
||||
|
||||
@item @code{ssbd}
|
||||
|
||||
Required to enable the CVE-2018-3639 fix
|
||||
|
||||
Not included by default in any Intel CPU model.
|
||||
|
||||
Must be explicitly turned on for all Intel CPU models.
|
||||
|
||||
Requires the host CPU microcode to support this feature before it
|
||||
can be used for guest CPUs.
|
||||
|
||||
|
||||
@item @code{pdpe1gb}
|
||||
|
||||
Recommended to allow guest OS to use 1GB size pages
|
||||
|
||||
Not included by default in any Intel CPU model.
|
||||
|
||||
Should be explicitly turned on for all Intel CPU models.
|
||||
|
||||
Note that not all CPU hardware will support this feature.
|
||||
|
||||
@item @code{md-clear}
|
||||
|
||||
Required to confirm the MDS (CVE-2018-12126, CVE-2018-12127, CVE-2018-12130,
|
||||
CVE-2019-11091) fixes.
|
||||
|
||||
Not included by default in any Intel CPU model.
|
||||
|
||||
Must be explicitly turned on for all Intel CPU models.
|
||||
|
||||
Requires the host CPU microcode to support this feature before it
|
||||
can be used for guest CPUs.
|
||||
@end table
|
||||
|
||||
|
||||
@node preferred_cpu_models_amd_x86
|
||||
@subsubsection Preferred CPU models for AMD x86 hosts
|
||||
|
||||
The following CPU models are preferred for use on Intel hosts. Administrators /
|
||||
applications are recommended to use the CPU model that matches the generation
|
||||
of the host CPUs in use. In a deployment with a mixture of host CPU models
|
||||
between machines, if live migration compatibility is required, use the newest
|
||||
CPU model that is compatible across all desired hosts.
|
||||
|
||||
@table @option
|
||||
|
||||
@item @code{EPYC}
|
||||
@item @code{EPYC-IBPB}
|
||||
|
||||
AMD EPYC Processor (2017)
|
||||
|
||||
|
||||
@item @code{Opteron_G5}
|
||||
|
||||
AMD Opteron 63xx class CPU (2012)
|
||||
|
||||
|
||||
@item @code{Opteron_G4}
|
||||
|
||||
AMD Opteron 62xx class CPU (2011)
|
||||
|
||||
|
||||
@item @code{Opteron_G3}
|
||||
|
||||
AMD Opteron 23xx (Gen 3 Class Opteron, 2009)
|
||||
|
||||
|
||||
@item @code{Opteron_G2}
|
||||
|
||||
AMD Opteron 22xx (Gen 2 Class Opteron, 2006)
|
||||
|
||||
|
||||
@item @code{Opteron_G1}
|
||||
|
||||
AMD Opteron 240 (Gen 1 Class Opteron, 2004)
|
||||
@end table
|
||||
|
||||
@node important_cpu_features_amd_x86
|
||||
@subsubsection Important CPU features for AMD x86 hosts
|
||||
|
||||
The following are important CPU features that should be used on AMD x86
|
||||
hosts, when available in the host CPU. Some of them require explicit
|
||||
configuration to enable, as they are not included by default in some, or all,
|
||||
of the named CPU models listed above. In general all of these features are
|
||||
included if using "Host passthrough" or "Host model".
|
||||
|
||||
|
||||
@table @option
|
||||
|
||||
@item @code{ibpb}
|
||||
|
||||
Required to enable the Spectre v2 (CVE-2017-5715) fix.
|
||||
|
||||
Included by default in AMD CPU models with -IBPB suffix.
|
||||
|
||||
Must be explicitly turned on for AMD CPU models without -IBPB suffix.
|
||||
|
||||
Requires the host CPU microcode to support this feature before it
|
||||
can be used for guest CPUs.
|
||||
|
||||
|
||||
@item @code{stibp}
|
||||
|
||||
Required to enable stronger Spectre v2 (CVE-2017-5715) fixes in some
|
||||
operating systems.
|
||||
|
||||
Must be explicitly turned on for all AMD CPU models.
|
||||
|
||||
Requires the host CPU microcode to support this feature before it
|
||||
can be used for guest CPUs.
|
||||
|
||||
|
||||
@item @code{virt-ssbd}
|
||||
|
||||
Required to enable the CVE-2018-3639 fix
|
||||
|
||||
Not included by default in any AMD CPU model.
|
||||
|
||||
Must be explicitly turned on for all AMD CPU models.
|
||||
|
||||
This should be provided to guests, even if amd-ssbd is also
|
||||
provided, for maximum guest compatibility.
|
||||
|
||||
Note for some QEMU / libvirt versions, this must be force enabled
|
||||
when when using "Host model", because this is a virtual feature
|
||||
that doesn't exist in the physical host CPUs.
|
||||
|
||||
|
||||
@item @code{amd-ssbd}
|
||||
|
||||
Required to enable the CVE-2018-3639 fix
|
||||
|
||||
Not included by default in any AMD CPU model.
|
||||
|
||||
Must be explicitly turned on for all AMD CPU models.
|
||||
|
||||
This provides higher performance than virt-ssbd so should be
|
||||
exposed to guests whenever available in the host. virt-ssbd
|
||||
should none the less also be exposed for maximum guest
|
||||
compatibility as some kernels only know about virt-ssbd.
|
||||
|
||||
|
||||
@item @code{amd-no-ssb}
|
||||
|
||||
Recommended to indicate the host is not vulnerable CVE-2018-3639
|
||||
|
||||
Not included by default in any AMD CPU model.
|
||||
|
||||
Future hardware generations of CPU will not be vulnerable to
|
||||
CVE-2018-3639, and thus the guest should be told not to enable
|
||||
its mitigations, by exposing amd-no-ssb. This is mutually
|
||||
exclusive with virt-ssbd and amd-ssbd.
|
||||
|
||||
|
||||
@item @code{pdpe1gb}
|
||||
|
||||
Recommended to allow guest OS to use 1GB size pages
|
||||
|
||||
Not included by default in any AMD CPU model.
|
||||
|
||||
Should be explicitly turned on for all AMD CPU models.
|
||||
|
||||
Note that not all CPU hardware will support this feature.
|
||||
@end table
|
||||
|
||||
|
||||
@node default_cpu_models_x86
|
||||
@subsubsection Default x86 CPU models
|
||||
|
||||
The default QEMU CPU models are designed such that they can run on all hosts.
|
||||
If an application does not wish to do perform any host compatibility checks
|
||||
before launching guests, the default is guaranteed to work.
|
||||
|
||||
The default CPU models will, however, leave the guest OS vulnerable to various
|
||||
CPU hardware flaws, so their use is strongly discouraged. Applications should
|
||||
follow the earlier guidance to setup a better CPU configuration, with host
|
||||
passthrough recommended if live migration is not needed.
|
||||
|
||||
@table @option
|
||||
@item @code{qemu32}
|
||||
@item @code{qemu64}
|
||||
|
||||
QEMU Virtual CPU version 2.5+ (32 & 64 bit variants)
|
||||
|
||||
qemu64 is used for x86_64 guests and qemu32 is used for i686 guests, when no
|
||||
-cpu argument is given to QEMU, or no <cpu> is provided in libvirt XML.
|
||||
@end table
|
||||
|
||||
|
||||
@node other_non_recommended_cpu_models_x86
|
||||
@subsubsection Other non-recommended x86 CPUs
|
||||
|
||||
The following CPUs models are compatible with most AMD and Intel x86 hosts, but
|
||||
their usage is discouraged, as they expose a very limited featureset, which
|
||||
prevents guests having optimal performance.
|
||||
|
||||
@table @option
|
||||
|
||||
@item @code{kvm32}
|
||||
@item @code{kvm64}
|
||||
|
||||
Common KVM processor (32 & 64 bit variants)
|
||||
|
||||
Legacy models just for historical compatibility with ancient QEMU versions.
|
||||
|
||||
|
||||
@item @code{486}
|
||||
@item @code{athlon}
|
||||
@item @code{phenom}
|
||||
@item @code{coreduo}
|
||||
@item @code{core2duo}
|
||||
@item @code{n270}
|
||||
@item @code{pentium}
|
||||
@item @code{pentium2}
|
||||
@item @code{pentium3}
|
||||
|
||||
Various very old x86 CPU models, mostly predating the introduction of
|
||||
hardware assisted virtualization, that should thus not be required for
|
||||
running virtual machines.
|
||||
@end table
|
||||
|
||||
@node recommendations_cpu_models_MIPS
|
||||
@subsection Supported CPU model configurations on MIPS hosts
|
||||
|
||||
QEMU supports variety of MIPS CPU models:
|
||||
|
||||
@menu
|
||||
* cpu_models_MIPS32:: Supported CPU models for MIPS32 hosts
|
||||
* cpu_models_MIPS64:: Supported CPU models for MIPS64 hosts
|
||||
* cpu_models_nanoMIPS:: Supported CPU models for nanoMIPS hosts
|
||||
* preferred_cpu_models_MIPS:: Preferred CPU models for MIPS hosts
|
||||
@end menu
|
||||
|
||||
@node cpu_models_MIPS32
|
||||
@subsubsection Supported CPU models for MIPS32 hosts
|
||||
|
||||
The following CPU models are supported for use on MIPS32 hosts. Administrators /
|
||||
applications are recommended to use the CPU model that matches the generation
|
||||
of the host CPUs in use. In a deployment with a mixture of host CPU models
|
||||
between machines, if live migration compatibility is required, use the newest
|
||||
CPU model that is compatible across all desired hosts.
|
||||
|
||||
@table @option
|
||||
@item @code{mips32r6-generic}
|
||||
|
||||
MIPS32 Processor (Release 6, 2015)
|
||||
|
||||
|
||||
@item @code{P5600}
|
||||
|
||||
MIPS32 Processor (P5600, 2014)
|
||||
|
||||
|
||||
@item @code{M14K}
|
||||
@item @code{M14Kc}
|
||||
|
||||
MIPS32 Processor (M14K, 2009)
|
||||
|
||||
|
||||
@item @code{74Kf}
|
||||
|
||||
MIPS32 Processor (74K, 2007)
|
||||
|
||||
|
||||
@item @code{34Kf}
|
||||
|
||||
MIPS32 Processor (34K, 2006)
|
||||
|
||||
|
||||
@item @code{24Kc}
|
||||
@item @code{24KEc}
|
||||
@item @code{24Kf}
|
||||
|
||||
MIPS32 Processor (24K, 2003)
|
||||
|
||||
|
||||
@item @code{4Kc}
|
||||
@item @code{4Km}
|
||||
@item @code{4KEcR1}
|
||||
@item @code{4KEmR1}
|
||||
@item @code{4KEc}
|
||||
@item @code{4KEm}
|
||||
|
||||
MIPS32 Processor (4K, 1999)
|
||||
@end table
|
||||
|
||||
@node cpu_models_MIPS64
|
||||
@subsubsection Supported CPU models for MIPS64 hosts
|
||||
|
||||
The following CPU models are supported for use on MIPS64 hosts. Administrators /
|
||||
applications are recommended to use the CPU model that matches the generation
|
||||
of the host CPUs in use. In a deployment with a mixture of host CPU models
|
||||
between machines, if live migration compatibility is required, use the newest
|
||||
CPU model that is compatible across all desired hosts.
|
||||
|
||||
@table @option
|
||||
@item @code{I6400}
|
||||
|
||||
MIPS64 Processor (Release 6, 2014)
|
||||
|
||||
|
||||
@item @code{Loongson-2F}
|
||||
|
||||
MIPS64 Processor (Loongson 2, 2008)
|
||||
|
||||
|
||||
@item @code{Loongson-2E}
|
||||
|
||||
MIPS64 Processor (Loongson 2, 2006)
|
||||
|
||||
|
||||
@item @code{mips64dspr2}
|
||||
|
||||
MIPS64 Processor (Release 2, 2006)
|
||||
|
||||
|
||||
@item @code{MIPS64R2-generic}
|
||||
@item @code{5KEc}
|
||||
@item @code{5KEf}
|
||||
|
||||
MIPS64 Processor (Release 2, 2002)
|
||||
|
||||
|
||||
@item @code{20Kc}
|
||||
|
||||
MIPS64 Processor (20K, 2000)
|
||||
|
||||
|
||||
@item @code{5Kc}
|
||||
@item @code{5Kf}
|
||||
|
||||
MIPS64 Processor (5K, 1999)
|
||||
|
||||
|
||||
@item @code{VR5432}
|
||||
|
||||
MIPS64 Processor (VR, 1998)
|
||||
|
||||
|
||||
@item @code{R4000}
|
||||
|
||||
MIPS64 Processor (MIPS III, 1991)
|
||||
@end table
|
||||
|
||||
@node cpu_models_nanoMIPS
|
||||
@subsubsection Supported CPU models for nanoMIPS hosts
|
||||
|
||||
The following CPU models are supported for use on nanoMIPS hosts. Administrators /
|
||||
applications are recommended to use the CPU model that matches the generation
|
||||
of the host CPUs in use. In a deployment with a mixture of host CPU models
|
||||
between machines, if live migration compatibility is required, use the newest
|
||||
CPU model that is compatible across all desired hosts.
|
||||
|
||||
@table @option
|
||||
@item @code{I7200}
|
||||
|
||||
MIPS I7200 (nanoMIPS, 2018)
|
||||
|
||||
@end table
|
||||
|
||||
@node preferred_cpu_models_MIPS
|
||||
@subsubsection Preferred CPU models for MIPS hosts
|
||||
|
||||
The following CPU models are preferred for use on different MIPS hosts:
|
||||
|
||||
@table @option
|
||||
@item @code{MIPS III}
|
||||
R4000
|
||||
|
||||
@item @code{MIPS32R2}
|
||||
34Kf
|
||||
|
||||
@item @code{MIPS64R6}
|
||||
I6400
|
||||
|
||||
@item @code{nanoMIPS}
|
||||
I7200
|
||||
@end table
|
||||
|
||||
@node cpu_model_syntax_apps
|
||||
@subsection Syntax for configuring CPU models
|
||||
|
||||
The example below illustrate the approach to configuring the various
|
||||
CPU models / features in QEMU and libvirt
|
||||
|
||||
@menu
|
||||
* cpu_model_syntax_qemu:: QEMU command line
|
||||
* cpu_model_syntax_libvirt:: Libvirt guest XML
|
||||
@end menu
|
||||
|
||||
@node cpu_model_syntax_qemu
|
||||
@subsubsection QEMU command line
|
||||
|
||||
@table @option
|
||||
|
||||
@item Host passthrough
|
||||
|
||||
@example
|
||||
$ @value{qemu_system_x86} -cpu host
|
||||
@end example
|
||||
|
||||
With feature customization:
|
||||
|
||||
@example
|
||||
$ @value{qemu_system_x86} -cpu host,-vmx,...
|
||||
@end example
|
||||
|
||||
@item Named CPU models
|
||||
|
||||
@example
|
||||
$ @value{qemu_system_x86} -cpu Westmere
|
||||
@end example
|
||||
|
||||
With feature customization:
|
||||
|
||||
@example
|
||||
$ @value{qemu_system_x86} -cpu Westmere,+pcid,...
|
||||
@end example
|
||||
|
||||
@end table
|
||||
|
||||
@node cpu_model_syntax_libvirt
|
||||
@subsubsection Libvirt guest XML
|
||||
|
||||
@table @option
|
||||
|
||||
@item Host passthrough
|
||||
|
||||
@example
|
||||
<cpu mode='host-passthrough'/>
|
||||
@end example
|
||||
|
||||
With feature customization:
|
||||
|
||||
@example
|
||||
<cpu mode='host-passthrough'>
|
||||
<feature name="vmx" policy="disable"/>
|
||||
...
|
||||
</cpu>
|
||||
@end example
|
||||
|
||||
@item Host model
|
||||
|
||||
@example
|
||||
<cpu mode='host-model'/>
|
||||
@end example
|
||||
|
||||
With feature customization:
|
||||
|
||||
@example
|
||||
<cpu mode='host-model'>
|
||||
<feature name="vmx" policy="disable"/>
|
||||
...
|
||||
</cpu>
|
||||
@end example
|
||||
|
||||
@item Named model
|
||||
|
||||
@example
|
||||
<cpu mode='custom'>
|
||||
<model name="Westmere"/>
|
||||
</cpu>
|
||||
@end example
|
||||
|
||||
With feature customization:
|
||||
|
||||
@example
|
||||
<cpu mode='custom'>
|
||||
<model name="Westmere"/>
|
||||
<feature name="pcid" policy="require"/>
|
||||
...
|
||||
</cpu>
|
||||
@end example
|
||||
|
||||
@end table
|
||||
|
||||
@c man end
|
||||
|
||||
@ignore
|
||||
|
||||
@setfilename qemu-cpu-models
|
||||
@settitle QEMU / KVM CPU model configuration
|
||||
|
||||
@c man begin SEEALSO
|
||||
The HTML documentation of QEMU for more precise information and Linux
|
||||
user mode emulator invocation.
|
||||
@c man end
|
||||
|
||||
@c man begin AUTHOR
|
||||
Daniel P. Berrange
|
||||
@c man end
|
||||
|
||||
@end ignore
|
|
@ -38,8 +38,8 @@ There are two basic configurations:
|
|||
Interrupts are message-signaled (MSI-X). vectors=N configures the
|
||||
number of vectors to use.
|
||||
|
||||
For more details on ivshmem device properties, see The QEMU Emulator
|
||||
User Documentation (qemu-doc.*).
|
||||
For more details on ivshmem device properties, see the QEMU Emulator
|
||||
user documentation.
|
||||
|
||||
|
||||
== The ivshmem PCI device's guest interface ==
|
||||
|
|
|
@ -60,8 +60,9 @@ def parse_defheading(file, lnum, line):
|
|||
# empty we ignore the directive -- these are used only to add
|
||||
# blank lines in the plain-text content of the --help output.
|
||||
#
|
||||
# Return the heading text
|
||||
match = re.match(r'DEFHEADING\((.*)\)', line)
|
||||
# Return the heading text. We strip out any trailing ':' for
|
||||
# consistency with other headings in the rST documentation.
|
||||
match = re.match(r'DEFHEADING\((.*?):?\)', line)
|
||||
if match is None:
|
||||
serror(file, lnum, "Invalid DEFHEADING line")
|
||||
return match.group(1)
|
||||
|
@ -72,8 +73,9 @@ def parse_archheading(file, lnum, line):
|
|||
# though note that the 'some string' could be the empty string.
|
||||
# As with DEFHEADING, empty string ARCHHEADINGs will be ignored.
|
||||
#
|
||||
# Return the heading text
|
||||
match = re.match(r'ARCHHEADING\((.*),.*\)', line)
|
||||
# Return the heading text. We strip out any trailing ':' for
|
||||
# consistency with other headings in the rST documentation.
|
||||
match = re.match(r'ARCHHEADING\((.*?):?,.*\)', line)
|
||||
if match is None:
|
||||
serror(file, lnum, "Invalid ARCHHEADING line")
|
||||
return match.group(1)
|
||||
|
|
79
docs/system/build-platforms.rst
Normal file
79
docs/system/build-platforms.rst
Normal file
|
@ -0,0 +1,79 @@
|
|||
.. _Supported-build-platforms:
|
||||
|
||||
Supported build platforms
|
||||
=========================
|
||||
|
||||
QEMU aims to support building and executing on multiple host OS
|
||||
platforms. This appendix outlines which platforms are the major build
|
||||
targets. These platforms are used as the basis for deciding upon the
|
||||
minimum required versions of 3rd party software QEMU depends on. The
|
||||
supported platforms are the targets for automated testing performed by
|
||||
the project when patches are submitted for review, and tested before and
|
||||
after merge.
|
||||
|
||||
If a platform is not listed here, it does not imply that QEMU won't
|
||||
work. If an unlisted platform has comparable software versions to a
|
||||
listed platform, there is every expectation that it will work. Bug
|
||||
reports are welcome for problems encountered on unlisted platforms
|
||||
unless they are clearly older vintage than what is described here.
|
||||
|
||||
Note that when considering software versions shipped in distros as
|
||||
support targets, QEMU considers only the version number, and assumes the
|
||||
features in that distro match the upstream release with the same
|
||||
version. In other words, if a distro backports extra features to the
|
||||
software in their distro, QEMU upstream code will not add explicit
|
||||
support for those backports, unless the feature is auto-detectable in a
|
||||
manner that works for the upstream releases too.
|
||||
|
||||
The Repology site https://repology.org is a useful resource to identify
|
||||
currently shipped versions of software in various operating systems,
|
||||
though it does not cover all distros listed below.
|
||||
|
||||
Linux OS
|
||||
--------
|
||||
|
||||
For distributions with frequent, short-lifetime releases, the project
|
||||
will aim to support all versions that are not end of life by their
|
||||
respective vendors. For the purposes of identifying supported software
|
||||
versions, the project will look at Fedora, Ubuntu, and openSUSE distros.
|
||||
Other short- lifetime distros will be assumed to ship similar software
|
||||
versions.
|
||||
|
||||
For distributions with long-lifetime releases, the project will aim to
|
||||
support the most recent major version at all times. Support for the
|
||||
previous major version will be dropped 2 years after the new major
|
||||
version is released, or when it reaches "end of life". For the purposes
|
||||
of identifying supported software versions, the project will look at
|
||||
RHEL, Debian, Ubuntu LTS, and SLES distros. Other long-lifetime distros
|
||||
will be assumed to ship similar software versions.
|
||||
|
||||
Windows
|
||||
-------
|
||||
|
||||
The project supports building with current versions of the MinGW
|
||||
toolchain, hosted on Linux.
|
||||
|
||||
macOS
|
||||
-----
|
||||
|
||||
The project supports building with the two most recent versions of
|
||||
macOS, with the current homebrew package set available.
|
||||
|
||||
FreeBSD
|
||||
-------
|
||||
|
||||
The project aims to support the all the versions which are not end of
|
||||
life.
|
||||
|
||||
NetBSD
|
||||
------
|
||||
|
||||
The project aims to support the most recent major version at all times.
|
||||
Support for the previous major version will be dropped 2 years after the
|
||||
new major version is released.
|
||||
|
||||
OpenBSD
|
||||
-------
|
||||
|
||||
The project aims to support the all the versions which are not end of
|
||||
life.
|
|
@ -13,10 +13,16 @@ exec(compile(open(parent_config, "rb").read(), parent_config, 'exec'))
|
|||
# This slightly misuses the 'description', but is the best way to get
|
||||
# the manual title to appear in the sidebar.
|
||||
html_theme_options['description'] = u'System Emulation User''s Guide'
|
||||
|
||||
# One entry per manual page. List of tuples
|
||||
# (source start file, name, description, authors, manual section).
|
||||
man_pages = [
|
||||
('qemu-manpage', 'qemu', u'QEMU User Documentation',
|
||||
['Fabrice Bellard'], 1),
|
||||
('qemu-block-drivers', 'qemu-block-drivers',
|
||||
u'QEMU block drivers reference',
|
||||
['Fabrice Bellard and the QEMU Project developers'], 7)
|
||||
['Fabrice Bellard and the QEMU Project developers'], 7),
|
||||
('qemu-cpu-models', 'qemu-cpu-models',
|
||||
u'QEMU CPU Models',
|
||||
['The QEMU Project developers'], 7)
|
||||
]
|
||||
|
|
105
docs/system/cpu-models-mips.rst.inc
Normal file
105
docs/system/cpu-models-mips.rst.inc
Normal file
|
@ -0,0 +1,105 @@
|
|||
Supported CPU model configurations on MIPS hosts
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
QEMU supports variety of MIPS CPU models:
|
||||
|
||||
Supported CPU models for MIPS32 hosts
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The following CPU models are supported for use on MIPS32 hosts.
|
||||
Administrators / applications are recommended to use the CPU model that
|
||||
matches the generation of the host CPUs in use. In a deployment with a
|
||||
mixture of host CPU models between machines, if live migration
|
||||
compatibility is required, use the newest CPU model that is compatible
|
||||
across all desired hosts.
|
||||
|
||||
``mips32r6-generic``
|
||||
MIPS32 Processor (Release 6, 2015)
|
||||
|
||||
``P5600``
|
||||
MIPS32 Processor (P5600, 2014)
|
||||
|
||||
``M14K``, ``M14Kc``
|
||||
MIPS32 Processor (M14K, 2009)
|
||||
|
||||
``74Kf``
|
||||
MIPS32 Processor (74K, 2007)
|
||||
|
||||
``34Kf``
|
||||
MIPS32 Processor (34K, 2006)
|
||||
|
||||
``24Kc``, ``24KEc``, ``24Kf``
|
||||
MIPS32 Processor (24K, 2003)
|
||||
|
||||
``4Kc``, ``4Km``, ``4KEcR1``, ``4KEmR1``, ``4KEc``, ``4KEm``
|
||||
MIPS32 Processor (4K, 1999)
|
||||
|
||||
|
||||
Supported CPU models for MIPS64 hosts
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The following CPU models are supported for use on MIPS64 hosts.
|
||||
Administrators / applications are recommended to use the CPU model that
|
||||
matches the generation of the host CPUs in use. In a deployment with a
|
||||
mixture of host CPU models between machines, if live migration
|
||||
compatibility is required, use the newest CPU model that is compatible
|
||||
across all desired hosts.
|
||||
|
||||
``I6400``
|
||||
MIPS64 Processor (Release 6, 2014)
|
||||
|
||||
``Loongson-2F``
|
||||
MIPS64 Processor (Loongson 2, 2008)
|
||||
|
||||
``Loongson-2E``
|
||||
MIPS64 Processor (Loongson 2, 2006)
|
||||
|
||||
``mips64dspr2``
|
||||
MIPS64 Processor (Release 2, 2006)
|
||||
|
||||
``MIPS64R2-generic``, ``5KEc``, ``5KEf``
|
||||
MIPS64 Processor (Release 2, 2002)
|
||||
|
||||
``20Kc``
|
||||
MIPS64 Processor (20K, 2000
|
||||
|
||||
``5Kc``, ``5Kf``
|
||||
MIPS64 Processor (5K, 1999)
|
||||
|
||||
``VR5432``
|
||||
MIPS64 Processor (VR, 1998)
|
||||
|
||||
``R4000``
|
||||
MIPS64 Processor (MIPS III, 1991)
|
||||
|
||||
|
||||
Supported CPU models for nanoMIPS hosts
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The following CPU models are supported for use on nanoMIPS hosts.
|
||||
Administrators / applications are recommended to use the CPU model that
|
||||
matches the generation of the host CPUs in use. In a deployment with a
|
||||
mixture of host CPU models between machines, if live migration
|
||||
compatibility is required, use the newest CPU model that is compatible
|
||||
across all desired hosts.
|
||||
|
||||
``I7200``
|
||||
MIPS I7200 (nanoMIPS, 2018)
|
||||
|
||||
Preferred CPU models for MIPS hosts
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The following CPU models are preferred for use on different MIPS hosts:
|
||||
|
||||
``MIPS III``
|
||||
R4000
|
||||
|
||||
``MIPS32R2``
|
||||
34Kf
|
||||
|
||||
``MIPS64R6``
|
||||
I6400
|
||||
|
||||
``nanoMIPS``
|
||||
I7200
|
||||
|
365
docs/system/cpu-models-x86.rst.inc
Normal file
365
docs/system/cpu-models-x86.rst.inc
Normal file
|
@ -0,0 +1,365 @@
|
|||
Recommendations for KVM CPU model configuration on x86 hosts
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The information that follows provides recommendations for configuring
|
||||
CPU models on x86 hosts. The goals are to maximise performance, while
|
||||
protecting guest OS against various CPU hardware flaws, and optionally
|
||||
enabling live migration between hosts with heterogeneous CPU models.
|
||||
|
||||
|
||||
Two ways to configure CPU models with QEMU / KVM
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
(1) **Host passthrough**
|
||||
|
||||
This passes the host CPU model features, model, stepping, exactly to
|
||||
the guest. Note that KVM may filter out some host CPU model features
|
||||
if they cannot be supported with virtualization. Live migration is
|
||||
unsafe when this mode is used as libvirt / QEMU cannot guarantee a
|
||||
stable CPU is exposed to the guest across hosts. This is the
|
||||
recommended CPU to use, provided live migration is not required.
|
||||
|
||||
(2) **Named model**
|
||||
|
||||
QEMU comes with a number of predefined named CPU models, that
|
||||
typically refer to specific generations of hardware released by
|
||||
Intel and AMD. These allow the guest VMs to have a degree of
|
||||
isolation from the host CPU, allowing greater flexibility in live
|
||||
migrating between hosts with differing hardware. @end table
|
||||
|
||||
In both cases, it is possible to optionally add or remove individual CPU
|
||||
features, to alter what is presented to the guest by default.
|
||||
|
||||
Libvirt supports a third way to configure CPU models known as "Host
|
||||
model". This uses the QEMU "Named model" feature, automatically picking
|
||||
a CPU model that is similar the host CPU, and then adding extra features
|
||||
to approximate the host model as closely as possible. This does not
|
||||
guarantee the CPU family, stepping, etc will precisely match the host
|
||||
CPU, as they would with "Host passthrough", but gives much of the
|
||||
benefit of passthrough, while making live migration safe.
|
||||
|
||||
|
||||
Preferred CPU models for Intel x86 hosts
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The following CPU models are preferred for use on Intel hosts.
|
||||
Administrators / applications are recommended to use the CPU model that
|
||||
matches the generation of the host CPUs in use. In a deployment with a
|
||||
mixture of host CPU models between machines, if live migration
|
||||
compatibility is required, use the newest CPU model that is compatible
|
||||
across all desired hosts.
|
||||
|
||||
``Skylake-Server``, ``Skylake-Server-IBRS``
|
||||
Intel Xeon Processor (Skylake, 2016)
|
||||
|
||||
``Skylake-Client``, ``Skylake-Client-IBRS``
|
||||
Intel Core Processor (Skylake, 2015)
|
||||
|
||||
``Broadwell``, ``Broadwell-IBRS``, ``Broadwell-noTSX``, ``Broadwell-noTSX-IBRS``
|
||||
Intel Core Processor (Broadwell, 2014)
|
||||
|
||||
``Haswell``, ``Haswell-IBRS``, ``Haswell-noTSX``, ``Haswell-noTSX-IBRS``
|
||||
Intel Core Processor (Haswell, 2013)
|
||||
|
||||
``IvyBridge``, ``IvyBridge-IBR``
|
||||
Intel Xeon E3-12xx v2 (Ivy Bridge, 2012)
|
||||
|
||||
``SandyBridge``, ``SandyBridge-IBRS``
|
||||
Intel Xeon E312xx (Sandy Bridge, 2011)
|
||||
|
||||
``Westmere``, ``Westmere-IBRS``
|
||||
Westmere E56xx/L56xx/X56xx (Nehalem-C, 2010)
|
||||
|
||||
``Nehalem``, ``Nehalem-IBRS``
|
||||
Intel Core i7 9xx (Nehalem Class Core i7, 2008)
|
||||
|
||||
``Penryn``
|
||||
Intel Core 2 Duo P9xxx (Penryn Class Core 2, 2007)
|
||||
|
||||
``Conroe``
|
||||
Intel Celeron_4x0 (Conroe/Merom Class Core 2, 2006)
|
||||
|
||||
|
||||
Important CPU features for Intel x86 hosts
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The following are important CPU features that should be used on Intel
|
||||
x86 hosts, when available in the host CPU. Some of them require explicit
|
||||
configuration to enable, as they are not included by default in some, or
|
||||
all, of the named CPU models listed above. In general all of these
|
||||
features are included if using "Host passthrough" or "Host model".
|
||||
|
||||
``pcid``
|
||||
Recommended to mitigate the cost of the Meltdown (CVE-2017-5754) fix.
|
||||
|
||||
Included by default in Haswell, Broadwell & Skylake Intel CPU models.
|
||||
|
||||
Should be explicitly turned on for Westmere, SandyBridge, and
|
||||
IvyBridge Intel CPU models. Note that some desktop/mobile Westmere
|
||||
CPUs cannot support this feature.
|
||||
|
||||
``spec-ctrl``
|
||||
Required to enable the Spectre v2 (CVE-2017-5715) fix.
|
||||
|
||||
Included by default in Intel CPU models with -IBRS suffix.
|
||||
|
||||
Must be explicitly turned on for Intel CPU models without -IBRS
|
||||
suffix.
|
||||
|
||||
Requires the host CPU microcode to support this feature before it
|
||||
can be used for guest CPUs.
|
||||
|
||||
``stibp``
|
||||
Required to enable stronger Spectre v2 (CVE-2017-5715) fixes in some
|
||||
operating systems.
|
||||
|
||||
Must be explicitly turned on for all Intel CPU models.
|
||||
|
||||
Requires the host CPU microcode to support this feature before it can
|
||||
be used for guest CPUs.
|
||||
|
||||
``ssbd``
|
||||
Required to enable the CVE-2018-3639 fix.
|
||||
|
||||
Not included by default in any Intel CPU model.
|
||||
|
||||
Must be explicitly turned on for all Intel CPU models.
|
||||
|
||||
Requires the host CPU microcode to support this feature before it
|
||||
can be used for guest CPUs.
|
||||
|
||||
``pdpe1gb``
|
||||
Recommended to allow guest OS to use 1GB size pages.
|
||||
|
||||
Not included by default in any Intel CPU model.
|
||||
|
||||
Should be explicitly turned on for all Intel CPU models.
|
||||
|
||||
Note that not all CPU hardware will support this feature.
|
||||
|
||||
``md-clear``
|
||||
Required to confirm the MDS (CVE-2018-12126, CVE-2018-12127,
|
||||
CVE-2018-12130, CVE-2019-11091) fixes.
|
||||
|
||||
Not included by default in any Intel CPU model.
|
||||
|
||||
Must be explicitly turned on for all Intel CPU models.
|
||||
|
||||
Requires the host CPU microcode to support this feature before it
|
||||
can be used for guest CPUs.
|
||||
|
||||
|
||||
Preferred CPU models for AMD x86 hosts
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The following CPU models are preferred for use on Intel hosts.
|
||||
Administrators / applications are recommended to use the CPU model that
|
||||
matches the generation of the host CPUs in use. In a deployment with a
|
||||
mixture of host CPU models between machines, if live migration
|
||||
compatibility is required, use the newest CPU model that is compatible
|
||||
across all desired hosts.
|
||||
|
||||
``EPYC``, ``EPYC-IBPB``
|
||||
AMD EPYC Processor (2017)
|
||||
|
||||
``Opteron_G5``
|
||||
AMD Opteron 63xx class CPU (2012)
|
||||
|
||||
``Opteron_G4``
|
||||
AMD Opteron 62xx class CPU (2011)
|
||||
|
||||
``Opteron_G3``
|
||||
AMD Opteron 23xx (Gen 3 Class Opteron, 2009)
|
||||
|
||||
``Opteron_G2``
|
||||
AMD Opteron 22xx (Gen 2 Class Opteron, 2006)
|
||||
|
||||
``Opteron_G1``
|
||||
AMD Opteron 240 (Gen 1 Class Opteron, 2004)
|
||||
|
||||
|
||||
Important CPU features for AMD x86 hosts
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The following are important CPU features that should be used on AMD x86
|
||||
hosts, when available in the host CPU. Some of them require explicit
|
||||
configuration to enable, as they are not included by default in some, or
|
||||
all, of the named CPU models listed above. In general all of these
|
||||
features are included if using "Host passthrough" or "Host model".
|
||||
|
||||
``ibpb``
|
||||
Required to enable the Spectre v2 (CVE-2017-5715) fix.
|
||||
|
||||
Included by default in AMD CPU models with -IBPB suffix.
|
||||
|
||||
Must be explicitly turned on for AMD CPU models without -IBPB suffix.
|
||||
|
||||
Requires the host CPU microcode to support this feature before it
|
||||
can be used for guest CPUs.
|
||||
|
||||
``stibp``
|
||||
Required to enable stronger Spectre v2 (CVE-2017-5715) fixes in some
|
||||
operating systems.
|
||||
|
||||
Must be explicitly turned on for all AMD CPU models.
|
||||
|
||||
Requires the host CPU microcode to support this feature before it
|
||||
can be used for guest CPUs.
|
||||
|
||||
``virt-ssbd``
|
||||
Required to enable the CVE-2018-3639 fix
|
||||
|
||||
Not included by default in any AMD CPU model.
|
||||
|
||||
Must be explicitly turned on for all AMD CPU models.
|
||||
|
||||
This should be provided to guests, even if amd-ssbd is also provided,
|
||||
for maximum guest compatibility.
|
||||
|
||||
Note for some QEMU / libvirt versions, this must be force enabled when
|
||||
when using "Host model", because this is a virtual feature that
|
||||
doesn't exist in the physical host CPUs.
|
||||
|
||||
``amd-ssbd``
|
||||
Required to enable the CVE-2018-3639 fix
|
||||
|
||||
Not included by default in any AMD CPU model.
|
||||
|
||||
Must be explicitly turned on for all AMD CPU models.
|
||||
|
||||
This provides higher performance than ``virt-ssbd`` so should be
|
||||
exposed to guests whenever available in the host. ``virt-ssbd`` should
|
||||
none the less also be exposed for maximum guest compatibility as some
|
||||
kernels only know about ``virt-ssbd``.
|
||||
|
||||
``amd-no-ssb``
|
||||
Recommended to indicate the host is not vulnerable CVE-2018-3639
|
||||
|
||||
Not included by default in any AMD CPU model.
|
||||
|
||||
Future hardware generations of CPU will not be vulnerable to
|
||||
CVE-2018-3639, and thus the guest should be told not to enable
|
||||
its mitigations, by exposing amd-no-ssb. This is mutually
|
||||
exclusive with virt-ssbd and amd-ssbd.
|
||||
|
||||
``pdpe1gb``
|
||||
Recommended to allow guest OS to use 1GB size pages
|
||||
|
||||
Not included by default in any AMD CPU model.
|
||||
|
||||
Should be explicitly turned on for all AMD CPU models.
|
||||
|
||||
Note that not all CPU hardware will support this feature.
|
||||
|
||||
|
||||
Default x86 CPU models
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The default QEMU CPU models are designed such that they can run on all
|
||||
hosts. If an application does not wish to do perform any host
|
||||
compatibility checks before launching guests, the default is guaranteed
|
||||
to work.
|
||||
|
||||
The default CPU models will, however, leave the guest OS vulnerable to
|
||||
various CPU hardware flaws, so their use is strongly discouraged.
|
||||
Applications should follow the earlier guidance to setup a better CPU
|
||||
configuration, with host passthrough recommended if live migration is
|
||||
not needed.
|
||||
|
||||
``qemu32``, ``qemu64``
|
||||
QEMU Virtual CPU version 2.5+ (32 & 64 bit variants)
|
||||
|
||||
``qemu64`` is used for x86_64 guests and ``qemu32`` is used for i686
|
||||
guests, when no ``-cpu`` argument is given to QEMU, or no ``<cpu>`` is
|
||||
provided in libvirt XML.
|
||||
|
||||
Other non-recommended x86 CPUs
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The following CPUs models are compatible with most AMD and Intel x86
|
||||
hosts, but their usage is discouraged, as they expose a very limited
|
||||
featureset, which prevents guests having optimal performance.
|
||||
|
||||
``kvm32``, ``kvm64``
|
||||
Common KVM processor (32 & 64 bit variants).
|
||||
|
||||
Legacy models just for historical compatibility with ancient QEMU
|
||||
versions.
|
||||
|
||||
``486``, ``athlon``, ``phenom``, ``coreduo``, ``core2duo``, ``n270``, ``pentium``, ``pentium2``, ``pentium3``
|
||||
Various very old x86 CPU models, mostly predating the introduction
|
||||
of hardware assisted virtualization, that should thus not be
|
||||
required for running virtual machines.
|
||||
|
||||
|
||||
Syntax for configuring CPU models
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The examples below illustrate the approach to configuring the various
|
||||
CPU models / features in QEMU and libvirt.
|
||||
|
||||
QEMU command line
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
Host passthrough:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -cpu host
|
||||
|
||||
Host passthrough with feature customization:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -cpu host,-vmx,...
|
||||
|
||||
Named CPU models:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -cpu Westmere
|
||||
|
||||
Named CPU models with feature customization:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -cpu Westmere,+pcid,...
|
||||
|
||||
Libvirt guest XML
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
Host passthrough::
|
||||
|
||||
<cpu mode='host-passthrough'/>
|
||||
|
||||
Host passthrough with feature customization::
|
||||
|
||||
<cpu mode='host-passthrough'>
|
||||
<feature name="vmx" policy="disable"/>
|
||||
...
|
||||
</cpu>
|
||||
|
||||
Host model::
|
||||
|
||||
<cpu mode='host-model'/>
|
||||
|
||||
Host model with feature customization::
|
||||
|
||||
<cpu mode='host-model'>
|
||||
<feature name="vmx" policy="disable"/>
|
||||
...
|
||||
</cpu>
|
||||
|
||||
Named model::
|
||||
|
||||
<cpu mode='custom'>
|
||||
<model name="Westmere"/>
|
||||
</cpu>
|
||||
|
||||
Named model with feature customization::
|
||||
|
||||
<cpu mode='custom'>
|
||||
<model name="Westmere"/>
|
||||
<feature name="pcid" policy="require"/>
|
||||
...
|
||||
</cpu>
|
446
docs/system/deprecated.rst
Normal file
446
docs/system/deprecated.rst
Normal file
|
@ -0,0 +1,446 @@
|
|||
Deprecated features
|
||||
===================
|
||||
|
||||
In general features are intended to be supported indefinitely once
|
||||
introduced into QEMU. In the event that a feature needs to be removed,
|
||||
it will be listed in this section. The feature will remain functional
|
||||
for 2 releases prior to actual removal. Deprecated features may also
|
||||
generate warnings on the console when QEMU starts up, or if activated
|
||||
via a monitor command, however, this is not a mandatory requirement.
|
||||
|
||||
Prior to the 2.10.0 release there was no official policy on how
|
||||
long features would be deprecated prior to their removal, nor
|
||||
any documented list of which features were deprecated. Thus
|
||||
any features deprecated prior to 2.10.0 will be treated as if
|
||||
they were first deprecated in the 2.10.0 release.
|
||||
|
||||
What follows is a list of all features currently marked as
|
||||
deprecated.
|
||||
|
||||
System emulator command line arguments
|
||||
--------------------------------------
|
||||
|
||||
``-machine enforce-config-section=on|off`` (since 3.1)
|
||||
''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The ``enforce-config-section`` parameter is replaced by the
|
||||
``-global migration.send-configuration={on|off}`` option.
|
||||
|
||||
``-no-kvm`` (since 1.3.0)
|
||||
'''''''''''''''''''''''''
|
||||
|
||||
The ``-no-kvm`` argument is now a synonym for setting ``-accel tcg``.
|
||||
|
||||
``-usbdevice`` (since 2.10.0)
|
||||
'''''''''''''''''''''''''''''
|
||||
|
||||
The ``-usbdevice DEV`` argument is now a synonym for setting
|
||||
the ``-device usb-DEV`` argument instead. The deprecated syntax
|
||||
would automatically enable USB support on the machine type.
|
||||
If using the new syntax, USB support must be explicitly
|
||||
enabled via the ``-machine usb=on`` argument.
|
||||
|
||||
``-drive file=json:{...{'driver':'file'}}`` (since 3.0)
|
||||
'''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The 'file' driver for drives is no longer appropriate for character or host
|
||||
devices and will only accept regular files (S_IFREG). The correct driver
|
||||
for these file types is 'host_cdrom' or 'host_device' as appropriate.
|
||||
|
||||
``-net ...,name=``\ *name* (since 3.1)
|
||||
''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The ``name`` parameter of the ``-net`` option is a synonym
|
||||
for the ``id`` parameter, which should now be used instead.
|
||||
|
||||
``-smp`` (invalid topologies) (since 3.1)
|
||||
'''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
CPU topology properties should describe whole machine topology including
|
||||
possible CPUs.
|
||||
|
||||
However, historically it was possible to start QEMU with an incorrect topology
|
||||
where *n* <= *sockets* * *cores* * *threads* < *maxcpus*,
|
||||
which could lead to an incorrect topology enumeration by the guest.
|
||||
Support for invalid topologies will be removed, the user must ensure
|
||||
topologies described with -smp include all possible cpus, i.e.
|
||||
*sockets* * *cores* * *threads* = *maxcpus*.
|
||||
|
||||
``-vnc acl`` (since 4.0.0)
|
||||
''''''''''''''''''''''''''
|
||||
|
||||
The ``acl`` option to the ``-vnc`` argument has been replaced
|
||||
by the ``tls-authz`` and ``sasl-authz`` options.
|
||||
|
||||
``QEMU_AUDIO_`` environment variables and ``-audio-help`` (since 4.0)
|
||||
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The ``-audiodev`` argument is now the preferred way to specify audio
|
||||
backend settings instead of environment variables. To ease migration to
|
||||
the new format, the ``-audiodev-help`` option can be used to convert
|
||||
the current values of the environment variables to ``-audiodev`` options.
|
||||
|
||||
Creating sound card devices and vnc without ``audiodev=`` property (since 4.2)
|
||||
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
When not using the deprecated legacy audio config, each sound card
|
||||
should specify an ``audiodev=`` property. Additionally, when using
|
||||
vnc, you should specify an ``audiodev=`` propery if you plan to
|
||||
transmit audio through the VNC protocol.
|
||||
|
||||
``-mon ...,control=readline,pretty=on|off`` (since 4.1)
|
||||
'''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The ``pretty=on|off`` switch has no effect for HMP monitors, but is
|
||||
silently ignored. Using the switch with HMP monitors will become an
|
||||
error in the future.
|
||||
|
||||
``-realtime`` (since 4.1)
|
||||
'''''''''''''''''''''''''
|
||||
|
||||
The ``-realtime mlock=on|off`` argument has been replaced by the
|
||||
``-overcommit mem-lock=on|off`` argument.
|
||||
|
||||
``-numa node,mem=``\ *size* (since 4.1)
|
||||
'''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The parameter ``mem`` of ``-numa node`` is used to assign a part of
|
||||
guest RAM to a NUMA node. But when using it, it's impossible to manage specified
|
||||
RAM chunk on the host side (like bind it to a host node, setting bind policy, ...),
|
||||
so guest end-ups with the fake NUMA configuration with suboptiomal performance.
|
||||
However since 2014 there is an alternative way to assign RAM to a NUMA node
|
||||
using parameter ``memdev``, which does the same as ``mem`` and adds
|
||||
means to actualy manage node RAM on the host side. Use parameter ``memdev``
|
||||
with *memory-backend-ram* backend as an replacement for parameter ``mem``
|
||||
to achieve the same fake NUMA effect or a properly configured
|
||||
*memory-backend-file* backend to actually benefit from NUMA configuration.
|
||||
In future new machine versions will not accept the option but it will still
|
||||
work with old machine types. User can check QAPI schema to see if the legacy
|
||||
option is supported by looking at MachineInfo::numa-mem-supported property.
|
||||
|
||||
``-numa`` node (without memory specified) (since 4.1)
|
||||
'''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
Splitting RAM by default between NUMA nodes has the same issues as ``mem``
|
||||
parameter described above with the difference that the role of the user plays
|
||||
QEMU using implicit generic or board specific splitting rule.
|
||||
Use ``memdev`` with *memory-backend-ram* backend or ``mem`` (if
|
||||
it's supported by used machine type) to define mapping explictly instead.
|
||||
|
||||
``-mem-path`` fallback to RAM (since 4.1)
|
||||
'''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
Currently if guest RAM allocation from file pointed by ``mem-path``
|
||||
fails, QEMU falls back to allocating from RAM, which might result
|
||||
in unpredictable behavior since the backing file specified by the user
|
||||
is ignored. In the future, users will be responsible for making sure
|
||||
the backing storage specified with ``-mem-path`` can actually provide
|
||||
the guest RAM configured with ``-m`` and QEMU will fail to start up if
|
||||
RAM allocation is unsuccessful.
|
||||
|
||||
RISC-V ``-bios`` (since 4.1)
|
||||
''''''''''''''''''''''''''''
|
||||
|
||||
QEMU 4.1 introduced support for the -bios option in QEMU for RISC-V for the
|
||||
RISC-V virt machine and sifive_u machine.
|
||||
|
||||
QEMU 4.1 has no changes to the default behaviour to avoid breakages. This
|
||||
default will change in a future QEMU release, so please prepare now. All users
|
||||
of the virt or sifive_u machine must change their command line usage.
|
||||
|
||||
QEMU 4.1 has three options, please migrate to one of these three:
|
||||
1. ``-bios none`` - This is the current default behavior if no -bios option
|
||||
is included. QEMU will not automatically load any firmware. It is up
|
||||
to the user to load all the images they need.
|
||||
2. ``-bios default`` - In a future QEMU release this will become the default
|
||||
behaviour if no -bios option is specified. This option will load the
|
||||
default OpenSBI firmware automatically. The firmware is included with
|
||||
the QEMU release and no user interaction is required. All a user needs
|
||||
to do is specify the kernel they want to boot with the -kernel option
|
||||
3. ``-bios <file>`` - Tells QEMU to load the specified file as the firmwrae.
|
||||
|
||||
``-tb-size`` option (since 5.0)
|
||||
'''''''''''''''''''''''''''''''
|
||||
|
||||
QEMU 5.0 introduced an alternative syntax to specify the size of the translation
|
||||
block cache, ``-accel tcg,tb-size=``. The new syntax deprecates the
|
||||
previously available ``-tb-size`` option.
|
||||
|
||||
``-show-cursor`` option (since 5.0)
|
||||
'''''''''''''''''''''''''''''''''''
|
||||
|
||||
Use ``-display sdl,show-cursor=on`` or
|
||||
``-display gtk,show-cursor=on`` instead.
|
||||
|
||||
QEMU Machine Protocol (QMP) commands
|
||||
------------------------------------
|
||||
|
||||
``change`` (since 2.5.0)
|
||||
''''''''''''''''''''''''
|
||||
|
||||
Use ``blockdev-change-medium`` or ``change-vnc-password`` instead.
|
||||
|
||||
``migrate_set_downtime`` and ``migrate_set_speed`` (since 2.8.0)
|
||||
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
Use ``migrate-set-parameters`` instead.
|
||||
|
||||
``migrate-set-cache-size`` and ``query-migrate-cache-size`` (since 2.11.0)
|
||||
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
Use ``migrate-set-parameters`` and ``query-migrate-parameters`` instead.
|
||||
|
||||
``query-block`` result field ``dirty-bitmaps[i].status`` (since 4.0)
|
||||
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The ``status`` field of the ``BlockDirtyInfo`` structure, returned by
|
||||
the query-block command is deprecated. Two new boolean fields,
|
||||
``recording`` and ``busy`` effectively replace it.
|
||||
|
||||
``query-block`` result field ``dirty-bitmaps`` (Since 4.2)
|
||||
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The ``dirty-bitmaps`` field of the ``BlockInfo`` structure, returned by
|
||||
the query-block command is itself now deprecated. The ``dirty-bitmaps``
|
||||
field of the ``BlockDeviceInfo`` struct should be used instead, which is the
|
||||
type of the ``inserted`` field in query-block replies, as well as the
|
||||
type of array items in query-named-block-nodes.
|
||||
|
||||
Since the ``dirty-bitmaps`` field is optionally present in both the old and
|
||||
new locations, clients must use introspection to learn where to anticipate
|
||||
the field if/when it does appear in command output.
|
||||
|
||||
``query-cpus`` (since 2.12.0)
|
||||
'''''''''''''''''''''''''''''
|
||||
|
||||
The ``query-cpus`` command is replaced by the ``query-cpus-fast`` command.
|
||||
|
||||
``query-cpus-fast`` ``arch`` output member (since 3.0.0)
|
||||
''''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The ``arch`` output member of the ``query-cpus-fast`` command is
|
||||
replaced by the ``target`` output member.
|
||||
|
||||
``cpu-add`` (since 4.0)
|
||||
'''''''''''''''''''''''
|
||||
|
||||
Use ``device_add`` for hotplugging vCPUs instead of ``cpu-add``. See
|
||||
documentation of ``query-hotpluggable-cpus`` for additional
|
||||
details.
|
||||
|
||||
``query-events`` (since 4.0)
|
||||
''''''''''''''''''''''''''''
|
||||
|
||||
The ``query-events`` command has been superseded by the more powerful
|
||||
and accurate ``query-qmp-schema`` command.
|
||||
|
||||
chardev client socket with ``wait`` option (since 4.0)
|
||||
''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
Character devices creating sockets in client mode should not specify
|
||||
the 'wait' field, which is only applicable to sockets in server mode
|
||||
|
||||
Human Monitor Protocol (HMP) commands
|
||||
-------------------------------------
|
||||
|
||||
The ``hub_id`` parameter of ``hostfwd_add`` / ``hostfwd_remove`` (since 3.1)
|
||||
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The ``[hub_id name]`` parameter tuple of the 'hostfwd_add' and
|
||||
'hostfwd_remove' HMP commands has been replaced by ``netdev_id``.
|
||||
|
||||
``cpu-add`` (since 4.0)
|
||||
'''''''''''''''''''''''
|
||||
|
||||
Use ``device_add`` for hotplugging vCPUs instead of ``cpu-add``. See
|
||||
documentation of ``query-hotpluggable-cpus`` for additional details.
|
||||
|
||||
``acl_show``, ``acl_reset``, ``acl_policy``, ``acl_add``, ``acl_remove`` (since 4.0.0)
|
||||
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The ``acl_show``, ``acl_reset``, ``acl_policy``, ``acl_add``, and
|
||||
``acl_remove`` commands are deprecated with no replacement. Authorization
|
||||
for VNC should be performed using the pluggable QAuthZ objects.
|
||||
|
||||
Guest Emulator ISAs
|
||||
-------------------
|
||||
|
||||
RISC-V ISA privledge specification version 1.09.1 (since 4.1)
|
||||
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The RISC-V ISA privledge specification version 1.09.1 has been deprecated.
|
||||
QEMU supports both the newer version 1.10.0 and the ratified version 1.11.0, these
|
||||
should be used instead of the 1.09.1 version.
|
||||
|
||||
System emulator CPUS
|
||||
--------------------
|
||||
|
||||
RISC-V ISA CPUs (since 4.1)
|
||||
'''''''''''''''''''''''''''
|
||||
|
||||
The RISC-V cpus with the ISA version in the CPU name have been depcreated. The
|
||||
four CPUs are: ``rv32gcsu-v1.9.1``, ``rv32gcsu-v1.10.0``, ``rv64gcsu-v1.9.1`` and
|
||||
``rv64gcsu-v1.10.0``. Instead the version can be specified via the CPU ``priv_spec``
|
||||
option when using the ``rv32`` or ``rv64`` CPUs.
|
||||
|
||||
RISC-V ISA CPUs (since 4.1)
|
||||
'''''''''''''''''''''''''''
|
||||
|
||||
The RISC-V no MMU cpus have been depcreated. The two CPUs: ``rv32imacu-nommu`` and
|
||||
``rv64imacu-nommu`` should no longer be used. Instead the MMU status can be specified
|
||||
via the CPU ``mmu`` option when using the ``rv32`` or ``rv64`` CPUs.
|
||||
|
||||
System emulator devices
|
||||
-----------------------
|
||||
|
||||
``ide-drive`` (since 4.2)
|
||||
'''''''''''''''''''''''''
|
||||
|
||||
The 'ide-drive' device is deprecated. Users should use 'ide-hd' or
|
||||
'ide-cd' as appropriate to get an IDE hard disk or CD-ROM as needed.
|
||||
|
||||
``scsi-disk`` (since 4.2)
|
||||
'''''''''''''''''''''''''
|
||||
|
||||
The 'scsi-disk' device is deprecated. Users should use 'scsi-hd' or
|
||||
'scsi-cd' as appropriate to get a SCSI hard disk or CD-ROM as needed.
|
||||
|
||||
System emulator machines
|
||||
------------------------
|
||||
|
||||
mips ``r4k`` platform (since 5.0)
|
||||
'''''''''''''''''''''''''''''''''
|
||||
|
||||
This machine type is very old and unmaintained. Users should use the ``malta``
|
||||
machine type instead.
|
||||
|
||||
``pc-1.0``, ``pc-1.1``, ``pc-1.2`` and ``pc-1.3`` (since 5.0)
|
||||
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
These machine types are very old and likely can not be used for live migration
|
||||
from old QEMU versions anymore. A newer machine type should be used instead.
|
||||
|
||||
``spike_v1.9.1`` and ``spike_v1.10`` (since 4.1)
|
||||
''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The version specific Spike machines have been deprecated in favour of the
|
||||
generic ``spike`` machine. If you need to specify an older version of the RISC-V
|
||||
spec you can use the ``-cpu rv64gcsu,priv_spec=v1.9.1`` command line argument.
|
||||
|
||||
Device options
|
||||
--------------
|
||||
|
||||
Emulated device options
|
||||
'''''''''''''''''''''''
|
||||
|
||||
``-device virtio-blk,scsi=on|off`` (since 5.0.0)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0
|
||||
and later do not support it because the virtio-scsi device was introduced for
|
||||
full SCSI support. Use virtio-scsi instead when SCSI passthrough is required.
|
||||
|
||||
Note this also applies to ``-device virtio-blk-pci,scsi=on|off``, which is an
|
||||
alias.
|
||||
|
||||
Block device options
|
||||
''''''''''''''''''''
|
||||
|
||||
``"backing": ""`` (since 2.12.0)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
In order to prevent QEMU from automatically opening an image's backing
|
||||
chain, use ``"backing": null`` instead.
|
||||
|
||||
``rbd`` keyvalue pair encoded filenames: ``""`` (since 3.1.0)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Options for ``rbd`` should be specified according to its runtime options,
|
||||
like other block drivers. Legacy parsing of keyvalue pair encoded
|
||||
filenames is useful to open images with the old format for backing files;
|
||||
These image files should be updated to use the current format.
|
||||
|
||||
Example of legacy encoding::
|
||||
|
||||
json:{"file.driver":"rbd", "file.filename":"rbd:rbd/name"}
|
||||
|
||||
The above, converted to the current supported format::
|
||||
|
||||
json:{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"}
|
||||
|
||||
Related binaries
|
||||
----------------
|
||||
|
||||
``qemu-img convert -n -o`` (since 4.2.0)
|
||||
''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
All options specified in ``-o`` are image creation options, so
|
||||
they have no effect when used with ``-n`` to skip image creation.
|
||||
Silently ignored options can be confusing, so this combination of
|
||||
options will be made an error in future versions.
|
||||
|
||||
Backwards compatibility
|
||||
-----------------------
|
||||
|
||||
Runnability guarantee of CPU models (since 4.1.0)
|
||||
'''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
Previous versions of QEMU never changed existing CPU models in
|
||||
ways that introduced additional host software or hardware
|
||||
requirements to the VM. This allowed management software to
|
||||
safely change the machine type of an existing VM without
|
||||
introducing new requirements ("runnability guarantee"). This
|
||||
prevented CPU models from being updated to include CPU
|
||||
vulnerability mitigations, leaving guests vulnerable in the
|
||||
default configuration.
|
||||
|
||||
The CPU model runnability guarantee won't apply anymore to
|
||||
existing CPU models. Management software that needs runnability
|
||||
guarantees must resolve the CPU model aliases using te
|
||||
``alias-of`` field returned by the ``query-cpu-definitions`` QMP
|
||||
command.
|
||||
|
||||
While those guarantees are kept, the return value of
|
||||
``query-cpu-definitions`` will have existing CPU model aliases
|
||||
point to a version that doesn't break runnability guarantees
|
||||
(specifically, version 1 of those CPU models). In future QEMU
|
||||
versions, aliases will point to newer CPU model versions
|
||||
depending on the machine type, so management software must
|
||||
resolve CPU model aliases before starting a virtual machine.
|
||||
|
||||
|
||||
Recently removed features
|
||||
=========================
|
||||
|
||||
What follows is a record of recently removed, formerly deprecated
|
||||
features that serves as a record for users who have encountered
|
||||
trouble after a recent upgrade.
|
||||
|
||||
QEMU Machine Protocol (QMP) commands
|
||||
------------------------------------
|
||||
|
||||
``block-dirty-bitmap-add`` "autoload" parameter (since 4.2.0)
|
||||
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The "autoload" parameter has been ignored since 2.12.0. All bitmaps
|
||||
are automatically loaded from qcow2 images.
|
||||
|
||||
Related binaries
|
||||
----------------
|
||||
|
||||
``qemu-nbd --partition`` (removed in 5.0.0)
|
||||
'''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
The ``qemu-nbd --partition $digit`` code (also spelled ``-P``)
|
||||
could only handle MBR partitions, and never correctly handled logical
|
||||
partitions beyond partition 5. Exporting a partition can still be
|
||||
done by utilizing the ``--image-opts`` option with a raw blockdev
|
||||
using the ``offset`` and ``size`` parameters layered on top of
|
||||
any other existing blockdev. For example, if partition 1 is 100MiB
|
||||
long starting at 1MiB, the old command::
|
||||
|
||||
qemu-nbd -t -P 1 -f qcow2 file.qcow2
|
||||
|
||||
can be rewritten as::
|
||||
|
||||
qemu-nbd -t --image-opts driver=raw,offset=1M,size=100M,file.driver=qcow2,file.file.driver=file,file.file.filename=file.qcow2
|
228
docs/system/device-url-syntax.rst.inc
Normal file
228
docs/system/device-url-syntax.rst.inc
Normal file
|
@ -0,0 +1,228 @@
|
|||
|
||||
In addition to using normal file images for the emulated storage
|
||||
devices, QEMU can also use networked resources such as iSCSI devices.
|
||||
These are specified using a special URL syntax.
|
||||
|
||||
``iSCSI``
|
||||
iSCSI support allows QEMU to access iSCSI resources directly and use
|
||||
as images for the guest storage. Both disk and cdrom images are
|
||||
supported.
|
||||
|
||||
Syntax for specifying iSCSI LUNs is
|
||||
"iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>"
|
||||
|
||||
By default qemu will use the iSCSI initiator-name
|
||||
'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from
|
||||
the command line or a configuration file.
|
||||
|
||||
Since version Qemu 2.4 it is possible to specify a iSCSI request
|
||||
timeout to detect stalled requests and force a reestablishment of the
|
||||
session. The timeout is specified in seconds. The default is 0 which
|
||||
means no timeout. Libiscsi 1.15.0 or greater is required for this
|
||||
feature.
|
||||
|
||||
Example (without authentication):
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
|
||||
-cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
|
||||
-drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
|
||||
|
||||
Example (CHAP username/password via URL):
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -drive file=iscsi://user%password@192.0.2.1/iqn.2001-04.com.example/1
|
||||
|
||||
Example (CHAP username/password via environment variables):
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
LIBISCSI_CHAP_USERNAME="user" \
|
||||
LIBISCSI_CHAP_PASSWORD="password" \
|
||||
|qemu_system| -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
|
||||
|
||||
``NBD``
|
||||
QEMU supports NBD (Network Block Devices) both using TCP protocol as
|
||||
well as Unix Domain Sockets. With TCP, the default port is 10809.
|
||||
|
||||
Syntax for specifying a NBD device using TCP, in preferred URI form:
|
||||
"nbd://<server-ip>[:<port>]/[<export>]"
|
||||
|
||||
Syntax for specifying a NBD device using Unix Domain Sockets;
|
||||
remember that '?' is a shell glob character and may need quoting:
|
||||
"nbd+unix:///[<export>]?socket=<domain-socket>"
|
||||
|
||||
Older syntax that is also recognized:
|
||||
"nbd:<server-ip>:<port>[:exportname=<export>]"
|
||||
|
||||
Syntax for specifying a NBD device using Unix Domain Sockets
|
||||
"nbd:unix:<domain-socket>[:exportname=<export>]"
|
||||
|
||||
Example for TCP
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| --drive file=nbd:192.0.2.1:30000
|
||||
|
||||
Example for Unix Domain Sockets
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| --drive file=nbd:unix:/tmp/nbd-socket
|
||||
|
||||
``SSH``
|
||||
QEMU supports SSH (Secure Shell) access to remote disks.
|
||||
|
||||
Examples:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -drive file=ssh://user@host/path/to/disk.img
|
||||
|qemu_system| -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
|
||||
|
||||
Currently authentication must be done using ssh-agent. Other
|
||||
authentication methods may be supported in future.
|
||||
|
||||
``Sheepdog``
|
||||
Sheepdog is a distributed storage system for QEMU. QEMU supports
|
||||
using either local sheepdog devices or remote networked devices.
|
||||
|
||||
Syntax for specifying a sheepdog device
|
||||
|
||||
::
|
||||
|
||||
sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
|
||||
|
||||
Example
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
|
||||
|
||||
See also https://sheepdog.github.io/sheepdog/.
|
||||
|
||||
``GlusterFS``
|
||||
GlusterFS is a user space distributed file system. QEMU supports the
|
||||
use of GlusterFS volumes for hosting VM disk images using TCP, Unix
|
||||
Domain Sockets and RDMA transport protocols.
|
||||
|
||||
Syntax for specifying a VM disk image on GlusterFS volume is
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
URI:
|
||||
gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
|
||||
|
||||
JSON:
|
||||
'json:{"driver":"qcow2","file":{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...",
|
||||
"server":[{"type":"tcp","host":"...","port":"..."},
|
||||
{"type":"unix","socket":"..."}]}}'
|
||||
|
||||
Example
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
URI:
|
||||
|qemu_system| --drive file=gluster://192.0.2.1/testvol/a.img,
|
||||
file.debug=9,file.logfile=/var/log/qemu-gluster.log
|
||||
|
||||
JSON:
|
||||
|qemu_system| 'json:{"driver":"qcow2",
|
||||
"file":{"driver":"gluster",
|
||||
"volume":"testvol","path":"a.img",
|
||||
"debug":9,"logfile":"/var/log/qemu-gluster.log",
|
||||
"server":[{"type":"tcp","host":"1.2.3.4","port":24007},
|
||||
{"type":"unix","socket":"/var/run/glusterd.socket"}]}}'
|
||||
|qemu_system| -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
|
||||
file.debug=9,file.logfile=/var/log/qemu-gluster.log,
|
||||
file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
|
||||
file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
|
||||
|
||||
See also http://www.gluster.org.
|
||||
|
||||
``HTTP/HTTPS/FTP/FTPS``
|
||||
QEMU supports read-only access to files accessed over http(s) and
|
||||
ftp(s).
|
||||
|
||||
Syntax using a single filename:
|
||||
|
||||
::
|
||||
|
||||
<protocol>://[<username>[:<password>]@]<host>/<path>
|
||||
|
||||
where:
|
||||
|
||||
``protocol``
|
||||
'http', 'https', 'ftp', or 'ftps'.
|
||||
|
||||
``username``
|
||||
Optional username for authentication to the remote server.
|
||||
|
||||
``password``
|
||||
Optional password for authentication to the remote server.
|
||||
|
||||
``host``
|
||||
Address of the remote server.
|
||||
|
||||
``path``
|
||||
Path on the remote server, including any query string.
|
||||
|
||||
The following options are also supported:
|
||||
|
||||
``url``
|
||||
The full URL when passing options to the driver explicitly.
|
||||
|
||||
``readahead``
|
||||
The amount of data to read ahead with each range request to the
|
||||
remote server. This value may optionally have the suffix 'T', 'G',
|
||||
'M', 'K', 'k' or 'b'. If it does not have a suffix, it will be
|
||||
assumed to be in bytes. The value must be a multiple of 512 bytes.
|
||||
It defaults to 256k.
|
||||
|
||||
``sslverify``
|
||||
Whether to verify the remote server's certificate when connecting
|
||||
over SSL. It can have the value 'on' or 'off'. It defaults to
|
||||
'on'.
|
||||
|
||||
``cookie``
|
||||
Send this cookie (it can also be a list of cookies separated by
|
||||
';') with each outgoing request. Only supported when using
|
||||
protocols such as HTTP which support cookies, otherwise ignored.
|
||||
|
||||
``timeout``
|
||||
Set the timeout in seconds of the CURL connection. This timeout is
|
||||
the time that CURL waits for a response from the remote server to
|
||||
get the size of the image to be downloaded. If not set, the
|
||||
default timeout of 5 seconds is used.
|
||||
|
||||
Note that when passing options to qemu explicitly, ``driver`` is the
|
||||
value of <protocol>.
|
||||
|
||||
Example: boot from a remote Fedora 20 live ISO image
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system_x86| --drive media=cdrom,file=https://archives.fedoraproject.org/pub/archive/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
|
||||
|
||||
|qemu_system_x86| --drive media=cdrom,file.driver=http,file.url=http://archives.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
|
||||
|
||||
Example: boot from a remote Fedora 20 cloud image using a local
|
||||
overlay for writes, copy-on-read, and a readahead of 64k
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
qemu-img create -f qcow2 -o backing_file='json:{"file.driver":"http",, "file.url":"http://archives.fedoraproject.org/pub/archive/fedora/linux/releases/20/Images/x86_64/Fedora-x86_64-20-20131211.1-sda.qcow2",, "file.readahead":"64k"}' /tmp/Fedora-x86_64-20-20131211.1-sda.qcow2
|
||||
|
||||
|qemu_system_x86| -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
|
||||
|
||||
Example: boot from an image stored on a VMware vSphere server with a
|
||||
self-signed certificate using a local overlay for writes, a readahead
|
||||
of 64k and a timeout of 10 seconds.
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
qemu-img create -f qcow2 -o backing_file='json:{"file.driver":"https",, "file.url":"https://user:password@vsphere.example.com/folder/test/test-flat.vmdk?dcPath=Datacenter&dsName=datastore1",, "file.sslverify":"off",, "file.readahead":"64k",, "file.timeout":10}' /tmp/test.qcow2
|
||||
|
||||
|qemu_system_x86| -drive file=/tmp/test.qcow2
|
81
docs/system/gdb.rst
Normal file
81
docs/system/gdb.rst
Normal file
|
@ -0,0 +1,81 @@
|
|||
.. _gdb_005fusage:
|
||||
|
||||
GDB usage
|
||||
---------
|
||||
|
||||
QEMU has a primitive support to work with gdb, so that you can do
|
||||
'Ctrl-C' while the virtual machine is running and inspect its state.
|
||||
|
||||
In order to use gdb, launch QEMU with the '-s' option. It will wait for
|
||||
a gdb connection:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -s -kernel bzImage -hda rootdisk.img -append "root=/dev/hda"
|
||||
Connected to host network interface: tun0
|
||||
Waiting gdb connection on port 1234
|
||||
|
||||
Then launch gdb on the 'vmlinux' executable::
|
||||
|
||||
> gdb vmlinux
|
||||
|
||||
In gdb, connect to QEMU::
|
||||
|
||||
(gdb) target remote localhost:1234
|
||||
|
||||
Then you can use gdb normally. For example, type 'c' to launch the
|
||||
kernel::
|
||||
|
||||
(gdb) c
|
||||
|
||||
Here are some useful tips in order to use gdb on system code:
|
||||
|
||||
1. Use ``info reg`` to display all the CPU registers.
|
||||
|
||||
2. Use ``x/10i $eip`` to display the code at the PC position.
|
||||
|
||||
3. Use ``set architecture i8086`` to dump 16 bit code. Then use
|
||||
``x/10i $cs*16+$eip`` to dump the code at the PC position.
|
||||
|
||||
Advanced debugging options:
|
||||
|
||||
The default single stepping behavior is step with the IRQs and timer
|
||||
service routines off. It is set this way because when gdb executes a
|
||||
single step it expects to advance beyond the current instruction. With
|
||||
the IRQs and timer service routines on, a single step might jump into
|
||||
the one of the interrupt or exception vectors instead of executing the
|
||||
current instruction. This means you may hit the same breakpoint a number
|
||||
of times before executing the instruction gdb wants to have executed.
|
||||
Because there are rare circumstances where you want to single step into
|
||||
an interrupt vector the behavior can be controlled from GDB. There are
|
||||
three commands you can query and set the single step behavior:
|
||||
|
||||
``maintenance packet qqemu.sstepbits``
|
||||
This will display the MASK bits used to control the single stepping
|
||||
IE:
|
||||
|
||||
::
|
||||
|
||||
(gdb) maintenance packet qqemu.sstepbits
|
||||
sending: "qqemu.sstepbits"
|
||||
received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
|
||||
|
||||
``maintenance packet qqemu.sstep``
|
||||
This will display the current value of the mask used when single
|
||||
stepping IE:
|
||||
|
||||
::
|
||||
|
||||
(gdb) maintenance packet qqemu.sstep
|
||||
sending: "qqemu.sstep"
|
||||
received: "0x7"
|
||||
|
||||
``maintenance packet Qqemu.sstep=HEX_VALUE``
|
||||
This will change the single step mask, so if wanted to enable IRQs on
|
||||
the single step, but not timers, you would use:
|
||||
|
||||
::
|
||||
|
||||
(gdb) maintenance packet Qqemu.sstep=0x5
|
||||
sending: "qemu.sstep=0x5"
|
||||
received: "OK"
|
85
docs/system/images.rst
Normal file
85
docs/system/images.rst
Normal file
|
@ -0,0 +1,85 @@
|
|||
.. _disk_005fimages:
|
||||
|
||||
Disk Images
|
||||
-----------
|
||||
|
||||
QEMU supports many disk image formats, including growable disk images
|
||||
(their size increase as non empty sectors are written), compressed and
|
||||
encrypted disk images.
|
||||
|
||||
.. _disk_005fimages_005fquickstart:
|
||||
|
||||
Quick start for disk image creation
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
You can create a disk image with the command::
|
||||
|
||||
qemu-img create myimage.img mysize
|
||||
|
||||
where myimage.img is the disk image filename and mysize is its size in
|
||||
kilobytes. You can add an ``M`` suffix to give the size in megabytes and
|
||||
a ``G`` suffix for gigabytes.
|
||||
|
||||
See the qemu-img invocation documentation for more information.
|
||||
|
||||
.. _disk_005fimages_005fsnapshot_005fmode:
|
||||
|
||||
Snapshot mode
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
If you use the option ``-snapshot``, all disk images are considered as
|
||||
read only. When sectors in written, they are written in a temporary file
|
||||
created in ``/tmp``. You can however force the write back to the raw
|
||||
disk images by using the ``commit`` monitor command (or C-a s in the
|
||||
serial console).
|
||||
|
||||
.. _vm_005fsnapshots:
|
||||
|
||||
VM snapshots
|
||||
~~~~~~~~~~~~
|
||||
|
||||
VM snapshots are snapshots of the complete virtual machine including CPU
|
||||
state, RAM, device state and the content of all the writable disks. In
|
||||
order to use VM snapshots, you must have at least one non removable and
|
||||
writable block device using the ``qcow2`` disk image format. Normally
|
||||
this device is the first virtual hard drive.
|
||||
|
||||
Use the monitor command ``savevm`` to create a new VM snapshot or
|
||||
replace an existing one. A human readable name can be assigned to each
|
||||
snapshot in addition to its numerical ID.
|
||||
|
||||
Use ``loadvm`` to restore a VM snapshot and ``delvm`` to remove a VM
|
||||
snapshot. ``info snapshots`` lists the available snapshots with their
|
||||
associated information::
|
||||
|
||||
(qemu) info snapshots
|
||||
Snapshot devices: hda
|
||||
Snapshot list (from hda):
|
||||
ID TAG VM SIZE DATE VM CLOCK
|
||||
1 start 41M 2006-08-06 12:38:02 00:00:14.954
|
||||
2 40M 2006-08-06 12:43:29 00:00:18.633
|
||||
3 msys 40M 2006-08-06 12:44:04 00:00:23.514
|
||||
|
||||
A VM snapshot is made of a VM state info (its size is shown in
|
||||
``info snapshots``) and a snapshot of every writable disk image. The VM
|
||||
state info is stored in the first ``qcow2`` non removable and writable
|
||||
block device. The disk image snapshots are stored in every disk image.
|
||||
The size of a snapshot in a disk image is difficult to evaluate and is
|
||||
not shown by ``info snapshots`` because the associated disk sectors are
|
||||
shared among all the snapshots to save disk space (otherwise each
|
||||
snapshot would need a full copy of all the disk images).
|
||||
|
||||
When using the (unrelated) ``-snapshot`` option
|
||||
(:ref:`disk_005fimages_005fsnapshot_005fmode`),
|
||||
you can always make VM snapshots, but they are deleted as soon as you
|
||||
exit QEMU.
|
||||
|
||||
VM snapshots currently have the following known limitations:
|
||||
|
||||
- They cannot cope with removable devices if they are removed or
|
||||
inserted after a snapshot is done.
|
||||
|
||||
- A few device drivers still have incomplete snapshot support so their
|
||||
state is not saved or restored properly (in particular USB).
|
||||
|
||||
.. include:: qemu-block-drivers.rst.inc
|
|
@ -12,7 +12,25 @@ or Hypervisor.Framework.
|
|||
Contents:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:maxdepth: 3
|
||||
|
||||
qemu-block-drivers
|
||||
quickstart
|
||||
invocation
|
||||
keys
|
||||
mux-chardev
|
||||
monitor
|
||||
images
|
||||
net
|
||||
usb
|
||||
ivshmem
|
||||
linuxboot
|
||||
vnc-security
|
||||
tls
|
||||
gdb
|
||||
managed-startup
|
||||
targets
|
||||
security
|
||||
vfio-ap
|
||||
deprecated
|
||||
build-platforms
|
||||
license
|
||||
|
|
18
docs/system/invocation.rst
Normal file
18
docs/system/invocation.rst
Normal file
|
@ -0,0 +1,18 @@
|
|||
.. _sec_005finvocation:
|
||||
|
||||
Invocation
|
||||
----------
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| [options] [disk_image]
|
||||
|
||||
disk_image is a raw hard disk image for IDE hard disk 0. Some targets do
|
||||
not need a disk image.
|
||||
|
||||
.. hxtool-doc:: qemu-options.hx
|
||||
|
||||
Device URL Syntax
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. include:: device-url-syntax.rst.inc
|
64
docs/system/ivshmem.rst
Normal file
64
docs/system/ivshmem.rst
Normal file
|
@ -0,0 +1,64 @@
|
|||
.. _pcsys_005fivshmem:
|
||||
|
||||
Inter-VM Shared Memory device
|
||||
-----------------------------
|
||||
|
||||
On Linux hosts, a shared memory device is available. The basic syntax
|
||||
is:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system_x86| -device ivshmem-plain,memdev=hostmem
|
||||
|
||||
where hostmem names a host memory backend. For a POSIX shared memory
|
||||
backend, use something like
|
||||
|
||||
::
|
||||
|
||||
-object memory-backend-file,size=1M,share,mem-path=/dev/shm/ivshmem,id=hostmem
|
||||
|
||||
If desired, interrupts can be sent between guest VMs accessing the same
|
||||
shared memory region. Interrupt support requires using a shared memory
|
||||
server and using a chardev socket to connect to it. The code for the
|
||||
shared memory server is qemu.git/contrib/ivshmem-server. An example
|
||||
syntax when using the shared memory server is:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
# First start the ivshmem server once and for all
|
||||
ivshmem-server -p pidfile -S path -m shm-name -l shm-size -n vectors
|
||||
|
||||
# Then start your qemu instances with matching arguments
|
||||
|qemu_system_x86| -device ivshmem-doorbell,vectors=vectors,chardev=id
|
||||
-chardev socket,path=path,id=id
|
||||
|
||||
When using the server, the guest will be assigned a VM ID (>=0) that
|
||||
allows guests using the same server to communicate via interrupts.
|
||||
Guests can read their VM ID from a device register (see
|
||||
ivshmem-spec.txt).
|
||||
|
||||
Migration with ivshmem
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
With device property ``master=on``, the guest will copy the shared
|
||||
memory on migration to the destination host. With ``master=off``, the
|
||||
guest will not be able to migrate with the device attached. In the
|
||||
latter case, the device should be detached and then reattached after
|
||||
migration using the PCI hotplug support.
|
||||
|
||||
At most one of the devices sharing the same memory can be master. The
|
||||
master must complete migration before you plug back the other devices.
|
||||
|
||||
ivshmem and hugepages
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Instead of specifying the <shm size> using POSIX shm, you may specify a
|
||||
memory backend that has hugepage support:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system_x86| -object memory-backend-file,size=1G,mem-path=/dev/hugepages/my-shmem-file,share,id=mb1
|
||||
-device ivshmem-plain,memdev=mb1
|
||||
|
||||
ivshmem-server also supports hugepages mount points with the ``-m``
|
||||
memory path argument.
|
6
docs/system/keys.rst
Normal file
6
docs/system/keys.rst
Normal file
|
@ -0,0 +1,6 @@
|
|||
.. _pcsys_005fkeys:
|
||||
|
||||
Keys in the graphical frontends
|
||||
-------------------------------
|
||||
|
||||
.. include:: keys.rst.inc
|
35
docs/system/keys.rst.inc
Normal file
35
docs/system/keys.rst.inc
Normal file
|
@ -0,0 +1,35 @@
|
|||
During the graphical emulation, you can use special key combinations to
|
||||
change modes. The default key mappings are shown below, but if you use
|
||||
``-alt-grab`` then the modifier is Ctrl-Alt-Shift (instead of Ctrl-Alt)
|
||||
and if you use ``-ctrl-grab`` then the modifier is the right Ctrl key
|
||||
(instead of Ctrl-Alt):
|
||||
|
||||
Ctrl-Alt-f
|
||||
Toggle full screen
|
||||
|
||||
Ctrl-Alt-+
|
||||
Enlarge the screen
|
||||
|
||||
Ctrl-Alt\--
|
||||
Shrink the screen
|
||||
|
||||
Ctrl-Alt-u
|
||||
Restore the screen's un-scaled dimensions
|
||||
|
||||
Ctrl-Alt-n
|
||||
Switch to virtual console 'n'. Standard console mappings are:
|
||||
|
||||
*1*
|
||||
Target system display
|
||||
|
||||
*2*
|
||||
Monitor
|
||||
|
||||
*3*
|
||||
Serial port
|
||||
|
||||
Ctrl-Alt
|
||||
Toggle mouse and keyboard grab.
|
||||
|
||||
In the virtual consoles, you can use Ctrl-Up, Ctrl-Down, Ctrl-PageUp and
|
||||
Ctrl-PageDown to move in the back log.
|
11
docs/system/license.rst
Normal file
11
docs/system/license.rst
Normal file
|
@ -0,0 +1,11 @@
|
|||
.. _License:
|
||||
|
||||
License
|
||||
=======
|
||||
|
||||
QEMU is a trademark of Fabrice Bellard.
|
||||
|
||||
QEMU is released under the `GNU General Public
|
||||
License <https://www.gnu.org/licenses/gpl-2.0.txt>`__, version 2. Parts
|
||||
of QEMU have specific licenses, see file
|
||||
`LICENSE <https://git.qemu.org/?p=qemu.git;a=blob_plain;f=LICENSE>`__.
|
30
docs/system/linuxboot.rst
Normal file
30
docs/system/linuxboot.rst
Normal file
|
@ -0,0 +1,30 @@
|
|||
.. _direct_005flinux_005fboot:
|
||||
|
||||
Direct Linux Boot
|
||||
-----------------
|
||||
|
||||
This section explains how to launch a Linux kernel inside QEMU without
|
||||
having to make a full bootable image. It is very useful for fast Linux
|
||||
kernel testing.
|
||||
|
||||
The syntax is:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -kernel bzImage -hda rootdisk.img -append "root=/dev/hda"
|
||||
|
||||
Use ``-kernel`` to provide the Linux kernel image and ``-append`` to
|
||||
give the kernel command line arguments. The ``-initrd`` option can be
|
||||
used to provide an INITRD image.
|
||||
|
||||
If you do not need graphical output, you can disable it and redirect the
|
||||
virtual serial port and the QEMU monitor to the console with the
|
||||
``-nographic`` option. The typical command line is:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -kernel bzImage -hda rootdisk.img \
|
||||
-append "root=/dev/hda console=ttyS0" -nographic
|
||||
|
||||
Use Ctrl-a c to switch between the serial console and the monitor (see
|
||||
:ref:`pcsys_005fkeys`).
|
35
docs/system/managed-startup.rst
Normal file
35
docs/system/managed-startup.rst
Normal file
|
@ -0,0 +1,35 @@
|
|||
Managed start up options
|
||||
========================
|
||||
|
||||
In system mode emulation, it's possible to create a VM in a paused
|
||||
state using the ``-S`` command line option. In this state the machine
|
||||
is completely initialized according to command line options and ready
|
||||
to execute VM code but VCPU threads are not executing any code. The VM
|
||||
state in this paused state depends on the way QEMU was started. It
|
||||
could be in:
|
||||
|
||||
- initial state (after reset/power on state)
|
||||
- with direct kernel loading, the initial state could be amended to execute
|
||||
code loaded by QEMU in the VM's RAM and with incoming migration
|
||||
- with incoming migration, initial state will be amended with the migrated
|
||||
machine state after migration completes
|
||||
|
||||
This paused state is typically used by users to query machine state and/or
|
||||
additionally configure the machine (by hotplugging devices) in runtime before
|
||||
allowing VM code to run.
|
||||
|
||||
However, at the ``-S`` pause point, it's impossible to configure options
|
||||
that affect initial VM creation (like: ``-smp``/``-m``/``-numa`` ...) or
|
||||
cold plug devices. The experimental ``--preconfig`` command line option
|
||||
allows pausing QEMU before the initial VM creation, in a "preconfig" state,
|
||||
where additional queries and configuration can be performed via QMP
|
||||
before moving on to the resulting configuration startup. In the
|
||||
preconfig state, QEMU only allows a limited set of commands over the
|
||||
QMP monitor, where the commands do not depend on an initialized
|
||||
machine, including but not limited to:
|
||||
|
||||
- ``qmp_capabilities``
|
||||
- ``query-qmp-schema``
|
||||
- ``query-commands``
|
||||
- ``query-status``
|
||||
- ``x-exit-preconfig``
|
31
docs/system/monitor.rst
Normal file
31
docs/system/monitor.rst
Normal file
|
@ -0,0 +1,31 @@
|
|||
.. _pcsys_005fmonitor:
|
||||
|
||||
QEMU Monitor
|
||||
------------
|
||||
|
||||
The QEMU monitor is used to give complex commands to the QEMU emulator.
|
||||
You can use it to:
|
||||
|
||||
- Remove or insert removable media images (such as CD-ROM or
|
||||
floppies).
|
||||
|
||||
- Freeze/unfreeze the Virtual Machine (VM) and save or restore its
|
||||
state from a disk file.
|
||||
|
||||
- Inspect the VM state without an external debugger.
|
||||
|
||||
Commands
|
||||
~~~~~~~~
|
||||
|
||||
The following commands are available:
|
||||
|
||||
.. hxtool-doc:: hmp-commands.hx
|
||||
|
||||
.. hxtool-doc:: hmp-commands-info.hx
|
||||
|
||||
Integer expressions
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The monitor understands integers expressions for every integer argument.
|
||||
You can use register names to get the value of specifics CPU registers
|
||||
by prefixing them with *$*.
|
6
docs/system/mux-chardev.rst
Normal file
6
docs/system/mux-chardev.rst
Normal file
|
@ -0,0 +1,6 @@
|
|||
.. _mux_005fkeys:
|
||||
|
||||
Keys in the character backend multiplexer
|
||||
-----------------------------------------
|
||||
|
||||
.. include:: mux-chardev.rst.inc
|
27
docs/system/mux-chardev.rst.inc
Normal file
27
docs/system/mux-chardev.rst.inc
Normal file
|
@ -0,0 +1,27 @@
|
|||
During emulation, if you are using a character backend multiplexer
|
||||
(which is the default if you are using ``-nographic``) then several
|
||||
commands are available via an escape sequence. These key sequences all
|
||||
start with an escape character, which is Ctrl-a by default, but can be
|
||||
changed with ``-echr``. The list below assumes you're using the default.
|
||||
|
||||
Ctrl-a h
|
||||
Print this help
|
||||
|
||||
Ctrl-a x
|
||||
Exit emulator
|
||||
|
||||
Ctrl-a s
|
||||
Save disk data back to file (if -snapshot)
|
||||
|
||||
Ctrl-a t
|
||||
Toggle console timestamps
|
||||
|
||||
Ctrl-a b
|
||||
Send break (magic sysrq in Linux)
|
||||
|
||||
Ctrl-a c
|
||||
Rotate between the frontends connected to the multiplexer (usually
|
||||
this switches between the monitor and the console)
|
||||
|
||||
Ctrl-a Ctrl-a
|
||||
Send the escape character to the frontend
|
100
docs/system/net.rst
Normal file
100
docs/system/net.rst
Normal file
|
@ -0,0 +1,100 @@
|
|||
.. _pcsys_005fnetwork:
|
||||
|
||||
Network emulation
|
||||
-----------------
|
||||
|
||||
QEMU can simulate several network cards (e.g. PCI or ISA cards on the PC
|
||||
target) and can connect them to a network backend on the host or an
|
||||
emulated hub. The various host network backends can either be used to
|
||||
connect the NIC of the guest to a real network (e.g. by using a TAP
|
||||
devices or the non-privileged user mode network stack), or to other
|
||||
guest instances running in another QEMU process (e.g. by using the
|
||||
socket host network backend).
|
||||
|
||||
Using TAP network interfaces
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This is the standard way to connect QEMU to a real network. QEMU adds a
|
||||
virtual network device on your host (called ``tapN``), and you can then
|
||||
configure it as if it was a real ethernet card.
|
||||
|
||||
Linux host
|
||||
^^^^^^^^^^
|
||||
|
||||
As an example, you can download the ``linux-test-xxx.tar.gz`` archive
|
||||
and copy the script ``qemu-ifup`` in ``/etc`` and configure properly
|
||||
``sudo`` so that the command ``ifconfig`` contained in ``qemu-ifup`` can
|
||||
be executed as root. You must verify that your host kernel supports the
|
||||
TAP network interfaces: the device ``/dev/net/tun`` must be present.
|
||||
|
||||
See :ref:`sec_005finvocation` to have examples of command
|
||||
lines using the TAP network interfaces.
|
||||
|
||||
Windows host
|
||||
^^^^^^^^^^^^
|
||||
|
||||
There is a virtual ethernet driver for Windows 2000/XP systems, called
|
||||
TAP-Win32. But it is not included in standard QEMU for Windows, so you
|
||||
will need to get it separately. It is part of OpenVPN package, so
|
||||
download OpenVPN from : https://openvpn.net/.
|
||||
|
||||
Using the user mode network stack
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
By using the option ``-net user`` (default configuration if no ``-net``
|
||||
option is specified), QEMU uses a completely user mode network stack
|
||||
(you don't need root privilege to use the virtual network). The virtual
|
||||
network configuration is the following::
|
||||
|
||||
guest (10.0.2.15) <------> Firewall/DHCP server <-----> Internet
|
||||
| (10.0.2.2)
|
||||
|
|
||||
----> DNS server (10.0.2.3)
|
||||
|
|
||||
----> SMB server (10.0.2.4)
|
||||
|
||||
The QEMU VM behaves as if it was behind a firewall which blocks all
|
||||
incoming connections. You can use a DHCP client to automatically
|
||||
configure the network in the QEMU VM. The DHCP server assign addresses
|
||||
to the hosts starting from 10.0.2.15.
|
||||
|
||||
In order to check that the user mode network is working, you can ping
|
||||
the address 10.0.2.2 and verify that you got an address in the range
|
||||
10.0.2.x from the QEMU virtual DHCP server.
|
||||
|
||||
Note that ICMP traffic in general does not work with user mode
|
||||
networking. ``ping``, aka. ICMP echo, to the local router (10.0.2.2)
|
||||
shall work, however. If you're using QEMU on Linux >= 3.0, it can use
|
||||
unprivileged ICMP ping sockets to allow ``ping`` to the Internet. The
|
||||
host admin has to set the ping_group_range in order to grant access to
|
||||
those sockets. To allow ping for GID 100 (usually users group)::
|
||||
|
||||
echo 100 100 > /proc/sys/net/ipv4/ping_group_range
|
||||
|
||||
When using the built-in TFTP server, the router is also the TFTP server.
|
||||
|
||||
When using the ``'-netdev user,hostfwd=...'`` option, TCP or UDP
|
||||
connections can be redirected from the host to the guest. It allows for
|
||||
example to redirect X11, telnet or SSH connections.
|
||||
|
||||
Hubs
|
||||
~~~~
|
||||
|
||||
QEMU can simulate several hubs. A hub can be thought of as a virtual
|
||||
connection between several network devices. These devices can be for
|
||||
example QEMU virtual ethernet cards or virtual Host ethernet devices
|
||||
(TAP devices). You can connect guest NICs or host network backends to
|
||||
such a hub using the ``-netdev
|
||||
hubport`` or ``-nic hubport`` options. The legacy ``-net`` option also
|
||||
connects the given device to the emulated hub with ID 0 (i.e. the
|
||||
default hub) unless you specify a netdev with ``-net nic,netdev=xxx``
|
||||
here.
|
||||
|
||||
Connecting emulated networks between QEMU instances
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Using the ``-netdev socket`` (or ``-nic socket`` or ``-net socket``)
|
||||
option, it is possible to create emulated networks that span several
|
||||
QEMU instances. See the description of the ``-netdev socket`` option in
|
||||
:ref:`sec_005finvocation` to have a basic
|
||||
example.
|
|
@ -1,985 +1,20 @@
|
|||
:orphan:
|
||||
|
||||
QEMU block drivers reference
|
||||
============================
|
||||
|
||||
.. |qemu_system| replace:: qemu-system-x86_64
|
||||
Synopsis
|
||||
--------
|
||||
|
||||
..
|
||||
We put the 'Synopsis' and 'See also' sections into the manpage, but not
|
||||
the HTML. This makes the HTML docs read better and means the ToC in
|
||||
the index has a more useful set of entries. Ideally, the section
|
||||
headings 'Disk image file formats' would be top-level headings for
|
||||
the HTML, but sub-headings of the conventional manpage 'Description'
|
||||
header for the manpage. Unfortunately, due to deficiencies in
|
||||
the Sphinx 'only' directive, this isn't possible: they must be headers
|
||||
at the same level as 'Synopsis' and 'See also', otherwise Sphinx's
|
||||
identification of which header underline style is which gets confused.
|
||||
QEMU block driver reference manual
|
||||
|
||||
.. only:: man
|
||||
Description
|
||||
-----------
|
||||
|
||||
Synopsis
|
||||
--------
|
||||
.. include:: qemu-block-drivers.rst.inc
|
||||
|
||||
QEMU block driver reference manual
|
||||
See also
|
||||
--------
|
||||
|
||||
Disk image file formats
|
||||
-----------------------
|
||||
|
||||
QEMU supports many image file formats that can be used with VMs as well as with
|
||||
any of the tools (like ``qemu-img``). This includes the preferred formats
|
||||
raw and qcow2 as well as formats that are supported for compatibility with
|
||||
older QEMU versions or other hypervisors.
|
||||
|
||||
Depending on the image format, different options can be passed to
|
||||
``qemu-img create`` and ``qemu-img convert`` using the ``-o`` option.
|
||||
This section describes each format and the options that are supported for it.
|
||||
|
||||
.. program:: image-formats
|
||||
.. option:: raw
|
||||
|
||||
Raw disk image format. This format has the advantage of
|
||||
being simple and easily exportable to all other emulators. If your
|
||||
file system supports *holes* (for example in ext2 or ext3 on
|
||||
Linux or NTFS on Windows), then only the written sectors will reserve
|
||||
space. Use ``qemu-img info`` to know the real size used by the
|
||||
image or ``ls -ls`` on Unix/Linux.
|
||||
|
||||
Supported options:
|
||||
|
||||
.. program:: raw
|
||||
.. option:: preallocation
|
||||
|
||||
Preallocation mode (allowed values: ``off``, ``falloc``,
|
||||
``full``). ``falloc`` mode preallocates space for image by
|
||||
calling ``posix_fallocate()``. ``full`` mode preallocates space
|
||||
for image by writing data to underlying storage. This data may or
|
||||
may not be zero, depending on the storage location.
|
||||
|
||||
.. program:: image-formats
|
||||
.. option:: qcow2
|
||||
|
||||
QEMU image format, the most versatile format. Use it to have smaller
|
||||
images (useful if your filesystem does not supports holes, for example
|
||||
on Windows), zlib based compression and support of multiple VM
|
||||
snapshots.
|
||||
|
||||
Supported options:
|
||||
|
||||
.. program:: qcow2
|
||||
.. option:: compat
|
||||
|
||||
Determines the qcow2 version to use. ``compat=0.10`` uses the
|
||||
traditional image format that can be read by any QEMU since 0.10.
|
||||
``compat=1.1`` enables image format extensions that only QEMU 1.1 and
|
||||
newer understand (this is the default). Amongst others, this includes
|
||||
zero clusters, which allow efficient copy-on-read for sparse images.
|
||||
|
||||
.. option:: backing_file
|
||||
|
||||
File name of a base image (see ``create`` subcommand)
|
||||
|
||||
.. option:: backing_fmt
|
||||
|
||||
Image format of the base image
|
||||
|
||||
.. option:: encryption
|
||||
|
||||
This option is deprecated and equivalent to ``encrypt.format=aes``
|
||||
|
||||
.. option:: encrypt.format
|
||||
|
||||
If this is set to ``luks``, it requests that the qcow2 payload (not
|
||||
qcow2 header) be encrypted using the LUKS format. The passphrase to
|
||||
use to unlock the LUKS key slot is given by the ``encrypt.key-secret``
|
||||
parameter. LUKS encryption parameters can be tuned with the other
|
||||
``encrypt.*`` parameters.
|
||||
|
||||
If this is set to ``aes``, the image is encrypted with 128-bit AES-CBC.
|
||||
The encryption key is given by the ``encrypt.key-secret`` parameter.
|
||||
This encryption format is considered to be flawed by modern cryptography
|
||||
standards, suffering from a number of design problems:
|
||||
|
||||
- The AES-CBC cipher is used with predictable initialization vectors based
|
||||
on the sector number. This makes it vulnerable to chosen plaintext attacks
|
||||
which can reveal the existence of encrypted data.
|
||||
- The user passphrase is directly used as the encryption key. A poorly
|
||||
chosen or short passphrase will compromise the security of the encryption.
|
||||
- In the event of the passphrase being compromised there is no way to
|
||||
change the passphrase to protect data in any qcow images. The files must
|
||||
be cloned, using a different encryption passphrase in the new file. The
|
||||
original file must then be securely erased using a program like shred,
|
||||
though even this is ineffective with many modern storage technologies.
|
||||
|
||||
The use of this is no longer supported in system emulators. Support only
|
||||
remains in the command line utilities, for the purposes of data liberation
|
||||
and interoperability with old versions of QEMU. The ``luks`` format
|
||||
should be used instead.
|
||||
|
||||
.. option:: encrypt.key-secret
|
||||
|
||||
Provides the ID of a ``secret`` object that contains the passphrase
|
||||
(``encrypt.format=luks``) or encryption key (``encrypt.format=aes``).
|
||||
|
||||
.. option:: encrypt.cipher-alg
|
||||
|
||||
Name of the cipher algorithm and key length. Currently defaults
|
||||
to ``aes-256``. Only used when ``encrypt.format=luks``.
|
||||
|
||||
.. option:: encrypt.cipher-mode
|
||||
|
||||
Name of the encryption mode to use. Currently defaults to ``xts``.
|
||||
Only used when ``encrypt.format=luks``.
|
||||
|
||||
.. option:: encrypt.ivgen-alg
|
||||
|
||||
Name of the initialization vector generator algorithm. Currently defaults
|
||||
to ``plain64``. Only used when ``encrypt.format=luks``.
|
||||
|
||||
.. option:: encrypt.ivgen-hash-alg
|
||||
|
||||
Name of the hash algorithm to use with the initialization vector generator
|
||||
(if required). Defaults to ``sha256``. Only used when ``encrypt.format=luks``.
|
||||
|
||||
.. option:: encrypt.hash-alg
|
||||
|
||||
Name of the hash algorithm to use for PBKDF algorithm
|
||||
Defaults to ``sha256``. Only used when ``encrypt.format=luks``.
|
||||
|
||||
.. option:: encrypt.iter-time
|
||||
|
||||
Amount of time, in milliseconds, to use for PBKDF algorithm per key slot.
|
||||
Defaults to ``2000``. Only used when ``encrypt.format=luks``.
|
||||
|
||||
.. option:: cluster_size
|
||||
|
||||
Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
|
||||
sizes can improve the image file size whereas larger cluster sizes generally
|
||||
provide better performance.
|
||||
|
||||
.. option:: preallocation
|
||||
|
||||
Preallocation mode (allowed values: ``off``, ``metadata``, ``falloc``,
|
||||
``full``). An image with preallocated metadata is initially larger but can
|
||||
improve performance when the image needs to grow. ``falloc`` and ``full``
|
||||
preallocations are like the same options of ``raw`` format, but sets up
|
||||
metadata also.
|
||||
|
||||
.. option:: lazy_refcounts
|
||||
|
||||
If this option is set to ``on``, reference count updates are postponed with
|
||||
the goal of avoiding metadata I/O and improving performance. This is
|
||||
particularly interesting with :option:`cache=writethrough` which doesn't batch
|
||||
metadata updates. The tradeoff is that after a host crash, the reference count
|
||||
tables must be rebuilt, i.e. on the next open an (automatic) ``qemu-img
|
||||
check -r all`` is required, which may take some time.
|
||||
|
||||
This option can only be enabled if ``compat=1.1`` is specified.
|
||||
|
||||
.. option:: nocow
|
||||
|
||||
If this option is set to ``on``, it will turn off COW of the file. It's only
|
||||
valid on btrfs, no effect on other file systems.
|
||||
|
||||
Btrfs has low performance when hosting a VM image file, even more
|
||||
when the guest on the VM also using btrfs as file system. Turning off
|
||||
COW is a way to mitigate this bad performance. Generally there are two
|
||||
ways to turn off COW on btrfs:
|
||||
|
||||
- Disable it by mounting with nodatacow, then all newly created files
|
||||
will be NOCOW.
|
||||
- For an empty file, add the NOCOW file attribute. That's what this
|
||||
option does.
|
||||
|
||||
Note: this option is only valid to new or empty files. If there is
|
||||
an existing file which is COW and has data blocks already, it couldn't
|
||||
be changed to NOCOW by setting ``nocow=on``. One can issue ``lsattr
|
||||
filename`` to check if the NOCOW flag is set or not (Capital 'C' is
|
||||
NOCOW flag).
|
||||
|
||||
.. program:: image-formats
|
||||
.. option:: qed
|
||||
|
||||
Old QEMU image format with support for backing files and compact image files
|
||||
(when your filesystem or transport medium does not support holes).
|
||||
|
||||
When converting QED images to qcow2, you might want to consider using the
|
||||
``lazy_refcounts=on`` option to get a more QED-like behaviour.
|
||||
|
||||
Supported options:
|
||||
|
||||
.. program:: qed
|
||||
.. option:: backing_file
|
||||
|
||||
File name of a base image (see ``create`` subcommand).
|
||||
|
||||
.. option:: backing_fmt
|
||||
|
||||
Image file format of backing file (optional). Useful if the format cannot be
|
||||
autodetected because it has no header, like some vhd/vpc files.
|
||||
|
||||
.. option:: cluster_size
|
||||
|
||||
Changes the cluster size (must be power-of-2 between 4K and 64K). Smaller
|
||||
cluster sizes can improve the image file size whereas larger cluster sizes
|
||||
generally provide better performance.
|
||||
|
||||
.. option:: table_size
|
||||
|
||||
Changes the number of clusters per L1/L2 table (must be
|
||||
power-of-2 between 1 and 16). There is normally no need to
|
||||
change this value but this option can between used for
|
||||
performance benchmarking.
|
||||
|
||||
.. program:: image-formats
|
||||
.. option:: qcow
|
||||
|
||||
Old QEMU image format with support for backing files, compact image files,
|
||||
encryption and compression.
|
||||
|
||||
Supported options:
|
||||
|
||||
.. program:: qcow
|
||||
.. option:: backing_file
|
||||
|
||||
File name of a base image (see ``create`` subcommand)
|
||||
|
||||
.. option:: encryption
|
||||
|
||||
This option is deprecated and equivalent to ``encrypt.format=aes``
|
||||
|
||||
.. option:: encrypt.format
|
||||
|
||||
If this is set to ``aes``, the image is encrypted with 128-bit AES-CBC.
|
||||
The encryption key is given by the ``encrypt.key-secret`` parameter.
|
||||
This encryption format is considered to be flawed by modern cryptography
|
||||
standards, suffering from a number of design problems enumerated previously
|
||||
against the ``qcow2`` image format.
|
||||
|
||||
The use of this is no longer supported in system emulators. Support only
|
||||
remains in the command line utilities, for the purposes of data liberation
|
||||
and interoperability with old versions of QEMU.
|
||||
|
||||
Users requiring native encryption should use the ``qcow2`` format
|
||||
instead with ``encrypt.format=luks``.
|
||||
|
||||
.. option:: encrypt.key-secret
|
||||
|
||||
Provides the ID of a ``secret`` object that contains the encryption
|
||||
key (``encrypt.format=aes``).
|
||||
|
||||
.. program:: image-formats
|
||||
.. option:: luks
|
||||
|
||||
LUKS v1 encryption format, compatible with Linux dm-crypt/cryptsetup
|
||||
|
||||
Supported options:
|
||||
|
||||
.. program:: luks
|
||||
.. option:: key-secret
|
||||
|
||||
Provides the ID of a ``secret`` object that contains the passphrase.
|
||||
|
||||
.. option:: cipher-alg
|
||||
|
||||
Name of the cipher algorithm and key length. Currently defaults
|
||||
to ``aes-256``.
|
||||
|
||||
.. option:: cipher-mode
|
||||
|
||||
Name of the encryption mode to use. Currently defaults to ``xts``.
|
||||
|
||||
.. option:: ivgen-alg
|
||||
|
||||
Name of the initialization vector generator algorithm. Currently defaults
|
||||
to ``plain64``.
|
||||
|
||||
.. option:: ivgen-hash-alg
|
||||
|
||||
Name of the hash algorithm to use with the initialization vector generator
|
||||
(if required). Defaults to ``sha256``.
|
||||
|
||||
.. option:: hash-alg
|
||||
|
||||
Name of the hash algorithm to use for PBKDF algorithm
|
||||
Defaults to ``sha256``.
|
||||
|
||||
.. option:: iter-time
|
||||
|
||||
Amount of time, in milliseconds, to use for PBKDF algorithm per key slot.
|
||||
Defaults to ``2000``.
|
||||
|
||||
.. program:: image-formats
|
||||
.. option:: vdi
|
||||
|
||||
VirtualBox 1.1 compatible image format.
|
||||
|
||||
Supported options:
|
||||
|
||||
.. program:: vdi
|
||||
.. option:: static
|
||||
|
||||
If this option is set to ``on``, the image is created with metadata
|
||||
preallocation.
|
||||
|
||||
.. program:: image-formats
|
||||
.. option:: vmdk
|
||||
|
||||
VMware 3 and 4 compatible image format.
|
||||
|
||||
Supported options:
|
||||
|
||||
.. program: vmdk
|
||||
.. option:: backing_file
|
||||
|
||||
File name of a base image (see ``create`` subcommand).
|
||||
|
||||
.. option:: compat6
|
||||
|
||||
Create a VMDK version 6 image (instead of version 4)
|
||||
|
||||
.. option:: hwversion
|
||||
|
||||
Specify vmdk virtual hardware version. Compat6 flag cannot be enabled
|
||||
if hwversion is specified.
|
||||
|
||||
.. option:: subformat
|
||||
|
||||
Specifies which VMDK subformat to use. Valid options are
|
||||
``monolithicSparse`` (default),
|
||||
``monolithicFlat``,
|
||||
``twoGbMaxExtentSparse``,
|
||||
``twoGbMaxExtentFlat`` and
|
||||
``streamOptimized``.
|
||||
|
||||
.. program:: image-formats
|
||||
.. option:: vpc
|
||||
|
||||
VirtualPC compatible image format (VHD).
|
||||
|
||||
Supported options:
|
||||
|
||||
.. program:: vpc
|
||||
.. option:: subformat
|
||||
|
||||
Specifies which VHD subformat to use. Valid options are
|
||||
``dynamic`` (default) and ``fixed``.
|
||||
|
||||
.. program:: image-formats
|
||||
.. option:: VHDX
|
||||
|
||||
Hyper-V compatible image format (VHDX).
|
||||
|
||||
Supported options:
|
||||
|
||||
.. program:: VHDX
|
||||
.. option:: subformat
|
||||
|
||||
Specifies which VHDX subformat to use. Valid options are
|
||||
``dynamic`` (default) and ``fixed``.
|
||||
|
||||
.. option:: block_state_zero
|
||||
|
||||
Force use of payload blocks of type 'ZERO'. Can be set to ``on`` (default)
|
||||
or ``off``. When set to ``off``, new blocks will be created as
|
||||
``PAYLOAD_BLOCK_NOT_PRESENT``, which means parsers are free to return
|
||||
arbitrary data for those blocks. Do not set to ``off`` when using
|
||||
``qemu-img convert`` with ``subformat=dynamic``.
|
||||
|
||||
.. option:: block_size
|
||||
|
||||
Block size; min 1 MB, max 256 MB. 0 means auto-calculate based on
|
||||
image size.
|
||||
|
||||
.. option:: log_size
|
||||
|
||||
Log size; min 1 MB.
|
||||
|
||||
Read-only formats
|
||||
-----------------
|
||||
|
||||
More disk image file formats are supported in a read-only mode.
|
||||
|
||||
.. program:: image-formats
|
||||
.. option:: bochs
|
||||
|
||||
Bochs images of ``growing`` type.
|
||||
|
||||
.. program:: image-formats
|
||||
.. option:: cloop
|
||||
|
||||
Linux Compressed Loop image, useful only to reuse directly compressed
|
||||
CD-ROM images present for example in the Knoppix CD-ROMs.
|
||||
|
||||
.. program:: image-formats
|
||||
.. option:: dmg
|
||||
|
||||
Apple disk image.
|
||||
|
||||
.. program:: image-formats
|
||||
.. option:: parallels
|
||||
|
||||
Parallels disk image format.
|
||||
|
||||
Using host drives
|
||||
-----------------
|
||||
|
||||
In addition to disk image files, QEMU can directly access host
|
||||
devices. We describe here the usage for QEMU version >= 0.8.3.
|
||||
|
||||
Linux
|
||||
'''''
|
||||
|
||||
On Linux, you can directly use the host device filename instead of a
|
||||
disk image filename provided you have enough privileges to access
|
||||
it. For example, use ``/dev/cdrom`` to access to the CDROM.
|
||||
|
||||
CD
|
||||
You can specify a CDROM device even if no CDROM is loaded. QEMU has
|
||||
specific code to detect CDROM insertion or removal. CDROM ejection by
|
||||
the guest OS is supported. Currently only data CDs are supported.
|
||||
|
||||
Floppy
|
||||
You can specify a floppy device even if no floppy is loaded. Floppy
|
||||
removal is currently not detected accurately (if you change floppy
|
||||
without doing floppy access while the floppy is not loaded, the guest
|
||||
OS will think that the same floppy is loaded).
|
||||
Use of the host's floppy device is deprecated, and support for it will
|
||||
be removed in a future release.
|
||||
|
||||
Hard disks
|
||||
Hard disks can be used. Normally you must specify the whole disk
|
||||
(``/dev/hdb`` instead of ``/dev/hdb1``) so that the guest OS can
|
||||
see it as a partitioned disk. WARNING: unless you know what you do, it
|
||||
is better to only make READ-ONLY accesses to the hard disk otherwise
|
||||
you may corrupt your host data (use the ``-snapshot`` command
|
||||
line option or modify the device permissions accordingly).
|
||||
|
||||
Windows
|
||||
'''''''
|
||||
|
||||
CD
|
||||
The preferred syntax is the drive letter (e.g. ``d:``). The
|
||||
alternate syntax ``\\.\d:`` is supported. ``/dev/cdrom`` is
|
||||
supported as an alias to the first CDROM drive.
|
||||
|
||||
Currently there is no specific code to handle removable media, so it
|
||||
is better to use the ``change`` or ``eject`` monitor commands to
|
||||
change or eject media.
|
||||
|
||||
Hard disks
|
||||
Hard disks can be used with the syntax: ``\\.\PhysicalDriveN``
|
||||
where *N* is the drive number (0 is the first hard disk).
|
||||
|
||||
WARNING: unless you know what you do, it is better to only make
|
||||
READ-ONLY accesses to the hard disk otherwise you may corrupt your
|
||||
host data (use the ``-snapshot`` command line so that the
|
||||
modifications are written in a temporary file).
|
||||
|
||||
Mac OS X
|
||||
''''''''
|
||||
|
||||
``/dev/cdrom`` is an alias to the first CDROM.
|
||||
|
||||
Currently there is no specific code to handle removable media, so it
|
||||
is better to use the ``change`` or ``eject`` monitor commands to
|
||||
change or eject media.
|
||||
|
||||
Virtual FAT disk images
|
||||
-----------------------
|
||||
|
||||
QEMU can automatically create a virtual FAT disk image from a
|
||||
directory tree. In order to use it, just type:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| linux.img -hdb fat:/my_directory
|
||||
|
||||
Then you access access to all the files in the ``/my_directory``
|
||||
directory without having to copy them in a disk image or to export
|
||||
them via SAMBA or NFS. The default access is *read-only*.
|
||||
|
||||
Floppies can be emulated with the ``:floppy:`` option:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| linux.img -fda fat:floppy:/my_directory
|
||||
|
||||
A read/write support is available for testing (beta stage) with the
|
||||
``:rw:`` option:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| linux.img -fda fat:floppy:rw:/my_directory
|
||||
|
||||
What you should *never* do:
|
||||
|
||||
- use non-ASCII filenames
|
||||
- use "-snapshot" together with ":rw:"
|
||||
- expect it to work when loadvm'ing
|
||||
- write to the FAT directory on the host system while accessing it with the guest system
|
||||
|
||||
NBD access
|
||||
----------
|
||||
|
||||
QEMU can access directly to block device exported using the Network Block Device
|
||||
protocol.
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| linux.img -hdb nbd://my_nbd_server.mydomain.org:1024/
|
||||
|
||||
If the NBD server is located on the same host, you can use an unix socket instead
|
||||
of an inet socket:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| linux.img -hdb nbd+unix://?socket=/tmp/my_socket
|
||||
|
||||
In this case, the block device must be exported using qemu-nbd:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
|
||||
|
||||
The use of qemu-nbd allows sharing of a disk between several guests:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
|
||||
|
||||
and then you can use it with two guests:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| linux1.img -hdb nbd+unix://?socket=/tmp/my_socket
|
||||
|qemu_system| linux2.img -hdb nbd+unix://?socket=/tmp/my_socket
|
||||
|
||||
If the nbd-server uses named exports (supported since NBD 2.9.18, or with QEMU's
|
||||
own embedded NBD server), you must specify an export name in the URI:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -cdrom nbd://localhost/debian-500-ppc-netinst
|
||||
|qemu_system| -cdrom nbd://localhost/openSUSE-11.1-ppc-netinst
|
||||
|
||||
The URI syntax for NBD is supported since QEMU 1.3. An alternative syntax is
|
||||
also available. Here are some example of the older syntax:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
|
||||
|qemu_system| linux2.img -hdb nbd:unix:/tmp/my_socket
|
||||
|qemu_system| -cdrom nbd:localhost:10809:exportname=debian-500-ppc-netinst
|
||||
|
||||
|
||||
|
||||
Sheepdog disk images
|
||||
--------------------
|
||||
|
||||
Sheepdog is a distributed storage system for QEMU. It provides highly
|
||||
available block level storage volumes that can be attached to
|
||||
QEMU-based virtual machines.
|
||||
|
||||
You can create a Sheepdog disk image with the command:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
qemu-img create sheepdog:///IMAGE SIZE
|
||||
|
||||
where *IMAGE* is the Sheepdog image name and *SIZE* is its
|
||||
size.
|
||||
|
||||
To import the existing *FILENAME* to Sheepdog, you can use a
|
||||
convert command.
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
qemu-img convert FILENAME sheepdog:///IMAGE
|
||||
|
||||
You can boot from the Sheepdog disk image with the command:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| sheepdog:///IMAGE
|
||||
|
||||
You can also create a snapshot of the Sheepdog image like qcow2.
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
qemu-img snapshot -c TAG sheepdog:///IMAGE
|
||||
|
||||
where *TAG* is a tag name of the newly created snapshot.
|
||||
|
||||
To boot from the Sheepdog snapshot, specify the tag name of the
|
||||
snapshot.
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| sheepdog:///IMAGE#TAG
|
||||
|
||||
You can create a cloned image from the existing snapshot.
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
qemu-img create -b sheepdog:///BASE#TAG sheepdog:///IMAGE
|
||||
|
||||
where *BASE* is an image name of the source snapshot and *TAG*
|
||||
is its tag name.
|
||||
|
||||
You can use an unix socket instead of an inet socket:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| sheepdog+unix:///IMAGE?socket=PATH
|
||||
|
||||
If the Sheepdog daemon doesn't run on the local host, you need to
|
||||
specify one of the Sheepdog servers to connect to.
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
qemu-img create sheepdog://HOSTNAME:PORT/IMAGE SIZE
|
||||
|qemu_system| sheepdog://HOSTNAME:PORT/IMAGE
|
||||
|
||||
iSCSI LUNs
|
||||
----------
|
||||
|
||||
iSCSI is a popular protocol used to access SCSI devices across a computer
|
||||
network.
|
||||
|
||||
There are two different ways iSCSI devices can be used by QEMU.
|
||||
|
||||
The first method is to mount the iSCSI LUN on the host, and make it appear as
|
||||
any other ordinary SCSI device on the host and then to access this device as a
|
||||
/dev/sd device from QEMU. How to do this differs between host OSes.
|
||||
|
||||
The second method involves using the iSCSI initiator that is built into
|
||||
QEMU. This provides a mechanism that works the same way regardless of which
|
||||
host OS you are running QEMU on. This section will describe this second method
|
||||
of using iSCSI together with QEMU.
|
||||
|
||||
In QEMU, iSCSI devices are described using special iSCSI URLs. URL syntax:
|
||||
|
||||
::
|
||||
|
||||
iscsi://[<username>[%<password>]@]<host>[:<port>]/<target-iqn-name>/<lun>
|
||||
|
||||
Username and password are optional and only used if your target is set up
|
||||
using CHAP authentication for access control.
|
||||
Alternatively the username and password can also be set via environment
|
||||
variables to have these not show up in the process list:
|
||||
|
||||
::
|
||||
|
||||
export LIBISCSI_CHAP_USERNAME=<username>
|
||||
export LIBISCSI_CHAP_PASSWORD=<password>
|
||||
iscsi://<host>/<target-iqn-name>/<lun>
|
||||
|
||||
Various session related parameters can be set via special options, either
|
||||
in a configuration file provided via '-readconfig' or directly on the
|
||||
command line.
|
||||
|
||||
If the initiator-name is not specified qemu will use a default name
|
||||
of 'iqn.2008-11.org.linux-kvm[:<uuid>'] where <uuid> is the UUID of the
|
||||
virtual machine. If the UUID is not specified qemu will use
|
||||
'iqn.2008-11.org.linux-kvm[:<name>'] where <name> is the name of the
|
||||
virtual machine.
|
||||
|
||||
Setting a specific initiator name to use when logging in to the target:
|
||||
|
||||
::
|
||||
|
||||
-iscsi initiator-name=iqn.qemu.test:my-initiator
|
||||
|
||||
Controlling which type of header digest to negotiate with the target:
|
||||
|
||||
::
|
||||
|
||||
-iscsi header-digest=CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
|
||||
|
||||
These can also be set via a configuration file:
|
||||
|
||||
::
|
||||
|
||||
[iscsi]
|
||||
user = "CHAP username"
|
||||
password = "CHAP password"
|
||||
initiator-name = "iqn.qemu.test:my-initiator"
|
||||
# header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
|
||||
header-digest = "CRC32C"
|
||||
|
||||
Setting the target name allows different options for different targets:
|
||||
|
||||
::
|
||||
|
||||
[iscsi "iqn.target.name"]
|
||||
user = "CHAP username"
|
||||
password = "CHAP password"
|
||||
initiator-name = "iqn.qemu.test:my-initiator"
|
||||
# header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
|
||||
header-digest = "CRC32C"
|
||||
|
||||
How to use a configuration file to set iSCSI configuration options:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
cat >iscsi.conf <<EOF
|
||||
[iscsi]
|
||||
user = "me"
|
||||
password = "my password"
|
||||
initiator-name = "iqn.qemu.test:my-initiator"
|
||||
header-digest = "CRC32C"
|
||||
EOF
|
||||
|
||||
|qemu_system| -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \\
|
||||
-readconfig iscsi.conf
|
||||
|
||||
How to set up a simple iSCSI target on loopback and access it via QEMU:
|
||||
this example shows how to set up an iSCSI target with one CDROM and one DISK
|
||||
using the Linux STGT software target. This target is available on Red Hat based
|
||||
systems as the package 'scsi-target-utils'.
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
tgtd --iscsi portal=127.0.0.1:3260
|
||||
tgtadm --lld iscsi --op new --mode target --tid 1 -T iqn.qemu.test
|
||||
tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 1 \\
|
||||
-b /IMAGES/disk.img --device-type=disk
|
||||
tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 2 \\
|
||||
-b /IMAGES/cd.iso --device-type=cd
|
||||
tgtadm --lld iscsi --op bind --mode target --tid 1 -I ALL
|
||||
|
||||
|qemu_system| -iscsi initiator-name=iqn.qemu.test:my-initiator \\
|
||||
-boot d -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \\
|
||||
-cdrom iscsi://127.0.0.1/iqn.qemu.test/2
|
||||
|
||||
GlusterFS disk images
|
||||
---------------------
|
||||
|
||||
GlusterFS is a user space distributed file system.
|
||||
|
||||
You can boot from the GlusterFS disk image with the command:
|
||||
|
||||
URI:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -drive file=gluster[+TYPE]://[HOST}[:PORT]]/VOLUME/PATH
|
||||
[?socket=...][,file.debug=9][,file.logfile=...]
|
||||
|
||||
JSON:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| 'json:{"driver":"qcow2",
|
||||
"file":{"driver":"gluster",
|
||||
"volume":"testvol","path":"a.img","debug":9,"logfile":"...",
|
||||
"server":[{"type":"tcp","host":"...","port":"..."},
|
||||
{"type":"unix","socket":"..."}]}}'
|
||||
|
||||
*gluster* is the protocol.
|
||||
|
||||
*TYPE* specifies the transport type used to connect to gluster
|
||||
management daemon (glusterd). Valid transport types are
|
||||
tcp and unix. In the URI form, if a transport type isn't specified,
|
||||
then tcp type is assumed.
|
||||
|
||||
*HOST* specifies the server where the volume file specification for
|
||||
the given volume resides. This can be either a hostname or an ipv4 address.
|
||||
If transport type is unix, then *HOST* field should not be specified.
|
||||
Instead *socket* field needs to be populated with the path to unix domain
|
||||
socket.
|
||||
|
||||
*PORT* is the port number on which glusterd is listening. This is optional
|
||||
and if not specified, it defaults to port 24007. If the transport type is unix,
|
||||
then *PORT* should not be specified.
|
||||
|
||||
*VOLUME* is the name of the gluster volume which contains the disk image.
|
||||
|
||||
*PATH* is the path to the actual disk image that resides on gluster volume.
|
||||
|
||||
*debug* is the logging level of the gluster protocol driver. Debug levels
|
||||
are 0-9, with 9 being the most verbose, and 0 representing no debugging output.
|
||||
The default level is 4. The current logging levels defined in the gluster source
|
||||
are 0 - None, 1 - Emergency, 2 - Alert, 3 - Critical, 4 - Error, 5 - Warning,
|
||||
6 - Notice, 7 - Info, 8 - Debug, 9 - Trace
|
||||
|
||||
*logfile* is a commandline option to mention log file path which helps in
|
||||
logging to the specified file and also help in persisting the gfapi logs. The
|
||||
default is stderr.
|
||||
|
||||
You can create a GlusterFS disk image with the command:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
qemu-img create gluster://HOST/VOLUME/PATH SIZE
|
||||
|
||||
Examples
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -drive file=gluster://1.2.3.4/testvol/a.img
|
||||
|qemu_system| -drive file=gluster+tcp://1.2.3.4/testvol/a.img
|
||||
|qemu_system| -drive file=gluster+tcp://1.2.3.4:24007/testvol/dir/a.img
|
||||
|qemu_system| -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]/testvol/dir/a.img
|
||||
|qemu_system| -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]:24007/testvol/dir/a.img
|
||||
|qemu_system| -drive file=gluster+tcp://server.domain.com:24007/testvol/dir/a.img
|
||||
|qemu_system| -drive file=gluster+unix:///testvol/dir/a.img?socket=/tmp/glusterd.socket
|
||||
|qemu_system| -drive file=gluster+rdma://1.2.3.4:24007/testvol/a.img
|
||||
|qemu_system| -drive file=gluster://1.2.3.4/testvol/a.img,file.debug=9,file.logfile=/var/log/qemu-gluster.log
|
||||
|qemu_system| 'json:{"driver":"qcow2",
|
||||
"file":{"driver":"gluster",
|
||||
"volume":"testvol","path":"a.img",
|
||||
"debug":9,"logfile":"/var/log/qemu-gluster.log",
|
||||
"server":[{"type":"tcp","host":"1.2.3.4","port":24007},
|
||||
{"type":"unix","socket":"/var/run/glusterd.socket"}]}}'
|
||||
|qemu_system| -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
|
||||
file.debug=9,file.logfile=/var/log/qemu-gluster.log,
|
||||
file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
|
||||
file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
|
||||
|
||||
Secure Shell (ssh) disk images
|
||||
------------------------------
|
||||
|
||||
You can access disk images located on a remote ssh server
|
||||
by using the ssh protocol:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -drive file=ssh://[USER@]SERVER[:PORT]/PATH[?host_key_check=HOST_KEY_CHECK]
|
||||
|
||||
Alternative syntax using properties:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -drive file.driver=ssh[,file.user=USER],file.host=SERVER[,file.port=PORT],file.path=PATH[,file.host_key_check=HOST_KEY_CHECK]
|
||||
|
||||
*ssh* is the protocol.
|
||||
|
||||
*USER* is the remote user. If not specified, then the local
|
||||
username is tried.
|
||||
|
||||
*SERVER* specifies the remote ssh server. Any ssh server can be
|
||||
used, but it must implement the sftp-server protocol. Most Unix/Linux
|
||||
systems should work without requiring any extra configuration.
|
||||
|
||||
*PORT* is the port number on which sshd is listening. By default
|
||||
the standard ssh port (22) is used.
|
||||
|
||||
*PATH* is the path to the disk image.
|
||||
|
||||
The optional *HOST_KEY_CHECK* parameter controls how the remote
|
||||
host's key is checked. The default is ``yes`` which means to use
|
||||
the local ``.ssh/known_hosts`` file. Setting this to ``no``
|
||||
turns off known-hosts checking. Or you can check that the host key
|
||||
matches a specific fingerprint:
|
||||
``host_key_check=md5:78:45:8e:14:57:4f:d5:45:83:0a:0e:f3:49:82:c9:c8``
|
||||
(``sha1:`` can also be used as a prefix, but note that OpenSSH
|
||||
tools only use MD5 to print fingerprints).
|
||||
|
||||
Currently authentication must be done using ssh-agent. Other
|
||||
authentication methods may be supported in future.
|
||||
|
||||
Note: Many ssh servers do not support an ``fsync``-style operation.
|
||||
The ssh driver cannot guarantee that disk flush requests are
|
||||
obeyed, and this causes a risk of disk corruption if the remote
|
||||
server or network goes down during writes. The driver will
|
||||
print a warning when ``fsync`` is not supported:
|
||||
|
||||
::
|
||||
|
||||
warning: ssh server ssh.example.com:22 does not support fsync
|
||||
|
||||
With sufficiently new versions of libssh and OpenSSH, ``fsync`` is
|
||||
supported.
|
||||
|
||||
NVMe disk images
|
||||
----------------
|
||||
|
||||
NVM Express (NVMe) storage controllers can be accessed directly by a userspace
|
||||
driver in QEMU. This bypasses the host kernel file system and block layers
|
||||
while retaining QEMU block layer functionalities, such as block jobs, I/O
|
||||
throttling, image formats, etc. Disk I/O performance is typically higher than
|
||||
with ``-drive file=/dev/sda`` using either thread pool or linux-aio.
|
||||
|
||||
The controller will be exclusively used by the QEMU process once started. To be
|
||||
able to share storage between multiple VMs and other applications on the host,
|
||||
please use the file based protocols.
|
||||
|
||||
Before starting QEMU, bind the host NVMe controller to the host vfio-pci
|
||||
driver. For example:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
# modprobe vfio-pci
|
||||
# lspci -n -s 0000:06:0d.0
|
||||
06:0d.0 0401: 1102:0002 (rev 08)
|
||||
# echo 0000:06:0d.0 > /sys/bus/pci/devices/0000:06:0d.0/driver/unbind
|
||||
# echo 1102 0002 > /sys/bus/pci/drivers/vfio-pci/new_id
|
||||
|
||||
# |qemu_system| -drive file=nvme://HOST:BUS:SLOT.FUNC/NAMESPACE
|
||||
|
||||
Alternative syntax using properties:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -drive file.driver=nvme,file.device=HOST:BUS:SLOT.FUNC,file.namespace=NAMESPACE
|
||||
|
||||
*HOST*:*BUS*:*SLOT*.\ *FUNC* is the NVMe controller's PCI device
|
||||
address on the host.
|
||||
|
||||
*NAMESPACE* is the NVMe namespace number, starting from 1.
|
||||
|
||||
Disk image file locking
|
||||
-----------------------
|
||||
|
||||
By default, QEMU tries to protect image files from unexpected concurrent
|
||||
access, as long as it's supported by the block protocol driver and host
|
||||
operating system. If multiple QEMU processes (including QEMU emulators and
|
||||
utilities) try to open the same image with conflicting accessing modes, all but
|
||||
the first one will get an error.
|
||||
|
||||
This feature is currently supported by the file protocol on Linux with the Open
|
||||
File Descriptor (OFD) locking API, and can be configured to fall back to POSIX
|
||||
locking if the POSIX host doesn't support Linux OFD locking.
|
||||
|
||||
To explicitly enable image locking, specify "locking=on" in the file protocol
|
||||
driver options. If OFD locking is not possible, a warning will be printed and
|
||||
the POSIX locking API will be used. In this case there is a risk that the lock
|
||||
will get silently lost when doing hot plugging and block jobs, due to the
|
||||
shortcomings of the POSIX locking API.
|
||||
|
||||
QEMU transparently handles lock handover during shared storage migration. For
|
||||
shared virtual disk images between multiple VMs, the "share-rw" device option
|
||||
should be used.
|
||||
|
||||
By default, the guest has exclusive write access to its disk image. If the
|
||||
guest can safely share the disk image with other writers the
|
||||
``-device ...,share-rw=on`` parameter can be used. This is only safe if
|
||||
the guest is running software, such as a cluster file system, that
|
||||
coordinates disk accesses to avoid corruption.
|
||||
|
||||
Note that share-rw=on only declares the guest's ability to share the disk.
|
||||
Some QEMU features, such as image file formats, require exclusive write access
|
||||
to the disk image and this is unaffected by the share-rw=on option.
|
||||
|
||||
Alternatively, locking can be fully disabled by "locking=off" block device
|
||||
option. In the command line, the option is usually in the form of
|
||||
"file.locking=off" as the protocol driver is normally placed as a "file" child
|
||||
under a format driver. For example:
|
||||
|
||||
::
|
||||
|
||||
-blockdev driver=qcow2,file.filename=/path/to/image,file.locking=off,file.driver=file
|
||||
|
||||
To check if image locking is active, check the output of the "lslocks" command
|
||||
on host and see if there are locks held by the QEMU process on the image file.
|
||||
More than one byte could be locked by the QEMU instance, each byte of which
|
||||
reflects a particular permission that is acquired or protected by the running
|
||||
block driver.
|
||||
|
||||
.. only:: man
|
||||
|
||||
See also
|
||||
--------
|
||||
|
||||
The HTML documentation of QEMU for more precise information and Linux
|
||||
user mode emulator invocation.
|
||||
The HTML documentation of QEMU for more precise information and Linux
|
||||
user mode emulator invocation.
|
||||
|
|
954
docs/system/qemu-block-drivers.rst.inc
Normal file
954
docs/system/qemu-block-drivers.rst.inc
Normal file
|
@ -0,0 +1,954 @@
|
|||
Disk image file formats
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
QEMU supports many image file formats that can be used with VMs as well as with
|
||||
any of the tools (like ``qemu-img``). This includes the preferred formats
|
||||
raw and qcow2 as well as formats that are supported for compatibility with
|
||||
older QEMU versions or other hypervisors.
|
||||
|
||||
Depending on the image format, different options can be passed to
|
||||
``qemu-img create`` and ``qemu-img convert`` using the ``-o`` option.
|
||||
This section describes each format and the options that are supported for it.
|
||||
|
||||
.. program:: image-formats
|
||||
.. option:: raw
|
||||
|
||||
Raw disk image format. This format has the advantage of
|
||||
being simple and easily exportable to all other emulators. If your
|
||||
file system supports *holes* (for example in ext2 or ext3 on
|
||||
Linux or NTFS on Windows), then only the written sectors will reserve
|
||||
space. Use ``qemu-img info`` to know the real size used by the
|
||||
image or ``ls -ls`` on Unix/Linux.
|
||||
|
||||
Supported options:
|
||||
|
||||
.. program:: raw
|
||||
.. option:: preallocation
|
||||
|
||||
Preallocation mode (allowed values: ``off``, ``falloc``,
|
||||
``full``). ``falloc`` mode preallocates space for image by
|
||||
calling ``posix_fallocate()``. ``full`` mode preallocates space
|
||||
for image by writing data to underlying storage. This data may or
|
||||
may not be zero, depending on the storage location.
|
||||
|
||||
.. program:: image-formats
|
||||
.. option:: qcow2
|
||||
|
||||
QEMU image format, the most versatile format. Use it to have smaller
|
||||
images (useful if your filesystem does not supports holes, for example
|
||||
on Windows), zlib based compression and support of multiple VM
|
||||
snapshots.
|
||||
|
||||
Supported options:
|
||||
|
||||
.. program:: qcow2
|
||||
.. option:: compat
|
||||
|
||||
Determines the qcow2 version to use. ``compat=0.10`` uses the
|
||||
traditional image format that can be read by any QEMU since 0.10.
|
||||
``compat=1.1`` enables image format extensions that only QEMU 1.1 and
|
||||
newer understand (this is the default). Amongst others, this includes
|
||||
zero clusters, which allow efficient copy-on-read for sparse images.
|
||||
|
||||
.. option:: backing_file
|
||||
|
||||
File name of a base image (see ``create`` subcommand)
|
||||
|
||||
.. option:: backing_fmt
|
||||
|
||||
Image format of the base image
|
||||
|
||||
.. option:: encryption
|
||||
|
||||
This option is deprecated and equivalent to ``encrypt.format=aes``
|
||||
|
||||
.. option:: encrypt.format
|
||||
|
||||
If this is set to ``luks``, it requests that the qcow2 payload (not
|
||||
qcow2 header) be encrypted using the LUKS format. The passphrase to
|
||||
use to unlock the LUKS key slot is given by the ``encrypt.key-secret``
|
||||
parameter. LUKS encryption parameters can be tuned with the other
|
||||
``encrypt.*`` parameters.
|
||||
|
||||
If this is set to ``aes``, the image is encrypted with 128-bit AES-CBC.
|
||||
The encryption key is given by the ``encrypt.key-secret`` parameter.
|
||||
This encryption format is considered to be flawed by modern cryptography
|
||||
standards, suffering from a number of design problems:
|
||||
|
||||
- The AES-CBC cipher is used with predictable initialization vectors based
|
||||
on the sector number. This makes it vulnerable to chosen plaintext attacks
|
||||
which can reveal the existence of encrypted data.
|
||||
- The user passphrase is directly used as the encryption key. A poorly
|
||||
chosen or short passphrase will compromise the security of the encryption.
|
||||
- In the event of the passphrase being compromised there is no way to
|
||||
change the passphrase to protect data in any qcow images. The files must
|
||||
be cloned, using a different encryption passphrase in the new file. The
|
||||
original file must then be securely erased using a program like shred,
|
||||
though even this is ineffective with many modern storage technologies.
|
||||
|
||||
The use of this is no longer supported in system emulators. Support only
|
||||
remains in the command line utilities, for the purposes of data liberation
|
||||
and interoperability with old versions of QEMU. The ``luks`` format
|
||||
should be used instead.
|
||||
|
||||
.. option:: encrypt.key-secret
|
||||
|
||||
Provides the ID of a ``secret`` object that contains the passphrase
|
||||
(``encrypt.format=luks``) or encryption key (``encrypt.format=aes``).
|
||||
|
||||
.. option:: encrypt.cipher-alg
|
||||
|
||||
Name of the cipher algorithm and key length. Currently defaults
|
||||
to ``aes-256``. Only used when ``encrypt.format=luks``.
|
||||
|
||||
.. option:: encrypt.cipher-mode
|
||||
|
||||
Name of the encryption mode to use. Currently defaults to ``xts``.
|
||||
Only used when ``encrypt.format=luks``.
|
||||
|
||||
.. option:: encrypt.ivgen-alg
|
||||
|
||||
Name of the initialization vector generator algorithm. Currently defaults
|
||||
to ``plain64``. Only used when ``encrypt.format=luks``.
|
||||
|
||||
.. option:: encrypt.ivgen-hash-alg
|
||||
|
||||
Name of the hash algorithm to use with the initialization vector generator
|
||||
(if required). Defaults to ``sha256``. Only used when ``encrypt.format=luks``.
|
||||
|
||||
.. option:: encrypt.hash-alg
|
||||
|
||||
Name of the hash algorithm to use for PBKDF algorithm
|
||||
Defaults to ``sha256``. Only used when ``encrypt.format=luks``.
|
||||
|
||||
.. option:: encrypt.iter-time
|
||||
|
||||
Amount of time, in milliseconds, to use for PBKDF algorithm per key slot.
|
||||
Defaults to ``2000``. Only used when ``encrypt.format=luks``.
|
||||
|
||||
.. option:: cluster_size
|
||||
|
||||
Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
|
||||
sizes can improve the image file size whereas larger cluster sizes generally
|
||||
provide better performance.
|
||||
|
||||
.. option:: preallocation
|
||||
|
||||
Preallocation mode (allowed values: ``off``, ``metadata``, ``falloc``,
|
||||
``full``). An image with preallocated metadata is initially larger but can
|
||||
improve performance when the image needs to grow. ``falloc`` and ``full``
|
||||
preallocations are like the same options of ``raw`` format, but sets up
|
||||
metadata also.
|
||||
|
||||
.. option:: lazy_refcounts
|
||||
|
||||
If this option is set to ``on``, reference count updates are postponed with
|
||||
the goal of avoiding metadata I/O and improving performance. This is
|
||||
particularly interesting with :option:`cache=writethrough` which doesn't batch
|
||||
metadata updates. The tradeoff is that after a host crash, the reference count
|
||||
tables must be rebuilt, i.e. on the next open an (automatic) ``qemu-img
|
||||
check -r all`` is required, which may take some time.
|
||||
|
||||
This option can only be enabled if ``compat=1.1`` is specified.
|
||||
|
||||
.. option:: nocow
|
||||
|
||||
If this option is set to ``on``, it will turn off COW of the file. It's only
|
||||
valid on btrfs, no effect on other file systems.
|
||||
|
||||
Btrfs has low performance when hosting a VM image file, even more
|
||||
when the guest on the VM also using btrfs as file system. Turning off
|
||||
COW is a way to mitigate this bad performance. Generally there are two
|
||||
ways to turn off COW on btrfs:
|
||||
|
||||
- Disable it by mounting with nodatacow, then all newly created files
|
||||
will be NOCOW.
|
||||
- For an empty file, add the NOCOW file attribute. That's what this
|
||||
option does.
|
||||
|
||||
Note: this option is only valid to new or empty files. If there is
|
||||
an existing file which is COW and has data blocks already, it couldn't
|
||||
be changed to NOCOW by setting ``nocow=on``. One can issue ``lsattr
|
||||
filename`` to check if the NOCOW flag is set or not (Capital 'C' is
|
||||
NOCOW flag).
|
||||
|
||||
.. program:: image-formats
|
||||
.. option:: qed
|
||||
|
||||
Old QEMU image format with support for backing files and compact image files
|
||||
(when your filesystem or transport medium does not support holes).
|
||||
|
||||
When converting QED images to qcow2, you might want to consider using the
|
||||
``lazy_refcounts=on`` option to get a more QED-like behaviour.
|
||||
|
||||
Supported options:
|
||||
|
||||
.. program:: qed
|
||||
.. option:: backing_file
|
||||
|
||||
File name of a base image (see ``create`` subcommand).
|
||||
|
||||
.. option:: backing_fmt
|
||||
|
||||
Image file format of backing file (optional). Useful if the format cannot be
|
||||
autodetected because it has no header, like some vhd/vpc files.
|
||||
|
||||
.. option:: cluster_size
|
||||
|
||||
Changes the cluster size (must be power-of-2 between 4K and 64K). Smaller
|
||||
cluster sizes can improve the image file size whereas larger cluster sizes
|
||||
generally provide better performance.
|
||||
|
||||
.. option:: table_size
|
||||
|
||||
Changes the number of clusters per L1/L2 table (must be
|
||||
power-of-2 between 1 and 16). There is normally no need to
|
||||
change this value but this option can between used for
|
||||
performance benchmarking.
|
||||
|
||||
.. program:: image-formats
|
||||
.. option:: qcow
|
||||
|
||||
Old QEMU image format with support for backing files, compact image files,
|
||||
encryption and compression.
|
||||
|
||||
Supported options:
|
||||
|
||||
.. program:: qcow
|
||||
.. option:: backing_file
|
||||
|
||||
File name of a base image (see ``create`` subcommand)
|
||||
|
||||
.. option:: encryption
|
||||
|
||||
This option is deprecated and equivalent to ``encrypt.format=aes``
|
||||
|
||||
.. option:: encrypt.format
|
||||
|
||||
If this is set to ``aes``, the image is encrypted with 128-bit AES-CBC.
|
||||
The encryption key is given by the ``encrypt.key-secret`` parameter.
|
||||
This encryption format is considered to be flawed by modern cryptography
|
||||
standards, suffering from a number of design problems enumerated previously
|
||||
against the ``qcow2`` image format.
|
||||
|
||||
The use of this is no longer supported in system emulators. Support only
|
||||
remains in the command line utilities, for the purposes of data liberation
|
||||
and interoperability with old versions of QEMU.
|
||||
|
||||
Users requiring native encryption should use the ``qcow2`` format
|
||||
instead with ``encrypt.format=luks``.
|
||||
|
||||
.. option:: encrypt.key-secret
|
||||
|
||||
Provides the ID of a ``secret`` object that contains the encryption
|
||||
key (``encrypt.format=aes``).
|
||||
|
||||
.. program:: image-formats
|
||||
.. option:: luks
|
||||
|
||||
LUKS v1 encryption format, compatible with Linux dm-crypt/cryptsetup
|
||||
|
||||
Supported options:
|
||||
|
||||
.. program:: luks
|
||||
.. option:: key-secret
|
||||
|
||||
Provides the ID of a ``secret`` object that contains the passphrase.
|
||||
|
||||
.. option:: cipher-alg
|
||||
|
||||
Name of the cipher algorithm and key length. Currently defaults
|
||||
to ``aes-256``.
|
||||
|
||||
.. option:: cipher-mode
|
||||
|
||||
Name of the encryption mode to use. Currently defaults to ``xts``.
|
||||
|
||||
.. option:: ivgen-alg
|
||||
|
||||
Name of the initialization vector generator algorithm. Currently defaults
|
||||
to ``plain64``.
|
||||
|
||||
.. option:: ivgen-hash-alg
|
||||
|
||||
Name of the hash algorithm to use with the initialization vector generator
|
||||
(if required). Defaults to ``sha256``.
|
||||
|
||||
.. option:: hash-alg
|
||||
|
||||
Name of the hash algorithm to use for PBKDF algorithm
|
||||
Defaults to ``sha256``.
|
||||
|
||||
.. option:: iter-time
|
||||
|
||||
Amount of time, in milliseconds, to use for PBKDF algorithm per key slot.
|
||||
Defaults to ``2000``.
|
||||
|
||||
.. program:: image-formats
|
||||
.. option:: vdi
|
||||
|
||||
VirtualBox 1.1 compatible image format.
|
||||
|
||||
Supported options:
|
||||
|
||||
.. program:: vdi
|
||||
.. option:: static
|
||||
|
||||
If this option is set to ``on``, the image is created with metadata
|
||||
preallocation.
|
||||
|
||||
.. program:: image-formats
|
||||
.. option:: vmdk
|
||||
|
||||
VMware 3 and 4 compatible image format.
|
||||
|
||||
Supported options:
|
||||
|
||||
.. program: vmdk
|
||||
.. option:: backing_file
|
||||
|
||||
File name of a base image (see ``create`` subcommand).
|
||||
|
||||
.. option:: compat6
|
||||
|
||||
Create a VMDK version 6 image (instead of version 4)
|
||||
|
||||
.. option:: hwversion
|
||||
|
||||
Specify vmdk virtual hardware version. Compat6 flag cannot be enabled
|
||||
if hwversion is specified.
|
||||
|
||||
.. option:: subformat
|
||||
|
||||
Specifies which VMDK subformat to use. Valid options are
|
||||
``monolithicSparse`` (default),
|
||||
``monolithicFlat``,
|
||||
``twoGbMaxExtentSparse``,
|
||||
``twoGbMaxExtentFlat`` and
|
||||
``streamOptimized``.
|
||||
|
||||
.. program:: image-formats
|
||||
.. option:: vpc
|
||||
|
||||
VirtualPC compatible image format (VHD).
|
||||
|
||||
Supported options:
|
||||
|
||||
.. program:: vpc
|
||||
.. option:: subformat
|
||||
|
||||
Specifies which VHD subformat to use. Valid options are
|
||||
``dynamic`` (default) and ``fixed``.
|
||||
|
||||
.. program:: image-formats
|
||||
.. option:: VHDX
|
||||
|
||||
Hyper-V compatible image format (VHDX).
|
||||
|
||||
Supported options:
|
||||
|
||||
.. program:: VHDX
|
||||
.. option:: subformat
|
||||
|
||||
Specifies which VHDX subformat to use. Valid options are
|
||||
``dynamic`` (default) and ``fixed``.
|
||||
|
||||
.. option:: block_state_zero
|
||||
|
||||
Force use of payload blocks of type 'ZERO'. Can be set to ``on`` (default)
|
||||
or ``off``. When set to ``off``, new blocks will be created as
|
||||
``PAYLOAD_BLOCK_NOT_PRESENT``, which means parsers are free to return
|
||||
arbitrary data for those blocks. Do not set to ``off`` when using
|
||||
``qemu-img convert`` with ``subformat=dynamic``.
|
||||
|
||||
.. option:: block_size
|
||||
|
||||
Block size; min 1 MB, max 256 MB. 0 means auto-calculate based on
|
||||
image size.
|
||||
|
||||
.. option:: log_size
|
||||
|
||||
Log size; min 1 MB.
|
||||
|
||||
Read-only formats
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
More disk image file formats are supported in a read-only mode.
|
||||
|
||||
.. program:: image-formats
|
||||
.. option:: bochs
|
||||
|
||||
Bochs images of ``growing`` type.
|
||||
|
||||
.. program:: image-formats
|
||||
.. option:: cloop
|
||||
|
||||
Linux Compressed Loop image, useful only to reuse directly compressed
|
||||
CD-ROM images present for example in the Knoppix CD-ROMs.
|
||||
|
||||
.. program:: image-formats
|
||||
.. option:: dmg
|
||||
|
||||
Apple disk image.
|
||||
|
||||
.. program:: image-formats
|
||||
.. option:: parallels
|
||||
|
||||
Parallels disk image format.
|
||||
|
||||
Using host drives
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
In addition to disk image files, QEMU can directly access host
|
||||
devices. We describe here the usage for QEMU version >= 0.8.3.
|
||||
|
||||
Linux
|
||||
^^^^^
|
||||
|
||||
On Linux, you can directly use the host device filename instead of a
|
||||
disk image filename provided you have enough privileges to access
|
||||
it. For example, use ``/dev/cdrom`` to access to the CDROM.
|
||||
|
||||
CD
|
||||
You can specify a CDROM device even if no CDROM is loaded. QEMU has
|
||||
specific code to detect CDROM insertion or removal. CDROM ejection by
|
||||
the guest OS is supported. Currently only data CDs are supported.
|
||||
|
||||
Floppy
|
||||
You can specify a floppy device even if no floppy is loaded. Floppy
|
||||
removal is currently not detected accurately (if you change floppy
|
||||
without doing floppy access while the floppy is not loaded, the guest
|
||||
OS will think that the same floppy is loaded).
|
||||
Use of the host's floppy device is deprecated, and support for it will
|
||||
be removed in a future release.
|
||||
|
||||
Hard disks
|
||||
Hard disks can be used. Normally you must specify the whole disk
|
||||
(``/dev/hdb`` instead of ``/dev/hdb1``) so that the guest OS can
|
||||
see it as a partitioned disk. WARNING: unless you know what you do, it
|
||||
is better to only make READ-ONLY accesses to the hard disk otherwise
|
||||
you may corrupt your host data (use the ``-snapshot`` command
|
||||
line option or modify the device permissions accordingly).
|
||||
|
||||
Windows
|
||||
^^^^^^^
|
||||
|
||||
CD
|
||||
The preferred syntax is the drive letter (e.g. ``d:``). The
|
||||
alternate syntax ``\\.\d:`` is supported. ``/dev/cdrom`` is
|
||||
supported as an alias to the first CDROM drive.
|
||||
|
||||
Currently there is no specific code to handle removable media, so it
|
||||
is better to use the ``change`` or ``eject`` monitor commands to
|
||||
change or eject media.
|
||||
|
||||
Hard disks
|
||||
Hard disks can be used with the syntax: ``\\.\PhysicalDriveN``
|
||||
where *N* is the drive number (0 is the first hard disk).
|
||||
|
||||
WARNING: unless you know what you do, it is better to only make
|
||||
READ-ONLY accesses to the hard disk otherwise you may corrupt your
|
||||
host data (use the ``-snapshot`` command line so that the
|
||||
modifications are written in a temporary file).
|
||||
|
||||
Mac OS X
|
||||
^^^^^^^^
|
||||
|
||||
``/dev/cdrom`` is an alias to the first CDROM.
|
||||
|
||||
Currently there is no specific code to handle removable media, so it
|
||||
is better to use the ``change`` or ``eject`` monitor commands to
|
||||
change or eject media.
|
||||
|
||||
Virtual FAT disk images
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
QEMU can automatically create a virtual FAT disk image from a
|
||||
directory tree. In order to use it, just type:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| linux.img -hdb fat:/my_directory
|
||||
|
||||
Then you access access to all the files in the ``/my_directory``
|
||||
directory without having to copy them in a disk image or to export
|
||||
them via SAMBA or NFS. The default access is *read-only*.
|
||||
|
||||
Floppies can be emulated with the ``:floppy:`` option:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| linux.img -fda fat:floppy:/my_directory
|
||||
|
||||
A read/write support is available for testing (beta stage) with the
|
||||
``:rw:`` option:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| linux.img -fda fat:floppy:rw:/my_directory
|
||||
|
||||
What you should *never* do:
|
||||
|
||||
- use non-ASCII filenames
|
||||
- use "-snapshot" together with ":rw:"
|
||||
- expect it to work when loadvm'ing
|
||||
- write to the FAT directory on the host system while accessing it with the guest system
|
||||
|
||||
NBD access
|
||||
~~~~~~~~~~
|
||||
|
||||
QEMU can access directly to block device exported using the Network Block Device
|
||||
protocol.
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| linux.img -hdb nbd://my_nbd_server.mydomain.org:1024/
|
||||
|
||||
If the NBD server is located on the same host, you can use an unix socket instead
|
||||
of an inet socket:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| linux.img -hdb nbd+unix://?socket=/tmp/my_socket
|
||||
|
||||
In this case, the block device must be exported using qemu-nbd:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
|
||||
|
||||
The use of qemu-nbd allows sharing of a disk between several guests:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
|
||||
|
||||
and then you can use it with two guests:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| linux1.img -hdb nbd+unix://?socket=/tmp/my_socket
|
||||
|qemu_system| linux2.img -hdb nbd+unix://?socket=/tmp/my_socket
|
||||
|
||||
If the nbd-server uses named exports (supported since NBD 2.9.18, or with QEMU's
|
||||
own embedded NBD server), you must specify an export name in the URI:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -cdrom nbd://localhost/debian-500-ppc-netinst
|
||||
|qemu_system| -cdrom nbd://localhost/openSUSE-11.1-ppc-netinst
|
||||
|
||||
The URI syntax for NBD is supported since QEMU 1.3. An alternative syntax is
|
||||
also available. Here are some example of the older syntax:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
|
||||
|qemu_system| linux2.img -hdb nbd:unix:/tmp/my_socket
|
||||
|qemu_system| -cdrom nbd:localhost:10809:exportname=debian-500-ppc-netinst
|
||||
|
||||
|
||||
|
||||
Sheepdog disk images
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Sheepdog is a distributed storage system for QEMU. It provides highly
|
||||
available block level storage volumes that can be attached to
|
||||
QEMU-based virtual machines.
|
||||
|
||||
You can create a Sheepdog disk image with the command:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
qemu-img create sheepdog:///IMAGE SIZE
|
||||
|
||||
where *IMAGE* is the Sheepdog image name and *SIZE* is its
|
||||
size.
|
||||
|
||||
To import the existing *FILENAME* to Sheepdog, you can use a
|
||||
convert command.
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
qemu-img convert FILENAME sheepdog:///IMAGE
|
||||
|
||||
You can boot from the Sheepdog disk image with the command:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| sheepdog:///IMAGE
|
||||
|
||||
You can also create a snapshot of the Sheepdog image like qcow2.
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
qemu-img snapshot -c TAG sheepdog:///IMAGE
|
||||
|
||||
where *TAG* is a tag name of the newly created snapshot.
|
||||
|
||||
To boot from the Sheepdog snapshot, specify the tag name of the
|
||||
snapshot.
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| sheepdog:///IMAGE#TAG
|
||||
|
||||
You can create a cloned image from the existing snapshot.
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
qemu-img create -b sheepdog:///BASE#TAG sheepdog:///IMAGE
|
||||
|
||||
where *BASE* is an image name of the source snapshot and *TAG*
|
||||
is its tag name.
|
||||
|
||||
You can use an unix socket instead of an inet socket:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| sheepdog+unix:///IMAGE?socket=PATH
|
||||
|
||||
If the Sheepdog daemon doesn't run on the local host, you need to
|
||||
specify one of the Sheepdog servers to connect to.
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
qemu-img create sheepdog://HOSTNAME:PORT/IMAGE SIZE
|
||||
|qemu_system| sheepdog://HOSTNAME:PORT/IMAGE
|
||||
|
||||
iSCSI LUNs
|
||||
~~~~~~~~~~
|
||||
|
||||
iSCSI is a popular protocol used to access SCSI devices across a computer
|
||||
network.
|
||||
|
||||
There are two different ways iSCSI devices can be used by QEMU.
|
||||
|
||||
The first method is to mount the iSCSI LUN on the host, and make it appear as
|
||||
any other ordinary SCSI device on the host and then to access this device as a
|
||||
/dev/sd device from QEMU. How to do this differs between host OSes.
|
||||
|
||||
The second method involves using the iSCSI initiator that is built into
|
||||
QEMU. This provides a mechanism that works the same way regardless of which
|
||||
host OS you are running QEMU on. This section will describe this second method
|
||||
of using iSCSI together with QEMU.
|
||||
|
||||
In QEMU, iSCSI devices are described using special iSCSI URLs. URL syntax:
|
||||
|
||||
::
|
||||
|
||||
iscsi://[<username>[%<password>]@]<host>[:<port>]/<target-iqn-name>/<lun>
|
||||
|
||||
Username and password are optional and only used if your target is set up
|
||||
using CHAP authentication for access control.
|
||||
Alternatively the username and password can also be set via environment
|
||||
variables to have these not show up in the process list:
|
||||
|
||||
::
|
||||
|
||||
export LIBISCSI_CHAP_USERNAME=<username>
|
||||
export LIBISCSI_CHAP_PASSWORD=<password>
|
||||
iscsi://<host>/<target-iqn-name>/<lun>
|
||||
|
||||
Various session related parameters can be set via special options, either
|
||||
in a configuration file provided via '-readconfig' or directly on the
|
||||
command line.
|
||||
|
||||
If the initiator-name is not specified qemu will use a default name
|
||||
of 'iqn.2008-11.org.linux-kvm[:<uuid>'] where <uuid> is the UUID of the
|
||||
virtual machine. If the UUID is not specified qemu will use
|
||||
'iqn.2008-11.org.linux-kvm[:<name>'] where <name> is the name of the
|
||||
virtual machine.
|
||||
|
||||
Setting a specific initiator name to use when logging in to the target:
|
||||
|
||||
::
|
||||
|
||||
-iscsi initiator-name=iqn.qemu.test:my-initiator
|
||||
|
||||
Controlling which type of header digest to negotiate with the target:
|
||||
|
||||
::
|
||||
|
||||
-iscsi header-digest=CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
|
||||
|
||||
These can also be set via a configuration file:
|
||||
|
||||
::
|
||||
|
||||
[iscsi]
|
||||
user = "CHAP username"
|
||||
password = "CHAP password"
|
||||
initiator-name = "iqn.qemu.test:my-initiator"
|
||||
# header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
|
||||
header-digest = "CRC32C"
|
||||
|
||||
Setting the target name allows different options for different targets:
|
||||
|
||||
::
|
||||
|
||||
[iscsi "iqn.target.name"]
|
||||
user = "CHAP username"
|
||||
password = "CHAP password"
|
||||
initiator-name = "iqn.qemu.test:my-initiator"
|
||||
# header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
|
||||
header-digest = "CRC32C"
|
||||
|
||||
How to use a configuration file to set iSCSI configuration options:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
cat >iscsi.conf <<EOF
|
||||
[iscsi]
|
||||
user = "me"
|
||||
password = "my password"
|
||||
initiator-name = "iqn.qemu.test:my-initiator"
|
||||
header-digest = "CRC32C"
|
||||
EOF
|
||||
|
||||
|qemu_system| -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \\
|
||||
-readconfig iscsi.conf
|
||||
|
||||
How to set up a simple iSCSI target on loopback and access it via QEMU:
|
||||
this example shows how to set up an iSCSI target with one CDROM and one DISK
|
||||
using the Linux STGT software target. This target is available on Red Hat based
|
||||
systems as the package 'scsi-target-utils'.
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
tgtd --iscsi portal=127.0.0.1:3260
|
||||
tgtadm --lld iscsi --op new --mode target --tid 1 -T iqn.qemu.test
|
||||
tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 1 \\
|
||||
-b /IMAGES/disk.img --device-type=disk
|
||||
tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 2 \\
|
||||
-b /IMAGES/cd.iso --device-type=cd
|
||||
tgtadm --lld iscsi --op bind --mode target --tid 1 -I ALL
|
||||
|
||||
|qemu_system| -iscsi initiator-name=iqn.qemu.test:my-initiator \\
|
||||
-boot d -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \\
|
||||
-cdrom iscsi://127.0.0.1/iqn.qemu.test/2
|
||||
|
||||
GlusterFS disk images
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
GlusterFS is a user space distributed file system.
|
||||
|
||||
You can boot from the GlusterFS disk image with the command:
|
||||
|
||||
URI:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -drive file=gluster[+TYPE]://[HOST}[:PORT]]/VOLUME/PATH
|
||||
[?socket=...][,file.debug=9][,file.logfile=...]
|
||||
|
||||
JSON:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| 'json:{"driver":"qcow2",
|
||||
"file":{"driver":"gluster",
|
||||
"volume":"testvol","path":"a.img","debug":9,"logfile":"...",
|
||||
"server":[{"type":"tcp","host":"...","port":"..."},
|
||||
{"type":"unix","socket":"..."}]}}'
|
||||
|
||||
*gluster* is the protocol.
|
||||
|
||||
*TYPE* specifies the transport type used to connect to gluster
|
||||
management daemon (glusterd). Valid transport types are
|
||||
tcp and unix. In the URI form, if a transport type isn't specified,
|
||||
then tcp type is assumed.
|
||||
|
||||
*HOST* specifies the server where the volume file specification for
|
||||
the given volume resides. This can be either a hostname or an ipv4 address.
|
||||
If transport type is unix, then *HOST* field should not be specified.
|
||||
Instead *socket* field needs to be populated with the path to unix domain
|
||||
socket.
|
||||
|
||||
*PORT* is the port number on which glusterd is listening. This is optional
|
||||
and if not specified, it defaults to port 24007. If the transport type is unix,
|
||||
then *PORT* should not be specified.
|
||||
|
||||
*VOLUME* is the name of the gluster volume which contains the disk image.
|
||||
|
||||
*PATH* is the path to the actual disk image that resides on gluster volume.
|
||||
|
||||
*debug* is the logging level of the gluster protocol driver. Debug levels
|
||||
are 0-9, with 9 being the most verbose, and 0 representing no debugging output.
|
||||
The default level is 4. The current logging levels defined in the gluster source
|
||||
are 0 - None, 1 - Emergency, 2 - Alert, 3 - Critical, 4 - Error, 5 - Warning,
|
||||
6 - Notice, 7 - Info, 8 - Debug, 9 - Trace
|
||||
|
||||
*logfile* is a commandline option to mention log file path which helps in
|
||||
logging to the specified file and also help in persisting the gfapi logs. The
|
||||
default is stderr.
|
||||
|
||||
You can create a GlusterFS disk image with the command:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
qemu-img create gluster://HOST/VOLUME/PATH SIZE
|
||||
|
||||
Examples
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -drive file=gluster://1.2.3.4/testvol/a.img
|
||||
|qemu_system| -drive file=gluster+tcp://1.2.3.4/testvol/a.img
|
||||
|qemu_system| -drive file=gluster+tcp://1.2.3.4:24007/testvol/dir/a.img
|
||||
|qemu_system| -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]/testvol/dir/a.img
|
||||
|qemu_system| -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]:24007/testvol/dir/a.img
|
||||
|qemu_system| -drive file=gluster+tcp://server.domain.com:24007/testvol/dir/a.img
|
||||
|qemu_system| -drive file=gluster+unix:///testvol/dir/a.img?socket=/tmp/glusterd.socket
|
||||
|qemu_system| -drive file=gluster+rdma://1.2.3.4:24007/testvol/a.img
|
||||
|qemu_system| -drive file=gluster://1.2.3.4/testvol/a.img,file.debug=9,file.logfile=/var/log/qemu-gluster.log
|
||||
|qemu_system| 'json:{"driver":"qcow2",
|
||||
"file":{"driver":"gluster",
|
||||
"volume":"testvol","path":"a.img",
|
||||
"debug":9,"logfile":"/var/log/qemu-gluster.log",
|
||||
"server":[{"type":"tcp","host":"1.2.3.4","port":24007},
|
||||
{"type":"unix","socket":"/var/run/glusterd.socket"}]}}'
|
||||
|qemu_system| -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
|
||||
file.debug=9,file.logfile=/var/log/qemu-gluster.log,
|
||||
file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
|
||||
file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
|
||||
|
||||
Secure Shell (ssh) disk images
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
You can access disk images located on a remote ssh server
|
||||
by using the ssh protocol:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -drive file=ssh://[USER@]SERVER[:PORT]/PATH[?host_key_check=HOST_KEY_CHECK]
|
||||
|
||||
Alternative syntax using properties:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -drive file.driver=ssh[,file.user=USER],file.host=SERVER[,file.port=PORT],file.path=PATH[,file.host_key_check=HOST_KEY_CHECK]
|
||||
|
||||
*ssh* is the protocol.
|
||||
|
||||
*USER* is the remote user. If not specified, then the local
|
||||
username is tried.
|
||||
|
||||
*SERVER* specifies the remote ssh server. Any ssh server can be
|
||||
used, but it must implement the sftp-server protocol. Most Unix/Linux
|
||||
systems should work without requiring any extra configuration.
|
||||
|
||||
*PORT* is the port number on which sshd is listening. By default
|
||||
the standard ssh port (22) is used.
|
||||
|
||||
*PATH* is the path to the disk image.
|
||||
|
||||
The optional *HOST_KEY_CHECK* parameter controls how the remote
|
||||
host's key is checked. The default is ``yes`` which means to use
|
||||
the local ``.ssh/known_hosts`` file. Setting this to ``no``
|
||||
turns off known-hosts checking. Or you can check that the host key
|
||||
matches a specific fingerprint:
|
||||
``host_key_check=md5:78:45:8e:14:57:4f:d5:45:83:0a:0e:f3:49:82:c9:c8``
|
||||
(``sha1:`` can also be used as a prefix, but note that OpenSSH
|
||||
tools only use MD5 to print fingerprints).
|
||||
|
||||
Currently authentication must be done using ssh-agent. Other
|
||||
authentication methods may be supported in future.
|
||||
|
||||
Note: Many ssh servers do not support an ``fsync``-style operation.
|
||||
The ssh driver cannot guarantee that disk flush requests are
|
||||
obeyed, and this causes a risk of disk corruption if the remote
|
||||
server or network goes down during writes. The driver will
|
||||
print a warning when ``fsync`` is not supported:
|
||||
|
||||
::
|
||||
|
||||
warning: ssh server ssh.example.com:22 does not support fsync
|
||||
|
||||
With sufficiently new versions of libssh and OpenSSH, ``fsync`` is
|
||||
supported.
|
||||
|
||||
NVMe disk images
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
NVM Express (NVMe) storage controllers can be accessed directly by a userspace
|
||||
driver in QEMU. This bypasses the host kernel file system and block layers
|
||||
while retaining QEMU block layer functionalities, such as block jobs, I/O
|
||||
throttling, image formats, etc. Disk I/O performance is typically higher than
|
||||
with ``-drive file=/dev/sda`` using either thread pool or linux-aio.
|
||||
|
||||
The controller will be exclusively used by the QEMU process once started. To be
|
||||
able to share storage between multiple VMs and other applications on the host,
|
||||
please use the file based protocols.
|
||||
|
||||
Before starting QEMU, bind the host NVMe controller to the host vfio-pci
|
||||
driver. For example:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
# modprobe vfio-pci
|
||||
# lspci -n -s 0000:06:0d.0
|
||||
06:0d.0 0401: 1102:0002 (rev 08)
|
||||
# echo 0000:06:0d.0 > /sys/bus/pci/devices/0000:06:0d.0/driver/unbind
|
||||
# echo 1102 0002 > /sys/bus/pci/drivers/vfio-pci/new_id
|
||||
|
||||
# |qemu_system| -drive file=nvme://HOST:BUS:SLOT.FUNC/NAMESPACE
|
||||
|
||||
Alternative syntax using properties:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -drive file.driver=nvme,file.device=HOST:BUS:SLOT.FUNC,file.namespace=NAMESPACE
|
||||
|
||||
*HOST*:*BUS*:*SLOT*.\ *FUNC* is the NVMe controller's PCI device
|
||||
address on the host.
|
||||
|
||||
*NAMESPACE* is the NVMe namespace number, starting from 1.
|
||||
|
||||
Disk image file locking
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
By default, QEMU tries to protect image files from unexpected concurrent
|
||||
access, as long as it's supported by the block protocol driver and host
|
||||
operating system. If multiple QEMU processes (including QEMU emulators and
|
||||
utilities) try to open the same image with conflicting accessing modes, all but
|
||||
the first one will get an error.
|
||||
|
||||
This feature is currently supported by the file protocol on Linux with the Open
|
||||
File Descriptor (OFD) locking API, and can be configured to fall back to POSIX
|
||||
locking if the POSIX host doesn't support Linux OFD locking.
|
||||
|
||||
To explicitly enable image locking, specify "locking=on" in the file protocol
|
||||
driver options. If OFD locking is not possible, a warning will be printed and
|
||||
the POSIX locking API will be used. In this case there is a risk that the lock
|
||||
will get silently lost when doing hot plugging and block jobs, due to the
|
||||
shortcomings of the POSIX locking API.
|
||||
|
||||
QEMU transparently handles lock handover during shared storage migration. For
|
||||
shared virtual disk images between multiple VMs, the "share-rw" device option
|
||||
should be used.
|
||||
|
||||
By default, the guest has exclusive write access to its disk image. If the
|
||||
guest can safely share the disk image with other writers the
|
||||
``-device ...,share-rw=on`` parameter can be used. This is only safe if
|
||||
the guest is running software, such as a cluster file system, that
|
||||
coordinates disk accesses to avoid corruption.
|
||||
|
||||
Note that share-rw=on only declares the guest's ability to share the disk.
|
||||
Some QEMU features, such as image file formats, require exclusive write access
|
||||
to the disk image and this is unaffected by the share-rw=on option.
|
||||
|
||||
Alternatively, locking can be fully disabled by "locking=off" block device
|
||||
option. In the command line, the option is usually in the form of
|
||||
"file.locking=off" as the protocol driver is normally placed as a "file" child
|
||||
under a format driver. For example:
|
||||
|
||||
::
|
||||
|
||||
-blockdev driver=qcow2,file.filename=/path/to/image,file.locking=off,file.driver=file
|
||||
|
||||
To check if image locking is active, check the output of the "lslocks" command
|
||||
on host and see if there are locks held by the QEMU process on the image file.
|
||||
More than one byte could be locked by the QEMU instance, each byte of which
|
||||
reflects a particular permission that is acquired or protected by the running
|
||||
block driver.
|
20
docs/system/qemu-cpu-models.rst
Normal file
20
docs/system/qemu-cpu-models.rst
Normal file
|
@ -0,0 +1,20 @@
|
|||
:orphan:
|
||||
|
||||
QEMU / KVM CPU model configuration
|
||||
==================================
|
||||
|
||||
Synopsis
|
||||
''''''''
|
||||
|
||||
QEMU CPU Modelling Infrastructure manual
|
||||
|
||||
Description
|
||||
'''''''''''
|
||||
|
||||
.. include:: cpu-models-x86.rst.inc
|
||||
.. include:: cpu-models-mips.rst.inc
|
||||
|
||||
See also
|
||||
''''''''
|
||||
|
||||
The HTML documentation of QEMU for more precise information and Linux user mode emulator invocation.
|
45
docs/system/qemu-manpage.rst
Normal file
45
docs/system/qemu-manpage.rst
Normal file
|
@ -0,0 +1,45 @@
|
|||
:orphan:
|
||||
|
||||
..
|
||||
This file is the skeleton for the qemu.1 manpage. It mostly
|
||||
should simply include the .rst.inc files corresponding to the
|
||||
parts of the documentation that go in the manpage as well as the
|
||||
HTML manual.
|
||||
|
||||
Title
|
||||
=====
|
||||
|
||||
Synopsis
|
||||
--------
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| [options] [disk_image]
|
||||
|
||||
Description
|
||||
-----------
|
||||
|
||||
.. include:: target-i386-desc.rst.inc
|
||||
|
||||
Options
|
||||
-------
|
||||
|
||||
disk_image is a raw hard disk image for IDE hard disk 0. Some targets do
|
||||
not need a disk image.
|
||||
|
||||
.. hxtool-doc:: qemu-options.hx
|
||||
|
||||
.. include:: keys.rst.inc
|
||||
|
||||
.. include:: mux-chardev.rst.inc
|
||||
|
||||
Notes
|
||||
-----
|
||||
|
||||
.. include:: device-url-syntax.rst.inc
|
||||
|
||||
See also
|
||||
--------
|
||||
|
||||
The HTML documentation of QEMU for more precise information and Linux
|
||||
user mode emulator invocation.
|
13
docs/system/quickstart.rst
Normal file
13
docs/system/quickstart.rst
Normal file
|
@ -0,0 +1,13 @@
|
|||
.. _pcsys_005fquickstart:
|
||||
|
||||
Quick Start
|
||||
-----------
|
||||
|
||||
Download and uncompress a PC hard disk image with Linux installed (e.g.
|
||||
``linux.img``) and type:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| linux.img
|
||||
|
||||
Linux should boot and give you a prompt.
|
|
@ -1,19 +1,22 @@
|
|||
@node Security
|
||||
@chapter Security
|
||||
Security
|
||||
========
|
||||
|
||||
@section Overview
|
||||
Overview
|
||||
--------
|
||||
|
||||
This chapter explains the security requirements that QEMU is designed to meet
|
||||
and principles for securely deploying QEMU.
|
||||
|
||||
@section Security Requirements
|
||||
Security Requirements
|
||||
---------------------
|
||||
|
||||
QEMU supports many different use cases, some of which have stricter security
|
||||
requirements than others. The community has agreed on the overall security
|
||||
requirements that users may depend on. These requirements define what is
|
||||
considered supported from a security perspective.
|
||||
|
||||
@subsection Virtualization Use Case
|
||||
Virtualization Use Case
|
||||
'''''''''''''''''''''''
|
||||
|
||||
The virtualization use case covers cloud and virtual private server (VPS)
|
||||
hosting, as well as traditional data center and desktop virtualization. These
|
||||
|
@ -23,18 +26,17 @@ safely on the physical CPU at close-to-native speed.
|
|||
The following entities are untrusted, meaning that they may be buggy or
|
||||
malicious:
|
||||
|
||||
@itemize
|
||||
@item Guest
|
||||
@item User-facing interfaces (e.g. VNC, SPICE, WebSocket)
|
||||
@item Network protocols (e.g. NBD, live migration)
|
||||
@item User-supplied files (e.g. disk images, kernels, device trees)
|
||||
@item Passthrough devices (e.g. PCI, USB)
|
||||
@end itemize
|
||||
- Guest
|
||||
- User-facing interfaces (e.g. VNC, SPICE, WebSocket)
|
||||
- Network protocols (e.g. NBD, live migration)
|
||||
- User-supplied files (e.g. disk images, kernels, device trees)
|
||||
- Passthrough devices (e.g. PCI, USB)
|
||||
|
||||
Bugs affecting these entities are evaluated on whether they can cause damage in
|
||||
real-world use cases and treated as security bugs if this is the case.
|
||||
|
||||
@subsection Non-virtualization Use Case
|
||||
Non-virtualization Use Case
|
||||
'''''''''''''''''''''''''''
|
||||
|
||||
The non-virtualization use case covers emulation using the Tiny Code Generator
|
||||
(TCG). In principle the TCG and device emulation code used in conjunction with
|
||||
|
@ -47,12 +49,14 @@ Bugs affecting the non-virtualization use case are not considered security
|
|||
bugs at this time. Users with non-virtualization use cases must not rely on
|
||||
QEMU to provide guest isolation or any security guarantees.
|
||||
|
||||
@section Architecture
|
||||
Architecture
|
||||
------------
|
||||
|
||||
This section describes the design principles that ensure the security
|
||||
requirements are met.
|
||||
|
||||
@subsection Guest Isolation
|
||||
Guest Isolation
|
||||
'''''''''''''''
|
||||
|
||||
Guest isolation is the confinement of guest code to the virtual machine. When
|
||||
guest code gains control of execution on the host this is called escaping the
|
||||
|
@ -71,7 +75,8 @@ malicious guest must not gain control of other guests or access their data.
|
|||
Disk image files and network traffic must be protected from other guests unless
|
||||
explicitly shared between them by the user.
|
||||
|
||||
@subsection Principle of Least Privilege
|
||||
Principle of Least Privilege
|
||||
''''''''''''''''''''''''''''
|
||||
|
||||
The principle of least privilege states that each component only has access to
|
||||
the privileges necessary for its function. In the case of QEMU this means that
|
||||
|
@ -84,7 +89,7 @@ the guest.
|
|||
|
||||
Following the principle of least privilege immediately fulfills guest isolation
|
||||
requirements. For example, guest A only has access to its own disk image file
|
||||
@code{a.img} and not guest B's disk image file @code{b.img}.
|
||||
``a.img`` and not guest B's disk image file ``b.img``.
|
||||
|
||||
In reality certain resources are inaccessible to the guest but must be
|
||||
available to QEMU to perform its function. For example, host system calls are
|
||||
|
@ -95,7 +100,8 @@ New features must be designed to follow the principle of least privilege.
|
|||
Should this not be possible for technical reasons, the security risk must be
|
||||
clearly documented so users are aware of the trade-off of enabling the feature.
|
||||
|
||||
@subsection Isolation mechanisms
|
||||
Isolation mechanisms
|
||||
''''''''''''''''''''
|
||||
|
||||
Several isolation mechanisms are available to realize this architecture of
|
||||
guest isolation and the principle of least privilege. With the exception of
|
||||
|
@ -105,46 +111,46 @@ described briefly for Linux here.
|
|||
|
||||
The fundamental isolation mechanism is that QEMU processes must run as
|
||||
unprivileged users. Sometimes it seems more convenient to launch QEMU as
|
||||
root to give it access to host devices (e.g. @code{/dev/net/tun}) but this poses a
|
||||
root to give it access to host devices (e.g. ``/dev/net/tun``) but this poses a
|
||||
huge security risk. File descriptor passing can be used to give an otherwise
|
||||
unprivileged QEMU process access to host devices without running QEMU as root.
|
||||
It is also possible to launch QEMU as a non-root user and configure UNIX groups
|
||||
for access to @code{/dev/kvm}, @code{/dev/net/tun}, and other device nodes.
|
||||
for access to ``/dev/kvm``, ``/dev/net/tun``, and other device nodes.
|
||||
Some Linux distros already ship with UNIX groups for these devices by default.
|
||||
|
||||
@itemize
|
||||
@item SELinux and AppArmor make it possible to confine processes beyond the
|
||||
traditional UNIX process and file permissions model. They restrict the QEMU
|
||||
process from accessing processes and files on the host system that are not
|
||||
needed by QEMU.
|
||||
- SELinux and AppArmor make it possible to confine processes beyond the
|
||||
traditional UNIX process and file permissions model. They restrict the QEMU
|
||||
process from accessing processes and files on the host system that are not
|
||||
needed by QEMU.
|
||||
|
||||
@item Resource limits and cgroup controllers provide throughput and utilization
|
||||
limits on key resources such as CPU time, memory, and I/O bandwidth.
|
||||
- Resource limits and cgroup controllers provide throughput and utilization
|
||||
limits on key resources such as CPU time, memory, and I/O bandwidth.
|
||||
|
||||
@item Linux namespaces can be used to make process, file system, and other system
|
||||
resources unavailable to QEMU. A namespaced QEMU process is restricted to only
|
||||
those resources that were granted to it.
|
||||
- Linux namespaces can be used to make process, file system, and other system
|
||||
resources unavailable to QEMU. A namespaced QEMU process is restricted to only
|
||||
those resources that were granted to it.
|
||||
|
||||
@item Linux seccomp is available via the QEMU @option{--sandbox} option. It disables
|
||||
system calls that are not needed by QEMU, thereby reducing the host kernel
|
||||
attack surface.
|
||||
@end itemize
|
||||
- Linux seccomp is available via the QEMU ``--sandbox`` option. It disables
|
||||
system calls that are not needed by QEMU, thereby reducing the host kernel
|
||||
attack surface.
|
||||
|
||||
@section Sensitive configurations
|
||||
Sensitive configurations
|
||||
------------------------
|
||||
|
||||
There are aspects of QEMU that can have security implications which users &
|
||||
management applications must be aware of.
|
||||
|
||||
@subsection Monitor console (QMP and HMP)
|
||||
Monitor console (QMP and HMP)
|
||||
'''''''''''''''''''''''''''''
|
||||
|
||||
The monitor console (whether used with QMP or HMP) provides an interface
|
||||
to dynamically control many aspects of QEMU's runtime operation. Many of the
|
||||
commands exposed will instruct QEMU to access content on the host file system
|
||||
and/or trigger spawning of external processes.
|
||||
|
||||
For example, the @code{migrate} command allows for the spawning of arbitrary
|
||||
For example, the ``migrate`` command allows for the spawning of arbitrary
|
||||
processes for the purpose of tunnelling the migration data stream. The
|
||||
@code{blockdev-add} command instructs QEMU to open arbitrary files, exposing
|
||||
``blockdev-add`` command instructs QEMU to open arbitrary files, exposing
|
||||
their content to the guest as a virtual disk.
|
||||
|
||||
Unless QEMU is otherwise confined using technologies such as SELinux, AppArmor,
|
217
docs/system/target-arm.rst
Normal file
217
docs/system/target-arm.rst
Normal file
|
@ -0,0 +1,217 @@
|
|||
.. _ARM-System-emulator:
|
||||
|
||||
ARM System emulator
|
||||
-------------------
|
||||
|
||||
Use the executable ``qemu-system-arm`` to simulate a ARM machine. The
|
||||
ARM Integrator/CP board is emulated with the following devices:
|
||||
|
||||
- ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
|
||||
|
||||
- Two PL011 UARTs
|
||||
|
||||
- SMC 91c111 Ethernet adapter
|
||||
|
||||
- PL110 LCD controller
|
||||
|
||||
- PL050 KMI with PS/2 keyboard and mouse.
|
||||
|
||||
- PL181 MultiMedia Card Interface with SD card.
|
||||
|
||||
The ARM Versatile baseboard is emulated with the following devices:
|
||||
|
||||
- ARM926E, ARM1136 or Cortex-A8 CPU
|
||||
|
||||
- PL190 Vectored Interrupt Controller
|
||||
|
||||
- Four PL011 UARTs
|
||||
|
||||
- SMC 91c111 Ethernet adapter
|
||||
|
||||
- PL110 LCD controller
|
||||
|
||||
- PL050 KMI with PS/2 keyboard and mouse.
|
||||
|
||||
- PCI host bridge. Note the emulated PCI bridge only provides access
|
||||
to PCI memory space. It does not provide access to PCI IO space. This
|
||||
means some devices (eg. ne2k_pci NIC) are not usable, and others (eg.
|
||||
rtl8139 NIC) are only usable when the guest drivers use the memory
|
||||
mapped control registers.
|
||||
|
||||
- PCI OHCI USB controller.
|
||||
|
||||
- LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM
|
||||
devices.
|
||||
|
||||
- PL181 MultiMedia Card Interface with SD card.
|
||||
|
||||
Several variants of the ARM RealView baseboard are emulated, including
|
||||
the EB, PB-A8 and PBX-A9. Due to interactions with the bootloader, only
|
||||
certain Linux kernel configurations work out of the box on these boards.
|
||||
|
||||
Kernels for the PB-A8 board should have CONFIG_REALVIEW_HIGH_PHYS_OFFSET
|
||||
enabled in the kernel, and expect 512M RAM. Kernels for The PBX-A9 board
|
||||
should have CONFIG_SPARSEMEM enabled, CONFIG_REALVIEW_HIGH_PHYS_OFFSET
|
||||
disabled and expect 1024M RAM.
|
||||
|
||||
The following devices are emulated:
|
||||
|
||||
- ARM926E, ARM1136, ARM11MPCore, Cortex-A8 or Cortex-A9 MPCore CPU
|
||||
|
||||
- ARM AMBA Generic/Distributed Interrupt Controller
|
||||
|
||||
- Four PL011 UARTs
|
||||
|
||||
- SMC 91c111 or SMSC LAN9118 Ethernet adapter
|
||||
|
||||
- PL110 LCD controller
|
||||
|
||||
- PL050 KMI with PS/2 keyboard and mouse
|
||||
|
||||
- PCI host bridge
|
||||
|
||||
- PCI OHCI USB controller
|
||||
|
||||
- LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM
|
||||
devices
|
||||
|
||||
- PL181 MultiMedia Card Interface with SD card.
|
||||
|
||||
The XScale-based clamshell PDA models (\"Spitz\", \"Akita\", \"Borzoi\"
|
||||
and \"Terrier\") emulation includes the following peripherals:
|
||||
|
||||
- Intel PXA270 System-on-chip (ARM V5TE core)
|
||||
|
||||
- NAND Flash memory
|
||||
|
||||
- IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in \"Akita\"
|
||||
|
||||
- On-chip OHCI USB controller
|
||||
|
||||
- On-chip LCD controller
|
||||
|
||||
- On-chip Real Time Clock
|
||||
|
||||
- TI ADS7846 touchscreen controller on SSP bus
|
||||
|
||||
- Maxim MAX1111 analog-digital converter on |I2C| bus
|
||||
|
||||
- GPIO-connected keyboard controller and LEDs
|
||||
|
||||
- Secure Digital card connected to PXA MMC/SD host
|
||||
|
||||
- Three on-chip UARTs
|
||||
|
||||
- WM8750 audio CODEC on |I2C| and |I2S| busses
|
||||
|
||||
The Palm Tungsten|E PDA (codename \"Cheetah\") emulation includes the
|
||||
following elements:
|
||||
|
||||
- Texas Instruments OMAP310 System-on-chip (ARM 925T core)
|
||||
|
||||
- ROM and RAM memories (ROM firmware image can be loaded with
|
||||
-option-rom)
|
||||
|
||||
- On-chip LCD controller
|
||||
|
||||
- On-chip Real Time Clock
|
||||
|
||||
- TI TSC2102i touchscreen controller / analog-digital converter /
|
||||
Audio CODEC, connected through MicroWire and |I2S| busses
|
||||
|
||||
- GPIO-connected matrix keypad
|
||||
|
||||
- Secure Digital card connected to OMAP MMC/SD host
|
||||
|
||||
- Three on-chip UARTs
|
||||
|
||||
Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 /
|
||||
48) emulation supports the following elements:
|
||||
|
||||
- Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)
|
||||
|
||||
- RAM and non-volatile OneNAND Flash memories
|
||||
|
||||
- Display connected to EPSON remote framebuffer chip and OMAP on-chip
|
||||
display controller and a LS041y3 MIPI DBI-C controller
|
||||
|
||||
- TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen
|
||||
controllers driven through SPI bus
|
||||
|
||||
- National Semiconductor LM8323-controlled qwerty keyboard driven
|
||||
through |I2C| bus
|
||||
|
||||
- Secure Digital card connected to OMAP MMC/SD host
|
||||
|
||||
- Three OMAP on-chip UARTs and on-chip STI debugging console
|
||||
|
||||
- Mentor Graphics \"Inventra\" dual-role USB controller embedded in a
|
||||
TI TUSB6010 chip - only USB host mode is supported
|
||||
|
||||
- TI TMP105 temperature sensor driven through |I2C| bus
|
||||
|
||||
- TI TWL92230C power management companion with an RTC on
|
||||
|I2C| bus
|
||||
|
||||
- Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
|
||||
through CBUS
|
||||
|
||||
The Luminary Micro Stellaris LM3S811EVB emulation includes the following
|
||||
devices:
|
||||
|
||||
- Cortex-M3 CPU core.
|
||||
|
||||
- 64k Flash and 8k SRAM.
|
||||
|
||||
- Timers, UARTs, ADC and |I2C| interface.
|
||||
|
||||
- OSRAM Pictiva 96x16 OLED with SSD0303 controller on
|
||||
|I2C| bus.
|
||||
|
||||
The Luminary Micro Stellaris LM3S6965EVB emulation includes the
|
||||
following devices:
|
||||
|
||||
- Cortex-M3 CPU core.
|
||||
|
||||
- 256k Flash and 64k SRAM.
|
||||
|
||||
- Timers, UARTs, ADC, |I2C| and SSI interfaces.
|
||||
|
||||
- OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via
|
||||
SSI.
|
||||
|
||||
The Freecom MusicPal internet radio emulation includes the following
|
||||
elements:
|
||||
|
||||
- Marvell MV88W8618 ARM core.
|
||||
|
||||
- 32 MB RAM, 256 KB SRAM, 8 MB flash.
|
||||
|
||||
- Up to 2 16550 UARTs
|
||||
|
||||
- MV88W8xx8 Ethernet controller
|
||||
|
||||
- MV88W8618 audio controller, WM8750 CODEC and mixer
|
||||
|
||||
- 128x64 display with brightness control
|
||||
|
||||
- 2 buttons, 2 navigation wheels with button function
|
||||
|
||||
The Siemens SX1 models v1 and v2 (default) basic emulation. The
|
||||
emulation includes the following elements:
|
||||
|
||||
- Texas Instruments OMAP310 System-on-chip (ARM 925T core)
|
||||
|
||||
- ROM and RAM memories (ROM firmware image can be loaded with
|
||||
-pflash) V1 1 Flash of 16MB and 1 Flash of 8MB V2 1 Flash of 32MB
|
||||
|
||||
- On-chip LCD controller
|
||||
|
||||
- On-chip Real Time Clock
|
||||
|
||||
- Secure Digital card connected to OMAP MMC/SD host
|
||||
|
||||
- Three on-chip UARTs
|
||||
|
||||
A Linux 2.6 test image is available on the QEMU web site. More
|
||||
information is available in the QEMU mailing-list archive.
|
62
docs/system/target-i386-desc.rst.inc
Normal file
62
docs/system/target-i386-desc.rst.inc
Normal file
|
@ -0,0 +1,62 @@
|
|||
The QEMU PC System emulator simulates the following peripherals:
|
||||
|
||||
- i440FX host PCI bridge and PIIX3 PCI to ISA bridge
|
||||
|
||||
- Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
|
||||
extensions (hardware level, including all non standard modes).
|
||||
|
||||
- PS/2 mouse and keyboard
|
||||
|
||||
- 2 PCI IDE interfaces with hard disk and CD-ROM support
|
||||
|
||||
- Floppy disk
|
||||
|
||||
- PCI and ISA network adapters
|
||||
|
||||
- Serial ports
|
||||
|
||||
- IPMI BMC, either and internal or external one
|
||||
|
||||
- Creative SoundBlaster 16 sound card
|
||||
|
||||
- ENSONIQ AudioPCI ES1370 sound card
|
||||
|
||||
- Intel 82801AA AC97 Audio compatible sound card
|
||||
|
||||
- Intel HD Audio Controller and HDA codec
|
||||
|
||||
- Adlib (OPL2) - Yamaha YM3812 compatible chip
|
||||
|
||||
- Gravis Ultrasound GF1 sound card
|
||||
|
||||
- CS4231A compatible sound card
|
||||
|
||||
- PCI UHCI, OHCI, EHCI or XHCI USB controller and a virtual USB-1.1
|
||||
hub.
|
||||
|
||||
SMP is supported with up to 255 CPUs.
|
||||
|
||||
QEMU uses the PC BIOS from the Seabios project and the Plex86/Bochs LGPL
|
||||
VGA BIOS.
|
||||
|
||||
QEMU uses YM3812 emulation by Tatsuyuki Satoh.
|
||||
|
||||
QEMU uses GUS emulation (GUSEMU32 http://www.deinmeister.de/gusemu/) by
|
||||
Tibor \"TS\" Schütz.
|
||||
|
||||
Note that, by default, GUS shares IRQ(7) with parallel ports and so QEMU
|
||||
must be told to not have parallel ports to have working GUS.
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system_x86| dos.img -soundhw gus -parallel none
|
||||
|
||||
Alternatively:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system_x86| dos.img -device gus,irq=5
|
||||
|
||||
Or some other unclaimed IRQ.
|
||||
|
||||
CS4231A is the chip used in Windows Sound System and GUSMAX products
|
23
docs/system/target-i386.rst
Normal file
23
docs/system/target-i386.rst
Normal file
|
@ -0,0 +1,23 @@
|
|||
.. _QEMU-PC-System-emulator:
|
||||
|
||||
x86 (PC) System emulator
|
||||
------------------------
|
||||
|
||||
.. _pcsys_005fdevices:
|
||||
|
||||
Peripherals
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. include:: target-i386-desc.rst.inc
|
||||
|
||||
.. include:: cpu-models-x86.rst.inc
|
||||
|
||||
.. _pcsys_005freq:
|
||||
|
||||
OS requirements
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
On x86_64 hosts, the default set of CPU features enabled by the KVM
|
||||
accelerator require the host to be running Linux v4.5 or newer. Red Hat
|
||||
Enterprise Linux 7 is also supported, since the required
|
||||
functionality was backported.
|
21
docs/system/target-m68k.rst
Normal file
21
docs/system/target-m68k.rst
Normal file
|
@ -0,0 +1,21 @@
|
|||
.. _ColdFire-System-emulator:
|
||||
|
||||
ColdFire System emulator
|
||||
------------------------
|
||||
|
||||
Use the executable ``qemu-system-m68k`` to simulate a ColdFire machine.
|
||||
The emulator is able to boot a uClinux kernel.
|
||||
|
||||
The M5208EVB emulation includes the following devices:
|
||||
|
||||
- MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).
|
||||
|
||||
- Three Two on-chip UARTs.
|
||||
|
||||
- Fast Ethernet Controller (FEC)
|
||||
|
||||
The AN5206 emulation includes the following devices:
|
||||
|
||||
- MCF5206 ColdFire V2 Microprocessor.
|
||||
|
||||
- Two on-chip UARTs.
|
120
docs/system/target-mips.rst
Normal file
120
docs/system/target-mips.rst
Normal file
|
@ -0,0 +1,120 @@
|
|||
.. _MIPS-System-emulator:
|
||||
|
||||
MIPS System emulator
|
||||
--------------------
|
||||
|
||||
Four executables cover simulation of 32 and 64-bit MIPS systems in both
|
||||
endian options, ``qemu-system-mips``, ``qemu-system-mipsel``
|
||||
``qemu-system-mips64`` and ``qemu-system-mips64el``. Five different
|
||||
machine types are emulated:
|
||||
|
||||
- A generic ISA PC-like machine \"mips\"
|
||||
|
||||
- The MIPS Malta prototype board \"malta\"
|
||||
|
||||
- An ACER Pica \"pica61\". This machine needs the 64-bit emulator.
|
||||
|
||||
- MIPS emulator pseudo board \"mipssim\"
|
||||
|
||||
- A MIPS Magnum R4000 machine \"magnum\". This machine needs the
|
||||
64-bit emulator.
|
||||
|
||||
The generic emulation is supported by Debian 'Etch' and is able to
|
||||
install Debian into a virtual disk image. The following devices are
|
||||
emulated:
|
||||
|
||||
- A range of MIPS CPUs, default is the 24Kf
|
||||
|
||||
- PC style serial port
|
||||
|
||||
- PC style IDE disk
|
||||
|
||||
- NE2000 network card
|
||||
|
||||
The Malta emulation supports the following devices:
|
||||
|
||||
- Core board with MIPS 24Kf CPU and Galileo system controller
|
||||
|
||||
- PIIX4 PCI/USB/SMbus controller
|
||||
|
||||
- The Multi-I/O chip's serial device
|
||||
|
||||
- PCI network cards (PCnet32 and others)
|
||||
|
||||
- Malta FPGA serial device
|
||||
|
||||
- Cirrus (default) or any other PCI VGA graphics card
|
||||
|
||||
The Boston board emulation supports the following devices:
|
||||
|
||||
- Xilinx FPGA, which includes a PCIe root port and an UART
|
||||
|
||||
- Intel EG20T PCH connects the I/O peripherals, but only the SATA bus
|
||||
is emulated
|
||||
|
||||
The ACER Pica emulation supports:
|
||||
|
||||
- MIPS R4000 CPU
|
||||
|
||||
- PC-style IRQ and DMA controllers
|
||||
|
||||
- PC Keyboard
|
||||
|
||||
- IDE controller
|
||||
|
||||
The MIPS Magnum R4000 emulation supports:
|
||||
|
||||
- MIPS R4000 CPU
|
||||
|
||||
- PC-style IRQ controller
|
||||
|
||||
- PC Keyboard
|
||||
|
||||
- SCSI controller
|
||||
|
||||
- G364 framebuffer
|
||||
|
||||
The Fulong 2E emulation supports:
|
||||
|
||||
- Loongson 2E CPU
|
||||
|
||||
- Bonito64 system controller as North Bridge
|
||||
|
||||
- VT82C686 chipset as South Bridge
|
||||
|
||||
- RTL8139D as a network card chipset
|
||||
|
||||
The mipssim pseudo board emulation provides an environment similar to
|
||||
what the proprietary MIPS emulator uses for running Linux. It supports:
|
||||
|
||||
- A range of MIPS CPUs, default is the 24Kf
|
||||
|
||||
- PC style serial port
|
||||
|
||||
- MIPSnet network emulation
|
||||
|
||||
.. include:: cpu-models-mips.rst.inc
|
||||
|
||||
.. _nanoMIPS-System-emulator:
|
||||
|
||||
nanoMIPS System emulator
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Executable ``qemu-system-mipsel`` also covers simulation of 32-bit
|
||||
nanoMIPS system in little endian mode:
|
||||
|
||||
- nanoMIPS I7200 CPU
|
||||
|
||||
Example of ``qemu-system-mipsel`` usage for nanoMIPS is shown below:
|
||||
|
||||
Download ``<disk_image_file>`` from
|
||||
https://mipsdistros.mips.com/LinuxDistro/nanomips/buildroot/index.html.
|
||||
|
||||
Download ``<kernel_image_file>`` from
|
||||
https://mipsdistros.mips.com/LinuxDistro/nanomips/kernels/v4.15.18-432-gb2eb9a8b07a1-20180627102142/index.html.
|
||||
|
||||
Start system emulation of Malta board with nanoMIPS I7200 CPU::
|
||||
|
||||
qemu-system-mipsel -cpu I7200 -kernel <kernel_image_file> \
|
||||
-M malta -serial stdio -m <memory_size> -hda <disk_image_file> \
|
||||
-append "mem=256m@0x0 rw console=ttyS0 vga=cirrus vesa=0x111 root=/dev/sda"
|
47
docs/system/target-ppc.rst
Normal file
47
docs/system/target-ppc.rst
Normal file
|
@ -0,0 +1,47 @@
|
|||
.. _PowerPC-System-emulator:
|
||||
|
||||
PowerPC System emulator
|
||||
-----------------------
|
||||
|
||||
Use the executable ``qemu-system-ppc`` to simulate a complete 40P (PREP)
|
||||
or PowerMac PowerPC system.
|
||||
|
||||
QEMU emulates the following PowerMac peripherals:
|
||||
|
||||
- UniNorth or Grackle PCI Bridge
|
||||
|
||||
- PCI VGA compatible card with VESA Bochs Extensions
|
||||
|
||||
- 2 PMAC IDE interfaces with hard disk and CD-ROM support
|
||||
|
||||
- NE2000 PCI adapters
|
||||
|
||||
- Non Volatile RAM
|
||||
|
||||
- VIA-CUDA with ADB keyboard and mouse.
|
||||
|
||||
QEMU emulates the following 40P (PREP) peripherals:
|
||||
|
||||
- PCI Bridge
|
||||
|
||||
- PCI VGA compatible card with VESA Bochs Extensions
|
||||
|
||||
- 2 IDE interfaces with hard disk and CD-ROM support
|
||||
|
||||
- Floppy disk
|
||||
|
||||
- PCnet network adapters
|
||||
|
||||
- Serial port
|
||||
|
||||
- PREP Non Volatile RAM
|
||||
|
||||
- PC compatible keyboard and mouse.
|
||||
|
||||
Since version 0.9.1, QEMU uses OpenBIOS https://www.openbios.org/ for
|
||||
the g3beige and mac99 PowerMac and the 40p machines. OpenBIOS is a free
|
||||
(GPL v2) portable firmware implementation. The goal is to implement a
|
||||
100% IEEE 1275-1994 (referred to as Open Firmware) compliant firmware.
|
||||
|
||||
More information is available at
|
||||
http://perso.magic.fr/l_indien/qemu-ppc/.
|
62
docs/system/target-sparc.rst
Normal file
62
docs/system/target-sparc.rst
Normal file
|
@ -0,0 +1,62 @@
|
|||
.. _Sparc32-System-emulator:
|
||||
|
||||
Sparc32 System emulator
|
||||
-----------------------
|
||||
|
||||
Use the executable ``qemu-system-sparc`` to simulate the following Sun4m
|
||||
architecture machines:
|
||||
|
||||
- SPARCstation 4
|
||||
|
||||
- SPARCstation 5
|
||||
|
||||
- SPARCstation 10
|
||||
|
||||
- SPARCstation 20
|
||||
|
||||
- SPARCserver 600MP
|
||||
|
||||
- SPARCstation LX
|
||||
|
||||
- SPARCstation Voyager
|
||||
|
||||
- SPARCclassic
|
||||
|
||||
- SPARCbook
|
||||
|
||||
The emulation is somewhat complete. SMP up to 16 CPUs is supported, but
|
||||
Linux limits the number of usable CPUs to 4.
|
||||
|
||||
QEMU emulates the following sun4m peripherals:
|
||||
|
||||
- IOMMU
|
||||
|
||||
- TCX or cgthree Frame buffer
|
||||
|
||||
- Lance (Am7990) Ethernet
|
||||
|
||||
- Non Volatile RAM M48T02/M48T08
|
||||
|
||||
- Slave I/O: timers, interrupt controllers, Zilog serial ports,
|
||||
keyboard and power/reset logic
|
||||
|
||||
- ESP SCSI controller with hard disk and CD-ROM support
|
||||
|
||||
- Floppy drive (not on SS-600MP)
|
||||
|
||||
- CS4231 sound device (only on SS-5, not working yet)
|
||||
|
||||
The number of peripherals is fixed in the architecture. Maximum memory
|
||||
size depends on the machine type, for SS-5 it is 256MB and for others
|
||||
2047MB.
|
||||
|
||||
Since version 0.8.2, QEMU uses OpenBIOS https://www.openbios.org/.
|
||||
OpenBIOS is a free (GPL v2) portable firmware implementation. The goal
|
||||
is to implement a 100% IEEE 1275-1994 (referred to as Open Firmware)
|
||||
compliant firmware.
|
||||
|
||||
A sample Linux 2.6 series kernel and ram disk image are available on the
|
||||
QEMU web site. There are still issues with NetBSD and OpenBSD, but most
|
||||
kernel versions work. Please note that currently older Solaris kernels
|
||||
don't work probably due to interface issues between OpenBIOS and
|
||||
Solaris.
|
37
docs/system/target-sparc64.rst
Normal file
37
docs/system/target-sparc64.rst
Normal file
|
@ -0,0 +1,37 @@
|
|||
.. _Sparc64-System-emulator:
|
||||
|
||||
Sparc64 System emulator
|
||||
-----------------------
|
||||
|
||||
Use the executable ``qemu-system-sparc64`` to simulate a Sun4u
|
||||
(UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic
|
||||
Niagara (T1) machine. The Sun4u emulator is mostly complete, being able
|
||||
to run Linux, NetBSD and OpenBSD in headless (-nographic) mode. The
|
||||
Sun4v emulator is still a work in progress.
|
||||
|
||||
The Niagara T1 emulator makes use of firmware and OS binaries supplied
|
||||
in the S10image/ directory of the OpenSPARC T1 project
|
||||
http://download.oracle.com/technetwork/systems/opensparc/OpenSPARCT1_Arch.1.5.tar.bz2
|
||||
and is able to boot the disk.s10hw2 Solaris image.
|
||||
|
||||
::
|
||||
|
||||
qemu-system-sparc64 -M niagara -L /path-to/S10image/ \
|
||||
-nographic -m 256 \
|
||||
-drive if=pflash,readonly=on,file=/S10image/disk.s10hw2
|
||||
|
||||
QEMU emulates the following peripherals:
|
||||
|
||||
- UltraSparc IIi APB PCI Bridge
|
||||
|
||||
- PCI VGA compatible card with VESA Bochs Extensions
|
||||
|
||||
- PS/2 mouse and keyboard
|
||||
|
||||
- Non Volatile RAM M48T59
|
||||
|
||||
- PC-compatible serial ports
|
||||
|
||||
- 2 PCI IDE interfaces with hard disk and CD-ROM support
|
||||
|
||||
- Floppy disk
|
27
docs/system/target-xtensa.rst
Normal file
27
docs/system/target-xtensa.rst
Normal file
|
@ -0,0 +1,27 @@
|
|||
.. _Xtensa-System-emulator:
|
||||
|
||||
Xtensa System emulator
|
||||
----------------------
|
||||
|
||||
Two executables cover simulation of both Xtensa endian options,
|
||||
``qemu-system-xtensa`` and ``qemu-system-xtensaeb``. Two different
|
||||
machine types are emulated:
|
||||
|
||||
- Xtensa emulator pseudo board \"sim\"
|
||||
|
||||
- Avnet LX60/LX110/LX200 board
|
||||
|
||||
The sim pseudo board emulation provides an environment similar to one
|
||||
provided by the proprietary Tensilica ISS. It supports:
|
||||
|
||||
- A range of Xtensa CPUs, default is the DC232B
|
||||
|
||||
- Console and filesystem access via semihosting calls
|
||||
|
||||
The Avnet LX60/LX110/LX200 emulation supports:
|
||||
|
||||
- A range of Xtensa CPUs, default is the DC232B
|
||||
|
||||
- 16550 UART
|
||||
|
||||
- OpenCores 10/100 Mbps Ethernet MAC
|
19
docs/system/targets.rst
Normal file
19
docs/system/targets.rst
Normal file
|
@ -0,0 +1,19 @@
|
|||
QEMU System Emulator Targets
|
||||
============================
|
||||
|
||||
QEMU is a generic emulator and it emulates many machines. Most of the
|
||||
options are similar for all machines. Specific information about the
|
||||
various targets are mentioned in the following sections.
|
||||
|
||||
Contents:
|
||||
|
||||
.. toctree::
|
||||
|
||||
target-i386
|
||||
target-ppc
|
||||
target-sparc
|
||||
target-sparc64
|
||||
target-mips
|
||||
target-arm
|
||||
target-m68k
|
||||
target-xtensa
|
328
docs/system/tls.rst
Normal file
328
docs/system/tls.rst
Normal file
|
@ -0,0 +1,328 @@
|
|||
.. _network_005ftls:
|
||||
|
||||
TLS setup for network services
|
||||
------------------------------
|
||||
|
||||
Almost all network services in QEMU have the ability to use TLS for
|
||||
session data encryption, along with x509 certificates for simple client
|
||||
authentication. What follows is a description of how to generate
|
||||
certificates suitable for usage with QEMU, and applies to the VNC
|
||||
server, character devices with the TCP backend, NBD server and client,
|
||||
and migration server and client.
|
||||
|
||||
At a high level, QEMU requires certificates and private keys to be
|
||||
provided in PEM format. Aside from the core fields, the certificates
|
||||
should include various extension data sets, including v3 basic
|
||||
constraints data, key purpose, key usage and subject alt name.
|
||||
|
||||
The GnuTLS package includes a command called ``certtool`` which can be
|
||||
used to easily generate certificates and keys in the required format
|
||||
with expected data present. Alternatively a certificate management
|
||||
service may be used.
|
||||
|
||||
At a minimum it is necessary to setup a certificate authority, and issue
|
||||
certificates to each server. If using x509 certificates for
|
||||
authentication, then each client will also need to be issued a
|
||||
certificate.
|
||||
|
||||
Assuming that the QEMU network services will only ever be exposed to
|
||||
clients on a private intranet, there is no need to use a commercial
|
||||
certificate authority to create certificates. A self-signed CA is
|
||||
sufficient, and in fact likely to be more secure since it removes the
|
||||
ability of malicious 3rd parties to trick the CA into mis-issuing certs
|
||||
for impersonating your services. The only likely exception where a
|
||||
commercial CA might be desirable is if enabling the VNC websockets
|
||||
server and exposing it directly to remote browser clients. In such a
|
||||
case it might be useful to use a commercial CA to avoid needing to
|
||||
install custom CA certs in the web browsers.
|
||||
|
||||
The recommendation is for the server to keep its certificates in either
|
||||
``/etc/pki/qemu`` or for unprivileged users in ``$HOME/.pki/qemu``.
|
||||
|
||||
.. _tls_005fgenerate_005fca:
|
||||
|
||||
Setup the Certificate Authority
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This step only needs to be performed once per organization /
|
||||
organizational unit. First the CA needs a private key. This key must be
|
||||
kept VERY secret and secure. If this key is compromised the entire trust
|
||||
chain of the certificates issued with it is lost.
|
||||
|
||||
::
|
||||
|
||||
# certtool --generate-privkey > ca-key.pem
|
||||
|
||||
To generate a self-signed certificate requires one core piece of
|
||||
information, the name of the organization. A template file ``ca.info``
|
||||
should be populated with the desired data to avoid having to deal with
|
||||
interactive prompts from certtool::
|
||||
|
||||
# cat > ca.info <<EOF
|
||||
cn = Name of your organization
|
||||
ca
|
||||
cert_signing_key
|
||||
EOF
|
||||
# certtool --generate-self-signed \
|
||||
--load-privkey ca-key.pem
|
||||
--template ca.info \
|
||||
--outfile ca-cert.pem
|
||||
|
||||
The ``ca`` keyword in the template sets the v3 basic constraints
|
||||
extension to indicate this certificate is for a CA, while
|
||||
``cert_signing_key`` sets the key usage extension to indicate this will
|
||||
be used for signing other keys. The generated ``ca-cert.pem`` file
|
||||
should be copied to all servers and clients wishing to utilize TLS
|
||||
support in the VNC server. The ``ca-key.pem`` must not be
|
||||
disclosed/copied anywhere except the host responsible for issuing
|
||||
certificates.
|
||||
|
||||
.. _tls_005fgenerate_005fserver:
|
||||
|
||||
Issuing server certificates
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Each server (or host) needs to be issued with a key and certificate.
|
||||
When connecting the certificate is sent to the client which validates it
|
||||
against the CA certificate. The core pieces of information for a server
|
||||
certificate are the hostnames and/or IP addresses that will be used by
|
||||
clients when connecting. The hostname / IP address that the client
|
||||
specifies when connecting will be validated against the hostname(s) and
|
||||
IP address(es) recorded in the server certificate, and if no match is
|
||||
found the client will close the connection.
|
||||
|
||||
Thus it is recommended that the server certificate include both the
|
||||
fully qualified and unqualified hostnames. If the server will have
|
||||
permanently assigned IP address(es), and clients are likely to use them
|
||||
when connecting, they may also be included in the certificate. Both IPv4
|
||||
and IPv6 addresses are supported. Historically certificates only
|
||||
included 1 hostname in the ``CN`` field, however, usage of this field
|
||||
for validation is now deprecated. Instead modern TLS clients will
|
||||
validate against the Subject Alt Name extension data, which allows for
|
||||
multiple entries. In the future usage of the ``CN`` field may be
|
||||
discontinued entirely, so providing SAN extension data is strongly
|
||||
recommended.
|
||||
|
||||
On the host holding the CA, create template files containing the
|
||||
information for each server, and use it to issue server certificates.
|
||||
|
||||
::
|
||||
|
||||
# cat > server-hostNNN.info <<EOF
|
||||
organization = Name of your organization
|
||||
cn = hostNNN.foo.example.com
|
||||
dns_name = hostNNN
|
||||
dns_name = hostNNN.foo.example.com
|
||||
ip_address = 10.0.1.87
|
||||
ip_address = 192.8.0.92
|
||||
ip_address = 2620:0:cafe::87
|
||||
ip_address = 2001:24::92
|
||||
tls_www_server
|
||||
encryption_key
|
||||
signing_key
|
||||
EOF
|
||||
# certtool --generate-privkey > server-hostNNN-key.pem
|
||||
# certtool --generate-certificate \
|
||||
--load-ca-certificate ca-cert.pem \
|
||||
--load-ca-privkey ca-key.pem \
|
||||
--load-privkey server-hostNNN-key.pem \
|
||||
--template server-hostNNN.info \
|
||||
--outfile server-hostNNN-cert.pem
|
||||
|
||||
The ``dns_name`` and ``ip_address`` fields in the template are setting
|
||||
the subject alt name extension data. The ``tls_www_server`` keyword is
|
||||
the key purpose extension to indicate this certificate is intended for
|
||||
usage in a web server. Although QEMU network services are not in fact
|
||||
HTTP servers (except for VNC websockets), setting this key purpose is
|
||||
still recommended. The ``encryption_key`` and ``signing_key`` keyword is
|
||||
the key usage extension to indicate this certificate is intended for
|
||||
usage in the data session.
|
||||
|
||||
The ``server-hostNNN-key.pem`` and ``server-hostNNN-cert.pem`` files
|
||||
should now be securely copied to the server for which they were
|
||||
generated, and renamed to ``server-key.pem`` and ``server-cert.pem``
|
||||
when added to the ``/etc/pki/qemu`` directory on the target host. The
|
||||
``server-key.pem`` file is security sensitive and should be kept
|
||||
protected with file mode 0600 to prevent disclosure.
|
||||
|
||||
.. _tls_005fgenerate_005fclient:
|
||||
|
||||
Issuing client certificates
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The QEMU x509 TLS credential setup defaults to enabling client
|
||||
verification using certificates, providing a simple authentication
|
||||
mechanism. If this default is used, each client also needs to be issued
|
||||
a certificate. The client certificate contains enough metadata to
|
||||
uniquely identify the client with the scope of the certificate
|
||||
authority. The client certificate would typically include fields for
|
||||
organization, state, city, building, etc.
|
||||
|
||||
Once again on the host holding the CA, create template files containing
|
||||
the information for each client, and use it to issue client
|
||||
certificates.
|
||||
|
||||
::
|
||||
|
||||
# cat > client-hostNNN.info <<EOF
|
||||
country = GB
|
||||
state = London
|
||||
locality = City Of London
|
||||
organization = Name of your organization
|
||||
cn = hostNNN.foo.example.com
|
||||
tls_www_client
|
||||
encryption_key
|
||||
signing_key
|
||||
EOF
|
||||
# certtool --generate-privkey > client-hostNNN-key.pem
|
||||
# certtool --generate-certificate \
|
||||
--load-ca-certificate ca-cert.pem \
|
||||
--load-ca-privkey ca-key.pem \
|
||||
--load-privkey client-hostNNN-key.pem \
|
||||
--template client-hostNNN.info \
|
||||
--outfile client-hostNNN-cert.pem
|
||||
|
||||
The subject alt name extension data is not required for clients, so the
|
||||
the ``dns_name`` and ``ip_address`` fields are not included. The
|
||||
``tls_www_client`` keyword is the key purpose extension to indicate this
|
||||
certificate is intended for usage in a web client. Although QEMU network
|
||||
clients are not in fact HTTP clients, setting this key purpose is still
|
||||
recommended. The ``encryption_key`` and ``signing_key`` keyword is the
|
||||
key usage extension to indicate this certificate is intended for usage
|
||||
in the data session.
|
||||
|
||||
The ``client-hostNNN-key.pem`` and ``client-hostNNN-cert.pem`` files
|
||||
should now be securely copied to the client for which they were
|
||||
generated, and renamed to ``client-key.pem`` and ``client-cert.pem``
|
||||
when added to the ``/etc/pki/qemu`` directory on the target host. The
|
||||
``client-key.pem`` file is security sensitive and should be kept
|
||||
protected with file mode 0600 to prevent disclosure.
|
||||
|
||||
If a single host is going to be using TLS in both a client and server
|
||||
role, it is possible to create a single certificate to cover both roles.
|
||||
This would be quite common for the migration and NBD services, where a
|
||||
QEMU process will be started by accepting a TLS protected incoming
|
||||
migration, and later itself be migrated out to another host. To generate
|
||||
a single certificate, simply include the template data from both the
|
||||
client and server instructions in one.
|
||||
|
||||
::
|
||||
|
||||
# cat > both-hostNNN.info <<EOF
|
||||
country = GB
|
||||
state = London
|
||||
locality = City Of London
|
||||
organization = Name of your organization
|
||||
cn = hostNNN.foo.example.com
|
||||
dns_name = hostNNN
|
||||
dns_name = hostNNN.foo.example.com
|
||||
ip_address = 10.0.1.87
|
||||
ip_address = 192.8.0.92
|
||||
ip_address = 2620:0:cafe::87
|
||||
ip_address = 2001:24::92
|
||||
tls_www_server
|
||||
tls_www_client
|
||||
encryption_key
|
||||
signing_key
|
||||
EOF
|
||||
# certtool --generate-privkey > both-hostNNN-key.pem
|
||||
# certtool --generate-certificate \
|
||||
--load-ca-certificate ca-cert.pem \
|
||||
--load-ca-privkey ca-key.pem \
|
||||
--load-privkey both-hostNNN-key.pem \
|
||||
--template both-hostNNN.info \
|
||||
--outfile both-hostNNN-cert.pem
|
||||
|
||||
When copying the PEM files to the target host, save them twice, once as
|
||||
``server-cert.pem`` and ``server-key.pem``, and again as
|
||||
``client-cert.pem`` and ``client-key.pem``.
|
||||
|
||||
.. _tls_005fcreds_005fsetup:
|
||||
|
||||
TLS x509 credential configuration
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
QEMU has a standard mechanism for loading x509 credentials that will be
|
||||
used for network services and clients. It requires specifying the
|
||||
``tls-creds-x509`` class name to the ``--object`` command line argument
|
||||
for the system emulators. Each set of credentials loaded should be given
|
||||
a unique string identifier via the ``id`` parameter. A single set of TLS
|
||||
credentials can be used for multiple network backends, so VNC,
|
||||
migration, NBD, character devices can all share the same credentials.
|
||||
Note, however, that credentials for use in a client endpoint must be
|
||||
loaded separately from those used in a server endpoint.
|
||||
|
||||
When specifying the object, the ``dir`` parameters specifies which
|
||||
directory contains the credential files. This directory is expected to
|
||||
contain files with the names mentioned previously, ``ca-cert.pem``,
|
||||
``server-key.pem``, ``server-cert.pem``, ``client-key.pem`` and
|
||||
``client-cert.pem`` as appropriate. It is also possible to include a set
|
||||
of pre-generated Diffie-Hellman (DH) parameters in a file
|
||||
``dh-params.pem``, which can be created using the
|
||||
``certtool --generate-dh-params`` command. If omitted, QEMU will
|
||||
dynamically generate DH parameters when loading the credentials.
|
||||
|
||||
The ``endpoint`` parameter indicates whether the credentials will be
|
||||
used for a network client or server, and determines which PEM files are
|
||||
loaded.
|
||||
|
||||
The ``verify`` parameter determines whether x509 certificate validation
|
||||
should be performed. This defaults to enabled, meaning clients will
|
||||
always validate the server hostname against the certificate subject alt
|
||||
name fields and/or CN field. It also means that servers will request
|
||||
that clients provide a certificate and validate them. Verification
|
||||
should never be turned off for client endpoints, however, it may be
|
||||
turned off for server endpoints if an alternative mechanism is used to
|
||||
authenticate clients. For example, the VNC server can use SASL to
|
||||
authenticate clients instead.
|
||||
|
||||
To load server credentials with client certificate validation enabled
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server
|
||||
|
||||
while to load client credentials use
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=client
|
||||
|
||||
Network services which support TLS will all have a ``tls-creds``
|
||||
parameter which expects the ID of the TLS credentials object. For
|
||||
example with VNC:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| -vnc 0.0.0.0:0,tls-creds=tls0
|
||||
|
||||
.. _tls_005fpsk:
|
||||
|
||||
TLS Pre-Shared Keys (PSK)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Instead of using certificates, you may also use TLS Pre-Shared Keys
|
||||
(TLS-PSK). This can be simpler to set up than certificates but is less
|
||||
scalable.
|
||||
|
||||
Use the GnuTLS ``psktool`` program to generate a ``keys.psk`` file
|
||||
containing one or more usernames and random keys::
|
||||
|
||||
mkdir -m 0700 /tmp/keys
|
||||
psktool -u rich -p /tmp/keys/keys.psk
|
||||
|
||||
TLS-enabled servers such as qemu-nbd can use this directory like so::
|
||||
|
||||
qemu-nbd \
|
||||
-t -x / \
|
||||
--object tls-creds-psk,id=tls0,endpoint=server,dir=/tmp/keys \
|
||||
--tls-creds tls0 \
|
||||
image.qcow2
|
||||
|
||||
When connecting from a qemu-based client you must specify the directory
|
||||
containing ``keys.psk`` and an optional username (defaults to "qemu")::
|
||||
|
||||
qemu-img info \
|
||||
--object tls-creds-psk,id=tls0,dir=/tmp/keys,username=rich,endpoint=client \
|
||||
--image-opts \
|
||||
file.driver=nbd,file.host=localhost,file.port=10809,file.tls-creds=tls0,file.export=/
|
137
docs/system/usb.rst
Normal file
137
docs/system/usb.rst
Normal file
|
@ -0,0 +1,137 @@
|
|||
.. _pcsys_005fusb:
|
||||
|
||||
USB emulation
|
||||
-------------
|
||||
|
||||
QEMU can emulate a PCI UHCI, OHCI, EHCI or XHCI USB controller. You can
|
||||
plug virtual USB devices or real host USB devices (only works with
|
||||
certain host operating systems). QEMU will automatically create and
|
||||
connect virtual USB hubs as necessary to connect multiple USB devices.
|
||||
|
||||
.. _usb_005fdevices:
|
||||
|
||||
Connecting USB devices
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
USB devices can be connected with the ``-device usb-...`` command line
|
||||
option or the ``device_add`` monitor command. Available devices are:
|
||||
|
||||
``usb-mouse``
|
||||
Virtual Mouse. This will override the PS/2 mouse emulation when
|
||||
activated.
|
||||
|
||||
``usb-tablet``
|
||||
Pointer device that uses absolute coordinates (like a touchscreen).
|
||||
This means QEMU is able to report the mouse position without having
|
||||
to grab the mouse. Also overrides the PS/2 mouse emulation when
|
||||
activated.
|
||||
|
||||
``usb-storage,drive=drive_id``
|
||||
Mass storage device backed by drive_id (see
|
||||
:ref:`disk_005fimages`)
|
||||
|
||||
``usb-uas``
|
||||
USB attached SCSI device, see
|
||||
`usb-storage.txt <https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt>`__
|
||||
for details
|
||||
|
||||
``usb-bot``
|
||||
Bulk-only transport storage device, see
|
||||
`usb-storage.txt <https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt>`__
|
||||
for details here, too
|
||||
|
||||
``usb-mtp,rootdir=dir``
|
||||
Media transfer protocol device, using dir as root of the file tree
|
||||
that is presented to the guest.
|
||||
|
||||
``usb-host,hostbus=bus,hostaddr=addr``
|
||||
Pass through the host device identified by bus and addr
|
||||
|
||||
``usb-host,vendorid=vendor,productid=product``
|
||||
Pass through the host device identified by vendor and product ID
|
||||
|
||||
``usb-wacom-tablet``
|
||||
Virtual Wacom PenPartner tablet. This device is similar to the
|
||||
``tablet`` above but it can be used with the tslib library because in
|
||||
addition to touch coordinates it reports touch pressure.
|
||||
|
||||
``usb-kbd``
|
||||
Standard USB keyboard. Will override the PS/2 keyboard (if present).
|
||||
|
||||
``usb-serial,chardev=id``
|
||||
Serial converter. This emulates an FTDI FT232BM chip connected to
|
||||
host character device id.
|
||||
|
||||
``usb-braille,chardev=id``
|
||||
Braille device. This will use BrlAPI to display the braille output on
|
||||
a real or fake device referenced by id.
|
||||
|
||||
``usb-net[,netdev=id]``
|
||||
Network adapter that supports CDC ethernet and RNDIS protocols. id
|
||||
specifies a netdev defined with ``-netdev …,id=id``. For instance,
|
||||
user-mode networking can be used with
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| [...] -netdev user,id=net0 -device usb-net,netdev=net0
|
||||
|
||||
``usb-ccid``
|
||||
Smartcard reader device
|
||||
|
||||
``usb-audio``
|
||||
USB audio device
|
||||
|
||||
.. _host_005fusb_005fdevices:
|
||||
|
||||
Using host USB devices on a Linux host
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
WARNING: this is an experimental feature. QEMU will slow down when using
|
||||
it. USB devices requiring real time streaming (i.e. USB Video Cameras)
|
||||
are not supported yet.
|
||||
|
||||
1. If you use an early Linux 2.4 kernel, verify that no Linux driver is
|
||||
actually using the USB device. A simple way to do that is simply to
|
||||
disable the corresponding kernel module by renaming it from
|
||||
``mydriver.o`` to ``mydriver.o.disabled``.
|
||||
|
||||
2. Verify that ``/proc/bus/usb`` is working (most Linux distributions
|
||||
should enable it by default). You should see something like that:
|
||||
|
||||
::
|
||||
|
||||
ls /proc/bus/usb
|
||||
001 devices drivers
|
||||
|
||||
3. Since only root can access to the USB devices directly, you can
|
||||
either launch QEMU as root or change the permissions of the USB
|
||||
devices you want to use. For testing, the following suffices:
|
||||
|
||||
::
|
||||
|
||||
chown -R myuid /proc/bus/usb
|
||||
|
||||
4. Launch QEMU and do in the monitor:
|
||||
|
||||
::
|
||||
|
||||
info usbhost
|
||||
Device 1.2, speed 480 Mb/s
|
||||
Class 00: USB device 1234:5678, USB DISK
|
||||
|
||||
You should see the list of the devices you can use (Never try to use
|
||||
hubs, it won't work).
|
||||
|
||||
5. Add the device in QEMU by using:
|
||||
|
||||
::
|
||||
|
||||
device_add usb-host,vendorid=0x1234,productid=0x5678
|
||||
|
||||
Normally the guest OS should report that a new USB device is plugged.
|
||||
You can use the option ``-device usb-host,...`` to do the same.
|
||||
|
||||
6. Now you can try to use the host USB device in QEMU.
|
||||
|
||||
When relaunching QEMU, you may have to unplug and plug again the USB
|
||||
device to make it work again (this is a bug).
|
202
docs/system/vnc-security.rst
Normal file
202
docs/system/vnc-security.rst
Normal file
|
@ -0,0 +1,202 @@
|
|||
.. _vnc_005fsecurity:
|
||||
|
||||
VNC security
|
||||
------------
|
||||
|
||||
The VNC server capability provides access to the graphical console of
|
||||
the guest VM across the network. This has a number of security
|
||||
considerations depending on the deployment scenarios.
|
||||
|
||||
.. _vnc_005fsec_005fnone:
|
||||
|
||||
Without passwords
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
The simplest VNC server setup does not include any form of
|
||||
authentication. For this setup it is recommended to restrict it to
|
||||
listen on a UNIX domain socket only. For example
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
|
||||
|
||||
This ensures that only users on local box with read/write access to that
|
||||
path can access the VNC server. To securely access the VNC server from a
|
||||
remote machine, a combination of netcat+ssh can be used to provide a
|
||||
secure tunnel.
|
||||
|
||||
.. _vnc_005fsec_005fpassword:
|
||||
|
||||
With passwords
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
The VNC protocol has limited support for password based authentication.
|
||||
Since the protocol limits passwords to 8 characters it should not be
|
||||
considered to provide high security. The password can be fairly easily
|
||||
brute-forced by a client making repeat connections. For this reason, a
|
||||
VNC server using password authentication should be restricted to only
|
||||
listen on the loopback interface or UNIX domain sockets. Password
|
||||
authentication is not supported when operating in FIPS 140-2 compliance
|
||||
mode as it requires the use of the DES cipher. Password authentication
|
||||
is requested with the ``password`` option, and then once QEMU is running
|
||||
the password is set with the monitor. Until the monitor is used to set
|
||||
the password all clients will be rejected.
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| [...OPTIONS...] -vnc :1,password -monitor stdio
|
||||
(qemu) change vnc password
|
||||
Password: ********
|
||||
(qemu)
|
||||
|
||||
.. _vnc_005fsec_005fcertificate:
|
||||
|
||||
With x509 certificates
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The QEMU VNC server also implements the VeNCrypt extension allowing use
|
||||
of TLS for encryption of the session, and x509 certificates for
|
||||
authentication. The use of x509 certificates is strongly recommended,
|
||||
because TLS on its own is susceptible to man-in-the-middle attacks.
|
||||
Basic x509 certificate support provides a secure session, but no
|
||||
authentication. This allows any client to connect, and provides an
|
||||
encrypted session.
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| [...OPTIONS...] \
|
||||
-object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=no \
|
||||
-vnc :1,tls-creds=tls0 -monitor stdio
|
||||
|
||||
In the above example ``/etc/pki/qemu`` should contain at least three
|
||||
files, ``ca-cert.pem``, ``server-cert.pem`` and ``server-key.pem``.
|
||||
Unprivileged users will want to use a private directory, for example
|
||||
``$HOME/.pki/qemu``. NB the ``server-key.pem`` file should be protected
|
||||
with file mode 0600 to only be readable by the user owning it.
|
||||
|
||||
.. _vnc_005fsec_005fcertificate_005fverify:
|
||||
|
||||
With x509 certificates and client verification
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Certificates can also provide a means to authenticate the client
|
||||
connecting. The server will request that the client provide a
|
||||
certificate, which it will then validate against the CA certificate.
|
||||
This is a good choice if deploying in an environment with a private
|
||||
internal certificate authority. It uses the same syntax as previously,
|
||||
but with ``verify-peer`` set to ``yes`` instead.
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| [...OPTIONS...] \
|
||||
-object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=yes \
|
||||
-vnc :1,tls-creds=tls0 -monitor stdio
|
||||
|
||||
.. _vnc_005fsec_005fcertificate_005fpw:
|
||||
|
||||
With x509 certificates, client verification and passwords
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Finally, the previous method can be combined with VNC password
|
||||
authentication to provide two layers of authentication for clients.
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| [...OPTIONS...] \
|
||||
-object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=yes \
|
||||
-vnc :1,tls-creds=tls0,password -monitor stdio
|
||||
(qemu) change vnc password
|
||||
Password: ********
|
||||
(qemu)
|
||||
|
||||
.. _vnc_005fsec_005fsasl:
|
||||
|
||||
With SASL authentication
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The SASL authentication method is a VNC extension, that provides an
|
||||
easily extendable, pluggable authentication method. This allows for
|
||||
integration with a wide range of authentication mechanisms, such as PAM,
|
||||
GSSAPI/Kerberos, LDAP, SQL databases, one-time keys and more. The
|
||||
strength of the authentication depends on the exact mechanism
|
||||
configured. If the chosen mechanism also provides a SSF layer, then it
|
||||
will encrypt the datastream as well.
|
||||
|
||||
Refer to the later docs on how to choose the exact SASL mechanism used
|
||||
for authentication, but assuming use of one supporting SSF, then QEMU
|
||||
can be launched with:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| [...OPTIONS...] -vnc :1,sasl -monitor stdio
|
||||
|
||||
.. _vnc_005fsec_005fcertificate_005fsasl:
|
||||
|
||||
With x509 certificates and SASL authentication
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If the desired SASL authentication mechanism does not supported SSF
|
||||
layers, then it is strongly advised to run it in combination with TLS
|
||||
and x509 certificates. This provides securely encrypted data stream,
|
||||
avoiding risk of compromising of the security credentials. This can be
|
||||
enabled, by combining the 'sasl' option with the aforementioned TLS +
|
||||
x509 options:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|qemu_system| [...OPTIONS...] \
|
||||
-object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=yes \
|
||||
-vnc :1,tls-creds=tls0,sasl -monitor stdio
|
||||
|
||||
.. _vnc_005fsetup_005fsasl:
|
||||
|
||||
Configuring SASL mechanisms
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The following documentation assumes use of the Cyrus SASL implementation
|
||||
on a Linux host, but the principles should apply to any other SASL
|
||||
implementation or host. When SASL is enabled, the mechanism
|
||||
configuration will be loaded from system default SASL service config
|
||||
/etc/sasl2/qemu.conf. If running QEMU as an unprivileged user, an
|
||||
environment variable SASL_CONF_PATH can be used to make it search
|
||||
alternate locations for the service config file.
|
||||
|
||||
If the TLS option is enabled for VNC, then it will provide session
|
||||
encryption, otherwise the SASL mechanism will have to provide
|
||||
encryption. In the latter case the list of possible plugins that can be
|
||||
used is drastically reduced. In fact only the GSSAPI SASL mechanism
|
||||
provides an acceptable level of security by modern standards. Previous
|
||||
versions of QEMU referred to the DIGEST-MD5 mechanism, however, it has
|
||||
multiple serious flaws described in detail in RFC 6331 and thus should
|
||||
never be used any more. The SCRAM-SHA-1 mechanism provides a simple
|
||||
username/password auth facility similar to DIGEST-MD5, but does not
|
||||
support session encryption, so can only be used in combination with TLS.
|
||||
|
||||
When not using TLS the recommended configuration is
|
||||
|
||||
::
|
||||
|
||||
mech_list: gssapi
|
||||
keytab: /etc/qemu/krb5.tab
|
||||
|
||||
This says to use the 'GSSAPI' mechanism with the Kerberos v5 protocol,
|
||||
with the server principal stored in /etc/qemu/krb5.tab. For this to work
|
||||
the administrator of your KDC must generate a Kerberos principal for the
|
||||
server, with a name of 'qemu/somehost.example.com@EXAMPLE.COM' replacing
|
||||
'somehost.example.com' with the fully qualified host name of the machine
|
||||
running QEMU, and 'EXAMPLE.COM' with the Kerberos Realm.
|
||||
|
||||
When using TLS, if username+password authentication is desired, then a
|
||||
reasonable configuration is
|
||||
|
||||
::
|
||||
|
||||
mech_list: scram-sha-1
|
||||
sasldb_path: /etc/qemu/passwd.db
|
||||
|
||||
The ``saslpasswd2`` program can be used to populate the ``passwd.db``
|
||||
file with accounts.
|
||||
|
||||
Other SASL configurations will be left as an exercise for the reader.
|
||||
Note that all mechanisms, except GSSAPI, should be combined with use of
|
||||
TLS to ensure a secure data channel.
|
15
docs/user/conf.py
Normal file
15
docs/user/conf.py
Normal file
|
@ -0,0 +1,15 @@
|
|||
# -*- coding: utf-8 -*-
|
||||
#
|
||||
# QEMU documentation build configuration file for the 'user' manual.
|
||||
#
|
||||
# This includes the top level conf file and then makes any necessary tweaks.
|
||||
import sys
|
||||
import os
|
||||
|
||||
qemu_docdir = os.path.abspath("..")
|
||||
parent_config = os.path.join(qemu_docdir, "conf.py")
|
||||
exec(compile(open(parent_config, "rb").read(), parent_config, 'exec'))
|
||||
|
||||
# This slightly misuses the 'description', but is the best way to get
|
||||
# the manual title to appear in the sidebar.
|
||||
html_theme_options['description'] = u'User Mode Emulation User''s Guide'
|
16
docs/user/index.rst
Normal file
16
docs/user/index.rst
Normal file
|
@ -0,0 +1,16 @@
|
|||
.. This is the top level page for the 'user' manual.
|
||||
|
||||
|
||||
QEMU User Mode Emulation User's Guide
|
||||
=====================================
|
||||
|
||||
This manual is the overall guide for users using QEMU
|
||||
for user-mode emulation. In this mode, QEMU can launch
|
||||
processes compiled for one CPU on another CPU.
|
||||
|
||||
Contents:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
main
|
295
docs/user/main.rst
Normal file
295
docs/user/main.rst
Normal file
|
@ -0,0 +1,295 @@
|
|||
QEMU User space emulator
|
||||
========================
|
||||
|
||||
Supported Operating Systems
|
||||
---------------------------
|
||||
|
||||
The following OS are supported in user space emulation:
|
||||
|
||||
- Linux (referred as qemu-linux-user)
|
||||
|
||||
- BSD (referred as qemu-bsd-user)
|
||||
|
||||
Features
|
||||
--------
|
||||
|
||||
QEMU user space emulation has the following notable features:
|
||||
|
||||
**System call translation:**
|
||||
QEMU includes a generic system call translator. This means that the
|
||||
parameters of the system calls can be converted to fix endianness and
|
||||
32/64-bit mismatches between hosts and targets. IOCTLs can be
|
||||
converted too.
|
||||
|
||||
**POSIX signal handling:**
|
||||
QEMU can redirect to the running program all signals coming from the
|
||||
host (such as ``SIGALRM``), as well as synthesize signals from
|
||||
virtual CPU exceptions (for example ``SIGFPE`` when the program
|
||||
executes a division by zero).
|
||||
|
||||
QEMU relies on the host kernel to emulate most signal system calls,
|
||||
for example to emulate the signal mask. On Linux, QEMU supports both
|
||||
normal and real-time signals.
|
||||
|
||||
**Threading:**
|
||||
On Linux, QEMU can emulate the ``clone`` syscall and create a real
|
||||
host thread (with a separate virtual CPU) for each emulated thread.
|
||||
Note that not all targets currently emulate atomic operations
|
||||
correctly. x86 and ARM use a global lock in order to preserve their
|
||||
semantics.
|
||||
|
||||
QEMU was conceived so that ultimately it can emulate itself. Although it
|
||||
is not very useful, it is an important test to show the power of the
|
||||
emulator.
|
||||
|
||||
Linux User space emulator
|
||||
-------------------------
|
||||
|
||||
Quick Start
|
||||
~~~~~~~~~~~
|
||||
|
||||
In order to launch a Linux process, QEMU needs the process executable
|
||||
itself and all the target (x86) dynamic libraries used by it.
|
||||
|
||||
- On x86, you can just try to launch any process by using the native
|
||||
libraries::
|
||||
|
||||
qemu-i386 -L / /bin/ls
|
||||
|
||||
``-L /`` tells that the x86 dynamic linker must be searched with a
|
||||
``/`` prefix.
|
||||
|
||||
- Since QEMU is also a linux process, you can launch QEMU with QEMU
|
||||
(NOTE: you can only do that if you compiled QEMU from the sources)::
|
||||
|
||||
qemu-i386 -L / qemu-i386 -L / /bin/ls
|
||||
|
||||
- On non x86 CPUs, you need first to download at least an x86 glibc
|
||||
(``qemu-runtime-i386-XXX-.tar.gz`` on the QEMU web page). Ensure that
|
||||
``LD_LIBRARY_PATH`` is not set::
|
||||
|
||||
unset LD_LIBRARY_PATH
|
||||
|
||||
Then you can launch the precompiled ``ls`` x86 executable::
|
||||
|
||||
qemu-i386 tests/i386/ls
|
||||
|
||||
You can look at ``scripts/qemu-binfmt-conf.sh`` so that QEMU is
|
||||
automatically launched by the Linux kernel when you try to launch x86
|
||||
executables. It requires the ``binfmt_misc`` module in the Linux
|
||||
kernel.
|
||||
|
||||
- The x86 version of QEMU is also included. You can try weird things
|
||||
such as::
|
||||
|
||||
qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \
|
||||
/usr/local/qemu-i386/bin/ls-i386
|
||||
|
||||
Wine launch
|
||||
~~~~~~~~~~~
|
||||
|
||||
- Ensure that you have a working QEMU with the x86 glibc distribution
|
||||
(see previous section). In order to verify it, you must be able to
|
||||
do::
|
||||
|
||||
qemu-i386 /usr/local/qemu-i386/bin/ls-i386
|
||||
|
||||
- Download the binary x86 Wine install (``qemu-XXX-i386-wine.tar.gz``
|
||||
on the QEMU web page).
|
||||
|
||||
- Configure Wine on your account. Look at the provided script
|
||||
``/usr/local/qemu-i386/bin/wine-conf.sh``. Your previous
|
||||
``${HOME}/.wine`` directory is saved to ``${HOME}/.wine.org``.
|
||||
|
||||
- Then you can try the example ``putty.exe``::
|
||||
|
||||
qemu-i386 /usr/local/qemu-i386/wine/bin/wine \
|
||||
/usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
|
||||
|
||||
Command line options
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
::
|
||||
|
||||
qemu-i386 [-h] [-d] [-L path] [-s size] [-cpu model] [-g port] [-B offset] [-R size] program [arguments...]
|
||||
|
||||
``-h``
|
||||
Print the help
|
||||
|
||||
``-L path``
|
||||
Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
|
||||
|
||||
``-s size``
|
||||
Set the x86 stack size in bytes (default=524288)
|
||||
|
||||
``-cpu model``
|
||||
Select CPU model (-cpu help for list and additional feature
|
||||
selection)
|
||||
|
||||
``-E var=value``
|
||||
Set environment var to value.
|
||||
|
||||
``-U var``
|
||||
Remove var from the environment.
|
||||
|
||||
``-B offset``
|
||||
Offset guest address by the specified number of bytes. This is useful
|
||||
when the address region required by guest applications is reserved on
|
||||
the host. This option is currently only supported on some hosts.
|
||||
|
||||
``-R size``
|
||||
Pre-allocate a guest virtual address space of the given size (in
|
||||
bytes). \"G\", \"M\", and \"k\" suffixes may be used when specifying
|
||||
the size.
|
||||
|
||||
Debug options:
|
||||
|
||||
``-d item1,...``
|
||||
Activate logging of the specified items (use '-d help' for a list of
|
||||
log items)
|
||||
|
||||
``-p pagesize``
|
||||
Act as if the host page size was 'pagesize' bytes
|
||||
|
||||
``-g port``
|
||||
Wait gdb connection to port
|
||||
|
||||
``-singlestep``
|
||||
Run the emulation in single step mode.
|
||||
|
||||
Environment variables:
|
||||
|
||||
QEMU_STRACE
|
||||
Print system calls and arguments similar to the 'strace' program
|
||||
(NOTE: the actual 'strace' program will not work because the user
|
||||
space emulator hasn't implemented ptrace). At the moment this is
|
||||
incomplete. All system calls that don't have a specific argument
|
||||
format are printed with information for six arguments. Many
|
||||
flag-style arguments don't have decoders and will show up as numbers.
|
||||
|
||||
Other binaries
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
user mode (Alpha)
|
||||
``qemu-alpha`` TODO.
|
||||
|
||||
user mode (ARM)
|
||||
``qemu-armeb`` TODO.
|
||||
|
||||
user mode (ARM)
|
||||
``qemu-arm`` is also capable of running ARM \"Angel\" semihosted ELF
|
||||
binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
|
||||
configurations), and arm-uclinux bFLT format binaries.
|
||||
|
||||
user mode (ColdFire)
|
||||
user mode (M68K)
|
||||
``qemu-m68k`` is capable of running semihosted binaries using the BDM
|
||||
(m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
|
||||
coldfire uClinux bFLT format binaries.
|
||||
|
||||
The binary format is detected automatically.
|
||||
|
||||
user mode (Cris)
|
||||
``qemu-cris`` TODO.
|
||||
|
||||
user mode (i386)
|
||||
``qemu-i386`` TODO. ``qemu-x86_64`` TODO.
|
||||
|
||||
user mode (Microblaze)
|
||||
``qemu-microblaze`` TODO.
|
||||
|
||||
user mode (MIPS)
|
||||
``qemu-mips`` executes 32-bit big endian MIPS binaries (MIPS O32 ABI).
|
||||
|
||||
``qemu-mipsel`` executes 32-bit little endian MIPS binaries (MIPS O32
|
||||
ABI).
|
||||
|
||||
``qemu-mips64`` executes 64-bit big endian MIPS binaries (MIPS N64 ABI).
|
||||
|
||||
``qemu-mips64el`` executes 64-bit little endian MIPS binaries (MIPS N64
|
||||
ABI).
|
||||
|
||||
``qemu-mipsn32`` executes 32-bit big endian MIPS binaries (MIPS N32
|
||||
ABI).
|
||||
|
||||
``qemu-mipsn32el`` executes 32-bit little endian MIPS binaries (MIPS N32
|
||||
ABI).
|
||||
|
||||
user mode (NiosII)
|
||||
``qemu-nios2`` TODO.
|
||||
|
||||
user mode (PowerPC)
|
||||
``qemu-ppc64abi32`` TODO. ``qemu-ppc64`` TODO. ``qemu-ppc`` TODO.
|
||||
|
||||
user mode (SH4)
|
||||
``qemu-sh4eb`` TODO. ``qemu-sh4`` TODO.
|
||||
|
||||
user mode (SPARC)
|
||||
``qemu-sparc`` can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI).
|
||||
|
||||
``qemu-sparc32plus`` can execute Sparc32 and SPARC32PLUS binaries
|
||||
(Sparc64 CPU, 32 bit ABI).
|
||||
|
||||
``qemu-sparc64`` can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and
|
||||
SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).
|
||||
|
||||
BSD User space emulator
|
||||
-----------------------
|
||||
|
||||
BSD Status
|
||||
~~~~~~~~~~
|
||||
|
||||
- target Sparc64 on Sparc64: Some trivial programs work.
|
||||
|
||||
Quick Start
|
||||
~~~~~~~~~~~
|
||||
|
||||
In order to launch a BSD process, QEMU needs the process executable
|
||||
itself and all the target dynamic libraries used by it.
|
||||
|
||||
- On Sparc64, you can just try to launch any process by using the
|
||||
native libraries::
|
||||
|
||||
qemu-sparc64 /bin/ls
|
||||
|
||||
Command line options
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
::
|
||||
|
||||
qemu-sparc64 [-h] [-d] [-L path] [-s size] [-bsd type] program [arguments...]
|
||||
|
||||
``-h``
|
||||
Print the help
|
||||
|
||||
``-L path``
|
||||
Set the library root path (default=/)
|
||||
|
||||
``-s size``
|
||||
Set the stack size in bytes (default=524288)
|
||||
|
||||
``-ignore-environment``
|
||||
Start with an empty environment. Without this option, the initial
|
||||
environment is a copy of the caller's environment.
|
||||
|
||||
``-E var=value``
|
||||
Set environment var to value.
|
||||
|
||||
``-U var``
|
||||
Remove var from the environment.
|
||||
|
||||
``-bsd type``
|
||||
Set the type of the emulated BSD Operating system. Valid values are
|
||||
FreeBSD, NetBSD and OpenBSD (default).
|
||||
|
||||
Debug options:
|
||||
|
||||
``-d item1,...``
|
||||
Activate logging of the specified items (use '-d help' for a list of
|
||||
log items)
|
||||
|
||||
``-p pagesize``
|
||||
Act as if the host page size was 'pagesize' bytes
|
||||
|
||||
``-singlestep``
|
||||
Run the emulation in single step mode.
|
|
@ -4,14 +4,18 @@ HXCOMM discarded from C version
|
|||
HXCOMM DEF(command, args, callback, arg_string, help) is used to construct
|
||||
HXCOMM monitor info commands
|
||||
HXCOMM HXCOMM can be used for comments, discarded from both texi and C
|
||||
HXCOMM
|
||||
HXCOMM In this file, generally SRST fragments should have two extra
|
||||
HXCOMM spaces of indent, so that the documentation list item for "info foo"
|
||||
HXCOMM appears inside the documentation list item for the top level
|
||||
HXCOMM "info" documentation entry. The exception is the first SRST
|
||||
HXCOMM fragment that defines that top level entry.
|
||||
|
||||
STEXI
|
||||
@table @option
|
||||
@item info @var{subcommand}
|
||||
@findex info
|
||||
Show various information about the system state.
|
||||
@table @option
|
||||
ETEXI
|
||||
SRST
|
||||
``info`` *subcommand*
|
||||
Show various information about the system state.
|
||||
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "version",
|
||||
|
@ -22,11 +26,10 @@ ETEXI
|
|||
.flags = "p",
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info version
|
||||
@findex info version
|
||||
Show the version of QEMU.
|
||||
ETEXI
|
||||
SRST
|
||||
``info version``
|
||||
Show the version of QEMU.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "network",
|
||||
|
@ -36,11 +39,10 @@ ETEXI
|
|||
.cmd = hmp_info_network,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info network
|
||||
@findex info network
|
||||
Show the network state.
|
||||
ETEXI
|
||||
SRST
|
||||
``info network``
|
||||
Show the network state.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "chardev",
|
||||
|
@ -51,11 +53,10 @@ ETEXI
|
|||
.flags = "p",
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info chardev
|
||||
@findex info chardev
|
||||
Show the character devices.
|
||||
ETEXI
|
||||
SRST
|
||||
``info chardev``
|
||||
Show the character devices.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "block",
|
||||
|
@ -66,11 +67,10 @@ ETEXI
|
|||
.cmd = hmp_info_block,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info block
|
||||
@findex info block
|
||||
Show info of one block device or all block devices.
|
||||
ETEXI
|
||||
SRST
|
||||
``info block``
|
||||
Show info of one block device or all block devices.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "blockstats",
|
||||
|
@ -80,11 +80,10 @@ ETEXI
|
|||
.cmd = hmp_info_blockstats,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info blockstats
|
||||
@findex info blockstats
|
||||
Show block device statistics.
|
||||
ETEXI
|
||||
SRST
|
||||
``info blockstats``
|
||||
Show block device statistics.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "block-jobs",
|
||||
|
@ -94,11 +93,10 @@ ETEXI
|
|||
.cmd = hmp_info_block_jobs,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info block-jobs
|
||||
@findex info block-jobs
|
||||
Show progress of ongoing block device operations.
|
||||
ETEXI
|
||||
SRST
|
||||
``info block-jobs``
|
||||
Show progress of ongoing block device operations.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "registers",
|
||||
|
@ -108,11 +106,10 @@ ETEXI
|
|||
.cmd = hmp_info_registers,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info registers
|
||||
@findex info registers
|
||||
Show the cpu registers.
|
||||
ETEXI
|
||||
SRST
|
||||
``info registers``
|
||||
Show the cpu registers.
|
||||
ERST
|
||||
|
||||
#if defined(TARGET_I386)
|
||||
{
|
||||
|
@ -125,11 +122,10 @@ ETEXI
|
|||
},
|
||||
#endif
|
||||
|
||||
STEXI
|
||||
@item info lapic
|
||||
@findex info lapic
|
||||
Show local APIC state
|
||||
ETEXI
|
||||
SRST
|
||||
``info lapic``
|
||||
Show local APIC state
|
||||
ERST
|
||||
|
||||
#if defined(TARGET_I386)
|
||||
{
|
||||
|
@ -141,11 +137,10 @@ ETEXI
|
|||
},
|
||||
#endif
|
||||
|
||||
STEXI
|
||||
@item info ioapic
|
||||
@findex info ioapic
|
||||
Show io APIC state
|
||||
ETEXI
|
||||
SRST
|
||||
``info ioapic``
|
||||
Show io APIC state
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "cpus",
|
||||
|
@ -155,11 +150,10 @@ ETEXI
|
|||
.cmd = hmp_info_cpus,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info cpus
|
||||
@findex info cpus
|
||||
Show infos for each CPU.
|
||||
ETEXI
|
||||
SRST
|
||||
``info cpus``
|
||||
Show infos for each CPU.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "history",
|
||||
|
@ -170,11 +164,10 @@ ETEXI
|
|||
.flags = "p",
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info history
|
||||
@findex info history
|
||||
Show the command line history.
|
||||
ETEXI
|
||||
SRST
|
||||
``info history``
|
||||
Show the command line history.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "irq",
|
||||
|
@ -184,11 +177,10 @@ ETEXI
|
|||
.cmd = hmp_info_irq,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info irq
|
||||
@findex info irq
|
||||
Show the interrupts statistics (if available).
|
||||
ETEXI
|
||||
SRST
|
||||
``info irq``
|
||||
Show the interrupts statistics (if available).
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "pic",
|
||||
|
@ -198,11 +190,10 @@ ETEXI
|
|||
.cmd = hmp_info_pic,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info pic
|
||||
@findex info pic
|
||||
Show PIC state.
|
||||
ETEXI
|
||||
SRST
|
||||
``info pic``
|
||||
Show PIC state.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "rdma",
|
||||
|
@ -212,11 +203,10 @@ ETEXI
|
|||
.cmd = hmp_info_rdma,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info rdma
|
||||
@findex info rdma
|
||||
Show RDMA state.
|
||||
ETEXI
|
||||
SRST
|
||||
``info rdma``
|
||||
Show RDMA state.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "pci",
|
||||
|
@ -226,11 +216,10 @@ ETEXI
|
|||
.cmd = hmp_info_pci,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info pci
|
||||
@findex info pci
|
||||
Show PCI information.
|
||||
ETEXI
|
||||
SRST
|
||||
``info pci``
|
||||
Show PCI information.
|
||||
ERST
|
||||
|
||||
#if defined(TARGET_I386) || defined(TARGET_SH4) || defined(TARGET_SPARC) || \
|
||||
defined(TARGET_PPC) || defined(TARGET_XTENSA) || defined(TARGET_M68K)
|
||||
|
@ -243,11 +232,10 @@ ETEXI
|
|||
},
|
||||
#endif
|
||||
|
||||
STEXI
|
||||
@item info tlb
|
||||
@findex info tlb
|
||||
Show virtual to physical memory mappings.
|
||||
ETEXI
|
||||
SRST
|
||||
``info tlb``
|
||||
Show virtual to physical memory mappings.
|
||||
ERST
|
||||
|
||||
#if defined(TARGET_I386) || defined(TARGET_RISCV)
|
||||
{
|
||||
|
@ -259,11 +247,10 @@ ETEXI
|
|||
},
|
||||
#endif
|
||||
|
||||
STEXI
|
||||
@item info mem
|
||||
@findex info mem
|
||||
Show the active virtual memory mappings.
|
||||
ETEXI
|
||||
SRST
|
||||
``info mem``
|
||||
Show the active virtual memory mappings.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "mtree",
|
||||
|
@ -275,11 +262,10 @@ ETEXI
|
|||
.cmd = hmp_info_mtree,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info mtree
|
||||
@findex info mtree
|
||||
Show memory tree.
|
||||
ETEXI
|
||||
SRST
|
||||
``info mtree``
|
||||
Show memory tree.
|
||||
ERST
|
||||
|
||||
#if defined(CONFIG_TCG)
|
||||
{
|
||||
|
@ -291,11 +277,10 @@ ETEXI
|
|||
},
|
||||
#endif
|
||||
|
||||
STEXI
|
||||
@item info jit
|
||||
@findex info jit
|
||||
Show dynamic compiler info.
|
||||
ETEXI
|
||||
SRST
|
||||
``info jit``
|
||||
Show dynamic compiler info.
|
||||
ERST
|
||||
|
||||
#if defined(CONFIG_TCG)
|
||||
{
|
||||
|
@ -307,11 +292,10 @@ ETEXI
|
|||
},
|
||||
#endif
|
||||
|
||||
STEXI
|
||||
@item info opcount
|
||||
@findex info opcount
|
||||
Show dynamic compiler opcode counters
|
||||
ETEXI
|
||||
SRST
|
||||
``info opcount``
|
||||
Show dynamic compiler opcode counters
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "sync-profile",
|
||||
|
@ -324,16 +308,20 @@ ETEXI
|
|||
.cmd = hmp_info_sync_profile,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info sync-profile [-m|-n] [@var{max}]
|
||||
@findex info sync-profile
|
||||
Show synchronization profiling info, up to @var{max} entries (default: 10),
|
||||
sorted by total wait time.
|
||||
-m: sort by mean wait time
|
||||
-n: do not coalesce objects with the same call site
|
||||
When different objects that share the same call site are coalesced, the "Object"
|
||||
field shows---enclosed in brackets---the number of objects being coalesced.
|
||||
ETEXI
|
||||
SRST
|
||||
``info sync-profile [-m|-n]`` [*max*]
|
||||
Show synchronization profiling info, up to *max* entries (default: 10),
|
||||
sorted by total wait time.
|
||||
|
||||
``-m``
|
||||
sort by mean wait time
|
||||
``-n``
|
||||
do not coalesce objects with the same call site
|
||||
|
||||
When different objects that share the same call site are coalesced,
|
||||
the "Object" field shows---enclosed in brackets---the number of objects
|
||||
being coalesced.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "kvm",
|
||||
|
@ -343,11 +331,10 @@ ETEXI
|
|||
.cmd = hmp_info_kvm,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info kvm
|
||||
@findex info kvm
|
||||
Show KVM information.
|
||||
ETEXI
|
||||
SRST
|
||||
``info kvm``
|
||||
Show KVM information.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "numa",
|
||||
|
@ -357,11 +344,10 @@ ETEXI
|
|||
.cmd = hmp_info_numa,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info numa
|
||||
@findex info numa
|
||||
Show NUMA information.
|
||||
ETEXI
|
||||
SRST
|
||||
``info numa``
|
||||
Show NUMA information.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "usb",
|
||||
|
@ -371,11 +357,10 @@ ETEXI
|
|||
.cmd = hmp_info_usb,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info usb
|
||||
@findex info usb
|
||||
Show guest USB devices.
|
||||
ETEXI
|
||||
SRST
|
||||
``info usb``
|
||||
Show guest USB devices.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "usbhost",
|
||||
|
@ -385,11 +370,10 @@ ETEXI
|
|||
.cmd = hmp_info_usbhost,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info usbhost
|
||||
@findex info usbhost
|
||||
Show host USB devices.
|
||||
ETEXI
|
||||
SRST
|
||||
``info usbhost``
|
||||
Show host USB devices.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "profile",
|
||||
|
@ -399,11 +383,10 @@ ETEXI
|
|||
.cmd = hmp_info_profile,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info profile
|
||||
@findex info profile
|
||||
Show profiling information.
|
||||
ETEXI
|
||||
SRST
|
||||
``info profile``
|
||||
Show profiling information.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "capture",
|
||||
|
@ -413,11 +396,10 @@ ETEXI
|
|||
.cmd = hmp_info_capture,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info capture
|
||||
@findex info capture
|
||||
Show capture information.
|
||||
ETEXI
|
||||
SRST
|
||||
``info capture``
|
||||
Show capture information.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "snapshots",
|
||||
|
@ -427,11 +409,10 @@ ETEXI
|
|||
.cmd = hmp_info_snapshots,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info snapshots
|
||||
@findex info snapshots
|
||||
Show the currently saved VM snapshots.
|
||||
ETEXI
|
||||
SRST
|
||||
``info snapshots``
|
||||
Show the currently saved VM snapshots.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "status",
|
||||
|
@ -442,11 +423,10 @@ ETEXI
|
|||
.flags = "p",
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info status
|
||||
@findex info status
|
||||
Show the current VM status (running|paused).
|
||||
ETEXI
|
||||
SRST
|
||||
``info status``
|
||||
Show the current VM status (running|paused).
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "mice",
|
||||
|
@ -456,11 +436,10 @@ ETEXI
|
|||
.cmd = hmp_info_mice,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info mice
|
||||
@findex info mice
|
||||
Show which guest mouse is receiving events.
|
||||
ETEXI
|
||||
SRST
|
||||
``info mice``
|
||||
Show which guest mouse is receiving events.
|
||||
ERST
|
||||
|
||||
#if defined(CONFIG_VNC)
|
||||
{
|
||||
|
@ -472,11 +451,10 @@ ETEXI
|
|||
},
|
||||
#endif
|
||||
|
||||
STEXI
|
||||
@item info vnc
|
||||
@findex info vnc
|
||||
Show the vnc server status.
|
||||
ETEXI
|
||||
SRST
|
||||
``info vnc``
|
||||
Show the vnc server status.
|
||||
ERST
|
||||
|
||||
#if defined(CONFIG_SPICE)
|
||||
{
|
||||
|
@ -488,11 +466,10 @@ ETEXI
|
|||
},
|
||||
#endif
|
||||
|
||||
STEXI
|
||||
@item info spice
|
||||
@findex info spice
|
||||
Show the spice server status.
|
||||
ETEXI
|
||||
SRST
|
||||
``info spice``
|
||||
Show the spice server status.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "name",
|
||||
|
@ -503,11 +480,10 @@ ETEXI
|
|||
.flags = "p",
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info name
|
||||
@findex info name
|
||||
Show the current VM name.
|
||||
ETEXI
|
||||
SRST
|
||||
``info name``
|
||||
Show the current VM name.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "uuid",
|
||||
|
@ -518,11 +494,10 @@ ETEXI
|
|||
.flags = "p",
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info uuid
|
||||
@findex info uuid
|
||||
Show the current VM UUID.
|
||||
ETEXI
|
||||
SRST
|
||||
``info uuid``
|
||||
Show the current VM UUID.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "cpustats",
|
||||
|
@ -532,11 +507,10 @@ ETEXI
|
|||
.cmd = hmp_info_cpustats,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info cpustats
|
||||
@findex info cpustats
|
||||
Show CPU statistics.
|
||||
ETEXI
|
||||
SRST
|
||||
``info cpustats``
|
||||
Show CPU statistics.
|
||||
ERST
|
||||
|
||||
#if defined(CONFIG_SLIRP)
|
||||
{
|
||||
|
@ -548,11 +522,10 @@ ETEXI
|
|||
},
|
||||
#endif
|
||||
|
||||
STEXI
|
||||
@item info usernet
|
||||
@findex info usernet
|
||||
Show user network stack connection states.
|
||||
ETEXI
|
||||
SRST
|
||||
``info usernet``
|
||||
Show user network stack connection states.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "migrate",
|
||||
|
@ -562,11 +535,10 @@ ETEXI
|
|||
.cmd = hmp_info_migrate,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info migrate
|
||||
@findex info migrate
|
||||
Show migration status.
|
||||
ETEXI
|
||||
SRST
|
||||
``info migrate``
|
||||
Show migration status.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "migrate_capabilities",
|
||||
|
@ -576,11 +548,10 @@ ETEXI
|
|||
.cmd = hmp_info_migrate_capabilities,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info migrate_capabilities
|
||||
@findex info migrate_capabilities
|
||||
Show current migration capabilities.
|
||||
ETEXI
|
||||
SRST
|
||||
``info migrate_capabilities``
|
||||
Show current migration capabilities.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "migrate_parameters",
|
||||
|
@ -590,11 +561,10 @@ ETEXI
|
|||
.cmd = hmp_info_migrate_parameters,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info migrate_parameters
|
||||
@findex info migrate_parameters
|
||||
Show current migration parameters.
|
||||
ETEXI
|
||||
SRST
|
||||
``info migrate_parameters``
|
||||
Show current migration parameters.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "migrate_cache_size",
|
||||
|
@ -604,11 +574,10 @@ ETEXI
|
|||
.cmd = hmp_info_migrate_cache_size,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info migrate_cache_size
|
||||
@findex info migrate_cache_size
|
||||
Show current migration xbzrle cache size.
|
||||
ETEXI
|
||||
SRST
|
||||
``info migrate_cache_size``
|
||||
Show current migration xbzrle cache size.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "balloon",
|
||||
|
@ -618,11 +587,10 @@ ETEXI
|
|||
.cmd = hmp_info_balloon,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info balloon
|
||||
@findex info balloon
|
||||
Show balloon information.
|
||||
ETEXI
|
||||
SRST
|
||||
``info balloon``
|
||||
Show balloon information.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "qtree",
|
||||
|
@ -632,11 +600,10 @@ ETEXI
|
|||
.cmd = hmp_info_qtree,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info qtree
|
||||
@findex info qtree
|
||||
Show device tree.
|
||||
ETEXI
|
||||
SRST
|
||||
``info qtree``
|
||||
Show device tree.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "qdm",
|
||||
|
@ -646,11 +613,10 @@ ETEXI
|
|||
.cmd = hmp_info_qdm,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info qdm
|
||||
@findex info qdm
|
||||
Show qdev device model list.
|
||||
ETEXI
|
||||
SRST
|
||||
``info qdm``
|
||||
Show qdev device model list.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "qom-tree",
|
||||
|
@ -661,11 +627,10 @@ ETEXI
|
|||
.flags = "p",
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info qom-tree
|
||||
@findex info qom-tree
|
||||
Show QOM composition tree.
|
||||
ETEXI
|
||||
SRST
|
||||
``info qom-tree``
|
||||
Show QOM composition tree.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "roms",
|
||||
|
@ -675,11 +640,10 @@ ETEXI
|
|||
.cmd = hmp_info_roms,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info roms
|
||||
@findex info roms
|
||||
Show roms.
|
||||
ETEXI
|
||||
SRST
|
||||
``info roms``
|
||||
Show roms.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "trace-events",
|
||||
|
@ -691,11 +655,10 @@ ETEXI
|
|||
.command_completion = info_trace_events_completion,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info trace-events
|
||||
@findex info trace-events
|
||||
Show available trace-events & their state.
|
||||
ETEXI
|
||||
SRST
|
||||
``info trace-events``
|
||||
Show available trace-events & their state.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "tpm",
|
||||
|
@ -705,11 +668,10 @@ ETEXI
|
|||
.cmd = hmp_info_tpm,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info tpm
|
||||
@findex info tpm
|
||||
Show the TPM device.
|
||||
ETEXI
|
||||
SRST
|
||||
``info tpm``
|
||||
Show the TPM device.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "memdev",
|
||||
|
@ -720,11 +682,10 @@ ETEXI
|
|||
.flags = "p",
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info memdev
|
||||
@findex info memdev
|
||||
Show memory backends
|
||||
ETEXI
|
||||
SRST
|
||||
``info memdev``
|
||||
Show memory backends
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "memory-devices",
|
||||
|
@ -734,11 +695,10 @@ ETEXI
|
|||
.cmd = hmp_info_memory_devices,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info memory-devices
|
||||
@findex info memory-devices
|
||||
Show memory devices.
|
||||
ETEXI
|
||||
SRST
|
||||
``info memory-devices``
|
||||
Show memory devices.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "iothreads",
|
||||
|
@ -749,11 +709,10 @@ ETEXI
|
|||
.flags = "p",
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info iothreads
|
||||
@findex info iothreads
|
||||
Show iothread's identifiers.
|
||||
ETEXI
|
||||
SRST
|
||||
``info iothreads``
|
||||
Show iothread's identifiers.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "rocker",
|
||||
|
@ -763,11 +722,10 @@ ETEXI
|
|||
.cmd = hmp_rocker,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info rocker @var{name}
|
||||
@findex info rocker
|
||||
Show rocker switch.
|
||||
ETEXI
|
||||
SRST
|
||||
``info rocker`` *name*
|
||||
Show rocker switch.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "rocker-ports",
|
||||
|
@ -777,11 +735,10 @@ ETEXI
|
|||
.cmd = hmp_rocker_ports,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info rocker-ports @var{name}-ports
|
||||
@findex info rocker-ports
|
||||
Show rocker ports.
|
||||
ETEXI
|
||||
SRST
|
||||
``info rocker-ports`` *name*-ports
|
||||
Show rocker ports.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "rocker-of-dpa-flows",
|
||||
|
@ -791,11 +748,10 @@ ETEXI
|
|||
.cmd = hmp_rocker_of_dpa_flows,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info rocker-of-dpa-flows @var{name} [@var{tbl_id}]
|
||||
@findex info rocker-of-dpa-flows
|
||||
Show rocker OF-DPA flow tables.
|
||||
ETEXI
|
||||
SRST
|
||||
``info rocker-of-dpa-flows`` *name* [*tbl_id*]
|
||||
Show rocker OF-DPA flow tables.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "rocker-of-dpa-groups",
|
||||
|
@ -805,11 +761,10 @@ ETEXI
|
|||
.cmd = hmp_rocker_of_dpa_groups,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info rocker-of-dpa-groups @var{name} [@var{type}]
|
||||
@findex info rocker-of-dpa-groups
|
||||
Show rocker OF-DPA groups.
|
||||
ETEXI
|
||||
SRST
|
||||
``info rocker-of-dpa-groups`` *name* [*type*]
|
||||
Show rocker OF-DPA groups.
|
||||
ERST
|
||||
|
||||
#if defined(TARGET_S390X)
|
||||
{
|
||||
|
@ -821,11 +776,10 @@ ETEXI
|
|||
},
|
||||
#endif
|
||||
|
||||
STEXI
|
||||
@item info skeys @var{address}
|
||||
@findex info skeys
|
||||
Display the value of a storage key (s390 only)
|
||||
ETEXI
|
||||
SRST
|
||||
``info skeys`` *address*
|
||||
Display the value of a storage key (s390 only)
|
||||
ERST
|
||||
|
||||
#if defined(TARGET_S390X)
|
||||
{
|
||||
|
@ -837,11 +791,11 @@ ETEXI
|
|||
},
|
||||
#endif
|
||||
|
||||
STEXI
|
||||
@item info cmma @var{address}
|
||||
@findex info cmma
|
||||
Display the values of the CMMA storage attributes for a range of pages (s390 only)
|
||||
ETEXI
|
||||
SRST
|
||||
``info cmma`` *address*
|
||||
Display the values of the CMMA storage attributes for a range of
|
||||
pages (s390 only)
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "dump",
|
||||
|
@ -851,11 +805,10 @@ ETEXI
|
|||
.cmd = hmp_info_dump,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info dump
|
||||
@findex info dump
|
||||
Display the latest dump status.
|
||||
ETEXI
|
||||
SRST
|
||||
``info dump``
|
||||
Display the latest dump status.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "ramblock",
|
||||
|
@ -865,11 +818,10 @@ ETEXI
|
|||
.cmd = hmp_info_ramblock,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info ramblock
|
||||
@findex info ramblock
|
||||
Dump all the ramblocks of the system.
|
||||
ETEXI
|
||||
SRST
|
||||
``info ramblock``
|
||||
Dump all the ramblocks of the system.
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "hotpluggable-cpus",
|
||||
|
@ -880,11 +832,10 @@ ETEXI
|
|||
.flags = "p",
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info hotpluggable-cpus
|
||||
@findex info hotpluggable-cpus
|
||||
Show information about hotpluggable CPUs
|
||||
ETEXI
|
||||
SRST
|
||||
``info hotpluggable-cpus``
|
||||
Show information about hotpluggable CPUs
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "vm-generation-id",
|
||||
|
@ -894,11 +845,10 @@ ETEXI
|
|||
.cmd = hmp_info_vm_generation_id,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info vm-generation-id
|
||||
@findex info vm-generation-id
|
||||
Show Virtual Machine Generation ID
|
||||
ETEXI
|
||||
SRST
|
||||
``info vm-generation-id``
|
||||
Show Virtual Machine Generation ID
|
||||
ERST
|
||||
|
||||
{
|
||||
.name = "memory_size_summary",
|
||||
|
@ -909,12 +859,11 @@ ETEXI
|
|||
.cmd = hmp_info_memory_size_summary,
|
||||
},
|
||||
|
||||
STEXI
|
||||
@item info memory_size_summary
|
||||
@findex info memory_size_summary
|
||||
Display the amount of initially allocated and present hotpluggable (if
|
||||
enabled) memory in bytes.
|
||||
ETEXI
|
||||
SRST
|
||||
``info memory_size_summary``
|
||||
Display the amount of initially allocated and present hotpluggable (if
|
||||
enabled) memory in bytes.
|
||||
ERST
|
||||
|
||||
#if defined(TARGET_I386)
|
||||
{
|
||||
|
@ -926,16 +875,9 @@ ETEXI
|
|||
},
|
||||
#endif
|
||||
|
||||
STEXI
|
||||
@item info sev
|
||||
@findex info sev
|
||||
Show SEV information.
|
||||
ETEXI
|
||||
SRST
|
||||
``info sev``
|
||||
Show SEV information.
|
||||
ERST
|
||||
|
||||
STEXI
|
||||
@end table
|
||||
ETEXI
|
||||
|
||||
STEXI
|
||||
@end table
|
||||
ETEXI
|
||||
|
|
1449
hmp-commands.hx
1449
hmp-commands.hx
File diff suppressed because it is too large
Load diff
|
@ -1,377 +0,0 @@
|
|||
@node Deprecated features
|
||||
@appendix Deprecated features
|
||||
|
||||
In general features are intended to be supported indefinitely once
|
||||
introduced into QEMU. In the event that a feature needs to be removed,
|
||||
it will be listed in this appendix. The feature will remain functional
|
||||
for 2 releases prior to actual removal. Deprecated features may also
|
||||
generate warnings on the console when QEMU starts up, or if activated
|
||||
via a monitor command, however, this is not a mandatory requirement.
|
||||
|
||||
Prior to the 2.10.0 release there was no official policy on how
|
||||
long features would be deprecated prior to their removal, nor
|
||||
any documented list of which features were deprecated. Thus
|
||||
any features deprecated prior to 2.10.0 will be treated as if
|
||||
they were first deprecated in the 2.10.0 release.
|
||||
|
||||
What follows is a list of all features currently marked as
|
||||
deprecated.
|
||||
|
||||
@section System emulator command line arguments
|
||||
|
||||
@subsection -machine enforce-config-section=on|off (since 3.1)
|
||||
|
||||
The @option{enforce-config-section} parameter is replaced by the
|
||||
@option{-global migration.send-configuration=@var{on|off}} option.
|
||||
|
||||
@subsection -no-kvm (since 1.3.0)
|
||||
|
||||
The ``-no-kvm'' argument is now a synonym for setting ``-accel tcg''.
|
||||
|
||||
@subsection -usbdevice (since 2.10.0)
|
||||
|
||||
The ``-usbdevice DEV'' argument is now a synonym for setting
|
||||
the ``-device usb-DEV'' argument instead. The deprecated syntax
|
||||
would automatically enable USB support on the machine type.
|
||||
If using the new syntax, USB support must be explicitly
|
||||
enabled via the ``-machine usb=on'' argument.
|
||||
|
||||
@subsection -drive file=json:@{...@{'driver':'file'@}@} (since 3.0)
|
||||
|
||||
The 'file' driver for drives is no longer appropriate for character or host
|
||||
devices and will only accept regular files (S_IFREG). The correct driver
|
||||
for these file types is 'host_cdrom' or 'host_device' as appropriate.
|
||||
|
||||
@subsection -net ...,name=@var{name} (since 3.1)
|
||||
|
||||
The @option{name} parameter of the @option{-net} option is a synonym
|
||||
for the @option{id} parameter, which should now be used instead.
|
||||
|
||||
@subsection -smp (invalid topologies) (since 3.1)
|
||||
|
||||
CPU topology properties should describe whole machine topology including
|
||||
possible CPUs.
|
||||
|
||||
However, historically it was possible to start QEMU with an incorrect topology
|
||||
where @math{@var{n} <= @var{sockets} * @var{cores} * @var{threads} < @var{maxcpus}},
|
||||
which could lead to an incorrect topology enumeration by the guest.
|
||||
Support for invalid topologies will be removed, the user must ensure
|
||||
topologies described with -smp include all possible cpus, i.e.
|
||||
@math{@var{sockets} * @var{cores} * @var{threads} = @var{maxcpus}}.
|
||||
|
||||
@subsection -vnc acl (since 4.0.0)
|
||||
|
||||
The @code{acl} option to the @code{-vnc} argument has been replaced
|
||||
by the @code{tls-authz} and @code{sasl-authz} options.
|
||||
|
||||
@subsection QEMU_AUDIO_ environment variables and -audio-help (since 4.0)
|
||||
|
||||
The ``-audiodev'' argument is now the preferred way to specify audio
|
||||
backend settings instead of environment variables. To ease migration to
|
||||
the new format, the ``-audiodev-help'' option can be used to convert
|
||||
the current values of the environment variables to ``-audiodev'' options.
|
||||
|
||||
@subsection Creating sound card devices and vnc without audiodev= property (since 4.2)
|
||||
|
||||
When not using the deprecated legacy audio config, each sound card
|
||||
should specify an @code{audiodev=} property. Additionally, when using
|
||||
vnc, you should specify an @code{audiodev=} propery if you plan to
|
||||
transmit audio through the VNC protocol.
|
||||
|
||||
@subsection -mon ...,control=readline,pretty=on|off (since 4.1)
|
||||
|
||||
The @code{pretty=on|off} switch has no effect for HMP monitors, but is
|
||||
silently ignored. Using the switch with HMP monitors will become an
|
||||
error in the future.
|
||||
|
||||
@subsection -realtime (since 4.1)
|
||||
|
||||
The @code{-realtime mlock=on|off} argument has been replaced by the
|
||||
@code{-overcommit mem-lock=on|off} argument.
|
||||
|
||||
@subsection -numa node,mem=@var{size} (since 4.1)
|
||||
|
||||
The parameter @option{mem} of @option{-numa node} is used to assign a part of
|
||||
guest RAM to a NUMA node. But when using it, it's impossible to manage specified
|
||||
RAM chunk on the host side (like bind it to a host node, setting bind policy, ...),
|
||||
so guest end-ups with the fake NUMA configuration with suboptiomal performance.
|
||||
However since 2014 there is an alternative way to assign RAM to a NUMA node
|
||||
using parameter @option{memdev}, which does the same as @option{mem} and adds
|
||||
means to actualy manage node RAM on the host side. Use parameter @option{memdev}
|
||||
with @var{memory-backend-ram} backend as an replacement for parameter @option{mem}
|
||||
to achieve the same fake NUMA effect or a properly configured
|
||||
@var{memory-backend-file} backend to actually benefit from NUMA configuration.
|
||||
In future new machine versions will not accept the option but it will still
|
||||
work with old machine types. User can check QAPI schema to see if the legacy
|
||||
option is supported by looking at MachineInfo::numa-mem-supported property.
|
||||
|
||||
@subsection -numa node (without memory specified) (since 4.1)
|
||||
|
||||
Splitting RAM by default between NUMA nodes has the same issues as @option{mem}
|
||||
parameter described above with the difference that the role of the user plays
|
||||
QEMU using implicit generic or board specific splitting rule.
|
||||
Use @option{memdev} with @var{memory-backend-ram} backend or @option{mem} (if
|
||||
it's supported by used machine type) to define mapping explictly instead.
|
||||
|
||||
@subsection RISC-V -bios (since 4.1)
|
||||
|
||||
QEMU 4.1 introduced support for the -bios option in QEMU for RISC-V for the
|
||||
RISC-V virt machine and sifive_u machine.
|
||||
|
||||
QEMU 4.1 has no changes to the default behaviour to avoid breakages. This
|
||||
default will change in a future QEMU release, so please prepare now. All users
|
||||
of the virt or sifive_u machine must change their command line usage.
|
||||
|
||||
QEMU 4.1 has three options, please migrate to one of these three:
|
||||
1. ``-bios none`` - This is the current default behavior if no -bios option
|
||||
is included. QEMU will not automatically load any firmware. It is up
|
||||
to the user to load all the images they need.
|
||||
2. ``-bios default`` - In a future QEMU release this will become the default
|
||||
behaviour if no -bios option is specified. This option will load the
|
||||
default OpenSBI firmware automatically. The firmware is included with
|
||||
the QEMU release and no user interaction is required. All a user needs
|
||||
to do is specify the kernel they want to boot with the -kernel option
|
||||
3. ``-bios <file>`` - Tells QEMU to load the specified file as the firmwrae.
|
||||
|
||||
@subsection -tb-size option (since 5.0)
|
||||
|
||||
QEMU 5.0 introduced an alternative syntax to specify the size of the translation
|
||||
block cache, @option{-accel tcg,tb-size=}. The new syntax deprecates the
|
||||
previously available @option{-tb-size} option.
|
||||
|
||||
@subsection -show-cursor option (since 5.0)
|
||||
|
||||
Use @option{-display sdl,show-cursor=on} or
|
||||
@option{-display gtk,show-cursor=on} instead.
|
||||
|
||||
@section QEMU Machine Protocol (QMP) commands
|
||||
|
||||
@subsection change (since 2.5.0)
|
||||
|
||||
Use ``blockdev-change-medium'' or ``change-vnc-password'' instead.
|
||||
|
||||
@subsection migrate_set_downtime and migrate_set_speed (since 2.8.0)
|
||||
|
||||
Use ``migrate-set-parameters'' instead.
|
||||
|
||||
@subsection migrate-set-cache-size and query-migrate-cache-size (since 2.11.0)
|
||||
|
||||
Use ``migrate-set-parameters'' and ``query-migrate-parameters'' instead.
|
||||
|
||||
@subsection query-block result field dirty-bitmaps[i].status (since 4.0)
|
||||
|
||||
The ``status'' field of the ``BlockDirtyInfo'' structure, returned by
|
||||
the query-block command is deprecated. Two new boolean fields,
|
||||
``recording'' and ``busy'' effectively replace it.
|
||||
|
||||
@subsection query-block result field dirty-bitmaps (Since 4.2)
|
||||
|
||||
The ``dirty-bitmaps`` field of the ``BlockInfo`` structure, returned by
|
||||
the query-block command is itself now deprecated. The ``dirty-bitmaps``
|
||||
field of the ``BlockDeviceInfo`` struct should be used instead, which is the
|
||||
type of the ``inserted`` field in query-block replies, as well as the
|
||||
type of array items in query-named-block-nodes.
|
||||
|
||||
Since the ``dirty-bitmaps`` field is optionally present in both the old and
|
||||
new locations, clients must use introspection to learn where to anticipate
|
||||
the field if/when it does appear in command output.
|
||||
|
||||
@subsection query-cpus (since 2.12.0)
|
||||
|
||||
The ``query-cpus'' command is replaced by the ``query-cpus-fast'' command.
|
||||
|
||||
@subsection query-cpus-fast "arch" output member (since 3.0.0)
|
||||
|
||||
The ``arch'' output member of the ``query-cpus-fast'' command is
|
||||
replaced by the ``target'' output member.
|
||||
|
||||
@subsection cpu-add (since 4.0)
|
||||
|
||||
Use ``device_add'' for hotplugging vCPUs instead of ``cpu-add''. See
|
||||
documentation of ``query-hotpluggable-cpus'' for additional
|
||||
details.
|
||||
|
||||
@subsection query-events (since 4.0)
|
||||
|
||||
The ``query-events'' command has been superseded by the more powerful
|
||||
and accurate ``query-qmp-schema'' command.
|
||||
|
||||
@subsection chardev client socket with 'wait' option (since 4.0)
|
||||
|
||||
Character devices creating sockets in client mode should not specify
|
||||
the 'wait' field, which is only applicable to sockets in server mode
|
||||
|
||||
@section Human Monitor Protocol (HMP) commands
|
||||
|
||||
@subsection The hub_id parameter of 'hostfwd_add' / 'hostfwd_remove' (since 3.1)
|
||||
|
||||
The @option{[hub_id name]} parameter tuple of the 'hostfwd_add' and
|
||||
'hostfwd_remove' HMP commands has been replaced by @option{netdev_id}.
|
||||
|
||||
@subsection cpu-add (since 4.0)
|
||||
|
||||
Use ``device_add'' for hotplugging vCPUs instead of ``cpu-add''. See
|
||||
documentation of ``query-hotpluggable-cpus'' for additional details.
|
||||
|
||||
@subsection acl_show, acl_reset, acl_policy, acl_add, acl_remove (since 4.0.0)
|
||||
|
||||
The ``acl_show'', ``acl_reset'', ``acl_policy'', ``acl_add'', and
|
||||
``acl_remove'' commands are deprecated with no replacement. Authorization
|
||||
for VNC should be performed using the pluggable QAuthZ objects.
|
||||
|
||||
@section Guest Emulator ISAs
|
||||
|
||||
@subsection RISC-V ISA privledge specification version 1.09.1 (since 4.1)
|
||||
|
||||
The RISC-V ISA privledge specification version 1.09.1 has been deprecated.
|
||||
QEMU supports both the newer version 1.10.0 and the ratified version 1.11.0, these
|
||||
should be used instead of the 1.09.1 version.
|
||||
|
||||
@section System emulator CPUS
|
||||
|
||||
@subsection RISC-V ISA CPUs (since 4.1)
|
||||
|
||||
The RISC-V cpus with the ISA version in the CPU name have been depcreated. The
|
||||
four CPUs are: ``rv32gcsu-v1.9.1``, ``rv32gcsu-v1.10.0``, ``rv64gcsu-v1.9.1`` and
|
||||
``rv64gcsu-v1.10.0``. Instead the version can be specified via the CPU ``priv_spec``
|
||||
option when using the ``rv32`` or ``rv64`` CPUs.
|
||||
|
||||
@subsection RISC-V ISA CPUs (since 4.1)
|
||||
|
||||
The RISC-V no MMU cpus have been depcreated. The two CPUs: ``rv32imacu-nommu`` and
|
||||
``rv64imacu-nommu`` should no longer be used. Instead the MMU status can be specified
|
||||
via the CPU ``mmu`` option when using the ``rv32`` or ``rv64`` CPUs.
|
||||
|
||||
@section System emulator devices
|
||||
|
||||
@subsection ide-drive (since 4.2)
|
||||
|
||||
The 'ide-drive' device is deprecated. Users should use 'ide-hd' or
|
||||
'ide-cd' as appropriate to get an IDE hard disk or CD-ROM as needed.
|
||||
|
||||
@subsection scsi-disk (since 4.2)
|
||||
|
||||
The 'scsi-disk' device is deprecated. Users should use 'scsi-hd' or
|
||||
'scsi-cd' as appropriate to get a SCSI hard disk or CD-ROM as needed.
|
||||
|
||||
@section System emulator machines
|
||||
|
||||
@subsection mips r4k platform (since 5.0)
|
||||
|
||||
This machine type is very old and unmaintained. Users should use the 'malta'
|
||||
machine type instead.
|
||||
|
||||
@subsection pc-1.0, pc-1.1, pc-1.2 and pc-1.3 (since 5.0)
|
||||
|
||||
These machine types are very old and likely can not be used for live migration
|
||||
from old QEMU versions anymore. A newer machine type should be used instead.
|
||||
|
||||
@subsection spike_v1.9.1 and spike_v1.10 (since 4.1)
|
||||
|
||||
The version specific Spike machines have been deprecated in favour of the
|
||||
generic ``spike`` machine. If you need to specify an older version of the RISC-V
|
||||
spec you can use the ``-cpu rv64gcsu,priv_spec=v1.9.1`` command line argument.
|
||||
|
||||
@section Device options
|
||||
|
||||
@subsection Emulated device options
|
||||
|
||||
@subsubsection -device virtio-blk,scsi=on|off (since 5.0.0)
|
||||
|
||||
The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTIO 1.0
|
||||
and later do not support it because the virtio-scsi device was introduced for
|
||||
full SCSI support. Use virtio-scsi instead when SCSI passthrough is required.
|
||||
|
||||
Note this also applies to ``-device virtio-blk-pci,scsi=on|off'', which is an
|
||||
alias.
|
||||
|
||||
@subsection Block device options
|
||||
|
||||
@subsubsection "backing": "" (since 2.12.0)
|
||||
|
||||
In order to prevent QEMU from automatically opening an image's backing
|
||||
chain, use ``"backing": null'' instead.
|
||||
|
||||
@subsubsection rbd keyvalue pair encoded filenames: "" (since 3.1.0)
|
||||
|
||||
Options for ``rbd'' should be specified according to its runtime options,
|
||||
like other block drivers. Legacy parsing of keyvalue pair encoded
|
||||
filenames is useful to open images with the old format for backing files;
|
||||
These image files should be updated to use the current format.
|
||||
|
||||
Example of legacy encoding:
|
||||
|
||||
@code{json:@{"file.driver":"rbd", "file.filename":"rbd:rbd/name"@}}
|
||||
|
||||
The above, converted to the current supported format:
|
||||
|
||||
@code{json:@{"file.driver":"rbd", "file.pool":"rbd", "file.image":"name"@}}
|
||||
|
||||
@section Related binaries
|
||||
|
||||
@subsection qemu-img convert -n -o (since 4.2.0)
|
||||
|
||||
All options specified in @option{-o} are image creation options, so
|
||||
they have no effect when used with @option{-n} to skip image creation.
|
||||
Silently ignored options can be confusing, so this combination of
|
||||
options will be made an error in future versions.
|
||||
|
||||
@section Backwards compatibility
|
||||
|
||||
@subsection Runnability guarantee of CPU models (since 4.1.0)
|
||||
|
||||
Previous versions of QEMU never changed existing CPU models in
|
||||
ways that introduced additional host software or hardware
|
||||
requirements to the VM. This allowed management software to
|
||||
safely change the machine type of an existing VM without
|
||||
introducing new requirements ("runnability guarantee"). This
|
||||
prevented CPU models from being updated to include CPU
|
||||
vulnerability mitigations, leaving guests vulnerable in the
|
||||
default configuration.
|
||||
|
||||
The CPU model runnability guarantee won't apply anymore to
|
||||
existing CPU models. Management software that needs runnability
|
||||
guarantees must resolve the CPU model aliases using te
|
||||
``alias-of'' field returned by the ``query-cpu-definitions'' QMP
|
||||
command.
|
||||
|
||||
While those guarantees are kept, the return value of
|
||||
``query-cpu-definitions'' will have existing CPU model aliases
|
||||
point to a version that doesn't break runnability guarantees
|
||||
(specifically, version 1 of those CPU models). In future QEMU
|
||||
versions, aliases will point to newer CPU model versions
|
||||
depending on the machine type, so management software must
|
||||
resolve CPU model aliases before starting a virtual machine.
|
||||
|
||||
|
||||
@node Recently removed features
|
||||
@appendix Recently removed features
|
||||
|
||||
What follows is a record of recently removed, formerly deprecated
|
||||
features that serves as a record for users who have encountered
|
||||
trouble after a recent upgrade.
|
||||
|
||||
@section QEMU Machine Protocol (QMP) commands
|
||||
|
||||
@subsection block-dirty-bitmap-add "autoload" parameter (since 4.2.0)
|
||||
|
||||
The "autoload" parameter has been ignored since 2.12.0. All bitmaps
|
||||
are automatically loaded from qcow2 images.
|
||||
|
||||
@section Related binaries
|
||||
|
||||
@subsection qemu-nbd --partition (removed in 5.0.0)
|
||||
|
||||
The ``qemu-nbd --partition $digit'' code (also spelled @option{-P})
|
||||
could only handle MBR partitions, and never correctly handled logical
|
||||
partitions beyond partition 5. Exporting a partition can still be
|
||||
done by utilizing the @option{--image-opts} option with a raw blockdev
|
||||
using the @code{offset} and @code{size} parameters layered on top of
|
||||
any other existing blockdev. For example, if partition 1 is 100MiB
|
||||
long starting at 1MiB, the old command:
|
||||
|
||||
@code{qemu-nbd -t -P 1 -f qcow2 file.qcow2}
|
||||
|
||||
can be rewritten as:
|
||||
|
||||
@code{qemu-nbd -t --image-opts driver=raw,offset=1M,size=100M,file.driver=qcow2,file.file.driver=file,file.file.filename=file.qcow2}
|
2967
qemu-doc.texi
2967
qemu-doc.texi
File diff suppressed because it is too large
Load diff
|
@ -1,28 +0,0 @@
|
|||
@c The contents of this file must be kept in sync with qemu-option-trace.rst.inc
|
||||
@c until all the users of the texi file have been converted to rst and
|
||||
@c the texi file can be removed.
|
||||
|
||||
Specify tracing options.
|
||||
|
||||
@table @option
|
||||
@item [enable=]@var{pattern}
|
||||
Immediately enable events matching @var{pattern}
|
||||
(either event name or a globbing pattern). This option is only
|
||||
available if QEMU has been compiled with the @var{simple}, @var{log}
|
||||
or @var{ftrace} tracing backend. To specify multiple events or patterns,
|
||||
specify the @option{-trace} option multiple times.
|
||||
|
||||
Use @code{-trace help} to print a list of names of trace points.
|
||||
|
||||
@item events=@var{file}
|
||||
Immediately enable events listed in @var{file}.
|
||||
The file must contain one event name (as listed in the @file{trace-events-all}
|
||||
file) per line; globbing patterns are accepted too. This option is only
|
||||
available if QEMU has been compiled with the @var{simple}, @var{log} or
|
||||
@var{ftrace} tracing backend.
|
||||
|
||||
@item file=@var{file}
|
||||
Log output traces to @var{file}.
|
||||
This option is only available if QEMU has been compiled with
|
||||
the @var{simple} tracing backend.
|
||||
@end table
|
6813
qemu-options.hx
6813
qemu-options.hx
File diff suppressed because it is too large
Load diff
195
qemu-tech.texi
195
qemu-tech.texi
|
@ -1,195 +0,0 @@
|
|||
@node Implementation notes
|
||||
@appendix Implementation notes
|
||||
|
||||
@menu
|
||||
* CPU emulation::
|
||||
* Managed start up options::
|
||||
@end menu
|
||||
|
||||
@node CPU emulation
|
||||
@section CPU emulation
|
||||
|
||||
@menu
|
||||
* x86:: x86 and x86-64 emulation
|
||||
* ARM:: ARM emulation
|
||||
* MIPS:: MIPS emulation
|
||||
* PPC:: PowerPC emulation
|
||||
* SPARC:: Sparc32 and Sparc64 emulation
|
||||
* Xtensa:: Xtensa emulation
|
||||
@end menu
|
||||
|
||||
@node x86
|
||||
@subsection x86 and x86-64 emulation
|
||||
|
||||
QEMU x86 target features:
|
||||
|
||||
@itemize
|
||||
|
||||
@item The virtual x86 CPU supports 16 bit and 32 bit addressing with segmentation.
|
||||
LDT/GDT and IDT are emulated. VM86 mode is also supported to run
|
||||
DOSEMU. There is some support for MMX/3DNow!, SSE, SSE2, SSE3, SSSE3,
|
||||
and SSE4 as well as x86-64 SVM.
|
||||
|
||||
@item Support of host page sizes bigger than 4KB in user mode emulation.
|
||||
|
||||
@item QEMU can emulate itself on x86.
|
||||
|
||||
@item An extensive Linux x86 CPU test program is included @file{tests/test-i386}.
|
||||
It can be used to test other x86 virtual CPUs.
|
||||
|
||||
@end itemize
|
||||
|
||||
Current QEMU limitations:
|
||||
|
||||
@itemize
|
||||
|
||||
@item Limited x86-64 support.
|
||||
|
||||
@item IPC syscalls are missing.
|
||||
|
||||
@item The x86 segment limits and access rights are not tested at every
|
||||
memory access (yet). Hopefully, very few OSes seem to rely on that for
|
||||
normal use.
|
||||
|
||||
@end itemize
|
||||
|
||||
@node ARM
|
||||
@subsection ARM emulation
|
||||
|
||||
@itemize
|
||||
|
||||
@item Full ARM 7 user emulation.
|
||||
|
||||
@item NWFPE FPU support included in user Linux emulation.
|
||||
|
||||
@item Can run most ARM Linux binaries.
|
||||
|
||||
@end itemize
|
||||
|
||||
@node MIPS
|
||||
@subsection MIPS emulation
|
||||
|
||||
@itemize
|
||||
|
||||
@item The system emulation allows full MIPS32/MIPS64 Release 2 emulation,
|
||||
including privileged instructions, FPU and MMU, in both little and big
|
||||
endian modes.
|
||||
|
||||
@item The Linux userland emulation can run many 32 bit MIPS Linux binaries.
|
||||
|
||||
@end itemize
|
||||
|
||||
Current QEMU limitations:
|
||||
|
||||
@itemize
|
||||
|
||||
@item Self-modifying code is not always handled correctly.
|
||||
|
||||
@item 64 bit userland emulation is not implemented.
|
||||
|
||||
@item The system emulation is not complete enough to run real firmware.
|
||||
|
||||
@item The watchpoint debug facility is not implemented.
|
||||
|
||||
@end itemize
|
||||
|
||||
@node PPC
|
||||
@subsection PowerPC emulation
|
||||
|
||||
@itemize
|
||||
|
||||
@item Full PowerPC 32 bit emulation, including privileged instructions,
|
||||
FPU and MMU.
|
||||
|
||||
@item Can run most PowerPC Linux binaries.
|
||||
|
||||
@end itemize
|
||||
|
||||
@node SPARC
|
||||
@subsection Sparc32 and Sparc64 emulation
|
||||
|
||||
@itemize
|
||||
|
||||
@item Full SPARC V8 emulation, including privileged
|
||||
instructions, FPU and MMU. SPARC V9 emulation includes most privileged
|
||||
and VIS instructions, FPU and I/D MMU. Alignment is fully enforced.
|
||||
|
||||
@item Can run most 32-bit SPARC Linux binaries, SPARC32PLUS Linux binaries and
|
||||
some 64-bit SPARC Linux binaries.
|
||||
|
||||
@end itemize
|
||||
|
||||
Current QEMU limitations:
|
||||
|
||||
@itemize
|
||||
|
||||
@item IPC syscalls are missing.
|
||||
|
||||
@item Floating point exception support is buggy.
|
||||
|
||||
@item Atomic instructions are not correctly implemented.
|
||||
|
||||
@item There are still some problems with Sparc64 emulators.
|
||||
|
||||
@end itemize
|
||||
|
||||
@node Xtensa
|
||||
@subsection Xtensa emulation
|
||||
|
||||
@itemize
|
||||
|
||||
@item Core Xtensa ISA emulation, including most options: code density,
|
||||
loop, extended L32R, 16- and 32-bit multiplication, 32-bit division,
|
||||
MAC16, miscellaneous operations, boolean, FP coprocessor, coprocessor
|
||||
context, debug, multiprocessor synchronization,
|
||||
conditional store, exceptions, relocatable vectors, unaligned exception,
|
||||
interrupts (including high priority and timer), hardware alignment,
|
||||
region protection, region translation, MMU, windowed registers, thread
|
||||
pointer, processor ID.
|
||||
|
||||
@item Not implemented options: data/instruction cache (including cache
|
||||
prefetch and locking), XLMI, processor interface. Also options not
|
||||
covered by the core ISA (e.g. FLIX, wide branches) are not implemented.
|
||||
|
||||
@item Can run most Xtensa Linux binaries.
|
||||
|
||||
@item New core configuration that requires no additional instructions
|
||||
may be created from overlay with minimal amount of hand-written code.
|
||||
|
||||
@end itemize
|
||||
|
||||
@node Managed start up options
|
||||
@section Managed start up options
|
||||
|
||||
In system mode emulation, it's possible to create a VM in a paused state using
|
||||
the -S command line option. In this state the machine is completely initialized
|
||||
according to command line options and ready to execute VM code but VCPU threads
|
||||
are not executing any code. The VM state in this paused state depends on the way
|
||||
QEMU was started. It could be in:
|
||||
@table @asis
|
||||
@item initial state (after reset/power on state)
|
||||
@item with direct kernel loading, the initial state could be amended to execute
|
||||
code loaded by QEMU in the VM's RAM and with incoming migration
|
||||
@item with incoming migration, initial state will by amended with the migrated
|
||||
machine state after migration completes.
|
||||
@end table
|
||||
|
||||
This paused state is typically used by users to query machine state and/or
|
||||
additionally configure the machine (by hotplugging devices) in runtime before
|
||||
allowing VM code to run.
|
||||
|
||||
However, at the -S pause point, it's impossible to configure options that affect
|
||||
initial VM creation (like: -smp/-m/-numa ...) or cold plug devices. The
|
||||
experimental --preconfig command line option allows pausing QEMU
|
||||
before the initial VM creation, in a ``preconfig'' state, where additional
|
||||
queries and configuration can be performed via QMP before moving on to
|
||||
the resulting configuration startup. In the preconfig state, QEMU only allows
|
||||
a limited set of commands over the QMP monitor, where the commands do not
|
||||
depend on an initialized machine, including but not limited to:
|
||||
@table @asis
|
||||
@item qmp_capabilities
|
||||
@item query-qmp-schema
|
||||
@item query-commands
|
||||
@item query-status
|
||||
@item x-exit-preconfig
|
||||
@end table
|
137
scripts/hxtool-conv.pl
Executable file
137
scripts/hxtool-conv.pl
Executable file
|
@ -0,0 +1,137 @@
|
|||
#!/usr/bin/perl -w
|
||||
#
|
||||
# Script to convert .hx file STEXI/ETEXI blocks to SRST/ERST
|
||||
#
|
||||
# Copyright (C) 2020 Linaro
|
||||
#
|
||||
# This work is licensed under the terms of the GNU GPL, version 2 or
|
||||
# (at your option) any later version. See the COPYING file in the
|
||||
# top-level directory.
|
||||
|
||||
# This script was only ever intended as a one-off conversion operation.
|
||||
# Please excuse the places where it is a bit hacky.
|
||||
# Some manual intervention after the conversion is expected, as are
|
||||
# some warnings from makeinfo.
|
||||
# Warning: this script is not idempotent: don't try to run it on
|
||||
# a .hx file that already has SRST/ERST sections.
|
||||
|
||||
# Expected usage:
|
||||
# scripts/hxtool-conv.pl file.hx > file.hx.new
|
||||
|
||||
use utf8;
|
||||
|
||||
my $reading_texi = 0;
|
||||
my $texiblock = '';
|
||||
my @tables = ();
|
||||
|
||||
sub update_tables($) {
|
||||
my ($texi) = @_;
|
||||
# Update our list of open table directives: every @table
|
||||
# line in the texi fragment is added to the list, and every
|
||||
# @end table line means we remove an entry from the list.
|
||||
# If this fragment had a completely self contained table with
|
||||
# both the @table and @end table lines, this will be a no-op.
|
||||
foreach (split(/\n/, $texi)) {
|
||||
push @tables, $_ if /^\@table/;
|
||||
pop @tables if /^\@end table/;
|
||||
}
|
||||
}
|
||||
|
||||
sub only_table_directives($) {
|
||||
# Return true if every line in the fragment is a start or end table directive
|
||||
my ($texi) = @_;
|
||||
foreach (split(/\n/, $texi)) {
|
||||
return 0 unless /^\@table/ or /^\@end table/;
|
||||
}
|
||||
return 1;
|
||||
}
|
||||
|
||||
sub output_rstblock($) {
|
||||
# Write the output to /tmp/frag.texi, wrapped in whatever current @table
|
||||
# lines we need.
|
||||
my ($texi) = @_;
|
||||
|
||||
# As a special case, if this fragment is only table directives and
|
||||
# nothing else, update our set of open table directives but otherwise
|
||||
# ignore it. This avoids emitting an empty SRST/ERST block.
|
||||
if (only_table_directives($texi)) {
|
||||
update_tables($texi);
|
||||
return;
|
||||
}
|
||||
|
||||
open(my $fragfh, '>', '/tmp/frag.texi');
|
||||
# First output the currently active set of open table directives
|
||||
print $fragfh join("\n", @tables);
|
||||
# Next, update our list of open table directives.
|
||||
# We need to do this before we emit the closing table directives
|
||||
# so that we emit the right number if this fragment had an
|
||||
# unbalanced set of directives.
|
||||
update_tables($texi);
|
||||
# Then emit the texi fragment itself.
|
||||
print $fragfh "\n$texi\n";
|
||||
# Finally, add the necessary closing table directives.
|
||||
print $fragfh "\@end table\n" x scalar @tables;
|
||||
close $fragfh;
|
||||
|
||||
# Now invoke makeinfo/pandoc on it and slurp the results into a string
|
||||
open(my $fh, '-|', "makeinfo --force -o - --docbook "
|
||||
. "-D 'qemu_system_x86 QEMU_SYSTEM_X86_MACRO' "
|
||||
. "-D 'qemu_system QEMU_SYSTEM_MACRO' /tmp/frag.texi "
|
||||
. " | pandoc -f docbook -t rst")
|
||||
or die "can't start makeinfo/pandoc: $!";
|
||||
|
||||
binmode $fh, ':encoding(utf8)';
|
||||
|
||||
print "SRST\n";
|
||||
|
||||
# Slurp the whole thing into a string so we can do multiline
|
||||
# string matches on it.
|
||||
my $rst = do {
|
||||
local $/ = undef;
|
||||
<$fh>;
|
||||
};
|
||||
$rst =~ s/^- − /- /gm;
|
||||
$rst =~ s/“/"/gm;
|
||||
$rst =~ s/”/"/gm;
|
||||
$rst =~ s/‘/'/gm;
|
||||
$rst =~ s/’/'/gm;
|
||||
$rst =~ s/QEMU_SYSTEM_MACRO/|qemu_system|/g;
|
||||
$rst =~ s/QEMU_SYSTEM_X86_MACRO/|qemu_system_x86|/g;
|
||||
$rst =~ s/(?=::\n\n +\|qemu)/.. parsed-literal/g;
|
||||
$rst =~ s/:\n\n::$/::/gm;
|
||||
|
||||
# Fix up the invalid reference format makeinfo/pandoc emit:
|
||||
# `Some string here <#anchorname>`__
|
||||
# should be:
|
||||
# :ref:`anchorname`
|
||||
$rst =~ s/\`[^<`]+\<\#([^>]+)\>\`__/:ref:`$1`/gm;
|
||||
print $rst;
|
||||
|
||||
close $fh or die "error on close: $!";
|
||||
print "ERST\n";
|
||||
}
|
||||
|
||||
# Read the whole .hx input file.
|
||||
while (<>) {
|
||||
# Always print the current line
|
||||
print;
|
||||
if (/STEXI/) {
|
||||
$reading_texi = 1;
|
||||
$texiblock = '';
|
||||
next;
|
||||
}
|
||||
if (/ETEXI/) {
|
||||
$reading_texi = 0;
|
||||
# dump RST version of block
|
||||
output_rstblock($texiblock);
|
||||
next;
|
||||
}
|
||||
if ($reading_texi) {
|
||||
# Accumulate the texi into a string
|
||||
# but drop findex entries as they will confuse makeinfo
|
||||
next if /^\@findex/;
|
||||
$texiblock .= $_;
|
||||
}
|
||||
}
|
||||
|
||||
die "Unexpectedly still in texi block at EOF" if $reading_texi;
|
|
@ -143,6 +143,24 @@ while(<$inf>) {
|
|||
next;
|
||||
};
|
||||
|
||||
# Single line command handlers.
|
||||
|
||||
/^\@include\s+(.+)$/ and do {
|
||||
push @instack, $inf;
|
||||
$inf = gensym();
|
||||
$file = postprocess($1);
|
||||
|
||||
# Try cwd and $ibase, then explicit -I paths.
|
||||
$done = 0;
|
||||
foreach $path ("", $ibase, @ipath) {
|
||||
$mypath = $file;
|
||||
$mypath = $path . "/" . $mypath if ($path ne "");
|
||||
open($inf, "<" . $mypath) and ($done = 1, last);
|
||||
}
|
||||
die "cannot find $file" if !$done;
|
||||
next;
|
||||
};
|
||||
|
||||
next unless $output;
|
||||
|
||||
# Discard comments. (Can't do it above, because then we'd never see
|
||||
|
@ -242,24 +260,6 @@ while(<$inf>) {
|
|||
s/>/>/g;
|
||||
}
|
||||
|
||||
# Single line command handlers.
|
||||
|
||||
/^\@include\s+(.+)$/ and do {
|
||||
push @instack, $inf;
|
||||
$inf = gensym();
|
||||
$file = postprocess($1);
|
||||
|
||||
# Try cwd and $ibase, then explicit -I paths.
|
||||
$done = 0;
|
||||
foreach $path ("", $ibase, @ipath) {
|
||||
$mypath = $file;
|
||||
$mypath = $path . "/" . $mypath if ($path ne "");
|
||||
open($inf, "<" . $mypath) and ($done = 1, last);
|
||||
}
|
||||
die "cannot find $file" if !$done;
|
||||
next;
|
||||
};
|
||||
|
||||
/^\@(?:section|unnumbered|unnumberedsec|center)\s+(.+)$/
|
||||
and $_ = "\n=head2 $1\n";
|
||||
/^\@subsection\s+(.+)$/
|
||||
|
|
|
@ -1174,7 +1174,7 @@ QemuCocoaView *cocoaView;
|
|||
- (void) openDocumentation: (NSString *) filename
|
||||
{
|
||||
/* Where to look for local files */
|
||||
NSString *path_array[] = {@"../share/doc/qemu/", @"../doc/qemu/", @"../"};
|
||||
NSString *path_array[] = {@"../share/doc/qemu/", @"../doc/qemu/", @"../docs/"};
|
||||
NSString *full_file_path;
|
||||
|
||||
/* iterate thru the possible paths until the file is found */
|
||||
|
@ -1198,7 +1198,7 @@ QemuCocoaView *cocoaView;
|
|||
{
|
||||
COCOA_DEBUG("QemuCocoaAppController: showQEMUDoc\n");
|
||||
|
||||
[self openDocumentation: @"qemu-doc.html"];
|
||||
[self openDocumentation: @"index.html"];
|
||||
}
|
||||
|
||||
/* Stretches video to fit host monitor size */
|
||||
|
|
Loading…
Reference in a new issue