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