1 HXCOMM Use DEFHEADING() to define headings in both help text and texi
2 HXCOMM Text between STEXI and ETEXI are copied to texi version and
3 HXCOMM discarded from C version
4 HXCOMM DEF(option, HAS_ARG/0, opt_enum, opt_help, arch_mask) is used to
5 HXCOMM construct option structures, enums and help message for specified
7 HXCOMM HXCOMM can be used for comments, discarded from both texi and C
9 DEFHEADING(Standard options:)
14 DEF("help", 0, QEMU_OPTION_h,
15 "-h or -help display this help and exit\n", QEMU_ARCH_ALL)
22 DEF("version", 0, QEMU_OPTION_version,
23 "-version display version information and exit\n", QEMU_ARCH_ALL)
27 Display version information and exit
30 DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
31 "-machine [type=]name[,prop[=value][,...]]\n"
32 " selects emulated machine (-machine ? for list)\n"
33 " property accel=accel1[:accel2[:...]] selects accelerator\n"
34 " supported accelerators are kvm, xen, tcg (default: tcg)\n"
35 " kernel_irqchip=on|off controls accelerated irqchip support\n",
38 @item -machine [type=]@var{name}[,prop=@var{value}[,...]]
40 Select the emulated machine by @var{name}. Use @code{-machine ?} to list
41 available machines. Supported machine properties are:
43 @item accel=@var{accels1}[:@var{accels2}[:...]]
44 This is used to enable an accelerator. Depending on the target architecture,
45 kvm, xen, or tcg can be available. By default, tcg is used. If there is more
46 than one accelerator specified, the next one is used if the previous one fails
48 @item kernel_irqchip=on|off
49 Enables in-kernel irqchip support for the chosen accelerator when available.
53 HXCOMM Deprecated by -machine
54 DEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL)
56 DEF("cpu", HAS_ARG, QEMU_OPTION_cpu,
57 "-cpu cpu select CPU (-cpu ? for list)\n", QEMU_ARCH_ALL)
59 @item -cpu @var{model}
61 Select CPU model (-cpu ? for list and additional feature selection)
64 DEF("smp", HAS_ARG, QEMU_OPTION_smp,
65 "-smp n[,maxcpus=cpus][,cores=cores][,threads=threads][,sockets=sockets]\n"
66 " set the number of CPUs to 'n' [default=1]\n"
67 " maxcpus= maximum number of total cpus, including\n"
68 " offline CPUs for hotplug, etc\n"
69 " cores= number of CPU cores on one socket\n"
70 " threads= number of threads on one CPU core\n"
71 " sockets= number of discrete sockets in the system\n",
74 @item -smp @var{n}[,cores=@var{cores}][,threads=@var{threads}][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}]
76 Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255
77 CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs
79 For the PC target, the number of @var{cores} per socket, the number
80 of @var{threads} per cores and the total number of @var{sockets} can be
81 specified. Missing values will be computed. If any on the three values is
82 given, the total number of CPUs @var{n} can be omitted. @var{maxcpus}
83 specifies the maximum number of hotpluggable CPUs.
86 DEF("numa", HAS_ARG, QEMU_OPTION_numa,
87 "-numa node[,mem=size][,cpus=cpu[-cpu]][,nodeid=node]\n", QEMU_ARCH_ALL)
89 @item -numa @var{opts}
91 Simulate a multi node NUMA system. If mem and cpus are omitted, resources
95 DEF("fda", HAS_ARG, QEMU_OPTION_fda,
96 "-fda/-fdb file use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL)
97 DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL)
100 @item -fdb @var{file}
103 Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}). You can
104 use the host floppy by using @file{/dev/fd0} as filename (@pxref{host_drives}).
107 DEF("hda", HAS_ARG, QEMU_OPTION_hda,
108 "-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL)
109 DEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL)
110 DEF("hdc", HAS_ARG, QEMU_OPTION_hdc,
111 "-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL)
112 DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL)
114 @item -hda @var{file}
115 @item -hdb @var{file}
116 @item -hdc @var{file}
117 @item -hdd @var{file}
122 Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}).
125 DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom,
126 "-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n",
129 @item -cdrom @var{file}
131 Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and
132 @option{-cdrom} at the same time). You can use the host CD-ROM by
133 using @file{/dev/cdrom} as filename (@pxref{host_drives}).
136 DEF("drive", HAS_ARG, QEMU_OPTION_drive,
137 "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n"
138 " [,cyls=c,heads=h,secs=s[,trans=t]][,snapshot=on|off]\n"
139 " [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n"
140 " [,serial=s][,addr=A][,id=name][,aio=threads|native]\n"
141 " [,readonly=on|off][,copy-on-read=on|off]\n"
142 " [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]][[,iops=i]|[[,iops_rd=r][,iops_wr=w]]\n"
143 " use 'file' as a drive image\n", QEMU_ARCH_ALL)
145 @item -drive @var{option}[,@var{option}[,@var{option}[,...]]]
148 Define a new drive. Valid options are:
151 @item file=@var{file}
152 This option defines which disk image (@pxref{disk_images}) to use with
153 this drive. If the filename contains comma, you must double it
154 (for instance, "file=my,,file" to use file "my,file").
156 Special files such as iSCSI devices can be specified using protocol
157 specific URLs. See the section for "Device URL Syntax" for more information.
158 @item if=@var{interface}
159 This option defines on which type on interface the drive is connected.
160 Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio.
161 @item bus=@var{bus},unit=@var{unit}
162 These options define where is connected the drive by defining the bus number and
164 @item index=@var{index}
165 This option defines where is connected the drive by using an index in the list
166 of available connectors of a given interface type.
167 @item media=@var{media}
168 This option defines the type of the media: disk or cdrom.
169 @item cyls=@var{c},heads=@var{h},secs=@var{s}[,trans=@var{t}]
170 These options have the same definition as they have in @option{-hdachs}.
171 @item snapshot=@var{snapshot}
172 @var{snapshot} is "on" or "off" and allows to enable snapshot for given drive (see @option{-snapshot}).
173 @item cache=@var{cache}
174 @var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough" and controls how the host cache is used to access block data.
176 @var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO.
177 @item format=@var{format}
178 Specify which disk @var{format} will be used rather than detecting
179 the format. Can be used to specifiy format=raw to avoid interpreting
180 an untrusted format header.
181 @item serial=@var{serial}
182 This option specifies the serial number to assign to the device.
183 @item addr=@var{addr}
184 Specify the controller's PCI address (if=virtio only).
185 @item werror=@var{action},rerror=@var{action}
186 Specify which @var{action} to take on write and read errors. Valid actions are:
187 "ignore" (ignore the error and try to continue), "stop" (pause QEMU),
188 "report" (report the error to the guest), "enospc" (pause QEMU only if the
189 host disk is full; report the error to the guest otherwise).
190 The default setting is @option{werror=enospc} and @option{rerror=report}.
192 Open drive @option{file} as read-only. Guest write attempts will fail.
193 @item copy-on-read=@var{copy-on-read}
194 @var{copy-on-read} is "on" or "off" and enables whether to copy read backing
195 file sectors into the image file.
198 By default, writethrough caching is used for all block device. This means that
199 the host page cache will be used to read and write data but write notification
200 will be sent to the guest only when the data has been reported as written by
201 the storage subsystem.
203 Writeback caching will report data writes as completed as soon as the data is
204 present in the host page cache. This is safe as long as you trust your host.
205 If your host crashes or loses power, then the guest may experience data
208 The host page cache can be avoided entirely with @option{cache=none}. This will
209 attempt to do disk IO directly to the guests memory. QEMU may still perform
210 an internal copy of the data.
212 The host page cache can be avoided while only sending write notifications to
213 the guest when the data has been reported as written by the storage subsystem
214 using @option{cache=directsync}.
216 Some block drivers perform badly with @option{cache=writethrough}, most notably,
217 qcow2. If performance is more important than correctness,
218 @option{cache=writeback} should be used with qcow2.
220 In case you don't care about data integrity over host failures, use
221 cache=unsafe. This option tells qemu that it never needs to write any data
222 to the disk but can instead keeps things in cache. If anything goes wrong,
223 like your host losing power, the disk storage getting disconnected accidentally,
224 etc. you're image will most probably be rendered unusable. When using
225 the @option{-snapshot} option, unsafe caching is always used.
227 Copy-on-read avoids accessing the same backing file sectors repeatedly and is
228 useful when the backing file is over a slow network. By default copy-on-read
231 Instead of @option{-cdrom} you can use:
233 qemu -drive file=file,index=2,media=cdrom
236 Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can
239 qemu -drive file=file,index=0,media=disk
240 qemu -drive file=file,index=1,media=disk
241 qemu -drive file=file,index=2,media=disk
242 qemu -drive file=file,index=3,media=disk
245 You can connect a CDROM to the slave of ide0:
247 qemu -drive file=file,if=ide,index=1,media=cdrom
250 If you don't specify the "file=" argument, you define an empty drive:
252 qemu -drive if=ide,index=1,media=cdrom
255 You can connect a SCSI disk with unit ID 6 on the bus #0:
257 qemu -drive file=file,if=scsi,bus=0,unit=6
260 Instead of @option{-fda}, @option{-fdb}, you can use:
262 qemu -drive file=file,index=0,if=floppy
263 qemu -drive file=file,index=1,if=floppy
266 By default, @var{interface} is "ide" and @var{index} is automatically
269 qemu -drive file=a -drive file=b"
277 DEF("set", HAS_ARG, QEMU_OPTION_set,
278 "-set group.id.arg=value\n"
279 " set <arg> parameter for item <id> of type <group>\n"
280 " i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL)
287 DEF("global", HAS_ARG, QEMU_OPTION_global,
288 "-global driver.property=value\n"
289 " set a global default for a driver property\n",
297 DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock,
298 "-mtdblock file use 'file' as on-board Flash memory image\n",
301 @item -mtdblock @var{file}
303 Use @var{file} as on-board Flash memory image.
306 DEF("sd", HAS_ARG, QEMU_OPTION_sd,
307 "-sd file use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL)
311 Use @var{file} as SecureDigital card image.
314 DEF("pflash", HAS_ARG, QEMU_OPTION_pflash,
315 "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL)
317 @item -pflash @var{file}
319 Use @var{file} as a parallel flash image.
322 DEF("boot", HAS_ARG, QEMU_OPTION_boot,
323 "-boot [order=drives][,once=drives][,menu=on|off]\n"
324 " [,splash=sp_name][,splash-time=sp_time]\n"
325 " 'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n"
326 " 'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n"
327 " 'sp_time': the period that splash picture last if menu=on, unit is ms\n",
330 @item -boot [order=@var{drives}][,once=@var{drives}][,menu=on|off][,splash=@var{sp_name}][,splash-time=@var{sp_time}]
332 Specify boot order @var{drives} as a string of drive letters. Valid
333 drive letters depend on the target achitecture. The x86 PC uses: a, b
334 (floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot
335 from network adapter 1-4), hard disk boot is the default. To apply a
336 particular boot order only on the first startup, specify it via
339 Interactive boot menus/prompts can be enabled via @option{menu=on} as far
340 as firmware/BIOS supports them. The default is non-interactive boot.
342 A splash picture could be passed to bios, enabling user to show it as logo,
343 when option splash=@var{sp_name} is given and menu=on, If firmware/BIOS
344 supports them. Currently Seabios for X86 system support it.
345 limitation: The splash file could be a jpeg file or a BMP file in 24 BPP
346 format(true color). The resolution should be supported by the SVGA mode, so
347 the recommended is 320x240, 640x480, 800x640.
350 # try to boot from network first, then from hard disk
352 # boot from CD-ROM first, switch back to default order after reboot
354 # boot with a splash picture for 5 seconds.
355 qemu -boot menu=on,splash=/root/boot.bmp,splash-time=5000
358 Note: The legacy format '-boot @var{drives}' is still supported but its
359 use is discouraged as it may be removed from future versions.
362 DEF("snapshot", 0, QEMU_OPTION_snapshot,
363 "-snapshot write to temporary files instead of disk image files\n",
368 Write to temporary files instead of disk image files. In this case,
369 the raw disk image you use is not written back. You can however force
370 the write back by pressing @key{C-a s} (@pxref{disk_images}).
373 DEF("m", HAS_ARG, QEMU_OPTION_m,
374 "-m megs set virtual RAM size to megs MB [default="
375 stringify(DEFAULT_RAM_SIZE) "]\n", QEMU_ARCH_ALL)
379 Set virtual RAM size to @var{megs} megabytes. Default is 128 MiB. Optionally,
380 a suffix of ``M'' or ``G'' can be used to signify a value in megabytes or
381 gigabytes respectively.
384 DEF("mem-path", HAS_ARG, QEMU_OPTION_mempath,
385 "-mem-path FILE provide backing storage for guest RAM\n", QEMU_ARCH_ALL)
387 @item -mem-path @var{path}
388 Allocate guest RAM from a temporarily created file in @var{path}.
392 DEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc,
393 "-mem-prealloc preallocate guest memory (use with -mem-path)\n",
397 Preallocate memory when using -mem-path.
401 DEF("k", HAS_ARG, QEMU_OPTION_k,
402 "-k language use keyboard layout (for example 'fr' for French)\n",
405 @item -k @var{language}
407 Use keyboard layout @var{language} (for example @code{fr} for
408 French). This option is only needed where it is not easy to get raw PC
409 keycodes (e.g. on Macs, with some X11 servers or with a VNC
410 display). You don't normally need to use it on PC/Linux or PC/Windows
413 The available layouts are:
415 ar de-ch es fo fr-ca hu ja mk no pt-br sv
416 da en-gb et fr fr-ch is lt nl pl ru th
417 de en-us fi fr-be hr it lv nl-be pt sl tr
420 The default is @code{en-us}.
424 DEF("audio-help", 0, QEMU_OPTION_audio_help,
425 "-audio-help print list of audio drivers and their options\n",
430 Will show the audio subsystem help: list of drivers, tunable
434 DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw,
435 "-soundhw c1,... enable audio support\n"
436 " and only specified sound cards (comma separated list)\n"
437 " use -soundhw ? to get the list of supported cards\n"
438 " use -soundhw all to enable all of them\n", QEMU_ARCH_ALL)
440 @item -soundhw @var{card1}[,@var{card2},...] or -soundhw all
442 Enable audio and selected sound hardware. Use ? to print all
443 available sound hardware.
446 qemu -soundhw sb16,adlib disk.img
447 qemu -soundhw es1370 disk.img
448 qemu -soundhw ac97 disk.img
449 qemu -soundhw hda disk.img
450 qemu -soundhw all disk.img
454 Note that Linux's i810_audio OSS kernel (for AC97) module might
455 require manually specifying clocking.
458 modprobe i810_audio clocking=48000
462 DEF("balloon", HAS_ARG, QEMU_OPTION_balloon,
463 "-balloon none disable balloon device\n"
464 "-balloon virtio[,addr=str]\n"
465 " enable virtio balloon device (default)\n", QEMU_ARCH_ALL)
469 Disable balloon device.
470 @item -balloon virtio[,addr=@var{addr}]
471 Enable virtio balloon device (default), optionally with PCI address
479 DEF("usb", 0, QEMU_OPTION_usb,
480 "-usb enable the USB driver (will be the default soon)\n",
488 Enable the USB driver (will be the default soon)
491 DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice,
492 "-usbdevice name add the host or guest USB device 'name'\n",
496 @item -usbdevice @var{devname}
498 Add the USB device @var{devname}. @xref{usb_devices}.
503 Virtual Mouse. This will override the PS/2 mouse emulation when activated.
506 Pointer device that uses absolute coordinates (like a touchscreen). This
507 means qemu is able to report the mouse position without having to grab the
508 mouse. Also overrides the PS/2 mouse emulation when activated.
510 @item disk:[format=@var{format}]:@var{file}
511 Mass storage device based on file. The optional @var{format} argument
512 will be used rather than detecting the format. Can be used to specifiy
513 @code{format=raw} to avoid interpreting an untrusted format header.
515 @item host:@var{bus}.@var{addr}
516 Pass through the host device identified by @var{bus}.@var{addr} (Linux only).
518 @item host:@var{vendor_id}:@var{product_id}
519 Pass through the host device identified by @var{vendor_id}:@var{product_id}
522 @item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev}
523 Serial converter to host character device @var{dev}, see @code{-serial} for the
527 Braille device. This will use BrlAPI to display the braille output on a real
530 @item net:@var{options}
531 Network adapter that supports CDC ethernet and RNDIS protocols.
536 DEF("device", HAS_ARG, QEMU_OPTION_device,
537 "-device driver[,prop[=value][,...]]\n"
538 " add device (based on driver)\n"
539 " prop=value,... sets driver properties\n"
540 " use -device ? to print all possible drivers\n"
541 " use -device driver,? to print all possible properties\n",
544 @item -device @var{driver}[,@var{prop}[=@var{value}][,...]]
546 Add device @var{driver}. @var{prop}=@var{value} sets driver
547 properties. Valid properties depend on the driver. To get help on
548 possible drivers and properties, use @code{-device ?} and
549 @code{-device @var{driver},?}.
554 DEFHEADING(File system options:)
556 DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev,
557 "-fsdev fsdriver,id=id[,path=path,][security_model={mapped-xattr|mapped-file|passthrough|none}]\n"
558 " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd]\n",
563 @item -fsdev @var{fsdriver},id=@var{id},path=@var{path},[security_model=@var{security_model}][,writeout=@var{writeout}][,readonly][,socket=@var{socket}|sock_fd=@var{sock_fd}]
565 Define a new file system device. Valid options are:
568 This option specifies the fs driver backend to use.
569 Currently "local", "handle" and "proxy" file system drivers are supported.
571 Specifies identifier for this device
572 @item path=@var{path}
573 Specifies the export path for the file system device. Files under
574 this path will be available to the 9p client on the guest.
575 @item security_model=@var{security_model}
576 Specifies the security model to be used for this export path.
577 Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
578 In "passthrough" security model, files are stored using the same
579 credentials as they are created on the guest. This requires qemu
580 to run as root. In "mapped-xattr" security model, some of the file
581 attributes like uid, gid, mode bits and link target are stored as
582 file attributes. For "mapped-file" these attributes are stored in the
583 hidden .virtfs_metadata directory. Directories exported by this security model cannot
584 interact with other unix tools. "none" security model is same as
585 passthrough except the sever won't report failures if it fails to
586 set file attributes like ownership. Security model is mandatory
587 only for local fsdriver. Other fsdrivers (like handle, proxy) don't take
588 security model as a parameter.
589 @item writeout=@var{writeout}
590 This is an optional argument. The only supported value is "immediate".
591 This means that host page cache will be used to read and write data but
592 write notification will be sent to the guest only when the data has been
593 reported as written by the storage subsystem.
595 Enables exporting 9p share as a readonly mount for guests. By default
596 read-write access is given.
597 @item socket=@var{socket}
598 Enables proxy filesystem driver to use passed socket file for communicating
599 with virtfs-proxy-helper
600 @item sock_fd=@var{sock_fd}
601 Enables proxy filesystem driver to use passed socket descriptor for
602 communicating with virtfs-proxy-helper. Usually a helper like libvirt
603 will create socketpair and pass one of the fds as sock_fd
606 -fsdev option is used along with -device driver "virtio-9p-pci".
607 @item -device virtio-9p-pci,fsdev=@var{id},mount_tag=@var{mount_tag}
608 Options for virtio-9p-pci driver are:
611 Specifies the id value specified along with -fsdev option
612 @item mount_tag=@var{mount_tag}
613 Specifies the tag name to be used by the guest to mount this export point
620 DEFHEADING(Virtual File system pass-through options:)
622 DEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs,
623 "-virtfs local,path=path,mount_tag=tag,security_model=[mapped-xattr|mapped-file|passthrough|none]\n"
624 " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd]\n",
629 @item -virtfs @var{fsdriver}[,path=@var{path}],mount_tag=@var{mount_tag}[,security_model=@var{security_model}][,writeout=@var{writeout}][,readonly][,socket=@var{socket}|sock_fd=@var{sock_fd}]
632 The general form of a Virtual File system pass-through options are:
635 This option specifies the fs driver backend to use.
636 Currently "local", "handle" and "proxy" file system drivers are supported.
638 Specifies identifier for this device
639 @item path=@var{path}
640 Specifies the export path for the file system device. Files under
641 this path will be available to the 9p client on the guest.
642 @item security_model=@var{security_model}
643 Specifies the security model to be used for this export path.
644 Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none".
645 In "passthrough" security model, files are stored using the same
646 credentials as they are created on the guest. This requires qemu
647 to run as root. In "mapped-xattr" security model, some of the file
648 attributes like uid, gid, mode bits and link target are stored as
649 file attributes. For "mapped-file" these attributes are stored in the
650 hidden .virtfs_metadata directory. Directories exported by this security model cannot
651 interact with other unix tools. "none" security model is same as
652 passthrough except the sever won't report failures if it fails to
653 set file attributes like ownership. Security model is mandatory only
654 for local fsdriver. Other fsdrivers (like handle, proxy) don't take security
655 model as a parameter.
656 @item writeout=@var{writeout}
657 This is an optional argument. The only supported value is "immediate".
658 This means that host page cache will be used to read and write data but
659 write notification will be sent to the guest only when the data has been
660 reported as written by the storage subsystem.
662 Enables exporting 9p share as a readonly mount for guests. By default
663 read-write access is given.
664 @item socket=@var{socket}
665 Enables proxy filesystem driver to use passed socket file for
666 communicating with virtfs-proxy-helper. Usually a helper like libvirt
667 will create socketpair and pass one of the fds as sock_fd
669 Enables proxy filesystem driver to use passed 'sock_fd' as the socket
670 descriptor for interfacing with virtfs-proxy-helper
674 DEF("virtfs_synth", 0, QEMU_OPTION_virtfs_synth,
675 "-virtfs_synth Create synthetic file system image\n",
679 @findex -virtfs_synth
680 Create synthetic file system image
685 DEF("name", HAS_ARG, QEMU_OPTION_name,
686 "-name string1[,process=string2]\n"
687 " set the name of the guest\n"
688 " string1 sets the window title and string2 the process name (on Linux)\n",
691 @item -name @var{name}
693 Sets the @var{name} of the guest.
694 This name will be displayed in the SDL window caption.
695 The @var{name} will also be used for the VNC server.
696 Also optionally set the top visible process name in Linux.
699 DEF("uuid", HAS_ARG, QEMU_OPTION_uuid,
700 "-uuid %08x-%04x-%04x-%04x-%012x\n"
701 " specify machine UUID\n", QEMU_ARCH_ALL)
703 @item -uuid @var{uuid}
714 DEFHEADING(Display options:)
720 DEF("display", HAS_ARG, QEMU_OPTION_display,
721 "-display sdl[,frame=on|off][,alt_grab=on|off][,ctrl_grab=on|off]\n"
722 " [,window_close=on|off]|curses|none|\n"
723 " vnc=<display>[,<optargs>]\n"
724 " select display type\n", QEMU_ARCH_ALL)
726 @item -display @var{type}
728 Select type of display to use. This option is a replacement for the
729 old style -sdl/-curses/... options. Valid values for @var{type} are
732 Display video output via SDL (usually in a separate graphics
733 window; see the SDL documentation for other possibilities).
735 Display video output via curses. For graphics device models which
736 support a text mode, QEMU can display this output using a
737 curses/ncurses interface. Nothing is displayed when the graphics
738 device is in graphical mode or if the graphics device does not support
739 a text mode. Generally only the VGA device models support text mode.
741 Do not display video output. The guest will still see an emulated
742 graphics card, but its output will not be displayed to the QEMU
743 user. This option differs from the -nographic option in that it
744 only affects what is done with video output; -nographic also changes
745 the destination of the serial and parallel port data.
747 Start a VNC server on display <arg>
751 DEF("nographic", 0, QEMU_OPTION_nographic,
752 "-nographic disable graphical output and redirect serial I/Os to console\n",
757 Normally, QEMU uses SDL to display the VGA output. With this option,
758 you can totally disable graphical output so that QEMU is a simple
759 command line application. The emulated serial port is redirected on
760 the console. Therefore, you can still use QEMU to debug a Linux kernel
761 with a serial console.
764 DEF("curses", 0, QEMU_OPTION_curses,
765 "-curses use a curses/ncurses interface instead of SDL\n",
770 Normally, QEMU uses SDL to display the VGA output. With this option,
771 QEMU can display the VGA output when in text mode using a
772 curses/ncurses interface. Nothing is displayed in graphical mode.
775 DEF("no-frame", 0, QEMU_OPTION_no_frame,
776 "-no-frame open SDL window without a frame and window decorations\n",
781 Do not use decorations for SDL windows and start them using the whole
782 available screen space. This makes the using QEMU in a dedicated desktop
783 workspace more convenient.
786 DEF("alt-grab", 0, QEMU_OPTION_alt_grab,
787 "-alt-grab use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n",
792 Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also
793 affects the special keys (for fullscreen, monitor-mode switching, etc).
796 DEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab,
797 "-ctrl-grab use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n",
802 Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also
803 affects the special keys (for fullscreen, monitor-mode switching, etc).
806 DEF("no-quit", 0, QEMU_OPTION_no_quit,
807 "-no-quit disable SDL window close capability\n", QEMU_ARCH_ALL)
811 Disable SDL window close capability.
814 DEF("sdl", 0, QEMU_OPTION_sdl,
815 "-sdl enable SDL\n", QEMU_ARCH_ALL)
822 DEF("spice", HAS_ARG, QEMU_OPTION_spice,
823 "-spice <args> enable spice\n", QEMU_ARCH_ALL)
825 @item -spice @var{option}[,@var{option}[,...]]
827 Enable the spice remote desktop protocol. Valid options are
832 Set the TCP port spice is listening on for plaintext channels.
835 Set the IP address spice is listening on. Default is any address.
839 Force using the specified IP version.
841 @item password=<secret>
842 Set the password you need to authenticate.
845 Require that the client use SASL to authenticate with the spice.
846 The exact choice of authentication method used is controlled from the
847 system / user's SASL configuration file for the 'qemu' service. This
848 is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
849 unprivileged user, an environment variable SASL_CONF_PATH can be used
850 to make it search alternate locations for the service config.
851 While some SASL auth methods can also provide data encryption (eg GSSAPI),
852 it is recommended that SASL always be combined with the 'tls' and
853 'x509' settings to enable use of SSL and server certificates. This
854 ensures a data encryption preventing compromise of authentication
857 @item disable-ticketing
858 Allow client connects without authentication.
860 @item disable-copy-paste
861 Disable copy paste between the client and the guest.
864 Set the TCP port spice is listening on for encrypted channels.
867 Set the x509 file directory. Expects same filenames as -vnc $display,x509=$dir
869 @item x509-key-file=<file>
870 @item x509-key-password=<file>
871 @item x509-cert-file=<file>
872 @item x509-cacert-file=<file>
873 @item x509-dh-key-file=<file>
874 The x509 file names can also be configured individually.
876 @item tls-ciphers=<list>
877 Specify which ciphers to use.
879 @item tls-channel=[main|display|cursor|inputs|record|playback]
880 @item plaintext-channel=[main|display|cursor|inputs|record|playback]
881 Force specific channel to be used with or without TLS encryption. The
882 options can be specified multiple times to configure multiple
883 channels. The special name "default" can be used to set the default
884 mode. For channels which are not explicitly forced into one mode the
885 spice client is allowed to pick tls/plaintext as he pleases.
887 @item image-compression=[auto_glz|auto_lz|quic|glz|lz|off]
888 Configure image compression (lossless).
891 @item jpeg-wan-compression=[auto|never|always]
892 @item zlib-glz-wan-compression=[auto|never|always]
893 Configure wan image compression (lossy for slow links).
896 @item streaming-video=[off|all|filter]
897 Configure video stream detection. Default is filter.
899 @item agent-mouse=[on|off]
900 Enable/disable passing mouse events via vdagent. Default is on.
902 @item playback-compression=[on|off]
903 Enable/disable audio stream compression (using celt 0.5.1). Default is on.
908 DEF("portrait", 0, QEMU_OPTION_portrait,
909 "-portrait rotate graphical output 90 deg left (only PXA LCD)\n",
914 Rotate graphical output 90 deg left (only PXA LCD).
917 DEF("rotate", HAS_ARG, QEMU_OPTION_rotate,
918 "-rotate <deg> rotate graphical output some deg left (only PXA LCD)\n",
923 Rotate graphical output some deg left (only PXA LCD).
926 DEF("vga", HAS_ARG, QEMU_OPTION_vga,
927 "-vga [std|cirrus|vmware|qxl|xenfb|none]\n"
928 " select video card type\n", QEMU_ARCH_ALL)
930 @item -vga @var{type}
932 Select type of VGA card to emulate. Valid values for @var{type} are
935 Cirrus Logic GD5446 Video card. All Windows versions starting from
936 Windows 95 should recognize and use this graphic card. For optimal
937 performances, use 16 bit color depth in the guest and the host OS.
938 (This one is the default)
940 Standard VGA card with Bochs VBE extensions. If your guest OS
941 supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want
942 to use high resolution modes (>= 1280x1024x16) then you should use
945 VMWare SVGA-II compatible adapter. Use it if you have sufficiently
946 recent XFree86/XOrg server or Windows guest with a driver for this
949 QXL paravirtual graphic card. It is VGA compatible (including VESA
950 2.0 VBE support). Works best with qxl guest drivers installed though.
951 Recommended choice when using the spice protocol.
957 DEF("full-screen", 0, QEMU_OPTION_full_screen,
958 "-full-screen start in full screen\n", QEMU_ARCH_ALL)
962 Start in full screen.
965 DEF("g", 1, QEMU_OPTION_g ,
966 "-g WxH[xDEPTH] Set the initial graphical resolution and depth\n",
967 QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
969 @item -g @var{width}x@var{height}[x@var{depth}]
971 Set the initial graphical resolution and depth (PPC, SPARC only).
974 DEF("vnc", HAS_ARG, QEMU_OPTION_vnc ,
975 "-vnc display start a VNC server on display\n", QEMU_ARCH_ALL)
977 @item -vnc @var{display}[,@var{option}[,@var{option}[,...]]]
979 Normally, QEMU uses SDL to display the VGA output. With this option,
980 you can have QEMU listen on VNC display @var{display} and redirect the VGA
981 display over the VNC session. It is very useful to enable the usb
982 tablet device when using this option (option @option{-usbdevice
983 tablet}). When using the VNC display, you must use the @option{-k}
984 parameter to set the keyboard layout if you are not using en-us. Valid
985 syntax for the @var{display} is
989 @item @var{host}:@var{d}
991 TCP connections will only be allowed from @var{host} on display @var{d}.
992 By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can
993 be omitted in which case the server will accept connections from any host.
995 @item unix:@var{path}
997 Connections will be allowed over UNIX domain sockets where @var{path} is the
998 location of a unix socket to listen for connections on.
1002 VNC is initialized but not started. The monitor @code{change} command
1003 can be used to later start the VNC server.
1007 Following the @var{display} value there may be one or more @var{option} flags
1008 separated by commas. Valid options are
1014 Connect to a listening VNC client via a ``reverse'' connection. The
1015 client is specified by the @var{display}. For reverse network
1016 connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument
1017 is a TCP port number, not a display number.
1021 Require that password based authentication is used for client connections.
1022 The password must be set separately using the @code{change} command in the
1027 Require that client use TLS when communicating with the VNC server. This
1028 uses anonymous TLS credentials so is susceptible to a man-in-the-middle
1029 attack. It is recommended that this option be combined with either the
1030 @option{x509} or @option{x509verify} options.
1032 @item x509=@var{/path/to/certificate/dir}
1034 Valid if @option{tls} is specified. Require that x509 credentials are used
1035 for negotiating the TLS session. The server will send its x509 certificate
1036 to the client. It is recommended that a password be set on the VNC server
1037 to provide authentication of the client when this is used. The path following
1038 this option specifies where the x509 certificates are to be loaded from.
1039 See the @ref{vnc_security} section for details on generating certificates.
1041 @item x509verify=@var{/path/to/certificate/dir}
1043 Valid if @option{tls} is specified. Require that x509 credentials are used
1044 for negotiating the TLS session. The server will send its x509 certificate
1045 to the client, and request that the client send its own x509 certificate.
1046 The server will validate the client's certificate against the CA certificate,
1047 and reject clients when validation fails. If the certificate authority is
1048 trusted, this is a sufficient authentication mechanism. You may still wish
1049 to set a password on the VNC server as a second authentication layer. The
1050 path following this option specifies where the x509 certificates are to
1051 be loaded from. See the @ref{vnc_security} section for details on generating
1056 Require that the client use SASL to authenticate with the VNC server.
1057 The exact choice of authentication method used is controlled from the
1058 system / user's SASL configuration file for the 'qemu' service. This
1059 is typically found in /etc/sasl2/qemu.conf. If running QEMU as an
1060 unprivileged user, an environment variable SASL_CONF_PATH can be used
1061 to make it search alternate locations for the service config.
1062 While some SASL auth methods can also provide data encryption (eg GSSAPI),
1063 it is recommended that SASL always be combined with the 'tls' and
1064 'x509' settings to enable use of SSL and server certificates. This
1065 ensures a data encryption preventing compromise of authentication
1066 credentials. See the @ref{vnc_security} section for details on using
1067 SASL authentication.
1071 Turn on access control lists for checking of the x509 client certificate
1072 and SASL party. For x509 certs, the ACL check is made against the
1073 certificate's distinguished name. This is something that looks like
1074 @code{C=GB,O=ACME,L=Boston,CN=bob}. For SASL party, the ACL check is
1075 made against the username, which depending on the SASL plugin, may
1076 include a realm component, eg @code{bob} or @code{bob@@EXAMPLE.COM}.
1077 When the @option{acl} flag is set, the initial access list will be
1078 empty, with a @code{deny} policy. Thus no one will be allowed to
1079 use the VNC server until the ACLs have been loaded. This can be
1080 achieved using the @code{acl} monitor command.
1084 Enable lossy compression methods (gradient, JPEG, ...). If this
1085 option is set, VNC client may receive lossy framebuffer updates
1086 depending on its encoding settings. Enabling this option can save
1087 a lot of bandwidth at the expense of quality.
1091 Disable adaptive encodings. Adaptive encodings are enabled by default.
1092 An adaptive encoding will try to detect frequently updated screen regions,
1093 and send updates in these regions using a lossy encoding (like JPEG).
1094 This can be really helpful to save bandwidth when playing videos. Disabling
1095 adaptive encodings allows to restore the original static behavior of encodings
1098 @item share=[allow-exclusive|force-shared|ignore]
1100 Set display sharing policy. 'allow-exclusive' allows clients to ask
1101 for exclusive access. As suggested by the rfb spec this is
1102 implemented by dropping other connections. Connecting multiple
1103 clients in parallel requires all clients asking for a shared session
1104 (vncviewer: -shared switch). This is the default. 'force-shared'
1105 disables exclusive client access. Useful for shared desktop sessions,
1106 where you don't want someone forgetting specify -shared disconnect
1107 everybody else. 'ignore' completely ignores the shared flag and
1108 allows everybody connect unconditionally. Doesn't conform to the rfb
1109 spec but is traditional qemu behavior.
1118 ARCHHEADING(, QEMU_ARCH_I386)
1120 ARCHHEADING(i386 target only:, QEMU_ARCH_I386)
1125 DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack,
1126 "-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n",
1131 Use it when installing Windows 2000 to avoid a disk full bug. After
1132 Windows 2000 is installed, you no longer need this option (this option
1133 slows down the IDE transfers).
1136 HXCOMM Deprecated by -rtc
1137 DEF("rtc-td-hack", 0, QEMU_OPTION_rtc_td_hack, "", QEMU_ARCH_I386)
1139 DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk,
1140 "-no-fd-bootchk disable boot signature checking for floppy disks\n",
1143 @item -no-fd-bootchk
1144 @findex -no-fd-bootchk
1145 Disable boot signature checking for floppy disks in Bochs BIOS. It may
1146 be needed to boot from old floppy disks.
1147 TODO: check reference to Bochs BIOS.
1150 DEF("no-acpi", 0, QEMU_OPTION_no_acpi,
1151 "-no-acpi disable ACPI\n", QEMU_ARCH_I386)
1155 Disable ACPI (Advanced Configuration and Power Interface) support. Use
1156 it if your guest OS complains about ACPI problems (PC target machine
1160 DEF("no-hpet", 0, QEMU_OPTION_no_hpet,
1161 "-no-hpet disable HPET\n", QEMU_ARCH_I386)
1165 Disable HPET support.
1168 DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable,
1169 "-acpitable [sig=str][,rev=n][,oem_id=str][,oem_table_id=str][,oem_rev=n][,asl_compiler_id=str][,asl_compiler_rev=n][,{data|file}=file1[:file2]...]\n"
1170 " ACPI table description\n", QEMU_ARCH_I386)
1172 @item -acpitable [sig=@var{str}][,rev=@var{n}][,oem_id=@var{str}][,oem_table_id=@var{str}][,oem_rev=@var{n}] [,asl_compiler_id=@var{str}][,asl_compiler_rev=@var{n}][,data=@var{file1}[:@var{file2}]...]
1174 Add ACPI table with specified header fields and context from specified files.
1175 For file=, take whole ACPI table from the specified files, including all
1176 ACPI headers (possible overridden by other options).
1177 For data=, only data
1178 portion of the table is used, all header information is specified in the
1182 DEF("smbios", HAS_ARG, QEMU_OPTION_smbios,
1183 "-smbios file=binary\n"
1184 " load SMBIOS entry from binary file\n"
1185 "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n"
1186 " specify SMBIOS type 0 fields\n"
1187 "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n"
1188 " [,uuid=uuid][,sku=str][,family=str]\n"
1189 " specify SMBIOS type 1 fields\n", QEMU_ARCH_I386)
1191 @item -smbios file=@var{binary}
1193 Load SMBIOS entry from binary file.
1195 @item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}]
1197 Specify SMBIOS type 0 fields
1199 @item -smbios type=1[,manufacturer=@var{str}][,product=@var{str}] [,version=@var{str}][,serial=@var{str}][,uuid=@var{uuid}][,sku=@var{str}] [,family=@var{str}]
1200 Specify SMBIOS type 1 fields
1208 DEFHEADING(Network options:)
1213 HXCOMM Legacy slirp options (now moved to -net user):
1215 DEF("tftp", HAS_ARG, QEMU_OPTION_tftp, "", QEMU_ARCH_ALL)
1216 DEF("bootp", HAS_ARG, QEMU_OPTION_bootp, "", QEMU_ARCH_ALL)
1217 DEF("redir", HAS_ARG, QEMU_OPTION_redir, "", QEMU_ARCH_ALL)
1219 DEF("smb", HAS_ARG, QEMU_OPTION_smb, "", QEMU_ARCH_ALL)
1223 DEF("net", HAS_ARG, QEMU_OPTION_net,
1224 "-net nic[,vlan=n][,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n"
1225 " create a new Network Interface Card and connect it to VLAN 'n'\n"
1227 "-net user[,vlan=n][,name=str][,net=addr[/mask]][,host=addr][,restrict=on|off]\n"
1228 " [,hostname=host][,dhcpstart=addr][,dns=addr][,tftp=dir][,bootfile=f]\n"
1229 " [,hostfwd=rule][,guestfwd=rule]"
1231 "[,smb=dir[,smbserver=addr]]\n"
1233 " connect the user mode network stack to VLAN 'n', configure its\n"
1234 " DHCP server and enabled optional services\n"
1237 "-net tap[,vlan=n][,name=str],ifname=name\n"
1238 " connect the host TAP network interface to VLAN 'n'\n"
1240 "-net tap[,vlan=n][,name=str][,fd=h][,ifname=name][,script=file][,downscript=dfile][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off][,vhostfd=h][,vhostforce=on|off]\n"
1241 " connect the host TAP network interface to VLAN 'n' \n"
1242 " use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n"
1243 " to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n"
1244 " to deconfigure it\n"
1245 " use '[down]script=no' to disable script execution\n"
1246 " use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n"
1248 " use 'fd=h' to connect to an already opened TAP interface\n"
1249 " use 'sndbuf=nbytes' to limit the size of the send buffer (the\n"
1250 " default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n"
1251 " use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n"
1252 " use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n"
1253 " use vhost=on to enable experimental in kernel accelerator\n"
1254 " (only has effect for virtio guests which use MSIX)\n"
1255 " use vhostforce=on to force vhost on for non-MSIX virtio guests\n"
1256 " use 'vhostfd=h' to connect to an already opened vhost net device\n"
1257 "-net bridge[,vlan=n][,name=str][,br=bridge][,helper=helper]\n"
1258 " connects a host TAP network interface to a host bridge device 'br'\n"
1259 " (default=" DEFAULT_BRIDGE_INTERFACE ") using the program 'helper'\n"
1260 " (default=" DEFAULT_BRIDGE_HELPER ")\n"
1262 "-net socket[,vlan=n][,name=str][,fd=h][,listen=[host]:port][,connect=host:port]\n"
1263 " connect the vlan 'n' to another VLAN using a socket connection\n"
1264 "-net socket[,vlan=n][,name=str][,fd=h][,mcast=maddr:port[,localaddr=addr]]\n"
1265 " connect the vlan 'n' to multicast maddr and port\n"
1266 " use 'localaddr=addr' to specify the host address to send packets from\n"
1267 "-net socket[,vlan=n][,name=str][,fd=h][,udp=host:port][,localaddr=host:port]\n"
1268 " connect the vlan 'n' to another VLAN using an UDP tunnel\n"
1270 "-net vde[,vlan=n][,name=str][,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n"
1271 " connect the vlan 'n' to port 'n' of a vde switch running\n"
1272 " on host and listening for incoming connections on 'socketpath'.\n"
1273 " Use group 'groupname' and mode 'octalmode' to change default\n"
1274 " ownership and permissions for communication port.\n"
1276 "-net dump[,vlan=n][,file=f][,len=n]\n"
1277 " dump traffic on vlan 'n' to file 'f' (max n bytes per packet)\n"
1278 "-net none use it alone to have zero network devices. If no -net option\n"
1279 " is provided, the default is '-net nic -net user'\n", QEMU_ARCH_ALL)
1280 DEF("netdev", HAS_ARG, QEMU_OPTION_netdev,
1290 "socket],id=str[,option][,option][,...]\n", QEMU_ARCH_ALL)
1292 @item -net nic[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}]
1294 Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n}
1295 = 0 is the default). The NIC is an e1000 by default on the PC
1296 target. Optionally, the MAC address can be changed to @var{mac}, the
1297 device address set to @var{addr} (PCI cards only),
1298 and a @var{name} can be assigned for use in monitor commands.
1299 Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors
1300 that the card should have; this option currently only affects virtio cards; set
1301 @var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single
1302 NIC is created. Qemu can emulate several different models of network card.
1303 Valid values for @var{type} are
1304 @code{virtio}, @code{i82551}, @code{i82557b}, @code{i82559er},
1305 @code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139},
1306 @code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}.
1307 Not all devices are supported on all targets. Use -net nic,model=?
1308 for a list of available devices for your target.
1310 @item -net user[,@var{option}][,@var{option}][,...]
1311 Use the user mode network stack which requires no administrator
1312 privilege to run. Valid options are:
1316 Connect user mode stack to VLAN @var{n} (@var{n} = 0 is the default).
1318 @item name=@var{name}
1319 Assign symbolic name for use in monitor commands.
1321 @item net=@var{addr}[/@var{mask}]
1322 Set IP network address the guest will see. Optionally specify the netmask,
1323 either in the form a.b.c.d or as number of valid top-most bits. Default is
1326 @item host=@var{addr}
1327 Specify the guest-visible address of the host. Default is the 2nd IP in the
1328 guest network, i.e. x.x.x.2.
1330 @item restrict=on|off
1331 If this option is enabled, the guest will be isolated, i.e. it will not be
1332 able to contact the host and no guest IP packets will be routed over the host
1333 to the outside. This option does not affect any explicitly set forwarding rules.
1335 @item hostname=@var{name}
1336 Specifies the client hostname reported by the builtin DHCP server.
1338 @item dhcpstart=@var{addr}
1339 Specify the first of the 16 IPs the built-in DHCP server can assign. Default
1340 is the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31.
1342 @item dns=@var{addr}
1343 Specify the guest-visible address of the virtual nameserver. The address must
1344 be different from the host address. Default is the 3rd IP in the guest network,
1347 @item tftp=@var{dir}
1348 When using the user mode network stack, activate a built-in TFTP
1349 server. The files in @var{dir} will be exposed as the root of a TFTP server.
1350 The TFTP client on the guest must be configured in binary mode (use the command
1351 @code{bin} of the Unix TFTP client).
1353 @item bootfile=@var{file}
1354 When using the user mode network stack, broadcast @var{file} as the BOOTP
1355 filename. In conjunction with @option{tftp}, this can be used to network boot
1356 a guest from a local directory.
1358 Example (using pxelinux):
1360 qemu -hda linux.img -boot n -net user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
1363 @item smb=@var{dir}[,smbserver=@var{addr}]
1364 When using the user mode network stack, activate a built-in SMB
1365 server so that Windows OSes can access to the host files in @file{@var{dir}}
1366 transparently. The IP address of the SMB server can be set to @var{addr}. By
1367 default the 4th IP in the guest network is used, i.e. x.x.x.4.
1369 In the guest Windows OS, the line:
1373 must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me)
1374 or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000).
1376 Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}.
1378 Note that a SAMBA server must be installed on the host OS.
1379 QEMU was tested successfully with smbd versions from Red Hat 9,
1380 Fedora Core 3 and OpenSUSE 11.x.
1382 @item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport}
1383 Redirect incoming TCP or UDP connections to the host port @var{hostport} to
1384 the guest IP address @var{guestaddr} on guest port @var{guestport}. If
1385 @var{guestaddr} is not specified, its value is x.x.x.15 (default first address
1386 given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can
1387 be bound to a specific host interface. If no connection type is set, TCP is
1388 used. This option can be given multiple times.
1390 For example, to redirect host X11 connection from screen 1 to guest
1391 screen 0, use the following:
1395 qemu -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...]
1396 # this host xterm should open in the guest X11 server
1400 To redirect telnet connections from host port 5555 to telnet port on
1401 the guest, use the following:
1405 qemu -net user,hostfwd=tcp::5555-:23 [...]
1406 telnet localhost 5555
1409 Then when you use on the host @code{telnet localhost 5555}, you
1410 connect to the guest telnet server.
1412 @item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev}
1413 Forward guest TCP connections to the IP address @var{server} on port @var{port}
1414 to the character device @var{dev}. This option can be given multiple times.
1418 Note: Legacy stand-alone options -tftp, -bootp, -smb and -redir are still
1419 processed and applied to -net user. Mixing them with the new configuration
1420 syntax gives undefined results. Their use for new applications is discouraged
1421 as they will be removed from future versions.
1423 @item -net tap[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,helper=@var{helper}]
1424 Connect the host TAP network interface @var{name} to VLAN @var{n}.
1426 Use the network script @var{file} to configure it and the network script
1427 @var{dfile} to deconfigure it. If @var{name} is not provided, the OS
1428 automatically provides one. The default network configure script is
1429 @file{/etc/qemu-ifup} and the default network deconfigure script is
1430 @file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no}
1431 to disable script execution.
1433 If running QEMU as an unprivileged user, use the network helper
1434 @var{helper} to configure the TAP interface. The default network
1435 helper executable is @file{/usr/local/libexec/qemu-bridge-helper}.
1437 @option{fd}=@var{h} can be used to specify the handle of an already
1438 opened host TAP interface.
1443 #launch a QEMU instance with the default network script
1444 qemu linux.img -net nic -net tap
1448 #launch a QEMU instance with two NICs, each one connected
1450 qemu linux.img -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
1451 -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
1455 #launch a QEMU instance with the default network helper to
1456 #connect a TAP device to bridge br0
1457 qemu linux.img -net nic -net tap,"helper=/usr/local/libexec/qemu-bridge-helper"
1460 @item -net bridge[,vlan=@var{n}][,name=@var{name}][,br=@var{bridge}][,helper=@var{helper}]
1461 Connect a host TAP network interface to a host bridge device.
1463 Use the network helper @var{helper} to configure the TAP interface and
1464 attach it to the bridge. The default network helper executable is
1465 @file{/usr/local/libexec/qemu-bridge-helper} and the default bridge
1466 device is @file{br0}.
1471 #launch a QEMU instance with the default network helper to
1472 #connect a TAP device to bridge br0
1473 qemu linux.img -net bridge -net nic,model=virtio
1477 #launch a QEMU instance with the default network helper to
1478 #connect a TAP device to bridge qemubr0
1479 qemu linux.img -net bridge,br=qemubr0 -net nic,model=virtio
1482 @item -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}] [,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}]
1484 Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual
1485 machine using a TCP socket connection. If @option{listen} is
1486 specified, QEMU waits for incoming connections on @var{port}
1487 (@var{host} is optional). @option{connect} is used to connect to
1488 another QEMU instance using the @option{listen} option. @option{fd}=@var{h}
1489 specifies an already opened TCP socket.
1493 # launch a first QEMU instance
1494 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
1495 -net socket,listen=:1234
1496 # connect the VLAN 0 of this instance to the VLAN 0
1497 # of the first instance
1498 qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
1499 -net socket,connect=127.0.0.1:1234
1502 @item -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]]
1504 Create a VLAN @var{n} shared with another QEMU virtual
1505 machines using a UDP multicast socket, effectively making a bus for
1506 every QEMU with same multicast address @var{maddr} and @var{port}.
1510 Several QEMU can be running on different hosts and share same bus (assuming
1511 correct multicast setup for these hosts).
1513 mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see
1514 @url{http://user-mode-linux.sf.net}.
1516 Use @option{fd=h} to specify an already opened UDP multicast socket.
1521 # launch one QEMU instance
1522 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
1523 -net socket,mcast=230.0.0.1:1234
1524 # launch another QEMU instance on same "bus"
1525 qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \
1526 -net socket,mcast=230.0.0.1:1234
1527 # launch yet another QEMU instance on same "bus"
1528 qemu linux.img -net nic,macaddr=52:54:00:12:34:58 \
1529 -net socket,mcast=230.0.0.1:1234
1532 Example (User Mode Linux compat.):
1534 # launch QEMU instance (note mcast address selected
1536 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
1537 -net socket,mcast=239.192.168.1:1102
1539 /path/to/linux ubd0=/path/to/root_fs eth0=mcast
1542 Example (send packets from host's 1.2.3.4):
1544 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \
1545 -net socket,mcast=239.192.168.1:1102,localaddr=1.2.3.4
1548 @item -net vde[,vlan=@var{n}][,name=@var{name}][,sock=@var{socketpath}] [,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}]
1549 Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and
1550 listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname}
1551 and MODE @var{octalmode} to change default ownership and permissions for
1552 communication port. This option is only available if QEMU has been compiled
1553 with vde support enabled.
1558 vde_switch -F -sock /tmp/myswitch
1559 # launch QEMU instance
1560 qemu linux.img -net nic -net vde,sock=/tmp/myswitch
1563 @item -net dump[,vlan=@var{n}][,file=@var{file}][,len=@var{len}]
1564 Dump network traffic on VLAN @var{n} to file @var{file} (@file{qemu-vlan0.pcap} by default).
1565 At most @var{len} bytes (64k by default) per packet are stored. The file format is
1566 libpcap, so it can be analyzed with tools such as tcpdump or Wireshark.
1569 Indicate that no network devices should be configured. It is used to
1570 override the default configuration (@option{-net nic -net user}) which
1571 is activated if no @option{-net} options are provided.
1578 DEFHEADING(Character device options:)
1580 DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
1581 "-chardev null,id=id[,mux=on|off]\n"
1582 "-chardev socket,id=id[,host=host],port=host[,to=to][,ipv4][,ipv6][,nodelay]\n"
1583 " [,server][,nowait][,telnet][,mux=on|off] (tcp)\n"
1584 "-chardev socket,id=id,path=path[,server][,nowait][,telnet],[mux=on|off] (unix)\n"
1585 "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n"
1586 " [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n"
1587 "-chardev msmouse,id=id[,mux=on|off]\n"
1588 "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n"
1590 "-chardev file,id=id,path=path[,mux=on|off]\n"
1591 "-chardev pipe,id=id,path=path[,mux=on|off]\n"
1593 "-chardev console,id=id[,mux=on|off]\n"
1594 "-chardev serial,id=id,path=path[,mux=on|off]\n"
1596 "-chardev pty,id=id[,mux=on|off]\n"
1597 "-chardev stdio,id=id[,mux=on|off][,signal=on|off]\n"
1599 #ifdef CONFIG_BRLAPI
1600 "-chardev braille,id=id[,mux=on|off]\n"
1602 #if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \
1603 || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__)
1604 "-chardev tty,id=id,path=path[,mux=on|off]\n"
1606 #if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__)
1607 "-chardev parport,id=id,path=path[,mux=on|off]\n"
1609 #if defined(CONFIG_SPICE)
1610 "-chardev spicevmc,id=id,name=name[,debug=debug]\n"
1617 The general form of a character device option is:
1620 @item -chardev @var{backend} ,id=@var{id} [,mux=on|off] [,@var{options}]
1638 The specific backend will determine the applicable options.
1640 All devices must have an id, which can be any string up to 127 characters long.
1641 It is used to uniquely identify this device in other command line directives.
1643 A character device may be used in multiplexing mode by multiple front-ends.
1644 The key sequence of @key{Control-a} and @key{c} will rotate the input focus
1645 between attached front-ends. Specify @option{mux=on} to enable this mode.
1647 Options to each backend are described below.
1649 @item -chardev null ,id=@var{id}
1650 A void device. This device will not emit any data, and will drop any data it
1651 receives. The null backend does not take any options.
1653 @item -chardev socket ,id=@var{id} [@var{TCP options} or @var{unix options}] [,server] [,nowait] [,telnet]
1655 Create a two-way stream socket, which can be either a TCP or a unix socket. A
1656 unix socket will be created if @option{path} is specified. Behaviour is
1657 undefined if TCP options are specified for a unix socket.
1659 @option{server} specifies that the socket shall be a listening socket.
1661 @option{nowait} specifies that QEMU should not block waiting for a client to
1662 connect to a listening socket.
1664 @option{telnet} specifies that traffic on the socket should interpret telnet
1667 TCP and unix socket options are given below:
1671 @item TCP options: port=@var{port} [,host=@var{host}] [,to=@var{to}] [,ipv4] [,ipv6] [,nodelay]
1673 @option{host} for a listening socket specifies the local address to be bound.
1674 For a connecting socket species the remote host to connect to. @option{host} is
1675 optional for listening sockets. If not specified it defaults to @code{0.0.0.0}.
1677 @option{port} for a listening socket specifies the local port to be bound. For a
1678 connecting socket specifies the port on the remote host to connect to.
1679 @option{port} can be given as either a port number or a service name.
1680 @option{port} is required.
1682 @option{to} is only relevant to listening sockets. If it is specified, and
1683 @option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up
1684 to and including @option{to} until it succeeds. @option{to} must be specified
1687 @option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
1688 If neither is specified the socket may use either protocol.
1690 @option{nodelay} disables the Nagle algorithm.
1692 @item unix options: path=@var{path}
1694 @option{path} specifies the local path of the unix socket. @option{path} is
1699 @item -chardev udp ,id=@var{id} [,host=@var{host}] ,port=@var{port} [,localaddr=@var{localaddr}] [,localport=@var{localport}] [,ipv4] [,ipv6]
1701 Sends all traffic from the guest to a remote host over UDP.
1703 @option{host} specifies the remote host to connect to. If not specified it
1704 defaults to @code{localhost}.
1706 @option{port} specifies the port on the remote host to connect to. @option{port}
1709 @option{localaddr} specifies the local address to bind to. If not specified it
1710 defaults to @code{0.0.0.0}.
1712 @option{localport} specifies the local port to bind to. If not specified any
1713 available local port will be used.
1715 @option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used.
1716 If neither is specified the device may use either protocol.
1718 @item -chardev msmouse ,id=@var{id}
1720 Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not
1723 @item -chardev vc ,id=@var{id} [[,width=@var{width}] [,height=@var{height}]] [[,cols=@var{cols}] [,rows=@var{rows}]]
1725 Connect to a QEMU text console. @option{vc} may optionally be given a specific
1728 @option{width} and @option{height} specify the width and height respectively of
1729 the console, in pixels.
1731 @option{cols} and @option{rows} specify that the console be sized to fit a text
1732 console with the given dimensions.
1734 @item -chardev file ,id=@var{id} ,path=@var{path}
1736 Log all traffic received from the guest to a file.
1738 @option{path} specifies the path of the file to be opened. This file will be
1739 created if it does not already exist, and overwritten if it does. @option{path}
1742 @item -chardev pipe ,id=@var{id} ,path=@var{path}
1744 Create a two-way connection to the guest. The behaviour differs slightly between
1745 Windows hosts and other hosts:
1747 On Windows, a single duplex pipe will be created at
1748 @file{\\.pipe\@option{path}}.
1750 On other hosts, 2 pipes will be created called @file{@option{path}.in} and
1751 @file{@option{path}.out}. Data written to @file{@option{path}.in} will be
1752 received by the guest. Data written by the guest can be read from
1753 @file{@option{path}.out}. QEMU will not create these fifos, and requires them to
1756 @option{path} forms part of the pipe path as described above. @option{path} is
1759 @item -chardev console ,id=@var{id}
1761 Send traffic from the guest to QEMU's standard output. @option{console} does not
1764 @option{console} is only available on Windows hosts.
1766 @item -chardev serial ,id=@var{id} ,path=@option{path}
1768 Send traffic from the guest to a serial device on the host.
1771 only available on Windows hosts.
1773 @option{path} specifies the name of the serial device to open.
1775 @item -chardev pty ,id=@var{id}
1777 Create a new pseudo-terminal on the host and connect to it. @option{pty} does
1778 not take any options.
1780 @option{pty} is not available on Windows hosts.
1782 @item -chardev stdio ,id=@var{id} [,signal=on|off]
1783 Connect to standard input and standard output of the qemu process.
1785 @option{signal} controls if signals are enabled on the terminal, that includes
1786 exiting QEMU with the key sequence @key{Control-c}. This option is enabled by
1787 default, use @option{signal=off} to disable it.
1789 @option{stdio} is not available on Windows hosts.
1791 @item -chardev braille ,id=@var{id}
1793 Connect to a local BrlAPI server. @option{braille} does not take any options.
1795 @item -chardev tty ,id=@var{id} ,path=@var{path}
1797 Connect to a local tty device.
1799 @option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and
1802 @option{path} specifies the path to the tty. @option{path} is required.
1804 @item -chardev parport ,id=@var{id} ,path=@var{path}
1806 @option{parport} is only available on Linux, FreeBSD and DragonFlyBSD hosts.
1808 Connect to a local parallel port.
1810 @option{path} specifies the path to the parallel port device. @option{path} is
1813 @item -chardev spicevmc ,id=@var{id} ,debug=@var{debug}, name=@var{name}
1815 @option{spicevmc} is only available when spice support is built in.
1817 @option{debug} debug level for spicevmc
1819 @option{name} name of spice channel to connect to
1821 Connect to a spice virtual machine channel, such as vdiport.
1829 DEFHEADING(Device URL Syntax:)
1831 In addition to using normal file images for the emulated storage devices,
1832 QEMU can also use networked resources such as iSCSI devices. These are
1833 specified using a special URL syntax.
1837 iSCSI support allows QEMU to access iSCSI resources directly and use as
1838 images for the guest storage. Both disk and cdrom images are supported.
1840 Syntax for specifying iSCSI LUNs is
1841 ``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>''
1843 Example (without authentication):
1845 qemu -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
1846 -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
1847 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
1850 Example (CHAP username/password via URL):
1852 qemu -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
1855 Example (CHAP username/password via environment variables):
1857 LIBISCSI_CHAP_USERNAME="user" \
1858 LIBISCSI_CHAP_PASSWORD="password" \
1859 qemu -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
1862 iSCSI support is an optional feature of QEMU and only available when
1863 compiled and linked against libiscsi.
1865 DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
1866 "-iscsi [user=user][,password=password]\n"
1867 " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
1868 " [,initiator-name=iqn]\n"
1869 " iSCSI session parameters\n", QEMU_ARCH_ALL)
1873 QEMU supports NBD (Network Block Devices) both using TCP protocol as well
1874 as Unix Domain Sockets.
1876 Syntax for specifying a NBD device using TCP
1877 ``nbd:<server-ip>:<port>[:exportname=<export>]''
1879 Syntax for specifying a NBD device using Unix Domain Sockets
1880 ``nbd:unix:<domain-socket>[:exportname=<export>]''
1885 qemu --drive file=nbd:192.0.2.1:30000
1888 Example for Unix Domain Sockets
1890 qemu --drive file=nbd:unix:/tmp/nbd-socket
1894 Sheepdog is a distributed storage system for QEMU.
1895 QEMU supports using either local sheepdog devices or remote networked
1898 Syntax for specifying a sheepdog device
1900 ``sheepdog:<vdiname>''
1902 ``sheepdog:<vdiname>:<snapid>''
1904 ``sheepdog:<vdiname>:<tag>''
1906 ``sheepdog:<host>:<port>:<vdiname>''
1908 ``sheepdog:<host>:<port>:<vdiname>:<snapid>''
1910 ``sheepdog:<host>:<port>:<vdiname>:<tag>''
1915 qemu --drive file=sheepdog:192.0.2.1:30000:MyVirtualMachine
1918 See also @url{http://http://www.osrg.net/sheepdog/}.
1923 DEFHEADING(Bluetooth(R) options:)
1925 DEF("bt", HAS_ARG, QEMU_OPTION_bt, \
1926 "-bt hci,null dumb bluetooth HCI - doesn't respond to commands\n" \
1927 "-bt hci,host[:id]\n" \
1928 " use host's HCI with the given name\n" \
1929 "-bt hci[,vlan=n]\n" \
1930 " emulate a standard HCI in virtual scatternet 'n'\n" \
1931 "-bt vhci[,vlan=n]\n" \
1932 " add host computer to virtual scatternet 'n' using VHCI\n" \
1933 "-bt device:dev[,vlan=n]\n" \
1934 " emulate a bluetooth device 'dev' in scatternet 'n'\n",
1941 Defines the function of the corresponding Bluetooth HCI. -bt options
1942 are matched with the HCIs present in the chosen machine type. For
1943 example when emulating a machine with only one HCI built into it, only
1944 the first @code{-bt hci[...]} option is valid and defines the HCI's
1945 logic. The Transport Layer is decided by the machine type. Currently
1946 the machines @code{n800} and @code{n810} have one HCI and all other
1950 The following three types are recognized:
1954 (default) The corresponding Bluetooth HCI assumes no internal logic
1955 and will not respond to any HCI commands or emit events.
1957 @item -bt hci,host[:@var{id}]
1958 (@code{bluez} only) The corresponding HCI passes commands / events
1959 to / from the physical HCI identified by the name @var{id} (default:
1960 @code{hci0}) on the computer running QEMU. Only available on @code{bluez}
1961 capable systems like Linux.
1963 @item -bt hci[,vlan=@var{n}]
1964 Add a virtual, standard HCI that will participate in the Bluetooth
1965 scatternet @var{n} (default @code{0}). Similarly to @option{-net}
1966 VLANs, devices inside a bluetooth network @var{n} can only communicate
1967 with other devices in the same network (scatternet).
1970 @item -bt vhci[,vlan=@var{n}]
1971 (Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached
1972 to the host bluetooth stack instead of to the emulated target. This
1973 allows the host and target machines to participate in a common scatternet
1974 and communicate. Requires the Linux @code{vhci} driver installed. Can
1975 be used as following:
1978 qemu [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5
1981 @item -bt device:@var{dev}[,vlan=@var{n}]
1982 Emulate a bluetooth device @var{dev} and place it in network @var{n}
1983 (default @code{0}). QEMU can only emulate one type of bluetooth devices
1988 Virtual wireless keyboard implementing the HIDP bluetooth profile.
1995 DEFHEADING(Linux/Multiboot boot specific:)
1998 When using these options, you can use a given Linux or Multiboot
1999 kernel without installing it in the disk image. It can be useful
2000 for easier testing of various kernels.
2005 DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \
2006 "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL)
2008 @item -kernel @var{bzImage}
2010 Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel
2011 or in multiboot format.
2014 DEF("append", HAS_ARG, QEMU_OPTION_append, \
2015 "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL)
2017 @item -append @var{cmdline}
2019 Use @var{cmdline} as kernel command line
2022 DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \
2023 "-initrd file use 'file' as initial ram disk\n", QEMU_ARCH_ALL)
2025 @item -initrd @var{file}
2027 Use @var{file} as initial ram disk.
2029 @item -initrd "@var{file1} arg=foo,@var{file2}"
2031 This syntax is only available with multiboot.
2033 Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the
2043 DEFHEADING(Debug/Expert options:)
2049 DEF("serial", HAS_ARG, QEMU_OPTION_serial, \
2050 "-serial dev redirect the serial port to char device 'dev'\n",
2053 @item -serial @var{dev}
2055 Redirect the virtual serial port to host character device
2056 @var{dev}. The default device is @code{vc} in graphical mode and
2057 @code{stdio} in non graphical mode.
2059 This option can be used several times to simulate up to 4 serial
2062 Use @code{-serial none} to disable all serial ports.
2064 Available character devices are:
2066 @item vc[:@var{W}x@var{H}]
2067 Virtual console. Optionally, a width and height can be given in pixel with
2071 It is also possible to specify width or height in characters:
2076 [Linux only] Pseudo TTY (a new PTY is automatically allocated)
2078 No device is allocated.
2082 [Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port
2083 parameters are set according to the emulated ones.
2084 @item /dev/parport@var{N}
2085 [Linux only, parallel port only] Use host parallel port
2086 @var{N}. Currently SPP and EPP parallel port features can be used.
2087 @item file:@var{filename}
2088 Write output to @var{filename}. No character can be read.
2090 [Unix only] standard input/output
2091 @item pipe:@var{filename}
2092 name pipe @var{filename}
2094 [Windows only] Use host serial port @var{n}
2095 @item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}]
2096 This implements UDP Net Console.
2097 When @var{remote_host} or @var{src_ip} are not specified
2098 they default to @code{0.0.0.0}.
2099 When not using a specified @var{src_port} a random port is automatically chosen.
2101 If you just want a simple readonly console you can use @code{netcat} or
2102 @code{nc}, by starting qemu with: @code{-serial udp::4555} and nc as:
2103 @code{nc -u -l -p 4555}. Any time qemu writes something to that port it
2104 will appear in the netconsole session.
2106 If you plan to send characters back via netconsole or you want to stop
2107 and start qemu a lot of times, you should have qemu use the same
2108 source port each time by using something like @code{-serial
2109 udp::4555@@:4556} to qemu. Another approach is to use a patched
2110 version of netcat which can listen to a TCP port and send and receive
2111 characters via udp. If you have a patched version of netcat which
2112 activates telnet remote echo and single char transfer, then you can
2113 use the following options to step up a netcat redirector to allow
2114 telnet on port 5555 to access the qemu port.
2117 -serial udp::4555@@:4556
2118 @item netcat options:
2119 -u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T
2120 @item telnet options:
2124 @item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay]
2125 The TCP Net Console has two modes of operation. It can send the serial
2126 I/O to a location or wait for a connection from a location. By default
2127 the TCP Net Console is sent to @var{host} at the @var{port}. If you use
2128 the @var{server} option QEMU will wait for a client socket application
2129 to connect to the port before continuing, unless the @code{nowait}
2130 option was specified. The @code{nodelay} option disables the Nagle buffering
2131 algorithm. If @var{host} is omitted, 0.0.0.0 is assumed. Only
2132 one TCP connection at a time is accepted. You can use @code{telnet} to
2133 connect to the corresponding character device.
2135 @item Example to send tcp console to 192.168.0.2 port 4444
2136 -serial tcp:192.168.0.2:4444
2137 @item Example to listen and wait on port 4444 for connection
2138 -serial tcp::4444,server
2139 @item Example to not wait and listen on ip 192.168.0.100 port 4444
2140 -serial tcp:192.168.0.100:4444,server,nowait
2143 @item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay]
2144 The telnet protocol is used instead of raw tcp sockets. The options
2145 work the same as if you had specified @code{-serial tcp}. The
2146 difference is that the port acts like a telnet server or client using
2147 telnet option negotiation. This will also allow you to send the
2148 MAGIC_SYSRQ sequence if you use a telnet that supports sending the break
2149 sequence. Typically in unix telnet you do it with Control-] and then
2150 type "send break" followed by pressing the enter key.
2152 @item unix:@var{path}[,server][,nowait]
2153 A unix domain socket is used instead of a tcp socket. The option works the
2154 same as if you had specified @code{-serial tcp} except the unix domain socket
2155 @var{path} is used for connections.
2157 @item mon:@var{dev_string}
2158 This is a special option to allow the monitor to be multiplexed onto
2159 another serial port. The monitor is accessed with key sequence of
2160 @key{Control-a} and then pressing @key{c}. See monitor access
2161 @ref{pcsys_keys} in the -nographic section for more keys.
2162 @var{dev_string} should be any one of the serial devices specified
2163 above. An example to multiplex the monitor onto a telnet server
2164 listening on port 4444 would be:
2166 @item -serial mon:telnet::4444,server,nowait
2170 Braille device. This will use BrlAPI to display the braille output on a real
2174 Three button serial mouse. Configure the guest to use Microsoft protocol.
2178 DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \
2179 "-parallel dev redirect the parallel port to char device 'dev'\n",
2182 @item -parallel @var{dev}
2184 Redirect the virtual parallel port to host device @var{dev} (same
2185 devices as the serial port). On Linux hosts, @file{/dev/parportN} can
2186 be used to use hardware devices connected on the corresponding host
2189 This option can be used several times to simulate up to 3 parallel
2192 Use @code{-parallel none} to disable all parallel ports.
2195 DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \
2196 "-monitor dev redirect the monitor to char device 'dev'\n",
2199 @item -monitor @var{dev}
2201 Redirect the monitor to host device @var{dev} (same devices as the
2203 The default device is @code{vc} in graphical mode and @code{stdio} in
2206 DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \
2207 "-qmp dev like -monitor but opens in 'control' mode\n",
2210 @item -qmp @var{dev}
2212 Like -monitor but opens in 'control' mode.
2215 DEF("mon", HAS_ARG, QEMU_OPTION_mon, \
2216 "-mon chardev=[name][,mode=readline|control][,default]\n", QEMU_ARCH_ALL)
2218 @item -mon chardev=[name][,mode=readline|control][,default]
2220 Setup monitor on chardev @var{name}.
2223 DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \
2224 "-debugcon dev redirect the debug console to char device 'dev'\n",
2227 @item -debugcon @var{dev}
2229 Redirect the debug console to host device @var{dev} (same devices as the
2230 serial port). The debug console is an I/O port which is typically port
2231 0xe9; writing to that I/O port sends output to this device.
2232 The default device is @code{vc} in graphical mode and @code{stdio} in
2236 DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \
2237 "-pidfile file write PID to 'file'\n", QEMU_ARCH_ALL)
2239 @item -pidfile @var{file}
2241 Store the QEMU process PID in @var{file}. It is useful if you launch QEMU
2245 DEF("singlestep", 0, QEMU_OPTION_singlestep, \
2246 "-singlestep always run in singlestep mode\n", QEMU_ARCH_ALL)
2250 Run the emulation in single step mode.
2253 DEF("S", 0, QEMU_OPTION_S, \
2254 "-S freeze CPU at startup (use 'c' to start execution)\n",
2259 Do not start CPU at startup (you must type 'c' in the monitor).
2262 DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \
2263 "-gdb dev wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL)
2265 @item -gdb @var{dev}
2267 Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical
2268 connections will likely be TCP-based, but also UDP, pseudo TTY, or even
2269 stdio are reasonable use case. The latter is allowing to start qemu from
2270 within gdb and establish the connection via a pipe:
2272 (gdb) target remote | exec qemu -gdb stdio ...
2276 DEF("s", 0, QEMU_OPTION_s, \
2277 "-s shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n",
2282 Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234
2283 (@pxref{gdb_usage}).
2286 DEF("d", HAS_ARG, QEMU_OPTION_d, \
2287 "-d item1,... output log to /tmp/qemu.log (use -d ? for a list of log items)\n",
2292 Output log in /tmp/qemu.log
2295 DEF("D", HAS_ARG, QEMU_OPTION_D, \
2296 "-D logfile output log to logfile (instead of the default /tmp/qemu.log)\n",
2301 Output log in logfile instead of /tmp/qemu.log
2304 DEF("hdachs", HAS_ARG, QEMU_OPTION_hdachs, \
2305 "-hdachs c,h,s[,t]\n" \
2306 " force hard disk 0 physical geometry and the optional BIOS\n" \
2307 " translation (t=none or lba) (usually qemu can guess them)\n",
2310 @item -hdachs @var{c},@var{h},@var{s},[,@var{t}]
2312 Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <=
2313 @var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS
2314 translation mode (@var{t}=none, lba or auto). Usually QEMU can guess
2315 all those parameters. This option is useful for old MS-DOS disk
2319 DEF("L", HAS_ARG, QEMU_OPTION_L, \
2320 "-L path set the directory for the BIOS, VGA BIOS and keymaps\n",
2325 Set the directory for the BIOS, VGA BIOS and keymaps.
2328 DEF("bios", HAS_ARG, QEMU_OPTION_bios, \
2329 "-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL)
2331 @item -bios @var{file}
2333 Set the filename for the BIOS.
2336 DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \
2337 "-enable-kvm enable KVM full virtualization support\n", QEMU_ARCH_ALL)
2341 Enable KVM full virtualization support. This option is only available
2342 if KVM support is enabled when compiling.
2345 DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid,
2346 "-xen-domid id specify xen guest domain id\n", QEMU_ARCH_ALL)
2347 DEF("xen-create", 0, QEMU_OPTION_xen_create,
2348 "-xen-create create domain using xen hypercalls, bypassing xend\n"
2349 " warning: should not be used when xend is in use\n",
2351 DEF("xen-attach", 0, QEMU_OPTION_xen_attach,
2352 "-xen-attach attach to existing xen domain\n"
2353 " xend will use this when starting qemu\n",
2356 @item -xen-domid @var{id}
2358 Specify xen guest domain @var{id} (XEN only).
2361 Create domain using xen hypercalls, bypassing xend.
2362 Warning: should not be used when xend is in use (XEN only).
2365 Attach to existing xen domain.
2366 xend will use this when starting qemu (XEN only).
2369 DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \
2370 "-no-reboot exit instead of rebooting\n", QEMU_ARCH_ALL)
2374 Exit instead of rebooting.
2377 DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \
2378 "-no-shutdown stop before shutdown\n", QEMU_ARCH_ALL)
2381 @findex -no-shutdown
2382 Don't exit QEMU on guest shutdown, but instead only stop the emulation.
2383 This allows for instance switching to monitor to commit changes to the
2387 DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \
2388 "-loadvm [tag|id]\n" \
2389 " start right away with a saved state (loadvm in monitor)\n",
2392 @item -loadvm @var{file}
2394 Start right away with a saved state (@code{loadvm} in monitor)
2398 DEF("daemonize", 0, QEMU_OPTION_daemonize, \
2399 "-daemonize daemonize QEMU after initializing\n", QEMU_ARCH_ALL)
2404 Daemonize the QEMU process after initialization. QEMU will not detach from
2405 standard IO until it is ready to receive connections on any of its devices.
2406 This option is a useful way for external programs to launch QEMU without having
2407 to cope with initialization race conditions.
2410 DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \
2411 "-option-rom rom load a file, rom, into the option ROM space\n",
2414 @item -option-rom @var{file}
2416 Load the contents of @var{file} as an option ROM.
2417 This option is useful to load things like EtherBoot.
2420 DEF("clock", HAS_ARG, QEMU_OPTION_clock, \
2421 "-clock force the use of the given methods for timer alarm.\n" \
2422 " To see what timers are available use -clock ?\n",
2425 @item -clock @var{method}
2427 Force the use of the given methods for timer alarm. To see what timers
2428 are available use -clock ?.
2431 HXCOMM Options deprecated by -rtc
2432 DEF("localtime", 0, QEMU_OPTION_localtime, "", QEMU_ARCH_ALL)
2433 DEF("startdate", HAS_ARG, QEMU_OPTION_startdate, "", QEMU_ARCH_ALL)
2435 DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \
2436 "-rtc [base=utc|localtime|date][,clock=host|vm][,driftfix=none|slew]\n" \
2437 " set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n",
2442 @item -rtc [base=utc|localtime|@var{date}][,clock=host|vm][,driftfix=none|slew]
2444 Specify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current
2445 UTC or local time, respectively. @code{localtime} is required for correct date in
2446 MS-DOS or Windows. To start at a specific point in time, provide @var{date} in the
2447 format @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC.
2449 By default the RTC is driven by the host system time. This allows to use the
2450 RTC as accurate reference clock inside the guest, specifically if the host
2451 time is smoothly following an accurate external reference clock, e.g. via NTP.
2452 If you want to isolate the guest time from the host, even prevent it from
2453 progressing during suspension, you can set @option{clock} to @code{vm} instead.
2455 Enable @option{driftfix} (i386 targets only) if you experience time drift problems,
2456 specifically with Windows' ACPI HAL. This option will try to figure out how
2457 many timer interrupts were not processed by the Windows guest and will
2461 DEF("icount", HAS_ARG, QEMU_OPTION_icount, \
2462 "-icount [N|auto]\n" \
2463 " enable virtual instruction counter with 2^N clock ticks per\n" \
2464 " instruction\n", QEMU_ARCH_ALL)
2466 @item -icount [@var{N}|auto]
2468 Enable virtual instruction counter. The virtual cpu will execute one
2469 instruction every 2^@var{N} ns of virtual time. If @code{auto} is specified
2470 then the virtual cpu speed will be automatically adjusted to keep virtual
2471 time within a few seconds of real time.
2473 Note that while this option can give deterministic behavior, it does not
2474 provide cycle accurate emulation. Modern CPUs contain superscalar out of
2475 order cores with complex cache hierarchies. The number of instructions
2476 executed often has little or no correlation with actual performance.
2479 DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \
2480 "-watchdog i6300esb|ib700\n" \
2481 " enable virtual hardware watchdog [default=none]\n",
2484 @item -watchdog @var{model}
2486 Create a virtual hardware watchdog device. Once enabled (by a guest
2487 action), the watchdog must be periodically polled by an agent inside
2488 the guest or else the guest will be restarted.
2490 The @var{model} is the model of hardware watchdog to emulate. Choices
2491 for model are: @code{ib700} (iBASE 700) which is a very simple ISA
2492 watchdog with a single timer, or @code{i6300esb} (Intel 6300ESB I/O
2493 controller hub) which is a much more featureful PCI-based dual-timer
2494 watchdog. Choose a model for which your guest has drivers.
2496 Use @code{-watchdog ?} to list available hardware models. Only one
2497 watchdog can be enabled for a guest.
2500 DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \
2501 "-watchdog-action reset|shutdown|poweroff|pause|debug|none\n" \
2502 " action when watchdog fires [default=reset]\n",
2505 @item -watchdog-action @var{action}
2507 The @var{action} controls what QEMU will do when the watchdog timer
2510 @code{reset} (forcefully reset the guest).
2511 Other possible actions are:
2512 @code{shutdown} (attempt to gracefully shutdown the guest),
2513 @code{poweroff} (forcefully poweroff the guest),
2514 @code{pause} (pause the guest),
2515 @code{debug} (print a debug message and continue), or
2516 @code{none} (do nothing).
2518 Note that the @code{shutdown} action requires that the guest responds
2519 to ACPI signals, which it may not be able to do in the sort of
2520 situations where the watchdog would have expired, and thus
2521 @code{-watchdog-action shutdown} is not recommended for production use.
2526 @item -watchdog i6300esb -watchdog-action pause
2527 @item -watchdog ib700
2531 DEF("echr", HAS_ARG, QEMU_OPTION_echr, \
2532 "-echr chr set terminal escape character instead of ctrl-a\n",
2536 @item -echr @var{numeric_ascii_value}
2538 Change the escape character used for switching to the monitor when using
2539 monitor and serial sharing. The default is @code{0x01} when using the
2540 @code{-nographic} option. @code{0x01} is equal to pressing
2541 @code{Control-a}. You can select a different character from the ascii
2542 control keys where 1 through 26 map to Control-a through Control-z. For
2543 instance you could use the either of the following to change the escape
2544 character to Control-t.
2551 DEF("virtioconsole", HAS_ARG, QEMU_OPTION_virtiocon, \
2552 "-virtioconsole c\n" \
2553 " set virtio console\n", QEMU_ARCH_ALL)
2555 @item -virtioconsole @var{c}
2556 @findex -virtioconsole
2559 This option is maintained for backward compatibility.
2561 Please use @code{-device virtconsole} for the new way of invocation.
2564 DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \
2565 "-show-cursor show cursor\n", QEMU_ARCH_ALL)
2568 @findex -show-cursor
2572 DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \
2573 "-tb-size n set TB size\n", QEMU_ARCH_ALL)
2575 @item -tb-size @var{n}
2580 DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
2581 "-incoming p prepare for incoming migration, listen on port p\n",
2584 @item -incoming @var{port}
2586 Prepare for incoming migration, listen on @var{port}.
2589 DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \
2590 "-nodefaults don't create default devices\n", QEMU_ARCH_ALL)
2594 Don't create default devices.
2598 DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \
2599 "-chroot dir chroot to dir just before starting the VM\n",
2603 @item -chroot @var{dir}
2605 Immediately before starting guest execution, chroot to the specified
2606 directory. Especially useful in combination with -runas.
2610 DEF("runas", HAS_ARG, QEMU_OPTION_runas, \
2611 "-runas user change to user id user just before starting the VM\n",
2615 @item -runas @var{user}
2617 Immediately before starting guest execution, drop root privileges, switching
2618 to the specified user.
2621 DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env,
2622 "-prom-env variable=value\n"
2623 " set OpenBIOS nvram variables\n",
2624 QEMU_ARCH_PPC | QEMU_ARCH_SPARC)
2626 @item -prom-env @var{variable}=@var{value}
2628 Set OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only).
2630 DEF("semihosting", 0, QEMU_OPTION_semihosting,
2631 "-semihosting semihosting mode\n", QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA)
2634 @findex -semihosting
2635 Semihosting mode (ARM, M68K, Xtensa only).
2637 DEF("old-param", 0, QEMU_OPTION_old_param,
2638 "-old-param old param mode\n", QEMU_ARCH_ARM)
2641 @findex -old-param (ARM)
2642 Old param mode (ARM only).
2645 DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig,
2646 "-readconfig <file>\n", QEMU_ARCH_ALL)
2648 @item -readconfig @var{file}
2650 Read device configuration from @var{file}.
2652 DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig,
2653 "-writeconfig <file>\n"
2654 " read/write config file\n", QEMU_ARCH_ALL)
2656 @item -writeconfig @var{file}
2657 @findex -writeconfig
2658 Write device configuration to @var{file}.
2660 DEF("nodefconfig", 0, QEMU_OPTION_nodefconfig,
2662 " do not load default config files at startup\n",
2666 @findex -nodefconfig
2667 Normally QEMU loads a configuration file from @var{sysconfdir}/qemu.conf and
2668 @var{sysconfdir}/target-@var{ARCH}.conf on startup. The @code{-nodefconfig}
2669 option will prevent QEMU from loading these configuration files at startup.
2671 DEF("trace", HAS_ARG, QEMU_OPTION_trace,
2672 "-trace [events=<file>][,file=<file>]\n"
2673 " specify tracing options\n",
2676 HXCOMM This line is not accurate, as some sub-options are backend-specific but
2677 HXCOMM HX does not support conditional compilation of text.
2678 @item -trace [events=@var{file}][,file=@var{file}]
2681 Specify tracing options.
2684 @item events=@var{file}
2685 Immediately enable events listed in @var{file}.
2686 The file must contain one event name (as listed in the @var{trace-events} file)
2688 This option is only available if QEMU has been compiled with
2689 either @var{simple} or @var{stderr} tracing backend.
2690 @item file=@var{file}
2691 Log output traces to @var{file}.
2693 This option is only available if QEMU has been compiled with
2694 the @var{simple} tracing backend.
2698 HXCOMM This is the last statement. Insert new options before this line!