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 -cpu model
177 Select CPU model (-cpu help for list and additional feature se‐
178 lection)
179 -accel name[,prop=value[,...]]
181 This is used to enable an accelerator. Depending on the target
182 architecture, kvm, xen, hax, hvf, nvmm, whpx or tcg can be
183 available. By default, tcg is used. If there is more than one
184 accelerator specified, the next one is used if the previous one
185 fails to initialize.
186 igd-passthru=on|off
188 When Xen is in use, this option controls whether Intel
189 integrated graphics devices can be passed through to the
190 guest (default=off)
191 kernel-irqchip=on|off|split
193 Controls KVM in-kernel irqchip support. The default is
194 full acceleration of the interrupt controllers. On x86,
195 split irqchip reduces the kernel attack surface, at a
196 performance cost for non-MSI interrupts. Disabling the
197 in-kernel irqchip completely is not recommended except
198 for debugging purposes.
199 kvm-shadow-mem=size
201 Defines the size of the KVM shadow MMU.
202 split-wx=on|off
204 Controls the use of split w^x mapping for the TCG code
205 generation buffer. Some operating systems require this to
206 be enabled, and in such a case this will default on. On
207 other operating systems, this will default off, but one
208 may enable this for testing or debugging.
209 tb-size=n
211 Controls the size (in MiB) of the TCG translation block
212 cache.
213 thread=single|multi
215 Controls number of TCG threads. When the TCG is
216 multi-threaded there will be one thread per vCPU there‐
217 fore taking advantage of additional host cores. The de‐
218 fault is to enable multi-threading where both the
219 back-end and front-ends support it and no incompatible
220 TCG features have been enabled (e.g. icount/replay).
221 dirty-ring-size=n
223 When the KVM accelerator is used, it controls the size of
224 the per-vCPU dirty page ring buffer (number of entries
225 for each vCPU). It should be a value that is power of
226 two, and it should be 1024 or bigger (but still less than
227 the maximum value that the kernel supports). 4096 could
228 be a good initial value if you have no idea which is the
229 best. Set this value to 0 to disable the feature. By
230 default, this feature is disabled (dirty-ring-size=0).
231 When enabled, KVM will instead record dirty pages in a
232 bitmap.
233 -smp [[cpus=]n][,maxcpus=maxcpus][,sockets=sock‐
235 ets][,dies=dies][,cores=cores][,threads=threads]
236 Simulate a SMP system with 'n' CPUs initially present on the ma‐
237 chine type board. On boards supporting CPU hotplug, the optional
238 'maxcpus' parameter can be set to enable further CPUs to be
239 added at runtime. If omitted the maximum number of CPUs will be
240 set to match the initial CPU count. Both parameters are subject
241 to an upper limit that is determined by the specific machine
242 type chosen.
243 To control reporting of CPU topology information, the number of
245 sockets, dies per socket, cores per die, and threads per core
246 can be specified. The sum `` sockets * cores * dies * threads
247 `` must be equal to the maximum CPU count. CPU targets may only
248 support a subset of the topology parameters. Where a CPU target
249 does not support use of a particular topology parameter, its
250 value should be assumed to be 1 for the purpose of computing the
251 CPU maximum count.
252 Either the initial CPU count, or at least one of the topology
254 parameters must be specified. Values for any omitted parameters
255 will be computed from those which are given. Historically pref‐
256 erence was given to the coarsest topology parameters when com‐
257 puting missing values (ie sockets preferred over cores, which
258 were preferred over threads), however, this behaviour is consid‐
259 ered liable to change.
260 -numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initia‐
262 tor=initiator]
263 -numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initia‐
266 tor=initiator]
267 -numa dist,src=source,dst=destination,val=distance
270 -numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]
273 -numa hmat-lb,initiator=node,target=node,hierarchy=hierar‐
276 chy,data-type=tpye[,latency=lat][,bandwidth=bw]
277 -numa hmat-cache,node-id=node,size=size,level=level[,associativ‐
280 ity=str][,policy=str][,line=size]
281 Define a NUMA node and assign RAM and VCPUs to it. Set the NUMA
282 distance from a source node to a destination node. Set the ACPI
283 Heterogeneous Memory Attributes for the given nodes.
284 Legacy VCPU assignment uses 'cpus' option where firstcpu and
286 lastcpu are CPU indexes. Each 'cpus' option represent a contigu‐
287 ous range of CPU indexes (or a single VCPU if lastcpu is omit‐
288 ted). A non-contiguous set of VCPUs can be represented by pro‐
289 viding multiple 'cpus' options. If 'cpus' is omitted on all
290 nodes, VCPUs are automatically split between them.
291 For example, the following option assigns VCPUs 0, 1, 2 and 5 to
293 a NUMA node:
294 -numa node,cpus=0-2,cpus=5
296 'cpu' option is a new alternative to 'cpus' option which uses
298 'socket-id|core-id|thread-id' properties to assign CPU objects
299 to a node using topology layout properties of CPU. The set of
300 properties is machine specific, and depends on used machine
301 type/'smp' options. It could be queried with 'hotpluggable-cpus'
302 monitor command. 'node-id' property specifies node to which CPU
303 object will be assigned, it's required for node to be declared
304 with 'node' option before it's used with 'cpu' option.
305 For example:
307 -M pc \
309 -smp 1,sockets=2,maxcpus=2 \
310 -numa node,nodeid=0 -numa node,nodeid=1 \
311 -numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1
312 Legacy 'mem' assigns a given RAM amount to a node (not supported
314 for 5.1 and newer machine types). 'memdev' assigns RAM from a
315 given memory backend device to a node. If 'mem' and 'memdev' are
316 omitted in all nodes, RAM is split equally between them.
317 'mem' and 'memdev' are mutually exclusive. Furthermore, if one
319 node uses 'memdev', all of them have to use it.
320 'initiator' is an additional option that points to an initiator
322 NUMA node that has best performance (the lowest latency or
323 largest bandwidth) to this NUMA node. Note that this option can
324 be set only when the machine property 'hmat' is set to 'on'.
325 Following example creates a machine with 2 NUMA nodes, node 0
327 has CPU. node 1 has only memory, and its initiator is node 0.
328 Note that because node 0 has CPU, by default the initiator of
329 node 0 is itself and must be itself.
330 -machine hmat=on \
332 -m 2G,slots=2,maxmem=4G \
333 -object memory-backend-ram,size=1G,id=m0 \
334 -object memory-backend-ram,size=1G,id=m1 \
335 -numa node,nodeid=0,memdev=m0 \
336 -numa node,nodeid=1,memdev=m1,initiator=0 \
337 -smp 2,sockets=2,maxcpus=2 \
338 -numa cpu,node-id=0,socket-id=0 \
339 -numa cpu,node-id=0,socket-id=1
340 source and destination are NUMA node IDs. distance is the NUMA
342 distance from source to destination. The distance from a node to
343 itself is always 10. If any pair of nodes is given a distance,
344 then all pairs must be given distances. Although, when distances
345 are only given in one direction for each pair of nodes, then the
346 distances in the opposite directions are assumed to be the same.
347 If, however, an asymmetrical pair of distances is given for even
348 one node pair, then all node pairs must be provided distance
349 values for both directions, even when they are symmetrical. When
350 a node is unreachable from another node, set the pair's distance
351 to 255.
352 Note that the -numa option doesn't allocate any of the specified
354 resources, it just assigns existing resources to NUMA nodes.
355 This means that one still has to use the -m, -smp options to al‐
356 locate RAM and VCPUs respectively.
357 Use 'hmat-lb' to set System Locality Latency and Bandwidth In‐
359 formation between initiator and target NUMA nodes in ACPI Het‐
360 erogeneous Attribute Memory Table (HMAT). Initiator NUMA node
361 can create memory requests, usually it has one or more proces‐
362 sors. Target NUMA node contains addressable memory.
363 In 'hmat-lb' option, node are NUMA node IDs. hierarchy is the
365 memory hierarchy of the target NUMA node: if hierarchy is 'mem‐
366 ory', the structure represents the memory performance; if hier‐
367 archy is 'first-level|second-level|third-level', this structure
368 represents aggregated performance of memory side caches for each
369 domain. type of 'data-type' is type of data represented by this
370 structure instance: if 'hierarchy' is 'memory', 'data-type' is
371 'access|read|write' latency or 'access|read|write' bandwidth of
372 the target memory; if 'hierarchy' is 'first-level|sec‐
373 ond-level|third-level', 'data-type' is 'access|read|write' hit
374 latency or 'access|read|write' hit bandwidth of the target mem‐
375 ory side cache.
376 lat is latency value in nanoseconds. bw is bandwidth value, the
378 possible value and units are NUM[M|G|T], mean that the bandwidth
379 value are NUM byte per second (or MB/s, GB/s or TB/s depending
380 on used suffix). Note that if latency or bandwidth value is 0,
381 means the corresponding latency or bandwidth information is not
382 provided.
383 In 'hmat-cache' option, node-id is the NUMA-id of the memory be‐
385 longs. size is the size of memory side cache in bytes. level is
386 the cache level described in this structure, note that the cache
387 level 0 should not be used with 'hmat-cache' option. associa‐
388 tivity is the cache associativity, the possible value is
389 'none/direct(direct-mapped)/complex(complex cache indexing)'.
390 policy is the write policy. line is the cache Line size in
391 bytes.
392 For example, the following options describe 2 NUMA nodes. Node 0
394 has 2 cpus and a ram, node 1 has only a ram. The processors in
395 node 0 access memory in node 0 with access-latency 5 nanosec‐
396 onds, access-bandwidth is 200 MB/s; The processors in NUMA node
397 0 access memory in NUMA node 1 with access-latency 10 nanosec‐
398 onds, access-bandwidth is 100 MB/s. And for memory side cache
399 information, NUMA node 0 and 1 both have 1 level memory cache,
400 size is 10KB, policy is write-back, the cache Line size is 8
401 bytes:
402 -machine hmat=on \
404 -m 2G \
405 -object memory-backend-ram,size=1G,id=m0 \
406 -object memory-backend-ram,size=1G,id=m1 \
407 -smp 2 \
408 -numa node,nodeid=0,memdev=m0 \
409 -numa node,nodeid=1,memdev=m1,initiator=0 \
410 -numa cpu,node-id=0,socket-id=0 \
411 -numa cpu,node-id=0,socket-id=1 \
412 -numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-latency,latency=5 \
413 -numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-bandwidth,bandwidth=200M \
414 -numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-latency,latency=10 \
415 -numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-bandwidth,bandwidth=100M \
416 -numa hmat-cache,node-id=0,size=10K,level=1,associativity=direct,policy=write-back,line=8 \
417 -numa hmat-cache,node-id=1,size=10K,level=1,associativity=direct,policy=write-back,line=8
418 -add-fd fd=fd,set=set[,opaque=opaque]
420 Add a file descriptor to an fd set. Valid options are:
421 fd=fd This option defines the file descriptor of which a dupli‐
423 cate is added to fd set. The file descriptor cannot be
424 stdin, stdout, or stderr.
425 set=set
427 This option defines the ID of the fd set to add the file
428 descriptor to.
429 opaque=opaque
431 This option defines a free-form string that can be used
432 to describe fd.
433 You can open an image using pre-opened file descriptors from an
435 fd set:
436 qemu-system-x86_64 \
438 -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \
439 -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \
440 -drive file=/dev/fdset/2,index=0,media=disk
441 -set group.id.arg=value
443 Set parameter arg for item id of type group
444 -global driver.prop=value
446 -global driver=driver,property=property,value=value
449 Set default value of driver's property prop to value, e.g.:
450 qemu-system-x86_64 -global ide-hd.physical_block_size=4096 disk-image.img
452 In particular, you can use this to set driver properties for de‐
454 vices which are created automatically by the machine model. To
455 create a device which is not created automatically and set prop‐
456 erties on it, use -device.
457 -global driver.prop=value is shorthand for -global
459 driver=driver,property=prop,value=value. The longhand syntax
460 works even when driver contains a dot.
461 -boot [or‐
463 der=drives][,once=drives][,menu=on|off][,splash=sp_name][,splash-time=sp_time][,re‐
464 boot-timeout=rb_timeout][,strict=on|off]
465 Specify boot order drives as a string of drive letters. Valid
466 drive letters depend on the target architecture. The x86 PC
467 uses: a, b (floppy 1 and 2), c (first hard disk), d (first
468 CD-ROM), n-p (Etherboot from network adapter 1-4), hard disk
469 boot is the default. To apply a particular boot order only on
470 the first startup, specify it via once. Note that the order or
471 once parameter should not be used together with the bootindex
472 property of devices, since the firmware implementations normally
473 do not support both at the same time.
474 Interactive boot menus/prompts can be enabled via menu=on as far
476 as firmware/BIOS supports them. The default is non-interactive
477 boot.
478 A splash picture could be passed to bios, enabling user to show
480 it as logo, when option splash=sp_name is given and menu=on, If
481 firmware/BIOS supports them. Currently Seabios for X86 system
482 support it. limitation: The splash file could be a jpeg file or
483 a BMP file in 24 BPP format(true color). The resolution should
484 be supported by the SVGA mode, so the recommended is 320x240,
485 640x480, 800x640.
486 A timeout could be passed to bios, guest will pause for rb_time‐
488 out ms when boot failed, then reboot. If rb_timeout is '-1',
489 guest will not reboot, qemu passes '-1' to bios by default. Cur‐
490 rently Seabios for X86 system support it.
491 Do strict boot via strict=on as far as firmware/BIOS supports
493 it. This only effects when boot priority is changed by bootindex
494 options. The default is non-strict boot.
495 # try to boot from network first, then from hard disk
497 qemu-system-x86_64 -boot order=nc
498 # boot from CD-ROM first, switch back to default order after reboot
499 qemu-system-x86_64 -boot once=d
500 # boot with a splash picture for 5 seconds.
501 qemu-system-x86_64 -boot menu=on,splash=/root/boot.bmp,splash-time=5000
502 Note: The legacy format '-boot drives' is still supported but
504 its use is discouraged as it may be removed from future ver‐
505 sions.
506 -m [size=]megs[,slots=n,maxmem=size]
508 Sets guest startup RAM size to megs megabytes. Default is 128
509 MiB. Optionally, a suffix of "M" or "G" can be used to signify
510 a value in megabytes or gigabytes respectively. Optional pair
511 slots, maxmem could be used to set amount of hotpluggable memory
512 slots and maximum amount of memory. Note that maxmem must be
513 aligned to the page size.
514 For example, the following command-line sets the guest startup
516 RAM size to 1GB, creates 3 slots to hotplug additional memory
517 and sets the maximum memory the guest can reach to 4GB:
518 qemu-system-x86_64 -m 1G,slots=3,maxmem=4G
520 If slots and maxmem are not specified, memory hotplug won't be
522 enabled and the guest startup RAM will never increase.
523 -mem-path path
525 Allocate guest RAM from a temporarily created file in path.
526 -mem-prealloc
528 Preallocate memory when using -mem-path.
529 -k language
531 Use keyboard layout language (for example fr for French). This
532 option is only needed where it is not easy to get raw PC key‐
533 codes (e.g. on Macs, with some X11 servers or with a VNC or
534 curses display). You don't normally need to use it on PC/Linux
535 or PC/Windows hosts.
536 The available layouts are:
538 ar de-ch es fo fr-ca hu ja mk no pt-br sv
540 da en-gb et fr fr-ch is lt nl pl ru th
541 de en-us fi fr-be hr it lv nl-be pt sl tr
542 The default is en-us.
544 -audio-help
546 Will show the -audiodev equivalent of the currently specified
547 (deprecated) environment variables.
548 -audiodev [driver=]driver,id=id[,prop[=value][,...]]
550 Adds a new audio backend driver identified by id. There are
551 global and driver specific properties. Some values can be set
552 differently for input and output, they're marked with in|out..
553 You can set the input's property with in.prop and the output's
554 property with out.prop. For example:
555 -audiodev alsa,id=example,in.frequency=44110,out.frequency=8000
557 -audiodev alsa,id=example,out.channels=1 # leaves in.channels unspecified
558 NOTE: parameter validation is known to be incomplete, in many
560 cases specifying an invalid option causes QEMU to print an error
561 message and continue emulation without sound.
562 Valid global options are:
564 id=identifier
566 Identifies the audio backend.
567 timer-period=period
569 Sets the timer period used by the audio subsystem in mi‐
570 croseconds. Default is 10000 (10 ms).
571 in|out.mixing-engine=on|off
573 Use QEMU's mixing engine to mix all streams inside QEMU
574 and convert audio formats when not supported by the back‐
575 end. When off, fixed-settings must be off too. Note that
576 disabling this option means that the selected backend
577 must support multiple streams and the audio formats used
578 by the virtual cards, otherwise you'll get no sound. It's
579 not recommended to disable this option unless you want to
580 use 5.1 or 7.1 audio, as mixing engine only supports mono
581 and stereo audio. Default is on.
582 in|out.fixed-settings=on|off
584 Use fixed settings for host audio. When off, it will
585 change based on how the guest opens the sound card. In
586 this case you must not specify frequency, channels or
587 format. Default is on.
588 in|out.frequency=frequency
590 Specify the frequency to use when using fixed-settings.
591 Default is 44100Hz.
592 in|out.channels=channels
594 Specify the number of channels to use when using
595 fixed-settings. Default is 2 (stereo).
596 in|out.format=format
598 Specify the sample format to use when using fixed-set‐
599 tings. Valid values are: s8, s16, s32, u8, u16, u32,
600 f32. Default is s16.
601 in|out.voices=voices
603 Specify the number of voices to use. Default is 1.
604 in|out.buffer-length=usecs
606 Sets the size of the buffer in microseconds.
607 -audiodev none,id=id[,prop[=value][,...]]
609 Creates a dummy backend that discards all outputs. This backend
610 has no backend specific properties.
611 -audiodev alsa,id=id[,prop[=value][,...]]
613 Creates backend using the ALSA. This backend is only available
614 on Linux.
615 ALSA specific options are:
617 in|out.dev=device
619 Specify the ALSA device to use for input and/or output.
620 Default is default.
621 in|out.period-length=usecs
623 Sets the period length in microseconds.
624 in|out.try-poll=on|off
626 Attempt to use poll mode with the device. Default is on.
627 threshold=threshold
629 Threshold (in microseconds) when playback starts. Default
630 is 0.
631 -audiodev coreaudio,id=id[,prop[=value][,...]]
633 Creates a backend using Apple's Core Audio. This backend is only
634 available on Mac OS and only supports playback.
635 Core Audio specific options are:
637 in|out.buffer-count=count
639 Sets the count of the buffers.
640 -audiodev dsound,id=id[,prop[=value][,...]]
642 Creates a backend using Microsoft's DirectSound. This backend is
643 only available on Windows and only supports playback.
644 DirectSound specific options are:
646 latency=usecs
648 Add extra usecs microseconds latency to playback. Default
649 is 10000 (10 ms).
650 -audiodev oss,id=id[,prop[=value][,...]]
652 Creates a backend using OSS. This backend is available on most
653 Unix-like systems.
654 OSS specific options are:
656 in|out.dev=device
658 Specify the file name of the OSS device to use. Default
659 is /dev/dsp.
660 in|out.buffer-count=count
662 Sets the count of the buffers.
663 in|out.try-poll=on|of
665 Attempt to use poll mode with the device. Default is on.
666 try-mmap=on|off
668 Try using memory mapped device access. Default is off.
669 exclusive=on|off
671 Open the device in exclusive mode (vmix won't work in
672 this case). Default is off.
673 dsp-policy=policy
675 Sets the timing policy (between 0 and 10, where smaller
676 number means smaller latency but higher CPU usage). Use
677 -1 to use buffer sizes specified by buffer and buf‐
678 fer-count. This option is ignored if you do not have OSS
679 4. Default is 5.
680 -audiodev pa,id=id[,prop[=value][,...]]
682 Creates a backend using PulseAudio. This backend is available on
683 most systems.
684 PulseAudio specific options are:
686 server=server
688 Sets the PulseAudio server to connect to.
689 in|out.name=sink
691 Use the specified source/sink for recording/playback.
692 in|out.latency=usecs
694 Desired latency in microseconds. The PulseAudio server
695 will try to honor this value but actual latencies may be
696 lower or higher.
697 -audiodev sdl,id=id[,prop[=value][,...]]
699 Creates a backend using SDL. This backend is available on most
700 systems, but you should use your platform's native backend if
701 possible.
702 SDL specific options are:
704 in|out.buffer-count=count
706 Sets the count of the buffers.
707 -audiodev spice,id=id[,prop[=value][,...]]
709 Creates a backend that sends audio through SPICE. This backend
710 requires -spice and automatically selected in that case, so usu‐
711 ally you can ignore this option. This backend has no backend
712 specific properties.
713 -audiodev wav,id=id[,prop[=value][,...]]
715 Creates a backend that writes audio to a WAV file.
716 Backend specific options are:
718 path=path
720 Write recorded audio into the specified file. Default is
721 qemu.wav.
722 -soundhw card1[,card2,...] or -soundhw all
724 Enable audio and selected sound hardware. Use 'help' to print
725 all available sound hardware. For example:
726 qemu-system-x86_64 -soundhw sb16,adlib disk.img
728 qemu-system-x86_64 -soundhw es1370 disk.img
729 qemu-system-x86_64 -soundhw ac97 disk.img
730 qemu-system-x86_64 -soundhw hda disk.img
731 qemu-system-x86_64 -soundhw all disk.img
732 qemu-system-x86_64 -soundhw help
733 Note that Linux's i810_audio OSS kernel (for AC97) module might
735 require manually specifying clocking.
736 modprobe i810_audio clocking=48000
738 -device driver[,prop[=value][,...]]
740 Add device driver. prop=value sets driver properties. Valid
741 properties depend on the driver. To get help on possible drivers
742 and properties, use -device help and -device driver,help.
743 Some drivers are:
745 -device ipmi-bmc-sim,id=id[,prop[=value][,...]]
747 Add an IPMI BMC. This is a simulation of a hardware management
748 interface processor that normally sits on a system. It provides
749 a watchdog and the ability to reset and power control the sys‐
750 tem. You need to connect this to an IPMI interface to make it
751 useful
752 The IPMI slave address to use for the BMC. The default is 0x20.
754 This address is the BMC's address on the I2C network of manage‐
755 ment controllers. If you don't know what this means, it is safe
756 to ignore it.
757 id=id The BMC id for interfaces to use this device.
759 slave_addr=val
761 Define slave address to use for the BMC. The default is
762 0x20.
763 sdrfile=file
765 file containing raw Sensor Data Records (SDR) data. The
766 default is none.
767 fruareasize=val
769 size of a Field Replaceable Unit (FRU) area. The default
770 is 1024.
771 frudatafile=file
773 file containing raw Field Replaceable Unit (FRU) inven‐
774 tory data. The default is none.
775 guid=uuid
777 value for the GUID for the BMC, in standard UUID format.
778 If this is set, get "Get GUID" command to the BMC will
779 return it. Otherwise "Get GUID" will return an error.
780 -device ipmi-bmc-extern,id=id,chardev=id[,slave_addr=val]
782 Add a connection to an external IPMI BMC simulator. Instead of
783 locally emulating the BMC like the above item, instead connect
784 to an external entity that provides the IPMI services.
785 A connection is made to an external BMC simulator. If you do
787 this, it is strongly recommended that you use the "reconnect="
788 chardev option to reconnect to the simulator if the connection
789 is lost. Note that if this is not used carefully, it can be a
790 security issue, as the interface has the ability to send resets,
791 NMIs, and power off the VM. It's best if QEMU makes a connection
792 to an external simulator running on a secure port on localhost,
793 so neither the simulator nor QEMU is exposed to any outside net‐
794 work.
795 See the "lanserv/README.vm" file in the OpenIPMI library for
797 more details on the external interface.
798 -device isa-ipmi-kcs,bmc=id[,ioport=val][,irq=val]
800 Add a KCS IPMI interafce on the ISA bus. This also adds a corre‐
801 sponding ACPI and SMBIOS entries, if appropriate.
802 bmc=id The BMC to connect to, one of ipmi-bmc-sim or
804 ipmi-bmc-extern above.
805 ioport=val
807 Define the I/O address of the interface. The default is
808 0xca0 for KCS.
809 irq=val
811 Define the interrupt to use. The default is 5. To disable
812 interrupts, set this to 0.
813 -device isa-ipmi-bt,bmc=id[,ioport=val][,irq=val]
815 Like the KCS interface, but defines a BT interface. The default
816 port is 0xe4 and the default interrupt is 5.
817 -device pci-ipmi-kcs,bmc=id
819 Add a KCS IPMI interafce on the PCI bus.
820 bmc=id The BMC to connect to, one of ipmi-bmc-sim or
822 ipmi-bmc-extern above.
823 -device pci-ipmi-bt,bmc=id
825 Like the KCS interface, but defines a BT interface on the PCI
826 bus.
827 -device intel-iommu[,option=...]
829 This is only supported by -machine q35, which will enable Intel
830 VT-d emulation within the guest. It supports below options:
831 intremap=on|off (default: auto)
833 This enables interrupt remapping feature. It's required
834 to enable complete x2apic. Currently it only supports
835 kvm kernel-irqchip modes off or split, while full ker‐
836 nel-irqchip is not yet supported. The default value is
837 "auto", which will be decided by the mode of ker‐
838 nel-irqchip.
839 caching-mode=on|off (default: off)
841 This enables caching mode for the VT-d emulated device.
842 When caching-mode is enabled, each guest DMA buffer map‐
843 ping will generate an IOTLB invalidation from the guest
844 IOMMU driver to the vIOMMU device in a synchronous way.
845 It is required for -device vfio-pci to work with the VT-d
846 device, because host assigned devices requires to setup
847 the DMA mapping on the host before guest DMA starts.
848 device-iotlb=on|off (default: off)
850 This enables device-iotlb capability for the emulated
851 VT-d device. So far virtio/vhost should be the only real
852 user for this parameter, paired with ats=on configured
853 for the device.
854 aw-bits=39|48 (default: 39)
856 This decides the address width of IOVA address space.
857 The address space has 39 bits width for 3-level IOMMU
858 page tables, and 48 bits for 4-level IOMMU page tables.
859 Please also refer to the wiki page for general scenarios of VT-d
861 emulation in QEMU: https://wiki.qemu.org/Features/VT-d.
862 -name name
864 Sets the name of the guest. This name will be displayed in the
865 SDL window caption. The name will also be used for the VNC
866 server. Also optionally set the top visible process name in
867 Linux. Naming of individual threads can also be enabled on Linux
868 to aid debugging.
869 -uuid uuid
871 Set system UUID.
872 Block device options
874 -fda file
875 -fdb file
878 Use file as floppy disk 0/1 image (see the disk images chapter
879 in the System Emulation Users Guide).
880 -hda file
882 -hdb file
885 -hdc file
888 -hdd file
891 Use file as hard disk 0, 1, 2 or 3 image (see the disk images
892 chapter in the System Emulation Users Guide).
893 -cdrom file
895 Use file as CD-ROM image (you cannot use -hdc and -cdrom at the
896 same time). You can use the host CD-ROM by using /dev/cdrom as
897 filename.
898 -blockdev option[,option[,option[,...]]]
900 Define a new block driver node. Some of the options apply to all
901 block drivers, other options are only accepted for a specific
902 block driver. See below for a list of generic options and op‐
903 tions for the most common block drivers.
904 Options that expect a reference to another node (e.g. file) can
906 be given in two ways. Either you specify the node name of an al‐
907 ready existing node (file=node-name), or you define a new node
908 inline, adding options for the referenced node after a dot
909 (file.filename=path,file.aio=native).
910 A block driver node created with -blockdev can be used for a
912 guest device by specifying its node name for the drive property
913 in a -device argument that defines a block device.
914 Valid options for any block driver node:
916 driver Specifies the block driver to use for the given
918 node.
919 node-name
921 This defines the name of the block driver node by
922 which it will be referenced later. The name must
923 be unique, i.e. it must not match the name of a
924 different block driver node, or (if you use -drive
925 as well) the ID of a drive.
926 If no node name is specified, it is automatically
928 generated. The generated node name is not in‐
929 tended to be predictable and changes between QEMU
930 invocations. For the top level, an explicit node
931 name must be specified.
932 read-only
934 Open the node read-only. Guest write attempts will
935 fail.
936 Note that some block drivers support only
938 read-only access, either generally or in certain
939 configurations. In this case, the default value
940 read-only=off does not work and the option must be
941 specified explicitly.
942 auto-read-only
944 If auto-read-only=on is set, QEMU may fall back to
945 read-only usage even when read-only=off is re‐
946 quested, or even switch between modes as needed,
947 e.g. depending on whether the image file is
948 writable or whether a writing user is attached to
949 the node.
950 force-share
952 Override the image locking system of QEMU by forc‐
953 ing the node to utilize weaker shared access for
954 permissions where it would normally request exclu‐
955 sive access. When there is the potential for mul‐
956 tiple instances to have the same file open
957 (whether this invocation of QEMU is the first or
958 the second instance), both instances must permit
959 shared access for the second instance to succeed
960 at opening the file.
961 Enabling force-share=on requires read-only=on.
963 cache.direct
965 The host page cache can be avoided with cache.di‐
966 rect=on. This will attempt to do disk IO directly
967 to the guest's memory. QEMU may still perform an
968 internal copy of the data.
969 cache.no-flush
971 In case you don't care about data integrity over
972 host failures, you can use cache.no-flush=on. This
973 option tells QEMU that it never needs to write any
974 data to the disk but can instead keep things in
975 cache. If anything goes wrong, like your host los‐
976 ing power, the disk storage getting disconnected
977 accidentally, etc. your image will most probably
978 be rendered unusable.
979 discard=discard
981 discard is one of "ignore" (or "off") or "unmap"
982 (or "on") and controls whether discard (also known
983 as trim or unmap) requests are ignored or passed
984 to the filesystem. Some machine types may not
985 support discard requests.
986 detect-zeroes=detect-zeroes
988 detect-zeroes is "off", "on" or "unmap" and en‐
989 ables the automatic conversion of plain zero
990 writes by the OS to driver specific optimized zero
991 write commands. You may even choose "unmap" if
992 discard is set to "unmap" to allow a zero write to
993 be converted to an unmap operation.
994 Driver-specific options for file
996 This is the protocol-level block driver for accessing
997 regular files.
998 filename
1000 The path to the image file in the local filesystem
1001 aio Specifies the AIO backend (threads/native/io_ur‐
1003 ing, default: threads)
1004 locking
1006 Specifies whether the image file is protected with
1007 Linux OFD / POSIX locks. The default is to use the
1008 Linux Open File Descriptor API if available, oth‐
1009 erwise no lock is applied. (auto/on/off, default:
1010 auto)
1011 Example:
1013 -blockdev driver=file,node-name=disk,filename=disk.img
1015 Driver-specific options for raw
1017 This is the image format block driver for raw images. It
1018 is usually stacked on top of a protocol level block
1019 driver such as file.
1020 file Reference to or definition of the data source
1022 block driver node (e.g. a file driver node)
1023 Example 1:
1025 -blockdev driver=file,node-name=disk_file,filename=disk.img
1027 -blockdev driver=raw,node-name=disk,file=disk_file
1028 Example 2:
1030 -blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img
1032 Driver-specific options for qcow2
1034 This is the image format block driver for qcow2 images.
1035 It is usually stacked on top of a protocol level block
1036 driver such as file.
1037 file Reference to or definition of the data source
1039 block driver node (e.g. a file driver node)
1040 backing
1042 Reference to or definition of the backing file
1043 block device (default is taken from the image
1044 file). It is allowed to pass null here in order to
1045 disable the default backing file.
1046 lazy-refcounts
1048 Whether to enable the lazy refcounts feature
1049 (on/off; default is taken from the image file)
1050 cache-size
1052 The maximum total size of the L2 table and ref‐
1053 count block caches in bytes (default: the sum of
1054 l2-cache-size and refcount-cache-size)
1055 l2-cache-size
1057 The maximum size of the L2 table cache in bytes
1058 (default: if cache-size is not specified - 32M on
1059 Linux platforms, and 8M on non-Linux platforms;
1060 otherwise, as large as possible within the
1061 cache-size, while permitting the requested or the
1062 minimal refcount cache size)
1063 refcount-cache-size
1065 The maximum size of the refcount block cache in
1066 bytes (default: 4 times the cluster size; or if
1067 cache-size is specified, the part of it which is
1068 not used for the L2 cache)
1069 cache-clean-interval
1071 Clean unused entries in the L2 and refcount
1072 caches. The interval is in seconds. The default
1073 value is 600 on supporting platforms, and 0 on
1074 other platforms. Setting it to 0 disables this
1075 feature.
1076 pass-discard-request
1078 Whether discard requests to the qcow2 device
1079 should be forwarded to the data source (on/off;
1080 default: on if discard=unmap is specified, off
1081 otherwise)
1082 pass-discard-snapshot
1084 Whether discard requests for the data source
1085 should be issued when a snapshot operation (e.g.
1086 deleting a snapshot) frees clusters in the qcow2
1087 file (on/off; default: on)
1088 pass-discard-other
1090 Whether discard requests for the data source
1091 should be issued on other occasions where a clus‐
1092 ter gets freed (on/off; default: off)
1093 overlap-check
1095 Which overlap checks to perform for writes to the
1096 image (none/constant/cached/all; default: cached).
1097 For details or finer granularity control refer to
1098 the QAPI documentation of blockdev-add.
1099 Example 1:
1101 -blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2
1103 -blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216
1104 Example 2:
1106 -blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2
1108 Driver-specific options for other drivers
1110 Please refer to the QAPI documentation of the block‐
1111 dev-add QMP command.
1112 -drive option[,option[,option[,...]]]
1114 Define a new drive. This includes creating a block driver node
1115 (the backend) as well as a guest device, and is mostly a short‐
1116 cut for defining the corresponding -blockdev and -device op‐
1117 tions.
1118 -drive accepts all options that are accepted by -blockdev. In
1120 addition, it knows the following options:
1121 file=file
1123 This option defines which disk image (see the disk images
1124 chapter in the System Emulation Users Guide) to use with
1125 this drive. If the filename contains comma, you must
1126 double it (for instance, "file=my,,file" to use file
1127 "my,file").
1128 Special files such as iSCSI devices can be specified us‐
1130 ing protocol specific URLs. See the section for "Device
1131 URL Syntax" for more information.
1132 if=interface
1134 This option defines on which type on interface the drive
1135 is connected. Available types are: ide, scsi, sd, mtd,
1136 floppy, pflash, virtio, none.
1137 bus=bus,unit=unit
1139 These options define where is connected the drive by
1140 defining the bus number and the unit id.
1141 index=index
1143 This option defines where is connected the drive by using
1144 an index in the list of available connectors of a given
1145 interface type.
1146 media=media
1148 This option defines the type of the media: disk or cdrom.
1149 snapshot=snapshot
1151 snapshot is "on" or "off" and controls snapshot mode for
1152 the given drive (see -snapshot).
1153 cache=cache
1155 cache is "none", "writeback", "unsafe", "directsync" or
1156 "writethrough" and controls how the host cache is used to
1157 access block data. This is a shortcut that sets the
1158 cache.direct and cache.no-flush options (as in -block‐
1159 dev), and additionally cache.writeback, which provides a
1160 default for the write-cache option of block guest devices
1161 (as in -device). The modes correspond to the following
1162 settings:
1163 ┌─────────────┬─────────────────┬──────────────┬────────────────┐
1165 │ │ cache.writeback │ cache.direct │ cache.no-flush │
1166 ├─────────────┼─────────────────┼──────────────┼────────────────┤
1167 │writeback │ on │ off │ off │
1168 └─────────────┴─────────────────┴──────────────┴────────────────┘
1169 │none │ on │ on │ off │
1172 ├─────────────┼─────────────────┼──────────────┼────────────────┤
1173 │writethrough │ off │ off │ off │
1174 ├─────────────┼─────────────────┼──────────────┼────────────────┤
1175 │directsync │ off │ on │ off │
1176 ├─────────────┼─────────────────┼──────────────┼────────────────┤
1177 │unsafe │ on │ off │ on │
1178 └─────────────┴─────────────────┴──────────────┴────────────────┘
1179 The default mode is cache=writeback.
1181 aio=aio
1183 aio is "threads", "native", or "io_uring" and selects be‐
1184 tween pthread based disk I/O, native Linux AIO, or Linux
1185 io_uring API.
1186 format=format
1188 Specify which disk format will be used rather than de‐
1189 tecting the format. Can be used to specify format=raw to
1190 avoid interpreting an untrusted format header.
1191 werror=action,rerror=action
1193 Specify which action to take on write and read errors.
1194 Valid actions are: "ignore" (ignore the error and try to
1195 continue), "stop" (pause QEMU), "report" (report the er‐
1196 ror to the guest), "enospc" (pause QEMU only if the host
1197 disk is full; report the error to the guest otherwise).
1198 The default setting is werror=enospc and rerror=report.
1199 copy-on-read=copy-on-read
1201 copy-on-read is "on" or "off" and enables whether to copy
1202 read backing file sectors into the image file.
1203 bps=b,bps_rd=r,bps_wr=w
1205 Specify bandwidth throttling limits in bytes per second,
1206 either for all request types or for reads or writes only.
1207 Small values can lead to timeouts or hangs inside the
1208 guest. A safe minimum for disks is 2 MB/s.
1209 bps_max=bm,bps_rd_max=rm,bps_wr_max=wm
1211 Specify bursts in bytes per second, either for all re‐
1212 quest types or for reads or writes only. Bursts allow the
1213 guest I/O to spike above the limit temporarily.
1214 iops=i,iops_rd=r,iops_wr=w
1216 Specify request rate limits in requests per second, ei‐
1217 ther for all request types or for reads or writes only.
1218 iops_max=bm,iops_rd_max=rm,iops_wr_max=wm
1220 Specify bursts in requests 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_size=is
1225 Let every is bytes of a request count as a new request
1226 for iops throttling purposes. Use this option to prevent
1227 guests from circumventing iops limits by sending fewer
1228 but larger requests.
1229 group=g
1231 Join a throttling quota group with given name g. All
1232 drives that are members of the same group are accounted
1233 for together. Use this option to prevent guests from cir‐
1234 cumventing throttling limits by using many small disks
1235 instead of a single larger disk.
1236 By default, the cache.writeback=on mode is used. It will report
1238 data writes as completed as soon as the data is present in the
1239 host page cache. This is safe as long as your guest OS makes
1240 sure to correctly flush disk caches where needed. If your guest
1241 OS does not handle volatile disk write caches correctly and your
1242 host crashes or loses power, then the guest may experience data
1243 corruption.
1244 For such guests, you should consider using cache.writeback=off.
1246 This means that the host page cache will be used to read and
1247 write data, but write notification will be sent to the guest
1248 only after QEMU has made sure to flush each write to the disk.
1249 Be aware that this has a major impact on performance.
1250 When using the -snapshot option, unsafe caching is always used.
1252 Copy-on-read avoids accessing the same backing file sectors re‐
1254 peatedly and is useful when the backing file is over a slow net‐
1255 work. By default copy-on-read is off.
1256 Instead of -cdrom you can use:
1258 qemu-system-x86_64 -drive file=file,index=2,media=cdrom
1260 Instead of -hda, -hdb, -hdc, -hdd, you can use:
1262 qemu-system-x86_64 -drive file=file,index=0,media=disk
1264 qemu-system-x86_64 -drive file=file,index=1,media=disk
1265 qemu-system-x86_64 -drive file=file,index=2,media=disk
1266 qemu-system-x86_64 -drive file=file,index=3,media=disk
1267 You can open an image using pre-opened file descriptors from an
1269 fd set:
1270 qemu-system-x86_64 \
1272 -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \
1273 -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \
1274 -drive file=/dev/fdset/2,index=0,media=disk
1275 You can connect a CDROM to the slave of ide0:
1277 qemu-system-x86_64 -drive file=file,if=ide,index=1,media=cdrom
1279 If you don't specify the "file=" argument, you define an empty
1281 drive:
1282 qemu-system-x86_64 -drive if=ide,index=1,media=cdrom
1284 Instead of -fda, -fdb, you can use:
1286 qemu-system-x86_64 -drive file=file,index=0,if=floppy
1288 qemu-system-x86_64 -drive file=file,index=1,if=floppy
1289 By default, interface is "ide" and index is automatically incre‐
1291 mented:
1292 qemu-system-x86_64 -drive file=a -drive file=b"
1294 is interpreted like:
1296 qemu-system-x86_64 -hda a -hdb b
1298 -mtdblock file
1300 Use file as on-board Flash memory image.
1301 -sd file
1303 Use file as SecureDigital card image.
1304 -pflash file
1306 Use file as a parallel flash image.
1307 -snapshot
1309 Write to temporary files instead of disk image files. In this
1310 case, the raw disk image you use is not written back. You can
1311 however force the write back by pressing C-a s (see the disk im‐
1312 ages chapter in the System Emulation Users Guide).
1313 -fsdev local,id=id,path=path,security_model=security_model [,write‐
1315 out=writeout][,readonly=on][,fmode=fmode][,dmode=dmode] [,throt‐
1316 tling.option=value[,throttling.option=value[,...]]]
1317 -fsdev proxy,id=id,socket=socket[,writeout=writeout][,readonly=on]
1320 -fsdev proxy,id=id,sock_fd=sock_fd[,writeout=writeout][,readonly=on]
1323 -fsdev synth,id=id[,readonly=on]
1326 Define a new file system device. Valid options are:
1327 local Accesses to the filesystem are done by QEMU.
1329 proxy Accesses to the filesystem are done by
1331 virtfs-proxy-helper(1).
1332 synth Synthetic filesystem, only used by QTests.
1334 id=id Specifies identifier for this device.
1336 path=path
1338 Specifies the export path for the file system device.
1339 Files under this path will be available to the 9p client
1340 on the guest.
1341 security_model=security_model
1343 Specifies the security model to be used for this export
1344 path. Supported security models are "passthrough",
1345 "mapped-xattr", "mapped-file" and "none". In
1346 "passthrough" security model, files are stored using the
1347 same credentials as they are created on the guest. This
1348 requires QEMU to run as root. In "mapped-xattr" security
1349 model, some of the file attributes like uid, gid, mode
1350 bits and link target are stored as file attributes. For
1351 "mapped-file" these attributes are stored in the hidden
1352 .virtfs_metadata directory. Directories exported by this
1353 security model cannot interact with other unix tools.
1354 "none" security model is same as passthrough except the
1355 sever won't report failures if it fails to set file at‐
1356 tributes like ownership. Security model is mandatory only
1357 for local fsdriver. Other fsdrivers (like proxy) don't
1358 take security model as a parameter.
1359 writeout=writeout
1361 This is an optional argument. The only supported value is
1362 "immediate". This means that host page cache will be used
1363 to read and write data but write notification will be
1364 sent to the guest only when the data has been reported as
1365 written by the storage subsystem.
1366 readonly=on
1368 Enables exporting 9p share as a readonly mount for
1369 guests. By default read-write access is given.
1370 socket=socket
1372 Enables proxy filesystem driver to use passed socket file
1373 for communicating with virtfs-proxy-helper(1).
1374 sock_fd=sock_fd
1376 Enables proxy filesystem driver to use passed socket de‐
1377 scriptor for communicating with virtfs-proxy-helper(1).
1378 Usually a helper like libvirt will create socketpair and
1379 pass one of the fds as sock_fd.
1380 fmode=fmode
1382 Specifies the default mode for newly created files on the
1383 host. Works only with security models "mapped-xattr" and
1384 "mapped-file".
1385 dmode=dmode
1387 Specifies the default mode for newly created directories
1388 on the host. Works only with security models
1389 "mapped-xattr" and "mapped-file".
1390 throttling.bps-total=b,throttling.bps-read=r,throt‐
1392 tling.bps-write=w
1393 Specify bandwidth throttling limits in bytes per second,
1394 either for all request types or for reads or writes only.
1395 throttling.bps-total-max=bm,bps-read-max=rm,bps-write-max=wm
1397 Specify bursts in bytes per second, either for all re‐
1398 quest types or for reads or writes only. Bursts allow the
1399 guest I/O to spike above the limit temporarily.
1400 throttling.iops-total=i,throttling.iops-read=r, throt‐
1402 tling.iops-write=w
1403 Specify request rate limits in requests per second, ei‐
1404 ther for all request types or for reads or writes only.
1405 throttling.iops-total-max=im,throttling.iops-read-max=irm,
1407 throttling.iops-write-max=iwm
1408 Specify bursts in requests per second, either for all re‐
1409 quest types or for reads or writes only. Bursts allow the
1410 guest I/O to spike above the limit temporarily.
1411 throttling.iops-size=is
1413 Let every is bytes of a request count as a new request
1414 for iops throttling purposes.
1415 -fsdev option is used along with -device driver "virtio-9p-...".
1417 -device virtio-9p-type,fsdev=id,mount_tag=mount_tag
1419 Options for virtio-9p-... driver are:
1420 type Specifies the variant to be used. Supported values are
1422 "pci", "ccw" or "device", depending on the machine type.
1423 fsdev=id
1425 Specifies the id value specified along with -fsdev op‐
1426 tion.
1427 mount_tag=mount_tag
1429 Specifies the tag name to be used by the guest to mount
1430 this export point.
1431 -virtfs local,path=path,mount_tag=mount_tag ,security_model=secu‐
1433 rity_model[,writeout=writeout][,readonly=on]
1434 [,fmode=fmode][,dmode=dmode][,multidevs=multidevs]
1435 -virtfs proxy,socket=socket,mount_tag=mount_tag [,writeout=write‐
1438 out][,readonly=on]
1439 -virtfs proxy,sock_fd=sock_fd,mount_tag=mount_tag [,writeout=write‐
1442 out][,readonly=on]
1443 -virtfs synth,mount_tag=mount_tag
1446 Define a new virtual filesystem device and expose it to the
1447 guest using a virtio-9p-device (a.k.a. 9pfs), which essentially
1448 means that a certain directory on host is made directly accessi‐
1449 ble by guest as a pass-through file system by using the 9P net‐
1450 work protocol for communication between host and guests, if de‐
1451 sired even accessible, shared by several guests simultaniously.
1452 Note that -virtfs is actually just a convenience shortcut for
1454 its generalized form -fsdev -device virtio-9p-pci.
1455 The general form of pass-through file system options are:
1457 local Accesses to the filesystem are done by QEMU.
1459 proxy Accesses to the filesystem are done by
1461 virtfs-proxy-helper(1).
1462 synth Synthetic filesystem, only used by QTests.
1464 id=id Specifies identifier for the filesystem device
1466 path=path
1468 Specifies the export path for the file system device.
1469 Files under this path will be available to the 9p client
1470 on the guest.
1471 security_model=security_model
1473 Specifies the security model to be used for this export
1474 path. Supported security models are "passthrough",
1475 "mapped-xattr", "mapped-file" and "none". In
1476 "passthrough" security model, files are stored using the
1477 same credentials as they are created on the guest. This
1478 requires QEMU to run as root. In "mapped-xattr" security
1479 model, some of the file attributes like uid, gid, mode
1480 bits and link target are stored as file attributes. For
1481 "mapped-file" these attributes are stored in the hidden
1482 .virtfs_metadata directory. Directories exported by this
1483 security model cannot interact with other unix tools.
1484 "none" security model is same as passthrough except the
1485 sever won't report failures if it fails to set file at‐
1486 tributes like ownership. Security model is mandatory only
1487 for local fsdriver. Other fsdrivers (like proxy) don't
1488 take security model as a parameter.
1489 writeout=writeout
1491 This is an optional argument. The only supported value is
1492 "immediate". This means that host page cache will be used
1493 to read and write data but write notification will be
1494 sent to the guest only when the data has been reported as
1495 written by the storage subsystem.
1496 readonly=on
1498 Enables exporting 9p share as a readonly mount for
1499 guests. By default read-write access is given.
1500 socket=socket
1502 Enables proxy filesystem driver to use passed socket file
1503 for communicating with virtfs-proxy-helper(1). Usually a
1504 helper like libvirt will create socketpair and pass one
1505 of the fds as sock_fd.
1506 sock_fd
1508 Enables proxy filesystem driver to use passed 'sock_fd'
1509 as the socket descriptor for interfacing with
1510 virtfs-proxy-helper(1).
1511 fmode=fmode
1513 Specifies the default mode for newly created files on the
1514 host. Works only with security models "mapped-xattr" and
1515 "mapped-file".
1516 dmode=dmode
1518 Specifies the default mode for newly created directories
1519 on the host. Works only with security models
1520 "mapped-xattr" and "mapped-file".
1521 mount_tag=mount_tag
1523 Specifies the tag name to be used by the guest to mount
1524 this export point.
1525 multidevs=multidevs
1527 Specifies how to deal with multiple devices being shared
1528 with a 9p export. Supported behaviours are either
1529 "remap", "forbid" or "warn". The latter is the default
1530 behaviour on which virtfs 9p expects only one device to
1531 be shared with the same export, and if more than one de‐
1532 vice is shared and accessed via the same 9p export then
1533 only a warning message is logged (once) by qemu on host
1534 side. In order to avoid file ID collisions on guest you
1535 should either create a separate virtfs export for each
1536 device to be shared with guests (recommended way) or you
1537 might use "remap" instead which allows you to share mul‐
1538 tiple devices with only one export instead, which is
1539 achieved by remapping the original inode numbers from
1540 host to guest in a way that would prevent such colli‐
1541 sions. Remapping inodes in such use cases is required be‐
1542 cause the original device IDs from host are never passed
1543 and exposed on guest. Instead all files of an export
1544 shared with virtfs always share the same device id on
1545 guest. So two files with identical inode numbers but from
1546 actually different devices on host would otherwise cause
1547 a file ID collision and hence potential misbehaviours on
1548 guest. "forbid" on the other hand assumes like "warn"
1549 that only one device is shared by the same export, how‐
1550 ever it will not only log a warning message but also deny
1551 access to additional devices on guest. Note though that
1552 "forbid" does currently not block all possible file ac‐
1553 cess operations (e.g. readdir() would still return en‐
1554 tries from other devices).
1555 -iscsi Configure iSCSI session parameters.
1557 USB convenience options
1559 -usb Enable USB emulation on machine types with an on-board USB host
1560 controller (if not enabled by default). Note that on-board USB
1561 host controllers may not support USB 3.0. In this case -device
1562 qemu-xhci can be used instead on machines with PCI.
1563 -usbdevice devname
1565 Add the USB device devname, and enable an on-board USB con‐
1566 troller if possible and necessary (just like it can be done via
1567 -machine usb=on). Note that this option is mainly intended for
1568 the user's convenience only. More fine-grained control can be
1569 achieved by selecting a USB host controller (if necessary) and
1570 the desired USB device via the -device option instead. For exam‐
1571 ple, instead of using -usbdevice mouse it is possible to use
1572 -device qemu-xhci -device usb-mouse to connect the USB mouse to
1573 a USB 3.0 controller instead (at least on machines that support
1574 PCI and do not have an USB controller enabled by default yet).
1575 For more details, see the chapter about Connecting USB devices
1576 in the System Emulation Users Guide. Possible devices for dev‐
1577 name are:
1578 braille
1580 Braille device. This will use BrlAPI to display the
1581 braille output on a real or fake device (i.e. it also
1582 creates a corresponding braille chardev automatically be‐
1583 side the usb-braille USB device).
1584 keyboard
1586 Standard USB keyboard. Will override the PS/2 keyboard
1587 (if present).
1588 mouse Virtual Mouse. This will override the PS/2 mouse emula‐
1590 tion when activated.
1591 tablet Pointer device that uses absolute coordinates (like a
1593 touchscreen). This means QEMU is able to report the mouse
1594 position without having to grab the mouse. Also overrides
1595 the PS/2 mouse emulation when activated.
1596 wacom-tablet
1598 Wacom PenPartner USB tablet.
1599 Display options
1601 -display type
1602 Select type of display to use. This option is a replacement for
1603 the old style -sdl/-curses/... options. Use -display help to
1604 list the available display types. Valid values for type are
1605 spice-app[,gl=on|off]
1607 Start QEMU as a Spice server and launch the default Spice
1608 client application. The Spice server will redirect the
1609 serial consoles and QEMU monitors. (Since 4.0)
1610 sdl Display video output via SDL (usually in a separate
1612 graphics window; see the SDL documentation for other pos‐
1613 sibilities). Valid parameters are:
1614 alt_grab=on|off : Use Control+Alt+Shift-g to toggle mouse
1616 grabbing
1617 ctrl_grab=on|off : Use Right-Control-g to toggle mouse
1619 grabbing
1620 gl=on|off|core|es : Use OpenGL for displaying
1622 show-cursor=on|off : Force showing the mouse cursor
1624 window-close=on|off : Allow to quit qemu with window
1626 close button
1627 gtk Display video output in a GTK window. This interface pro‐
1629 vides drop-down menus and other UI elements to configure
1630 and control the VM during runtime. Valid parameters are:
1631 full-screen=on|off : Start in fullscreen mode
1633 gl=on|off : Use OpenGL for displaying
1635 grab-on-hover=on|off : Grab keyboard input on mouse hover
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 curses[,charset=<encoding>]
1644 Display video output via curses. For graphics device mod‐
1645 els which support a text mode, QEMU can display this out‐
1646 put using a curses/ncurses interface. Nothing is dis‐
1647 played when the graphics device is in graphical mode or
1648 if the graphics device does not support a text mode. Gen‐
1649 erally only the VGA device models support text mode. The
1650 font charset used by the guest can be specified with the
1651 charset option, for example charset=CP850 for IBM CP850
1652 encoding. The default is CP437.
1653 egl-headless[,rendernode=<file>]
1655 Offload all OpenGL operations to a local DRI device. For
1656 any graphical display, this display needs to be paired
1657 with either VNC or SPICE displays.
1658 vnc=<display>
1660 Start a VNC server on display <display>
1661 none Do not display video output. The guest will still see an
1663 emulated graphics card, but its output will not be dis‐
1664 played to the QEMU user. This option differs from the
1665 -nographic option in that it only affects what is done
1666 with video output; -nographic also changes the destina‐
1667 tion of the serial and parallel port data.
1668 -nographic
1670 Normally, if QEMU is compiled with graphical window support, it
1671 displays output such as guest graphics, guest console, and the
1672 QEMU monitor in a window. With this option, you can totally dis‐
1673 able graphical output so that QEMU is a simple command line ap‐
1674 plication. The emulated serial port is redirected on the con‐
1675 sole and muxed with the monitor (unless redirected elsewhere ex‐
1676 plicitly). Therefore, you can still use QEMU to debug a Linux
1677 kernel with a serial console. Use C-a h for help on switching
1678 between the console and monitor.
1679 -curses
1681 Normally, if QEMU is compiled with graphical window support, it
1682 displays output such as guest graphics, guest console, and the
1683 QEMU monitor in a window. With this option, QEMU can display the
1684 VGA output when in text mode using a curses/ncurses interface.
1685 Nothing is displayed in graphical mode.
1686 -alt-grab
1688 Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note
1689 that this also affects the special keys (for fullscreen, moni‐
1690 tor-mode switching, etc).
1691 -ctrl-grab
1693 Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that
1694 this also affects the special keys (for fullscreen, monitor-mode
1695 switching, etc).
1696 -no-quit
1698 Disable window close capability (SDL and GTK only). This option
1699 is deprecated, please use -display ...,window-close=off instead.
1700 -sdl Enable SDL.
1702 -spice option[,option[,...]]
1704 Enable the spice remote desktop protocol. Valid options are
1705 port=<nr>
1707 Set the TCP port spice is listening on for plaintext
1708 channels.
1709 addr=<addr>
1711 Set the IP address spice is listening on. Default is any
1712 address.
1713 ipv4=on|off; ipv6=on|off; unix=on|off
1715 Force using the specified IP version.
1716 password=<string>
1718 Set the password you need to authenticate.
1719 This option is deprecated and insecure because it leaves
1721 the password visible in the process listing. Use pass‐
1722 word-secret instead.
1723 password-secret=<secret-id>
1725 Set the ID of the secret object containing the password
1726 you need to authenticate.
1727 sasl=on|off
1729 Require that the client use SASL to authenticate with the
1730 spice. The exact choice of authentication method used is
1731 controlled from the system / user's SASL configuration
1732 file for the 'qemu' service. This is typically found in
1733 /etc/sasl2/qemu.conf. If running QEMU as an unprivileged
1734 user, an environment variable SASL_CONF_PATH can be used
1735 to make it search alternate locations for the service
1736 config. While some SASL auth methods can also provide
1737 data encryption (eg GSSAPI), it is recommended that SASL
1738 always be combined with the 'tls' and 'x509' settings to
1739 enable use of SSL and server certificates. This ensures a
1740 data encryption preventing compromise of authentication
1741 credentials.
1742 disable-ticketing=on|off
1744 Allow client connects without authentication.
1745 disable-copy-paste=on|off
1747 Disable copy paste between the client and the guest.
1748 disable-agent-file-xfer=on|off
1750 Disable spice-vdagent based file-xfer between the client
1751 and the guest.
1752 tls-port=<nr>
1754 Set the TCP port spice is listening on for encrypted
1755 channels.
1756 x509-dir=<dir>
1758 Set the x509 file directory. Expects same filenames as
1759 -vnc $display,x509=$dir
1760 x509-key-file=<file>; x509-key-password=<file>;
1762 x509-cert-file=<file>; x509-cacert-file=<file>;
1763 x509-dh-key-file=<file>
1764 The x509 file names can also be configured individually.
1765 tls-ciphers=<list>
1767 Specify which ciphers to use.
1768 tls-channel=[main|display|cursor|inputs|record|playback]; plain‐
1770 text-channel=[main|display|cursor|inputs|record|playback]
1771 Force specific channel to be used with or without TLS en‐
1772 cryption. The options can be specified multiple times to
1773 configure multiple channels. The special name "default"
1774 can be used to set the default mode. For channels which
1775 are not explicitly forced into one mode the spice client
1776 is allowed to pick tls/plaintext as he pleases.
1777 image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
1779 Configure image compression (lossless). Default is
1780 auto_glz.
1781 jpeg-wan-compression=[auto|never|always]; zlib-glz-wan-compres‐
1783 sion=[auto|never|always]
1784 Configure wan image compression (lossy for slow links).
1785 Default is auto.
1786 streaming-video=[off|all|filter]
1788 Configure video stream detection. Default is off.
1789 agent-mouse=[on|off]
1791 Enable/disable passing mouse events via vdagent. Default
1792 is on.
1793 playback-compression=[on|off]
1795 Enable/disable audio stream compression (using celt
1796 0.5.1). Default is on.
1797 seamless-migration=[on|off]
1799 Enable/disable spice seamless migration. Default is off.
1800 gl=[on|off]
1802 Enable/disable OpenGL context. Default is off.
1803 rendernode=<file>
1805 DRM render node for OpenGL rendering. If not specified,
1806 it will pick the first available. (Since 2.9)
1807 -portrait
1809 Rotate graphical output 90 deg left (only PXA LCD).
1810 -rotate deg
1812 Rotate graphical output some deg left (only PXA LCD).
1813 -vga type
1815 Select type of VGA card to emulate. Valid values for type are
1816 cirrus Cirrus Logic GD5446 Video card. All Windows versions
1818 starting from Windows 95 should recognize and use this
1819 graphic card. For optimal performances, use 16 bit color
1820 depth in the guest and the host OS. (This card was the
1821 default before QEMU 2.2)
1822 std Standard VGA card with Bochs VBE extensions. If your
1824 guest OS supports the VESA 2.0 VBE extensions (e.g. Win‐
1825 dows XP) and if you want to use high resolution modes (>=
1826 1280x1024x16) then you should use this option. (This card
1827 is the default since QEMU 2.2)
1828 vmware VMWare SVGA-II compatible adapter. Use it if you have
1830 sufficiently recent XFree86/XOrg server or Windows guest
1831 with a driver for this card.
1832 qxl QXL paravirtual graphic card. It is VGA compatible (in‐
1834 cluding VESA 2.0 VBE support). Works best with qxl guest
1835 drivers installed though. Recommended choice when using
1836 the spice protocol.
1837 tcx (sun4m only) Sun TCX framebuffer. This is the default
1839 framebuffer for sun4m machines and offers both 8-bit and
1840 24-bit colour depths at a fixed resolution of 1024x768.
1841 cg3 (sun4m only) Sun cgthree framebuffer. This is a simple
1843 8-bit framebuffer for sun4m machines available in both
1844 1024x768 (OpenBIOS) and 1152x900 (OBP) resolutions aimed
1845 at people wishing to run older Solaris versions.
1846 virtio Virtio VGA card.
1848 none Disable VGA card.
1850 -full-screen
1852 Start in full screen.
1853 -g widthxheight[xdepth]
1855 Set the initial graphical resolution and depth (PPC, SPARC
1856 only).
1857 For PPC the default is 800x600x32.
1859 For SPARC with the TCX graphics device, the default is
1861 1024x768x8 with the option of 1024x768x24. For cgthree, the de‐
1862 fault is 1024x768x8 with the option of 1152x900x8 for people who
1863 wish to use OBP.
1864 -vnc display[,option[,option[,...]]]
1866 Normally, if QEMU is compiled with graphical window support, it
1867 displays output such as guest graphics, guest console, and the
1868 QEMU monitor in a window. With this option, you can have QEMU
1869 listen on VNC display display and redirect the VGA display over
1870 the VNC session. It is very useful to enable the usb tablet de‐
1871 vice when using this option (option -device usb-tablet). When
1872 using the VNC display, you must use the -k parameter to set the
1873 keyboard layout if you are not using en-us. Valid syntax for the
1874 display is
1875 to=L With this option, QEMU will try next available VNC dis‐
1877 plays, until the number L, if the origianlly defined
1878 "-vnc display" is not available, e.g. port 5900+display
1879 is already used by another application. By default, to=0.
1880 host:d TCP connections will only be allowed from host on display
1882 d. By convention the TCP port is 5900+d. Optionally, host
1883 can be omitted in which case the server will accept con‐
1884 nections from any host.
1885 unix:path
1887 Connections will be allowed over UNIX domain sockets
1888 where path is the location of a unix socket to listen for
1889 connections on.
1890 none VNC is initialized but not started. The monitor change
1892 command can be used to later start the VNC server.
1893 Following the display value there may be one or more option
1895 flags separated by commas. Valid options are
1896 reverse=on|off
1898 Connect to a listening VNC client via a "reverse" connec‐
1899 tion. The client is specified by the display. For re‐
1900 verse network connections (host:d,``reverse``), the d ar‐
1901 gument is a TCP port number, not a display number.
1902 websocket=on|off
1904 Opens an additional TCP listening port dedicated to VNC
1905 Websocket connections. If a bare websocket option is
1906 given, the Websocket port is 5700+display. An alternative
1907 port can be specified with the syntax websocket=port.
1908 If host is specified connections will only be allowed
1910 from this host. It is possible to control the websocket
1911 listen address independently, using the syntax web‐
1912 socket=host:port.
1913 If no TLS credentials are provided, the websocket connec‐
1915 tion runs in unencrypted mode. If TLS credentials are
1916 provided, the websocket connection requires encrypted
1917 client connections.
1918 password=on|off
1920 Require that password based authentication is used for
1921 client connections.
1922 The password must be set separately using the set_pass‐
1924 word command in the QEMU monitor. The syntax to change
1925 your password is: set_password <protocol> <password>
1926 where <protocol> could be either "vnc" or "spice".
1927 If you would like to change <protocol> password expira‐
1929 tion, you should use expire_password <protocol> <expira‐
1930 tion-time> where expiration time could be one of the fol‐
1931 lowing options: now, never, +seconds or UNIX time of ex‐
1932 piration, e.g. +60 to make password expire in 60 seconds,
1933 or 1335196800 to make password expire on "Mon Apr 23
1934 12:00:00 EDT 2012" (UNIX time for this date and time).
1935 You can also use keywords "now" or "never" for the expi‐
1937 ration time to allow <protocol> password to expire imme‐
1938 diately or never expire.
1939 password-secret=<secret-id>
1941 Require that password based authentication is used for
1942 client connections, using the password provided by the
1943 secret object identified by secret-id.
1944 tls-creds=ID
1946 Provides the ID of a set of TLS credentials to use to se‐
1947 cure the VNC server. They will apply to both the normal
1948 VNC server socket and the websocket socket (if enabled).
1949 Setting TLS credentials will cause the VNC server socket
1950 to enable the VeNCrypt auth mechanism. The credentials
1951 should have been previously created using the -object
1952 tls-creds argument.
1953 tls-authz=ID
1955 Provides the ID of the QAuthZ authorization object
1956 against which the client's x509 distinguished name will
1957 validated. This object is only resolved at time of use,
1958 so can be deleted and recreated on the fly while the VNC
1959 server is active. If missing, it will default to denying
1960 access.
1961 sasl=on|off
1963 Require that the client use SASL to authenticate with the
1964 VNC server. The exact choice of authentication method
1965 used is controlled from the system / user's SASL configu‐
1966 ration file for the 'qemu' service. This is typically
1967 found in /etc/sasl2/qemu.conf. If running QEMU as an un‐
1968 privileged user, an environment variable SASL_CONF_PATH
1969 can be used to make it search alternate locations for the
1970 service config. While some SASL auth methods can also
1971 provide data encryption (eg GSSAPI), it is recommended
1972 that SASL always be combined with the 'tls' and 'x509'
1973 settings to enable use of SSL and server certificates.
1974 This ensures a data encryption preventing compromise of
1975 authentication credentials. See the VNC security section
1976 in the System Emulation Users Guide for details on using
1977 SASL authentication.
1978 sasl-authz=ID
1980 Provides the ID of the QAuthZ authorization object
1981 against which the client's SASL username will validated.
1982 This object is only resolved at time of use, so can be
1983 deleted and recreated on the fly while the VNC server is
1984 active. If missing, it will default to denying access.
1985 acl=on|off
1987 Legacy method for enabling authorization of clients
1988 against the x509 distinguished name and SASL username. It
1989 results in the creation of two authz-list objects with
1990 IDs of vnc.username and vnc.x509dname. The rules for
1991 these objects must be configured with the HMP ACL com‐
1992 mands.
1993 This option is deprecated and should no longer be used.
1995 The new sasl-authz and tls-authz options are a replace‐
1996 ment.
1997 lossy=on|off
1999 Enable lossy compression methods (gradient, JPEG, ...).
2000 If this option is set, VNC client may receive lossy
2001 framebuffer updates depending on its encoding settings.
2002 Enabling this option can save a lot of bandwidth at the
2003 expense of quality.
2004 non-adaptive=on|off
2006 Disable adaptive encodings. Adaptive encodings are en‐
2007 abled by default. An adaptive encoding will try to detect
2008 frequently updated screen regions, and send updates in
2009 these regions using a lossy encoding (like JPEG). This
2010 can be really helpful to save bandwidth when playing
2011 videos. Disabling adaptive encodings restores the origi‐
2012 nal static behavior of encodings like Tight.
2013 share=[allow-exclusive|force-shared|ignore]
2015 Set display sharing policy. 'allow-exclusive' allows
2016 clients to ask for exclusive access. As suggested by the
2017 rfb spec this is implemented by dropping other connec‐
2018 tions. Connecting multiple clients in parallel requires
2019 all clients asking for a shared session (vncviewer:
2020 -shared switch). This is the default. 'force-shared'
2021 disables exclusive client access. Useful for shared desk‐
2022 top sessions, where you don't want someone forgetting
2023 specify -shared disconnect everybody else. 'ignore' com‐
2024 pletely ignores the shared flag and allows everybody con‐
2025 nect unconditionally. Doesn't conform to the rfb spec but
2026 is traditional QEMU behavior.
2027 key-delay-ms
2029 Set keyboard delay, for key down and key up events, in
2030 milliseconds. Default is 10. Keyboards are low-bandwidth
2031 devices, so this slowdown can help the device and guest
2032 to keep up and not lose events in case events are arriv‐
2033 ing in bulk. Possible causes for the latter are flaky
2034 network connections, or scripts for automated testing.
2035 audiodev=audiodev
2037 Use the specified audiodev when the VNC client requests
2038 audio transmission. When not using an -audiodev argument,
2039 this option must be omitted, otherwise is must be present
2040 and specify a valid audiodev.
2041 power-control=on|off
2043 Permit the remote client to issue shutdown, reboot or re‐
2044 set power control requests.
2045 i386 target only
2047 -win2k-hack
2048 Use it when installing Windows 2000 to avoid a disk full bug.
2049 After Windows 2000 is installed, you no longer need this option
2050 (this option slows down the IDE transfers).
2051 -no-fd-bootchk
2053 Disable boot signature checking for floppy disks in BIOS. May be
2054 needed to boot from old floppy disks.
2055 -no-acpi
2057 Disable ACPI (Advanced Configuration and Power Interface) sup‐
2058 port. Use it if your guest OS complains about ACPI problems (PC
2059 target machine only).
2060 -no-hpet
2062 Disable HPET support.
2063 -acpitable [sig=str][,rev=n][,oem_id=str][,oem_ta‐
2065 ble_id=str][,oem_rev=n] [,asl_compiler_id=str][,asl_com‐
2066 piler_rev=n][,data=file1[:file2]...]
2067 Add ACPI table with specified header fields and context from
2068 specified files. For file=, take whole ACPI table from the spec‐
2069 ified files, including all ACPI headers (possible overridden by
2070 other options). For data=, only data portion of the table is
2071 used, all header information is specified in the command line.
2072 If a SLIC table is supplied to QEMU, then the SLIC's oem_id and
2073 oem_table_id fields will override the same in the RSDT and the
2074 FADT (a.k.a. FACP), in order to ensure the field matches re‐
2075 quired by the Microsoft SLIC spec and the ACPI spec.
2076 -smbios file=binary
2078 Load SMBIOS entry from binary file.
2079 -smbios type=0[,vendor=str][,version=str][,date=str][,re‐
2081 lease=%d.%d][,uefi=on|off]
2082 Specify SMBIOS type 0 fields
2083 -smbios type=1[,manufacturer=str][,product=str][,version=str][,se‐
2085 rial=str][,uuid=uuid][,sku=str][,family=str]
2086 Specify SMBIOS type 1 fields
2087 -smbios type=2[,manufacturer=str][,product=str][,version=str][,se‐
2089 rial=str][,asset=str][,location=str]
2090 Specify SMBIOS type 2 fields
2091 -smbios type=3[,manufacturer=str][,version=str][,serial=str][,as‐
2093 set=str][,sku=str]
2094 Specify SMBIOS type 3 fields
2095 -smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,se‐
2097 rial=str][,asset=str][,part=str]
2098 Specify SMBIOS type 4 fields
2099 -smbios type=11[,value=str][,path=filename]
2101 Specify SMBIOS type 11 fields
2102 This argument can be repeated multiple times, and values are
2104 added in the order they are parsed. Applications intending to
2105 use OEM strings data are encouraged to use their application
2106 name as a prefix for the value string. This facilitates passing
2107 information for multiple applications concurrently.
2108 The value=str syntax provides the string data inline, while the
2110 path=filename syntax loads data from a file on disk. Note that
2111 the file is not permitted to contain any NUL bytes.
2112 Both the value and path options can be repeated multiple times
2114 and will be added to the SMBIOS table in the order in which they
2115 appear.
2116 Note that on the x86 architecture, the total size of all SMBIOS
2118 tables is limited to 65535 bytes. Thus the OEM strings data is
2119 not suitable for passing large amounts of data into the guest.
2120 Instead it should be used as a indicator to inform the guest
2121 where to locate the real data set, for example, by specifying
2122 the serial ID of a block device.
2123 An example passing three strings is
2125 -smbios type=11,value=cloud-init:ds=nocloud-net;s=http://10.10.0.1:8000/,\
2127 value=anaconda:method=http://dl.fedoraproject.org/pub/fedora/linux/releases/25/x86_64/os,\
2128 path=/some/file/with/oemstringsdata.txt
2129 In the guest OS this is visible with the dmidecode command
2131 $ dmidecode -t 11
2133 Handle 0x0E00, DMI type 11, 5 bytes
2134 OEM Strings
2135 String 1: cloud-init:ds=nocloud-net;s=http://10.10.0.1:8000/
2136 String 2: anaconda:method=http://dl.fedoraproject.org/pub/fedora/linux/releases/25/x86_64/os
2137 String 3: myapp:some extra data
2138 -smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,se‐
2140 rial=str][,asset=str][,part=str][,speed=%d]
2141 Specify SMBIOS type 17 fields
2142 -smbios type=41[,designation=str][,kind=str][,instance=%d][,pcidev=str]
2144 Specify SMBIOS type 41 fields
2145 This argument can be repeated multiple times. Its main use is
2147 to allow network interfaces be created as enoX on Linux, with X
2148 being the instance number, instead of the name depending on the
2149 interface position on the PCI bus.
2150 Here is an example of use:
2152 -netdev user,id=internet \
2154 -device virtio-net-pci,mac=50:54:00:00:00:42,netdev=internet,id=internet-dev \
2155 -smbios type=41,designation='Onboard LAN',instance=1,kind=ethernet,pcidev=internet-dev
2156 In the guest OS, the device should then appear as eno1:
2158 ..parsed-literal:
2160 $ ip -brief l
2162 lo UNKNOWN 00:00:00:00:00:00 <LOOPBACK,UP,LOWER_UP>
2163 eno1 UP 50:54:00:00:00:42 <BROADCAST,MULTICAST,UP,LOWER_UP>
2164 Currently, the PCI device has to be attached to the root bus.
2166 Network options
2168 -nic
2169 [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn]
2170 This option is a shortcut for configuring both the on-board (de‐
2171 fault) guest NIC hardware and the host network backend in one
2172 go. The host backend options are the same as with the corre‐
2173 sponding -netdev options below. The guest NIC model can be set
2174 with model=modelname. Use model=help to list the available de‐
2175 vice types. The hardware MAC address can be set with
2176 mac=macaddr.
2177 The following two example do exactly the same, to show how -nic
2179 can be used to shorten the command line length:
2180 qemu-system-x86_64 -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32
2182 qemu-system-x86_64 -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32
2183 -nic none
2185 Indicate that no network devices should be configured. It is
2186 used to override the default configuration (default NIC with
2187 "user" host network backend) which is activated if no other net‐
2188 working options are provided.
2189 -netdev user,id=id[,option][,option][,...]
2191 Configure user mode host network backend which requires no ad‐
2192 ministrator privilege to run. Valid options are:
2193 id=id Assign symbolic name for use in monitor commands.
2195 ipv4=on|off and ipv6=on|off
2197 Specify that either IPv4 or IPv6 must be enabled. If nei‐
2198 ther is specified both protocols are enabled.
2199 net=addr[/mask]
2201 Set IP network address the guest will see. Optionally
2202 specify the netmask, either in the form a.b.c.d or as
2203 number of valid top-most bits. Default is 10.0.2.0/24.
2204 host=addr
2206 Specify the guest-visible address of the host. Default is
2207 the 2nd IP in the guest network, i.e. x.x.x.2.
2208 ipv6-net=addr[/int]
2210 Set IPv6 network address the guest will see (default is
2211 fec0::/64). The network prefix is given in the usual
2212 hexadecimal IPv6 address notation. The prefix size is op‐
2213 tional, and is given as the number of valid top-most bits
2214 (default is 64).
2215 ipv6-host=addr
2217 Specify the guest-visible IPv6 address of the host. De‐
2218 fault is the 2nd IPv6 in the guest network, i.e. xxxx::2.
2219 restrict=on|off
2221 If this option is enabled, the guest will be isolated,
2222 i.e. it will not be able to contact the host and no guest
2223 IP packets will be routed over the host to the outside.
2224 This option does not affect any explicitly set forwarding
2225 rules.
2226 hostname=name
2228 Specifies the client hostname reported by the built-in
2229 DHCP server.
2230 dhcpstart=addr
2232 Specify the first of the 16 IPs the built-in DHCP server
2233 can assign. Default is the 15th to 31st IP in the guest
2234 network, i.e. x.x.x.15 to x.x.x.31.
2235 dns=addr
2237 Specify the guest-visible address of the virtual name‐
2238 server. The address must be different from the host ad‐
2239 dress. Default is the 3rd IP in the guest network, i.e.
2240 x.x.x.3.
2241 ipv6-dns=addr
2243 Specify the guest-visible address of the IPv6 virtual
2244 nameserver. The address must be different from the host
2245 address. Default is the 3rd IP in the guest network,
2246 i.e. xxxx::3.
2247 dnssearch=domain
2249 Provides an entry for the domain-search list sent by the
2250 built-in DHCP server. More than one domain suffix can be
2251 transmitted by specifying this option multiple times. If
2252 supported, this will cause the guest to automatically try
2253 to append the given domain suffix(es) in case a domain
2254 name can not be resolved.
2255 Example:
2257 qemu-system-x86_64 -nic user,dnssearch=mgmt.example.org,dnssearch=example.org
2259 domainname=domain
2261 Specifies the client domain name reported by the built-in
2262 DHCP server.
2263 tftp=dir
2265 When using the user mode network stack, activate a
2266 built-in TFTP server. The files in dir will be exposed as
2267 the root of a TFTP server. The TFTP client on the guest
2268 must be configured in binary mode (use the command bin of
2269 the Unix TFTP client).
2270 tftp-server-name=name
2272 In BOOTP reply, broadcast name as the "TFTP server name"
2273 (RFC2132 option 66). This can be used to advise the guest
2274 to load boot files or configurations from a different
2275 server than the host address.
2276 bootfile=file
2278 When using the user mode network stack, broadcast file as
2279 the BOOTP filename. In conjunction with tftp, this can be
2280 used to network boot a guest from a local directory.
2281 Example (using pxelinux):
2283 qemu-system-x86_64 -hda linux.img -boot n -device e1000,netdev=n1 \
2285 -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
2286 smb=dir[,smbserver=addr]
2288 When using the user mode network stack, activate a
2289 built-in SMB server so that Windows OSes can access to
2290 the host files in dir transparently. The IP address of
2291 the SMB server can be set to addr. By default the 4th IP
2292 in the guest network is used, i.e. x.x.x.4.
2293 In the guest Windows OS, the line:
2295 10.0.2.4 smbserver
2297 must be added in the file C:\WINDOWS\LMHOSTS (for windows
2299 9x/Me) or C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS (Windows
2300 NT/2000).
2301 Then dir can be accessed in \\smbserver\qemu.
2303 Note that a SAMBA server must be installed on the host
2305 OS.
2306 hostfwd=[tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport
2308 Redirect incoming TCP or UDP connections to the host port
2309 hostport to the guest IP address guestaddr on guest port
2310 guestport. If guestaddr is not specified, its value is
2311 x.x.x.15 (default first address given by the built-in
2312 DHCP server). By specifying hostaddr, the rule can be
2313 bound to a specific host interface. If no connection type
2314 is set, TCP is used. This option can be given multiple
2315 times.
2316 For example, to redirect host X11 connection from screen
2318 1 to guest screen 0, use the following:
2319 # on the host
2321 qemu-system-x86_64 -nic user,hostfwd=tcp:127.0.0.1:6001-:6000
2322 # this host xterm should open in the guest X11 server
2323 xterm -display :1
2324 To redirect telnet connections from host port 5555 to
2326 telnet port on the guest, use the following:
2327 # on the host
2329 qemu-system-x86_64 -nic user,hostfwd=tcp::5555-:23
2330 telnet localhost 5555
2331 Then when you use on the host telnet localhost 5555, you
2333 connect to the guest telnet server.
2334 guestfwd=[tcp]:server:port-dev; guest‐
2336 fwd=[tcp]:server:port-cmd:command
2337 Forward guest TCP connections to the IP address server on
2338 port port to the character device dev or to a program ex‐
2339 ecuted by cmd:command which gets spawned for each connec‐
2340 tion. This option can be given multiple times.
2341 You can either use a chardev directly and have that one
2343 used throughout QEMU's lifetime, like in the following
2344 example:
2345 # open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
2347 # the guest accesses it
2348 qemu-system-x86_64 -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321
2349 Or you can execute a command on every TCP connection es‐
2351 tablished by the guest, so that QEMU behaves similar to
2352 an inetd process for that virtual server:
2353 # call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
2355 # and connect the TCP stream to its stdin/stdout
2356 qemu-system-x86_64 -nic 'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
2357 -netdev tap,id=id[,fd=h][,ifname=name][,script=file][,down‐
2359 script=dfile][,br=bridge][,helper=helper]
2360 Configure a host TAP network backend with ID id.
2361 Use the network script file to configure it and the network
2363 script dfile to deconfigure it. If name is not provided, the OS
2364 automatically provides one. The default network configure script
2365 is /etc/qemu-ifup and the default network deconfigure script is
2366 /etc/qemu-ifdown. Use script=no or downscript=no to disable
2367 script execution.
2368 If running QEMU as an unprivileged user, use the network helper
2370 to configure the TAP interface and attach it to the bridge. The
2371 default network helper executable is /path/to/qemu-bridge-helper
2372 and the default bridge device is br0.
2373 fd=h can be used to specify the handle of an already opened host
2375 TAP interface.
2376 Examples:
2378 #launch a QEMU instance with the default network script
2380 qemu-system-x86_64 linux.img -nic tap
2381 #launch a QEMU instance with two NICs, each one connected
2383 #to a TAP device
2384 qemu-system-x86_64 linux.img \
2385 -netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 \
2386 -netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1
2387 #launch a QEMU instance with the default network helper to
2389 #connect a TAP device to bridge br0
2390 qemu-system-x86_64 linux.img -device virtio-net-pci,netdev=n1 \
2391 -netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper"
2392 -netdev bridge,id=id[,br=bridge][,helper=helper]
2394 Connect a host TAP network interface to a host bridge device.
2395 Use the network helper helper to configure the TAP interface and
2397 attach it to the bridge. The default network helper executable
2398 is /path/to/qemu-bridge-helper and the default bridge device is
2399 br0.
2400 Examples:
2402 #launch a QEMU instance with the default network helper to
2404 #connect a TAP device to bridge br0
2405 qemu-system-x86_64 linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1
2406 #launch a QEMU instance with the default network helper to
2408 #connect a TAP device to bridge qemubr0
2409 qemu-system-x86_64 linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1
2410 -netdev socket,id=id[,fd=h][,listen=[host]:port][,connect=host:port]
2412 This host network backend can be used to connect the guest's
2413 network to another QEMU virtual machine using a TCP socket con‐
2414 nection. If listen is specified, QEMU waits for incoming connec‐
2415 tions on port (host is optional). connect is used to connect to
2416 another QEMU instance using the listen option. fd=h specifies an
2417 already opened TCP socket.
2418 Example:
2420 # launch a first QEMU instance
2422 qemu-system-x86_64 linux.img \
2423 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2424 -netdev socket,id=n1,listen=:1234
2425 # connect the network of this instance to the network of the first instance
2426 qemu-system-x86_64 linux.img \
2427 -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
2428 -netdev socket,id=n2,connect=127.0.0.1:1234
2429 -netdev socket,id=id[,fd=h][,mcast=maddr:port[,localaddr=addr]]
2431 Configure a socket host network backend to share the guest's
2432 network traffic with another QEMU virtual machines using a UDP
2433 multicast socket, effectively making a bus for every QEMU with
2434 same multicast address maddr and port. NOTES:
2435 1. Several QEMU can be running on different hosts and share same
2437 bus (assuming correct multicast setup for these hosts).
2438 2. mcast support is compatible with User Mode Linux (argument
2440 ethN=mcast), see http://user-mode-linux.sf.net.
2441 3. Use fd=h to specify an already opened UDP multicast socket.
2443 Example:
2445 # launch one QEMU instance
2447 qemu-system-x86_64 linux.img \
2448 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2449 -netdev socket,id=n1,mcast=230.0.0.1:1234
2450 # launch another QEMU instance on same "bus"
2451 qemu-system-x86_64 linux.img \
2452 -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
2453 -netdev socket,id=n2,mcast=230.0.0.1:1234
2454 # launch yet another QEMU instance on same "bus"
2455 qemu-system-x86_64 linux.img \
2456 -device e1000,netdev=n3,mac=52:54:00:12:34:58 \
2457 -netdev socket,id=n3,mcast=230.0.0.1:1234
2458 Example (User Mode Linux compat.):
2460 # launch QEMU instance (note mcast address selected is UML's default)
2462 qemu-system-x86_64 linux.img \
2463 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2464 -netdev socket,id=n1,mcast=239.192.168.1:1102
2465 # launch UML
2466 /path/to/linux ubd0=/path/to/root_fs eth0=mcast
2467 Example (send packets from host's 1.2.3.4):
2469 qemu-system-x86_64 linux.img \
2471 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2472 -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4
2473 -netdev l2tpv3,id=id,src=srcaddr,dst=dstaddr[,srcport=srcport][,dst‐
2475 port=dstport],txsession=txsession[,rxsession=rxses‐
2476 sion][,ipv6=on|off][,udp=on|off][,cookie64][,counter][,pincounter][,tx‐
2477 cookie=txcookie][,rxcookie=rxcookie][,offset=offset]
2478 Configure a L2TPv3 pseudowire host network backend. L2TPv3
2479 (RFC3931) is a popular protocol to transport Ethernet (and other
2480 Layer 2) data frames between two systems. It is present in
2481 routers, firewalls and the Linux kernel (from version 3.3 on‐
2482 wards).
2483 This transport allows a VM to communicate to another VM, router
2485 or firewall directly.
2486 src=srcaddr
2488 source address (mandatory)
2489 dst=dstaddr
2491 destination address (mandatory)
2492 udp select udp encapsulation (default is ip).
2494 srcport=srcport
2496 source udp port.
2497 dstport=dstport
2499 destination udp port.
2500 ipv6 force v6, otherwise defaults to v4.
2502 rxcookie=rxcookie; txcookie=txcookie
2504 Cookies are a weak form of security in the l2tpv3 speci‐
2505 fication. Their function is mostly to prevent misconfig‐
2506 uration. By default they are 32 bit.
2507 cookie64
2509 Set cookie size to 64 bit instead of the default 32
2510 counter=off
2512 Force a 'cut-down' L2TPv3 with no counter as in
2513 draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
2514 pincounter=on
2516 Work around broken counter handling in peer. This may
2517 also help on networks which have packet reorder.
2518 offset=offset
2520 Add an extra offset between header and data
2521 For example, to attach a VM running on host 4.3.2.1 via L2TPv3
2523 to the bridge br-lan on the remote Linux host 1.2.3.4:
2524 # Setup tunnel on linux host using raw ip as encapsulation
2526 # on 1.2.3.4
2527 ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \
2528 encap udp udp_sport 16384 udp_dport 16384
2529 ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \
2530 0xFFFFFFFF peer_session_id 0xFFFFFFFF
2531 ifconfig vmtunnel0 mtu 1500
2532 ifconfig vmtunnel0 up
2533 brctl addif br-lan vmtunnel0
2534 # on 4.3.2.1
2537 # launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
2538 qemu-system-x86_64 linux.img -device e1000,netdev=n1 \
2540 -netdev l2tpv3,id=n1,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter
2541 -netdev vde,id=id[,sock=socketpath][,port=n][,group=group‐
2543 name][,mode=octalmode]
2544 Configure VDE backend to connect to PORT n of a vde switch run‐
2545 ning on host and listening for incoming connections on socket‐
2546 path. Use GROUP groupname and MODE octalmode to change default
2547 ownership and permissions for communication port. This option is
2548 only available if QEMU has been compiled with vde support en‐
2549 abled.
2550 Example:
2552 # launch vde switch
2554 vde_switch -F -sock /tmp/myswitch
2555 # launch QEMU instance
2556 qemu-system-x86_64 linux.img -nic vde,sock=/tmp/myswitch
2557 -netdev vhost-user,chardev=id[,vhostforce=on|off][,queues=n]
2559 Establish a vhost-user netdev, backed by a chardev id. The
2560 chardev should be a unix domain socket backed one. The
2561 vhost-user uses a specifically defined protocol to pass vhost
2562 ioctl replacement messages to an application on the other end of
2563 the socket. On non-MSIX guests, the feature can be forced with
2564 vhostforce. Use 'queues=n' to specify the number of queues to be
2565 created for multiqueue vhost-user.
2566 Example:
2568 qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
2570 -numa node,memdev=mem \
2571 -chardev socket,id=chr0,path=/path/to/socket \
2572 -netdev type=vhost-user,id=net0,chardev=chr0 \
2573 -device virtio-net-pci,netdev=net0
2574 -netdev vhost-vdpa,vhostdev=/path/to/dev
2576 Establish a vhost-vdpa netdev.
2577 vDPA device is a device that uses a datapath which complies with
2579 the virtio specifications with a vendor specific control path.
2580 vDPA devices can be both physically located on the hardware or
2581 emulated by software.
2582 -netdev hubport,id=id,hubid=hubid[,netdev=nd]
2584 Create a hub port on the emulated hub with ID hubid.
2585 The hubport netdev lets you connect a NIC to a QEMU emulated hub
2587 instead of a single netdev. Alternatively, you can also connect
2588 the hubport to another netdev with ID nd by using the netdev=nd
2589 option.
2590 -net nic[,netdev=nd][,macaddr=mac][,model=type]
2592 [,name=name][,addr=addr][,vectors=v]
2593 Legacy option to configure or create an on-board (or machine de‐
2594 fault) Network Interface Card(NIC) and connect it either to the
2595 emulated hub with ID 0 (i.e. the default hub), or to the netdev
2596 nd. If model is omitted, then the default NIC model associated
2597 with the machine type is used. Note that the default NIC model
2598 may change in future QEMU releases, so it is highly recommended
2599 to always specify a model. Optionally, the MAC address can be
2600 changed to mac, the device address set to addr (PCI cards only),
2601 and a name can be assigned for use in monitor commands. Option‐
2602 ally, for PCI cards, you can specify the number v of MSI-X vec‐
2603 tors that the card should have; this option currently only af‐
2604 fects virtio cards; set v = 0 to disable MSI-X. If no -net op‐
2605 tion is specified, a single NIC is created. QEMU can emulate
2606 several different models of network card. Use -net
2607 nic,model=help for a list of available devices for your target.
2608 -net user|tap|bridge|socket|l2tpv3|vde[,...][,name=name]
2610 Configure a host network backend (with the options corresponding
2611 to the same -netdev option) and connect it to the emulated hub 0
2612 (the default hub). Use name to specify the name of the hub port.
2613 Character device options
2615 The general form of a character device option is:
2616 -chardev backend,id=id[,mux=on|off][,options]
2618 Backend is one of: null, socket, udp, msmouse, vc, ringbuf,
2619 file, pipe, console, serial, pty, stdio, braille, tty, parallel,
2620 parport, spicevmc, spiceport. The specific backend will deter‐
2621 mine the applicable options.
2622 Use -chardev help to print all available chardev backend types.
2624 All devices must have an id, which can be any string up to 127
2626 characters long. It is used to uniquely identify this device in
2627 other command line directives.
2628 A character device may be used in multiplexing mode by multiple
2630 front-ends. Specify mux=on to enable this mode. A multiplexer is
2631 a "1:N" device, and here the "1" end is your specified chardev
2632 backend, and the "N" end is the various parts of QEMU that can
2633 talk to a chardev. If you create a chardev with id=myid and
2634 mux=on, QEMU will create a multiplexer with your specified ID,
2635 and you can then configure multiple front ends to use that
2636 chardev ID for their input/output. Up to four different front
2637 ends can be connected to a single multiplexed chardev. (Without
2638 multiplexing enabled, a chardev can only be used by a single
2639 front end.) For instance you could use this to allow a single
2640 stdio chardev to be used by two serial ports and the QEMU moni‐
2641 tor:
2642 -chardev stdio,mux=on,id=char0 \
2644 -mon chardev=char0,mode=readline \
2645 -serial chardev:char0 \
2646 -serial chardev:char0
2647 You can have more than one multiplexer in a system configura‐
2649 tion; for instance you could have a TCP port multiplexed between
2650 UART 0 and UART 1, and stdio multiplexed between the QEMU moni‐
2651 tor and a parallel port:
2652 -chardev stdio,mux=on,id=char0 \
2654 -mon chardev=char0,mode=readline \
2655 -parallel chardev:char0 \
2656 -chardev tcp,...,mux=on,id=char1 \
2657 -serial chardev:char1 \
2658 -serial chardev:char1
2659 When you're using a multiplexed character device, some escape
2661 sequences are interpreted in the input. See the chapter about
2662 keys in the character backend multiplexer in the System Emula‐
2663 tion Users Guide for more details.
2664 Note that some other command line options may implicitly create
2666 multiplexed character backends; for instance -serial mon:stdio
2667 creates a multiplexed stdio backend connected to the serial port
2668 and the QEMU monitor, and -nographic also multiplexes the con‐
2669 sole and the monitor to stdio.
2670 There is currently no support for multiplexing in the other di‐
2672 rection (where a single QEMU front end takes input and output
2673 from multiple chardevs).
2674 Every backend supports the logfile option, which supplies the
2676 path to a file to record all data transmitted via the backend.
2677 The logappend option controls whether the log file will be trun‐
2678 cated or appended to when opened.
2679 The available backends are:
2681 -chardev null,id=id
2683 A void device. This device will not emit any data, and will drop
2684 any data it receives. The null backend does not take any op‐
2685 tions.
2686 -chardev socket,id=id[,TCP options or unix op‐
2688 tions][,server=on|off][,wait=on|off][,telnet=on|off][,web‐
2689 socket=on|off][,reconnect=seconds][,tls-creds=id][,tls-authz=id]
2690 Create a two-way stream socket, which can be either a TCP or a
2691 unix socket. A unix socket will be created if path is specified.
2692 Behaviour is undefined if TCP options are specified for a unix
2693 socket.
2694 server=on|off specifies that the socket shall be a listening
2696 socket.
2697 wait=on|off specifies that QEMU should not block waiting for a
2699 client to connect to a listening socket.
2700 telnet=on|off specifies that traffic on the socket should inter‐
2702 pret telnet escape sequences.
2703 websocket=on|off specifies that the socket uses WebSocket proto‐
2705 col for communication.
2706 reconnect sets the timeout for reconnecting on non-server sock‐
2708 ets when the remote end goes away. qemu will delay this many
2709 seconds and then attempt to reconnect. Zero disables reconnect‐
2710 ing, and is the default.
2711 tls-creds requests enablement of the TLS protocol for encryp‐
2713 tion, and specifies the id of the TLS credentials to use for the
2714 handshake. The credentials must be previously created with the
2715 -object tls-creds argument.
2716 tls-auth provides the ID of the QAuthZ authorization object
2718 against which the client's x509 distinguished name will be vali‐
2719 dated. This object is only resolved at time of use, so can be
2720 deleted and recreated on the fly while the chardev server is ac‐
2721 tive. If missing, it will default to denying access.
2722 TCP and unix socket options are given below:
2724 TCP options:
2726 port=port[,host=host][,to=to][,ipv4=on|off][,ipv6=on|off][,node‐
2727 lay=on|off]
2728 host for a listening socket specifies the local address
2729 to be bound. For a connecting socket species the remote
2730 host to connect to. host is optional for listening sock‐
2731 ets. If not specified it defaults to 0.0.0.0.
2732 port for a listening socket specifies the local port to
2734 be bound. For a connecting socket specifies the port on
2735 the remote host to connect to. port can be given as ei‐
2736 ther a port number or a service name. port is required.
2737 to is only relevant to listening sockets. If it is speci‐
2739 fied, and port cannot be bound, QEMU will attempt to bind
2740 to subsequent ports up to and including to until it suc‐
2741 ceeds. to must be specified as a port number.
2742 ipv4=on|off and ipv6=on|off specify that either IPv4 or
2744 IPv6 must be used. If neither is specified the socket may
2745 use either protocol.
2746 nodelay=on|off disables the Nagle algorithm.
2748 unix options: path=path[,abstract=on|off][,tight=on|off]
2750 path specifies the local path of the unix socket. path is
2751 required. abstract=on|off specifies the use of the ab‐
2752 stract socket namespace, rather than the filesystem. Op‐
2753 tional, defaults to false. tight=on|off sets the socket
2754 length of abstract sockets to their minimum, rather than
2755 the full sun_path length. Optional, defaults to true.
2756 -chardev udp,id=id[,host=host],port=port[,localaddr=localaddr][,local‐
2758 port=localport][,ipv4=on|off][,ipv6=on|off]
2759 Sends all traffic from the guest to a remote host over UDP.
2760 host specifies the remote host to connect to. If not specified
2762 it defaults to localhost.
2763 port specifies the port on the remote host to connect to. port
2765 is required.
2766 localaddr specifies the local address to bind to. If not speci‐
2768 fied it defaults to 0.0.0.0.
2769 localport specifies the local port to bind to. If not specified
2771 any available local port will be used.
2772 ipv4=on|off and ipv6=on|off specify that either IPv4 or IPv6
2774 must be used. If neither is specified the device may use either
2775 protocol.
2776 -chardev msmouse,id=id
2778 Forward QEMU's emulated msmouse events to the guest. msmouse
2779 does not take any options.
2780 -chardev
2782 vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]
2783 Connect to a QEMU text console. vc may optionally be given a
2784 specific size.
2785 width and height specify the width and height respectively of
2787 the console, in pixels.
2788 cols and rows specify that the console be sized to fit a text
2790 console with the given dimensions.
2791 -chardev ringbuf,id=id[,size=size]
2793 Create a ring buffer with fixed size size. size must be a power
2794 of two and defaults to 64K.
2795 -chardev file,id=id,path=path
2797 Log all traffic received from the guest to a file.
2798 path specifies the path of the file to be opened. This file will
2800 be created if it does not already exist, and overwritten if it
2801 does. path is required.
2802 -chardev pipe,id=id,path=path
2804 Create a two-way connection to the guest. The behaviour differs
2805 slightly between Windows hosts and other hosts:
2806 On Windows, a single duplex pipe will be created at
2808 \\.pipe\path.
2809 On other hosts, 2 pipes will be created called path.in and
2811 path.out. Data written to path.in will be received by the guest.
2812 Data written by the guest can be read from path.out. QEMU will
2813 not create these fifos, and requires them to be present.
2814 path forms part of the pipe path as described above. path is re‐
2816 quired.
2817 -chardev console,id=id
2819 Send traffic from the guest to QEMU's standard output. console
2820 does not take any options.
2821 console is only available on Windows hosts.
2823 -chardev serial,id=id,path=path
2825 Send traffic from the guest to a serial device on the host.
2826 On Unix hosts serial will actually accept any tty device, not
2828 only serial lines.
2829 path specifies the name of the serial device to open.
2831 -chardev pty,id=id
2833 Create a new pseudo-terminal on the host and connect to it. pty
2834 does not take any options.
2835 pty is not available on Windows hosts.
2837 -chardev stdio,id=id[,signal=on|off]
2839 Connect to standard input and standard output of the QEMU
2840 process.
2841 signal controls if signals are enabled on the terminal, that in‐
2843 cludes exiting QEMU with the key sequence Control-c. This option
2844 is enabled by default, use signal=off to disable it.
2845 -chardev braille,id=id
2847 Connect to a local BrlAPI server. braille does not take any op‐
2848 tions.
2849 -chardev tty,id=id,path=path
2851 tty is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD
2852 and DragonFlyBSD hosts. It is an alias for serial.
2853 path specifies the path to the tty. path is required.
2855 -chardev parallel,id=id,path=path
2857 -chardev parport,id=id,path=path
2860 parallel is only available on Linux, FreeBSD and DragonFlyBSD
2861 hosts.
2862 Connect to a local parallel port.
2864 path specifies the path to the parallel port device. path is re‐
2866 quired.
2867 -chardev spicevmc,id=id,debug=debug,name=name
2869 spicevmc is only available when spice support is built in.
2870 debug debug level for spicevmc
2872 name name of spice channel to connect to
2874 Connect to a spice virtual machine channel, such as vdiport.
2876 -chardev spiceport,id=id,debug=debug,name=name
2878 spiceport is only available when spice support is built in.
2879 debug debug level for spicevmc
2881 name name of spice port to connect to
2883 Connect to a spice port, allowing a Spice client to handle the
2885 traffic identified by a name (preferably a fqdn).
2886 TPM device options
2888 The general form of a TPM device option is:
2889 -tpmdev backend,id=id[,options]
2891 The specific backend type will determine the applicable options.
2892 The -tpmdev option creates the TPM backend and requires a -de‐
2893 vice option that specifies the TPM frontend interface model.
2894 Use -tpmdev help to print all available TPM backend types.
2896 The available backends are:
2898 -tpmdev passthrough,id=id,path=path,cancel-path=cancel-path
2900 (Linux-host only) Enable access to the host's TPM using the
2901 passthrough driver.
2902 path specifies the path to the host's TPM device, i.e., on a
2904 Linux host this would be /dev/tpm0. path is optional and by de‐
2905 fault /dev/tpm0 is used.
2906 cancel-path specifies the path to the host TPM device's sysfs
2908 entry allowing for cancellation of an ongoing TPM command. can‐
2909 cel-path is optional and by default QEMU will search for the
2910 sysfs entry to use.
2911 Some notes about using the host's TPM with the passthrough
2913 driver:
2914 The TPM device accessed by the passthrough driver must not be
2916 used by any other application on the host.
2917 Since the host's firmware (BIOS/UEFI) has already initialized
2919 the TPM, the VM's firmware (BIOS/UEFI) will not be able to ini‐
2920 tialize the TPM again and may therefore not show a TPM-specific
2921 menu that would otherwise allow the user to configure the TPM,
2922 e.g., allow the user to enable/disable or activate/deactivate
2923 the TPM. Further, if TPM ownership is released from within a VM
2924 then the host's TPM will get disabled and deactivated. To enable
2925 and activate the TPM again afterwards, the host has to be re‐
2926 booted and the user is required to enter the firmware's menu to
2927 enable and activate the TPM. If the TPM is left disabled and/or
2928 deactivated most TPM commands will fail.
2929 To create a passthrough TPM use the following two options:
2931 -tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
2933 Note that the -tpmdev id is tpm0 and is referenced by tp‐
2935 mdev=tpm0 in the device option.
2936 -tpmdev emulator,id=id,chardev=dev
2938 (Linux-host only) Enable access to a TPM emulator using Unix do‐
2939 main socket based chardev backend.
2940 chardev specifies the unique ID of a character device backend
2942 that provides connection to the software TPM server.
2943 To create a TPM emulator backend device with chardev socket
2945 backend:
2946 -chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0
2948 Linux/Multiboot boot specific
2950 When using these options, you can use a given Linux or Multiboot kernel
2951 without installing it in the disk image. It can be useful for easier
2952 testing of various kernels.
2953 -kernel bzImage
2955 Use bzImage as kernel image. The kernel can be either a Linux
2956 kernel or in multiboot format.
2957 -append cmdline
2959 Use cmdline as kernel command line
2960 -initrd file
2962 Use file as initial ram disk.
2963 -initrd file1 arg=foo,file2
2965 This syntax is only available with multiboot.
2966 Use file1 and file2 as modules and pass arg=foo as parameter to
2968 the first module.
2969 -dtb file
2971 Use file as a device tree binary (dtb) image and pass it to the
2972 kernel on boot.
2973 Debug/Expert options
2975 -compat [deprecated-input=@var{input-policy}][,deprecated-out‐
2976 put=@var{output-policy}]
2977 Set policy for handling deprecated management interfaces (exper‐
2978 imental):
2979 deprecated-input=accept (default)
2981 Accept deprecated commands and arguments
2982 deprecated-input=reject
2984 Reject deprecated commands and arguments
2985 deprecated-input=crash
2987 Crash on deprecated commands and arguments
2988 deprecated-output=accept (default)
2990 Emit deprecated command results and events
2991 deprecated-output=hide
2993 Suppress deprecated command results and events
2994 Limitation: covers only syntactic aspects of QMP.
2996 -fw_cfg [name=]name,file=file
2998 Add named fw_cfg entry with contents from file file.
2999 -fw_cfg [name=]name,string=str
3001 Add named fw_cfg entry with contents from string str.
3002 The terminating NUL character of the contents of str will not be
3004 included as part of the fw_cfg item data. To insert contents
3005 with embedded NUL characters, you have to use the file parame‐
3006 ter.
3007 The fw_cfg entries are passed by QEMU through to the guest.
3009 Example:
3011 -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
3013 creates an fw_cfg entry named opt/com.mycompany/blob with con‐
3015 tents from ./my_blob.bin.
3016 -serial dev
3018 Redirect the virtual serial port to host character device dev.
3019 The default device is vc in graphical mode and stdio in non
3020 graphical mode.
3021 This option can be used several times to simulate up to 4 serial
3023 ports.
3024 Use -serial none to disable all serial ports.
3026 Available character devices are:
3028 vc[:WxH]
3030 Virtual console. Optionally, a width and height can be
3031 given in pixel with
3032 vc:800x600
3034 It is also possible to specify width or height in charac‐
3036 ters:
3037 vc:80Cx24C
3039 pty [Linux only] Pseudo TTY (a new PTY is automatically allo‐
3041 cated)
3042 none No device is allocated.
3044 null void device
3046 chardev:id
3048 Use a named character device defined with the -chardev
3049 option.
3050 /dev/XXX
3052 [Linux only] Use host tty, e.g. /dev/ttyS0. The host se‐
3053 rial port parameters are set according to the emulated
3054 ones.
3055 /dev/parportN
3057 [Linux only, parallel port only] Use host parallel port
3058 N. Currently SPP and EPP parallel port features can be
3059 used.
3060 file:filename
3062 Write output to filename. No character can be read.
3063 stdio [Unix only] standard input/output
3065 pipe:filename
3067 name pipe filename
3068 COMn [Windows only] Use host serial port n
3070 udp:[remote_host]:remote_port[@[src_ip]:src_port]
3072 This implements UDP Net Console. When remote_host or
3073 src_ip are not specified they default to 0.0.0.0. When
3074 not using a specified src_port a random port is automati‐
3075 cally chosen.
3076 If you just want a simple readonly console you can use
3078 netcat or nc, by starting QEMU with: -serial udp::4555
3079 and nc as: nc -u -l -p 4555. Any time QEMU writes some‐
3080 thing to that port it will appear in the netconsole ses‐
3081 sion.
3082 If you plan to send characters back via netconsole or you
3084 want to stop and start QEMU a lot of times, you should
3085 have QEMU use the same source port each time by using
3086 something like -serial udp::4555@:4556 to QEMU. Another
3087 approach is to use a patched version of netcat which can
3088 listen to a TCP port and send and receive characters via
3089 udp. If you have a patched version of netcat which acti‐
3090 vates telnet remote echo and single char transfer, then
3091 you can use the following options to set up a netcat
3092 redirector to allow telnet on port 5555 to access the
3093 QEMU port.
3094 QEMU Options:
3096 -serial udp::4555@:4556
3097 netcat options:
3099 -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
3100 telnet options:
3102 localhost 5555
3103 tcp:[host]:port[,server=on|off][,wait=on|off][,node‐
3105 lay=on|off][,reconnect=seconds]
3106 The TCP Net Console has two modes of operation. It can
3107 send the serial I/O to a location or wait for a connec‐
3108 tion from a location. By default the TCP Net Console is
3109 sent to host at the port. If you use the server=on option
3110 QEMU will wait for a client socket application to connect
3111 to the port before continuing, unless the wait=on|off op‐
3112 tion was specified. The nodelay=on|off option disables
3113 the Nagle buffering algorithm. The reconnect=on option
3114 only applies if server=no is set, if the connection goes
3115 down it will attempt to reconnect at the given interval.
3116 If host is omitted, 0.0.0.0 is assumed. Only one TCP con‐
3117 nection at a time is accepted. You can use telnet=on to
3118 connect to the corresponding character device.
3119 Example to send tcp console to 192.168.0.2 port 4444
3121 -serial tcp:192.168.0.2:4444
3122 Example to listen and wait on port 4444 for connection
3124 -serial tcp::4444,server=on
3125 Example to not wait and listen on ip 192.168.0.100 port
3127 4444
3128 -serial tcp:192.168.0.100:4444,server=on,wait=off
3129 telnet:host:port[,server=on|off][,wait=on|off][,nodelay=on|off]
3131 The telnet protocol is used instead of raw tcp sockets.
3132 The options work the same as if you had specified -serial
3133 tcp. The difference is that the port acts like a telnet
3134 server or client using telnet option negotiation. This
3135 will also allow you to send the MAGIC_SYSRQ sequence if
3136 you use a telnet that supports sending the break se‐
3137 quence. Typically in unix telnet you do it with Control-]
3138 and then type "send break" followed by pressing the enter
3139 key.
3140 websocket:host:port,server=on[,wait=on|off][,nodelay=on|off]
3142 The WebSocket protocol is used instead of raw tcp socket.
3143 The port acts as a WebSocket server. Client mode is not
3144 supported.
3145 unix:path[,server=on|off][,wait=on|off][,reconnect=seconds]
3147 A unix domain socket is used instead of a tcp socket. The
3148 option works the same as if you had specified -serial tcp
3149 except the unix domain socket path is used for connec‐
3150 tions.
3151 mon:dev_string
3153 This is a special option to allow the monitor to be mul‐
3154 tiplexed onto another serial port. The monitor is ac‐
3155 cessed with key sequence of Control-a and then pressing
3156 c. dev_string should be any one of the serial devices
3157 specified above. An example to multiplex the monitor onto
3158 a telnet server listening on port 4444 would be:
3159 -serial mon:telnet::4444,server=on,wait=off
3161 When the monitor is multiplexed to stdio in this way,
3163 Ctrl+C will not terminate QEMU any more but will be
3164 passed to the guest instead.
3165 braille
3167 Braille device. This will use BrlAPI to display the
3168 braille output on a real or fake device.
3169 msmouse
3171 Three button serial mouse. Configure the guest to use Mi‐
3172 crosoft protocol.
3173 -parallel dev
3175 Redirect the virtual parallel port to host device dev (same de‐
3176 vices as the serial port). On Linux hosts, /dev/parportN can be
3177 used to use hardware devices connected on the corresponding host
3178 parallel port.
3179 This option can be used several times to simulate up to 3 paral‐
3181 lel ports.
3182 Use -parallel none to disable all parallel ports.
3184 -monitor dev
3186 Redirect the monitor to host device dev (same devices as the se‐
3187 rial port). The default device is vc in graphical mode and stdio
3188 in non graphical mode. Use -monitor none to disable the default
3189 monitor.
3190 -qmp dev
3192 Like -monitor but opens in 'control' mode.
3193 -qmp-pretty dev
3195 Like -qmp but uses pretty JSON formatting.
3196 -mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]
3198 Setup monitor on chardev name. mode=control configures a QMP
3199 monitor (a JSON RPC-style protocol) and it is not the same as
3200 HMP, the human monitor that has a "(qemu)" prompt. pretty is
3201 only valid when mode=control, turning on JSON pretty printing to
3202 ease human reading and debugging.
3203 -debugcon dev
3205 Redirect the debug console to host device dev (same devices as
3206 the serial port). The debug console is an I/O port which is typ‐
3207 ically port 0xe9; writing to that I/O port sends output to this
3208 device. The default device is vc in graphical mode and stdio in
3209 non graphical mode.
3210 -pidfile file
3212 Store the QEMU process PID in file. It is useful if you launch
3213 QEMU from a script.
3214 -singlestep
3216 Run the emulation in single step mode.
3217 --preconfig
3219 Pause QEMU for interactive configuration before the machine is
3220 created, which allows querying and configuring properties that
3221 will affect machine initialization. Use QMP command 'x-exit-pre‐
3222 config' to exit the preconfig state and move to the next state
3223 (i.e. run guest if -S isn't used or pause the second time if -S
3224 is used). This option is experimental.
3225 -S Do not start CPU at startup (you must type 'c' in the monitor).
3227 -overcommit mem-lock=on|off
3229 -overcommit cpu-pm=on|off
3232 Run qemu with hints about host resource overcommit. The default
3233 is to assume that host overcommits all resources.
3234 Locking qemu and guest memory can be enabled via mem-lock=on
3236 (disabled by default). This works when host memory is not over‐
3237 committed and reduces the worst-case latency for guest.
3238 Guest ability to manage power state of host cpus (increasing la‐
3240 tency for other processes on the same host cpu, but decreasing
3241 latency for guest) can be enabled via cpu-pm=on (disabled by de‐
3242 fault). This works best when host CPU is not overcommitted. When
3243 used, host estimates of CPU cycle and power utilization will be
3244 incorrect, not taking into account guest idle time.
3245 -gdb dev
3247 Accept a gdb connection on device dev (see the GDB usage chapter
3248 in the System Emulation Users Guide). Note that this option does
3249 not pause QEMU execution -- if you want QEMU to not start the
3250 guest until you connect with gdb and issue a continue command,
3251 you will need to also pass the -S option to QEMU.
3252 The most usual configuration is to listen on a local TCP socket:
3254 -gdb tcp::3117
3256 but you can specify other backends; UDP, pseudo TTY, or even
3258 stdio are all reasonable use cases. For example, a stdio connec‐
3259 tion allows you to start QEMU from within gdb and establish the
3260 connection via a pipe:
3261 (gdb) target remote | exec qemu-system-x86_64 -gdb stdio ...
3263 -s Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port
3265 1234 (see the GDB usage chapter in the System Emulation Users
3266 Guide).
3267 -d item1[,...]
3269 Enable logging of specified items. Use '-d help' for a list of
3270 log items.
3271 -D logfile
3273 Output log in logfile instead of to stderr
3274 -dfilter range1[,...]
3276 Filter debug output to that relevant to a range of target ad‐
3277 dresses. The filter spec can be either start+size, start-size
3278 or start..end where start end and size are the addresses and
3279 sizes required. For example:
3280 -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000
3282 Will dump output for any code in the 0x1000 sized block starting
3284 at 0x8000 and the 0x200 sized block starting at
3285 0xffffffc000080000 and another 0x1000 sized block starting at
3286 0xffffffc00005f000.
3287 -seed number
3289 Force the guest to use a deterministic pseudo-random number gen‐
3290 erator, seeded with number. This does not affect crypto routines
3291 within the host.
3292 -L path
3294 Set the directory for the BIOS, VGA BIOS and keymaps.
3295 To list all the data directories, use -L help.
3297 -bios file
3299 Set the filename for the BIOS.
3300 -enable-kvm
3302 Enable KVM full virtualization support. This option is only
3303 available if KVM support is enabled when compiling.
3304 -xen-domid id
3306 Specify xen guest domain id (XEN only).
3307 -xen-attach
3309 Attach to existing xen domain. libxl will use this when starting
3310 QEMU (XEN only). Restrict set of available xen operations to
3311 specified domain id (XEN only).
3312 -no-reboot
3314 Exit instead of rebooting.
3315 -no-shutdown
3317 Don't exit QEMU on guest shutdown, but instead only stop the em‐
3318 ulation. This allows for instance switching to monitor to commit
3319 changes to the disk image.
3320 -action event=action
3322 The action parameter serves to modify QEMU's default behavior
3323 when certain guest events occur. It provides a generic method
3324 for specifying the same behaviors that are modified by the
3325 -no-reboot and -no-shutdown parameters.
3326 Examples:
3328 -action panic=none -action reboot=shutdown,shutdown=pause
3330 -watchdog i6300esb -action watchdog=pause
3331 -loadvm file
3333 Start right away with a saved state (loadvm in monitor)
3334 -daemonize
3336 Daemonize the QEMU process after initialization. QEMU will not
3337 detach from standard IO until it is ready to receive connections
3338 on any of its devices. This option is a useful way for external
3339 programs to launch QEMU without having to cope with initializa‐
3340 tion race conditions.
3341 -option-rom file
3343 Load the contents of file as an option ROM. This option is use‐
3344 ful to load things like EtherBoot.
3345 -rtc [base=utc|localtime|datetime][,clock=host|rt|vm][,drift‐
3347 fix=none|slew]
3348 Specify base as utc or localtime to let the RTC start at the
3349 current UTC or local time, respectively. localtime is required
3350 for correct date in MS-DOS or Windows. To start at a specific
3351 point in time, provide datetime in the format
3352 2006-06-17T16:01:21 or 2006-06-17. The default base is UTC.
3353 By default the RTC is driven by the host system time. This al‐
3355 lows using of the RTC as accurate reference clock inside the
3356 guest, specifically if the host time is smoothly following an
3357 accurate external reference clock, e.g. via NTP. If you want to
3358 isolate the guest time from the host, you can set clock to rt
3359 instead, which provides a host monotonic clock if host support
3360 it. To even prevent the RTC from progressing during suspension,
3361 you can set clock to vm (virtual clock). 'clock=vm' is recom‐
3362 mended especially in icount mode in order to preserve determin‐
3363 ism; however, note that in icount mode the speed of the virtual
3364 clock is variable and can in general differ from the host clock.
3365 Enable driftfix (i386 targets only) if you experience time drift
3367 problems, specifically with Windows' ACPI HAL. This option will
3368 try to figure out how many timer interrupts were not processed
3369 by the Windows guest and will re-inject them.
3370 -icount [shift=N|auto][,align=on|off][,sleep=on|off][,rr=record|re‐
3372 play,rrfile=filename[,rrsnapshot=snapshot]]
3373 Enable virtual instruction counter. The virtual cpu will execute
3374 one instruction every 2^N ns of virtual time. If auto is speci‐
3375 fied then the virtual cpu speed will be automatically adjusted
3376 to keep virtual time within a few seconds of real time.
3377 Note that while this option can give deterministic behavior, it
3379 does not provide cycle accurate emulation. Modern CPUs contain
3380 superscalar out of order cores with complex cache hierarchies.
3381 The number of instructions executed often has little or no cor‐
3382 relation with actual performance.
3383 When the virtual cpu is sleeping, the virtual time will advance
3385 at default speed unless sleep=on is specified. With sleep=on,
3386 the virtual time will jump to the next timer deadline instantly
3387 whenever the virtual cpu goes to sleep mode and will not advance
3388 if no timer is enabled. This behavior gives deterministic execu‐
3389 tion times from the guest point of view. The default if icount
3390 is enabled is sleep=off. sleep=on cannot be used together with
3391 either shift=auto or align=on.
3392 align=on will activate the delay algorithm which will try to
3394 synchronise the host clock and the virtual clock. The goal is to
3395 have a guest running at the real frequency imposed by the shift
3396 option. Whenever the guest clock is behind the host clock and if
3397 align=on is specified then we print a message to the user to in‐
3398 form about the delay. Currently this option does not work when
3399 shift is auto. Note: The sync algorithm will work for those
3400 shift values for which the guest clock runs ahead of the host
3401 clock. Typically this happens when the shift value is high (how
3402 high depends on the host machine). The default if icount is en‐
3403 abled is align=off.
3404 When the rr option is specified deterministic record/replay is
3406 enabled. The rrfile= option must also be provided to specify the
3407 path to the replay log. In record mode data is written to this
3408 file, and in replay mode it is read back. If the rrsnapshot op‐
3409 tion is given then it specifies a VM snapshot name. In record
3410 mode, a new VM snapshot with the given name is created at the
3411 start of execution recording. In replay mode this option speci‐
3412 fies the snapshot name used to load the initial VM state.
3413 -watchdog model
3415 Create a virtual hardware watchdog device. Once enabled (by a
3416 guest action), the watchdog must be periodically polled by an
3417 agent inside the guest or else the guest will be restarted.
3418 Choose a model for which your guest has drivers.
3419 The model is the model of hardware watchdog to emulate. Use
3421 -watchdog help to list available hardware models. Only one
3422 watchdog can be enabled for a guest.
3423 The following models may be available:
3425 ib700 iBASE 700 is a very simple ISA watchdog with a single
3427 timer.
3428 i6300esb
3430 Intel 6300ESB I/O controller hub is a much more feature‐
3431 ful PCI-based dual-timer watchdog.
3432 diag288
3434 A virtual watchdog for s390x backed by the diagnose 288
3435 hypercall (currently KVM only).
3436 -watchdog-action action
3438 The action controls what QEMU will do when the watchdog timer
3439 expires. The default is reset (forcefully reset the guest).
3440 Other possible actions are: shutdown (attempt to gracefully
3441 shutdown the guest), poweroff (forcefully poweroff the guest),
3442 inject-nmi (inject a NMI into the guest), pause (pause the
3443 guest), debug (print a debug message and continue), or none (do
3444 nothing).
3445 Note that the shutdown action requires that the guest responds
3447 to ACPI signals, which it may not be able to do in the sort of
3448 situations where the watchdog would have expired, and thus
3449 -watchdog-action shutdown is not recommended for production use.
3450 Examples:
3452 -watchdog i6300esb -watchdog-action pause; -watchdog ib700
3454 -echr numeric_ascii_value
3456 Change the escape character used for switching to the monitor
3457 when using monitor and serial sharing. The default is 0x01 when
3458 using the -nographic option. 0x01 is equal to pressing Con‐
3459 trol-a. You can select a different character from the ascii con‐
3460 trol keys where 1 through 26 map to Control-a through Control-z.
3461 For instance you could use the either of the following to change
3462 the escape character to Control-t.
3463 -echr 0x14; -echr 20
3465 -incoming tcp:[host]:port[,to=maxport][,ipv4=on|off][,ipv6=on|off]
3467 -incoming rdma:host:port[,ipv4=on|off][,ipv6=on|off]
3470 Prepare for incoming migration, listen on a given tcp port.
3471 -incoming unix:socketpath
3473 Prepare for incoming migration, listen on a given unix socket.
3474 -incoming fd:fd
3476 Accept incoming migration from a given filedescriptor.
3477 -incoming exec:cmdline
3479 Accept incoming migration as an output from specified external
3480 command.
3481 -incoming defer
3483 Wait for the URI to be specified via migrate_incoming. The moni‐
3484 tor can be used to change settings (such as migration parame‐
3485 ters) prior to issuing the migrate_incoming to allow the migra‐
3486 tion to begin.
3487 -only-migratable
3489 Only allow migratable devices. Devices will not be allowed to
3490 enter an unmigratable state.
3491 -nodefaults
3493 Don't create default devices. Normally, QEMU sets the default
3494 devices like serial port, parallel port, virtual console, moni‐
3495 tor device, VGA adapter, floppy and CD-ROM drive and others. The
3496 -nodefaults option will disable all those default devices.
3497 -chroot dir
3499 Immediately before starting guest execution, chroot to the spec‐
3500 ified directory. Especially useful in combination with -runas.
3501 -runas user
3503 Immediately before starting guest execution, drop root privi‐
3504 leges, switching to the specified user.
3505 -prom-env variable=value
3507 Set OpenBIOS nvram variable to given value (PPC, SPARC only).
3508 qemu-system-sparc -prom-env 'auto-boot?=false' \
3510 -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
3511 qemu-system-ppc -prom-env 'auto-boot?=false' \
3513 -prom-env 'boot-device=hd:2,\yaboot' \
3514 -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
3515 -semihosting
3517 Enable semihosting mode (ARM, M68K, Xtensa, MIPS, Nios II,
3518 RISC-V only).
3519 Note that this allows guest direct access to the host filesys‐
3521 tem, so should only be used with a trusted guest OS.
3522 See the -semihosting-config option documentation for further in‐
3524 formation about the facilities this enables.
3525 -semihosting-config [enable=on|off][,target=na‐
3527 tive|gdb|auto][,chardev=id][,arg=str[,...]]
3528 Enable and configure semihosting (ARM, M68K, Xtensa, MIPS, Nios
3529 II, RISC-V only).
3530 Note that this allows guest direct access to the host filesys‐
3532 tem, so should only be used with a trusted guest OS.
3533 On Arm this implements the standard semihosting API, version
3535 2.0.
3536 On M68K this implements the "ColdFire GDB" interface used by
3538 libgloss.
3539 Xtensa semihosting provides basic file IO calls, such as
3541 open/read/write/seek/select. Tensilica baremetal libc for ISS
3542 and linux platform "sim" use this interface.
3543 On RISC-V this implements the standard semihosting API, version
3545 0.2.
3546 target=native|gdb|auto
3548 Defines where the semihosting calls will be addressed, to
3549 QEMU (native) or to GDB (gdb). The default is auto, which
3550 means gdb during debug sessions and native otherwise.
3551 chardev=str1
3553 Send the output to a chardev backend output for native or
3554 auto output when not in gdb
3555 arg=str1,arg=str2,...
3557 Allows the user to pass input arguments, and can be used
3558 multiple times to build up a list. The old-style -ker‐
3559 nel/-append method of passing a command line is still
3560 supported for backward compatibility. If both the --semi‐
3561 hosting-config arg and the -kernel/-append are specified,
3562 the former is passed to semihosting as it always takes
3563 precedence.
3564 -old-param
3566 Old param mode (ARM only).
3567 -sandbox arg[,obsolete=string][,elevateprivi‐
3569 leges=string][,spawn=string][,resourcecontrol=string]
3570 Enable Seccomp mode 2 system call filter. 'on' will enable
3571 syscall filtering and 'off' will disable it. The default is
3572 'off'.
3573 obsolete=string
3575 Enable Obsolete system calls
3576 elevateprivileges=string
3578 Disable set*uid|gid system calls
3579 spawn=string
3581 Disable *fork and execve
3582 resourcecontrol=string
3584 Disable process affinity and schedular priority
3585 -readconfig file
3587 Read device configuration from file. This approach is useful
3588 when you want to spawn QEMU process with many command line op‐
3589 tions but you don't want to exceed the command line character
3590 limit.
3591 -no-user-config
3593 The -no-user-config option makes QEMU not load any of the
3594 user-provided config files on sysconfdir.
3595 -trace [[enable=]pattern][,events=file][,file=file]
3597 Specify tracing options.
3598 [enable=]PATTERN
3600 Immediately enable events matching PATTERN (either event name
3601 or a globbing pattern). This option is only available if
3602 QEMU has been compiled with the simple, log or ftrace tracing
3603 backend. To specify multiple events or patterns, specify the
3604 -trace option multiple times.
3605 Use -trace help to print a list of names of trace points.
3607 events=FILE
3609 Immediately enable events listed in FILE. The file must con‐
3610 tain one event name (as listed in the trace-events-all file)
3611 per line; globbing patterns are accepted too. This option is
3612 only available if QEMU has been compiled with the simple, log
3613 or ftrace tracing backend.
3614 file=FILE
3616 Log output traces to FILE. This option is only available if
3617 QEMU has been compiled with the simple tracing backend.
3618 -plugin file=file[,arg=string]
3620 Load a plugin.
3621 file=file
3623 Load the given plugin from a shared library file.
3624 arg=string
3626 Argument string passed to the plugin. (Can be given mul‐
3627 tiple times.)
3628 -enable-fips
3630 Enable FIPS 140-2 compliance mode.
3631 -msg [timestamp[=on|off]][,guest-name[=on|off]]
3633 Control error message format.
3634 timestamp=on|off
3636 Prefix messages with a timestamp. Default is off.
3637 guest-name=on|off
3639 Prefix messages with guest name but only if -name guest
3640 option is set otherwise the option is ignored. Default is
3641 off.
3642 -dump-vmstate file
3644 Dump json-encoded vmstate information for current machine type
3645 to file in file
3646 -enable-sync-profile
3648 Enable synchronization profiling.
3649 Generic object creation
3651 -object typename[,prop1=value1,...]
3652 Create a new object of type typename setting properties in the
3653 order they are specified. Note that the 'id' property must be
3654 set. These objects are placed in the '/objects' path.
3655 -object memory-back‐
3657 end-file,id=id,size=size,mem-path=dir,share=on|off,dis‐
3658 card-data=on|off,merge=on|off,dump=on|off,preal‐
3659 loc=on|off,host-nodes=host-nodes,policy=default|pre‐
3660 ferred|bind|interleave,align=align,readonly=on|off
3661 Creates a memory file backend object, which can be used
3662 to back the guest RAM with huge pages.
3663 The id parameter is a unique ID that will be used to ref‐
3665 erence this memory region in other parameters, e.g.
3666 -numa, -device nvdimm, etc.
3667 The size option provides the size of the memory region,
3669 and accepts common suffixes, e.g. 500M.
3670 The mem-path provides the path to either a shared memory
3672 or huge page filesystem mount.
3673 The share boolean option determines whether the memory
3675 region is marked as private to QEMU, or shared. The lat‐
3676 ter allows a co-operating external process to access the
3677 QEMU memory region.
3678 The share is also required for pvrdma devices due to lim‐
3680 itations in the RDMA API provided by Linux.
3681 Setting share=on might affect the ability to configure
3683 NUMA bindings for the memory backend under some circum‐
3684 stances, see Documentation/vm/numa_memory_policy.txt on
3685 the Linux kernel source tree for additional details.
3686 Setting the discard-data boolean option to on indicates
3688 that file contents can be destroyed when QEMU exits, to
3689 avoid unnecessarily flushing data to the backing file.
3690 Note that discard-data is only an optimization, and QEMU
3691 might not discard file contents if it aborts unexpectedly
3692 or is terminated using SIGKILL.
3693 The merge boolean option enables memory merge, also known
3695 as MADV_MERGEABLE, so that Kernel Samepage Merging will
3696 consider the pages for memory deduplication.
3697 Setting the dump boolean option to off excludes the mem‐
3699 ory from core dumps. This feature is also known as
3700 MADV_DONTDUMP.
3701 The prealloc boolean option enables memory preallocation.
3703 The host-nodes option binds the memory range to a list of
3705 NUMA host nodes.
3706 The policy option sets the NUMA policy to one of the fol‐
3708 lowing values:
3709 default
3711 default host policy
3712 preferred
3714 prefer the given host node list for allocation
3715 bind restrict memory allocation to the given host node
3717 list
3718 interleave
3720 interleave memory allocations across the given
3721 host node list
3722 The align option specifies the base address alignment
3724 when QEMU mmap(2) mem-path, and accepts common suffixes,
3725 eg 2M. Some backend store specified by mem-path requires
3726 an alignment different than the default one used by QEMU,
3727 eg the device DAX /dev/dax0.0 requires 2M alignment
3728 rather than 4K. In such cases, users can specify the re‐
3729 quired alignment via this option.
3730 The pmem option specifies whether the backing file speci‐
3732 fied by mem-path is in host persistent memory that can be
3733 accessed using the SNIA NVM programming model (e.g. Intel
3734 NVDIMM). If pmem is set to 'on', QEMU will take necessary
3735 operations to guarantee the persistence of its own writes
3736 to mem-path (e.g. in vNVDIMM label emulation and live mi‐
3737 gration). Also, we will map the backend-file with
3738 MAP_SYNC flag, which ensures the file metadata is in sync
3739 for mem-path in case of host crash or a power failure.
3740 MAP_SYNC requires support from both the host kernel
3741 (since Linux kernel 4.15) and the filesystem of mem-path
3742 mounted with DAX option.
3743 The readonly option specifies whether the backing file is
3745 opened read-only or read-write (default).
3746 -object memory-back‐
3748 end-ram,id=id,merge=on|off,dump=on|off,share=on|off,preal‐
3749 loc=on|off,size=size,host-nodes=host-nodes,policy=default|pre‐
3750 ferred|bind|interleave
3751 Creates a memory backend object, which can be used to
3752 back the guest RAM. Memory backend objects offer more
3753 control than the -m option that is traditionally used to
3754 define guest RAM. Please refer to memory-backend-file
3755 for a description of the options.
3756 -object memory-back‐
3758 end-memfd,id=id,merge=on|off,dump=on|off,share=on|off,preal‐
3759 loc=on|off,size=size,host-nodes=host-nodes,policy=default|pre‐
3760 ferred|bind|interleave,seal=on|off,hugetlb=on|off,hugetlb‐
3761 size=size
3762 Creates an anonymous memory file backend object, which
3763 allows QEMU to share the memory with an external process
3764 (e.g. when using vhost-user). The memory is allocated
3765 with memfd and optional sealing. (Linux only)
3766 The seal option creates a sealed-file, that will block
3768 further resizing the memory ('on' by default).
3769 The hugetlb option specify the file to be created resides
3771 in the hugetlbfs filesystem (since Linux 4.14). Used in
3772 conjunction with the hugetlb option, the hugetlbsize op‐
3773 tion specify the hugetlb page size on systems that sup‐
3774 port multiple hugetlb page sizes (it must be a power of 2
3775 value supported by the system).
3776 In some versions of Linux, the hugetlb option is incom‐
3778 patible with the seal option (requires at least Linux
3779 4.16).
3780 Please refer to memory-backend-file for a description of
3782 the other options.
3783 The share boolean option is on by default with memfd.
3785 -object rng-builtin,id=id
3787 Creates a random number generator backend which obtains
3788 entropy from QEMU builtin functions. The id parameter is
3789 a unique ID that will be used to reference this entropy
3790 backend from the virtio-rng device. By default, the vir‐
3791 tio-rng device uses this RNG backend.
3792 -object rng-random,id=id,filename=/dev/random
3794 Creates a random number generator backend which obtains
3795 entropy from a device on the host. The id parameter is a
3796 unique ID that will be used to reference this entropy
3797 backend from the virtio-rng device. The filename parame‐
3798 ter specifies which file to obtain entropy from and if
3799 omitted defaults to /dev/urandom.
3800 -object rng-egd,id=id,chardev=chardevid
3802 Creates a random number generator backend which obtains
3803 entropy from an external daemon running on the host. The
3804 id parameter is a unique ID that will be used to refer‐
3805 ence this entropy backend from the virtio-rng device. The
3806 chardev parameter is the unique ID of a character device
3807 backend that provides the connection to the RNG daemon.
3808 -object tls-creds-anon,id=id,endpoint=end‐
3810 point,dir=/path/to/cred/dir,verify-peer=on|off
3811 Creates a TLS anonymous credentials object, which can be
3812 used to provide TLS support on network backends. The id
3813 parameter is a unique ID which network backends will use
3814 to access the credentials. The endpoint is either server
3815 or client depending on whether the QEMU network backend
3816 that uses the credentials will be acting as a client or
3817 as a server. If verify-peer is enabled (the default) then
3818 once the handshake is completed, the peer credentials
3819 will be verified, though this is a no-op for anonymous
3820 credentials.
3821 The dir parameter tells QEMU where to find the credential
3823 files. For server endpoints, this directory may contain
3824 a file dh-params.pem providing diffie-hellman parameters
3825 to use for the TLS server. If the file is missing, QEMU
3826 will generate a set of DH parameters at startup. This is
3827 a computationally expensive operation that consumes ran‐
3828 dom pool entropy, so it is recommended that a persistent
3829 set of parameters be generated upfront and saved.
3830 -object tls-creds-psk,id=id,endpoint=end‐
3832 point,dir=/path/to/keys/dir[,username=username]
3833 Creates a TLS Pre-Shared Keys (PSK) credentials object,
3834 which can be used to provide TLS support on network back‐
3835 ends. The id parameter is a unique ID which network back‐
3836 ends will use to access the credentials. The endpoint is
3837 either server or client depending on whether the QEMU
3838 network backend that uses the credentials will be acting
3839 as a client or as a server. For clients only, username
3840 is the username which will be sent to the server. If
3841 omitted it defaults to "qemu".
3842 The dir parameter tells QEMU where to find the keys file.
3844 It is called "dir/keys.psk" and contains "username:key"
3845 pairs. This file can most easily be created using the
3846 GnuTLS psktool program.
3847 For server endpoints, dir may also contain a file
3849 dh-params.pem providing diffie-hellman parameters to use
3850 for the TLS server. If the file is missing, QEMU will
3851 generate a set of DH parameters at startup. This is a
3852 computationally expensive operation that consumes random
3853 pool entropy, so it is recommended that a persistent set
3854 of parameters be generated up front and saved.
3855 -object tls-creds-x509,id=id,endpoint=end‐
3857 point,dir=/path/to/cred/dir,priority=priority,ver‐
3858 ify-peer=on|off,passwordid=id
3859 Creates a TLS anonymous credentials object, which can be
3860 used to provide TLS support on network backends. The id
3861 parameter is a unique ID which network backends will use
3862 to access the credentials. The endpoint is either server
3863 or client depending on whether the QEMU network backend
3864 that uses the credentials will be acting as a client or
3865 as a server. If verify-peer is enabled (the default) then
3866 once the handshake is completed, the peer credentials
3867 will be verified. With x509 certificates, this implies
3868 that the clients must be provided with valid client cer‐
3869 tificates too.
3870 The dir parameter tells QEMU where to find the credential
3872 files. For server endpoints, this directory may contain
3873 a file dh-params.pem providing diffie-hellman parameters
3874 to use for the TLS server. If the file is missing, QEMU
3875 will generate a set of DH parameters at startup. This is
3876 a computationally expensive operation that consumes ran‐
3877 dom pool entropy, so it is recommended that a persistent
3878 set of parameters be generated upfront and saved.
3879 For x509 certificate credentials the directory will con‐
3881 tain further files providing the x509 certificates. The
3882 certificates must be stored in PEM format, in filenames
3883 ca-cert.pem, ca-crl.pem (optional), server-cert.pem (only
3884 servers), server-key.pem (only servers), client-cert.pem
3885 (only clients), and client-key.pem (only clients).
3886 For the server-key.pem and client-key.pem files which
3888 contain sensitive private keys, it is possible to use an
3889 encrypted version by providing the passwordid parameter.
3890 This provides the ID of a previously created secret ob‐
3891 ject containing the password for decryption.
3892 The priority parameter allows to override the global de‐
3894 fault priority used by gnutls. This can be useful if the
3895 system administrator needs to use a weaker set of crypto
3896 priorities for QEMU without potentially forcing the weak‐
3897 ness onto all applications. Or conversely if one wants
3898 wants a stronger default for QEMU than for all other ap‐
3899 plications, they can do this through this parameter. Its
3900 format is a gnutls priority string as described at
3901 https://gnutls.org/manual/html_node/Priority-Strings.html.
3902 -object tls-cipher-suites,id=id,priority=priority
3904 Creates a TLS cipher suites object, which can be used to
3905 control the TLS cipher/protocol algorithms that applica‐
3906 tions are permitted to use.
3907 The id parameter is a unique ID which frontends will use
3909 to access the ordered list of permitted TLS cipher suites
3910 from the host.
3911 The priority parameter allows to override the global de‐
3913 fault priority used by gnutls. This can be useful if the
3914 system administrator needs to use a weaker set of crypto
3915 priorities for QEMU without potentially forcing the weak‐
3916 ness onto all applications. Or conversely if one wants
3917 wants a stronger default for QEMU than for all other ap‐
3918 plications, they can do this through this parameter. Its
3919 format is a gnutls priority string as described at
3920 https://gnutls.org/manual/html_node/Priority-Strings.html.
3921 An example of use of this object is to control UEFI HTTPS
3923 Boot. The tls-cipher-suites object exposes the ordered
3924 list of permitted TLS cipher suites from the host side to
3925 the guest firmware, via fw_cfg. The list is represented
3926 as an array of IANA_TLS_CIPHER objects. The firmware uses
3927 the IANA_TLS_CIPHER array for configuring guest-side TLS.
3928 In the following example, the priority at which the
3930 host-side policy is retrieved is given by the priority
3931 property. Given that QEMU uses GNUTLS, priority=@SYSTEM
3932 may be used to refer to /etc/crypto-poli‐
3933 cies/back-ends/gnutls.config.
3934 # qemu-system-x86_64 \
3936 -object tls-cipher-suites,id=mysuite0,priority=@SYSTEM \
3937 -fw_cfg name=etc/edk2/https/ciphers,gen_id=mysuite0
3938 -object filter-buffer,id=id,netdev=netdevid,inter‐
3940 val=t[,queue=all|rx|tx][,status=on|off][,posi‐
3941 tion=head|tail|id=<id>][,insert=behind|before]
3942 Interval t can't be 0, this filter batches the packet de‐
3943 livery: all packets arriving in a given interval on net‐
3944 dev netdevid are delayed until the end of the interval.
3945 Interval is in microseconds. status is optional that in‐
3946 dicate whether the netfilter is on (enabled) or off (dis‐
3947 abled), the default status for netfilter will be 'on'.
3948 queue all|rx|tx is an option that can be applied to any
3950 netfilter.
3951 all: the filter is attached both to the receive and the
3953 transmit queue of the netdev (default).
3954 rx: the filter is attached to the receive queue of the
3956 netdev, where it will receive packets sent to the netdev.
3957 tx: the filter is attached to the transmit queue of the
3959 netdev, where it will receive packets sent by the netdev.
3960 position head|tail|id=<id> is an option to specify where
3962 the filter should be inserted in the filter list. It can
3963 be applied to any netfilter.
3964 head: the filter is inserted at the head of the filter
3966 list, before any existing filters.
3967 tail: the filter is inserted at the tail of the filter
3969 list, behind any existing filters (default).
3970 id=<id>: the filter is inserted before or behind the fil‐
3972 ter specified by <id>, see the insert option below.
3973 insert behind|before is an option to specify where to in‐
3975 sert the new filter relative to the one specified with
3976 position=id=<id>. It can be applied to any netfilter.
3977 before: insert before the specified filter.
3979 behind: insert behind the specified filter (default).
3981 -object filter-mirror,id=id,netdev=netdevid,outdev=charde‐
3983 vid,queue=all|rx|tx[,vnet_hdr_support][,posi‐
3984 tion=head|tail|id=<id>][,insert=behind|before]
3985 filter-mirror on netdev netdevid,mirror net packet to
3986 chardevchardevid, if it has the vnet_hdr_support flag,
3987 filter-mirror will mirror packet with vnet_hdr_len.
3988 -object filter-redirector,id=id,netdev=netdevid,indev=charde‐
3990 vid,outdev=chardevid,queue=all|rx|tx[,vnet_hdr_support][,posi‐
3991 tion=head|tail|id=<id>][,insert=behind|before]
3992 filter-redirector on netdev netdevid,redirect filter's
3993 net packet to chardev chardevid,and redirect indev's
3994 packet to filter.if it has the vnet_hdr_support flag,
3995 filter-redirector will redirect packet with vnet_hdr_len.
3996 Create a filter-redirector we need to differ outdev id
3997 from indev id, id can not be the same. we can just use
3998 indev or outdev, but at least one of indev or outdev need
3999 to be specified.
4000 -object filter-rewriter,id=id,netdev=netde‐
4002 vid,queue=all|rx|tx,[vnet_hdr_support][,posi‐
4003 tion=head|tail|id=<id>][,insert=behind|before]
4004 Filter-rewriter is a part of COLO project.It will rewrite
4005 tcp packet to secondary from primary to keep secondary
4006 tcp connection,and rewrite tcp packet to primary from
4007 secondary make tcp packet can be handled by client.if it
4008 has the vnet_hdr_support flag, we can parse packet with
4009 vnet header.
4010 usage: colo secondary: -object filter-redirec‐
4012 tor,id=f1,netdev=hn0,queue=tx,indev=red0 -object fil‐
4013 ter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 -ob‐
4014 ject filter-rewriter,id=rew0,netdev=hn0,queue=all
4015 -object filter-dump,id=id,netdev=dev[,file=file‐
4017 name][,maxlen=len][,position=head|tail|id=<id>][,insert=be‐
4018 hind|before]
4019 Dump the network traffic on netdev dev to the file speci‐
4020 fied by filename. At most len bytes (64k by default) per
4021 packet are stored. The file format is libpcap, so it can
4022 be analyzed with tools such as tcpdump or Wireshark.
4023 -object colo-compare,id=id,primary_in=chardevid,sec‐
4025 ondary_in=chardevid,outdev=chardevid,iothread=id[,vnet_hdr_sup‐
4026 port][,notify_dev=id][,compare_timeout=@var{ms}][,ex‐
4027 pired_scan_cycle=@var{ms}][,max_queue_size=@var{size}]
4028 Colo-compare gets packet from primary_in chardevid and
4029 secondary_in, then compare whether the payload of primary
4030 packet and secondary packet are the same. If same, it
4031 will output primary packet to out_dev, else it will no‐
4032 tify COLO-framework to do checkpoint and send primary
4033 packet to out_dev. In order to improve efficiency, we
4034 need to put the task of comparison in another iothread.
4035 If it has the vnet_hdr_support flag, colo compare will
4036 send/recv packet with vnet_hdr_len. The
4037 compare_timeout=@var{ms} determines the maximum time of
4038 the colo-compare hold the packet. The
4039 expired_scan_cycle=@var{ms} is to set the period of scan‐
4040 ning expired primary node network packets. The
4041 max_queue_size=@var{size} is to set the max compare queue
4042 size depend on user environment. If user want to use Xen
4043 COLO, need to add the notify_dev to notify Xen colo-frame
4044 to do checkpoint.
4045 COLO-compare must be used with the help of filter-mirror,
4047 filter-redirector and filter-rewriter.
4048 KVM COLO
4050 primary:
4052 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
4053 -device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
4054 -chardev socket,id=mirror0,host=3.3.3.3,port=9003,server=on,wait=off
4055 -chardev socket,id=compare1,host=3.3.3.3,port=9004,server=on,wait=off
4056 -chardev socket,id=compare0,host=3.3.3.3,port=9001,server=on,wait=off
4057 -chardev socket,id=compare0-0,host=3.3.3.3,port=9001
4058 -chardev socket,id=compare_out,host=3.3.3.3,port=9005,server=on,wait=off
4059 -chardev socket,id=compare_out0,host=3.3.3.3,port=9005
4060 -object iothread,id=iothread1
4061 -object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
4062 -object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
4063 -object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
4064 -object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,iothread=iothread1
4065 secondary:
4067 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
4068 -device e1000,netdev=hn0,mac=52:a4:00:12:78:66
4069 -chardev socket,id=red0,host=3.3.3.3,port=9003
4070 -chardev socket,id=red1,host=3.3.3.3,port=9004
4071 -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
4072 -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
4073 Xen COLO
4076 primary:
4078 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
4079 -device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
4080 -chardev socket,id=mirror0,host=3.3.3.3,port=9003,server=on,wait=off
4081 -chardev socket,id=compare1,host=3.3.3.3,port=9004,server=on,wait=off
4082 -chardev socket,id=compare0,host=3.3.3.3,port=9001,server=on,wait=off
4083 -chardev socket,id=compare0-0,host=3.3.3.3,port=9001
4084 -chardev socket,id=compare_out,host=3.3.3.3,port=9005,server=on,wait=off
4085 -chardev socket,id=compare_out0,host=3.3.3.3,port=9005
4086 -chardev socket,id=notify_way,host=3.3.3.3,port=9009,server=on,wait=off
4087 -object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
4088 -object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
4089 -object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
4090 -object iothread,id=iothread1
4091 -object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,notify_dev=nofity_way,iothread=iothread1
4092 secondary:
4094 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
4095 -device e1000,netdev=hn0,mac=52:a4:00:12:78:66
4096 -chardev socket,id=red0,host=3.3.3.3,port=9003
4097 -chardev socket,id=red1,host=3.3.3.3,port=9004
4098 -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
4099 -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
4100 If you want to know the detail of above command line, you
4102 can read the colo-compare git log.
4103 -object cryptodev-backend-builtin,id=id[,queues=queues]
4105 Creates a cryptodev backend which executes crypto
4106 opreation from the QEMU cipher APIS. The id parameter is
4107 a unique ID that will be used to reference this cryptodev
4108 backend from the virtio-crypto device. The queues parame‐
4109 ter is optional, which specify the queue number of cryp‐
4110 todev backend, the default of queues is 1.
4111 # qemu-system-x86_64 \
4113 [...] \
4114 -object cryptodev-backend-builtin,id=cryptodev0 \
4115 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
4116 [...]
4117 -object cryptodev-vhost-user,id=id,chardev=charde‐
4119 vid[,queues=queues]
4120 Creates a vhost-user cryptodev backend, backed by a
4121 chardev chardevid. The id parameter is a unique ID that
4122 will be used to reference this cryptodev backend from the
4123 virtio-crypto device. The chardev should be a unix domain
4124 socket backed one. The vhost-user uses a specifically
4125 defined protocol to pass vhost ioctl replacement messages
4126 to an application on the other end of the socket. The
4127 queues parameter is optional, which specify the queue
4128 number of cryptodev backend for multiqueue vhost-user,
4129 the default of queues is 1.
4130 # qemu-system-x86_64 \
4132 [...] \
4133 -chardev socket,id=chardev0,path=/path/to/socket \
4134 -object cryptodev-vhost-user,id=cryptodev0,chardev=chardev0 \
4135 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
4136 [...]
4137 -object secret,id=id,data=string,format=raw|base64[,keyid=se‐
4139 cretid,iv=string]
4140 -object secret,id=id,file=filename,format=raw|base64[,keyid=se‐
4143 cretid,iv=string]
4144 Defines a secret to store a password, encryption key, or
4145 some other sensitive data. The sensitive data can either
4146 be passed directly via the data parameter, or indirectly
4147 via the file parameter. Using the data parameter is inse‐
4148 cure unless the sensitive data is encrypted.
4149 The sensitive data can be provided in raw format (the de‐
4151 fault), or base64. When encoded as JSON, the raw format
4152 only supports valid UTF-8 characters, so base64 is recom‐
4153 mended for sending binary data. QEMU will convert from
4154 which ever format is provided to the format it needs in‐
4155 ternally. eg, an RBD password can be provided in raw for‐
4156 mat, even though it will be base64 encoded when passed
4157 onto the RBD sever.
4158 For added protection, it is possible to encrypt the data
4160 associated with a secret using the AES-256-CBC cipher.
4161 Use of encryption is indicated by providing the keyid and
4162 iv parameters. The keyid parameter provides the ID of a
4163 previously defined secret that contains the AES-256 de‐
4164 cryption key. This key should be 32-bytes long and be
4165 base64 encoded. The iv parameter provides the random ini‐
4166 tialization vector used for encryption of this particular
4167 secret and should be a base64 encrypted string of the
4168 16-byte IV.
4169 The simplest (insecure) usage is to provide the secret
4171 inline
4172 # qemu-system-x86_64 -object secret,id=sec0,data=letmein,format=raw
4174 The simplest secure usage is to provide the secret via a
4176 file
4177 # printf "letmein" > mypasswd.txt # QEMU_SYSTEM_MACRO
4179 -object secret,id=sec0,file=mypasswd.txt,format=raw
4180 For greater security, AES-256-CBC should be used. To il‐
4182 lustrate usage, consider the openssl command line tool
4183 which can encrypt the data. Note that when encrypting,
4184 the plaintext must be padded to the cipher block size (32
4185 bytes) using the standard PKCS#5/6 compatible padding al‐
4186 gorithm.
4187 First a master key needs to be created in base64 encod‐
4189 ing:
4190 # openssl rand -base64 32 > key.b64
4192 # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"')
4193 Each secret to be encrypted needs to have a random ini‐
4195 tialization vector generated. These do not need to be
4196 kept secret
4197 # openssl rand -base64 16 > iv.b64
4199 # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"')
4200 The secret to be defined can now be encrypted, in this
4202 case we're telling openssl to base64 encode the result,
4203 but it could be left as raw bytes if desired.
4204 # SECRET=$(printf "letmein" |
4206 openssl enc -aes-256-cbc -a -K $KEY -iv $IV)
4207 When launching QEMU, create a master secret pointing to
4209 key.b64 and specify that to be used to decrypt the user
4210 password. Pass the contents of iv.b64 to the second se‐
4211 cret
4212 # qemu-system-x86_64 \
4214 -object secret,id=secmaster0,format=base64,file=key.b64 \
4215 -object secret,id=sec0,keyid=secmaster0,format=base64,\
4216 data=$SECRET,iv=$(<iv.b64)
4217 -object sev-guest,id=id,cbitpos=cbitpos,re‐
4219 duced-phys-bits=val,[sev-device=string,policy=policy,handle=han‐
4220 dle,dh-cert-file=file,session-file=file]
4221 Create a Secure Encrypted Virtualization (SEV) guest ob‐
4222 ject, which can be used to provide the guest memory en‐
4223 cryption support on AMD processors.
4224 When memory encryption is enabled, one of the physical
4226 address bit (aka the C-bit) is utilized to mark if a mem‐
4227 ory page is protected. The cbitpos is used to provide the
4228 C-bit position. The C-bit position is Host family depen‐
4229 dent hence user must provide this value. On EPYC, the
4230 value should be 47.
4231 When memory encryption is enabled, we loose certain bits
4233 in physical address space. The reduced-phys-bits is used
4234 to provide the number of bits we loose in physical ad‐
4235 dress space. Similar to C-bit, the value is Host family
4236 dependent. On EPYC, the value should be 5.
4237 The sev-device provides the device file to use for commu‐
4239 nicating with the SEV firmware running inside AMD Secure
4240 Processor. The default device is '/dev/sev'. If hardware
4241 supports memory encryption then /dev/sev devices are cre‐
4242 ated by CCP driver.
4243 The policy provides the guest policy to be enforced by
4245 the SEV firmware and restrict what configuration and op‐
4246 erational commands can be performed on this guest by the
4247 hypervisor. The policy should be provided by the guest
4248 owner and is bound to the guest and cannot be changed
4249 throughout the lifetime of the guest. The default is 0.
4250 If guest policy allows sharing the key with another SEV
4252 guest then handle can be use to provide handle of the
4253 guest from which to share the key.
4254 The dh-cert-file and session-file provides the guest
4256 owner's Public Diffie-Hillman key defined in SEV spec.
4257 The PDH and session parameters are used for establishing
4258 a cryptographic session with the guest owner to negotiate
4259 keys used for attestation. The file must be encoded in
4260 base64.
4261 e.g to launch a SEV guest
4263 # qemu-system-x86_64 \
4265 ...... \
4266 -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=5 \
4267 -machine ...,memory-encryption=sev0 \
4268 .....
4269 -object authz-simple,id=id,identity=string
4271 Create an authorization object that will control access
4272 to network services.
4273 The identity parameter is identifies the user and its
4275 format depends on the network service that authorization
4276 object is associated with. For authorizing based on TLS
4277 x509 certificates, the identity must be the x509 distin‐
4278 guished name. Note that care must be taken to escape any
4279 commas in the distinguished name.
4280 An example authorization object to validate a x509 dis‐
4282 tinguished name would look like:
4283 # qemu-system-x86_64 \
4285 ... \
4286 -object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,O=Example Org,,L=London,,ST=London,,C=GB' \
4287 ...
4288 Note the use of quotes due to the x509 distinguished name
4290 containing whitespace, and escaping of ','.
4291 -object authz-listfile,id=id,filename=path,refresh=on|off
4293 Create an authorization object that will control access
4294 to network services.
4295 The filename parameter is the fully qualified path to a
4297 file containing the access control list rules in JSON
4298 format.
4299 An example set of rules that match against SASL usernames
4301 might look like:
4302 {
4304 "rules": [
4305 { "match": "fred", "policy": "allow", "format": "exact" },
4306 { "match": "bob", "policy": "allow", "format": "exact" },
4307 { "match": "danb", "policy": "deny", "format": "glob" },
4308 { "match": "dan*", "policy": "allow", "format": "exact" },
4309 ],
4310 "policy": "deny"
4311 }
4312 When checking access the object will iterate over all the
4314 rules and the first rule to match will have its policy
4315 value returned as the result. If no rules match, then the
4316 default policy value is returned.
4317 The rules can either be an exact string match, or they
4319 can use the simple UNIX glob pattern matching to allow
4320 wildcards to be used.
4321 If refresh is set to true the file will be monitored and
4323 automatically reloaded whenever its content changes.
4324 As with the authz-simple object, the format of the iden‐
4326 tity strings being matched depends on the network ser‐
4327 vice, but is usually a TLS x509 distinguished name, or a
4328 SASL username.
4329 An example authorization object to validate a SASL user‐
4331 name would look like:
4332 # qemu-system-x86_64 \
4334 ... \
4335 -object authz-simple,id=auth0,filename=/etc/qemu/vnc-sasl.acl,refresh=on \
4336 ...
4337 -object authz-pam,id=id,service=string
4339 Create an authorization object that will control access
4340 to network services.
4341 The service parameter provides the name of a PAM service
4343 to use for authorization. It requires that a file
4344 /etc/pam.d/service exist to provide the configuration for
4345 the account subsystem.
4346 An example authorization object to validate a TLS x509
4348 distinguished name would look like:
4349 # qemu-system-x86_64 \
4351 ... \
4352 -object authz-pam,id=auth0,service=qemu-vnc \
4353 ...
4354 There would then be a corresponding config file for PAM
4356 at /etc/pam.d/qemu-vnc that contains:
4357 account requisite pam_listfile.so item=user sense=allow \
4359 file=/etc/qemu/vnc.allow
4360 Finally the /etc/qemu/vnc.allow file would contain the
4362 list of x509 distingished names that are permitted access
4363 CN=laptop.example.com,O=Example Home,L=London,ST=London,C=GB
4365 -object io‐
4367 thread,id=id,poll-max-ns=poll-max-ns,poll-grow=poll-grow,poll-shrink=poll-shrink,aio-max-batch=aio-max-batch
4368 Creates a dedicated event loop thread that devices can be
4369 assigned to. This is known as an IOThread. By default de‐
4370 vice emulation happens in vCPU threads or the main event
4371 loop thread. This can become a scalability bottleneck.
4372 IOThreads allow device emulation and I/O to run on other
4373 host CPUs.
4374 The id parameter is a unique ID that will be used to ref‐
4376 erence this IOThread from -device ...,iothread=id. Mul‐
4377 tiple devices can be assigned to an IOThread. Note that
4378 not all devices support an iothread parameter.
4379 The query-iothreads QMP command lists IOThreads and re‐
4381 ports their thread IDs so that the user can configure
4382 host CPU pinning/affinity.
4383 IOThreads use an adaptive polling algorithm to reduce
4385 event loop latency. Instead of entering a blocking system
4386 call to monitor file descriptors and then pay the cost of
4387 being woken up when an event occurs, the polling algo‐
4388 rithm spins waiting for events for a short time. The al‐
4389 gorithm's default parameters are suitable for many cases
4390 but can be adjusted based on knowledge of the workload
4391 and/or host device latency.
4392 The poll-max-ns parameter is the maximum number of
4394 nanoseconds to busy wait for events. Polling can be dis‐
4395 abled by setting this value to 0.
4396 The poll-grow parameter is the multiplier used to in‐
4398 crease the polling time when the algorithm detects it is
4399 missing events due to not polling long enough.
4400 The poll-shrink parameter is the divisor used to decrease
4402 the polling time when the algorithm detects it is spend‐
4403 ing too long polling without encountering events.
4404 The aio-max-batch parameter is the maximum number of re‐
4406 quests in a batch for the AIO engine, 0 means that the
4407 engine will use its default.
4408 The IOThread parameters can be modified at run-time using
4410 the qom-set command (where iothread1 is the IOThread's
4411 id):
4412 (qemu) qom-set /objects/iothread1 poll-max-ns 100000
4414 During the graphical emulation, you can use special key combinations to
4416 change modes. The default key mappings are shown below, but if you use
4417 -alt-grab then the modifier is Ctrl-Alt-Shift (instead of Ctrl-Alt) and
4418 if you use -ctrl-grab then the modifier is the right Ctrl key (instead
4419 of Ctrl-Alt):
4420 Ctrl-Alt-f
4422 Toggle full screen
4423 Ctrl-Alt-+
4425 Enlarge the screen
4426 Ctrl-Alt--
4428 Shrink the screen
4429 Ctrl-Alt-u
4431 Restore the screen's un-scaled dimensions
4432 Ctrl-Alt-n
4434 Switch to virtual console 'n'. Standard console mappings are:
4435 1 Target system display
4437 2 Monitor
4439 3 Serial port
4441 Ctrl-Alt
4443 Toggle mouse and keyboard grab.
4444 In the virtual consoles, you can use Ctrl-Up, Ctrl-Down, Ctrl-PageUp
4446 and Ctrl-PageDown to move in the back log.
4447 During emulation, if you are using a character backend multiplexer
4449 (which is the default if you are using -nographic) then several com‐
4450 mands are available via an escape sequence. These key sequences all
4451 start with an escape character, which is Ctrl-a by default, but can be
4452 changed with -echr. The list below assumes you're using the default.
4453 Ctrl-a h
4455 Print this help
4456 Ctrl-a x
4458 Exit emulator
4459 Ctrl-a s
4461 Save disk data back to file (if -snapshot)
4462 Ctrl-a t
4464 Toggle console timestamps
4465 Ctrl-a b
4467 Send break (magic sysrq in Linux)
4468 Ctrl-a c
4470 Rotate between the frontends connected to the multiplexer (usu‐
4471 ally this switches between the monitor and the console)
4472 Ctrl-a Ctrl-a
4474 Send the escape character to the frontend
4475
4477 In addition to using normal file images for the emulated storage de‐
4478 vices, QEMU can also use networked resources such as iSCSI devices.
4479 These are specified using a special URL syntax.
4480 iSCSI iSCSI support allows QEMU to access iSCSI resources directly and
4482 use as images for the guest storage. Both disk and cdrom images
4483 are supported.
4484 Syntax for specifying iSCSI LUNs is "iscsi://<tar‐
4486 get-ip>[:<port>]/<target-iqn>/<lun>"
4487 By default qemu will use the iSCSI initiator-name
4489 'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set
4490 from the command line or a configuration file.
4491 Since version Qemu 2.4 it is possible to specify a iSCSI request
4493 timeout to detect stalled requests and force a reestablishment
4494 of the session. The timeout is specified in seconds. The default
4495 is 0 which means no timeout. Libiscsi 1.15.0 or greater is re‐
4496 quired for this feature.
4497 Example (without authentication):
4499 qemu-system-x86_64 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
4501 -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
4502 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
4503 Example (CHAP username/password via URL):
4505 qemu-system-x86_64 -drive file=iscsi://user%password@192.0.2.1/iqn.2001-04.com.example/1
4507 Example (CHAP username/password via environment variables):
4509 LIBISCSI_CHAP_USERNAME="user" \
4511 LIBISCSI_CHAP_PASSWORD="password" \
4512 qemu-system-x86_64 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
4513 NBD QEMU supports NBD (Network Block Devices) both using TCP proto‐
4515 col as well as Unix Domain Sockets. With TCP, the default port
4516 is 10809.
4517 Syntax for specifying a NBD device using TCP, in preferred URI
4519 form: "nbd://<server-ip>[:<port>]/[<export>]"
4520 Syntax for specifying a NBD device using Unix Domain Sockets;
4522 remember that '?' is a shell glob character and may need quot‐
4523 ing: "nbd+unix:///[<export>]?socket=<domain-socket>"
4524 Older syntax that is also recognized:
4526 "nbd:<server-ip>:<port>[:exportname=<export>]"
4527 Syntax for specifying a NBD device using Unix Domain Sockets
4529 "nbd:unix:<domain-socket>[:exportname=<export>]"
4530 Example for TCP
4532 qemu-system-x86_64 --drive file=nbd:192.0.2.1:30000
4534 Example for Unix Domain Sockets
4536 qemu-system-x86_64 --drive file=nbd:unix:/tmp/nbd-socket
4538 SSH QEMU supports SSH (Secure Shell) access to remote disks.
4540 Examples:
4542 qemu-system-x86_64 -drive file=ssh://user@host/path/to/disk.img
4544 qemu-system-x86_64 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
4545 Currently authentication must be done using ssh-agent. Other au‐
4547 thentication methods may be supported in future.
4548 GlusterFS
4550 GlusterFS is a user space distributed file system. QEMU supports
4551 the use of GlusterFS volumes for hosting VM disk images using
4552 TCP, Unix Domain Sockets and RDMA transport protocols.
4553 Syntax for specifying a VM disk image on GlusterFS volume is
4555 URI:
4557 gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
4558 JSON:
4560 'json:{"driver":"qcow2","file":{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...",
4561 "server":[{"type":"tcp","host":"...","port":"..."},
4562 {"type":"unix","socket":"..."}]}}'
4563 Example
4565 URI:
4567 qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img,
4568 file.debug=9,file.logfile=/var/log/qemu-gluster.log
4569 JSON:
4571 qemu-system-x86_64 'json:{"driver":"qcow2",
4572 "file":{"driver":"gluster",
4573 "volume":"testvol","path":"a.img",
4574 "debug":9,"logfile":"/var/log/qemu-gluster.log",
4575 "server":[{"type":"tcp","host":"1.2.3.4","port":24007},
4576 {"type":"unix","socket":"/var/run/glusterd.socket"}]}}'
4577 qemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
4578 file.debug=9,file.logfile=/var/log/qemu-gluster.log,
4579 file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
4580 file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
4581 See also http://www.gluster.org.
4583 HTTP/HTTPS/FTP/FTPS
4585 QEMU supports read-only access to files accessed over http(s)
4586 and ftp(s).
4587 Syntax using a single filename:
4589 <protocol>://[<username>[:<password>]@]<host>/<path>
4591 where:
4593 protocol
4595 'http', 'https', 'ftp', or 'ftps'.
4596 username
4598 Optional username for authentication to the remote
4599 server.
4600 password
4602 Optional password for authentication to the remote
4603 server.
4604 host Address of the remote server.
4606 path Path on the remote server, including any query string.
4608 The following options are also supported:
4610 url The full URL when passing options to the driver explic‐
4612 itly.
4613 readahead
4615 The amount of data to read ahead with each range request
4616 to the remote server. This value may optionally have the
4617 suffix 'T', 'G', 'M', 'K', 'k' or 'b'. If it does not
4618 have a suffix, it will be assumed to be in bytes. The
4619 value must be a multiple of 512 bytes. It defaults to
4620 256k.
4621 sslverify
4623 Whether to verify the remote server's certificate when
4624 connecting over SSL. It can have the value 'on' or 'off'.
4625 It defaults to 'on'.
4626 cookie Send this cookie (it can also be a list of cookies sepa‐
4628 rated by ';') with each outgoing request. Only supported
4629 when using protocols such as HTTP which support cookies,
4630 otherwise ignored.
4631 timeout
4633 Set the timeout in seconds of the CURL connection. This
4634 timeout is the time that CURL waits for a response from
4635 the remote server to get the size of the image to be
4636 downloaded. If not set, the default timeout of 5 seconds
4637 is used.
4638 Note that when passing options to qemu explicitly, driver is the
4640 value of <protocol>.
4641 Example: boot from a remote Fedora 20 live ISO image
4643 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
4645 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
4647 Example: boot from a remote Fedora 20 cloud image using a local
4649 overlay for writes, copy-on-read, and a readahead of 64k
4650 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
4652 qemu-system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
4654 Example: boot from an image stored on a VMware vSphere server
4656 with a self-signed certificate using a local overlay for writes,
4657 a readahead of 64k and a timeout of 10 seconds.
4658 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
4660 qemu-system-x86_64 -drive file=/tmp/test.qcow2
4662
4664 The HTML documentation of QEMU for more precise information and Linux
4665 user mode emulator invocation.
4666
4668 Fabrice Bellard
4669
4671 2021, The QEMU Project Developers
46726.1.0 Nov 08, 2021 QEMU(1)