From nobody Sun Oct 5 14:30:41 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=1583493552; cv=none; d=zohomail.com; s=zohoarc; b=D1CDeZKKFuL5/8g25A+sMXEbN2xaF+5joXhLDF31mrG0YgVv5uZJrHpCZajTvyWioo9SgG0D7NbD8mZoomq1YUEbPC7Fj2HcqYaj0rzAB/9b9sTYUrlcJnoF4gAvaXc92As2JwXdOAlP9mgYsVZCC3e2E7iD4tHt9UluW+F1VEY= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1583493552; 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=lqQmx9SBTn9mo6iuQQIIgdssXawK/tQJq2+WQTK7NcA=; b=AfcZCamk5NmphWIi62gAgJEh+uqlV+Wy/WBrcHT6eMw8rpAO8ad6Sn93Py3zM3IoMtK7XjcrgYUw1sNsIzN3NgXiJc/pDRK8m4xJ0iWWOUnpAyi4OSfQ3bLAtnNatw8LOStVOQXub+PYmGpI/Fuyz+OORB+wA0v374j0V4jV1uo= 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 1583493552704919.602431310089; Fri, 6 Mar 2020 03:19:12 -0800 (PST) Received: from localhost ([::1]:34985 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jAB0Z-0002jB-GN for importer@patchew.org; Fri, 06 Mar 2020 06:19:11 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:39419) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jAAs8-0003mp-Q3 for qemu-devel@nongnu.org; Fri, 06 Mar 2020 06:10:43 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jAAry-0004qb-5z for qemu-devel@nongnu.org; Fri, 06 Mar 2020 06:10:28 -0500 Received: from mail-wm1-x331.google.com ([2a00:1450:4864:20::331]:54081) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1jAArx-0004mA-Ef for qemu-devel@nongnu.org; Fri, 06 Mar 2020 06:10:18 -0500 Received: by mail-wm1-x331.google.com with SMTP id g134so1925448wme.3 for ; Fri, 06 Mar 2020 03:10:17 -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.07 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 06 Mar 2020 03:10:09 -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=lqQmx9SBTn9mo6iuQQIIgdssXawK/tQJq2+WQTK7NcA=; b=kIhRwJUXYBDao8FBgB+V7GKHo2lNSdlkZU/1iQOpUWSiZaSCJv5pTU3GwhHxCZNNmP ng82g7w+PUatOWAFW8TaqpW8fdAiO08EB/S9hxArLU7NQIw2xP9eUYSkIxfLAn68bz0P isbzV7vfT9jmroIScBxrk0BbWDmCE3Qg3PByJhat/vmvVHikhmODqTdSavXUM5ansNkV kpfIwYac7bMkUaVK7z9lLOzmLwHDIP7JrsF47s63DGLaWC5LJf1TqXvMllMo5Nu4BVWW gQauxRkvgX0iicKnhUnYIn8o7xJMXjiXrTJ1pMQc0ykw6Uwcfsv820kESJC2bXGtakis Hmmg== 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=lqQmx9SBTn9mo6iuQQIIgdssXawK/tQJq2+WQTK7NcA=; b=DmIbOHfrXZYiKivduVS00MRmXfhAh04wuSQNNB4ZxViscNDU1YvIJ2RS7HXsq1yHXu TlaOz+S3U3zbCIjtf0oBsgLnvJMLWovakfwQsJ4h+eRXLyhmvjKpXA4bcqITm86j2bdC gyEOKsBA6Ypa0ogs/+0/dwplXO7okhv8EW+6+bBs9qheHWqeHBPV1JhcaBIeqpxeiman 0jYkAOdkg20xUSH78RqEbxGUQTfhEG5deG8cyJZwi19926hIL3AnJr1Tw6o7bDv1uLJb 7OP/oybA1VIMkJQ2U5HoUXdzRgM1GRMRgWhVosejTVVWerij07V+sYVRu1vKc2PAtkeF vLyg== X-Gm-Message-State: ANhLgQ1tK1wBJYTIKbuHPyK1P89nbl2gOb01FbOPiECK/UU7HPZtSehg 0hwAfnUcQNT7kE3AH8uQC40+dWdo7L+9rA== X-Google-Smtp-Source: ADFU+vvNqi6hdsZByubm/f4xDXnGBOHIAa3Dpx0A9RIZ2eY+YjB2Q8/ndzeK4H/C/CaoBAAAW0WgKQ== X-Received: by 2002:a7b:c34d:: with SMTP id l13mr3380392wmj.19.1583493010263; Fri, 06 Mar 2020 03:10:10 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PULL 05/33] qemu-doc: split qemu-doc.texi in multiple files Date: Fri, 6 Mar 2020 11:09:31 +0000 Message-Id: <20200306110959.29461-6-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::331 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) From: Paolo Bonzini In order to facilitate the reorganization of qemu-doc.texi content, as well as the conversion to rST/Sphinx, split it in multiple .texi files that are included from docs/system. The "other devices" section is renamed to ivshmem and placed last. Signed-off-by: Paolo Bonzini Reviewed-by: Peter Maydell Reviewed-by: Alex Benn=C3=A9e Tested-by: Alex Benn=C3=A9e Signed-off-by: Peter Maydell Message-id: 20200228153619.9906-6-peter.maydell@linaro.org Message-id: 20200226113034.6741-6-pbonzini@redhat.com Reviewed-by: Peter Maydell Signed-off-by: Peter Maydell --- Makefile | 16 + docs/system/build-platforms.texi | 67 ++ docs/system/gdb.texi | 71 ++ docs/system/images.texi | 88 ++ docs/system/invocation.texi | 240 +++++ docs/system/ivshmem.texi | 60 ++ docs/system/keys.texi | 53 ++ docs/system/license.texi | 9 + docs/system/linuxboot.texi | 27 + docs/system/monitor.texi | 35 + docs/system/mux-chardev.texi | 51 ++ docs/system/net.texi | 96 ++ docs/system/quickstart.texi | 13 + docs/system/tls.texi | 329 +++++++ docs/system/usb.texi | 115 +++ docs/system/vnc-security.texi | 196 ++++ qemu-doc.texi | 1471 +----------------------------- 17 files changed, 1483 insertions(+), 1454 deletions(-) create mode 100644 docs/system/build-platforms.texi create mode 100644 docs/system/gdb.texi create mode 100644 docs/system/images.texi create mode 100644 docs/system/invocation.texi create mode 100644 docs/system/ivshmem.texi create mode 100644 docs/system/keys.texi create mode 100644 docs/system/license.texi create mode 100644 docs/system/linuxboot.texi create mode 100644 docs/system/monitor.texi create mode 100644 docs/system/mux-chardev.texi create mode 100644 docs/system/net.texi create mode 100644 docs/system/quickstart.texi create mode 100644 docs/system/tls.texi create mode 100644 docs/system/usb.texi create mode 100644 docs/system/vnc-security.texi diff --git a/Makefile b/Makefile index f75a7b51938..9790a0fd15b 100644 --- a/Makefile +++ b/Makefile @@ -1123,6 +1123,22 @@ qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.tx= t: \ qemu-tech.texi qemu-option-trace.texi \ qemu-deprecated.texi qemu-monitor.texi \ qemu-monitor-info.texi \ + docs/system/quickstart.texi \ + docs/system/invocation.texi \ + docs/system/keys.texi \ + docs/system/mux-chardev.texi \ + docs/system/monitor.texi \ + docs/system/cpu-models-x86.texi \ + docs/system/images.texi \ + docs/system/net.texi \ + docs/system/usb.texi \ + docs/system/ivshmem.texi \ + docs/system/linuxboot.texi \ + docs/system/vnc-security.texi \ + docs/system/tls.texi \ + docs/system/gdb.texi \ + docs/system/build-platforms.texi \ + docs/system/license.texi \ docs/system/cpu-models-x86.texi docs/system/cpu-models-mips.texi \ docs/security.texi =20 diff --git a/docs/system/build-platforms.texi b/docs/system/build-platforms= .texi new file mode 100644 index 00000000000..531ef5bed44 --- /dev/null +++ b/docs/system/build-platforms.texi @@ -0,0 +1,67 @@ +@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/gdb.texi b/docs/system/gdb.texi new file mode 100644 index 00000000000..f49bc5891e9 --- /dev/null +++ b/docs/system/gdb.texi @@ -0,0 +1,71 @@ +@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 new file mode 100644 index 00000000000..c5060348ecc --- /dev/null +++ b/docs/system/images.texi @@ -0,0 +1,88 @@ +@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 new file mode 100644 index 00000000000..dac41cc7e55 --- /dev/null +++ b/docs/system/invocation.texi @@ -0,0 +1,240 @@ +@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 new file mode 100644 index 00000000000..bd97719eaf7 --- /dev/null +++ b/docs/system/ivshmem.texi @@ -0,0 +1,60 @@ +@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 new file mode 100644 index 00000000000..4c74b3bf4dd --- /dev/null +++ b/docs/system/keys.texi @@ -0,0 +1,53 @@ +@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 +@kindex Ctrl-Alt-f +Toggle full screen + +@item Ctrl-Alt-+ +@kindex Ctrl-Alt-+ +Enlarge the screen + +@item Ctrl-Alt-- +@kindex Ctrl-Alt-- +Shrink the screen + +@item Ctrl-Alt-u +@kindex Ctrl-Alt-u +Restore the screen's un-scaled dimensions + +@item Ctrl-Alt-n +@kindex 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 +@kindex Ctrl-Alt +Toggle mouse and keyboard grab. +@end table + +@kindex Ctrl-Up +@kindex Ctrl-Down +@kindex Ctrl-PageUp +@kindex Ctrl-PageDown +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 new file mode 100644 index 00000000000..b682235a7e9 --- /dev/null +++ b/docs/system/license.texi @@ -0,0 +1,9 @@ +@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 new file mode 100644 index 00000000000..97c3cefae0a --- /dev/null +++ b/docs/system/linuxboot.texi @@ -0,0 +1,27 @@ +@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/monitor.texi b/docs/system/monitor.texi new file mode 100644 index 00000000000..c5b6a9b38e4 --- /dev/null +++ b/docs/system/monitor.texi @@ -0,0 +1,35 @@ +@node pcsys_monitor +@section QEMU Monitor +@cindex 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 new file mode 100644 index 00000000000..c9a2d14cb88 --- /dev/null +++ b/docs/system/mux-chardev.texi @@ -0,0 +1,51 @@ +@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 +@kindex Ctrl-a h +Print this help +@item Ctrl-a x +@kindex Ctrl-a x +Exit emulator +@item Ctrl-a s +@kindex Ctrl-a s +Save disk data back to file (if -snapshot) +@item Ctrl-a t +@kindex Ctrl-a t +Toggle console timestamps +@item Ctrl-a b +@kindex Ctrl-a b +Send break (magic sysrq in Linux) +@item Ctrl-a c +@kindex 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 +@kindex 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 new file mode 100644 index 00000000000..4a6fb2e6a8a --- /dev/null +++ b/docs/system/net.texi @@ -0,0 +1,96 @@ +@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/quickstart.texi b/docs/system/quickstart.texi new file mode 100644 index 00000000000..8cd5b4bc6e5 --- /dev/null +++ b/docs/system/quickstart.texi @@ -0,0 +1,13 @@ +@node pcsys_quickstart +@section Quick Start +@cindex quick start + +Download and uncompress a 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/tls.texi b/docs/system/tls.texi new file mode 100644 index 00000000000..c233531d3a1 --- /dev/null +++ b/docs/system/tls.texi @@ -0,0 +1,329 @@ +@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 new file mode 100644 index 00000000000..840adac9785 --- /dev/null +++ b/docs/system/usb.texi @@ -0,0 +1,115 @@ +@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 new file mode 100644 index 00000000000..abf7f7fa43a --- /dev/null +++ b/docs/system/vnc-security.texi @@ -0,0 +1,196 @@ +@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 index 617a701b678..33d24caf946 100644 --- a/qemu-doc.texi +++ b/qemu-doc.texi @@ -142,9 +142,9 @@ accelerator is required to use more than one host CPU f= or emulation. * cpu_models_x86:: Supported CPU model configurations on x86 hosts * disk_images:: Disk Images * pcsys_network:: Network emulation -* pcsys_other_devs:: Other Devices -* direct_linux_boot:: Direct Linux Boot * 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 @@ -222,1384 +222,20 @@ CS4231A is the chip used in Windows Sound System an= d GUSMAX products =20 @c man end =20 -@node pcsys_quickstart -@section Quick Start -@cindex quick start - -Download and uncompress a 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. - -@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 - -@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 -@kindex Ctrl-Alt-f -Toggle full screen - -@item Ctrl-Alt-+ -@kindex Ctrl-Alt-+ -Enlarge the screen - -@item Ctrl-Alt-- -@kindex Ctrl-Alt-- -Shrink the screen - -@item Ctrl-Alt-u -@kindex Ctrl-Alt-u -Restore the screen's un-scaled dimensions - -@item Ctrl-Alt-n -@kindex 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 -@kindex Ctrl-Alt -Toggle mouse and keyboard grab. -@end table - -@kindex Ctrl-Up -@kindex Ctrl-Down -@kindex Ctrl-PageUp -@kindex Ctrl-PageDown -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 - -@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 -@kindex Ctrl-a h -Print this help -@item Ctrl-a x -@kindex Ctrl-a x -Exit emulator -@item Ctrl-a s -@kindex Ctrl-a s -Save disk data back to file (if -snapshot) -@item Ctrl-a t -@kindex Ctrl-a t -Toggle console timestamps -@item Ctrl-a b -@kindex Ctrl-a b -Send break (magic sysrq in Linux) -@item Ctrl-a c -@kindex 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 -@kindex 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 - -@node pcsys_monitor -@section QEMU Monitor -@cindex 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{$}. - +@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/cpu-models-x86.texi - -@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 - -@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. - -@node pcsys_other_devs -@section Other Devices - -@subsection 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). - -@subsubsection 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. - -@subsubsection 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. - -@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}). - -@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). - -@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. - - -@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 - -@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 +@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 =20 @node QEMU System emulator for non PC targets @chapter QEMU System emulator for non PC targets @@ -2411,83 +1047,10 @@ to make it close to a 4.5 or newer kernel. =20 @include qemu-deprecated.texi =20 -@node Supported build platforms -@appendix Supported build platforms +@include docs/system/build-platforms.texi =20 -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. +@include docs/system/license.texi =20 -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. - -@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= }. =20 @node Index @appendix Index --=20 2.20.1