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