1QEMU.1(1) QEMU.1(1)
2
6 qemu-doc - QEMU version 3.0.1 User Documentation
7
9 qemu-system-i386 [options] [disk_image]
10
12 The QEMU PC System emulator simulates the following peripherals:
13 - i440FX host PCI bridge and PIIX3 PCI to ISA bridge
15 - Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
17 extensions (hardware level, including all non standard modes).
18 - PS/2 mouse and keyboard
20 - 2 PCI IDE interfaces with hard disk and CD-ROM support
22 - Floppy disk
24 - PCI and ISA network adapters
26 - Serial ports
28 - IPMI BMC, either and internal or external one
30 - Creative SoundBlaster 16 sound card
32 - ENSONIQ AudioPCI ES1370 sound card
34 - Intel 82801AA AC97 Audio compatible sound card
36 - Intel HD Audio Controller and HDA codec
38 - Adlib (OPL2) - Yamaha YM3812 compatible chip
40 - Gravis Ultrasound GF1 sound card
42 - CS4231A compatible sound card
44 - PCI UHCI, OHCI, EHCI or XHCI USB controller and a virtual USB-1.1
46 hub.
47 SMP is supported with up to 255 CPUs.
49 QEMU uses the PC BIOS from the Seabios project and the Plex86/Bochs
51 LGPL VGA BIOS.
52 QEMU uses YM3812 emulation by Tatsuyuki Satoh.
54 QEMU uses GUS emulation (GUSEMU32 <http://www.deinmeister.de/gusemu/>)
56 by Tibor "TS" Schütz.
57 Note that, by default, GUS shares IRQ(7) with parallel ports and so
59 QEMU must be told to not have parallel ports to have working GUS.
60 qemu-system-i386 dos.img -soundhw gus -parallel none
62 Alternatively:
64 qemu-system-i386 dos.img -device gus,irq=5
66 Or some other unclaimed IRQ.
68 CS4231A is the chip used in Windows Sound System and GUSMAX products
70
72 disk_image is a raw hard disk image for IDE hard disk 0. Some targets
73 do not need a disk image.
74 Standard options
76 -h Display help and exit
78 -version
80 Display version information and exit
81 -machine [type=]name[,prop=value[,...]]
83 Select the emulated machine by name. Use "-machine help" to list
84 available machines.
85 For architectures which aim to support live migration compatibility
87 across releases, each release will introduce a new versioned
88 machine type. For example, the 2.8.0 release introduced machine
89 types "pc-i440fx-2.8" and "pc-q35-2.8" for the x86_64/i686
90 architectures.
91 To allow live migration of guests from QEMU version 2.8.0, to QEMU
93 version 2.9.0, the 2.9.0 version must support the "pc-i440fx-2.8"
94 and "pc-q35-2.8" machines too. To allow users live migrating VMs to
95 skip multiple intermediate releases when upgrading, new releases of
96 QEMU will support machine types from many previous versions.
97 Supported machine properties are:
99 accel=accels1[:accels2[:...]]
101 This is used to enable an accelerator. Depending on the target
102 architecture, kvm, xen, hax, hvf, whpx or tcg can be available.
103 By default, tcg is used. If there is more than one accelerator
104 specified, the next one is used if the previous one fails to
105 initialize.
106 kernel_irqchip=on|off
108 Controls in-kernel irqchip support for the chosen accelerator
109 when available.
110 gfx_passthru=on|off
112 Enables IGD GFX passthrough support for the chosen machine when
113 available.
114 vmport=on|off|auto
116 Enables emulation of VMWare IO port, for vmmouse etc. auto says
117 to select the value based on accel. For accel=xen the default
118 is off otherwise the default is on.
119 kvm_shadow_mem=size
121 Defines the size of the KVM shadow MMU.
122 dump-guest-core=on|off
124 Include guest memory in a core dump. The default is on.
125 mem-merge=on|off
127 Enables or disables memory merge support. This feature, when
128 supported by the host, de-duplicates identical memory pages
129 among VMs instances (enabled by default).
130 aes-key-wrap=on|off
132 Enables or disables AES key wrapping support on s390-ccw hosts.
133 This feature controls whether AES wrapping keys will be created
134 to allow execution of AES cryptographic functions. The default
135 is on.
136 dea-key-wrap=on|off
138 Enables or disables DEA key wrapping support on s390-ccw hosts.
139 This feature controls whether DEA wrapping keys will be created
140 to allow execution of DEA cryptographic functions. The default
141 is on.
142 nvdimm=on|off
144 Enables or disables NVDIMM support. The default is off.
145 s390-squash-mcss=on|off
147 Enables or disables squashing subchannels into the default css.
148 The default is off. NOTE: This property is deprecated and will
149 be removed in future releases. The "s390-squash-mcss=on"
150 property has been obsoleted by allowing the cssid to be chosen
151 freely. Instead of squashing subchannels into the default
152 channel subsystem image for guests that do not support multiple
153 channel subsystems, all devices can be put into the default
154 channel subsystem image.
155 enforce-config-section=on|off
157 If enforce-config-section is set to on, force migration code to
158 send configuration section even if the machine-type sets the
159 migration.send-configuration property to off. NOTE: this
160 parameter is deprecated. Please use -global
161 migration.send-configuration=on|off instead.
162 memory-encryption=
164 Memory encryption object to use. The default is none.
165 -cpu model
167 Select CPU model ("-cpu help" for list and additional feature
168 selection)
169 -accel name[,prop=value[,...]]
171 This is used to enable an accelerator. Depending on the target
172 architecture, kvm, xen, hax, hvf, whpx or tcg can be available. By
173 default, tcg is used. If there is more than one accelerator
174 specified, the next one is used if the previous one fails to
175 initialize.
176 thread=single|multi
178 Controls number of TCG threads. When the TCG is multi-threaded
179 there will be one thread per vCPU therefor taking advantage of
180 additional host cores. The default is to enable multi-threading
181 where both the back-end and front-ends support it and no
182 incompatible TCG features have been enabled (e.g.
183 icount/replay).
184 -smp
186 [cpus=]n[,cores=cores][,threads=threads][,sockets=sockets][,maxcpus=maxcpus]
187 Simulate an SMP system with n CPUs. On the PC target, up to 255
188 CPUs are supported. On Sparc32 target, Linux limits the number of
189 usable CPUs to 4. For the PC target, the number of cores per
190 socket, the number of threads per cores and the total number of
191 sockets can be specified. Missing values will be computed. If any
192 on the three values is given, the total number of CPUs n can be
193 omitted. maxcpus specifies the maximum number of hotpluggable CPUs.
194 -numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node]
196 -numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node]
197 -numa dist,src=source,dst=destination,val=distance
198 -numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]
199 Define a NUMA node and assign RAM and VCPUs to it. Set the NUMA
200 distance from a source node to a destination node.
201 Legacy VCPU assignment uses cpus option where firstcpu and lastcpu
203 are CPU indexes. Each cpus option represent a contiguous range of
204 CPU indexes (or a single VCPU if lastcpu is omitted). A non-
205 contiguous set of VCPUs can be represented by providing multiple
206 cpus options. If cpus is omitted on all nodes, VCPUs are
207 automatically split between them.
208 For example, the following option assigns VCPUs 0, 1, 2 and 5 to a
210 NUMA node:
211 -numa node,cpus=0-2,cpus=5
213 cpu option is a new alternative to cpus option which uses
215 socket-id|core-id|thread-id properties to assign CPU objects to a
216 node using topology layout properties of CPU. The set of
217 properties is machine specific, and depends on used machine
218 type/smp options. It could be queried with hotpluggable-cpus
219 monitor command. node-id property specifies node to which CPU
220 object will be assigned, it's required for node to be declared with
221 node option before it's used with cpu option.
222 For example:
224 -M pc \
226 -smp 1,sockets=2,maxcpus=2 \
227 -numa node,nodeid=0 -numa node,nodeid=1 \
228 -numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1
229 mem assigns a given RAM amount to a node. memdev assigns RAM from a
231 given memory backend device to a node. If mem and memdev are
232 omitted in all nodes, RAM is split equally between them.
233 mem and memdev are mutually exclusive. Furthermore, if one node
235 uses memdev, all of them have to use it.
236 source and destination are NUMA node IDs. distance is the NUMA
238 distance from source to destination. The distance from a node to
239 itself is always 10. If any pair of nodes is given a distance, then
240 all pairs must be given distances. Although, when distances are
241 only given in one direction for each pair of nodes, then the
242 distances in the opposite directions are assumed to be the same.
243 If, however, an asymmetrical pair of distances is given for even
244 one node pair, then all node pairs must be provided distance values
245 for both directions, even when they are symmetrical. When a node is
246 unreachable from another node, set the pair's distance to 255.
247 Note that the -numa option doesn't allocate any of the specified
249 resources, it just assigns existing resources to NUMA nodes. This
250 means that one still has to use the -m, -smp options to allocate
251 RAM and VCPUs respectively.
252 -add-fd fd=fd,set=set[,opaque=opaque]
254 Add a file descriptor to an fd set. Valid options are:
255 fd=fd
257 This option defines the file descriptor of which a duplicate is
258 added to fd set. The file descriptor cannot be stdin, stdout,
259 or stderr.
260 set=set
262 This option defines the ID of the fd set to add the file
263 descriptor to.
264 opaque=opaque
266 This option defines a free-form string that can be used to
267 describe fd.
268 You can open an image using pre-opened file descriptors from an fd
270 set:
271 qemu-system-i386
273 -add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
274 -add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
275 -drive file=/dev/fdset/2,index=0,media=disk
276 -set group.id.arg=value
278 Set parameter arg for item id of type group
279 -global driver.prop=value
281 -global driver=driver,property=property,value=value
282 Set default value of driver's property prop to value, e.g.:
283 qemu-system-i386 -global ide-hd.physical_block_size=4096 disk-image.img
285 In particular, you can use this to set driver properties for
287 devices which are created automatically by the machine model. To
288 create a device which is not created automatically and set
289 properties on it, use -device.
290 -global driver.prop=value is shorthand for -global
292 driver=driver,property=prop,value=value. The longhand syntax works
293 even when driver contains a dot.
294 -boot
296 [order=drives][,once=drives][,menu=on|off][,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_timeout][,strict=on|off]
297 Specify boot order drives as a string of drive letters. Valid drive
298 letters depend on the target architecture. The x86 PC uses: a, b
299 (floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p
300 (Etherboot from network adapter 1-4), hard disk boot is the
301 default. To apply a particular boot order only on the first
302 startup, specify it via once. Note that the order or once parameter
303 should not be used together with the bootindex property of devices,
304 since the firmware implementations normally do not support both at
305 the same time.
306 Interactive boot menus/prompts can be enabled via menu=on as far as
308 firmware/BIOS supports them. The default is non-interactive boot.
309 A splash picture could be passed to bios, enabling user to show it
311 as logo, when option splash=sp_name is given and menu=on, If
312 firmware/BIOS supports them. Currently Seabios for X86 system
313 support it. limitation: The splash file could be a jpeg file or a
314 BMP file in 24 BPP format(true color). The resolution should be
315 supported by the SVGA mode, so the recommended is 320x240, 640x480,
316 800x640.
317 A timeout could be passed to bios, guest will pause for rb_timeout
319 ms when boot failed, then reboot. If rb_timeout is '-1', guest will
320 not reboot, qemu passes '-1' to bios by default. Currently Seabios
321 for X86 system support it.
322 Do strict boot via strict=on as far as firmware/BIOS supports it.
324 This only effects when boot priority is changed by bootindex
325 options. The default is non-strict boot.
326 # try to boot from network first, then from hard disk
328 qemu-system-i386 -boot order=nc
329 # boot from CD-ROM first, switch back to default order after reboot
330 qemu-system-i386 -boot once=d
331 # boot with a splash picture for 5 seconds.
332 qemu-system-i386 -boot menu=on,splash=/root/boot.bmp,splash-time=5000
333 Note: The legacy format '-boot drives' is still supported but its
335 use is discouraged as it may be removed from future versions.
336 -m [size=]megs[,slots=n,maxmem=size]
338 Sets guest startup RAM size to megs megabytes. Default is 128 MiB.
339 Optionally, a suffix of "M" or "G" can be used to signify a value
340 in megabytes or gigabytes respectively. Optional pair slots, maxmem
341 could be used to set amount of hotpluggable memory slots and
342 maximum amount of memory. Note that maxmem must be aligned to the
343 page size.
344 For example, the following command-line sets the guest startup RAM
346 size to 1GB, creates 3 slots to hotplug additional memory and sets
347 the maximum memory the guest can reach to 4GB:
348 qemu-system-x86_64 -m 1G,slots=3,maxmem=4G
350 If slots and maxmem are not specified, memory hotplug won't be
352 enabled and the guest startup RAM will never increase.
353 -mem-path path
355 Allocate guest RAM from a temporarily created file in path.
356 -mem-prealloc
358 Preallocate memory when using -mem-path.
359 -k language
361 Use keyboard layout language (for example "fr" for French). This
362 option is only needed where it is not easy to get raw PC keycodes
363 (e.g. on Macs, with some X11 servers or with a VNC or curses
364 display). You don't normally need to use it on PC/Linux or
365 PC/Windows hosts.
366 The available layouts are:
368 ar de-ch es fo fr-ca hu ja mk no pt-br sv
370 da en-gb et fr fr-ch is lt nl pl ru th
371 de en-us fi fr-be hr it lv nl-be pt sl tr
372 The default is "en-us".
374 -audio-help
376 Will show the audio subsystem help: list of drivers, tunable
377 parameters.
378 -soundhw card1[,card2,...] or -soundhw all
380 Enable audio and selected sound hardware. Use 'help' to print all
381 available sound hardware.
382 qemu-system-i386 -soundhw sb16,adlib disk.img
384 qemu-system-i386 -soundhw es1370 disk.img
385 qemu-system-i386 -soundhw ac97 disk.img
386 qemu-system-i386 -soundhw hda disk.img
387 qemu-system-i386 -soundhw all disk.img
388 qemu-system-i386 -soundhw help
389 Note that Linux's i810_audio OSS kernel (for AC97) module might
391 require manually specifying clocking.
392 modprobe i810_audio clocking=48000
394 -balloon virtio[,addr=addr]
396 Enable virtio balloon device, optionally with PCI address addr.
397 This option is deprecated, use -device virtio-balloon instead.
398 -device driver[,prop[=value][,...]]
400 Add device driver. prop=value sets driver properties. Valid
401 properties depend on the driver. To get help on possible drivers
402 and properties, use "-device help" and "-device driver,help".
403 Some drivers are:
405 -device
407 ipmi-bmc-sim,id=id[,slave_addr=val][,sdrfile=file][,furareasize=val][,furdatafile=file]
408 Add an IPMI BMC. This is a simulation of a hardware management
409 interface processor that normally sits on a system. It provides a
410 watchdog and the ability to reset and power control the system.
411 You need to connect this to an IPMI interface to make it useful
412 The IPMI slave address to use for the BMC. The default is 0x20.
414 This address is the BMC's address on the I2C network of management
415 controllers. If you don't know what this means, it is safe to
416 ignore it.
417 bmc=id
419 The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern
420 above.
421 slave_addr=val
423 Define slave address to use for the BMC. The default is 0x20.
424 sdrfile=file
426 file containing raw Sensor Data Records (SDR) data. The default
427 is none.
428 fruareasize=val
430 size of a Field Replaceable Unit (FRU) area. The default is
431 1024.
432 frudatafile=file
434 file containing raw Field Replaceable Unit (FRU) inventory
435 data. The default is none.
436 -device ipmi-bmc-extern,id=id,chardev=id[,slave_addr=val]
438 Add a connection to an external IPMI BMC simulator. Instead of
439 locally emulating the BMC like the above item, instead connect to
440 an external entity that provides the IPMI services.
441 A connection is made to an external BMC simulator. If you do this,
443 it is strongly recommended that you use the "reconnect=" chardev
444 option to reconnect to the simulator if the connection is lost.
445 Note that if this is not used carefully, it can be a security
446 issue, as the interface has the ability to send resets, NMIs, and
447 power off the VM. It's best if QEMU makes a connection to an
448 external simulator running on a secure port on localhost, so
449 neither the simulator nor QEMU is exposed to any outside network.
450 See the "lanserv/README.vm" file in the OpenIPMI library for more
452 details on the external interface.
453 -device isa-ipmi-kcs,bmc=id[,ioport=val][,irq=val]
455 Add a KCS IPMI interafce on the ISA bus. This also adds a
456 corresponding ACPI and SMBIOS entries, if appropriate.
457 bmc=id
459 The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern
460 above.
461 ioport=val
463 Define the I/O address of the interface. The default is 0xca0
464 for KCS.
465 irq=val
467 Define the interrupt to use. The default is 5. To disable
468 interrupts, set this to 0.
469 -device isa-ipmi-bt,bmc=id[,ioport=val][,irq=val]
471 Like the KCS interface, but defines a BT interface. The default
472 port is 0xe4 and the default interrupt is 5.
473 -name name
475 Sets the name of the guest. This name will be displayed in the SDL
476 window caption. The name will also be used for the VNC server.
477 Also optionally set the top visible process name in Linux. Naming
478 of individual threads can also be enabled on Linux to aid
479 debugging.
480 -uuid uuid
482 Set system UUID.
483 Block device options
485 -fda file
487 -fdb file
488 Use file as floppy disk 0/1 image.
489 -hda file
491 -hdb file
492 -hdc file
493 -hdd file
494 Use file as hard disk 0, 1, 2 or 3 image.
495 -cdrom file
497 Use file as CD-ROM image (you cannot use -hdc and -cdrom at the
498 same time). You can use the host CD-ROM by using /dev/cdrom as
499 filename.
500 -blockdev option[,option[,option[,...]]]
502 Define a new block driver node. Some of the options apply to all
503 block drivers, other options are only accepted for a specific block
504 driver. See below for a list of generic options and options for the
505 most common block drivers.
506 Options that expect a reference to another node (e.g. "file") can
508 be given in two ways. Either you specify the node name of an
509 already existing node (file=node-name), or you define a new node
510 inline, adding options for the referenced node after a dot
511 (file.filename=path,file.aio=native).
512 A block driver node created with -blockdev can be used for a guest
514 device by specifying its node name for the "drive" property in a
515 -device argument that defines a block device.
516 Valid options for any block driver node:
518 "driver"
519 Specifies the block driver to use for the given node.
520 "node-name"
522 This defines the name of the block driver node by which it
523 will be referenced later. The name must be unique, i.e. it
524 must not match the name of a different block driver node,
525 or (if you use -drive as well) the ID of a drive.
526 If no node name is specified, it is automatically
528 generated. The generated node name is not intended to be
529 predictable and changes between QEMU invocations. For the
530 top level, an explicit node name must be specified.
531 "read-only"
533 Open the node read-only. Guest write attempts will fail.
534 "cache.direct"
536 The host page cache can be avoided with cache.direct=on.
537 This will attempt to do disk IO directly to the guest's
538 memory. QEMU may still perform an internal copy of the
539 data.
540 "cache.no-flush"
542 In case you don't care about data integrity over host
543 failures, you can use cache.no-flush=on. This option tells
544 QEMU that it never needs to write any data to the disk but
545 can instead keep things in cache. If anything goes wrong,
546 like your host losing power, the disk storage getting
547 disconnected accidentally, etc. your image will most
548 probably be rendered unusable.
549 "discard=discard"
551 discard is one of "ignore" (or "off") or "unmap" (or "on")
552 and controls whether "discard" (also known as "trim" or
553 "unmap") requests are ignored or passed to the filesystem.
554 Some machine types may not support discard requests.
555 "detect-zeroes=detect-zeroes"
557 detect-zeroes is "off", "on" or "unmap" and enables the
558 automatic conversion of plain zero writes by the OS to
559 driver specific optimized zero write commands. You may even
560 choose "unmap" if discard is set to "unmap" to allow a zero
561 write to be converted to an "unmap" operation.
562 Driver-specific options for "file"
564 This is the protocol-level block driver for accessing regular
565 files.
566 "filename"
568 The path to the image file in the local filesystem
569 "aio"
571 Specifies the AIO backend (threads/native, default:
572 threads)
573 "locking"
575 Specifies whether the image file is protected with Linux
576 OFD / POSIX locks. The default is to use the Linux Open
577 File Descriptor API if available, otherwise no lock is
578 applied. (auto/on/off, default: auto)
579 Example:
581 -blockdev driver=file,node-name=disk,filename=disk.img
583 Driver-specific options for "raw"
585 This is the image format block driver for raw images. It is
586 usually stacked on top of a protocol level block driver such as
587 "file".
588 "file"
590 Reference to or definition of the data source block driver
591 node (e.g. a "file" driver node)
592 Example 1:
594 -blockdev driver=file,node-name=disk_file,filename=disk.img
596 -blockdev driver=raw,node-name=disk,file=disk_file
597 Example 2:
599 -blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img
601 Driver-specific options for "qcow2"
603 This is the image format block driver for qcow2 images. It is
604 usually stacked on top of a protocol level block driver such as
605 "file".
606 "file"
608 Reference to or definition of the data source block driver
609 node (e.g. a "file" driver node)
610 "backing"
612 Reference to or definition of the backing file block device
613 (default is taken from the image file). It is allowed to
614 pass "null" here in order to disable the default backing
615 file.
616 "lazy-refcounts"
618 Whether to enable the lazy refcounts feature (on/off;
619 default is taken from the image file)
620 "cache-size"
622 The maximum total size of the L2 table and refcount block
623 caches in bytes (default: 1048576 bytes or 8 clusters,
624 whichever is larger)
625 "l2-cache-size"
627 The maximum size of the L2 table cache in bytes (default:
628 4/5 of the total cache size)
629 "refcount-cache-size"
631 The maximum size of the refcount block cache in bytes
632 (default: 1/5 of the total cache size)
633 "cache-clean-interval"
635 Clean unused entries in the L2 and refcount caches. The
636 interval is in seconds. The default value is 0 and it
637 disables this feature.
638 "pass-discard-request"
640 Whether discard requests to the qcow2 device should be
641 forwarded to the data source (on/off; default: on if
642 discard=unmap is specified, off otherwise)
643 "pass-discard-snapshot"
645 Whether discard requests for the data source should be
646 issued when a snapshot operation (e.g. deleting a snapshot)
647 frees clusters in the qcow2 file (on/off; default: on)
648 "pass-discard-other"
650 Whether discard requests for the data source should be
651 issued on other occasions where a cluster gets freed
652 (on/off; default: off)
653 "overlap-check"
655 Which overlap checks to perform for writes to the image
656 (none/constant/cached/all; default: cached). For details or
657 finer granularity control refer to the QAPI documentation
658 of "blockdev-add".
659 Example 1:
661 -blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2
663 -blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216
664 Example 2:
666 -blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2
668 Driver-specific options for other drivers
670 Please refer to the QAPI documentation of the "blockdev-add"
671 QMP command.
672 -drive option[,option[,option[,...]]]
674 Define a new drive. This includes creating a block driver node (the
675 backend) as well as a guest device, and is mostly a shortcut for
676 defining the corresponding -blockdev and -device options.
677 -drive accepts all options that are accepted by -blockdev. In
679 addition, it knows the following options:
680 file=file
682 This option defines which disk image to use with this drive. If
683 the filename contains comma, you must double it (for instance,
684 "file=my,,file" to use file "my,file").
685 Special files such as iSCSI devices can be specified using
687 protocol specific URLs. See the section for "Device URL Syntax"
688 for more information.
689 if=interface
691 This option defines on which type on interface the drive is
692 connected. Available types are: ide, scsi, sd, mtd, floppy,
693 pflash, virtio, none.
694 bus=bus,unit=unit
696 These options define where is connected the drive by defining
697 the bus number and the unit id.
698 index=index
700 This option defines where is connected the drive by using an
701 index in the list of available connectors of a given interface
702 type.
703 media=media
705 This option defines the type of the media: disk or cdrom.
706 cyls=c,heads=h,secs=s[,trans=t]
708 Force disk physical geometry and the optional BIOS translation
709 (trans=none or lba). These parameters are deprecated, use the
710 corresponding parameters of "-device" instead.
711 snapshot=snapshot
713 snapshot is "on" or "off" and controls snapshot mode for the
714 given drive (see -snapshot).
715 cache=cache
717 cache is "none", "writeback", "unsafe", "directsync" or
718 "writethrough" and controls how the host cache is used to
719 access block data. This is a shortcut that sets the
720 cache.direct and cache.no-flush options (as in -blockdev), and
721 additionally cache.writeback, which provides a default for the
722 write-cache option of block guest devices (as in -device). The
723 modes correspond to the following settings:
724 │ cache.writeback cache.direct cache.no-flush
726 ─────────────┼─────────────────────────────────────────────────
727 writeback │ on off off
728 none │ on on off
729 writethrough │ off off off
730 directsync │ off on off
731 unsafe │ on off on
732 The default mode is cache=writeback.
734 aio=aio
736 aio is "threads", or "native" and selects between pthread based
737 disk I/O and native Linux AIO.
738 format=format
740 Specify which disk format will be used rather than detecting
741 the format. Can be used to specify format=raw to avoid
742 interpreting an untrusted format header.
743 serial=serial
745 This option specifies the serial number to assign to the
746 device. This parameter is deprecated, use the corresponding
747 parameter of "-device" instead.
748 addr=addr
750 Specify the controller's PCI address (if=virtio only). This
751 parameter is deprecated, use the corresponding parameter of
752 "-device" instead.
753 werror=action,rerror=action
755 Specify which action to take on write and read errors. Valid
756 actions are: "ignore" (ignore the error and try to continue),
757 "stop" (pause QEMU), "report" (report the error to the guest),
758 "enospc" (pause QEMU only if the host disk is full; report the
759 error to the guest otherwise). The default setting is
760 werror=enospc and rerror=report.
761 copy-on-read=copy-on-read
763 copy-on-read is "on" or "off" and enables whether to copy read
764 backing file sectors into the image file.
765 bps=b,bps_rd=r,bps_wr=w
767 Specify bandwidth throttling limits in bytes per second, either
768 for all request types or for reads or writes only. Small
769 values can lead to timeouts or hangs inside the guest. A safe
770 minimum for disks is 2 MB/s.
771 bps_max=bm,bps_rd_max=rm,bps_wr_max=wm
773 Specify bursts in bytes per second, either for all request
774 types or for reads or writes only. Bursts allow the guest I/O
775 to spike above the limit temporarily.
776 iops=i,iops_rd=r,iops_wr=w
778 Specify request rate limits in requests per second, either for
779 all request types or for reads or writes only.
780 iops_max=bm,iops_rd_max=rm,iops_wr_max=wm
782 Specify bursts in requests per second, either for all request
783 types or for reads or writes only. Bursts allow the guest I/O
784 to spike above the limit temporarily.
785 iops_size=is
787 Let every is bytes of a request count as a new request for iops
788 throttling purposes. Use this option to prevent guests from
789 circumventing iops limits by sending fewer but larger requests.
790 group=g
792 Join a throttling quota group with given name g. All drives
793 that are members of the same group are accounted for together.
794 Use this option to prevent guests from circumventing throttling
795 limits by using many small disks instead of a single larger
796 disk.
797 By default, the cache.writeback=on mode is used. It will report
799 data writes as completed as soon as the data is present in the host
800 page cache. This is safe as long as your guest OS makes sure to
801 correctly flush disk caches where needed. If your guest OS does not
802 handle volatile disk write caches correctly and your host crashes
803 or loses power, then the guest may experience data corruption.
804 For such guests, you should consider using cache.writeback=off.
806 This means that the host page cache will be used to read and write
807 data, but write notification will be sent to the guest only after
808 QEMU has made sure to flush each write to the disk. Be aware that
809 this has a major impact on performance.
810 When using the -snapshot option, unsafe caching is always used.
812 Copy-on-read avoids accessing the same backing file sectors
814 repeatedly and is useful when the backing file is over a slow
815 network. By default copy-on-read is off.
816 Instead of -cdrom you can use:
818 qemu-system-i386 -drive file=file,index=2,media=cdrom
820 Instead of -hda, -hdb, -hdc, -hdd, you can use:
822 qemu-system-i386 -drive file=file,index=0,media=disk
824 qemu-system-i386 -drive file=file,index=1,media=disk
825 qemu-system-i386 -drive file=file,index=2,media=disk
826 qemu-system-i386 -drive file=file,index=3,media=disk
827 You can open an image using pre-opened file descriptors from an fd
829 set:
830 qemu-system-i386
832 -add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
833 -add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
834 -drive file=/dev/fdset/2,index=0,media=disk
835 You can connect a CDROM to the slave of ide0:
837 qemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom
839 If you don't specify the "file=" argument, you define an empty
841 drive:
842 qemu-system-i386 -drive if=ide,index=1,media=cdrom
844 Instead of -fda, -fdb, you can use:
846 qemu-system-i386 -drive file=file,index=0,if=floppy
848 qemu-system-i386 -drive file=file,index=1,if=floppy
849 By default, interface is "ide" and index is automatically
851 incremented:
852 qemu-system-i386 -drive file=a -drive file=b"
854 is interpreted like:
856 qemu-system-i386 -hda a -hdb b
858 -mtdblock file
860 Use file as on-board Flash memory image.
861 -sd file
863 Use file as SecureDigital card image.
864 -pflash file
866 Use file as a parallel flash image.
867 -snapshot
869 Write to temporary files instead of disk image files. In this case,
870 the raw disk image you use is not written back. You can however
871 force the write back by pressing C-a s.
872 -fsdev
874 fsdriver,id=id,path=path,[security_model=security_model][,writeout=writeout][,readonly][,socket=socket|sock_fd=sock_fd][,fmode=fmode][,dmode=dmode]
875 Define a new file system device. Valid options are:
876 fsdriver
878 This option specifies the fs driver backend to use. Currently
879 "local", "handle" and "proxy" file system drivers are
880 supported.
881 id=id
883 Specifies identifier for this device
884 path=path
886 Specifies the export path for the file system device. Files
887 under this path will be available to the 9p client on the
888 guest.
889 security_model=security_model
891 Specifies the security model to be used for this export path.
892 Supported security models are "passthrough", "mapped-xattr",
893 "mapped-file" and "none". In "passthrough" security model,
894 files are stored using the same credentials as they are created
895 on the guest. This requires QEMU to run as root. In "mapped-
896 xattr" security model, some of the file attributes like uid,
897 gid, mode bits and link target are stored as file attributes.
898 For "mapped-file" these attributes are stored in the hidden
899 .virtfs_metadata directory. Directories exported by this
900 security model cannot interact with other unix tools. "none"
901 security model is same as passthrough except the sever won't
902 report failures if it fails to set file attributes like
903 ownership. Security model is mandatory only for local fsdriver.
904 Other fsdrivers (like handle, proxy) don't take security model
905 as a parameter.
906 writeout=writeout
908 This is an optional argument. The only supported value is
909 "immediate". This means that host page cache will be used to
910 read and write data but write notification will be sent to the
911 guest only when the data has been reported as written by the
912 storage subsystem.
913 readonly
915 Enables exporting 9p share as a readonly mount for guests. By
916 default read-write access is given.
917 socket=socket
919 Enables proxy filesystem driver to use passed socket file for
920 communicating with virtfs-proxy-helper
921 sock_fd=sock_fd
923 Enables proxy filesystem driver to use passed socket descriptor
924 for communicating with virtfs-proxy-helper. Usually a helper
925 like libvirt will create socketpair and pass one of the fds as
926 sock_fd
927 fmode=fmode
929 Specifies the default mode for newly created files on the host.
930 Works only with security models "mapped-xattr" and "mapped-
931 file".
932 dmode=dmode
934 Specifies the default mode for newly created directories on the
935 host. Works only with security models "mapped-xattr" and
936 "mapped-file".
937 -fsdev option is used along with -device driver "virtio-9p-pci".
939 -device virtio-9p-pci,fsdev=id,mount_tag=mount_tag
941 Options for virtio-9p-pci driver are:
942 fsdev=id
944 Specifies the id value specified along with -fsdev option
945 mount_tag=mount_tag
947 Specifies the tag name to be used by the guest to mount this
948 export point
949 -virtfs
951 fsdriver[,path=path],mount_tag=mount_tag[,security_model=security_model][,writeout=writeout][,readonly][,socket=socket|sock_fd=sock_fd][,fmode=fmode][,dmode=dmode]
952 The general form of a Virtual File system pass-through options are:
953 fsdriver
955 This option specifies the fs driver backend to use. Currently
956 "local", "handle" and "proxy" file system drivers are
957 supported.
958 id=id
960 Specifies identifier for this device
961 path=path
963 Specifies the export path for the file system device. Files
964 under this path will be available to the 9p client on the
965 guest.
966 security_model=security_model
968 Specifies the security model to be used for this export path.
969 Supported security models are "passthrough", "mapped-xattr",
970 "mapped-file" and "none". In "passthrough" security model,
971 files are stored using the same credentials as they are created
972 on the guest. This requires QEMU to run as root. In "mapped-
973 xattr" security model, some of the file attributes like uid,
974 gid, mode bits and link target are stored as file attributes.
975 For "mapped-file" these attributes are stored in the hidden
976 .virtfs_metadata directory. Directories exported by this
977 security model cannot interact with other unix tools. "none"
978 security model is same as passthrough except the sever won't
979 report failures if it fails to set file attributes like
980 ownership. Security model is mandatory only for local fsdriver.
981 Other fsdrivers (like handle, proxy) don't take security model
982 as a parameter.
983 writeout=writeout
985 This is an optional argument. The only supported value is
986 "immediate". This means that host page cache will be used to
987 read and write data but write notification will be sent to the
988 guest only when the data has been reported as written by the
989 storage subsystem.
990 readonly
992 Enables exporting 9p share as a readonly mount for guests. By
993 default read-write access is given.
994 socket=socket
996 Enables proxy filesystem driver to use passed socket file for
997 communicating with virtfs-proxy-helper. Usually a helper like
998 libvirt will create socketpair and pass one of the fds as
999 sock_fd
1000 sock_fd
1002 Enables proxy filesystem driver to use passed 'sock_fd' as the
1003 socket descriptor for interfacing with virtfs-proxy-helper
1004 fmode=fmode
1006 Specifies the default mode for newly created files on the host.
1007 Works only with security models "mapped-xattr" and "mapped-
1008 file".
1009 dmode=dmode
1011 Specifies the default mode for newly created directories on the
1012 host. Works only with security models "mapped-xattr" and
1013 "mapped-file".
1014 -virtfs_synth
1016 Create synthetic file system image
1017 -iscsi
1019 Configure iSCSI session parameters.
1020 USB options
1022 -usb
1024 Enable the USB driver (if it is not used by default yet).
1025 -usbdevice devname
1027 Add the USB device devname. Note that this option is deprecated,
1028 please use "-device usb-..." instead.
1029 mouse
1031 Virtual Mouse. This will override the PS/2 mouse emulation when
1032 activated.
1033 tablet
1035 Pointer device that uses absolute coordinates (like a
1036 touchscreen). This means QEMU is able to report the mouse
1037 position without having to grab the mouse. Also overrides the
1038 PS/2 mouse emulation when activated.
1039 braille
1041 Braille device. This will use BrlAPI to display the braille
1042 output on a real or fake device.
1043 Display options
1045 -display type
1047 Select type of display to use. This option is a replacement for the
1048 old style -sdl/-curses/... options. Valid values for type are
1049 sdl Display video output via SDL (usually in a separate graphics
1051 window; see the SDL documentation for other possibilities).
1052 curses
1054 Display video output via curses. For graphics device models
1055 which support a text mode, QEMU can display this output using a
1056 curses/ncurses interface. Nothing is displayed when the
1057 graphics device is in graphical mode or if the graphics device
1058 does not support a text mode. Generally only the VGA device
1059 models support text mode.
1060 none
1062 Do not display video output. The guest will still see an
1063 emulated graphics card, but its output will not be displayed to
1064 the QEMU user. This option differs from the -nographic option
1065 in that it only affects what is done with video output;
1066 -nographic also changes the destination of the serial and
1067 parallel port data.
1068 gtk Display video output in a GTK window. This interface provides
1070 drop-down menus and other UI elements to configure and control
1071 the VM during runtime.
1072 vnc Start a VNC server on display <arg>
1074 -nographic
1076 Normally, if QEMU is compiled with graphical window support, it
1077 displays output such as guest graphics, guest console, and the QEMU
1078 monitor in a window. With this option, you can totally disable
1079 graphical output so that QEMU is a simple command line application.
1080 The emulated serial port is redirected on the console and muxed
1081 with the monitor (unless redirected elsewhere explicitly).
1082 Therefore, you can still use QEMU to debug a Linux kernel with a
1083 serial console. Use C-a h for help on switching between the console
1084 and monitor.
1085 -curses
1087 Normally, if QEMU is compiled with graphical window support, it
1088 displays output such as guest graphics, guest console, and the QEMU
1089 monitor in a window. With this option, QEMU can display the VGA
1090 output when in text mode using a curses/ncurses interface. Nothing
1091 is displayed in graphical mode.
1092 -no-frame
1094 Do not use decorations for SDL windows and start them using the
1095 whole available screen space. This makes the using QEMU in a
1096 dedicated desktop workspace more convenient.
1097 -alt-grab
1099 Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that
1100 this also affects the special keys (for fullscreen, monitor-mode
1101 switching, etc).
1102 -ctrl-grab
1104 Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this
1105 also affects the special keys (for fullscreen, monitor-mode
1106 switching, etc).
1107 -no-quit
1109 Disable SDL window close capability.
1110 -sdl
1112 Enable SDL.
1113 -spice option[,option[,...]]
1115 Enable the spice remote desktop protocol. Valid options are
1116 port=<nr>
1118 Set the TCP port spice is listening on for plaintext channels.
1119 addr=<addr>
1121 Set the IP address spice is listening on. Default is any
1122 address.
1123 ipv4
1125 ipv6
1126 unix
1127 Force using the specified IP version.
1128 password=<secret>
1130 Set the password you need to authenticate.
1131 sasl
1133 Require that the client use SASL to authenticate with the
1134 spice. The exact choice of authentication method used is
1135 controlled from the system / user's SASL configuration file for
1136 the 'qemu' service. This is typically found in
1137 /etc/sasl2/qemu.conf. If running QEMU as an unprivileged user,
1138 an environment variable SASL_CONF_PATH can be used to make it
1139 search alternate locations for the service config. While some
1140 SASL auth methods can also provide data encryption (eg GSSAPI),
1141 it is recommended that SASL always be combined with the 'tls'
1142 and 'x509' settings to enable use of SSL and server
1143 certificates. This ensures a data encryption preventing
1144 compromise of authentication credentials.
1145 disable-ticketing
1147 Allow client connects without authentication.
1148 disable-copy-paste
1150 Disable copy paste between the client and the guest.
1151 disable-agent-file-xfer
1153 Disable spice-vdagent based file-xfer between the client and
1154 the guest.
1155 tls-port=<nr>
1157 Set the TCP port spice is listening on for encrypted channels.
1158 x509-dir=<dir>
1160 Set the x509 file directory. Expects same filenames as -vnc
1161 $display,x509=$dir
1162 x509-key-file=<file>
1164 x509-key-password=<file>
1165 x509-cert-file=<file>
1166 x509-cacert-file=<file>
1167 x509-dh-key-file=<file>
1168 The x509 file names can also be configured individually.
1169 tls-ciphers=<list>
1171 Specify which ciphers to use.
1172 tls-channel=[main|display|cursor|inputs|record|playback]
1174 plaintext-channel=[main|display|cursor|inputs|record|playback]
1175 Force specific channel to be used with or without TLS
1176 encryption. The options can be specified multiple times to
1177 configure multiple channels. The special name "default" can be
1178 used to set the default mode. For channels which are not
1179 explicitly forced into one mode the spice client is allowed to
1180 pick tls/plaintext as he pleases.
1181 image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
1183 Configure image compression (lossless). Default is auto_glz.
1184 jpeg-wan-compression=[auto|never|always]
1186 zlib-glz-wan-compression=[auto|never|always]
1187 Configure wan image compression (lossy for slow links).
1188 Default is auto.
1189 streaming-video=[off|all|filter]
1191 Configure video stream detection. Default is off.
1192 agent-mouse=[on|off]
1194 Enable/disable passing mouse events via vdagent. Default is
1195 on.
1196 playback-compression=[on|off]
1198 Enable/disable audio stream compression (using celt 0.5.1).
1199 Default is on.
1200 seamless-migration=[on|off]
1202 Enable/disable spice seamless migration. Default is off.
1203 gl=[on|off]
1205 Enable/disable OpenGL context. Default is off.
1206 rendernode=<file>
1208 DRM render node for OpenGL rendering. If not specified, it will
1209 pick the first available. (Since 2.9)
1210 -portrait
1212 Rotate graphical output 90 deg left (only PXA LCD).
1213 -rotate deg
1215 Rotate graphical output some deg left (only PXA LCD).
1216 -vga type
1218 Select type of VGA card to emulate. Valid values for type are
1219 cirrus
1221 Cirrus Logic GD5446 Video card. All Windows versions starting
1222 from Windows 95 should recognize and use this graphic card. For
1223 optimal performances, use 16 bit color depth in the guest and
1224 the host OS. (This card was the default before QEMU 2.2)
1225 std Standard VGA card with Bochs VBE extensions. If your guest OS
1227 supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if
1228 you want to use high resolution modes (>= 1280x1024x16) then
1229 you should use this option. (This card is the default since
1230 QEMU 2.2)
1231 vmware
1233 VMWare SVGA-II compatible adapter. Use it if you have
1234 sufficiently recent XFree86/XOrg server or Windows guest with a
1235 driver for this card.
1236 qxl QXL paravirtual graphic card. It is VGA compatible (including
1238 VESA 2.0 VBE support). Works best with qxl guest drivers
1239 installed though. Recommended choice when using the spice
1240 protocol.
1241 tcx (sun4m only) Sun TCX framebuffer. This is the default
1243 framebuffer for sun4m machines and offers both 8-bit and 24-bit
1244 colour depths at a fixed resolution of 1024x768.
1245 cg3 (sun4m only) Sun cgthree framebuffer. This is a simple 8-bit
1247 framebuffer for sun4m machines available in both 1024x768
1248 (OpenBIOS) and 1152x900 (OBP) resolutions aimed at people
1249 wishing to run older Solaris versions.
1250 virtio
1252 Virtio VGA card.
1253 none
1255 Disable VGA card.
1256 -full-screen
1258 Start in full screen.
1259 -g widthxheight[xdepth]
1261 Set the initial graphical resolution and depth (PPC, SPARC only).
1262 -vnc display[,option[,option[,...]]]
1264 Normally, if QEMU is compiled with graphical window support, it
1265 displays output such as guest graphics, guest console, and the QEMU
1266 monitor in a window. With this option, you can have QEMU listen on
1267 VNC display display and redirect the VGA display over the VNC
1268 session. It is very useful to enable the usb tablet device when
1269 using this option (option -device usb-tablet). When using the VNC
1270 display, you must use the -k parameter to set the keyboard layout
1271 if you are not using en-us. Valid syntax for the display is
1272 to=L
1274 With this option, QEMU will try next available VNC displays,
1275 until the number L, if the origianlly defined "-vnc display" is
1276 not available, e.g. port 5900+display is already used by
1277 another application. By default, to=0.
1278 host:d
1280 TCP connections will only be allowed from host on display d.
1281 By convention the TCP port is 5900+d. Optionally, host can be
1282 omitted in which case the server will accept connections from
1283 any host.
1284 unix:path
1286 Connections will be allowed over UNIX domain sockets where path
1287 is the location of a unix socket to listen for connections on.
1288 none
1290 VNC is initialized but not started. The monitor "change"
1291 command can be used to later start the VNC server.
1292 Following the display value there may be one or more option flags
1294 separated by commas. Valid options are
1295 reverse
1297 Connect to a listening VNC client via a "reverse" connection.
1298 The client is specified by the display. For reverse network
1299 connections (host:d,"reverse"), the d argument is a TCP port
1300 number, not a display number.
1301 websocket
1303 Opens an additional TCP listening port dedicated to VNC
1304 Websocket connections. If a bare websocket option is given,
1305 the Websocket port is 5700+display. An alternative port can be
1306 specified with the syntax "websocket"=port.
1307 If host is specified connections will only be allowed from this
1309 host. It is possible to control the websocket listen address
1310 independently, using the syntax "websocket"=host:port.
1311 If no TLS credentials are provided, the websocket connection
1313 runs in unencrypted mode. If TLS credentials are provided, the
1314 websocket connection requires encrypted client connections.
1315 password
1317 Require that password based authentication is used for client
1318 connections.
1319 The password must be set separately using the "set_password"
1321 command in the pcsys_monitor. The syntax to change your
1322 password is: "set_password <protocol> <password>" where
1323 <protocol> could be either "vnc" or "spice".
1324 If you would like to change <protocol> password expiration, you
1326 should use "expire_password <protocol> <expiration-time>" where
1327 expiration time could be one of the following options: now,
1328 never, +seconds or UNIX time of expiration, e.g. +60 to make
1329 password expire in 60 seconds, or 1335196800 to make password
1330 expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this
1331 date and time).
1332 You can also use keywords "now" or "never" for the expiration
1334 time to allow <protocol> password to expire immediately or
1335 never expire.
1336 tls-creds=ID
1338 Provides the ID of a set of TLS credentials to use to secure
1339 the VNC server. They will apply to both the normal VNC server
1340 socket and the websocket socket (if enabled). Setting TLS
1341 credentials will cause the VNC server socket to enable the
1342 VeNCrypt auth mechanism. The credentials should have been
1343 previously created using the -object tls-creds argument.
1344 The tls-creds parameter obsoletes the tls, x509, and x509verify
1346 options, and as such it is not permitted to set both new and
1347 old type options at the same time.
1348 tls Require that client use TLS when communicating with the VNC
1350 server. This uses anonymous TLS credentials so is susceptible
1351 to a man-in-the-middle attack. It is recommended that this
1352 option be combined with either the x509 or x509verify options.
1353 This option is now deprecated in favor of using the tls-creds
1355 argument.
1356 x509=/path/to/certificate/dir
1358 Valid if tls is specified. Require that x509 credentials are
1359 used for negotiating the TLS session. The server will send its
1360 x509 certificate to the client. It is recommended that a
1361 password be set on the VNC server to provide authentication of
1362 the client when this is used. The path following this option
1363 specifies where the x509 certificates are to be loaded from.
1364 See the vnc_security section for details on generating
1365 certificates.
1366 This option is now deprecated in favour of using the tls-creds
1368 argument.
1369 x509verify=/path/to/certificate/dir
1371 Valid if tls is specified. Require that x509 credentials are
1372 used for negotiating the TLS session. The server will send its
1373 x509 certificate to the client, and request that the client
1374 send its own x509 certificate. The server will validate the
1375 client's certificate against the CA certificate, and reject
1376 clients when validation fails. If the certificate authority is
1377 trusted, this is a sufficient authentication mechanism. You may
1378 still wish to set a password on the VNC server as a second
1379 authentication layer. The path following this option specifies
1380 where the x509 certificates are to be loaded from. See the
1381 vnc_security section for details on generating certificates.
1382 This option is now deprecated in favour of using the tls-creds
1384 argument.
1385 sasl
1387 Require that the client use SASL to authenticate with the VNC
1388 server. The exact choice of authentication method used is
1389 controlled from the system / user's SASL configuration file for
1390 the 'qemu' service. This is typically found in
1391 /etc/sasl2/qemu.conf. If running QEMU as an unprivileged user,
1392 an environment variable SASL_CONF_PATH can be used to make it
1393 search alternate locations for the service config. While some
1394 SASL auth methods can also provide data encryption (eg GSSAPI),
1395 it is recommended that SASL always be combined with the 'tls'
1396 and 'x509' settings to enable use of SSL and server
1397 certificates. This ensures a data encryption preventing
1398 compromise of authentication credentials. See the vnc_security
1399 section for details on using SASL authentication.
1400 acl Turn on access control lists for checking of the x509 client
1402 certificate and SASL party. For x509 certs, the ACL check is
1403 made against the certificate's distinguished name. This is
1404 something that looks like "C=GB,O=ACME,L=Boston,CN=bob". For
1405 SASL party, the ACL check is made against the username, which
1406 depending on the SASL plugin, may include a realm component, eg
1407 "bob" or "bob@EXAMPLE.COM". When the acl flag is set, the
1408 initial access list will be empty, with a "deny" policy. Thus
1409 no one will be allowed to use the VNC server until the ACLs
1410 have been loaded. This can be achieved using the "acl" monitor
1411 command.
1412 lossy
1414 Enable lossy compression methods (gradient, JPEG, ...). If this
1415 option is set, VNC client may receive lossy framebuffer updates
1416 depending on its encoding settings. Enabling this option can
1417 save a lot of bandwidth at the expense of quality.
1418 non-adaptive
1420 Disable adaptive encodings. Adaptive encodings are enabled by
1421 default. An adaptive encoding will try to detect frequently
1422 updated screen regions, and send updates in these regions using
1423 a lossy encoding (like JPEG). This can be really helpful to
1424 save bandwidth when playing videos. Disabling adaptive
1425 encodings restores the original static behavior of encodings
1426 like Tight.
1427 share=[allow-exclusive|force-shared|ignore]
1429 Set display sharing policy. 'allow-exclusive' allows clients
1430 to ask for exclusive access. As suggested by the rfb spec this
1431 is implemented by dropping other connections. Connecting
1432 multiple clients in parallel requires all clients asking for a
1433 shared session (vncviewer: -shared switch). This is the
1434 default. 'force-shared' disables exclusive client access.
1435 Useful for shared desktop sessions, where you don't want
1436 someone forgetting specify -shared disconnect everybody else.
1437 'ignore' completely ignores the shared flag and allows
1438 everybody connect unconditionally. Doesn't conform to the rfb
1439 spec but is traditional QEMU behavior.
1440 key-delay-ms
1442 Set keyboard delay, for key down and key up events, in
1443 milliseconds. Default is 10. Keyboards are low-bandwidth
1444 devices, so this slowdown can help the device and guest to keep
1445 up and not lose events in case events are arriving in bulk.
1446 Possible causes for the latter are flaky network connections,
1447 or scripts for automated testing.
1448 i386 target only
1450 -win2k-hack
1452 Use it when installing Windows 2000 to avoid a disk full bug. After
1453 Windows 2000 is installed, you no longer need this option (this
1454 option slows down the IDE transfers).
1455 -no-fd-bootchk
1457 Disable boot signature checking for floppy disks in BIOS. May be
1458 needed to boot from old floppy disks.
1459 -no-acpi
1461 Disable ACPI (Advanced Configuration and Power Interface) support.
1462 Use it if your guest OS complains about ACPI problems (PC target
1463 machine only).
1464 -no-hpet
1466 Disable HPET support.
1467 -acpitable
1469 [sig=str][,rev=n][,oem_id=str][,oem_table_id=str][,oem_rev=n]
1470 [,asl_compiler_id=str][,asl_compiler_rev=n][,data=file1[:file2]...]
1471 Add ACPI table with specified header fields and context from
1472 specified files. For file=, take whole ACPI table from the
1473 specified files, including all ACPI headers (possible overridden by
1474 other options). For data=, only data portion of the table is used,
1475 all header information is specified in the command line. If a SLIC
1476 table is supplied to QEMU, then the SLIC's oem_id and oem_table_id
1477 fields will override the same in the RSDT and the FADT (a.k.a.
1478 FACP), in order to ensure the field matches required by the
1479 Microsoft SLIC spec and the ACPI spec.
1480 -smbios file=binary
1482 Load SMBIOS entry from binary file.
1483 -smbios
1485 type=0[,vendor=str][,version=str][,date=str][,release=%d.%d][,uefi=on|off]
1486 Specify SMBIOS type 0 fields
1487 -smbios
1489 type=1[,manufacturer=str][,product=str][,version=str][,serial=str][,uuid=uuid][,sku=str][,family=str]
1490 Specify SMBIOS type 1 fields
1491 -smbios
1493 type=2[,manufacturer=str][,product=str][,version=str][,serial=str][,asset=str][,location=str][,family=str]
1494 Specify SMBIOS type 2 fields
1495 -smbios
1497 type=3[,manufacturer=str][,version=str][,serial=str][,asset=str][,sku=str]
1498 Specify SMBIOS type 3 fields
1499 -smbios
1501 type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str][,asset=str][,part=str]
1502 Specify SMBIOS type 4 fields
1503 -smbios
1505 type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str][,asset=str][,part=str][,speed=%d]
1506 Specify SMBIOS type 17 fields
1507 Network options
1509 -nic
1511 [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn]
1512 This option is a shortcut for configuring both the on-board
1513 (default) guest NIC hardware and the host network backend in one
1514 go. The host backend options are the same as with the corresponding
1515 -netdev options below. The guest NIC model can be set with
1516 model=modelname. Use model=help to list the available device
1517 types. The hardware MAC address can be set with mac=macaddr.
1518 The following two example do exactly the same, to show how -nic can
1520 be used to shorten the command line length (note that the e1000 is
1521 the default on i386, so the model=e1000 parameter could even be
1522 omitted here, too):
1523 qemu-system-i386 -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32
1525 qemu-system-i386 -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32
1526 -nic none
1528 Indicate that no network devices should be configured. It is used
1529 to override the default configuration (default NIC with "user" host
1530 network backend) which is activated if no other networking options
1531 are provided.
1532 -netdev user,id=id[,option][,option][,...]
1534 Configure user mode host network backend which requires no
1535 administrator privilege to run. Valid options are:
1536 id=id
1538 Assign symbolic name for use in monitor commands.
1539 ipv4=on|off and ipv6=on|off
1541 Specify that either IPv4 or IPv6 must be enabled. If neither is
1542 specified both protocols are enabled.
1543 net=addr[/mask]
1545 Set IP network address the guest will see. Optionally specify
1546 the netmask, either in the form a.b.c.d or as number of valid
1547 top-most bits. Default is 10.0.2.0/24.
1548 host=addr
1550 Specify the guest-visible address of the host. Default is the
1551 2nd IP in the guest network, i.e. x.x.x.2.
1552 ipv6-net=addr[/int]
1554 Set IPv6 network address the guest will see (default is
1555 fec0::/64). The network prefix is given in the usual
1556 hexadecimal IPv6 address notation. The prefix size is optional,
1557 and is given as the number of valid top-most bits (default is
1558 64).
1559 ipv6-host=addr
1561 Specify the guest-visible IPv6 address of the host. Default is
1562 the 2nd IPv6 in the guest network, i.e. xxxx::2.
1563 restrict=on|off
1565 If this option is enabled, the guest will be isolated, i.e. it
1566 will not be able to contact the host and no guest IP packets
1567 will be routed over the host to the outside. This option does
1568 not affect any explicitly set forwarding rules.
1569 hostname=name
1571 Specifies the client hostname reported by the built-in DHCP
1572 server.
1573 dhcpstart=addr
1575 Specify the first of the 16 IPs the built-in DHCP server can
1576 assign. Default is the 15th to 31st IP in the guest network,
1577 i.e. x.x.x.15 to x.x.x.31.
1578 dns=addr
1580 Specify the guest-visible address of the virtual nameserver.
1581 The address must be different from the host address. Default is
1582 the 3rd IP in the guest network, i.e. x.x.x.3.
1583 ipv6-dns=addr
1585 Specify the guest-visible address of the IPv6 virtual
1586 nameserver. The address must be different from the host
1587 address. Default is the 3rd IP in the guest network, i.e.
1588 xxxx::3.
1589 dnssearch=domain
1591 Provides an entry for the domain-search list sent by the built-
1592 in DHCP server. More than one domain suffix can be transmitted
1593 by specifying this option multiple times. If supported, this
1594 will cause the guest to automatically try to append the given
1595 domain suffix(es) in case a domain name can not be resolved.
1596 Example:
1598 qemu-system-i386 -nic user,dnssearch=mgmt.example.org,dnssearch=example.org
1600 domainname=domain
1602 Specifies the client domain name reported by the built-in DHCP
1603 server.
1604 tftp=dir
1606 When using the user mode network stack, activate a built-in
1607 TFTP server. The files in dir will be exposed as the root of a
1608 TFTP server. The TFTP client on the guest must be configured
1609 in binary mode (use the command "bin" of the Unix TFTP client).
1610 bootfile=file
1612 When using the user mode network stack, broadcast file as the
1613 BOOTP filename. In conjunction with tftp, this can be used to
1614 network boot a guest from a local directory.
1615 Example (using pxelinux):
1617 qemu-system-i386 -hda linux.img -boot n -device e1000,netdev=n1 \
1619 -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
1620 smb=dir[,smbserver=addr]
1622 When using the user mode network stack, activate a built-in SMB
1623 server so that Windows OSes can access to the host files in dir
1624 transparently. The IP address of the SMB server can be set to
1625 addr. By default the 4th IP in the guest network is used, i.e.
1626 x.x.x.4.
1627 In the guest Windows OS, the line:
1629 10.0.2.4 smbserver
1631 must be added in the file C:\WINDOWS\LMHOSTS (for windows
1633 9x/Me) or C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS (Windows
1634 NT/2000).
1635 Then dir can be accessed in \\smbserver\qemu.
1637 Note that a SAMBA server must be installed on the host OS.
1639 hostfwd=[tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport
1641 Redirect incoming TCP or UDP connections to the host port
1642 hostport to the guest IP address guestaddr on guest port
1643 guestport. If guestaddr is not specified, its value is x.x.x.15
1644 (default first address given by the built-in DHCP server). By
1645 specifying hostaddr, the rule can be bound to a specific host
1646 interface. If no connection type is set, TCP is used. This
1647 option can be given multiple times.
1648 For example, to redirect host X11 connection from screen 1 to
1650 guest screen 0, use the following:
1651 # on the host
1653 qemu-system-i386 -nic user,hostfwd=tcp:127.0.0.1:6001-:6000
1654 # this host xterm should open in the guest X11 server
1655 xterm -display :1
1656 To redirect telnet connections from host port 5555 to telnet
1658 port on the guest, use the following:
1659 # on the host
1661 qemu-system-i386 -nic user,hostfwd=tcp::5555-:23
1662 telnet localhost 5555
1663 Then when you use on the host "telnet localhost 5555", you
1665 connect to the guest telnet server.
1666 guestfwd=[tcp]:server:port-dev
1668 guestfwd=[tcp]:server:port-cmd:command
1669 Forward guest TCP connections to the IP address server on port
1670 port to the character device dev or to a program executed by
1671 cmd:command which gets spawned for each connection. This option
1672 can be given multiple times.
1673 You can either use a chardev directly and have that one used
1675 throughout QEMU's lifetime, like in the following example:
1676 # open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
1678 # the guest accesses it
1679 qemu-system-i386 -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321
1680 Or you can execute a command on every TCP connection
1682 established by the guest, so that QEMU behaves similar to an
1683 inetd process for that virtual server:
1684 # call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
1686 # and connect the TCP stream to its stdin/stdout
1687 qemu-system-i386 -nic 'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
1688 Note: Legacy stand-alone options -tftp, -bootp, -smb and -redir are
1690 still processed and applied to -net user. Mixing them with the new
1691 configuration syntax gives undefined results. Their use for new
1692 applications is discouraged as they will be removed from future
1693 versions.
1694 -netdev
1696 tap,id=id[,fd=h][,ifname=name][,script=file][,downscript=dfile][,br=bridge][,helper=helper]
1697 Configure a host TAP network backend with ID id.
1698 Use the network script file to configure it and the network script
1700 dfile to deconfigure it. If name is not provided, the OS
1701 automatically provides one. The default network configure script is
1702 /etc/qemu-ifup and the default network deconfigure script is
1703 /etc/qemu-ifdown. Use script=no or downscript=no to disable script
1704 execution.
1705 If running QEMU as an unprivileged user, use the network helper
1707 helper to configure the TAP interface and attach it to the bridge.
1708 The default network helper executable is
1709 /path/to/qemu-bridge-helper and the default bridge device is br0.
1710 fd=h can be used to specify the handle of an already opened host
1712 TAP interface.
1713 Examples:
1715 #launch a QEMU instance with the default network script
1717 qemu-system-i386 linux.img -nic tap
1718 #launch a QEMU instance with two NICs, each one connected
1722 #to a TAP device
1723 qemu-system-i386 linux.img \
1724 -netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 \
1725 -netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1
1726 #launch a QEMU instance with the default network helper to
1730 #connect a TAP device to bridge br0
1731 qemu-system-i386 linux.img -device virtio-net-pci,netdev=n1 \
1732 -netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper"
1733 -netdev bridge,id=id[,br=bridge][,helper=helper]
1735 Connect a host TAP network interface to a host bridge device.
1736 Use the network helper helper to configure the TAP interface and
1738 attach it to the bridge. The default network helper executable is
1739 /path/to/qemu-bridge-helper and the default bridge device is br0.
1740 Examples:
1742 #launch a QEMU instance with the default network helper to
1744 #connect a TAP device to bridge br0
1745 qemu-system-i386 linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1
1746 #launch a QEMU instance with the default network helper to
1750 #connect a TAP device to bridge qemubr0
1751 qemu-system-i386 linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1
1752 -netdev socket,id=id[,fd=h][,listen=[host]:port][,connect=host:port]
1754 This host network backend can be used to connect the guest's
1755 network to another QEMU virtual machine using a TCP socket
1756 connection. If listen is specified, QEMU waits for incoming
1757 connections on port (host is optional). connect is used to connect
1758 to another QEMU instance using the listen option. fd=h specifies an
1759 already opened TCP socket.
1760 Example:
1762 # launch a first QEMU instance
1764 qemu-system-i386 linux.img \
1765 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
1766 -netdev socket,id=n1,listen=:1234
1767 # connect the network of this instance to the network of the first instance
1768 qemu-system-i386 linux.img \
1769 -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
1770 -netdev socket,id=n2,connect=127.0.0.1:1234
1771 -netdev socket,id=id[,fd=h][,mcast=maddr:port[,localaddr=addr]]
1773 Configure a socket host network backend to share the guest's
1774 network traffic with another QEMU virtual machines using a UDP
1775 multicast socket, effectively making a bus for every QEMU with same
1776 multicast address maddr and port. NOTES:
1777 1. Several QEMU can be running on different hosts and share same
1779 bus (assuming correct multicast setup for these hosts).
1780 2. mcast support is compatible with User Mode Linux (argument
1782 ethN=mcast), see <http://user-mode-linux.sf.net>.
1783 3. Use fd=h to specify an already opened UDP multicast socket.
1785 Example:
1787 # launch one QEMU instance
1789 qemu-system-i386 linux.img \
1790 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
1791 -netdev socket,id=n1,mcast=230.0.0.1:1234
1792 # launch another QEMU instance on same "bus"
1793 qemu-system-i386 linux.img \
1794 -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
1795 -netdev socket,id=n2,mcast=230.0.0.1:1234
1796 # launch yet another QEMU instance on same "bus"
1797 qemu-system-i386 linux.img \
1798 -device e1000,netdev=n3,macaddr=52:54:00:12:34:58 \
1799 -netdev socket,id=n3,mcast=230.0.0.1:1234
1800 Example (User Mode Linux compat.):
1802 # launch QEMU instance (note mcast address selected is UML's default)
1804 qemu-system-i386 linux.img \
1805 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
1806 -netdev socket,id=n1,mcast=239.192.168.1:1102
1807 # launch UML
1808 /path/to/linux ubd0=/path/to/root_fs eth0=mcast
1809 Example (send packets from host's 1.2.3.4):
1811 qemu-system-i386 linux.img \
1813 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
1814 -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4
1815 -netdev
1817 l2tpv3,id=id,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport],txsession=txsession[,rxsession=rxsession][,ipv6][,udp][,cookie64][,counter][,pincounter][,txcookie=txcookie][,rxcookie=rxcookie][,offset=offset]
1818 Configure a L2TPv3 pseudowire host network backend. L2TPv3
1819 (RFC3391) is a popular protocol to transport Ethernet (and other
1820 Layer 2) data frames between two systems. It is present in routers,
1821 firewalls and the Linux kernel (from version 3.3 onwards).
1822 This transport allows a VM to communicate to another VM, router or
1824 firewall directly.
1825 src=srcaddr
1827 source address (mandatory)
1828 dst=dstaddr
1830 destination address (mandatory)
1831 udp select udp encapsulation (default is ip).
1833 srcport=srcport
1835 source udp port.
1836 dstport=dstport
1838 destination udp port.
1839 ipv6
1841 force v6, otherwise defaults to v4.
1842 rxcookie=rxcookie
1844 txcookie=txcookie
1845 Cookies are a weak form of security in the l2tpv3
1846 specification. Their function is mostly to prevent
1847 misconfiguration. By default they are 32 bit.
1848 cookie64
1850 Set cookie size to 64 bit instead of the default 32
1851 counter=off
1853 Force a 'cut-down' L2TPv3 with no counter as in
1854 draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
1855 pincounter=on
1857 Work around broken counter handling in peer. This may also help
1858 on networks which have packet reorder.
1859 offset=offset
1861 Add an extra offset between header and data
1862 For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to
1864 the bridge br-lan on the remote Linux host 1.2.3.4:
1865 # Setup tunnel on linux host using raw ip as encapsulation
1867 # on 1.2.3.4
1868 ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \
1869 encap udp udp_sport 16384 udp_dport 16384
1870 ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \
1871 0xFFFFFFFF peer_session_id 0xFFFFFFFF
1872 ifconfig vmtunnel0 mtu 1500
1873 ifconfig vmtunnel0 up
1874 brctl addif br-lan vmtunnel0
1875 # on 4.3.2.1
1878 # launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
1879 qemu-system-i386 linux.img -device e1000,netdev=n1 \
1881 -netdev l2tpv3,id=n1,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter
1882 -netdev
1884 vde,id=id[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]
1885 Configure VDE backend to connect to PORT n of a vde switch running
1886 on host and listening for incoming connections on socketpath. Use
1887 GROUP groupname and MODE octalmode to change default ownership and
1888 permissions for communication port. This option is only available
1889 if QEMU has been compiled with vde support enabled.
1890 Example:
1892 # launch vde switch
1894 vde_switch -F -sock /tmp/myswitch
1895 # launch QEMU instance
1896 qemu-system-i386 linux.img -nic vde,sock=/tmp/myswitch
1897 -netdev vhost-user,chardev=id[,vhostforce=on|off][,queues=n]
1899 Establish a vhost-user netdev, backed by a chardev id. The chardev
1900 should be a unix domain socket backed one. The vhost-user uses a
1901 specifically defined protocol to pass vhost ioctl replacement
1902 messages to an application on the other end of the socket. On non-
1903 MSIX guests, the feature can be forced with vhostforce. Use
1904 'queues=n' to specify the number of queues to be created for
1905 multiqueue vhost-user.
1906 Example:
1908 qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
1910 -numa node,memdev=mem \
1911 -chardev socket,id=chr0,path=/path/to/socket \
1912 -netdev type=vhost-user,id=net0,chardev=chr0 \
1913 -device virtio-net-pci,netdev=net0
1914 -netdev hubport,id=id,hubid=hubid[,netdev=nd]
1916 Create a hub port on the emulated hub with ID hubid.
1917 The hubport netdev lets you connect a NIC to a QEMU emulated hub
1919 instead of a single netdev. Alternatively, you can also connect the
1920 hubport to another netdev with ID nd by using the netdev=nd option.
1921 -net nic[,netdev=nd][,macaddr=mac][,model=type]
1923 [,name=name][,addr=addr][,vectors=v]
1924 Legacy option to configure or create an on-board (or machine
1925 default) Network Interface Card(NIC) and connect it either to the
1926 emulated hub with ID 0 (i.e. the default hub), or to the netdev
1927 nd. The NIC is an e1000 by default on the PC target. Optionally,
1928 the MAC address can be changed to mac, the device address set to
1929 addr (PCI cards only), and a name can be assigned for use in
1930 monitor commands. Optionally, for PCI cards, you can specify the
1931 number v of MSI-X vectors that the card should have; this option
1932 currently only affects virtio cards; set v = 0 to disable MSI-X. If
1933 no -net option is specified, a single NIC is created. QEMU can
1934 emulate several different models of network card. Use "-net
1935 nic,model=help" for a list of available devices for your target.
1936 -net user|tap|bridge|socket|l2tpv3|vde[,...][,name=name]
1938 Configure a host network backend (with the options corresponding to
1939 the same -netdev option) and connect it to the emulated hub 0 (the
1940 default hub). Use name to specify the name of the hub port.
1941 Character device options
1943 The general form of a character device option is:
1945 -chardev backend,id=id[,mux=on|off][,options]
1947 Backend is one of: null, socket, udp, msmouse, vc, ringbuf, file,
1948 pipe, console, serial, pty, stdio, braille, tty, parallel, parport,
1949 spicevmc, spiceport. The specific backend will determine the
1950 applicable options.
1951 Use "-chardev help" to print all available chardev backend types.
1953 All devices must have an id, which can be any string up to 127
1955 characters long. It is used to uniquely identify this device in
1956 other command line directives.
1957 A character device may be used in multiplexing mode by multiple
1959 front-ends. Specify mux=on to enable this mode. A multiplexer is
1960 a "1:N" device, and here the "1" end is your specified chardev
1961 backend, and the "N" end is the various parts of QEMU that can talk
1962 to a chardev. If you create a chardev with id=myid and mux=on,
1963 QEMU will create a multiplexer with your specified ID, and you can
1964 then configure multiple front ends to use that chardev ID for their
1965 input/output. Up to four different front ends can be connected to a
1966 single multiplexed chardev. (Without multiplexing enabled, a
1967 chardev can only be used by a single front end.) For instance you
1968 could use this to allow a single stdio chardev to be used by two
1969 serial ports and the QEMU monitor:
1970 -chardev stdio,mux=on,id=char0 \
1972 -mon chardev=char0,mode=readline \
1973 -serial chardev:char0 \
1974 -serial chardev:char0
1975 You can have more than one multiplexer in a system configuration;
1977 for instance you could have a TCP port multiplexed between UART 0
1978 and UART 1, and stdio multiplexed between the QEMU monitor and a
1979 parallel port:
1980 -chardev stdio,mux=on,id=char0 \
1982 -mon chardev=char0,mode=readline \
1983 -parallel chardev:char0 \
1984 -chardev tcp,...,mux=on,id=char1 \
1985 -serial chardev:char1 \
1986 -serial chardev:char1
1987 When you're using a multiplexed character device, some escape
1989 sequences are interpreted in the input.
1990 Note that some other command line options may implicitly create
1992 multiplexed character backends; for instance -serial mon:stdio
1993 creates a multiplexed stdio backend connected to the serial port
1994 and the QEMU monitor, and -nographic also multiplexes the console
1995 and the monitor to stdio.
1996 There is currently no support for multiplexing in the other
1998 direction (where a single QEMU front end takes input and output
1999 from multiple chardevs).
2000 Every backend supports the logfile option, which supplies the path
2002 to a file to record all data transmitted via the backend. The
2003 logappend option controls whether the log file will be truncated or
2004 appended to when opened.
2005 The available backends are:
2007 -chardev null,id=id
2009 A void device. This device will not emit any data, and will drop
2010 any data it receives. The null backend does not take any options.
2011 -chardev socket,id=id[,TCP options or unix
2013 options][,server][,nowait][,telnet][,reconnect=seconds][,tls-creds=id]
2014 Create a two-way stream socket, which can be either a TCP or a unix
2015 socket. A unix socket will be created if path is specified.
2016 Behaviour is undefined if TCP options are specified for a unix
2017 socket.
2018 server specifies that the socket shall be a listening socket.
2020 nowait specifies that QEMU should not block waiting for a client to
2022 connect to a listening socket.
2023 telnet specifies that traffic on the socket should interpret telnet
2025 escape sequences.
2026 reconnect sets the timeout for reconnecting on non-server sockets
2028 when the remote end goes away. qemu will delay this many seconds
2029 and then attempt to reconnect. Zero disables reconnecting, and is
2030 the default.
2031 tls-creds requests enablement of the TLS protocol for encryption,
2033 and specifies the id of the TLS credentials to use for the
2034 handshake. The credentials must be previously created with the
2035 -object tls-creds argument.
2036 TCP and unix socket options are given below:
2038 TCP options: port=port[,host=host][,to=to][,ipv4][,ipv6][,nodelay]
2040 host for a listening socket specifies the local address to be
2041 bound. For a connecting socket species the remote host to
2042 connect to. host is optional for listening sockets. If not
2043 specified it defaults to 0.0.0.0.
2044 port for a listening socket specifies the local port to be
2046 bound. For a connecting socket specifies the port on the remote
2047 host to connect to. port can be given as either a port number
2048 or a service name. port is required.
2049 to is only relevant to listening sockets. If it is specified,
2051 and port cannot be bound, QEMU will attempt to bind to
2052 subsequent ports up to and including to until it succeeds. to
2053 must be specified as a port number.
2054 ipv4 and ipv6 specify that either IPv4 or IPv6 must be used.
2056 If neither is specified the socket may use either protocol.
2057 nodelay disables the Nagle algorithm.
2059 unix options: path=path
2061 path specifies the local path of the unix socket. path is
2062 required.
2063 -chardev
2065 udp,id=id[,host=host],port=port[,localaddr=localaddr][,localport=localport][,ipv4][,ipv6]
2066 Sends all traffic from the guest to a remote host over UDP.
2067 host specifies the remote host to connect to. If not specified it
2069 defaults to "localhost".
2070 port specifies the port on the remote host to connect to. port is
2072 required.
2073 localaddr specifies the local address to bind to. If not specified
2075 it defaults to 0.0.0.0.
2076 localport specifies the local port to bind to. If not specified any
2078 available local port will be used.
2079 ipv4 and ipv6 specify that either IPv4 or IPv6 must be used. If
2081 neither is specified the device may use either protocol.
2082 -chardev msmouse,id=id
2084 Forward QEMU's emulated msmouse events to the guest. msmouse does
2085 not take any options.
2086 -chardev
2088 vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]
2089 Connect to a QEMU text console. vc may optionally be given a
2090 specific size.
2091 width and height specify the width and height respectively of the
2093 console, in pixels.
2094 cols and rows specify that the console be sized to fit a text
2096 console with the given dimensions.
2097 -chardev ringbuf,id=id[,size=size]
2099 Create a ring buffer with fixed size size. size must be a power of
2100 two and defaults to "64K".
2101 -chardev file,id=id,path=path
2103 Log all traffic received from the guest to a file.
2104 path specifies the path of the file to be opened. This file will be
2106 created if it does not already exist, and overwritten if it does.
2107 path is required.
2108 -chardev pipe,id=id,path=path
2110 Create a two-way connection to the guest. The behaviour differs
2111 slightly between Windows hosts and other hosts:
2112 On Windows, a single duplex pipe will be created at \\.pipe\path.
2114 On other hosts, 2 pipes will be created called path.in and
2116 path.out. Data written to path.in will be received by the guest.
2117 Data written by the guest can be read from path.out. QEMU will not
2118 create these fifos, and requires them to be present.
2119 path forms part of the pipe path as described above. path is
2121 required.
2122 -chardev console,id=id
2124 Send traffic from the guest to QEMU's standard output. console does
2125 not take any options.
2126 console is only available on Windows hosts.
2128 -chardev serial,id=id,path=path
2130 Send traffic from the guest to a serial device on the host.
2131 On Unix hosts serial will actually accept any tty device, not only
2133 serial lines.
2134 path specifies the name of the serial device to open.
2136 -chardev pty,id=id
2138 Create a new pseudo-terminal on the host and connect to it. pty
2139 does not take any options.
2140 pty is not available on Windows hosts.
2142 -chardev stdio,id=id[,signal=on|off]
2144 Connect to standard input and standard output of the QEMU process.
2145 signal controls if signals are enabled on the terminal, that
2147 includes exiting QEMU with the key sequence Control-c. This option
2148 is enabled by default, use signal=off to disable it.
2149 -chardev braille,id=id
2151 Connect to a local BrlAPI server. braille does not take any
2152 options.
2153 -chardev tty,id=id,path=path
2155 tty is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
2156 DragonFlyBSD hosts. It is an alias for serial.
2157 path specifies the path to the tty. path is required.
2159 -chardev parallel,id=id,path=path
2161 -chardev parport,id=id,path=path
2162 parallel is only available on Linux, FreeBSD and DragonFlyBSD
2163 hosts.
2164 Connect to a local parallel port.
2166 path specifies the path to the parallel port device. path is
2168 required.
2169 -chardev spicevmc,id=id,debug=debug,name=name
2171 spicevmc is only available when spice support is built in.
2172 debug debug level for spicevmc
2174 name name of spice channel to connect to
2176 Connect to a spice virtual machine channel, such as vdiport.
2178 -chardev spiceport,id=id,debug=debug,name=name
2180 spiceport is only available when spice support is built in.
2181 debug debug level for spicevmc
2183 name name of spice port to connect to
2185 Connect to a spice port, allowing a Spice client to handle the
2187 traffic identified by a name (preferably a fqdn).
2188 Bluetooth(R) options
2190 -bt hci[...]
2192 Defines the function of the corresponding Bluetooth HCI. -bt
2193 options are matched with the HCIs present in the chosen machine
2194 type. For example when emulating a machine with only one HCI built
2195 into it, only the first "-bt hci[...]" option is valid and defines
2196 the HCI's logic. The Transport Layer is decided by the machine
2197 type. Currently the machines "n800" and "n810" have one HCI and
2198 all other machines have none.
2199 The following three types are recognized:
2201 -bt hci,null
2203 (default) The corresponding Bluetooth HCI assumes no internal
2204 logic and will not respond to any HCI commands or emit events.
2205 -bt hci,host[:id]
2207 ("bluez" only) The corresponding HCI passes commands / events
2208 to / from the physical HCI identified by the name id (default:
2209 "hci0") on the computer running QEMU. Only available on
2210 "bluez" capable systems like Linux.
2211 -bt hci[,vlan=n]
2213 Add a virtual, standard HCI that will participate in the
2214 Bluetooth scatternet n (default 0). Similarly to -net VLANs,
2215 devices inside a bluetooth network n can only communicate with
2216 other devices in the same network (scatternet).
2217 -bt vhci[,vlan=n]
2219 (Linux-host only) Create a HCI in scatternet n (default 0) attached
2220 to the host bluetooth stack instead of to the emulated target.
2221 This allows the host and target machines to participate in a common
2222 scatternet and communicate. Requires the Linux "vhci" driver
2223 installed. Can be used as following:
2224 qemu-system-i386 [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
2226 -bt device:dev[,vlan=n]
2228 Emulate a bluetooth device dev and place it in network n (default
2229 0). QEMU can only emulate one type of bluetooth devices currently:
2230 keyboard
2232 Virtual wireless keyboard implementing the HIDP bluetooth
2233 profile.
2234 TPM device options
2236 The general form of a TPM device option is:
2238 -tpmdev backend,id=id[,options]
2240 The specific backend type will determine the applicable options.
2241 The "-tpmdev" option creates the TPM backend and requires a
2242 "-device" option that specifies the TPM frontend interface model.
2243 Use "-tpmdev help" to print all available TPM backend types.
2245 The available backends are:
2247 -tpmdev passthrough,id=id,path=path,cancel-path=cancel-path
2249 (Linux-host only) Enable access to the host's TPM using the
2250 passthrough driver.
2251 path specifies the path to the host's TPM device, i.e., on a Linux
2253 host this would be "/dev/tpm0". path is optional and by default
2254 "/dev/tpm0" is used.
2255 cancel-path specifies the path to the host TPM device's sysfs entry
2257 allowing for cancellation of an ongoing TPM command. cancel-path
2258 is optional and by default QEMU will search for the sysfs entry to
2259 use.
2260 Some notes about using the host's TPM with the passthrough driver:
2262 The TPM device accessed by the passthrough driver must not be used
2264 by any other application on the host.
2265 Since the host's firmware (BIOS/UEFI) has already initialized the
2267 TPM, the VM's firmware (BIOS/UEFI) will not be able to initialize
2268 the TPM again and may therefore not show a TPM-specific menu that
2269 would otherwise allow the user to configure the TPM, e.g., allow
2270 the user to enable/disable or activate/deactivate the TPM.
2271 Further, if TPM ownership is released from within a VM then the
2272 host's TPM will get disabled and deactivated. To enable and
2273 activate the TPM again afterwards, the host has to be rebooted and
2274 the user is required to enter the firmware's menu to enable and
2275 activate the TPM. If the TPM is left disabled and/or deactivated
2276 most TPM commands will fail.
2277 To create a passthrough TPM use the following two options:
2279 -tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
2281 Note that the "-tpmdev" id is "tpm0" and is referenced by
2283 "tpmdev=tpm0" in the device option.
2284 -tpmdev emulator,id=id,chardev=dev
2286 (Linux-host only) Enable access to a TPM emulator using Unix domain
2287 socket based chardev backend.
2288 chardev specifies the unique ID of a character device backend that
2290 provides connection to the software TPM server.
2291 To create a TPM emulator backend device with chardev socket
2293 backend:
2294 -chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0
2296 Linux/Multiboot boot specific
2298 When using these options, you can use a given Linux or Multiboot kernel
2300 without installing it in the disk image. It can be useful for easier
2301 testing of various kernels.
2302 -kernel bzImage
2304 Use bzImage as kernel image. The kernel can be either a Linux
2305 kernel or in multiboot format.
2306 -append cmdline
2308 Use cmdline as kernel command line
2309 -initrd file
2311 Use file as initial ram disk.
2312 -initrd "file1 arg=foo,file2"
2314 This syntax is only available with multiboot.
2315 Use file1 and file2 as modules and pass arg=foo as parameter to the
2317 first module.
2318 -dtb file
2320 Use file as a device tree binary (dtb) image and pass it to the
2321 kernel on boot.
2322 Debug/Expert options
2324 -fw_cfg [name=]name,file=file
2326 Add named fw_cfg entry with contents from file file.
2327 -fw_cfg [name=]name,string=str
2329 Add named fw_cfg entry with contents from string str.
2330 The terminating NUL character of the contents of str will not be
2332 included as part of the fw_cfg item data. To insert contents with
2333 embedded NUL characters, you have to use the file parameter.
2334 The fw_cfg entries are passed by QEMU through to the guest.
2336 Example:
2338 -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
2340 creates an fw_cfg entry named opt/com.mycompany/blob with contents
2342 from ./my_blob.bin.
2343 -serial dev
2345 Redirect the virtual serial port to host character device dev. The
2346 default device is "vc" in graphical mode and "stdio" in non
2347 graphical mode.
2348 This option can be used several times to simulate up to 4 serial
2350 ports.
2351 Use "-serial none" to disable all serial ports.
2353 Available character devices are:
2355 vc[:WxH]
2357 Virtual console. Optionally, a width and height can be given in
2358 pixel with
2359 vc:800x600
2361 It is also possible to specify width or height in characters:
2363 vc:80Cx24C
2365 pty [Linux only] Pseudo TTY (a new PTY is automatically allocated)
2367 none
2369 No device is allocated.
2370 null
2372 void device
2373 chardev:id
2375 Use a named character device defined with the "-chardev"
2376 option.
2377 /dev/XXX
2379 [Linux only] Use host tty, e.g. /dev/ttyS0. The host serial
2380 port parameters are set according to the emulated ones.
2381 /dev/parportN
2383 [Linux only, parallel port only] Use host parallel port N.
2384 Currently SPP and EPP parallel port features can be used.
2385 file:filename
2387 Write output to filename. No character can be read.
2388 stdio
2390 [Unix only] standard input/output
2391 pipe:filename
2393 name pipe filename
2394 COMn
2396 [Windows only] Use host serial port n
2397 udp:[remote_host]:remote_port[@[src_ip]:src_port]
2399 This implements UDP Net Console. When remote_host or src_ip
2400 are not specified they default to 0.0.0.0. When not using a
2401 specified src_port a random port is automatically chosen.
2402 If you just want a simple readonly console you can use "netcat"
2404 or "nc", by starting QEMU with: "-serial udp::4555" and nc as:
2405 "nc -u -l -p 4555". Any time QEMU writes something to that port
2406 it will appear in the netconsole session.
2407 If you plan to send characters back via netconsole or you want
2409 to stop and start QEMU a lot of times, you should have QEMU use
2410 the same source port each time by using something like "-serial
2411 udp::4555@4556" to QEMU. Another approach is to use a patched
2412 version of netcat which can listen to a TCP port and send and
2413 receive characters via udp. If you have a patched version of
2414 netcat which activates telnet remote echo and single char
2415 transfer, then you can use the following options to set up a
2416 netcat redirector to allow telnet on port 5555 to access the
2417 QEMU port.
2418 "QEMU Options:"
2420 -serial udp::4555@4556
2421 "netcat options:"
2423 -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
2424 "telnet options:"
2426 localhost 5555
2427 tcp:[host]:port[,server][,nowait][,nodelay][,reconnect=seconds]
2429 The TCP Net Console has two modes of operation. It can send
2430 the serial I/O to a location or wait for a connection from a
2431 location. By default the TCP Net Console is sent to host at
2432 the port. If you use the server option QEMU will wait for a
2433 client socket application to connect to the port before
2434 continuing, unless the "nowait" option was specified. The
2435 "nodelay" option disables the Nagle buffering algorithm. The
2436 "reconnect" option only applies if noserver is set, if the
2437 connection goes down it will attempt to reconnect at the given
2438 interval. If host is omitted, 0.0.0.0 is assumed. Only one TCP
2439 connection at a time is accepted. You can use "telnet" to
2440 connect to the corresponding character device.
2441 "Example to send tcp console to 192.168.0.2 port 4444"
2443 -serial tcp:192.168.0.2:4444
2444 "Example to listen and wait on port 4444 for connection"
2446 -serial tcp::4444,server
2447 "Example to not wait and listen on ip 192.168.0.100 port 4444"
2449 -serial tcp:192.168.0.100:4444,server,nowait
2450 telnet:host:port[,server][,nowait][,nodelay]
2452 The telnet protocol is used instead of raw tcp sockets. The
2453 options work the same as if you had specified "-serial tcp".
2454 The difference is that the port acts like a telnet server or
2455 client using telnet option negotiation. This will also allow
2456 you to send the MAGIC_SYSRQ sequence if you use a telnet that
2457 supports sending the break sequence. Typically in unix telnet
2458 you do it with Control-] and then type "send break" followed by
2459 pressing the enter key.
2460 unix:path[,server][,nowait][,reconnect=seconds]
2462 A unix domain socket is used instead of a tcp socket. The
2463 option works the same as if you had specified "-serial tcp"
2464 except the unix domain socket path is used for connections.
2465 mon:dev_string
2467 This is a special option to allow the monitor to be multiplexed
2468 onto another serial port. The monitor is accessed with key
2469 sequence of Control-a and then pressing c. dev_string should
2470 be any one of the serial devices specified above. An example
2471 to multiplex the monitor onto a telnet server listening on port
2472 4444 would be:
2473 "-serial mon:telnet::4444,server,nowait"
2475 When the monitor is multiplexed to stdio in this way, Ctrl+C
2477 will not terminate QEMU any more but will be passed to the
2478 guest instead.
2479 braille
2481 Braille device. This will use BrlAPI to display the braille
2482 output on a real or fake device.
2483 msmouse
2485 Three button serial mouse. Configure the guest to use Microsoft
2486 protocol.
2487 -parallel dev
2489 Redirect the virtual parallel port to host device dev (same devices
2490 as the serial port). On Linux hosts, /dev/parportN can be used to
2491 use hardware devices connected on the corresponding host parallel
2492 port.
2493 This option can be used several times to simulate up to 3 parallel
2495 ports.
2496 Use "-parallel none" to disable all parallel ports.
2498 -monitor dev
2500 Redirect the monitor to host device dev (same devices as the serial
2501 port). The default device is "vc" in graphical mode and "stdio" in
2502 non graphical mode. Use "-monitor none" to disable the default
2503 monitor.
2504 -qmp dev
2506 Like -monitor but opens in 'control' mode.
2507 -qmp-pretty dev
2509 Like -qmp but uses pretty JSON formatting.
2510 -mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]
2512 Setup monitor on chardev name. "pretty" turns on JSON pretty
2513 printing easing human reading and debugging.
2514 -debugcon dev
2516 Redirect the debug console to host device dev (same devices as the
2517 serial port). The debug console is an I/O port which is typically
2518 port 0xe9; writing to that I/O port sends output to this device.
2519 The default device is "vc" in graphical mode and "stdio" in non
2520 graphical mode.
2521 -pidfile file
2523 Store the QEMU process PID in file. It is useful if you launch QEMU
2524 from a script.
2525 -singlestep
2527 Run the emulation in single step mode.
2528 --preconfig
2530 Pause QEMU for interactive configuration before the machine is
2531 created, which allows querying and configuring properties that will
2532 affect machine initialization. Use QMP command 'x-exit-preconfig'
2533 to exit the preconfig state and move to the next state (i.e. run
2534 guest if -S isn't used or pause the second time if -S is used).
2535 This option is experimental.
2536 -S Do not start CPU at startup (you must type 'c' in the monitor).
2538 -realtime mlock=on|off
2540 Run qemu with realtime features. mlocking qemu and guest memory
2541 can be enabled via mlock=on (enabled by default).
2542 -overcommit mem-lock=on|off
2544 -overcommit cpu-pm=on|off
2545 Run qemu with hints about host resource overcommit. The default is
2546 to assume that host overcommits all resources.
2547 Locking qemu and guest memory can be enabled via mem-lock=on
2549 (disabled by default). This works when host memory is not
2550 overcommitted and reduces the worst-case latency for guest. This
2551 is equivalent to realtime.
2552 Guest ability to manage power state of host cpus (increasing
2554 latency for other processes on the same host cpu, but decreasing
2555 latency for guest) can be enabled via cpu-pm=on (disabled by
2556 default). This works best when host CPU is not overcommitted. When
2557 used, host estimates of CPU cycle and power utilization will be
2558 incorrect, not taking into account guest idle time.
2559 -gdb dev
2561 Wait for gdb connection on device dev. Typical connections will
2562 likely be TCP-based, but also UDP, pseudo TTY, or even stdio are
2563 reasonable use case. The latter is allowing to start QEMU from
2564 within gdb and establish the connection via a pipe:
2565 (gdb) target remote | exec qemu-system-i386 -gdb stdio ...
2567 -s Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port
2569 1234.
2570 -d item1[,...]
2572 Enable logging of specified items. Use '-d help' for a list of log
2573 items.
2574 -D logfile
2576 Output log in logfile instead of to stderr
2577 -dfilter range1[,...]
2579 Filter debug output to that relevant to a range of target
2580 addresses. The filter spec can be either start+size, start-size or
2581 start..end where start end and size are the addresses and sizes
2582 required. For example:
2583 -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000
2585 Will dump output for any code in the 0x1000 sized block starting at
2587 0x8000 and the 0x200 sized block starting at 0xffffffc000080000 and
2588 another 0x1000 sized block starting at 0xffffffc00005f000.
2589 -L path
2591 Set the directory for the BIOS, VGA BIOS and keymaps.
2592 To list all the data directories, use "-L help".
2594 -bios file
2596 Set the filename for the BIOS.
2597 -enable-kvm
2599 Enable KVM full virtualization support. This option is only
2600 available if KVM support is enabled when compiling.
2601 -enable-hax
2603 Enable HAX (Hardware-based Acceleration eXecution) support. This
2604 option is only available if HAX support is enabled when compiling.
2605 HAX is only applicable to MAC and Windows platform, and thus does
2606 not conflict with KVM. This option is deprecated, use -accel hax
2607 instead.
2608 -xen-domid id
2610 Specify xen guest domain id (XEN only).
2611 -xen-create
2613 Create domain using xen hypercalls, bypassing xend. Warning:
2614 should not be used when xend is in use (XEN only).
2615 -xen-attach
2617 Attach to existing xen domain. xend will use this when starting
2618 QEMU (XEN only). Restrict set of available xen operations to
2619 specified domain id (XEN only).
2620 -no-reboot
2622 Exit instead of rebooting.
2623 -no-shutdown
2625 Don't exit QEMU on guest shutdown, but instead only stop the
2626 emulation. This allows for instance switching to monitor to commit
2627 changes to the disk image.
2628 -loadvm file
2630 Start right away with a saved state ("loadvm" in monitor)
2631 -daemonize
2633 Daemonize the QEMU process after initialization. QEMU will not
2634 detach from standard IO until it is ready to receive connections on
2635 any of its devices. This option is a useful way for external
2636 programs to launch QEMU without having to cope with initialization
2637 race conditions.
2638 -option-rom file
2640 Load the contents of file as an option ROM. This option is useful
2641 to load things like EtherBoot.
2642 -rtc [base=utc|localtime|date][,clock=host|vm][,driftfix=none|slew]
2644 Specify base as "utc" or "localtime" to let the RTC start at the
2645 current UTC or local time, respectively. "localtime" is required
2646 for correct date in MS-DOS or Windows. To start at a specific point
2647 in time, provide date in the format "2006-06-17T16:01:21" or
2648 "2006-06-17". The default base is UTC.
2649 By default the RTC is driven by the host system time. This allows
2651 using of the RTC as accurate reference clock inside the guest,
2652 specifically if the host time is smoothly following an accurate
2653 external reference clock, e.g. via NTP. If you want to isolate the
2654 guest time from the host, you can set clock to "rt" instead. To
2655 even prevent it from progressing during suspension, you can set it
2656 to "vm".
2657 Enable driftfix (i386 targets only) if you experience time drift
2659 problems, specifically with Windows' ACPI HAL. This option will try
2660 to figure out how many timer interrupts were not processed by the
2661 Windows guest and will re-inject them.
2662 -icount
2664 [shift=N|auto][,rr=record|replay,rrfile=filename,rrsnapshot=snapshot]
2665 Enable virtual instruction counter. The virtual cpu will execute
2666 one instruction every 2^N ns of virtual time. If "auto" is
2667 specified then the virtual cpu speed will be automatically adjusted
2668 to keep virtual time within a few seconds of real time.
2669 When the virtual cpu is sleeping, the virtual time will advance at
2671 default speed unless sleep=on|off is specified. With sleep=on|off,
2672 the virtual time will jump to the next timer deadline instantly
2673 whenever the virtual cpu goes to sleep mode and will not advance if
2674 no timer is enabled. This behavior give deterministic execution
2675 times from the guest point of view.
2676 Note that while this option can give deterministic behavior, it
2678 does not provide cycle accurate emulation. Modern CPUs contain
2679 superscalar out of order cores with complex cache hierarchies. The
2680 number of instructions executed often has little or no correlation
2681 with actual performance.
2682 align=on will activate the delay algorithm which will try to
2684 synchronise the host clock and the virtual clock. The goal is to
2685 have a guest running at the real frequency imposed by the shift
2686 option. Whenever the guest clock is behind the host clock and if
2687 align=on is specified then we print a message to the user to inform
2688 about the delay. Currently this option does not work when shift is
2689 "auto". Note: The sync algorithm will work for those shift values
2690 for which the guest clock runs ahead of the host clock. Typically
2691 this happens when the shift value is high (how high depends on the
2692 host machine).
2693 When rr option is specified deterministic record/replay is enabled.
2695 Replay log is written into filename file in record mode and read
2696 from this file in replay mode.
2697 Option rrsnapshot is used to create new vm snapshot named snapshot
2699 at the start of execution recording. In replay mode this option is
2700 used to load the initial VM state.
2701 -watchdog model
2703 Create a virtual hardware watchdog device. Once enabled (by a
2704 guest action), the watchdog must be periodically polled by an agent
2705 inside the guest or else the guest will be restarted. Choose a
2706 model for which your guest has drivers.
2707 The model is the model of hardware watchdog to emulate. Use
2709 "-watchdog help" to list available hardware models. Only one
2710 watchdog can be enabled for a guest.
2711 The following models may be available:
2713 ib700
2715 iBASE 700 is a very simple ISA watchdog with a single timer.
2716 i6300esb
2718 Intel 6300ESB I/O controller hub is a much more featureful PCI-
2719 based dual-timer watchdog.
2720 diag288
2722 A virtual watchdog for s390x backed by the diagnose 288
2723 hypercall (currently KVM only).
2724 -watchdog-action action
2726 The action controls what QEMU will do when the watchdog timer
2727 expires. The default is "reset" (forcefully reset the guest).
2728 Other possible actions are: "shutdown" (attempt to gracefully
2729 shutdown the guest), "poweroff" (forcefully poweroff the guest),
2730 "inject-nmi" (inject a NMI into the guest), "pause" (pause the
2731 guest), "debug" (print a debug message and continue), or "none" (do
2732 nothing).
2733 Note that the "shutdown" action requires that the guest responds to
2735 ACPI signals, which it may not be able to do in the sort of
2736 situations where the watchdog would have expired, and thus
2737 "-watchdog-action shutdown" is not recommended for production use.
2738 Examples:
2740 "-watchdog i6300esb -watchdog-action pause"
2742 "-watchdog ib700"
2743 -echr numeric_ascii_value
2744 Change the escape character used for switching to the monitor when
2745 using monitor and serial sharing. The default is 0x01 when using
2746 the "-nographic" option. 0x01 is equal to pressing "Control-a".
2747 You can select a different character from the ascii control keys
2748 where 1 through 26 map to Control-a through Control-z. For
2749 instance you could use the either of the following to change the
2750 escape character to Control-t.
2751 "-echr 0x14"
2753 "-echr 20"
2754 -virtioconsole c
2755 Set virtio console. This option is deprecated, please use -device
2756 virtconsole instead.
2757 -show-cursor
2759 Show cursor.
2760 -tb-size n
2762 Set TB size.
2763 -incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]
2765 -incoming rdma:host:port[,ipv4][,ipv6]
2766 Prepare for incoming migration, listen on a given tcp port.
2767 -incoming unix:socketpath
2769 Prepare for incoming migration, listen on a given unix socket.
2770 -incoming fd:fd
2772 Accept incoming migration from a given filedescriptor.
2773 -incoming exec:cmdline
2775 Accept incoming migration as an output from specified external
2776 command.
2777 -incoming defer
2779 Wait for the URI to be specified via migrate_incoming. The monitor
2780 can be used to change settings (such as migration parameters) prior
2781 to issuing the migrate_incoming to allow the migration to begin.
2782 -only-migratable
2784 Only allow migratable devices. Devices will not be allowed to enter
2785 an unmigratable state.
2786 -nodefaults
2788 Don't create default devices. Normally, QEMU sets the default
2789 devices like serial port, parallel port, virtual console, monitor
2790 device, VGA adapter, floppy and CD-ROM drive and others. The
2791 "-nodefaults" option will disable all those default devices.
2792 -chroot dir
2794 Immediately before starting guest execution, chroot to the
2795 specified directory. Especially useful in combination with -runas.
2796 -runas user
2798 Immediately before starting guest execution, drop root privileges,
2799 switching to the specified user.
2800 -prom-env variable=value
2802 Set OpenBIOS nvram variable to given value (PPC, SPARC only).
2803 -semihosting
2805 Enable semihosting mode (ARM, M68K, Xtensa, MIPS only).
2806 -semihosting-config
2808 [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]
2809 Enable and configure semihosting (ARM, M68K, Xtensa, MIPS only).
2810 target="native|gdb|auto"
2812 Defines where the semihosting calls will be addressed, to QEMU
2813 ("native") or to GDB ("gdb"). The default is "auto", which
2814 means "gdb" during debug sessions and "native" otherwise.
2815 arg=str1,arg=str2,...
2817 Allows the user to pass input arguments, and can be used
2818 multiple times to build up a list. The old-style
2819 "-kernel"/"-append" method of passing a command line is still
2820 supported for backward compatibility. If both the
2821 "--semihosting-config arg" and the "-kernel"/"-append" are
2822 specified, the former is passed to semihosting as it always
2823 takes precedence.
2824 -old-param
2826 Old param mode (ARM only).
2827 -sandbox
2829 arg[,obsolete=string][,elevateprivileges=string][,spawn=string][,resourcecontrol=string]
2830 Enable Seccomp mode 2 system call filter. 'on' will enable syscall
2831 filtering and 'off' will disable it. The default is 'off'.
2832 obsolete=string
2834 Enable Obsolete system calls
2835 elevateprivileges=string
2837 Disable set*uid|gid system calls
2838 spawn=string
2840 Disable *fork and execve
2841 resourcecontrol=string
2843 Disable process affinity and schedular priority
2844 -readconfig file
2846 Read device configuration from file. This approach is useful when
2847 you want to spawn QEMU process with many command line options but
2848 you don't want to exceed the command line character limit.
2849 -writeconfig file
2851 Write device configuration to file. The file can be either filename
2852 to save command line and device configuration into file or dash
2853 "-") character to print the output to stdout. This can be later
2854 used as input file for "-readconfig" option.
2855 -no-user-config
2857 The "-no-user-config" option makes QEMU not load any of the user-
2858 provided config files on sysconfdir.
2859 -trace [[enable=]pattern][,events=file][,file=file]
2861 Specify tracing options.
2862 [enable=]pattern
2864 Immediately enable events matching pattern (either event name
2865 or a globbing pattern). This option is only available if QEMU
2866 has been compiled with the simple, log or ftrace tracing
2867 backend. To specify multiple events or patterns, specify the
2868 -trace option multiple times.
2869 Use "-trace help" to print a list of names of trace points.
2871 events=file
2873 Immediately enable events listed in file. The file must
2874 contain one event name (as listed in the trace-events-all file)
2875 per line; globbing patterns are accepted too. This option is
2876 only available if QEMU has been compiled with the simple, log
2877 or ftrace tracing backend.
2878 file=file
2880 Log output traces to file. This option is only available if
2881 QEMU has been compiled with the simple tracing backend.
2882 -enable-fips
2884 Enable FIPS 140-2 compliance mode.
2885 -msg timestamp[=on|off]
2887 prepend a timestamp to each log message.(default:on)
2888 -dump-vmstate file
2890 Dump json-encoded vmstate information for current machine type to
2891 file in file
2892 Generic object creation
2894 -object typename[,prop1=value1,...]
2896 Create a new object of type typename setting properties in the
2897 order they are specified. Note that the 'id' property must be set.
2898 These objects are placed in the '/objects' path.
2899 -object
2901 memory-backend-file,id=id,size=size,mem-path=dir,share=on|off,discard-data=on|off,merge=on|off,dump=on|off,prealloc=on|off,host-nodes=host-
2902 nodes,policy=default|preferred|bind|interleave,align=align
2903 Creates a memory file backend object, which can be used to back
2904 the guest RAM with huge pages.
2905 The id parameter is a unique ID that will be used to reference
2907 this memory region when configuring the -numa argument.
2908 The size option provides the size of the memory region, and
2910 accepts common suffixes, eg 500M.
2911 The mem-path provides the path to either a shared memory or
2913 huge page filesystem mount.
2914 The share boolean option determines whether the memory region
2916 is marked as private to QEMU, or shared. The latter allows a
2917 co-operating external process to access the QEMU memory region.
2918 The share is also required for pvrdma devices due to
2920 limitations in the RDMA API provided by Linux.
2921 Setting share=on might affect the ability to configure NUMA
2923 bindings for the memory backend under some circumstances, see
2924 Documentation/vm/numa_memory_policy.txt on the Linux kernel
2925 source tree for additional details.
2926 Setting the discard-data boolean option to on indicates that
2928 file contents can be destroyed when QEMU exits, to avoid
2929 unnecessarily flushing data to the backing file. Note that
2930 discard-data is only an optimization, and QEMU might not
2931 discard file contents if it aborts unexpectedly or is
2932 terminated using SIGKILL.
2933 The merge boolean option enables memory merge, also known as
2935 MADV_MERGEABLE, so that Kernel Samepage Merging will consider
2936 the pages for memory deduplication.
2937 Setting the dump boolean option to off excludes the memory from
2939 core dumps. This feature is also known as MADV_DONTDUMP.
2940 The prealloc boolean option enables memory preallocation.
2942 The host-nodes option binds the memory range to a list of NUMA
2944 host nodes.
2945 The policy option sets the NUMA policy to one of the following
2947 values:
2948 default
2950 default host policy
2951 preferred
2953 prefer the given host node list for allocation
2954 bind
2956 restrict memory allocation to the given host node list
2957 interleave
2959 interleave memory allocations across the given host node
2960 list
2961 The align option specifies the base address alignment when QEMU
2963 mmap(2) mem-path, and accepts common suffixes, eg 2M. Some
2964 backend store specified by mem-path requires an alignment
2965 different than the default one used by QEMU, eg the device DAX
2966 /dev/dax0.0 requires 2M alignment rather than 4K. In such
2967 cases, users can specify the required alignment via this
2968 option.
2969 -object
2971 memory-backend-ram,id=id,merge=on|off,dump=on|off,share=on|off,prealloc=on|off,size=size,host-nodes=host-
2972 nodes,policy=default|preferred|bind|interleave
2973 Creates a memory backend object, which can be used to back the
2974 guest RAM. Memory backend objects offer more control than the
2975 -m option that is traditionally used to define guest RAM.
2976 Please refer to memory-backend-file for a description of the
2977 options.
2978 -object
2980 memory-backend-memfd,id=id,merge=on|off,dump=on|off,prealloc=on|off,size=size,host-nodes=host-
2981 nodes,policy=default|preferred|bind|interleave,seal=on|off,hugetlb=on|off,hugetlbsize=size
2982 Creates an anonymous memory file backend object, which allows
2983 QEMU to share the memory with an external process (e.g. when
2984 using vhost-user). The memory is allocated with memfd and
2985 optional sealing. (Linux only)
2986 The seal option creates a sealed-file, that will block further
2988 resizing the memory ('on' by default).
2989 The hugetlb option specify the file to be created resides in
2991 the hugetlbfs filesystem (since Linux 4.14). Used in
2992 conjunction with the hugetlb option, the hugetlbsize option
2993 specify the hugetlb page size on systems that support multiple
2994 hugetlb page sizes (it must be a power of 2 value supported by
2995 the system).
2996 In some versions of Linux, the hugetlb option is incompatible
2998 with the seal option (requires at least Linux 4.16).
2999 Please refer to memory-backend-file for a description of the
3001 other options.
3002 -object rng-random,id=id,filename=/dev/random
3004 Creates a random number generator backend which obtains entropy
3005 from a device on the host. The id parameter is a unique ID that
3006 will be used to reference this entropy backend from the virtio-
3007 rng device. The filename parameter specifies which file to
3008 obtain entropy from and if omitted defaults to /dev/random.
3009 -object rng-egd,id=id,chardev=chardevid
3011 Creates a random number generator backend which obtains entropy
3012 from an external daemon running on the host. The id parameter
3013 is a unique ID that will be used to reference this entropy
3014 backend from the virtio-rng device. The chardev parameter is
3015 the unique ID of a character device backend that provides the
3016 connection to the RNG daemon.
3017 -object
3019 tls-creds-anon,id=id,endpoint=endpoint,dir=/path/to/cred/dir,verify-peer=on|off
3020 Creates a TLS anonymous credentials object, which can be used
3021 to provide TLS support on network backends. The id parameter is
3022 a unique ID which network backends will use to access the
3023 credentials. The endpoint is either server or client depending
3024 on whether the QEMU network backend that uses the credentials
3025 will be acting as a client or as a server. If verify-peer is
3026 enabled (the default) then once the handshake is completed, the
3027 peer credentials will be verified, though this is a no-op for
3028 anonymous credentials.
3029 The dir parameter tells QEMU where to find the credential
3031 files. For server endpoints, this directory may contain a file
3032 dh-params.pem providing diffie-hellman parameters to use for
3033 the TLS server. If the file is missing, QEMU will generate a
3034 set of DH parameters at startup. This is a computationally
3035 expensive operation that consumes random pool entropy, so it is
3036 recommended that a persistent set of parameters be generated
3037 upfront and saved.
3038 -object
3040 tls-creds-psk,id=id,endpoint=endpoint,dir=/path/to/keys/dir[,username=username]
3041 Creates a TLS Pre-Shared Keys (PSK) credentials object, which
3042 can be used to provide TLS support on network backends. The id
3043 parameter is a unique ID which network backends will use to
3044 access the credentials. The endpoint is either server or client
3045 depending on whether the QEMU network backend that uses the
3046 credentials will be acting as a client or as a server. For
3047 clients only, username is the username which will be sent to
3048 the server. If omitted it defaults to "qemu".
3049 The dir parameter tells QEMU where to find the keys file. It
3051 is called "dir/keys.psk" and contains "username:key" pairs.
3052 This file can most easily be created using the GnuTLS "psktool"
3053 program.
3054 For server endpoints, dir may also contain a file dh-params.pem
3056 providing diffie-hellman parameters to use for the TLS server.
3057 If the file is missing, QEMU will generate a set of DH
3058 parameters at startup. This is a computationally expensive
3059 operation that consumes random pool entropy, so it is
3060 recommended that a persistent set of parameters be generated up
3061 front and saved.
3062 -object
3064 tls-creds-x509,id=id,endpoint=endpoint,dir=/path/to/cred/dir,priority=priority,verify-peer=on|off,passwordid=id
3065 Creates a TLS anonymous credentials object, which can be used
3066 to provide TLS support on network backends. The id parameter is
3067 a unique ID which network backends will use to access the
3068 credentials. The endpoint is either server or client depending
3069 on whether the QEMU network backend that uses the credentials
3070 will be acting as a client or as a server. If verify-peer is
3071 enabled (the default) then once the handshake is completed, the
3072 peer credentials will be verified. With x509 certificates, this
3073 implies that the clients must be provided with valid client
3074 certificates too.
3075 The dir parameter tells QEMU where to find the credential
3077 files. For server endpoints, this directory may contain a file
3078 dh-params.pem providing diffie-hellman parameters to use for
3079 the TLS server. If the file is missing, QEMU will generate a
3080 set of DH parameters at startup. This is a computationally
3081 expensive operation that consumes random pool entropy, so it is
3082 recommended that a persistent set of parameters be generated
3083 upfront and saved.
3084 For x509 certificate credentials the directory will contain
3086 further files providing the x509 certificates. The certificates
3087 must be stored in PEM format, in filenames ca-cert.pem,
3088 ca-crl.pem (optional), server-cert.pem (only servers),
3089 server-key.pem (only servers), client-cert.pem (only clients),
3090 and client-key.pem (only clients).
3091 For the server-key.pem and client-key.pem files which contain
3093 sensitive private keys, it is possible to use an encrypted
3094 version by providing the passwordid parameter. This provides
3095 the ID of a previously created "secret" object containing the
3096 password for decryption.
3097 The priority parameter allows to override the global default
3099 priority used by gnutls. This can be useful if the system
3100 administrator needs to use a weaker set of crypto priorities
3101 for QEMU without potentially forcing the weakness onto all
3102 applications. Or conversely if one wants wants a stronger
3103 default for QEMU than for all other applications, they can do
3104 this through this parameter. Its format is a gnutls priority
3105 string as described at
3106 <https://gnutls.org/manual/html_node/Priority-Strings.html>.
3107 -object
3109 filter-buffer,id=id,netdev=netdevid,interval=t[,queue=all|rx|tx][,status=on|off]
3110 Interval t can't be 0, this filter batches the packet delivery:
3111 all packets arriving in a given interval on netdev netdevid are
3112 delayed until the end of the interval. Interval is in
3113 microseconds. status is optional that indicate whether the
3114 netfilter is on (enabled) or off (disabled), the default status
3115 for netfilter will be 'on'.
3116 queue all|rx|tx is an option that can be applied to any
3118 netfilter.
3119 all: the filter is attached both to the receive and the
3121 transmit queue of the netdev (default).
3122 rx: the filter is attached to the receive queue of the netdev,
3124 where it will receive packets sent to the netdev.
3125 tx: the filter is attached to the transmit queue of the netdev,
3127 where it will receive packets sent by the netdev.
3128 -object
3130 filter-mirror,id=id,netdev=netdevid,outdev=chardevid,queue=all|rx|tx[,vnet_hdr_support]
3131 filter-mirror on netdev netdevid,mirror net packet to
3132 chardevchardevid, if it has the vnet_hdr_support flag, filter-
3133 mirror will mirror packet with vnet_hdr_len.
3134 -object
3136 filter-redirector,id=id,netdev=netdevid,indev=chardevid,outdev=chardevid,queue=all|rx|tx[,vnet_hdr_support]
3137 filter-redirector on netdev netdevid,redirect filter's net
3138 packet to chardev chardevid,and redirect indev's packet to
3139 filter.if it has the vnet_hdr_support flag, filter-redirector
3140 will redirect packet with vnet_hdr_len. Create a filter-
3141 redirector we need to differ outdev id from indev id, id can
3142 not be the same. we can just use indev or outdev, but at least
3143 one of indev or outdev need to be specified.
3144 -object
3146 filter-rewriter,id=id,netdev=netdevid,queue=all|rx|tx,[vnet_hdr_support]
3147 Filter-rewriter is a part of COLO project.It will rewrite tcp
3148 packet to secondary from primary to keep secondary tcp
3149 connection,and rewrite tcp packet to primary from secondary
3150 make tcp packet can be handled by client.if it has the
3151 vnet_hdr_support flag, we can parse packet with vnet header.
3152 usage: colo secondary: -object
3154 filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 -object
3155 filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 -object
3156 filter-rewriter,id=rew0,netdev=hn0,queue=all
3157 -object filter-dump,id=id,netdev=dev[,file=filename][,maxlen=len]
3159 Dump the network traffic on netdev dev to the file specified by
3160 filename. At most len bytes (64k by default) per packet are
3161 stored. The file format is libpcap, so it can be analyzed with
3162 tools such as tcpdump or Wireshark.
3163 -object
3165 colo-compare,id=id,primary_in=chardevid,secondary_in=chardevid,outdev=chardevid[,vnet_hdr_support]
3166 Colo-compare gets packet from primary_inchardevid and
3167 secondary_inchardevid, than compare primary packet with
3168 secondary packet. If the packets are same, we will output
3169 primary packet to outdevchardevid, else we will notify colo-
3170 frame do checkpoint and send primary packet to outdevchardevid.
3171 if it has the vnet_hdr_support flag, colo compare will
3172 send/recv packet with vnet_hdr_len.
3173 we must use it with the help of filter-mirror and filter-
3175 redirector.
3176 primary:
3178 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
3179 -device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
3180 -chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait
3181 -chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait
3182 -chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait
3183 -chardev socket,id=compare0-0,host=3.3.3.3,port=9001
3184 -chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait
3185 -chardev socket,id=compare_out0,host=3.3.3.3,port=9005
3186 -object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
3187 -object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
3188 -object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
3189 -object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0
3190 secondary:
3192 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
3193 -device e1000,netdev=hn0,mac=52:a4:00:12:78:66
3194 -chardev socket,id=red0,host=3.3.3.3,port=9003
3195 -chardev socket,id=red1,host=3.3.3.3,port=9004
3196 -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
3197 -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
3198 If you want to know the detail of above command line, you can
3200 read the colo-compare git log.
3201 -object cryptodev-backend-builtin,id=id[,queues=queues]
3203 Creates a cryptodev backend which executes crypto opreation
3204 from the QEMU cipher APIS. The id parameter is a unique ID that
3205 will be used to reference this cryptodev backend from the
3206 virtio-crypto device. The queues parameter is optional, which
3207 specify the queue number of cryptodev backend, the default of
3208 queues is 1.
3209 # qemu-system-x86_64 \
3211 [...] \
3212 -object cryptodev-backend-builtin,id=cryptodev0 \
3213 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
3214 [...]
3215 -object
3217 cryptodev-vhost-user,id=id,chardev=chardevid[,queues=queues]
3218 Creates a vhost-user cryptodev backend, backed by a chardev
3219 chardevid. The id parameter is a unique ID that will be used
3220 to reference this cryptodev backend from the virtio-crypto
3221 device. The chardev should be a unix domain socket backed one.
3222 The vhost-user uses a specifically defined protocol to pass
3223 vhost ioctl replacement messages to an application on the other
3224 end of the socket. The queues parameter is optional, which
3225 specify the queue number of cryptodev backend for multiqueue
3226 vhost-user, the default of queues is 1.
3227 # qemu-system-x86_64 \
3229 [...] \
3230 -chardev socket,id=chardev0,path=/path/to/socket \
3231 -object cryptodev-vhost-user,id=cryptodev0,chardev=chardev0 \
3232 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
3233 [...]
3234 -object
3236 secret,id=id,data=string,format=raw|base64[,keyid=secretid,iv=string]
3237 -object
3238 secret,id=id,file=filename,format=raw|base64[,keyid=secretid,iv=string]
3239 Defines a secret to store a password, encryption key, or some
3240 other sensitive data. The sensitive data can either be passed
3241 directly via the data parameter, or indirectly via the file
3242 parameter. Using the data parameter is insecure unless the
3243 sensitive data is encrypted.
3244 The sensitive data can be provided in raw format (the default),
3246 or base64. When encoded as JSON, the raw format only supports
3247 valid UTF-8 characters, so base64 is recommended for sending
3248 binary data. QEMU will convert from which ever format is
3249 provided to the format it needs internally. eg, an RBD password
3250 can be provided in raw format, even though it will be base64
3251 encoded when passed onto the RBD sever.
3252 For added protection, it is possible to encrypt the data
3254 associated with a secret using the AES-256-CBC cipher. Use of
3255 encryption is indicated by providing the keyid and iv
3256 parameters. The keyid parameter provides the ID of a previously
3257 defined secret that contains the AES-256 decryption key. This
3258 key should be 32-bytes long and be base64 encoded. The iv
3259 parameter provides the random initialization vector used for
3260 encryption of this particular secret and should be a base64
3261 encrypted string of the 16-byte IV.
3262 The simplest (insecure) usage is to provide the secret inline
3264 # $QEMU -object secret,id=sec0,data=letmein,format=raw
3266 The simplest secure usage is to provide the secret via a file
3268 # printf "letmein" > mypasswd.txt # $QEMU -object
3270 secret,id=sec0,file=mypasswd.txt,format=raw
3271 For greater security, AES-256-CBC should be used. To illustrate
3273 usage, consider the openssl command line tool which can encrypt
3274 the data. Note that when encrypting, the plaintext must be
3275 padded to the cipher block size (32 bytes) using the standard
3276 PKCS#5/6 compatible padding algorithm.
3277 First a master key needs to be created in base64 encoding:
3279 # openssl rand -base64 32 > key.b64
3281 # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"')
3282 Each secret to be encrypted needs to have a random
3284 initialization vector generated. These do not need to be kept
3285 secret
3286 # openssl rand -base64 16 > iv.b64
3288 # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"')
3289 The secret to be defined can now be encrypted, in this case
3291 we're telling openssl to base64 encode the result, but it could
3292 be left as raw bytes if desired.
3293 # SECRET=$(printf "letmein" |
3295 openssl enc -aes-256-cbc -a -K $KEY -iv $IV)
3296 When launching QEMU, create a master secret pointing to
3298 "key.b64" and specify that to be used to decrypt the user
3299 password. Pass the contents of "iv.b64" to the second secret
3300 # $QEMU \
3302 -object secret,id=secmaster0,format=base64,file=key.b64 \
3303 -object secret,id=sec0,keyid=secmaster0,format=base64,\
3304 data=$SECRET,iv=$(<iv.b64)
3305 -object
3307 sev-guest,id=id,cbitpos=cbitpos,reduced-phys-bits=val,[sev-device=string,policy=policy,handle=handle,dh-cert-file=file,session-file=file]
3308 Create a Secure Encrypted Virtualization (SEV) guest object,
3309 which can be used to provide the guest memory encryption
3310 support on AMD processors.
3311 When memory encryption is enabled, one of the physical address
3313 bit (aka the C-bit) is utilized to mark if a memory page is
3314 protected. The cbitpos is used to provide the C-bit position.
3315 The C-bit position is Host family dependent hence user must
3316 provide this value. On EPYC, the value should be 47.
3317 When memory encryption is enabled, we loose certain bits in
3319 physical address space. The reduced-phys-bits is used to
3320 provide the number of bits we loose in physical address space.
3321 Similar to C-bit, the value is Host family dependent. On EPYC,
3322 the value should be 5.
3323 The sev-device provides the device file to use for
3325 communicating with the SEV firmware running inside AMD Secure
3326 Processor. The default device is '/dev/sev'. If hardware
3327 supports memory encryption then /dev/sev devices are created by
3328 CCP driver.
3329 The policy provides the guest policy to be enforced by the SEV
3331 firmware and restrict what configuration and operational
3332 commands can be performed on this guest by the hypervisor. The
3333 policy should be provided by the guest owner and is bound to
3334 the guest and cannot be changed throughout the lifetime of the
3335 guest. The default is 0.
3336 If guest policy allows sharing the key with another SEV guest
3338 then handle can be use to provide handle of the guest from
3339 which to share the key.
3340 The dh-cert-file and session-file provides the guest owner's
3342 Public Diffie-Hillman key defined in SEV spec. The PDH and
3343 session parameters are used for establishing a cryptographic
3344 session with the guest owner to negotiate keys used for
3345 attestation. The file must be encoded in base64.
3346 e.g to launch a SEV guest
3348 # $QEMU \
3350 ......
3351 -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=5 \
3352 -machine ...,memory-encryption=sev0
3353 .....
3354 During the graphical emulation, you can use special key combinations to
3356 change modes. The default key mappings are shown below, but if you use
3357 "-alt-grab" then the modifier is Ctrl-Alt-Shift (instead of Ctrl-Alt)
3358 and if you use "-ctrl-grab" then the modifier is the right Ctrl key
3359 (instead of Ctrl-Alt):
3360 Ctrl-Alt-f
3362 Toggle full screen
3363 Ctrl-Alt-+
3365 Enlarge the screen
3366 Ctrl-Alt--
3368 Shrink the screen
3369 Ctrl-Alt-u
3371 Restore the screen's un-scaled dimensions
3372 Ctrl-Alt-n
3374 Switch to virtual console 'n'. Standard console mappings are:
3375 1 Target system display
3377 2 Monitor
3379 3 Serial port
3381 Ctrl-Alt
3383 Toggle mouse and keyboard grab.
3384 In the virtual consoles, you can use Ctrl-Up, Ctrl-Down, Ctrl-PageUp
3386 and Ctrl-PageDown to move in the back log.
3387 During emulation, if you are using a character backend multiplexer
3389 (which is the default if you are using -nographic) then several
3390 commands are available via an escape sequence. These key sequences all
3391 start with an escape character, which is Ctrl-a by default, but can be
3392 changed with -echr. The list below assumes you're using the default.
3393 Ctrl-a h
3395 Print this help
3396 Ctrl-a x
3398 Exit emulator
3399 Ctrl-a s
3401 Save disk data back to file (if -snapshot)
3402 Ctrl-a t
3404 Toggle console timestamps
3405 Ctrl-a b
3407 Send break (magic sysrq in Linux)
3408 Ctrl-a c
3410 Rotate between the frontends connected to the multiplexer (usually
3411 this switches between the monitor and the console)
3412 Ctrl-a Ctrl-a
3414 Send the escape character to the frontend
3415 The following options are specific to the PowerPC emulation:
3417 -g WxH[xDEPTH]
3419 Set the initial VGA graphic mode. The default is 800x600x32.
3420 -prom-env string
3422 Set OpenBIOS variables in NVRAM, for example:
3423 qemu-system-ppc -prom-env 'auto-boot?=false' \
3425 -prom-env 'boot-device=hd:2,\yaboot' \
3426 -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
3427 These variables are not used by Open Hack'Ware.
3429 The following options are specific to the Sparc32 emulation:
3431 -g WxHx[xDEPTH]
3433 Set the initial graphics mode. For TCX, the default is 1024x768x8
3434 with the option of 1024x768x24. For cgthree, the default is
3435 1024x768x8 with the option of 1152x900x8 for people who wish to use
3436 OBP.
3437 -prom-env string
3439 Set OpenBIOS variables in NVRAM, for example:
3440 qemu-system-sparc -prom-env 'auto-boot?=false' \
3442 -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
3443 -M [SS-4|SS-5|SS-10|SS-20|SS-600MP|LX|Voyager|SPARCClassic]
3445 [|SPARCbook]
3446 Set the emulated machine type. Default is SS-5.
3447 The following options are specific to the Sparc64 emulation:
3449 -prom-env string
3451 Set OpenBIOS variables in NVRAM, for example:
3452 qemu-system-sparc64 -prom-env 'auto-boot?=false'
3454 -M [sun4u|sun4v|niagara]
3456 Set the emulated machine type. The default is sun4u.
3457 The following options are specific to the ARM emulation:
3459 -semihosting
3461 Enable semihosting syscall emulation.
3462 On ARM this implements the "Angel" interface.
3464 Note that this allows guest direct access to the host filesystem,
3466 so should only be used with trusted guest OS.
3467 The following options are specific to the ColdFire emulation:
3469 -semihosting
3471 Enable semihosting syscall emulation.
3472 On M68K this implements the "ColdFire GDB" interface used by
3474 libgloss.
3475 Note that this allows guest direct access to the host filesystem,
3477 so should only be used with trusted guest OS.
3478 The following options are specific to the Xtensa emulation:
3480 -semihosting
3482 Enable semihosting syscall emulation.
3483 Xtensa semihosting provides basic file IO calls, such as
3485 open/read/write/seek/select. Tensilica baremetal libc for ISS and
3486 linux platform "sim" use this interface.
3487 Note that this allows guest direct access to the host filesystem,
3489 so should only be used with trusted guest OS.
3490
3492 In addition to using normal file images for the emulated storage
3493 devices, QEMU can also use networked resources such as iSCSI devices.
3494 These are specified using a special URL syntax.
3495 iSCSI
3497 iSCSI support allows QEMU to access iSCSI resources directly and
3498 use as images for the guest storage. Both disk and cdrom images are
3499 supported.
3500 Syntax for specifying iSCSI LUNs is
3502 "iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>"
3503 By default qemu will use the iSCSI initiator-name
3505 'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from
3506 the command line or a configuration file.
3507 Since version Qemu 2.4 it is possible to specify a iSCSI request
3509 timeout to detect stalled requests and force a reestablishment of
3510 the session. The timeout is specified in seconds. The default is 0
3511 which means no timeout. Libiscsi 1.15.0 or greater is required for
3512 this feature.
3513 Example (without authentication):
3515 qemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
3517 -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
3518 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
3519 Example (CHAP username/password via URL):
3521 qemu-system-i386 -drive file=iscsi://user%password@192.0.2.1/iqn.2001-04.com.example/1
3523 Example (CHAP username/password via environment variables):
3525 LIBISCSI_CHAP_USERNAME="user" \
3527 LIBISCSI_CHAP_PASSWORD="password" \
3528 qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
3529 NBD QEMU supports NBD (Network Block Devices) both using TCP protocol
3531 as well as Unix Domain Sockets.
3532 Syntax for specifying a NBD device using TCP
3534 "nbd:<server-ip>:<port>[:exportname=<export>]"
3535 Syntax for specifying a NBD device using Unix Domain Sockets
3537 "nbd:unix:<domain-socket>[:exportname=<export>]"
3538 Example for TCP
3540 qemu-system-i386 --drive file=nbd:192.0.2.1:30000
3542 Example for Unix Domain Sockets
3544 qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket
3546 SSH QEMU supports SSH (Secure Shell) access to remote disks.
3548 Examples:
3550 qemu-system-i386 -drive file=ssh://user@host/path/to/disk.img
3552 qemu-system-i386 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
3553 Currently authentication must be done using ssh-agent. Other
3555 authentication methods may be supported in future.
3556 Sheepdog
3558 Sheepdog is a distributed storage system for QEMU. QEMU supports
3559 using either local sheepdog devices or remote networked devices.
3560 Syntax for specifying a sheepdog device
3562 sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
3564 Example
3566 qemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
3568 See also <https://sheepdog.github.io/sheepdog/>.
3570 GlusterFS
3572 GlusterFS is a user space distributed file system. QEMU supports
3573 the use of GlusterFS volumes for hosting VM disk images using TCP,
3574 Unix Domain Sockets and RDMA transport protocols.
3575 Syntax for specifying a VM disk image on GlusterFS volume is
3577 URI:
3579 gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
3580 JSON:
3582 'json:{"driver":"qcow2","file":{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...",
3583 "server":[{"type":"tcp","host":"...","port":"..."},
3584 {"type":"unix","socket":"..."}]}}'
3585 Example
3587 URI:
3589 qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img,
3590 file.debug=9,file.logfile=/var/log/qemu-gluster.log
3591 JSON:
3593 qemu-system-x86_64 'json:{"driver":"qcow2",
3594 "file":{"driver":"gluster",
3595 "volume":"testvol","path":"a.img",
3596 "debug":9,"logfile":"/var/log/qemu-gluster.log",
3597 "server":[{"type":"tcp","host":"1.2.3.4","port":24007},
3598 {"type":"unix","socket":"/var/run/glusterd.socket"}]}}'
3599 qemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
3600 file.debug=9,file.logfile=/var/log/qemu-gluster.log,
3601 file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
3602 file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
3603 See also <http://www.gluster.org>.
3605 HTTP/HTTPS/FTP/FTPS
3607 QEMU supports read-only access to files accessed over http(s) and
3608 ftp(s).
3609 Syntax using a single filename:
3611 <protocol>://[<username>[:<password>]@]<host>/<path>
3613 where:
3615 protocol
3617 'http', 'https', 'ftp', or 'ftps'.
3618 username
3620 Optional username for authentication to the remote server.
3621 password
3623 Optional password for authentication to the remote server.
3624 host
3626 Address of the remote server.
3627 path
3629 Path on the remote server, including any query string.
3630 The following options are also supported:
3632 url The full URL when passing options to the driver explicitly.
3634 readahead
3636 The amount of data to read ahead with each range request to the
3637 remote server. This value may optionally have the suffix 'T',
3638 'G', 'M', 'K', 'k' or 'b'. If it does not have a suffix, it
3639 will be assumed to be in bytes. The value must be a multiple of
3640 512 bytes. It defaults to 256k.
3641 sslverify
3643 Whether to verify the remote server's certificate when
3644 connecting over SSL. It can have the value 'on' or 'off'. It
3645 defaults to 'on'.
3646 cookie
3648 Send this cookie (it can also be a list of cookies separated by
3649 ';') with each outgoing request. Only supported when using
3650 protocols such as HTTP which support cookies, otherwise
3651 ignored.
3652 timeout
3654 Set the timeout in seconds of the CURL connection. This timeout
3655 is the time that CURL waits for a response from the remote
3656 server to get the size of the image to be downloaded. If not
3657 set, the default timeout of 5 seconds is used.
3658 Note that when passing options to qemu explicitly, driver is the
3660 value of <protocol>.
3661 Example: boot from a remote Fedora 20 live ISO image
3663 qemu-system-x86_64 --drive media=cdrom,file=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
3665 qemu-system-x86_64 --drive media=cdrom,file.driver=http,file.url=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
3667 Example: boot from a remote Fedora 20 cloud image using a local
3669 overlay for writes, copy-on-read, and a readahead of 64k
3670 qemu-img create -f qcow2 -o backing_file='json:{"file.driver":"http",, "file.url":"https://dl.fedoraproject.org/pub/fedora/linux/releases/20/Images/x86_64/Fedora-x86_64-20-20131211.1-sda.qcow2",, "file.readahead":"64k"}' /tmp/Fedora-x86_64-20-20131211.1-sda.qcow2
3672 qemu-system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
3674 Example: boot from an image stored on a VMware vSphere server with
3676 a self-signed certificate using a local overlay for writes, a
3677 readahead of 64k and a timeout of 10 seconds.
3678 qemu-img create -f qcow2 -o backing_file='json:{"file.driver":"https",, "file.url":"https://user:password@vsphere.example.com/folder/test/test-flat.vmdk?dcPath=Datacenter&dsName=datastore1",, "file.sslverify":"off",, "file.readahead":"64k",, "file.timeout":10}' /tmp/test.qcow2
3680 qemu-system-x86_64 -drive file=/tmp/test.qcow2
3682
3684 The HTML documentation of QEMU for more precise information and Linux
3685 user mode emulator invocation.
3686
3688 Fabrice Bellard
3689 2019-05-14 QEMU.1(1)