1QEMU.1(1) QEMU.1(1)
2
6 qemu-doc - QEMU version 4.1.1 User Documentation
7
9 qemu-system-i386 [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-i386 dos.img -soundhw gus -parallel none
62 Alternatively:
64 qemu-system-i386 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-i386
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-i386 -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 rb_timeout is '-1', guest will
311 not reboot, qemu passes '-1' to bios by default. Currently Seabios
312 for X86 system 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-i386 -boot order=nc
320 # boot from CD-ROM first, switch back to default order after reboot
321 qemu-system-i386 -boot once=d
322 # boot with a splash picture for 5 seconds.
323 qemu-system-i386 -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 Valid global options are:
381 id=identifier
383 Identifies the audio backend.
384 timer-period=period
386 Sets the timer period used by the audio subsystem in
387 microseconds. Default is 10000 (10 ms).
388 in|out.fixed-settings=on|off
390 Use fixed settings for host audio. When off, it will change
391 based on how the guest opens the sound card. In this case you
392 must not specify frequency, channels or format. Default is on.
393 in|out.frequency=frequency
395 Specify the frequency to use when using fixed-settings.
396 Default is 44100Hz.
397 in|out.channels=channels
399 Specify the number of channels to use when using fixed-
400 settings. Default is 2 (stereo).
401 in|out.format=format
403 Specify the sample format to use when using fixed-settings.
404 Valid values are: "s8", "s16", "s32", "u8", "u16", "u32".
405 Default is "s16".
406 in|out.voices=voices
408 Specify the number of voices to use. Default is 1.
409 in|out.buffer=usecs
411 Sets the size of the buffer in microseconds.
412 -audiodev none,id=id[,prop[=value][,...]]
414 Creates a dummy backend that discards all outputs. This backend
415 has no backend specific properties.
416 -audiodev alsa,id=id[,prop[=value][,...]]
418 Creates backend using the ALSA. This backend is only available on
419 Linux.
420 ALSA specific options are:
422 in|out.dev=device
424 Specify the ALSA device to use for input and/or output.
425 Default is "default".
426 in|out.period-len=usecs
428 Sets the period length in microseconds.
429 in|out.try-poll=on|off
431 Attempt to use poll mode with the device. Default is on.
432 threshold=threshold
434 Threshold (in microseconds) when playback starts. Default is
435 0.
436 -audiodev coreaudio,id=id[,prop[=value][,...]]
438 Creates a backend using Apple's Core Audio. This backend is only
439 available on Mac OS and only supports playback.
440 Core Audio specific options are:
442 in|out.buffer-count=count
444 Sets the count of the buffers.
445 -audiodev dsound,id=id[,prop[=value][,...]]
447 Creates a backend using Microsoft's DirectSound. This backend is
448 only available on Windows and only supports playback.
449 DirectSound specific options are:
451 latency=usecs
453 Add extra usecs microseconds latency to playback. Default is
454 10000 (10 ms).
455 -audiodev oss,id=id[,prop[=value][,...]]
457 Creates a backend using OSS. This backend is available on most
458 Unix-like systems.
459 OSS specific options are:
461 in|out.dev=device
463 Specify the file name of the OSS device to use. Default is
464 "/dev/dsp".
465 in|out.buffer-count=count
467 Sets the count of the buffers.
468 in|out.try-poll=on|of
470 Attempt to use poll mode with the device. Default is on.
471 try-mmap=on|off
473 Try using memory mapped device access. Default is off.
474 exclusive=on|off
476 Open the device in exclusive mode (vmix won't work in this
477 case). Default is off.
478 dsp-policy=policy
480 Sets the timing policy (between 0 and 10, where smaller number
481 means smaller latency but higher CPU usage). Use -1 to use
482 buffer sizes specified by "buffer" and "buffer-count". This
483 option is ignored if you do not have OSS 4. Default is 5.
484 -audiodev pa,id=id[,prop[=value][,...]]
486 Creates a backend using PulseAudio. This backend is available on
487 most systems.
488 PulseAudio specific options are:
490 server=server
492 Sets the PulseAudio server to connect to.
493 in|out.name=sink
495 Use the specified source/sink for recording/playback.
496 -audiodev sdl,id=id[,prop[=value][,...]]
498 Creates a backend using SDL. This backend is available on most
499 systems, but you should use your platform's native backend if
500 possible. This backend has no backend specific properties.
501 -audiodev spice,id=id[,prop[=value][,...]]
503 Creates a backend that sends audio through SPICE. This backend
504 requires "-spice" and automatically selected in that case, so
505 usually you can ignore this option. This backend has no backend
506 specific properties.
507 -audiodev wav,id=id[,prop[=value][,...]]
509 Creates a backend that writes audio to a WAV file.
510 Backend specific options are:
512 path=path
514 Write recorded audio into the specified file. Default is
515 "qemu.wav".
516 -soundhw card1[,card2,...] or -soundhw all
518 Enable audio and selected sound hardware. Use 'help' to print all
519 available sound hardware.
520 qemu-system-i386 -soundhw sb16,adlib disk.img
522 qemu-system-i386 -soundhw es1370 disk.img
523 qemu-system-i386 -soundhw ac97 disk.img
524 qemu-system-i386 -soundhw hda disk.img
525 qemu-system-i386 -soundhw all disk.img
526 qemu-system-i386 -soundhw help
527 Note that Linux's i810_audio OSS kernel (for AC97) module might
529 require manually specifying clocking.
530 modprobe i810_audio clocking=48000
532 -device driver[,prop[=value][,...]]
534 Add device driver. prop=value sets driver properties. Valid
535 properties depend on the driver. To get help on possible drivers
536 and properties, use "-device help" and "-device driver,help".
537 Some drivers are:
539 -device
541 ipmi-bmc-sim,id=id[,slave_addr=val][,sdrfile=file][,furareasize=val][,furdatafile=file]
542 Add an IPMI BMC. This is a simulation of a hardware management
543 interface processor that normally sits on a system. It provides a
544 watchdog and the ability to reset and power control the system.
545 You need to connect this to an IPMI interface to make it useful
546 The IPMI slave address to use for the BMC. The default is 0x20.
548 This address is the BMC's address on the I2C network of management
549 controllers. If you don't know what this means, it is safe to
550 ignore it.
551 bmc=id
553 The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern
554 above.
555 slave_addr=val
557 Define slave address to use for the BMC. The default is 0x20.
558 sdrfile=file
560 file containing raw Sensor Data Records (SDR) data. The default
561 is none.
562 fruareasize=val
564 size of a Field Replaceable Unit (FRU) area. The default is
565 1024.
566 frudatafile=file
568 file containing raw Field Replaceable Unit (FRU) inventory
569 data. The default is none.
570 -device ipmi-bmc-extern,id=id,chardev=id[,slave_addr=val]
572 Add a connection to an external IPMI BMC simulator. Instead of
573 locally emulating the BMC like the above item, instead connect to
574 an external entity that provides the IPMI services.
575 A connection is made to an external BMC simulator. If you do this,
577 it is strongly recommended that you use the "reconnect=" chardev
578 option to reconnect to the simulator if the connection is lost.
579 Note that if this is not used carefully, it can be a security
580 issue, as the interface has the ability to send resets, NMIs, and
581 power off the VM. It's best if QEMU makes a connection to an
582 external simulator running on a secure port on localhost, so
583 neither the simulator nor QEMU is exposed to any outside network.
584 See the "lanserv/README.vm" file in the OpenIPMI library for more
586 details on the external interface.
587 -device isa-ipmi-kcs,bmc=id[,ioport=val][,irq=val]
589 Add a KCS IPMI interafce on the ISA bus. This also adds a
590 corresponding ACPI and SMBIOS entries, if appropriate.
591 bmc=id
593 The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern
594 above.
595 ioport=val
597 Define the I/O address of the interface. The default is 0xca0
598 for KCS.
599 irq=val
601 Define the interrupt to use. The default is 5. To disable
602 interrupts, set this to 0.
603 -device isa-ipmi-bt,bmc=id[,ioport=val][,irq=val]
605 Like the KCS interface, but defines a BT interface. The default
606 port is 0xe4 and the default interrupt is 5.
607 -name name
609 Sets the name of the guest. This name will be displayed in the SDL
610 window caption. The name will also be used for the VNC server.
611 Also optionally set the top visible process name in Linux. Naming
612 of individual threads can also be enabled on Linux to aid
613 debugging.
614 -uuid uuid
616 Set system UUID.
617 Block device options
619 -fda file
621 -fdb file
622 Use file as floppy disk 0/1 image.
623 -hda file
625 -hdb file
626 -hdc file
627 -hdd file
628 Use file as hard disk 0, 1, 2 or 3 image.
629 -cdrom file
631 Use file as CD-ROM image (you cannot use -hdc and -cdrom at the
632 same time). You can use the host CD-ROM by using /dev/cdrom as
633 filename.
634 -blockdev option[,option[,option[,...]]]
636 Define a new block driver node. Some of the options apply to all
637 block drivers, other options are only accepted for a specific block
638 driver. See below for a list of generic options and options for the
639 most common block drivers.
640 Options that expect a reference to another node (e.g. "file") can
642 be given in two ways. Either you specify the node name of an
643 already existing node (file=node-name), or you define a new node
644 inline, adding options for the referenced node after a dot
645 (file.filename=path,file.aio=native).
646 A block driver node created with -blockdev can be used for a guest
648 device by specifying its node name for the "drive" property in a
649 -device argument that defines a block device.
650 Valid options for any block driver node:
652 "driver"
653 Specifies the block driver to use for the given node.
654 "node-name"
656 This defines the name of the block driver node by which it
657 will be referenced later. The name must be unique, i.e. it
658 must not match the name of a different block driver node,
659 or (if you use -drive as well) the ID of a drive.
660 If no node name is specified, it is automatically
662 generated. The generated node name is not intended to be
663 predictable and changes between QEMU invocations. For the
664 top level, an explicit node name must be specified.
665 "read-only"
667 Open the node read-only. Guest write attempts will fail.
668 "cache.direct"
670 The host page cache can be avoided with cache.direct=on.
671 This will attempt to do disk IO directly to the guest's
672 memory. QEMU may still perform an internal copy of the
673 data.
674 "cache.no-flush"
676 In case you don't care about data integrity over host
677 failures, you can use cache.no-flush=on. This option tells
678 QEMU that it never needs to write any data to the disk but
679 can instead keep things in cache. If anything goes wrong,
680 like your host losing power, the disk storage getting
681 disconnected accidentally, etc. your image will most
682 probably be rendered unusable.
683 "discard=discard"
685 discard is one of "ignore" (or "off") or "unmap" (or "on")
686 and controls whether "discard" (also known as "trim" or
687 "unmap") requests are ignored or passed to the filesystem.
688 Some machine types may not support discard requests.
689 "detect-zeroes=detect-zeroes"
691 detect-zeroes is "off", "on" or "unmap" and enables the
692 automatic conversion of plain zero writes by the OS to
693 driver specific optimized zero write commands. You may even
694 choose "unmap" if discard is set to "unmap" to allow a zero
695 write to be converted to an "unmap" operation.
696 Driver-specific options for "file"
698 This is the protocol-level block driver for accessing regular
699 files.
700 "filename"
702 The path to the image file in the local filesystem
703 "aio"
705 Specifies the AIO backend (threads/native, default:
706 threads)
707 "locking"
709 Specifies whether the image file is protected with Linux
710 OFD / POSIX locks. The default is to use the Linux Open
711 File Descriptor API if available, otherwise no lock is
712 applied. (auto/on/off, default: auto)
713 Example:
715 -blockdev driver=file,node-name=disk,filename=disk.img
717 Driver-specific options for "raw"
719 This is the image format block driver for raw images. It is
720 usually stacked on top of a protocol level block driver such as
721 "file".
722 "file"
724 Reference to or definition of the data source block driver
725 node (e.g. a "file" driver node)
726 Example 1:
728 -blockdev driver=file,node-name=disk_file,filename=disk.img
730 -blockdev driver=raw,node-name=disk,file=disk_file
731 Example 2:
733 -blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img
735 Driver-specific options for "qcow2"
737 This is the image format block driver for qcow2 images. It is
738 usually stacked on top of a protocol level block driver such as
739 "file".
740 "file"
742 Reference to or definition of the data source block driver
743 node (e.g. a "file" driver node)
744 "backing"
746 Reference to or definition of the backing file block device
747 (default is taken from the image file). It is allowed to
748 pass "null" here in order to disable the default backing
749 file.
750 "lazy-refcounts"
752 Whether to enable the lazy refcounts feature (on/off;
753 default is taken from the image file)
754 "cache-size"
756 The maximum total size of the L2 table and refcount block
757 caches in bytes (default: the sum of l2-cache-size and
758 refcount-cache-size)
759 "l2-cache-size"
761 The maximum size of the L2 table cache in bytes (default:
762 if cache-size is not specified - 32M on Linux platforms,
763 and 8M on non-Linux platforms; otherwise, as large as
764 possible within the cache-size, while permitting the
765 requested or the minimal refcount cache size)
766 "refcount-cache-size"
768 The maximum size of the refcount block cache in bytes
769 (default: 4 times the cluster size; or if cache-size is
770 specified, the part of it which is not used for the L2
771 cache)
772 "cache-clean-interval"
774 Clean unused entries in the L2 and refcount caches. The
775 interval is in seconds. The default value is 600 on
776 supporting platforms, and 0 on other platforms. Setting it
777 to 0 disables this feature.
778 "pass-discard-request"
780 Whether discard requests to the qcow2 device should be
781 forwarded to the data source (on/off; default: on if
782 discard=unmap is specified, off otherwise)
783 "pass-discard-snapshot"
785 Whether discard requests for the data source should be
786 issued when a snapshot operation (e.g. deleting a snapshot)
787 frees clusters in the qcow2 file (on/off; default: on)
788 "pass-discard-other"
790 Whether discard requests for the data source should be
791 issued on other occasions where a cluster gets freed
792 (on/off; default: off)
793 "overlap-check"
795 Which overlap checks to perform for writes to the image
796 (none/constant/cached/all; default: cached). For details or
797 finer granularity control refer to the QAPI documentation
798 of "blockdev-add".
799 Example 1:
801 -blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2
803 -blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216
804 Example 2:
806 -blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2
808 Driver-specific options for other drivers
810 Please refer to the QAPI documentation of the "blockdev-add"
811 QMP command.
812 -drive option[,option[,option[,...]]]
814 Define a new drive. This includes creating a block driver node (the
815 backend) as well as a guest device, and is mostly a shortcut for
816 defining the corresponding -blockdev and -device options.
817 -drive accepts all options that are accepted by -blockdev. In
819 addition, it knows the following options:
820 file=file
822 This option defines which disk image to use with this drive. If
823 the filename contains comma, you must double it (for instance,
824 "file=my,,file" to use file "my,file").
825 Special files such as iSCSI devices can be specified using
827 protocol specific URLs. See the section for "Device URL Syntax"
828 for more information.
829 if=interface
831 This option defines on which type on interface the drive is
832 connected. Available types are: ide, scsi, sd, mtd, floppy,
833 pflash, virtio, none.
834 bus=bus,unit=unit
836 These options define where is connected the drive by defining
837 the bus number and the unit id.
838 index=index
840 This option defines where is connected the drive by using an
841 index in the list of available connectors of a given interface
842 type.
843 media=media
845 This option defines the type of the media: disk or cdrom.
846 snapshot=snapshot
848 snapshot is "on" or "off" and controls snapshot mode for the
849 given drive (see -snapshot).
850 cache=cache
852 cache is "none", "writeback", "unsafe", "directsync" or
853 "writethrough" and controls how the host cache is used to
854 access block data. This is a shortcut that sets the
855 cache.direct and cache.no-flush options (as in -blockdev), and
856 additionally cache.writeback, which provides a default for the
857 write-cache option of block guest devices (as in -device). The
858 modes correspond to the following settings:
859 │ cache.writeback cache.direct cache.no-flush
861 ─────────────┼─────────────────────────────────────────────────
862 writeback │ on off off
863 none │ on on off
864 writethrough │ off off off
865 directsync │ off on off
866 unsafe │ on off on
867 The default mode is cache=writeback.
869 aio=aio
871 aio is "threads", or "native" and selects between pthread based
872 disk I/O and native Linux AIO.
873 format=format
875 Specify which disk format will be used rather than detecting
876 the format. Can be used to specify format=raw to avoid
877 interpreting an untrusted format header.
878 werror=action,rerror=action
880 Specify which action to take on write and read errors. Valid
881 actions are: "ignore" (ignore the error and try to continue),
882 "stop" (pause QEMU), "report" (report the error to the guest),
883 "enospc" (pause QEMU only if the host disk is full; report the
884 error to the guest otherwise). The default setting is
885 werror=enospc and rerror=report.
886 copy-on-read=copy-on-read
888 copy-on-read is "on" or "off" and enables whether to copy read
889 backing file sectors into the image file.
890 bps=b,bps_rd=r,bps_wr=w
892 Specify bandwidth throttling limits in bytes per second, either
893 for all request types or for reads or writes only. Small
894 values can lead to timeouts or hangs inside the guest. A safe
895 minimum for disks is 2 MB/s.
896 bps_max=bm,bps_rd_max=rm,bps_wr_max=wm
898 Specify bursts in bytes per second, either for all request
899 types or for reads or writes only. Bursts allow the guest I/O
900 to spike above the limit temporarily.
901 iops=i,iops_rd=r,iops_wr=w
903 Specify request rate limits in requests per second, either for
904 all request types or for reads or writes only.
905 iops_max=bm,iops_rd_max=rm,iops_wr_max=wm
907 Specify bursts in requests per second, either for all request
908 types or for reads or writes only. Bursts allow the guest I/O
909 to spike above the limit temporarily.
910 iops_size=is
912 Let every is bytes of a request count as a new request for iops
913 throttling purposes. Use this option to prevent guests from
914 circumventing iops limits by sending fewer but larger requests.
915 group=g
917 Join a throttling quota group with given name g. All drives
918 that are members of the same group are accounted for together.
919 Use this option to prevent guests from circumventing throttling
920 limits by using many small disks instead of a single larger
921 disk.
922 By default, the cache.writeback=on mode is used. It will report
924 data writes as completed as soon as the data is present in the host
925 page cache. This is safe as long as your guest OS makes sure to
926 correctly flush disk caches where needed. If your guest OS does not
927 handle volatile disk write caches correctly and your host crashes
928 or loses power, then the guest may experience data corruption.
929 For such guests, you should consider using cache.writeback=off.
931 This means that the host page cache will be used to read and write
932 data, but write notification will be sent to the guest only after
933 QEMU has made sure to flush each write to the disk. Be aware that
934 this has a major impact on performance.
935 When using the -snapshot option, unsafe caching is always used.
937 Copy-on-read avoids accessing the same backing file sectors
939 repeatedly and is useful when the backing file is over a slow
940 network. By default copy-on-read is off.
941 Instead of -cdrom you can use:
943 qemu-system-i386 -drive file=file,index=2,media=cdrom
945 Instead of -hda, -hdb, -hdc, -hdd, you can use:
947 qemu-system-i386 -drive file=file,index=0,media=disk
949 qemu-system-i386 -drive file=file,index=1,media=disk
950 qemu-system-i386 -drive file=file,index=2,media=disk
951 qemu-system-i386 -drive file=file,index=3,media=disk
952 You can open an image using pre-opened file descriptors from an fd
954 set:
955 qemu-system-i386
957 -add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
958 -add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
959 -drive file=/dev/fdset/2,index=0,media=disk
960 You can connect a CDROM to the slave of ide0:
962 qemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom
964 If you don't specify the "file=" argument, you define an empty
966 drive:
967 qemu-system-i386 -drive if=ide,index=1,media=cdrom
969 Instead of -fda, -fdb, you can use:
971 qemu-system-i386 -drive file=file,index=0,if=floppy
973 qemu-system-i386 -drive file=file,index=1,if=floppy
974 By default, interface is "ide" and index is automatically
976 incremented:
977 qemu-system-i386 -drive file=a -drive file=b"
979 is interpreted like:
981 qemu-system-i386 -hda a -hdb b
983 -mtdblock file
985 Use file as on-board Flash memory image.
986 -sd file
988 Use file as SecureDigital card image.
989 -pflash file
991 Use file as a parallel flash image.
992 -snapshot
994 Write to temporary files instead of disk image files. In this case,
995 the raw disk image you use is not written back. You can however
996 force the write back by pressing C-a s.
997 -fsdev local,id=id,path=path,security_model=security_model
999 [,writeout=writeout][,readonly][,fmode=fmode][,dmode=dmode]
1000 [,throttling.option=value[,throttling.option=value[,...]]]
1001 -fsdev proxy,id=id,socket=socket[,writeout=writeout][,readonly]
1002 -fsdev proxy,id=id,sock_fd=sock_fd[,writeout=writeout][,readonly]
1003 -fsdev synth,id=id[,readonly]
1004 Define a new file system device. Valid options are:
1005 local
1007 Accesses to the filesystem are done by QEMU.
1008 proxy
1010 Accesses to the filesystem are done by virtfs-proxy-helper(1).
1011 synth
1013 Synthetic filesystem, only used by QTests.
1014 id=id
1016 Specifies identifier for this device.
1017 path=path
1019 Specifies the export path for the file system device. Files
1020 under this path will be available to the 9p client on the
1021 guest.
1022 security_model=security_model
1024 Specifies the security model to be used for this export path.
1025 Supported security models are "passthrough", "mapped-xattr",
1026 "mapped-file" and "none". In "passthrough" security model,
1027 files are stored using the same credentials as they are created
1028 on the guest. This requires QEMU to run as root. In "mapped-
1029 xattr" security model, some of the file attributes like uid,
1030 gid, mode bits and link target are stored as file attributes.
1031 For "mapped-file" these attributes are stored in the hidden
1032 .virtfs_metadata directory. Directories exported by this
1033 security model cannot interact with other unix tools. "none"
1034 security model is same as passthrough except the sever won't
1035 report failures if it fails to set file attributes like
1036 ownership. Security model is mandatory only for local fsdriver.
1037 Other fsdrivers (like proxy) don't take security model as a
1038 parameter.
1039 writeout=writeout
1041 This is an optional argument. The only supported value is
1042 "immediate". This means that host page cache will be used to
1043 read and write data but write notification will be sent to the
1044 guest only when the data has been reported as written by the
1045 storage subsystem.
1046 readonly
1048 Enables exporting 9p share as a readonly mount for guests. By
1049 default read-write access is given.
1050 socket=socket
1052 Enables proxy filesystem driver to use passed socket file for
1053 communicating with virtfs-proxy-helper(1).
1054 sock_fd=sock_fd
1056 Enables proxy filesystem driver to use passed socket descriptor
1057 for communicating with virtfs-proxy-helper(1). Usually a helper
1058 like libvirt will create socketpair and pass one of the fds as
1059 sock_fd.
1060 fmode=fmode
1062 Specifies the default mode for newly created files on the host.
1063 Works only with security models "mapped-xattr" and "mapped-
1064 file".
1065 dmode=dmode
1067 Specifies the default mode for newly created directories on the
1068 host. Works only with security models "mapped-xattr" and
1069 "mapped-file".
1070 throttling.bps-total=b,throttling.bps-read=r,throttling.bps-write=w
1072 Specify bandwidth throttling limits in bytes per second, either
1073 for all request types or for reads or writes only.
1074 throttling.bps-total-max=bm,bps-read-max=rm,bps-write-max=wm
1076 Specify bursts in bytes per second, either for all request
1077 types or for reads or writes only. Bursts allow the guest I/O
1078 to spike above the limit temporarily.
1079 throttling.iops-total=i,throttling.iops-read=r,
1081 throttling.iops-write=w
1082 Specify request rate limits in requests per second, either for
1083 all request types or for reads or writes only.
1084 throttling.iops-total-max=im,throttling.iops-read-max=irm,
1086 throttling.iops-write-max=iwm
1087 Specify bursts in requests per second, either for all request
1088 types or for reads or writes only. Bursts allow the guest I/O
1089 to spike above the limit temporarily.
1090 throttling.iops-size=is
1092 Let every is bytes of a request count as a new request for iops
1093 throttling purposes.
1094 -fsdev option is used along with -device driver "virtio-9p-...".
1096 -device virtio-9p-type,fsdev=id,mount_tag=mount_tag
1098 Options for virtio-9p-... driver are:
1099 type
1101 Specifies the variant to be used. Supported values are "pci",
1102 "ccw" or "device", depending on the machine type.
1103 fsdev=id
1105 Specifies the id value specified along with -fsdev option.
1106 mount_tag=mount_tag
1108 Specifies the tag name to be used by the guest to mount this
1109 export point.
1110 -virtfs local,path=path,mount_tag=mount_tag
1112 ,security_model=security_model[,writeout=writeout][,readonly]
1113 [,fmode=fmode][,dmode=dmode]
1114 -virtfs proxy,socket=socket,mount_tag=mount_tag
1115 [,writeout=writeout][,readonly]
1116 -virtfs proxy,sock_fd=sock_fd,mount_tag=mount_tag
1117 [,writeout=writeout][,readonly]
1118 -virtfs synth,mount_tag=mount_tag
1119 Define a new filesystem device and expose it to the guest using a
1120 virtio-9p-device. The general form of a Virtual File system pass-
1121 through options are:
1122 local
1124 Accesses to the filesystem are done by QEMU.
1125 proxy
1127 Accesses to the filesystem are done by virtfs-proxy-helper(1).
1128 synth
1130 Synthetic filesystem, only used by QTests.
1131 id=id
1133 Specifies identifier for the filesystem device
1134 path=path
1136 Specifies the export path for the file system device. Files
1137 under this path will be available to the 9p client on the
1138 guest.
1139 security_model=security_model
1141 Specifies the security model to be used for this export path.
1142 Supported security models are "passthrough", "mapped-xattr",
1143 "mapped-file" and "none". In "passthrough" security model,
1144 files are stored using the same credentials as they are created
1145 on the guest. This requires QEMU to run as root. In "mapped-
1146 xattr" security model, some of the file attributes like uid,
1147 gid, mode bits and link target are stored as file attributes.
1148 For "mapped-file" these attributes are stored in the hidden
1149 .virtfs_metadata directory. Directories exported by this
1150 security model cannot interact with other unix tools. "none"
1151 security model is same as passthrough except the sever won't
1152 report failures if it fails to set file attributes like
1153 ownership. Security model is mandatory only for local fsdriver.
1154 Other fsdrivers (like proxy) don't take security model as a
1155 parameter.
1156 writeout=writeout
1158 This is an optional argument. The only supported value is
1159 "immediate". This means that host page cache will be used to
1160 read and write data but write notification will be sent to the
1161 guest only when the data has been reported as written by the
1162 storage subsystem.
1163 readonly
1165 Enables exporting 9p share as a readonly mount for guests. By
1166 default read-write access is given.
1167 socket=socket
1169 Enables proxy filesystem driver to use passed socket file for
1170 communicating with virtfs-proxy-helper(1). Usually a helper
1171 like libvirt will create socketpair and pass one of the fds as
1172 sock_fd.
1173 sock_fd
1175 Enables proxy filesystem driver to use passed 'sock_fd' as the
1176 socket descriptor for interfacing with virtfs-proxy-helper(1).
1177 fmode=fmode
1179 Specifies the default mode for newly created files on the host.
1180 Works only with security models "mapped-xattr" and "mapped-
1181 file".
1182 dmode=dmode
1184 Specifies the default mode for newly created directories on the
1185 host. Works only with security models "mapped-xattr" and
1186 "mapped-file".
1187 mount_tag=mount_tag
1189 Specifies the tag name to be used by the guest to mount this
1190 export point.
1191 -virtfs_synth
1193 Create synthetic file system image. Note that this option is now
1194 deprecated. Please use "-fsdev synth" and "-device virtio-9p-..."
1195 instead.
1196 -iscsi
1198 Configure iSCSI session parameters.
1199 USB options
1201 -usb
1203 Enable the USB driver (if it is not used by default yet).
1204 -usbdevice devname
1206 Add the USB device devname. Note that this option is deprecated,
1207 please use "-device usb-..." instead.
1208 mouse
1210 Virtual Mouse. This will override the PS/2 mouse emulation when
1211 activated.
1212 tablet
1214 Pointer device that uses absolute coordinates (like a
1215 touchscreen). This means QEMU is able to report the mouse
1216 position without having to grab the mouse. Also overrides the
1217 PS/2 mouse emulation when activated.
1218 braille
1220 Braille device. This will use BrlAPI to display the braille
1221 output on a real or fake device.
1222 Display options
1224 -display type
1226 Select type of display to use. This option is a replacement for the
1227 old style -sdl/-curses/... options. Valid values for type are
1228 sdl Display video output via SDL (usually in a separate graphics
1230 window; see the SDL documentation for other possibilities).
1231 curses
1233 Display video output via curses. For graphics device models
1234 which support a text mode, QEMU can display this output using a
1235 curses/ncurses interface. Nothing is displayed when the
1236 graphics device is in graphical mode or if the graphics device
1237 does not support a text mode. Generally only the VGA device
1238 models support text mode. The font charset used by the guest
1239 can be specified with the "charset" option, for example
1240 "charset=CP850" for IBM CP850 encoding. The default is "CP437".
1241 none
1243 Do not display video output. The guest will still see an
1244 emulated graphics card, but its output will not be displayed to
1245 the QEMU user. This option differs from the -nographic option
1246 in that it only affects what is done with video output;
1247 -nographic also changes the destination of the serial and
1248 parallel port data.
1249 gtk Display video output in a GTK window. This interface provides
1251 drop-down menus and other UI elements to configure and control
1252 the VM during runtime.
1253 vnc Start a VNC server on display <arg>
1255 egl-headless
1257 Offload all OpenGL operations to a local DRI device. For any
1258 graphical display, this display needs to be paired with either
1259 VNC or SPICE displays.
1260 spice-app
1262 Start QEMU as a Spice server and launch the default Spice
1263 client application. The Spice server will redirect the serial
1264 consoles and QEMU monitors. (Since 4.0)
1265 -nographic
1267 Normally, if QEMU is compiled with graphical window support, it
1268 displays output such as guest graphics, guest console, and the QEMU
1269 monitor in a window. With this option, you can totally disable
1270 graphical output so that QEMU is a simple command line application.
1271 The emulated serial port is redirected on the console and muxed
1272 with the monitor (unless redirected elsewhere explicitly).
1273 Therefore, you can still use QEMU to debug a Linux kernel with a
1274 serial console. Use C-a h for help on switching between the console
1275 and monitor.
1276 -curses
1278 Normally, if QEMU is compiled with graphical window support, it
1279 displays output such as guest graphics, guest console, and the QEMU
1280 monitor in a window. With this option, QEMU can display the VGA
1281 output when in text mode using a curses/ncurses interface. Nothing
1282 is displayed in graphical mode.
1283 -alt-grab
1285 Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that
1286 this also affects the special keys (for fullscreen, monitor-mode
1287 switching, etc).
1288 -ctrl-grab
1290 Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this
1291 also affects the special keys (for fullscreen, monitor-mode
1292 switching, etc).
1293 -no-quit
1295 Disable SDL window close capability.
1296 -sdl
1298 Enable SDL.
1299 -spice option[,option[,...]]
1301 Enable the spice remote desktop protocol. Valid options are
1302 port=<nr>
1304 Set the TCP port spice is listening on for plaintext channels.
1305 addr=<addr>
1307 Set the IP address spice is listening on. Default is any
1308 address.
1309 ipv4
1311 ipv6
1312 unix
1313 Force using the specified IP version.
1314 password=<secret>
1316 Set the password you need to authenticate.
1317 sasl
1319 Require that the client use SASL to authenticate with the
1320 spice. The exact choice of authentication method used is
1321 controlled from the system / user's SASL configuration file for
1322 the 'qemu' service. This is typically found in
1323 /etc/sasl2/qemu.conf. If running QEMU as an unprivileged user,
1324 an environment variable SASL_CONF_PATH can be used to make it
1325 search alternate locations for the service config. While some
1326 SASL auth methods can also provide data encryption (eg GSSAPI),
1327 it is recommended that SASL always be combined with the 'tls'
1328 and 'x509' settings to enable use of SSL and server
1329 certificates. This ensures a data encryption preventing
1330 compromise of authentication credentials.
1331 disable-ticketing
1333 Allow client connects without authentication.
1334 disable-copy-paste
1336 Disable copy paste between the client and the guest.
1337 disable-agent-file-xfer
1339 Disable spice-vdagent based file-xfer between the client and
1340 the guest.
1341 tls-port=<nr>
1343 Set the TCP port spice is listening on for encrypted channels.
1344 x509-dir=<dir>
1346 Set the x509 file directory. Expects same filenames as -vnc
1347 $display,x509=$dir
1348 x509-key-file=<file>
1350 x509-key-password=<file>
1351 x509-cert-file=<file>
1352 x509-cacert-file=<file>
1353 x509-dh-key-file=<file>
1354 The x509 file names can also be configured individually.
1355 tls-ciphers=<list>
1357 Specify which ciphers to use.
1358 tls-channel=[main|display|cursor|inputs|record|playback]
1360 plaintext-channel=[main|display|cursor|inputs|record|playback]
1361 Force specific channel to be used with or without TLS
1362 encryption. The options can be specified multiple times to
1363 configure multiple channels. The special name "default" can be
1364 used to set the default mode. For channels which are not
1365 explicitly forced into one mode the spice client is allowed to
1366 pick tls/plaintext as he pleases.
1367 image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
1369 Configure image compression (lossless). Default is auto_glz.
1370 jpeg-wan-compression=[auto|never|always]
1372 zlib-glz-wan-compression=[auto|never|always]
1373 Configure wan image compression (lossy for slow links).
1374 Default is auto.
1375 streaming-video=[off|all|filter]
1377 Configure video stream detection. Default is off.
1378 agent-mouse=[on|off]
1380 Enable/disable passing mouse events via vdagent. Default is
1381 on.
1382 playback-compression=[on|off]
1384 Enable/disable audio stream compression (using celt 0.5.1).
1385 Default is on.
1386 seamless-migration=[on|off]
1388 Enable/disable spice seamless migration. Default is off.
1389 gl=[on|off]
1391 Enable/disable OpenGL context. Default is off.
1392 rendernode=<file>
1394 DRM render node for OpenGL rendering. If not specified, it will
1395 pick the first available. (Since 2.9)
1396 -portrait
1398 Rotate graphical output 90 deg left (only PXA LCD).
1399 -rotate deg
1401 Rotate graphical output some deg left (only PXA LCD).
1402 -vga type
1404 Select type of VGA card to emulate. Valid values for type are
1405 cirrus
1407 Cirrus Logic GD5446 Video card. All Windows versions starting
1408 from Windows 95 should recognize and use this graphic card. For
1409 optimal performances, use 16 bit color depth in the guest and
1410 the host OS. (This card was the default before QEMU 2.2)
1411 std Standard VGA card with Bochs VBE extensions. If your guest OS
1413 supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if
1414 you want to use high resolution modes (>= 1280x1024x16) then
1415 you should use this option. (This card is the default since
1416 QEMU 2.2)
1417 vmware
1419 VMWare SVGA-II compatible adapter. Use it if you have
1420 sufficiently recent XFree86/XOrg server or Windows guest with a
1421 driver for this card.
1422 qxl QXL paravirtual graphic card. It is VGA compatible (including
1424 VESA 2.0 VBE support). Works best with qxl guest drivers
1425 installed though. Recommended choice when using the spice
1426 protocol.
1427 tcx (sun4m only) Sun TCX framebuffer. This is the default
1429 framebuffer for sun4m machines and offers both 8-bit and 24-bit
1430 colour depths at a fixed resolution of 1024x768.
1431 cg3 (sun4m only) Sun cgthree framebuffer. This is a simple 8-bit
1433 framebuffer for sun4m machines available in both 1024x768
1434 (OpenBIOS) and 1152x900 (OBP) resolutions aimed at people
1435 wishing to run older Solaris versions.
1436 virtio
1438 Virtio VGA card.
1439 none
1441 Disable VGA card.
1442 -full-screen
1444 Start in full screen.
1445 -g widthxheight[xdepth]
1447 Set the initial graphical resolution and depth (PPC, SPARC only).
1448 -vnc display[,option[,option[,...]]]
1450 Normally, if QEMU is compiled with graphical window support, it
1451 displays output such as guest graphics, guest console, and the QEMU
1452 monitor in a window. With this option, you can have QEMU listen on
1453 VNC display display and redirect the VGA display over the VNC
1454 session. It is very useful to enable the usb tablet device when
1455 using this option (option -device usb-tablet). When using the VNC
1456 display, you must use the -k parameter to set the keyboard layout
1457 if you are not using en-us. Valid syntax for the display is
1458 to=L
1460 With this option, QEMU will try next available VNC displays,
1461 until the number L, if the origianlly defined "-vnc display" is
1462 not available, e.g. port 5900+display is already used by
1463 another application. By default, to=0.
1464 host:d
1466 TCP connections will only be allowed from host on display d.
1467 By convention the TCP port is 5900+d. Optionally, host can be
1468 omitted in which case the server will accept connections from
1469 any host.
1470 unix:path
1472 Connections will be allowed over UNIX domain sockets where path
1473 is the location of a unix socket to listen for connections on.
1474 none
1476 VNC is initialized but not started. The monitor "change"
1477 command can be used to later start the VNC server.
1478 Following the display value there may be one or more option flags
1480 separated by commas. Valid options are
1481 reverse
1483 Connect to a listening VNC client via a "reverse" connection.
1484 The client is specified by the display. For reverse network
1485 connections (host:d,"reverse"), the d argument is a TCP port
1486 number, not a display number.
1487 websocket
1489 Opens an additional TCP listening port dedicated to VNC
1490 Websocket connections. If a bare websocket option is given,
1491 the Websocket port is 5700+display. An alternative port can be
1492 specified with the syntax "websocket"=port.
1493 If host is specified connections will only be allowed from this
1495 host. It is possible to control the websocket listen address
1496 independently, using the syntax "websocket"=host:port.
1497 If no TLS credentials are provided, the websocket connection
1499 runs in unencrypted mode. If TLS credentials are provided, the
1500 websocket connection requires encrypted client connections.
1501 password
1503 Require that password based authentication is used for client
1504 connections.
1505 The password must be set separately using the "set_password"
1507 command in the pcsys_monitor. The syntax to change your
1508 password is: "set_password <protocol> <password>" where
1509 <protocol> could be either "vnc" or "spice".
1510 If you would like to change <protocol> password expiration, you
1512 should use "expire_password <protocol> <expiration-time>" where
1513 expiration time could be one of the following options: now,
1514 never, +seconds or UNIX time of expiration, e.g. +60 to make
1515 password expire in 60 seconds, or 1335196800 to make password
1516 expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this
1517 date and time).
1518 You can also use keywords "now" or "never" for the expiration
1520 time to allow <protocol> password to expire immediately or
1521 never expire.
1522 tls-creds=ID
1524 Provides the ID of a set of TLS credentials to use to secure
1525 the VNC server. They will apply to both the normal VNC server
1526 socket and the websocket socket (if enabled). Setting TLS
1527 credentials will cause the VNC server socket to enable the
1528 VeNCrypt auth mechanism. The credentials should have been
1529 previously created using the -object tls-creds argument.
1530 tls-authz=ID
1532 Provides the ID of the QAuthZ authorization object against
1533 which the client's x509 distinguished name will validated. This
1534 object is only resolved at time of use, so can be deleted and
1535 recreated on the fly while the VNC server is active. If
1536 missing, it will default to denying access.
1537 sasl
1539 Require that the client use SASL to authenticate with the VNC
1540 server. The exact choice of authentication method used is
1541 controlled from the system / user's SASL configuration file for
1542 the 'qemu' service. This is typically found in
1543 /etc/sasl2/qemu.conf. If running QEMU as an unprivileged user,
1544 an environment variable SASL_CONF_PATH can be used to make it
1545 search alternate locations for the service config. While some
1546 SASL auth methods can also provide data encryption (eg GSSAPI),
1547 it is recommended that SASL always be combined with the 'tls'
1548 and 'x509' settings to enable use of SSL and server
1549 certificates. This ensures a data encryption preventing
1550 compromise of authentication credentials. See the vnc_security
1551 section for details on using SASL authentication.
1552 sasl-authz=ID
1554 Provides the ID of the QAuthZ authorization object against
1555 which the client's SASL username will validated. This object is
1556 only resolved at time of use, so can be deleted and recreated
1557 on the fly while the VNC server is active. If missing, it will
1558 default to denying access.
1559 acl Legacy method for enabling authorization of clients against the
1561 x509 distinguished name and SASL username. It results in the
1562 creation of two "authz-list" objects with IDs of "vnc.username"
1563 and "vnc.x509dname". The rules for these objects must be
1564 configured with the HMP ACL commands.
1565 This option is deprecated and should no longer be used. The new
1567 sasl-authz and tls-authz options are a replacement.
1568 lossy
1570 Enable lossy compression methods (gradient, JPEG, ...). If this
1571 option is set, VNC client may receive lossy framebuffer updates
1572 depending on its encoding settings. Enabling this option can
1573 save a lot of bandwidth at the expense of quality.
1574 non-adaptive
1576 Disable adaptive encodings. Adaptive encodings are enabled by
1577 default. An adaptive encoding will try to detect frequently
1578 updated screen regions, and send updates in these regions using
1579 a lossy encoding (like JPEG). This can be really helpful to
1580 save bandwidth when playing videos. Disabling adaptive
1581 encodings restores the original static behavior of encodings
1582 like Tight.
1583 share=[allow-exclusive|force-shared|ignore]
1585 Set display sharing policy. 'allow-exclusive' allows clients
1586 to ask for exclusive access. As suggested by the rfb spec this
1587 is implemented by dropping other connections. Connecting
1588 multiple clients in parallel requires all clients asking for a
1589 shared session (vncviewer: -shared switch). This is the
1590 default. 'force-shared' disables exclusive client access.
1591 Useful for shared desktop sessions, where you don't want
1592 someone forgetting specify -shared disconnect everybody else.
1593 'ignore' completely ignores the shared flag and allows
1594 everybody connect unconditionally. Doesn't conform to the rfb
1595 spec but is traditional QEMU behavior.
1596 key-delay-ms
1598 Set keyboard delay, for key down and key up events, in
1599 milliseconds. Default is 10. Keyboards are low-bandwidth
1600 devices, so this slowdown can help the device and guest to keep
1601 up and not lose events in case events are arriving in bulk.
1602 Possible causes for the latter are flaky network connections,
1603 or scripts for automated testing.
1604 i386 target only
1606 -win2k-hack
1608 Use it when installing Windows 2000 to avoid a disk full bug. After
1609 Windows 2000 is installed, you no longer need this option (this
1610 option slows down the IDE transfers).
1611 -no-fd-bootchk
1613 Disable boot signature checking for floppy disks in BIOS. May be
1614 needed to boot from old floppy disks.
1615 -no-acpi
1617 Disable ACPI (Advanced Configuration and Power Interface) support.
1618 Use it if your guest OS complains about ACPI problems (PC target
1619 machine only).
1620 -no-hpet
1622 Disable HPET support.
1623 -acpitable
1625 [sig=str][,rev=n][,oem_id=str][,oem_table_id=str][,oem_rev=n]
1626 [,asl_compiler_id=str][,asl_compiler_rev=n][,data=file1[:file2]...]
1627 Add ACPI table with specified header fields and context from
1628 specified files. For file=, take whole ACPI table from the
1629 specified files, including all ACPI headers (possible overridden by
1630 other options). For data=, only data portion of the table is used,
1631 all header information is specified in the command line. If a SLIC
1632 table is supplied to QEMU, then the SLIC's oem_id and oem_table_id
1633 fields will override the same in the RSDT and the FADT (a.k.a.
1634 FACP), in order to ensure the field matches required by the
1635 Microsoft SLIC spec and the ACPI spec.
1636 -smbios file=binary
1638 Load SMBIOS entry from binary file.
1639 -smbios
1641 type=0[,vendor=str][,version=str][,date=str][,release=%d.%d][,uefi=on|off]
1642 Specify SMBIOS type 0 fields
1643 -smbios
1645 type=1[,manufacturer=str][,product=str][,version=str][,serial=str][,uuid=uuid][,sku=str][,family=str]
1646 Specify SMBIOS type 1 fields
1647 -smbios
1649 type=2[,manufacturer=str][,product=str][,version=str][,serial=str][,asset=str][,location=str]
1650 Specify SMBIOS type 2 fields
1651 -smbios
1653 type=3[,manufacturer=str][,version=str][,serial=str][,asset=str][,sku=str]
1654 Specify SMBIOS type 3 fields
1655 -smbios
1657 type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str][,asset=str][,part=str]
1658 Specify SMBIOS type 4 fields
1659 -smbios
1661 type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str][,asset=str][,part=str][,speed=%d]
1662 Specify SMBIOS type 17 fields
1663 Network options
1665 -nic
1667 [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn]
1668 This option is a shortcut for configuring both the on-board
1669 (default) guest NIC hardware and the host network backend in one
1670 go. The host backend options are the same as with the corresponding
1671 -netdev options below. The guest NIC model can be set with
1672 model=modelname. Use model=help to list the available device
1673 types. The hardware MAC address can be set with mac=macaddr.
1674 The following two example do exactly the same, to show how -nic can
1676 be used to shorten the command line length (note that the e1000 is
1677 the default on i386, so the model=e1000 parameter could even be
1678 omitted here, too):
1679 qemu-system-i386 -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32
1681 qemu-system-i386 -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32
1682 -nic none
1684 Indicate that no network devices should be configured. It is used
1685 to override the default configuration (default NIC with "user" host
1686 network backend) which is activated if no other networking options
1687 are provided.
1688 -netdev user,id=id[,option][,option][,...]
1690 Configure user mode host network backend which requires no
1691 administrator privilege to run. Valid options are:
1692 id=id
1694 Assign symbolic name for use in monitor commands.
1695 ipv4=on|off and ipv6=on|off
1697 Specify that either IPv4 or IPv6 must be enabled. If neither is
1698 specified both protocols are enabled.
1699 net=addr[/mask]
1701 Set IP network address the guest will see. Optionally specify
1702 the netmask, either in the form a.b.c.d or as number of valid
1703 top-most bits. Default is 10.0.2.0/24.
1704 host=addr
1706 Specify the guest-visible address of the host. Default is the
1707 2nd IP in the guest network, i.e. x.x.x.2.
1708 ipv6-net=addr[/int]
1710 Set IPv6 network address the guest will see (default is
1711 fec0::/64). The network prefix is given in the usual
1712 hexadecimal IPv6 address notation. The prefix size is optional,
1713 and is given as the number of valid top-most bits (default is
1714 64).
1715 ipv6-host=addr
1717 Specify the guest-visible IPv6 address of the host. Default is
1718 the 2nd IPv6 in the guest network, i.e. xxxx::2.
1719 restrict=on|off
1721 If this option is enabled, the guest will be isolated, i.e. it
1722 will not be able to contact the host and no guest IP packets
1723 will be routed over the host to the outside. This option does
1724 not affect any explicitly set forwarding rules.
1725 hostname=name
1727 Specifies the client hostname reported by the built-in DHCP
1728 server.
1729 dhcpstart=addr
1731 Specify the first of the 16 IPs the built-in DHCP server can
1732 assign. Default is the 15th to 31st IP in the guest network,
1733 i.e. x.x.x.15 to x.x.x.31.
1734 dns=addr
1736 Specify the guest-visible address of the virtual nameserver.
1737 The address must be different from the host address. Default is
1738 the 3rd IP in the guest network, i.e. x.x.x.3.
1739 ipv6-dns=addr
1741 Specify the guest-visible address of the IPv6 virtual
1742 nameserver. The address must be different from the host
1743 address. Default is the 3rd IP in the guest network, i.e.
1744 xxxx::3.
1745 dnssearch=domain
1747 Provides an entry for the domain-search list sent by the built-
1748 in DHCP server. More than one domain suffix can be transmitted
1749 by specifying this option multiple times. If supported, this
1750 will cause the guest to automatically try to append the given
1751 domain suffix(es) in case a domain name can not be resolved.
1752 Example:
1754 qemu-system-i386 -nic user,dnssearch=mgmt.example.org,dnssearch=example.org
1756 domainname=domain
1758 Specifies the client domain name reported by the built-in DHCP
1759 server.
1760 tftp=dir
1762 When using the user mode network stack, activate a built-in
1763 TFTP server. The files in dir will be exposed as the root of a
1764 TFTP server. The TFTP client on the guest must be configured
1765 in binary mode (use the command "bin" of the Unix TFTP client).
1766 tftp-server-name=name
1768 In BOOTP reply, broadcast name as the "TFTP server name"
1769 (RFC2132 option 66). This can be used to advise the guest to
1770 load boot files or configurations from a different server than
1771 the host address.
1772 bootfile=file
1774 When using the user mode network stack, broadcast file as the
1775 BOOTP filename. In conjunction with tftp, this can be used to
1776 network boot a guest from a local directory.
1777 Example (using pxelinux):
1779 qemu-system-i386 -hda linux.img -boot n -device e1000,netdev=n1 \
1781 -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
1782 smb=dir[,smbserver=addr]
1784 When using the user mode network stack, activate a built-in SMB
1785 server so that Windows OSes can access to the host files in dir
1786 transparently. The IP address of the SMB server can be set to
1787 addr. By default the 4th IP in the guest network is used, i.e.
1788 x.x.x.4.
1789 In the guest Windows OS, the line:
1791 10.0.2.4 smbserver
1793 must be added in the file C:\WINDOWS\LMHOSTS (for windows
1795 9x/Me) or C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS (Windows
1796 NT/2000).
1797 Then dir can be accessed in \\smbserver\qemu.
1799 Note that a SAMBA server must be installed on the host OS.
1801 hostfwd=[tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport
1803 Redirect incoming TCP or UDP connections to the host port
1804 hostport to the guest IP address guestaddr on guest port
1805 guestport. If guestaddr is not specified, its value is x.x.x.15
1806 (default first address given by the built-in DHCP server). By
1807 specifying hostaddr, the rule can be bound to a specific host
1808 interface. If no connection type is set, TCP is used. This
1809 option can be given multiple times.
1810 For example, to redirect host X11 connection from screen 1 to
1812 guest screen 0, use the following:
1813 # on the host
1815 qemu-system-i386 -nic user,hostfwd=tcp:127.0.0.1:6001-:6000
1816 # this host xterm should open in the guest X11 server
1817 xterm -display :1
1818 To redirect telnet connections from host port 5555 to telnet
1820 port on the guest, use the following:
1821 # on the host
1823 qemu-system-i386 -nic user,hostfwd=tcp::5555-:23
1824 telnet localhost 5555
1825 Then when you use on the host "telnet localhost 5555", you
1827 connect to the guest telnet server.
1828 guestfwd=[tcp]:server:port-dev
1830 guestfwd=[tcp]:server:port-cmd:command
1831 Forward guest TCP connections to the IP address server on port
1832 port to the character device dev or to a program executed by
1833 cmd:command which gets spawned for each connection. This option
1834 can be given multiple times.
1835 You can either use a chardev directly and have that one used
1837 throughout QEMU's lifetime, like in the following example:
1838 # open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever
1840 # the guest accesses it
1841 qemu-system-i386 -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321
1842 Or you can execute a command on every TCP connection
1844 established by the guest, so that QEMU behaves similar to an
1845 inetd process for that virtual server:
1846 # call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234
1848 # and connect the TCP stream to its stdin/stdout
1849 qemu-system-i386 -nic 'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321'
1850 -netdev
1852 tap,id=id[,fd=h][,ifname=name][,script=file][,downscript=dfile][,br=bridge][,helper=helper]
1853 Configure a host TAP network backend with ID id.
1854 Use the network script file to configure it and the network script
1856 dfile to deconfigure it. If name is not provided, the OS
1857 automatically provides one. The default network configure script is
1858 /etc/qemu-ifup and the default network deconfigure script is
1859 /etc/qemu-ifdown. Use script=no or downscript=no to disable script
1860 execution.
1861 If running QEMU as an unprivileged user, use the network helper
1863 helper to configure the TAP interface and attach it to the bridge.
1864 The default network helper executable is
1865 /path/to/qemu-bridge-helper and the default bridge device is br0.
1866 fd=h can be used to specify the handle of an already opened host
1868 TAP interface.
1869 Examples:
1871 #launch a QEMU instance with the default network script
1873 qemu-system-i386 linux.img -nic tap
1874 #launch a QEMU instance with two NICs, each one connected
1878 #to a TAP device
1879 qemu-system-i386 linux.img \
1880 -netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 \
1881 -netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1
1882 #launch a QEMU instance with the default network helper to
1886 #connect a TAP device to bridge br0
1887 qemu-system-i386 linux.img -device virtio-net-pci,netdev=n1 \
1888 -netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper"
1889 -netdev bridge,id=id[,br=bridge][,helper=helper]
1891 Connect a host TAP network interface to a host bridge device.
1892 Use the network helper helper to configure the TAP interface and
1894 attach it to the bridge. The default network helper executable is
1895 /path/to/qemu-bridge-helper and the default bridge device is br0.
1896 Examples:
1898 #launch a QEMU instance with the default network helper to
1900 #connect a TAP device to bridge br0
1901 qemu-system-i386 linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1
1902 #launch a QEMU instance with the default network helper to
1906 #connect a TAP device to bridge qemubr0
1907 qemu-system-i386 linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1
1908 -netdev socket,id=id[,fd=h][,listen=[host]:port][,connect=host:port]
1910 This host network backend can be used to connect the guest's
1911 network to another QEMU virtual machine using a TCP socket
1912 connection. If listen is specified, QEMU waits for incoming
1913 connections on port (host is optional). connect is used to connect
1914 to another QEMU instance using the listen option. fd=h specifies an
1915 already opened TCP socket.
1916 Example:
1918 # launch a first QEMU instance
1920 qemu-system-i386 linux.img \
1921 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
1922 -netdev socket,id=n1,listen=:1234
1923 # connect the network of this instance to the network of the first instance
1924 qemu-system-i386 linux.img \
1925 -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
1926 -netdev socket,id=n2,connect=127.0.0.1:1234
1927 -netdev socket,id=id[,fd=h][,mcast=maddr:port[,localaddr=addr]]
1929 Configure a socket host network backend to share the guest's
1930 network traffic with another QEMU virtual machines using a UDP
1931 multicast socket, effectively making a bus for every QEMU with same
1932 multicast address maddr and port. NOTES:
1933 1. Several QEMU can be running on different hosts and share same
1935 bus (assuming correct multicast setup for these hosts).
1936 2. mcast support is compatible with User Mode Linux (argument
1938 ethN=mcast), see <http://user-mode-linux.sf.net>.
1939 3. Use fd=h to specify an already opened UDP multicast socket.
1941 Example:
1943 # launch one QEMU instance
1945 qemu-system-i386 linux.img \
1946 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
1947 -netdev socket,id=n1,mcast=230.0.0.1:1234
1948 # launch another QEMU instance on same "bus"
1949 qemu-system-i386 linux.img \
1950 -device e1000,netdev=n2,mac=52:54:00:12:34:57 \
1951 -netdev socket,id=n2,mcast=230.0.0.1:1234
1952 # launch yet another QEMU instance on same "bus"
1953 qemu-system-i386 linux.img \
1954 -device e1000,netdev=n3,mac=52:54:00:12:34:58 \
1955 -netdev socket,id=n3,mcast=230.0.0.1:1234
1956 Example (User Mode Linux compat.):
1958 # launch QEMU instance (note mcast address selected is UML's default)
1960 qemu-system-i386 linux.img \
1961 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
1962 -netdev socket,id=n1,mcast=239.192.168.1:1102
1963 # launch UML
1964 /path/to/linux ubd0=/path/to/root_fs eth0=mcast
1965 Example (send packets from host's 1.2.3.4):
1967 qemu-system-i386 linux.img \
1969 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \
1970 -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4
1971 -netdev
1973 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]
1974 Configure a L2TPv3 pseudowire host network backend. L2TPv3
1975 (RFC3391) is a popular protocol to transport Ethernet (and other
1976 Layer 2) data frames between two systems. It is present in routers,
1977 firewalls and the Linux kernel (from version 3.3 onwards).
1978 This transport allows a VM to communicate to another VM, router or
1980 firewall directly.
1981 src=srcaddr
1983 source address (mandatory)
1984 dst=dstaddr
1986 destination address (mandatory)
1987 udp select udp encapsulation (default is ip).
1989 srcport=srcport
1991 source udp port.
1992 dstport=dstport
1994 destination udp port.
1995 ipv6
1997 force v6, otherwise defaults to v4.
1998 rxcookie=rxcookie
2000 txcookie=txcookie
2001 Cookies are a weak form of security in the l2tpv3
2002 specification. Their function is mostly to prevent
2003 misconfiguration. By default they are 32 bit.
2004 cookie64
2006 Set cookie size to 64 bit instead of the default 32
2007 counter=off
2009 Force a 'cut-down' L2TPv3 with no counter as in
2010 draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
2011 pincounter=on
2013 Work around broken counter handling in peer. This may also help
2014 on networks which have packet reorder.
2015 offset=offset
2017 Add an extra offset between header and data
2018 For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to
2020 the bridge br-lan on the remote Linux host 1.2.3.4:
2021 # Setup tunnel on linux host using raw ip as encapsulation
2023 # on 1.2.3.4
2024 ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \
2025 encap udp udp_sport 16384 udp_dport 16384
2026 ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \
2027 0xFFFFFFFF peer_session_id 0xFFFFFFFF
2028 ifconfig vmtunnel0 mtu 1500
2029 ifconfig vmtunnel0 up
2030 brctl addif br-lan vmtunnel0
2031 # on 4.3.2.1
2034 # launch QEMU instance - if your network has reorder or is very lossy add ,pincounter
2035 qemu-system-i386 linux.img -device e1000,netdev=n1 \
2037 -netdev l2tpv3,id=n1,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter
2038 -netdev
2040 vde,id=id[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]
2041 Configure VDE backend to connect to PORT n of a vde switch running
2042 on host and listening for incoming connections on socketpath. Use
2043 GROUP groupname and MODE octalmode to change default ownership and
2044 permissions for communication port. This option is only available
2045 if QEMU has been compiled with vde support enabled.
2046 Example:
2048 # launch vde switch
2050 vde_switch -F -sock /tmp/myswitch
2051 # launch QEMU instance
2052 qemu-system-i386 linux.img -nic vde,sock=/tmp/myswitch
2053 -netdev vhost-user,chardev=id[,vhostforce=on|off][,queues=n]
2055 Establish a vhost-user netdev, backed by a chardev id. The chardev
2056 should be a unix domain socket backed one. The vhost-user uses a
2057 specifically defined protocol to pass vhost ioctl replacement
2058 messages to an application on the other end of the socket. On non-
2059 MSIX guests, the feature can be forced with vhostforce. Use
2060 'queues=n' to specify the number of queues to be created for
2061 multiqueue vhost-user.
2062 Example:
2064 qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \
2066 -numa node,memdev=mem \
2067 -chardev socket,id=chr0,path=/path/to/socket \
2068 -netdev type=vhost-user,id=net0,chardev=chr0 \
2069 -device virtio-net-pci,netdev=net0
2070 -netdev hubport,id=id,hubid=hubid[,netdev=nd]
2072 Create a hub port on the emulated hub with ID hubid.
2073 The hubport netdev lets you connect a NIC to a QEMU emulated hub
2075 instead of a single netdev. Alternatively, you can also connect the
2076 hubport to another netdev with ID nd by using the netdev=nd option.
2077 -net nic[,netdev=nd][,macaddr=mac][,model=type]
2079 [,name=name][,addr=addr][,vectors=v]
2080 Legacy option to configure or create an on-board (or machine
2081 default) Network Interface Card(NIC) and connect it either to the
2082 emulated hub with ID 0 (i.e. the default hub), or to the netdev
2083 nd. The NIC is an e1000 by default on the PC target. Optionally,
2084 the MAC address can be changed to mac, the device address set to
2085 addr (PCI cards only), and a name can be assigned for use in
2086 monitor commands. Optionally, for PCI cards, you can specify the
2087 number v of MSI-X vectors that the card should have; this option
2088 currently only affects virtio cards; set v = 0 to disable MSI-X. If
2089 no -net option is specified, a single NIC is created. QEMU can
2090 emulate several different models of network card. Use "-net
2091 nic,model=help" for a list of available devices for your target.
2092 -net user|tap|bridge|socket|l2tpv3|vde[,...][,name=name]
2094 Configure a host network backend (with the options corresponding to
2095 the same -netdev option) and connect it to the emulated hub 0 (the
2096 default hub). Use name to specify the name of the hub port.
2097 Character device options
2099 The general form of a character device option is:
2101 -chardev backend,id=id[,mux=on|off][,options]
2103 Backend is one of: null, socket, udp, msmouse, vc, ringbuf, file,
2104 pipe, console, serial, pty, stdio, braille, tty, parallel, parport,
2105 spicevmc, spiceport. The specific backend will determine the
2106 applicable options.
2107 Use "-chardev help" to print all available chardev backend types.
2109 All devices must have an id, which can be any string up to 127
2111 characters long. It is used to uniquely identify this device in
2112 other command line directives.
2113 A character device may be used in multiplexing mode by multiple
2115 front-ends. Specify mux=on to enable this mode. A multiplexer is
2116 a "1:N" device, and here the "1" end is your specified chardev
2117 backend, and the "N" end is the various parts of QEMU that can talk
2118 to a chardev. If you create a chardev with id=myid and mux=on,
2119 QEMU will create a multiplexer with your specified ID, and you can
2120 then configure multiple front ends to use that chardev ID for their
2121 input/output. Up to four different front ends can be connected to a
2122 single multiplexed chardev. (Without multiplexing enabled, a
2123 chardev can only be used by a single front end.) For instance you
2124 could use this to allow a single stdio chardev to be used by two
2125 serial ports and the QEMU monitor:
2126 -chardev stdio,mux=on,id=char0 \
2128 -mon chardev=char0,mode=readline \
2129 -serial chardev:char0 \
2130 -serial chardev:char0
2131 You can have more than one multiplexer in a system configuration;
2133 for instance you could have a TCP port multiplexed between UART 0
2134 and UART 1, and stdio multiplexed between the QEMU monitor and a
2135 parallel port:
2136 -chardev stdio,mux=on,id=char0 \
2138 -mon chardev=char0,mode=readline \
2139 -parallel chardev:char0 \
2140 -chardev tcp,...,mux=on,id=char1 \
2141 -serial chardev:char1 \
2142 -serial chardev:char1
2143 When you're using a multiplexed character device, some escape
2145 sequences are interpreted in the input.
2146 Note that some other command line options may implicitly create
2148 multiplexed character backends; for instance -serial mon:stdio
2149 creates a multiplexed stdio backend connected to the serial port
2150 and the QEMU monitor, and -nographic also multiplexes the console
2151 and the monitor to stdio.
2152 There is currently no support for multiplexing in the other
2154 direction (where a single QEMU front end takes input and output
2155 from multiple chardevs).
2156 Every backend supports the logfile option, which supplies the path
2158 to a file to record all data transmitted via the backend. The
2159 logappend option controls whether the log file will be truncated or
2160 appended to when opened.
2161 The available backends are:
2163 -chardev null,id=id
2165 A void device. This device will not emit any data, and will drop
2166 any data it receives. The null backend does not take any options.
2167 -chardev socket,id=id[,TCP options or unix
2169 options][,server][,nowait][,telnet][,websocket][,reconnect=seconds][,tls-creds=id][,tls-authz=id]
2170 Create a two-way stream socket, which can be either a TCP or a unix
2171 socket. A unix socket will be created if path is specified.
2172 Behaviour is undefined if TCP options are specified for a unix
2173 socket.
2174 server specifies that the socket shall be a listening socket.
2176 nowait specifies that QEMU should not block waiting for a client to
2178 connect to a listening socket.
2179 telnet specifies that traffic on the socket should interpret telnet
2181 escape sequences.
2182 websocket specifies that the socket uses WebSocket protocol for
2184 communication.
2185 reconnect sets the timeout for reconnecting on non-server sockets
2187 when the remote end goes away. qemu will delay this many seconds
2188 and then attempt to reconnect. Zero disables reconnecting, and is
2189 the default.
2190 tls-creds requests enablement of the TLS protocol for encryption,
2192 and specifies the id of the TLS credentials to use for the
2193 handshake. The credentials must be previously created with the
2194 -object tls-creds argument.
2195 tls-auth provides the ID of the QAuthZ authorization object against
2197 which the client's x509 distinguished name will be validated. This
2198 object is only resolved at time of use, so can be deleted and
2199 recreated on the fly while the chardev server is active. If
2200 missing, it will default to denying access.
2201 TCP and unix socket options are given below:
2203 TCP options: port=port[,host=host][,to=to][,ipv4][,ipv6][,nodelay]
2205 host for a listening socket specifies the local address to be
2206 bound. For a connecting socket species the remote host to
2207 connect to. host is optional for listening sockets. If not
2208 specified it defaults to 0.0.0.0.
2209 port for a listening socket specifies the local port to be
2211 bound. For a connecting socket specifies the port on the remote
2212 host to connect to. port can be given as either a port number
2213 or a service name. port is required.
2214 to is only relevant to listening sockets. If it is specified,
2216 and port cannot be bound, QEMU will attempt to bind to
2217 subsequent ports up to and including to until it succeeds. to
2218 must be specified as a port number.
2219 ipv4 and ipv6 specify that either IPv4 or IPv6 must be used.
2221 If neither is specified the socket may use either protocol.
2222 nodelay disables the Nagle algorithm.
2224 unix options: path=path
2226 path specifies the local path of the unix socket. path is
2227 required.
2228 -chardev
2230 udp,id=id[,host=host],port=port[,localaddr=localaddr][,localport=localport][,ipv4][,ipv6]
2231 Sends all traffic from the guest to a remote host over UDP.
2232 host specifies the remote host to connect to. If not specified it
2234 defaults to "localhost".
2235 port specifies the port on the remote host to connect to. port is
2237 required.
2238 localaddr specifies the local address to bind to. If not specified
2240 it defaults to 0.0.0.0.
2241 localport specifies the local port to bind to. If not specified any
2243 available local port will be used.
2244 ipv4 and ipv6 specify that either IPv4 or IPv6 must be used. If
2246 neither is specified the device may use either protocol.
2247 -chardev msmouse,id=id
2249 Forward QEMU's emulated msmouse events to the guest. msmouse does
2250 not take any options.
2251 -chardev
2253 vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]
2254 Connect to a QEMU text console. vc may optionally be given a
2255 specific size.
2256 width and height specify the width and height respectively of the
2258 console, in pixels.
2259 cols and rows specify that the console be sized to fit a text
2261 console with the given dimensions.
2262 -chardev ringbuf,id=id[,size=size]
2264 Create a ring buffer with fixed size size. size must be a power of
2265 two and defaults to "64K".
2266 -chardev file,id=id,path=path
2268 Log all traffic received from the guest to a file.
2269 path specifies the path of the file to be opened. This file will be
2271 created if it does not already exist, and overwritten if it does.
2272 path is required.
2273 -chardev pipe,id=id,path=path
2275 Create a two-way connection to the guest. The behaviour differs
2276 slightly between Windows hosts and other hosts:
2277 On Windows, a single duplex pipe will be created at \\.pipe\path.
2279 On other hosts, 2 pipes will be created called path.in and
2281 path.out. Data written to path.in will be received by the guest.
2282 Data written by the guest can be read from path.out. QEMU will not
2283 create these fifos, and requires them to be present.
2284 path forms part of the pipe path as described above. path is
2286 required.
2287 -chardev console,id=id
2289 Send traffic from the guest to QEMU's standard output. console does
2290 not take any options.
2291 console is only available on Windows hosts.
2293 -chardev serial,id=id,path=path
2295 Send traffic from the guest to a serial device on the host.
2296 On Unix hosts serial will actually accept any tty device, not only
2298 serial lines.
2299 path specifies the name of the serial device to open.
2301 -chardev pty,id=id
2303 Create a new pseudo-terminal on the host and connect to it. pty
2304 does not take any options.
2305 pty is not available on Windows hosts.
2307 -chardev stdio,id=id[,signal=on|off]
2309 Connect to standard input and standard output of the QEMU process.
2310 signal controls if signals are enabled on the terminal, that
2312 includes exiting QEMU with the key sequence Control-c. This option
2313 is enabled by default, use signal=off to disable it.
2314 -chardev braille,id=id
2316 Connect to a local BrlAPI server. braille does not take any
2317 options.
2318 -chardev tty,id=id,path=path
2320 tty is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
2321 DragonFlyBSD hosts. It is an alias for serial.
2322 path specifies the path to the tty. path is required.
2324 -chardev parallel,id=id,path=path
2326 -chardev parport,id=id,path=path
2327 parallel is only available on Linux, FreeBSD and DragonFlyBSD
2328 hosts.
2329 Connect to a local parallel port.
2331 path specifies the path to the parallel port device. path is
2333 required.
2334 -chardev spicevmc,id=id,debug=debug,name=name
2336 spicevmc is only available when spice support is built in.
2337 debug debug level for spicevmc
2339 name name of spice channel to connect to
2341 Connect to a spice virtual machine channel, such as vdiport.
2343 -chardev spiceport,id=id,debug=debug,name=name
2345 spiceport is only available when spice support is built in.
2346 debug debug level for spicevmc
2348 name name of spice port to connect to
2350 Connect to a spice port, allowing a Spice client to handle the
2352 traffic identified by a name (preferably a fqdn).
2353 Bluetooth(R) options
2355 -bt hci[...]
2357 Defines the function of the corresponding Bluetooth HCI. -bt
2358 options are matched with the HCIs present in the chosen machine
2359 type. For example when emulating a machine with only one HCI built
2360 into it, only the first "-bt hci[...]" option is valid and defines
2361 the HCI's logic. The Transport Layer is decided by the machine
2362 type. Currently the machines "n800" and "n810" have one HCI and
2363 all other machines have none.
2364 Note: This option and the whole bluetooth subsystem is considered
2366 as deprecated. If you still use it, please send a mail to
2367 <qemu-devel@nongnu.org> where you describe your usecase.
2368 The following three types are recognized:
2370 -bt hci,null
2372 (default) The corresponding Bluetooth HCI assumes no internal
2373 logic and will not respond to any HCI commands or emit events.
2374 -bt hci,host[:id]
2376 ("bluez" only) The corresponding HCI passes commands / events
2377 to / from the physical HCI identified by the name id (default:
2378 "hci0") on the computer running QEMU. Only available on
2379 "bluez" capable systems like Linux.
2380 -bt hci[,vlan=n]
2382 Add a virtual, standard HCI that will participate in the
2383 Bluetooth scatternet n (default 0). Similarly to -net VLANs,
2384 devices inside a bluetooth network n can only communicate with
2385 other devices in the same network (scatternet).
2386 -bt vhci[,vlan=n]
2388 (Linux-host only) Create a HCI in scatternet n (default 0) attached
2389 to the host bluetooth stack instead of to the emulated target.
2390 This allows the host and target machines to participate in a common
2391 scatternet and communicate. Requires the Linux "vhci" driver
2392 installed. Can be used as following:
2393 qemu-system-i386 [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
2395 -bt device:dev[,vlan=n]
2397 Emulate a bluetooth device dev and place it in network n (default
2398 0). QEMU can only emulate one type of bluetooth devices currently:
2399 keyboard
2401 Virtual wireless keyboard implementing the HIDP bluetooth
2402 profile.
2403 TPM device options
2405 The general form of a TPM device option is:
2407 -tpmdev backend,id=id[,options]
2409 The specific backend type will determine the applicable options.
2410 The "-tpmdev" option creates the TPM backend and requires a
2411 "-device" option that specifies the TPM frontend interface model.
2412 Use "-tpmdev help" to print all available TPM backend types.
2414 The available backends are:
2416 -tpmdev passthrough,id=id,path=path,cancel-path=cancel-path
2418 (Linux-host only) Enable access to the host's TPM using the
2419 passthrough driver.
2420 path specifies the path to the host's TPM device, i.e., on a Linux
2422 host this would be "/dev/tpm0". path is optional and by default
2423 "/dev/tpm0" is used.
2424 cancel-path specifies the path to the host TPM device's sysfs entry
2426 allowing for cancellation of an ongoing TPM command. cancel-path
2427 is optional and by default QEMU will search for the sysfs entry to
2428 use.
2429 Some notes about using the host's TPM with the passthrough driver:
2431 The TPM device accessed by the passthrough driver must not be used
2433 by any other application on the host.
2434 Since the host's firmware (BIOS/UEFI) has already initialized the
2436 TPM, the VM's firmware (BIOS/UEFI) will not be able to initialize
2437 the TPM again and may therefore not show a TPM-specific menu that
2438 would otherwise allow the user to configure the TPM, e.g., allow
2439 the user to enable/disable or activate/deactivate the TPM.
2440 Further, if TPM ownership is released from within a VM then the
2441 host's TPM will get disabled and deactivated. To enable and
2442 activate the TPM again afterwards, the host has to be rebooted and
2443 the user is required to enter the firmware's menu to enable and
2444 activate the TPM. If the TPM is left disabled and/or deactivated
2445 most TPM commands will fail.
2446 To create a passthrough TPM use the following two options:
2448 -tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0
2450 Note that the "-tpmdev" id is "tpm0" and is referenced by
2452 "tpmdev=tpm0" in the device option.
2453 -tpmdev emulator,id=id,chardev=dev
2455 (Linux-host only) Enable access to a TPM emulator using Unix domain
2456 socket based chardev backend.
2457 chardev specifies the unique ID of a character device backend that
2459 provides connection to the software TPM server.
2460 To create a TPM emulator backend device with chardev socket
2462 backend:
2463 -chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0
2465 Linux/Multiboot boot specific
2467 When using these options, you can use a given Linux or Multiboot kernel
2469 without installing it in the disk image. It can be useful for easier
2470 testing of various kernels.
2471 -kernel bzImage
2473 Use bzImage as kernel image. The kernel can be either a Linux
2474 kernel or in multiboot format.
2475 -append cmdline
2477 Use cmdline as kernel command line
2478 -initrd file
2480 Use file as initial ram disk.
2481 -initrd "file1 arg=foo,file2"
2483 This syntax is only available with multiboot.
2484 Use file1 and file2 as modules and pass arg=foo as parameter to the
2486 first module.
2487 -dtb file
2489 Use file as a device tree binary (dtb) image and pass it to the
2490 kernel on boot.
2491 Debug/Expert options
2493 -fw_cfg [name=]name,file=file
2495 Add named fw_cfg entry with contents from file file.
2496 -fw_cfg [name=]name,string=str
2498 Add named fw_cfg entry with contents from string str.
2499 The terminating NUL character of the contents of str will not be
2501 included as part of the fw_cfg item data. To insert contents with
2502 embedded NUL characters, you have to use the file parameter.
2503 The fw_cfg entries are passed by QEMU through to the guest.
2505 Example:
2507 -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin
2509 creates an fw_cfg entry named opt/com.mycompany/blob with contents
2511 from ./my_blob.bin.
2512 -serial dev
2514 Redirect the virtual serial port to host character device dev. The
2515 default device is "vc" in graphical mode and "stdio" in non
2516 graphical mode.
2517 This option can be used several times to simulate up to 4 serial
2519 ports.
2520 Use "-serial none" to disable all serial ports.
2522 Available character devices are:
2524 vc[:WxH]
2526 Virtual console. Optionally, a width and height can be given in
2527 pixel with
2528 vc:800x600
2530 It is also possible to specify width or height in characters:
2532 vc:80Cx24C
2534 pty [Linux only] Pseudo TTY (a new PTY is automatically allocated)
2536 none
2538 No device is allocated.
2539 null
2541 void device
2542 chardev:id
2544 Use a named character device defined with the "-chardev"
2545 option.
2546 /dev/XXX
2548 [Linux only] Use host tty, e.g. /dev/ttyS0. The host serial
2549 port parameters are set according to the emulated ones.
2550 /dev/parportN
2552 [Linux only, parallel port only] Use host parallel port N.
2553 Currently SPP and EPP parallel port features can be used.
2554 file:filename
2556 Write output to filename. No character can be read.
2557 stdio
2559 [Unix only] standard input/output
2560 pipe:filename
2562 name pipe filename
2563 COMn
2565 [Windows only] Use host serial port n
2566 udp:[remote_host]:remote_port[@[src_ip]:src_port]
2568 This implements UDP Net Console. When remote_host or src_ip
2569 are not specified they default to 0.0.0.0. When not using a
2570 specified src_port a random port is automatically chosen.
2571 If you just want a simple readonly console you can use "netcat"
2573 or "nc", by starting QEMU with: "-serial udp::4555" and nc as:
2574 "nc -u -l -p 4555". Any time QEMU writes something to that port
2575 it will appear in the netconsole session.
2576 If you plan to send characters back via netconsole or you want
2578 to stop and start QEMU a lot of times, you should have QEMU use
2579 the same source port each time by using something like "-serial
2580 udp::4555@4556" to QEMU. Another approach is to use a patched
2581 version of netcat which can listen to a TCP port and send and
2582 receive characters via udp. If you have a patched version of
2583 netcat which activates telnet remote echo and single char
2584 transfer, then you can use the following options to set up a
2585 netcat redirector to allow telnet on port 5555 to access the
2586 QEMU port.
2587 "QEMU Options:"
2589 -serial udp::4555@4556
2590 "netcat options:"
2592 -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
2593 "telnet options:"
2595 localhost 5555
2596 tcp:[host]:port[,server][,nowait][,nodelay][,reconnect=seconds]
2598 The TCP Net Console has two modes of operation. It can send
2599 the serial I/O to a location or wait for a connection from a
2600 location. By default the TCP Net Console is sent to host at
2601 the port. If you use the server option QEMU will wait for a
2602 client socket application to connect to the port before
2603 continuing, unless the "nowait" option was specified. The
2604 "nodelay" option disables the Nagle buffering algorithm. The
2605 "reconnect" option only applies if noserver is set, if the
2606 connection goes down it will attempt to reconnect at the given
2607 interval. If host is omitted, 0.0.0.0 is assumed. Only one TCP
2608 connection at a time is accepted. You can use "telnet" to
2609 connect to the corresponding character device.
2610 "Example to send tcp console to 192.168.0.2 port 4444"
2612 -serial tcp:192.168.0.2:4444
2613 "Example to listen and wait on port 4444 for connection"
2615 -serial tcp::4444,server
2616 "Example to not wait and listen on ip 192.168.0.100 port 4444"
2618 -serial tcp:192.168.0.100:4444,server,nowait
2619 telnet:host:port[,server][,nowait][,nodelay]
2621 The telnet protocol is used instead of raw tcp sockets. The
2622 options work the same as if you had specified "-serial tcp".
2623 The difference is that the port acts like a telnet server or
2624 client using telnet option negotiation. This will also allow
2625 you to send the MAGIC_SYSRQ sequence if you use a telnet that
2626 supports sending the break sequence. Typically in unix telnet
2627 you do it with Control-] and then type "send break" followed by
2628 pressing the enter key.
2629 websocket:host:port,server[,nowait][,nodelay]
2631 The WebSocket protocol is used instead of raw tcp socket. The
2632 port acts as a WebSocket server. Client mode is not supported.
2633 unix:path[,server][,nowait][,reconnect=seconds]
2635 A unix domain socket is used instead of a tcp socket. The
2636 option works the same as if you had specified "-serial tcp"
2637 except the unix domain socket path is used for connections.
2638 mon:dev_string
2640 This is a special option to allow the monitor to be multiplexed
2641 onto another serial port. The monitor is accessed with key
2642 sequence of Control-a and then pressing c. dev_string should
2643 be any one of the serial devices specified above. An example
2644 to multiplex the monitor onto a telnet server listening on port
2645 4444 would be:
2646 "-serial mon:telnet::4444,server,nowait"
2648 When the monitor is multiplexed to stdio in this way, Ctrl+C
2650 will not terminate QEMU any more but will be passed to the
2651 guest instead.
2652 braille
2654 Braille device. This will use BrlAPI to display the braille
2655 output on a real or fake device.
2656 msmouse
2658 Three button serial mouse. Configure the guest to use Microsoft
2659 protocol.
2660 -parallel dev
2662 Redirect the virtual parallel port to host device dev (same devices
2663 as the serial port). On Linux hosts, /dev/parportN can be used to
2664 use hardware devices connected on the corresponding host parallel
2665 port.
2666 This option can be used several times to simulate up to 3 parallel
2668 ports.
2669 Use "-parallel none" to disable all parallel ports.
2671 -monitor dev
2673 Redirect the monitor to host device dev (same devices as the serial
2674 port). The default device is "vc" in graphical mode and "stdio" in
2675 non graphical mode. Use "-monitor none" to disable the default
2676 monitor.
2677 -qmp dev
2679 Like -monitor but opens in 'control' mode.
2680 -qmp-pretty dev
2682 Like -qmp but uses pretty JSON formatting.
2683 -mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]
2685 Setup monitor on chardev name. "pretty" turns on JSON pretty
2686 printing easing human reading and debugging.
2687 -debugcon dev
2689 Redirect the debug console to host device dev (same devices as the
2690 serial port). The debug console is an I/O port which is typically
2691 port 0xe9; writing to that I/O port sends output to this device.
2692 The default device is "vc" in graphical mode and "stdio" in non
2693 graphical mode.
2694 -pidfile file
2696 Store the QEMU process PID in file. It is useful if you launch QEMU
2697 from a script.
2698 -singlestep
2700 Run the emulation in single step mode.
2701 --preconfig
2703 Pause QEMU for interactive configuration before the machine is
2704 created, which allows querying and configuring properties that will
2705 affect machine initialization. Use QMP command 'x-exit-preconfig'
2706 to exit the preconfig state and move to the next state (i.e. run
2707 guest if -S isn't used or pause the second time if -S is used).
2708 This option is experimental.
2709 -S Do not start CPU at startup (you must type 'c' in the monitor).
2711 -realtime mlock=on|off
2713 Run qemu with realtime features. mlocking qemu and guest memory
2714 can be enabled via mlock=on (enabled by default).
2715 -overcommit mem-lock=on|off
2717 -overcommit cpu-pm=on|off
2718 Run qemu with hints about host resource overcommit. The default is
2719 to assume that host overcommits all resources.
2720 Locking qemu and guest memory can be enabled via mem-lock=on
2722 (disabled by default). This works when host memory is not
2723 overcommitted and reduces the worst-case latency for guest. This
2724 is equivalent to realtime.
2725 Guest ability to manage power state of host cpus (increasing
2727 latency for other processes on the same host cpu, but decreasing
2728 latency for guest) can be enabled via cpu-pm=on (disabled by
2729 default). This works best when host CPU is not overcommitted. When
2730 used, host estimates of CPU cycle and power utilization will be
2731 incorrect, not taking into account guest idle time.
2732 -gdb dev
2734 Wait for gdb connection on device dev. Typical connections will
2735 likely be TCP-based, but also UDP, pseudo TTY, or even stdio are
2736 reasonable use case. The latter is allowing to start QEMU from
2737 within gdb and establish the connection via a pipe:
2738 (gdb) target remote | exec qemu-system-i386 -gdb stdio ...
2740 -s Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port
2742 1234.
2743 -d item1[,...]
2745 Enable logging of specified items. Use '-d help' for a list of log
2746 items.
2747 -D logfile
2749 Output log in logfile instead of to stderr
2750 -dfilter range1[,...]
2752 Filter debug output to that relevant to a range of target
2753 addresses. The filter spec can be either start+size, start-size or
2754 start..end where start end and size are the addresses and sizes
2755 required. For example:
2756 -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000
2758 Will dump output for any code in the 0x1000 sized block starting at
2760 0x8000 and the 0x200 sized block starting at 0xffffffc000080000 and
2761 another 0x1000 sized block starting at 0xffffffc00005f000.
2762 -seed number
2764 Force the guest to use a deterministic pseudo-random number
2765 generator, seeded with number. This does not affect crypto
2766 routines within the host.
2767 -L path
2769 Set the directory for the BIOS, VGA BIOS and keymaps.
2770 To list all the data directories, use "-L help".
2772 -bios file
2774 Set the filename for the BIOS.
2775 -enable-kvm
2777 Enable KVM full virtualization support. This option is only
2778 available if KVM support is enabled when compiling.
2779 -xen-domid id
2781 Specify xen guest domain id (XEN only).
2782 -xen-attach
2784 Attach to existing xen domain. libxl will use this when starting
2785 QEMU (XEN only). Restrict set of available xen operations to
2786 specified domain id (XEN only).
2787 -no-reboot
2789 Exit instead of rebooting.
2790 -no-shutdown
2792 Don't exit QEMU on guest shutdown, but instead only stop the
2793 emulation. This allows for instance switching to monitor to commit
2794 changes to the disk image.
2795 -loadvm file
2797 Start right away with a saved state ("loadvm" in monitor)
2798 -daemonize
2800 Daemonize the QEMU process after initialization. QEMU will not
2801 detach from standard IO until it is ready to receive connections on
2802 any of its devices. This option is a useful way for external
2803 programs to launch QEMU without having to cope with initialization
2804 race conditions.
2805 -option-rom file
2807 Load the contents of file as an option ROM. This option is useful
2808 to load things like EtherBoot.
2809 -rtc
2811 [base=utc|localtime|datetime][,clock=host|rt|vm][,driftfix=none|slew]
2812 Specify base as "utc" or "localtime" to let the RTC start at the
2813 current UTC or local time, respectively. "localtime" is required
2814 for correct date in MS-DOS or Windows. To start at a specific point
2815 in time, provide datetime in the format "2006-06-17T16:01:21" or
2816 "2006-06-17". The default base is UTC.
2817 By default the RTC is driven by the host system time. This allows
2819 using of the RTC as accurate reference clock inside the guest,
2820 specifically if the host time is smoothly following an accurate
2821 external reference clock, e.g. via NTP. If you want to isolate the
2822 guest time from the host, you can set clock to "rt" instead, which
2823 provides a host monotonic clock if host support it. To even
2824 prevent the RTC from progressing during suspension, you can set
2825 clock to "vm" (virtual clock). clock=vm is recommended especially
2826 in icount mode in order to preserve determinism; however, note that
2827 in icount mode the speed of the virtual clock is variable and can
2828 in general differ from the host clock.
2829 Enable driftfix (i386 targets only) if you experience time drift
2831 problems, specifically with Windows' ACPI HAL. This option will try
2832 to figure out how many timer interrupts were not processed by the
2833 Windows guest and will re-inject them.
2834 -icount
2836 [shift=N|auto][,rr=record|replay,rrfile=filename,rrsnapshot=snapshot]
2837 Enable virtual instruction counter. The virtual cpu will execute
2838 one instruction every 2^N ns of virtual time. If "auto" is
2839 specified then the virtual cpu speed will be automatically adjusted
2840 to keep virtual time within a few seconds of real time.
2841 When the virtual cpu is sleeping, the virtual time will advance at
2843 default speed unless sleep=on|off is specified. With sleep=on|off,
2844 the virtual time will jump to the next timer deadline instantly
2845 whenever the virtual cpu goes to sleep mode and will not advance if
2846 no timer is enabled. This behavior give deterministic execution
2847 times from the guest point of view.
2848 Note that while this option can give deterministic behavior, it
2850 does not provide cycle accurate emulation. Modern CPUs contain
2851 superscalar out of order cores with complex cache hierarchies. The
2852 number of instructions executed often has little or no correlation
2853 with actual performance.
2854 align=on will activate the delay algorithm which will try to
2856 synchronise the host clock and the virtual clock. The goal is to
2857 have a guest running at the real frequency imposed by the shift
2858 option. Whenever the guest clock is behind the host clock and if
2859 align=on is specified then we print a message to the user to inform
2860 about the delay. Currently this option does not work when shift is
2861 "auto". Note: The sync algorithm will work for those shift values
2862 for which the guest clock runs ahead of the host clock. Typically
2863 this happens when the shift value is high (how high depends on the
2864 host machine).
2865 When rr option is specified deterministic record/replay is enabled.
2867 Replay log is written into filename file in record mode and read
2868 from this file in replay mode.
2869 Option rrsnapshot is used to create new vm snapshot named snapshot
2871 at the start of execution recording. In replay mode this option is
2872 used to load the initial VM state.
2873 -watchdog model
2875 Create a virtual hardware watchdog device. Once enabled (by a
2876 guest action), the watchdog must be periodically polled by an agent
2877 inside the guest or else the guest will be restarted. Choose a
2878 model for which your guest has drivers.
2879 The model is the model of hardware watchdog to emulate. Use
2881 "-watchdog help" to list available hardware models. Only one
2882 watchdog can be enabled for a guest.
2883 The following models may be available:
2885 ib700
2887 iBASE 700 is a very simple ISA watchdog with a single timer.
2888 i6300esb
2890 Intel 6300ESB I/O controller hub is a much more featureful PCI-
2891 based dual-timer watchdog.
2892 diag288
2894 A virtual watchdog for s390x backed by the diagnose 288
2895 hypercall (currently KVM only).
2896 -watchdog-action action
2898 The action controls what QEMU will do when the watchdog timer
2899 expires. The default is "reset" (forcefully reset the guest).
2900 Other possible actions are: "shutdown" (attempt to gracefully
2901 shutdown the guest), "poweroff" (forcefully poweroff the guest),
2902 "inject-nmi" (inject a NMI into the guest), "pause" (pause the
2903 guest), "debug" (print a debug message and continue), or "none" (do
2904 nothing).
2905 Note that the "shutdown" action requires that the guest responds to
2907 ACPI signals, which it may not be able to do in the sort of
2908 situations where the watchdog would have expired, and thus
2909 "-watchdog-action shutdown" is not recommended for production use.
2910 Examples:
2912 "-watchdog i6300esb -watchdog-action pause"
2914 "-watchdog ib700"
2915 -echr numeric_ascii_value
2916 Change the escape character used for switching to the monitor when
2917 using monitor and serial sharing. The default is 0x01 when using
2918 the "-nographic" option. 0x01 is equal to pressing "Control-a".
2919 You can select a different character from the ascii control keys
2920 where 1 through 26 map to Control-a through Control-z. For
2921 instance you could use the either of the following to change the
2922 escape character to Control-t.
2923 "-echr 0x14"
2925 "-echr 20"
2926 -show-cursor
2927 Show cursor.
2928 -tb-size n
2930 Set TB size.
2931 -incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]
2933 -incoming rdma:host:port[,ipv4][,ipv6]
2934 Prepare for incoming migration, listen on a given tcp port.
2935 -incoming unix:socketpath
2937 Prepare for incoming migration, listen on a given unix socket.
2938 -incoming fd:fd
2940 Accept incoming migration from a given filedescriptor.
2941 -incoming exec:cmdline
2943 Accept incoming migration as an output from specified external
2944 command.
2945 -incoming defer
2947 Wait for the URI to be specified via migrate_incoming. The monitor
2948 can be used to change settings (such as migration parameters) prior
2949 to issuing the migrate_incoming to allow the migration to begin.
2950 -only-migratable
2952 Only allow migratable devices. Devices will not be allowed to enter
2953 an unmigratable state.
2954 -nodefaults
2956 Don't create default devices. Normally, QEMU sets the default
2957 devices like serial port, parallel port, virtual console, monitor
2958 device, VGA adapter, floppy and CD-ROM drive and others. The
2959 "-nodefaults" option will disable all those default devices.
2960 -chroot dir
2962 Immediately before starting guest execution, chroot to the
2963 specified directory. Especially useful in combination with -runas.
2964 -runas user
2966 Immediately before starting guest execution, drop root privileges,
2967 switching to the specified user.
2968 -prom-env variable=value
2970 Set OpenBIOS nvram variable to given value (PPC, SPARC only).
2971 -semihosting
2973 Enable semihosting mode (ARM, M68K, Xtensa, MIPS, Nios II only).
2974 -semihosting-config
2976 [enable=on|off][,target=native|gdb|auto][,chardev=id][,arg=str[,...]]
2977 Enable and configure semihosting (ARM, M68K, Xtensa, MIPS, Nios II
2978 only).
2979 target="native|gdb|auto"
2981 Defines where the semihosting calls will be addressed, to QEMU
2982 ("native") or to GDB ("gdb"). The default is "auto", which
2983 means "gdb" during debug sessions and "native" otherwise.
2984 chardev=str1
2986 Send the output to a chardev backend output for native or auto
2987 output when not in gdb
2988 arg=str1,arg=str2,...
2990 Allows the user to pass input arguments, and can be used
2991 multiple times to build up a list. The old-style
2992 "-kernel"/"-append" method of passing a command line is still
2993 supported for backward compatibility. If both the
2994 "--semihosting-config arg" and the "-kernel"/"-append" are
2995 specified, the former is passed to semihosting as it always
2996 takes precedence.
2997 -old-param
2999 Old param mode (ARM only).
3000 -sandbox
3002 arg[,obsolete=string][,elevateprivileges=string][,spawn=string][,resourcecontrol=string]
3003 Enable Seccomp mode 2 system call filter. 'on' will enable syscall
3004 filtering and 'off' will disable it. The default is 'off'.
3005 obsolete=string
3007 Enable Obsolete system calls
3008 elevateprivileges=string
3010 Disable set*uid|gid system calls
3011 spawn=string
3013 Disable *fork and execve
3014 resourcecontrol=string
3016 Disable process affinity and schedular priority
3017 -readconfig file
3019 Read device configuration from file. This approach is useful when
3020 you want to spawn QEMU process with many command line options but
3021 you don't want to exceed the command line character limit.
3022 -writeconfig file
3024 Write device configuration to file. The file can be either filename
3025 to save command line and device configuration into file or dash
3026 "-") character to print the output to stdout. This can be later
3027 used as input file for "-readconfig" option.
3028 -no-user-config
3030 The "-no-user-config" option makes QEMU not load any of the user-
3031 provided config files on sysconfdir.
3032 -trace [[enable=]pattern][,events=file][,file=file]
3034 Specify tracing options.
3035 [enable=]pattern
3037 Immediately enable events matching pattern (either event name
3038 or a globbing pattern). This option is only available if QEMU
3039 has been compiled with the simple, log or ftrace tracing
3040 backend. To specify multiple events or patterns, specify the
3041 -trace option multiple times.
3042 Use "-trace help" to print a list of names of trace points.
3044 events=file
3046 Immediately enable events listed in file. The file must
3047 contain one event name (as listed in the trace-events-all file)
3048 per line; globbing patterns are accepted too. This option is
3049 only available if QEMU has been compiled with the simple, log
3050 or ftrace tracing backend.
3051 file=file
3053 Log output traces to file. This option is only available if
3054 QEMU has been compiled with the simple tracing backend.
3055 -enable-fips
3057 Enable FIPS 140-2 compliance mode.
3058 -msg timestamp[=on|off]
3060 prepend a timestamp to each log message.(default:on)
3061 -dump-vmstate file
3063 Dump json-encoded vmstate information for current machine type to
3064 file in file
3065 -enable-sync-profile
3067 Enable synchronization profiling.
3068 Generic object creation
3070 -object typename[,prop1=value1,...]
3072 Create a new object of type typename setting properties in the
3073 order they are specified. Note that the 'id' property must be set.
3074 These objects are placed in the '/objects' path.
3075 -object
3077 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-
3078 nodes,policy=default|preferred|bind|interleave,align=align
3079 Creates a memory file backend object, which can be used to back
3080 the guest RAM with huge pages.
3081 The id parameter is a unique ID that will be used to reference
3083 this memory region when configuring the -numa argument.
3084 The size option provides the size of the memory region, and
3086 accepts common suffixes, eg 500M.
3087 The mem-path provides the path to either a shared memory or
3089 huge page filesystem mount.
3090 The share boolean option determines whether the memory region
3092 is marked as private to QEMU, or shared. The latter allows a
3093 co-operating external process to access the QEMU memory region.
3094 The share is also required for pvrdma devices due to
3096 limitations in the RDMA API provided by Linux.
3097 Setting share=on might affect the ability to configure NUMA
3099 bindings for the memory backend under some circumstances, see
3100 Documentation/vm/numa_memory_policy.txt on the Linux kernel
3101 source tree for additional details.
3102 Setting the discard-data boolean option to on indicates that
3104 file contents can be destroyed when QEMU exits, to avoid
3105 unnecessarily flushing data to the backing file. Note that
3106 discard-data is only an optimization, and QEMU might not
3107 discard file contents if it aborts unexpectedly or is
3108 terminated using SIGKILL.
3109 The merge boolean option enables memory merge, also known as
3111 MADV_MERGEABLE, so that Kernel Samepage Merging will consider
3112 the pages for memory deduplication.
3113 Setting the dump boolean option to off excludes the memory from
3115 core dumps. This feature is also known as MADV_DONTDUMP.
3116 The prealloc boolean option enables memory preallocation.
3118 The host-nodes option binds the memory range to a list of NUMA
3120 host nodes.
3121 The policy option sets the NUMA policy to one of the following
3123 values:
3124 default
3126 default host policy
3127 preferred
3129 prefer the given host node list for allocation
3130 bind
3132 restrict memory allocation to the given host node list
3133 interleave
3135 interleave memory allocations across the given host node
3136 list
3137 The align option specifies the base address alignment when QEMU
3139 mmap(2) mem-path, and accepts common suffixes, eg 2M. Some
3140 backend store specified by mem-path requires an alignment
3141 different than the default one used by QEMU, eg the device DAX
3142 /dev/dax0.0 requires 2M alignment rather than 4K. In such
3143 cases, users can specify the required alignment via this
3144 option.
3145 The pmem option specifies whether the backing file specified by
3147 mem-path is in host persistent memory that can be accessed
3148 using the SNIA NVM programming model (e.g. Intel NVDIMM). If
3149 pmem is set to 'on', QEMU will take necessary operations to
3150 guarantee the persistence of its own writes to mem-path (e.g.
3151 in vNVDIMM label emulation and live migration). Also, we will
3152 map the backend-file with MAP_SYNC flag, which ensures the file
3153 metadata is in sync for mem-path in case of host crash or a
3154 power failure. MAP_SYNC requires support from both the host
3155 kernel (since Linux kernel 4.15) and the filesystem of mem-path
3156 mounted with DAX option.
3157 -object
3159 memory-backend-ram,id=id,merge=on|off,dump=on|off,share=on|off,prealloc=on|off,size=size,host-nodes=host-
3160 nodes,policy=default|preferred|bind|interleave
3161 Creates a memory backend object, which can be used to back the
3162 guest RAM. Memory backend objects offer more control than the
3163 -m option that is traditionally used to define guest RAM.
3164 Please refer to memory-backend-file for a description of the
3165 options.
3166 -object
3168 memory-backend-memfd,id=id,merge=on|off,dump=on|off,share=on|off,prealloc=on|off,size=size,host-nodes=host-
3169 nodes,policy=default|preferred|bind|interleave,seal=on|off,hugetlb=on|off,hugetlbsize=size
3170 Creates an anonymous memory file backend object, which allows
3171 QEMU to share the memory with an external process (e.g. when
3172 using vhost-user). The memory is allocated with memfd and
3173 optional sealing. (Linux only)
3174 The seal option creates a sealed-file, that will block further
3176 resizing the memory ('on' by default).
3177 The hugetlb option specify the file to be created resides in
3179 the hugetlbfs filesystem (since Linux 4.14). Used in
3180 conjunction with the hugetlb option, the hugetlbsize option
3181 specify the hugetlb page size on systems that support multiple
3182 hugetlb page sizes (it must be a power of 2 value supported by
3183 the system).
3184 In some versions of Linux, the hugetlb option is incompatible
3186 with the seal option (requires at least Linux 4.16).
3187 Please refer to memory-backend-file for a description of the
3189 other options.
3190 The share boolean option is on by default with memfd.
3192 -object rng-random,id=id,filename=/dev/random
3194 Creates a random number generator backend which obtains entropy
3195 from a device on the host. The id parameter is a unique ID that
3196 will be used to reference this entropy backend from the virtio-
3197 rng device. The filename parameter specifies which file to
3198 obtain entropy from and if omitted defaults to /dev/urandom.
3199 -object rng-egd,id=id,chardev=chardevid
3201 Creates a random number generator backend which obtains entropy
3202 from an external daemon running on the host. The id parameter
3203 is a unique ID that will be used to reference this entropy
3204 backend from the virtio-rng device. The chardev parameter is
3205 the unique ID of a character device backend that provides the
3206 connection to the RNG daemon.
3207 -object
3209 tls-creds-anon,id=id,endpoint=endpoint,dir=/path/to/cred/dir,verify-peer=on|off
3210 Creates a TLS anonymous credentials object, which can be used
3211 to provide TLS support on network backends. The id parameter is
3212 a unique ID which network backends will use to access the
3213 credentials. The endpoint is either server or client depending
3214 on whether the QEMU network backend that uses the credentials
3215 will be acting as a client or as a server. If verify-peer is
3216 enabled (the default) then once the handshake is completed, the
3217 peer credentials will be verified, though this is a no-op for
3218 anonymous credentials.
3219 The dir parameter tells QEMU where to find the credential
3221 files. For server endpoints, this directory may contain a file
3222 dh-params.pem providing diffie-hellman parameters to use for
3223 the TLS server. If the file is missing, QEMU will generate a
3224 set of DH parameters at startup. This is a computationally
3225 expensive operation that consumes random pool entropy, so it is
3226 recommended that a persistent set of parameters be generated
3227 upfront and saved.
3228 -object
3230 tls-creds-psk,id=id,endpoint=endpoint,dir=/path/to/keys/dir[,username=username]
3231 Creates a TLS Pre-Shared Keys (PSK) credentials object, which
3232 can be used to provide TLS support on network backends. The id
3233 parameter is a unique ID which network backends will use to
3234 access the credentials. The endpoint is either server or client
3235 depending on whether the QEMU network backend that uses the
3236 credentials will be acting as a client or as a server. For
3237 clients only, username is the username which will be sent to
3238 the server. If omitted it defaults to "qemu".
3239 The dir parameter tells QEMU where to find the keys file. It
3241 is called "dir/keys.psk" and contains "username:key" pairs.
3242 This file can most easily be created using the GnuTLS "psktool"
3243 program.
3244 For server endpoints, dir may also contain a file dh-params.pem
3246 providing diffie-hellman parameters to use for the TLS server.
3247 If the file is missing, QEMU will generate a set of DH
3248 parameters at startup. This is a computationally expensive
3249 operation that consumes random pool entropy, so it is
3250 recommended that a persistent set of parameters be generated up
3251 front and saved.
3252 -object
3254 tls-creds-x509,id=id,endpoint=endpoint,dir=/path/to/cred/dir,priority=priority,verify-peer=on|off,passwordid=id
3255 Creates a TLS anonymous credentials object, which can be used
3256 to provide TLS support on network backends. The id parameter is
3257 a unique ID which network backends will use to access the
3258 credentials. The endpoint is either server or client depending
3259 on whether the QEMU network backend that uses the credentials
3260 will be acting as a client or as a server. If verify-peer is
3261 enabled (the default) then once the handshake is completed, the
3262 peer credentials will be verified. With x509 certificates, this
3263 implies that the clients must be provided with valid client
3264 certificates too.
3265 The dir parameter tells QEMU where to find the credential
3267 files. For server endpoints, this directory may contain a file
3268 dh-params.pem providing diffie-hellman parameters to use for
3269 the TLS server. If the file is missing, QEMU will generate a
3270 set of DH parameters at startup. This is a computationally
3271 expensive operation that consumes random pool entropy, so it is
3272 recommended that a persistent set of parameters be generated
3273 upfront and saved.
3274 For x509 certificate credentials the directory will contain
3276 further files providing the x509 certificates. The certificates
3277 must be stored in PEM format, in filenames ca-cert.pem,
3278 ca-crl.pem (optional), server-cert.pem (only servers),
3279 server-key.pem (only servers), client-cert.pem (only clients),
3280 and client-key.pem (only clients).
3281 For the server-key.pem and client-key.pem files which contain
3283 sensitive private keys, it is possible to use an encrypted
3284 version by providing the passwordid parameter. This provides
3285 the ID of a previously created "secret" object containing the
3286 password for decryption.
3287 The priority parameter allows to override the global default
3289 priority used by gnutls. This can be useful if the system
3290 administrator needs to use a weaker set of crypto priorities
3291 for QEMU without potentially forcing the weakness onto all
3292 applications. Or conversely if one wants wants a stronger
3293 default for QEMU than for all other applications, they can do
3294 this through this parameter. Its format is a gnutls priority
3295 string as described at
3296 <https://gnutls.org/manual/html_node/Priority-Strings.html>.
3297 -object
3299 filter-buffer,id=id,netdev=netdevid,interval=t[,queue=all|rx|tx][,status=on|off]
3300 Interval t can't be 0, this filter batches the packet delivery:
3301 all packets arriving in a given interval on netdev netdevid are
3302 delayed until the end of the interval. Interval is in
3303 microseconds. status is optional that indicate whether the
3304 netfilter is on (enabled) or off (disabled), the default status
3305 for netfilter will be 'on'.
3306 queue all|rx|tx is an option that can be applied to any
3308 netfilter.
3309 all: the filter is attached both to the receive and the
3311 transmit queue of the netdev (default).
3312 rx: the filter is attached to the receive queue of the netdev,
3314 where it will receive packets sent to the netdev.
3315 tx: the filter is attached to the transmit queue of the netdev,
3317 where it will receive packets sent by the netdev.
3318 -object
3320 filter-mirror,id=id,netdev=netdevid,outdev=chardevid,queue=all|rx|tx[,vnet_hdr_support]
3321 filter-mirror on netdev netdevid,mirror net packet to
3322 chardevchardevid, if it has the vnet_hdr_support flag, filter-
3323 mirror will mirror packet with vnet_hdr_len.
3324 -object
3326 filter-redirector,id=id,netdev=netdevid,indev=chardevid,outdev=chardevid,queue=all|rx|tx[,vnet_hdr_support]
3327 filter-redirector on netdev netdevid,redirect filter's net
3328 packet to chardev chardevid,and redirect indev's packet to
3329 filter.if it has the vnet_hdr_support flag, filter-redirector
3330 will redirect packet with vnet_hdr_len. Create a filter-
3331 redirector we need to differ outdev id from indev id, id can
3332 not be the same. we can just use indev or outdev, but at least
3333 one of indev or outdev need to be specified.
3334 -object
3336 filter-rewriter,id=id,netdev=netdevid,queue=all|rx|tx,[vnet_hdr_support]
3337 Filter-rewriter is a part of COLO project.It will rewrite tcp
3338 packet to secondary from primary to keep secondary tcp
3339 connection,and rewrite tcp packet to primary from secondary
3340 make tcp packet can be handled by client.if it has the
3341 vnet_hdr_support flag, we can parse packet with vnet header.
3342 usage: colo secondary: -object
3344 filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 -object
3345 filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 -object
3346 filter-rewriter,id=rew0,netdev=hn0,queue=all
3347 -object filter-dump,id=id,netdev=dev[,file=filename][,maxlen=len]
3349 Dump the network traffic on netdev dev to the file specified by
3350 filename. At most len bytes (64k by default) per packet are
3351 stored. The file format is libpcap, so it can be analyzed with
3352 tools such as tcpdump or Wireshark.
3353 -object
3355 colo-compare,id=id,primary_in=chardevid,secondary_in=chardevid,outdev=chardevid,iothread=id[,vnet_hdr_support][,notify_dev=id]
3356 Colo-compare gets packet from primary_inchardevid and
3357 secondary_inchardevid, than compare primary packet with
3358 secondary packet. If the packets are same, we will output
3359 primary packet to outdevchardevid, else we will notify colo-
3360 frame do checkpoint and send primary packet to outdevchardevid.
3361 In order to improve efficiency, we need to put the task of
3362 comparison in another thread. If it has the vnet_hdr_support
3363 flag, colo compare will send/recv packet with vnet_hdr_len. If
3364 you want to use Xen COLO, will need the notify_dev to notify
3365 Xen colo-frame to do checkpoint.
3366 we must use it with the help of filter-mirror and filter-
3368 redirector.
3369 KVM COLO
3371 primary:
3373 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
3374 -device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
3375 -chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait
3376 -chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait
3377 -chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait
3378 -chardev socket,id=compare0-0,host=3.3.3.3,port=9001
3379 -chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait
3380 -chardev socket,id=compare_out0,host=3.3.3.3,port=9005
3381 -object iothread,id=iothread1
3382 -object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
3383 -object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
3384 -object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
3385 -object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,iothread=iothread1
3386 secondary:
3388 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
3389 -device e1000,netdev=hn0,mac=52:a4:00:12:78:66
3390 -chardev socket,id=red0,host=3.3.3.3,port=9003
3391 -chardev socket,id=red1,host=3.3.3.3,port=9004
3392 -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
3393 -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
3394 Xen COLO
3397 primary:
3399 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown
3400 -device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66
3401 -chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait
3402 -chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait
3403 -chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait
3404 -chardev socket,id=compare0-0,host=3.3.3.3,port=9001
3405 -chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait
3406 -chardev socket,id=compare_out0,host=3.3.3.3,port=9005
3407 -chardev socket,id=notify_way,host=3.3.3.3,port=9009,server,nowait
3408 -object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0
3409 -object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out
3410 -object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0
3411 -object iothread,id=iothread1
3412 -object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,notify_dev=nofity_way,iothread=iothread1
3413 secondary:
3415 -netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown
3416 -device e1000,netdev=hn0,mac=52:a4:00:12:78:66
3417 -chardev socket,id=red0,host=3.3.3.3,port=9003
3418 -chardev socket,id=red1,host=3.3.3.3,port=9004
3419 -object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0
3420 -object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1
3421 If you want to know the detail of above command line, you can
3423 read the colo-compare git log.
3424 -object cryptodev-backend-builtin,id=id[,queues=queues]
3426 Creates a cryptodev backend which executes crypto opreation
3427 from the QEMU cipher APIS. The id parameter is a unique ID that
3428 will be used to reference this cryptodev backend from the
3429 virtio-crypto device. The queues parameter is optional, which
3430 specify the queue number of cryptodev backend, the default of
3431 queues is 1.
3432 # qemu-system-x86_64 \
3434 [...] \
3435 -object cryptodev-backend-builtin,id=cryptodev0 \
3436 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
3437 [...]
3438 -object
3440 cryptodev-vhost-user,id=id,chardev=chardevid[,queues=queues]
3441 Creates a vhost-user cryptodev backend, backed by a chardev
3442 chardevid. The id parameter is a unique ID that will be used
3443 to reference this cryptodev backend from the virtio-crypto
3444 device. The chardev should be a unix domain socket backed one.
3445 The vhost-user uses a specifically defined protocol to pass
3446 vhost ioctl replacement messages to an application on the other
3447 end of the socket. The queues parameter is optional, which
3448 specify the queue number of cryptodev backend for multiqueue
3449 vhost-user, the default of queues is 1.
3450 # qemu-system-x86_64 \
3452 [...] \
3453 -chardev socket,id=chardev0,path=/path/to/socket \
3454 -object cryptodev-vhost-user,id=cryptodev0,chardev=chardev0 \
3455 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \
3456 [...]
3457 -object
3459 secret,id=id,data=string,format=raw|base64[,keyid=secretid,iv=string]
3460 -object
3461 secret,id=id,file=filename,format=raw|base64[,keyid=secretid,iv=string]
3462 Defines a secret to store a password, encryption key, or some
3463 other sensitive data. The sensitive data can either be passed
3464 directly via the data parameter, or indirectly via the file
3465 parameter. Using the data parameter is insecure unless the
3466 sensitive data is encrypted.
3467 The sensitive data can be provided in raw format (the default),
3469 or base64. When encoded as JSON, the raw format only supports
3470 valid UTF-8 characters, so base64 is recommended for sending
3471 binary data. QEMU will convert from which ever format is
3472 provided to the format it needs internally. eg, an RBD password
3473 can be provided in raw format, even though it will be base64
3474 encoded when passed onto the RBD sever.
3475 For added protection, it is possible to encrypt the data
3477 associated with a secret using the AES-256-CBC cipher. Use of
3478 encryption is indicated by providing the keyid and iv
3479 parameters. The keyid parameter provides the ID of a previously
3480 defined secret that contains the AES-256 decryption key. This
3481 key should be 32-bytes long and be base64 encoded. The iv
3482 parameter provides the random initialization vector used for
3483 encryption of this particular secret and should be a base64
3484 encrypted string of the 16-byte IV.
3485 The simplest (insecure) usage is to provide the secret inline
3487 # $QEMU -object secret,id=sec0,data=letmein,format=raw
3489 The simplest secure usage is to provide the secret via a file
3491 # printf "letmein" > mypasswd.txt # $QEMU -object
3493 secret,id=sec0,file=mypasswd.txt,format=raw
3494 For greater security, AES-256-CBC should be used. To illustrate
3496 usage, consider the openssl command line tool which can encrypt
3497 the data. Note that when encrypting, the plaintext must be
3498 padded to the cipher block size (32 bytes) using the standard
3499 PKCS#5/6 compatible padding algorithm.
3500 First a master key needs to be created in base64 encoding:
3502 # openssl rand -base64 32 > key.b64
3504 # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"')
3505 Each secret to be encrypted needs to have a random
3507 initialization vector generated. These do not need to be kept
3508 secret
3509 # openssl rand -base64 16 > iv.b64
3511 # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"')
3512 The secret to be defined can now be encrypted, in this case
3514 we're telling openssl to base64 encode the result, but it could
3515 be left as raw bytes if desired.
3516 # SECRET=$(printf "letmein" |
3518 openssl enc -aes-256-cbc -a -K $KEY -iv $IV)
3519 When launching QEMU, create a master secret pointing to
3521 "key.b64" and specify that to be used to decrypt the user
3522 password. Pass the contents of "iv.b64" to the second secret
3523 # $QEMU \
3525 -object secret,id=secmaster0,format=base64,file=key.b64 \
3526 -object secret,id=sec0,keyid=secmaster0,format=base64,\
3527 data=$SECRET,iv=$(<iv.b64)
3528 -object
3530 sev-guest,id=id,cbitpos=cbitpos,reduced-phys-bits=val,[sev-device=string,policy=policy,handle=handle,dh-cert-file=file,session-file=file]
3531 Create a Secure Encrypted Virtualization (SEV) guest object,
3532 which can be used to provide the guest memory encryption
3533 support on AMD processors.
3534 When memory encryption is enabled, one of the physical address
3536 bit (aka the C-bit) is utilized to mark if a memory page is
3537 protected. The cbitpos is used to provide the C-bit position.
3538 The C-bit position is Host family dependent hence user must
3539 provide this value. On EPYC, the value should be 47.
3540 When memory encryption is enabled, we loose certain bits in
3542 physical address space. The reduced-phys-bits is used to
3543 provide the number of bits we loose in physical address space.
3544 Similar to C-bit, the value is Host family dependent. On EPYC,
3545 the value should be 5.
3546 The sev-device provides the device file to use for
3548 communicating with the SEV firmware running inside AMD Secure
3549 Processor. The default device is '/dev/sev'. If hardware
3550 supports memory encryption then /dev/sev devices are created by
3551 CCP driver.
3552 The policy provides the guest policy to be enforced by the SEV
3554 firmware and restrict what configuration and operational
3555 commands can be performed on this guest by the hypervisor. The
3556 policy should be provided by the guest owner and is bound to
3557 the guest and cannot be changed throughout the lifetime of the
3558 guest. The default is 0.
3559 If guest policy allows sharing the key with another SEV guest
3561 then handle can be use to provide handle of the guest from
3562 which to share the key.
3563 The dh-cert-file and session-file provides the guest owner's
3565 Public Diffie-Hillman key defined in SEV spec. The PDH and
3566 session parameters are used for establishing a cryptographic
3567 session with the guest owner to negotiate keys used for
3568 attestation. The file must be encoded in base64.
3569 e.g to launch a SEV guest
3571 # $QEMU \
3573 ......
3574 -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=5 \
3575 -machine ...,memory-encryption=sev0
3576 .....
3577 -object authz-simple,id=id,identity=string
3579 Create an authorization object that will control access to
3580 network services.
3581 The identity parameter is identifies the user and its format
3583 depends on the network service that authorization object is
3584 associated with. For authorizing based on TLS x509
3585 certificates, the identity must be the x509 distinguished name.
3586 Note that care must be taken to escape any commas in the
3587 distinguished name.
3588 An example authorization object to validate a x509
3590 distinguished name would look like:
3591 # $QEMU \
3593 ...
3594 -object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,O=Example Org,,L=London,,ST=London,,C=GB' \
3595 ...
3596 Note the use of quotes due to the x509 distinguished name
3598 containing whitespace, and escaping of ','.
3599 -object authz-listfile,id=id,filename=path,refresh=yes|no
3601 Create an authorization object that will control access to
3602 network services.
3603 The filename parameter is the fully qualified path to a file
3605 containing the access control list rules in JSON format.
3606 An example set of rules that match against SASL usernames might
3608 look like:
3609 {
3611 "rules": [
3612 { "match": "fred", "policy": "allow", "format": "exact" },
3613 { "match": "bob", "policy": "allow", "format": "exact" },
3614 { "match": "danb", "policy": "deny", "format": "glob" },
3615 { "match": "dan*", "policy": "allow", "format": "exact" },
3616 ],
3617 "policy": "deny"
3618 }
3619 When checking access the object will iterate over all the rules
3621 and the first rule to match will have its policy value returned
3622 as the result. If no rules match, then the default policy value
3623 is returned.
3624 The rules can either be an exact string match, or they can use
3626 the simple UNIX glob pattern matching to allow wildcards to be
3627 used.
3628 If refresh is set to true the file will be monitored and
3630 automatically reloaded whenever its content changes.
3631 As with the "authz-simple" object, the format of the identity
3633 strings being matched depends on the network service, but is
3634 usually a TLS x509 distinguished name, or a SASL username.
3635 An example authorization object to validate a SASL username
3637 would look like:
3638 # $QEMU \
3640 ...
3641 -object authz-simple,id=auth0,filename=/etc/qemu/vnc-sasl.acl,refresh=yes
3642 ...
3643 -object authz-pam,id=id,service=string
3645 Create an authorization object that will control access to
3646 network services.
3647 The service parameter provides the name of a PAM service to use
3649 for authorization. It requires that a file "/etc/pam.d/service"
3650 exist to provide the configuration for the "account" subsystem.
3651 An example authorization object to validate a TLS x509
3653 distinguished name would look like:
3654 # $QEMU \
3656 ...
3657 -object authz-pam,id=auth0,service=qemu-vnc
3658 ...
3659 There would then be a corresponding config file for PAM at
3661 "/etc/pam.d/qemu-vnc" that contains:
3662 account requisite pam_listfile.so item=user sense=allow \
3664 file=/etc/qemu/vnc.allow
3665 Finally the "/etc/qemu/vnc.allow" file would contain the list
3667 of x509 distingished names that are permitted access
3668 CN=laptop.example.com,O=Example Home,L=London,ST=London,C=GB
3670 During the graphical emulation, you can use special key combinations to
3672 change modes. The default key mappings are shown below, but if you use
3673 "-alt-grab" then the modifier is Ctrl-Alt-Shift (instead of Ctrl-Alt)
3674 and if you use "-ctrl-grab" then the modifier is the right Ctrl key
3675 (instead of Ctrl-Alt):
3676 Ctrl-Alt-f
3678 Toggle full screen
3679 Ctrl-Alt-+
3681 Enlarge the screen
3682 Ctrl-Alt--
3684 Shrink the screen
3685 Ctrl-Alt-u
3687 Restore the screen's un-scaled dimensions
3688 Ctrl-Alt-n
3690 Switch to virtual console 'n'. Standard console mappings are:
3691 1 Target system display
3693 2 Monitor
3695 3 Serial port
3697 Ctrl-Alt
3699 Toggle mouse and keyboard grab.
3700 In the virtual consoles, you can use Ctrl-Up, Ctrl-Down, Ctrl-PageUp
3702 and Ctrl-PageDown to move in the back log.
3703 During emulation, if you are using a character backend multiplexer
3705 (which is the default if you are using -nographic) then several
3706 commands are available via an escape sequence. These key sequences all
3707 start with an escape character, which is Ctrl-a by default, but can be
3708 changed with -echr. The list below assumes you're using the default.
3709 Ctrl-a h
3711 Print this help
3712 Ctrl-a x
3714 Exit emulator
3715 Ctrl-a s
3717 Save disk data back to file (if -snapshot)
3718 Ctrl-a t
3720 Toggle console timestamps
3721 Ctrl-a b
3723 Send break (magic sysrq in Linux)
3724 Ctrl-a c
3726 Rotate between the frontends connected to the multiplexer (usually
3727 this switches between the monitor and the console)
3728 Ctrl-a Ctrl-a
3730 Send the escape character to the frontend
3731 The following options are specific to the PowerPC emulation:
3733 -g WxH[xDEPTH]
3735 Set the initial VGA graphic mode. The default is 800x600x32.
3736 -prom-env string
3738 Set OpenBIOS variables in NVRAM, for example:
3739 qemu-system-ppc -prom-env 'auto-boot?=false' \
3741 -prom-env 'boot-device=hd:2,\yaboot' \
3742 -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
3743 These variables are not used by Open Hack'Ware.
3745 The following options are specific to the Sparc32 emulation:
3747 -g WxHx[xDEPTH]
3749 Set the initial graphics mode. For TCX, the default is 1024x768x8
3750 with the option of 1024x768x24. For cgthree, the default is
3751 1024x768x8 with the option of 1152x900x8 for people who wish to use
3752 OBP.
3753 -prom-env string
3755 Set OpenBIOS variables in NVRAM, for example:
3756 qemu-system-sparc -prom-env 'auto-boot?=false' \
3758 -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
3759 -M [SS-4|SS-5|SS-10|SS-20|SS-600MP|LX|Voyager|SPARCClassic]
3761 [|SPARCbook]
3762 Set the emulated machine type. Default is SS-5.
3763 The following options are specific to the Sparc64 emulation:
3765 -prom-env string
3767 Set OpenBIOS variables in NVRAM, for example:
3768 qemu-system-sparc64 -prom-env 'auto-boot?=false'
3770 -M [sun4u|sun4v|niagara]
3772 Set the emulated machine type. The default is sun4u.
3773 The following options are specific to the ARM emulation:
3775 -semihosting
3777 Enable semihosting syscall emulation.
3778 On ARM this implements the "Angel" interface.
3780 Note that this allows guest direct access to the host filesystem,
3782 so should only be used with trusted guest OS.
3783 The following options are specific to the ColdFire emulation:
3785 -semihosting
3787 Enable semihosting syscall emulation.
3788 On M68K this implements the "ColdFire GDB" interface used by
3790 libgloss.
3791 Note that this allows guest direct access to the host filesystem,
3793 so should only be used with trusted guest OS.
3794 The following options are specific to the Xtensa emulation:
3796 -semihosting
3798 Enable semihosting syscall emulation.
3799 Xtensa semihosting provides basic file IO calls, such as
3801 open/read/write/seek/select. Tensilica baremetal libc for ISS and
3802 linux platform "sim" use this interface.
3803 Note that this allows guest direct access to the host filesystem,
3805 so should only be used with trusted guest OS.
3806
3808 In addition to using normal file images for the emulated storage
3809 devices, QEMU can also use networked resources such as iSCSI devices.
3810 These are specified using a special URL syntax.
3811 iSCSI
3813 iSCSI support allows QEMU to access iSCSI resources directly and
3814 use as images for the guest storage. Both disk and cdrom images are
3815 supported.
3816 Syntax for specifying iSCSI LUNs is
3818 "iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>"
3819 By default qemu will use the iSCSI initiator-name
3821 'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from
3822 the command line or a configuration file.
3823 Since version Qemu 2.4 it is possible to specify a iSCSI request
3825 timeout to detect stalled requests and force a reestablishment of
3826 the session. The timeout is specified in seconds. The default is 0
3827 which means no timeout. Libiscsi 1.15.0 or greater is required for
3828 this feature.
3829 Example (without authentication):
3831 qemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
3833 -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
3834 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
3835 Example (CHAP username/password via URL):
3837 qemu-system-i386 -drive file=iscsi://user%password@192.0.2.1/iqn.2001-04.com.example/1
3839 Example (CHAP username/password via environment variables):
3841 LIBISCSI_CHAP_USERNAME="user" \
3843 LIBISCSI_CHAP_PASSWORD="password" \
3844 qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
3845 NBD QEMU supports NBD (Network Block Devices) both using TCP protocol
3847 as well as Unix Domain Sockets.
3848 Syntax for specifying a NBD device using TCP
3850 "nbd:<server-ip>:<port>[:exportname=<export>]"
3851 Syntax for specifying a NBD device using Unix Domain Sockets
3853 "nbd:unix:<domain-socket>[:exportname=<export>]"
3854 Example for TCP
3856 qemu-system-i386 --drive file=nbd:192.0.2.1:30000
3858 Example for Unix Domain Sockets
3860 qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket
3862 SSH QEMU supports SSH (Secure Shell) access to remote disks.
3864 Examples:
3866 qemu-system-i386 -drive file=ssh://user@host/path/to/disk.img
3868 qemu-system-i386 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
3869 Currently authentication must be done using ssh-agent. Other
3871 authentication methods may be supported in future.
3872 Sheepdog
3874 Sheepdog is a distributed storage system for QEMU. QEMU supports
3875 using either local sheepdog devices or remote networked devices.
3876 Syntax for specifying a sheepdog device
3878 sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
3880 Example
3882 qemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
3884 See also <https://sheepdog.github.io/sheepdog/>.
3886 GlusterFS
3888 GlusterFS is a user space distributed file system. QEMU supports
3889 the use of GlusterFS volumes for hosting VM disk images using TCP,
3890 Unix Domain Sockets and RDMA transport protocols.
3891 Syntax for specifying a VM disk image on GlusterFS volume is
3893 URI:
3895 gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
3896 JSON:
3898 'json:{"driver":"qcow2","file":{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...",
3899 "server":[{"type":"tcp","host":"...","port":"..."},
3900 {"type":"unix","socket":"..."}]}}'
3901 Example
3903 URI:
3905 qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img,
3906 file.debug=9,file.logfile=/var/log/qemu-gluster.log
3907 JSON:
3909 qemu-system-x86_64 'json:{"driver":"qcow2",
3910 "file":{"driver":"gluster",
3911 "volume":"testvol","path":"a.img",
3912 "debug":9,"logfile":"/var/log/qemu-gluster.log",
3913 "server":[{"type":"tcp","host":"1.2.3.4","port":24007},
3914 {"type":"unix","socket":"/var/run/glusterd.socket"}]}}'
3915 qemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
3916 file.debug=9,file.logfile=/var/log/qemu-gluster.log,
3917 file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
3918 file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
3919 See also <http://www.gluster.org>.
3921 HTTP/HTTPS/FTP/FTPS
3923 QEMU supports read-only access to files accessed over http(s) and
3924 ftp(s).
3925 Syntax using a single filename:
3927 <protocol>://[<username>[:<password>]@]<host>/<path>
3929 where:
3931 protocol
3933 'http', 'https', 'ftp', or 'ftps'.
3934 username
3936 Optional username for authentication to the remote server.
3937 password
3939 Optional password for authentication to the remote server.
3940 host
3942 Address of the remote server.
3943 path
3945 Path on the remote server, including any query string.
3946 The following options are also supported:
3948 url The full URL when passing options to the driver explicitly.
3950 readahead
3952 The amount of data to read ahead with each range request to the
3953 remote server. This value may optionally have the suffix 'T',
3954 'G', 'M', 'K', 'k' or 'b'. If it does not have a suffix, it
3955 will be assumed to be in bytes. The value must be a multiple of
3956 512 bytes. It defaults to 256k.
3957 sslverify
3959 Whether to verify the remote server's certificate when
3960 connecting over SSL. It can have the value 'on' or 'off'. It
3961 defaults to 'on'.
3962 cookie
3964 Send this cookie (it can also be a list of cookies separated by
3965 ';') with each outgoing request. Only supported when using
3966 protocols such as HTTP which support cookies, otherwise
3967 ignored.
3968 timeout
3970 Set the timeout in seconds of the CURL connection. This timeout
3971 is the time that CURL waits for a response from the remote
3972 server to get the size of the image to be downloaded. If not
3973 set, the default timeout of 5 seconds is used.
3974 Note that when passing options to qemu explicitly, driver is the
3976 value of <protocol>.
3977 Example: boot from a remote Fedora 20 live ISO image
3979 qemu-system-x86_64 --drive media=cdrom,file=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
3981 qemu-system-x86_64 --drive media=cdrom,file.driver=http,file.url=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
3983 Example: boot from a remote Fedora 20 cloud image using a local
3985 overlay for writes, copy-on-read, and a readahead of 64k
3986 qemu-img create -f qcow2 -o backing_file='json:{"file.driver":"http",, "file.url":"https://dl.fedoraproject.org/pub/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
3988 qemu-system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
3990 Example: boot from an image stored on a VMware vSphere server with
3992 a self-signed certificate using a local overlay for writes, a
3993 readahead of 64k and a timeout of 10 seconds.
3994 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
3996 qemu-system-x86_64 -drive file=/tmp/test.qcow2
3998
4000 The HTML documentation of QEMU for more precise information and Linux
4001 user mode emulator invocation.
4002
4004 Fabrice Bellard
4005 2019-11-15 QEMU.1(1)