From nobody Wed Nov 12 00:08:35 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.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; spf=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1566985041; cv=none; d=zoho.com; s=zohoarc; b=eHyt8Pvj+oKqNLbcLBHiI5w+/lFxiOfsbY89HNCS94dN44RueBXdlSV4Z7gF6jn6/JiornCOS0nOW9SJqFx3YMEP4oHpBN44tjdUzlKJkLNZCp4mkkv+M6R/XTCcHoTD2WeNg5k/N2VmJrnO+KT8dLq+h3+tGvmJr9vEas8M4g4= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1566985041; h=Cc:Date:From:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:Message-ID:Sender:Subject:To:ARC-Authentication-Results; bh=dsi8/ELzH03iyyQTjELVcjQwvp7EHL5yPlB7Faj/X9s=; b=S8FIaQ+igzhQdrr5Nv4JXLZt8H0JORy/1ewDQc4Z5iAq8tMY65ZQrK1sltkci72zYURDymvG6MZC0pS7IVA2a14SpRUBFbdtR7rhXBqPawxkm/n/7izaMifJaelNZTXjE6YQrovHsMIb1Typ004NNh7j17IS/34QnaJPxJOuHuU= ARC-Authentication-Results: i=1; mx.zoho.com; spf=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail 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 1566985041747531.4796164544573; Wed, 28 Aug 2019 02:37:21 -0700 (PDT) Received: from localhost ([::1]:34254 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1i2uOD-00037U-CU for importer@patchew.org; Wed, 28 Aug 2019 05:37:17 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:44236) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1i2uMD-0001Sc-5S for qemu-devel@nongnu.org; Wed, 28 Aug 2019 05:35:18 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1i2uM8-00004y-8i for qemu-devel@nongnu.org; Wed, 28 Aug 2019 05:35:13 -0400 Received: from mx1.redhat.com ([209.132.183.28]:5803) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1i2uLv-0008Nz-Cx; Wed, 28 Aug 2019 05:34:55 -0400 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id B1EDD8667D; Wed, 28 Aug 2019 09:34:54 +0000 (UTC) Received: from thuth.com (ovpn-116-90.ams2.redhat.com [10.36.116.90]) by smtp.corp.redhat.com (Postfix) with ESMTP id 1F4CF6060D; Wed, 28 Aug 2019 09:34:51 +0000 (UTC) From: Thomas Huth To: qemu-devel@nongnu.org, Paolo Bonzini Date: Wed, 28 Aug 2019 11:34:47 +0200 Message-Id: <20190828093447.12441-1-thuth@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.26]); Wed, 28 Aug 2019 09:34:54 +0000 (UTC) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.132.183.28 Subject: [Qemu-devel] [PATCH] qemu-doc: Do not hard-code the name of the QEMU binary 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: , Cc: qemu-trivial@nongnu.org, mrezanin@redhat.com, Eduardo Habkost , qemu-block@nongnu.org, Richard Henderson Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" In our documentation, we use a mix of "$QEMU", "qemu-system-i386" and "qemu-system-x86_64" when we give examples to the users how to run QEMU. Some more consistency would be good here. Also some distributions use different names for the QEMU binary (e.g. "qemu-kvm" in RHEL), so providing more flexibility here would also be good. Thus let's define some variables for the names of the QEMU command and use those in the documentation instead: @value{qemu_system} for generic examples, and @value{qemu_system_x86} for examples that only work with the x86 binaries. Signed-off-by: Thomas Huth Reviewed-by: John Snow Reviewed-by: Miroslav Rezanina --- docs/qemu-block-drivers.texi | 72 ++++++++++---------- docs/qemu-cpu-models.texi | 10 +-- qemu-doc.texi | 81 +++++++++++----------- qemu-options.hx | 128 +++++++++++++++++------------------ 4 files changed, 149 insertions(+), 142 deletions(-) diff --git a/docs/qemu-block-drivers.texi b/docs/qemu-block-drivers.texi index c02547e28c..2c7ea49c32 100644 --- a/docs/qemu-block-drivers.texi +++ b/docs/qemu-block-drivers.texi @@ -2,6 +2,8 @@ QEMU block driver reference manual @c man end =20 +@set qemu_system qemu-system-x86_64 + @c man begin DESCRIPTION =20 @node disk_images_formats @@ -405,7 +407,7 @@ QEMU can automatically create a virtual FAT disk image = from a directory tree. In order to use it, just type: =20 @example -qemu-system-i386 linux.img -hdb fat:/my_directory +@value{qemu_system} linux.img -hdb fat:/my_directory @end example =20 Then you access access to all the files in the @file{/my_directory} @@ -415,14 +417,14 @@ them via SAMBA or NFS. The default access is @emph{re= ad-only}. Floppies can be emulated with the @code{:floppy:} option: =20 @example -qemu-system-i386 linux.img -fda fat:floppy:/my_directory +@value{qemu_system} linux.img -fda fat:floppy:/my_directory @end example =20 A read/write support is available for testing (beta stage) with the @code{:rw:} option: =20 @example -qemu-system-i386 linux.img -fda fat:floppy:rw:/my_directory +@value{qemu_system} linux.img -fda fat:floppy:rw:/my_directory @end example =20 What you should @emph{never} do: @@ -440,14 +442,14 @@ QEMU can access directly to block device exported usi= ng the Network Block Device protocol. =20 @example -qemu-system-i386 linux.img -hdb nbd://my_nbd_server.mydomain.org:1024/ +@value{qemu_system} linux.img -hdb nbd://my_nbd_server.mydomain.org:1024/ @end example =20 If the NBD server is located on the same host, you can use an unix socket = instead of an inet socket: =20 @example -qemu-system-i386 linux.img -hdb nbd+unix://?socket=3D/tmp/my_socket +@value{qemu_system} linux.img -hdb nbd+unix://?socket=3D/tmp/my_socket @end example =20 In this case, the block device must be exported using qemu-nbd: @@ -464,23 +466,23 @@ qemu-nbd --socket=3D/tmp/my_socket --share=3D2 my_dis= k.qcow2 @noindent and then you can use it with two guests: @example -qemu-system-i386 linux1.img -hdb nbd+unix://?socket=3D/tmp/my_socket -qemu-system-i386 linux2.img -hdb nbd+unix://?socket=3D/tmp/my_socket +@value{qemu_system} linux1.img -hdb nbd+unix://?socket=3D/tmp/my_socket +@value{qemu_system} linux2.img -hdb nbd+unix://?socket=3D/tmp/my_socket @end example =20 If the nbd-server uses named exports (supported since NBD 2.9.18, or with = QEMU's own embedded NBD server), you must specify an export name in the URI: @example -qemu-system-i386 -cdrom nbd://localhost/debian-500-ppc-netinst -qemu-system-i386 -cdrom nbd://localhost/openSUSE-11.1-ppc-netinst +@value{qemu_system} -cdrom nbd://localhost/debian-500-ppc-netinst +@value{qemu_system} -cdrom nbd://localhost/openSUSE-11.1-ppc-netinst @end example =20 The URI syntax for NBD is supported since QEMU 1.3. An alternative syntax= is also available. Here are some example of the older syntax: @example -qemu-system-i386 linux.img -hdb nbd:my_nbd_server.mydomain.org:1024 -qemu-system-i386 linux2.img -hdb nbd:unix:/tmp/my_socket -qemu-system-i386 -cdrom nbd:localhost:10809:exportname=3Ddebian-500-ppc-ne= tinst +@value{qemu_system} linux.img -hdb nbd:my_nbd_server.mydomain.org:1024 +@value{qemu_system} linux2.img -hdb nbd:unix:/tmp/my_socket +@value{qemu_system} -cdrom nbd:localhost:10809:exportname=3Ddebian-500-ppc= -netinst @end example =20 @node disk_images_sheepdog @@ -505,7 +507,7 @@ qemu-img convert @var{filename} sheepdog:///@var{image} =20 You can boot from the Sheepdog disk image with the command: @example -qemu-system-i386 sheepdog:///@var{image} +@value{qemu_system} sheepdog:///@var{image} @end example =20 You can also create a snapshot of the Sheepdog image like qcow2. @@ -517,7 +519,7 @@ where @var{tag} is a tag name of the newly created snap= shot. To boot from the Sheepdog snapshot, specify the tag name of the snapshot. @example -qemu-system-i386 sheepdog:///@var{image}#@var{tag} +@value{qemu_system} sheepdog:///@var{image}#@var{tag} @end example =20 You can create a cloned image from the existing snapshot. @@ -530,14 +532,14 @@ is its tag name. You can use an unix socket instead of an inet socket: =20 @example -qemu-system-i386 sheepdog+unix:///@var{image}?socket=3D@var{path} +@value{qemu_system} sheepdog+unix:///@var{image}?socket=3D@var{path} @end example =20 If the Sheepdog daemon doesn't run on the local host, you need to specify one of the Sheepdog servers to connect to. @example qemu-img create sheepdog://@var{hostname}:@var{port}/@var{image} @var{size} -qemu-system-i386 sheepdog://@var{hostname}:@var{port}/@var{image} +@value{qemu_system} sheepdog://@var{hostname}:@var{port}/@var{image} @end example =20 @node disk_images_iscsi @@ -627,7 +629,7 @@ cat >iscsi.conf < /sys/bus/pci/devices/0000:06:0d.0/driver/unbind # echo 1102 0002 > /sys/bus/pci/drivers/vfio-pci/new_id =20 -# qemu-system-x86_64 -drive file=3Dnvme://@var{host}:@var{bus}:@var{slot}.= @var{func}/@var{namespace} +# @value{qemu_system} -drive file=3Dnvme://@var{host}:@var{bus}:@var{slot}= .@var{func}/@var{namespace} @end example =20 Alternative syntax using properties: =20 @example -qemu-system-x86_64 -drive file.driver=3Dnvme,file.device=3D@var{host}:@var= {bus}:@var{slot}.@var{func},file.namespace=3D@var{namespace} +@value{qemu_system} -drive file.driver=3Dnvme,file.device=3D@var{host}:@va= r{bus}:@var{slot}.@var{func},file.namespace=3D@var{namespace} @end example =20 @var{host}:@var{bus}:@var{slot}.@var{func} is the NVMe controller's PCI de= vice diff --git a/docs/qemu-cpu-models.texi b/docs/qemu-cpu-models.texi index ad040cfc98..f88a1def0d 100644 --- a/docs/qemu-cpu-models.texi +++ b/docs/qemu-cpu-models.texi @@ -2,6 +2,8 @@ QEMU / KVM CPU model configuration @c man end =20 +@set qemu_system_x86 qemu-system-x86_64 + @c man begin DESCRIPTION =20 @menu @@ -578,25 +580,25 @@ CPU models / features in QEMU and libvirt @item Host passthrough =20 @example - $ qemu-system-x86_64 -cpu host + $ @value{qemu_system_x86} -cpu host @end example =20 With feature customization: =20 @example - $ qemu-system-x86_64 -cpu host,-vmx,... + $ @value{qemu_system_x86} -cpu host,-vmx,... @end example =20 @item Named CPU models =20 @example - $ qemu-system-x86_64 -cpu Westmere + $ @value{qemu_system_x86} -cpu Westmere @end example =20 With feature customization: =20 @example - $ qemu-system-x86_64 -cpu Westmere,+pcid,... + $ @value{qemu_system_x86} -cpu Westmere,+pcid,... @end example =20 @end table diff --git a/qemu-doc.texi b/qemu-doc.texi index 577d1e8376..b2654c76a0 100644 --- a/qemu-doc.texi +++ b/qemu-doc.texi @@ -11,6 +11,9 @@ @paragraphindent 0 @c %**end of header =20 +@set qemu_system qemu-system-x86_64 +@set qemu_system_x86 qemu-system-x86_64 + @ifinfo @direntry * QEMU: (qemu-doc). The QEMU Emulator User Documentation. @@ -207,12 +210,12 @@ Note that, by default, GUS shares IRQ(7) with paralle= l ports and so QEMU must be told to not have parallel ports to have working GUS. =20 @example -qemu-system-i386 dos.img -soundhw gus -parallel none +@value{qemu_system_x86} dos.img -soundhw gus -parallel none @end example =20 Alternatively: @example -qemu-system-i386 dos.img -device gus,irq=3D5 +@value{qemu_system_x86} dos.img -device gus,irq=3D5 @end example =20 Or some other unclaimed IRQ. @@ -225,10 +228,11 @@ CS4231A is the chip used in Windows Sound System and = GUSMAX products @section Quick Start @cindex quick start =20 -Download and uncompress the linux image (@file{linux.img}) and type: +Download and uncompress a hard disk image with Linux installed (e.g. +@file{linux.img}) and type: =20 @example -qemu-system-i386 linux.img +@value{qemu_system} linux.img @end example =20 Linux should boot and give you a prompt. @@ -238,7 +242,7 @@ Linux should boot and give you a prompt. =20 @example @c man begin SYNOPSIS -@command{qemu-system-i386} [@var{options}] [@var{disk_image}] +@command{@value{qemu_system}} [@var{options}] [@var{disk_image}] @c man end @end example =20 @@ -278,21 +282,21 @@ is specified in seconds. The default is 0 which means= no timeout. Libiscsi =20 Example (without authentication): @example -qemu-system-i386 -iscsi initiator-name=3Diqn.2001-04.com.example:my-initia= tor \ +@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 =20 Example (CHAP username/password via URL): @example -qemu-system-i386 -drive file=3Discsi://user%password@@192.0.2.1/iqn.2001-0= 4.com.example/1 +@value{qemu_system} -drive file=3Discsi://user%password@@192.0.2.1/iqn.200= 1-04.com.example/1 @end example =20 Example (CHAP username/password via environment variables): @example LIBISCSI_CHAP_USERNAME=3D"user" \ LIBISCSI_CHAP_PASSWORD=3D"password" \ -qemu-system-i386 -drive file=3Discsi://192.0.2.1/iqn.2001-04.com.example/1 +@value{qemu_system} -drive file=3Discsi://192.0.2.1/iqn.2001-04.com.exampl= e/1 @end example =20 @item NBD @@ -307,12 +311,12 @@ Syntax for specifying a NBD device using Unix Domain = Sockets =20 Example for TCP @example -qemu-system-i386 --drive file=3Dnbd:192.0.2.1:30000 +@value{qemu_system} --drive file=3Dnbd:192.0.2.1:30000 @end example =20 Example for Unix Domain Sockets @example -qemu-system-i386 --drive file=3Dnbd:unix:/tmp/nbd-socket +@value{qemu_system} --drive file=3Dnbd:unix:/tmp/nbd-socket @end example =20 @item SSH @@ -320,8 +324,8 @@ QEMU supports SSH (Secure Shell) access to remote disks. =20 Examples: @example -qemu-system-i386 -drive file=3Dssh://user@@host/path/to/disk.img -qemu-system-i386 -drive file.driver=3Dssh,file.user=3Duser,file.host=3Dhos= t,file.port=3D22,file.path=3D/path/to/disk.img +@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 =20 Currently authentication must be done using ssh-agent. Other @@ -339,7 +343,7 @@ sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=3Dpa= th][#snapid|#tag] =20 Example @example -qemu-system-i386 --drive file=3Dsheepdog://192.0.2.1:30000/MyVirtualMachine +@value{qemu_system} --drive file=3Dsheepdog://192.0.2.1:30000/MyVirtualMac= hine @end example =20 See also @url{https://sheepdog.github.io/sheepdog/}. @@ -365,17 +369,17 @@ JSON: Example @example URI: -qemu-system-x86_64 --drive file=3Dgluster://192.0.2.1/testvol/a.img, +@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 =20 JSON: -qemu-system-x86_64 'json:@{"driver":"qcow2", +@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"@}]@}@}' -qemu-system-x86_64 -drive driver=3Dqcow2,file.driver=3Dgluster,file.volume= =3Dtestvol,file.path=3D/path/a.img, +@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 @@ -440,9 +444,9 @@ of . =20 Example: boot from a remote Fedora 20 live ISO image @example -qemu-system-x86_64 --drive media=3Dcdrom,file=3Dhttp://dl.fedoraproject.or= g/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.= iso,readonly +@value{qemu_system_x86} --drive media=3Dcdrom,file=3Dhttp://dl.fedoraproje= ct.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-= 20-1.iso,readonly =20 -qemu-system-x86_64 --drive media=3Dcdrom,file.driver=3Dhttp,file.url=3Dhtt= p://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Li= ve-Desktop-x86_64-20-1.iso,readonly +@value{qemu_system_x86} --drive media=3Dcdrom,file.driver=3Dhttp,file.url= =3Dhttp://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fed= ora-Live-Desktop-x86_64-20-1.iso,readonly @end example =20 Example: boot from a remote Fedora 20 cloud image using a local overlay for @@ -450,7 +454,7 @@ 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":"https://dl.fedoraproject.org/pub/fedora/linux/releases/20/Image= s/x86_64/Fedora-x86_64-20-20131211.1-sda.qcow2",, "file.readahead":"64k"@}'= /tmp/Fedora-x86_64-20-20131211.1-sda.qcow2 =20 -qemu-system-x86_64 -drive file=3D/tmp/Fedora-x86_64-20-20131211.1-sda.qcow= 2,copy-on-read=3Don +@value{qemu_system_x86} -drive file=3D/tmp/Fedora-x86_64-20-20131211.1-sda= .qcow2,copy-on-read=3Don @end example =20 Example: boot from an image stored on a VMware vSphere server with a self-= signed @@ -459,7 +463,7 @@ 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 =20 -qemu-system-x86_64 -drive file=3D/tmp/test.qcow2 +@value{qemu_system_x86} -drive file=3D/tmp/test.qcow2 @end example =20 @end table @@ -826,7 +830,7 @@ On Linux hosts, a shared memory device is available. T= he basic syntax is: =20 @example -qemu-system-x86_64 -device ivshmem-plain,memdev=3D@var{hostmem} +@value{qemu_system_x86} -device ivshmem-plain,memdev=3D@var{hostmem} @end example =20 where @var{hostmem} names a host memory backend. For a POSIX shared @@ -847,7 +851,7 @@ memory server is: ivshmem-server -p @var{pidfile} -S @var{path} -m @var{shm-name} -l @var{sh= m-size} -n @var{vectors} =20 # Then start your qemu instances with matching arguments -qemu-system-x86_64 -device ivshmem-doorbell,vectors=3D@var{vectors},charde= v=3D@var{id} +@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 =20 @@ -872,7 +876,7 @@ Instead of specifying the using POSIX shm, y= ou may specify a memory backend that has hugepage support: =20 @example -qemu-system-x86_64 -object memory-backend-file,size=3D1G,mem-path=3D/dev/h= ugepages/my-shmem-file,share,id=3Dmb1 +@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 =20 @@ -888,7 +892,7 @@ kernel testing. =20 The syntax is: @example -qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -appe= nd "root=3D/dev/hda" +@value{qemu_system} -kernel bzImage -hda rootdisk.img -append "root=3D/dev= /hda" @end example =20 Use @option{-kernel} to provide the Linux kernel image and @@ -903,7 +907,7 @@ 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 -qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \ +@value{qemu_system} -kernel bzImage -hda rootdisk.img \ -append "root=3D/dev/hda console=3DttyS0" -nographic @end example =20 @@ -969,7 +973,7 @@ Network adapter that supports CDC ethernet and RNDIS pr= otocols. @var{id} specifies a netdev defined with @code{-netdev @dots{},id=3D@var{id}}. For instance, user-mode networking can be used with @example -qemu-system-i386 [...] -netdev user,id=3Dnet0 -device usb-net,netdev=3Dnet0 +@value{qemu_system} [...] -netdev user,id=3Dnet0 -device usb-net,netdev=3D= net0 @end example @item usb-ccid Smartcard reader device @@ -988,7 +992,7 @@ no type is given, the HCI logic corresponds to @code{-b= t hci,vlan=3D0}. This USB device implements the USB Transport Layer of HCI. Example usage: @example -@command{qemu-system-i386} [...@var{OPTIONS}...] @option{-usbdevice} bt:hc= i,vlan=3D3 @option{-bt} device:keyboard,vlan=3D3 +@command{@value{qemu_system}} [...@var{OPTIONS}...] @option{-usbdevice} bt= :hci,vlan=3D3 @option{-bt} device:keyboard,vlan=3D3 @end example @end table =20 @@ -1065,7 +1069,7 @@ For this setup it is recommended to restrict it to li= sten on a UNIX domain socket only. For example =20 @example -qemu-system-i386 [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc +@value{qemu_system} [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-v= nc @end example =20 This ensures that only users on local box with read/write access to that @@ -1088,7 +1092,7 @@ is running the password is set with the monitor. Unti= l the monitor is used to set the password all clients will be rejected. =20 @example -qemu-system-i386 [...OPTIONS...] -vnc :1,password -monitor stdio +@value{qemu_system} [...OPTIONS...] -vnc :1,password -monitor stdio (qemu) change vnc password Password: ******** (qemu) @@ -1105,7 +1109,7 @@ support provides a secure session, but no authenticat= ion. This allows any client to connect, and provides an encrypted session. =20 @example -qemu-system-i386 [...OPTIONS...] \ +@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 @@ -1127,7 +1131,7 @@ same syntax as previously, but with @code{verify-peer= } set to @code{yes} instead. =20 @example -qemu-system-i386 [...OPTIONS...] \ +@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 @@ -1140,7 +1144,7 @@ Finally, the previous method can be combined with VNC= password authentication to provide two layers of authentication for clients. =20 @example -qemu-system-i386 [...OPTIONS...] \ +@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 @@ -1165,7 +1169,7 @@ used for authentication, but assuming use of one supp= orting SSF, then QEMU can be launched with: =20 @example -qemu-system-i386 [...OPTIONS...] -vnc :1,sasl -monitor stdio +@value{qemu_system} [...OPTIONS...] -vnc :1,sasl -monitor stdio @end example =20 @node vnc_sec_certificate_sasl @@ -1179,7 +1183,7 @@ credentials. This can be enabled, by combining the 's= asl' option with the aforementioned TLS + x509 options: =20 @example -qemu-system-i386 [...OPTIONS...] \ +@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 @@ -1512,13 +1516,13 @@ To load server credentials with client certificate = validation enabled =20 @example -$QEMU -object tls-creds-x509,id=3Dtls0,dir=3D/etc/pki/qemu,endpoint=3Dserv= er +@value{qemu_system} -object tls-creds-x509,id=3Dtls0,dir=3D/etc/pki/qemu,e= ndpoint=3Dserver @end example =20 while to load client credentials use =20 @example -$QEMU -object tls-creds-x509,id=3Dtls0,dir=3D/etc/pki/qemu,endpoint=3Dclie= nt +@value{qemu_system} -object tls-creds-x509,id=3Dtls0,dir=3D/etc/pki/qemu,e= ndpoint=3Dclient @end example =20 Network services which support TLS will all have a @code{tls-creds} @@ -1526,7 +1530,7 @@ parameter which expects the ID of the TLS credentials= object. For example with VNC: =20 @example -$QEMU -vnc 0.0.0.0:0,tls-creds=3Dtls0 +@value{qemu_system} -vnc 0.0.0.0:0,tls-creds=3Dtls0 @end example =20 @node tls_psk @@ -1574,8 +1578,7 @@ QEMU has a primitive support to work with gdb, so tha= t you can do In order to use gdb, launch QEMU with the '-s' option. It will wait for a gdb connection: @example -qemu-system-i386 -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \ - -append "root=3D/dev/hda" +@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 diff --git a/qemu-options.hx b/qemu-options.hx index ea0638e92d..09e6439646 100644 --- a/qemu-options.hx +++ b/qemu-options.hx @@ -254,10 +254,10 @@ This option defines a free-form string that can be us= ed to describe @var{fd}. =20 You can open an image using pre-opened file descriptors from an fd set: @example -qemu-system-i386 --add-fd fd=3D3,set=3D2,opaque=3D"rdwr:/path/to/file" --add-fd fd=3D4,set=3D2,opaque=3D"rdonly:/path/to/file" --drive file=3D/dev/fdset/2,index=3D0,media=3Ddisk +@value{qemu_system} \ + -add-fd fd=3D3,set=3D2,opaque=3D"rdwr:/path/to/file" \ + -add-fd fd=3D4,set=3D2,opaque=3D"rdonly:/path/to/file" \ + -drive file=3D/dev/fdset/2,index=3D0,media=3Ddisk @end example ETEXI =20 @@ -283,7 +283,7 @@ STEXI Set default value of @var{driver}'s property @var{prop} to @var{value}, e.= g.: =20 @example -qemu-system-i386 -global ide-hd.physical_block_size=3D4096 disk-image.img +@value{qemu_system_x86} -global ide-hd.physical_block_size=3D4096 disk-ima= ge.img @end example =20 In particular, you can use this to set driver properties for devices which= are @@ -337,11 +337,11 @@ bootindex options. The default is non-strict boot. =20 @example # try to boot from network first, then from hard disk -qemu-system-i386 -boot order=3Dnc +@value{qemu_system_x86} -boot order=3Dnc # boot from CD-ROM first, switch back to default order after reboot -qemu-system-i386 -boot once=3Dd +@value{qemu_system_x86} -boot once=3Dd # boot with a splash picture for 5 seconds. -qemu-system-i386 -boot menu=3Don,splash=3D/root/boot.bmp,splash-time=3D5000 +@value{qemu_system_x86} -boot menu=3Don,splash=3D/root/boot.bmp,splash-tim= e=3D5000 @end example =20 Note: The legacy format '-boot @var{drives}' is still supported but its @@ -370,7 +370,7 @@ For example, the following command-line sets the guest = startup RAM size to memory the guest can reach to 4GB: =20 @example -qemu-system-x86_64 -m 1G,slots=3D3,maxmem=3D4G +@value{qemu_system} -m 1G,slots=3D3,maxmem=3D4G @end example =20 If @var{slots} and @var{maxmem} are not specified, memory hotplug won't @@ -666,15 +666,15 @@ STEXI @item -soundhw @var{card1}[,@var{card2},...] or -soundhw all @findex -soundhw Enable audio and selected sound hardware. Use 'help' to print all -available sound hardware. +available sound hardware. For example: =20 @example -qemu-system-i386 -soundhw sb16,adlib disk.img -qemu-system-i386 -soundhw es1370 disk.img -qemu-system-i386 -soundhw ac97 disk.img -qemu-system-i386 -soundhw hda disk.img -qemu-system-i386 -soundhw all disk.img -qemu-system-i386 -soundhw help +@value{qemu_system_x86} -soundhw sb16,adlib disk.img +@value{qemu_system_x86} -soundhw es1370 disk.img +@value{qemu_system_x86} -soundhw ac97 disk.img +@value{qemu_system_x86} -soundhw hda disk.img +@value{qemu_system_x86} -soundhw all disk.img +@value{qemu_system_x86} -soundhw help @end example =20 Note that Linux's i810_audio OSS kernel (for AC97) module might @@ -1149,50 +1149,50 @@ is off. =20 Instead of @option{-cdrom} you can use: @example -qemu-system-i386 -drive file=3Dfile,index=3D2,media=3Dcdrom +@value{qemu_system} -drive file=3Dfile,index=3D2,media=3Dcdrom @end example =20 Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you= can use: @example -qemu-system-i386 -drive file=3Dfile,index=3D0,media=3Ddisk -qemu-system-i386 -drive file=3Dfile,index=3D1,media=3Ddisk -qemu-system-i386 -drive file=3Dfile,index=3D2,media=3Ddisk -qemu-system-i386 -drive file=3Dfile,index=3D3,media=3Ddisk +@value{qemu_system} -drive file=3Dfile,index=3D0,media=3Ddisk +@value{qemu_system} -drive file=3Dfile,index=3D1,media=3Ddisk +@value{qemu_system} -drive file=3Dfile,index=3D2,media=3Ddisk +@value{qemu_system} -drive file=3Dfile,index=3D3,media=3Ddisk @end example =20 You can open an image using pre-opened file descriptors from an fd set: @example -qemu-system-i386 --add-fd fd=3D3,set=3D2,opaque=3D"rdwr:/path/to/file" --add-fd fd=3D4,set=3D2,opaque=3D"rdonly:/path/to/file" --drive file=3D/dev/fdset/2,index=3D0,media=3Ddisk +@value{qemu_system} \ + -add-fd fd=3D3,set=3D2,opaque=3D"rdwr:/path/to/file" \ + -add-fd fd=3D4,set=3D2,opaque=3D"rdonly:/path/to/file" \ + -drive file=3D/dev/fdset/2,index=3D0,media=3Ddisk @end example =20 You can connect a CDROM to the slave of ide0: @example -qemu-system-i386 -drive file=3Dfile,if=3Dide,index=3D1,media=3Dcdrom +@value{qemu_system_x86} -drive file=3Dfile,if=3Dide,index=3D1,media=3Dcdrom @end example =20 If you don't specify the "file=3D" argument, you define an empty drive: @example -qemu-system-i386 -drive if=3Dide,index=3D1,media=3Dcdrom +@value{qemu_system_x86} -drive if=3Dide,index=3D1,media=3Dcdrom @end example =20 Instead of @option{-fda}, @option{-fdb}, you can use: @example -qemu-system-i386 -drive file=3Dfile,index=3D0,if=3Dfloppy -qemu-system-i386 -drive file=3Dfile,index=3D1,if=3Dfloppy +@value{qemu_system_x86} -drive file=3Dfile,index=3D0,if=3Dfloppy +@value{qemu_system_x86} -drive file=3Dfile,index=3D1,if=3Dfloppy @end example =20 By default, @var{interface} is "ide" and @var{index} is automatically incremented: @example -qemu-system-i386 -drive file=3Da -drive file=3Db" +@value{qemu_system_x86} -drive file=3Da -drive file=3Db" @end example is interpreted like: @example -qemu-system-i386 -hda a -hdb b +@value{qemu_system_x86} -hda a -hdb b @end example ETEXI =20 @@ -2272,8 +2272,8 @@ The following two example do exactly the same, to sho= w how @option{-nic} can be used to shorten the command line length (note that the e1000 is the def= ault on i386, so the @option{model=3De1000} parameter could even be omitted her= e, too): @example -qemu-system-i386 -netdev user,id=3Dn1,ipv6=3Doff -device e1000,netdev=3Dn1= ,mac=3D52:54:98:76:54:32 -qemu-system-i386 -nic user,ipv6=3Doff,model=3De1000,mac=3D52:54:98:76:54:32 +@value{qemu_system} -netdev user,id=3Dn1,ipv6=3Doff -device e1000,netdev= =3Dn1,mac=3D52:54:98:76:54:32 +@value{qemu_system} -nic user,ipv6=3Doff,model=3De1000,mac=3D52:54:98:76:5= 4:32 @end example =20 @item -nic none @@ -2344,7 +2344,7 @@ can not be resolved. =20 Example: @example -qemu-system-i386 -nic user,dnssearch=3Dmgmt.example.org,dnssearch=3Dexampl= e.org +@value{qemu_system} -nic user,dnssearch=3Dmgmt.example.org,dnssearch=3Dexa= mple.org @end example =20 @item domainname=3D@var{domain} @@ -2368,7 +2368,7 @@ a guest from a local directory. =20 Example (using pxelinux): @example -qemu-system-i386 -hda linux.img -boot n -device e1000,netdev=3Dn1 \ +@value{qemu_system} -hda linux.img -boot n -device e1000,netdev=3Dn1 \ -netdev user,id=3Dn1,tftp=3D/path/to/tftp/files,bootfile=3D/pxelinux.0 @end example =20 @@ -2402,7 +2402,7 @@ screen 0, use the following: =20 @example # on the host -qemu-system-i386 -nic user,hostfwd=3Dtcp:127.0.0.1:6001-:6000 +@value{qemu_system} -nic user,hostfwd=3Dtcp:127.0.0.1:6001-:6000 # this host xterm should open in the guest X11 server xterm -display :1 @end example @@ -2412,7 +2412,7 @@ the guest, use the following: =20 @example # on the host -qemu-system-i386 -nic user,hostfwd=3Dtcp::5555-:23 +@value{qemu_system} -nic user,hostfwd=3Dtcp::5555-:23 telnet localhost 5555 @end example =20 @@ -2431,7 +2431,7 @@ lifetime, like in the following example: @example # open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever # the guest accesses it -qemu-system-i386 -nic user,guestfwd=3Dtcp:10.0.2.100:1234-tcp:10.10.1.1:43= 21 +@value{qemu_system} -nic user,guestfwd=3Dtcp:10.0.2.100:1234-tcp:10.10.1.1= :4321 @end example =20 Or you can execute a command on every TCP connection established by the gu= est, @@ -2440,7 +2440,7 @@ so that QEMU behaves similar to an inetd process for = that virtual server: @example # call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234 # and connect the TCP stream to its stdin/stdout -qemu-system-i386 -nic 'user,id=3Dn1,guestfwd=3Dtcp:10.0.2.100:1234-cmd:ne= tcat 10.10.1.1 4321' +@value{qemu_system} -nic 'user,id=3Dn1,guestfwd=3Dtcp:10.0.2.100:1234-cmd= :netcat 10.10.1.1 4321' @end example =20 @end table @@ -2467,13 +2467,13 @@ Examples: =20 @example #launch a QEMU instance with the default network script -qemu-system-i386 linux.img -nic tap +@value{qemu_system} linux.img -nic tap @end example =20 @example #launch a QEMU instance with two NICs, each one connected #to a TAP device -qemu-system-i386 linux.img \ +@value{qemu_system} linux.img \ -netdev tap,id=3Dnd0,ifname=3Dtap0 -device e1000,netdev=3Dnd0 \ -netdev tap,id=3Dnd1,ifname=3Dtap1 -device rtl8139,netdev=3Dnd1 @end example @@ -2481,7 +2481,7 @@ qemu-system-i386 linux.img \ @example #launch a QEMU instance with the default network helper to #connect a TAP device to bridge br0 -qemu-system-i386 linux.img -device virtio-net-pci,netdev=3Dn1 \ +@value{qemu_system} linux.img -device virtio-net-pci,netdev=3Dn1 \ -netdev tap,id=3Dn1,"helper=3D/path/to/qemu-bridge-helper" @end example =20 @@ -2498,13 +2498,13 @@ Examples: @example #launch a QEMU instance with the default network helper to #connect a TAP device to bridge br0 -qemu-system-i386 linux.img -netdev bridge,id=3Dn1 -device virtio-net,netde= v=3Dn1 +@value{qemu_system} linux.img -netdev bridge,id=3Dn1 -device virtio-net,ne= tdev=3Dn1 @end example =20 @example #launch a QEMU instance with the default network helper to #connect a TAP device to bridge qemubr0 -qemu-system-i386 linux.img -netdev bridge,br=3Dqemubr0,id=3Dn1 -device vir= tio-net,netdev=3Dn1 +@value{qemu_system} linux.img -netdev bridge,br=3Dqemubr0,id=3Dn1 -device = virtio-net,netdev=3Dn1 @end example =20 @item -netdev socket,id=3D@var{id}[,fd=3D@var{h}][,listen=3D[@var{host}]:@= var{port}][,connect=3D@var{host}:@var{port}] @@ -2519,11 +2519,11 @@ specifies an already opened TCP socket. Example: @example # launch a first QEMU instance -qemu-system-i386 linux.img \ +@value{qemu_system} linux.img \ -device e1000,netdev=3Dn1,mac=3D52:54:00:12:34:56 \ -netdev socket,id=3Dn1,listen=3D:1234 # connect the network of this instance to the network of the first instance -qemu-system-i386 linux.img \ +@value{qemu_system} linux.img \ -device e1000,netdev=3Dn2,mac=3D52:54:00:12:34:57 \ -netdev socket,id=3Dn2,connect=3D127.0.0.1:1234 @end example @@ -2548,15 +2548,15 @@ Use @option{fd=3Dh} to specify an already opened UD= P multicast socket. Example: @example # launch one QEMU instance -qemu-system-i386 linux.img \ +@value{qemu_system} linux.img \ -device e1000,netdev=3Dn1,mac=3D52:54:00:12:34:56 \ -netdev socket,id=3Dn1,mcast=3D230.0.0.1:1234 # launch another QEMU instance on same "bus" -qemu-system-i386 linux.img \ +@value{qemu_system} linux.img \ -device e1000,netdev=3Dn2,mac=3D52:54:00:12:34:57 \ -netdev socket,id=3Dn2,mcast=3D230.0.0.1:1234 # launch yet another QEMU instance on same "bus" -qemu-system-i386 linux.img \ +@value{qemu_system} linux.img \ -device e1000,netdev=3Dn3,mac=3D52:54:00:12:34:58 \ -netdev socket,id=3Dn3,mcast=3D230.0.0.1:1234 @end example @@ -2564,7 +2564,7 @@ qemu-system-i386 linux.img \ Example (User Mode Linux compat.): @example # launch QEMU instance (note mcast address selected is UML's default) -qemu-system-i386 linux.img \ +@value{qemu_system} linux.img \ -device e1000,netdev=3Dn1,mac=3D52:54:00:12:34:56 \ -netdev socket,id=3Dn1,mcast=3D239.192.168.1:1102 # launch UML @@ -2573,7 +2573,7 @@ qemu-system-i386 linux.img \ =20 Example (send packets from host's 1.2.3.4): @example -qemu-system-i386 linux.img \ +@value{qemu_system} linux.img \ -device e1000,netdev=3Dn1,mac=3D52:54:00:12:34:56 \ -netdev socket,id=3Dn1,mcast=3D239.192.168.1:1102,localad= dr=3D1.2.3.4 @end example @@ -2633,7 +2633,7 @@ brctl addif br-lan vmtunnel0 # on 4.3.2.1 # launch QEMU instance - if your network has reorder or is very lossy add = ,pincounter =20 -qemu-system-i386 linux.img -device e1000,netdev=3Dn1 \ +@value{qemu_system} linux.img -device e1000,netdev=3Dn1 \ -netdev l2tpv3,id=3Dn1,src=3D4.2.3.1,dst=3D1.2.3.4,udp,srcport=3D16384= ,dstport=3D16384,rxsession=3D0xffffffff,txsession=3D0xffffffff,counter =20 @end example @@ -2650,7 +2650,7 @@ Example: # launch vde switch vde_switch -F -sock /tmp/myswitch # launch QEMU instance -qemu-system-i386 linux.img -nic vde,sock=3D/tmp/myswitch +@value{qemu_system} linux.img -nic vde,sock=3D/tmp/myswitch @end example =20 @item -netdev vhost-user,chardev=3D@var{id}[,vhostforce=3Don|off][,queues= =3Dn] @@ -3107,7 +3107,7 @@ and communicate. Requires the Linux @code{vhci} driv= er installed. Can be used as following: =20 @example -qemu-system-i386 [...OPTIONS...] -bt hci,vlan=3D5 -bt vhci,vlan=3D5 +@value{qemu_system} [...OPTIONS...] -bt hci,vlan=3D5 -bt vhci,vlan=3D5 @end example =20 @item -bt device:@var{dev}[,vlan=3D@var{n}] @@ -3601,7 +3601,7 @@ connections will likely be TCP-based, but also UDP, p= seudo TTY, or even stdio are reasonable use case. The latter is allowing to start QEMU from within gdb and establish the connection via a pipe: @example -(gdb) target remote | exec qemu-system-i386 -gdb stdio ... +(gdb) target remote | exec @value{qemu_system} -gdb stdio ... @end example ETEXI =20 @@ -4571,7 +4571,7 @@ which specify the queue number of cryptodev backend, = the default of =20 @example =20 - # qemu-system-x86_64 \ + # @value{qemu_system} \ [...] \ -object cryptodev-backend-builtin,id=3Dcryptodev0 \ -device virtio-crypto-pci,id=3Dcrypto0,cryptodev=3Dcryptodev0 \ @@ -4591,7 +4591,7 @@ of cryptodev backend for multiqueue vhost-user, the d= efault of @var{queues} is 1 =20 @example =20 - # qemu-system-x86_64 \ + # @value{qemu_system} \ [...] \ -chardev socket,id=3Dchardev0,path=3D/path/to/socket \ -object cryptodev-vhost-user,id=3Dcryptodev0,chardev=3Dchardev0 \ @@ -4627,14 +4627,14 @@ The simplest (insecure) usage is to provide the sec= ret inline =20 @example =20 - # $QEMU -object secret,id=3Dsec0,data=3Dletmein,format=3Draw + # @value{qemu_system} -object secret,id=3Dsec0,data=3Dletmein,format=3Draw =20 @end example =20 The simplest secure usage is to provide the secret via a file =20 # printf "letmein" > mypasswd.txt - # $QEMU -object secret,id=3Dsec0,file=3Dmypasswd.txt,format=3Draw + # @value{qemu_system} -object secret,id=3Dsec0,file=3Dmypasswd.txt,format= =3Draw =20 For greater security, AES-256-CBC should be used. To illustrate usage, consider the openssl command line tool which can encrypt the data. Note @@ -4670,7 +4670,7 @@ and specify that to be used to decrypt the user passw= ord. Pass the contents of @code{iv.b64} to the second secret =20 @example - # $QEMU \ + # @value{qemu_system} \ -object secret,id=3Dsecmaster0,format=3Dbase64,file=3Dkey.b64 \ -object secret,id=3Dsec0,keyid=3Dsecmaster0,format=3Dbase64,\ data=3D$SECRET,iv=3D$(