1QEMU.1(1) QEMU.1(1)
2
6 qemu-doc - QEMU version 4.2.0 User Documentation
7
9 qemu-system-x86_64 [options] [disk_image]
10
12 The QEMU PC System emulator simulates the following peripherals:
13 - i440FX host PCI bridge and PIIX3 PCI to ISA bridge
15 - Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
17 extensions (hardware level, including all non standard modes).
18 - PS/2 mouse and keyboard
20 - 2 PCI IDE interfaces with hard disk and CD-ROM support
22 - Floppy disk
24 - PCI and ISA network adapters
26 - Serial ports
28 - IPMI BMC, either and internal or external one
30 - Creative SoundBlaster 16 sound card
32 - ENSONIQ AudioPCI ES1370 sound card
34 - Intel 82801AA AC97 Audio compatible sound card
36 - Intel HD Audio Controller and HDA codec
38 - Adlib (OPL2) - Yamaha YM3812 compatible chip
40 - Gravis Ultrasound GF1 sound card
42 - CS4231A compatible sound card
44 - PCI UHCI, OHCI, EHCI or XHCI USB controller and a virtual USB-1.1
46 hub.
47 SMP is supported with up to 255 CPUs.
49 QEMU uses the PC BIOS from the Seabios project and the Plex86/Bochs
51 LGPL VGA BIOS.
52 QEMU uses YM3812 emulation by Tatsuyuki Satoh.
54 QEMU uses GUS emulation (GUSEMU32 <http://www.deinmeister.de/gusemu/>)
56 by Tibor "TS" Schütz.
57 Note that, by default, GUS shares IRQ(7) with parallel ports and so
59 QEMU must be told to not have parallel ports to have working GUS.
60 qemu-system-x86_64 dos.img -soundhw gus -parallel none
62 Alternatively:
64 qemu-system-x86_64 dos.img -device gus,irq=5
66 Or some other unclaimed IRQ.
68 CS4231A is the chip used in Windows Sound System and GUSMAX products
70
72 disk_image is a raw hard disk image for IDE hard disk 0. Some targets
73 do not need a disk image.
74 Standard options
76 -h Display help and exit
78 -version
80 Display version information and exit
81 -machine [type=]name[,prop=value[,...]]
83 Select the emulated machine by name. Use "-machine help" to list
84 available machines.
85 For architectures which aim to support live migration compatibility
87 across releases, each release will introduce a new versioned
88 machine type. For example, the 2.8.0 release introduced machine
89 types "pc-i440fx-2.8" and "pc-q35-2.8" for the x86_64/i686
90 architectures.
91 To allow live migration of guests from QEMU version 2.8.0, to QEMU
93 version 2.9.0, the 2.9.0 version must support the "pc-i440fx-2.8"
94 and "pc-q35-2.8" machines too. To allow users live migrating VMs to
95 skip multiple intermediate releases when upgrading, new releases of
96 QEMU will support machine types from many previous versions.
97 Supported machine properties are:
99 accel=accels1[:accels2[:...]]
101 This is used to enable an accelerator. Depending on the target
102 architecture, kvm, xen, hax, hvf, whpx or tcg can be available.
103 By default, tcg is used. If there is more than one accelerator
104 specified, the next one is used if the previous one fails to
105 initialize.
106 kernel_irqchip=on|off
108 Controls in-kernel irqchip support for the chosen accelerator
109 when available.
110 gfx_passthru=on|off
112 Enables IGD GFX passthrough support for the chosen machine when
113 available.
114 vmport=on|off|auto
116 Enables emulation of VMWare IO port, for vmmouse etc. auto says
117 to select the value based on accel. For accel=xen the default
118 is off otherwise the default is on.
119 kvm_shadow_mem=size
121 Defines the size of the KVM shadow MMU.
122 dump-guest-core=on|off
124 Include guest memory in a core dump. The default is on.
125 mem-merge=on|off
127 Enables or disables memory merge support. This feature, when
128 supported by the host, de-duplicates identical memory pages
129 among VMs instances (enabled by default).
130 aes-key-wrap=on|off
132 Enables or disables AES key wrapping support on s390-ccw hosts.
133 This feature controls whether AES wrapping keys will be created
134 to allow execution of AES cryptographic functions. The default
135 is on.
136 dea-key-wrap=on|off
138 Enables or disables DEA key wrapping support on s390-ccw hosts.
139 This feature controls whether DEA wrapping keys will be created
140 to allow execution of DEA cryptographic functions. The default
141 is on.
142 nvdimm=on|off
144 Enables or disables NVDIMM support. The default is off.
145 enforce-config-section=on|off
147 If enforce-config-section is set to on, force migration code to
148 send configuration section even if the machine-type sets the
149 migration.send-configuration property to off. NOTE: this
150 parameter is deprecated. Please use -global
151 migration.send-configuration=on|off instead.
152 memory-encryption=
154 Memory encryption object to use. The default is none.
155 -cpu model
157 Select CPU model ("-cpu help" for list and additional feature
158 selection)
159 -accel name[,prop=value[,...]]
161 This is used to enable an accelerator. Depending on the target
162 architecture, kvm, xen, hax, hvf, whpx or tcg can be available. By
163 default, tcg is used. If there is more than one accelerator
164 specified, the next one is used if the previous one fails to
165 initialize.
166 thread=single|multi
168 Controls number of TCG threads. When the TCG is multi-threaded
169 there will be one thread per vCPU therefor taking advantage of
170 additional host cores. The default is to enable multi-threading
171 where both the back-end and front-ends support it and no
172 incompatible TCG features have been enabled (e.g.
173 icount/replay).
174 -smp
176 [cpus=]n[,cores=cores][,threads=threads][,dies=dies][,sockets=sockets][,maxcpus=maxcpus]
177 Simulate an SMP system with n CPUs. On the PC target, up to 255
178 CPUs are supported. On Sparc32 target, Linux limits the number of
179 usable CPUs to 4. For the PC target, the number of cores per die,
180 the number of threads per cores, the number of dies per packages
181 and the total number of sockets can be specified. Missing values
182 will be computed. If any on the three values is given, the total
183 number of CPUs n can be omitted. maxcpus specifies the maximum
184 number of hotpluggable CPUs.
185 -numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node]
187 -numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node]
188 -numa dist,src=source,dst=destination,val=distance
189 -numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]
190 Define a NUMA node and assign RAM and VCPUs to it. Set the NUMA
191 distance from a source node to a destination node.
192 Legacy VCPU assignment uses cpus option where firstcpu and lastcpu
194 are CPU indexes. Each cpus option represent a contiguous range of
195 CPU indexes (or a single VCPU if lastcpu is omitted). A non-
196 contiguous set of VCPUs can be represented by providing multiple
197 cpus options. If cpus is omitted on all nodes, VCPUs are
198 automatically split between them.
199 For example, the following option assigns VCPUs 0, 1, 2 and 5 to a
201 NUMA node:
202 -numa node,cpus=0-2,cpus=5
204 cpu option is a new alternative to cpus option which uses
206 socket-id|core-id|thread-id properties to assign CPU objects to a
207 node using topology layout properties of CPU. The set of
208 properties is machine specific, and depends on used machine
209 type/smp options. It could be queried with hotpluggable-cpus
210 monitor command. node-id property specifies node to which CPU
211 object will be assigned, it's required for node to be declared with
212 node option before it's used with cpu option.
213 For example:
215 -M pc \
217 -smp 1,sockets=2,maxcpus=2 \
218 -numa node,nodeid=0 -numa node,nodeid=1 \
219 -numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1
220 mem assigns a given RAM amount to a node. memdev assigns RAM from a
222 given memory backend device to a node. If mem and memdev are
223 omitted in all nodes, RAM is split equally between them.
224 mem and memdev are mutually exclusive. Furthermore, if one node
226 uses memdev, all of them have to use it.
227 source and destination are NUMA node IDs. distance is the NUMA
229 distance from source to destination. The distance from a node to
230 itself is always 10. If any pair of nodes is given a distance, then
231 all pairs must be given distances. Although, when distances are
232 only given in one direction for each pair of nodes, then the
233 distances in the opposite directions are assumed to be the same.
234 If, however, an asymmetrical pair of distances is given for even
235 one node pair, then all node pairs must be provided distance values
236 for both directions, even when they are symmetrical. When a node is
237 unreachable from another node, set the pair's distance to 255.
238 Note that the -numa option doesn't allocate any of the specified
240 resources, it just assigns existing resources to NUMA nodes. This
241 means that one still has to use the -m, -smp options to allocate
242 RAM and VCPUs respectively.
243 -add-fd fd=fd,set=set[,opaque=opaque]
245 Add a file descriptor to an fd set. Valid options are:
246 fd=fd
248 This option defines the file descriptor of which a duplicate is
249 added to fd set. The file descriptor cannot be stdin, stdout,
250 or stderr.
251 set=set
253 This option defines the ID of the fd set to add the file
254 descriptor to.
255 opaque=opaque
257 This option defines a free-form string that can be used to
258 describe fd.
259 You can open an image using pre-opened file descriptors from an fd
261 set:
262 qemu-system-x86_64 \
264 -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \
265 -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \
266 -drive file=/dev/fdset/2,index=0,media=disk
267 -set group.id.arg=value
269 Set parameter arg for item id of type group
270 -global driver.prop=value
272 -global driver=driver,property=property,value=value
273 Set default value of driver's property prop to value, e.g.:
274 qemu-system-x86_64 -global ide-hd.physical_block_size=4096 disk-image.img
276 In particular, you can use this to set driver properties for
278 devices which are created automatically by the machine model. To
279 create a device which is not created automatically and set
280 properties on it, use -device.
281 -global driver.prop=value is shorthand for -global
283 driver=driver,property=prop,value=value. The longhand syntax works
284 even when driver contains a dot.
285 -boot
287 [order=drives][,once=drives][,menu=on|off][,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_timeout][,strict=on|off]
288 Specify boot order drives as a string of drive letters. Valid drive
289 letters depend on the target architecture. The x86 PC uses: a, b
290 (floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p
291 (Etherboot from network adapter 1-4), hard disk boot is the
292 default. To apply a particular boot order only on the first
293 startup, specify it via once. Note that the order or once parameter
294 should not be used together with the bootindex property of devices,
295 since the firmware implementations normally do not support both at
296 the same time.
297 Interactive boot menus/prompts can be enabled via menu=on as far as
299 firmware/BIOS supports them. The default is non-interactive boot.
300 A splash picture could be passed to bios, enabling user to show it
302 as logo, when option splash=sp_name is given and menu=on, If
303 firmware/BIOS supports them. Currently Seabios for X86 system
304 support it. limitation: The splash file could be a jpeg file or a
305 BMP file in 24 BPP format(true color). The resolution should be
306 supported by the SVGA mode, so the recommended is 320x240, 640x480,
307 800x640.
308 A timeout could be passed to bios, guest will pause for rb_timeout
310 ms when boot failed, then reboot. If reboot-timeout is not set,
311 guest will not reboot by default. Currently Seabios for X86 system
312 support it.
313 Do strict boot via strict=on as far as firmware/BIOS supports it.
315 This only effects when boot priority is changed by bootindex
316 options. The default is non-strict boot.
317 # try to boot from network first, then from hard disk
319 qemu-system-x86_64 -boot order=nc
320 # boot from CD-ROM first, switch back to default order after reboot
321 qemu-system-x86_64 -boot once=d
322 # boot with a splash picture for 5 seconds.
323 qemu-system-x86_64 -boot menu=on,splash=/root/boot.bmp,splash-time=5000
324 Note: The legacy format '-boot drives' is still supported but its
326 use is discouraged as it may be removed from future versions.
327 -m [size=]megs[,slots=n,maxmem=size]
329 Sets guest startup RAM size to megs megabytes. Default is 128 MiB.
330 Optionally, a suffix of "M" or "G" can be used to signify a value
331 in megabytes or gigabytes respectively. Optional pair slots, maxmem
332 could be used to set amount of hotpluggable memory slots and
333 maximum amount of memory. Note that maxmem must be aligned to the
334 page size.
335 For example, the following command-line sets the guest startup RAM
337 size to 1GB, creates 3 slots to hotplug additional memory and sets
338 the maximum memory the guest can reach to 4GB:
339 qemu-system-x86_64 -m 1G,slots=3,maxmem=4G
341 If slots and maxmem are not specified, memory hotplug won't be
343 enabled and the guest startup RAM will never increase.
344 -mem-path path
346 Allocate guest RAM from a temporarily created file in path.
347 -mem-prealloc
349 Preallocate memory when using -mem-path.
350 -k language
352 Use keyboard layout language (for example "fr" for French). This
353 option is only needed where it is not easy to get raw PC keycodes
354 (e.g. on Macs, with some X11 servers or with a VNC or curses
355 display). You don't normally need to use it on PC/Linux or
356 PC/Windows hosts.
357 The available layouts are:
359 ar de-ch es fo fr-ca hu ja mk no pt-br sv
361 da en-gb et fr fr-ch is lt nl pl ru th
362 de en-us fi fr-be hr it lv nl-be pt sl tr
363 The default is "en-us".
365 -audio-help
367 Will show the -audiodev equivalent of the currently specified
368 (deprecated) environment variables.
369 -audiodev [driver=]driver,id=id[,prop[=value][,...]]
371 Adds a new audio backend driver identified by id. There are global
372 and driver specific properties. Some values can be set differently
373 for input and output, they're marked with "in|out.". You can set
374 the input's property with "in.prop" and the output's property with
375 "out.prop". For example:
376 -audiodev alsa,id=example,in.frequency=44110,out.frequency=8000
378 -audiodev alsa,id=example,out.channels=1 # leaves in.channels unspecified
379 NOTE: parameter validation is known to be incomplete, in many cases
381 specifying an invalid option causes QEMU to print an error message
382 and continue emulation without sound.
383 Valid global options are:
385 id=identifier
387 Identifies the audio backend.
388 timer-period=period
390 Sets the timer period used by the audio subsystem in
391 microseconds. Default is 10000 (10 ms).
392 in|out.mixing-engine=on|off
394 Use QEMU's mixing engine to mix all streams inside QEMU and
395 convert audio formats when not supported by the backend. When
396 off, fixed-settings must be off too. Note that disabling this
397 option means that the selected backend must support multiple
398 streams and the audio formats used by the virtual cards,
399 otherwise you'll get no sound. It's not recommended to disable
400 this option unless you want to use 5.1 or 7.1 audio, as mixing
401 engine only supports mono and stereo audio. Default is on.
402 in|out.fixed-settings=on|off
404 Use fixed settings for host audio. When off, it will change
405 based on how the guest opens the sound card. In this case you
406 must not specify frequency, channels or format. Default is on.
407 in|out.frequency=frequency
409 Specify the frequency to use when using fixed-settings.
410 Default is 44100Hz.
411 in|out.channels=channels
413 Specify the number of channels to use when using fixed-
414 settings. Default is 2 (stereo).
415 in|out.format=format
417 Specify the sample format to use when using fixed-settings.
418 Valid values are: "s8", "s16", "s32", "u8", "u16", "u32".
419 Default is "s16".
420 in|out.voices=voices
422 Specify the number of voices to use. Default is 1.
423 in|out.buffer-length=usecs
425 Sets the size of the buffer in microseconds.
426 -audiodev none,id=id[,prop[=value][,...]]
428 Creates a dummy backend that discards all outputs. This backend
429 has no backend specific properties.
430 -audiodev alsa,id=id[,prop[=value][,...]]
432 Creates backend using the ALSA. This backend is only available on
433 Linux.
434 ALSA specific options are:
436 in|out.dev=device
438 Specify the ALSA device to use for input and/or output.
439 Default is "default".
440 in|out.period-length=usecs
442 Sets the period length in microseconds.
443 in|out.try-poll=on|off
445 Attempt to use poll mode with the device. Default is on.
446 threshold=threshold
448 Threshold (in microseconds) when playback starts. Default is
449 0.
450 -audiodev coreaudio,id=id[,prop[=value][,...]]
452 Creates a backend using Apple's Core Audio. This backend is only
453 available on Mac OS and only supports playback.
454 Core Audio specific options are:
456 in|out.buffer-count=count
458 Sets the count of the buffers.
459 -audiodev dsound,id=id[,prop[=value][,...]]
461 Creates a backend using Microsoft's DirectSound. This backend is
462 only available on Windows and only supports playback.
463 DirectSound specific options are:
465 latency=usecs
467 Add extra usecs microseconds latency to playback. Default is
468 10000 (10 ms).
469 -audiodev oss,id=id[,prop[=value][,...]]
471 Creates a backend using OSS. This backend is available on most
472 Unix-like systems.
473 OSS specific options are:
475 in|out.dev=device
477 Specify the file name of the OSS device to use. Default is
478 "/dev/dsp".
479 in|out.buffer-count=count
481 Sets the count of the buffers.
482 in|out.try-poll=on|of
484 Attempt to use poll mode with the device. Default is on.
485 try-mmap=on|off
487 Try using memory mapped device access. Default is off.
488 exclusive=on|off
490 Open the device in exclusive mode (vmix won't work in this
491 case). Default is off.
492 dsp-policy=policy
494 Sets the timing policy (between 0 and 10, where smaller number
495 means smaller latency but higher CPU usage). Use -1 to use
496 buffer sizes specified by "buffer" and "buffer-count". This
497 option is ignored if you do not have OSS 4. Default is 5.
498 -audiodev pa,id=id[,prop[=value][,...]]
500 Creates a backend using PulseAudio. This backend is available on
501 most systems.
502 PulseAudio specific options are:
504 server=server
506 Sets the PulseAudio server to connect to.
507 in|out.name=sink
509 Use the specified source/sink for recording/playback.
510 in|out.latency=usecs
512 Desired latency in microseconds. The PulseAudio server will
513 try to honor this value but actual latencies may be lower or
514 higher.
515 -audiodev sdl,id=id[,prop[=value][,...]]
517 Creates a backend using SDL. This backend is available on most
518 systems, but you should use your platform's native backend if
519 possible. This backend has no backend specific properties.
520 -audiodev spice,id=id[,prop[=value][,...]]
522 Creates a backend that sends audio through SPICE. This backend
523 requires "-spice" and automatically selected in that case, so
524 usually you can ignore this option. This backend has no backend
525 specific properties.
526 -audiodev wav,id=id[,prop[=value][,...]]
528 Creates a backend that writes audio to a WAV file.
529 Backend specific options are:
531 path=path
533 Write recorded audio into the specified file. Default is
534 "qemu.wav".
535 -soundhw card1[,card2,...] or -soundhw all
537 Enable audio and selected sound hardware. Use 'help' to print all
538 available sound hardware. For example:
539 qemu-system-x86_64 -soundhw sb16,adlib disk.img
541 qemu-system-x86_64 -soundhw es1370 disk.img
542 qemu-system-x86_64 -soundhw ac97 disk.img
543 qemu-system-x86_64 -soundhw hda disk.img
544 qemu-system-x86_64 -soundhw all disk.img
545 qemu-system-x86_64 -soundhw help
546 Note that Linux's i810_audio OSS kernel (for AC97) module might
548 require manually specifying clocking.
549 modprobe i810_audio clocking=48000
551 -device driver[,prop[=value][,...]]
553 Add device driver. prop=value sets driver properties. Valid
554 properties depend on the driver. To get help on possible drivers
555 and properties, use "-device help" and "-device driver,help".
556 Some drivers are:
558 -device
560 ipmi-bmc-sim,id=id[,slave_addr=val][,sdrfile=file][,furareasize=val][,furdatafile=file][,guid=uuid]
561 Add an IPMI BMC. This is a simulation of a hardware management
562 interface processor that normally sits on a system. It provides a
563 watchdog and the ability to reset and power control the system.
564 You need to connect this to an IPMI interface to make it useful
565 The IPMI slave address to use for the BMC. The default is 0x20.
567 This address is the BMC's address on the I2C network of management
568 controllers. If you don't know what this means, it is safe to
569 ignore it.
570 id=id
572 The BMC id for interfaces to use this device.
573 slave_addr=val
575 Define slave address to use for the BMC. The default is 0x20.
576 sdrfile=file
578 file containing raw Sensor Data Records (SDR) data. The default
579 is none.
580 fruareasize=val
582 size of a Field Replaceable Unit (FRU) area. The default is
583 1024.
584 frudatafile=file
586 file containing raw Field Replaceable Unit (FRU) inventory
587 data. The default is none.
588 guid=uuid
590 value for the GUID for the BMC, in standard UUID format. If
591 this is set, get "Get GUID" command to the BMC will return it.
592 Otherwise "Get GUID" will return an error.
593 -device ipmi-bmc-extern,id=id,chardev=id[,slave_addr=val]
595 Add a connection to an external IPMI BMC simulator. Instead of
596 locally emulating the BMC like the above item, instead connect to
597 an external entity that provides the IPMI services.
598 A connection is made to an external BMC simulator. If you do this,
600 it is strongly recommended that you use the "reconnect=" chardev
601 option to reconnect to the simulator if the connection is lost.
602 Note that if this is not used carefully, it can be a security
603 issue, as the interface has the ability to send resets, NMIs, and
604 power off the VM. It's best if QEMU makes a connection to an
605 external simulator running on a secure port on localhost, so
606 neither the simulator nor QEMU is exposed to any outside network.
607 See the "lanserv/README.vm" file in the OpenIPMI library for more
609 details on the external interface.
610 -device isa-ipmi-kcs,bmc=id[,ioport=val][,irq=val]
612 Add a KCS IPMI interafce on the ISA bus. This also adds a
613 corresponding ACPI and SMBIOS entries, if appropriate.
614 bmc=id
616 The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern
617 above.
618 ioport=val
620 Define the I/O address of the interface. The default is 0xca0
621 for KCS.
622 irq=val
624 Define the interrupt to use. The default is 5. To disable
625 interrupts, set this to 0.
626 -device isa-ipmi-bt,bmc=id[,ioport=val][,irq=val]
628 Like the KCS interface, but defines a BT interface. The default
629 port is 0xe4 and the default interrupt is 5.
630 -name name
632 Sets the name of the guest. This name will be displayed in the SDL
633 window caption. The name will also be used for the VNC server.
634 Also optionally set the top visible process name in Linux. Naming
635 of individual threads can also be enabled on Linux to aid
636 debugging.
637 -uuid uuid
639 Set system UUID.
640 Block device options
642 -fda file
644 -fdb file
645 Use file as floppy disk 0/1 image.
646 -hda file
648 -hdb file
649 -hdc file
650 -hdd file
651 Use file as hard disk 0, 1, 2 or 3 image.
652 -cdrom file
654 Use file as CD-ROM image (you cannot use -hdc and -cdrom at the
655 same time). You can use the host CD-ROM by using /dev/cdrom as
656 filename.
657 -blockdev option[,option[,option[,...]]]
659 Define a new block driver node. Some of the options apply to all
660 block drivers, other options are only accepted for a specific block
661 driver. See below for a list of generic options and options for the
662 most common block drivers.
663 Options that expect a reference to another node (e.g. "file") can
665 be given in two ways. Either you specify the node name of an
666 already existing node (file=node-name), or you define a new node
667 inline, adding options for the referenced node after a dot
668 (file.filename=path,file.aio=native).
669 A block driver node created with -blockdev can be used for a guest
671 device by specifying its node name for the "drive" property in a
672 -device argument that defines a block device.
673 Valid options for any block driver node:
675 "driver"
676 Specifies the block driver to use for the given node.
677 "node-name"
679 This defines the name of the block driver node by which it
680 will be referenced later. The name must be unique, i.e. it
681 must not match the name of a different block driver node,
682 or (if you use -drive as well) the ID of a drive.
683 If no node name is specified, it is automatically
685 generated. The generated node name is not intended to be
686 predictable and changes between QEMU invocations. For the
687 top level, an explicit node name must be specified.
688 "read-only"
690 Open the node read-only. Guest write attempts will fail.
691 Note that some block drivers support only read-only access,
693 either generally or in certain configurations. In this
694 case, the default value read-only=off does not work and the
695 option must be specified explicitly.
696 "auto-read-only"
698 If auto-read-only=on is set, QEMU may fall back to read-
699 only usage even when read-only=off is requested, or even
700 switch between modes as needed, e.g. depending on whether
701 the image file is writable or whether a writing user is
702 attached to the node.
703 "force-share"
705 Override the image locking system of QEMU by forcing the
706 node to utilize weaker shared access for permissions where
707 it would normally request exclusive access. When there is
708 the potential for multiple instances to have the same file
709 open (whether this invocation of QEMU is the first or the
710 second instance), both instances must permit shared access
711 for the second instance to succeed at opening the file.
712 Enabling force-share=on requires read-only=on.
714 "cache.direct"
716 The host page cache can be avoided with cache.direct=on.
717 This will attempt to do disk IO directly to the guest's
718 memory. QEMU may still perform an internal copy of the
719 data.
720 "cache.no-flush"
722 In case you don't care about data integrity over host
723 failures, you can use cache.no-flush=on. This option tells
724 QEMU that it never needs to write any data to the disk but
725 can instead keep things in cache. If anything goes wrong,
726 like your host losing power, the disk storage getting
727 disconnected accidentally, etc. your image will most
728 probably be rendered unusable.
729 "discard=discard"
731 discard is one of "ignore" (or "off") or "unmap" (or "on")
732 and controls whether "discard" (also known as "trim" or
733 "unmap") requests are ignored or passed to the filesystem.
734 Some machine types may not support discard requests.
735 "detect-zeroes=detect-zeroes"
737 detect-zeroes is "off", "on" or "unmap" and enables the
738 automatic conversion of plain zero writes by the OS to
739 driver specific optimized zero write commands. You may even
740 choose "unmap" if discard is set to "unmap" to allow a zero
741 write to be converted to an "unmap" operation.
742 Driver-specific options for "file"
744 This is the protocol-level block driver for accessing regular
745 files.
746 "filename"
748 The path to the image file in the local filesystem
749 "aio"
751 Specifies the AIO backend (threads/native, default:
752 threads)
753 "locking"
755 Specifies whether the image file is protected with Linux
756 OFD / POSIX locks. The default is to use the Linux Open
757 File Descriptor API if available, otherwise no lock is
758 applied. (auto/on/off, default: auto)
759 Example:
761 -blockdev driver=file,node-name=disk,filename=disk.img
763 Driver-specific options for "raw"
765 This is the image format block driver for raw images. It is
766 usually stacked on top of a protocol level block driver such as
767 "file".
768 "file"
770 Reference to or definition of the data source block driver
771 node (e.g. a "file" driver node)
772 Example 1:
774 -blockdev driver=file,node-name=disk_file,filename=disk.img
776 -blockdev driver=raw,node-name=disk,file=disk_file
777 Example 2:
779 -blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img
781 Driver-specific options for "qcow2"
783 This is the image format block driver for qcow2 images. It is
784 usually stacked on top of a protocol level block driver such as
785 "file".
786 "file"
788 Reference to or definition of the data source block driver
789 node (e.g. a "file" driver node)
790 "backing"
792 Reference to or definition of the backing file block device
793 (default is taken from the image file). It is allowed to
794 pass "null" here in order to disable the default backing
795 file.
796 "lazy-refcounts"
798 Whether to enable the lazy refcounts feature (on/off;
799 default is taken from the image file)
800 "cache-size"
802 The maximum total size of the L2 table and refcount block
803 caches in bytes (default: the sum of l2-cache-size and
804 refcount-cache-size)
805 "l2-cache-size"
807 The maximum size of the L2 table cache in bytes (default:
808 if cache-size is not specified - 32M on Linux platforms,
809 and 8M on non-Linux platforms; otherwise, as large as
810 possible within the cache-size, while permitting the
811 requested or the minimal refcount cache size)
812 "refcount-cache-size"
814 The maximum size of the refcount block cache in bytes
815 (default: 4 times the cluster size; or if cache-size is
816 specified, the part of it which is not used for the L2
817 cache)
818 "cache-clean-interval"
820 Clean unused entries in the L2 and refcount caches. The
821 interval is in seconds. The default value is 600 on
822 supporting platforms, and 0 on other platforms. Setting it
823 to 0 disables this feature.
824 "pass-discard-request"
826 Whether discard requests to the qcow2 device should be
827 forwarded to the data source (on/off; default: on if
828 discard=unmap is specified, off otherwise)
829 "pass-discard-snapshot"
831 Whether discard requests for the data source should be
832 issued when a snapshot operation (e.g. deleting a snapshot)
833 frees clusters in the qcow2 file (on/off; default: on)
834 "pass-discard-other"
836 Whether discard requests for the data source should be
837 issued on other occasions where a cluster gets freed
838 (on/off; default: off)
839 "overlap-check"
841 Which overlap checks to perform for writes to the image
842 (none/constant/cached/all; default: cached). For details or
843 finer granularity control refer to the QAPI documentation
844 of "blockdev-add".
845 Example 1:
847 -blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2
849 -blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216
850 Example 2:
852 -blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2
854 Driver-specific options for other drivers
856 Please refer to the QAPI documentation of the "blockdev-add"
857 QMP command.
858 -drive option[,option[,option[,...]]]
860 Define a new drive. This includes creating a block driver node (the
861 backend) as well as a guest device, and is mostly a shortcut for
862 defining the corresponding -blockdev and -device options.
863 -drive accepts all options that are accepted by -blockdev. In
865 addition, it knows the following options:
866 file=file
868 This option defines which disk image to use with this drive. If
869 the filename contains comma, you must double it (for instance,
870 "file=my,,file" to use file "my,file").
871 Special files such as iSCSI devices can be specified using
873 protocol specific URLs. See the section for "Device URL Syntax"
874 for more information.
875 if=interface
877 This option defines on which type on interface the drive is
878 connected. Available types are: ide, scsi, sd, mtd, floppy,
879 pflash, virtio, none.
880 bus=bus,unit=unit
882 These options define where is connected the drive by defining
883 the bus number and the unit id.
884 index=index
886 This option defines where is connected the drive by using an
887 index in the list of available connectors of a given interface
888 type.
889 media=media
891 This option defines the type of the media: disk or cdrom.
892 snapshot=snapshot
894 snapshot is "on" or "off" and controls snapshot mode for the
895 given drive (see -snapshot).
896 cache=cache
898 cache is "none", "writeback", "unsafe", "directsync" or
899 "writethrough" and controls how the host cache is used to
900 access block data. This is a shortcut that sets the
901 cache.direct and cache.no-flush options (as in -blockdev), and
902 additionally cache.writeback, which provides a default for the
903 write-cache option of block guest devices (as in -device). The
904 modes correspond to the following settings:
905 │ cache.writeback cache.direct cache.no-flush
907 ─────────────┼─────────────────────────────────────────────────
908 writeback │ on off off
909 none │ on on off
910 writethrough │ off off off
911 directsync │ off on off
912 unsafe │ on off on
913 The default mode is cache=writeback.
915 aio=aio
917 aio is "threads", or "native" and selects between pthread based
918 disk I/O and native Linux AIO.
919 format=format
921 Specify which disk format will be used rather than detecting
922 the format. Can be used to specify format=raw to avoid
923 interpreting an untrusted format header.
924 werror=action,rerror=action
926 Specify which action to take on write and read errors. Valid
927 actions are: "ignore" (ignore the error and try to continue),
928 "stop" (pause QEMU), "report" (report the error to the guest),
929 "enospc" (pause QEMU only if the host disk is full; report the
930 error to the guest otherwise). The default setting is
931 werror=enospc and rerror=report.
932 copy-on-read=copy-on-read
934 copy-on-read is "on" or "off" and enables whether to copy read
935 backing file sectors into the image file.
936 bps=b,bps_rd=r,bps_wr=w
938 Specify bandwidth throttling limits in bytes per second, either
939 for all request types or for reads or writes only. Small
940 values can lead to timeouts or hangs inside the guest. A safe
941 minimum for disks is 2 MB/s.
942 bps_max=bm,bps_rd_max=rm,bps_wr_max=wm
944 Specify bursts in bytes per second, either for all request
945 types or for reads or writes only. Bursts allow the guest I/O
946 to spike above the limit temporarily.
947 iops=i,iops_rd=r,iops_wr=w
949 Specify request rate limits in requests per second, either for
950 all request types or for reads or writes only.
951 iops_max=bm,iops_rd_max=rm,iops_wr_max=wm
953 Specify bursts in requests per second, either for all request
954 types or for reads or writes only. Bursts allow the guest I/O
955 to spike above the limit temporarily.
956 iops_size=is
958 Let every is bytes of a request count as a new request for iops
959 throttling purposes. Use this option to prevent guests from
960 circumventing iops limits by sending fewer but larger requests.
961 group=g
963 Join a throttling quota group with given name g. All drives
964 that are members of the same group are accounted for together.
965 Use this option to prevent guests from circumventing throttling
966 limits by using many small disks instead of a single larger
967 disk.
968 By default, the cache.writeback=on mode is used. It will report
970 data writes as completed as soon as the data is present in the host
971 page cache. This is safe as long as your guest OS makes sure to
972 correctly flush disk caches where needed. If your guest OS does not
973 handle volatile disk write caches correctly and your host crashes
974 or loses power, then the guest may experience data corruption.
975 For such guests, you should consider using cache.writeback=off.
977 This means that the host page cache will be used to read and write
978 data, but write notification will be sent to the guest only after
979 QEMU has made sure to flush each write to the disk. Be aware that
980 this has a major impact on performance.
981 When using the -snapshot option, unsafe caching is always used.
983 Copy-on-read avoids accessing the same backing file sectors
985 repeatedly and is useful when the backing file is over a slow
986 network. By default copy-on-read is off.
987 Instead of -cdrom you can use:
989 qemu-system-x86_64 -drive file=file,index=2,media=cdrom
991 Instead of -hda, -hdb, -hdc, -hdd, you can use:
993 qemu-system-x86_64 -drive file=file,index=0,media=disk
995 qemu-system-x86_64 -drive file=file,index=1,media=disk
996 qemu-system-x86_64 -drive file=file,index=2,media=disk
997 qemu-system-x86_64 -drive file=file,index=3,media=disk
998 You can open an image using pre-opened file descriptors from an fd
1000 set:
1001 qemu-system-x86_64 \
1003 -add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \
1004 -add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \
1005 -drive file=/dev/fdset/2,index=0,media=disk
1006 You can connect a CDROM to the slave of ide0:
1008 qemu-system-x86_64 -drive file=file,if=ide,index=1,media=cdrom
1010 If you don't specify the "file=" argument, you define an empty
1012 drive:
1013 qemu-system-x86_64 -drive if=ide,index=1,media=cdrom
1015 Instead of -fda, -fdb, you can use:
1017 qemu-system-x86_64 -drive file=file,index=0,if=floppy
1019 qemu-system-x86_64 -drive file=file,index=1,if=floppy
1020 By default, interface is "ide" and index is automatically
1022 incremented:
1023 qemu-system-x86_64 -drive file=a -drive file=b"
1025 is interpreted like:
1027 qemu-system-x86_64 -hda a -hdb b
1029 -mtdblock file
1031 Use file as on-board Flash memory image.
1032 -sd file
1034 Use file as SecureDigital card image.
1035 -pflash file
1037 Use file as a parallel flash image.
1038 -snapshot
1040 Write to temporary files instead of disk image files. In this case,
1041 the raw disk image you use is not written back. You can however
1042 force the write back by pressing C-a s.
1043 -fsdev local,id=id,path=path,security_model=security_model
1045 [,writeout=writeout][,readonly][,fmode=fmode][,dmode=dmode]
1046 [,throttling.option=value[,throttling.option=value[,...]]]
1047 -fsdev proxy,id=id,socket=socket[,writeout=writeout][,readonly]
1048 -fsdev proxy,id=id,sock_fd=sock_fd[,writeout=writeout][,readonly]
1049 -fsdev synth,id=id[,readonly]
1050 Define a new file system device. Valid options are:
1051 local
1053 Accesses to the filesystem are done by QEMU.
1054 proxy
1056 Accesses to the filesystem are done by virtfs-proxy-helper(1).
1057 synth
1059 Synthetic filesystem, only used by QTests.
1060 id=id
1062 Specifies identifier for this device.
1063 path=path
1065 Specifies the export path for the file system device. Files
1066 under this path will be available to the 9p client on the
1067 guest.
1068 security_model=security_model
1070 Specifies the security model to be used for this export path.
1071 Supported security models are "passthrough", "mapped-xattr",
1072 "mapped-file" and "none". In "passthrough" security model,
1073 files are stored using the same credentials as they are created
1074 on the guest. This requires QEMU to run as root. In "mapped-
1075 xattr" security model, some of the file attributes like uid,
1076 gid, mode bits and link target are stored as file attributes.
1077 For "mapped-file" these attributes are stored in the hidden
1078 .virtfs_metadata directory. Directories exported by this
1079 security model cannot interact with other unix tools. "none"
1080 security model is same as passthrough except the sever won't
1081 report failures if it fails to set file attributes like
1082 ownership. Security model is mandatory only for local fsdriver.
1083 Other fsdrivers (like proxy) don't take security model as a
1084 parameter.
1085 writeout=writeout
1087 This is an optional argument. The only supported value is
1088 "immediate". This means that host page cache will be used to
1089 read and write data but write notification will be sent to the
1090 guest only when the data has been reported as written by the
1091 storage subsystem.
1092 readonly
1094 Enables exporting 9p share as a readonly mount for guests. By
1095 default read-write access is given.
1096 socket=socket
1098 Enables proxy filesystem driver to use passed socket file for
1099 communicating with virtfs-proxy-helper(1).
1100 sock_fd=sock_fd
1102 Enables proxy filesystem driver to use passed socket descriptor
1103 for communicating with virtfs-proxy-helper(1). Usually a helper
1104 like libvirt will create socketpair and pass one of the fds as
1105 sock_fd.
1106 fmode=fmode
1108 Specifies the default mode for newly created files on the host.
1109 Works only with security models "mapped-xattr" and "mapped-
1110 file".
1111 dmode=dmode
1113 Specifies the default mode for newly created directories on the
1114 host. Works only with security models "mapped-xattr" and
1115 "mapped-file".
1116 throttling.bps-total=b,throttling.bps-read=r,throttling.bps-write=w
1118 Specify bandwidth throttling limits in bytes per second, either
1119 for all request types or for reads or writes only.
1120 throttling.bps-total-max=bm,bps-read-max=rm,bps-write-max=wm
1122 Specify bursts in bytes per second, either for all request
1123 types or for reads or writes only. Bursts allow the guest I/O
1124 to spike above the limit temporarily.
1125 throttling.iops-total=i,throttling.iops-read=r,
1127 throttling.iops-write=w
1128 Specify request rate limits in requests per second, either for
1129 all request types or for reads or writes only.
1130 throttling.iops-total-max=im,throttling.iops-read-max=irm,
1132 throttling.iops-write-max=iwm
1133 Specify bursts in requests per second, either for all request
1134 types or for reads or writes only. Bursts allow the guest I/O
1135 to spike above the limit temporarily.
1136 throttling.iops-size=is
1138 Let every is bytes of a request count as a new request for iops
1139 throttling purposes.
1140 -fsdev option is used along with -device driver "virtio-9p-...".
1142 -device virtio-9p-type,fsdev=id,mount_tag=mount_tag
1144 Options for virtio-9p-... driver are:
1145 type
1147 Specifies the variant to be used. Supported values are "pci",
1148 "ccw" or "device", depending on the machine type.
1149 fsdev=id
1151 Specifies the id value specified along with -fsdev option.
1152 mount_tag=mount_tag
1154 Specifies the tag name to be used by the guest to mount this
1155 export point.
1156 -virtfs local,path=path,mount_tag=mount_tag
1158 ,security_model=security_model[,writeout=writeout][,readonly]
1159 [,fmode=fmode][,dmode=dmode][,multidevs=multidevs]
1160 -virtfs proxy,socket=socket,mount_tag=mount_tag
1161 [,writeout=writeout][,readonly]
1162 -virtfs proxy,sock_fd=sock_fd,mount_tag=mount_tag
1163 [,writeout=writeout][,readonly]
1164 -virtfs synth,mount_tag=mount_tag
1165 Define a new filesystem device and expose it to the guest using a
1166 virtio-9p-device. The general form of a Virtual File system pass-
1167 through options are:
1168 local
1170 Accesses to the filesystem are done by QEMU.
1171 proxy
1173 Accesses to the filesystem are done by virtfs-proxy-helper(1).
1174 synth
1176 Synthetic filesystem, only used by QTests.
1177 id=id
1179 Specifies identifier for the filesystem device
1180 path=path
1182 Specifies the export path for the file system device. Files
1183 under this path will be available to the 9p client on the
1184 guest.
1185 security_model=security_model
1187 Specifies the security model to be used for this export path.
1188 Supported security models are "passthrough", "mapped-xattr",
1189 "mapped-file" and "none". In "passthrough" security model,
1190 files are stored using the same credentials as they are created
1191 on the guest. This requires QEMU to run as root. In "mapped-
1192 xattr" security model, some of the file attributes like uid,
1193 gid, mode bits and link target are stored as file attributes.
1194 For "mapped-file" these attributes are stored in the hidden
1195 .virtfs_metadata directory. Directories exported by this
1196 security model cannot interact with other unix tools. "none"
1197 security model is same as passthrough except the sever won't
1198 report failures if it fails to set file attributes like
1199 ownership. Security model is mandatory only for local fsdriver.
1200 Other fsdrivers (like proxy) don't take security model as a
1201 parameter.
1202 writeout=writeout
1204 This is an optional argument. The only supported value is
1205 "immediate". This means that host page cache will be used to
1206 read and write data but write notification will be sent to the
1207 guest only when the data has been reported as written by the
1208 storage subsystem.
1209 readonly
1211 Enables exporting 9p share as a readonly mount for guests. By
1212 default read-write access is given.
1213 socket=socket
1215 Enables proxy filesystem driver to use passed socket file for
1216 communicating with virtfs-proxy-helper(1). Usually a helper
1217 like libvirt will create socketpair and pass one of the fds as
1218 sock_fd.
1219 sock_fd
1221 Enables proxy filesystem driver to use passed 'sock_fd' as the
1222 socket descriptor for interfacing with virtfs-proxy-helper(1).
1223 fmode=fmode
1225 Specifies the default mode for newly created files on the host.
1226 Works only with security models "mapped-xattr" and "mapped-
1227 file".
1228 dmode=dmode
1230 Specifies the default mode for newly created directories on the
1231 host. Works only with security models "mapped-xattr" and
1232 "mapped-file".
1233 mount_tag=mount_tag
1235 Specifies the tag name to be used by the guest to mount this
1236 export point.
1237 multidevs=multidevs
1239 Specifies how to deal with multiple devices being shared with a
1240 9p export. Supported behaviours are either "remap", "forbid"
1241 or "warn". The latter is the default behaviour on which virtfs
1242 9p expects only one device to be shared with the same export,
1243 and if more than one device is shared and accessed via the same
1244 9p export then only a warning message is logged (once) by qemu
1245 on host side. In order to avoid file ID collisions on guest you
1246 should either create a separate virtfs export for each device
1247 to be shared with guests (recommended way) or you might use
1248 "remap" instead which allows you to share multiple devices with
1249 only one export instead, which is achieved by remapping the
1250 original inode numbers from host to guest in a way that would
1251 prevent such collisions. Remapping inodes in such use cases is
1252 required because the original device IDs from host are never
1253 passed and exposed on guest. Instead all files of an export
1254 shared with virtfs always share the same device id on guest. So
1255 two files with identical inode numbers but from actually
1256 different devices on host would otherwise cause a file ID
1257 collision and hence potential misbehaviours on guest. "forbid"
1258 on the other hand assumes like "warn" that only one device is
1259 shared by the same export, however it will not only log a
1260 warning message but also deny access to additional devices on
1261 guest. Note though that "forbid" does currently not block all
1262 possible file access operations (e.g. readdir() would still
1263 return entries from other devices).
1264 -virtfs_synth
1266 Create synthetic file system image. Note that this option is now
1267 deprecated. Please use "-fsdev synth" and "-device virtio-9p-..."
1268 instead.
1269 -iscsi
1271 Configure iSCSI session parameters.
1272 USB options
1274 -usb
1276 Enable USB emulation on machine types with an on-board USB host
1277 controller (if not enabled by default). Note that on-board USB
1278 host controllers may not support USB 3.0. In this case -device
1279 qemu-xhci can be used instead on machines with PCI.
1280 -usbdevice devname
1282 Add the USB device devname. Note that this option is deprecated,
1283 please use "-device usb-..." instead.
1284 mouse
1286 Virtual Mouse. This will override the PS/2 mouse emulation when
1287 activated.
1288 tablet
1290 Pointer device that uses absolute coordinates (like a
1291 touchscreen). This means QEMU is able to report the mouse
1292 position without having to grab the mouse. Also overrides the
1293 PS/2 mouse emulation when activated.
1294 braille
1296 Braille device. This will use BrlAPI to display the braille
1297 output on a real or fake device.
1298 Display options
1300 -display type
1302 Select type of display to use. This option is a replacement for the
1303 old style -sdl/-curses/... options. Valid values for type are
1304 sdl Display video output via SDL (usually in a separate graphics
1306 window; see the SDL documentation for other possibilities).
1307 curses
1309 Display video output via curses. For graphics device models
1310 which support a text mode, QEMU can display this output using a
1311 curses/ncurses interface. Nothing is displayed when the
1312 graphics device is in graphical mode or if the graphics device
1313 does not support a text mode. Generally only the VGA device
1314 models support text mode. The font charset used by the guest
1315 can be specified with the "charset" option, for example
1316 "charset=CP850" for IBM CP850 encoding. The default is "CP437".
1317 none
1319 Do not display video output. The guest will still see an
1320 emulated graphics card, but its output will not be displayed to
1321 the QEMU user. This option differs from the -nographic option
1322 in that it only affects what is done with video output;
1323 -nographic also changes the destination of the serial and
1324 parallel port data.
1325 gtk Display video output in a GTK window. This interface provides
1327 drop-down menus and other UI elements to configure and control
1328 the VM during runtime.
1329 vnc Start a VNC server on display <arg>
1331 egl-headless
1333 Offload all OpenGL operations to a local DRI device. For any
1334 graphical display, this display needs to be paired with either
1335 VNC or SPICE displays.
1336 spice-app
1338 Start QEMU as a Spice server and launch the default Spice
1339 client application. The Spice server will redirect the serial
1340 consoles and QEMU monitors. (Since 4.0)
1341 -nographic
1343 Normally, if QEMU is compiled with graphical window support, it
1344 displays output such as guest graphics, guest console, and the QEMU
1345 monitor in a window. With this option, you can totally disable
1346 graphical output so that QEMU is a simple command line application.
1347 The emulated serial port is redirected on the console and muxed
1348 with the monitor (unless redirected elsewhere explicitly).
1349 Therefore, you can still use QEMU to debug a Linux kernel with a
1350 serial console. Use C-a h for help on switching between the console
1351 and monitor.
1352 -curses
1354 Normally, if QEMU is compiled with graphical window support, it
1355 displays output such as guest graphics, guest console, and the QEMU
1356 monitor in a window. With this option, QEMU can display the VGA
1357 output when in text mode using a curses/ncurses interface. Nothing
1358 is displayed in graphical mode.
1359 -alt-grab
1361 Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that
1362 this also affects the special keys (for fullscreen, monitor-mode
1363 switching, etc).
1364 -ctrl-grab
1366 Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this
1367 also affects the special keys (for fullscreen, monitor-mode
1368 switching, etc).
1369 -no-quit
1371 Disable SDL window close capability.
1372 -sdl
1374 Enable SDL.
1375 -spice option[,option[,...]]
1377 Enable the spice remote desktop protocol. Valid options are
1378 port=<nr>
1380 Set the TCP port spice is listening on for plaintext channels.
1381 addr=<addr>
1383 Set the IP address spice is listening on. Default is any
1384 address.
1385 ipv4
1387 ipv6
1388 unix
1389 Force using the specified IP version.
1390 password=<secret>
1392 Set the password you need to authenticate.
1393 sasl
1395 Require that the client use SASL to authenticate with the
1396 spice. The exact choice of authentication method used is
1397 controlled from the system / user's SASL configuration file for
1398 the 'qemu' service. This is typically found in
1399 /etc/sasl2/qemu.conf. If running QEMU as an unprivileged user,
1400 an environment variable SASL_CONF_PATH can be used to make it
1401 search alternate locations for the service config. While some
1402 SASL auth methods can also provide data encryption (eg GSSAPI),
1403 it is recommended that SASL always be combined with the 'tls'
1404 and 'x509' settings to enable use of SSL and server
1405 certificates. This ensures a data encryption preventing
1406 compromise of authentication credentials.
1407 disable-ticketing
1409 Allow client connects without authentication.
1410 disable-copy-paste
1412 Disable copy paste between the client and the guest.
1413 disable-agent-file-xfer
1415 Disable spice-vdagent based file-xfer between the client and
1416 the guest.
1417 tls-port=<nr>
1419 Set the TCP port spice is listening on for encrypted channels.
1420 x509-dir=<dir>
1422 Set the x509 file directory. Expects same filenames as -vnc
1423 $display,x509=$dir
1424 x509-key-file=<file>
1426 x509-key-password=<file>
1427 x509-cert-file=<file>
1428 x509-cacert-file=<file>
1429 x509-dh-key-file=<file>
1430 The x509 file names can also be configured individually.
1431 tls-ciphers=<list>
1433 Specify which ciphers to use.
1434 tls-channel=[main|display|cursor|inputs|record|playback]
1436 plaintext-channel=[main|display|cursor|inputs|record|playback]
1437 Force specific channel to be used with or without TLS
1438 encryption. The options can be specified multiple times to
1439 configure multiple channels. The special name "default" can be
1440 used to set the default mode. For channels which are not
1441 explicitly forced into one mode the spice client is allowed to
1442 pick tls/plaintext as he pleases.
1443 image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
1445 Configure image compression (lossless). Default is auto_glz.
1446 jpeg-wan-compression=[auto|never|always]
1448 zlib-glz-wan-compression=[auto|never|always]
1449 Configure wan image compression (lossy for slow links).
1450 Default is auto.
1451 streaming-video=[off|all|filter]
1453 Configure video stream detection. Default is off.
1454 agent-mouse=[on|off]
1456 Enable/disable passing mouse events via vdagent. Default is
1457 on.
1458 playback-compression=[on|off]
1460 Enable/disable audio stream compression (using celt 0.5.1).
1461 Default is on.
1462 seamless-migration=[on|off]
1464 Enable/disable spice seamless migration. Default is off.
1465 gl=[on|off]
1467 Enable/disable OpenGL context. Default is off.
1468 rendernode=<file>
1470 DRM render node for OpenGL rendering. If not specified, it will
1471 pick the first available. (Since 2.9)
1472 -portrait
1474 Rotate graphical output 90 deg left (only PXA LCD).
1475 -rotate deg
1477 Rotate graphical output some deg left (only PXA LCD).
1478 -vga type
1480 Select type of VGA card to emulate. Valid values for type are
1481 cirrus
1483 Cirrus Logic GD5446 Video card. All Windows versions starting
1484 from Windows 95 should recognize and use this graphic card. For
1485 optimal performances, use 16 bit color depth in the guest and
1486 the host OS. (This card was the default before QEMU 2.2)
1487 std Standard VGA card with Bochs VBE extensions. If your guest OS
1489 supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if
1490 you want to use high resolution modes (>= 1280x1024x16) then
1491 you should use this option. (This card is the default since
1492 QEMU 2.2)
1493 vmware
1495 VMWare SVGA-II compatible adapter. Use it if you have
1496 sufficiently recent XFree86/XOrg server or Windows guest with a
1497 driver for this card.
1498 qxl QXL paravirtual graphic card. It is VGA compatible (including
1500 VESA 2.0 VBE support). Works best with qxl guest drivers
1501 installed though. Recommended choice when using the spice
1502 protocol.
1503 tcx (sun4m only) Sun TCX framebuffer. This is the default
1505 framebuffer for sun4m machines and offers both 8-bit and 24-bit
1506 colour depths at a fixed resolution of 1024x768.
1507 cg3 (sun4m only) Sun cgthree framebuffer. This is a simple 8-bit
1509 framebuffer for sun4m machines available in both 1024x768
1510 (OpenBIOS) and 1152x900 (OBP) resolutions aimed at people
1511 wishing to run older Solaris versions.
1512 virtio
1514 Virtio VGA card.
1515 none
1517 Disable VGA card.
1518 -full-screen
1520 Start in full screen.
1521 -g widthxheight[xdepth]
1523 Set the initial graphical resolution and depth (PPC, SPARC only).
1524 -vnc display[,option[,option[,...]]]
1526 Normally, if QEMU is compiled with graphical window support, it
1527 displays output such as guest graphics, guest console, and the QEMU
1528 monitor in a window. With this option, you can have QEMU listen on
1529 VNC display display and redirect the VGA display over the VNC
1530 session. It is very useful to enable the usb tablet device when
1531 using this option (option -device usb-tablet). When using the VNC
1532 display, you must use the -k parameter to set the keyboard layout
1533 if you are not using en-us. Valid syntax for the display is
1534 to=L
1536 With this option, QEMU will try next available VNC displays,
1537 until the number L, if the origianlly defined "-vnc display" is
1538 not available, e.g. port 5900+display is already used by
1539 another application. By default, to=0.
1540 host:d
1542 TCP connections will only be allowed from host on display d.
1543 By convention the TCP port is 5900+d. Optionally, host can be
1544 omitted in which case the server will accept connections from
1545 any host.
1546 unix:path
1548 Connections will be allowed over UNIX domain sockets where path
1549 is the location of a unix socket to listen for connections on.
1550 none
1552 VNC is initialized but not started. The monitor "change"
1553 command can be used to later start the VNC server.
1554 Following the display value there may be one or more option flags
1556 separated by commas. Valid options are
1557 reverse
1559 Connect to a listening VNC client via a "reverse" connection.
1560 The client is specified by the display. For reverse network
1561 connections (host:d,"reverse"), the d argument is a TCP port
1562 number, not a display number.
1563 websocket
1565 Opens an additional TCP listening port dedicated to VNC
1566 Websocket connections. If a bare websocket option is given,
1567 the Websocket port is 5700+display. An alternative port can be
1568 specified with the syntax "websocket"=port.
1569 If host is specified connections will only be allowed from this
1571 host. It is possible to control the websocket listen address
1572 independently, using the syntax "websocket"=host:port.
1573 If no TLS credentials are provided, the websocket connection
1575 runs in unencrypted mode. If TLS credentials are provided, the
1576 websocket connection requires encrypted client connections.
1577 password
1579 Require that password based authentication is used for client
1580 connections.
1581 The password must be set separately using the "set_password"
1583 command in the pcsys_monitor. The syntax to change your
1584 password is: "set_password <protocol> <password>" where
1585 <protocol> could be either "vnc" or "spice".
1586 If you would like to change <protocol> password expiration, you
1588 should use "expire_password <protocol> <expiration-time>" where
1589 expiration time could be one of the following options: now,
1590 never, +seconds or UNIX time of expiration, e.g. +60 to make
1591 password expire in 60 seconds, or 1335196800 to make password
1592 expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this
1593 date and time).
1594 You can also use keywords "now" or "never" for the expiration
1596 time to allow <protocol> password to expire immediately or
1597 never expire.
1598 tls-creds=ID
1600 Provides the ID of a set of TLS credentials to use to secure
1601 the VNC server. They will apply to both the normal VNC server
1602 socket and the websocket socket (if enabled). Setting TLS
1603 credentials will cause the VNC server socket to enable the
1604 VeNCrypt auth mechanism. The credentials should have been
1605 previously created using the -object tls-creds argument.
1606 tls-authz=ID
1608 Provides the ID of the QAuthZ authorization object against
1609 which the client's x509 distinguished name will validated. This
1610 object is only resolved at time of use, so can be deleted and
1611 recreated on the fly while the VNC server is active. If
1612 missing, it will default to denying access.
1613 sasl
1615 Require that the client use SASL to authenticate with the VNC
1616 server. The exact choice of authentication method used is
1617 controlled from the system / user's SASL configuration file for
1618 the 'qemu' service. This is typically found in
1619 /etc/sasl2/qemu.conf. If running QEMU as an unprivileged user,
1620 an environment variable SASL_CONF_PATH can be used to make it
1621 search alternate locations for the service config. While some
1622 SASL auth methods can also provide data encryption (eg GSSAPI),
1623 it is recommended that SASL always be combined with the 'tls'
1624 and 'x509' settings to enable use of SSL and server
1625 certificates. This ensures a data encryption preventing
1626 compromise of authentication credentials. See the vnc_security
1627 section for details on using SASL authentication.
1628 sasl-authz=ID
1630 Provides the ID of the QAuthZ authorization object against
1631 which the client's SASL username will validated. This object is
1632 only resolved at time of use, so can be deleted and recreated
1633 on the fly while the VNC server is active. If missing, it will
1634 default to denying access.
1635 acl Legacy method for enabling authorization of clients against the
1637 x509 distinguished name and SASL username. It results in the
1638 creation of two "authz-list" objects with IDs of "vnc.username"
1639 and "vnc.x509dname". The rules for these objects must be
1640 configured with the HMP ACL commands.
1641 This option is deprecated and should no longer be used. The new
1643 sasl-authz and tls-authz options are a replacement.
1644 lossy
1646 Enable lossy compression methods (gradient, JPEG, ...). If this
1647 option is set, VNC client may receive lossy framebuffer updates
1648 depending on its encoding settings. Enabling this option can
1649 save a lot of bandwidth at the expense of quality.
1650 non-adaptive
1652 Disable adaptive encodings. Adaptive encodings are enabled by
1653 default. An adaptive encoding will try to detect frequently
1654 updated screen regions, and send updates in these regions using
1655 a lossy encoding (like JPEG). This can be really helpful to
1656 save bandwidth when playing videos. Disabling adaptive
1657 encodings restores the original static behavior of encodings
1658 like Tight.
1659 share=[allow-exclusive|force-shared|ignore]
1661 Set display sharing policy. 'allow-exclusive' allows clients
1662 to ask for exclusive access. As suggested by the rfb spec this
1663 is implemented by dropping other connections. Connecting
1664 multiple clients in parallel requires all clients asking for a
1665 shared session (vncviewer: -shared switch). This is the
1666 default. 'force-shared' disables exclusive client access.
1667 Useful for shared desktop sessions, where you don't want
1668 someone forgetting specify -shared disconnect everybody else.
1669 'ignore' completely ignores the shared flag and allows
1670 everybody connect unconditionally. Doesn't conform to the rfb
1671 spec but is traditional QEMU behavior.
1672 key-delay-ms
1674 Set keyboard delay, for key down and key up events, in
1675 milliseconds. Default is 10. Keyboards are low-bandwidth
1676 devices, so this slowdown can help the device and guest to keep
1677 up and not lose events in case events are arriving in bulk.
1678 Possible causes for the latter are flaky network connections,
1679 or scripts for automated testing.
1680 audiodev=audiodev
1682 Use the specified audiodev when the VNC client requests audio
1683 transmission. When not using an -audiodev argument, this option
1684 must be omitted, otherwise is must be present and specify a
1685 valid audiodev.
1686 i386 target only
1688 -win2k-hack
1690 Use it when installing Windows 2000 to avoid a disk full bug. After
1691 Windows 2000 is installed, you no longer need this option (this
1692 option slows down the IDE transfers).
1693 -no-fd-bootchk
1695 Disable boot signature checking for floppy disks in BIOS. May be
1696 needed to boot from old floppy disks.
1697 -no-acpi
1699 Disable ACPI (Advanced Configuration and Power Interface) support.
1700 Use it if your guest OS complains about ACPI problems (PC target
1701 machine only).
1702 -no-hpet
1704 Disable HPET support.
1705 -acpitable
1707 [sig=str][,rev=n][,oem_id=str][,oem_table_id=str][,oem_rev=n]
1708 [,asl_compiler_id=str][,asl_compiler_rev=n][,data=file1[:file2]...]
1709 Add ACPI table with specified header fields and context from
1710 specified files. For file=, take whole ACPI table from the
1711 specified files, including all ACPI headers (possible overridden by
1712 other options). For data=, only data portion of the table is used,
1713 all header information is specified in the command line. If a SLIC
1714 table is supplied to QEMU, then the SLIC's oem_id and oem_table_id
1715 fields will override the same in the RSDT and the FADT (a.k.a.
1716 FACP), in order to ensure the field matches required by the
1717 Microsoft SLIC spec and the ACPI spec.
1718 -smbios file=binary
1720 Load SMBIOS entry from binary file.
1721 -smbios
1723 type=0[,vendor=str][,version=str][,date=str][,release=%d.%d][,uefi=on|off]
1724 Specify SMBIOS type 0 fields
1725 -smbios
1727 type=1[,manufacturer=str][,product=str][,version=str][,serial=str][,uuid=uuid][,sku=str][,family=str]
1728 Specify SMBIOS type 1 fields
1729 -smbios
1731 type=2[,manufacturer=str][,product=str][,version=str][,serial=str][,asset=str][,location=str]
1732 Specify SMBIOS type 2 fields
1733 -smbios
1735 type=3[,manufacturer=str][,version=str][,serial=str][,asset=str][,sku=str]
1736 Specify SMBIOS type 3 fields
1737 -smbios
1739 type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str][,asset=str][,part=str]
1740 Specify SMBIOS type 4 fields
1741 -smbios
1743 type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str][,asset=str][,part=str][,speed=%d]
1744 Specify SMBIOS type 17 fields
1745 Network options
1747 -nic
1749 [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn]
1750 This option is a shortcut for configuring both the on-board
1751 (default) guest NIC hardware and the host network backend in one
1752 go. The host backend options are the same as with the corresponding
1753 -netdev options below. The guest NIC model can be set with
1754 model=modelname. Use model=help to list the available device
1755 types. The hardware MAC address can be set with mac=macaddr.
1756 The following two example do exactly the same, to show how -nic can
1758 be used to shorten the command line length (note that the e1000 is
1759 the default on i386, so the model=e1000 parameter could even be
1760 omitted here, too):
1761 qemu-system-x86_64 -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32
1763 qemu-system-x86_64 -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32
1764 -nic none
1766 Indicate that no network devices should be configured. It is used
1767 to override the default configuration (default NIC with "user" host
1768 network backend) which is activated if no other networking options
1769 are provided.
1770 -netdev user,id=id[,option][,option][,...]
1772 Configure user mode host network backend which requires no
1773 administrator privilege to run. Valid options are:
1774 id=id
1776 Assign symbolic name for use in monitor commands.
1777 ipv4=on|off and ipv6=on|off
1779 Specify that either IPv4 or IPv6 must be enabled. If neither is
1780 specified both protocols are enabled.
1781 net=addr[/mask]
1783 Set IP network address the guest will see. Optionally specify
1784 the netmask, either in the form a.b.c.d or as number of valid
1785 top-most bits. Default is 10.0.2.0/24.
1786 host=addr
1788 Specify the guest-visible address of the host. Default is the
1789 2nd IP in the guest network, i.e. x.x.x.2.
1790 ipv6-net=addr[/int]
1792 Set IPv6 network address the guest will see (default is
1793 fec0::/64). The network prefix is given in the usual
1794 hexadecimal IPv6 address notation. The prefix size is optional,
1795 and is given as the number of valid top-most bits (default is
1796 64).
1797 ipv6-host=addr
1799 Specify the guest-visible IPv6 address of the host. Default is
1800 the 2nd IPv6 in the guest network, i.e. xxxx::2.
1801 restrict=on|off
1803 If this option is enabled, the guest will be isolated, i.e. it
1804 will not be able to contact the host and no guest IP packets
1805 will be routed over the host to the outside. This option does
1806 not affect any explicitly set forwarding rules.
1807 hostname=name
1809 Specifies the client hostname reported by the built-in DHCP
1810 server.
1811 dhcpstart=addr
1813 Specify the first of the 16 IPs the built-in DHCP server can
1814 assign. Default is the 15th to 31st IP in the guest network,
1815 i.e. x.x.x.15 to x.x.x.31.
1816 dns=addr
1818 Specify the guest-visible address of the virtual nameserver.
1819 The address must be different from the host address. Default is
1820 the 3rd IP in the guest network, i.e. x.x.x.3.
1821 ipv6-dns=addr
1823 Specify the guest-visible address of the IPv6 virtual
1824 nameserver. The address must be different from the host
1825 address. Default is the 3rd IP in the guest network, i.e.
1826 xxxx::3.
1827 dnssearch=domain
1829 Provides an entry for the domain-search list sent by the built-
1830 in DHCP server. More than one domain suffix can be transmitted
1831 by specifying this option multiple times. If supported, this
1832 will cause the guest to automatically try to append the given
1833 domain suffix(es) in case a domain name can not be resolved.
1834 Example:
1836 qemu-system-x86_64 -nic user,dnssearch=mgmt.example.org,dnssearch=example.org
1838 domainname=domain
1840 Specifies the client domain name reported by the built-in DHCP
1841 server.
1842 tftp=dir
1844 When using the user mode network stack, activate a built-in
1845 TFTP server. The files in dir will be exposed as the root of a
1846 TFTP server. The TFTP client on the guest must be configured
1847 in binary mode (use the command "bin" of the Unix TFTP client).
1848 tftp-server-name=name
1850 In BOOTP reply, broadcast name as the "TFTP server name"
1851 (RFC2132 option 66). This can be used to advise the guest to
1852 load boot files or configurations from a different server than
1853 the host address.
1854 bootfile=file
1856 When using the user mode network stack, broadcast file as the
1857 BOOTP filename. In conjunction with tftp, this can be used to
1858 network boot a guest from a local directory.
1859 Example (using pxelinux):
1861 qemu-system-x86_64 -hda linux.img -boot n -device e1000,netdev=n1 \
1863 -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
1864 smb=dir[,smbserver=addr]
1866 When using the user mode network stack, activate a built-in SMB
1867 server so that Windows OSes can access to the host files in dir
1868 transparently. The IP address of the SMB server can be set to
1869 addr. By default the 4th IP in the guest network is used, i.e.
1870 x.x.x.4.
1871 In the guest Windows OS, the line:
1873 10.0.2.4 smbserver
1875 must be added in the file C:\WINDOWS\LMHOSTS (for windows
1877 9x/Me) or C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS (Windows
1878 NT/2000).
1879 Then dir can be accessed in \\smbserver\qemu.
1881 Note that a SAMBA server must be installed on the host OS.
1883 hostfwd=[tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport
1885 Redirect incoming TCP or UDP connections to the host port
1886 hostport to the guest IP address guestaddr on guest port
1887 guestport. If guestaddr is not specified, its value is x.x.x.15
1888 (default first address given by the built-in DHCP server). By
1889 specifying hostaddr, the rule can be bound to a specific host
1890 interface. If no connection type is set, TCP is used. This
1891 option can be given multiple times.
1892 For example, to redirect host X11 connection from screen 1 to
1894 guest screen 0, use the following:
1895 # on the host
1897 qemu-system-x86_64 -nic user,hostfwd=tcp:127.0.0.1:6001-:6000
1898 # this host xterm should open in the guest X11 server
1899 xterm -display :1
1900 To redirect telnet connections from host port 5555 to telnet
1902 port on the guest, use the following:
1903 # on the host
1905 qemu-system-x86_64 -nic user,hostfwd=tcp::5555-:23
1906 telnet localhost 5555
1907 Then when you use on the host "telnet localhost 5555", you
1909 connect to the guest telnet server.
1910 guestfwd=[tcp]:server:port-dev
1912 guestfwd=[tcp]:server:port-cmd:command
1913 Forward guest TCP connections to the IP address server on port
1914 port to the character device dev or to a program executed by
1915 cmd:command which gets spawned for each connection. This option
1916 can be given multiple times.
1917 You can either use a chardev directly and have that one used
1919 throughout QEMU's lifetime, like in the following example:
1920 # open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
1922 # the guest accesses it
1923 qemu-system-x86_64 -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321
1924 Or you can execute a command on every TCP connection
1926 established by the guest, so that QEMU behaves similar to an
1927 inetd process for that virtual server:
1928 # call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
1930 # and connect the TCP stream to its stdin/stdout
1931 qemu-system-x86_64 -nic 'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
1932 -netdev
1934 tap,id=id[,fd=h][,ifname=name][,script=file][,downscript=dfile][,br=bridge][,helper=helper]
1935 Configure a host TAP network backend with ID id.
1936 Use the network script file to configure it and the network script
1938 dfile to deconfigure it. If name is not provided, the OS
1939 automatically provides one. The default network configure script is
1940 /etc/qemu-ifup and the default network deconfigure script is
1941 /etc/qemu-ifdown. Use script=no or downscript=no to disable script
1942 execution.
1943 If running QEMU as an unprivileged user, use the network helper
1945 helper to configure the TAP interface and attach it to the bridge.
1946 The default network helper executable is
1947 /path/to/qemu-bridge-helper and the default bridge device is br0.
1948 fd=h can be used to specify the handle of an already opened host
1950 TAP interface.
1951 Examples:
1953 #launch a QEMU instance with the default network script
1955 qemu-system-x86_64 linux.img -nic tap
1956 #launch a QEMU instance with two NICs, each one connected
1960 #to a TAP device
1961 qemu-system-x86_64 linux.img \
1962 -netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 \
1963 -netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1
1964 #launch a QEMU instance with the default network helper to
1968 #connect a TAP device to bridge br0
1969 qemu-system-x86_64 linux.img -device virtio-net-pci,netdev=n1 \
1970 -netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper"
1971 -netdev bridge,id=id[,br=bridge][,helper=helper]
1973 Connect a host TAP network interface to a host bridge device.
1974 Use the network helper helper to configure the TAP interface and
1976 attach it to the bridge. The default network helper executable is
1977 /path/to/qemu-bridge-helper and the default bridge device is br0.
1978 Examples:
1980 #launch a QEMU instance with the default network helper to
1982 #connect a TAP device to bridge br0
1983 qemu-system-x86_64 linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1
1984 #launch a QEMU instance with the default network helper to
1988 #connect a TAP device to bridge qemubr0
1989 qemu-system-x86_64 linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1
1990 -netdev socket,id=id[,fd=h][,listen=[host]:port][,connect=host:port]
1992 This host network backend can be used to connect the guest's
1993 network to another QEMU virtual machine using a TCP socket
1994 connection. If listen is specified, QEMU waits for incoming
1995 connections on port (host is optional). connect is used to connect
1996 to another QEMU instance using the listen option. fd=h specifies an
1997 already opened TCP socket.
1998 Example:
2000 # launch a first QEMU instance
2002 qemu-system-x86_64 linux.img \
2003 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2004 -netdev socket,id=n1,listen=:1234
2005 # connect the network of this instance to the network of the first instance
2006 qemu-system-x86_64 linux.img \
2007 -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
2008 -netdev socket,id=n2,connect=127.0.0.1:1234
2009 -netdev socket,id=id[,fd=h][,mcast=maddr:port[,localaddr=addr]]
2011 Configure a socket host network backend to share the guest's
2012 network traffic with another QEMU virtual machines using a UDP
2013 multicast socket, effectively making a bus for every QEMU with same
2014 multicast address maddr and port. NOTES:
2015 1. Several QEMU can be running on different hosts and share same
2017 bus (assuming correct multicast setup for these hosts).
2018 2. mcast support is compatible with User Mode Linux (argument
2020 ethN=mcast), see <http://user-mode-linux.sf.net>.
2021 3. Use fd=h to specify an already opened UDP multicast socket.
2023 Example:
2025 # launch one QEMU instance
2027 qemu-system-x86_64 linux.img \
2028 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2029 -netdev socket,id=n1,mcast=230.0.0.1:1234
2030 # launch another QEMU instance on same "bus"
2031 qemu-system-x86_64 linux.img \
2032 -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
2033 -netdev socket,id=n2,mcast=230.0.0.1:1234
2034 # launch yet another QEMU instance on same "bus"
2035 qemu-system-x86_64 linux.img \
2036 -device e1000,netdev=n3,mac=52:54:00:12:34:58 \
2037 -netdev socket,id=n3,mcast=230.0.0.1:1234
2038 Example (User Mode Linux compat.):
2040 # launch QEMU instance (note mcast address selected is UML's default)
2042 qemu-system-x86_64 linux.img \
2043 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2044 -netdev socket,id=n1,mcast=239.192.168.1:1102
2045 # launch UML
2046 /path/to/linux ubd0=/path/to/root_fs eth0=mcast
2047 Example (send packets from host's 1.2.3.4):
2049 qemu-system-x86_64 linux.img \
2051 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
2052 -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4
2053 -netdev
2055 l2tpv3,id=id,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport],txsession=txsession[,rxsession=rxsession][,ipv6][,udp][,cookie64][,counter][,pincounter][,txcookie=txcookie][,rxcookie=rxcookie][,offset=offset]
2056 Configure a L2TPv3 pseudowire host network backend. L2TPv3
2057 (RFC3391) is a popular protocol to transport Ethernet (and other
2058 Layer 2) data frames between two systems. It is present in routers,
2059 firewalls and the Linux kernel (from version 3.3 onwards).
2060 This transport allows a VM to communicate to another VM, router or
2062 firewall directly.
2063 src=srcaddr
2065 source address (mandatory)
2066 dst=dstaddr
2068 destination address (mandatory)
2069 udp select udp encapsulation (default is ip).
2071 srcport=srcport
2073 source udp port.
2074 dstport=dstport
2076 destination udp port.
2077 ipv6
2079 force v6, otherwise defaults to v4.
2080 rxcookie=rxcookie
2082 txcookie=txcookie
2083 Cookies are a weak form of security in the l2tpv3
2084 specification. Their function is mostly to prevent
2085 misconfiguration. By default they are 32 bit.
2086 cookie64
2088 Set cookie size to 64 bit instead of the default 32
2089 counter=off
2091 Force a 'cut-down' L2TPv3 with no counter as in
2092 draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
2093 pincounter=on
2095 Work around broken counter handling in peer. This may also help
2096 on networks which have packet reorder.
2097 offset=offset
2099 Add an extra offset between header and data
2100 For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to
2102 the bridge br-lan on the remote Linux host 1.2.3.4:
2103 # Setup tunnel on linux host using raw ip as encapsulation
2105 # on 1.2.3.4
2106 ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \
2107 encap udp udp_sport 16384 udp_dport 16384
2108 ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \
2109 0xFFFFFFFF peer_session_id 0xFFFFFFFF
2110 ifconfig vmtunnel0 mtu 1500
2111 ifconfig vmtunnel0 up
2112 brctl addif br-lan vmtunnel0
2113 # on 4.3.2.1
2116 # launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
2117 qemu-system-x86_64 linux.img -device e1000,netdev=n1 \
2119 -netdev l2tpv3,id=n1,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter
2120 -netdev
2122 vde,id=id[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]
2123 Configure VDE backend to connect to PORT n of a vde switch running
2124 on host and listening for incoming connections on socketpath. Use
2125 GROUP groupname and MODE octalmode to change default ownership and
2126 permissions for communication port. This option is only available
2127 if QEMU has been compiled with vde support enabled.
2128 Example:
2130 # launch vde switch
2132 vde_switch -F -sock /tmp/myswitch
2133 # launch QEMU instance
2134 qemu-system-x86_64 linux.img -nic vde,sock=/tmp/myswitch
2135 -netdev vhost-user,chardev=id[,vhostforce=on|off][,queues=n]
2137 Establish a vhost-user netdev, backed by a chardev id. The chardev
2138 should be a unix domain socket backed one. The vhost-user uses a
2139 specifically defined protocol to pass vhost ioctl replacement
2140 messages to an application on the other end of the socket. On non-
2141 MSIX guests, the feature can be forced with vhostforce. Use
2142 'queues=n' to specify the number of queues to be created for
2143 multiqueue vhost-user.
2144 Example:
2146 qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
2148 -numa node,memdev=mem \
2149 -chardev socket,id=chr0,path=/path/to/socket \
2150 -netdev type=vhost-user,id=net0,chardev=chr0 \
2151 -device virtio-net-pci,netdev=net0
2152 -netdev hubport,id=id,hubid=hubid[,netdev=nd]
2154 Create a hub port on the emulated hub with ID hubid.
2155 The hubport netdev lets you connect a NIC to a QEMU emulated hub
2157 instead of a single netdev. Alternatively, you can also connect the
2158 hubport to another netdev with ID nd by using the netdev=nd option.
2159 -net nic[,netdev=nd][,macaddr=mac][,model=type]
2161 [,name=name][,addr=addr][,vectors=v]
2162 Legacy option to configure or create an on-board (or machine
2163 default) Network Interface Card(NIC) and connect it either to the
2164 emulated hub with ID 0 (i.e. the default hub), or to the netdev
2165 nd. The NIC is an e1000 by default on the PC target. Optionally,
2166 the MAC address can be changed to mac, the device address set to
2167 addr (PCI cards only), and a name can be assigned for use in
2168 monitor commands. Optionally, for PCI cards, you can specify the
2169 number v of MSI-X vectors that the card should have; this option
2170 currently only affects virtio cards; set v = 0 to disable MSI-X. If
2171 no -net option is specified, a single NIC is created. QEMU can
2172 emulate several different models of network card. Use "-net
2173 nic,model=help" for a list of available devices for your target.
2174 -net user|tap|bridge|socket|l2tpv3|vde[,...][,name=name]
2176 Configure a host network backend (with the options corresponding to
2177 the same -netdev option) and connect it to the emulated hub 0 (the
2178 default hub). Use name to specify the name of the hub port.
2179 Character device options
2181 The general form of a character device option is:
2183 -chardev backend,id=id[,mux=on|off][,options]
2185 Backend is one of: null, socket, udp, msmouse, vc, ringbuf, file,
2186 pipe, console, serial, pty, stdio, braille, tty, parallel, parport,
2187 spicevmc, spiceport. The specific backend will determine the
2188 applicable options.
2189 Use "-chardev help" to print all available chardev backend types.
2191 All devices must have an id, which can be any string up to 127
2193 characters long. It is used to uniquely identify this device in
2194 other command line directives.
2195 A character device may be used in multiplexing mode by multiple
2197 front-ends. Specify mux=on to enable this mode. A multiplexer is
2198 a "1:N" device, and here the "1" end is your specified chardev
2199 backend, and the "N" end is the various parts of QEMU that can talk
2200 to a chardev. If you create a chardev with id=myid and mux=on,
2201 QEMU will create a multiplexer with your specified ID, and you can
2202 then configure multiple front ends to use that chardev ID for their
2203 input/output. Up to four different front ends can be connected to a
2204 single multiplexed chardev. (Without multiplexing enabled, a
2205 chardev can only be used by a single front end.) For instance you
2206 could use this to allow a single stdio chardev to be used by two
2207 serial ports and the QEMU monitor:
2208 -chardev stdio,mux=on,id=char0 \
2210 -mon chardev=char0,mode=readline \
2211 -serial chardev:char0 \
2212 -serial chardev:char0
2213 You can have more than one multiplexer in a system configuration;
2215 for instance you could have a TCP port multiplexed between UART 0
2216 and UART 1, and stdio multiplexed between the QEMU monitor and a
2217 parallel port:
2218 -chardev stdio,mux=on,id=char0 \
2220 -mon chardev=char0,mode=readline \
2221 -parallel chardev:char0 \
2222 -chardev tcp,...,mux=on,id=char1 \
2223 -serial chardev:char1 \
2224 -serial chardev:char1
2225 When you're using a multiplexed character device, some escape
2227 sequences are interpreted in the input.
2228 Note that some other command line options may implicitly create
2230 multiplexed character backends; for instance -serial mon:stdio
2231 creates a multiplexed stdio backend connected to the serial port
2232 and the QEMU monitor, and -nographic also multiplexes the console
2233 and the monitor to stdio.
2234 There is currently no support for multiplexing in the other
2236 direction (where a single QEMU front end takes input and output
2237 from multiple chardevs).
2238 Every backend supports the logfile option, which supplies the path
2240 to a file to record all data transmitted via the backend. The
2241 logappend option controls whether the log file will be truncated or
2242 appended to when opened.
2243 The available backends are:
2245 -chardev null,id=id
2247 A void device. This device will not emit any data, and will drop
2248 any data it receives. The null backend does not take any options.
2249 -chardev socket,id=id[,TCP options or unix
2251 options][,server][,nowait][,telnet][,websocket][,reconnect=seconds][,tls-creds=id][,tls-authz=id]
2252 Create a two-way stream socket, which can be either a TCP or a unix
2253 socket. A unix socket will be created if path is specified.
2254 Behaviour is undefined if TCP options are specified for a unix
2255 socket.
2256 server specifies that the socket shall be a listening socket.
2258 nowait specifies that QEMU should not block waiting for a client to
2260 connect to a listening socket.
2261 telnet specifies that traffic on the socket should interpret telnet
2263 escape sequences.
2264 websocket specifies that the socket uses WebSocket protocol for
2266 communication.
2267 reconnect sets the timeout for reconnecting on non-server sockets
2269 when the remote end goes away. qemu will delay this many seconds
2270 and then attempt to reconnect. Zero disables reconnecting, and is
2271 the default.
2272 tls-creds requests enablement of the TLS protocol for encryption,
2274 and specifies the id of the TLS credentials to use for the
2275 handshake. The credentials must be previously created with the
2276 -object tls-creds argument.
2277 tls-auth provides the ID of the QAuthZ authorization object against
2279 which the client's x509 distinguished name will be validated. This
2280 object is only resolved at time of use, so can be deleted and
2281 recreated on the fly while the chardev server is active. If
2282 missing, it will default to denying access.
2283 TCP and unix socket options are given below:
2285 TCP options: port=port[,host=host][,to=to][,ipv4][,ipv6][,nodelay]
2287 host for a listening socket specifies the local address to be
2288 bound. For a connecting socket species the remote host to
2289 connect to. host is optional for listening sockets. If not
2290 specified it defaults to 0.0.0.0.
2291 port for a listening socket specifies the local port to be
2293 bound. For a connecting socket specifies the port on the remote
2294 host to connect to. port can be given as either a port number
2295 or a service name. port is required.
2296 to is only relevant to listening sockets. If it is specified,
2298 and port cannot be bound, QEMU will attempt to bind to
2299 subsequent ports up to and including to until it succeeds. to
2300 must be specified as a port number.
2301 ipv4 and ipv6 specify that either IPv4 or IPv6 must be used.
2303 If neither is specified the socket may use either protocol.
2304 nodelay disables the Nagle algorithm.
2306 unix options: path=path
2308 path specifies the local path of the unix socket. path is
2309 required.
2310 -chardev
2312 udp,id=id[,host=host],port=port[,localaddr=localaddr][,localport=localport][,ipv4][,ipv6]
2313 Sends all traffic from the guest to a remote host over UDP.
2314 host specifies the remote host to connect to. If not specified it
2316 defaults to "localhost".
2317 port specifies the port on the remote host to connect to. port is
2319 required.
2320 localaddr specifies the local address to bind to. If not specified
2322 it defaults to 0.0.0.0.
2323 localport specifies the local port to bind to. If not specified any
2325 available local port will be used.
2326 ipv4 and ipv6 specify that either IPv4 or IPv6 must be used. If
2328 neither is specified the device may use either protocol.
2329 -chardev msmouse,id=id
2331 Forward QEMU's emulated msmouse events to the guest. msmouse does
2332 not take any options.
2333 -chardev
2335 vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]
2336 Connect to a QEMU text console. vc may optionally be given a
2337 specific size.
2338 width and height specify the width and height respectively of the
2340 console, in pixels.
2341 cols and rows specify that the console be sized to fit a text
2343 console with the given dimensions.
2344 -chardev ringbuf,id=id[,size=size]
2346 Create a ring buffer with fixed size size. size must be a power of
2347 two and defaults to "64K".
2348 -chardev file,id=id,path=path
2350 Log all traffic received from the guest to a file.
2351 path specifies the path of the file to be opened. This file will be
2353 created if it does not already exist, and overwritten if it does.
2354 path is required.
2355 -chardev pipe,id=id,path=path
2357 Create a two-way connection to the guest. The behaviour differs
2358 slightly between Windows hosts and other hosts:
2359 On Windows, a single duplex pipe will be created at \\.pipe\path.
2361 On other hosts, 2 pipes will be created called path.in and
2363 path.out. Data written to path.in will be received by the guest.
2364 Data written by the guest can be read from path.out. QEMU will not
2365 create these fifos, and requires them to be present.
2366 path forms part of the pipe path as described above. path is
2368 required.
2369 -chardev console,id=id
2371 Send traffic from the guest to QEMU's standard output. console does
2372 not take any options.
2373 console is only available on Windows hosts.
2375 -chardev serial,id=id,path=path
2377 Send traffic from the guest to a serial device on the host.
2378 On Unix hosts serial will actually accept any tty device, not only
2380 serial lines.
2381 path specifies the name of the serial device to open.
2383 -chardev pty,id=id
2385 Create a new pseudo-terminal on the host and connect to it. pty
2386 does not take any options.
2387 pty is not available on Windows hosts.
2389 -chardev stdio,id=id[,signal=on|off]
2391 Connect to standard input and standard output of the QEMU process.
2392 signal controls if signals are enabled on the terminal, that
2394 includes exiting QEMU with the key sequence Control-c. This option
2395 is enabled by default, use signal=off to disable it.
2396 -chardev braille,id=id
2398 Connect to a local BrlAPI server. braille does not take any
2399 options.
2400 -chardev tty,id=id,path=path
2402 tty is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
2403 DragonFlyBSD hosts. It is an alias for serial.
2404 path specifies the path to the tty. path is required.
2406 -chardev parallel,id=id,path=path
2408 -chardev parport,id=id,path=path
2409 parallel is only available on Linux, FreeBSD and DragonFlyBSD
2410 hosts.
2411 Connect to a local parallel port.
2413 path specifies the path to the parallel port device. path is
2415 required.
2416 -chardev spicevmc,id=id,debug=debug,name=name
2418 spicevmc is only available when spice support is built in.
2419 debug debug level for spicevmc
2421 name name of spice channel to connect to
2423 Connect to a spice virtual machine channel, such as vdiport.
2425 -chardev spiceport,id=id,debug=debug,name=name
2427 spiceport is only available when spice support is built in.
2428 debug debug level for spicevmc
2430 name name of spice port to connect to
2432 Connect to a spice port, allowing a Spice client to handle the
2434 traffic identified by a name (preferably a fqdn).
2435 Bluetooth(R) options
2437 -bt hci[...]
2439 Defines the function of the corresponding Bluetooth HCI. -bt
2440 options are matched with the HCIs present in the chosen machine
2441 type. For example when emulating a machine with only one HCI built
2442 into it, only the first "-bt hci[...]" option is valid and defines
2443 the HCI's logic. The Transport Layer is decided by the machine
2444 type. Currently the machines "n800" and "n810" have one HCI and
2445 all other machines have none.
2446 Note: This option and the whole bluetooth subsystem is considered
2448 as deprecated. If you still use it, please send a mail to
2449 <qemu-devel@nongnu.org> where you describe your usecase.
2450 The following three types are recognized:
2452 -bt hci,null
2454 (default) The corresponding Bluetooth HCI assumes no internal
2455 logic and will not respond to any HCI commands or emit events.
2456 -bt hci,host[:id]
2458 ("bluez" only) The corresponding HCI passes commands / events
2459 to / from the physical HCI identified by the name id (default:
2460 "hci0") on the computer running QEMU. Only available on
2461 "bluez" capable systems like Linux.
2462 -bt hci[,vlan=n]
2464 Add a virtual, standard HCI that will participate in the
2465 Bluetooth scatternet n (default 0). Similarly to -net VLANs,
2466 devices inside a bluetooth network n can only communicate with
2467 other devices in the same network (scatternet).
2468 -bt vhci[,vlan=n]
2470 (Linux-host only) Create a HCI in scatternet n (default 0) attached
2471 to the host bluetooth stack instead of to the emulated target.
2472 This allows the host and target machines to participate in a common
2473 scatternet and communicate. Requires the Linux "vhci" driver
2474 installed. Can be used as following:
2475 qemu-system-x86_64 [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
2477 -bt device:dev[,vlan=n]
2479 Emulate a bluetooth device dev and place it in network n (default
2480 0). QEMU can only emulate one type of bluetooth devices currently:
2481 keyboard
2483 Virtual wireless keyboard implementing the HIDP bluetooth
2484 profile.
2485 TPM device options
2487 The general form of a TPM device option is:
2489 -tpmdev backend,id=id[,options]
2491 The specific backend type will determine the applicable options.
2492 The "-tpmdev" option creates the TPM backend and requires a
2493 "-device" option that specifies the TPM frontend interface model.
2494 Use "-tpmdev help" to print all available TPM backend types.
2496 The available backends are:
2498 -tpmdev passthrough,id=id,path=path,cancel-path=cancel-path
2500 (Linux-host only) Enable access to the host's TPM using the
2501 passthrough driver.
2502 path specifies the path to the host's TPM device, i.e., on a Linux
2504 host this would be "/dev/tpm0". path is optional and by default
2505 "/dev/tpm0" is used.
2506 cancel-path specifies the path to the host TPM device's sysfs entry
2508 allowing for cancellation of an ongoing TPM command. cancel-path
2509 is optional and by default QEMU will search for the sysfs entry to
2510 use.
2511 Some notes about using the host's TPM with the passthrough driver:
2513 The TPM device accessed by the passthrough driver must not be used
2515 by any other application on the host.
2516 Since the host's firmware (BIOS/UEFI) has already initialized the
2518 TPM, the VM's firmware (BIOS/UEFI) will not be able to initialize
2519 the TPM again and may therefore not show a TPM-specific menu that
2520 would otherwise allow the user to configure the TPM, e.g., allow
2521 the user to enable/disable or activate/deactivate the TPM.
2522 Further, if TPM ownership is released from within a VM then the
2523 host's TPM will get disabled and deactivated. To enable and
2524 activate the TPM again afterwards, the host has to be rebooted and
2525 the user is required to enter the firmware's menu to enable and
2526 activate the TPM. If the TPM is left disabled and/or deactivated
2527 most TPM commands will fail.
2528 To create a passthrough TPM use the following two options:
2530 -tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
2532 Note that the "-tpmdev" id is "tpm0" and is referenced by
2534 "tpmdev=tpm0" in the device option.
2535 -tpmdev emulator,id=id,chardev=dev
2537 (Linux-host only) Enable access to a TPM emulator using Unix domain
2538 socket based chardev backend.
2539 chardev specifies the unique ID of a character device backend that
2541 provides connection to the software TPM server.
2542 To create a TPM emulator backend device with chardev socket
2544 backend:
2545 -chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0
2547 Linux/Multiboot boot specific
2549 When using these options, you can use a given Linux or Multiboot kernel
2551 without installing it in the disk image. It can be useful for easier
2552 testing of various kernels.
2553 -kernel bzImage
2555 Use bzImage as kernel image. The kernel can be either a Linux
2556 kernel or in multiboot format.
2557 -append cmdline
2559 Use cmdline as kernel command line
2560 -initrd file
2562 Use file as initial ram disk.
2563 -initrd "file1 arg=foo,file2"
2565 This syntax is only available with multiboot.
2566 Use file1 and file2 as modules and pass arg=foo as parameter to the
2568 first module.
2569 -dtb file
2571 Use file as a device tree binary (dtb) image and pass it to the
2572 kernel on boot.
2573 Debug/Expert options
2575 -fw_cfg [name=]name,file=file
2577 Add named fw_cfg entry with contents from file file.
2578 -fw_cfg [name=]name,string=str
2580 Add named fw_cfg entry with contents from string str.
2581 The terminating NUL character of the contents of str will not be
2583 included as part of the fw_cfg item data. To insert contents with
2584 embedded NUL characters, you have to use the file parameter.
2585 The fw_cfg entries are passed by QEMU through to the guest.
2587 Example:
2589 -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
2591 creates an fw_cfg entry named opt/com.mycompany/blob with contents
2593 from ./my_blob.bin.
2594 -serial dev
2596 Redirect the virtual serial port to host character device dev. The
2597 default device is "vc" in graphical mode and "stdio" in non
2598 graphical mode.
2599 This option can be used several times to simulate up to 4 serial
2601 ports.
2602 Use "-serial none" to disable all serial ports.
2604 Available character devices are:
2606 vc[:WxH]
2608 Virtual console. Optionally, a width and height can be given in
2609 pixel with
2610 vc:800x600
2612 It is also possible to specify width or height in characters:
2614 vc:80Cx24C
2616 pty [Linux only] Pseudo TTY (a new PTY is automatically allocated)
2618 none
2620 No device is allocated.
2621 null
2623 void device
2624 chardev:id
2626 Use a named character device defined with the "-chardev"
2627 option.
2628 /dev/XXX
2630 [Linux only] Use host tty, e.g. /dev/ttyS0. The host serial
2631 port parameters are set according to the emulated ones.
2632 /dev/parportN
2634 [Linux only, parallel port only] Use host parallel port N.
2635 Currently SPP and EPP parallel port features can be used.
2636 file:filename
2638 Write output to filename. No character can be read.
2639 stdio
2641 [Unix only] standard input/output
2642 pipe:filename
2644 name pipe filename
2645 COMn
2647 [Windows only] Use host serial port n
2648 udp:[remote_host]:remote_port[@[src_ip]:src_port]
2650 This implements UDP Net Console. When remote_host or src_ip
2651 are not specified they default to 0.0.0.0. When not using a
2652 specified src_port a random port is automatically chosen.
2653 If you just want a simple readonly console you can use "netcat"
2655 or "nc", by starting QEMU with: "-serial udp::4555" and nc as:
2656 "nc -u -l -p 4555". Any time QEMU writes something to that port
2657 it will appear in the netconsole session.
2658 If you plan to send characters back via netconsole or you want
2660 to stop and start QEMU a lot of times, you should have QEMU use
2661 the same source port each time by using something like "-serial
2662 udp::4555@4556" to QEMU. Another approach is to use a patched
2663 version of netcat which can listen to a TCP port and send and
2664 receive characters via udp. If you have a patched version of
2665 netcat which activates telnet remote echo and single char
2666 transfer, then you can use the following options to set up a
2667 netcat redirector to allow telnet on port 5555 to access the
2668 QEMU port.
2669 "QEMU Options:"
2671 -serial udp::4555@4556
2672 "netcat options:"
2674 -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
2675 "telnet options:"
2677 localhost 5555
2678 tcp:[host]:port[,server][,nowait][,nodelay][,reconnect=seconds]
2680 The TCP Net Console has two modes of operation. It can send
2681 the serial I/O to a location or wait for a connection from a
2682 location. By default the TCP Net Console is sent to host at
2683 the port. If you use the server option QEMU will wait for a
2684 client socket application to connect to the port before
2685 continuing, unless the "nowait" option was specified. The
2686 "nodelay" option disables the Nagle buffering algorithm. The
2687 "reconnect" option only applies if noserver is set, if the
2688 connection goes down it will attempt to reconnect at the given
2689 interval. If host is omitted, 0.0.0.0 is assumed. Only one TCP
2690 connection at a time is accepted. You can use "telnet" to
2691 connect to the corresponding character device.
2692 "Example to send tcp console to 192.168.0.2 port 4444"
2694 -serial tcp:192.168.0.2:4444
2695 "Example to listen and wait on port 4444 for connection"
2697 -serial tcp::4444,server
2698 "Example to not wait and listen on ip 192.168.0.100 port 4444"
2700 -serial tcp:192.168.0.100:4444,server,nowait
2701 telnet:host:port[,server][,nowait][,nodelay]
2703 The telnet protocol is used instead of raw tcp sockets. The
2704 options work the same as if you had specified "-serial tcp".
2705 The difference is that the port acts like a telnet server or
2706 client using telnet option negotiation. This will also allow
2707 you to send the MAGIC_SYSRQ sequence if you use a telnet that
2708 supports sending the break sequence. Typically in unix telnet
2709 you do it with Control-] and then type "send break" followed by
2710 pressing the enter key.
2711 websocket:host:port,server[,nowait][,nodelay]
2713 The WebSocket protocol is used instead of raw tcp socket. The
2714 port acts as a WebSocket server. Client mode is not supported.
2715 unix:path[,server][,nowait][,reconnect=seconds]
2717 A unix domain socket is used instead of a tcp socket. The
2718 option works the same as if you had specified "-serial tcp"
2719 except the unix domain socket path is used for connections.
2720 mon:dev_string
2722 This is a special option to allow the monitor to be multiplexed
2723 onto another serial port. The monitor is accessed with key
2724 sequence of Control-a and then pressing c. dev_string should
2725 be any one of the serial devices specified above. An example
2726 to multiplex the monitor onto a telnet server listening on port
2727 4444 would be:
2728 "-serial mon:telnet::4444,server,nowait"
2730 When the monitor is multiplexed to stdio in this way, Ctrl+C
2732 will not terminate QEMU any more but will be passed to the
2733 guest instead.
2734 braille
2736 Braille device. This will use BrlAPI to display the braille
2737 output on a real or fake device.
2738 msmouse
2740 Three button serial mouse. Configure the guest to use Microsoft
2741 protocol.
2742 -parallel dev
2744 Redirect the virtual parallel port to host device dev (same devices
2745 as the serial port). On Linux hosts, /dev/parportN can be used to
2746 use hardware devices connected on the corresponding host parallel
2747 port.
2748 This option can be used several times to simulate up to 3 parallel
2750 ports.
2751 Use "-parallel none" to disable all parallel ports.
2753 -monitor dev
2755 Redirect the monitor to host device dev (same devices as the serial
2756 port). The default device is "vc" in graphical mode and "stdio" in
2757 non graphical mode. Use "-monitor none" to disable the default
2758 monitor.
2759 -qmp dev
2761 Like -monitor but opens in 'control' mode.
2762 -qmp-pretty dev
2764 Like -qmp but uses pretty JSON formatting.
2765 -mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]
2767 Setup monitor on chardev name. "pretty" turns on JSON pretty
2768 printing easing human reading and debugging.
2769 -debugcon dev
2771 Redirect the debug console to host device dev (same devices as the
2772 serial port). The debug console is an I/O port which is typically
2773 port 0xe9; writing to that I/O port sends output to this device.
2774 The default device is "vc" in graphical mode and "stdio" in non
2775 graphical mode.
2776 -pidfile file
2778 Store the QEMU process PID in file. It is useful if you launch QEMU
2779 from a script.
2780 -singlestep
2782 Run the emulation in single step mode.
2783 --preconfig
2785 Pause QEMU for interactive configuration before the machine is
2786 created, which allows querying and configuring properties that will
2787 affect machine initialization. Use QMP command 'x-exit-preconfig'
2788 to exit the preconfig state and move to the next state (i.e. run
2789 guest if -S isn't used or pause the second time if -S is used).
2790 This option is experimental.
2791 -S Do not start CPU at startup (you must type 'c' in the monitor).
2793 -realtime mlock=on|off
2795 Run qemu with realtime features. mlocking qemu and guest memory
2796 can be enabled via mlock=on (enabled by default).
2797 -overcommit mem-lock=on|off
2799 -overcommit cpu-pm=on|off
2800 Run qemu with hints about host resource overcommit. The default is
2801 to assume that host overcommits all resources.
2802 Locking qemu and guest memory can be enabled via mem-lock=on
2804 (disabled by default). This works when host memory is not
2805 overcommitted and reduces the worst-case latency for guest. This
2806 is equivalent to realtime.
2807 Guest ability to manage power state of host cpus (increasing
2809 latency for other processes on the same host cpu, but decreasing
2810 latency for guest) can be enabled via cpu-pm=on (disabled by
2811 default). This works best when host CPU is not overcommitted. When
2812 used, host estimates of CPU cycle and power utilization will be
2813 incorrect, not taking into account guest idle time.
2814 -gdb dev
2816 Wait for gdb connection on device dev. Typical connections will
2817 likely be TCP-based, but also UDP, pseudo TTY, or even stdio are
2818 reasonable use case. The latter is allowing to start QEMU from
2819 within gdb and establish the connection via a pipe:
2820 (gdb) target remote | exec qemu-system-x86_64 -gdb stdio ...
2822 -s Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port
2824 1234.
2825 -d item1[,...]
2827 Enable logging of specified items. Use '-d help' for a list of log
2828 items.
2829 -D logfile
2831 Output log in logfile instead of to stderr
2832 -dfilter range1[,...]
2834 Filter debug output to that relevant to a range of target
2835 addresses. The filter spec can be either start+size, start-size or
2836 start..end where start end and size are the addresses and sizes
2837 required. For example:
2838 -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000
2840 Will dump output for any code in the 0x1000 sized block starting at
2842 0x8000 and the 0x200 sized block starting at 0xffffffc000080000 and
2843 another 0x1000 sized block starting at 0xffffffc00005f000.
2844 -seed number
2846 Force the guest to use a deterministic pseudo-random number
2847 generator, seeded with number. This does not affect crypto
2848 routines within the host.
2849 -L path
2851 Set the directory for the BIOS, VGA BIOS and keymaps.
2852 To list all the data directories, use "-L help".
2854 -bios file
2856 Set the filename for the BIOS.
2857 -enable-kvm
2859 Enable KVM full virtualization support. This option is only
2860 available if KVM support is enabled when compiling.
2861 -xen-domid id
2863 Specify xen guest domain id (XEN only).
2864 -xen-attach
2866 Attach to existing xen domain. libxl will use this when starting
2867 QEMU (XEN only). Restrict set of available xen operations to
2868 specified domain id (XEN only).
2869 -no-reboot
2871 Exit instead of rebooting.
2872 -no-shutdown
2874 Don't exit QEMU on guest shutdown, but instead only stop the
2875 emulation. This allows for instance switching to monitor to commit
2876 changes to the disk image.
2877 -loadvm file
2879 Start right away with a saved state ("loadvm" in monitor)
2880 -daemonize
2882 Daemonize the QEMU process after initialization. QEMU will not
2883 detach from standard IO until it is ready to receive connections on
2884 any of its devices. This option is a useful way for external
2885 programs to launch QEMU without having to cope with initialization
2886 race conditions.
2887 -option-rom file
2889 Load the contents of file as an option ROM. This option is useful
2890 to load things like EtherBoot.
2891 -rtc
2893 [base=utc|localtime|datetime][,clock=host|rt|vm][,driftfix=none|slew]
2894 Specify base as "utc" or "localtime" to let the RTC start at the
2895 current UTC or local time, respectively. "localtime" is required
2896 for correct date in MS-DOS or Windows. To start at a specific point
2897 in time, provide datetime in the format "2006-06-17T16:01:21" or
2898 "2006-06-17". The default base is UTC.
2899 By default the RTC is driven by the host system time. This allows
2901 using of the RTC as accurate reference clock inside the guest,
2902 specifically if the host time is smoothly following an accurate
2903 external reference clock, e.g. via NTP. If you want to isolate the
2904 guest time from the host, you can set clock to "rt" instead, which
2905 provides a host monotonic clock if host support it. To even
2906 prevent the RTC from progressing during suspension, you can set
2907 clock to "vm" (virtual clock). clock=vm is recommended especially
2908 in icount mode in order to preserve determinism; however, note that
2909 in icount mode the speed of the virtual clock is variable and can
2910 in general differ from the host clock.
2911 Enable driftfix (i386 targets only) if you experience time drift
2913 problems, specifically with Windows' ACPI HAL. This option will try
2914 to figure out how many timer interrupts were not processed by the
2915 Windows guest and will re-inject them.
2916 -icount
2918 [shift=N|auto][,rr=record|replay,rrfile=filename,rrsnapshot=snapshot]
2919 Enable virtual instruction counter. The virtual cpu will execute
2920 one instruction every 2^N ns of virtual time. If "auto" is
2921 specified then the virtual cpu speed will be automatically adjusted
2922 to keep virtual time within a few seconds of real time.
2923 When the virtual cpu is sleeping, the virtual time will advance at
2925 default speed unless sleep=on|off is specified. With sleep=on|off,
2926 the virtual time will jump to the next timer deadline instantly
2927 whenever the virtual cpu goes to sleep mode and will not advance if
2928 no timer is enabled. This behavior give deterministic execution
2929 times from the guest point of view.
2930 Note that while this option can give deterministic behavior, it
2932 does not provide cycle accurate emulation. Modern CPUs contain
2933 superscalar out of order cores with complex cache hierarchies. The
2934 number of instructions executed often has little or no correlation
2935 with actual performance.
2936 align=on will activate the delay algorithm which will try to
2938 synchronise the host clock and the virtual clock. The goal is to
2939 have a guest running at the real frequency imposed by the shift
2940 option. Whenever the guest clock is behind the host clock and if
2941 align=on is specified then we print a message to the user to inform
2942 about the delay. Currently this option does not work when shift is
2943 "auto". Note: The sync algorithm will work for those shift values
2944 for which the guest clock runs ahead of the host clock. Typically
2945 this happens when the shift value is high (how high depends on the
2946 host machine).
2947 When rr option is specified deterministic record/replay is enabled.
2949 Replay log is written into filename file in record mode and read
2950 from this file in replay mode.
2951 Option rrsnapshot is used to create new vm snapshot named snapshot
2953 at the start of execution recording. In replay mode this option is
2954 used to load the initial VM state.
2955 -watchdog model
2957 Create a virtual hardware watchdog device. Once enabled (by a
2958 guest action), the watchdog must be periodically polled by an agent
2959 inside the guest or else the guest will be restarted. Choose a
2960 model for which your guest has drivers.
2961 The model is the model of hardware watchdog to emulate. Use
2963 "-watchdog help" to list available hardware models. Only one
2964 watchdog can be enabled for a guest.
2965 The following models may be available:
2967 ib700
2969 iBASE 700 is a very simple ISA watchdog with a single timer.
2970 i6300esb
2972 Intel 6300ESB I/O controller hub is a much more featureful PCI-
2973 based dual-timer watchdog.
2974 diag288
2976 A virtual watchdog for s390x backed by the diagnose 288
2977 hypercall (currently KVM only).
2978 -watchdog-action action
2980 The action controls what QEMU will do when the watchdog timer
2981 expires. The default is "reset" (forcefully reset the guest).
2982 Other possible actions are: "shutdown" (attempt to gracefully
2983 shutdown the guest), "poweroff" (forcefully poweroff the guest),
2984 "inject-nmi" (inject a NMI into the guest), "pause" (pause the
2985 guest), "debug" (print a debug message and continue), or "none" (do
2986 nothing).
2987 Note that the "shutdown" action requires that the guest responds to
2989 ACPI signals, which it may not be able to do in the sort of
2990 situations where the watchdog would have expired, and thus
2991 "-watchdog-action shutdown" is not recommended for production use.
2992 Examples:
2994 "-watchdog i6300esb -watchdog-action pause"
2996 "-watchdog ib700"
2997 -echr numeric_ascii_value
2998 Change the escape character used for switching to the monitor when
2999 using monitor and serial sharing. The default is 0x01 when using
3000 the "-nographic" option. 0x01 is equal to pressing "Control-a".
3001 You can select a different character from the ascii control keys
3002 where 1 through 26 map to Control-a through Control-z. For
3003 instance you could use the either of the following to change the
3004 escape character to Control-t.
3005 "-echr 0x14"
3007 "-echr 20"
3008 -show-cursor
3009 Show cursor.
3010 -tb-size n
3012 Set TB size.
3013 -incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]
3015 -incoming rdma:host:port[,ipv4][,ipv6]
3016 Prepare for incoming migration, listen on a given tcp port.
3017 -incoming unix:socketpath
3019 Prepare for incoming migration, listen on a given unix socket.
3020 -incoming fd:fd
3022 Accept incoming migration from a given filedescriptor.
3023 -incoming exec:cmdline
3025 Accept incoming migration as an output from specified external
3026 command.
3027 -incoming defer
3029 Wait for the URI to be specified via migrate_incoming. The monitor
3030 can be used to change settings (such as migration parameters) prior
3031 to issuing the migrate_incoming to allow the migration to begin.
3032 -only-migratable
3034 Only allow migratable devices. Devices will not be allowed to enter
3035 an unmigratable state.
3036 -nodefaults
3038 Don't create default devices. Normally, QEMU sets the default
3039 devices like serial port, parallel port, virtual console, monitor
3040 device, VGA adapter, floppy and CD-ROM drive and others. The
3041 "-nodefaults" option will disable all those default devices.
3042 -chroot dir
3044 Immediately before starting guest execution, chroot to the
3045 specified directory. Especially useful in combination with -runas.
3046 -runas user
3048 Immediately before starting guest execution, drop root privileges,
3049 switching to the specified user.
3050 -prom-env variable=value
3052 Set OpenBIOS nvram variable to given value (PPC, SPARC only).
3053 -semihosting
3055 Enable semihosting mode (ARM, M68K, Xtensa, MIPS, Nios II only).
3056 -semihosting-config
3058 [enable=on|off][,target=native|gdb|auto][,chardev=id][,arg=str[,...]]
3059 Enable and configure semihosting (ARM, M68K, Xtensa, MIPS, Nios II
3060 only).
3061 target="native|gdb|auto"
3063 Defines where the semihosting calls will be addressed, to QEMU
3064 ("native") or to GDB ("gdb"). The default is "auto", which
3065 means "gdb" during debug sessions and "native" otherwise.
3066 chardev=str1
3068 Send the output to a chardev backend output for native or auto
3069 output when not in gdb
3070 arg=str1,arg=str2,...
3072 Allows the user to pass input arguments, and can be used
3073 multiple times to build up a list. The old-style
3074 "-kernel"/"-append" method of passing a command line is still
3075 supported for backward compatibility. If both the
3076 "--semihosting-config arg" and the "-kernel"/"-append" are
3077 specified, the former is passed to semihosting as it always
3078 takes precedence.
3079 -old-param
3081 Old param mode (ARM only).
3082 -sandbox
3084 arg[,obsolete=string][,elevateprivileges=string][,spawn=string][,resourcecontrol=string]
3085 Enable Seccomp mode 2 system call filter. 'on' will enable syscall
3086 filtering and 'off' will disable it. The default is 'off'.
3087 obsolete=string
3089 Enable Obsolete system calls
3090 elevateprivileges=string
3092 Disable set*uid|gid system calls
3093 spawn=string
3095 Disable *fork and execve
3096 resourcecontrol=string
3098 Disable process affinity and schedular priority
3099 -readconfig file
3101 Read device configuration from file. This approach is useful when
3102 you want to spawn QEMU process with many command line options but
3103 you don't want to exceed the command line character limit.
3104 -writeconfig file
3106 Write device configuration to file. The file can be either filename
3107 to save command line and device configuration into file or dash
3108 "-") character to print the output to stdout. This can be later
3109 used as input file for "-readconfig" option.
3110 -no-user-config
3112 The "-no-user-config" option makes QEMU not load any of the user-
3113 provided config files on sysconfdir.
3114 -trace [[enable=]pattern][,events=file][,file=file]
3116 Specify tracing options.
3117 [enable=]pattern
3119 Immediately enable events matching pattern (either event name
3120 or a globbing pattern). This option is only available if QEMU
3121 has been compiled with the simple, log or ftrace tracing
3122 backend. To specify multiple events or patterns, specify the
3123 -trace option multiple times.
3124 Use "-trace help" to print a list of names of trace points.
3126 events=file
3128 Immediately enable events listed in file. The file must
3129 contain one event name (as listed in the trace-events-all file)
3130 per line; globbing patterns are accepted too. This option is
3131 only available if QEMU has been compiled with the simple, log
3132 or ftrace tracing backend.
3133 file=file
3135 Log output traces to file. This option is only available if
3136 QEMU has been compiled with the simple tracing backend.
3137 -plugin file=file[,arg=string]
3139 Load a plugin.
3140 file=file
3142 Load the given plugin from a shared library file.
3143 arg=string
3145 Argument string passed to the plugin. (Can be given multiple
3146 times.)
3147 -enable-fips
3149 Enable FIPS 140-2 compliance mode.
3150 -msg timestamp[=on|off]
3152 prepend a timestamp to each log message.(default:on)
3153 -dump-vmstate file
3155 Dump json-encoded vmstate information for current machine type to
3156 file in file
3157 -enable-sync-profile
3159 Enable synchronization profiling.
3160 Generic object creation
3162 -object typename[,prop1=value1,...]
3164 Create a new object of type typename setting properties in the
3165 order they are specified. Note that the 'id' property must be set.
3166 These objects are placed in the '/objects' path.
3167 -object
3169 memory-backend-file,id=id,size=size,mem-path=dir,share=on|off,discard-data=on|off,merge=on|off,dump=on|off,prealloc=on|off,host-nodes=host-
3170 nodes,policy=default|preferred|bind|interleave,align=align
3171 Creates a memory file backend object, which can be used to back
3172 the guest RAM with huge pages.
3173 The id parameter is a unique ID that will be used to reference
3175 this memory region when configuring the -numa argument.
3176 The size option provides the size of the memory region, and
3178 accepts common suffixes, eg 500M.
3179 The mem-path provides the path to either a shared memory or
3181 huge page filesystem mount.
3182 The share boolean option determines whether the memory region
3184 is marked as private to QEMU, or shared. The latter allows a
3185 co-operating external process to access the QEMU memory region.
3186 The share is also required for pvrdma devices due to
3188 limitations in the RDMA API provided by Linux.
3189 Setting share=on might affect the ability to configure NUMA
3191 bindings for the memory backend under some circumstances, see
3192 Documentation/vm/numa_memory_policy.txt on the Linux kernel
3193 source tree for additional details.
3194 Setting the discard-data boolean option to on indicates that
3196 file contents can be destroyed when QEMU exits, to avoid
3197 unnecessarily flushing data to the backing file. Note that
3198 discard-data is only an optimization, and QEMU might not
3199 discard file contents if it aborts unexpectedly or is
3200 terminated using SIGKILL.
3201 The merge boolean option enables memory merge, also known as
3203 MADV_MERGEABLE, so that Kernel Samepage Merging will consider
3204 the pages for memory deduplication.
3205 Setting the dump boolean option to off excludes the memory from
3207 core dumps. This feature is also known as MADV_DONTDUMP.
3208 The prealloc boolean option enables memory preallocation.
3210 The host-nodes option binds the memory range to a list of NUMA
3212 host nodes.
3213 The policy option sets the NUMA policy to one of the following
3215 values:
3216 default
3218 default host policy
3219 preferred
3221 prefer the given host node list for allocation
3222 bind
3224 restrict memory allocation to the given host node list
3225 interleave
3227 interleave memory allocations across the given host node
3228 list
3229 The align option specifies the base address alignment when QEMU
3231 mmap(2) mem-path, and accepts common suffixes, eg 2M. Some
3232 backend store specified by mem-path requires an alignment
3233 different than the default one used by QEMU, eg the device DAX
3234 /dev/dax0.0 requires 2M alignment rather than 4K. In such
3235 cases, users can specify the required alignment via this
3236 option.
3237 The pmem option specifies whether the backing file specified by
3239 mem-path is in host persistent memory that can be accessed
3240 using the SNIA NVM programming model (e.g. Intel NVDIMM). If
3241 pmem is set to 'on', QEMU will take necessary operations to
3242 guarantee the persistence of its own writes to mem-path (e.g.
3243 in vNVDIMM label emulation and live migration). Also, we will
3244 map the backend-file with MAP_SYNC flag, which ensures the file
3245 metadata is in sync for mem-path in case of host crash or a
3246 power failure. MAP_SYNC requires support from both the host
3247 kernel (since Linux kernel 4.15) and the filesystem of mem-path
3248 mounted with DAX option.
3249 -object
3251 memory-backend-ram,id=id,merge=on|off,dump=on|off,share=on|off,prealloc=on|off,size=size,host-nodes=host-
3252 nodes,policy=default|preferred|bind|interleave
3253 Creates a memory backend object, which can be used to back the
3254 guest RAM. Memory backend objects offer more control than the
3255 -m option that is traditionally used to define guest RAM.
3256 Please refer to memory-backend-file for a description of the
3257 options.
3258 -object
3260 memory-backend-memfd,id=id,merge=on|off,dump=on|off,share=on|off,prealloc=on|off,size=size,host-nodes=host-
3261 nodes,policy=default|preferred|bind|interleave,seal=on|off,hugetlb=on|off,hugetlbsize=size
3262 Creates an anonymous memory file backend object, which allows
3263 QEMU to share the memory with an external process (e.g. when
3264 using vhost-user). The memory is allocated with memfd and
3265 optional sealing. (Linux only)
3266 The seal option creates a sealed-file, that will block further
3268 resizing the memory ('on' by default).
3269 The hugetlb option specify the file to be created resides in
3271 the hugetlbfs filesystem (since Linux 4.14). Used in
3272 conjunction with the hugetlb option, the hugetlbsize option
3273 specify the hugetlb page size on systems that support multiple
3274 hugetlb page sizes (it must be a power of 2 value supported by
3275 the system).
3276 In some versions of Linux, the hugetlb option is incompatible
3278 with the seal option (requires at least Linux 4.16).
3279 Please refer to memory-backend-file for a description of the
3281 other options.
3282 The share boolean option is on by default with memfd.
3284 -object rng-builtin,id=id
3286 Creates a random number generator backend which obtains entropy
3287 from QEMU builtin functions. The id parameter is a unique ID
3288 that will be used to reference this entropy backend from the
3289 virtio-rng device. By default, the virtio-rng device uses this
3290 RNG backend.
3291 -object rng-random,id=id,filename=/dev/random
3293 Creates a random number generator backend which obtains entropy
3294 from a device on the host. The id parameter is a unique ID that
3295 will be used to reference this entropy backend from the virtio-
3296 rng device. The filename parameter specifies which file to
3297 obtain entropy from and if omitted defaults to /dev/urandom.
3298 -object rng-egd,id=id,chardev=chardevid
3300 Creates a random number generator backend which obtains entropy
3301 from an external daemon running on the host. The id parameter
3302 is a unique ID that will be used to reference this entropy
3303 backend from the virtio-rng device. The chardev parameter is
3304 the unique ID of a character device backend that provides the
3305 connection to the RNG daemon.
3306 -object
3308 tls-creds-anon,id=id,endpoint=endpoint,dir=/path/to/cred/dir,verify-peer=on|off
3309 Creates a TLS anonymous credentials object, which can be used
3310 to provide TLS support on network backends. The id parameter is
3311 a unique ID which network backends will use to access the
3312 credentials. The endpoint is either server or client depending
3313 on whether the QEMU network backend that uses the credentials
3314 will be acting as a client or as a server. If verify-peer is
3315 enabled (the default) then once the handshake is completed, the
3316 peer credentials will be verified, though this is a no-op for
3317 anonymous credentials.
3318 The dir parameter tells QEMU where to find the credential
3320 files. For server endpoints, this directory may contain a file
3321 dh-params.pem providing diffie-hellman parameters to use for
3322 the TLS server. If the file is missing, QEMU will generate a
3323 set of DH parameters at startup. This is a computationally
3324 expensive operation that consumes random pool entropy, so it is
3325 recommended that a persistent set of parameters be generated
3326 upfront and saved.
3327 -object
3329 tls-creds-psk,id=id,endpoint=endpoint,dir=/path/to/keys/dir[,username=username]
3330 Creates a TLS Pre-Shared Keys (PSK) credentials object, which
3331 can be used to provide TLS support on network backends. The id
3332 parameter is a unique ID which network backends will use to
3333 access the credentials. The endpoint is either server or client
3334 depending on whether the QEMU network backend that uses the
3335 credentials will be acting as a client or as a server. For
3336 clients only, username is the username which will be sent to
3337 the server. If omitted it defaults to "qemu".
3338 The dir parameter tells QEMU where to find the keys file. It
3340 is called "dir/keys.psk" and contains "username:key" pairs.
3341 This file can most easily be created using the GnuTLS "psktool"
3342 program.
3343 For server endpoints, dir may also contain a file dh-params.pem
3345 providing diffie-hellman parameters to use for the TLS server.
3346 If the file is missing, QEMU will generate a set of DH
3347 parameters at startup. This is a computationally expensive
3348 operation that consumes random pool entropy, so it is
3349 recommended that a persistent set of parameters be generated up
3350 front and saved.
3351 -object
3353 tls-creds-x509,id=id,endpoint=endpoint,dir=/path/to/cred/dir,priority=priority,verify-peer=on|off,passwordid=id
3354 Creates a TLS anonymous credentials object, which can be used
3355 to provide TLS support on network backends. The id parameter is
3356 a unique ID which network backends will use to access the
3357 credentials. The endpoint is either server or client depending
3358 on whether the QEMU network backend that uses the credentials
3359 will be acting as a client or as a server. If verify-peer is
3360 enabled (the default) then once the handshake is completed, the
3361 peer credentials will be verified. With x509 certificates, this
3362 implies that the clients must be provided with valid client
3363 certificates too.
3364 The dir parameter tells QEMU where to find the credential
3366 files. For server endpoints, this directory may contain a file
3367 dh-params.pem providing diffie-hellman parameters to use for
3368 the TLS server. If the file is missing, QEMU will generate a
3369 set of DH parameters at startup. This is a computationally
3370 expensive operation that consumes random pool entropy, so it is
3371 recommended that a persistent set of parameters be generated
3372 upfront and saved.
3373 For x509 certificate credentials the directory will contain
3375 further files providing the x509 certificates. The certificates
3376 must be stored in PEM format, in filenames ca-cert.pem,
3377 ca-crl.pem (optional), server-cert.pem (only servers),
3378 server-key.pem (only servers), client-cert.pem (only clients),
3379 and client-key.pem (only clients).
3380 For the server-key.pem and client-key.pem files which contain
3382 sensitive private keys, it is possible to use an encrypted
3383 version by providing the passwordid parameter. This provides
3384 the ID of a previously created "secret" object containing the
3385 password for decryption.
3386 The priority parameter allows to override the global default
3388 priority used by gnutls. This can be useful if the system
3389 administrator needs to use a weaker set of crypto priorities
3390 for QEMU without potentially forcing the weakness onto all
3391 applications. Or conversely if one wants wants a stronger
3392 default for QEMU than for all other applications, they can do
3393 this through this parameter. Its format is a gnutls priority
3394 string as described at
3395 <https://gnutls.org/manual/html_node/Priority-Strings.html>.
3396 -object
3398 filter-buffer,id=id,netdev=netdevid,interval=t[,queue=all|rx|tx][,status=on|off]
3399 Interval t can't be 0, this filter batches the packet delivery:
3400 all packets arriving in a given interval on netdev netdevid are
3401 delayed until the end of the interval. Interval is in
3402 microseconds. status is optional that indicate whether the
3403 netfilter is on (enabled) or off (disabled), the default status
3404 for netfilter will be 'on'.
3405 queue all|rx|tx is an option that can be applied to any
3407 netfilter.
3408 all: the filter is attached both to the receive and the
3410 transmit queue of the netdev (default).
3411 rx: the filter is attached to the receive queue of the netdev,
3413 where it will receive packets sent to the netdev.
3414 tx: the filter is attached to the transmit queue of the netdev,
3416 where it will receive packets sent by the netdev.
3417 -object
3419 filter-mirror,id=id,netdev=netdevid,outdev=chardevid,queue=all|rx|tx[,vnet_hdr_support]
3420 filter-mirror on netdev netdevid,mirror net packet to
3421 chardevchardevid, if it has the vnet_hdr_support flag, filter-
3422 mirror will mirror packet with vnet_hdr_len.
3423 -object
3425 filter-redirector,id=id,netdev=netdevid,indev=chardevid,outdev=chardevid,queue=all|rx|tx[,vnet_hdr_support]
3426 filter-redirector on netdev netdevid,redirect filter's net
3427 packet to chardev chardevid,and redirect indev's packet to
3428 filter.if it has the vnet_hdr_support flag, filter-redirector
3429 will redirect packet with vnet_hdr_len. Create a filter-
3430 redirector we need to differ outdev id from indev id, id can
3431 not be the same. we can just use indev or outdev, but at least
3432 one of indev or outdev need to be specified.
3433 -object
3435 filter-rewriter,id=id,netdev=netdevid,queue=all|rx|tx,[vnet_hdr_support]
3436 Filter-rewriter is a part of COLO project.It will rewrite tcp
3437 packet to secondary from primary to keep secondary tcp
3438 connection,and rewrite tcp packet to primary from secondary
3439 make tcp packet can be handled by client.if it has the
3440 vnet_hdr_support flag, we can parse packet with vnet header.
3441 usage: colo secondary: -object
3443 filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 -object
3444 filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 -object
3445 filter-rewriter,id=rew0,netdev=hn0,queue=all
3446 -object filter-dump,id=id,netdev=dev[,file=filename][,maxlen=len]
3448 Dump the network traffic on netdev dev to the file specified by
3449 filename. At most len bytes (64k by default) per packet are
3450 stored. The file format is libpcap, so it can be analyzed with
3451 tools such as tcpdump or Wireshark.
3452 -object
3454 colo-compare,id=id,primary_in=chardevid,secondary_in=chardevid,outdev=chardevid,iothread=id[,vnet_hdr_support][,notify_dev=id]
3455 Colo-compare gets packet from primary_inchardevid and
3456 secondary_inchardevid, than compare primary packet with
3457 secondary packet. If the packets are same, we will output
3458 primary packet to outdevchardevid, else we will notify colo-
3459 frame do checkpoint and send primary packet to outdevchardevid.
3460 In order to improve efficiency, we need to put the task of
3461 comparison in another thread. If it has the vnet_hdr_support
3462 flag, colo compare will send/recv packet with vnet_hdr_len. If
3463 you want to use Xen COLO, will need the notify_dev to notify
3464 Xen colo-frame to do checkpoint.
3465 we must use it with the help of filter-mirror and filter-
3467 redirector.
3468 KVM COLO
3470 primary:
3472 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
3473 -device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
3474 -chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait
3475 -chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait
3476 -chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait
3477 -chardev socket,id=compare0-0,host=3.3.3.3,port=9001
3478 -chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait
3479 -chardev socket,id=compare_out0,host=3.3.3.3,port=9005
3480 -object iothread,id=iothread1
3481 -object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
3482 -object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
3483 -object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
3484 -object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,iothread=iothread1
3485 secondary:
3487 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
3488 -device e1000,netdev=hn0,mac=52:a4:00:12:78:66
3489 -chardev socket,id=red0,host=3.3.3.3,port=9003
3490 -chardev socket,id=red1,host=3.3.3.3,port=9004
3491 -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
3492 -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
3493 Xen COLO
3496 primary:
3498 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
3499 -device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
3500 -chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait
3501 -chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait
3502 -chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait
3503 -chardev socket,id=compare0-0,host=3.3.3.3,port=9001
3504 -chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait
3505 -chardev socket,id=compare_out0,host=3.3.3.3,port=9005
3506 -chardev socket,id=notify_way,host=3.3.3.3,port=9009,server,nowait
3507 -object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
3508 -object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
3509 -object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
3510 -object iothread,id=iothread1
3511 -object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,notify_dev=nofity_way,iothread=iothread1
3512 secondary:
3514 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
3515 -device e1000,netdev=hn0,mac=52:a4:00:12:78:66
3516 -chardev socket,id=red0,host=3.3.3.3,port=9003
3517 -chardev socket,id=red1,host=3.3.3.3,port=9004
3518 -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
3519 -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
3520 If you want to know the detail of above command line, you can
3522 read the colo-compare git log.
3523 -object cryptodev-backend-builtin,id=id[,queues=queues]
3525 Creates a cryptodev backend which executes crypto opreation
3526 from the QEMU cipher APIS. The id parameter is a unique ID that
3527 will be used to reference this cryptodev backend from the
3528 virtio-crypto device. The queues parameter is optional, which
3529 specify the queue number of cryptodev backend, the default of
3530 queues is 1.
3531 # qemu-system-x86_64 \
3533 [...] \
3534 -object cryptodev-backend-builtin,id=cryptodev0 \
3535 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
3536 [...]
3537 -object
3539 cryptodev-vhost-user,id=id,chardev=chardevid[,queues=queues]
3540 Creates a vhost-user cryptodev backend, backed by a chardev
3541 chardevid. The id parameter is a unique ID that will be used
3542 to reference this cryptodev backend from the virtio-crypto
3543 device. The chardev should be a unix domain socket backed one.
3544 The vhost-user uses a specifically defined protocol to pass
3545 vhost ioctl replacement messages to an application on the other
3546 end of the socket. The queues parameter is optional, which
3547 specify the queue number of cryptodev backend for multiqueue
3548 vhost-user, the default of queues is 1.
3549 # qemu-system-x86_64 \
3551 [...] \
3552 -chardev socket,id=chardev0,path=/path/to/socket \
3553 -object cryptodev-vhost-user,id=cryptodev0,chardev=chardev0 \
3554 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
3555 [...]
3556 -object
3558 secret,id=id,data=string,format=raw|base64[,keyid=secretid,iv=string]
3559 -object
3560 secret,id=id,file=filename,format=raw|base64[,keyid=secretid,iv=string]
3561 Defines a secret to store a password, encryption key, or some
3562 other sensitive data. The sensitive data can either be passed
3563 directly via the data parameter, or indirectly via the file
3564 parameter. Using the data parameter is insecure unless the
3565 sensitive data is encrypted.
3566 The sensitive data can be provided in raw format (the default),
3568 or base64. When encoded as JSON, the raw format only supports
3569 valid UTF-8 characters, so base64 is recommended for sending
3570 binary data. QEMU will convert from which ever format is
3571 provided to the format it needs internally. eg, an RBD password
3572 can be provided in raw format, even though it will be base64
3573 encoded when passed onto the RBD sever.
3574 For added protection, it is possible to encrypt the data
3576 associated with a secret using the AES-256-CBC cipher. Use of
3577 encryption is indicated by providing the keyid and iv
3578 parameters. The keyid parameter provides the ID of a previously
3579 defined secret that contains the AES-256 decryption key. This
3580 key should be 32-bytes long and be base64 encoded. The iv
3581 parameter provides the random initialization vector used for
3582 encryption of this particular secret and should be a base64
3583 encrypted string of the 16-byte IV.
3584 The simplest (insecure) usage is to provide the secret inline
3586 # qemu-system-x86_64 -object secret,id=sec0,data=letmein,format=raw
3588 The simplest secure usage is to provide the secret via a file
3590 # printf "letmein" > mypasswd.txt # qemu-system-x86_64 -object
3592 secret,id=sec0,file=mypasswd.txt,format=raw
3593 For greater security, AES-256-CBC should be used. To illustrate
3595 usage, consider the openssl command line tool which can encrypt
3596 the data. Note that when encrypting, the plaintext must be
3597 padded to the cipher block size (32 bytes) using the standard
3598 PKCS#5/6 compatible padding algorithm.
3599 First a master key needs to be created in base64 encoding:
3601 # openssl rand -base64 32 > key.b64
3603 # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"')
3604 Each secret to be encrypted needs to have a random
3606 initialization vector generated. These do not need to be kept
3607 secret
3608 # openssl rand -base64 16 > iv.b64
3610 # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"')
3611 The secret to be defined can now be encrypted, in this case
3613 we're telling openssl to base64 encode the result, but it could
3614 be left as raw bytes if desired.
3615 # SECRET=$(printf "letmein" |
3617 openssl enc -aes-256-cbc -a -K $KEY -iv $IV)
3618 When launching QEMU, create a master secret pointing to
3620 "key.b64" and specify that to be used to decrypt the user
3621 password. Pass the contents of "iv.b64" to the second secret
3622 # qemu-system-x86_64 \
3624 -object secret,id=secmaster0,format=base64,file=key.b64 \
3625 -object secret,id=sec0,keyid=secmaster0,format=base64,\
3626 data=$SECRET,iv=$(<iv.b64)
3627 -object
3629 sev-guest,id=id,cbitpos=cbitpos,reduced-phys-bits=val,[sev-device=string,policy=policy,handle=handle,dh-cert-file=file,session-file=file]
3630 Create a Secure Encrypted Virtualization (SEV) guest object,
3631 which can be used to provide the guest memory encryption
3632 support on AMD processors.
3633 When memory encryption is enabled, one of the physical address
3635 bit (aka the C-bit) is utilized to mark if a memory page is
3636 protected. The cbitpos is used to provide the C-bit position.
3637 The C-bit position is Host family dependent hence user must
3638 provide this value. On EPYC, the value should be 47.
3639 When memory encryption is enabled, we loose certain bits in
3641 physical address space. The reduced-phys-bits is used to
3642 provide the number of bits we loose in physical address space.
3643 Similar to C-bit, the value is Host family dependent. On EPYC,
3644 the value should be 5.
3645 The sev-device provides the device file to use for
3647 communicating with the SEV firmware running inside AMD Secure
3648 Processor. The default device is '/dev/sev'. If hardware
3649 supports memory encryption then /dev/sev devices are created by
3650 CCP driver.
3651 The policy provides the guest policy to be enforced by the SEV
3653 firmware and restrict what configuration and operational
3654 commands can be performed on this guest by the hypervisor. The
3655 policy should be provided by the guest owner and is bound to
3656 the guest and cannot be changed throughout the lifetime of the
3657 guest. The default is 0.
3658 If guest policy allows sharing the key with another SEV guest
3660 then handle can be use to provide handle of the guest from
3661 which to share the key.
3662 The dh-cert-file and session-file provides the guest owner's
3664 Public Diffie-Hillman key defined in SEV spec. The PDH and
3665 session parameters are used for establishing a cryptographic
3666 session with the guest owner to negotiate keys used for
3667 attestation. The file must be encoded in base64.
3668 e.g to launch a SEV guest
3670 # qemu-system-x86_64 \
3672 ......
3673 -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=5 \
3674 -machine ...,memory-encryption=sev0
3675 .....
3676 -object authz-simple,id=id,identity=string
3678 Create an authorization object that will control access to
3679 network services.
3680 The identity parameter is identifies the user and its format
3682 depends on the network service that authorization object is
3683 associated with. For authorizing based on TLS x509
3684 certificates, the identity must be the x509 distinguished name.
3685 Note that care must be taken to escape any commas in the
3686 distinguished name.
3687 An example authorization object to validate a x509
3689 distinguished name would look like:
3690 # qemu-system-x86_64 \
3692 ...
3693 -object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,O=Example Org,,L=London,,ST=London,,C=GB' \
3694 ...
3695 Note the use of quotes due to the x509 distinguished name
3697 containing whitespace, and escaping of ','.
3698 -object authz-listfile,id=id,filename=path,refresh=yes|no
3700 Create an authorization object that will control access to
3701 network services.
3702 The filename parameter is the fully qualified path to a file
3704 containing the access control list rules in JSON format.
3705 An example set of rules that match against SASL usernames might
3707 look like:
3708 {
3710 "rules": [
3711 { "match": "fred", "policy": "allow", "format": "exact" },
3712 { "match": "bob", "policy": "allow", "format": "exact" },
3713 { "match": "danb", "policy": "deny", "format": "glob" },
3714 { "match": "dan*", "policy": "allow", "format": "exact" },
3715 ],
3716 "policy": "deny"
3717 }
3718 When checking access the object will iterate over all the rules
3720 and the first rule to match will have its policy value returned
3721 as the result. If no rules match, then the default policy value
3722 is returned.
3723 The rules can either be an exact string match, or they can use
3725 the simple UNIX glob pattern matching to allow wildcards to be
3726 used.
3727 If refresh is set to true the file will be monitored and
3729 automatically reloaded whenever its content changes.
3730 As with the "authz-simple" object, the format of the identity
3732 strings being matched depends on the network service, but is
3733 usually a TLS x509 distinguished name, or a SASL username.
3734 An example authorization object to validate a SASL username
3736 would look like:
3737 # qemu-system-x86_64 \
3739 ...
3740 -object authz-simple,id=auth0,filename=/etc/qemu/vnc-sasl.acl,refresh=yes
3741 ...
3742 -object authz-pam,id=id,service=string
3744 Create an authorization object that will control access to
3745 network services.
3746 The service parameter provides the name of a PAM service to use
3748 for authorization. It requires that a file "/etc/pam.d/service"
3749 exist to provide the configuration for the "account" subsystem.
3750 An example authorization object to validate a TLS x509
3752 distinguished name would look like:
3753 # qemu-system-x86_64 \
3755 ...
3756 -object authz-pam,id=auth0,service=qemu-vnc
3757 ...
3758 There would then be a corresponding config file for PAM at
3760 "/etc/pam.d/qemu-vnc" that contains:
3761 account requisite pam_listfile.so item=user sense=allow \
3763 file=/etc/qemu/vnc.allow
3764 Finally the "/etc/qemu/vnc.allow" file would contain the list
3766 of x509 distingished names that are permitted access
3767 CN=laptop.example.com,O=Example Home,L=London,ST=London,C=GB
3769 During the graphical emulation, you can use special key combinations to
3771 change modes. The default key mappings are shown below, but if you use
3772 "-alt-grab" then the modifier is Ctrl-Alt-Shift (instead of Ctrl-Alt)
3773 and if you use "-ctrl-grab" then the modifier is the right Ctrl key
3774 (instead of Ctrl-Alt):
3775 Ctrl-Alt-f
3777 Toggle full screen
3778 Ctrl-Alt-+
3780 Enlarge the screen
3781 Ctrl-Alt--
3783 Shrink the screen
3784 Ctrl-Alt-u
3786 Restore the screen's un-scaled dimensions
3787 Ctrl-Alt-n
3789 Switch to virtual console 'n'. Standard console mappings are:
3790 1 Target system display
3792 2 Monitor
3794 3 Serial port
3796 Ctrl-Alt
3798 Toggle mouse and keyboard grab.
3799 In the virtual consoles, you can use Ctrl-Up, Ctrl-Down, Ctrl-PageUp
3801 and Ctrl-PageDown to move in the back log.
3802 During emulation, if you are using a character backend multiplexer
3804 (which is the default if you are using -nographic) then several
3805 commands are available via an escape sequence. These key sequences all
3806 start with an escape character, which is Ctrl-a by default, but can be
3807 changed with -echr. The list below assumes you're using the default.
3808 Ctrl-a h
3810 Print this help
3811 Ctrl-a x
3813 Exit emulator
3814 Ctrl-a s
3816 Save disk data back to file (if -snapshot)
3817 Ctrl-a t
3819 Toggle console timestamps
3820 Ctrl-a b
3822 Send break (magic sysrq in Linux)
3823 Ctrl-a c
3825 Rotate between the frontends connected to the multiplexer (usually
3826 this switches between the monitor and the console)
3827 Ctrl-a Ctrl-a
3829 Send the escape character to the frontend
3830 The following options are specific to the PowerPC emulation:
3832 -g WxH[xDEPTH]
3834 Set the initial VGA graphic mode. The default is 800x600x32.
3835 -prom-env string
3837 Set OpenBIOS variables in NVRAM, for example:
3838 qemu-system-ppc -prom-env 'auto-boot?=false' \
3840 -prom-env 'boot-device=hd:2,\yaboot' \
3841 -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
3842 These variables are not used by Open Hack'Ware.
3844 The following options are specific to the Sparc32 emulation:
3846 -g WxHx[xDEPTH]
3848 Set the initial graphics mode. For TCX, the default is 1024x768x8
3849 with the option of 1024x768x24. For cgthree, the default is
3850 1024x768x8 with the option of 1152x900x8 for people who wish to use
3851 OBP.
3852 -prom-env string
3854 Set OpenBIOS variables in NVRAM, for example:
3855 qemu-system-sparc -prom-env 'auto-boot?=false' \
3857 -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
3858 -M [SS-4|SS-5|SS-10|SS-20|SS-600MP|LX|Voyager|SPARCClassic]
3860 [|SPARCbook]
3861 Set the emulated machine type. Default is SS-5.
3862 The following options are specific to the Sparc64 emulation:
3864 -prom-env string
3866 Set OpenBIOS variables in NVRAM, for example:
3867 qemu-system-sparc64 -prom-env 'auto-boot?=false'
3869 -M [sun4u|sun4v|niagara]
3871 Set the emulated machine type. The default is sun4u.
3872 The following options are specific to the ARM emulation:
3874 -semihosting
3876 Enable semihosting syscall emulation.
3877 On ARM this implements the "Angel" interface.
3879 Note that this allows guest direct access to the host filesystem,
3881 so should only be used with trusted guest OS.
3882 The following options are specific to the ColdFire emulation:
3884 -semihosting
3886 Enable semihosting syscall emulation.
3887 On M68K this implements the "ColdFire GDB" interface used by
3889 libgloss.
3890 Note that this allows guest direct access to the host filesystem,
3892 so should only be used with trusted guest OS.
3893 The following options are specific to the Xtensa emulation:
3895 -semihosting
3897 Enable semihosting syscall emulation.
3898 Xtensa semihosting provides basic file IO calls, such as
3900 open/read/write/seek/select. Tensilica baremetal libc for ISS and
3901 linux platform "sim" use this interface.
3902 Note that this allows guest direct access to the host filesystem,
3904 so should only be used with trusted guest OS.
3905
3907 In addition to using normal file images for the emulated storage
3908 devices, QEMU can also use networked resources such as iSCSI devices.
3909 These are specified using a special URL syntax.
3910 iSCSI
3912 iSCSI support allows QEMU to access iSCSI resources directly and
3913 use as images for the guest storage. Both disk and cdrom images are
3914 supported.
3915 Syntax for specifying iSCSI LUNs is
3917 "iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>"
3918 By default qemu will use the iSCSI initiator-name
3920 'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from
3921 the command line or a configuration file.
3922 Since version Qemu 2.4 it is possible to specify a iSCSI request
3924 timeout to detect stalled requests and force a reestablishment of
3925 the session. The timeout is specified in seconds. The default is 0
3926 which means no timeout. Libiscsi 1.15.0 or greater is required for
3927 this feature.
3928 Example (without authentication):
3930 qemu-system-x86_64 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
3932 -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
3933 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
3934 Example (CHAP username/password via URL):
3936 qemu-system-x86_64 -drive file=iscsi://user%password@192.0.2.1/iqn.2001-04.com.example/1
3938 Example (CHAP username/password via environment variables):
3940 LIBISCSI_CHAP_USERNAME="user" \
3942 LIBISCSI_CHAP_PASSWORD="password" \
3943 qemu-system-x86_64 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
3944 NBD QEMU supports NBD (Network Block Devices) both using TCP protocol
3946 as well as Unix Domain Sockets. With TCP, the default port is
3947 10809.
3948 Syntax for specifying a NBD device using TCP, in preferred URI
3950 form: "nbd://<server-ip>[:<port>]/[<export>]"
3951 Syntax for specifying a NBD device using Unix Domain Sockets;
3953 remember that '?' is a shell glob character and may need quoting:
3954 "nbd+unix:///[<export>]?socket=<domain-socket>"
3955 Older syntax that is also recognized:
3957 "nbd:<server-ip>:<port>[:exportname=<export>]"
3958 Syntax for specifying a NBD device using Unix Domain Sockets
3960 "nbd:unix:<domain-socket>[:exportname=<export>]"
3961 Example for TCP
3963 qemu-system-x86_64 --drive file=nbd:192.0.2.1:30000
3965 Example for Unix Domain Sockets
3967 qemu-system-x86_64 --drive file=nbd:unix:/tmp/nbd-socket
3969 SSH QEMU supports SSH (Secure Shell) access to remote disks.
3971 Examples:
3973 qemu-system-x86_64 -drive file=ssh://user@host/path/to/disk.img
3975 qemu-system-x86_64 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
3976 Currently authentication must be done using ssh-agent. Other
3978 authentication methods may be supported in future.
3979 Sheepdog
3981 Sheepdog is a distributed storage system for QEMU. QEMU supports
3982 using either local sheepdog devices or remote networked devices.
3983 Syntax for specifying a sheepdog device
3985 sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
3987 Example
3989 qemu-system-x86_64 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
3991 See also <https://sheepdog.github.io/sheepdog/>.
3993 GlusterFS
3995 GlusterFS is a user space distributed file system. QEMU supports
3996 the use of GlusterFS volumes for hosting VM disk images using TCP,
3997 Unix Domain Sockets and RDMA transport protocols.
3998 Syntax for specifying a VM disk image on GlusterFS volume is
4000 URI:
4002 gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
4003 JSON:
4005 'json:{"driver":"qcow2","file":{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...",
4006 "server":[{"type":"tcp","host":"...","port":"..."},
4007 {"type":"unix","socket":"..."}]}}'
4008 Example
4010 URI:
4012 qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img,
4013 file.debug=9,file.logfile=/var/log/qemu-gluster.log
4014 JSON:
4016 qemu-system-x86_64 'json:{"driver":"qcow2",
4017 "file":{"driver":"gluster",
4018 "volume":"testvol","path":"a.img",
4019 "debug":9,"logfile":"/var/log/qemu-gluster.log",
4020 "server":[{"type":"tcp","host":"1.2.3.4","port":24007},
4021 {"type":"unix","socket":"/var/run/glusterd.socket"}]}}'
4022 qemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
4023 file.debug=9,file.logfile=/var/log/qemu-gluster.log,
4024 file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
4025 file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
4026 See also <http://www.gluster.org>.
4028 HTTP/HTTPS/FTP/FTPS
4030 QEMU supports read-only access to files accessed over http(s) and
4031 ftp(s).
4032 Syntax using a single filename:
4034 <protocol>://[<username>[:<password>]@]<host>/<path>
4036 where:
4038 protocol
4040 'http', 'https', 'ftp', or 'ftps'.
4041 username
4043 Optional username for authentication to the remote server.
4044 password
4046 Optional password for authentication to the remote server.
4047 host
4049 Address of the remote server.
4050 path
4052 Path on the remote server, including any query string.
4053 The following options are also supported:
4055 url The full URL when passing options to the driver explicitly.
4057 readahead
4059 The amount of data to read ahead with each range request to the
4060 remote server. This value may optionally have the suffix 'T',
4061 'G', 'M', 'K', 'k' or 'b'. If it does not have a suffix, it
4062 will be assumed to be in bytes. The value must be a multiple of
4063 512 bytes. It defaults to 256k.
4064 sslverify
4066 Whether to verify the remote server's certificate when
4067 connecting over SSL. It can have the value 'on' or 'off'. It
4068 defaults to 'on'.
4069 cookie
4071 Send this cookie (it can also be a list of cookies separated by
4072 ';') with each outgoing request. Only supported when using
4073 protocols such as HTTP which support cookies, otherwise
4074 ignored.
4075 timeout
4077 Set the timeout in seconds of the CURL connection. This timeout
4078 is the time that CURL waits for a response from the remote
4079 server to get the size of the image to be downloaded. If not
4080 set, the default timeout of 5 seconds is used.
4081 Note that when passing options to qemu explicitly, driver is the
4083 value of <protocol>.
4084 Example: boot from a remote Fedora 20 live ISO image
4086 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
4088 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
4090 Example: boot from a remote Fedora 20 cloud image using a local
4092 overlay for writes, copy-on-read, and a readahead of 64k
4093 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
4095 qemu-system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
4097 Example: boot from an image stored on a VMware vSphere server with
4099 a self-signed certificate using a local overlay for writes, a
4100 readahead of 64k and a timeout of 10 seconds.
4101 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
4103 qemu-system-x86_64 -drive file=/tmp/test.qcow2
4105
4107 The HTML documentation of QEMU for more precise information and Linux
4108 user mode emulator invocation.
4109
4111 Fabrice Bellard
4112 2020-03-17 QEMU.1(1)