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