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