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
17 extensions (hardware level, including all non standard modes).
18 · PS/2 mouse and keyboard
20 · 2 PCI IDE interfaces with hard disk and CD-ROM support
22 · Floppy disk
24 · PCI and ISA network adapters
26 · Serial ports
28 · IPMI BMC, either and internal or external one
30 · Creative SoundBlaster 16 sound card
32 · ENSONIQ AudioPCI ES1370 sound card
34 · Intel 82801AA AC97 Audio compatible sound card
36 · Intel HD Audio Controller and HDA codec
38 · Adlib (OPL2) - Yamaha YM3812 compatible chip
40 · Gravis Ultrasound GF1 sound card
42 · CS4231A compatible sound card
44 · 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, whpx or tcg can
110 be available. By default, tcg is used. If there is more
111 than one accelerator specified, the next one is used if
112 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
117 accel=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 enforce-config-section=on|off
143 If enforce-config-section is set to on, force migration
144 code to send configuration section even if the
145 machine-type sets the migration.send-configuration prop‐
146 erty to off. NOTE: this parameter is deprecated. Please
147 use -global migration.send-configuration=on|off instead.
148 memory-encryption=
150 Memory encryption object to use. The default is none.
151 hmat=on|off
153 Enables or disables ACPI Heterogeneous Memory Attribute
154 Table (HMAT) support. The default is off.
155 -cpu model
157 Select CPU model (-cpu help for list and additional feature
158 selection)
159 -accel name[,prop=value[,...]]
161 This is used to enable an accelerator. Depending on the target
162 architecture, kvm, xen, hax, hvf, whpx or tcg can be available.
163 By default, tcg is used. If there is more than one accelerator
164 specified, the next one is used if the previous one fails to
165 initialize.
166 igd-passthru=on|off
168 When Xen is in use, this option controls whether Intel
169 integrated graphics devices can be passed through to the
170 guest (default=off)
171 kernel-irqchip=on|off|split
173 Controls KVM in-kernel irqchip support. The default is
174 full acceleration of the interrupt controllers. On x86,
175 split irqchip reduces the kernel attack surface, at a
176 performance cost for non-MSI interrupts. Disabling the
177 in-kernel irqchip completely is not recommended except
178 for debugging purposes.
179 kvm-shadow-mem=size
181 Defines the size of the KVM shadow MMU.
182 tb-size=n
184 Controls the size (in MiB) of the TCG translation block
185 cache.
186 thread=single|multi
188 Controls number of TCG threads. When the TCG is
189 multi-threaded there will be one thread per vCPU therefor
190 taking advantage of additional host cores. The default is
191 to enable multi-threading where both the back-end and
192 front-ends support it and no incompatible TCG features
193 have been enabled (e.g. icount/replay).
194 -smp [cpus=]n[,cores=cores][,threads=threads][,dies=dies][,sock‐
196 ets=sockets][,maxcpus=maxcpus]
197 Simulate an SMP system with n CPUs. On the PC target, up to 255
198 CPUs are supported. On Sparc32 target, Linux limits the number
199 of usable CPUs to 4. For the PC target, the number of cores per
200 die, the number of threads per cores, the number of dies per
201 packages and the total number of sockets can be specified. Miss‐
202 ing values will be computed. If any on the three values is
203 given, the total number of CPUs n can be omitted. maxcpus speci‐
204 fies the maximum number of hotpluggable CPUs.
205 -numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initia‐
207 tor=initiator]
208 -numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initia‐
211 tor=initiator]
212 -numa dist,src=source,dst=destination,val=distance
215 -numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]
218 -numa hmat-lb,initiator=node,target=node,hierarchy=hierar‐
221 chy,data-type=tpye[,latency=lat][,bandwidth=bw]
222 -numa hmat-cache,node-id=node,size=size,level=level[,associativ‐
225 ity=str][,policy=str][,line=size]
226 Define a NUMA node and assign RAM and VCPUs to it. Set the NUMA
227 distance from a source node to a destination node. Set the ACPI
228 Heterogeneous Memory Attributes for the given nodes.
229 Legacy VCPU assignment uses 'cpus' option where firstcpu and
231 lastcpu are CPU indexes. Each 'cpus' option represent a contigu‐
232 ous range of CPU indexes (or a single VCPU if lastcpu is omit‐
233 ted). A non-contiguous set of VCPUs can be represented by pro‐
234 viding multiple 'cpus' options. If 'cpus' is omitted on all
235 nodes, VCPUs are automatically split between them.
236 For example, the following option assigns VCPUs 0, 1, 2 and 5 to
238 a NUMA node:
239 -numa node,cpus=0-2,cpus=5
241 'cpu' option is a new alternative to 'cpus' option which uses
243 'socket-id|core-id|thread-id' properties to assign CPU objects
244 to a node using topology layout properties of CPU. The set of
245 properties is machine specific, and depends on used machine
246 type/'smp' options. It could be queried with 'hotpluggable-cpus'
247 monitor command. 'node-id' property specifies node to which CPU
248 object will be assigned, it's required for node to be declared
249 with 'node' option before it's used with 'cpu' option.
250 For example:
252 -M pc \
254 -smp 1,sockets=2,maxcpus=2 \
255 -numa node,nodeid=0 -numa node,nodeid=1 \
256 -numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1
257 Legacy 'mem' assigns a given RAM amount to a node (not supported
259 for 5.1 and newer machine types). 'memdev' assigns RAM from a
260 given memory backend device to a node. If 'mem' and 'memdev' are
261 omitted in all nodes, RAM is split equally between them.
262 'mem' and 'memdev' are mutually exclusive. Furthermore, if one
264 node uses 'memdev', all of them have to use it.
265 'initiator' is an additional option that points to an initiator
267 NUMA node that has best performance (the lowest latency or
268 largest bandwidth) to this NUMA node. Note that this option can
269 be set only when the machine property 'hmat' is set to 'on'.
270 Following example creates a machine with 2 NUMA nodes, node 0
272 has CPU. node 1 has only memory, and its initiator is node 0.
273 Note that because node 0 has CPU, by default the initiator of
274 node 0 is itself and must be itself.
275 -machine hmat=on \
277 -m 2G,slots=2,maxmem=4G \
278 -object memory-backend-ram,size=1G,id=m0 \
279 -object memory-backend-ram,size=1G,id=m1 \
280 -numa node,nodeid=0,memdev=m0 \
281 -numa node,nodeid=1,memdev=m1,initiator=0 \
282 -smp 2,sockets=2,maxcpus=2 \
283 -numa cpu,node-id=0,socket-id=0 \
284 -numa cpu,node-id=0,socket-id=1
285 source and destination are NUMA node IDs. distance is the NUMA
287 distance from source to destination. The distance from a node to
288 itself is always 10. If any pair of nodes is given a distance,
289 then all pairs must be given distances. Although, when distances
290 are only given in one direction for each pair of nodes, then the
291 distances in the opposite directions are assumed to be the same.
292 If, however, an asymmetrical pair of distances is given for even
293 one node pair, then all node pairs must be provided distance
294 values for both directions, even when they are symmetrical. When
295 a node is unreachable from another node, set the pair's distance
296 to 255.
297 Note that the -numa option doesn't allocate any of the specified
299 resources, it just assigns existing resources to NUMA nodes.
300 This means that one still has to use the -m, -smp options to
301 allocate RAM and VCPUs respectively.
302 Use 'hmat-lb' to set System Locality Latency and Bandwidth
304 Information between initiator and target NUMA nodes in ACPI Het‐
305 erogeneous Attribute Memory Table (HMAT). Initiator NUMA node
306 can create memory requests, usually it has one or more proces‐
307 sors. Target NUMA node contains addressable memory.
308 In 'hmat-lb' option, node are NUMA node IDs. hierarchy is the
310 memory hierarchy of the target NUMA node: if hierarchy is 'mem‐
311 ory', the structure represents the memory performance; if hier‐
312 archy is 'first-level|second-level|third-level', this structure
313 represents aggregated performance of memory side caches for each
314 domain. type of 'data-type' is type of data represented by this
315 structure instance: if 'hierarchy' is 'memory', 'data-type' is
316 'access|read|write' latency or 'access|read|write' bandwidth of
317 the target memory; if 'hierarchy' is 'first-level|sec‐
318 ond-level|third-level', 'data-type' is 'access|read|write' hit
319 latency or 'access|read|write' hit bandwidth of the target mem‐
320 ory side cache.
321 lat is latency value in nanoseconds. bw is bandwidth value, the
323 possible value and units are NUM[M|G|T], mean that the bandwidth
324 value are NUM byte per second (or MB/s, GB/s or TB/s depending
325 on used suffix). Note that if latency or bandwidth value is 0,
326 means the corresponding latency or bandwidth information is not
327 provided.
328 In 'hmat-cache' option, node-id is the NUMA-id of the memory
330 belongs. size is the size of memory side cache in bytes. level
331 is the cache level described in this structure, note that the
332 cache level 0 should not be used with 'hmat-cache' option.
333 associativity is the cache associativity, the possible value is
334 'none/direct(direct-mapped)/complex(complex cache indexing)'.
335 policy is the write policy. line is the cache Line size in
336 bytes.
337 For example, the following options describe 2 NUMA nodes. Node 0
339 has 2 cpus and a ram, node 1 has only a ram. The processors in
340 node 0 access memory in node 0 with access-latency 5 nanosec‐
341 onds, access-bandwidth is 200 MB/s; The processors in NUMA node
342 0 access memory in NUMA node 1 with access-latency 10 nanosec‐
343 onds, access-bandwidth is 100 MB/s. And for memory side cache
344 information, NUMA node 0 and 1 both have 1 level memory cache,
345 size is 10KB, policy is write-back, the cache Line size is 8
346 bytes:
347 -machine hmat=on \
349 -m 2G \
350 -object memory-backend-ram,size=1G,id=m0 \
351 -object memory-backend-ram,size=1G,id=m1 \
352 -smp 2 \
353 -numa node,nodeid=0,memdev=m0 \
354 -numa node,nodeid=1,memdev=m1,initiator=0 \
355 -numa cpu,node-id=0,socket-id=0 \
356 -numa cpu,node-id=0,socket-id=1 \
357 -numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-latency,latency=5 \
358 -numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-bandwidth,bandwidth=200M \
359 -numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-latency,latency=10 \
360 -numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-bandwidth,bandwidth=100M \
361 -numa hmat-cache,node-id=0,size=10K,level=1,associativity=direct,policy=write-back,line=8 \
362 -numa hmat-cache,node-id=1,size=10K,level=1,associativity=direct,policy=write-back,line=8
363 -add-fd fd=fd,set=set[,opaque=opaque]
365 Add a file descriptor to an fd set. Valid options are:
366 fd=fd This option defines the file descriptor of which a dupli‐
368 cate is added to fd set. The file descriptor cannot be
369 stdin, stdout, or stderr.
370 set=set
372 This option defines the ID of the fd set to add the file
373 descriptor to.
374 opaque=opaque
376 This option defines a free-form string that can be used
377 to describe fd.
378 You can open an image using pre-opened file descriptors from an
380 fd set:
381 qemu-system-x86_64 -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" -drive file=/dev/fdset/2,index=0,media=disk
383 -set group.id.arg=value
385 Set parameter arg for item id of type group
386 -global driver.prop=value
388 -global driver=driver,property=property,value=value
391 Set default value of driver's property prop to value, e.g.:
392 qemu_system-x86_64 -global ide-hd.physical_block_size=4096 disk-image.img
394 In particular, you can use this to set driver properties for
396 devices which are created automatically by the machine model. To
397 create a device which is not created automatically and set prop‐
398 erties on it, use -device.
399 -global driver.prop=value is shorthand for -global
401 driver=driver,property=prop,value=value. The longhand syntax
402 works even when driver contains a dot.
403 -boot
405 [order=drives][,once=drives][,menu=on|off][,splash=sp_name][,splash-time=sp_time][,reboot-time‐
406 out=rb_timeout][,strict=on|off]
407 Specify boot order drives as a string of drive letters. Valid
408 drive letters depend on the target architecture. The x86 PC
409 uses: a, b (floppy 1 and 2), c (first hard disk), d (first
410 CD-ROM), n-p (Etherboot from network adapter 1-4), hard disk
411 boot is the default. To apply a particular boot order only on
412 the first startup, specify it via once. Note that the order or
413 once parameter should not be used together with the bootindex
414 property of devices, since the firmware implementations normally
415 do not support both at the same time.
416 Interactive boot menus/prompts can be enabled via menu=on as far
418 as firmware/BIOS supports them. The default is non-interactive
419 boot.
420 A splash picture could be passed to bios, enabling user to show
422 it as logo, when option splash=sp_name is given and menu=on, If
423 firmware/BIOS supports them. Currently Seabios for X86 system
424 support it. limitation: The splash file could be a jpeg file or
425 a BMP file in 24 BPP format(true color). The resolution should
426 be supported by the SVGA mode, so the recommended is 320x240,
427 640x480, 800x640.
428 A timeout could be passed to bios, guest will pause for rb_time‐
430 out ms when boot failed, then reboot. If rb_timeout is '-1',
431 guest will not reboot, qemu passes '-1' to bios by default. Cur‐
432 rently Seabios for X86 system support it.
433 Do strict boot via strict=on as far as firmware/BIOS supports
435 it. This only effects when boot priority is changed by bootindex
436 options. The default is non-strict boot.
437 # try to boot from network first, then from hard disk
439 qemu_system-x86_64 -boot order=nc
440 # boot from CD-ROM first, switch back to default order after reboot
441 qemu_system-x86_64 -boot once=d
442 # boot with a splash picture for 5 seconds.
443 qemu_system-x86_64 -boot menu=on,splash=/root/boot.bmp,splash-time=5000
444 Note: The legacy format '-boot drives' is still supported but
446 its use is discouraged as it may be removed from future ver‐
447 sions.
448 -m [size=]megs[,slots=n,maxmem=size]
450 Sets guest startup RAM size to megs megabytes. Default is 128
451 MiB. Optionally, a suffix of "M" or "G" can be used to signify
452 a value in megabytes or gigabytes respectively. Optional pair
453 slots, maxmem could be used to set amount of hotpluggable memory
454 slots and maximum amount of memory. Note that maxmem must be
455 aligned to the page size.
456 For example, the following command-line sets the guest startup
458 RAM size to 1GB, creates 3 slots to hotplug additional memory
459 and sets the maximum memory the guest can reach to 4GB:
460 qemu-system-x86_64 -m 1G,slots=3,maxmem=4G
462 If slots and maxmem are not specified, memory hotplug won't be
464 enabled and the guest startup RAM will never increase.
465 -mem-path path
467 Allocate guest RAM from a temporarily created file in path.
468 -mem-prealloc
470 Preallocate memory when using -mem-path.
471 -k language
473 Use keyboard layout language (for example fr for French). This
474 option is only needed where it is not easy to get raw PC key‐
475 codes (e.g. on Macs, with some X11 servers or with a VNC or
476 curses display). You don't normally need to use it on PC/Linux
477 or PC/Windows hosts.
478 The available layouts are:
480 ar de-ch es fo fr-ca hu ja mk no pt-br sv
482 da en-gb et fr fr-ch is lt nl pl ru th
483 de en-us fi fr-be hr it lv nl-be pt sl tr
484 The default is en-us.
486 -audio-help
488 Will show the -audiodev equivalent of the currently specified
489 (deprecated) environment variables.
490 -audiodev [driver=]driver,id=id[,prop[=value][,...]]
492 Adds a new audio backend driver identified by id. There are
493 global and driver specific properties. Some values can be set
494 differently for input and output, they're marked with in|out..
495 You can set the input's property with in.prop and the output's
496 property with out.prop. For example:
497 -audiodev alsa,id=example,in.frequency=44110,out.frequency=8000
499 -audiodev alsa,id=example,out.channels=1 # leaves in.channels unspecified
500 NOTE: parameter validation is known to be incomplete, in many
502 cases specifying an invalid option causes QEMU to print an error
503 message and continue emulation without sound.
504 Valid global options are:
506 id=identifier
508 Identifies the audio backend.
509 timer-period=period
511 Sets the timer period used by the audio subsystem in
512 microseconds. Default is 10000 (10 ms).
513 in|out.mixing-engine=on|off
515 Use QEMU's mixing engine to mix all streams inside QEMU
516 and convert audio formats when not supported by the back‐
517 end. When off, fixed-settings must be off too. Note that
518 disabling this option means that the selected backend
519 must support multiple streams and the audio formats used
520 by the virtual cards, otherwise you'll get no sound. It's
521 not recommended to disable this option unless you want to
522 use 5.1 or 7.1 audio, as mixing engine only supports mono
523 and stereo audio. Default is on.
524 in|out.fixed-settings=on|off
526 Use fixed settings for host audio. When off, it will
527 change based on how the guest opens the sound card. In
528 this case you must not specify frequency, channels or
529 format. Default is on.
530 in|out.frequency=frequency
532 Specify the frequency to use when using fixed-settings.
533 Default is 44100Hz.
534 in|out.channels=channels
536 Specify the number of channels to use when using
537 fixed-settings. Default is 2 (stereo).
538 in|out.format=format
540 Specify the sample format to use when using fixed-set‐
541 tings. Valid values are: s8, s16, s32, u8, u16, u32,
542 f32. Default is s16.
543 in|out.voices=voices
545 Specify the number of voices to use. Default is 1.
546 in|out.buffer-length=usecs
548 Sets the size of the buffer in microseconds.
549 -audiodev none,id=id[,prop[=value][,...]]
551 Creates a dummy backend that discards all outputs. This backend
552 has no backend specific properties.
553 -audiodev alsa,id=id[,prop[=value][,...]]
555 Creates backend using the ALSA. This backend is only available
556 on Linux.
557 ALSA specific options are:
559 in|out.dev=device
561 Specify the ALSA device to use for input and/or output.
562 Default is default.
563 in|out.period-length=usecs
565 Sets the period length in microseconds.
566 in|out.try-poll=on|off
568 Attempt to use poll mode with the device. Default is on.
569 threshold=threshold
571 Threshold (in microseconds) when playback starts. Default
572 is 0.
573 -audiodev coreaudio,id=id[,prop[=value][,...]]
575 Creates a backend using Apple's Core Audio. This backend is only
576 available on Mac OS and only supports playback.
577 Core Audio specific options are:
579 in|out.buffer-count=count
581 Sets the count of the buffers.
582 -audiodev dsound,id=id[,prop[=value][,...]]
584 Creates a backend using Microsoft's DirectSound. This backend is
585 only available on Windows and only supports playback.
586 DirectSound specific options are:
588 latency=usecs
590 Add extra usecs microseconds latency to playback. Default
591 is 10000 (10 ms).
592 -audiodev oss,id=id[,prop[=value][,...]]
594 Creates a backend using OSS. This backend is available on most
595 Unix-like systems.
596 OSS specific options are:
598 in|out.dev=device
600 Specify the file name of the OSS device to use. Default
601 is /dev/dsp.
602 in|out.buffer-count=count
604 Sets the count of the buffers.
605 in|out.try-poll=on|of
607 Attempt to use poll mode with the device. Default is on.
608 try-mmap=on|off
610 Try using memory mapped device access. Default is off.
611 exclusive=on|off
613 Open the device in exclusive mode (vmix won't work in
614 this case). Default is off.
615 dsp-policy=policy
617 Sets the timing policy (between 0 and 10, where smaller
618 number means smaller latency but higher CPU usage). Use
619 -1 to use buffer sizes specified by buffer and buf‐
620 fer-count. This option is ignored if you do not have OSS
621 4. Default is 5.
622 -audiodev pa,id=id[,prop[=value][,...]]
624 Creates a backend using PulseAudio. This backend is available on
625 most systems.
626 PulseAudio specific options are:
628 server=server
630 Sets the PulseAudio server to connect to.
631 in|out.name=sink
633 Use the specified source/sink for recording/playback.
634 in|out.latency=usecs
636 Desired latency in microseconds. The PulseAudio server
637 will try to honor this value but actual latencies may be
638 lower or higher.
639 -audiodev sdl,id=id[,prop[=value][,...]]
641 Creates a backend using SDL. This backend is available on most
642 systems, but you should use your platform's native backend if
643 possible. This backend has no backend specific properties.
644 -audiodev spice,id=id[,prop[=value][,...]]
646 Creates a backend that sends audio through SPICE. This backend
647 requires -spice and automatically selected in that case, so usu‐
648 ally you can ignore this option. This backend has no backend
649 specific properties.
650 -audiodev wav,id=id[,prop[=value][,...]]
652 Creates a backend that writes audio to a WAV file.
653 Backend specific options are:
655 path=path
657 Write recorded audio into the specified file. Default is
658 qemu.wav.
659 -soundhw card1[,card2,...] or -soundhw all
661 Enable audio and selected sound hardware. Use 'help' to print
662 all available sound hardware. For example:
663 qemu_system-x86_64 -soundhw sb16,adlib disk.img
665 qemu_system-x86_64 -soundhw es1370 disk.img
666 qemu_system-x86_64 -soundhw ac97 disk.img
667 qemu_system-x86_64 -soundhw hda disk.img
668 qemu_system-x86_64 -soundhw all disk.img
669 qemu_system-x86_64 -soundhw help
670 Note that Linux's i810_audio OSS kernel (for AC97) module might
672 require manually specifying clocking.
673 modprobe i810_audio clocking=48000
675 -device driver[,prop[=value][,...]]
677 Add device driver. prop=value sets driver properties. Valid
678 properties depend on the driver. To get help on possible drivers
679 and properties, use -device help and -device driver,help.
680 Some drivers are:
682 -device ipmi-bmc-sim,id=id[,prop[=value][,...]]
684 Add an IPMI BMC. This is a simulation of a hardware management
685 interface processor that normally sits on a system. It provides
686 a watchdog and the ability to reset and power control the sys‐
687 tem. You need to connect this to an IPMI interface to make it
688 useful
689 The IPMI slave address to use for the BMC. The default is 0x20.
691 This address is the BMC's address on the I2C network of manage‐
692 ment controllers. If you don't know what this means, it is safe
693 to ignore it.
694 id=id The BMC id for interfaces to use this device.
696 slave_addr=val
698 Define slave address to use for the BMC. The default is
699 0x20.
700 sdrfile=file
702 file containing raw Sensor Data Records (SDR) data. The
703 default is none.
704 fruareasize=val
706 size of a Field Replaceable Unit (FRU) area. The default
707 is 1024.
708 frudatafile=file
710 file containing raw Field Replaceable Unit (FRU) inven‐
711 tory data. The default is none.
712 guid=uuid
714 value for the GUID for the BMC, in standard UUID format.
715 If this is set, get "Get GUID" command to the BMC will
716 return it. Otherwise "Get GUID" will return an error.
717 -device ipmi-bmc-extern,id=id,chardev=id[,slave_addr=val]
719 Add a connection to an external IPMI BMC simulator. Instead of
720 locally emulating the BMC like the above item, instead connect
721 to an external entity that provides the IPMI services.
722 A connection is made to an external BMC simulator. If you do
724 this, it is strongly recommended that you use the "reconnect="
725 chardev option to reconnect to the simulator if the connection
726 is lost. Note that if this is not used carefully, it can be a
727 security issue, as the interface has the ability to send resets,
728 NMIs, and power off the VM. It's best if QEMU makes a connection
729 to an external simulator running on a secure port on localhost,
730 so neither the simulator nor QEMU is exposed to any outside net‐
731 work.
732 See the "lanserv/README.vm" file in the OpenIPMI library for
734 more details on the external interface.
735 -device isa-ipmi-kcs,bmc=id[,ioport=val][,irq=val]
737 Add a KCS IPMI interafce on the ISA bus. This also adds a corre‐
738 sponding ACPI and SMBIOS entries, if appropriate.
739 bmc=id The BMC to connect to, one of ipmi-bmc-sim or
741 ipmi-bmc-extern above.
742 ioport=val
744 Define the I/O address of the interface. The default is
745 0xca0 for KCS.
746 irq=val
748 Define the interrupt to use. The default is 5. To disable
749 interrupts, set this to 0.
750 -device isa-ipmi-bt,bmc=id[,ioport=val][,irq=val]
752 Like the KCS interface, but defines a BT interface. The default
753 port is 0xe4 and the default interrupt is 5.
754 -device pci-ipmi-kcs,bmc=id
756 Add a KCS IPMI interafce on the PCI bus.
757 bmc=id The BMC to connect to, one of ipmi-bmc-sim or
759 ipmi-bmc-extern above.
760 -device pci-ipmi-bt,bmc=id
762 Like the KCS interface, but defines a BT interface on the PCI
763 bus.
764 -name name
766 Sets the name of the guest. This name will be displayed in the
767 SDL window caption. The name will also be used for the VNC
768 server. Also optionally set the top visible process name in
769 Linux. Naming of individual threads can also be enabled on Linux
770 to aid debugging.
771 -uuid uuid
773 Set system UUID.
774 Block device options
776 -fda file
777 -fdb file
780 Use file as floppy disk 0/1 image (see disk_005fimages).
781 -hda file
783 -hdb file
786 -hdc file
789 -hdd file
792 Use file as hard disk 0, 1, 2 or 3 image (see disk_005fimages).
793 -cdrom file
795 Use file as CD-ROM image (you cannot use -hdc and -cdrom at the
796 same time). You can use the host CD-ROM by using /dev/cdrom as
797 filename.
798 -blockdev option[,option[,option[,...]]]
800 Define a new block driver node. Some of the options apply to all
801 block drivers, other options are only accepted for a specific
802 block driver. See below for a list of generic options and
803 options for the most common block drivers.
804 Options that expect a reference to another node (e.g. file) can
806 be given in two ways. Either you specify the node name of an
807 already existing node (file=node-name), or you define a new node
808 inline, adding options for the referenced node after a dot
809 (file.filename=path,file.aio=native).
810 A block driver node created with -blockdev can be used for a
812 guest device by specifying its node name for the drive property
813 in a -device argument that defines a block device.
814 Valid options for any block driver node:
816 driver Specifies the block driver to use for the given
818 node.
819 node-name
821 This defines the name of the block driver node by
822 which it will be referenced later. The name must
823 be unique, i.e. it must not match the name of a
824 different block driver node, or (if you use -drive
825 as well) the ID of a drive.
826 If no node name is specified, it is automatically
828 generated. The generated node name is not
829 intended to be predictable and changes between
830 QEMU invocations. For the top level, an explicit
831 node name must be specified.
832 read-only
834 Open the node read-only. Guest write attempts will
835 fail.
836 Note that some block drivers support only
838 read-only access, either generally or in certain
839 configurations. In this case, the default value
840 read-only=off does not work and the option must be
841 specified explicitly.
842 auto-read-only
844 If auto-read-only=on is set, QEMU may fall back to
845 read-only usage even when read-only=off is
846 requested, or even switch between modes as needed,
847 e.g. depending on whether the image file is
848 writable or whether a writing user is attached to
849 the node.
850 force-share
852 Override the image locking system of QEMU by forc‐
853 ing the node to utilize weaker shared access for
854 permissions where it would normally request exclu‐
855 sive access. When there is the potential for mul‐
856 tiple instances to have the same file open
857 (whether this invocation of QEMU is the first or
858 the second instance), both instances must permit
859 shared access for the second instance to succeed
860 at opening the file.
861 Enabling force-share=on requires read-only=on.
863 cache.direct
865 The host page cache can be avoided with
866 cache.direct=on. This will attempt to do disk IO
867 directly to the guest's memory. QEMU may still
868 perform an internal copy of the data.
869 cache.no-flush
871 In case you don't care about data integrity over
872 host failures, you can use cache.no-flush=on. This
873 option tells QEMU that it never needs to write any
874 data to the disk but can instead keep things in
875 cache. If anything goes wrong, like your host los‐
876 ing power, the disk storage getting disconnected
877 accidentally, etc. your image will most probably
878 be rendered unusable.
879 discard=discard
881 discard is one of "ignore" (or "off") or "unmap"
882 (or "on") and controls whether discard (also known
883 as trim or unmap) requests are ignored or passed
884 to the filesystem. Some machine types may not
885 support discard requests.
886 detect-zeroes=detect-zeroes
888 detect-zeroes is "off", "on" or "unmap" and
889 enables the automatic conversion of plain zero
890 writes by the OS to driver specific optimized zero
891 write commands. You may even choose "unmap" if
892 discard is set to "unmap" to allow a zero write to
893 be converted to an unmap operation.
894 Driver-specific options for file
896 This is the protocol-level block driver for accessing
897 regular files.
898 filename
900 The path to the image file in the local filesystem
901 aio Specifies the AIO backend (threads/native,
903 default: threads)
904 locking
906 Specifies whether the image file is protected with
907 Linux OFD / POSIX locks. The default is to use the
908 Linux Open File Descriptor API if available, oth‐
909 erwise no lock is applied. (auto/on/off, default:
910 auto)
911 Example:
913 -blockdev driver=file,node-name=disk,filename=disk.img
915 Driver-specific options for raw
917 This is the image format block driver for raw images. It
918 is usually stacked on top of a protocol level block
919 driver such as file.
920 file Reference to or definition of the data source
922 block driver node (e.g. a file driver node)
923 Example 1:
925 -blockdev driver=file,node-name=disk_file,filename=disk.img
927 -blockdev driver=raw,node-name=disk,file=disk_file
928 Example 2:
930 -blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img
932 Driver-specific options for qcow2
934 This is the image format block driver for qcow2 images.
935 It is usually stacked on top of a protocol level block
936 driver such as file.
937 file Reference to or definition of the data source
939 block driver node (e.g. a file driver node)
940 backing
942 Reference to or definition of the backing file
943 block device (default is taken from the image
944 file). It is allowed to pass null here in order to
945 disable the default backing file.
946 lazy-refcounts
948 Whether to enable the lazy refcounts feature
949 (on/off; default is taken from the image file)
950 cache-size
952 The maximum total size of the L2 table and ref‐
953 count block caches in bytes (default: the sum of
954 l2-cache-size and refcount-cache-size)
955 l2-cache-size
957 The maximum size of the L2 table cache in bytes
958 (default: if cache-size is not specified - 32M on
959 Linux platforms, and 8M on non-Linux platforms;
960 otherwise, as large as possible within the
961 cache-size, while permitting the requested or the
962 minimal refcount cache size)
963 refcount-cache-size
965 The maximum size of the refcount block cache in
966 bytes (default: 4 times the cluster size; or if
967 cache-size is specified, the part of it which is
968 not used for the L2 cache)
969 cache-clean-interval
971 Clean unused entries in the L2 and refcount
972 caches. The interval is in seconds. The default
973 value is 600 on supporting platforms, and 0 on
974 other platforms. Setting it to 0 disables this
975 feature.
976 pass-discard-request
978 Whether discard requests to the qcow2 device
979 should be forwarded to the data source (on/off;
980 default: on if discard=unmap is specified, off
981 otherwise)
982 pass-discard-snapshot
984 Whether discard requests for the data source
985 should be issued when a snapshot operation (e.g.
986 deleting a snapshot) frees clusters in the qcow2
987 file (on/off; default: on)
988 pass-discard-other
990 Whether discard requests for the data source
991 should be issued on other occasions where a clus‐
992 ter gets freed (on/off; default: off)
993 overlap-check
995 Which overlap checks to perform for writes to the
996 image (none/constant/cached/all; default: cached).
997 For details or finer granularity control refer to
998 the QAPI documentation of blockdev-add.
999 Example 1:
1001 -blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2
1003 -blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216
1004 Example 2:
1006 -blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2
1008 Driver-specific options for other drivers
1010 Please refer to the QAPI documentation of the block‐
1011 dev-add QMP command.
1012 -drive option[,option[,option[,...]]]
1014 Define a new drive. This includes creating a block driver node
1015 (the backend) as well as a guest device, and is mostly a short‐
1016 cut for defining the corresponding -blockdev and -device
1017 options.
1018 -drive accepts all options that are accepted by -blockdev. In
1020 addition, it knows the following options:
1021 file=file
1023 This option defines which disk image (see disk_005fim‐
1024 ages) to use with this drive. If the filename contains
1025 comma, you must double it (for instance, "file=my,,file"
1026 to use file "my,file").
1027 Special files such as iSCSI devices can be specified
1029 using protocol specific URLs. See the section for "Device
1030 URL Syntax" for more information.
1031 if=interface
1033 This option defines on which type on interface the drive
1034 is connected. Available types are: ide, scsi, sd, mtd,
1035 floppy, pflash, virtio, none.
1036 bus=bus,unit=unit
1038 These options define where is connected the drive by
1039 defining the bus number and the unit id.
1040 index=index
1042 This option defines where is connected the drive by using
1043 an index in the list of available connectors of a given
1044 interface type.
1045 media=media
1047 This option defines the type of the media: disk or cdrom.
1048 snapshot=snapshot
1050 snapshot is "on" or "off" and controls snapshot mode for
1051 the given drive (see -snapshot).
1052 cache=cache
1054 cache is "none", "writeback", "unsafe", "directsync" or
1055 "writethrough" and controls how the host cache is used to
1056 access block data. This is a shortcut that sets the
1057 cache.direct and cache.no-flush options (as in -block‐
1058 dev), and additionally cache.writeback, which provides a
1059 default for the write-cache option of block guest devices
1060 (as in -device). The modes correspond to the following
1061 settings:
1062 ┌─────────────┬─────────────────┬──────────────┬────────────────┐
1066 │ │ cache.writeback │ cache.direct │ cache.no-flush │
1067 ├─────────────┼─────────────────┼──────────────┼────────────────┤
1068 │writeback │ on │ off │ off │
1069 ├─────────────┼─────────────────┼──────────────┼────────────────┤
1070 │none │ on │ on │ off │
1071 ├─────────────┼─────────────────┼──────────────┼────────────────┤
1072 │writethrough │ off │ off │ off │
1073 ├─────────────┼─────────────────┼──────────────┼────────────────┤
1074 │directsync │ off │ on │ off │
1075 ├─────────────┼─────────────────┼──────────────┼────────────────┤
1076 │unsafe │ on │ off │ on │
1077 └─────────────┴─────────────────┴──────────────┴────────────────┘
1078 The default mode is cache=writeback.
1080 aio=aio
1082 aio is "threads", or "native" and selects between pthread
1083 based disk I/O and native Linux AIO.
1084 format=format
1086 Specify which disk format will be used rather than
1087 detecting the format. Can be used to specify format=raw
1088 to avoid interpreting an untrusted format header.
1089 werror=action,rerror=action
1091 Specify which action to take on write and read errors.
1092 Valid actions are: "ignore" (ignore the error and try to
1093 continue), "stop" (pause QEMU), "report" (report the
1094 error to the guest), "enospc" (pause QEMU only if the
1095 host disk is full; report the error to the guest other‐
1096 wise). The default setting is werror=enospc and
1097 rerror=report.
1098 copy-on-read=copy-on-read
1100 copy-on-read is "on" or "off" and enables whether to copy
1101 read backing file sectors into the image file.
1102 bps=b,bps_rd=r,bps_wr=w
1104 Specify bandwidth throttling limits in bytes per second,
1105 either for all request types or for reads or writes only.
1106 Small values can lead to timeouts or hangs inside the
1107 guest. A safe minimum for disks is 2 MB/s.
1108 bps_max=bm,bps_rd_max=rm,bps_wr_max=wm
1110 Specify bursts in bytes per second, either for all
1111 request types or for reads or writes only. Bursts allow
1112 the guest I/O to spike above the limit temporarily.
1113 iops=i,iops_rd=r,iops_wr=w
1115 Specify request rate limits in requests per second,
1116 either for all request types or for reads or writes only.
1117 iops_max=bm,iops_rd_max=rm,iops_wr_max=wm
1119 Specify bursts in requests per second, either for all
1120 request types or for reads or writes only. Bursts allow
1121 the guest I/O to spike above the limit temporarily.
1122 iops_size=is
1124 Let every is bytes of a request count as a new request
1125 for iops throttling purposes. Use this option to prevent
1126 guests from circumventing iops limits by sending fewer
1127 but larger requests.
1128 group=g
1130 Join a throttling quota group with given name g. All
1131 drives that are members of the same group are accounted
1132 for together. Use this option to prevent guests from cir‐
1133 cumventing throttling limits by using many small disks
1134 instead of a single larger disk.
1135 By default, the cache.writeback=on mode is used. It will report
1137 data writes as completed as soon as the data is present in the
1138 host page cache. This is safe as long as your guest OS makes
1139 sure to correctly flush disk caches where needed. If your guest
1140 OS does not handle volatile disk write caches correctly and your
1141 host crashes or loses power, then the guest may experience data
1142 corruption.
1143 For such guests, you should consider using cache.writeback=off.
1145 This means that the host page cache will be used to read and
1146 write data, but write notification will be sent to the guest
1147 only after QEMU has made sure to flush each write to the disk.
1148 Be aware that this has a major impact on performance.
1149 When using the -snapshot option, unsafe caching is always used.
1151 Copy-on-read avoids accessing the same backing file sectors
1153 repeatedly and is useful when the backing file is over a slow
1154 network. By default copy-on-read is off.
1155 Instead of -cdrom you can use:
1157 qemu-system-x86_64 -drive file=file,index=2,media=cdrom
1159 Instead of -hda, -hdb, -hdc, -hdd, you can use:
1161 qemu-system-x86_64 -drive file=file,index=0,media=disk
1163 qemu-system-x86_64 -drive file=file,index=1,media=disk
1164 qemu-system-x86_64 -drive file=file,index=2,media=disk
1165 qemu-system-x86_64 -drive file=file,index=3,media=disk
1166 You can open an image using pre-opened file descriptors from an
1168 fd set:
1169 qemu-system-x86_64 -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" -drive file=/dev/fdset/2,index=0,media=disk
1171 You can connect a CDROM to the slave of ide0:
1173 qemu_system-x86_64 -drive file=file,if=ide,index=1,media=cdrom
1175 If you don't specify the "file=" argument, you define an empty
1177 drive:
1178 qemu_system-x86_64 -drive if=ide,index=1,media=cdrom
1180 Instead of -fda, -fdb, you can use:
1182 qemu_system-x86_64 -drive file=file,index=0,if=floppy
1184 qemu_system-x86_64 -drive file=file,index=1,if=floppy
1185 By default, interface is "ide" and index is automatically incre‐
1187 mented:
1188 qemu_system-x86_64 -drive file=a -drive file=b"
1190 is interpreted like:
1192 qemu_system-x86_64 -hda a -hdb b
1194 -mtdblock file
1196 Use file as on-board Flash memory image.
1197 -sd file
1199 Use file as SecureDigital card image.
1200 -pflash file
1202 Use file as a parallel flash image.
1203 -snapshot
1205 Write to temporary files instead of disk image files. In this
1206 case, the raw disk image you use is not written back. You can
1207 however force the write back by pressing C-a s (see disk_005fim‐
1208 ages).
1209 -fsdev local,id=id,path=path,security_model=security_model [,write‐
1211 out=writeout][,readonly][,fmode=fmode][,dmode=dmode] [,throt‐
1212 tling.option=value[,throttling.option=value[,...]]]
1213 -fsdev proxy,id=id,socket=socket[,writeout=writeout][,readonly]
1216 -fsdev proxy,id=id,sock_fd=sock_fd[,writeout=writeout][,readonly]
1219 -fsdev synth,id=id[,readonly]
1222 Define a new file system device. Valid options are:
1223 local Accesses to the filesystem are done by QEMU.
1225 proxy Accesses to the filesystem are done by
1227 virtfs-proxy-helper(1).
1228 synth Synthetic filesystem, only used by QTests.
1230 id=id Specifies identifier for this device.
1232 path=path
1234 Specifies the export path for the file system device.
1235 Files under this path will be available to the 9p client
1236 on the guest.
1237 security_model=security_model
1239 Specifies the security model to be used for this export
1240 path. Supported security models are "passthrough",
1241 "mapped-xattr", "mapped-file" and "none". In
1242 "passthrough" security model, files are stored using the
1243 same credentials as they are created on the guest. This
1244 requires QEMU to run as root. In "mapped-xattr" security
1245 model, some of the file attributes like uid, gid, mode
1246 bits and link target are stored as file attributes. For
1247 "mapped-file" these attributes are stored in the hidden
1248 .virtfs_metadata directory. Directories exported by this
1249 security model cannot interact with other unix tools.
1250 "none" security model is same as passthrough except the
1251 sever won't report failures if it fails to set file
1252 attributes like ownership. Security model is mandatory
1253 only for local fsdriver. Other fsdrivers (like proxy)
1254 don't take security model as a parameter.
1255 writeout=writeout
1257 This is an optional argument. The only supported value is
1258 "immediate". This means that host page cache will be used
1259 to read and write data but write notification will be
1260 sent to the guest only when the data has been reported as
1261 written by the storage subsystem.
1262 readonly
1264 Enables exporting 9p share as a readonly mount for
1265 guests. By default read-write access is given.
1266 socket=socket
1268 Enables proxy filesystem driver to use passed socket file
1269 for communicating with virtfs-proxy-helper(1).
1270 sock_fd=sock_fd
1272 Enables proxy filesystem driver to use passed socket
1273 descriptor for communicating with virtfs-proxy-helper(1).
1274 Usually a helper like libvirt will create socketpair and
1275 pass one of the fds as sock_fd.
1276 fmode=fmode
1278 Specifies the default mode for newly created files on the
1279 host. Works only with security models "mapped-xattr" and
1280 "mapped-file".
1281 dmode=dmode
1283 Specifies the default mode for newly created directories
1284 on the host. Works only with security models
1285 "mapped-xattr" and "mapped-file".
1286 throttling.bps-total=b,throttling.bps-read=r,throt‐
1288 tling.bps-write=w
1289 Specify bandwidth throttling limits in bytes per second,
1290 either for all request types or for reads or writes only.
1291 throttling.bps-total-max=bm,bps-read-max=rm,bps-write-max=wm
1293 Specify bursts in bytes per second, either for all
1294 request types or for reads or writes only. Bursts allow
1295 the guest I/O to spike above the limit temporarily.
1296 throttling.iops-total=i,throttling.iops-read=r, throt‐
1298 tling.iops-write=w
1299 Specify request rate limits in requests per second,
1300 either for all request types or for reads or writes only.
1301 throttling.iops-total-max=im,throttling.iops-read-max=irm,
1303 throttling.iops-write-max=iwm
1304 Specify bursts in requests per second, either for all
1305 request types or for reads or writes only. Bursts allow
1306 the guest I/O to spike above the limit temporarily.
1307 throttling.iops-size=is
1309 Let every is bytes of a request count as a new request
1310 for iops throttling purposes.
1311 -fsdev option is used along with -device driver "virtio-9p-...".
1313 -device virtio-9p-type,fsdev=id,mount_tag=mount_tag
1315 Options for virtio-9p-... driver are:
1316 type Specifies the variant to be used. Supported values are
1318 "pci", "ccw" or "device", depending on the machine type.
1319 fsdev=id
1321 Specifies the id value specified along with -fsdev
1322 option.
1323 mount_tag=mount_tag
1325 Specifies the tag name to be used by the guest to mount
1326 this export point.
1327 -virtfs local,path=path,mount_tag=mount_tag ,security_model=secu‐
1329 rity_model[,writeout=writeout][,readonly]
1330 [,fmode=fmode][,dmode=dmode][,multidevs=multidevs]
1331 -virtfs proxy,socket=socket,mount_tag=mount_tag [,writeout=write‐
1334 out][,readonly]
1335 -virtfs proxy,sock_fd=sock_fd,mount_tag=mount_tag [,writeout=write‐
1338 out][,readonly]
1339 -virtfs synth,mount_tag=mount_tag
1342 Define a new virtual filesystem device and expose it to the
1343 guest using a virtio-9p-device (a.k.a. 9pfs), which essentially
1344 means that a certain directory on host is made directly accessi‐
1345 ble by guest as a pass-through file system by using the 9P net‐
1346 work protocol for communication between host and guests, if
1347 desired even accessible, shared by several guests simultan‐
1348 iously.
1349 Note that -virtfs is actually just a convenience shortcut for
1351 its generalized form -fsdev -device virtio-9p-pci.
1352 The general form of pass-through file system options are:
1354 local Accesses to the filesystem are done by QEMU.
1356 proxy Accesses to the filesystem are done by
1358 virtfs-proxy-helper(1).
1359 synth Synthetic filesystem, only used by QTests.
1361 id=id Specifies identifier for the filesystem device
1363 path=path
1365 Specifies the export path for the file system device.
1366 Files under this path will be available to the 9p client
1367 on the guest.
1368 security_model=security_model
1370 Specifies the security model to be used for this export
1371 path. Supported security models are "passthrough",
1372 "mapped-xattr", "mapped-file" and "none". In
1373 "passthrough" security model, files are stored using the
1374 same credentials as they are created on the guest. This
1375 requires QEMU to run as root. In "mapped-xattr" security
1376 model, some of the file attributes like uid, gid, mode
1377 bits and link target are stored as file attributes. For
1378 "mapped-file" these attributes are stored in the hidden
1379 .virtfs_metadata directory. Directories exported by this
1380 security model cannot interact with other unix tools.
1381 "none" security model is same as passthrough except the
1382 sever won't report failures if it fails to set file
1383 attributes like ownership. Security model is mandatory
1384 only for local fsdriver. Other fsdrivers (like proxy)
1385 don't take security model as a parameter.
1386 writeout=writeout
1388 This is an optional argument. The only supported value is
1389 "immediate". This means that host page cache will be used
1390 to read and write data but write notification will be
1391 sent to the guest only when the data has been reported as
1392 written by the storage subsystem.
1393 readonly
1395 Enables exporting 9p share as a readonly mount for
1396 guests. By default read-write access is given.
1397 socket=socket
1399 Enables proxy filesystem driver to use passed socket file
1400 for communicating with virtfs-proxy-helper(1). Usually a
1401 helper like libvirt will create socketpair and pass one
1402 of the fds as sock_fd.
1403 sock_fd
1405 Enables proxy filesystem driver to use passed 'sock_fd'
1406 as the socket descriptor for interfacing with
1407 virtfs-proxy-helper(1).
1408 fmode=fmode
1410 Specifies the default mode for newly created files on the
1411 host. Works only with security models "mapped-xattr" and
1412 "mapped-file".
1413 dmode=dmode
1415 Specifies the default mode for newly created directories
1416 on the host. Works only with security models
1417 "mapped-xattr" and "mapped-file".
1418 mount_tag=mount_tag
1420 Specifies the tag name to be used by the guest to mount
1421 this export point.
1422 multidevs=multidevs
1424 Specifies how to deal with multiple devices being shared
1425 with a 9p export. Supported behaviours are either
1426 "remap", "forbid" or "warn". The latter is the default
1427 behaviour on which virtfs 9p expects only one device to
1428 be shared with the same export, and if more than one
1429 device is shared and accessed via the same 9p export then
1430 only a warning message is logged (once) by qemu on host
1431 side. In order to avoid file ID collisions on guest you
1432 should either create a separate virtfs export for each
1433 device to be shared with guests (recommended way) or you
1434 might use "remap" instead which allows you to share mul‐
1435 tiple devices with only one export instead, which is
1436 achieved by remapping the original inode numbers from
1437 host to guest in a way that would prevent such colli‐
1438 sions. Remapping inodes in such use cases is required
1439 because the original device IDs from host are never
1440 passed and exposed on guest. Instead all files of an
1441 export shared with virtfs always share the same device id
1442 on guest. So two files with identical inode numbers but
1443 from actually different devices on host would otherwise
1444 cause a file ID collision and hence potential misbe‐
1445 haviours on guest. "forbid" on the other hand assumes
1446 like "warn" that only one device is shared by the same
1447 export, however it will not only log a warning message
1448 but also deny access to additional devices on guest. Note
1449 though that "forbid" does currently not block all possi‐
1450 ble file access operations (e.g. readdir() would still
1451 return entries from other devices).
1452 -iscsi Configure iSCSI session parameters.
1454 USB options
1456 -usb Enable USB emulation on machine types with an on-board USB host
1457 controller (if not enabled by default). Note that on-board USB
1458 host controllers may not support USB 3.0. In this case -device
1459 qemu-xhci can be used instead on machines with PCI.
1460 -usbdevice devname
1462 Add the USB device devname. Note that this option is deprecated,
1463 please use -device usb-... instead. See usb_005fdevices.
1464 mouse Virtual Mouse. This will override the PS/2 mouse emula‐
1466 tion when activated.
1467 tablet Pointer device that uses absolute coordinates (like a
1469 touchscreen). This means QEMU is able to report the mouse
1470 position without having to grab the mouse. Also overrides
1471 the PS/2 mouse emulation when activated.
1472 braille
1474 Braille device. This will use BrlAPI to display the
1475 braille output on a real or fake device.
1476 Display options
1478 -display type
1479 Select type of display to use. This option is a replacement for
1480 the old style -sdl/-curses/... options. Use -display help to
1481 list the available display types. Valid values for type are
1482 sdl Display video output via SDL (usually in a separate
1484 graphics window; see the SDL documentation for other pos‐
1485 sibilities).
1486 curses Display video output via curses. For graphics device mod‐
1488 els which support a text mode, QEMU can display this out‐
1489 put using a curses/ncurses interface. Nothing is dis‐
1490 played when the graphics device is in graphical mode or
1491 if the graphics device does not support a text mode. Gen‐
1492 erally only the VGA device models support text mode. The
1493 font charset used by the guest can be specified with the
1494 charset option, for example charset=CP850 for IBM CP850
1495 encoding. The default is CP437.
1496 none Do not display video output. The guest will still see an
1498 emulated graphics card, but its output will not be dis‐
1499 played to the QEMU user. This option differs from the
1500 -nographic option in that it only affects what is done
1501 with video output; -nographic also changes the destina‐
1502 tion of the serial and parallel port data.
1503 gtk Display video output in a GTK window. This interface pro‐
1505 vides drop-down menus and other UI elements to configure
1506 and control the VM during runtime.
1507 vnc Start a VNC server on display <arg>
1509 egl-headless
1511 Offload all OpenGL operations to a local DRI device. For
1512 any graphical display, this display needs to be paired
1513 with either VNC or SPICE displays.
1514 spice-app
1516 Start QEMU as a Spice server and launch the default Spice
1517 client application. The Spice server will redirect the
1518 serial consoles and QEMU monitors. (Since 4.0)
1519 -nographic
1521 Normally, if QEMU is compiled with graphical window support, it
1522 displays output such as guest graphics, guest console, and the
1523 QEMU monitor in a window. With this option, you can totally dis‐
1524 able graphical output so that QEMU is a simple command line
1525 application. The emulated serial port is redirected on the con‐
1526 sole and muxed with the monitor (unless redirected elsewhere
1527 explicitly). Therefore, you can still use QEMU to debug a Linux
1528 kernel with a serial console. Use C-a h for help on switching
1529 between the console and monitor.
1530 -curses
1532 Normally, if QEMU is compiled with graphical window support, it
1533 displays output such as guest graphics, guest console, and the
1534 QEMU monitor in a window. With this option, QEMU can display the
1535 VGA output when in text mode using a curses/ncurses interface.
1536 Nothing is displayed in graphical mode.
1537 -alt-grab
1539 Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note
1540 that this also affects the special keys (for fullscreen, moni‐
1541 tor-mode switching, etc).
1542 -ctrl-grab
1544 Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that
1545 this also affects the special keys (for fullscreen, monitor-mode
1546 switching, etc).
1547 -no-quit
1549 Disable SDL window close capability.
1550 -sdl Enable SDL.
1552 -spice option[,option[,...]]
1554 Enable the spice remote desktop protocol. Valid options are
1555 port=<nr>
1557 Set the TCP port spice is listening on for plaintext
1558 channels.
1559 addr=<addr>
1561 Set the IP address spice is listening on. Default is any
1562 address.
1563 ipv4; ipv6; unix
1565 Force using the specified IP version.
1566 password=<secret>
1568 Set the password you need to authenticate.
1569 sasl Require that the client use SASL to authenticate with the
1571 spice. The exact choice of authentication method used is
1572 controlled from the system / user's SASL configuration
1573 file for the 'qemu' service. This is typically found in
1574 /etc/sasl2/qemu.conf. If running QEMU as an unprivileged
1575 user, an environment variable SASL_CONF_PATH can be used
1576 to make it search alternate locations for the service
1577 config. While some SASL auth methods can also provide
1578 data encryption (eg GSSAPI), it is recommended that SASL
1579 always be combined with the 'tls' and 'x509' settings to
1580 enable use of SSL and server certificates. This ensures a
1581 data encryption preventing compromise of authentication
1582 credentials.
1583 disable-ticketing
1585 Allow client connects without authentication.
1586 disable-copy-paste
1588 Disable copy paste between the client and the guest.
1589 disable-agent-file-xfer
1591 Disable spice-vdagent based file-xfer between the client
1592 and the guest.
1593 tls-port=<nr>
1595 Set the TCP port spice is listening on for encrypted
1596 channels.
1597 x509-dir=<dir>
1599 Set the x509 file directory. Expects same filenames as
1600 -vnc $display,x509=$dir
1601 x509-key-file=<file>; x509-key-password=<file>;
1603 x509-cert-file=<file>; x509-cacert-file=<file>;
1604 x509-dh-key-file=<file>
1605 The x509 file names can also be configured individually.
1606 tls-ciphers=<list>
1608 Specify which ciphers to use.
1609 tls-channel=[main|display|cursor|inputs|record|playback]; plain‐
1611 text-channel=[main|display|cursor|inputs|record|playback]
1612 Force specific channel to be used with or without TLS
1613 encryption. The options can be specified multiple times
1614 to configure multiple channels. The special name
1615 "default" can be used to set the default mode. For chan‐
1616 nels which are not explicitly forced into one mode the
1617 spice client is allowed to pick tls/plaintext as he
1618 pleases.
1619 image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
1621 Configure image compression (lossless). Default is
1622 auto_glz.
1623 jpeg-wan-compression=[auto|never|always]; zlib-glz-wan-compres‐
1625 sion=[auto|never|always]
1626 Configure wan image compression (lossy for slow links).
1627 Default is auto.
1628 streaming-video=[off|all|filter]
1630 Configure video stream detection. Default is off.
1631 agent-mouse=[on|off]
1633 Enable/disable passing mouse events via vdagent. Default
1634 is on.
1635 playback-compression=[on|off]
1637 Enable/disable audio stream compression (using celt
1638 0.5.1). Default is on.
1639 seamless-migration=[on|off]
1641 Enable/disable spice seamless migration. Default is off.
1642 gl=[on|off]
1644 Enable/disable OpenGL context. Default is off.
1645 rendernode=<file>
1647 DRM render node for OpenGL rendering. If not specified,
1648 it will pick the first available. (Since 2.9)
1649 -portrait
1651 Rotate graphical output 90 deg left (only PXA LCD).
1652 -rotate deg
1654 Rotate graphical output some deg left (only PXA LCD).
1655 -vga type
1657 Select type of VGA card to emulate. Valid values for type are
1658 cirrus Cirrus Logic GD5446 Video card. All Windows versions
1660 starting from Windows 95 should recognize and use this
1661 graphic card. For optimal performances, use 16 bit color
1662 depth in the guest and the host OS. (This card was the
1663 default before QEMU 2.2)
1664 std Standard VGA card with Bochs VBE extensions. If your
1666 guest OS supports the VESA 2.0 VBE extensions (e.g. Win‐
1667 dows XP) and if you want to use high resolution modes (>=
1668 1280x1024x16) then you should use this option. (This card
1669 is the default since QEMU 2.2)
1670 vmware VMWare SVGA-II compatible adapter. Use it if you have
1672 sufficiently recent XFree86/XOrg server or Windows guest
1673 with a driver for this card.
1674 qxl QXL paravirtual graphic card. It is VGA compatible
1676 (including VESA 2.0 VBE support). Works best with qxl
1677 guest drivers installed though. Recommended choice when
1678 using the spice protocol.
1679 tcx (sun4m only) Sun TCX framebuffer. This is the default
1681 framebuffer for sun4m machines and offers both 8-bit and
1682 24-bit colour depths at a fixed resolution of 1024x768.
1683 cg3 (sun4m only) Sun cgthree framebuffer. This is a simple
1685 8-bit framebuffer for sun4m machines available in both
1686 1024x768 (OpenBIOS) and 1152x900 (OBP) resolutions aimed
1687 at people wishing to run older Solaris versions.
1688 virtio Virtio VGA card.
1690 none Disable VGA card.
1692 -full-screen
1694 Start in full screen.
1695 -g widthxheight[xdepth]
1697 Set the initial graphical resolution and depth (PPC, SPARC
1698 only).
1699 For PPC the default is 800x600x32.
1701 For SPARC with the TCX graphics device, the default is
1703 1024x768x8 with the option of 1024x768x24. For cgthree, the
1704 default is 1024x768x8 with the option of 1152x900x8 for people
1705 who wish to use OBP.
1706 -vnc display[,option[,option[,...]]]
1708 Normally, if QEMU is compiled with graphical window support, it
1709 displays output such as guest graphics, guest console, and the
1710 QEMU monitor in a window. With this option, you can have QEMU
1711 listen on VNC display display and redirect the VGA display over
1712 the VNC session. It is very useful to enable the usb tablet
1713 device when using this option (option -device usb-tablet). When
1714 using the VNC display, you must use the -k parameter to set the
1715 keyboard layout if you are not using en-us. Valid syntax for the
1716 display is
1717 to=L With this option, QEMU will try next available VNC dis‐
1719 plays, until the number L, if the origianlly defined
1720 "-vnc display" is not available, e.g. port 5900+display
1721 is already used by another application. By default, to=0.
1722 host:d TCP connections will only be allowed from host on display
1724 d. By convention the TCP port is 5900+d. Optionally, host
1725 can be omitted in which case the server will accept con‐
1726 nections from any host.
1727 unix:path
1729 Connections will be allowed over UNIX domain sockets
1730 where path is the location of a unix socket to listen for
1731 connections on.
1732 none VNC is initialized but not started. The monitor change
1734 command can be used to later start the VNC server.
1735 Following the display value there may be one or more option
1737 flags separated by commas. Valid options are
1738 reverse
1740 Connect to a listening VNC client via a "reverse" connec‐
1741 tion. The client is specified by the display. For
1742 reverse network connections (host:d,``reverse``), the d
1743 argument is a TCP port number, not a display number.
1744 websocket
1746 Opens an additional TCP listening port dedicated to VNC
1747 Websocket connections. If a bare websocket option is
1748 given, the Websocket port is 5700+display. An alternative
1749 port can be specified with the syntax websocket=port.
1750 If host is specified connections will only be allowed
1752 from this host. It is possible to control the websocket
1753 listen address independently, using the syntax web‐
1754 socket=host:port.
1755 If no TLS credentials are provided, the websocket connec‐
1757 tion runs in unencrypted mode. If TLS credentials are
1758 provided, the websocket connection requires encrypted
1759 client connections.
1760 password
1762 Require that password based authentication is used for
1763 client connections.
1764 The password must be set separately using the set_pass‐
1766 word command in the pcsys_005fmonitor. The syntax to
1767 change your password is: set_password <protocol> <pass‐
1768 word> where <protocol> could be either "vnc" or "spice".
1769 If you would like to change <protocol> password expira‐
1771 tion, you should use expire_password <protocol> <expira‐
1772 tion-time> where expiration time could be one of the fol‐
1773 lowing options: now, never, +seconds or UNIX time of
1774 expiration, e.g. +60 to make password expire in 60 sec‐
1775 onds, or 1335196800 to make password expire on "Mon Apr
1776 23 12:00:00 EDT 2012" (UNIX time for this date and time).
1777 You can also use keywords "now" or "never" for the expi‐
1779 ration time to allow <protocol> password to expire imme‐
1780 diately or never expire.
1781 tls-creds=ID
1783 Provides the ID of a set of TLS credentials to use to
1784 secure the VNC server. They will apply to both the normal
1785 VNC server socket and the websocket socket (if enabled).
1786 Setting TLS credentials will cause the VNC server socket
1787 to enable the VeNCrypt auth mechanism. The credentials
1788 should have been previously created using the -object
1789 tls-creds argument.
1790 tls-authz=ID
1792 Provides the ID of the QAuthZ authorization object
1793 against which the client's x509 distinguished name will
1794 validated. This object is only resolved at time of use,
1795 so can be deleted and recreated on the fly while the VNC
1796 server is active. If missing, it will default to denying
1797 access.
1798 sasl Require that the client use SASL to authenticate with the
1800 VNC server. The exact choice of authentication method
1801 used is controlled from the system / user's SASL configu‐
1802 ration file for the 'qemu' service. This is typically
1803 found in /etc/sasl2/qemu.conf. If running QEMU as an
1804 unprivileged user, an environment variable SASL_CONF_PATH
1805 can be used to make it search alternate locations for the
1806 service config. While some SASL auth methods can also
1807 provide data encryption (eg GSSAPI), it is recommended
1808 that SASL always be combined with the 'tls' and 'x509'
1809 settings to enable use of SSL and server certificates.
1810 This ensures a data encryption preventing compromise of
1811 authentication credentials. See the vnc_005fsecurity sec‐
1812 tion for details on using SASL authentication.
1813 sasl-authz=ID
1815 Provides the ID of the QAuthZ authorization object
1816 against which the client's SASL username will validated.
1817 This object is only resolved at time of use, so can be
1818 deleted and recreated on the fly while the VNC server is
1819 active. If missing, it will default to denying access.
1820 acl Legacy method for enabling authorization of clients
1822 against the x509 distinguished name and SASL username. It
1823 results in the creation of two authz-list objects with
1824 IDs of vnc.username and vnc.x509dname. The rules for
1825 these objects must be configured with the HMP ACL com‐
1826 mands.
1827 This option is deprecated and should no longer be used.
1829 The new sasl-authz and tls-authz options are a replace‐
1830 ment.
1831 lossy Enable lossy compression methods (gradient, JPEG, ...).
1833 If this option is set, VNC client may receive lossy
1834 framebuffer updates depending on its encoding settings.
1835 Enabling this option can save a lot of bandwidth at the
1836 expense of quality.
1837 non-adaptive
1839 Disable adaptive encodings. Adaptive encodings are
1840 enabled by default. An adaptive encoding will try to
1841 detect frequently updated screen regions, and send
1842 updates in these regions using a lossy encoding (like
1843 JPEG). This can be really helpful to save bandwidth when
1844 playing videos. Disabling adaptive encodings restores the
1845 original static behavior of encodings like Tight.
1846 share=[allow-exclusive|force-shared|ignore]
1848 Set display sharing policy. 'allow-exclusive' allows
1849 clients to ask for exclusive access. As suggested by the
1850 rfb spec this is implemented by dropping other connec‐
1851 tions. Connecting multiple clients in parallel requires
1852 all clients asking for a shared session (vncviewer:
1853 -shared switch). This is the default. 'force-shared'
1854 disables exclusive client access. Useful for shared desk‐
1855 top sessions, where you don't want someone forgetting
1856 specify -shared disconnect everybody else. 'ignore' com‐
1857 pletely ignores the shared flag and allows everybody con‐
1858 nect unconditionally. Doesn't conform to the rfb spec but
1859 is traditional QEMU behavior.
1860 key-delay-ms
1862 Set keyboard delay, for key down and key up events, in
1863 milliseconds. Default is 10. Keyboards are low-bandwidth
1864 devices, so this slowdown can help the device and guest
1865 to keep up and not lose events in case events are arriv‐
1866 ing in bulk. Possible causes for the latter are flaky
1867 network connections, or scripts for automated testing.
1868 audiodev=audiodev
1870 Use the specified audiodev when the VNC client requests
1871 audio transmission. When not using an -audiodev argument,
1872 this option must be omitted, otherwise is must be present
1873 and specify a valid audiodev.
1874 i386 target only
1876 -win2k-hack
1877 Use it when installing Windows 2000 to avoid a disk full bug.
1878 After Windows 2000 is installed, you no longer need this option
1879 (this option slows down the IDE transfers).
1880 -no-fd-bootchk
1882 Disable boot signature checking for floppy disks in BIOS. May be
1883 needed to boot from old floppy disks.
1884 -no-acpi
1886 Disable ACPI (Advanced Configuration and Power Interface) sup‐
1887 port. Use it if your guest OS complains about ACPI problems (PC
1888 target machine only).
1889 -no-hpet
1891 Disable HPET support.
1892 -acpitable [sig=str][,rev=n][,oem_id=str][,oem_ta‐
1894 ble_id=str][,oem_rev=n] [,asl_compiler_id=str][,asl_com‐
1895 piler_rev=n][,data=file1[:file2]...]
1896 Add ACPI table with specified header fields and context from
1897 specified files. For file=, take whole ACPI table from the spec‐
1898 ified files, including all ACPI headers (possible overridden by
1899 other options). For data=, only data portion of the table is
1900 used, all header information is specified in the command line.
1901 If a SLIC table is supplied to QEMU, then the SLIC's oem_id and
1902 oem_table_id fields will override the same in the RSDT and the
1903 FADT (a.k.a. FACP), in order to ensure the field matches
1904 required by the Microsoft SLIC spec and the ACPI spec.
1905 -smbios file=binary
1907 Load SMBIOS entry from binary file.
1908 -smbios type=0[,vendor=str][,ver‐
1910 sion=str][,date=str][,release=%d.%d][,uefi=on|off]
1911 Specify SMBIOS type 0 fields
1912 -smbios type=1[,manufacturer=str][,product=str][,ver‐
1914 sion=str][,serial=str][,uuid=uuid][,sku=str][,family=str]
1915 Specify SMBIOS type 1 fields
1916 -smbios type=2[,manufacturer=str][,product=str][,ver‐
1918 sion=str][,serial=str][,asset=str][,location=str]
1919 Specify SMBIOS type 2 fields
1920 -smbios type=3[,manufacturer=str][,ver‐
1922 sion=str][,serial=str][,asset=str][,sku=str]
1923 Specify SMBIOS type 3 fields
1924 -smbios type=4[,sock_pfx=str][,manufacturer=str][,ver‐
1926 sion=str][,serial=str][,asset=str][,part=str]
1927 Specify SMBIOS type 4 fields
1928 -smbios type=17[,loc_pfx=str][,bank=str][,manufac‐
1930 turer=str][,serial=str][,asset=str][,part=str][,speed=%d]
1931 Specify SMBIOS type 17 fields
1932 Network options
1934 -nic
1935 [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn]
1936 This option is a shortcut for configuring both the on-board
1937 (default) guest NIC hardware and the host network backend in one
1938 go. The host backend options are the same as with the corre‐
1939 sponding -netdev options below. The guest NIC model can be set
1940 with model=modelname. Use model=help to list the available
1941 device types. The hardware MAC address can be set with
1942 mac=macaddr.
1943 The following two example do exactly the same, to show how -nic
1945 can be used to shorten the command line length:
1946 qemu-system-x86_64 -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32
1948 qemu-system-x86_64 -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32
1949 -nic none
1951 Indicate that no network devices should be configured. It is
1952 used to override the default configuration (default NIC with
1953 "user" host network backend) which is activated if no other net‐
1954 working options are provided.
1955 -netdev user,id=id[,option][,option][,...]
1957 Configure user mode host network backend which requires no
1958 administrator privilege to run. Valid options are:
1959 id=id Assign symbolic name for use in monitor commands.
1961 ipv4=on|off and ipv6=on|off
1963 Specify that either IPv4 or IPv6 must be enabled. If nei‐
1964 ther is specified both protocols are enabled.
1965 net=addr[/mask]
1967 Set IP network address the guest will see. Optionally
1968 specify the netmask, either in the form a.b.c.d or as
1969 number of valid top-most bits. Default is 10.0.2.0/24.
1970 host=addr
1972 Specify the guest-visible address of the host. Default is
1973 the 2nd IP in the guest network, i.e. x.x.x.2.
1974 ipv6-net=addr[/int]
1976 Set IPv6 network address the guest will see (default is
1977 fec0::/64). The network prefix is given in the usual
1978 hexadecimal IPv6 address notation. The prefix size is
1979 optional, and is given as the number of valid top-most
1980 bits (default is 64).
1981 ipv6-host=addr
1983 Specify the guest-visible IPv6 address of the host.
1984 Default is the 2nd IPv6 in the guest network, i.e.
1985 xxxx::2.
1986 restrict=on|off
1988 If this option is enabled, the guest will be isolated,
1989 i.e. it will not be able to contact the host and no guest
1990 IP packets will be routed over the host to the outside.
1991 This option does not affect any explicitly set forwarding
1992 rules.
1993 hostname=name
1995 Specifies the client hostname reported by the built-in
1996 DHCP server.
1997 dhcpstart=addr
1999 Specify the first of the 16 IPs the built-in DHCP server
2000 can assign. Default is the 15th to 31st IP in the guest
2001 network, i.e. x.x.x.15 to x.x.x.31.
2002 dns=addr
2004 Specify the guest-visible address of the virtual name‐
2005 server. The address must be different from the host
2006 address. Default is the 3rd IP in the guest network, i.e.
2007 x.x.x.3.
2008 ipv6-dns=addr
2010 Specify the guest-visible address of the IPv6 virtual
2011 nameserver. The address must be different from the host
2012 address. Default is the 3rd IP in the guest network,
2013 i.e. xxxx::3.
2014 dnssearch=domain
2016 Provides an entry for the domain-search list sent by the
2017 built-in DHCP server. More than one domain suffix can be
2018 transmitted by specifying this option multiple times. If
2019 supported, this will cause the guest to automatically try
2020 to append the given domain suffix(es) in case a domain
2021 name can not be resolved.
2022 Example:
2024 qemu-system-x86_64 -nic user,dnssearch=mgmt.example.org,dnssearch=example.org
2026 domainname=domain
2028 Specifies the client domain name reported by the built-in
2029 DHCP server.
2030 tftp=dir
2032 When using the user mode network stack, activate a
2033 built-in TFTP server. The files in dir will be exposed as
2034 the root of a TFTP server. The TFTP client on the guest
2035 must be configured in binary mode (use the command bin of
2036 the Unix TFTP client).
2037 tftp-server-name=name
2039 In BOOTP reply, broadcast name as the "TFTP server name"
2040 (RFC2132 option 66). This can be used to advise the guest
2041 to load boot files or configurations from a different
2042 server than the host address.
2043 bootfile=file
2045 When using the user mode network stack, broadcast file as
2046 the BOOTP filename. In conjunction with tftp, this can be
2047 used to network boot a guest from a local directory.
2048 Example (using pxelinux):
2050 qemu-system-x86_64 -hda linux.img -boot n -device e1000,netdev=n1 -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
2052 smb=dir[,smbserver=addr]
2054 When using the user mode network stack, activate a
2055 built-in SMB server so that Windows OSes can access to
2056 the host files in dir transparently. The IP address of
2057 the SMB server can be set to addr. By default the 4th IP
2058 in the guest network is used, i.e. x.x.x.4.
2059 In the guest Windows OS, the line:
2061 10.0.2.4 smbserver
2063 must be added in the file C:\WINDOWS\LMHOSTS (for windows
2065 9x/Me) or C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS (Windows
2066 NT/2000).
2067 Then dir can be accessed in \\smbserver\qemu.
2069 Note that a SAMBA server must be installed on the host
2071 OS.
2072 hostfwd=[tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport
2074 Redirect incoming TCP or UDP connections to the host port
2075 hostport to the guest IP address guestaddr on guest port
2076 guestport. If guestaddr is not specified, its value is
2077 x.x.x.15 (default first address given by the built-in
2078 DHCP server). By specifying hostaddr, the rule can be
2079 bound to a specific host interface. If no connection type
2080 is set, TCP is used. This option can be given multiple
2081 times.
2082 For example, to redirect host X11 connection from screen
2084 1 to guest screen 0, use the following:
2085 # on the host
2087 qemu-system-x86_64 -nic user,hostfwd=tcp:127.0.0.1:6001-:6000
2088 # this host xterm should open in the guest X11 server
2089 xterm -display :1
2090 To redirect telnet connections from host port 5555 to
2092 telnet port on the guest, use the following:
2093 # on the host
2095 qemu-system-x86_64 -nic user,hostfwd=tcp::5555-:23
2096 telnet localhost 5555
2097 Then when you use on the host telnet localhost 5555, you
2099 connect to the guest telnet server.
2100 guestfwd=[tcp]:server:port-dev; guest‐
2102 fwd=[tcp]:server:port-cmd:command
2103 Forward guest TCP connections to the IP address server on
2104 port port to the character device dev or to a program
2105 executed by cmd:command which gets spawned for each con‐
2106 nection. This option can be given multiple times.
2107 You can either use a chardev directly and have that one
2109 used throughout QEMU's lifetime, like in the following
2110 example:
2111 # open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
2113 # the guest accesses it
2114 qemu-system-x86_64 -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321
2115 Or you can execute a command on every TCP connection
2117 established by the guest, so that QEMU behaves similar to
2118 an inetd process for that virtual server:
2119 # call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
2121 # and connect the TCP stream to its stdin/stdout
2122 qemu-system-x86_64 -nic 'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
2123 -netdev tap,id=id[,fd=h][,ifname=name][,script=file][,down‐
2125 script=dfile][,br=bridge][,helper=helper]
2126 Configure a host TAP network backend with ID id.
2127 Use the network script file to configure it and the network
2129 script dfile to deconfigure it. If name is not provided, the OS
2130 automatically provides one. The default network configure script
2131 is /etc/qemu-ifup and the default network deconfigure script is
2132 /etc/qemu-ifdown. Use script=no or downscript=no to disable
2133 script execution.
2134 If running QEMU as an unprivileged user, use the network helper
2136 helper to configure the TAP interface and attach it to the
2137 bridge. The default network helper executable is
2138 /path/to/qemu-bridge-helper and the default bridge device is
2139 br0.
2140 fd=h can be used to specify the handle of an already opened host
2142 TAP interface.
2143 Examples:
2145 #launch a QEMU instance with the default network script
2147 qemu-system-x86_64 linux.img -nic tap
2148 #launch a QEMU instance with two NICs, each one connected
2150 #to a TAP device
2151 qemu-system-x86_64 linux.img -netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 -netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1
2152 #launch a QEMU instance with the default network helper to
2154 #connect a TAP device to bridge br0
2155 qemu-system-x86_64 linux.img -device virtio-net-pci,netdev=n1 -netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper"
2156 -netdev bridge,id=id[,br=bridge][,helper=helper]
2158 Connect a host TAP network interface to a host bridge device.
2159 Use the network helper helper to configure the TAP interface and
2161 attach it to the bridge. The default network helper executable
2162 is /path/to/qemu-bridge-helper and the default bridge device is
2163 br0.
2164 Examples:
2166 #launch a QEMU instance with the default network helper to
2168 #connect a TAP device to bridge br0
2169 qemu-system-x86_64 linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1
2170 #launch a QEMU instance with the default network helper to
2172 #connect a TAP device to bridge qemubr0
2173 qemu-system-x86_64 linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1
2174 -netdev socket,id=id[,fd=h][,listen=[host]:port][,connect=host:port]
2176 This host network backend can be used to connect the guest's
2177 network to another QEMU virtual machine using a TCP socket con‐
2178 nection. If listen is specified, QEMU waits for incoming connec‐
2179 tions on port (host is optional). connect is used to connect to
2180 another QEMU instance using the listen option. fd=h specifies an
2181 already opened TCP socket.
2182 Example:
2184 # launch a first QEMU instance
2186 qemu-system-x86_64 linux.img -device e1000,netdev=n1,mac=52:54:00:12:34:56 -netdev socket,id=n1,listen=:1234
2187 # connect the network of this instance to the network of the first instance
2188 qemu-system-x86_64 linux.img -device e1000,netdev=n2,mac=52:54:00:12:34:57 -netdev socket,id=n2,connect=127.0.0.1:1234
2189 -netdev socket,id=id[,fd=h][,mcast=maddr:port[,localaddr=addr]]
2191 Configure a socket host network backend to share the guest's
2192 network traffic with another QEMU virtual machines using a UDP
2193 multicast socket, effectively making a bus for every QEMU with
2194 same multicast address maddr and port. NOTES:
2195 1. Several QEMU can be running on different hosts and share same
2197 bus (assuming correct multicast setup for these hosts).
2198 2. mcast support is compatible with User Mode Linux (argument
2200 ethN=mcast), see http://user-mode-linux.sf.net.
2201 3. Use fd=h to specify an already opened UDP multicast socket.
2203 Example:
2205 # launch one QEMU instance
2207 qemu-system-x86_64 linux.img -device e1000,netdev=n1,mac=52:54:00:12:34:56 -netdev socket,id=n1,mcast=230.0.0.1:1234
2208 # launch another QEMU instance on same "bus"
2209 qemu-system-x86_64 linux.img -device e1000,netdev=n2,mac=52:54:00:12:34:57 -netdev socket,id=n2,mcast=230.0.0.1:1234
2210 # launch yet another QEMU instance on same "bus"
2211 qemu-system-x86_64 linux.img -device e1000,netdev=n3,mac=52:54:00:12:34:58 -netdev socket,id=n3,mcast=230.0.0.1:1234
2212 Example (User Mode Linux compat.):
2214 # launch QEMU instance (note mcast address selected is UML's default)
2216 qemu-system-x86_64 linux.img -device e1000,netdev=n1,mac=52:54:00:12:34:56 -netdev socket,id=n1,mcast=239.192.168.1:1102
2217 # launch UML
2218 /path/to/linux ubd0=/path/to/root_fs eth0=mcast
2219 Example (send packets from host's 1.2.3.4):
2221 qemu-system-x86_64 linux.img -device e1000,netdev=n1,mac=52:54:00:12:34:56 -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4
2223 -netdev l2tpv3,id=id,src=srcaddr,dst=dstaddr[,srcport=srcport][,dst‐
2225 port=dstport],txsession=txsession[,rxsession=rxses‐
2226 sion][,ipv6][,udp][,cookie64][,counter][,pin‐
2227 counter][,txcookie=txcookie][,rxcookie=rxcookie][,offset=offset]
2228 Configure a L2TPv3 pseudowire host network backend. L2TPv3
2229 (RFC3931) is a popular protocol to transport Ethernet (and other
2230 Layer 2) data frames between two systems. It is present in
2231 routers, firewalls and the Linux kernel (from version 3.3
2232 onwards).
2233 This transport allows a VM to communicate to another VM, router
2235 or firewall directly.
2236 src=srcaddr
2238 source address (mandatory)
2239 dst=dstaddr
2241 destination address (mandatory)
2242 udp select udp encapsulation (default is ip).
2244 srcport=srcport
2246 source udp port.
2247 dstport=dstport
2249 destination udp port.
2250 ipv6 force v6, otherwise defaults to v4.
2252 rxcookie=rxcookie; txcookie=txcookie
2254 Cookies are a weak form of security in the l2tpv3 speci‐
2255 fication. Their function is mostly to prevent misconfig‐
2256 uration. By default they are 32 bit.
2257 cookie64
2259 Set cookie size to 64 bit instead of the default 32
2260 counter=off
2262 Force a 'cut-down' L2TPv3 with no counter as in
2263 draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
2264 pincounter=on
2266 Work around broken counter handling in peer. This may
2267 also help on networks which have packet reorder.
2268 offset=offset
2270 Add an extra offset between header and data
2271 For example, to attach a VM running on host 4.3.2.1 via L2TPv3
2273 to the bridge br-lan on the remote Linux host 1.2.3.4:
2274 # Setup tunnel on linux host using raw ip as encapsulation
2276 # on 1.2.3.4
2277 ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 encap udp udp_sport 16384 udp_dport 16384
2278 ip l2tp add session tunnel_id 1 name vmtunnel0 session_id 0xFFFFFFFF peer_session_id 0xFFFFFFFF
2279 ifconfig vmtunnel0 mtu 1500
2280 ifconfig vmtunnel0 up
2281 brctl addif br-lan vmtunnel0
2282 # on 4.3.2.1
2285 # launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
2286 qemu-system-x86_64 linux.img -device e1000,netdev=n1 -netdev l2tpv3,id=n1,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter
2288 -netdev vde,id=id[,sock=socketpath][,port=n][,group=group‐
2290 name][,mode=octalmode]
2291 Configure VDE backend to connect to PORT n of a vde switch run‐
2292 ning on host and listening for incoming connections on socket‐
2293 path. Use GROUP groupname and MODE octalmode to change default
2294 ownership and permissions for communication port. This option is
2295 only available if QEMU has been compiled with vde support
2296 enabled.
2297 Example:
2299 # launch vde switch
2301 vde_switch -F -sock /tmp/myswitch
2302 # launch QEMU instance
2303 qemu-system-x86_64 linux.img -nic vde,sock=/tmp/myswitch
2304 -netdev vhost-user,chardev=id[,vhostforce=on|off][,queues=n]
2306 Establish a vhost-user netdev, backed by a chardev id. The
2307 chardev should be a unix domain socket backed one. The
2308 vhost-user uses a specifically defined protocol to pass vhost
2309 ioctl replacement messages to an application on the other end of
2310 the socket. On non-MSIX guests, the feature can be forced with
2311 vhostforce. Use 'queues=n' to specify the number of queues to be
2312 created for multiqueue vhost-user.
2313 Example:
2315 qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
2317 -numa node,memdev=mem \
2318 -chardev socket,id=chr0,path=/path/to/socket \
2319 -netdev type=vhost-user,id=net0,chardev=chr0 \
2320 -device virtio-net-pci,netdev=net0
2321 -netdev vhost-vdpa,vhostdev=/path/to/dev
2323 Establish a vhost-vdpa netdev.
2324 vDPA device is a device that uses a datapath which complies with
2326 the virtio specifications with a vendor specific control path.
2327 vDPA devices can be both physically located on the hardware or
2328 emulated by software.
2329 -netdev hubport,id=id,hubid=hubid[,netdev=nd]
2331 Create a hub port on the emulated hub with ID hubid.
2332 The hubport netdev lets you connect a NIC to a QEMU emulated hub
2334 instead of a single netdev. Alternatively, you can also connect
2335 the hubport to another netdev with ID nd by using the netdev=nd
2336 option.
2337 -net nic[,netdev=nd][,macaddr=mac][,model=type]
2339 [,name=name][,addr=addr][,vectors=v]
2340 Legacy option to configure or create an on-board (or machine
2341 default) Network Interface Card(NIC) and connect it either to
2342 the emulated hub with ID 0 (i.e. the default hub), or to the
2343 netdev nd. If model is omitted, then the default NIC model
2344 associated with the machine type is used. Note that the default
2345 NIC model may change in future QEMU releases, so it is highly
2346 recommended to always specify a model. Optionally, the MAC
2347 address can be changed to mac, the device address set to addr
2348 (PCI cards only), and a name can be assigned for use in monitor
2349 commands. Optionally, for PCI cards, you can specify the number
2350 v of MSI-X vectors that the card should have; this option cur‐
2351 rently only affects virtio cards; set v = 0 to disable MSI-X. If
2352 no -net option is specified, a single NIC is created. QEMU can
2353 emulate several different models of network card. Use -net
2354 nic,model=help for a list of available devices for your target.
2355 -net user|tap|bridge|socket|l2tpv3|vde[,...][,name=name]
2357 Configure a host network backend (with the options corresponding
2358 to the same -netdev option) and connect it to the emulated hub 0
2359 (the default hub). Use name to specify the name of the hub port.
2360 Character device options
2362 The general form of a character device option is:
2363 -chardev backend,id=id[,mux=on|off][,options]
2365 Backend is one of: null, socket, udp, msmouse, vc, ringbuf,
2366 file, pipe, console, serial, pty, stdio, braille, tty, parallel,
2367 parport, spicevmc, spiceport. The specific backend will deter‐
2368 mine the applicable options.
2369 Use -chardev help to print all available chardev backend types.
2371 All devices must have an id, which can be any string up to 127
2373 characters long. It is used to uniquely identify this device in
2374 other command line directives.
2375 A character device may be used in multiplexing mode by multiple
2377 front-ends. Specify mux=on to enable this mode. A multiplexer is
2378 a "1:N" device, and here the "1" end is your specified chardev
2379 backend, and the "N" end is the various parts of QEMU that can
2380 talk to a chardev. If you create a chardev with id=myid and
2381 mux=on, QEMU will create a multiplexer with your specified ID,
2382 and you can then configure multiple front ends to use that
2383 chardev ID for their input/output. Up to four different front
2384 ends can be connected to a single multiplexed chardev. (Without
2385 multiplexing enabled, a chardev can only be used by a single
2386 front end.) For instance you could use this to allow a single
2387 stdio chardev to be used by two serial ports and the QEMU moni‐
2388 tor:
2389 -chardev stdio,mux=on,id=char0 \
2391 -mon chardev=char0,mode=readline \
2392 -serial chardev:char0 \
2393 -serial chardev:char0
2394 You can have more than one multiplexer in a system configura‐
2396 tion; for instance you could have a TCP port multiplexed between
2397 UART 0 and UART 1, and stdio multiplexed between the QEMU moni‐
2398 tor and a parallel port:
2399 -chardev stdio,mux=on,id=char0 \
2401 -mon chardev=char0,mode=readline \
2402 -parallel chardev:char0 \
2403 -chardev tcp,...,mux=on,id=char1 \
2404 -serial chardev:char1 \
2405 -serial chardev:char1
2406 When you're using a multiplexed character device, some escape
2408 sequences are interpreted in the input. See mux_005fkeys.
2409 Note that some other command line options may implicitly create
2411 multiplexed character backends; for instance -serial mon:stdio
2412 creates a multiplexed stdio backend connected to the serial port
2413 and the QEMU monitor, and -nographic also multiplexes the con‐
2414 sole and the monitor to stdio.
2415 There is currently no support for multiplexing in the other
2417 direction (where a single QEMU front end takes input and output
2418 from multiple chardevs).
2419 Every backend supports the logfile option, which supplies the
2421 path to a file to record all data transmitted via the backend.
2422 The logappend option controls whether the log file will be trun‐
2423 cated or appended to when opened.
2424 The available backends are:
2426 -chardev null,id=id
2428 A void device. This device will not emit any data, and will drop
2429 any data it receives. The null backend does not take any
2430 options.
2431 -chardev socket,id=id[,TCP options or unix
2433 options][,server][,nowait][,telnet][,websocket][,reconnect=sec‐
2434 onds][,tls-creds=id][,tls-authz=id]
2435 Create a two-way stream socket, which can be either a TCP or a
2436 unix socket. A unix socket will be created if path is specified.
2437 Behaviour is undefined if TCP options are specified for a unix
2438 socket.
2439 server specifies that the socket shall be a listening socket.
2441 nowait specifies that QEMU should not block waiting for a client
2443 to connect to a listening socket.
2444 telnet specifies that traffic on the socket should interpret
2446 telnet escape sequences.
2447 websocket specifies that the socket uses WebSocket protocol for
2449 communication.
2450 reconnect sets the timeout for reconnecting on non-server sock‐
2452 ets when the remote end goes away. qemu will delay this many
2453 seconds and then attempt to reconnect. Zero disables reconnect‐
2454 ing, and is the default.
2455 tls-creds requests enablement of the TLS protocol for encryp‐
2457 tion, and specifies the id of the TLS credentials to use for the
2458 handshake. The credentials must be previously created with the
2459 -object tls-creds argument.
2460 tls-auth provides the ID of the QAuthZ authorization object
2462 against which the client's x509 distinguished name will be vali‐
2463 dated. This object is only resolved at time of use, so can be
2464 deleted and recreated on the fly while the chardev server is
2465 active. If missing, it will default to denying access.
2466 TCP and unix socket options are given below:
2468 TCP options: port=port[,host=host][,to=to][,ipv4][,ipv6][,node‐
2470 lay]
2471 host for a listening socket specifies the local address
2472 to be bound. For a connecting socket species the remote
2473 host to connect to. host is optional for listening sock‐
2474 ets. If not specified it defaults to 0.0.0.0.
2475 port for a listening socket specifies the local port to
2477 be bound. For a connecting socket specifies the port on
2478 the remote host to connect to. port can be given as
2479 either a port number or a service name. port is required.
2480 to is only relevant to listening sockets. If it is speci‐
2482 fied, and port cannot be bound, QEMU will attempt to bind
2483 to subsequent ports up to and including to until it suc‐
2484 ceeds. to must be specified as a port number.
2485 ipv4 and ipv6 specify that either IPv4 or IPv6 must be
2487 used. If neither is specified the socket may use either
2488 protocol.
2489 nodelay disables the Nagle algorithm.
2491 unix options: path=path[,abstract=on|off][,tight=on|off]
2493 path specifies the local path of the unix socket. path is
2494 required. abstract specifies the use of the abstract
2495 socket namespace, rather than the filesystem. Optional,
2496 defaults to false. tight sets the socket length of
2497 abstract sockets to their minimum, rather than the full
2498 sun_path length. Optional, defaults to true.
2499 -chardev udp,id=id[,host=host],port=port[,localaddr=localaddr][,local‐
2501 port=localport][,ipv4][,ipv6]
2502 Sends all traffic from the guest to a remote host over UDP.
2503 host specifies the remote host to connect to. If not specified
2505 it defaults to localhost.
2506 port specifies the port on the remote host to connect to. port
2508 is required.
2509 localaddr specifies the local address to bind to. If not speci‐
2511 fied it defaults to 0.0.0.0.
2512 localport specifies the local port to bind to. If not specified
2514 any available local port will be used.
2515 ipv4 and ipv6 specify that either IPv4 or IPv6 must be used. If
2517 neither is specified the device may use either protocol.
2518 -chardev msmouse,id=id
2520 Forward QEMU's emulated msmouse events to the guest. msmouse
2521 does not take any options.
2522 -chardev
2524 vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]
2525 Connect to a QEMU text console. vc may optionally be given a
2526 specific size.
2527 width and height specify the width and height respectively of
2529 the console, in pixels.
2530 cols and rows specify that the console be sized to fit a text
2532 console with the given dimensions.
2533 -chardev ringbuf,id=id[,size=size]
2535 Create a ring buffer with fixed size size. size must be a power
2536 of two and defaults to 64K.
2537 -chardev file,id=id,path=path
2539 Log all traffic received from the guest to a file.
2540 path specifies the path of the file to be opened. This file will
2542 be created if it does not already exist, and overwritten if it
2543 does. path is required.
2544 -chardev pipe,id=id,path=path
2546 Create a two-way connection to the guest. The behaviour differs
2547 slightly between Windows hosts and other hosts:
2548 On Windows, a single duplex pipe will be created at
2550 \\.pipe\path.
2551 On other hosts, 2 pipes will be created called path.in and
2553 path.out. Data written to path.in will be received by the guest.
2554 Data written by the guest can be read from path.out. QEMU will
2555 not create these fifos, and requires them to be present.
2556 path forms part of the pipe path as described above. path is
2558 required.
2559 -chardev console,id=id
2561 Send traffic from the guest to QEMU's standard output. console
2562 does not take any options.
2563 console is only available on Windows hosts.
2565 -chardev serial,id=id,path=path
2567 Send traffic from the guest to a serial device on the host.
2568 On Unix hosts serial will actually accept any tty device, not
2570 only serial lines.
2571 path specifies the name of the serial device to open.
2573 -chardev pty,id=id
2575 Create a new pseudo-terminal on the host and connect to it. pty
2576 does not take any options.
2577 pty is not available on Windows hosts.
2579 -chardev stdio,id=id[,signal=on|off]
2581 Connect to standard input and standard output of the QEMU
2582 process.
2583 signal controls if signals are enabled on the terminal, that
2585 includes exiting QEMU with the key sequence Control-c. This
2586 option is enabled by default, use signal=off to disable it.
2587 -chardev braille,id=id
2589 Connect to a local BrlAPI server. braille does not take any
2590 options.
2591 -chardev tty,id=id,path=path
2593 tty is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD
2594 and DragonFlyBSD hosts. It is an alias for serial.
2595 path specifies the path to the tty. path is required.
2597 -chardev parallel,id=id,path=path
2599 -chardev parport,id=id,path=path
2602 parallel is only available on Linux, FreeBSD and DragonFlyBSD
2603 hosts.
2604 Connect to a local parallel port.
2606 path specifies the path to the parallel port device. path is
2608 required.
2609 -chardev spicevmc,id=id,debug=debug,name=name
2611 spicevmc is only available when spice support is built in.
2612 debug debug level for spicevmc
2614 name name of spice channel to connect to
2616 Connect to a spice virtual machine channel, such as vdiport.
2618 -chardev spiceport,id=id,debug=debug,name=name
2620 spiceport is only available when spice support is built in.
2621 debug debug level for spicevmc
2623 name name of spice port to connect to
2625 Connect to a spice port, allowing a Spice client to handle the
2627 traffic identified by a name (preferably a fqdn).
2628 TPM device options
2630 The general form of a TPM device option is:
2631 -tpmdev backend,id=id[,options]
2633 The specific backend type will determine the applicable options.
2634 The -tpmdev option creates the TPM backend and requires a
2635 -device option that specifies the TPM frontend interface model.
2636 Use -tpmdev help to print all available TPM backend types.
2638 The available backends are:
2640 -tpmdev passthrough,id=id,path=path,cancel-path=cancel-path
2642 (Linux-host only) Enable access to the host's TPM using the
2643 passthrough driver.
2644 path specifies the path to the host's TPM device, i.e., on a
2646 Linux host this would be /dev/tpm0. path is optional and by
2647 default /dev/tpm0 is used.
2648 cancel-path specifies the path to the host TPM device's sysfs
2650 entry allowing for cancellation of an ongoing TPM command. can‐
2651 cel-path is optional and by default QEMU will search for the
2652 sysfs entry to use.
2653 Some notes about using the host's TPM with the passthrough
2655 driver:
2656 The TPM device accessed by the passthrough driver must not be
2658 used by any other application on the host.
2659 Since the host's firmware (BIOS/UEFI) has already initialized
2661 the TPM, the VM's firmware (BIOS/UEFI) will not be able to ini‐
2662 tialize the TPM again and may therefore not show a TPM-specific
2663 menu that would otherwise allow the user to configure the TPM,
2664 e.g., allow the user to enable/disable or activate/deactivate
2665 the TPM. Further, if TPM ownership is released from within a VM
2666 then the host's TPM will get disabled and deactivated. To enable
2667 and activate the TPM again afterwards, the host has to be
2668 rebooted and the user is required to enter the firmware's menu
2669 to enable and activate the TPM. If the TPM is left disabled
2670 and/or deactivated most TPM commands will fail.
2671 To create a passthrough TPM use the following two options:
2673 -tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
2675 Note that the -tpmdev id is tpm0 and is referenced by
2677 tpmdev=tpm0 in the device option.
2678 -tpmdev emulator,id=id,chardev=dev
2680 (Linux-host only) Enable access to a TPM emulator using Unix
2681 domain socket based chardev backend.
2682 chardev specifies the unique ID of a character device backend
2684 that provides connection to the software TPM server.
2685 To create a TPM emulator backend device with chardev socket
2687 backend:
2688 -chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0
2690 Linux/Multiboot boot specific
2692 When using these options, you can use a given Linux or Multiboot kernel
2693 without installing it in the disk image. It can be useful for easier
2694 testing of various kernels.
2695 -kernel bzImage
2697 Use bzImage as kernel image. The kernel can be either a Linux
2698 kernel or in multiboot format.
2699 -append cmdline
2701 Use cmdline as kernel command line
2702 -initrd file
2704 Use file as initial ram disk.
2705 -initrd file1 arg=foo,file2
2707 This syntax is only available with multiboot.
2708 Use file1 and file2 as modules and pass arg=foo as parameter to
2710 the first module.
2711 -dtb file
2713 Use file as a device tree binary (dtb) image and pass it to the
2714 kernel on boot.
2715 Debug/Expert options
2717 -fw_cfg [name=]name,file=file
2718 Add named fw_cfg entry with contents from file file.
2719 -fw_cfg [name=]name,string=str
2721 Add named fw_cfg entry with contents from string str.
2722 The terminating NUL character of the contents of str will not be
2724 included as part of the fw_cfg item data. To insert contents
2725 with embedded NUL characters, you have to use the file parame‐
2726 ter.
2727 The fw_cfg entries are passed by QEMU through to the guest.
2729 Example:
2731 -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
2733 creates an fw_cfg entry named opt/com.mycompany/blob with con‐
2735 tents from ./my_blob.bin.
2736 -serial dev
2738 Redirect the virtual serial port to host character device dev.
2739 The default device is vc in graphical mode and stdio in non
2740 graphical mode.
2741 This option can be used several times to simulate up to 4 serial
2743 ports.
2744 Use -serial none to disable all serial ports.
2746 Available character devices are:
2748 vc[:WxH]
2750 Virtual console. Optionally, a width and height can be
2751 given in pixel with
2752 vc:800x600
2754 It is also possible to specify width or height in charac‐
2756 ters:
2757 vc:80Cx24C
2759 pty [Linux only] Pseudo TTY (a new PTY is automatically allo‐
2761 cated)
2762 none No device is allocated.
2764 null void device
2766 chardev:id
2768 Use a named character device defined with the -chardev
2769 option.
2770 /dev/XXX
2772 [Linux only] Use host tty, e.g. /dev/ttyS0. The host
2773 serial port parameters are set according to the emulated
2774 ones.
2775 /dev/parportN
2777 [Linux only, parallel port only] Use host parallel port
2778 N. Currently SPP and EPP parallel port features can be
2779 used.
2780 file:filename
2782 Write output to filename. No character can be read.
2783 stdio [Unix only] standard input/output
2785 pipe:filename
2787 name pipe filename
2788 COMn [Windows only] Use host serial port n
2790 udp:[remote_host]:remote_port[@[src_ip]:src_port]
2792 This implements UDP Net Console. When remote_host or
2793 src_ip are not specified they default to 0.0.0.0. When
2794 not using a specified src_port a random port is automati‐
2795 cally chosen.
2796 If you just want a simple readonly console you can use
2798 netcat or nc, by starting QEMU with: -serial udp::4555
2799 and nc as: nc -u -l -p 4555. Any time QEMU writes some‐
2800 thing to that port it will appear in the netconsole ses‐
2801 sion.
2802 If you plan to send characters back via netconsole or you
2804 want to stop and start QEMU a lot of times, you should
2805 have QEMU use the same source port each time by using
2806 something like -serial udp::4555@:4556 to QEMU. Another
2807 approach is to use a patched version of netcat which can
2808 listen to a TCP port and send and receive characters via
2809 udp. If you have a patched version of netcat which acti‐
2810 vates telnet remote echo and single char transfer, then
2811 you can use the following options to set up a netcat
2812 redirector to allow telnet on port 5555 to access the
2813 QEMU port.
2814 QEMU Options:
2816 -serial udp::4555@:4556
2817 netcat options:
2819 -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
2820 telnet options:
2822 localhost 5555
2823 tcp:[host]:port[,server][,nowait][,nodelay][,reconnect=seconds]
2825 The TCP Net Console has two modes of operation. It can
2826 send the serial I/O to a location or wait for a connec‐
2827 tion from a location. By default the TCP Net Console is
2828 sent to host at the port. If you use the server option
2829 QEMU will wait for a client socket application to connect
2830 to the port before continuing, unless the nowait option
2831 was specified. The nodelay option disables the Nagle
2832 buffering algorithm. The reconnect option only applies if
2833 noserver is set, if the connection goes down it will
2834 attempt to reconnect at the given interval. If host is
2835 omitted, 0.0.0.0 is assumed. Only one TCP connection at a
2836 time is accepted. You can use telnet to connect to the
2837 corresponding character device.
2838 Example to send tcp console to 192.168.0.2 port 4444
2840 -serial tcp:192.168.0.2:4444
2841 Example to listen and wait on port 4444 for connection
2843 -serial tcp::4444,server
2844 Example to not wait and listen on ip 192.168.0.100 port
2846 4444
2847 -serial tcp:192.168.0.100:4444,server,nowait
2848 telnet:host:port[,server][,nowait][,nodelay]
2850 The telnet protocol is used instead of raw tcp sockets.
2851 The options work the same as if you had specified -serial
2852 tcp. The difference is that the port acts like a telnet
2853 server or client using telnet option negotiation. This
2854 will also allow you to send the MAGIC_SYSRQ sequence if
2855 you use a telnet that supports sending the break
2856 sequence. Typically in unix telnet you do it with Con‐
2857 trol-] and then type "send break" followed by pressing
2858 the enter key.
2859 websocket:host:port,server[,nowait][,nodelay]
2861 The WebSocket protocol is used instead of raw tcp socket.
2862 The port acts as a WebSocket server. Client mode is not
2863 supported.
2864 unix:path[,server][,nowait][,reconnect=seconds]
2866 A unix domain socket is used instead of a tcp socket. The
2867 option works the same as if you had specified -serial tcp
2868 except the unix domain socket path is used for connec‐
2869 tions.
2870 mon:dev_string
2872 This is a special option to allow the monitor to be mul‐
2873 tiplexed onto another serial port. The monitor is
2874 accessed with key sequence of Control-a and then pressing
2875 c. dev_string should be any one of the serial devices
2876 specified above. An example to multiplex the monitor onto
2877 a telnet server listening on port 4444 would be:
2878 -serial mon:telnet::4444,server,nowait
2880 When the monitor is multiplexed to stdio in this way,
2882 Ctrl+C will not terminate QEMU any more but will be
2883 passed to the guest instead.
2884 braille
2886 Braille device. This will use BrlAPI to display the
2887 braille output on a real or fake device.
2888 msmouse
2890 Three button serial mouse. Configure the guest to use Mi‐
2891 crosoft protocol.
2892 -parallel dev
2894 Redirect the virtual parallel port to host device dev (same
2895 devices as the serial port). On Linux hosts, /dev/parportN can
2896 be used to use hardware devices connected on the corresponding
2897 host parallel port.
2898 This option can be used several times to simulate up to 3 paral‐
2900 lel ports.
2901 Use -parallel none to disable all parallel ports.
2903 -monitor dev
2905 Redirect the monitor to host device dev (same devices as the
2906 serial port). The default device is vc in graphical mode and
2907 stdio in non graphical mode. Use -monitor none to disable the
2908 default monitor.
2909 -qmp dev
2911 Like -monitor but opens in 'control' mode.
2912 -qmp-pretty dev
2914 Like -qmp but uses pretty JSON formatting.
2915 -mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]
2917 Setup monitor on chardev name. pretty turns on JSON pretty
2918 printing easing human reading and debugging.
2919 -debugcon dev
2921 Redirect the debug console to host device dev (same devices as
2922 the serial port). The debug console is an I/O port which is typ‐
2923 ically port 0xe9; writing to that I/O port sends output to this
2924 device. The default device is vc in graphical mode and stdio in
2925 non graphical mode.
2926 -pidfile file
2928 Store the QEMU process PID in file. It is useful if you launch
2929 QEMU from a script.
2930 -singlestep
2932 Run the emulation in single step mode.
2933 --preconfig
2935 Pause QEMU for interactive configuration before the machine is
2936 created, which allows querying and configuring properties that
2937 will affect machine initialization. Use QMP command 'x-exit-pre‐
2938 config' to exit the preconfig state and move to the next state
2939 (i.e. run guest if -S isn't used or pause the second time if -S
2940 is used). This option is experimental.
2941 -S Do not start CPU at startup (you must type 'c' in the monitor).
2943 -realtime mlock=on|off
2945 Run qemu with realtime features. mlocking qemu and guest memory
2946 can be enabled via mlock=on (enabled by default).
2947 -overcommit mem-lock=on|off
2949 -overcommit cpu-pm=on|off
2952 Run qemu with hints about host resource overcommit. The default
2953 is to assume that host overcommits all resources.
2954 Locking qemu and guest memory can be enabled via mem-lock=on
2956 (disabled by default). This works when host memory is not over‐
2957 committed and reduces the worst-case latency for guest. This is
2958 equivalent to realtime.
2959 Guest ability to manage power state of host cpus (increasing
2961 latency for other processes on the same host cpu, but decreasing
2962 latency for guest) can be enabled via cpu-pm=on (disabled by
2963 default). This works best when host CPU is not overcommitted.
2964 When used, host estimates of CPU cycle and power utilization
2965 will be incorrect, not taking into account guest idle time.
2966 -gdb dev
2968 Accept a gdb connection on device dev (see gdb_005fusage). Note
2969 that this option does not pause QEMU execution -- if you want
2970 QEMU to not start the guest until you connect with gdb and issue
2971 a continue command, you will need to also pass the -S option to
2972 QEMU.
2973 The most usual configuration is to listen on a local TCP socket:
2975 -gdb tcp::3117
2977 but you can specify other backends; UDP, pseudo TTY, or even
2979 stdio are all reasonable use cases. For example, a stdio connec‐
2980 tion allows you to start QEMU from within gdb and establish the
2981 connection via a pipe:
2982 (gdb) target remote | exec qemu-system-x86_64 -gdb stdio ...
2984 -s Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port
2986 1234 (see gdb_005fusage).
2987 -d item1[,...]
2989 Enable logging of specified items. Use '-d help' for a list of
2990 log items.
2991 -D logfile
2993 Output log in logfile instead of to stderr
2994 -dfilter range1[,...]
2996 Filter debug output to that relevant to a range of target
2997 addresses. The filter spec can be either start+size, start-size
2998 or start..end where start end and size are the addresses and
2999 sizes required. For example:
3000 -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000
3002 Will dump output for any code in the 0x1000 sized block starting
3004 at 0x8000 and the 0x200 sized block starting at
3005 0xffffffc000080000 and another 0x1000 sized block starting at
3006 0xffffffc00005f000.
3007 -seed number
3009 Force the guest to use a deterministic pseudo-random number gen‐
3010 erator, seeded with number. This does not affect crypto routines
3011 within the host.
3012 -L path
3014 Set the directory for the BIOS, VGA BIOS and keymaps.
3015 To list all the data directories, use -L help.
3017 -bios file
3019 Set the filename for the BIOS.
3020 -enable-kvm
3022 Enable KVM full virtualization support. This option is only
3023 available if KVM support is enabled when compiling.
3024 -xen-domid id
3026 Specify xen guest domain id (XEN only).
3027 -xen-attach
3029 Attach to existing xen domain. libxl will use this when starting
3030 QEMU (XEN only). Restrict set of available xen operations to
3031 specified domain id (XEN only).
3032 -no-reboot
3034 Exit instead of rebooting.
3035 -no-shutdown
3037 Don't exit QEMU on guest shutdown, but instead only stop the
3038 emulation. This allows for instance switching to monitor to com‐
3039 mit changes to the disk image.
3040 -loadvm file
3042 Start right away with a saved state (loadvm in monitor)
3043 -daemonize
3045 Daemonize the QEMU process after initialization. QEMU will not
3046 detach from standard IO until it is ready to receive connections
3047 on any of its devices. This option is a useful way for external
3048 programs to launch QEMU without having to cope with initializa‐
3049 tion race conditions.
3050 -option-rom file
3052 Load the contents of file as an option ROM. This option is use‐
3053 ful to load things like EtherBoot.
3054 -rtc [base=utc|localtime|datetime][,clock=host|rt|vm][,drift‐
3056 fix=none|slew]
3057 Specify base as utc or localtime to let the RTC start at the
3058 current UTC or local time, respectively. localtime is required
3059 for correct date in MS-DOS or Windows. To start at a specific
3060 point in time, provide datetime in the format
3061 2006-06-17T16:01:21 or 2006-06-17. The default base is UTC.
3062 By default the RTC is driven by the host system time. This
3064 allows using of the RTC as accurate reference clock inside the
3065 guest, specifically if the host time is smoothly following an
3066 accurate external reference clock, e.g. via NTP. If you want to
3067 isolate the guest time from the host, you can set clock to rt
3068 instead, which provides a host monotonic clock if host support
3069 it. To even prevent the RTC from progressing during suspension,
3070 you can set clock to vm (virtual clock). 'clock=vm' is recom‐
3071 mended especially in icount mode in order to preserve determin‐
3072 ism; however, note that in icount mode the speed of the virtual
3073 clock is variable and can in general differ from the host clock.
3074 Enable driftfix (i386 targets only) if you experience time drift
3076 problems, specifically with Windows' ACPI HAL. This option will
3077 try to figure out how many timer interrupts were not processed
3078 by the Windows guest and will re-inject them.
3079 -icount [shift=N|auto][,rr=record|replay,rrfile=filename,rrsnap‐
3081 shot=snapshot]
3082 Enable virtual instruction counter. The virtual cpu will execute
3083 one instruction every 2^N ns of virtual time. If auto is speci‐
3084 fied then the virtual cpu speed will be automatically adjusted
3085 to keep virtual time within a few seconds of real time.
3086 When the virtual cpu is sleeping, the virtual time will advance
3088 at default speed unless sleep=on|off is specified. With
3089 sleep=on|off, the virtual time will jump to the next timer dead‐
3090 line instantly whenever the virtual cpu goes to sleep mode and
3091 will not advance if no timer is enabled. This behavior give
3092 deterministic execution times from the guest point of view.
3093 Note that while this option can give deterministic behavior, it
3095 does not provide cycle accurate emulation. Modern CPUs contain
3096 superscalar out of order cores with complex cache hierarchies.
3097 The number of instructions executed often has little or no cor‐
3098 relation with actual performance.
3099 align=on will activate the delay algorithm which will try to
3101 synchronise the host clock and the virtual clock. The goal is to
3102 have a guest running at the real frequency imposed by the shift
3103 option. Whenever the guest clock is behind the host clock and if
3104 align=on is specified then we print a message to the user to
3105 inform about the delay. Currently this option does not work when
3106 shift is auto. Note: The sync algorithm will work for those
3107 shift values for which the guest clock runs ahead of the host
3108 clock. Typically this happens when the shift value is high (how
3109 high depends on the host machine).
3110 When rr option is specified deterministic record/replay is
3112 enabled. Replay log is written into filename file in record mode
3113 and read from this file in replay mode.
3114 Option rrsnapshot is used to create new vm snapshot named snap‐
3116 shot at the start of execution recording. In replay mode this
3117 option is used to load the initial VM state.
3118 -watchdog model
3120 Create a virtual hardware watchdog device. Once enabled (by a
3121 guest action), the watchdog must be periodically polled by an
3122 agent inside the guest or else the guest will be restarted.
3123 Choose a model for which your guest has drivers.
3124 The model is the model of hardware watchdog to emulate. Use
3126 -watchdog help to list available hardware models. Only one
3127 watchdog can be enabled for a guest.
3128 The following models may be available:
3130 ib700 iBASE 700 is a very simple ISA watchdog with a single
3132 timer.
3133 i6300esb
3135 Intel 6300ESB I/O controller hub is a much more feature‐
3136 ful PCI-based dual-timer watchdog.
3137 diag288
3139 A virtual watchdog for s390x backed by the diagnose 288
3140 hypercall (currently KVM only).
3141 -watchdog-action action
3143 The action controls what QEMU will do when the watchdog timer
3144 expires. The default is reset (forcefully reset the guest).
3145 Other possible actions are: shutdown (attempt to gracefully
3146 shutdown the guest), poweroff (forcefully poweroff the guest),
3147 inject-nmi (inject a NMI into the guest), pause (pause the
3148 guest), debug (print a debug message and continue), or none (do
3149 nothing).
3150 Note that the shutdown action requires that the guest responds
3152 to ACPI signals, which it may not be able to do in the sort of
3153 situations where the watchdog would have expired, and thus
3154 -watchdog-action shutdown is not recommended for production use.
3155 Examples:
3157 -watchdog i6300esb -watchdog-action pause; -watchdog ib700
3159 -echr numeric_ascii_value
3161 Change the escape character used for switching to the monitor
3162 when using monitor and serial sharing. The default is 0x01 when
3163 using the -nographic option. 0x01 is equal to pressing Con‐
3164 trol-a. You can select a different character from the ascii con‐
3165 trol keys where 1 through 26 map to Control-a through Control-z.
3166 For instance you could use the either of the following to change
3167 the escape character to Control-t.
3168 -echr 0x14; -echr 20
3170 -show-cursor
3172 Show cursor.
3173 -tb-size n
3175 Set TCG translation block cache size. Deprecated, use '-accel
3176 tcg,tb-size=n' instead.
3177 -incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]
3179 -incoming rdma:host:port[,ipv4][,ipv6]
3182 Prepare for incoming migration, listen on a given tcp port.
3183 -incoming unix:socketpath
3185 Prepare for incoming migration, listen on a given unix socket.
3186 -incoming fd:fd
3188 Accept incoming migration from a given filedescriptor.
3189 -incoming exec:cmdline
3191 Accept incoming migration as an output from specified external
3192 command.
3193 -incoming defer
3195 Wait for the URI to be specified via migrate_incoming. The moni‐
3196 tor can be used to change settings (such as migration parame‐
3197 ters) prior to issuing the migrate_incoming to allow the migra‐
3198 tion to begin.
3199 -only-migratable
3201 Only allow migratable devices. Devices will not be allowed to
3202 enter an unmigratable state.
3203 -nodefaults
3205 Don't create default devices. Normally, QEMU sets the default
3206 devices like serial port, parallel port, virtual console, moni‐
3207 tor device, VGA adapter, floppy and CD-ROM drive and others. The
3208 -nodefaults option will disable all those default devices.
3209 -chroot dir
3211 Immediately before starting guest execution, chroot to the spec‐
3212 ified directory. Especially useful in combination with -runas.
3213 -runas user
3215 Immediately before starting guest execution, drop root privi‐
3216 leges, switching to the specified user.
3217 -prom-env variable=value
3219 Set OpenBIOS nvram variable to given value (PPC, SPARC only).
3220 qemu-system-sparc -prom-env 'auto-boot?=false' \
3222 -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
3223 qemu-system-ppc -prom-env 'auto-boot?=false' \
3225 -prom-env 'boot-device=hd:2,\yaboot' \
3226 -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
3227 -semihosting
3229 Enable semihosting mode (ARM, M68K, Xtensa, MIPS, Nios II only).
3230 Note that this allows guest direct access to the host filesys‐
3232 tem, so should only be used with a trusted guest OS.
3233 See the -semihosting-config option documentation for further
3235 information about the facilities this enables.
3236 -semihosting-config [enable=on|off][,tar‐
3238 get=native|gdb|auto][,chardev=id][,arg=str[,...]]
3239 Enable and configure semihosting (ARM, M68K, Xtensa, MIPS, Nios
3240 II only).
3241 Note that this allows guest direct access to the host filesys‐
3243 tem, so should only be used with a trusted guest OS.
3244 On Arm this implements the standard semihosting API, version
3246 2.0.
3247 On M68K this implements the "ColdFire GDB" interface used by
3249 libgloss.
3250 Xtensa semihosting provides basic file IO calls, such as
3252 open/read/write/seek/select. Tensilica baremetal libc for ISS
3253 and linux platform "sim" use this interface.
3254 target=native|gdb|auto
3256 Defines where the semihosting calls will be addressed, to
3257 QEMU (native) or to GDB (gdb). The default is auto, which
3258 means gdb during debug sessions and native otherwise.
3259 chardev=str1
3261 Send the output to a chardev backend output for native or
3262 auto output when not in gdb
3263 arg=str1,arg=str2,...
3265 Allows the user to pass input arguments, and can be used
3266 multiple times to build up a list. The old-style -ker‐
3267 nel/-append method of passing a command line is still
3268 supported for backward compatibility. If both the --semi‐
3269 hosting-config arg and the -kernel/-append are specified,
3270 the former is passed to semihosting as it always takes
3271 precedence.
3272 -old-param
3274 Old param mode (ARM only).
3275 -sandbox arg[,obsolete=string][,elevateprivi‐
3277 leges=string][,spawn=string][,resourcecontrol=string]
3278 Enable Seccomp mode 2 system call filter. 'on' will enable
3279 syscall filtering and 'off' will disable it. The default is
3280 'off'.
3281 obsolete=string
3283 Enable Obsolete system calls
3284 elevateprivileges=string
3286 Disable set*uid|gid system calls
3287 spawn=string
3289 Disable *fork and execve
3290 resourcecontrol=string
3292 Disable process affinity and schedular priority
3293 -readconfig file
3295 Read device configuration from file. This approach is useful
3296 when you want to spawn QEMU process with many command line
3297 options but you don't want to exceed the command line character
3298 limit.
3299 -writeconfig file
3301 Write device configuration to file. The file can be either file‐
3302 name to save command line and device configuration into file or
3303 dash -) character to print the output to stdout. This can be
3304 later used as input file for -readconfig option.
3305 -no-user-config
3307 The -no-user-config option makes QEMU not load any of the
3308 user-provided config files on sysconfdir.
3309 -trace [[enable=]pattern][,events=file][,file=file]
3311 Specify tracing options.
3312 [enable=]PATTERN
3314 Immediately enable events matching PATTERN (either event
3315 name or a globbing pattern). This option is only avail‐
3316 able if QEMU has been compiled with the simple, log or
3317 ftrace tracing backend. To specify multiple events or
3318 patterns, specify the -trace option multiple times.
3319 Use -trace help to print a list of names of trace points.
3321 events=FILE
3323 Immediately enable events listed in FILE. The file must
3324 contain one event name (as listed in the trace-events-all
3325 file) per line; globbing patterns are accepted too. This
3326 option is only available if QEMU has been compiled with
3327 the simple, log or ftrace tracing backend.
3328 file=FILE
3330 Log output traces to FILE. This option is only available
3331 if QEMU has been compiled with the simple tracing back‐
3332 end.
3333 -plugin file=file[,arg=string]
3335 Load a plugin.
3336 file=file
3338 Load the given plugin from a shared library file.
3339 arg=string
3341 Argument string passed to the plugin. (Can be given mul‐
3342 tiple times.)
3343 -enable-fips
3345 Enable FIPS 140-2 compliance mode.
3346 -msg [timestamp[=on|off]][,guest-name[=on|off]]
3348 Control error message format.
3349 timestamp=on|off
3351 Prefix messages with a timestamp. Default is off.
3352 guest-name=on|off
3354 Prefix messages with guest name but only if -name guest
3355 option is set otherwise the option is ignored. Default is
3356 off.
3357 -dump-vmstate file
3359 Dump json-encoded vmstate information for current machine type
3360 to file in file
3361 -enable-sync-profile
3363 Enable synchronization profiling.
3364 Generic object creation
3366 -object typename[,prop1=value1,...]
3367 Create a new object of type typename setting properties in the
3368 order they are specified. Note that the 'id' property must be
3369 set. These objects are placed in the '/objects' path.
3370 -object memory-back‐
3372 end-file,id=id,size=size,mem-path=dir,share=on|off,dis‐
3373 card-data=on|off,merge=on|off,dump=on|off,preal‐
3374 loc=on|off,host-nodes=host-nodes,policy=default|pre‐
3375 ferred|bind|interleave,align=align
3376 Creates a memory file backend object, which can be used
3377 to back the guest RAM with huge pages.
3378 The id parameter is a unique ID that will be used to ref‐
3380 erence this memory region when configuring the -numa
3381 argument.
3382 The size option provides the size of the memory region,
3384 and accepts common suffixes, eg 500M.
3385 The mem-path provides the path to either a shared memory
3387 or huge page filesystem mount.
3388 The share boolean option determines whether the memory
3390 region is marked as private to QEMU, or shared. The lat‐
3391 ter allows a co-operating external process to access the
3392 QEMU memory region.
3393 The share is also required for pvrdma devices due to lim‐
3395 itations in the RDMA API provided by Linux.
3396 Setting share=on might affect the ability to configure
3398 NUMA bindings for the memory backend under some circum‐
3399 stances, see Documentation/vm/numa_memory_policy.txt on
3400 the Linux kernel source tree for additional details.
3401 Setting the discard-data boolean option to on indicates
3403 that file contents can be destroyed when QEMU exits, to
3404 avoid unnecessarily flushing data to the backing file.
3405 Note that discard-data is only an optimization, and QEMU
3406 might not discard file contents if it aborts unexpectedly
3407 or is terminated using SIGKILL.
3408 The merge boolean option enables memory merge, also known
3410 as MADV_MERGEABLE, so that Kernel Samepage Merging will
3411 consider the pages for memory deduplication.
3412 Setting the dump boolean option to off excludes the mem‐
3414 ory from core dumps. This feature is also known as
3415 MADV_DONTDUMP.
3416 The prealloc boolean option enables memory preallocation.
3418 The host-nodes option binds the memory range to a list of
3420 NUMA host nodes.
3421 The policy option sets the NUMA policy to one of the fol‐
3423 lowing values:
3424 default
3426 default host policy
3427 preferred
3429 prefer the given host node list for allocation
3430 bind restrict memory allocation to the given host node
3432 list
3433 interleave
3435 interleave memory allocations across the given
3436 host node list
3437 The align option specifies the base address alignment
3439 when QEMU mmap(2) mem-path, and accepts common suffixes,
3440 eg 2M. Some backend store specified by mem-path requires
3441 an alignment different than the default one used by QEMU,
3442 eg the device DAX /dev/dax0.0 requires 2M alignment
3443 rather than 4K. In such cases, users can specify the
3444 required alignment via this option.
3445 The pmem option specifies whether the backing file speci‐
3447 fied by mem-path is in host persistent memory that can be
3448 accessed using the SNIA NVM programming model (e.g. Intel
3449 NVDIMM). If pmem is set to 'on', QEMU will take necessary
3450 operations to guarantee the persistence of its own writes
3451 to mem-path (e.g. in vNVDIMM label emulation and live
3452 migration). Also, we will map the backend-file with
3453 MAP_SYNC flag, which ensures the file metadata is in sync
3454 for mem-path in case of host crash or a power failure.
3455 MAP_SYNC requires support from both the host kernel
3456 (since Linux kernel 4.15) and the filesystem of mem-path
3457 mounted with DAX option.
3458 -object memory-back‐
3460 end-ram,id=id,merge=on|off,dump=on|off,share=on|off,preal‐
3461 loc=on|off,size=size,host-nodes=host-nodes,policy=default|pre‐
3462 ferred|bind|interleave
3463 Creates a memory backend object, which can be used to
3464 back the guest RAM. Memory backend objects offer more
3465 control than the -m option that is traditionally used to
3466 define guest RAM. Please refer to memory-backend-file
3467 for a description of the options.
3468 -object memory-back‐
3470 end-memfd,id=id,merge=on|off,dump=on|off,share=on|off,preal‐
3471 loc=on|off,size=size,host-nodes=host-nodes,policy=default|pre‐
3472 ferred|bind|interleave,seal=on|off,hugetlb=on|off,hugetlb‐
3473 size=size
3474 Creates an anonymous memory file backend object, which
3475 allows QEMU to share the memory with an external process
3476 (e.g. when using vhost-user). The memory is allocated
3477 with memfd and optional sealing. (Linux only)
3478 The seal option creates a sealed-file, that will block
3480 further resizing the memory ('on' by default).
3481 The hugetlb option specify the file to be created resides
3483 in the hugetlbfs filesystem (since Linux 4.14). Used in
3484 conjunction with the hugetlb option, the hugetlbsize
3485 option specify the hugetlb page size on systems that sup‐
3486 port multiple hugetlb page sizes (it must be a power of 2
3487 value supported by the system).
3488 In some versions of Linux, the hugetlb option is incom‐
3490 patible with the seal option (requires at least Linux
3491 4.16).
3492 Please refer to memory-backend-file for a description of
3494 the other options.
3495 The share boolean option is on by default with memfd.
3497 -object rng-builtin,id=id
3499 Creates a random number generator backend which obtains
3500 entropy from QEMU builtin functions. The id parameter is
3501 a unique ID that will be used to reference this entropy
3502 backend from the virtio-rng device. By default, the vir‐
3503 tio-rng device uses this RNG backend.
3504 -object rng-random,id=id,filename=/dev/random
3506 Creates a random number generator backend which obtains
3507 entropy from a device on the host. The id parameter is a
3508 unique ID that will be used to reference this entropy
3509 backend from the virtio-rng device. The filename parame‐
3510 ter specifies which file to obtain entropy from and if
3511 omitted defaults to /dev/urandom.
3512 -object rng-egd,id=id,chardev=chardevid
3514 Creates a random number generator backend which obtains
3515 entropy from an external daemon running on the host. The
3516 id parameter is a unique ID that will be used to refer‐
3517 ence this entropy backend from the virtio-rng device. The
3518 chardev parameter is the unique ID of a character device
3519 backend that provides the connection to the RNG daemon.
3520 -object tls-creds-anon,id=id,endpoint=end‐
3522 point,dir=/path/to/cred/dir,verify-peer=on|off
3523 Creates a TLS anonymous credentials object, which can be
3524 used to provide TLS support on network backends. The id
3525 parameter is a unique ID which network backends will use
3526 to access the credentials. The endpoint is either server
3527 or client depending on whether the QEMU network backend
3528 that uses the credentials will be acting as a client or
3529 as a server. If verify-peer is enabled (the default) then
3530 once the handshake is completed, the peer credentials
3531 will be verified, though this is a no-op for anonymous
3532 credentials.
3533 The dir parameter tells QEMU where to find the credential
3535 files. For server endpoints, this directory may contain
3536 a file dh-params.pem providing diffie-hellman parameters
3537 to use for the TLS server. If the file is missing, QEMU
3538 will generate a set of DH parameters at startup. This is
3539 a computationally expensive operation that consumes ran‐
3540 dom pool entropy, so it is recommended that a persistent
3541 set of parameters be generated upfront and saved.
3542 -object tls-creds-psk,id=id,endpoint=end‐
3544 point,dir=/path/to/keys/dir[,username=username]
3545 Creates a TLS Pre-Shared Keys (PSK) credentials object,
3546 which can be used to provide TLS support on network back‐
3547 ends. The id parameter is a unique ID which network back‐
3548 ends will use to access the credentials. The endpoint is
3549 either server or client depending on whether the QEMU
3550 network backend that uses the credentials will be acting
3551 as a client or as a server. For clients only, username
3552 is the username which will be sent to the server. If
3553 omitted it defaults to "qemu".
3554 The dir parameter tells QEMU where to find the keys file.
3556 It is called "dir/keys.psk" and contains "username:key"
3557 pairs. This file can most easily be created using the
3558 GnuTLS psktool program.
3559 For server endpoints, dir may also contain a file
3561 dh-params.pem providing diffie-hellman parameters to use
3562 for the TLS server. If the file is missing, QEMU will
3563 generate a set of DH parameters at startup. This is a
3564 computationally expensive operation that consumes random
3565 pool entropy, so it is recommended that a persistent set
3566 of parameters be generated up front and saved.
3567 -object tls-creds-x509,id=id,endpoint=end‐
3569 point,dir=/path/to/cred/dir,priority=priority,ver‐
3570 ify-peer=on|off,passwordid=id
3571 Creates a TLS anonymous credentials object, which can be
3572 used to provide TLS support on network backends. The id
3573 parameter is a unique ID which network backends will use
3574 to access the credentials. The endpoint is either server
3575 or client depending on whether the QEMU network backend
3576 that uses the credentials will be acting as a client or
3577 as a server. If verify-peer is enabled (the default) then
3578 once the handshake is completed, the peer credentials
3579 will be verified. With x509 certificates, this implies
3580 that the clients must be provided with valid client cer‐
3581 tificates too.
3582 The dir parameter tells QEMU where to find the credential
3584 files. For server endpoints, this directory may contain
3585 a file dh-params.pem providing diffie-hellman parameters
3586 to use for the TLS server. If the file is missing, QEMU
3587 will generate a set of DH parameters at startup. This is
3588 a computationally expensive operation that consumes ran‐
3589 dom pool entropy, so it is recommended that a persistent
3590 set of parameters be generated upfront and saved.
3591 For x509 certificate credentials the directory will con‐
3593 tain further files providing the x509 certificates. The
3594 certificates must be stored in PEM format, in filenames
3595 ca-cert.pem, ca-crl.pem (optional), server-cert.pem (only
3596 servers), server-key.pem (only servers), client-cert.pem
3597 (only clients), and client-key.pem (only clients).
3598 For the server-key.pem and client-key.pem files which
3600 contain sensitive private keys, it is possible to use an
3601 encrypted version by providing the passwordid parameter.
3602 This provides the ID of a previously created secret
3603 object containing the password for decryption.
3604 The priority parameter allows to override the global
3606 default priority used by gnutls. This can be useful if
3607 the system administrator needs to use a weaker set of
3608 crypto priorities for QEMU without potentially forcing
3609 the weakness onto all applications. Or conversely if one
3610 wants wants a stronger default for QEMU than for all
3611 other applications, they can do this through this parame‐
3612 ter. Its format is a gnutls priority string as described
3613 at
3614 https://gnutls.org/manual/html_node/Priority-Strings.html.
3615 -object tls-cipher-suites,id=id,priority=priority
3617 Creates a TLS cipher suites object, which can be used to
3618 control the TLS cipher/protocol algorithms that applica‐
3619 tions are permitted to use.
3620 The id parameter is a unique ID which frontends will use
3622 to access the ordered list of permitted TLS cipher suites
3623 from the host.
3624 The priority parameter allows to override the global
3626 default priority used by gnutls. This can be useful if
3627 the system administrator needs to use a weaker set of
3628 crypto priorities for QEMU without potentially forcing
3629 the weakness onto all applications. Or conversely if one
3630 wants wants a stronger default for QEMU than for all
3631 other applications, they can do this through this parame‐
3632 ter. Its format is a gnutls priority string as described
3633 at
3634 https://gnutls.org/manual/html_node/Priority-Strings.html.
3635 An example of use of this object is to control UEFI HTTPS
3637 Boot. The tls-cipher-suites object exposes the ordered
3638 list of permitted TLS cipher suites from the host side to
3639 the guest firmware, via fw_cfg. The list is represented
3640 as an array of IANA_TLS_CIPHER objects. The firmware uses
3641 the IANA_TLS_CIPHER array for configuring guest-side TLS.
3642 In the following example, the priority at which the
3644 host-side policy is retrieved is given by the priority
3645 property. Given that QEMU uses GNUTLS, priority=@SYSTEM
3646 may be used to refer to /etc/crypto-poli‐
3647 cies/back-ends/gnutls.config.
3648 # qemu-system-x86_64 -object tls-cipher-suites,id=mysuite0,priority=@SYSTEM -fw_cfg name=etc/edk2/https/ciphers,gen_id=mysuite0
3650 -object filter-buffer,id=id,netdev=netdevid,inter‐
3652 val=t[,queue=all|rx|tx][,status=on|off][,posi‐
3653 tion=head|tail|id=<id>][,insert=behind|before]
3654 Interval t can't be 0, this filter batches the packet
3655 delivery: all packets arriving in a given interval on
3656 netdev netdevid are delayed until the end of the inter‐
3657 val. Interval is in microseconds. status is optional that
3658 indicate whether the netfilter is on (enabled) or off
3659 (disabled), the default status for netfilter will be
3660 'on'.
3661 queue all|rx|tx is an option that can be applied to any
3663 netfilter.
3664 all: the filter is attached both to the receive and the
3666 transmit queue of the netdev (default).
3667 rx: the filter is attached to the receive queue of the
3669 netdev, where it will receive packets sent to the netdev.
3670 tx: the filter is attached to the transmit queue of the
3672 netdev, where it will receive packets sent by the netdev.
3673 position head|tail|id=<id> is an option to specify where
3675 the filter should be inserted in the filter list. It can
3676 be applied to any netfilter.
3677 head: the filter is inserted at the head of the filter
3679 list, before any existing filters.
3680 tail: the filter is inserted at the tail of the filter
3682 list, behind any existing filters (default).
3683 id=<id>: the filter is inserted before or behind the fil‐
3685 ter specified by <id>, see the insert option below.
3686 insert behind|before is an option to specify where to
3688 insert the new filter relative to the one specified with
3689 position=id=<id>. It can be applied to any netfilter.
3690 before: insert before the specified filter.
3692 behind: insert behind the specified filter (default).
3694 -object filter-mirror,id=id,netdev=netdevid,outdev=charde‐
3696 vid,queue=all|rx|tx[,vnet_hdr_support][,posi‐
3697 tion=head|tail|id=<id>][,insert=behind|before]
3698 filter-mirror on netdev netdevid,mirror net packet to
3699 chardevchardevid, if it has the vnet_hdr_support flag,
3700 filter-mirror will mirror packet with vnet_hdr_len.
3701 -object filter-redirector,id=id,netdev=netdevid,indev=charde‐
3703 vid,outdev=chardevid,queue=all|rx|tx[,vnet_hdr_support][,posi‐
3704 tion=head|tail|id=<id>][,insert=behind|before]
3705 filter-redirector on netdev netdevid,redirect filter's
3706 net packet to chardev chardevid,and redirect indev's
3707 packet to filter.if it has the vnet_hdr_support flag,
3708 filter-redirector will redirect packet with vnet_hdr_len.
3709 Create a filter-redirector we need to differ outdev id
3710 from indev id, id can not be the same. we can just use
3711 indev or outdev, but at least one of indev or outdev need
3712 to be specified.
3713 -object filter-rewriter,id=id,netdev=netde‐
3715 vid,queue=all|rx|tx,[vnet_hdr_support][,posi‐
3716 tion=head|tail|id=<id>][,insert=behind|before]
3717 Filter-rewriter is a part of COLO project.It will rewrite
3718 tcp packet to secondary from primary to keep secondary
3719 tcp connection,and rewrite tcp packet to primary from
3720 secondary make tcp packet can be handled by client.if it
3721 has the vnet_hdr_support flag, we can parse packet with
3722 vnet header.
3723 usage: colo secondary: -object filter-redirec‐
3725 tor,id=f1,netdev=hn0,queue=tx,indev=red0 -object fil‐
3726 ter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
3727 -object filter-rewriter,id=rew0,netdev=hn0,queue=all
3728 -object filter-dump,id=id,netdev=dev[,file=file‐
3730 name][,maxlen=len][,posi‐
3731 tion=head|tail|id=<id>][,insert=behind|before]
3732 Dump the network traffic on netdev dev to the file speci‐
3733 fied by filename. At most len bytes (64k by default) per
3734 packet are stored. The file format is libpcap, so it can
3735 be analyzed with tools such as tcpdump or Wireshark.
3736 -object colo-compare,id=id,primary_in=chardevid,sec‐
3738 ondary_in=chardevid,outdev=chardevid,iothread=id[,vnet_hdr_sup‐
3739 port][,notify_dev=id][,compare_time‐
3740 out=@var{ms}][,expired_scan_cycle=@var{ms}][,max_queue_size=@var{size}]
3741 Colo-compare gets packet from primary_in chardevid and
3742 secondary_in, then compare whether the payload of primary
3743 packet and secondary packet are the same. If same, it
3744 will output primary packet to out_dev, else it will
3745 notify COLO-framework to do checkpoint and send primary
3746 packet to out_dev. In order to improve efficiency, we
3747 need to put the task of comparison in another iothread.
3748 If it has the vnet_hdr_support flag, colo compare will
3749 send/recv packet with vnet_hdr_len. The
3750 compare_timeout=@var{ms} determines the maximum time of
3751 the colo-compare hold the packet. The
3752 expired_scan_cycle=@var{ms} is to set the period of scan‐
3753 ning expired primary node network packets. The
3754 max_queue_size=@var{size} is to set the max compare queue
3755 size depend on user environment. If user want to use Xen
3756 COLO, need to add the notify_dev to notify Xen colo-frame
3757 to do checkpoint.
3758 COLO-compare must be used with the help of filter-mirror,
3760 filter-redirector and filter-rewriter.
3761 KVM COLO
3763 primary:
3765 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
3766 -device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
3767 -chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait
3768 -chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait
3769 -chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait
3770 -chardev socket,id=compare0-0,host=3.3.3.3,port=9001
3771 -chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait
3772 -chardev socket,id=compare_out0,host=3.3.3.3,port=9005
3773 -object iothread,id=iothread1
3774 -object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
3775 -object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
3776 -object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
3777 -object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,iothread=iothread1
3778 secondary:
3780 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
3781 -device e1000,netdev=hn0,mac=52:a4:00:12:78:66
3782 -chardev socket,id=red0,host=3.3.3.3,port=9003
3783 -chardev socket,id=red1,host=3.3.3.3,port=9004
3784 -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
3785 -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
3786 Xen COLO
3789 primary:
3791 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
3792 -device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
3793 -chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait
3794 -chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait
3795 -chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait
3796 -chardev socket,id=compare0-0,host=3.3.3.3,port=9001
3797 -chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait
3798 -chardev socket,id=compare_out0,host=3.3.3.3,port=9005
3799 -chardev socket,id=notify_way,host=3.3.3.3,port=9009,server,nowait
3800 -object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
3801 -object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
3802 -object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
3803 -object iothread,id=iothread1
3804 -object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,notify_dev=nofity_way,iothread=iothread1
3805 secondary:
3807 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
3808 -device e1000,netdev=hn0,mac=52:a4:00:12:78:66
3809 -chardev socket,id=red0,host=3.3.3.3,port=9003
3810 -chardev socket,id=red1,host=3.3.3.3,port=9004
3811 -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
3812 -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
3813 If you want to know the detail of above command line, you
3815 can read the colo-compare git log.
3816 -object cryptodev-backend-builtin,id=id[,queues=queues]
3818 Creates a cryptodev backend which executes crypto
3819 opreation from the QEMU cipher APIS. The id parameter is
3820 a unique ID that will be used to reference this cryptodev
3821 backend from the virtio-crypto device. The queues parame‐
3822 ter is optional, which specify the queue number of cryp‐
3823 todev backend, the default of queues is 1.
3824 # qemu-system-x86_64 [...] -object cryptodev-backend-builtin,id=cryptodev0 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 [...]
3826 -object cryptodev-vhost-user,id=id,chardev=charde‐
3828 vid[,queues=queues]
3829 Creates a vhost-user cryptodev backend, backed by a
3830 chardev chardevid. The id parameter is a unique ID that
3831 will be used to reference this cryptodev backend from the
3832 virtio-crypto device. The chardev should be a unix domain
3833 socket backed one. The vhost-user uses a specifically
3834 defined protocol to pass vhost ioctl replacement messages
3835 to an application on the other end of the socket. The
3836 queues parameter is optional, which specify the queue
3837 number of cryptodev backend for multiqueue vhost-user,
3838 the default of queues is 1.
3839 # qemu-system-x86_64 [...] -chardev socket,id=chardev0,path=/path/to/socket -object cryptodev-vhost-user,id=cryptodev0,chardev=chardev0 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 [...]
3841 -object secret,id=id,data=string,for‐
3843 mat=raw|base64[,keyid=secretid,iv=string]
3844 -object secret,id=id,file=filename,for‐
3847 mat=raw|base64[,keyid=secretid,iv=string]
3848 Defines a secret to store a password, encryption key, or
3849 some other sensitive data. The sensitive data can either
3850 be passed directly via the data parameter, or indirectly
3851 via the file parameter. Using the data parameter is inse‐
3852 cure unless the sensitive data is encrypted.
3853 The sensitive data can be provided in raw format (the
3855 default), or base64. When encoded as JSON, the raw format
3856 only supports valid UTF-8 characters, so base64 is recom‐
3857 mended for sending binary data. QEMU will convert from
3858 which ever format is provided to the format it needs
3859 internally. eg, an RBD password can be provided in raw
3860 format, even though it will be base64 encoded when passed
3861 onto the RBD sever.
3862 For added protection, it is possible to encrypt the data
3864 associated with a secret using the AES-256-CBC cipher.
3865 Use of encryption is indicated by providing the keyid and
3866 iv parameters. The keyid parameter provides the ID of a
3867 previously defined secret that contains the AES-256
3868 decryption key. This key should be 32-bytes long and be
3869 base64 encoded. The iv parameter provides the random ini‐
3870 tialization vector used for encryption of this particular
3871 secret and should be a base64 encrypted string of the
3872 16-byte IV.
3873 The simplest (insecure) usage is to provide the secret
3875 inline
3876 # qemu-system-x86_64 -object secret,id=sec0,data=letmein,format=raw
3878 The simplest secure usage is to provide the secret via a
3880 file
3881 # printf "letmein" > mypasswd.txt # QEMU_SYSTEM_MACRO
3883 -object secret,id=sec0,file=mypasswd.txt,format=raw
3884 For greater security, AES-256-CBC should be used. To
3886 illustrate usage, consider the openssl command line tool
3887 which can encrypt the data. Note that when encrypting,
3888 the plaintext must be padded to the cipher block size (32
3889 bytes) using the standard PKCS#5/6 compatible padding
3890 algorithm.
3891 First a master key needs to be created in base64 encod‐
3893 ing:
3894 # openssl rand -base64 32 > key.b64
3896 # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"')
3897 Each secret to be encrypted needs to have a random ini‐
3899 tialization vector generated. These do not need to be
3900 kept secret
3901 # openssl rand -base64 16 > iv.b64
3903 # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"')
3904 The secret to be defined can now be encrypted, in this
3906 case we're telling openssl to base64 encode the result,
3907 but it could be left as raw bytes if desired.
3908 # SECRET=$(printf "letmein" |
3910 openssl enc -aes-256-cbc -a -K $KEY -iv $IV)
3911 When launching QEMU, create a master secret pointing to
3913 key.b64 and specify that to be used to decrypt the user
3914 password. Pass the contents of iv.b64 to the second
3915 secret
3916 # qemu-system-x86_64 -object secret,id=secmaster0,format=base64,file=key.b64 -object secret,id=sec0,keyid=secmaster0,format=base64, data=$SECRET,iv=$(<iv.b64)
3918 -object sev-guest,id=id,cbitpos=cbit‐
3920 pos,reduced-phys-bits=val,[sev-device=string,policy=policy,han‐
3921 dle=handle,dh-cert-file=file,session-file=file]
3922 Create a Secure Encrypted Virtualization (SEV) guest
3923 object, which can be used to provide the guest memory
3924 encryption support on AMD processors.
3925 When memory encryption is enabled, one of the physical
3927 address bit (aka the C-bit) is utilized to mark if a mem‐
3928 ory page is protected. The cbitpos is used to provide the
3929 C-bit position. The C-bit position is Host family depen‐
3930 dent hence user must provide this value. On EPYC, the
3931 value should be 47.
3932 When memory encryption is enabled, we loose certain bits
3934 in physical address space. The reduced-phys-bits is used
3935 to provide the number of bits we loose in physical
3936 address space. Similar to C-bit, the value is Host fam‐
3937 ily dependent. On EPYC, the value should be 5.
3938 The sev-device provides the device file to use for commu‐
3940 nicating with the SEV firmware running inside AMD Secure
3941 Processor. The default device is '/dev/sev'. If hardware
3942 supports memory encryption then /dev/sev devices are cre‐
3943 ated by CCP driver.
3944 The policy provides the guest policy to be enforced by
3946 the SEV firmware and restrict what configuration and
3947 operational commands can be performed on this guest by
3948 the hypervisor. The policy should be provided by the
3949 guest owner and is bound to the guest and cannot be
3950 changed throughout the lifetime of the guest. The default
3951 is 0.
3952 If guest policy allows sharing the key with another SEV
3954 guest then handle can be use to provide handle of the
3955 guest from which to share the key.
3956 The dh-cert-file and session-file provides the guest
3958 owner's Public Diffie-Hillman key defined in SEV spec.
3959 The PDH and session parameters are used for establishing
3960 a cryptographic session with the guest owner to negotiate
3961 keys used for attestation. The file must be encoded in
3962 base64.
3963 e.g to launch a SEV guest
3965 # qemu_system-x86_64 ......
3967 -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=5 -machine ...,memory-encryption=sev0
3968 .....
3969 -object authz-simple,id=id,identity=string
3971 Create an authorization object that will control access
3972 to network services.
3973 The identity parameter is identifies the user and its
3975 format depends on the network service that authorization
3976 object is associated with. For authorizing based on TLS
3977 x509 certificates, the identity must be the x509 distin‐
3978 guished name. Note that care must be taken to escape any
3979 commas in the distinguished name.
3980 An example authorization object to validate a x509 dis‐
3982 tinguished name would look like:
3983 # qemu-system-x86_64 ...
3985 -object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,O=Example Org,,L=London,,ST=London,,C=GB' ...
3986 Note the use of quotes due to the x509 distinguished name
3988 containing whitespace, and escaping of ','.
3989 -object authz-listfile,id=id,filename=path,refresh=yes|no
3991 Create an authorization object that will control access
3992 to network services.
3993 The filename parameter is the fully qualified path to a
3995 file containing the access control list rules in JSON
3996 format.
3997 An example set of rules that match against SASL usernames
3999 might look like:
4000 {
4002 "rules": [
4003 { "match": "fred", "policy": "allow", "format": "exact" },
4004 { "match": "bob", "policy": "allow", "format": "exact" },
4005 { "match": "danb", "policy": "deny", "format": "glob" },
4006 { "match": "dan*", "policy": "allow", "format": "exact" },
4007 ],
4008 "policy": "deny"
4009 }
4010 When checking access the object will iterate over all the
4012 rules and the first rule to match will have its policy
4013 value returned as the result. If no rules match, then the
4014 default policy value is returned.
4015 The rules can either be an exact string match, or they
4017 can use the simple UNIX glob pattern matching to allow
4018 wildcards to be used.
4019 If refresh is set to true the file will be monitored and
4021 automatically reloaded whenever its content changes.
4022 As with the authz-simple object, the format of the iden‐
4024 tity strings being matched depends on the network ser‐
4025 vice, but is usually a TLS x509 distinguished name, or a
4026 SASL username.
4027 An example authorization object to validate a SASL user‐
4029 name would look like:
4030 # qemu-system-x86_64 ...
4032 -object authz-simple,id=auth0,filename=/etc/qemu/vnc-sasl.acl,refresh=yes
4033 ...
4034 -object authz-pam,id=id,service=string
4036 Create an authorization object that will control access
4037 to network services.
4038 The service parameter provides the name of a PAM service
4040 to use for authorization. It requires that a file
4041 /etc/pam.d/service exist to provide the configuration for
4042 the account subsystem.
4043 An example authorization object to validate a TLS x509
4045 distinguished name would look like:
4046 # qemu-system-x86_64 ...
4048 -object authz-pam,id=auth0,service=qemu-vnc
4049 ...
4050 There would then be a corresponding config file for PAM
4052 at /etc/pam.d/qemu-vnc that contains:
4053 account requisite pam_listfile.so item=user sense=allow \
4055 file=/etc/qemu/vnc.allow
4056 Finally the /etc/qemu/vnc.allow file would contain the
4058 list of x509 distingished names that are permitted access
4059 CN=laptop.example.com,O=Example Home,L=London,ST=London,C=GB
4061 -object
4063 iothread,id=id,poll-max-ns=poll-max-ns,poll-grow=poll-grow,poll-shrink=poll-shrink
4064 Creates a dedicated event loop thread that devices can be
4065 assigned to. This is known as an IOThread. By default
4066 device emulation happens in vCPU threads or the main
4067 event loop thread. This can become a scalability bottle‐
4068 neck. IOThreads allow device emulation and I/O to run on
4069 other host CPUs.
4070 The id parameter is a unique ID that will be used to ref‐
4072 erence this IOThread from -device ...,iothread=id. Mul‐
4073 tiple devices can be assigned to an IOThread. Note that
4074 not all devices support an iothread parameter.
4075 The query-iothreads QMP command lists IOThreads and
4077 reports their thread IDs so that the user can configure
4078 host CPU pinning/affinity.
4079 IOThreads use an adaptive polling algorithm to reduce
4081 event loop latency. Instead of entering a blocking system
4082 call to monitor file descriptors and then pay the cost of
4083 being woken up when an event occurs, the polling algo‐
4084 rithm spins waiting for events for a short time. The
4085 algorithm's default parameters are suitable for many
4086 cases but can be adjusted based on knowledge of the work‐
4087 load and/or host device latency.
4088 The poll-max-ns parameter is the maximum number of
4090 nanoseconds to busy wait for events. Polling can be dis‐
4091 abled by setting this value to 0.
4092 The poll-grow parameter is the multiplier used to
4094 increase the polling time when the algorithm detects it
4095 is missing events due to not polling long enough.
4096 The poll-shrink parameter is the divisor used to decrease
4098 the polling time when the algorithm detects it is spend‐
4099 ing too long polling without encountering events.
4100 The polling parameters can be modified at run-time using
4102 the qom-set command (where iothread1 is the IOThread's
4103 id):
4104 (qemu) qom-set /objects/iothread1 poll-max-ns 100000
4106 During the graphical emulation, you can use special key combinations to
4108 change modes. The default key mappings are shown below, but if you use
4109 -alt-grab then the modifier is Ctrl-Alt-Shift (instead of Ctrl-Alt) and
4110 if you use -ctrl-grab then the modifier is the right Ctrl key (instead
4111 of Ctrl-Alt):
4112 Ctrl-Alt-f
4114 Toggle full screen
4115 Ctrl-Alt-+
4117 Enlarge the screen
4118 Ctrl-Alt--
4120 Shrink the screen
4121 Ctrl-Alt-u
4123 Restore the screen's un-scaled dimensions
4124 Ctrl-Alt-n
4126 Switch to virtual console 'n'. Standard console mappings are:
4127 1 Target system display
4129 2 Monitor
4131 3 Serial port
4133 Ctrl-Alt
4135 Toggle mouse and keyboard grab.
4136 In the virtual consoles, you can use Ctrl-Up, Ctrl-Down, Ctrl-PageUp
4138 and Ctrl-PageDown to move in the back log.
4139 During emulation, if you are using a character backend multiplexer
4141 (which is the default if you are using -nographic) then several com‐
4142 mands are available via an escape sequence. These key sequences all
4143 start with an escape character, which is Ctrl-a by default, but can be
4144 changed with -echr. The list below assumes you're using the default.
4145 Ctrl-a h
4147 Print this help
4148 Ctrl-a x
4150 Exit emulator
4151 Ctrl-a s
4153 Save disk data back to file (if -snapshot)
4154 Ctrl-a t
4156 Toggle console timestamps
4157 Ctrl-a b
4159 Send break (magic sysrq in Linux)
4160 Ctrl-a c
4162 Rotate between the frontends connected to the multiplexer (usu‐
4163 ally this switches between the monitor and the console)
4164 Ctrl-a Ctrl-a
4166 Send the escape character to the frontend
4167
4169 In addition to using normal file images for the emulated storage
4170 devices, QEMU can also use networked resources such as iSCSI devices.
4171 These are specified using a special URL syntax.
4172 iSCSI iSCSI support allows QEMU to access iSCSI resources directly and
4174 use as images for the guest storage. Both disk and cdrom images
4175 are supported.
4176 Syntax for specifying iSCSI LUNs is "iscsi://<tar‐
4178 get-ip>[:<port>]/<target-iqn>/<lun>"
4179 By default qemu will use the iSCSI initiator-name
4181 'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set
4182 from the command line or a configuration file.
4183 Since version Qemu 2.4 it is possible to specify a iSCSI request
4185 timeout to detect stalled requests and force a reestablishment
4186 of the session. The timeout is specified in seconds. The default
4187 is 0 which means no timeout. Libiscsi 1.15.0 or greater is
4188 required for this feature.
4189 Example (without authentication):
4191 qemu-system-x86_64 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
4193 Example (CHAP username/password via URL):
4195 qemu-system-x86_64 -drive file=iscsi://user%password@192.0.2.1/iqn.2001-04.com.example/1
4197 Example (CHAP username/password via environment variables):
4199 LIBISCSI_CHAP_USERNAME="user" LIBISCSI_CHAP_PASSWORD="password" qemu-system-x86_64 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
4201 NBD QEMU supports NBD (Network Block Devices) both using TCP proto‐
4203 col as well as Unix Domain Sockets. With TCP, the default port
4204 is 10809.
4205 Syntax for specifying a NBD device using TCP, in preferred URI
4207 form: "nbd://<server-ip>[:<port>]/[<export>]"
4208 Syntax for specifying a NBD device using Unix Domain Sockets;
4210 remember that '?' is a shell glob character and may need quot‐
4211 ing: "nbd+unix:///[<export>]?socket=<domain-socket>"
4212 Older syntax that is also recognized:
4214 "nbd:<server-ip>:<port>[:exportname=<export>]"
4215 Syntax for specifying a NBD device using Unix Domain Sockets
4217 "nbd:unix:<domain-socket>[:exportname=<export>]"
4218 Example for TCP
4220 qemu-system-x86_64 --drive file=nbd:192.0.2.1:30000
4222 Example for Unix Domain Sockets
4224 qemu-system-x86_64 --drive file=nbd:unix:/tmp/nbd-socket
4226 SSH QEMU supports SSH (Secure Shell) access to remote disks.
4228 Examples:
4230 qemu-system-x86_64 -drive file=ssh://user@host/path/to/disk.img
4232 qemu-system-x86_64 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
4233 Currently authentication must be done using ssh-agent. Other
4235 authentication methods may be supported in future.
4236 Sheepdog
4238 Sheepdog is a distributed storage system for QEMU. QEMU supports
4239 using either local sheepdog devices or remote networked devices.
4240 Syntax for specifying a sheepdog device
4242 sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
4244 Example
4246 qemu-system-x86_64 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
4248 See also https://sheepdog.github.io/sheepdog/.
4250 GlusterFS
4252 GlusterFS is a user space distributed file system. QEMU supports
4253 the use of GlusterFS volumes for hosting VM disk images using
4254 TCP, Unix Domain Sockets and RDMA transport protocols.
4255 Syntax for specifying a VM disk image on GlusterFS volume is
4257 URI:
4259 gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
4260 JSON:
4262 'json:{"driver":"qcow2","file":{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...",
4263 "server":[{"type":"tcp","host":"...","port":"..."},
4264 {"type":"unix","socket":"..."}]}}'
4265 Example
4267 URI:
4269 qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img,
4270 file.debug=9,file.logfile=/var/log/qemu-gluster.log
4271 JSON:
4273 qemu-system-x86_64 'json:{"driver":"qcow2",
4274 "file":{"driver":"gluster",
4275 "volume":"testvol","path":"a.img",
4276 "debug":9,"logfile":"/var/log/qemu-gluster.log",
4277 "server":[{"type":"tcp","host":"1.2.3.4","port":24007},
4278 {"type":"unix","socket":"/var/run/glusterd.socket"}]}}'
4279 qemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
4280 file.debug=9,file.logfile=/var/log/qemu-gluster.log,
4281 file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
4282 file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
4283 See also http://www.gluster.org.
4285 HTTP/HTTPS/FTP/FTPS
4287 QEMU supports read-only access to files accessed over http(s)
4288 and ftp(s).
4289 Syntax using a single filename:
4291 <protocol>://[<username>[:<password>]@]<host>/<path>
4293 where:
4295 protocol
4297 'http', 'https', 'ftp', or 'ftps'.
4298 username
4300 Optional username for authentication to the remote
4301 server.
4302 password
4304 Optional password for authentication to the remote
4305 server.
4306 host Address of the remote server.
4308 path Path on the remote server, including any query string.
4310 The following options are also supported:
4312 url The full URL when passing options to the driver explic‐
4314 itly.
4315 readahead
4317 The amount of data to read ahead with each range request
4318 to the remote server. This value may optionally have the
4319 suffix 'T', 'G', 'M', 'K', 'k' or 'b'. If it does not
4320 have a suffix, it will be assumed to be in bytes. The
4321 value must be a multiple of 512 bytes. It defaults to
4322 256k.
4323 sslverify
4325 Whether to verify the remote server's certificate when
4326 connecting over SSL. It can have the value 'on' or 'off'.
4327 It defaults to 'on'.
4328 cookie Send this cookie (it can also be a list of cookies sepa‐
4330 rated by ';') with each outgoing request. Only supported
4331 when using protocols such as HTTP which support cookies,
4332 otherwise ignored.
4333 timeout
4335 Set the timeout in seconds of the CURL connection. This
4336 timeout is the time that CURL waits for a response from
4337 the remote server to get the size of the image to be
4338 downloaded. If not set, the default timeout of 5 seconds
4339 is used.
4340 Note that when passing options to qemu explicitly, driver is the
4342 value of <protocol>.
4343 Example: boot from a remote Fedora 20 live ISO image
4345 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
4347 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
4349 Example: boot from a remote Fedora 20 cloud image using a local
4351 overlay for writes, copy-on-read, and a readahead of 64k
4352 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
4354 qemu_system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
4356 Example: boot from an image stored on a VMware vSphere server
4358 with a self-signed certificate using a local overlay for writes,
4359 a readahead of 64k and a timeout of 10 seconds.
4360 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
4362 qemu_system-x86_64 -drive file=/tmp/test.qcow2
4364
4366 The HTML documentation of QEMU for more precise information and Linux
4367 user mode emulator invocation.
4368
4370 Fabrice Bellard
4371
4373 2021, The QEMU Project Developers
43745.1.0 Jan 11, 2021 QEMU(1)