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