1QEMU(1) QEMU QEMU(1)
2
6 qemu - QEMU User Documentation
7
9 qemu-system-x86_64 [options] [disk_image]
10
12 The QEMU PC System emulator simulates the following peripherals:
13 • i440FX host PCI bridge and PIIX3 PCI to ISA bridge
15 • Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA ex‐
17 tensions (hardware level, including all non standard modes).
18 • PS/2 mouse and keyboard
20 • 2 PCI IDE interfaces with hard disk and CD-ROM support
22 • Floppy disk
24 • PCI and ISA network adapters
26 • Serial ports
28 • IPMI BMC, either and internal or external one
30 • Creative SoundBlaster 16 sound card
32 • ENSONIQ AudioPCI ES1370 sound card
34 • Intel 82801AA AC97 Audio compatible sound card
36 • Intel HD Audio Controller and HDA codec
38 • Adlib (OPL2) - Yamaha YM3812 compatible chip
40 • Gravis Ultrasound GF1 sound card
42 • CS4231A compatible sound card
44 • PC speaker
46 • PCI UHCI, OHCI, EHCI or XHCI USB controller and a virtual USB-1.1
48 hub.
49 SMP is supported with up to 255 CPUs.
51 QEMU uses the PC BIOS from the Seabios project and the Plex86/Bochs
53 LGPL VGA BIOS.
54 QEMU uses YM3812 emulation by Tatsuyuki Satoh.
56 QEMU uses GUS emulation (GUSEMU32 http://www.deinmeister.de/gusemu/) by
58 Tibor "TS" Schütz.
59 Note that, by default, GUS shares IRQ(7) with parallel ports and so
61 QEMU must be told to not have parallel ports to have working GUS.
62 qemu-system-x86_64 dos.img -device gus -parallel none
64 Alternatively:
66 qemu-system-x86_64 dos.img -device gus,irq=5
68 Or some other unclaimed IRQ.
70 CS4231A is the chip used in Windows Sound System and GUSMAX products
72 The PC speaker audio device can be configured using the pcspk-audiodev
74 machine property, i.e.
75 qemu-system-x86_64 some.img -audiodev <backend>,id=<name> -machine pcspk-audiodev=<name>
77
79 disk_image is a raw hard disk image for IDE hard disk 0. Some targets
80 do not need a disk image.
81 Standard options
83 -h Display help and exit
84 -version
86 Display version information and exit
87 -machine [type=]name[,prop=value[,...]]
89 Select the emulated machine by name. Use -machine help to list
90 available machines.
91 For architectures which aim to support live migration compati‐
93 bility across releases, each release will introduce a new ver‐
94 sioned machine type. For example, the 2.8.0 release introduced
95 machine types "pc-i440fx-2.8" and "pc-q35-2.8" for the
96 x86_64/i686 architectures.
97 To allow live migration of guests from QEMU version 2.8.0, to
99 QEMU version 2.9.0, the 2.9.0 version must support the
100 "pc-i440fx-2.8" and "pc-q35-2.8" machines too. To allow users
101 live migrating VMs to skip multiple intermediate releases when
102 upgrading, new releases of QEMU will support machine types from
103 many previous versions.
104 Supported machine properties are:
106 accel=accels1[:accels2[:...]]
108 This is used to enable an accelerator. Depending on the
109 target architecture, kvm, xen, hax, hvf, nvmm, whpx or
110 tcg can be available. By default, tcg is used. If there
111 is more than one accelerator specified, the next one is
112 used if the previous one fails to initialize.
113 vmport=on|off|auto
115 Enables emulation of VMWare IO port, for vmmouse etc.
116 auto says to select the value based on accel. For ac‐
117 cel=xen the default is off otherwise the default is on.
118 dump-guest-core=on|off
120 Include guest memory in a core dump. The default is on.
121 mem-merge=on|off
123 Enables or disables memory merge support. This feature,
124 when supported by the host, de-duplicates identical mem‐
125 ory pages among VMs instances (enabled by default).
126 aes-key-wrap=on|off
128 Enables or disables AES key wrapping support on s390-ccw
129 hosts. This feature controls whether AES wrapping keys
130 will be created to allow execution of AES cryptographic
131 functions. The default is on.
132 dea-key-wrap=on|off
134 Enables or disables DEA key wrapping support on s390-ccw
135 hosts. This feature controls whether DEA wrapping keys
136 will be created to allow execution of DEA cryptographic
137 functions. The default is on.
138 nvdimm=on|off
140 Enables or disables NVDIMM support. The default is off.
141 memory-encryption=
143 Memory encryption object to use. The default is none.
144 hmat=on|off
146 Enables or disables ACPI Heterogeneous Memory Attribute
147 Table (HMAT) support. The default is off.
148 memory-backend='id'
150 An alternative to legacy -mem-path and mem-prealloc op‐
151 tions. Allows to use a memory backend as main RAM.
152 For example:
154 -object memory-backend-file,id=pc.ram,size=512M,mem-path=/hugetlbfs,prealloc=on,share=on
156 -machine memory-backend=pc.ram
157 -m 512M
158 Migration compatibility note:
160 • as backend id one shall use value of 'default-ram-id',
162 advertised by machine type (available via query-ma‐
163 chines QMP command), if migration to/from old QEMU
164 (<5.0) is expected.
165 • for machine types 4.0 and older, user shall use
167 x-use-canonical-path-for-ramblock-id=off backend option
168 if migration to/from old QEMU (<5.0) is expected.
169 For example:
171 -object memory-backend-ram,id=pc.ram,size=512M,x-use-canonical-path-for-ramblock-id=off
173 -machine memory-backend=pc.ram
174 -m 512M
175 sgx-epc.0.memdev=@var{memid}
177 Define an SGX EPC section.
178 -cpu model
180 Select CPU model (-cpu help for list and additional feature se‐
181 lection)
182 -accel name[,prop=value[,...]]
184 This is used to enable an accelerator. Depending on the target
185 architecture, kvm, xen, hax, hvf, nvmm, whpx or tcg can be
186 available. By default, tcg is used. If there is more than one
187 accelerator specified, the next one is used if the previous one
188 fails to initialize.
189 igd-passthru=on|off
191 When Xen is in use, this option controls whether Intel
192 integrated graphics devices can be passed through to the
193 guest (default=off)
194 kernel-irqchip=on|off|split
196 Controls KVM in-kernel irqchip support. The default is
197 full acceleration of the interrupt controllers. On x86,
198 split irqchip reduces the kernel attack surface, at a
199 performance cost for non-MSI interrupts. Disabling the
200 in-kernel irqchip completely is not recommended except
201 for debugging purposes.
202 kvm-shadow-mem=size
204 Defines the size of the KVM shadow MMU.
205 split-wx=on|off
207 Controls the use of split w^x mapping for the TCG code
208 generation buffer. Some operating systems require this to
209 be enabled, and in such a case this will default on. On
210 other operating systems, this will default off, but one
211 may enable this for testing or debugging.
212 tb-size=n
214 Controls the size (in MiB) of the TCG translation block
215 cache.
216 thread=single|multi
218 Controls number of TCG threads. When the TCG is
219 multi-threaded there will be one thread per vCPU there‐
220 fore taking advantage of additional host cores. The de‐
221 fault is to enable multi-threading where both the
222 back-end and front-ends support it and no incompatible
223 TCG features have been enabled (e.g. icount/replay).
224 dirty-ring-size=n
226 When the KVM accelerator is used, it controls the size of
227 the per-vCPU dirty page ring buffer (number of entries
228 for each vCPU). It should be a value that is power of
229 two, and it should be 1024 or bigger (but still less than
230 the maximum value that the kernel supports). 4096 could
231 be a good initial value if you have no idea which is the
232 best. Set this value to 0 to disable the feature. By
233 default, this feature is disabled (dirty-ring-size=0).
234 When enabled, KVM will instead record dirty pages in a
235 bitmap.
236 -smp [[cpus=]n][,maxcpus=maxcpus][,sockets=sock‐
238 ets][,dies=dies][,cores=cores][,threads=threads]
239 Simulate a SMP system with 'n' CPUs initially present on the ma‐
240 chine type board. On boards supporting CPU hotplug, the optional
241 'maxcpus' parameter can be set to enable further CPUs to be
242 added at runtime. When both parameters are omitted, the maximum
243 number of CPUs will be calculated from the provided topology
244 members and the initial CPU count will match the maximum number.
245 When only one of them is given then the omitted one will be set
246 to its counterpart's value. Both parameters may be specified,
247 but the maximum number of CPUs must be equal to or greater than
248 the initial CPU count. Both parameters are subject to an upper
249 limit that is determined by the specific machine type chosen.
250 To control reporting of CPU topology information, the number of
252 sockets, dies per socket, cores per die, and threads per core
253 can be specified. The sum `` sockets * cores * dies * threads
254 `` must be equal to the maximum CPU count. CPU targets may only
255 support a subset of the topology parameters. Where a CPU target
256 does not support use of a particular topology parameter, its
257 value should be assumed to be 1 for the purpose of computing the
258 CPU maximum count.
259 Either the initial CPU count, or at least one of the topology
261 parameters must be specified. The specified parameters must be
262 greater than zero, explicit configuration like "cpus=0" is not
263 allowed. Values for any omitted parameters will be computed from
264 those which are given. Historically preference was given to the
265 coarsest topology parameters when computing missing values (ie
266 sockets preferred over cores, which were preferred over
267 threads), however, this behaviour is considered liable to
268 change. Prior to 6.2 the preference was sockets over cores over
269 threads. Since 6.2 the preference is cores over sockets over
270 threads.
271 -numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initia‐
273 tor=initiator]
274 -numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initia‐
277 tor=initiator]
278 -numa dist,src=source,dst=destination,val=distance
281 -numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]
284 -numa hmat-lb,initiator=node,target=node,hierarchy=hierar‐
287 chy,data-type=tpye[,latency=lat][,bandwidth=bw]
288 -numa hmat-cache,node-id=node,size=size,level=level[,associativ‐
291 ity=str][,policy=str][,line=size]
292 Define a NUMA node and assign RAM and VCPUs to it. Set the NUMA
293 distance from a source node to a destination node. Set the ACPI
294 Heterogeneous Memory Attributes for the given nodes.
295 Legacy VCPU assignment uses 'cpus' option where firstcpu and
297 lastcpu are CPU indexes. Each 'cpus' option represent a contigu‐
298 ous range of CPU indexes (or a single VCPU if lastcpu is omit‐
299 ted). A non-contiguous set of VCPUs can be represented by pro‐
300 viding multiple 'cpus' options. If 'cpus' is omitted on all
301 nodes, VCPUs are automatically split between them.
302 For example, the following option assigns VCPUs 0, 1, 2 and 5 to
304 a NUMA node:
305 -numa node,cpus=0-2,cpus=5
307 'cpu' option is a new alternative to 'cpus' option which uses
309 'socket-id|core-id|thread-id' properties to assign CPU objects
310 to a node using topology layout properties of CPU. The set of
311 properties is machine specific, and depends on used machine
312 type/'smp' options. It could be queried with 'hotpluggable-cpus'
313 monitor command. 'node-id' property specifies node to which CPU
314 object will be assigned, it's required for node to be declared
315 with 'node' option before it's used with 'cpu' option.
316 For example:
318 -M pc \
320 -smp 1,sockets=2,maxcpus=2 \
321 -numa node,nodeid=0 -numa node,nodeid=1 \
322 -numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1
323 Legacy 'mem' assigns a given RAM amount to a node (not supported
325 for 5.1 and newer machine types). 'memdev' assigns RAM from a
326 given memory backend device to a node. If 'mem' and 'memdev' are
327 omitted in all nodes, RAM is split equally between them.
328 'mem' and 'memdev' are mutually exclusive. Furthermore, if one
330 node uses 'memdev', all of them have to use it.
331 'initiator' is an additional option that points to an initiator
333 NUMA node that has best performance (the lowest latency or
334 largest bandwidth) to this NUMA node. Note that this option can
335 be set only when the machine property 'hmat' is set to 'on'.
336 Following example creates a machine with 2 NUMA nodes, node 0
338 has CPU. node 1 has only memory, and its initiator is node 0.
339 Note that because node 0 has CPU, by default the initiator of
340 node 0 is itself and must be itself.
341 -machine hmat=on \
343 -m 2G,slots=2,maxmem=4G \
344 -object memory-backend-ram,size=1G,id=m0 \
345 -object memory-backend-ram,size=1G,id=m1 \
346 -numa node,nodeid=0,memdev=m0 \
347 -numa node,nodeid=1,memdev=m1,initiator=0 \
348 -smp 2,sockets=2,maxcpus=2 \
349 -numa cpu,node-id=0,socket-id=0 \
350 -numa cpu,node-id=0,socket-id=1
351 source and destination are NUMA node IDs. distance is the NUMA
353 distance from source to destination. The distance from a node to
354 itself is always 10. If any pair of nodes is given a distance,
355 then all pairs must be given distances. Although, when distances
356 are only given in one direction for each pair of nodes, then the
357 distances in the opposite directions are assumed to be the same.
358 If, however, an asymmetrical pair of distances is given for even
359 one node pair, then all node pairs must be provided distance
360 values for both directions, even when they are symmetrical. When
361 a node is unreachable from another node, set the pair's distance
362 to 255.
363 Note that the -numa option doesn't allocate any of the specified
365 resources, it just assigns existing resources to NUMA nodes.
366 This means that one still has to use the -m, -smp options to al‐
367 locate RAM and VCPUs respectively.
368 Use 'hmat-lb' to set System Locality Latency and Bandwidth In‐
370 formation between initiator and target NUMA nodes in ACPI Het‐
371 erogeneous Attribute Memory Table (HMAT). Initiator NUMA node
372 can create memory requests, usually it has one or more proces‐
373 sors. Target NUMA node contains addressable memory.
374 In 'hmat-lb' option, node are NUMA node IDs. hierarchy is the
376 memory hierarchy of the target NUMA node: if hierarchy is 'mem‐
377 ory', the structure represents the memory performance; if hier‐
378 archy is 'first-level|second-level|third-level', this structure
379 represents aggregated performance of memory side caches for each
380 domain. type of 'data-type' is type of data represented by this
381 structure instance: if 'hierarchy' is 'memory', 'data-type' is
382 'access|read|write' latency or 'access|read|write' bandwidth of
383 the target memory; if 'hierarchy' is 'first-level|sec‐
384 ond-level|third-level', 'data-type' is 'access|read|write' hit
385 latency or 'access|read|write' hit bandwidth of the target mem‐
386 ory side cache.
387 lat is latency value in nanoseconds. bw is bandwidth value, the
389 possible value and units are NUM[M|G|T], mean that the bandwidth
390 value are NUM byte per second (or MB/s, GB/s or TB/s depending
391 on used suffix). Note that if latency or bandwidth value is 0,
392 means the corresponding latency or bandwidth information is not
393 provided.
394 In 'hmat-cache' option, node-id is the NUMA-id of the memory be‐
396 longs. size is the size of memory side cache in bytes. level is
397 the cache level described in this structure, note that the cache
398 level 0 should not be used with 'hmat-cache' option. associa‐
399 tivity is the cache associativity, the possible value is
400 'none/direct(direct-mapped)/complex(complex cache indexing)'.
401 policy is the write policy. line is the cache Line size in
402 bytes.
403 For example, the following options describe 2 NUMA nodes. Node 0
405 has 2 cpus and a ram, node 1 has only a ram. The processors in
406 node 0 access memory in node 0 with access-latency 5 nanosec‐
407 onds, access-bandwidth is 200 MB/s; The processors in NUMA node
408 0 access memory in NUMA node 1 with access-latency 10 nanosec‐
409 onds, access-bandwidth is 100 MB/s. And for memory side cache
410 information, NUMA node 0 and 1 both have 1 level memory cache,
411 size is 10KB, policy is write-back, the cache Line size is 8
412 bytes:
413 -machine hmat=on \
415 -m 2G \
416 -object memory-backend-ram,size=1G,id=m0 \
417 -object memory-backend-ram,size=1G,id=m1 \
418 -smp 2,sockets=2,maxcpus=2 \
419 -numa node,nodeid=0,memdev=m0 \
420 -numa node,nodeid=1,memdev=m1,initiator=0 \
421 -numa cpu,node-id=0,socket-id=0 \
422 -numa cpu,node-id=0,socket-id=1 \
423 -numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-latency,latency=5 \
424 -numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-bandwidth,bandwidth=200M \
425 -numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-latency,latency=10 \
426 -numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-bandwidth,bandwidth=100M \
427 -numa hmat-cache,node-id=0,size=10K,level=1,associativity=direct,policy=write-back,line=8 \
428 -numa hmat-cache,node-id=1,size=10K,level=1,associativity=direct,policy=write-back,line=8
429 -add-fd fd=fd,set=set[,opaque=opaque]
431 Add a file descriptor to an fd set. Valid options are:
432 fd=fd This option defines the file descriptor of which a dupli‐
434 cate is added to fd set. The file descriptor cannot be
435 stdin, stdout, or stderr.
436 set=set
438 This option defines the ID of the fd set to add the file
439 descriptor to.
440 opaque=opaque
442 This option defines a free-form string that can be used
443 to describe fd.
444 You can open an image using pre-opened file descriptors from an
446 fd set:
447 qemu-system-x86_64 \
449 -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \
450 -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \
451 -drive file=/dev/fdset/2,index=0,media=disk
452 -set group.id.arg=value
454 Set parameter arg for item id of type group
455 -global driver.prop=value
457 -global driver=driver,property=property,value=value
460 Set default value of driver's property prop to value, e.g.:
461 qemu-system-x86_64 -global ide-hd.physical_block_size=4096 disk-image.img
463 In particular, you can use this to set driver properties for de‐
465 vices which are created automatically by the machine model. To
466 create a device which is not created automatically and set prop‐
467 erties on it, use -device.
468 -global driver.prop=value is shorthand for -global
470 driver=driver,property=prop,value=value. The longhand syntax
471 works even when driver contains a dot.
472 -boot [or‐
474 der=drives][,once=drives][,menu=on|off][,splash=sp_name][,splash-time=sp_time][,re‐
475 boot-timeout=rb_timeout][,strict=on|off]
476 Specify boot order drives as a string of drive letters. Valid
477 drive letters depend on the target architecture. The x86 PC
478 uses: a, b (floppy 1 and 2), c (first hard disk), d (first
479 CD-ROM), n-p (Etherboot from network adapter 1-4), hard disk
480 boot is the default. To apply a particular boot order only on
481 the first startup, specify it via once. Note that the order or
482 once parameter should not be used together with the bootindex
483 property of devices, since the firmware implementations normally
484 do not support both at the same time.
485 Interactive boot menus/prompts can be enabled via menu=on as far
487 as firmware/BIOS supports them. The default is non-interactive
488 boot.
489 A splash picture could be passed to bios, enabling user to show
491 it as logo, when option splash=sp_name is given and menu=on, If
492 firmware/BIOS supports them. Currently Seabios for X86 system
493 support it. limitation: The splash file could be a jpeg file or
494 a BMP file in 24 BPP format(true color). The resolution should
495 be supported by the SVGA mode, so the recommended is 320x240,
496 640x480, 800x640.
497 A timeout could be passed to bios, guest will pause for rb_time‐
499 out ms when boot failed, then reboot. If rb_timeout is '-1',
500 guest will not reboot, qemu passes '-1' to bios by default. Cur‐
501 rently Seabios for X86 system support it.
502 Do strict boot via strict=on as far as firmware/BIOS supports
504 it. This only effects when boot priority is changed by bootindex
505 options. The default is non-strict boot.
506 # try to boot from network first, then from hard disk
508 qemu-system-x86_64 -boot order=nc
509 # boot from CD-ROM first, switch back to default order after reboot
510 qemu-system-x86_64 -boot once=d
511 # boot with a splash picture for 5 seconds.
512 qemu-system-x86_64 -boot menu=on,splash=/root/boot.bmp,splash-time=5000
513 Note: The legacy format '-boot drives' is still supported but
515 its use is discouraged as it may be removed from future ver‐
516 sions.
517 -m [size=]megs[,slots=n,maxmem=size]
519 Sets guest startup RAM size to megs megabytes. Default is 128
520 MiB. Optionally, a suffix of "M" or "G" can be used to signify
521 a value in megabytes or gigabytes respectively. Optional pair
522 slots, maxmem could be used to set amount of hotpluggable memory
523 slots and maximum amount of memory. Note that maxmem must be
524 aligned to the page size.
525 For example, the following command-line sets the guest startup
527 RAM size to 1GB, creates 3 slots to hotplug additional memory
528 and sets the maximum memory the guest can reach to 4GB:
529 qemu-system-x86_64 -m 1G,slots=3,maxmem=4G
531 If slots and maxmem are not specified, memory hotplug won't be
533 enabled and the guest startup RAM will never increase.
534 -mem-path path
536 Allocate guest RAM from a temporarily created file in path.
537 -mem-prealloc
539 Preallocate memory when using -mem-path.
540 -k language
542 Use keyboard layout language (for example fr for French). This
543 option is only needed where it is not easy to get raw PC key‐
544 codes (e.g. on Macs, with some X11 servers or with a VNC or
545 curses display). You don't normally need to use it on PC/Linux
546 or PC/Windows hosts.
547 The available layouts are:
549 ar de-ch es fo fr-ca hu ja mk no pt-br sv
551 da en-gb et fr fr-ch is lt nl pl ru th
552 de en-us fi fr-be hr it lv nl-be pt sl tr
553 The default is en-us.
555 -audio-help
557 Will show the -audiodev equivalent of the currently specified
558 (deprecated) environment variables.
559 -audiodev [driver=]driver,id=id[,prop[=value][,...]]
561 Adds a new audio backend driver identified by id. There are
562 global and driver specific properties. Some values can be set
563 differently for input and output, they're marked with in|out..
564 You can set the input's property with in.prop and the output's
565 property with out.prop. For example:
566 -audiodev alsa,id=example,in.frequency=44110,out.frequency=8000
568 -audiodev alsa,id=example,out.channels=1 # leaves in.channels unspecified
569 NOTE: parameter validation is known to be incomplete, in many
571 cases specifying an invalid option causes QEMU to print an error
572 message and continue emulation without sound.
573 Valid global options are:
575 id=identifier
577 Identifies the audio backend.
578 timer-period=period
580 Sets the timer period used by the audio subsystem in mi‐
581 croseconds. Default is 10000 (10 ms).
582 in|out.mixing-engine=on|off
584 Use QEMU's mixing engine to mix all streams inside QEMU
585 and convert audio formats when not supported by the back‐
586 end. When off, fixed-settings must be off too. Note that
587 disabling this option means that the selected backend
588 must support multiple streams and the audio formats used
589 by the virtual cards, otherwise you'll get no sound. It's
590 not recommended to disable this option unless you want to
591 use 5.1 or 7.1 audio, as mixing engine only supports mono
592 and stereo audio. Default is on.
593 in|out.fixed-settings=on|off
595 Use fixed settings for host audio. When off, it will
596 change based on how the guest opens the sound card. In
597 this case you must not specify frequency, channels or
598 format. Default is on.
599 in|out.frequency=frequency
601 Specify the frequency to use when using fixed-settings.
602 Default is 44100Hz.
603 in|out.channels=channels
605 Specify the number of channels to use when using
606 fixed-settings. Default is 2 (stereo).
607 in|out.format=format
609 Specify the sample format to use when using fixed-set‐
610 tings. Valid values are: s8, s16, s32, u8, u16, u32,
611 f32. Default is s16.
612 in|out.voices=voices
614 Specify the number of voices to use. Default is 1.
615 in|out.buffer-length=usecs
617 Sets the size of the buffer in microseconds.
618 -audiodev none,id=id[,prop[=value][,...]]
620 Creates a dummy backend that discards all outputs. This backend
621 has no backend specific properties.
622 -audiodev alsa,id=id[,prop[=value][,...]]
624 Creates backend using the ALSA. This backend is only available
625 on Linux.
626 ALSA specific options are:
628 in|out.dev=device
630 Specify the ALSA device to use for input and/or output.
631 Default is default.
632 in|out.period-length=usecs
634 Sets the period length in microseconds.
635 in|out.try-poll=on|off
637 Attempt to use poll mode with the device. Default is on.
638 threshold=threshold
640 Threshold (in microseconds) when playback starts. Default
641 is 0.
642 -audiodev coreaudio,id=id[,prop[=value][,...]]
644 Creates a backend using Apple's Core Audio. This backend is only
645 available on Mac OS and only supports playback.
646 Core Audio specific options are:
648 in|out.buffer-count=count
650 Sets the count of the buffers.
651 -audiodev dsound,id=id[,prop[=value][,...]]
653 Creates a backend using Microsoft's DirectSound. This backend is
654 only available on Windows and only supports playback.
655 DirectSound specific options are:
657 latency=usecs
659 Add extra usecs microseconds latency to playback. Default
660 is 10000 (10 ms).
661 -audiodev oss,id=id[,prop[=value][,...]]
663 Creates a backend using OSS. This backend is available on most
664 Unix-like systems.
665 OSS specific options are:
667 in|out.dev=device
669 Specify the file name of the OSS device to use. Default
670 is /dev/dsp.
671 in|out.buffer-count=count
673 Sets the count of the buffers.
674 in|out.try-poll=on|of
676 Attempt to use poll mode with the device. Default is on.
677 try-mmap=on|off
679 Try using memory mapped device access. Default is off.
680 exclusive=on|off
682 Open the device in exclusive mode (vmix won't work in
683 this case). Default is off.
684 dsp-policy=policy
686 Sets the timing policy (between 0 and 10, where smaller
687 number means smaller latency but higher CPU usage). Use
688 -1 to use buffer sizes specified by buffer and buf‐
689 fer-count. This option is ignored if you do not have OSS
690 4. Default is 5.
691 -audiodev pa,id=id[,prop[=value][,...]]
693 Creates a backend using PulseAudio. This backend is available on
694 most systems.
695 PulseAudio specific options are:
697 server=server
699 Sets the PulseAudio server to connect to.
700 in|out.name=sink
702 Use the specified source/sink for recording/playback.
703 in|out.latency=usecs
705 Desired latency in microseconds. The PulseAudio server
706 will try to honor this value but actual latencies may be
707 lower or higher.
708 -audiodev sdl,id=id[,prop[=value][,...]]
710 Creates a backend using SDL. This backend is available on most
711 systems, but you should use your platform's native backend if
712 possible.
713 SDL specific options are:
715 in|out.buffer-count=count
717 Sets the count of the buffers.
718 -audiodev spice,id=id[,prop[=value][,...]]
720 Creates a backend that sends audio through SPICE. This backend
721 requires -spice and automatically selected in that case, so usu‐
722 ally you can ignore this option. This backend has no backend
723 specific properties.
724 -audiodev wav,id=id[,prop[=value][,...]]
726 Creates a backend that writes audio to a WAV file.
727 Backend specific options are:
729 path=path
731 Write recorded audio into the specified file. Default is
732 qemu.wav.
733 -soundhw card1[,card2,...] or -soundhw all
735 Enable audio and selected sound hardware. Use 'help' to print
736 all available sound hardware. For example:
737 qemu-system-x86_64 -soundhw sb16,adlib disk.img
739 qemu-system-x86_64 -soundhw es1370 disk.img
740 qemu-system-x86_64 -soundhw ac97 disk.img
741 qemu-system-x86_64 -soundhw hda disk.img
742 qemu-system-x86_64 -soundhw all disk.img
743 qemu-system-x86_64 -soundhw help
744 Note that Linux's i810_audio OSS kernel (for AC97) module might
746 require manually specifying clocking.
747 modprobe i810_audio clocking=48000
749 -device driver[,prop[=value][,...]]
751 Add device driver. prop=value sets driver properties. Valid
752 properties depend on the driver. To get help on possible drivers
753 and properties, use -device help and -device driver,help.
754 Some drivers are:
756 -device ipmi-bmc-sim,id=id[,prop[=value][,...]]
758 Add an IPMI BMC. This is a simulation of a hardware management
759 interface processor that normally sits on a system. It provides
760 a watchdog and the ability to reset and power control the sys‐
761 tem. You need to connect this to an IPMI interface to make it
762 useful
763 The IPMI slave address to use for the BMC. The default is 0x20.
765 This address is the BMC's address on the I2C network of manage‐
766 ment controllers. If you don't know what this means, it is safe
767 to ignore it.
768 id=id The BMC id for interfaces to use this device.
770 slave_addr=val
772 Define slave address to use for the BMC. The default is
773 0x20.
774 sdrfile=file
776 file containing raw Sensor Data Records (SDR) data. The
777 default is none.
778 fruareasize=val
780 size of a Field Replaceable Unit (FRU) area. The default
781 is 1024.
782 frudatafile=file
784 file containing raw Field Replaceable Unit (FRU) inven‐
785 tory data. The default is none.
786 guid=uuid
788 value for the GUID for the BMC, in standard UUID format.
789 If this is set, get "Get GUID" command to the BMC will
790 return it. Otherwise "Get GUID" will return an error.
791 -device ipmi-bmc-extern,id=id,chardev=id[,slave_addr=val]
793 Add a connection to an external IPMI BMC simulator. Instead of
794 locally emulating the BMC like the above item, instead connect
795 to an external entity that provides the IPMI services.
796 A connection is made to an external BMC simulator. If you do
798 this, it is strongly recommended that you use the "reconnect="
799 chardev option to reconnect to the simulator if the connection
800 is lost. Note that if this is not used carefully, it can be a
801 security issue, as the interface has the ability to send resets,
802 NMIs, and power off the VM. It's best if QEMU makes a connection
803 to an external simulator running on a secure port on localhost,
804 so neither the simulator nor QEMU is exposed to any outside net‐
805 work.
806 See the "lanserv/README.vm" file in the OpenIPMI library for
808 more details on the external interface.
809 -device isa-ipmi-kcs,bmc=id[,ioport=val][,irq=val]
811 Add a KCS IPMI interafce on the ISA bus. This also adds a corre‐
812 sponding ACPI and SMBIOS entries, if appropriate.
813 bmc=id The BMC to connect to, one of ipmi-bmc-sim or
815 ipmi-bmc-extern above.
816 ioport=val
818 Define the I/O address of the interface. The default is
819 0xca0 for KCS.
820 irq=val
822 Define the interrupt to use. The default is 5. To disable
823 interrupts, set this to 0.
824 -device isa-ipmi-bt,bmc=id[,ioport=val][,irq=val]
826 Like the KCS interface, but defines a BT interface. The default
827 port is 0xe4 and the default interrupt is 5.
828 -device pci-ipmi-kcs,bmc=id
830 Add a KCS IPMI interafce on the PCI bus.
831 bmc=id The BMC to connect to, one of ipmi-bmc-sim or
833 ipmi-bmc-extern above.
834 -device pci-ipmi-bt,bmc=id
836 Like the KCS interface, but defines a BT interface on the PCI
837 bus.
838 -device intel-iommu[,option=...]
840 This is only supported by -machine q35, which will enable Intel
841 VT-d emulation within the guest. It supports below options:
842 intremap=on|off (default: auto)
844 This enables interrupt remapping feature. It's required
845 to enable complete x2apic. Currently it only supports
846 kvm kernel-irqchip modes off or split, while full ker‐
847 nel-irqchip is not yet supported. The default value is
848 "auto", which will be decided by the mode of ker‐
849 nel-irqchip.
850 caching-mode=on|off (default: off)
852 This enables caching mode for the VT-d emulated device.
853 When caching-mode is enabled, each guest DMA buffer map‐
854 ping will generate an IOTLB invalidation from the guest
855 IOMMU driver to the vIOMMU device in a synchronous way.
856 It is required for -device vfio-pci to work with the VT-d
857 device, because host assigned devices requires to setup
858 the DMA mapping on the host before guest DMA starts.
859 device-iotlb=on|off (default: off)
861 This enables device-iotlb capability for the emulated
862 VT-d device. So far virtio/vhost should be the only real
863 user for this parameter, paired with ats=on configured
864 for the device.
865 aw-bits=39|48 (default: 39)
867 This decides the address width of IOVA address space.
868 The address space has 39 bits width for 3-level IOMMU
869 page tables, and 48 bits for 4-level IOMMU page tables.
870 Please also refer to the wiki page for general scenarios of VT-d
872 emulation in QEMU: https://wiki.qemu.org/Features/VT-d.
873 -name name
875 Sets the name of the guest. This name will be displayed in the
876 SDL window caption. The name will also be used for the VNC
877 server. Also optionally set the top visible process name in
878 Linux. Naming of individual threads can also be enabled on Linux
879 to aid debugging.
880 -uuid uuid
882 Set system UUID.
883 Block device options
885 -fda file
886 -fdb file
889 Use file as floppy disk 0/1 image (see the disk images chapter
890 in the System Emulation Users Guide).
891 -hda file
893 -hdb file
896 -hdc file
899 -hdd file
902 Use file as hard disk 0, 1, 2 or 3 image (see the disk images
903 chapter in the System Emulation Users Guide).
904 -cdrom file
906 Use file as CD-ROM image (you cannot use -hdc and -cdrom at the
907 same time). You can use the host CD-ROM by using /dev/cdrom as
908 filename.
909 -blockdev option[,option[,option[,...]]]
911 Define a new block driver node. Some of the options apply to all
912 block drivers, other options are only accepted for a specific
913 block driver. See below for a list of generic options and op‐
914 tions for the most common block drivers.
915 Options that expect a reference to another node (e.g. file) can
917 be given in two ways. Either you specify the node name of an al‐
918 ready existing node (file=node-name), or you define a new node
919 inline, adding options for the referenced node after a dot
920 (file.filename=path,file.aio=native).
921 A block driver node created with -blockdev can be used for a
923 guest device by specifying its node name for the drive property
924 in a -device argument that defines a block device.
925 Valid options for any block driver node:
927 driver Specifies the block driver to use for the given
929 node.
930 node-name
932 This defines the name of the block driver node by
933 which it will be referenced later. The name must
934 be unique, i.e. it must not match the name of a
935 different block driver node, or (if you use -drive
936 as well) the ID of a drive.
937 If no node name is specified, it is automatically
939 generated. The generated node name is not in‐
940 tended to be predictable and changes between QEMU
941 invocations. For the top level, an explicit node
942 name must be specified.
943 read-only
945 Open the node read-only. Guest write attempts will
946 fail.
947 Note that some block drivers support only
949 read-only access, either generally or in certain
950 configurations. In this case, the default value
951 read-only=off does not work and the option must be
952 specified explicitly.
953 auto-read-only
955 If auto-read-only=on is set, QEMU may fall back to
956 read-only usage even when read-only=off is re‐
957 quested, or even switch between modes as needed,
958 e.g. depending on whether the image file is
959 writable or whether a writing user is attached to
960 the node.
961 force-share
963 Override the image locking system of QEMU by forc‐
964 ing the node to utilize weaker shared access for
965 permissions where it would normally request exclu‐
966 sive access. When there is the potential for mul‐
967 tiple instances to have the same file open
968 (whether this invocation of QEMU is the first or
969 the second instance), both instances must permit
970 shared access for the second instance to succeed
971 at opening the file.
972 Enabling force-share=on requires read-only=on.
974 cache.direct
976 The host page cache can be avoided with cache.di‐
977 rect=on. This will attempt to do disk IO directly
978 to the guest's memory. QEMU may still perform an
979 internal copy of the data.
980 cache.no-flush
982 In case you don't care about data integrity over
983 host failures, you can use cache.no-flush=on. This
984 option tells QEMU that it never needs to write any
985 data to the disk but can instead keep things in
986 cache. If anything goes wrong, like your host los‐
987 ing power, the disk storage getting disconnected
988 accidentally, etc. your image will most probably
989 be rendered unusable.
990 discard=discard
992 discard is one of "ignore" (or "off") or "unmap"
993 (or "on") and controls whether discard (also known
994 as trim or unmap) requests are ignored or passed
995 to the filesystem. Some machine types may not
996 support discard requests.
997 detect-zeroes=detect-zeroes
999 detect-zeroes is "off", "on" or "unmap" and en‐
1000 ables the automatic conversion of plain zero
1001 writes by the OS to driver specific optimized zero
1002 write commands. You may even choose "unmap" if
1003 discard is set to "unmap" to allow a zero write to
1004 be converted to an unmap operation.
1005 Driver-specific options for file
1007 This is the protocol-level block driver for accessing
1008 regular files.
1009 filename
1011 The path to the image file in the local filesystem
1012 aio Specifies the AIO backend (threads/native/io_ur‐
1014 ing, default: threads)
1015 locking
1017 Specifies whether the image file is protected with
1018 Linux OFD / POSIX locks. The default is to use the
1019 Linux Open File Descriptor API if available, oth‐
1020 erwise no lock is applied. (auto/on/off, default:
1021 auto)
1022 Example:
1024 -blockdev driver=file,node-name=disk,filename=disk.img
1026 Driver-specific options for raw
1028 This is the image format block driver for raw images. It
1029 is usually stacked on top of a protocol level block
1030 driver such as file.
1031 file Reference to or definition of the data source
1033 block driver node (e.g. a file driver node)
1034 Example 1:
1036 -blockdev driver=file,node-name=disk_file,filename=disk.img
1038 -blockdev driver=raw,node-name=disk,file=disk_file
1039 Example 2:
1041 -blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img
1043 Driver-specific options for qcow2
1045 This is the image format block driver for qcow2 images.
1046 It is usually stacked on top of a protocol level block
1047 driver such as file.
1048 file Reference to or definition of the data source
1050 block driver node (e.g. a file driver node)
1051 backing
1053 Reference to or definition of the backing file
1054 block device (default is taken from the image
1055 file). It is allowed to pass null here in order to
1056 disable the default backing file.
1057 lazy-refcounts
1059 Whether to enable the lazy refcounts feature
1060 (on/off; default is taken from the image file)
1061 cache-size
1063 The maximum total size of the L2 table and ref‐
1064 count block caches in bytes (default: the sum of
1065 l2-cache-size and refcount-cache-size)
1066 l2-cache-size
1068 The maximum size of the L2 table cache in bytes
1069 (default: if cache-size is not specified - 32M on
1070 Linux platforms, and 8M on non-Linux platforms;
1071 otherwise, as large as possible within the
1072 cache-size, while permitting the requested or the
1073 minimal refcount cache size)
1074 refcount-cache-size
1076 The maximum size of the refcount block cache in
1077 bytes (default: 4 times the cluster size; or if
1078 cache-size is specified, the part of it which is
1079 not used for the L2 cache)
1080 cache-clean-interval
1082 Clean unused entries in the L2 and refcount
1083 caches. The interval is in seconds. The default
1084 value is 600 on supporting platforms, and 0 on
1085 other platforms. Setting it to 0 disables this
1086 feature.
1087 pass-discard-request
1089 Whether discard requests to the qcow2 device
1090 should be forwarded to the data source (on/off;
1091 default: on if discard=unmap is specified, off
1092 otherwise)
1093 pass-discard-snapshot
1095 Whether discard requests for the data source
1096 should be issued when a snapshot operation (e.g.
1097 deleting a snapshot) frees clusters in the qcow2
1098 file (on/off; default: on)
1099 pass-discard-other
1101 Whether discard requests for the data source
1102 should be issued on other occasions where a clus‐
1103 ter gets freed (on/off; default: off)
1104 overlap-check
1106 Which overlap checks to perform for writes to the
1107 image (none/constant/cached/all; default: cached).
1108 For details or finer granularity control refer to
1109 the QAPI documentation of blockdev-add.
1110 Example 1:
1112 -blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2
1114 -blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216
1115 Example 2:
1117 -blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2
1119 Driver-specific options for other drivers
1121 Please refer to the QAPI documentation of the block‐
1122 dev-add QMP command.
1123 -drive option[,option[,option[,...]]]
1125 Define a new drive. This includes creating a block driver node
1126 (the backend) as well as a guest device, and is mostly a short‐
1127 cut for defining the corresponding -blockdev and -device op‐
1128 tions.
1129 -drive accepts all options that are accepted by -blockdev. In
1131 addition, it knows the following options:
1132 file=file
1134 This option defines which disk image (see the disk images
1135 chapter in the System Emulation Users Guide) to use with
1136 this drive. If the filename contains comma, you must
1137 double it (for instance, "file=my,,file" to use file
1138 "my,file").
1139 Special files such as iSCSI devices can be specified us‐
1141 ing protocol specific URLs. See the section for "Device
1142 URL Syntax" for more information.
1143 if=interface
1145 This option defines on which type on interface the drive
1146 is connected. Available types are: ide, scsi, sd, mtd,
1147 floppy, pflash, virtio, none.
1148 bus=bus,unit=unit
1150 These options define where is connected the drive by
1151 defining the bus number and the unit id.
1152 index=index
1154 This option defines where is connected the drive by using
1155 an index in the list of available connectors of a given
1156 interface type.
1157 media=media
1159 This option defines the type of the media: disk or cdrom.
1160 snapshot=snapshot
1162 snapshot is "on" or "off" and controls snapshot mode for
1163 the given drive (see -snapshot).
1164 cache=cache
1166 cache is "none", "writeback", "unsafe", "directsync" or
1167 "writethrough" and controls how the host cache is used to
1168 access block data. This is a shortcut that sets the
1169 cache.direct and cache.no-flush options (as in -block‐
1170 dev), and additionally cache.writeback, which provides a
1171 default for the write-cache option of block guest devices
1172 (as in -device). The modes correspond to the following
1173 settings:
1174 ┌─────────────┬─────────────────┬──────────────┬────────────────┐
1176 │ │ cache.writeback │ cache.direct │ cache.no-flush │
1177 ├─────────────┼─────────────────┼──────────────┼────────────────┤
1178 │writeback │ on │ off │ off │
1179 ├─────────────┼─────────────────┼──────────────┼────────────────┤
1180 │none │ on │ on │ off │
1181 ├─────────────┼─────────────────┼──────────────┼────────────────┤
1182 │writethrough │ off │ off │ off │
1183 ├─────────────┼─────────────────┼──────────────┼────────────────┤
1184 │directsync │ off │ on │ off │
1185 ├─────────────┼─────────────────┼──────────────┼────────────────┤
1186 │unsafe │ on │ off │ on │
1187 └─────────────┴─────────────────┴──────────────┴────────────────┘
1188 The default mode is cache=writeback.
1190 aio=aio
1192 aio is "threads", "native", or "io_uring" and selects be‐
1193 tween pthread based disk I/O, native Linux AIO, or Linux
1194 io_uring API.
1195 format=format
1197 Specify which disk format will be used rather than de‐
1198 tecting the format. Can be used to specify format=raw to
1199 avoid interpreting an untrusted format header.
1200 werror=action,rerror=action
1202 Specify which action to take on write and read errors.
1203 Valid actions are: "ignore" (ignore the error and try to
1204 continue), "stop" (pause QEMU), "report" (report the er‐
1205 ror to the guest), "enospc" (pause QEMU only if the host
1206 disk is full; report the error to the guest otherwise).
1207 The default setting is werror=enospc and rerror=report.
1208 copy-on-read=copy-on-read
1210 copy-on-read is "on" or "off" and enables whether to copy
1211 read backing file sectors into the image file.
1212 bps=b,bps_rd=r,bps_wr=w
1214 Specify bandwidth throttling limits in bytes per second,
1215 either for all request types or for reads or writes only.
1216 Small values can lead to timeouts or hangs inside the
1217 guest. A safe minimum for disks is 2 MB/s.
1218 bps_max=bm,bps_rd_max=rm,bps_wr_max=wm
1220 Specify bursts in bytes per second, either for all re‐
1221 quest types or for reads or writes only. Bursts allow the
1222 guest I/O to spike above the limit temporarily.
1223 iops=i,iops_rd=r,iops_wr=w
1225 Specify request rate limits in requests per second, ei‐
1226 ther for all request types or for reads or writes only.
1227 iops_max=bm,iops_rd_max=rm,iops_wr_max=wm
1229 Specify bursts in requests per second, either for all re‐
1230 quest types or for reads or writes only. Bursts allow the
1231 guest I/O to spike above the limit temporarily.
1232 iops_size=is
1234 Let every is bytes of a request count as a new request
1235 for iops throttling purposes. Use this option to prevent
1236 guests from circumventing iops limits by sending fewer
1237 but larger requests.
1238 group=g
1240 Join a throttling quota group with given name g. All
1241 drives that are members of the same group are accounted
1242 for together. Use this option to prevent guests from cir‐
1243 cumventing throttling limits by using many small disks
1244 instead of a single larger disk.
1245 By default, the cache.writeback=on mode is used. It will report
1247 data writes as completed as soon as the data is present in the
1248 host page cache. This is safe as long as your guest OS makes
1249 sure to correctly flush disk caches where needed. If your guest
1250 OS does not handle volatile disk write caches correctly and your
1251 host crashes or loses power, then the guest may experience data
1252 corruption.
1253 For such guests, you should consider using cache.writeback=off.
1255 This means that the host page cache will be used to read and
1256 write data, but write notification will be sent to the guest
1257 only after QEMU has made sure to flush each write to the disk.
1258 Be aware that this has a major impact on performance.
1259 When using the -snapshot option, unsafe caching is always used.
1261 Copy-on-read avoids accessing the same backing file sectors re‐
1263 peatedly and is useful when the backing file is over a slow net‐
1264 work. By default copy-on-read is off.
1265 Instead of -cdrom you can use:
1267 qemu-system-x86_64 -drive file=file,index=2,media=cdrom
1269 Instead of -hda, -hdb, -hdc, -hdd, you can use:
1271 qemu-system-x86_64 -drive file=file,index=0,media=disk
1273 qemu-system-x86_64 -drive file=file,index=1,media=disk
1274 qemu-system-x86_64 -drive file=file,index=2,media=disk
1275 qemu-system-x86_64 -drive file=file,index=3,media=disk
1276 You can open an image using pre-opened file descriptors from an
1278 fd set:
1279 qemu-system-x86_64 \
1281 -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \
1282 -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \
1283 -drive file=/dev/fdset/2,index=0,media=disk
1284 You can connect a CDROM to the slave of ide0:
1286 qemu-system-x86_64 -drive file=file,if=ide,index=1,media=cdrom
1288 If you don't specify the "file=" argument, you define an empty
1290 drive:
1291 qemu-system-x86_64 -drive if=ide,index=1,media=cdrom
1293 Instead of -fda, -fdb, you can use:
1295 qemu-system-x86_64 -drive file=file,index=0,if=floppy
1297 qemu-system-x86_64 -drive file=file,index=1,if=floppy
1298 By default, interface is "ide" and index is automatically incre‐
1300 mented:
1301 qemu-system-x86_64 -drive file=a -drive file=b"
1303 is interpreted like:
1305 qemu-system-x86_64 -hda a -hdb b
1307 -mtdblock file
1309 Use file as on-board Flash memory image.
1310 -sd file
1312 Use file as SecureDigital card image.
1313 -pflash file
1315 Use file as a parallel flash image.
1316 -snapshot
1318 Write to temporary files instead of disk image files. In this
1319 case, the raw disk image you use is not written back. You can
1320 however force the write back by pressing C-a s (see the disk im‐
1321 ages chapter in the System Emulation Users Guide).
1322 -fsdev local,id=id,path=path,security_model=security_model [,write‐
1324 out=writeout][,readonly=on][,fmode=fmode][,dmode=dmode] [,throt‐
1325 tling.option=value[,throttling.option=value[,...]]]
1326 -fsdev proxy,id=id,socket=socket[,writeout=writeout][,readonly=on]
1329 -fsdev proxy,id=id,sock_fd=sock_fd[,writeout=writeout][,readonly=on]
1332 -fsdev synth,id=id[,readonly=on]
1335 Define a new file system device. Valid options are:
1336 local Accesses to the filesystem are done by QEMU.
1338 proxy Accesses to the filesystem are done by
1340 virtfs-proxy-helper(1).
1341 synth Synthetic filesystem, only used by QTests.
1343 id=id Specifies identifier for this device.
1345 path=path
1347 Specifies the export path for the file system device.
1348 Files under this path will be available to the 9p client
1349 on the guest.
1350 security_model=security_model
1352 Specifies the security model to be used for this export
1353 path. Supported security models are "passthrough",
1354 "mapped-xattr", "mapped-file" and "none". In
1355 "passthrough" security model, files are stored using the
1356 same credentials as they are created on the guest. This
1357 requires QEMU to run as root. In "mapped-xattr" security
1358 model, some of the file attributes like uid, gid, mode
1359 bits and link target are stored as file attributes. For
1360 "mapped-file" these attributes are stored in the hidden
1361 .virtfs_metadata directory. Directories exported by this
1362 security model cannot interact with other unix tools.
1363 "none" security model is same as passthrough except the
1364 sever won't report failures if it fails to set file at‐
1365 tributes like ownership. Security model is mandatory only
1366 for local fsdriver. Other fsdrivers (like proxy) don't
1367 take security model as a parameter.
1368 writeout=writeout
1370 This is an optional argument. The only supported value is
1371 "immediate". This means that host page cache will be used
1372 to read and write data but write notification will be
1373 sent to the guest only when the data has been reported as
1374 written by the storage subsystem.
1375 readonly=on
1377 Enables exporting 9p share as a readonly mount for
1378 guests. By default read-write access is given.
1379 socket=socket
1381 Enables proxy filesystem driver to use passed socket file
1382 for communicating with virtfs-proxy-helper(1).
1383 sock_fd=sock_fd
1385 Enables proxy filesystem driver to use passed socket de‐
1386 scriptor for communicating with virtfs-proxy-helper(1).
1387 Usually a helper like libvirt will create socketpair and
1388 pass one of the fds as sock_fd.
1389 fmode=fmode
1391 Specifies the default mode for newly created files on the
1392 host. Works only with security models "mapped-xattr" and
1393 "mapped-file".
1394 dmode=dmode
1396 Specifies the default mode for newly created directories
1397 on the host. Works only with security models
1398 "mapped-xattr" and "mapped-file".
1399 throttling.bps-total=b,throttling.bps-read=r,throt‐
1401 tling.bps-write=w
1402 Specify bandwidth throttling limits in bytes per second,
1403 either for all request types or for reads or writes only.
1404 throttling.bps-total-max=bm,bps-read-max=rm,bps-write-max=wm
1406 Specify bursts in bytes per second, either for all re‐
1407 quest types or for reads or writes only. Bursts allow the
1408 guest I/O to spike above the limit temporarily.
1409 throttling.iops-total=i,throttling.iops-read=r, throt‐
1411 tling.iops-write=w
1412 Specify request rate limits in requests per second, ei‐
1413 ther for all request types or for reads or writes only.
1414 throttling.iops-total-max=im,throttling.iops-read-max=irm,
1416 throttling.iops-write-max=iwm
1417 Specify bursts in requests per second, either for all re‐
1418 quest types or for reads or writes only. Bursts allow the
1419 guest I/O to spike above the limit temporarily.
1420 throttling.iops-size=is
1422 Let every is bytes of a request count as a new request
1423 for iops throttling purposes.
1424 -fsdev option is used along with -device driver "virtio-9p-...".
1426 -device virtio-9p-type,fsdev=id,mount_tag=mount_tag
1428 Options for virtio-9p-... driver are:
1429 type Specifies the variant to be used. Supported values are
1431 "pci", "ccw" or "device", depending on the machine type.
1432 fsdev=id
1434 Specifies the id value specified along with -fsdev op‐
1435 tion.
1436 mount_tag=mount_tag
1438 Specifies the tag name to be used by the guest to mount
1439 this export point.
1440 -virtfs local,path=path,mount_tag=mount_tag ,security_model=secu‐
1442 rity_model[,writeout=writeout][,readonly=on]
1443 [,fmode=fmode][,dmode=dmode][,multidevs=multidevs]
1444 -virtfs proxy,socket=socket,mount_tag=mount_tag [,writeout=write‐
1447 out][,readonly=on]
1448 -virtfs proxy,sock_fd=sock_fd,mount_tag=mount_tag [,writeout=write‐
1451 out][,readonly=on]
1452 -virtfs synth,mount_tag=mount_tag
1455 Define a new virtual filesystem device and expose it to the
1456 guest using a virtio-9p-device (a.k.a. 9pfs), which essentially
1457 means that a certain directory on host is made directly accessi‐
1458 ble by guest as a pass-through file system by using the 9P net‐
1459 work protocol for communication between host and guests, if de‐
1460 sired even accessible, shared by several guests simultaniously.
1461 Note that -virtfs is actually just a convenience shortcut for
1463 its generalized form -fsdev -device virtio-9p-pci.
1464 The general form of pass-through file system options are:
1466 local Accesses to the filesystem are done by QEMU.
1468 proxy Accesses to the filesystem are done by
1470 virtfs-proxy-helper(1).
1471 synth Synthetic filesystem, only used by QTests.
1473 id=id Specifies identifier for the filesystem device
1475 path=path
1477 Specifies the export path for the file system device.
1478 Files under this path will be available to the 9p client
1479 on the guest.
1480 security_model=security_model
1482 Specifies the security model to be used for this export
1483 path. Supported security models are "passthrough",
1484 "mapped-xattr", "mapped-file" and "none". In
1485 "passthrough" security model, files are stored using the
1486 same credentials as they are created on the guest. This
1487 requires QEMU to run as root. In "mapped-xattr" security
1488 model, some of the file attributes like uid, gid, mode
1489 bits and link target are stored as file attributes. For
1490 "mapped-file" these attributes are stored in the hidden
1491 .virtfs_metadata directory. Directories exported by this
1492 security model cannot interact with other unix tools.
1493 "none" security model is same as passthrough except the
1494 sever won't report failures if it fails to set file at‐
1495 tributes like ownership. Security model is mandatory only
1496 for local fsdriver. Other fsdrivers (like proxy) don't
1497 take security model as a parameter.
1498 writeout=writeout
1500 This is an optional argument. The only supported value is
1501 "immediate". This means that host page cache will be used
1502 to read and write data but write notification will be
1503 sent to the guest only when the data has been reported as
1504 written by the storage subsystem.
1505 readonly=on
1507 Enables exporting 9p share as a readonly mount for
1508 guests. By default read-write access is given.
1509 socket=socket
1511 Enables proxy filesystem driver to use passed socket file
1512 for communicating with virtfs-proxy-helper(1). Usually a
1513 helper like libvirt will create socketpair and pass one
1514 of the fds as sock_fd.
1515 sock_fd
1517 Enables proxy filesystem driver to use passed 'sock_fd'
1518 as the socket descriptor for interfacing with
1519 virtfs-proxy-helper(1).
1520 fmode=fmode
1522 Specifies the default mode for newly created files on the
1523 host. Works only with security models "mapped-xattr" and
1524 "mapped-file".
1525 dmode=dmode
1527 Specifies the default mode for newly created directories
1528 on the host. Works only with security models
1529 "mapped-xattr" and "mapped-file".
1530 mount_tag=mount_tag
1532 Specifies the tag name to be used by the guest to mount
1533 this export point.
1534 multidevs=multidevs
1536 Specifies how to deal with multiple devices being shared
1537 with a 9p export. Supported behaviours are either
1538 "remap", "forbid" or "warn". The latter is the default
1539 behaviour on which virtfs 9p expects only one device to
1540 be shared with the same export, and if more than one de‐
1541 vice is shared and accessed via the same 9p export then
1542 only a warning message is logged (once) by qemu on host
1543 side. In order to avoid file ID collisions on guest you
1544 should either create a separate virtfs export for each
1545 device to be shared with guests (recommended way) or you
1546 might use "remap" instead which allows you to share mul‐
1547 tiple devices with only one export instead, which is
1548 achieved by remapping the original inode numbers from
1549 host to guest in a way that would prevent such colli‐
1550 sions. Remapping inodes in such use cases is required be‐
1551 cause the original device IDs from host are never passed
1552 and exposed on guest. Instead all files of an export
1553 shared with virtfs always share the same device id on
1554 guest. So two files with identical inode numbers but from
1555 actually different devices on host would otherwise cause
1556 a file ID collision and hence potential misbehaviours on
1557 guest. "forbid" on the other hand assumes like "warn"
1558 that only one device is shared by the same export, how‐
1559 ever it will not only log a warning message but also deny
1560 access to additional devices on guest. Note though that
1561 "forbid" does currently not block all possible file ac‐
1562 cess operations (e.g. readdir() would still return en‐
1563 tries from other devices).
1564 -iscsi Configure iSCSI session parameters.
1566 USB convenience options
1568 -usb Enable USB emulation on machine types with an on-board USB host
1569 controller (if not enabled by default). Note that on-board USB
1570 host controllers may not support USB 3.0. In this case -device
1571 qemu-xhci can be used instead on machines with PCI.
1572 -usbdevice devname
1574 Add the USB device devname, and enable an on-board USB con‐
1575 troller if possible and necessary (just like it can be done via
1576 -machine usb=on). Note that this option is mainly intended for
1577 the user's convenience only. More fine-grained control can be
1578 achieved by selecting a USB host controller (if necessary) and
1579 the desired USB device via the -device option instead. For exam‐
1580 ple, instead of using -usbdevice mouse it is possible to use
1581 -device qemu-xhci -device usb-mouse to connect the USB mouse to
1582 a USB 3.0 controller instead (at least on machines that support
1583 PCI and do not have an USB controller enabled by default yet).
1584 For more details, see the chapter about Connecting USB devices
1585 in the System Emulation Users Guide. Possible devices for dev‐
1586 name are:
1587 braille
1589 Braille device. This will use BrlAPI to display the
1590 braille output on a real or fake device (i.e. it also
1591 creates a corresponding braille chardev automatically be‐
1592 side the usb-braille USB device).
1593 keyboard
1595 Standard USB keyboard. Will override the PS/2 keyboard
1596 (if present).
1597 mouse Virtual Mouse. This will override the PS/2 mouse emula‐
1599 tion when activated.
1600 tablet Pointer device that uses absolute coordinates (like a
1602 touchscreen). This means QEMU is able to report the mouse
1603 position without having to grab the mouse. Also overrides
1604 the PS/2 mouse emulation when activated.
1605 wacom-tablet
1607 Wacom PenPartner USB tablet.
1608 Display options
1610 -display type
1611 Select type of display to use. This option is a replacement for
1612 the old style -sdl/-curses/... options. Use -display help to
1613 list the available display types. Valid values for type are
1614 spice-app[,gl=on|off]
1616 Start QEMU as a Spice server and launch the default Spice
1617 client application. The Spice server will redirect the
1618 serial consoles and QEMU monitors. (Since 4.0)
1619 sdl Display video output via SDL (usually in a separate
1621 graphics window; see the SDL documentation for other pos‐
1622 sibilities). Valid parameters are:
1623 grab-mod=<mods> : Used to select the modifier keys for
1625 toggling the mouse grabbing in conjunction with the "g"
1626 key. <mods> can be either lshift-lctrl-lalt or rctrl.
1627 alt_grab=on|off : Use Control+Alt+Shift-g to toggle mouse
1629 grabbing. This parameter is deprecated - use grab-mod
1630 instead.
1631 ctrl_grab=on|off : Use Right-Control-g to toggle mouse
1633 grabbing. This parameter is deprecated - use grab-mod
1634 instead.
1635 gl=on|off|core|es : Use OpenGL for displaying
1637 show-cursor=on|off : Force showing the mouse cursor
1639 window-close=on|off : Allow to quit qemu with window
1641 close button
1642 gtk Display video output in a GTK window. This interface pro‐
1644 vides drop-down menus and other UI elements to configure
1645 and control the VM during runtime. Valid parameters are:
1646 full-screen=on|off : Start in fullscreen mode
1648 gl=on|off : Use OpenGL for displaying
1650 grab-on-hover=on|off : Grab keyboard input on mouse hover
1652 show-cursor=on|off : Force showing the mouse cursor
1654 window-close=on|off : Allow to quit qemu with window
1656 close button
1657 curses[,charset=<encoding>]
1659 Display video output via curses. For graphics device mod‐
1660 els which support a text mode, QEMU can display this out‐
1661 put using a curses/ncurses interface. Nothing is dis‐
1662 played when the graphics device is in graphical mode or
1663 if the graphics device does not support a text mode. Gen‐
1664 erally only the VGA device models support text mode. The
1665 font charset used by the guest can be specified with the
1666 charset option, for example charset=CP850 for IBM CP850
1667 encoding. The default is CP437.
1668 egl-headless[,rendernode=<file>]
1670 Offload all OpenGL operations to a local DRI device. For
1671 any graphical display, this display needs to be paired
1672 with either VNC or SPICE displays.
1673 vnc=<display>
1675 Start a VNC server on display <display>
1676 none Do not display video output. The guest will still see an
1678 emulated graphics card, but its output will not be dis‐
1679 played to the QEMU user. This option differs from the
1680 -nographic option in that it only affects what is done
1681 with video output; -nographic also changes the destina‐
1682 tion of the serial and parallel port data.
1683 -nographic
1685 Normally, if QEMU is compiled with graphical window support, it
1686 displays output such as guest graphics, guest console, and the
1687 QEMU monitor in a window. With this option, you can totally dis‐
1688 able graphical output so that QEMU is a simple command line ap‐
1689 plication. The emulated serial port is redirected on the con‐
1690 sole and muxed with the monitor (unless redirected elsewhere ex‐
1691 plicitly). Therefore, you can still use QEMU to debug a Linux
1692 kernel with a serial console. Use C-a h for help on switching
1693 between the console and monitor.
1694 -curses
1696 Normally, if QEMU is compiled with graphical window support, it
1697 displays output such as guest graphics, guest console, and the
1698 QEMU monitor in a window. With this option, QEMU can display the
1699 VGA output when in text mode using a curses/ncurses interface.
1700 Nothing is displayed in graphical mode.
1701 -alt-grab
1703 Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note
1704 that this also affects the special keys (for fullscreen, moni‐
1705 tor-mode switching, etc). This option is deprecated - please use
1706 -display sdl,grab-mod=lshift-lctrl-lalt instead.
1707 -ctrl-grab
1709 Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that
1710 this also affects the special keys (for fullscreen, monitor-mode
1711 switching, etc). This option is deprecated - please use -display
1712 sdl,grab-mod=rctrl instead.
1713 -no-quit
1715 Disable window close capability (SDL and GTK only). This option
1716 is deprecated, please use -display ...,window-close=off instead.
1717 -sdl Enable SDL.
1719 -spice option[,option[,...]]
1721 Enable the spice remote desktop protocol. Valid options are
1722 port=<nr>
1724 Set the TCP port spice is listening on for plaintext
1725 channels.
1726 addr=<addr>
1728 Set the IP address spice is listening on. Default is any
1729 address.
1730 ipv4=on|off; ipv6=on|off; unix=on|off
1732 Force using the specified IP version.
1733 password=<string>
1735 Set the password you need to authenticate.
1736 This option is deprecated and insecure because it leaves
1738 the password visible in the process listing. Use pass‐
1739 word-secret instead.
1740 password-secret=<secret-id>
1742 Set the ID of the secret object containing the password
1743 you need to authenticate.
1744 sasl=on|off
1746 Require that the client use SASL to authenticate with the
1747 spice. The exact choice of authentication method used is
1748 controlled from the system / user's SASL configuration
1749 file for the 'qemu' service. This is typically found in
1750 /etc/sasl2/qemu.conf. If running QEMU as an unprivileged
1751 user, an environment variable SASL_CONF_PATH can be used
1752 to make it search alternate locations for the service
1753 config. While some SASL auth methods can also provide
1754 data encryption (eg GSSAPI), it is recommended that SASL
1755 always be combined with the 'tls' and 'x509' settings to
1756 enable use of SSL and server certificates. This ensures a
1757 data encryption preventing compromise of authentication
1758 credentials.
1759 disable-ticketing=on|off
1761 Allow client connects without authentication.
1762 disable-copy-paste=on|off
1764 Disable copy paste between the client and the guest.
1765 disable-agent-file-xfer=on|off
1767 Disable spice-vdagent based file-xfer between the client
1768 and the guest.
1769 tls-port=<nr>
1771 Set the TCP port spice is listening on for encrypted
1772 channels.
1773 x509-dir=<dir>
1775 Set the x509 file directory. Expects same filenames as
1776 -vnc $display,x509=$dir
1777 x509-key-file=<file>; x509-key-password=<file>;
1779 x509-cert-file=<file>; x509-cacert-file=<file>;
1780 x509-dh-key-file=<file>
1781 The x509 file names can also be configured individually.
1782 tls-ciphers=<list>
1784 Specify which ciphers to use.
1785 tls-channel=[main|display|cursor|inputs|record|playback]; plain‐
1787 text-channel=[main|display|cursor|inputs|record|playback]
1788 Force specific channel to be used with or without TLS en‐
1789 cryption. The options can be specified multiple times to
1790 configure multiple channels. The special name "default"
1791 can be used to set the default mode. For channels which
1792 are not explicitly forced into one mode the spice client
1793 is allowed to pick tls/plaintext as he pleases.
1794 image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
1796 Configure image compression (lossless). Default is
1797 auto_glz.
1798 jpeg-wan-compression=[auto|never|always]; zlib-glz-wan-compres‐
1800 sion=[auto|never|always]
1801 Configure wan image compression (lossy for slow links).
1802 Default is auto.
1803 streaming-video=[off|all|filter]
1805 Configure video stream detection. Default is off.
1806 agent-mouse=[on|off]
1808 Enable/disable passing mouse events via vdagent. Default
1809 is on.
1810 playback-compression=[on|off]
1812 Enable/disable audio stream compression (using celt
1813 0.5.1). Default is on.
1814 seamless-migration=[on|off]
1816 Enable/disable spice seamless migration. Default is off.
1817 gl=[on|off]
1819 Enable/disable OpenGL context. Default is off.
1820 rendernode=<file>
1822 DRM render node for OpenGL rendering. If not specified,
1823 it will pick the first available. (Since 2.9)
1824 -portrait
1826 Rotate graphical output 90 deg left (only PXA LCD).
1827 -rotate deg
1829 Rotate graphical output some deg left (only PXA LCD).
1830 -vga type
1832 Select type of VGA card to emulate. Valid values for type are
1833 cirrus Cirrus Logic GD5446 Video card. All Windows versions
1835 starting from Windows 95 should recognize and use this
1836 graphic card. For optimal performances, use 16 bit color
1837 depth in the guest and the host OS. (This card was the
1838 default before QEMU 2.2)
1839 std Standard VGA card with Bochs VBE extensions. If your
1841 guest OS supports the VESA 2.0 VBE extensions (e.g. Win‐
1842 dows XP) and if you want to use high resolution modes (>=
1843 1280x1024x16) then you should use this option. (This card
1844 is the default since QEMU 2.2)
1845 vmware VMWare SVGA-II compatible adapter. Use it if you have
1847 sufficiently recent XFree86/XOrg server or Windows guest
1848 with a driver for this card.
1849 qxl QXL paravirtual graphic card. It is VGA compatible (in‐
1851 cluding VESA 2.0 VBE support). Works best with qxl guest
1852 drivers installed though. Recommended choice when using
1853 the spice protocol.
1854 tcx (sun4m only) Sun TCX framebuffer. This is the default
1856 framebuffer for sun4m machines and offers both 8-bit and
1857 24-bit colour depths at a fixed resolution of 1024x768.
1858 cg3 (sun4m only) Sun cgthree framebuffer. This is a simple
1860 8-bit framebuffer for sun4m machines available in both
1861 1024x768 (OpenBIOS) and 1152x900 (OBP) resolutions aimed
1862 at people wishing to run older Solaris versions.
1863 virtio Virtio VGA card.
1865 none Disable VGA card.
1867 -full-screen
1869 Start in full screen.
1870 -g widthxheight[xdepth]
1872 Set the initial graphical resolution and depth (PPC, SPARC
1873 only).
1874 For PPC the default is 800x600x32.
1876 For SPARC with the TCX graphics device, the default is
1878 1024x768x8 with the option of 1024x768x24. For cgthree, the de‐
1879 fault is 1024x768x8 with the option of 1152x900x8 for people who
1880 wish to use OBP.
1881 -vnc display[,option[,option[,...]]]
1883 Normally, if QEMU is compiled with graphical window support, it
1884 displays output such as guest graphics, guest console, and the
1885 QEMU monitor in a window. With this option, you can have QEMU
1886 listen on VNC display display and redirect the VGA display over
1887 the VNC session. It is very useful to enable the usb tablet de‐
1888 vice when using this option (option -device usb-tablet). When
1889 using the VNC display, you must use the -k parameter to set the
1890 keyboard layout if you are not using en-us. Valid syntax for the
1891 display is
1892 to=L With this option, QEMU will try next available VNC dis‐
1894 plays, until the number L, if the origianlly defined
1895 "-vnc display" is not available, e.g. port 5900+display
1896 is already used by another application. By default, to=0.
1897 host:d TCP connections will only be allowed from host on display
1899 d. By convention the TCP port is 5900+d. Optionally, host
1900 can be omitted in which case the server will accept con‐
1901 nections from any host.
1902 unix:path
1904 Connections will be allowed over UNIX domain sockets
1905 where path is the location of a unix socket to listen for
1906 connections on.
1907 none VNC is initialized but not started. The monitor change
1909 command can be used to later start the VNC server.
1910 Following the display value there may be one or more option
1912 flags separated by commas. Valid options are
1913 reverse=on|off
1915 Connect to a listening VNC client via a "reverse" connec‐
1916 tion. The client is specified by the display. For re‐
1917 verse network connections (host:d,``reverse``), the d ar‐
1918 gument is a TCP port number, not a display number.
1919 websocket=on|off
1921 Opens an additional TCP listening port dedicated to VNC
1922 Websocket connections. If a bare websocket option is
1923 given, the Websocket port is 5700+display. An alternative
1924 port can be specified with the syntax websocket=port.
1925 If host is specified connections will only be allowed
1927 from this host. It is possible to control the websocket
1928 listen address independently, using the syntax web‐
1929 socket=host:port.
1930 If no TLS credentials are provided, the websocket connec‐
1932 tion runs in unencrypted mode. If TLS credentials are
1933 provided, the websocket connection requires encrypted
1934 client connections.
1935 password=on|off
1937 Require that password based authentication is used for
1938 client connections.
1939 The password must be set separately using the set_pass‐
1941 word command in the QEMU monitor. The syntax to change
1942 your password is: set_password <protocol> <password>
1943 where <protocol> could be either "vnc" or "spice".
1944 If you would like to change <protocol> password expira‐
1946 tion, you should use expire_password <protocol> <expira‐
1947 tion-time> where expiration time could be one of the fol‐
1948 lowing options: now, never, +seconds or UNIX time of ex‐
1949 piration, e.g. +60 to make password expire in 60 seconds,
1950 or 1335196800 to make password expire on "Mon Apr 23
1951 12:00:00 EDT 2012" (UNIX time for this date and time).
1952 You can also use keywords "now" or "never" for the expi‐
1954 ration time to allow <protocol> password to expire imme‐
1955 diately or never expire.
1956 password-secret=<secret-id>
1958 Require that password based authentication is used for
1959 client connections, using the password provided by the
1960 secret object identified by secret-id.
1961 tls-creds=ID
1963 Provides the ID of a set of TLS credentials to use to se‐
1964 cure the VNC server. They will apply to both the normal
1965 VNC server socket and the websocket socket (if enabled).
1966 Setting TLS credentials will cause the VNC server socket
1967 to enable the VeNCrypt auth mechanism. The credentials
1968 should have been previously created using the -object
1969 tls-creds argument.
1970 tls-authz=ID
1972 Provides the ID of the QAuthZ authorization object
1973 against which the client's x509 distinguished name will
1974 validated. This object is only resolved at time of use,
1975 so can be deleted and recreated on the fly while the VNC
1976 server is active. If missing, it will default to denying
1977 access.
1978 sasl=on|off
1980 Require that the client use SASL to authenticate with the
1981 VNC server. The exact choice of authentication method
1982 used is controlled from the system / user's SASL configu‐
1983 ration file for the 'qemu' service. This is typically
1984 found in /etc/sasl2/qemu.conf. If running QEMU as an un‐
1985 privileged user, an environment variable SASL_CONF_PATH
1986 can be used to make it search alternate locations for the
1987 service config. While some SASL auth methods can also
1988 provide data encryption (eg GSSAPI), it is recommended
1989 that SASL always be combined with the 'tls' and 'x509'
1990 settings to enable use of SSL and server certificates.
1991 This ensures a data encryption preventing compromise of
1992 authentication credentials. See the VNC security section
1993 in the System Emulation Users Guide for details on using
1994 SASL authentication.
1995 sasl-authz=ID
1997 Provides the ID of the QAuthZ authorization object
1998 against which the client's SASL username will validated.
1999 This object is only resolved at time of use, so can be
2000 deleted and recreated on the fly while the VNC server is
2001 active. If missing, it will default to denying access.
2002 acl=on|off
2004 Legacy method for enabling authorization of clients
2005 against the x509 distinguished name and SASL username. It
2006 results in the creation of two authz-list objects with
2007 IDs of vnc.username and vnc.x509dname. The rules for
2008 these objects must be configured with the HMP ACL com‐
2009 mands.
2010 This option is deprecated and should no longer be used.
2012 The new sasl-authz and tls-authz options are a replace‐
2013 ment.
2014 lossy=on|off
2016 Enable lossy compression methods (gradient, JPEG, ...).
2017 If this option is set, VNC client may receive lossy
2018 framebuffer updates depending on its encoding settings.
2019 Enabling this option can save a lot of bandwidth at the
2020 expense of quality.
2021 non-adaptive=on|off
2023 Disable adaptive encodings. Adaptive encodings are en‐
2024 abled by default. An adaptive encoding will try to detect
2025 frequently updated screen regions, and send updates in
2026 these regions using a lossy encoding (like JPEG). This
2027 can be really helpful to save bandwidth when playing
2028 videos. Disabling adaptive encodings restores the origi‐
2029 nal static behavior of encodings like Tight.
2030 share=[allow-exclusive|force-shared|ignore]
2032 Set display sharing policy. 'allow-exclusive' allows
2033 clients to ask for exclusive access. As suggested by the
2034 rfb spec this is implemented by dropping other connec‐
2035 tions. Connecting multiple clients in parallel requires
2036 all clients asking for a shared session (vncviewer:
2037 -shared switch). This is the default. 'force-shared'
2038 disables exclusive client access. Useful for shared desk‐
2039 top sessions, where you don't want someone forgetting
2040 specify -shared disconnect everybody else. 'ignore' com‐
2041 pletely ignores the shared flag and allows everybody con‐
2042 nect unconditionally. Doesn't conform to the rfb spec but
2043 is traditional QEMU behavior.
2044 key-delay-ms
2046 Set keyboard delay, for key down and key up events, in
2047 milliseconds. Default is 10. Keyboards are low-bandwidth
2048 devices, so this slowdown can help the device and guest
2049 to keep up and not lose events in case events are arriv‐
2050 ing in bulk. Possible causes for the latter are flaky
2051 network connections, or scripts for automated testing.
2052 audiodev=audiodev
2054 Use the specified audiodev when the VNC client requests
2055 audio transmission. When not using an -audiodev argument,
2056 this option must be omitted, otherwise is must be present
2057 and specify a valid audiodev.
2058 power-control=on|off
2060 Permit the remote client to issue shutdown, reboot or re‐
2061 set power control requests.
2062 i386 target only
2064 -win2k-hack
2065 Use it when installing Windows 2000 to avoid a disk full bug.
2066 After Windows 2000 is installed, you no longer need this option
2067 (this option slows down the IDE transfers).
2068 -no-fd-bootchk
2070 Disable boot signature checking for floppy disks in BIOS. May be
2071 needed to boot from old floppy disks.
2072 -no-acpi
2074 Disable ACPI (Advanced Configuration and Power Interface) sup‐
2075 port. Use it if your guest OS complains about ACPI problems (PC
2076 target machine only).
2077 -no-hpet
2079 Disable HPET support.
2080 -acpitable [sig=str][,rev=n][,oem_id=str][,oem_ta‐
2082 ble_id=str][,oem_rev=n] [,asl_compiler_id=str][,asl_com‐
2083 piler_rev=n][,data=file1[:file2]...]
2084 Add ACPI table with specified header fields and context from
2085 specified files. For file=, take whole ACPI table from the spec‐
2086 ified files, including all ACPI headers (possible overridden by
2087 other options). For data=, only data portion of the table is
2088 used, all header information is specified in the command line.
2089 If a SLIC table is supplied to QEMU, then the SLIC's oem_id and
2090 oem_table_id fields will override the same in the RSDT and the
2091 FADT (a.k.a. FACP), in order to ensure the field matches re‐
2092 quired by the Microsoft SLIC spec and the ACPI spec.
2093 -smbios file=binary
2095 Load SMBIOS entry from binary file.
2096 -smbios type=0[,vendor=str][,version=str][,date=str][,re‐
2098 lease=%d.%d][,uefi=on|off]
2099 Specify SMBIOS type 0 fields
2100 -smbios type=1[,manufacturer=str][,product=str][,version=str][,se‐
2102 rial=str][,uuid=uuid][,sku=str][,family=str]
2103 Specify SMBIOS type 1 fields
2104 -smbios type=2[,manufacturer=str][,product=str][,version=str][,se‐
2106 rial=str][,asset=str][,location=str]
2107 Specify SMBIOS type 2 fields
2108 -smbios type=3[,manufacturer=str][,version=str][,serial=str][,as‐
2110 set=str][,sku=str]
2111 Specify SMBIOS type 3 fields
2112 -smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,se‐
2114 rial=str][,asset=str][,part=str]
2115 Specify SMBIOS type 4 fields
2116 -smbios type=11[,value=str][,path=filename]
2118 Specify SMBIOS type 11 fields
2119 This argument can be repeated multiple times, and values are
2121 added in the order they are parsed. Applications intending to
2122 use OEM strings data are encouraged to use their application
2123 name as a prefix for the value string. This facilitates passing
2124 information for multiple applications concurrently.
2125 The value=str syntax provides the string data inline, while the
2127 path=filename syntax loads data from a file on disk. Note that
2128 the file is not permitted to contain any NUL bytes.
2129 Both the value and path options can be repeated multiple times
2131 and will be added to the SMBIOS table in the order in which they
2132 appear.
2133 Note that on the x86 architecture, the total size of all SMBIOS
2135 tables is limited to 65535 bytes. Thus the OEM strings data is
2136 not suitable for passing large amounts of data into the guest.
2137 Instead it should be used as a indicator to inform the guest
2138 where to locate the real data set, for example, by specifying
2139 the serial ID of a block device.
2140 An example passing three strings is
2142 -smbios type=11,value=cloud-init:ds=nocloud-net;s=http://10.10.0.1:8000/,\
2144 value=anaconda:method=http://dl.fedoraproject.org/pub/fedora/linux/releases/25/x86_64/os,\
2145 path=/some/file/with/oemstringsdata.txt
2146 In the guest OS this is visible with the dmidecode command
2148 $ dmidecode -t 11
2150 Handle 0x0E00, DMI type 11, 5 bytes
2151 OEM Strings
2152 String 1: cloud-init:ds=nocloud-net;s=http://10.10.0.1:8000/
2153 String 2: anaconda:method=http://dl.fedoraproject.org/pub/fedora/linux/releases/25/x86_64/os
2154 String 3: myapp:some extra data
2155 -smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,se‐
2157 rial=str][,asset=str][,part=str][,speed=%d]
2158 Specify SMBIOS type 17 fields
2159 -smbios type=41[,designation=str][,kind=str][,instance=%d][,pcidev=str]
2161 Specify SMBIOS type 41 fields
2162 This argument can be repeated multiple times. Its main use is
2164 to allow network interfaces be created as enoX on Linux, with X
2165 being the instance number, instead of the name depending on the
2166 interface position on the PCI bus.
2167 Here is an example of use:
2169 -netdev user,id=internet \
2171 -device virtio-net-pci,mac=50:54:00:00:00:42,netdev=internet,id=internet-dev \
2172 -smbios type=41,designation='Onboard LAN',instance=1,kind=ethernet,pcidev=internet-dev
2173 In the guest OS, the device should then appear as eno1:
2175 ..parsed-literal:
2177 $ ip -brief l
2179 lo UNKNOWN 00:00:00:00:00:00 <LOOPBACK,UP,LOWER_UP>
2180 eno1 UP 50:54:00:00:00:42 <BROADCAST,MULTICAST,UP,LOWER_UP>
2181 Currently, the PCI device has to be attached to the root bus.
2183 Network options
2185 -nic
2186 [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn]
2187 This option is a shortcut for configuring both the on-board (de‐
2188 fault) guest NIC hardware and the host network backend in one
2189 go. The host backend options are the same as with the corre‐
2190 sponding -netdev options below. The guest NIC model can be set
2191 with model=modelname. Use model=help to list the available de‐
2192 vice types. The hardware MAC address can be set with
2193 mac=macaddr.
2194 The following two example do exactly the same, to show how -nic
2196 can be used to shorten the command line length:
2197 qemu-system-x86_64 -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32
2199 qemu-system-x86_64 -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32
2200 -nic none
2202 Indicate that no network devices should be configured. It is
2203 used to override the default configuration (default NIC with
2204 "user" host network backend) which is activated if no other net‐
2205 working options are provided.
2206 -netdev user,id=id[,option][,option][,...]
2208 Configure user mode host network backend which requires no ad‐
2209 ministrator privilege to run. Valid options are:
2210 id=id Assign symbolic name for use in monitor commands.
2212 ipv4=on|off and ipv6=on|off
2214 Specify that either IPv4 or IPv6 must be enabled. If nei‐
2215 ther is specified both protocols are enabled.
2216 net=addr[/mask]
2218 Set IP network address the guest will see. Optionally
2219 specify the netmask, either in the form a.b.c.d or as
2220 number of valid top-most bits. Default is 10.0.2.0/24.
2221 host=addr
2223 Specify the guest-visible address of the host. Default is
2224 the 2nd IP in the guest network, i.e. x.x.x.2.
2225 ipv6-net=addr[/int]
2227 Set IPv6 network address the guest will see (default is
2228 fec0::/64). The network prefix is given in the usual
2229 hexadecimal IPv6 address notation. The prefix size is op‐
2230 tional, and is given as the number of valid top-most bits
2231 (default is 64).
2232 ipv6-host=addr
2234 Specify the guest-visible IPv6 address of the host. De‐
2235 fault is the 2nd IPv6 in the guest network, i.e. xxxx::2.
2236 restrict=on|off
2238 If this option is enabled, the guest will be isolated,
2239 i.e. it will not be able to contact the host and no guest
2240 IP packets will be routed over the host to the outside.
2241 This option does not affect any explicitly set forwarding
2242 rules.
2243 hostname=name
2245 Specifies the client hostname reported by the built-in
2246 DHCP server.
2247 dhcpstart=addr
2249 Specify the first of the 16 IPs the built-in DHCP server
2250 can assign. Default is the 15th to 31st IP in the guest
2251 network, i.e. x.x.x.15 to x.x.x.31.
2252 dns=addr
2254 Specify the guest-visible address of the virtual name‐
2255 server. The address must be different from the host ad‐
2256 dress. Default is the 3rd IP in the guest network, i.e.
2257 x.x.x.3.
2258 ipv6-dns=addr
2260 Specify the guest-visible address of the IPv6 virtual
2261 nameserver. The address must be different from the host
2262 address. Default is the 3rd IP in the guest network,
2263 i.e. xxxx::3.
2264 dnssearch=domain
2266 Provides an entry for the domain-search list sent by the
2267 built-in DHCP server. More than one domain suffix can be
2268 transmitted by specifying this option multiple times. If
2269 supported, this will cause the guest to automatically try
2270 to append the given domain suffix(es) in case a domain
2271 name can not be resolved.
2272 Example:
2274 qemu-system-x86_64 -nic user,dnssearch=mgmt.example.org,dnssearch=example.org
2276 domainname=domain
2278 Specifies the client domain name reported by the built-in
2279 DHCP server.
2280 tftp=dir
2282 When using the user mode network stack, activate a
2283 built-in TFTP server. The files in dir will be exposed as
2284 the root of a TFTP server. The TFTP client on the guest
2285 must be configured in binary mode (use the command bin of
2286 the Unix TFTP client).
2287 tftp-server-name=name
2289 In BOOTP reply, broadcast name as the "TFTP server name"
2290 (RFC2132 option 66). This can be used to advise the guest
2291 to load boot files or configurations from a different
2292 server than the host address.
2293 bootfile=file
2295 When using the user mode network stack, broadcast file as
2296 the BOOTP filename. In conjunction with tftp, this can be
2297 used to network boot a guest from a local directory.
2298 Example (using pxelinux):
2300 qemu-system-x86_64 -hda linux.img -boot n -device e1000,netdev=n1 \
2302 -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
2303 smb=dir[,smbserver=addr]
2305 When using the user mode network stack, activate a
2306 built-in SMB server so that Windows OSes can access to
2307 the host files in dir transparently. The IP address of
2308 the SMB server can be set to addr. By default the 4th IP
2309 in the guest network is used, i.e. x.x.x.4.
2310 In the guest Windows OS, the line:
2312 10.0.2.4 smbserver
2314 must be added in the file C:\WINDOWS\LMHOSTS (for windows
2316 9x/Me) or C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS (Windows
2317 NT/2000).
2318 Then dir can be accessed in \\smbserver\qemu.
2320 Note that a SAMBA server must be installed on the host
2322 OS.
2323 hostfwd=[tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport
2325 Redirect incoming TCP or UDP connections to the host port
2326 hostport to the guest IP address guestaddr on guest port
2327 guestport. If guestaddr is not specified, its value is
2328 x.x.x.15 (default first address given by the built-in
2329 DHCP server). By specifying hostaddr, the rule can be
2330 bound to a specific host interface. If no connection type
2331 is set, TCP is used. This option can be given multiple
2332 times.
2333 For example, to redirect host X11 connection from screen
2335 1 to guest screen 0, use the following:
2336 # on the host
2338 qemu-system-x86_64 -nic user,hostfwd=tcp:127.0.0.1:6001-:6000
2339 # this host xterm should open in the guest X11 server
2340 xterm -display :1
2341 To redirect telnet connections from host port 5555 to
2343 telnet port on the guest, use the following:
2344 # on the host
2346 qemu-system-x86_64 -nic user,hostfwd=tcp::5555-:23
2347 telnet localhost 5555
2348 Then when you use on the host telnet localhost 5555, you
2350 connect to the guest telnet server.
2351 guestfwd=[tcp]:server:port-dev; guest‐
2353 fwd=[tcp]:server:port-cmd:command
2354 Forward guest TCP connections to the IP address server on
2355 port port to the character device dev or to a program ex‐
2356 ecuted by cmd:command which gets spawned for each connec‐
2357 tion. This option can be given multiple times.
2358 You can either use a chardev directly and have that one
2360 used throughout QEMU's lifetime, like in the following
2361 example:
2362 # open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
2364 # the guest accesses it
2365 qemu-system-x86_64 -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321
2366 Or you can execute a command on every TCP connection es‐
2368 tablished by the guest, so that QEMU behaves similar to
2369 an inetd process for that virtual server:
2370 # call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
2372 # and connect the TCP stream to its stdin/stdout
2373 qemu-system-x86_64 -nic 'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
2374 -netdev tap,id=id[,fd=h][,ifname=name][,script=file][,down‐
2376 script=dfile][,br=bridge][,helper=helper]
2377 Configure a host TAP network backend with ID id.
2378 Use the network script file to configure it and the network
2380 script dfile to deconfigure it. If name is not provided, the OS
2381 automatically provides one. The default network configure script
2382 is /etc/qemu-ifup and the default network deconfigure script is
2383 /etc/qemu-ifdown. Use script=no or downscript=no to disable
2384 script execution.
2385 If running QEMU as an unprivileged user, use the network helper
2387 to configure the TAP interface and attach it to the bridge. The
2388 default network helper executable is /path/to/qemu-bridge-helper
2389 and the default bridge device is br0.
2390 fd=h can be used to specify the handle of an already opened host
2392 TAP interface.
2393 Examples:
2395 #launch a QEMU instance with the default network script
2397 qemu-system-x86_64 linux.img -nic tap
2398 #launch a QEMU instance with two NICs, each one connected
2400 #to a TAP device
2401 qemu-system-x86_64 linux.img \
2402 -netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 \
2403 -netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1
2404 #launch a QEMU instance with the default network helper to
2406 #connect a TAP device to bridge br0
2407 qemu-system-x86_64 linux.img -device virtio-net-pci,netdev=n1 \
2408 -netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper"
2409 -netdev bridge,id=id[,br=bridge][,helper=helper]
2411 Connect a host TAP network interface to a host bridge device.
2412 Use the network helper helper to configure the TAP interface and
2414 attach it to the bridge. The default network helper executable
2415 is /path/to/qemu-bridge-helper and the default bridge device is
2416 br0.
2417 Examples:
2419 #launch a QEMU instance with the default network helper to
2421 #connect a TAP device to bridge br0
2422 qemu-system-x86_64 linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1
2423 #launch a QEMU instance with the default network helper to
2425 #connect a TAP device to bridge qemubr0
2426 qemu-system-x86_64 linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1
2427 -netdev socket,id=id[,fd=h][,listen=[host]:port][,connect=host:port]
2429 This host network backend can be used to connect the guest's
2430 network to another QEMU virtual machine using a TCP socket con‐
2431 nection. If listen is specified, QEMU waits for incoming connec‐
2432 tions on port (host is optional). connect is used to connect to
2433 another QEMU instance using the listen option. fd=h specifies an
2434 already opened TCP socket.
2435 Example:
2437 # launch a first QEMU instance
2439 qemu-system-x86_64 linux.img \
2440 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2441 -netdev socket,id=n1,listen=:1234
2442 # connect the network of this instance to the network of the first instance
2443 qemu-system-x86_64 linux.img \
2444 -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
2445 -netdev socket,id=n2,connect=127.0.0.1:1234
2446 -netdev socket,id=id[,fd=h][,mcast=maddr:port[,localaddr=addr]]
2448 Configure a socket host network backend to share the guest's
2449 network traffic with another QEMU virtual machines using a UDP
2450 multicast socket, effectively making a bus for every QEMU with
2451 same multicast address maddr and port. NOTES:
2452 1. Several QEMU can be running on different hosts and share same
2454 bus (assuming correct multicast setup for these hosts).
2455 2. mcast support is compatible with User Mode Linux (argument
2457 ethN=mcast), see http://user-mode-linux.sf.net.
2458 3. Use fd=h to specify an already opened UDP multicast socket.
2460 Example:
2462 # launch one QEMU instance
2464 qemu-system-x86_64 linux.img \
2465 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2466 -netdev socket,id=n1,mcast=230.0.0.1:1234
2467 # launch another QEMU instance on same "bus"
2468 qemu-system-x86_64 linux.img \
2469 -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
2470 -netdev socket,id=n2,mcast=230.0.0.1:1234
2471 # launch yet another QEMU instance on same "bus"
2472 qemu-system-x86_64 linux.img \
2473 -device e1000,netdev=n3,mac=52:54:00:12:34:58 \
2474 -netdev socket,id=n3,mcast=230.0.0.1:1234
2475 Example (User Mode Linux compat.):
2477 # launch QEMU instance (note mcast address selected is UML's default)
2479 qemu-system-x86_64 linux.img \
2480 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2481 -netdev socket,id=n1,mcast=239.192.168.1:1102
2482 # launch UML
2483 /path/to/linux ubd0=/path/to/root_fs eth0=mcast
2484 Example (send packets from host's 1.2.3.4):
2486 qemu-system-x86_64 linux.img \
2488 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2489 -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4
2490 -netdev l2tpv3,id=id,src=srcaddr,dst=dstaddr[,srcport=srcport][,dst‐
2492 port=dstport],txsession=txsession[,rxsession=rxses‐
2493 sion][,ipv6=on|off][,udp=on|off][,cookie64][,counter][,pincounter][,tx‐
2494 cookie=txcookie][,rxcookie=rxcookie][,offset=offset]
2495 Configure a L2TPv3 pseudowire host network backend. L2TPv3
2496 (RFC3931) is a popular protocol to transport Ethernet (and other
2497 Layer 2) data frames between two systems. It is present in
2498 routers, firewalls and the Linux kernel (from version 3.3 on‐
2499 wards).
2500 This transport allows a VM to communicate to another VM, router
2502 or firewall directly.
2503 src=srcaddr
2505 source address (mandatory)
2506 dst=dstaddr
2508 destination address (mandatory)
2509 udp select udp encapsulation (default is ip).
2511 srcport=srcport
2513 source udp port.
2514 dstport=dstport
2516 destination udp port.
2517 ipv6 force v6, otherwise defaults to v4.
2519 rxcookie=rxcookie; txcookie=txcookie
2521 Cookies are a weak form of security in the l2tpv3 speci‐
2522 fication. Their function is mostly to prevent misconfig‐
2523 uration. By default they are 32 bit.
2524 cookie64
2526 Set cookie size to 64 bit instead of the default 32
2527 counter=off
2529 Force a 'cut-down' L2TPv3 with no counter as in
2530 draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
2531 pincounter=on
2533 Work around broken counter handling in peer. This may
2534 also help on networks which have packet reorder.
2535 offset=offset
2537 Add an extra offset between header and data
2538 For example, to attach a VM running on host 4.3.2.1 via L2TPv3
2540 to the bridge br-lan on the remote Linux host 1.2.3.4:
2541 # Setup tunnel on linux host using raw ip as encapsulation
2543 # on 1.2.3.4
2544 ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \
2545 encap udp udp_sport 16384 udp_dport 16384
2546 ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \
2547 0xFFFFFFFF peer_session_id 0xFFFFFFFF
2548 ifconfig vmtunnel0 mtu 1500
2549 ifconfig vmtunnel0 up
2550 brctl addif br-lan vmtunnel0
2551 # on 4.3.2.1
2554 # launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
2555 qemu-system-x86_64 linux.img -device e1000,netdev=n1 \
2557 -netdev l2tpv3,id=n1,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter
2558 -netdev vde,id=id[,sock=socketpath][,port=n][,group=group‐
2560 name][,mode=octalmode]
2561 Configure VDE backend to connect to PORT n of a vde switch run‐
2562 ning on host and listening for incoming connections on socket‐
2563 path. Use GROUP groupname and MODE octalmode to change default
2564 ownership and permissions for communication port. This option is
2565 only available if QEMU has been compiled with vde support en‐
2566 abled.
2567 Example:
2569 # launch vde switch
2571 vde_switch -F -sock /tmp/myswitch
2572 # launch QEMU instance
2573 qemu-system-x86_64 linux.img -nic vde,sock=/tmp/myswitch
2574 -netdev vhost-user,chardev=id[,vhostforce=on|off][,queues=n]
2576 Establish a vhost-user netdev, backed by a chardev id. The
2577 chardev should be a unix domain socket backed one. The
2578 vhost-user uses a specifically defined protocol to pass vhost
2579 ioctl replacement messages to an application on the other end of
2580 the socket. On non-MSIX guests, the feature can be forced with
2581 vhostforce. Use 'queues=n' to specify the number of queues to be
2582 created for multiqueue vhost-user.
2583 Example:
2585 qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
2587 -numa node,memdev=mem \
2588 -chardev socket,id=chr0,path=/path/to/socket \
2589 -netdev type=vhost-user,id=net0,chardev=chr0 \
2590 -device virtio-net-pci,netdev=net0
2591 -netdev vhost-vdpa,vhostdev=/path/to/dev
2593 Establish a vhost-vdpa netdev.
2594 vDPA device is a device that uses a datapath which complies with
2596 the virtio specifications with a vendor specific control path.
2597 vDPA devices can be both physically located on the hardware or
2598 emulated by software.
2599 -netdev hubport,id=id,hubid=hubid[,netdev=nd]
2601 Create a hub port on the emulated hub with ID hubid.
2602 The hubport netdev lets you connect a NIC to a QEMU emulated hub
2604 instead of a single netdev. Alternatively, you can also connect
2605 the hubport to another netdev with ID nd by using the netdev=nd
2606 option.
2607 -net nic[,netdev=nd][,macaddr=mac][,model=type]
2609 [,name=name][,addr=addr][,vectors=v]
2610 Legacy option to configure or create an on-board (or machine de‐
2611 fault) Network Interface Card(NIC) and connect it either to the
2612 emulated hub with ID 0 (i.e. the default hub), or to the netdev
2613 nd. If model is omitted, then the default NIC model associated
2614 with the machine type is used. Note that the default NIC model
2615 may change in future QEMU releases, so it is highly recommended
2616 to always specify a model. Optionally, the MAC address can be
2617 changed to mac, the device address set to addr (PCI cards only),
2618 and a name can be assigned for use in monitor commands. Option‐
2619 ally, for PCI cards, you can specify the number v of MSI-X vec‐
2620 tors that the card should have; this option currently only af‐
2621 fects virtio cards; set v = 0 to disable MSI-X. If no -net op‐
2622 tion is specified, a single NIC is created. QEMU can emulate
2623 several different models of network card. Use -net
2624 nic,model=help for a list of available devices for your target.
2625 -net user|tap|bridge|socket|l2tpv3|vde[,...][,name=name]
2627 Configure a host network backend (with the options corresponding
2628 to the same -netdev option) and connect it to the emulated hub 0
2629 (the default hub). Use name to specify the name of the hub port.
2630 Character device options
2632 The general form of a character device option is:
2633 -chardev backend,id=id[,mux=on|off][,options]
2635 Backend is one of: null, socket, udp, msmouse, vc, ringbuf,
2636 file, pipe, console, serial, pty, stdio, braille, tty, parallel,
2637 parport, spicevmc, spiceport. The specific backend will deter‐
2638 mine the applicable options.
2639 Use -chardev help to print all available chardev backend types.
2641 All devices must have an id, which can be any string up to 127
2643 characters long. It is used to uniquely identify this device in
2644 other command line directives.
2645 A character device may be used in multiplexing mode by multiple
2647 front-ends. Specify mux=on to enable this mode. A multiplexer is
2648 a "1:N" device, and here the "1" end is your specified chardev
2649 backend, and the "N" end is the various parts of QEMU that can
2650 talk to a chardev. If you create a chardev with id=myid and
2651 mux=on, QEMU will create a multiplexer with your specified ID,
2652 and you can then configure multiple front ends to use that
2653 chardev ID for their input/output. Up to four different front
2654 ends can be connected to a single multiplexed chardev. (Without
2655 multiplexing enabled, a chardev can only be used by a single
2656 front end.) For instance you could use this to allow a single
2657 stdio chardev to be used by two serial ports and the QEMU moni‐
2658 tor:
2659 -chardev stdio,mux=on,id=char0 \
2661 -mon chardev=char0,mode=readline \
2662 -serial chardev:char0 \
2663 -serial chardev:char0
2664 You can have more than one multiplexer in a system configura‐
2666 tion; for instance you could have a TCP port multiplexed between
2667 UART 0 and UART 1, and stdio multiplexed between the QEMU moni‐
2668 tor and a parallel port:
2669 -chardev stdio,mux=on,id=char0 \
2671 -mon chardev=char0,mode=readline \
2672 -parallel chardev:char0 \
2673 -chardev tcp,...,mux=on,id=char1 \
2674 -serial chardev:char1 \
2675 -serial chardev:char1
2676 When you're using a multiplexed character device, some escape
2678 sequences are interpreted in the input. See the chapter about
2679 keys in the character backend multiplexer in the System Emula‐
2680 tion Users Guide for more details.
2681 Note that some other command line options may implicitly create
2683 multiplexed character backends; for instance -serial mon:stdio
2684 creates a multiplexed stdio backend connected to the serial port
2685 and the QEMU monitor, and -nographic also multiplexes the con‐
2686 sole and the monitor to stdio.
2687 There is currently no support for multiplexing in the other di‐
2689 rection (where a single QEMU front end takes input and output
2690 from multiple chardevs).
2691 Every backend supports the logfile option, which supplies the
2693 path to a file to record all data transmitted via the backend.
2694 The logappend option controls whether the log file will be trun‐
2695 cated or appended to when opened.
2696 The available backends are:
2698 -chardev null,id=id
2700 A void device. This device will not emit any data, and will drop
2701 any data it receives. The null backend does not take any op‐
2702 tions.
2703 -chardev socket,id=id[,TCP options or unix op‐
2705 tions][,server=on|off][,wait=on|off][,telnet=on|off][,web‐
2706 socket=on|off][,reconnect=seconds][,tls-creds=id][,tls-authz=id]
2707 Create a two-way stream socket, which can be either a TCP or a
2708 unix socket. A unix socket will be created if path is specified.
2709 Behaviour is undefined if TCP options are specified for a unix
2710 socket.
2711 server=on|off specifies that the socket shall be a listening
2713 socket.
2714 wait=on|off specifies that QEMU should not block waiting for a
2716 client to connect to a listening socket.
2717 telnet=on|off specifies that traffic on the socket should inter‐
2719 pret telnet escape sequences.
2720 websocket=on|off specifies that the socket uses WebSocket proto‐
2722 col for communication.
2723 reconnect sets the timeout for reconnecting on non-server sock‐
2725 ets when the remote end goes away. qemu will delay this many
2726 seconds and then attempt to reconnect. Zero disables reconnect‐
2727 ing, and is the default.
2728 tls-creds requests enablement of the TLS protocol for encryp‐
2730 tion, and specifies the id of the TLS credentials to use for the
2731 handshake. The credentials must be previously created with the
2732 -object tls-creds argument.
2733 tls-auth provides the ID of the QAuthZ authorization object
2735 against which the client's x509 distinguished name will be vali‐
2736 dated. This object is only resolved at time of use, so can be
2737 deleted and recreated on the fly while the chardev server is ac‐
2738 tive. If missing, it will default to denying access.
2739 TCP and unix socket options are given below:
2741 TCP options:
2743 port=port[,host=host][,to=to][,ipv4=on|off][,ipv6=on|off][,node‐
2744 lay=on|off]
2745 host for a listening socket specifies the local address
2746 to be bound. For a connecting socket species the remote
2747 host to connect to. host is optional for listening sock‐
2748 ets. If not specified it defaults to 0.0.0.0.
2749 port for a listening socket specifies the local port to
2751 be bound. For a connecting socket specifies the port on
2752 the remote host to connect to. port can be given as ei‐
2753 ther a port number or a service name. port is required.
2754 to is only relevant to listening sockets. If it is speci‐
2756 fied, and port cannot be bound, QEMU will attempt to bind
2757 to subsequent ports up to and including to until it suc‐
2758 ceeds. to must be specified as a port number.
2759 ipv4=on|off and ipv6=on|off specify that either IPv4 or
2761 IPv6 must be used. If neither is specified the socket may
2762 use either protocol.
2763 nodelay=on|off disables the Nagle algorithm.
2765 unix options: path=path[,abstract=on|off][,tight=on|off]
2767 path specifies the local path of the unix socket. path is
2768 required. abstract=on|off specifies the use of the ab‐
2769 stract socket namespace, rather than the filesystem. Op‐
2770 tional, defaults to false. tight=on|off sets the socket
2771 length of abstract sockets to their minimum, rather than
2772 the full sun_path length. Optional, defaults to true.
2773 -chardev udp,id=id[,host=host],port=port[,localaddr=localaddr][,local‐
2775 port=localport][,ipv4=on|off][,ipv6=on|off]
2776 Sends all traffic from the guest to a remote host over UDP.
2777 host specifies the remote host to connect to. If not specified
2779 it defaults to localhost.
2780 port specifies the port on the remote host to connect to. port
2782 is required.
2783 localaddr specifies the local address to bind to. If not speci‐
2785 fied it defaults to 0.0.0.0.
2786 localport specifies the local port to bind to. If not specified
2788 any available local port will be used.
2789 ipv4=on|off and ipv6=on|off specify that either IPv4 or IPv6
2791 must be used. If neither is specified the device may use either
2792 protocol.
2793 -chardev msmouse,id=id
2795 Forward QEMU's emulated msmouse events to the guest. msmouse
2796 does not take any options.
2797 -chardev
2799 vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]
2800 Connect to a QEMU text console. vc may optionally be given a
2801 specific size.
2802 width and height specify the width and height respectively of
2804 the console, in pixels.
2805 cols and rows specify that the console be sized to fit a text
2807 console with the given dimensions.
2808 -chardev ringbuf,id=id[,size=size]
2810 Create a ring buffer with fixed size size. size must be a power
2811 of two and defaults to 64K.
2812 -chardev file,id=id,path=path
2814 Log all traffic received from the guest to a file.
2815 path specifies the path of the file to be opened. This file will
2817 be created if it does not already exist, and overwritten if it
2818 does. path is required.
2819 -chardev pipe,id=id,path=path
2821 Create a two-way connection to the guest. The behaviour differs
2822 slightly between Windows hosts and other hosts:
2823 On Windows, a single duplex pipe will be created at
2825 \\.pipe\path.
2826 On other hosts, 2 pipes will be created called path.in and
2828 path.out. Data written to path.in will be received by the guest.
2829 Data written by the guest can be read from path.out. QEMU will
2830 not create these fifos, and requires them to be present.
2831 path forms part of the pipe path as described above. path is re‐
2833 quired.
2834 -chardev console,id=id
2836 Send traffic from the guest to QEMU's standard output. console
2837 does not take any options.
2838 console is only available on Windows hosts.
2840 -chardev serial,id=id,path=path
2842 Send traffic from the guest to a serial device on the host.
2843 On Unix hosts serial will actually accept any tty device, not
2845 only serial lines.
2846 path specifies the name of the serial device to open.
2848 -chardev pty,id=id
2850 Create a new pseudo-terminal on the host and connect to it. pty
2851 does not take any options.
2852 pty is not available on Windows hosts.
2854 -chardev stdio,id=id[,signal=on|off]
2856 Connect to standard input and standard output of the QEMU
2857 process.
2858 signal controls if signals are enabled on the terminal, that in‐
2860 cludes exiting QEMU with the key sequence Control-c. This option
2861 is enabled by default, use signal=off to disable it.
2862 -chardev braille,id=id
2864 Connect to a local BrlAPI server. braille does not take any op‐
2865 tions.
2866 -chardev tty,id=id,path=path
2868 tty is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD
2869 and DragonFlyBSD hosts. It is an alias for serial.
2870 path specifies the path to the tty. path is required.
2872 -chardev parallel,id=id,path=path
2874 -chardev parport,id=id,path=path
2877 parallel is only available on Linux, FreeBSD and DragonFlyBSD
2878 hosts.
2879 Connect to a local parallel port.
2881 path specifies the path to the parallel port device. path is re‐
2883 quired.
2884 -chardev spicevmc,id=id,debug=debug,name=name
2886 spicevmc is only available when spice support is built in.
2887 debug debug level for spicevmc
2889 name name of spice channel to connect to
2891 Connect to a spice virtual machine channel, such as vdiport.
2893 -chardev spiceport,id=id,debug=debug,name=name
2895 spiceport is only available when spice support is built in.
2896 debug debug level for spicevmc
2898 name name of spice port to connect to
2900 Connect to a spice port, allowing a Spice client to handle the
2902 traffic identified by a name (preferably a fqdn).
2903 TPM device options
2905 The general form of a TPM device option is:
2906 -tpmdev backend,id=id[,options]
2908 The specific backend type will determine the applicable options.
2909 The -tpmdev option creates the TPM backend and requires a -de‐
2910 vice option that specifies the TPM frontend interface model.
2911 Use -tpmdev help to print all available TPM backend types.
2913 The available backends are:
2915 -tpmdev passthrough,id=id,path=path,cancel-path=cancel-path
2917 (Linux-host only) Enable access to the host's TPM using the
2918 passthrough driver.
2919 path specifies the path to the host's TPM device, i.e., on a
2921 Linux host this would be /dev/tpm0. path is optional and by de‐
2922 fault /dev/tpm0 is used.
2923 cancel-path specifies the path to the host TPM device's sysfs
2925 entry allowing for cancellation of an ongoing TPM command. can‐
2926 cel-path is optional and by default QEMU will search for the
2927 sysfs entry to use.
2928 Some notes about using the host's TPM with the passthrough
2930 driver:
2931 The TPM device accessed by the passthrough driver must not be
2933 used by any other application on the host.
2934 Since the host's firmware (BIOS/UEFI) has already initialized
2936 the TPM, the VM's firmware (BIOS/UEFI) will not be able to ini‐
2937 tialize the TPM again and may therefore not show a TPM-specific
2938 menu that would otherwise allow the user to configure the TPM,
2939 e.g., allow the user to enable/disable or activate/deactivate
2940 the TPM. Further, if TPM ownership is released from within a VM
2941 then the host's TPM will get disabled and deactivated. To enable
2942 and activate the TPM again afterwards, the host has to be re‐
2943 booted and the user is required to enter the firmware's menu to
2944 enable and activate the TPM. If the TPM is left disabled and/or
2945 deactivated most TPM commands will fail.
2946 To create a passthrough TPM use the following two options:
2948 -tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
2950 Note that the -tpmdev id is tpm0 and is referenced by tp‐
2952 mdev=tpm0 in the device option.
2953 -tpmdev emulator,id=id,chardev=dev
2955 (Linux-host only) Enable access to a TPM emulator using Unix do‐
2956 main socket based chardev backend.
2957 chardev specifies the unique ID of a character device backend
2959 that provides connection to the software TPM server.
2960 To create a TPM emulator backend device with chardev socket
2962 backend:
2963 -chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0
2965 Linux/Multiboot boot specific
2967 When using these options, you can use a given Linux or Multiboot kernel
2968 without installing it in the disk image. It can be useful for easier
2969 testing of various kernels.
2970 -kernel bzImage
2972 Use bzImage as kernel image. The kernel can be either a Linux
2973 kernel or in multiboot format.
2974 -append cmdline
2976 Use cmdline as kernel command line
2977 -initrd file
2979 Use file as initial ram disk.
2980 -initrd file1 arg=foo,file2
2982 This syntax is only available with multiboot.
2983 Use file1 and file2 as modules and pass arg=foo as parameter to
2985 the first module.
2986 -dtb file
2988 Use file as a device tree binary (dtb) image and pass it to the
2989 kernel on boot.
2990 Debug/Expert options
2992 -compat [deprecated-input=@var{input-policy}][,deprecated-out‐
2993 put=@var{output-policy}]
2994 Set policy for handling deprecated management interfaces (exper‐
2995 imental):
2996 deprecated-input=accept (default)
2998 Accept deprecated commands and arguments
2999 deprecated-input=reject
3001 Reject deprecated commands and arguments
3002 deprecated-input=crash
3004 Crash on deprecated commands and arguments
3005 deprecated-output=accept (default)
3007 Emit deprecated command results and events
3008 deprecated-output=hide
3010 Suppress deprecated command results and events
3011 Limitation: covers only syntactic aspects of QMP.
3013 -compat [unstable-input=@var{input-policy}][,unstable-output=@var{out‐
3015 put-policy}]
3016 Set policy for handling unstable management interfaces (experi‐
3017 mental):
3018 unstable-input=accept (default)
3020 Accept unstable commands and arguments
3021 unstable-input=reject
3023 Reject unstable commands and arguments
3024 unstable-input=crash
3026 Crash on unstable commands and arguments
3027 unstable-output=accept (default)
3029 Emit unstable command results and events
3030 unstable-output=hide
3032 Suppress unstable command results and events
3033 Limitation: covers only syntactic aspects of QMP.
3035 -fw_cfg [name=]name,file=file
3037 Add named fw_cfg entry with contents from file file.
3038 -fw_cfg [name=]name,string=str
3040 Add named fw_cfg entry with contents from string str.
3041 The terminating NUL character of the contents of str will not be
3043 included as part of the fw_cfg item data. To insert contents
3044 with embedded NUL characters, you have to use the file parame‐
3045 ter.
3046 The fw_cfg entries are passed by QEMU through to the guest.
3048 Example:
3050 -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
3052 creates an fw_cfg entry named opt/com.mycompany/blob with con‐
3054 tents from ./my_blob.bin.
3055 -serial dev
3057 Redirect the virtual serial port to host character device dev.
3058 The default device is vc in graphical mode and stdio in non
3059 graphical mode.
3060 This option can be used several times to simulate up to 4 serial
3062 ports.
3063 Use -serial none to disable all serial ports.
3065 Available character devices are:
3067 vc[:WxH]
3069 Virtual console. Optionally, a width and height can be
3070 given in pixel with
3071 vc:800x600
3073 It is also possible to specify width or height in charac‐
3075 ters:
3076 vc:80Cx24C
3078 pty [Linux only] Pseudo TTY (a new PTY is automatically allo‐
3080 cated)
3081 none No device is allocated.
3083 null void device
3085 chardev:id
3087 Use a named character device defined with the -chardev
3088 option.
3089 /dev/XXX
3091 [Linux only] Use host tty, e.g. /dev/ttyS0. The host se‐
3092 rial port parameters are set according to the emulated
3093 ones.
3094 /dev/parportN
3096 [Linux only, parallel port only] Use host parallel port
3097 N. Currently SPP and EPP parallel port features can be
3098 used.
3099 file:filename
3101 Write output to filename. No character can be read.
3102 stdio [Unix only] standard input/output
3104 pipe:filename
3106 name pipe filename
3107 COMn [Windows only] Use host serial port n
3109 udp:[remote_host]:remote_port[@[src_ip]:src_port]
3111 This implements UDP Net Console. When remote_host or
3112 src_ip are not specified they default to 0.0.0.0. When
3113 not using a specified src_port a random port is automati‐
3114 cally chosen.
3115 If you just want a simple readonly console you can use
3117 netcat or nc, by starting QEMU with: -serial udp::4555
3118 and nc as: nc -u -l -p 4555. Any time QEMU writes some‐
3119 thing to that port it will appear in the netconsole ses‐
3120 sion.
3121 If you plan to send characters back via netconsole or you
3123 want to stop and start QEMU a lot of times, you should
3124 have QEMU use the same source port each time by using
3125 something like -serial udp::4555@:4556 to QEMU. Another
3126 approach is to use a patched version of netcat which can
3127 listen to a TCP port and send and receive characters via
3128 udp. If you have a patched version of netcat which acti‐
3129 vates telnet remote echo and single char transfer, then
3130 you can use the following options to set up a netcat
3131 redirector to allow telnet on port 5555 to access the
3132 QEMU port.
3133 QEMU Options:
3135 -serial udp::4555@:4556
3136 netcat options:
3138 -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
3139 telnet options:
3141 localhost 5555
3142 tcp:[host]:port[,server=on|off][,wait=on|off][,node‐
3144 lay=on|off][,reconnect=seconds]
3145 The TCP Net Console has two modes of operation. It can
3146 send the serial I/O to a location or wait for a connec‐
3147 tion from a location. By default the TCP Net Console is
3148 sent to host at the port. If you use the server=on option
3149 QEMU will wait for a client socket application to connect
3150 to the port before continuing, unless the wait=on|off op‐
3151 tion was specified. The nodelay=on|off option disables
3152 the Nagle buffering algorithm. The reconnect=on option
3153 only applies if server=no is set, if the connection goes
3154 down it will attempt to reconnect at the given interval.
3155 If host is omitted, 0.0.0.0 is assumed. Only one TCP con‐
3156 nection at a time is accepted. You can use telnet=on to
3157 connect to the corresponding character device.
3158 Example to send tcp console to 192.168.0.2 port 4444
3160 -serial tcp:192.168.0.2:4444
3161 Example to listen and wait on port 4444 for connection
3163 -serial tcp::4444,server=on
3164 Example to not wait and listen on ip 192.168.0.100 port
3166 4444
3167 -serial tcp:192.168.0.100:4444,server=on,wait=off
3168 telnet:host:port[,server=on|off][,wait=on|off][,nodelay=on|off]
3170 The telnet protocol is used instead of raw tcp sockets.
3171 The options work the same as if you had specified -serial
3172 tcp. The difference is that the port acts like a telnet
3173 server or client using telnet option negotiation. This
3174 will also allow you to send the MAGIC_SYSRQ sequence if
3175 you use a telnet that supports sending the break se‐
3176 quence. Typically in unix telnet you do it with Control-]
3177 and then type "send break" followed by pressing the enter
3178 key.
3179 websocket:host:port,server=on[,wait=on|off][,nodelay=on|off]
3181 The WebSocket protocol is used instead of raw tcp socket.
3182 The port acts as a WebSocket server. Client mode is not
3183 supported.
3184 unix:path[,server=on|off][,wait=on|off][,reconnect=seconds]
3186 A unix domain socket is used instead of a tcp socket. The
3187 option works the same as if you had specified -serial tcp
3188 except the unix domain socket path is used for connec‐
3189 tions.
3190 mon:dev_string
3192 This is a special option to allow the monitor to be mul‐
3193 tiplexed onto another serial port. The monitor is ac‐
3194 cessed with key sequence of Control-a and then pressing
3195 c. dev_string should be any one of the serial devices
3196 specified above. An example to multiplex the monitor onto
3197 a telnet server listening on port 4444 would be:
3198 -serial mon:telnet::4444,server=on,wait=off
3200 When the monitor is multiplexed to stdio in this way,
3202 Ctrl+C will not terminate QEMU any more but will be
3203 passed to the guest instead.
3204 braille
3206 Braille device. This will use BrlAPI to display the
3207 braille output on a real or fake device.
3208 msmouse
3210 Three button serial mouse. Configure the guest to use Mi‐
3211 crosoft protocol.
3212 -parallel dev
3214 Redirect the virtual parallel port to host device dev (same de‐
3215 vices as the serial port). On Linux hosts, /dev/parportN can be
3216 used to use hardware devices connected on the corresponding host
3217 parallel port.
3218 This option can be used several times to simulate up to 3 paral‐
3220 lel ports.
3221 Use -parallel none to disable all parallel ports.
3223 -monitor dev
3225 Redirect the monitor to host device dev (same devices as the se‐
3226 rial port). The default device is vc in graphical mode and stdio
3227 in non graphical mode. Use -monitor none to disable the default
3228 monitor.
3229 -qmp dev
3231 Like -monitor but opens in 'control' mode.
3232 -qmp-pretty dev
3234 Like -qmp but uses pretty JSON formatting.
3235 -mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]
3237 Setup monitor on chardev name. mode=control configures a QMP
3238 monitor (a JSON RPC-style protocol) and it is not the same as
3239 HMP, the human monitor that has a "(qemu)" prompt. pretty is
3240 only valid when mode=control, turning on JSON pretty printing to
3241 ease human reading and debugging.
3242 -debugcon dev
3244 Redirect the debug console to host device dev (same devices as
3245 the serial port). The debug console is an I/O port which is typ‐
3246 ically port 0xe9; writing to that I/O port sends output to this
3247 device. The default device is vc in graphical mode and stdio in
3248 non graphical mode.
3249 -pidfile file
3251 Store the QEMU process PID in file. It is useful if you launch
3252 QEMU from a script.
3253 -singlestep
3255 Run the emulation in single step mode.
3256 --preconfig
3258 Pause QEMU for interactive configuration before the machine is
3259 created, which allows querying and configuring properties that
3260 will affect machine initialization. Use QMP command 'x-exit-pre‐
3261 config' to exit the preconfig state and move to the next state
3262 (i.e. run guest if -S isn't used or pause the second time if -S
3263 is used). This option is experimental.
3264 -S Do not start CPU at startup (you must type 'c' in the monitor).
3266 -overcommit mem-lock=on|off
3268 -overcommit cpu-pm=on|off
3271 Run qemu with hints about host resource overcommit. The default
3272 is to assume that host overcommits all resources.
3273 Locking qemu and guest memory can be enabled via mem-lock=on
3275 (disabled by default). This works when host memory is not over‐
3276 committed and reduces the worst-case latency for guest.
3277 Guest ability to manage power state of host cpus (increasing la‐
3279 tency for other processes on the same host cpu, but decreasing
3280 latency for guest) can be enabled via cpu-pm=on (disabled by de‐
3281 fault). This works best when host CPU is not overcommitted. When
3282 used, host estimates of CPU cycle and power utilization will be
3283 incorrect, not taking into account guest idle time.
3284 -gdb dev
3286 Accept a gdb connection on device dev (see the GDB usage chapter
3287 in the System Emulation Users Guide). Note that this option does
3288 not pause QEMU execution -- if you want QEMU to not start the
3289 guest until you connect with gdb and issue a continue command,
3290 you will need to also pass the -S option to QEMU.
3291 The most usual configuration is to listen on a local TCP socket:
3293 -gdb tcp::3117
3295 but you can specify other backends; UDP, pseudo TTY, or even
3297 stdio are all reasonable use cases. For example, a stdio connec‐
3298 tion allows you to start QEMU from within gdb and establish the
3299 connection via a pipe:
3300 (gdb) target remote | exec qemu-system-x86_64 -gdb stdio ...
3302 -s Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port
3304 1234 (see the GDB usage chapter in the System Emulation Users
3305 Guide).
3306 -d item1[,...]
3308 Enable logging of specified items. Use '-d help' for a list of
3309 log items.
3310 -D logfile
3312 Output log in logfile instead of to stderr
3313 -dfilter range1[,...]
3315 Filter debug output to that relevant to a range of target ad‐
3316 dresses. The filter spec can be either start+size, start-size
3317 or start..end where start end and size are the addresses and
3318 sizes required. For example:
3319 -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000
3321 Will dump output for any code in the 0x1000 sized block starting
3323 at 0x8000 and the 0x200 sized block starting at
3324 0xffffffc000080000 and another 0x1000 sized block starting at
3325 0xffffffc00005f000.
3326 -seed number
3328 Force the guest to use a deterministic pseudo-random number gen‐
3329 erator, seeded with number. This does not affect crypto routines
3330 within the host.
3331 -L path
3333 Set the directory for the BIOS, VGA BIOS and keymaps.
3334 To list all the data directories, use -L help.
3336 -bios file
3338 Set the filename for the BIOS.
3339 -enable-kvm
3341 Enable KVM full virtualization support. This option is only
3342 available if KVM support is enabled when compiling.
3343 -xen-domid id
3345 Specify xen guest domain id (XEN only).
3346 -xen-attach
3348 Attach to existing xen domain. libxl will use this when starting
3349 QEMU (XEN only). Restrict set of available xen operations to
3350 specified domain id (XEN only).
3351 -no-reboot
3353 Exit instead of rebooting.
3354 -no-shutdown
3356 Don't exit QEMU on guest shutdown, but instead only stop the em‐
3357 ulation. This allows for instance switching to monitor to commit
3358 changes to the disk image.
3359 -action event=action
3361 The action parameter serves to modify QEMU's default behavior
3362 when certain guest events occur. It provides a generic method
3363 for specifying the same behaviors that are modified by the
3364 -no-reboot and -no-shutdown parameters.
3365 Examples:
3367 -action panic=none -action reboot=shutdown,shutdown=pause
3369 -watchdog i6300esb -action watchdog=pause
3370 -loadvm file
3372 Start right away with a saved state (loadvm in monitor)
3373 -daemonize
3375 Daemonize the QEMU process after initialization. QEMU will not
3376 detach from standard IO until it is ready to receive connections
3377 on any of its devices. This option is a useful way for external
3378 programs to launch QEMU without having to cope with initializa‐
3379 tion race conditions.
3380 -option-rom file
3382 Load the contents of file as an option ROM. This option is use‐
3383 ful to load things like EtherBoot.
3384 -rtc [base=utc|localtime|datetime][,clock=host|rt|vm][,drift‐
3386 fix=none|slew]
3387 Specify base as utc or localtime to let the RTC start at the
3388 current UTC or local time, respectively. localtime is required
3389 for correct date in MS-DOS or Windows. To start at a specific
3390 point in time, provide datetime in the format
3391 2006-06-17T16:01:21 or 2006-06-17. The default base is UTC.
3392 By default the RTC is driven by the host system time. This al‐
3394 lows using of the RTC as accurate reference clock inside the
3395 guest, specifically if the host time is smoothly following an
3396 accurate external reference clock, e.g. via NTP. If you want to
3397 isolate the guest time from the host, you can set clock to rt
3398 instead, which provides a host monotonic clock if host support
3399 it. To even prevent the RTC from progressing during suspension,
3400 you can set clock to vm (virtual clock). 'clock=vm' is recom‐
3401 mended especially in icount mode in order to preserve determin‐
3402 ism; however, note that in icount mode the speed of the virtual
3403 clock is variable and can in general differ from the host clock.
3404 Enable driftfix (i386 targets only) if you experience time drift
3406 problems, specifically with Windows' ACPI HAL. This option will
3407 try to figure out how many timer interrupts were not processed
3408 by the Windows guest and will re-inject them.
3409 -icount [shift=N|auto][,align=on|off][,sleep=on|off][,rr=record|re‐
3411 play,rrfile=filename[,rrsnapshot=snapshot]]
3412 Enable virtual instruction counter. The virtual cpu will execute
3413 one instruction every 2^N ns of virtual time. If auto is speci‐
3414 fied then the virtual cpu speed will be automatically adjusted
3415 to keep virtual time within a few seconds of real time.
3416 Note that while this option can give deterministic behavior, it
3418 does not provide cycle accurate emulation. Modern CPUs contain
3419 superscalar out of order cores with complex cache hierarchies.
3420 The number of instructions executed often has little or no cor‐
3421 relation with actual performance.
3422 When the virtual cpu is sleeping, the virtual time will advance
3424 at default speed unless sleep=on is specified. With sleep=on,
3425 the virtual time will jump to the next timer deadline instantly
3426 whenever the virtual cpu goes to sleep mode and will not advance
3427 if no timer is enabled. This behavior gives deterministic execu‐
3428 tion times from the guest point of view. The default if icount
3429 is enabled is sleep=off. sleep=on cannot be used together with
3430 either shift=auto or align=on.
3431 align=on will activate the delay algorithm which will try to
3433 synchronise the host clock and the virtual clock. The goal is to
3434 have a guest running at the real frequency imposed by the shift
3435 option. Whenever the guest clock is behind the host clock and if
3436 align=on is specified then we print a message to the user to in‐
3437 form about the delay. Currently this option does not work when
3438 shift is auto. Note: The sync algorithm will work for those
3439 shift values for which the guest clock runs ahead of the host
3440 clock. Typically this happens when the shift value is high (how
3441 high depends on the host machine). The default if icount is en‐
3442 abled is align=off.
3443 When the rr option is specified deterministic record/replay is
3445 enabled. The rrfile= option must also be provided to specify the
3446 path to the replay log. In record mode data is written to this
3447 file, and in replay mode it is read back. If the rrsnapshot op‐
3448 tion is given then it specifies a VM snapshot name. In record
3449 mode, a new VM snapshot with the given name is created at the
3450 start of execution recording. In replay mode this option speci‐
3451 fies the snapshot name used to load the initial VM state.
3452 -watchdog model
3454 Create a virtual hardware watchdog device. Once enabled (by a
3455 guest action), the watchdog must be periodically polled by an
3456 agent inside the guest or else the guest will be restarted.
3457 Choose a model for which your guest has drivers.
3458 The model is the model of hardware watchdog to emulate. Use
3460 -watchdog help to list available hardware models. Only one
3461 watchdog can be enabled for a guest.
3462 The following models may be available:
3464 ib700 iBASE 700 is a very simple ISA watchdog with a single
3466 timer.
3467 i6300esb
3469 Intel 6300ESB I/O controller hub is a much more feature‐
3470 ful PCI-based dual-timer watchdog.
3471 diag288
3473 A virtual watchdog for s390x backed by the diagnose 288
3474 hypercall (currently KVM only).
3475 -watchdog-action action
3477 The action controls what QEMU will do when the watchdog timer
3478 expires. The default is reset (forcefully reset the guest).
3479 Other possible actions are: shutdown (attempt to gracefully
3480 shutdown the guest), poweroff (forcefully poweroff the guest),
3481 inject-nmi (inject a NMI into the guest), pause (pause the
3482 guest), debug (print a debug message and continue), or none (do
3483 nothing).
3484 Note that the shutdown action requires that the guest responds
3486 to ACPI signals, which it may not be able to do in the sort of
3487 situations where the watchdog would have expired, and thus
3488 -watchdog-action shutdown is not recommended for production use.
3489 Examples:
3491 -watchdog i6300esb -watchdog-action pause; -watchdog ib700
3493 -echr numeric_ascii_value
3495 Change the escape character used for switching to the monitor
3496 when using monitor and serial sharing. The default is 0x01 when
3497 using the -nographic option. 0x01 is equal to pressing Con‐
3498 trol-a. You can select a different character from the ascii con‐
3499 trol keys where 1 through 26 map to Control-a through Control-z.
3500 For instance you could use the either of the following to change
3501 the escape character to Control-t.
3502 -echr 0x14; -echr 20
3504 -incoming tcp:[host]:port[,to=maxport][,ipv4=on|off][,ipv6=on|off]
3506 -incoming rdma:host:port[,ipv4=on|off][,ipv6=on|off]
3509 Prepare for incoming migration, listen on a given tcp port.
3510 -incoming unix:socketpath
3512 Prepare for incoming migration, listen on a given unix socket.
3513 -incoming fd:fd
3515 Accept incoming migration from a given filedescriptor.
3516 -incoming exec:cmdline
3518 Accept incoming migration as an output from specified external
3519 command.
3520 -incoming defer
3522 Wait for the URI to be specified via migrate_incoming. The moni‐
3523 tor can be used to change settings (such as migration parame‐
3524 ters) prior to issuing the migrate_incoming to allow the migra‐
3525 tion to begin.
3526 -only-migratable
3528 Only allow migratable devices. Devices will not be allowed to
3529 enter an unmigratable state.
3530 -nodefaults
3532 Don't create default devices. Normally, QEMU sets the default
3533 devices like serial port, parallel port, virtual console, moni‐
3534 tor device, VGA adapter, floppy and CD-ROM drive and others. The
3535 -nodefaults option will disable all those default devices.
3536 -chroot dir
3538 Immediately before starting guest execution, chroot to the spec‐
3539 ified directory. Especially useful in combination with -runas.
3540 -runas user
3542 Immediately before starting guest execution, drop root privi‐
3543 leges, switching to the specified user.
3544 -prom-env variable=value
3546 Set OpenBIOS nvram variable to given value (PPC, SPARC only).
3547 qemu-system-sparc -prom-env 'auto-boot?=false' \
3549 -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
3550 qemu-system-ppc -prom-env 'auto-boot?=false' \
3552 -prom-env 'boot-device=hd:2,\yaboot' \
3553 -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
3554 -semihosting
3556 Enable semihosting mode (ARM, M68K, Xtensa, MIPS, Nios II,
3557 RISC-V only).
3558 Note that this allows guest direct access to the host filesys‐
3560 tem, so should only be used with a trusted guest OS.
3561 See the -semihosting-config option documentation for further in‐
3563 formation about the facilities this enables.
3564 -semihosting-config [enable=on|off][,target=na‐
3566 tive|gdb|auto][,chardev=id][,arg=str[,...]]
3567 Enable and configure semihosting (ARM, M68K, Xtensa, MIPS, Nios
3568 II, RISC-V only).
3569 Note that this allows guest direct access to the host filesys‐
3571 tem, so should only be used with a trusted guest OS.
3572 On Arm this implements the standard semihosting API, version
3574 2.0.
3575 On M68K this implements the "ColdFire GDB" interface used by
3577 libgloss.
3578 Xtensa semihosting provides basic file IO calls, such as
3580 open/read/write/seek/select. Tensilica baremetal libc for ISS
3581 and linux platform "sim" use this interface.
3582 On RISC-V this implements the standard semihosting API, version
3584 0.2.
3585 target=native|gdb|auto
3587 Defines where the semihosting calls will be addressed, to
3588 QEMU (native) or to GDB (gdb). The default is auto, which
3589 means gdb during debug sessions and native otherwise.
3590 chardev=str1
3592 Send the output to a chardev backend output for native or
3593 auto output when not in gdb
3594 arg=str1,arg=str2,...
3596 Allows the user to pass input arguments, and can be used
3597 multiple times to build up a list. The old-style -ker‐
3598 nel/-append method of passing a command line is still
3599 supported for backward compatibility. If both the --semi‐
3600 hosting-config arg and the -kernel/-append are specified,
3601 the former is passed to semihosting as it always takes
3602 precedence.
3603 -old-param
3605 Old param mode (ARM only).
3606 -sandbox arg[,obsolete=string][,elevateprivi‐
3608 leges=string][,spawn=string][,resourcecontrol=string]
3609 Enable Seccomp mode 2 system call filter. 'on' will enable
3610 syscall filtering and 'off' will disable it. The default is
3611 'off'.
3612 obsolete=string
3614 Enable Obsolete system calls
3615 elevateprivileges=string
3617 Disable set*uid|gid system calls
3618 spawn=string
3620 Disable *fork and execve
3621 resourcecontrol=string
3623 Disable process affinity and schedular priority
3624 -readconfig file
3626 Read device configuration from file. This approach is useful
3627 when you want to spawn QEMU process with many command line op‐
3628 tions but you don't want to exceed the command line character
3629 limit.
3630 -no-user-config
3632 The -no-user-config option makes QEMU not load any of the
3633 user-provided config files on sysconfdir.
3634 -trace [[enable=]pattern][,events=file][,file=file]
3636 Specify tracing options.
3637 [enable=]PATTERN
3639 Immediately enable events matching PATTERN (either event name
3640 or a globbing pattern). This option is only available if
3641 QEMU has been compiled with the simple, log or ftrace tracing
3642 backend. To specify multiple events or patterns, specify the
3643 -trace option multiple times.
3644 Use -trace help to print a list of names of trace points.
3646 events=FILE
3648 Immediately enable events listed in FILE. The file must con‐
3649 tain one event name (as listed in the trace-events-all file)
3650 per line; globbing patterns are accepted too. This option is
3651 only available if QEMU has been compiled with the simple, log
3652 or ftrace tracing backend.
3653 file=FILE
3655 Log output traces to FILE. This option is only available if
3656 QEMU has been compiled with the simple tracing backend.
3657 -plugin file=file[,argname=argvalue]
3659 Load a plugin.
3660 file=file
3662 Load the given plugin from a shared library file.
3663 argname=argvalue
3665 Argument passed to the plugin. (Can be given multiple
3666 times.)
3667 -enable-fips
3669 Enable FIPS 140-2 compliance mode.
3670 -msg [timestamp[=on|off]][,guest-name[=on|off]]
3672 Control error message format.
3673 timestamp=on|off
3675 Prefix messages with a timestamp. Default is off.
3676 guest-name=on|off
3678 Prefix messages with guest name but only if -name guest
3679 option is set otherwise the option is ignored. Default is
3680 off.
3681 -dump-vmstate file
3683 Dump json-encoded vmstate information for current machine type
3684 to file in file
3685 -enable-sync-profile
3687 Enable synchronization profiling.
3688 Generic object creation
3690 -object typename[,prop1=value1,...]
3691 Create a new object of type typename setting properties in the
3692 order they are specified. Note that the 'id' property must be
3693 set. These objects are placed in the '/objects' path.
3694 -object memory-back‐
3696 end-file,id=id,size=size,mem-path=dir,share=on|off,dis‐
3697 card-data=on|off,merge=on|off,dump=on|off,preal‐
3698 loc=on|off,host-nodes=host-nodes,policy=default|pre‐
3699 ferred|bind|interleave,align=align,readonly=on|off
3700 Creates a memory file backend object, which can be used
3701 to back the guest RAM with huge pages.
3702 The id parameter is a unique ID that will be used to ref‐
3704 erence this memory region in other parameters, e.g.
3705 -numa, -device nvdimm, etc.
3706 The size option provides the size of the memory region,
3708 and accepts common suffixes, e.g. 500M.
3709 The mem-path provides the path to either a shared memory
3711 or huge page filesystem mount.
3712 The share boolean option determines whether the memory
3714 region is marked as private to QEMU, or shared. The lat‐
3715 ter allows a co-operating external process to access the
3716 QEMU memory region.
3717 The share is also required for pvrdma devices due to lim‐
3719 itations in the RDMA API provided by Linux.
3720 Setting share=on might affect the ability to configure
3722 NUMA bindings for the memory backend under some circum‐
3723 stances, see Documentation/vm/numa_memory_policy.txt on
3724 the Linux kernel source tree for additional details.
3725 Setting the discard-data boolean option to on indicates
3727 that file contents can be destroyed when QEMU exits, to
3728 avoid unnecessarily flushing data to the backing file.
3729 Note that discard-data is only an optimization, and QEMU
3730 might not discard file contents if it aborts unexpectedly
3731 or is terminated using SIGKILL.
3732 The merge boolean option enables memory merge, also known
3734 as MADV_MERGEABLE, so that Kernel Samepage Merging will
3735 consider the pages for memory deduplication.
3736 Setting the dump boolean option to off excludes the mem‐
3738 ory from core dumps. This feature is also known as
3739 MADV_DONTDUMP.
3740 The prealloc boolean option enables memory preallocation.
3742 The host-nodes option binds the memory range to a list of
3744 NUMA host nodes.
3745 The policy option sets the NUMA policy to one of the fol‐
3747 lowing values:
3748 default
3750 default host policy
3751 preferred
3753 prefer the given host node list for allocation
3754 bind restrict memory allocation to the given host node
3756 list
3757 interleave
3759 interleave memory allocations across the given
3760 host node list
3761 The align option specifies the base address alignment
3763 when QEMU mmap(2) mem-path, and accepts common suffixes,
3764 eg 2M. Some backend store specified by mem-path requires
3765 an alignment different than the default one used by QEMU,
3766 eg the device DAX /dev/dax0.0 requires 2M alignment
3767 rather than 4K. In such cases, users can specify the re‐
3768 quired alignment via this option.
3769 The pmem option specifies whether the backing file speci‐
3771 fied by mem-path is in host persistent memory that can be
3772 accessed using the SNIA NVM programming model (e.g. Intel
3773 NVDIMM). If pmem is set to 'on', QEMU will take necessary
3774 operations to guarantee the persistence of its own writes
3775 to mem-path (e.g. in vNVDIMM label emulation and live mi‐
3776 gration). Also, we will map the backend-file with
3777 MAP_SYNC flag, which ensures the file metadata is in sync
3778 for mem-path in case of host crash or a power failure.
3779 MAP_SYNC requires support from both the host kernel
3780 (since Linux kernel 4.15) and the filesystem of mem-path
3781 mounted with DAX option.
3782 The readonly option specifies whether the backing file is
3784 opened read-only or read-write (default).
3785 -object memory-back‐
3787 end-ram,id=id,merge=on|off,dump=on|off,share=on|off,preal‐
3788 loc=on|off,size=size,host-nodes=host-nodes,policy=default|pre‐
3789 ferred|bind|interleave
3790 Creates a memory backend object, which can be used to
3791 back the guest RAM. Memory backend objects offer more
3792 control than the -m option that is traditionally used to
3793 define guest RAM. Please refer to memory-backend-file
3794 for a description of the options.
3795 -object memory-back‐
3797 end-memfd,id=id,merge=on|off,dump=on|off,share=on|off,preal‐
3798 loc=on|off,size=size,host-nodes=host-nodes,policy=default|pre‐
3799 ferred|bind|interleave,seal=on|off,hugetlb=on|off,hugetlb‐
3800 size=size
3801 Creates an anonymous memory file backend object, which
3802 allows QEMU to share the memory with an external process
3803 (e.g. when using vhost-user). The memory is allocated
3804 with memfd and optional sealing. (Linux only)
3805 The seal option creates a sealed-file, that will block
3807 further resizing the memory ('on' by default).
3808 The hugetlb option specify the file to be created resides
3810 in the hugetlbfs filesystem (since Linux 4.14). Used in
3811 conjunction with the hugetlb option, the hugetlbsize op‐
3812 tion specify the hugetlb page size on systems that sup‐
3813 port multiple hugetlb page sizes (it must be a power of 2
3814 value supported by the system).
3815 In some versions of Linux, the hugetlb option is incom‐
3817 patible with the seal option (requires at least Linux
3818 4.16).
3819 Please refer to memory-backend-file for a description of
3821 the other options.
3822 The share boolean option is on by default with memfd.
3824 -object rng-builtin,id=id
3826 Creates a random number generator backend which obtains
3827 entropy from QEMU builtin functions. The id parameter is
3828 a unique ID that will be used to reference this entropy
3829 backend from the virtio-rng device. By default, the vir‐
3830 tio-rng device uses this RNG backend.
3831 -object rng-random,id=id,filename=/dev/random
3833 Creates a random number generator backend which obtains
3834 entropy from a device on the host. The id parameter is a
3835 unique ID that will be used to reference this entropy
3836 backend from the virtio-rng device. The filename parame‐
3837 ter specifies which file to obtain entropy from and if
3838 omitted defaults to /dev/urandom.
3839 -object rng-egd,id=id,chardev=chardevid
3841 Creates a random number generator backend which obtains
3842 entropy from an external daemon running on the host. The
3843 id parameter is a unique ID that will be used to refer‐
3844 ence this entropy backend from the virtio-rng device. The
3845 chardev parameter is the unique ID of a character device
3846 backend that provides the connection to the RNG daemon.
3847 -object tls-creds-anon,id=id,endpoint=end‐
3849 point,dir=/path/to/cred/dir,verify-peer=on|off
3850 Creates a TLS anonymous credentials object, which can be
3851 used to provide TLS support on network backends. The id
3852 parameter is a unique ID which network backends will use
3853 to access the credentials. The endpoint is either server
3854 or client depending on whether the QEMU network backend
3855 that uses the credentials will be acting as a client or
3856 as a server. If verify-peer is enabled (the default) then
3857 once the handshake is completed, the peer credentials
3858 will be verified, though this is a no-op for anonymous
3859 credentials.
3860 The dir parameter tells QEMU where to find the credential
3862 files. For server endpoints, this directory may contain
3863 a file dh-params.pem providing diffie-hellman parameters
3864 to use for the TLS server. If the file is missing, QEMU
3865 will generate a set of DH parameters at startup. This is
3866 a computationally expensive operation that consumes ran‐
3867 dom pool entropy, so it is recommended that a persistent
3868 set of parameters be generated upfront and saved.
3869 -object tls-creds-psk,id=id,endpoint=end‐
3871 point,dir=/path/to/keys/dir[,username=username]
3872 Creates a TLS Pre-Shared Keys (PSK) credentials object,
3873 which can be used to provide TLS support on network back‐
3874 ends. The id parameter is a unique ID which network back‐
3875 ends will use to access the credentials. The endpoint is
3876 either server or client depending on whether the QEMU
3877 network backend that uses the credentials will be acting
3878 as a client or as a server. For clients only, username
3879 is the username which will be sent to the server. If
3880 omitted it defaults to "qemu".
3881 The dir parameter tells QEMU where to find the keys file.
3883 It is called "dir/keys.psk" and contains "username:key"
3884 pairs. This file can most easily be created using the
3885 GnuTLS psktool program.
3886 For server endpoints, dir may also contain a file
3888 dh-params.pem providing diffie-hellman parameters to use
3889 for the TLS server. If the file is missing, QEMU will
3890 generate a set of DH parameters at startup. This is a
3891 computationally expensive operation that consumes random
3892 pool entropy, so it is recommended that a persistent set
3893 of parameters be generated up front and saved.
3894 -object tls-creds-x509,id=id,endpoint=end‐
3896 point,dir=/path/to/cred/dir,priority=priority,ver‐
3897 ify-peer=on|off,passwordid=id
3898 Creates a TLS anonymous credentials object, which can be
3899 used to provide TLS support on network backends. The id
3900 parameter is a unique ID which network backends will use
3901 to access the credentials. The endpoint is either server
3902 or client depending on whether the QEMU network backend
3903 that uses the credentials will be acting as a client or
3904 as a server. If verify-peer is enabled (the default) then
3905 once the handshake is completed, the peer credentials
3906 will be verified. With x509 certificates, this implies
3907 that the clients must be provided with valid client cer‐
3908 tificates too.
3909 The dir parameter tells QEMU where to find the credential
3911 files. For server endpoints, this directory may contain
3912 a file dh-params.pem providing diffie-hellman parameters
3913 to use for the TLS server. If the file is missing, QEMU
3914 will generate a set of DH parameters at startup. This is
3915 a computationally expensive operation that consumes ran‐
3916 dom pool entropy, so it is recommended that a persistent
3917 set of parameters be generated upfront and saved.
3918 For x509 certificate credentials the directory will con‐
3920 tain further files providing the x509 certificates. The
3921 certificates must be stored in PEM format, in filenames
3922 ca-cert.pem, ca-crl.pem (optional), server-cert.pem (only
3923 servers), server-key.pem (only servers), client-cert.pem
3924 (only clients), and client-key.pem (only clients).
3925 For the server-key.pem and client-key.pem files which
3927 contain sensitive private keys, it is possible to use an
3928 encrypted version by providing the passwordid parameter.
3929 This provides the ID of a previously created secret ob‐
3930 ject containing the password for decryption.
3931 The priority parameter allows to override the global de‐
3933 fault priority used by gnutls. This can be useful if the
3934 system administrator needs to use a weaker set of crypto
3935 priorities for QEMU without potentially forcing the weak‐
3936 ness onto all applications. Or conversely if one wants
3937 wants a stronger default for QEMU than for all other ap‐
3938 plications, they can do this through this parameter. Its
3939 format is a gnutls priority string as described at
3940 https://gnutls.org/manual/html_node/Priority-Strings.html.
3941 -object tls-cipher-suites,id=id,priority=priority
3943 Creates a TLS cipher suites object, which can be used to
3944 control the TLS cipher/protocol algorithms that applica‐
3945 tions are permitted to use.
3946 The id parameter is a unique ID which frontends will use
3948 to access the ordered list of permitted TLS cipher suites
3949 from the host.
3950 The priority parameter allows to override the global de‐
3952 fault priority used by gnutls. This can be useful if the
3953 system administrator needs to use a weaker set of crypto
3954 priorities for QEMU without potentially forcing the weak‐
3955 ness onto all applications. Or conversely if one wants
3956 wants a stronger default for QEMU than for all other ap‐
3957 plications, they can do this through this parameter. Its
3958 format is a gnutls priority string as described at
3959 https://gnutls.org/manual/html_node/Priority-Strings.html.
3960 An example of use of this object is to control UEFI HTTPS
3962 Boot. The tls-cipher-suites object exposes the ordered
3963 list of permitted TLS cipher suites from the host side to
3964 the guest firmware, via fw_cfg. The list is represented
3965 as an array of IANA_TLS_CIPHER objects. The firmware uses
3966 the IANA_TLS_CIPHER array for configuring guest-side TLS.
3967 In the following example, the priority at which the
3969 host-side policy is retrieved is given by the priority
3970 property. Given that QEMU uses GNUTLS, priority=@SYSTEM
3971 may be used to refer to /etc/crypto-poli‐
3972 cies/back-ends/gnutls.config.
3973 # qemu-system-x86_64 \
3975 -object tls-cipher-suites,id=mysuite0,priority=@SYSTEM \
3976 -fw_cfg name=etc/edk2/https/ciphers,gen_id=mysuite0
3977 -object filter-buffer,id=id,netdev=netdevid,inter‐
3979 val=t[,queue=all|rx|tx][,status=on|off][,posi‐
3980 tion=head|tail|id=<id>][,insert=behind|before]
3981 Interval t can't be 0, this filter batches the packet de‐
3982 livery: all packets arriving in a given interval on net‐
3983 dev netdevid are delayed until the end of the interval.
3984 Interval is in microseconds. status is optional that in‐
3985 dicate whether the netfilter is on (enabled) or off (dis‐
3986 abled), the default status for netfilter will be 'on'.
3987 queue all|rx|tx is an option that can be applied to any
3989 netfilter.
3990 all: the filter is attached both to the receive and the
3992 transmit queue of the netdev (default).
3993 rx: the filter is attached to the receive queue of the
3995 netdev, where it will receive packets sent to the netdev.
3996 tx: the filter is attached to the transmit queue of the
3998 netdev, where it will receive packets sent by the netdev.
3999 position head|tail|id=<id> is an option to specify where
4001 the filter should be inserted in the filter list. It can
4002 be applied to any netfilter.
4003 head: the filter is inserted at the head of the filter
4005 list, before any existing filters.
4006 tail: the filter is inserted at the tail of the filter
4008 list, behind any existing filters (default).
4009 id=<id>: the filter is inserted before or behind the fil‐
4011 ter specified by <id>, see the insert option below.
4012 insert behind|before is an option to specify where to in‐
4014 sert the new filter relative to the one specified with
4015 position=id=<id>. It can be applied to any netfilter.
4016 before: insert before the specified filter.
4018 behind: insert behind the specified filter (default).
4020 -object filter-mirror,id=id,netdev=netdevid,outdev=charde‐
4022 vid,queue=all|rx|tx[,vnet_hdr_support][,posi‐
4023 tion=head|tail|id=<id>][,insert=behind|before]
4024 filter-mirror on netdev netdevid,mirror net packet to
4025 chardevchardevid, if it has the vnet_hdr_support flag,
4026 filter-mirror will mirror packet with vnet_hdr_len.
4027 -object filter-redirector,id=id,netdev=netdevid,indev=charde‐
4029 vid,outdev=chardevid,queue=all|rx|tx[,vnet_hdr_support][,posi‐
4030 tion=head|tail|id=<id>][,insert=behind|before]
4031 filter-redirector on netdev netdevid,redirect filter's
4032 net packet to chardev chardevid,and redirect indev's
4033 packet to filter.if it has the vnet_hdr_support flag,
4034 filter-redirector will redirect packet with vnet_hdr_len.
4035 Create a filter-redirector we need to differ outdev id
4036 from indev id, id can not be the same. we can just use
4037 indev or outdev, but at least one of indev or outdev need
4038 to be specified.
4039 -object filter-rewriter,id=id,netdev=netde‐
4041 vid,queue=all|rx|tx,[vnet_hdr_support][,posi‐
4042 tion=head|tail|id=<id>][,insert=behind|before]
4043 Filter-rewriter is a part of COLO project.It will rewrite
4044 tcp packet to secondary from primary to keep secondary
4045 tcp connection,and rewrite tcp packet to primary from
4046 secondary make tcp packet can be handled by client.if it
4047 has the vnet_hdr_support flag, we can parse packet with
4048 vnet header.
4049 usage: colo secondary: -object filter-redirec‐
4051 tor,id=f1,netdev=hn0,queue=tx,indev=red0 -object fil‐
4052 ter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 -ob‐
4053 ject filter-rewriter,id=rew0,netdev=hn0,queue=all
4054 -object filter-dump,id=id,netdev=dev[,file=file‐
4056 name][,maxlen=len][,position=head|tail|id=<id>][,insert=be‐
4057 hind|before]
4058 Dump the network traffic on netdev dev to the file speci‐
4059 fied by filename. At most len bytes (64k by default) per
4060 packet are stored. The file format is libpcap, so it can
4061 be analyzed with tools such as tcpdump or Wireshark.
4062 -object colo-compare,id=id,primary_in=chardevid,sec‐
4064 ondary_in=chardevid,outdev=chardevid,iothread=id[,vnet_hdr_sup‐
4065 port][,notify_dev=id][,compare_timeout=@var{ms}][,ex‐
4066 pired_scan_cycle=@var{ms}][,max_queue_size=@var{size}]
4067 Colo-compare gets packet from primary_in chardevid and
4068 secondary_in, then compare whether the payload of primary
4069 packet and secondary packet are the same. If same, it
4070 will output primary packet to out_dev, else it will no‐
4071 tify COLO-framework to do checkpoint and send primary
4072 packet to out_dev. In order to improve efficiency, we
4073 need to put the task of comparison in another iothread.
4074 If it has the vnet_hdr_support flag, colo compare will
4075 send/recv packet with vnet_hdr_len. The
4076 compare_timeout=@var{ms} determines the maximum time of
4077 the colo-compare hold the packet. The
4078 expired_scan_cycle=@var{ms} is to set the period of scan‐
4079 ning expired primary node network packets. The
4080 max_queue_size=@var{size} is to set the max compare queue
4081 size depend on user environment. If user want to use Xen
4082 COLO, need to add the notify_dev to notify Xen colo-frame
4083 to do checkpoint.
4084 COLO-compare must be used with the help of filter-mirror,
4086 filter-redirector and filter-rewriter.
4087 KVM COLO
4089 primary:
4091 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
4092 -device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
4093 -chardev socket,id=mirror0,host=3.3.3.3,port=9003,server=on,wait=off
4094 -chardev socket,id=compare1,host=3.3.3.3,port=9004,server=on,wait=off
4095 -chardev socket,id=compare0,host=3.3.3.3,port=9001,server=on,wait=off
4096 -chardev socket,id=compare0-0,host=3.3.3.3,port=9001
4097 -chardev socket,id=compare_out,host=3.3.3.3,port=9005,server=on,wait=off
4098 -chardev socket,id=compare_out0,host=3.3.3.3,port=9005
4099 -object iothread,id=iothread1
4100 -object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
4101 -object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
4102 -object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
4103 -object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,iothread=iothread1
4104 secondary:
4106 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
4107 -device e1000,netdev=hn0,mac=52:a4:00:12:78:66
4108 -chardev socket,id=red0,host=3.3.3.3,port=9003
4109 -chardev socket,id=red1,host=3.3.3.3,port=9004
4110 -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
4111 -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
4112 Xen COLO
4115 primary:
4117 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
4118 -device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
4119 -chardev socket,id=mirror0,host=3.3.3.3,port=9003,server=on,wait=off
4120 -chardev socket,id=compare1,host=3.3.3.3,port=9004,server=on,wait=off
4121 -chardev socket,id=compare0,host=3.3.3.3,port=9001,server=on,wait=off
4122 -chardev socket,id=compare0-0,host=3.3.3.3,port=9001
4123 -chardev socket,id=compare_out,host=3.3.3.3,port=9005,server=on,wait=off
4124 -chardev socket,id=compare_out0,host=3.3.3.3,port=9005
4125 -chardev socket,id=notify_way,host=3.3.3.3,port=9009,server=on,wait=off
4126 -object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
4127 -object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
4128 -object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
4129 -object iothread,id=iothread1
4130 -object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,notify_dev=nofity_way,iothread=iothread1
4131 secondary:
4133 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
4134 -device e1000,netdev=hn0,mac=52:a4:00:12:78:66
4135 -chardev socket,id=red0,host=3.3.3.3,port=9003
4136 -chardev socket,id=red1,host=3.3.3.3,port=9004
4137 -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
4138 -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
4139 If you want to know the detail of above command line, you
4141 can read the colo-compare git log.
4142 -object cryptodev-backend-builtin,id=id[,queues=queues]
4144 Creates a cryptodev backend which executes crypto
4145 opreation from the QEMU cipher APIS. The id parameter is
4146 a unique ID that will be used to reference this cryptodev
4147 backend from the virtio-crypto device. The queues parame‐
4148 ter is optional, which specify the queue number of cryp‐
4149 todev backend, the default of queues is 1.
4150 # qemu-system-x86_64 \
4152 [...] \
4153 -object cryptodev-backend-builtin,id=cryptodev0 \
4154 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
4155 [...]
4156 -object cryptodev-vhost-user,id=id,chardev=charde‐
4158 vid[,queues=queues]
4159 Creates a vhost-user cryptodev backend, backed by a
4160 chardev chardevid. The id parameter is a unique ID that
4161 will be used to reference this cryptodev backend from the
4162 virtio-crypto device. The chardev should be a unix domain
4163 socket backed one. The vhost-user uses a specifically
4164 defined protocol to pass vhost ioctl replacement messages
4165 to an application on the other end of the socket. The
4166 queues parameter is optional, which specify the queue
4167 number of cryptodev backend for multiqueue vhost-user,
4168 the default of queues is 1.
4169 # qemu-system-x86_64 \
4171 [...] \
4172 -chardev socket,id=chardev0,path=/path/to/socket \
4173 -object cryptodev-vhost-user,id=cryptodev0,chardev=chardev0 \
4174 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
4175 [...]
4176 -object secret,id=id,data=string,format=raw|base64[,keyid=se‐
4178 cretid,iv=string]
4179 -object secret,id=id,file=filename,format=raw|base64[,keyid=se‐
4182 cretid,iv=string]
4183 Defines a secret to store a password, encryption key, or
4184 some other sensitive data. The sensitive data can either
4185 be passed directly via the data parameter, or indirectly
4186 via the file parameter. Using the data parameter is inse‐
4187 cure unless the sensitive data is encrypted.
4188 The sensitive data can be provided in raw format (the de‐
4190 fault), or base64. When encoded as JSON, the raw format
4191 only supports valid UTF-8 characters, so base64 is recom‐
4192 mended for sending binary data. QEMU will convert from
4193 which ever format is provided to the format it needs in‐
4194 ternally. eg, an RBD password can be provided in raw for‐
4195 mat, even though it will be base64 encoded when passed
4196 onto the RBD sever.
4197 For added protection, it is possible to encrypt the data
4199 associated with a secret using the AES-256-CBC cipher.
4200 Use of encryption is indicated by providing the keyid and
4201 iv parameters. The keyid parameter provides the ID of a
4202 previously defined secret that contains the AES-256 de‐
4203 cryption key. This key should be 32-bytes long and be
4204 base64 encoded. The iv parameter provides the random ini‐
4205 tialization vector used for encryption of this particular
4206 secret and should be a base64 encrypted string of the
4207 16-byte IV.
4208 The simplest (insecure) usage is to provide the secret
4210 inline
4211 # qemu-system-x86_64 -object secret,id=sec0,data=letmein,format=raw
4213 The simplest secure usage is to provide the secret via a
4215 file
4216 # printf "letmein" > mypasswd.txt # QEMU_SYSTEM_MACRO
4218 -object secret,id=sec0,file=mypasswd.txt,format=raw
4219 For greater security, AES-256-CBC should be used. To il‐
4221 lustrate usage, consider the openssl command line tool
4222 which can encrypt the data. Note that when encrypting,
4223 the plaintext must be padded to the cipher block size (32
4224 bytes) using the standard PKCS#5/6 compatible padding al‐
4225 gorithm.
4226 First a master key needs to be created in base64 encod‐
4228 ing:
4229 # openssl rand -base64 32 > key.b64
4231 # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"')
4232 Each secret to be encrypted needs to have a random ini‐
4234 tialization vector generated. These do not need to be
4235 kept secret
4236 # openssl rand -base64 16 > iv.b64
4238 # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"')
4239 The secret to be defined can now be encrypted, in this
4241 case we're telling openssl to base64 encode the result,
4242 but it could be left as raw bytes if desired.
4243 # SECRET=$(printf "letmein" |
4245 openssl enc -aes-256-cbc -a -K $KEY -iv $IV)
4246 When launching QEMU, create a master secret pointing to
4248 key.b64 and specify that to be used to decrypt the user
4249 password. Pass the contents of iv.b64 to the second se‐
4250 cret
4251 # qemu-system-x86_64 \
4253 -object secret,id=secmaster0,format=base64,file=key.b64 \
4254 -object secret,id=sec0,keyid=secmaster0,format=base64,\
4255 data=$SECRET,iv=$(<iv.b64)
4256 -object sev-guest,id=id,cbitpos=cbitpos,re‐
4258 duced-phys-bits=val,[sev-device=string,policy=policy,handle=han‐
4259 dle,dh-cert-file=file,session-file=file,kernel-hashes=on|off]
4260 Create a Secure Encrypted Virtualization (SEV) guest ob‐
4261 ject, which can be used to provide the guest memory en‐
4262 cryption support on AMD processors.
4263 When memory encryption is enabled, one of the physical
4265 address bit (aka the C-bit) is utilized to mark if a mem‐
4266 ory page is protected. The cbitpos is used to provide the
4267 C-bit position. The C-bit position is Host family depen‐
4268 dent hence user must provide this value. On EPYC, the
4269 value should be 47.
4270 When memory encryption is enabled, we loose certain bits
4272 in physical address space. The reduced-phys-bits is used
4273 to provide the number of bits we loose in physical ad‐
4274 dress space. Similar to C-bit, the value is Host family
4275 dependent. On EPYC, the value should be 5.
4276 The sev-device provides the device file to use for commu‐
4278 nicating with the SEV firmware running inside AMD Secure
4279 Processor. The default device is '/dev/sev'. If hardware
4280 supports memory encryption then /dev/sev devices are cre‐
4281 ated by CCP driver.
4282 The policy provides the guest policy to be enforced by
4284 the SEV firmware and restrict what configuration and op‐
4285 erational commands can be performed on this guest by the
4286 hypervisor. The policy should be provided by the guest
4287 owner and is bound to the guest and cannot be changed
4288 throughout the lifetime of the guest. The default is 0.
4289 If guest policy allows sharing the key with another SEV
4291 guest then handle can be use to provide handle of the
4292 guest from which to share the key.
4293 The dh-cert-file and session-file provides the guest
4295 owner's Public Diffie-Hillman key defined in SEV spec.
4296 The PDH and session parameters are used for establishing
4297 a cryptographic session with the guest owner to negotiate
4298 keys used for attestation. The file must be encoded in
4299 base64.
4300 The kernel-hashes adds the hashes of given kernel/initrd/
4302 cmdline to a designated guest firmware page for measured
4303 Linux boot with -kernel. The default is off. (Since 6.2)
4304 e.g to launch a SEV guest
4306 # qemu-system-x86_64 \
4308 ...... \
4309 -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=5 \
4310 -machine ...,memory-encryption=sev0 \
4311 .....
4312 -object authz-simple,id=id,identity=string
4314 Create an authorization object that will control access
4315 to network services.
4316 The identity parameter is identifies the user and its
4318 format depends on the network service that authorization
4319 object is associated with. For authorizing based on TLS
4320 x509 certificates, the identity must be the x509 distin‐
4321 guished name. Note that care must be taken to escape any
4322 commas in the distinguished name.
4323 An example authorization object to validate a x509 dis‐
4325 tinguished name would look like:
4326 # qemu-system-x86_64 \
4328 ... \
4329 -object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,O=Example Org,,L=London,,ST=London,,C=GB' \
4330 ...
4331 Note the use of quotes due to the x509 distinguished name
4333 containing whitespace, and escaping of ','.
4334 -object authz-listfile,id=id,filename=path,refresh=on|off
4336 Create an authorization object that will control access
4337 to network services.
4338 The filename parameter is the fully qualified path to a
4340 file containing the access control list rules in JSON
4341 format.
4342 An example set of rules that match against SASL usernames
4344 might look like:
4345 {
4347 "rules": [
4348 { "match": "fred", "policy": "allow", "format": "exact" },
4349 { "match": "bob", "policy": "allow", "format": "exact" },
4350 { "match": "danb", "policy": "deny", "format": "glob" },
4351 { "match": "dan*", "policy": "allow", "format": "exact" },
4352 ],
4353 "policy": "deny"
4354 }
4355 When checking access the object will iterate over all the
4357 rules and the first rule to match will have its policy
4358 value returned as the result. If no rules match, then the
4359 default policy value is returned.
4360 The rules can either be an exact string match, or they
4362 can use the simple UNIX glob pattern matching to allow
4363 wildcards to be used.
4364 If refresh is set to true the file will be monitored and
4366 automatically reloaded whenever its content changes.
4367 As with the authz-simple object, the format of the iden‐
4369 tity strings being matched depends on the network ser‐
4370 vice, but is usually a TLS x509 distinguished name, or a
4371 SASL username.
4372 An example authorization object to validate a SASL user‐
4374 name would look like:
4375 # qemu-system-x86_64 \
4377 ... \
4378 -object authz-simple,id=auth0,filename=/etc/qemu/vnc-sasl.acl,refresh=on \
4379 ...
4380 -object authz-pam,id=id,service=string
4382 Create an authorization object that will control access
4383 to network services.
4384 The service parameter provides the name of a PAM service
4386 to use for authorization. It requires that a file
4387 /etc/pam.d/service exist to provide the configuration for
4388 the account subsystem.
4389 An example authorization object to validate a TLS x509
4391 distinguished name would look like:
4392 # qemu-system-x86_64 \
4394 ... \
4395 -object authz-pam,id=auth0,service=qemu-vnc \
4396 ...
4397 There would then be a corresponding config file for PAM
4399 at /etc/pam.d/qemu-vnc that contains:
4400 account requisite pam_listfile.so item=user sense=allow \
4402 file=/etc/qemu/vnc.allow
4403 Finally the /etc/qemu/vnc.allow file would contain the
4405 list of x509 distingished names that are permitted access
4406 CN=laptop.example.com,O=Example Home,L=London,ST=London,C=GB
4408 -object io‐
4410 thread,id=id,poll-max-ns=poll-max-ns,poll-grow=poll-grow,poll-shrink=poll-shrink,aio-max-batch=aio-max-batch
4411 Creates a dedicated event loop thread that devices can be
4412 assigned to. This is known as an IOThread. By default de‐
4413 vice emulation happens in vCPU threads or the main event
4414 loop thread. This can become a scalability bottleneck.
4415 IOThreads allow device emulation and I/O to run on other
4416 host CPUs.
4417 The id parameter is a unique ID that will be used to ref‐
4419 erence this IOThread from -device ...,iothread=id. Mul‐
4420 tiple devices can be assigned to an IOThread. Note that
4421 not all devices support an iothread parameter.
4422 The query-iothreads QMP command lists IOThreads and re‐
4424 ports their thread IDs so that the user can configure
4425 host CPU pinning/affinity.
4426 IOThreads use an adaptive polling algorithm to reduce
4428 event loop latency. Instead of entering a blocking system
4429 call to monitor file descriptors and then pay the cost of
4430 being woken up when an event occurs, the polling algo‐
4431 rithm spins waiting for events for a short time. The al‐
4432 gorithm's default parameters are suitable for many cases
4433 but can be adjusted based on knowledge of the workload
4434 and/or host device latency.
4435 The poll-max-ns parameter is the maximum number of
4437 nanoseconds to busy wait for events. Polling can be dis‐
4438 abled by setting this value to 0.
4439 The poll-grow parameter is the multiplier used to in‐
4441 crease the polling time when the algorithm detects it is
4442 missing events due to not polling long enough.
4443 The poll-shrink parameter is the divisor used to decrease
4445 the polling time when the algorithm detects it is spend‐
4446 ing too long polling without encountering events.
4447 The aio-max-batch parameter is the maximum number of re‐
4449 quests in a batch for the AIO engine, 0 means that the
4450 engine will use its default.
4451 The IOThread parameters can be modified at run-time using
4453 the qom-set command (where iothread1 is the IOThread's
4454 id):
4455 (qemu) qom-set /objects/iothread1 poll-max-ns 100000
4457 During the graphical emulation, you can use special key combinations to
4459 change modes. The default key mappings are shown below, but if you use
4460 -alt-grab then the modifier is Ctrl-Alt-Shift (instead of Ctrl-Alt) and
4461 if you use -ctrl-grab then the modifier is the right Ctrl key (instead
4462 of Ctrl-Alt):
4463 Ctrl-Alt-f
4465 Toggle full screen
4466 Ctrl-Alt-+
4468 Enlarge the screen
4469 Ctrl-Alt--
4471 Shrink the screen
4472 Ctrl-Alt-u
4474 Restore the screen's un-scaled dimensions
4475 Ctrl-Alt-n
4477 Switch to virtual console 'n'. Standard console mappings are:
4478 1 Target system display
4480 2 Monitor
4482 3 Serial port
4484 Ctrl-Alt
4486 Toggle mouse and keyboard grab.
4487 In the virtual consoles, you can use Ctrl-Up, Ctrl-Down, Ctrl-PageUp
4489 and Ctrl-PageDown to move in the back log.
4490 During emulation, if you are using a character backend multiplexer
4492 (which is the default if you are using -nographic) then several com‐
4493 mands are available via an escape sequence. These key sequences all
4494 start with an escape character, which is Ctrl-a by default, but can be
4495 changed with -echr. The list below assumes you're using the default.
4496 Ctrl-a h
4498 Print this help
4499 Ctrl-a x
4501 Exit emulator
4502 Ctrl-a s
4504 Save disk data back to file (if -snapshot)
4505 Ctrl-a t
4507 Toggle console timestamps
4508 Ctrl-a b
4510 Send break (magic sysrq in Linux)
4511 Ctrl-a c
4513 Rotate between the frontends connected to the multiplexer (usu‐
4514 ally this switches between the monitor and the console)
4515 Ctrl-a Ctrl-a
4517 Send the escape character to the frontend
4518
4520 In addition to using normal file images for the emulated storage de‐
4521 vices, QEMU can also use networked resources such as iSCSI devices.
4522 These are specified using a special URL syntax.
4523 iSCSI iSCSI support allows QEMU to access iSCSI resources directly and
4525 use as images for the guest storage. Both disk and cdrom images
4526 are supported.
4527 Syntax for specifying iSCSI LUNs is "iscsi://<tar‐
4529 get-ip>[:<port>]/<target-iqn>/<lun>"
4530 By default qemu will use the iSCSI initiator-name
4532 'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set
4533 from the command line or a configuration file.
4534 Since version QEMU 2.4 it is possible to specify a iSCSI request
4536 timeout to detect stalled requests and force a reestablishment
4537 of the session. The timeout is specified in seconds. The default
4538 is 0 which means no timeout. Libiscsi 1.15.0 or greater is re‐
4539 quired for this feature.
4540 Example (without authentication):
4542 qemu-system-x86_64 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
4544 -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
4545 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
4546 Example (CHAP username/password via URL):
4548 qemu-system-x86_64 -drive file=iscsi://user%password@192.0.2.1/iqn.2001-04.com.example/1
4550 Example (CHAP username/password via environment variables):
4552 LIBISCSI_CHAP_USERNAME="user" \
4554 LIBISCSI_CHAP_PASSWORD="password" \
4555 qemu-system-x86_64 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
4556 NBD QEMU supports NBD (Network Block Devices) both using TCP proto‐
4558 col as well as Unix Domain Sockets. With TCP, the default port
4559 is 10809.
4560 Syntax for specifying a NBD device using TCP, in preferred URI
4562 form: "nbd://<server-ip>[:<port>]/[<export>]"
4563 Syntax for specifying a NBD device using Unix Domain Sockets;
4565 remember that '?' is a shell glob character and may need quot‐
4566 ing: "nbd+unix:///[<export>]?socket=<domain-socket>"
4567 Older syntax that is also recognized:
4569 "nbd:<server-ip>:<port>[:exportname=<export>]"
4570 Syntax for specifying a NBD device using Unix Domain Sockets
4572 "nbd:unix:<domain-socket>[:exportname=<export>]"
4573 Example for TCP
4575 qemu-system-x86_64 --drive file=nbd:192.0.2.1:30000
4577 Example for Unix Domain Sockets
4579 qemu-system-x86_64 --drive file=nbd:unix:/tmp/nbd-socket
4581 SSH QEMU supports SSH (Secure Shell) access to remote disks.
4583 Examples:
4585 qemu-system-x86_64 -drive file=ssh://user@host/path/to/disk.img
4587 qemu-system-x86_64 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
4588 Currently authentication must be done using ssh-agent. Other au‐
4590 thentication methods may be supported in future.
4591 GlusterFS
4593 GlusterFS is a user space distributed file system. QEMU supports
4594 the use of GlusterFS volumes for hosting VM disk images using
4595 TCP, Unix Domain Sockets and RDMA transport protocols.
4596 Syntax for specifying a VM disk image on GlusterFS volume is
4598 URI:
4600 gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
4601 JSON:
4603 'json:{"driver":"qcow2","file":{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...",
4604 "server":[{"type":"tcp","host":"...","port":"..."},
4605 {"type":"unix","socket":"..."}]}}'
4606 Example
4608 URI:
4610 qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img,
4611 file.debug=9,file.logfile=/var/log/qemu-gluster.log
4612 JSON:
4614 qemu-system-x86_64 'json:{"driver":"qcow2",
4615 "file":{"driver":"gluster",
4616 "volume":"testvol","path":"a.img",
4617 "debug":9,"logfile":"/var/log/qemu-gluster.log",
4618 "server":[{"type":"tcp","host":"1.2.3.4","port":24007},
4619 {"type":"unix","socket":"/var/run/glusterd.socket"}]}}'
4620 qemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
4621 file.debug=9,file.logfile=/var/log/qemu-gluster.log,
4622 file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
4623 file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
4624 See also http://www.gluster.org.
4626 HTTP/HTTPS/FTP/FTPS
4628 QEMU supports read-only access to files accessed over http(s)
4629 and ftp(s).
4630 Syntax using a single filename:
4632 <protocol>://[<username>[:<password>]@]<host>/<path>
4634 where:
4636 protocol
4638 'http', 'https', 'ftp', or 'ftps'.
4639 username
4641 Optional username for authentication to the remote
4642 server.
4643 password
4645 Optional password for authentication to the remote
4646 server.
4647 host Address of the remote server.
4649 path Path on the remote server, including any query string.
4651 The following options are also supported:
4653 url The full URL when passing options to the driver explic‐
4655 itly.
4656 readahead
4658 The amount of data to read ahead with each range request
4659 to the remote server. This value may optionally have the
4660 suffix 'T', 'G', 'M', 'K', 'k' or 'b'. If it does not
4661 have a suffix, it will be assumed to be in bytes. The
4662 value must be a multiple of 512 bytes. It defaults to
4663 256k.
4664 sslverify
4666 Whether to verify the remote server's certificate when
4667 connecting over SSL. It can have the value 'on' or 'off'.
4668 It defaults to 'on'.
4669 cookie Send this cookie (it can also be a list of cookies sepa‐
4671 rated by ';') with each outgoing request. Only supported
4672 when using protocols such as HTTP which support cookies,
4673 otherwise ignored.
4674 timeout
4676 Set the timeout in seconds of the CURL connection. This
4677 timeout is the time that CURL waits for a response from
4678 the remote server to get the size of the image to be
4679 downloaded. If not set, the default timeout of 5 seconds
4680 is used.
4681 Note that when passing options to qemu explicitly, driver is the
4683 value of <protocol>.
4684 Example: boot from a remote Fedora 20 live ISO image
4686 qemu-system-x86_64 --drive media=cdrom,file=https://archives.fedoraproject.org/pub/archive/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
4688 qemu-system-x86_64 --drive media=cdrom,file.driver=http,file.url=http://archives.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
4690 Example: boot from a remote Fedora 20 cloud image using a local
4692 overlay for writes, copy-on-read, and a readahead of 64k
4693 qemu-img create -f qcow2 -o backing_file='json:{"file.driver":"http",, "file.url":"http://archives.fedoraproject.org/pub/archive/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
4695 qemu-system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
4697 Example: boot from an image stored on a VMware vSphere server
4699 with a self-signed certificate using a local overlay for writes,
4700 a readahead of 64k and a timeout of 10 seconds.
4701 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
4703 qemu-system-x86_64 -drive file=/tmp/test.qcow2
4705
4707 The HTML documentation of QEMU for more precise information and Linux
4708 user mode emulator invocation.
4709
4711 Fabrice Bellard
4712
4714 2022, The QEMU Project Developers
47156.2.0 Jun 11, 2022 QEMU(1)