From nobody Sun Oct 5 14:49:28 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1583494364; cv=none; d=zohomail.com; s=zohoarc; b=Vk0MlesV16nqW01Sqyn1dBE5rK+VnzKhjg8jMepqH9s0Ytxu1Sm8Jho+NQdkidU2qzKQKAxGzfjiPtrkDpyGs2S16Y40Kg7olBQhg+8Y8eEaxUlDCn1lIcZ6UdTbC/cBnD4ae133pX/C0Mdjp95ix4xFv1N6xIjNhS1HaZx/etI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1583494364; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=Sk8cSM7Yejh31Gk1qWQTclu8KbqArG7abi93tvvPOO0=; b=cJtUwQrpqFMrSIvZ+JNURz+pcJM8xZBLYI/k83DdDJSnV9r0T9/n9f+sOe3bFcXtwkMvN7He1j02GbhbNOUmw+Q5ie+GwvUSonVtIBDMzE6GS4G49axobA3alDGH1X1cuL4BbzSKFwsTBwG0oFsWJSEkq6W4PCPmv5USGLT/7Po= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1583494364363805.4636107987293; Fri, 6 Mar 2020 03:32:44 -0800 (PST) Received: from localhost ([::1]:35346 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jABDd-0005bE-P0 for importer@patchew.org; Fri, 06 Mar 2020 06:32:41 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:40341) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jAAsq-0004lm-Hu for qemu-devel@nongnu.org; Fri, 06 Mar 2020 06:11:22 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jAAsg-0006RJ-80 for qemu-devel@nongnu.org; Fri, 06 Mar 2020 06:11:12 -0500 Received: from mail-wr1-x42f.google.com ([2a00:1450:4864:20::42f]:34244) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1jAAse-0006NA-Cg for qemu-devel@nongnu.org; Fri, 06 Mar 2020 06:11:01 -0500 Received: by mail-wr1-x42f.google.com with SMTP id z15so1884870wrl.1 for ; Fri, 06 Mar 2020 03:11:00 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id y10sm12553029wma.26.2020.03.06.03.10.49 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 06 Mar 2020 03:10:52 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:subject:date:message-id:in-reply-to:references:mime-version :content-transfer-encoding; bh=Sk8cSM7Yejh31Gk1qWQTclu8KbqArG7abi93tvvPOO0=; b=YL7KV6MY81CcirN6Fh/mMLZZUmleq/59iijbyAuiu5nS+JKQMKZqeQmeHiq5zlWWiB xNIP3zKnbP+hyUgn+vSx5QdolrA2AzMkDapZqJ4gc0ZI8HlhFlERU6jHbTQDT7lR3X72 Z8YIxTTrJzHEv9ZHo+kAduHoa0cp6bzsG0V755ln92Eep6tmmTBaSqlHJmBeG5S4XX5I NjCCy0S+0BIRAQfOrRW5SU53r4xapEtpemomJZJMC557ruUSQiWevq2tH8KL7PsSt+HC pRJ91CRr+HKnKAE2FueKgbeqDBOqFZSQ8QNDgXAZklgb9ldliXCJE5Zfaxf/oLbsVWti 48Rw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=Sk8cSM7Yejh31Gk1qWQTclu8KbqArG7abi93tvvPOO0=; b=jHcZWdUNUOfbyclgmHwPN3wGuF4rjVN5TtBt/Berf8zuGoX+E//bQRTJUTtMMINp8D OtQBc3BdEul2weEHOJpwtC6z9MkwWcA69wCkPEb+pV7I3pCX/3wUsPwOP1WovHC8xK/k sf5P/CBs0a4Q9D98FqH6LKnG/3KJA8hf0Wwu5GY8TcsRVX/QR4cjrWW+tSuXeETdm2fQ ccz3T+d4rYK1Cm/UqAMP9JwDPxcB/Z2g0aMr7dGk0nhGpcur1I69yzBTv+J7pHg8AWCZ 8UwU4ntmOhqm461tmsJBpVyy8guEg4jUmM4MH+oRoIaqwbzMv1DhaWYq0PXXwpIeTyfo 9eTw== X-Gm-Message-State: ANhLgQ22RKvYZT6IAZ9NtxynbZoR3O95IkPNnKmO0U/9NBTSZXhd8l4J FXuREUmGYqciiUuFV1rcowUZhMqJrgdcuQ== X-Google-Smtp-Source: ADFU+vtOtUfeLdX6mfkvaY5yjoPeDXyQswqtSGkrsax2kgsGl56gRr0+UjOESjm5PVvekf7IiMyUPw== X-Received: by 2002:adf:e38d:: with SMTP id e13mr3410878wrm.133.1583493052948; Fri, 06 Mar 2020 03:10:52 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PULL 32/33] docs: Remove old texinfo sources Date: Fri, 6 Mar 2020 11:09:58 +0000 Message-Id: <20200306110959.29461-33-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200306110959.29461-1-peter.maydell@linaro.org> References: <20200306110959.29461-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::42f X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) We can now delete the old .texi files, which we have been keeping in the tree as a parallel set of documentation to the new rST sources. The only remaining use of Texinfo is the autogenerated manuals and HTML documents created from the QAPI JSON doc comments. Signed-off-by: Peter Maydell Reviewed-by: Alex Benn=C3=A9e Reviewed-by: Kashyap Chamarthy Tested-by: Alex Benn=C3=A9e Message-id: 20200228153619.9906-33-peter.maydell@linaro.org --- MAINTAINERS | 5 +- docs/system/build-platforms.texi | 67 ---- docs/system/cpu-models-mips.texi | 157 ---------- docs/system/cpu-models-x86.texi | 482 ----------------------------- docs/system/deprecated.texi | 377 ---------------------- docs/system/gdb.texi | 71 ----- docs/system/images.texi | 88 ------ docs/system/invocation.texi | 240 -------------- docs/system/ivshmem.texi | 60 ---- docs/system/keys.texi | 43 --- docs/system/license.texi | 9 - docs/system/linuxboot.texi | 27 -- docs/system/managed-startup.texi | 35 --- docs/system/monitor.texi | 34 -- docs/system/mux-chardev.texi | 44 --- docs/system/net.texi | 96 ------ docs/system/qemu-option-trace.texi | 28 -- docs/system/quickstart.texi | 12 - docs/system/security.texi | 167 ---------- docs/system/target-arm.texi | 245 --------------- docs/system/target-i386.texi | 91 ------ docs/system/target-m68k.texi | 25 -- docs/system/target-mips.texi | 150 --------- docs/system/target-ppc.texi | 52 ---- docs/system/target-sparc.texi | 68 ---- docs/system/target-sparc64.texi | 38 --- docs/system/target-xtensa.texi | 35 --- docs/system/tls.texi | 329 -------------------- docs/system/usb.texi | 115 ------- docs/system/vnc-security.texi | 196 ------------ qemu-doc.texi | 201 ------------ 31 files changed, 1 insertion(+), 3586 deletions(-) delete mode 100644 docs/system/build-platforms.texi delete mode 100644 docs/system/cpu-models-mips.texi delete mode 100644 docs/system/cpu-models-x86.texi delete mode 100644 docs/system/deprecated.texi delete mode 100644 docs/system/gdb.texi delete mode 100644 docs/system/images.texi delete mode 100644 docs/system/invocation.texi delete mode 100644 docs/system/ivshmem.texi delete mode 100644 docs/system/keys.texi delete mode 100644 docs/system/license.texi delete mode 100644 docs/system/linuxboot.texi delete mode 100644 docs/system/managed-startup.texi delete mode 100644 docs/system/monitor.texi delete mode 100644 docs/system/mux-chardev.texi delete mode 100644 docs/system/net.texi delete mode 100644 docs/system/qemu-option-trace.texi delete mode 100644 docs/system/quickstart.texi delete mode 100644 docs/system/security.texi delete mode 100644 docs/system/target-arm.texi delete mode 100644 docs/system/target-i386.texi delete mode 100644 docs/system/target-m68k.texi delete mode 100644 docs/system/target-mips.texi delete mode 100644 docs/system/target-ppc.texi delete mode 100644 docs/system/target-sparc.texi delete mode 100644 docs/system/target-sparc64.texi delete mode 100644 docs/system/target-xtensa.texi delete mode 100644 docs/system/tls.texi delete mode 100644 docs/system/usb.texi delete mode 100644 docs/system/vnc-security.texi delete mode 100644 qemu-doc.texi diff --git a/MAINTAINERS b/MAINTAINERS index 4cdd2d52767..36d0c6887a9 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -215,7 +215,6 @@ S: Maintained F: target/mips/ F: default-configs/*mips* F: disas/*mips* -F: docs/system/cpu-models-mips.texi F: docs/system/cpu-models-mips.rst.inc F: hw/intc/mips_gic.c F: hw/mips/ @@ -321,7 +320,6 @@ F: tests/tcg/i386/ F: tests/tcg/x86_64/ F: hw/i386/ F: disas/i386.c -F: docs/system/cpu-models-x86.texi F: docs/system/cpu-models-x86.rst.inc T: git https://github.com/ehabkost/qemu.git x86-next =20 @@ -2236,7 +2234,7 @@ M: Stefan Hajnoczi S: Maintained F: trace/ F: trace-events -F: docs/system/qemu-option-trace.texi +F: docs/qemu-option-trace.rst.inc F: scripts/tracetool.py F: scripts/tracetool/ F: scripts/qemu-trace-stap* @@ -2806,7 +2804,6 @@ F: contrib/gitdm/* =20 Incompatible changes R: libvir-list@redhat.com -F: docs/system/deprecated.texi F: docs/system/deprecated.rst =20 Build System diff --git a/docs/system/build-platforms.texi b/docs/system/build-platforms= .texi deleted file mode 100644 index 531ef5bed44..00000000000 --- a/docs/system/build-platforms.texi +++ /dev/null @@ -1,67 +0,0 @@ -@node Supported build platforms -@appendix 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 platf= orm, -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 wor= ds, -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 @url{https://repology.org} is a useful resource to ident= ify -currently shipped versions of software in various operating systems, though -it does not cover all distros listed below. - -@section 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 sup= port -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. - -@section Windows - -The project supports building with current versions of the MinGW toolchain, -hosted on Linux. - -@section macOS - -The project supports building with the two most recent versions of macOS, = with -the current homebrew package set available. - -@section FreeBSD - -The project aims to support the all the versions which are not end of life. - -@section NetBSD - -The project aims to support the most recent major version at all times. Su= pport -for the previous major version will be dropped 2 years after the new major -version is released. - -@section OpenBSD - -The project aims to support the all the versions which are not end of life. diff --git a/docs/system/cpu-models-mips.texi b/docs/system/cpu-models-mips= .texi deleted file mode 100644 index 6a0370cb693..00000000000 --- a/docs/system/cpu-models-mips.texi +++ /dev/null @@ -1,157 +0,0 @@ -@node recommendations_cpu_models_MIPS -@section 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 -@subsection Supported CPU models for MIPS32 hosts - -The following CPU models are supported for use on MIPS32 hosts. Administra= tors / -applications are recommended to use the CPU model that matches the generat= ion -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 new= est -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 -@subsection Supported CPU models for MIPS64 hosts - -The following CPU models are supported for use on MIPS64 hosts. Administra= tors / -applications are recommended to use the CPU model that matches the generat= ion -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 new= est -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 -@subsection Supported CPU models for nanoMIPS hosts - -The following CPU models are supported for use on nanoMIPS hosts. Administ= rators / -applications are recommended to use the CPU model that matches the generat= ion -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 new= est -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 -@subsection 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 diff --git a/docs/system/cpu-models-x86.texi b/docs/system/cpu-models-x86.t= exi deleted file mode 100644 index 0cd64b0522e..00000000000 --- a/docs/system/cpu-models-x86.texi +++ /dev/null @@ -1,482 +0,0 @@ -@node cpu_models_x86 -@section Recommendations for KVM CPU model configuration on x86 hosts - -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 fam= ily, -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. - -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 x8= 6 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 x8= 6 hosts -* default_cpu_models_x86:: Default x86 CPU models -* other_non_recommended_cpu_models_x86:: Other non-recommended x86 CPUs -* cpu_model_syntax_apps:: Syntax for configuring CPU models -@end menu - -@node preferred_cpu_models_intel_x86 -@subsection Preferred CPU models for Intel x86 hosts - -The following CPU models are preferred for use on Intel hosts. Administrat= ors / -applications are recommended to use the CPU model that matches the generat= ion -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 new= est -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 -@subsection 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 a= ll, -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-1213= 0, -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 -@subsection Preferred CPU models for AMD x86 hosts - -The following CPU models are preferred for use on Intel hosts. Administrat= ors / -applications are recommended to use the CPU model that matches the generat= ion -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 new= est -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 -@subsection 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 a= ll, -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 -@subsection Default x86 CPU models - -The default QEMU CPU models are designed such that they can run on all hos= ts. -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 var= ious -CPU hardware flaws, so their use is strongly discouraged. Applications sho= uld -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 is provided in libvirt XML. -@end table - - -@node other_non_recommended_cpu_models_x86 -@subsection 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 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. - -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 - - -Libvirt guest XML: - -@table @option - -@item Host passthrough - -@example - -@end example - -With feature customization: - -@example - - - ... - -@end example - -@item Host model - -@example - -@end example - -With feature customization: - -@example - - - ... - -@end example - -@item Named model - -@example - - - -@end example - -With feature customization: - -@example - - - - ... - -@end example - -@end table diff --git a/docs/system/deprecated.texi b/docs/system/deprecated.texi deleted file mode 100644 index 66eca3a1ded..00000000000 --- a/docs/system/deprecated.texi +++ /dev/null @@ -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=3Don|off (since 3.1) - -The @option{enforce-config-section} parameter is replaced by the -@option{-global migration.send-configuration=3D@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=3Don'' argument. - -@subsection -drive file=3Djson:@{...@{'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=3D@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 topo= logy -where @math{@var{n} <=3D @var{sockets} * @var{cores} * @var{threads} < @va= r{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} =3D @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=3D proper= ty (since 4.2) - -When not using the deprecated legacy audio config, each sound card -should specify an @code{audiodev=3D} property. Additionally, when using -vnc, you should specify an @code{audiodev=3D} propery if you plan to -transmit audio through the VNC protocol. - -@subsection -mon ...,control=3Dreadline,pretty=3Don|off (since 4.1) - -The @code{pretty=3Don|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=3Don|off} argument has been replaced by the -@code{-overcommit mem-lock=3Don|off} argument. - -@subsection -numa node,mem=3D@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 spe= cified -RAM chunk on the host side (like bind it to a host node, setting bind poli= cy, ...), -so guest end-ups with the fake NUMA configuration with suboptiomal perform= ance. -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 a= dds -means to actualy manage node RAM on the host side. Use parameter @option{m= emdev} -with @var{memory-backend-ram} backend as an replacement for parameter @opt= ion{mem} -to achieve the same fake NUMA effect or a properly configured -@var{memory-backend-file} backend to actually benefit from NUMA configurat= ion. -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 lega= cy -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 pl= ays -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 u= sers -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 opti= on - 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 defa= ult - 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 nee= ds - to do is specify the kernel they want to boot with the -kernel option - 3. ``-bios `` - Tells QEMU to load the specified file as the firmwr= ae. - -@subsection -tb-size option (since 5.0) - -QEMU 5.0 introduced an alternative syntax to specify the size of the trans= lation -block cache, @option{-accel tcg,tb-size=3D}. The new syntax deprecates the -previously available @option{-tb-size} option. - -@subsection -show-cursor option (since 5.0) - -Use @option{-display sdl,show-cursor=3Don} or - @option{-display gtk,show-cursor=3Don} 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.1= 1.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 t= he -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' (sinc= e 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 ``p= riv_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-nom= mu`` and -``rv64imacu-nommu`` should no longer be used. Instead the MMU status can b= e 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 'malt= a' -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 migra= tion -from old QEMU versions anymore. A newer machine type should be used instea= d. - -@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=3Dv1.9.1`` command line arg= ument. - -@section Device options - -@subsection Emulated device options - -@subsubsection -device virtio-blk,scsi=3Don|off (since 5.0.0) - -The virtio-blk SCSI passthrough feature is a legacy VIRTIO feature. VIRTI= O 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 requi= red. - -Note this also applies to ``-device virtio-blk-pci,scsi=3Don|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=3Draw,offset=3D1M,size=3D100M,file.d= river=3Dqcow2,file.file.driver=3Dfile,file.file.filename=3Dfile.qcow2} diff --git a/docs/system/gdb.texi b/docs/system/gdb.texi deleted file mode 100644 index f49bc5891e9..00000000000 --- a/docs/system/gdb.texi +++ /dev/null @@ -1,71 +0,0 @@ -@node gdb_usage -@section 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: -@example -@value{qemu_system} -s -kernel bzImage -hda rootdisk.img -append "root=3D/= dev/hda" -Connected to host network interface: tun0 -Waiting gdb connection on port 1234 -@end example - -Then launch gdb on the 'vmlinux' executable: -@example -> gdb vmlinux -@end example - -In gdb, connect to QEMU: -@example -(gdb) target remote localhost:1234 -@end example - -Then you can use gdb normally. For example, type 'c' to launch the kernel: -@example -(gdb) c -@end example - -Here are some useful tips in order to use gdb on system code: - -@enumerate -@item -Use @code{info reg} to display all the CPU registers. -@item -Use @code{x/10i $eip} to display the code at the PC position. -@item -Use @code{set architecture i8086} to dump 16 bit code. Then use -@code{x/10i $cs*16+$eip} to dump the code at the PC position. -@end enumerate - -Advanced debugging options: - -The default single stepping behavior is step with the IRQs and timer servi= ce routines off. It is set this way because when gdb executes a single ste= p 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 int= errupt or exception vectors instead of executing the current instruction. T= his means you may hit the same breakpoint a number of times before executin= g the instruction gdb wants to have executed. Because there are rare circu= mstances where you want to single step into an interrupt vector the behavio= r can be controlled from GDB. There are three commands you can query and s= et the single step behavior: -@table @code -@item maintenance packet qqemu.sstepbits - -This will display the MASK bits used to control the single stepping IE: -@example -(gdb) maintenance packet qqemu.sstepbits -sending: "qqemu.sstepbits" -received: "ENABLE=3D1,NOIRQ=3D2,NOTIMER=3D4" -@end example -@item maintenance packet qqemu.sstep - -This will display the current value of the mask used when single stepping = IE: -@example -(gdb) maintenance packet qqemu.sstep -sending: "qqemu.sstep" -received: "0x7" -@end example -@item maintenance packet Qqemu.sstep=3DHEX_VALUE - -This will change the single step mask, so if wanted to enable IRQs on the = single step, but not timers, you would use: -@example -(gdb) maintenance packet Qqemu.sstep=3D0x5 -sending: "qemu.sstep=3D0x5" -received: "OK" -@end example -@end table - diff --git a/docs/system/images.texi b/docs/system/images.texi deleted file mode 100644 index c5060348ecc..00000000000 --- a/docs/system/images.texi +++ /dev/null @@ -1,88 +0,0 @@ -@node disk_images -@section 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. - -@menu -* disk_images_quickstart:: Quick start for disk image creation -* disk_images_snapshot_mode:: Snapshot mode -* vm_snapshots:: VM snapshots -@end menu - -@node disk_images_quickstart -@subsection Quick start for disk image creation - -You can create a disk image with the command: -@example -qemu-img create myimage.img mysize -@end example -where @var{myimage.img} is the disk image filename and @var{mysize} is its -size in kilobytes. You can add an @code{M} suffix to give the size in -megabytes and a @code{G} suffix for gigabytes. - -@c When this document is converted to rst we should make this into -@c a proper linked reference to the qemu-img documentation again: -See the qemu-img invocation documentation for more information. - -@node disk_images_snapshot_mode -@subsection Snapshot mode - -If you use the option @option{-snapshot}, all disk images are -considered as read only. When sectors in written, they are written in -a temporary file created in @file{/tmp}. You can however force the -write back to the raw disk images by using the @code{commit} monitor -command (or @key{C-a s} in the serial console). - -@node vm_snapshots -@subsection 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 @code{qcow2} disk image -format. Normally this device is the first virtual hard drive. - -Use the monitor command @code{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 @code{loadvm} to restore a VM snapshot and @code{delvm} to remove -a VM snapshot. @code{info snapshots} lists the available snapshots -with their associated information: - -@example -(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 -@end example - -A VM snapshot is made of a VM state info (its size is shown in -@code{info snapshots}) and a snapshot of every writable disk image. -The VM state info is stored in the first @code{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 @code{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) @code{-snapshot} option -(@ref{disk_images_snapshot_mode}), you can always make VM snapshots, -but they are deleted as soon as you exit QEMU. - -VM snapshots currently have the following known limitations: -@itemize -@item -They cannot cope with removable devices if they are removed or -inserted after a snapshot is done. -@item -A few device drivers still have incomplete snapshot support so their -state is not saved or restored properly (in particular USB). -@end itemize - diff --git a/docs/system/invocation.texi b/docs/system/invocation.texi deleted file mode 100644 index dac41cc7e55..00000000000 --- a/docs/system/invocation.texi +++ /dev/null @@ -1,240 +0,0 @@ -@node sec_invocation -@section Invocation - -@example -@c man begin SYNOPSIS -@command{@value{qemu_system}} [@var{options}] [@var{disk_image}] -@c man end -@end example - -@c man begin OPTIONS -@var{disk_image} is a raw hard disk image for IDE hard disk 0. Some -targets do not need a disk image. - -@include qemu-options.texi - -@c man end - -@subsection Device URL Syntax -@c TODO merge this with section Disk Images - -@c man begin NOTES - -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. - -@table @option -@item 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://[:]//'' - -By default qemu will use the iSCSI initiator-name -'iqn.2008-11.org.linux-kvm[:]' but this can also be set from the com= mand -line or a configuration file. - -Since version Qemu 2.4 it is possible to specify a iSCSI request timeout t= o 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): -@example -@value{qemu_system} -iscsi initiator-name=3Diqn.2001-04.com.example:my-ini= tiator \ - -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \ - -drive file=3Discsi://192.0.2.1/iqn.2001-04.com.example/1 -@end example - -Example (CHAP username/password via URL): -@example -@value{qemu_system} -drive file=3Discsi://user%password@@192.0.2.1/iqn.200= 1-04.com.example/1 -@end example - -Example (CHAP username/password via environment variables): -@example -LIBISCSI_CHAP_USERNAME=3D"user" \ -LIBISCSI_CHAP_PASSWORD=3D"password" \ -@value{qemu_system} -drive file=3Discsi://192.0.2.1/iqn.2001-04.com.exampl= e/1 -@end example - -@item 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://[:]/[]'' - -Syntax for specifying a NBD device using Unix Domain Sockets; remember -that '?' is a shell glob character and may need quoting: -``nbd+unix:///[]?socket=3D'' - -Older syntax that is also recognized: -``nbd::[:exportname=3D]'' - -Syntax for specifying a NBD device using Unix Domain Sockets -``nbd:unix:[:exportname=3D]'' - -Example for TCP -@example -@value{qemu_system} --drive file=3Dnbd:192.0.2.1:30000 -@end example - -Example for Unix Domain Sockets -@example -@value{qemu_system} --drive file=3Dnbd:unix:/tmp/nbd-socket -@end example - -@item SSH -QEMU supports SSH (Secure Shell) access to remote disks. - -Examples: -@example -@value{qemu_system} -drive file=3Dssh://user@@host/path/to/disk.img -@value{qemu_system} -drive file.driver=3Dssh,file.user=3Duser,file.host=3D= host,file.port=3D22,file.path=3D/path/to/disk.img -@end example - -Currently authentication must be done using ssh-agent. Other -authentication methods may be supported in future. - -@item 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 -@example -sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=3Dpath][#snapid|#tag] -@end example - -Example -@example -@value{qemu_system} --drive file=3Dsheepdog://192.0.2.1:30000/MyVirtualMac= hine -@end example - -See also @url{https://sheepdog.github.io/sheepdog/}. - -@item 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 -@example - -URI: -gluster[+type]://[host[:port]]/volume/path[?socket=3D...][,debug=3DN][,log= file=3D...] - -JSON: -'json:@{"driver":"qcow2","file":@{"driver":"gluster","volume":"testvol","p= ath":"a.img","debug":N,"logfile":"...", -@ "server":[@{"type":"tcp","host":"...","p= ort":"..."@}, -@ @{"type":"unix","socket":"..."= @}]@}@}' -@end example - - -Example -@example -URI: -@value{qemu_system} --drive file=3Dgluster://192.0.2.1/testvol/a.img, -@ file.debug=3D9,file.logfile=3D/var/log/qem= u-gluster.log - -JSON: -@value{qemu_system} 'json:@{"driver":"qcow2", -@ "file":@{"driver":"gluster", -@ "volume":"testvol","path":"a.img", -@ "debug":9,"logfile":"/var/log/qemu-glu= ster.log", -@ "server":[@{"type":"tcp","host":"1.2.3= .4","port":24007@}, -@ @{"type":"unix","socket":"/v= ar/run/glusterd.socket"@}]@}@}' -@value{qemu_system} -drive driver=3Dqcow2,file.driver=3Dgluster,file.volum= e=3Dtestvol,file.path=3D/path/a.img, -@ file.debug=3D9,file.logfile=3D/var/= log/qemu-gluster.log, -@ file.server.0.type=3Dtcp,file.serve= r.0.host=3D1.2.3.4,file.server.0.port=3D24007, -@ file.server.1.type=3Dunix,file.serv= er.1.socket=3D/var/run/glusterd.socket -@end example - -See also @url{http://www.gluster.org}. - -@item HTTP/HTTPS/FTP/FTPS -QEMU supports read-only access to files accessed over http(s) and ftp(s). - -Syntax using a single filename: -@example -://[[:]@@]/ -@end example - -where: -@table @option -@item protocol -'http', 'https', 'ftp', or 'ftps'. - -@item username -Optional username for authentication to the remote server. - -@item password -Optional password for authentication to the remote server. - -@item host -Address of the remote server. - -@item path -Path on the remote server, including any query string. -@end table - -The following options are also supported: -@table @option -@item url -The full URL when passing options to the driver explicitly. - -@item readahead -The amount of data to read ahead with each range request to the remote ser= ver. -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. - -@item 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'. - -@item 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. - -@item 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 t= he -image to be downloaded. If not set, the default timeout of 5 seconds is us= ed. -@end table - -Note that when passing options to qemu explicitly, @option{driver} is the = value -of . - -Example: boot from a remote Fedora 20 live ISO image -@example -@value{qemu_system_x86} --drive media=3Dcdrom,file=3Dhttps://archives.fedo= raproject.org/pub/archive/fedora/linux/releases/20/Live/x86_64/Fedora-Live-= Desktop-x86_64-20-1.iso,readonly - -@value{qemu_system_x86} --drive media=3Dcdrom,file.driver=3Dhttp,file.url= =3Dhttp://archives.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_= 64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly -@end example - -Example: boot from a remote Fedora 20 cloud image using a local overlay for -writes, copy-on-read, and a readahead of 64k -@example -qemu-img create -f qcow2 -o backing_file=3D'json:@{"file.driver":"http",, = "file.url":"http://archives.fedoraproject.org/pub/archive/fedora/linux/rele= ases/20/Images/x86_64/Fedora-x86_64-20-20131211.1-sda.qcow2",, "file.readah= ead":"64k"@}' /tmp/Fedora-x86_64-20-20131211.1-sda.qcow2 - -@value{qemu_system_x86} -drive file=3D/tmp/Fedora-x86_64-20-20131211.1-sda= .qcow2,copy-on-read=3Don -@end example - -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 tim= eout -of 10 seconds. -@example -qemu-img create -f qcow2 -o backing_file=3D'json:@{"file.driver":"https",,= "file.url":"https://user:password@@vsphere.example.com/folder/test/test-fl= at.vmdk?dcPath=3DDatacenter&dsName=3Ddatastore1",, "file.sslverify":"off",,= "file.readahead":"64k",, "file.timeout":10@}' /tmp/test.qcow2 - -@value{qemu_system_x86} -drive file=3D/tmp/test.qcow2 -@end example - -@end table - -@c man end - diff --git a/docs/system/ivshmem.texi b/docs/system/ivshmem.texi deleted file mode 100644 index bd97719eaf7..00000000000 --- a/docs/system/ivshmem.texi +++ /dev/null @@ -1,60 +0,0 @@ -@node pcsys_ivshmem -@section Inter-VM Shared Memory device - -On Linux hosts, a shared memory device is available. The basic syntax -is: - -@example -@value{qemu_system_x86} -device ivshmem-plain,memdev=3D@var{hostmem} -@end example - -where @var{hostmem} names a host memory backend. For a POSIX shared -memory backend, use something like - -@example --object memory-backend-file,size=3D1M,share,mem-path=3D/dev/shm/ivshmem,id= =3D@var{hostmem} -@end example - -If desired, interrupts can be sent between guest VMs accessing the same sh= ared -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 s= erver -is qemu.git/contrib/ivshmem-server. An example syntax when using the shar= ed -memory server is: - -@example -# First start the ivshmem server once and for all -ivshmem-server -p @var{pidfile} -S @var{path} -m @var{shm-name} -l @var{sh= m-size} -n @var{vectors} - -# Then start your qemu instances with matching arguments -@value{qemu_system_x86} -device ivshmem-doorbell,vectors=3D@var{vectors},c= hardev=3D@var{id} - -chardev socket,path=3D@var{path},id=3D@var{id} -@end example - -When using the server, the guest will be assigned a VM ID (>=3D0) that all= ows guests -using the same server to communicate via interrupts. Guests can read their -VM ID from a device register (see ivshmem-spec.txt). - -@subsection Migration with ivshmem - -With device property @option{master=3Don}, the guest will copy the shared -memory on migration to the destination host. With @option{master=3Doff}, -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. - -@subsection ivshmem and hugepages - -Instead of specifying the using POSIX shm, you may specify -a memory backend that has hugepage support: - -@example -@value{qemu_system_x86} -object memory-backend-file,size=3D1G,mem-path=3D/= dev/hugepages/my-shmem-file,share,id=3Dmb1 - -device ivshmem-plain,memdev=3Dmb1 -@end example - -ivshmem-server also supports hugepages mount points with the -@option{-m} memory path argument. - diff --git a/docs/system/keys.texi b/docs/system/keys.texi deleted file mode 100644 index c04daf54f23..00000000000 --- a/docs/system/keys.texi +++ /dev/null @@ -1,43 +0,0 @@ -@node pcsys_keys -@section Keys in the graphical frontends - -@c man begin OPTIONS - -During the graphical emulation, you can use special key combinations to ch= ange -modes. The default key mappings are shown below, but if you use @code{-alt= -grab} -then the modifier is Ctrl-Alt-Shift (instead of Ctrl-Alt) and if you use -@code{-ctrl-grab} then the modifier is the right Ctrl key (instead of Ctrl= -Alt): - -@table @key -@item Ctrl-Alt-f -Toggle full screen - -@item Ctrl-Alt-+ -Enlarge the screen - -@item Ctrl-Alt-- -Shrink the screen - -@item Ctrl-Alt-u -Restore the screen's un-scaled dimensions - -@item Ctrl-Alt-n -Switch to virtual console 'n'. Standard console mappings are: -@table @emph -@item 1 -Target system display -@item 2 -Monitor -@item 3 -Serial port -@end table - -@item Ctrl-Alt -Toggle mouse and keyboard grab. -@end table - -In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down}, -@key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log. - -@c man end - diff --git a/docs/system/license.texi b/docs/system/license.texi deleted file mode 100644 index b682235a7e9..00000000000 --- a/docs/system/license.texi +++ /dev/null @@ -1,9 +0,0 @@ -@node License -@appendix License - -QEMU is a trademark of Fabrice Bellard. - -QEMU is released under the -@url{https://www.gnu.org/licenses/gpl-2.0.txt,GNU General Public License}, -version 2. Parts of QEMU have specific licenses, see file -@url{https://git.qemu.org/?p=3Dqemu.git;a=3Dblob_plain;f=3DLICENSE,LICENSE= }. diff --git a/docs/system/linuxboot.texi b/docs/system/linuxboot.texi deleted file mode 100644 index 97c3cefae0a..00000000000 --- a/docs/system/linuxboot.texi +++ /dev/null @@ -1,27 +0,0 @@ -@node direct_linux_boot -@section 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: -@example -@value{qemu_system} -kernel bzImage -hda rootdisk.img -append "root=3D/dev= /hda" -@end example - -Use @option{-kernel} to provide the Linux kernel image and -@option{-append} to give the kernel command line arguments. The -@option{-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 -@option{-nographic} option. The typical command line is: -@example -@value{qemu_system} -kernel bzImage -hda rootdisk.img \ - -append "root=3D/dev/hda console=3DttyS0" -nographic -@end example - -Use @key{Ctrl-a c} to switch between the serial console and the -monitor (@pxref{pcsys_keys}). - diff --git a/docs/system/managed-startup.texi b/docs/system/managed-startup= .texi deleted file mode 100644 index ec168095cc4..00000000000 --- a/docs/system/managed-startup.texi +++ /dev/null @@ -1,35 +0,0 @@ -@node managed_startup -@section Managed start up options - -In system mode emulation, it's possible to create a VM in a paused state u= sing -the -S command line option. In this state the machine is completely initia= lized -according to command line options and ready to execute VM code but VCPU th= reads -are not executing any code. The VM state in this paused state depends on t= he 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 ex= ecute -code loaded by QEMU in the VM's RAM and with incoming migration -@item with incoming migration, initial state will by amended with the migr= ated -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 bef= ore -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 all= ows -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 diff --git a/docs/system/monitor.texi b/docs/system/monitor.texi deleted file mode 100644 index b41b144885d..00000000000 --- a/docs/system/monitor.texi +++ /dev/null @@ -1,34 +0,0 @@ -@node pcsys_monitor -@section QEMU Monitor - -The QEMU monitor is used to give complex commands to the QEMU -emulator. You can use it to: - -@itemize @minus - -@item -Remove or insert removable media images -(such as CD-ROM or floppies). - -@item -Freeze/unfreeze the Virtual Machine (VM) and save or restore its state -from a disk file. - -@item Inspect the VM state without an external debugger. - -@end itemize - -@subsection Commands - -The following commands are available: - -@include qemu-monitor.texi - -@include qemu-monitor-info.texi - -@subsection 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 @emph{$}. - diff --git a/docs/system/mux-chardev.texi b/docs/system/mux-chardev.texi deleted file mode 100644 index b21c2c56540..00000000000 --- a/docs/system/mux-chardev.texi +++ /dev/null @@ -1,44 +0,0 @@ -@node mux_keys -@section Keys in the character backend multiplexer - -@c man begin OPTIONS - -During emulation, if you are using a character backend multiplexer -(which is the default if you are using @option{-nographic}) then -several commands are available via an escape sequence. These -key sequences all start with an escape character, which is @key{Ctrl-a} -by default, but can be changed with @option{-echr}. The list below assumes -you're using the default. - -@table @key -@item Ctrl-a h -Print this help -@item Ctrl-a x -Exit emulator -@item Ctrl-a s -Save disk data back to file (if -snapshot) -@item Ctrl-a t -Toggle console timestamps -@item Ctrl-a b -Send break (magic sysrq in Linux) -@item Ctrl-a c -Rotate between the frontends connected to the multiplexer (usually -this switches between the monitor and the console) -@item Ctrl-a Ctrl-a -Send the escape character to the frontend -@end table -@c man end - -@ignore - -@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 -Fabrice Bellard -@c man end - -@end ignore - diff --git a/docs/system/net.texi b/docs/system/net.texi deleted file mode 100644 index 4a6fb2e6a8a..00000000000 --- a/docs/system/net.texi +++ /dev/null @@ -1,96 +0,0 @@ -@node pcsys_network -@section 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 emulat= ed -hub. The various host network backends can either be used to connect the N= IC of -the guest to a real network (e.g. by using a TAP devices or the non-privil= eged -user mode network stack), or to other guest instances running in another Q= EMU -process (e.g. by using the socket host network backend). - -@subsection 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 @code{tapN}), and you -can then configure it as if it was a real ethernet card. - -@subsubsection Linux host - -As an example, you can download the @file{linux-test-xxx.tar.gz} -archive and copy the script @file{qemu-ifup} in @file{/etc} and -configure properly @code{sudo} so that the command @code{ifconfig} -contained in @file{qemu-ifup} can be executed as root. You must verify -that your host kernel supports the TAP network interfaces: the -device @file{/dev/net/tun} must be present. - -See @ref{sec_invocation} to have examples of command lines using the -TAP network interfaces. - -@subsubsection 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 : @url{https://openvpn.net/}. - -@subsection Using the user mode network stack - -By using the option @option{-net user} (default configuration if no -@option{-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: - -@example - - 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) -@end example - -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. -@code{ping}, aka. ICMP echo, to the local router (10.0.2.2) shall work, -however. If you're using QEMU on Linux >=3D 3.0, it can use unprivileged I= CMP -ping sockets to allow @code{ping} to the Internet. The host admin has to s= et -the ping_group_range in order to grant access to those sockets. To allow p= ing -for GID 100 (usually users group): - -@example -echo 100 100 > /proc/sys/net/ipv4/ping_group_range -@end example - -When using the built-in TFTP server, the router is also the TFTP -server. - -When using the @option{'-netdev user,hostfwd=3D...'} 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. - -@subsection Hubs - -QEMU can simulate several hubs. A hub can be thought of as a virtual conne= ction -between several network devices. These devices can be for example QEMU vir= tual -ethernet cards or virtual Host ethernet devices (TAP devices). You can con= nect -guest NICs or host network backends to such a hub using the @option{-netdev -hubport} or @option{-nic hubport} options. The legacy @option{-net} option -also connects the given device to the emulated hub with ID 0 (i.e. the def= ault -hub) unless you specify a netdev with @option{-net nic,netdev=3Dxxx} here. - -@subsection Connecting emulated networks between QEMU instances - -Using the @option{-netdev socket} (or @option{-nic socket} or -@option{-net socket}) option, it is possible to create emulated -networks that span several QEMU instances. -See the description of the @option{-netdev socket} option in the -@ref{sec_invocation,,Invocation chapter} to have a basic example. diff --git a/docs/system/qemu-option-trace.texi b/docs/system/qemu-option-t= race.texi deleted file mode 100644 index 162f1528d21..00000000000 --- a/docs/system/qemu-option-trace.texi +++ /dev/null @@ -1,28 +0,0 @@ -@c The contents of this file must be kept in sync with qemu-option-trace.r= st.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=3D]@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=3D@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=3D@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 diff --git a/docs/system/quickstart.texi b/docs/system/quickstart.texi deleted file mode 100644 index baceaa96eb2..00000000000 --- a/docs/system/quickstart.texi +++ /dev/null @@ -1,12 +0,0 @@ -@node pcsys_quickstart -@section Quick Start - -Download and uncompress a PC hard disk image with Linux installed (e.g. -@file{linux.img}) and type: - -@example -@value{qemu_system} linux.img -@end example - -Linux should boot and give you a prompt. - diff --git a/docs/system/security.texi b/docs/system/security.texi deleted file mode 100644 index 0d6b30edfc0..00000000000 --- a/docs/system/security.texi +++ /dev/null @@ -1,167 +0,0 @@ -@node Security -@chapter Security - -@section Overview - -This chapter explains the security requirements that QEMU is designed to m= eet -and principles for securely deploying QEMU. - -@section Security Requirements - -QEMU supports many different use cases, some of which have stricter securi= ty -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 - -The virtualization use case covers cloud and virtual private server (VPS) -hosting, as well as traditional data center and desktop virtualization. T= hese -use cases rely on hardware virtualization extensions to execute guest code -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 - -Bugs affecting these entities are evaluated on whether they can cause dama= ge in -real-world use cases and treated as security bugs if this is the case. - -@subsection Non-virtualization Use Case - -The non-virtualization use case covers emulation using the Tiny Code Gener= ator -(TCG). In principle the TCG and device emulation code used in conjunction= with -the non-virtualization use case should meet the same security requirements= as -the virtualization use case. However, for historical reasons much of the -non-virtualization use case code was not written with these security -requirements in mind. - -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 - -This section describes the design principles that ensure the security -requirements are met. - -@subsection 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 -virtual machine. Isolation also includes resource limits such as throttli= ng of -CPU, memory, disk, or network. Guests must be unable to exceed their reso= urce -limits. - -QEMU presents an attack surface to the guest in the form of emulated devic= es. -The guest must not be able to gain control of QEMU. Bugs in emulated devi= ces -could allow malicious guests to gain code execution in QEMU. At this poin= t the -guest has escaped the virtual machine and is able to act in the context of= the -QEMU process on the host. - -Guests often interact with other guests and share resources with them. A -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 u= nless -explicitly shared between them by the user. - -@subsection Principle of Least Privilege - -The principle of least privilege states that each component only has acces= s to -the privileges necessary for its function. In the case of QEMU this means= that -each process only has access to resources belonging to the guest. - -The QEMU process should not have access to any resources that are inaccess= ible -to the guest. This way the guest does not gain anything by escaping into = the -QEMU process since it already has access to those same resources from with= in -the guest. - -Following the principle of least privilege immediately fulfills guest isol= ation -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}. - -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 -necessary for QEMU but are not exposed to guests. A guest that escapes in= to -the QEMU process can then begin invoking host system calls. - -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 fea= ture. - -@subsection Isolation mechanisms - -Several isolation mechanisms are available to realize this architecture of -guest isolation and the principle of least privilege. With the exception = of -Linux seccomp, these mechanisms are all deployed by management tools that -launch QEMU, such as libvirt. They are also platform-specific so they are= only -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 -huge security risk. File descriptor passing can be used to give an otherw= ise -unprivileged QEMU process access to host devices without running QEMU as r= oot. -It is also possible to launch QEMU as a non-root user and configure UNIX g= roups -for access to @code{/dev/kvm}, @code{/dev/net/tun}, and other device nodes. -Some Linux distros already ship with UNIX groups for these devices by defa= ult. - -@itemize -@item SELinux and AppArmor make it possible to confine processes beyond the -traditional UNIX process and file permissions model. They restrict the QE= MU -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 utiliz= ation -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. - -@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 - -@section 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) - -The monitor console (whether used with QMP or HMP) provides an interface -to dynamically control many aspects of QEMU's runtime operation. Many of t= he -commands exposed will instruct QEMU to access content on the host file sys= tem -and/or trigger spawning of external processes. - -For example, the @code{migrate} command allows for the spawning of arbitra= ry -processes for the purpose of tunnelling the migration data stream. The -@code{blockdev-add} command instructs QEMU to open arbitrary files, exposi= ng -their content to the guest as a virtual disk. - -Unless QEMU is otherwise confined using technologies such as SELinux, AppA= rmor, -or Linux namespaces, the monitor console should be considered to have priv= ileges -equivalent to those of the user account QEMU is running under. - -It is further important to consider the security of the character device b= ackend -over which the monitor console is exposed. It needs to have protection aga= inst -malicious third parties which might try to make unauthorized connections, = or -perform man-in-the-middle attacks. Many of the character device backends d= o not -satisfy this requirement and so must not be used for the monitor console. - -The general recommendation is that the monitor console should be exposed o= ver -a UNIX domain socket backend to the local host only. Use of the TCP based -character device backend is inappropriate unless configured to use both TLS -encryption and authorization control policy on client connections. - -In summary, the monitor console is considered a privileged control interfa= ce to -QEMU and as such should only be made accessible to a trusted management -application or user. diff --git a/docs/system/target-arm.texi b/docs/system/target-arm.texi deleted file mode 100644 index eb80dd35f0b..00000000000 --- a/docs/system/target-arm.texi +++ /dev/null @@ -1,245 +0,0 @@ -@node ARM System emulator -@section ARM System emulator - -Use the executable @file{qemu-system-arm} to simulate a ARM -machine. The ARM Integrator/CP board is emulated with the following -devices: - -@itemize @minus -@item -ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU -@item -Two PL011 UARTs -@item -SMC 91c111 Ethernet adapter -@item -PL110 LCD controller -@item -PL050 KMI with PS/2 keyboard and mouse. -@item -PL181 MultiMedia Card Interface with SD card. -@end itemize - -The ARM Versatile baseboard is emulated with the following devices: - -@itemize @minus -@item -ARM926E, ARM1136 or Cortex-A8 CPU -@item -PL190 Vectored Interrupt Controller -@item -Four PL011 UARTs -@item -SMC 91c111 Ethernet adapter -@item -PL110 LCD controller -@item -PL050 KMI with PS/2 keyboard and mouse. -@item -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. -@item -PCI OHCI USB controller. -@item -LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices. -@item -PL181 MultiMedia Card Interface with SD card. -@end itemize - -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: - -@itemize @minus -@item -ARM926E, ARM1136, ARM11MPCore, Cortex-A8 or Cortex-A9 MPCore CPU -@item -ARM AMBA Generic/Distributed Interrupt Controller -@item -Four PL011 UARTs -@item -SMC 91c111 or SMSC LAN9118 Ethernet adapter -@item -PL110 LCD controller -@item -PL050 KMI with PS/2 keyboard and mouse -@item -PCI host bridge -@item -PCI OHCI USB controller -@item -LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices -@item -PL181 MultiMedia Card Interface with SD card. -@end itemize - -The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi" -and "Terrier") emulation includes the following peripherals: - -@itemize @minus -@item -Intel PXA270 System-on-chip (ARM V5TE core) -@item -NAND Flash memory -@item -IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in "Akita" -@item -On-chip OHCI USB controller -@item -On-chip LCD controller -@item -On-chip Real Time Clock -@item -TI ADS7846 touchscreen controller on SSP bus -@item -Maxim MAX1111 analog-digital converter on I@math{^2}C bus -@item -GPIO-connected keyboard controller and LEDs -@item -Secure Digital card connected to PXA MMC/SD host -@item -Three on-chip UARTs -@item -WM8750 audio CODEC on I@math{^2}C and I@math{^2}S busses -@end itemize - -The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the -following elements: - -@itemize @minus -@item -Texas Instruments OMAP310 System-on-chip (ARM 925T core) -@item -ROM and RAM memories (ROM firmware image can be loaded with -option-rom) -@item -On-chip LCD controller -@item -On-chip Real Time Clock -@item -TI TSC2102i touchscreen controller / analog-digital converter / Audio -CODEC, connected through MicroWire and I@math{^2}S busses -@item -GPIO-connected matrix keypad -@item -Secure Digital card connected to OMAP MMC/SD host -@item -Three on-chip UARTs -@end itemize - -Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / 48) -emulation supports the following elements: - -@itemize @minus -@item -Texas Instruments OMAP2420 System-on-chip (ARM 1136 core) -@item -RAM and non-volatile OneNAND Flash memories -@item -Display connected to EPSON remote framebuffer chip and OMAP on-chip -display controller and a LS041y3 MIPI DBI-C controller -@item -TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen controllers -driven through SPI bus -@item -National Semiconductor LM8323-controlled qwerty keyboard driven -through I@math{^2}C bus -@item -Secure Digital card connected to OMAP MMC/SD host -@item -Three OMAP on-chip UARTs and on-chip STI debugging console -@item -Mentor Graphics "Inventra" dual-role USB controller embedded in a TI -TUSB6010 chip - only USB host mode is supported -@item -TI TMP105 temperature sensor driven through I@math{^2}C bus -@item -TI TWL92230C power management companion with an RTC on I@math{^2}C bus -@item -Nokia RETU and TAHVO multi-purpose chips with an RTC, connected -through CBUS -@end itemize - -The Luminary Micro Stellaris LM3S811EVB emulation includes the following -devices: - -@itemize @minus -@item -Cortex-M3 CPU core. -@item -64k Flash and 8k SRAM. -@item -Timers, UARTs, ADC and I@math{^2}C interface. -@item -OSRAM Pictiva 96x16 OLED with SSD0303 controller on I@math{^2}C bus. -@end itemize - -The Luminary Micro Stellaris LM3S6965EVB emulation includes the following -devices: - -@itemize @minus -@item -Cortex-M3 CPU core. -@item -256k Flash and 64k SRAM. -@item -Timers, UARTs, ADC, I@math{^2}C and SSI interfaces. -@item -OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI. -@end itemize - -The Freecom MusicPal internet radio emulation includes the following -elements: - -@itemize @minus -@item -Marvell MV88W8618 ARM core. -@item -32 MB RAM, 256 KB SRAM, 8 MB flash. -@item -Up to 2 16550 UARTs -@item -MV88W8xx8 Ethernet controller -@item -MV88W8618 audio controller, WM8750 CODEC and mixer -@item -128=C3=9764 display with brightness control -@item -2 buttons, 2 navigation wheels with button function -@end itemize - -The Siemens SX1 models v1 and v2 (default) basic emulation. -The emulation includes the following elements: - -@itemize @minus -@item -Texas Instruments OMAP310 System-on-chip (ARM 925T core) -@item -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 -@item -On-chip LCD controller -@item -On-chip Real Time Clock -@item -Secure Digital card connected to OMAP MMC/SD host -@item -Three on-chip UARTs -@end itemize - -A Linux 2.6 test image is available on the QEMU web site. More -information is available in the QEMU mailing-list archive. - diff --git a/docs/system/target-i386.texi b/docs/system/target-i386.texi deleted file mode 100644 index cc352b89a84..00000000000 --- a/docs/system/target-i386.texi +++ /dev/null @@ -1,91 +0,0 @@ -@node x86 (PC) System emulator -@section x86 (PC) System emulator - -@menu -* pcsys_devices:: Peripherals -* cpu_models_x86:: CPU models -* pcsys_req:: OS requirements -@end menu - -@node pcsys_devices -@subsection Peripherals - -@c man begin DESCRIPTION - -The QEMU PC System emulator simulates the following peripherals: - -@itemize @minus -@item -i440FX host PCI bridge and PIIX3 PCI to ISA bridge -@item -Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA -extensions (hardware level, including all non standard modes). -@item -PS/2 mouse and keyboard -@item -2 PCI IDE interfaces with hard disk and CD-ROM support -@item -Floppy disk -@item -PCI and ISA network adapters -@item -Serial ports -@item -IPMI BMC, either and internal or external one -@item -Creative SoundBlaster 16 sound card -@item -ENSONIQ AudioPCI ES1370 sound card -@item -Intel 82801AA AC97 Audio compatible sound card -@item -Intel HD Audio Controller and HDA codec -@item -Adlib (OPL2) - Yamaha YM3812 compatible chip -@item -Gravis Ultrasound GF1 sound card -@item -CS4231A compatible sound card -@item -PCI UHCI, OHCI, EHCI or XHCI USB controller and a virtual USB-1.1 hub. -@end itemize - -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 @url{http://www.deinmeister.de/gusemu/}) -by Tibor "TS" Sch=C3=BCtz. - -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. - -@example -@value{qemu_system_x86} dos.img -soundhw gus -parallel none -@end example - -Alternatively: -@example -@value{qemu_system_x86} dos.img -device gus,irq=3D5 -@end example - -Or some other unclaimed IRQ. - -CS4231A is the chip used in Windows Sound System and GUSMAX products - -@c man end - -@lowersections -@include docs/system/cpu-models-x86.texi -@raisesections - -@node pcsys_req -@subsection OS requirements - -On x86_64 hosts, the default set of CPU features enabled by the KVM accele= rator -require the host to be running Linux v4.5 or newer. Red Hat Enterprise Li= nux -7 is also supported, since the required functionality was backported. - diff --git a/docs/system/target-m68k.texi b/docs/system/target-m68k.texi deleted file mode 100644 index dcce7bc8c56..00000000000 --- a/docs/system/target-m68k.texi +++ /dev/null @@ -1,25 +0,0 @@ -@node ColdFire System emulator -@section ColdFire System emulator - -Use the executable @file{qemu-system-m68k} to simulate a ColdFire machine. -The emulator is able to boot a uClinux kernel. - -The M5208EVB emulation includes the following devices: - -@itemize @minus -@item -MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC). -@item -Three Two on-chip UARTs. -@item -Fast Ethernet Controller (FEC) -@end itemize - -The AN5206 emulation includes the following devices: - -@itemize @minus -@item -MCF5206 ColdFire V2 Microprocessor. -@item -Two on-chip UARTs. -@end itemize diff --git a/docs/system/target-mips.texi b/docs/system/target-mips.texi deleted file mode 100644 index fe12ee94c73..00000000000 --- a/docs/system/target-mips.texi +++ /dev/null @@ -1,150 +0,0 @@ -@node MIPS System emulator -@section MIPS System emulator - -@menu -* recommendations_cpu_models_MIPS:: Supported CPU model configurations on = MIPS hosts -* nanoMIPS System emulator :: -@end menu - -Four executables cover simulation of 32 and 64-bit MIPS systems in -both endian options, @file{qemu-system-mips}, @file{qemu-system-mipsel} -@file{qemu-system-mips64} and @file{qemu-system-mips64el}. -Five different machine types are emulated: - -@itemize @minus -@item -A generic ISA PC-like machine "mips" -@item -The MIPS Malta prototype board "malta" -@item -An ACER Pica "pica61". This machine needs the 64-bit emulator. -@item -MIPS emulator pseudo board "mipssim" -@item -A MIPS Magnum R4000 machine "magnum". This machine needs the 64-bit emulat= or. -@end itemize - -The generic emulation is supported by Debian 'Etch' and is able to -install Debian into a virtual disk image. The following devices are -emulated: - -@itemize @minus -@item -A range of MIPS CPUs, default is the 24Kf -@item -PC style serial port -@item -PC style IDE disk -@item -NE2000 network card -@end itemize - -The Malta emulation supports the following devices: - -@itemize @minus -@item -Core board with MIPS 24Kf CPU and Galileo system controller -@item -PIIX4 PCI/USB/SMbus controller -@item -The Multi-I/O chip's serial device -@item -PCI network cards (PCnet32 and others) -@item -Malta FPGA serial device -@item -Cirrus (default) or any other PCI VGA graphics card -@end itemize - -The Boston board emulation supports the following devices: - -@itemize @minus -@item -Xilinx FPGA, which includes a PCIe root port and an UART -@item -Intel EG20T PCH connects the I/O peripherals, but only the SATA bus is emu= lated -@end itemize - -The ACER Pica emulation supports: - -@itemize @minus -@item -MIPS R4000 CPU -@item -PC-style IRQ and DMA controllers -@item -PC Keyboard -@item -IDE controller -@end itemize - -The MIPS Magnum R4000 emulation supports: - -@itemize @minus -@item -MIPS R4000 CPU -@item -PC-style IRQ controller -@item -PC Keyboard -@item -SCSI controller -@item -G364 framebuffer -@end itemize - -The Fulong 2E emulation supports: - -@itemize @minus -@item -Loongson 2E CPU -@item -Bonito64 system controller as North Bridge -@item -VT82C686 chipset as South Bridge -@item -RTL8139D as a network card chipset -@end itemize - -The mipssim pseudo board emulation provides an environment similar -to what the proprietary MIPS emulator uses for running Linux. -It supports: - -@itemize @minus -@item -A range of MIPS CPUs, default is the 24Kf -@item -PC style serial port -@item -MIPSnet network emulation -@end itemize - -@lowersections -@include docs/system/cpu-models-mips.texi -@raisesections - -@node nanoMIPS System emulator -@subsection nanoMIPS System emulator - -Executable @file{qemu-system-mipsel} also covers simulation of -32-bit nanoMIPS system in little endian mode: - -@itemize @minus -@item -nanoMIPS I7200 CPU -@end itemize - -Example of @file{qemu-system-mipsel} usage for nanoMIPS is shown below: - -Download @code{} from @url{https://mipsdistros.mips.com/L= inuxDistro/nanomips/buildroot/index.html}. - -Download @code{} from @url{https://mipsdistros.mips.com= /LinuxDistro/nanomips/kernels/v4.15.18-432-gb2eb9a8b07a1-20180627102142/ind= ex.html}. - -Start system emulation of Malta board with nanoMIPS I7200 CPU: -@example -qemu-system-mipsel -cpu I7200 -kernel @code{} \ - -M malta -serial stdio -m @code{} -hda @code{} \ - -append "mem=3D256m@@0x0 rw console=3DttyS0 vga=3Dcirrus vesa=3D0x111 = root=3D/dev/sda" -@end example - - diff --git a/docs/system/target-ppc.texi b/docs/system/target-ppc.texi deleted file mode 100644 index 5c83d4f68e7..00000000000 --- a/docs/system/target-ppc.texi +++ /dev/null @@ -1,52 +0,0 @@ -@node PowerPC System emulator -@section PowerPC System emulator - -Use the executable @file{qemu-system-ppc} to simulate a complete 40P (PREP) -or PowerMac PowerPC system. - -QEMU emulates the following PowerMac peripherals: - -@itemize @minus -@item -UniNorth or Grackle PCI Bridge -@item -PCI VGA compatible card with VESA Bochs Extensions -@item -2 PMAC IDE interfaces with hard disk and CD-ROM support -@item -NE2000 PCI adapters -@item -Non Volatile RAM -@item -VIA-CUDA with ADB keyboard and mouse. -@end itemize - -QEMU emulates the following 40P (PREP) peripherals: - -@itemize @minus -@item -PCI Bridge -@item -PCI VGA compatible card with VESA Bochs Extensions -@item -2 IDE interfaces with hard disk and CD-ROM support -@item -Floppy disk -@item -PCnet network adapters -@item -Serial port -@item -PREP Non Volatile RAM -@item -PC compatible keyboard and mouse. -@end itemize - -Since version 0.9.1, QEMU uses OpenBIOS @url{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 -@url{http://perso.magic.fr/l_indien/qemu-ppc/}. - diff --git a/docs/system/target-sparc.texi b/docs/system/target-sparc.texi deleted file mode 100644 index 99fbf820b42..00000000000 --- a/docs/system/target-sparc.texi +++ /dev/null @@ -1,68 +0,0 @@ -@node Sparc32 System emulator -@section Sparc32 System emulator - -Use the executable @file{qemu-system-sparc} to simulate the following -Sun4m architecture machines: -@itemize @minus -@item -SPARCstation 4 -@item -SPARCstation 5 -@item -SPARCstation 10 -@item -SPARCstation 20 -@item -SPARCserver 600MP -@item -SPARCstation LX -@item -SPARCstation Voyager -@item -SPARCclassic -@item -SPARCbook -@end itemize - -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: - -@itemize @minus -@item -IOMMU -@item -TCX or cgthree Frame buffer -@item -Lance (Am7990) Ethernet -@item -Non Volatile RAM M48T02/M48T08 -@item -Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard -and power/reset logic -@item -ESP SCSI controller with hard disk and CD-ROM support -@item -Floppy drive (not on SS-600MP) -@item -CS4231 sound device (only on SS-5, not working yet) -@end itemize - -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 -@url{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. - -@c man end - diff --git a/docs/system/target-sparc64.texi b/docs/system/target-sparc64.t= exi deleted file mode 100644 index d381d3af719..00000000000 --- a/docs/system/target-sparc64.texi +++ /dev/null @@ -1,38 +0,0 @@ -@node Sparc64 System emulator -@section Sparc64 System emulator - -Use the executable @file{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 @url{http://download.oracle.com/technetwork/sy= stems/opensparc/OpenSPARCT1_Arch.1.5.tar.bz2} -and is able to boot the disk.s10hw2 Solaris image. -@example -qemu-system-sparc64 -M niagara -L /path-to/S10image/ \ - -nographic -m 256 \ - -drive if=3Dpflash,readonly=3Don,file=3D/S10image/disk= .s10hw2 -@end example - - -QEMU emulates the following peripherals: - -@itemize @minus -@item -UltraSparc IIi APB PCI Bridge -@item -PCI VGA compatible card with VESA Bochs Extensions -@item -PS/2 mouse and keyboard -@item -Non Volatile RAM M48T59 -@item -PC-compatible serial ports -@item -2 PCI IDE interfaces with hard disk and CD-ROM support -@item -Floppy disk -@end itemize - diff --git a/docs/system/target-xtensa.texi b/docs/system/target-xtensa.texi deleted file mode 100644 index 1e6c04dccd6..00000000000 --- a/docs/system/target-xtensa.texi +++ /dev/null @@ -1,35 +0,0 @@ -@node Xtensa System emulator -@section Xtensa System emulator - -Two executables cover simulation of both Xtensa endian options, -@file{qemu-system-xtensa} and @file{qemu-system-xtensaeb}. -Two different machine types are emulated: - -@itemize @minus -@item -Xtensa emulator pseudo board "sim" -@item -Avnet LX60/LX110/LX200 board -@end itemize - -The sim pseudo board emulation provides an environment similar -to one provided by the proprietary Tensilica ISS. -It supports: - -@itemize @minus -@item -A range of Xtensa CPUs, default is the DC232B -@item -Console and filesystem access via semihosting calls -@end itemize - -The Avnet LX60/LX110/LX200 emulation supports: - -@itemize @minus -@item -A range of Xtensa CPUs, default is the DC232B -@item -16550 UART -@item -OpenCores 10/100 Mbps Ethernet MAC -@end itemize diff --git a/docs/system/tls.texi b/docs/system/tls.texi deleted file mode 100644 index c233531d3a1..00000000000 --- a/docs/system/tls.texi +++ /dev/null @@ -1,329 +0,0 @@ -@node network_tls -@section 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 @code{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 -@code{/etc/pki/qemu} or for unprivileged users in @code{$HOME/.pki/qemu}. - -@menu -* tls_generate_ca:: -* tls_generate_server:: -* tls_generate_client:: -* tls_creds_setup:: -* tls_psk:: -@end menu -@node tls_generate_ca -@subsection 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 certi= ficates -issued with it is lost. - -@example -# certtool --generate-privkey > ca-key.pem -@end example - -To generate a self-signed certificate requires one core piece of informati= on, -the name of the organization. A template file @code{ca.info} should be -populated with the desired data to avoid having to deal with interactive -prompts from certtool: -@example -# cat > ca.info < server-hostNNN.info < 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 -@end example - -The @code{dns_name} and @code{ip_address} fields in the template are setti= ng -the subject alt name extension data. The @code{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 @code{encryption_key} and @code{signing_key} keyword is the key usage -extension to indicate this certificate is intended for usage in the data -session. - -The @code{server-hostNNN-key.pem} and @code{server-hostNNN-cert.pem} files -should now be securely copied to the server for which they were generated, -and renamed to @code{server-key.pem} and @code{server-cert.pem} when added -to the @code{/etc/pki/qemu} directory on the target host. The @code{server= -key.pem} -file is security sensitive and should be kept protected with file mode 0600 -to prevent disclosure. - -@node tls_generate_client -@subsection 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 cl= ient -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. - - -@example -# cat > client-hostNNN.info < 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 -@end example - -The subject alt name extension data is not required for clients, so the -the @code{dns_name} and @code{ip_address} fields are not included. -The @code{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 @code{encryption_key} and @code{signing_key} keyword -is the key usage extension to indicate this certificate is intended for -usage in the data session. - -The @code{client-hostNNN-key.pem} and @code{client-hostNNN-cert.pem} files -should now be securely copied to the client for which they were generated, -and renamed to @code{client-key.pem} and @code{client-cert.pem} when added -to the @code{/etc/pki/qemu} directory on the target host. The @code{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 migrati= on, -and later itself be migrated out to another host. To generate a single -certificate, simply include the template data from both the client and ser= ver -instructions in one. - -@example -# cat > both-hostNNN.info < 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 -@end example - -When copying the PEM files to the target host, save them twice, -once as @code{server-cert.pem} and @code{server-key.pem}, and -again as @code{client-cert.pem} and @code{client-key.pem}. - -@node tls_creds_setup -@subsection 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 -@code{tls-creds-x509} class name to the @code{--object} command line -argument for the system emulators. Each set of credentials loaded should -be given a unique string identifier via the @code{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 @code{dir} parameters specifies which -directory contains the credential files. This directory is expected to -contain files with the names mentioned previously, @code{ca-cert.pem}, -@code{server-key.pem}, @code{server-cert.pem}, @code{client-key.pem} -and @code{client-cert.pem} as appropriate. It is also possible to -include a set of pre-generated Diffie-Hellman (DH) parameters in a file -@code{dh-params.pem}, which can be created using the -@code{certtool --generate-dh-params} command. If omitted, QEMU will -dynamically generate DH parameters when loading the credentials. - -The @code{endpoint} parameter indicates whether the credentials will -be used for a network client or server, and determines which PEM -files are loaded. - -The @code{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 - -@example -@value{qemu_system} -object tls-creds-x509,id=3Dtls0,dir=3D/etc/pki/qemu,e= ndpoint=3Dserver -@end example - -while to load client credentials use - -@example -@value{qemu_system} -object tls-creds-x509,id=3Dtls0,dir=3D/etc/pki/qemu,e= ndpoint=3Dclient -@end example - -Network services which support TLS will all have a @code{tls-creds} -parameter which expects the ID of the TLS credentials object. For -example with VNC: - -@example -@value{qemu_system} -vnc 0.0.0.0:0,tls-creds=3Dtls0 -@end example - -@node tls_psk -@subsection 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 @code{psktool} program to generate a @code{keys.psk} -file containing one or more usernames and random keys: - -@example -mkdir -m 0700 /tmp/keys -psktool -u rich -p /tmp/keys/keys.psk -@end example - -TLS-enabled servers such as qemu-nbd can use this directory like so: - -@example -qemu-nbd \ - -t -x / \ - --object tls-creds-psk,id=3Dtls0,endpoint=3Dserver,dir=3D/tmp/keys \ - --tls-creds tls0 \ - image.qcow2 -@end example - -When connecting from a qemu-based client you must specify the -directory containing @code{keys.psk} and an optional @var{username} -(defaults to ``qemu''): - -@example -qemu-img info \ - --object tls-creds-psk,id=3Dtls0,dir=3D/tmp/keys,username=3Drich,endpoin= t=3Dclient \ - --image-opts \ - file.driver=3Dnbd,file.host=3Dlocalhost,file.port=3D10809,file.tls-creds= =3Dtls0,file.export=3D/ -@end example - diff --git a/docs/system/usb.texi b/docs/system/usb.texi deleted file mode 100644 index 840adac9785..00000000000 --- a/docs/system/usb.texi +++ /dev/null @@ -1,115 +0,0 @@ -@node pcsys_usb -@section 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. - -@menu -* usb_devices:: -* host_usb_devices:: -@end menu -@node usb_devices -@subsection Connecting USB devices - -USB devices can be connected with the @option{-device usb-...} command line -option or the @code{device_add} monitor command. Available devices are: - -@table @code -@item usb-mouse -Virtual Mouse. This will override the PS/2 mouse emulation when activated. -@item 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. -@item usb-storage,drive=3D@var{drive_id} -Mass storage device backed by @var{drive_id} (@pxref{disk_images}) -@item usb-uas -USB attached SCSI device, see -@url{https://git.qemu.org/?p=3Dqemu.git;a=3Dblob_plain;f=3Ddocs/usb-storag= e.txt,usb-storage.txt} -for details -@item usb-bot -Bulk-only transport storage device, see -@url{https://git.qemu.org/?p=3Dqemu.git;a=3Dblob_plain;f=3Ddocs/usb-storag= e.txt,usb-storage.txt} -for details here, too -@item usb-mtp,rootdir=3D@var{dir} -Media transfer protocol device, using @var{dir} as root of the file tree -that is presented to the guest. -@item usb-host,hostbus=3D@var{bus},hostaddr=3D@var{addr} -Pass through the host device identified by @var{bus} and @var{addr} -@item usb-host,vendorid=3D@var{vendor},productid=3D@var{product} -Pass through the host device identified by @var{vendor} and @var{product} = ID -@item usb-wacom-tablet -Virtual Wacom PenPartner tablet. This device is similar to the @code{tabl= et} -above but it can be used with the tslib library because in addition to tou= ch -coordinates it reports touch pressure. -@item usb-kbd -Standard USB keyboard. Will override the PS/2 keyboard (if present). -@item usb-serial,chardev=3D@var{id} -Serial converter. This emulates an FTDI FT232BM chip connected to host cha= racter -device @var{id}. -@item usb-braille,chardev=3D@var{id} -Braille device. This will use BrlAPI to display the braille output on a r= eal -or fake device referenced by @var{id}. -@item usb-net[,netdev=3D@var{id}] -Network adapter that supports CDC ethernet and RNDIS protocols. @var{id} -specifies a netdev defined with @code{-netdev @dots{},id=3D@var{id}}. -For instance, user-mode networking can be used with -@example -@value{qemu_system} [...] -netdev user,id=3Dnet0 -device usb-net,netdev=3D= net0 -@end example -@item usb-ccid -Smartcard reader device -@item usb-audio -USB audio device -@end table - -@node host_usb_devices -@subsection 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. - -@enumerate -@item 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 @file{mydriver= .o} -to @file{mydriver.o.disabled}. - -@item Verify that @file{/proc/bus/usb} is working (most Linux distribution= s should enable it by default). You should see something like that: -@example -ls /proc/bus/usb -001 devices drivers -@end example - -@item Since only root can access to the USB devices directly, you can eith= er launch QEMU as root or change the permissions of the USB devices you wan= t to use. For testing, the following suffices: -@example -chown -R myuid /proc/bus/usb -@end example - -@item Launch QEMU and do in the monitor: -@example -info usbhost - Device 1.2, speed 480 Mb/s - Class 00: USB device 1234:5678, USB DISK -@end example -You should see the list of the devices you can use (Never try to use -hubs, it won't work). - -@item Add the device in QEMU by using: -@example -device_add usb-host,vendorid=3D0x1234,productid=3D0x5678 -@end example - -Normally the guest OS should report that a new USB device is plugged. -You can use the option @option{-device usb-host,...} to do the same. - -@item Now you can try to use the host USB device in QEMU. - -@end enumerate - -When relaunching QEMU, you may have to unplug and plug again the USB -device to make it work again (this is a bug). - diff --git a/docs/system/vnc-security.texi b/docs/system/vnc-security.texi deleted file mode 100644 index abf7f7fa43a..00000000000 --- a/docs/system/vnc-security.texi +++ /dev/null @@ -1,196 +0,0 @@ -@node vnc_security -@section 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. - -@menu -* vnc_sec_none:: -* vnc_sec_password:: -* vnc_sec_certificate:: -* vnc_sec_certificate_verify:: -* vnc_sec_certificate_pw:: -* vnc_sec_sasl:: -* vnc_sec_certificate_sasl:: -* vnc_setup_sasl:: -@end menu -@node vnc_sec_none -@subsection 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 - -@example -@value{qemu_system} [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-v= nc -@end example - -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. - -@node vnc_sec_password -@subsection With passwords - -The VNC protocol has limited support for password based authentication. Si= nce -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 pa= ssword -authentication should be restricted to only listen on the loopback interfa= ce -or UNIX domain sockets. Password authentication is not supported when oper= ating -in FIPS 140-2 compliance mode as it requires the use of the DES cipher. Pa= ssword -authentication is requested with the @code{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. - -@example -@value{qemu_system} [...OPTIONS...] -vnc :1,password -monitor stdio -(qemu) change vnc password -Password: ******** -(qemu) -@end example - -@node vnc_sec_certificate -@subsection 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 authenticatio= n. -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. - -@example -@value{qemu_system} [...OPTIONS...] \ - -object tls-creds-x509,id=3Dtls0,dir=3D/etc/pki/qemu,endpoint=3Dserver,v= erify-peer=3Dno \ - -vnc :1,tls-creds=3Dtls0 -monitor stdio -@end example - -In the above example @code{/etc/pki/qemu} should contain at least three fi= les, -@code{ca-cert.pem}, @code{server-cert.pem} and @code{server-key.pem}. Unpr= ivileged -users will want to use a private directory, for example @code{$HOME/.pki/q= emu}. -NB the @code{server-key.pem} file should be protected with file mode 0600 = to -only be readable by the user owning it. - -@node vnc_sec_certificate_verify -@subsection With x509 certificates and client verification - -Certificates can also provide a means to authenticate the client connectin= g. -The server will request that the client provide a certificate, which it wi= ll -then validate against the CA certificate. This is a good choice if deployi= ng -in an environment with a private internal certificate authority. It uses t= he -same syntax as previously, but with @code{verify-peer} set to @code{yes} -instead. - -@example -@value{qemu_system} [...OPTIONS...] \ - -object tls-creds-x509,id=3Dtls0,dir=3D/etc/pki/qemu,endpoint=3Dserver,v= erify-peer=3Dyes \ - -vnc :1,tls-creds=3Dtls0 -monitor stdio -@end example - - -@node vnc_sec_certificate_pw -@subsection With x509 certificates, client verification and passwords - -Finally, the previous method can be combined with VNC password authenticat= ion -to provide two layers of authentication for clients. - -@example -@value{qemu_system} [...OPTIONS...] \ - -object tls-creds-x509,id=3Dtls0,dir=3D/etc/pki/qemu,endpoint=3Dserver,v= erify-peer=3Dyes \ - -vnc :1,tls-creds=3Dtls0,password -monitor stdio -(qemu) change vnc password -Password: ******** -(qemu) -@end example - - -@node vnc_sec_sasl -@subsection 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: - -@example -@value{qemu_system} [...OPTIONS...] -vnc :1,sasl -monitor stdio -@end example - -@node vnc_sec_certificate_sasl -@subsection 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: - -@example -@value{qemu_system} [...OPTIONS...] \ - -object tls-creds-x509,id=3Dtls0,dir=3D/etc/pki/qemu,endpoint=3Dserver,v= erify-peer=3Dyes \ - -vnc :1,tls-creds=3Dtls0,sasl -monitor stdio -@end example - -@node vnc_setup_sasl - -@subsection Configuring SASL mechanisms - -The following documentation assumes use of the Cyrus SASL implementation o= n a -Linux host, but the principles should apply to any other SASL implementati= on -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 a= s an -unprivileged user, an environment variable SASL_CONF_PATH can be used to m= ake -it search alternate locations for the service config file. - -If the TLS option is enabled for VNC, then it will provide session encrypt= ion, -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 securi= ty -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, b= ut -does not support session encryption, so can only be used in combination wi= th -TLS. - -When not using TLS the recommended configuration is - -@example -mech_list: gssapi -keytab: /etc/qemu/krb5.tab -@end example - -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 serve= r, -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 - -@example -mech_list: scram-sha-1 -sasldb_path: /etc/qemu/passwd.db -@end example - -The @code{saslpasswd2} program can be used to populate the @code{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 ensur= e a -secure data channel. - - diff --git a/qemu-doc.texi b/qemu-doc.texi deleted file mode 100644 index c2b9c87c645..00000000000 --- a/qemu-doc.texi +++ /dev/null @@ -1,201 +0,0 @@ -\input texinfo @c -*- texinfo -*- -@c %**start of header -@setfilename qemu-doc.info -@include version.texi - -@documentlanguage en -@documentencoding UTF-8 - -@settitle QEMU version @value{VERSION} User Documentation -@exampleindent 0 -@paragraphindent 0 -@c %**end of header - -@set qemu_system qemu-system-x86_64 -@set qemu_system_x86 qemu-system-x86_64 - -@ifinfo -@direntry -* QEMU: (qemu-doc). The QEMU Emulator User Documentation. -@end direntry -@end ifinfo - -@iftex -@titlepage -@sp 7 -@center @titlefont{QEMU version @value{VERSION}} -@sp 1 -@center @titlefont{User Documentation} -@sp 3 -@end titlepage -@end iftex - -@ifnottex -@node Top -@top - -@menu -* Introduction:: -* QEMU System emulator:: -* QEMU System emulator targets:: -* Security:: -* Deprecated features:: -* Recently removed features:: -* Supported build platforms:: -* License:: -* Index:: -@end menu -@end ifnottex - -@contents - -@node Introduction -@chapter Introduction - -@menu -* intro_features:: Features -@end menu - -@node intro_features -@section Features - -QEMU is a FAST! processor emulator using dynamic translation to -achieve good emulation speed. - -QEMU has two operating modes: - -@itemize -@item Full system emulation. In this mode, QEMU emulates a full system (for -example a PC), including one or several processors and various -peripherals. It can be used to launch different Operating Systems -without rebooting the PC or to debug system code. - -@item User mode emulation. In this mode, QEMU can launch -processes compiled for one CPU on another CPU. It can be used to -launch the Wine Windows API emulator (@url{https://www.winehq.org}) or -to ease cross-compilation and cross-debugging. - -@end itemize - -QEMU has the following features: - -@itemize -@item QEMU can run without a host kernel driver and yet gives acceptable -performance. It uses dynamic translation to native code for reasonable sp= eed, -with support for self-modifying code and precise exceptions. - -@item It is portable to several operating systems (GNU/Linux, *BSD, Mac OS= X, -Windows) and architectures. - -@item It performs accurate software emulation of the FPU. -@end itemize - -QEMU user mode emulation has the following features: -@itemize -@item Generic Linux system call converter, including most ioctls. - -@item clone() emulation using native CPU clone() to use Linux scheduler fo= r threads. - -@item Accurate signal handling by remapping host signals to target signals. -@end itemize - -QEMU full system emulation has the following features: -@itemize -@item -QEMU uses a full software MMU for maximum portability. - -@item -QEMU can optionally use an in-kernel accelerator, like kvm. The accelerato= rs -execute most of the guest code natively, while -continuing to emulate the rest of the machine. - -@item -Various hardware devices can be emulated and in some cases, host -devices (e.g. serial and parallel ports, USB, drives) can be used -transparently by the guest Operating System. Host device passthrough -can be used for talking to external physical peripherals (e.g. a -webcam, modem or tape drive). - -@item -Symmetric multiprocessing (SMP) support. Currently, an in-kernel -accelerator is required to use more than one host CPU for emulation. - -@end itemize - -@node QEMU System emulator -@chapter QEMU System emulator - -@menu -* pcsys_quickstart:: Quick start -* sec_invocation:: Invocation -* pcsys_keys:: Keys in the graphical frontends -* mux_keys:: Keys in the character backend multiplexer -* pcsys_monitor:: QEMU Monitor -* disk_images:: Disk Images -* pcsys_network:: Network emulation -* pcsys_usb:: USB emulation -* pcsys_ivshmem:: Inter-VM Shared Memory device -* direct_linux_boot:: Direct Linux Boot -* vnc_security:: VNC security -* network_tls:: TLS setup for network services -* gdb_usage:: GDB usage -* managed_startup:: Managed startup options -@end menu - -@include docs/system/quickstart.texi -@include docs/system/invocation.texi -@include docs/system/keys.texi -@include docs/system/mux-chardev.texi -@include docs/system/monitor.texi -@include docs/system/images.texi -@include docs/system/net.texi -@include docs/system/usb.texi -@include docs/system/ivshmem.texi -@include docs/system/linuxboot.texi -@include docs/system/vnc-security.texi -@include docs/system/tls.texi -@include docs/system/gdb.texi -@include docs/system/managed-startup.texi - -@node QEMU System emulator targets -@chapter 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. - -@menu -* x86 (PC) System emulator:: -* PowerPC System emulator:: -* Sparc32 System emulator:: -* Sparc64 System emulator:: -* MIPS System emulator:: -* ARM System emulator:: -* ColdFire System emulator:: -* Xtensa System emulator:: -@end menu - -@include docs/system/target-i386.texi -@include docs/system/target-ppc.texi -@include docs/system/target-sparc.texi -@include docs/system/target-sparc64.texi -@include docs/system/target-mips.texi -@include docs/system/target-arm.texi -@include docs/system/target-m68k.texi -@include docs/system/target-xtensa.texi - -@include docs/system/security.texi - -@include docs/system/deprecated.texi - -@include docs/system/build-platforms.texi - -@include docs/system/license.texi - - -@node Index -@appendix Index - -@printindex fn - -@bye --=20 2.20.1