1HXCOMM Use DEFHEADING() to define headings in both help text and texi 2HXCOMM Text between STEXI and ETEXI are copied to texi version and 3HXCOMM discarded from C version 4HXCOMM DEF(option, HAS_ARG/0, opt_enum, opt_help, arch_mask) is used to 5HXCOMM construct option structures, enums and help message for specified 6HXCOMM architectures. 7HXCOMM HXCOMM can be used for comments, discarded from both texi and C 8 9DEFHEADING(Standard options:) 10STEXI 11@table @option 12ETEXI 13 14DEF("help", 0, QEMU_OPTION_h, 15 "-h or -help display this help and exit\n", QEMU_ARCH_ALL) 16STEXI 17@item -h 18@findex -h 19Display help and exit 20ETEXI 21 22DEF("version", 0, QEMU_OPTION_version, 23 "-version display version information and exit\n", QEMU_ARCH_ALL) 24STEXI 25@item -version 26@findex -version 27Display version information and exit 28ETEXI 29 30DEF("machine", HAS_ARG, QEMU_OPTION_machine, \ 31 "-machine [type=]name[,prop[=value][,...]]\n" 32 " selects emulated machine ('-machine help' 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" 36 " vmport=on|off|auto controls emulation of vmport (default: auto)\n" 37 " kvm_shadow_mem=size of KVM shadow MMU\n" 38 " dump-guest-core=on|off include guest memory in a core dump (default=on)\n" 39 " mem-merge=on|off controls memory merge support (default: on)\n" 40 " iommu=on|off controls emulated Intel IOMMU (VT-d) support (default=off)\n" 41 " aes-key-wrap=on|off controls support for AES key wrapping (default=on)\n" 42 " dea-key-wrap=on|off controls support for DEA key wrapping (default=on)\n" 43 " suppress-vmdesc=on|off disables self-describing migration (default=off)\n", 44 QEMU_ARCH_ALL) 45STEXI 46@item -machine [type=]@var{name}[,prop=@var{value}[,...]] 47@findex -machine 48Select the emulated machine by @var{name}. Use @code{-machine help} to list 49available machines. Supported machine properties are: 50@table @option 51@item accel=@var{accels1}[:@var{accels2}[:...]] 52This is used to enable an accelerator. Depending on the target architecture, 53kvm, xen, or tcg can be available. By default, tcg is used. If there is more 54than one accelerator specified, the next one is used if the previous one fails 55to initialize. 56@item kernel_irqchip=on|off 57Enables in-kernel irqchip support for the chosen accelerator when available. 58@item vmport=on|off|auto 59Enables emulation of VMWare IO port, for vmmouse etc. auto says to select the 60value based on accel. For accel=xen the default is off otherwise the default 61is on. 62@item kvm_shadow_mem=size 63Defines the size of the KVM shadow MMU. 64@item dump-guest-core=on|off 65Include guest memory in a core dump. The default is on. 66@item mem-merge=on|off 67Enables or disables memory merge support. This feature, when supported by 68the host, de-duplicates identical memory pages among VMs instances 69(enabled by default). 70@item iommu=on|off 71Enables or disables emulated Intel IOMMU (VT-d) support. The default is off. 72@item aes-key-wrap=on|off 73Enables or disables AES key wrapping support on s390-ccw hosts. This feature 74controls whether AES wrapping keys will be created to allow 75execution of AES cryptographic functions. The default is on. 76@item dea-key-wrap=on|off 77Enables or disables DEA key wrapping support on s390-ccw hosts. This feature 78controls whether DEA wrapping keys will be created to allow 79execution of DEA cryptographic functions. The default is on. 80@end table 81ETEXI 82 83HXCOMM Deprecated by -machine 84DEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL) 85 86DEF("cpu", HAS_ARG, QEMU_OPTION_cpu, 87 "-cpu cpu select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL) 88STEXI 89@item -cpu @var{model} 90@findex -cpu 91Select CPU model (@code{-cpu help} for list and additional feature selection) 92ETEXI 93 94DEF("smp", HAS_ARG, QEMU_OPTION_smp, 95 "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,sockets=sockets]\n" 96 " set the number of CPUs to 'n' [default=1]\n" 97 " maxcpus= maximum number of total cpus, including\n" 98 " offline CPUs for hotplug, etc\n" 99 " cores= number of CPU cores on one socket\n" 100 " threads= number of threads on one CPU core\n" 101 " sockets= number of discrete sockets in the system\n", 102 QEMU_ARCH_ALL) 103STEXI 104@item -smp [cpus=]@var{n}[,cores=@var{cores}][,threads=@var{threads}][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}] 105@findex -smp 106Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255 107CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs 108to 4. 109For the PC target, the number of @var{cores} per socket, the number 110of @var{threads} per cores and the total number of @var{sockets} can be 111specified. Missing values will be computed. If any on the three values is 112given, the total number of CPUs @var{n} can be omitted. @var{maxcpus} 113specifies the maximum number of hotpluggable CPUs. 114ETEXI 115 116DEF("numa", HAS_ARG, QEMU_OPTION_numa, 117 "-numa node[,mem=size][,cpus=cpu[-cpu]][,nodeid=node]\n" 118 "-numa node[,memdev=id][,cpus=cpu[-cpu]][,nodeid=node]\n", QEMU_ARCH_ALL) 119STEXI 120@item -numa node[,mem=@var{size}][,cpus=@var{cpu[-cpu]}][,nodeid=@var{node}] 121@item -numa node[,memdev=@var{id}][,cpus=@var{cpu[-cpu]}][,nodeid=@var{node}] 122@findex -numa 123Simulate a multi node NUMA system. If @samp{mem}, @samp{memdev} 124and @samp{cpus} are omitted, resources are split equally. Also, note 125that the -@option{numa} option doesn't allocate any of the specified 126resources. That is, it just assigns existing resources to NUMA nodes. This 127means that one still has to use the @option{-m}, @option{-smp} options 128to allocate RAM and VCPUs respectively, and possibly @option{-object} 129to specify the memory backend for the @samp{memdev} suboption. 130 131@samp{mem} and @samp{memdev} are mutually exclusive. Furthermore, if one 132node uses @samp{memdev}, all of them have to use it. 133ETEXI 134 135DEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd, 136 "-add-fd fd=fd,set=set[,opaque=opaque]\n" 137 " Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL) 138STEXI 139@item -add-fd fd=@var{fd},set=@var{set}[,opaque=@var{opaque}] 140@findex -add-fd 141 142Add a file descriptor to an fd set. Valid options are: 143 144@table @option 145@item fd=@var{fd} 146This option defines the file descriptor of which a duplicate is added to fd set. 147The file descriptor cannot be stdin, stdout, or stderr. 148@item set=@var{set} 149This option defines the ID of the fd set to add the file descriptor to. 150@item opaque=@var{opaque} 151This option defines a free-form string that can be used to describe @var{fd}. 152@end table 153 154You can open an image using pre-opened file descriptors from an fd set: 155@example 156qemu-system-i386 157-add-fd fd=3,set=2,opaque="rdwr:/path/to/file" 158-add-fd fd=4,set=2,opaque="rdonly:/path/to/file" 159-drive file=/dev/fdset/2,index=0,media=disk 160@end example 161ETEXI 162 163DEF("set", HAS_ARG, QEMU_OPTION_set, 164 "-set group.id.arg=value\n" 165 " set <arg> parameter for item <id> of type <group>\n" 166 " i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL) 167STEXI 168@item -set @var{group}.@var{id}.@var{arg}=@var{value} 169@findex -set 170Set parameter @var{arg} for item @var{id} of type @var{group}\n" 171ETEXI 172 173DEF("global", HAS_ARG, QEMU_OPTION_global, 174 "-global driver.property=value\n" 175 "-global driver=driver,property=property,value=value\n" 176 " set a global default for a driver property\n", 177 QEMU_ARCH_ALL) 178STEXI 179@item -global @var{driver}.@var{prop}=@var{value} 180@itemx -global driver=@var{driver},property=@var{property},value=@var{value} 181@findex -global 182Set default value of @var{driver}'s property @var{prop} to @var{value}, e.g.: 183 184@example 185qemu-system-i386 -global ide-drive.physical_block_size=4096 -drive file=file,if=ide,index=0,media=disk 186@end example 187 188In particular, you can use this to set driver properties for devices which are 189created automatically by the machine model. To create a device which is not 190created automatically and set properties on it, use -@option{device}. 191 192The two syntaxes are equivalent. The longer one works for drivers whose name 193contains a dot. 194ETEXI 195 196DEF("boot", HAS_ARG, QEMU_OPTION_boot, 197 "-boot [order=drives][,once=drives][,menu=on|off]\n" 198 " [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n" 199 " 'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n" 200 " 'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n" 201 " 'sp_time': the period that splash picture last if menu=on, unit is ms\n" 202 " 'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n", 203 QEMU_ARCH_ALL) 204STEXI 205@item -boot [order=@var{drives}][,once=@var{drives}][,menu=on|off][,splash=@var{sp_name}][,splash-time=@var{sp_time}][,reboot-timeout=@var{rb_timeout}][,strict=on|off] 206@findex -boot 207Specify boot order @var{drives} as a string of drive letters. Valid 208drive letters depend on the target achitecture. The x86 PC uses: a, b 209(floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot 210from network adapter 1-4), hard disk boot is the default. To apply a 211particular boot order only on the first startup, specify it via 212@option{once}. 213 214Interactive boot menus/prompts can be enabled via @option{menu=on} as far 215as firmware/BIOS supports them. The default is non-interactive boot. 216 217A splash picture could be passed to bios, enabling user to show it as logo, 218when option splash=@var{sp_name} is given and menu=on, If firmware/BIOS 219supports them. Currently Seabios for X86 system support it. 220limitation: The splash file could be a jpeg file or a BMP file in 24 BPP 221format(true color). The resolution should be supported by the SVGA mode, so 222the recommended is 320x240, 640x480, 800x640. 223 224A timeout could be passed to bios, guest will pause for @var{rb_timeout} ms 225when boot failed, then reboot. If @var{rb_timeout} is '-1', guest will not 226reboot, qemu passes '-1' to bios by default. Currently Seabios for X86 227system support it. 228 229Do strict boot via @option{strict=on} as far as firmware/BIOS 230supports it. This only effects when boot priority is changed by 231bootindex options. The default is non-strict boot. 232 233@example 234# try to boot from network first, then from hard disk 235qemu-system-i386 -boot order=nc 236# boot from CD-ROM first, switch back to default order after reboot 237qemu-system-i386 -boot once=d 238# boot with a splash picture for 5 seconds. 239qemu-system-i386 -boot menu=on,splash=/root/boot.bmp,splash-time=5000 240@end example 241 242Note: The legacy format '-boot @var{drives}' is still supported but its 243use is discouraged as it may be removed from future versions. 244ETEXI 245 246DEF("m", HAS_ARG, QEMU_OPTION_m, 247 "-m[emory] [size=]megs[,slots=n,maxmem=size]\n" 248 " configure guest RAM\n" 249 " size: initial amount of guest memory\n" 250 " slots: number of hotplug slots (default: none)\n" 251 " maxmem: maximum amount of guest memory (default: none)\n" 252 "NOTE: Some architectures might enforce a specific granularity\n", 253 QEMU_ARCH_ALL) 254STEXI 255@item -m [size=]@var{megs}[,slots=n,maxmem=size] 256@findex -m 257Sets guest startup RAM size to @var{megs} megabytes. Default is 128 MiB. 258Optionally, a suffix of ``M'' or ``G'' can be used to signify a value in 259megabytes or gigabytes respectively. Optional pair @var{slots}, @var{maxmem} 260could be used to set amount of hotpluggable memory slots and maximum amount of 261memory. Note that @var{maxmem} must be aligned to the page size. 262 263For example, the following command-line sets the guest startup RAM size to 2641GB, creates 3 slots to hotplug additional memory and sets the maximum 265memory the guest can reach to 4GB: 266 267@example 268qemu-system-x86_64 -m 1G,slots=3,maxmem=4G 269@end example 270 271If @var{slots} and @var{maxmem} are not specified, memory hotplug won't 272be enabled and the guest startup RAM will never increase. 273ETEXI 274 275DEF("mem-path", HAS_ARG, QEMU_OPTION_mempath, 276 "-mem-path FILE provide backing storage for guest RAM\n", QEMU_ARCH_ALL) 277STEXI 278@item -mem-path @var{path} 279@findex -mem-path 280Allocate guest RAM from a temporarily created file in @var{path}. 281ETEXI 282 283DEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc, 284 "-mem-prealloc preallocate guest memory (use with -mem-path)\n", 285 QEMU_ARCH_ALL) 286STEXI 287@item -mem-prealloc 288@findex -mem-prealloc 289Preallocate memory when using -mem-path. 290ETEXI 291 292DEF("k", HAS_ARG, QEMU_OPTION_k, 293 "-k language use keyboard layout (for example 'fr' for French)\n", 294 QEMU_ARCH_ALL) 295STEXI 296@item -k @var{language} 297@findex -k 298Use keyboard layout @var{language} (for example @code{fr} for 299French). This option is only needed where it is not easy to get raw PC 300keycodes (e.g. on Macs, with some X11 servers or with a VNC 301display). You don't normally need to use it on PC/Linux or PC/Windows 302hosts. 303 304The available layouts are: 305@example 306ar de-ch es fo fr-ca hu ja mk no pt-br sv 307da en-gb et fr fr-ch is lt nl pl ru th 308de en-us fi fr-be hr it lv nl-be pt sl tr 309@end example 310 311The default is @code{en-us}. 312ETEXI 313 314 315DEF("audio-help", 0, QEMU_OPTION_audio_help, 316 "-audio-help print list of audio drivers and their options\n", 317 QEMU_ARCH_ALL) 318STEXI 319@item -audio-help 320@findex -audio-help 321Will show the audio subsystem help: list of drivers, tunable 322parameters. 323ETEXI 324 325DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw, 326 "-soundhw c1,... enable audio support\n" 327 " and only specified sound cards (comma separated list)\n" 328 " use '-soundhw help' to get the list of supported cards\n" 329 " use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL) 330STEXI 331@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all 332@findex -soundhw 333Enable audio and selected sound hardware. Use 'help' to print all 334available sound hardware. 335 336@example 337qemu-system-i386 -soundhw sb16,adlib disk.img 338qemu-system-i386 -soundhw es1370 disk.img 339qemu-system-i386 -soundhw ac97 disk.img 340qemu-system-i386 -soundhw hda disk.img 341qemu-system-i386 -soundhw all disk.img 342qemu-system-i386 -soundhw help 343@end example 344 345Note that Linux's i810_audio OSS kernel (for AC97) module might 346require manually specifying clocking. 347 348@example 349modprobe i810_audio clocking=48000 350@end example 351ETEXI 352 353DEF("balloon", HAS_ARG, QEMU_OPTION_balloon, 354 "-balloon none disable balloon device\n" 355 "-balloon virtio[,addr=str]\n" 356 " enable virtio balloon device (default)\n", QEMU_ARCH_ALL) 357STEXI 358@item -balloon none 359@findex -balloon 360Disable balloon device. 361@item -balloon virtio[,addr=@var{addr}] 362Enable virtio balloon device (default), optionally with PCI address 363@var{addr}. 364ETEXI 365 366DEF("device", HAS_ARG, QEMU_OPTION_device, 367 "-device driver[,prop[=value][,...]]\n" 368 " add device (based on driver)\n" 369 " prop=value,... sets driver properties\n" 370 " use '-device help' to print all possible drivers\n" 371 " use '-device driver,help' to print all possible properties\n", 372 QEMU_ARCH_ALL) 373STEXI 374@item -device @var{driver}[,@var{prop}[=@var{value}][,...]] 375@findex -device 376Add device @var{driver}. @var{prop}=@var{value} sets driver 377properties. Valid properties depend on the driver. To get help on 378possible drivers and properties, use @code{-device help} and 379@code{-device @var{driver},help}. 380ETEXI 381 382DEF("name", HAS_ARG, QEMU_OPTION_name, 383 "-name string1[,process=string2][,debug-threads=on|off]\n" 384 " set the name of the guest\n" 385 " string1 sets the window title and string2 the process name (on Linux)\n" 386 " When debug-threads is enabled, individual threads are given a separate name (on Linux)\n" 387 " NOTE: The thread names are for debugging and not a stable API.\n", 388 QEMU_ARCH_ALL) 389STEXI 390@item -name @var{name} 391@findex -name 392Sets the @var{name} of the guest. 393This name will be displayed in the SDL window caption. 394The @var{name} will also be used for the VNC server. 395Also optionally set the top visible process name in Linux. 396Naming of individual threads can also be enabled on Linux to aid debugging. 397ETEXI 398 399DEF("uuid", HAS_ARG, QEMU_OPTION_uuid, 400 "-uuid %08x-%04x-%04x-%04x-%012x\n" 401 " specify machine UUID\n", QEMU_ARCH_ALL) 402STEXI 403@item -uuid @var{uuid} 404@findex -uuid 405Set system UUID. 406ETEXI 407 408STEXI 409@end table 410ETEXI 411DEFHEADING() 412 413DEFHEADING(Block device options:) 414STEXI 415@table @option 416ETEXI 417 418DEF("fda", HAS_ARG, QEMU_OPTION_fda, 419 "-fda/-fdb file use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL) 420DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL) 421STEXI 422@item -fda @var{file} 423@item -fdb @var{file} 424@findex -fda 425@findex -fdb 426Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}). 427ETEXI 428 429DEF("hda", HAS_ARG, QEMU_OPTION_hda, 430 "-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL) 431DEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL) 432DEF("hdc", HAS_ARG, QEMU_OPTION_hdc, 433 "-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL) 434DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL) 435STEXI 436@item -hda @var{file} 437@item -hdb @var{file} 438@item -hdc @var{file} 439@item -hdd @var{file} 440@findex -hda 441@findex -hdb 442@findex -hdc 443@findex -hdd 444Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}). 445ETEXI 446 447DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom, 448 "-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n", 449 QEMU_ARCH_ALL) 450STEXI 451@item -cdrom @var{file} 452@findex -cdrom 453Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and 454@option{-cdrom} at the same time). You can use the host CD-ROM by 455using @file{/dev/cdrom} as filename (@pxref{host_drives}). 456ETEXI 457 458DEF("drive", HAS_ARG, QEMU_OPTION_drive, 459 "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n" 460 " [,cyls=c,heads=h,secs=s[,trans=t]][,snapshot=on|off]\n" 461 " [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n" 462 " [,serial=s][,addr=A][,rerror=ignore|stop|report]\n" 463 " [,werror=ignore|stop|report|enospc][,id=name][,aio=threads|native]\n" 464 " [,readonly=on|off][,copy-on-read=on|off]\n" 465 " [,discard=ignore|unmap][,detect-zeroes=on|off|unmap]\n" 466 " [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n" 467 " [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n" 468 " [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n" 469 " [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n" 470 " [[,iops_size=is]]\n" 471 " use 'file' as a drive image\n", QEMU_ARCH_ALL) 472STEXI 473@item -drive @var{option}[,@var{option}[,@var{option}[,...]]] 474@findex -drive 475 476Define a new drive. Valid options are: 477 478@table @option 479@item file=@var{file} 480This option defines which disk image (@pxref{disk_images}) to use with 481this drive. If the filename contains comma, you must double it 482(for instance, "file=my,,file" to use file "my,file"). 483 484Special files such as iSCSI devices can be specified using protocol 485specific URLs. See the section for "Device URL Syntax" for more information. 486@item if=@var{interface} 487This option defines on which type on interface the drive is connected. 488Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio. 489@item bus=@var{bus},unit=@var{unit} 490These options define where is connected the drive by defining the bus number and 491the unit id. 492@item index=@var{index} 493This option defines where is connected the drive by using an index in the list 494of available connectors of a given interface type. 495@item media=@var{media} 496This option defines the type of the media: disk or cdrom. 497@item cyls=@var{c},heads=@var{h},secs=@var{s}[,trans=@var{t}] 498These options have the same definition as they have in @option{-hdachs}. 499@item snapshot=@var{snapshot} 500@var{snapshot} is "on" or "off" and controls snapshot mode for the given drive 501(see @option{-snapshot}). 502@item cache=@var{cache} 503@var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough" and controls how the host cache is used to access block data. 504@item aio=@var{aio} 505@var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO. 506@item discard=@var{discard} 507@var{discard} is one of "ignore" (or "off") or "unmap" (or "on") and controls whether @dfn{discard} (also known as @dfn{trim} or @dfn{unmap}) requests are ignored or passed to the filesystem. Some machine types may not support discard requests. 508@item format=@var{format} 509Specify which disk @var{format} will be used rather than detecting 510the format. Can be used to specifiy format=raw to avoid interpreting 511an untrusted format header. 512@item serial=@var{serial} 513This option specifies the serial number to assign to the device. 514@item addr=@var{addr} 515Specify the controller's PCI address (if=virtio only). 516@item werror=@var{action},rerror=@var{action} 517Specify which @var{action} to take on write and read errors. Valid actions are: 518"ignore" (ignore the error and try to continue), "stop" (pause QEMU), 519"report" (report the error to the guest), "enospc" (pause QEMU only if the 520host disk is full; report the error to the guest otherwise). 521The default setting is @option{werror=enospc} and @option{rerror=report}. 522@item readonly 523Open drive @option{file} as read-only. Guest write attempts will fail. 524@item copy-on-read=@var{copy-on-read} 525@var{copy-on-read} is "on" or "off" and enables whether to copy read backing 526file sectors into the image file. 527@item detect-zeroes=@var{detect-zeroes} 528@var{detect-zeroes} is "off", "on" or "unmap" and enables the automatic 529conversion of plain zero writes by the OS to driver specific optimized 530zero write commands. You may even choose "unmap" if @var{discard} is set 531to "unmap" to allow a zero write to be converted to an UNMAP operation. 532@end table 533 534By default, the @option{cache=writeback} mode is used. It will report data 535writes as completed as soon as the data is present in the host page cache. 536This is safe as long as your guest OS makes sure to correctly flush disk caches 537where needed. If your guest OS does not handle volatile disk write caches 538correctly and your host crashes or loses power, then the guest may experience 539data corruption. 540 541For such guests, you should consider using @option{cache=writethrough}. This 542means that the host page cache will be used to read and write data, but write 543notification will be sent to the guest only after QEMU has made sure to flush 544each write to the disk. Be aware that this has a major impact on performance. 545 546The host page cache can be avoided entirely with @option{cache=none}. This will 547attempt to do disk IO directly to the guest's memory. QEMU may still perform 548an internal copy of the data. Note that this is considered a writeback mode and 549the guest OS must handle the disk write cache correctly in order to avoid data 550corruption on host crashes. 551 552The host page cache can be avoided while only sending write notifications to 553the guest when the data has been flushed to the disk using 554@option{cache=directsync}. 555 556In case you don't care about data integrity over host failures, use 557@option{cache=unsafe}. This option tells QEMU that it never needs to write any 558data to the disk but can instead keep things in cache. If anything goes wrong, 559like your host losing power, the disk storage getting disconnected accidentally, 560etc. your image will most probably be rendered unusable. When using 561the @option{-snapshot} option, unsafe caching is always used. 562 563Copy-on-read avoids accessing the same backing file sectors repeatedly and is 564useful when the backing file is over a slow network. By default copy-on-read 565is off. 566 567Instead of @option{-cdrom} you can use: 568@example 569qemu-system-i386 -drive file=file,index=2,media=cdrom 570@end example 571 572Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can 573use: 574@example 575qemu-system-i386 -drive file=file,index=0,media=disk 576qemu-system-i386 -drive file=file,index=1,media=disk 577qemu-system-i386 -drive file=file,index=2,media=disk 578qemu-system-i386 -drive file=file,index=3,media=disk 579@end example 580 581You can open an image using pre-opened file descriptors from an fd set: 582@example 583qemu-system-i386 584-add-fd fd=3,set=2,opaque="rdwr:/path/to/file" 585-add-fd fd=4,set=2,opaque="rdonly:/path/to/file" 586-drive file=/dev/fdset/2,index=0,media=disk 587@end example 588 589You can connect a CDROM to the slave of ide0: 590@example 591qemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom 592@end example 593 594If you don't specify the "file=" argument, you define an empty drive: 595@example 596qemu-system-i386 -drive if=ide,index=1,media=cdrom 597@end example 598 599You can connect a SCSI disk with unit ID 6 on the bus #0: 600@example 601qemu-system-i386 -drive file=file,if=scsi,bus=0,unit=6 602@end example 603 604Instead of @option{-fda}, @option{-fdb}, you can use: 605@example 606qemu-system-i386 -drive file=file,index=0,if=floppy 607qemu-system-i386 -drive file=file,index=1,if=floppy 608@end example 609 610By default, @var{interface} is "ide" and @var{index} is automatically 611incremented: 612@example 613qemu-system-i386 -drive file=a -drive file=b" 614@end example 615is interpreted like: 616@example 617qemu-system-i386 -hda a -hdb b 618@end example 619ETEXI 620 621DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock, 622 "-mtdblock file use 'file' as on-board Flash memory image\n", 623 QEMU_ARCH_ALL) 624STEXI 625@item -mtdblock @var{file} 626@findex -mtdblock 627Use @var{file} as on-board Flash memory image. 628ETEXI 629 630DEF("sd", HAS_ARG, QEMU_OPTION_sd, 631 "-sd file use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL) 632STEXI 633@item -sd @var{file} 634@findex -sd 635Use @var{file} as SecureDigital card image. 636ETEXI 637 638DEF("pflash", HAS_ARG, QEMU_OPTION_pflash, 639 "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL) 640STEXI 641@item -pflash @var{file} 642@findex -pflash 643Use @var{file} as a parallel flash image. 644ETEXI 645 646DEF("snapshot", 0, QEMU_OPTION_snapshot, 647 "-snapshot write to temporary files instead of disk image files\n", 648 QEMU_ARCH_ALL) 649STEXI 650@item -snapshot 651@findex -snapshot 652Write to temporary files instead of disk image files. In this case, 653the raw disk image you use is not written back. You can however force 654the write back by pressing @key{C-a s} (@pxref{disk_images}). 655ETEXI 656 657DEF("hdachs", HAS_ARG, QEMU_OPTION_hdachs, \ 658 "-hdachs c,h,s[,t]\n" \ 659 " force hard disk 0 physical geometry and the optional BIOS\n" \ 660 " translation (t=none or lba) (usually QEMU can guess them)\n", 661 QEMU_ARCH_ALL) 662STEXI 663@item -hdachs @var{c},@var{h},@var{s},[,@var{t}] 664@findex -hdachs 665Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <= 666@var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS 667translation mode (@var{t}=none, lba or auto). Usually QEMU can guess 668all those parameters. This option is useful for old MS-DOS disk 669images. 670ETEXI 671 672DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev, 673 "-fsdev fsdriver,id=id[,path=path,][security_model={mapped-xattr|mapped-file|passthrough|none}]\n" 674 " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd]\n", 675 QEMU_ARCH_ALL) 676 677STEXI 678 679@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}] 680@findex -fsdev 681Define a new file system device. Valid options are: 682@table @option 683@item @var{fsdriver} 684This option specifies the fs driver backend to use. 685Currently "local", "handle" and "proxy" file system drivers are supported. 686@item id=@var{id} 687Specifies identifier for this device 688@item path=@var{path} 689Specifies the export path for the file system device. Files under 690this path will be available to the 9p client on the guest. 691@item security_model=@var{security_model} 692Specifies the security model to be used for this export path. 693Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none". 694In "passthrough" security model, files are stored using the same 695credentials as they are created on the guest. This requires QEMU 696to run as root. In "mapped-xattr" security model, some of the file 697attributes like uid, gid, mode bits and link target are stored as 698file attributes. For "mapped-file" these attributes are stored in the 699hidden .virtfs_metadata directory. Directories exported by this security model cannot 700interact with other unix tools. "none" security model is same as 701passthrough except the sever won't report failures if it fails to 702set file attributes like ownership. Security model is mandatory 703only for local fsdriver. Other fsdrivers (like handle, proxy) don't take 704security model as a parameter. 705@item writeout=@var{writeout} 706This is an optional argument. The only supported value is "immediate". 707This means that host page cache will be used to read and write data but 708write notification will be sent to the guest only when the data has been 709reported as written by the storage subsystem. 710@item readonly 711Enables exporting 9p share as a readonly mount for guests. By default 712read-write access is given. 713@item socket=@var{socket} 714Enables proxy filesystem driver to use passed socket file for communicating 715with virtfs-proxy-helper 716@item sock_fd=@var{sock_fd} 717Enables proxy filesystem driver to use passed socket descriptor for 718communicating with virtfs-proxy-helper. Usually a helper like libvirt 719will create socketpair and pass one of the fds as sock_fd 720@end table 721 722-fsdev option is used along with -device driver "virtio-9p-pci". 723@item -device virtio-9p-pci,fsdev=@var{id},mount_tag=@var{mount_tag} 724Options for virtio-9p-pci driver are: 725@table @option 726@item fsdev=@var{id} 727Specifies the id value specified along with -fsdev option 728@item mount_tag=@var{mount_tag} 729Specifies the tag name to be used by the guest to mount this export point 730@end table 731 732ETEXI 733 734DEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs, 735 "-virtfs local,path=path,mount_tag=tag,security_model=[mapped-xattr|mapped-file|passthrough|none]\n" 736 " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd]\n", 737 QEMU_ARCH_ALL) 738 739STEXI 740 741@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}] 742@findex -virtfs 743 744The general form of a Virtual File system pass-through options are: 745@table @option 746@item @var{fsdriver} 747This option specifies the fs driver backend to use. 748Currently "local", "handle" and "proxy" file system drivers are supported. 749@item id=@var{id} 750Specifies identifier for this device 751@item path=@var{path} 752Specifies the export path for the file system device. Files under 753this path will be available to the 9p client on the guest. 754@item security_model=@var{security_model} 755Specifies the security model to be used for this export path. 756Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none". 757In "passthrough" security model, files are stored using the same 758credentials as they are created on the guest. This requires QEMU 759to run as root. In "mapped-xattr" security model, some of the file 760attributes like uid, gid, mode bits and link target are stored as 761file attributes. For "mapped-file" these attributes are stored in the 762hidden .virtfs_metadata directory. Directories exported by this security model cannot 763interact with other unix tools. "none" security model is same as 764passthrough except the sever won't report failures if it fails to 765set file attributes like ownership. Security model is mandatory only 766for local fsdriver. Other fsdrivers (like handle, proxy) don't take security 767model as a parameter. 768@item writeout=@var{writeout} 769This is an optional argument. The only supported value is "immediate". 770This means that host page cache will be used to read and write data but 771write notification will be sent to the guest only when the data has been 772reported as written by the storage subsystem. 773@item readonly 774Enables exporting 9p share as a readonly mount for guests. By default 775read-write access is given. 776@item socket=@var{socket} 777Enables proxy filesystem driver to use passed socket file for 778communicating with virtfs-proxy-helper. Usually a helper like libvirt 779will create socketpair and pass one of the fds as sock_fd 780@item sock_fd 781Enables proxy filesystem driver to use passed 'sock_fd' as the socket 782descriptor for interfacing with virtfs-proxy-helper 783@end table 784ETEXI 785 786DEF("virtfs_synth", 0, QEMU_OPTION_virtfs_synth, 787 "-virtfs_synth Create synthetic file system image\n", 788 QEMU_ARCH_ALL) 789STEXI 790@item -virtfs_synth 791@findex -virtfs_synth 792Create synthetic file system image 793ETEXI 794 795STEXI 796@end table 797ETEXI 798DEFHEADING() 799 800DEFHEADING(USB options:) 801STEXI 802@table @option 803ETEXI 804 805DEF("usb", 0, QEMU_OPTION_usb, 806 "-usb enable the USB driver (will be the default soon)\n", 807 QEMU_ARCH_ALL) 808STEXI 809@item -usb 810@findex -usb 811Enable the USB driver (will be the default soon) 812ETEXI 813 814DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice, 815 "-usbdevice name add the host or guest USB device 'name'\n", 816 QEMU_ARCH_ALL) 817STEXI 818 819@item -usbdevice @var{devname} 820@findex -usbdevice 821Add the USB device @var{devname}. @xref{usb_devices}. 822 823@table @option 824 825@item mouse 826Virtual Mouse. This will override the PS/2 mouse emulation when activated. 827 828@item tablet 829Pointer device that uses absolute coordinates (like a touchscreen). This 830means QEMU is able to report the mouse position without having to grab the 831mouse. Also overrides the PS/2 mouse emulation when activated. 832 833@item disk:[format=@var{format}]:@var{file} 834Mass storage device based on file. The optional @var{format} argument 835will be used rather than detecting the format. Can be used to specifiy 836@code{format=raw} to avoid interpreting an untrusted format header. 837 838@item host:@var{bus}.@var{addr} 839Pass through the host device identified by @var{bus}.@var{addr} (Linux only). 840 841@item host:@var{vendor_id}:@var{product_id} 842Pass through the host device identified by @var{vendor_id}:@var{product_id} 843(Linux only). 844 845@item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev} 846Serial converter to host character device @var{dev}, see @code{-serial} for the 847available devices. 848 849@item braille 850Braille device. This will use BrlAPI to display the braille output on a real 851or fake device. 852 853@item net:@var{options} 854Network adapter that supports CDC ethernet and RNDIS protocols. 855 856@end table 857ETEXI 858 859STEXI 860@end table 861ETEXI 862DEFHEADING() 863 864DEFHEADING(Display options:) 865STEXI 866@table @option 867ETEXI 868 869DEF("display", HAS_ARG, QEMU_OPTION_display, 870 "-display sdl[,frame=on|off][,alt_grab=on|off][,ctrl_grab=on|off]\n" 871 " [,window_close=on|off]|curses|none|\n" 872 " gtk[,grab_on_hover=on|off]|\n" 873 " vnc=<display>[,<optargs>]\n" 874 " select display type\n", QEMU_ARCH_ALL) 875STEXI 876@item -display @var{type} 877@findex -display 878Select type of display to use. This option is a replacement for the 879old style -sdl/-curses/... options. Valid values for @var{type} are 880@table @option 881@item sdl 882Display video output via SDL (usually in a separate graphics 883window; see the SDL documentation for other possibilities). 884@item curses 885Display video output via curses. For graphics device models which 886support a text mode, QEMU can display this output using a 887curses/ncurses interface. Nothing is displayed when the graphics 888device is in graphical mode or if the graphics device does not support 889a text mode. Generally only the VGA device models support text mode. 890@item none 891Do not display video output. The guest will still see an emulated 892graphics card, but its output will not be displayed to the QEMU 893user. This option differs from the -nographic option in that it 894only affects what is done with video output; -nographic also changes 895the destination of the serial and parallel port data. 896@item gtk 897Display video output in a GTK window. This interface provides drop-down 898menus and other UI elements to configure and control the VM during 899runtime. 900@item vnc 901Start a VNC server on display <arg> 902@end table 903ETEXI 904 905DEF("nographic", 0, QEMU_OPTION_nographic, 906 "-nographic disable graphical output and redirect serial I/Os to console\n", 907 QEMU_ARCH_ALL) 908STEXI 909@item -nographic 910@findex -nographic 911Normally, QEMU uses SDL to display the VGA output. With this option, 912you can totally disable graphical output so that QEMU is a simple 913command line application. The emulated serial port is redirected on 914the console and muxed with the monitor (unless redirected elsewhere 915explicitly). Therefore, you can still use QEMU to debug a Linux kernel 916with a serial console. Use @key{C-a h} for help on switching between 917the console and monitor. 918ETEXI 919 920DEF("curses", 0, QEMU_OPTION_curses, 921 "-curses use a curses/ncurses interface instead of SDL\n", 922 QEMU_ARCH_ALL) 923STEXI 924@item -curses 925@findex -curses 926Normally, QEMU uses SDL to display the VGA output. With this option, 927QEMU can display the VGA output when in text mode using a 928curses/ncurses interface. Nothing is displayed in graphical mode. 929ETEXI 930 931DEF("no-frame", 0, QEMU_OPTION_no_frame, 932 "-no-frame open SDL window without a frame and window decorations\n", 933 QEMU_ARCH_ALL) 934STEXI 935@item -no-frame 936@findex -no-frame 937Do not use decorations for SDL windows and start them using the whole 938available screen space. This makes the using QEMU in a dedicated desktop 939workspace more convenient. 940ETEXI 941 942DEF("alt-grab", 0, QEMU_OPTION_alt_grab, 943 "-alt-grab use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n", 944 QEMU_ARCH_ALL) 945STEXI 946@item -alt-grab 947@findex -alt-grab 948Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also 949affects the special keys (for fullscreen, monitor-mode switching, etc). 950ETEXI 951 952DEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab, 953 "-ctrl-grab use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n", 954 QEMU_ARCH_ALL) 955STEXI 956@item -ctrl-grab 957@findex -ctrl-grab 958Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also 959affects the special keys (for fullscreen, monitor-mode switching, etc). 960ETEXI 961 962DEF("no-quit", 0, QEMU_OPTION_no_quit, 963 "-no-quit disable SDL window close capability\n", QEMU_ARCH_ALL) 964STEXI 965@item -no-quit 966@findex -no-quit 967Disable SDL window close capability. 968ETEXI 969 970DEF("sdl", 0, QEMU_OPTION_sdl, 971 "-sdl enable SDL\n", QEMU_ARCH_ALL) 972STEXI 973@item -sdl 974@findex -sdl 975Enable SDL. 976ETEXI 977 978DEF("spice", HAS_ARG, QEMU_OPTION_spice, 979 "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n" 980 " [,x509-key-file=<file>][,x509-key-password=<file>]\n" 981 " [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n" 982 " [,x509-dh-key-file=<file>][,addr=addr][,ipv4|ipv6|unix]\n" 983 " [,tls-ciphers=<list>]\n" 984 " [,tls-channel=[main|display|cursor|inputs|record|playback]]\n" 985 " [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n" 986 " [,sasl][,password=<secret>][,disable-ticketing]\n" 987 " [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n" 988 " [,jpeg-wan-compression=[auto|never|always]]\n" 989 " [,zlib-glz-wan-compression=[auto|never|always]]\n" 990 " [,streaming-video=[off|all|filter]][,disable-copy-paste]\n" 991 " [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n" 992 " [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n" 993 " enable spice\n" 994 " at least one of {port, tls-port} is mandatory\n", 995 QEMU_ARCH_ALL) 996STEXI 997@item -spice @var{option}[,@var{option}[,...]] 998@findex -spice 999Enable the spice remote desktop protocol. Valid options are 1000 1001@table @option 1002 1003@item port=<nr> 1004Set the TCP port spice is listening on for plaintext channels. 1005 1006@item addr=<addr> 1007Set the IP address spice is listening on. Default is any address. 1008 1009@item ipv4 1010@item ipv6 1011@item unix 1012Force using the specified IP version. 1013 1014@item password=<secret> 1015Set the password you need to authenticate. 1016 1017@item sasl 1018Require that the client use SASL to authenticate with the spice. 1019The exact choice of authentication method used is controlled from the 1020system / user's SASL configuration file for the 'qemu' service. This 1021is typically found in /etc/sasl2/qemu.conf. If running QEMU as an 1022unprivileged user, an environment variable SASL_CONF_PATH can be used 1023to make it search alternate locations for the service config. 1024While some SASL auth methods can also provide data encryption (eg GSSAPI), 1025it is recommended that SASL always be combined with the 'tls' and 1026'x509' settings to enable use of SSL and server certificates. This 1027ensures a data encryption preventing compromise of authentication 1028credentials. 1029 1030@item disable-ticketing 1031Allow client connects without authentication. 1032 1033@item disable-copy-paste 1034Disable copy paste between the client and the guest. 1035 1036@item disable-agent-file-xfer 1037Disable spice-vdagent based file-xfer between the client and the guest. 1038 1039@item tls-port=<nr> 1040Set the TCP port spice is listening on for encrypted channels. 1041 1042@item x509-dir=<dir> 1043Set the x509 file directory. Expects same filenames as -vnc $display,x509=$dir 1044 1045@item x509-key-file=<file> 1046@item x509-key-password=<file> 1047@item x509-cert-file=<file> 1048@item x509-cacert-file=<file> 1049@item x509-dh-key-file=<file> 1050The x509 file names can also be configured individually. 1051 1052@item tls-ciphers=<list> 1053Specify which ciphers to use. 1054 1055@item tls-channel=[main|display|cursor|inputs|record|playback] 1056@item plaintext-channel=[main|display|cursor|inputs|record|playback] 1057Force specific channel to be used with or without TLS encryption. The 1058options can be specified multiple times to configure multiple 1059channels. The special name "default" can be used to set the default 1060mode. For channels which are not explicitly forced into one mode the 1061spice client is allowed to pick tls/plaintext as he pleases. 1062 1063@item image-compression=[auto_glz|auto_lz|quic|glz|lz|off] 1064Configure image compression (lossless). 1065Default is auto_glz. 1066 1067@item jpeg-wan-compression=[auto|never|always] 1068@item zlib-glz-wan-compression=[auto|never|always] 1069Configure wan image compression (lossy for slow links). 1070Default is auto. 1071 1072@item streaming-video=[off|all|filter] 1073Configure video stream detection. Default is filter. 1074 1075@item agent-mouse=[on|off] 1076Enable/disable passing mouse events via vdagent. Default is on. 1077 1078@item playback-compression=[on|off] 1079Enable/disable audio stream compression (using celt 0.5.1). Default is on. 1080 1081@item seamless-migration=[on|off] 1082Enable/disable spice seamless migration. Default is off. 1083 1084@end table 1085ETEXI 1086 1087DEF("portrait", 0, QEMU_OPTION_portrait, 1088 "-portrait rotate graphical output 90 deg left (only PXA LCD)\n", 1089 QEMU_ARCH_ALL) 1090STEXI 1091@item -portrait 1092@findex -portrait 1093Rotate graphical output 90 deg left (only PXA LCD). 1094ETEXI 1095 1096DEF("rotate", HAS_ARG, QEMU_OPTION_rotate, 1097 "-rotate <deg> rotate graphical output some deg left (only PXA LCD)\n", 1098 QEMU_ARCH_ALL) 1099STEXI 1100@item -rotate @var{deg} 1101@findex -rotate 1102Rotate graphical output some deg left (only PXA LCD). 1103ETEXI 1104 1105DEF("vga", HAS_ARG, QEMU_OPTION_vga, 1106 "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|none]\n" 1107 " select video card type\n", QEMU_ARCH_ALL) 1108STEXI 1109@item -vga @var{type} 1110@findex -vga 1111Select type of VGA card to emulate. Valid values for @var{type} are 1112@table @option 1113@item cirrus 1114Cirrus Logic GD5446 Video card. All Windows versions starting from 1115Windows 95 should recognize and use this graphic card. For optimal 1116performances, use 16 bit color depth in the guest and the host OS. 1117(This one is the default) 1118@item std 1119Standard VGA card with Bochs VBE extensions. If your guest OS 1120supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want 1121to use high resolution modes (>= 1280x1024x16) then you should use 1122this option. 1123@item vmware 1124VMWare SVGA-II compatible adapter. Use it if you have sufficiently 1125recent XFree86/XOrg server or Windows guest with a driver for this 1126card. 1127@item qxl 1128QXL paravirtual graphic card. It is VGA compatible (including VESA 11292.0 VBE support). Works best with qxl guest drivers installed though. 1130Recommended choice when using the spice protocol. 1131@item tcx 1132(sun4m only) Sun TCX framebuffer. This is the default framebuffer for 1133sun4m machines and offers both 8-bit and 24-bit colour depths at a 1134fixed resolution of 1024x768. 1135@item cg3 1136(sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer 1137for sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP) 1138resolutions aimed at people wishing to run older Solaris versions. 1139@item none 1140Disable VGA card. 1141@end table 1142ETEXI 1143 1144DEF("full-screen", 0, QEMU_OPTION_full_screen, 1145 "-full-screen start in full screen\n", QEMU_ARCH_ALL) 1146STEXI 1147@item -full-screen 1148@findex -full-screen 1149Start in full screen. 1150ETEXI 1151 1152DEF("g", 1, QEMU_OPTION_g , 1153 "-g WxH[xDEPTH] Set the initial graphical resolution and depth\n", 1154 QEMU_ARCH_PPC | QEMU_ARCH_SPARC) 1155STEXI 1156@item -g @var{width}x@var{height}[x@var{depth}] 1157@findex -g 1158Set the initial graphical resolution and depth (PPC, SPARC only). 1159ETEXI 1160 1161DEF("vnc", HAS_ARG, QEMU_OPTION_vnc , 1162 "-vnc display start a VNC server on display\n", QEMU_ARCH_ALL) 1163STEXI 1164@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]] 1165@findex -vnc 1166Normally, QEMU uses SDL to display the VGA output. With this option, 1167you can have QEMU listen on VNC display @var{display} and redirect the VGA 1168display over the VNC session. It is very useful to enable the usb 1169tablet device when using this option (option @option{-usbdevice 1170tablet}). When using the VNC display, you must use the @option{-k} 1171parameter to set the keyboard layout if you are not using en-us. Valid 1172syntax for the @var{display} is 1173 1174@table @option 1175 1176@item @var{host}:@var{d} 1177 1178TCP connections will only be allowed from @var{host} on display @var{d}. 1179By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can 1180be omitted in which case the server will accept connections from any host. 1181 1182@item unix:@var{path} 1183 1184Connections will be allowed over UNIX domain sockets where @var{path} is the 1185location of a unix socket to listen for connections on. 1186 1187@item none 1188 1189VNC is initialized but not started. The monitor @code{change} command 1190can be used to later start the VNC server. 1191 1192@end table 1193 1194Following the @var{display} value there may be one or more @var{option} flags 1195separated by commas. Valid options are 1196 1197@table @option 1198 1199@item reverse 1200 1201Connect to a listening VNC client via a ``reverse'' connection. The 1202client is specified by the @var{display}. For reverse network 1203connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument 1204is a TCP port number, not a display number. 1205 1206@item websocket 1207 1208Opens an additional TCP listening port dedicated to VNC Websocket connections. 1209By definition the Websocket port is 5700+@var{display}. If @var{host} is 1210specified connections will only be allowed from this host. 1211As an alternative the Websocket port could be specified by using 1212@code{websocket}=@var{port}. 1213TLS encryption for the Websocket connection is supported if the required 1214certificates are specified with the VNC option @option{x509}. 1215 1216@item password 1217 1218Require that password based authentication is used for client connections. 1219 1220The password must be set separately using the @code{set_password} command in 1221the @ref{pcsys_monitor}. The syntax to change your password is: 1222@code{set_password <protocol> <password>} where <protocol> could be either 1223"vnc" or "spice". 1224 1225If you would like to change <protocol> password expiration, you should use 1226@code{expire_password <protocol> <expiration-time>} where expiration time could 1227be one of the following options: now, never, +seconds or UNIX time of 1228expiration, e.g. +60 to make password expire in 60 seconds, or 1335196800 1229to make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this 1230date and time). 1231 1232You can also use keywords "now" or "never" for the expiration time to 1233allow <protocol> password to expire immediately or never expire. 1234 1235@item tls 1236 1237Require that client use TLS when communicating with the VNC server. This 1238uses anonymous TLS credentials so is susceptible to a man-in-the-middle 1239attack. It is recommended that this option be combined with either the 1240@option{x509} or @option{x509verify} options. 1241 1242@item x509=@var{/path/to/certificate/dir} 1243 1244Valid if @option{tls} is specified. Require that x509 credentials are used 1245for negotiating the TLS session. The server will send its x509 certificate 1246to the client. It is recommended that a password be set on the VNC server 1247to provide authentication of the client when this is used. The path following 1248this option specifies where the x509 certificates are to be loaded from. 1249See the @ref{vnc_security} section for details on generating certificates. 1250 1251@item x509verify=@var{/path/to/certificate/dir} 1252 1253Valid if @option{tls} is specified. Require that x509 credentials are used 1254for negotiating the TLS session. The server will send its x509 certificate 1255to the client, and request that the client send its own x509 certificate. 1256The server will validate the client's certificate against the CA certificate, 1257and reject clients when validation fails. If the certificate authority is 1258trusted, this is a sufficient authentication mechanism. You may still wish 1259to set a password on the VNC server as a second authentication layer. The 1260path following this option specifies where the x509 certificates are to 1261be loaded from. See the @ref{vnc_security} section for details on generating 1262certificates. 1263 1264@item sasl 1265 1266Require that the client use SASL to authenticate with the VNC server. 1267The exact choice of authentication method used is controlled from the 1268system / user's SASL configuration file for the 'qemu' service. This 1269is typically found in /etc/sasl2/qemu.conf. If running QEMU as an 1270unprivileged user, an environment variable SASL_CONF_PATH can be used 1271to make it search alternate locations for the service config. 1272While some SASL auth methods can also provide data encryption (eg GSSAPI), 1273it is recommended that SASL always be combined with the 'tls' and 1274'x509' settings to enable use of SSL and server certificates. This 1275ensures a data encryption preventing compromise of authentication 1276credentials. See the @ref{vnc_security} section for details on using 1277SASL authentication. 1278 1279@item acl 1280 1281Turn on access control lists for checking of the x509 client certificate 1282and SASL party. For x509 certs, the ACL check is made against the 1283certificate's distinguished name. This is something that looks like 1284@code{C=GB,O=ACME,L=Boston,CN=bob}. For SASL party, the ACL check is 1285made against the username, which depending on the SASL plugin, may 1286include a realm component, eg @code{bob} or @code{bob@@EXAMPLE.COM}. 1287When the @option{acl} flag is set, the initial access list will be 1288empty, with a @code{deny} policy. Thus no one will be allowed to 1289use the VNC server until the ACLs have been loaded. This can be 1290achieved using the @code{acl} monitor command. 1291 1292@item lossy 1293 1294Enable lossy compression methods (gradient, JPEG, ...). If this 1295option is set, VNC client may receive lossy framebuffer updates 1296depending on its encoding settings. Enabling this option can save 1297a lot of bandwidth at the expense of quality. 1298 1299@item non-adaptive 1300 1301Disable adaptive encodings. Adaptive encodings are enabled by default. 1302An adaptive encoding will try to detect frequently updated screen regions, 1303and send updates in these regions using a lossy encoding (like JPEG). 1304This can be really helpful to save bandwidth when playing videos. Disabling 1305adaptive encodings restores the original static behavior of encodings 1306like Tight. 1307 1308@item share=[allow-exclusive|force-shared|ignore] 1309 1310Set display sharing policy. 'allow-exclusive' allows clients to ask 1311for exclusive access. As suggested by the rfb spec this is 1312implemented by dropping other connections. Connecting multiple 1313clients in parallel requires all clients asking for a shared session 1314(vncviewer: -shared switch). This is the default. 'force-shared' 1315disables exclusive client access. Useful for shared desktop sessions, 1316where you don't want someone forgetting specify -shared disconnect 1317everybody else. 'ignore' completely ignores the shared flag and 1318allows everybody connect unconditionally. Doesn't conform to the rfb 1319spec but is traditional QEMU behavior. 1320 1321@end table 1322ETEXI 1323 1324STEXI 1325@end table 1326ETEXI 1327ARCHHEADING(, QEMU_ARCH_I386) 1328 1329ARCHHEADING(i386 target only:, QEMU_ARCH_I386) 1330STEXI 1331@table @option 1332ETEXI 1333 1334DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack, 1335 "-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n", 1336 QEMU_ARCH_I386) 1337STEXI 1338@item -win2k-hack 1339@findex -win2k-hack 1340Use it when installing Windows 2000 to avoid a disk full bug. After 1341Windows 2000 is installed, you no longer need this option (this option 1342slows down the IDE transfers). 1343ETEXI 1344 1345HXCOMM Deprecated by -rtc 1346DEF("rtc-td-hack", 0, QEMU_OPTION_rtc_td_hack, "", QEMU_ARCH_I386) 1347 1348DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk, 1349 "-no-fd-bootchk disable boot signature checking for floppy disks\n", 1350 QEMU_ARCH_I386) 1351STEXI 1352@item -no-fd-bootchk 1353@findex -no-fd-bootchk 1354Disable boot signature checking for floppy disks in BIOS. May 1355be needed to boot from old floppy disks. 1356ETEXI 1357 1358DEF("no-acpi", 0, QEMU_OPTION_no_acpi, 1359 "-no-acpi disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM) 1360STEXI 1361@item -no-acpi 1362@findex -no-acpi 1363Disable ACPI (Advanced Configuration and Power Interface) support. Use 1364it if your guest OS complains about ACPI problems (PC target machine 1365only). 1366ETEXI 1367 1368DEF("no-hpet", 0, QEMU_OPTION_no_hpet, 1369 "-no-hpet disable HPET\n", QEMU_ARCH_I386) 1370STEXI 1371@item -no-hpet 1372@findex -no-hpet 1373Disable HPET support. 1374ETEXI 1375 1376DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable, 1377 "-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" 1378 " ACPI table description\n", QEMU_ARCH_I386) 1379STEXI 1380@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}]...] 1381@findex -acpitable 1382Add ACPI table with specified header fields and context from specified files. 1383For file=, take whole ACPI table from the specified files, including all 1384ACPI headers (possible overridden by other options). 1385For data=, only data 1386portion of the table is used, all header information is specified in the 1387command line. 1388ETEXI 1389 1390DEF("smbios", HAS_ARG, QEMU_OPTION_smbios, 1391 "-smbios file=binary\n" 1392 " load SMBIOS entry from binary file\n" 1393 "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n" 1394 " [,uefi=on|off]\n" 1395 " specify SMBIOS type 0 fields\n" 1396 "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n" 1397 " [,uuid=uuid][,sku=str][,family=str]\n" 1398 " specify SMBIOS type 1 fields\n" 1399 "-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]\n" 1400 " [,asset=str][,location=str]\n" 1401 " specify SMBIOS type 2 fields\n" 1402 "-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]\n" 1403 " [,sku=str]\n" 1404 " specify SMBIOS type 3 fields\n" 1405 "-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]\n" 1406 " [,asset=str][,part=str]\n" 1407 " specify SMBIOS type 4 fields\n" 1408 "-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n" 1409 " [,asset=str][,part=str][,speed=%d]\n" 1410 " specify SMBIOS type 17 fields\n", 1411 QEMU_ARCH_I386) 1412STEXI 1413@item -smbios file=@var{binary} 1414@findex -smbios 1415Load SMBIOS entry from binary file. 1416 1417@item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}][,uefi=on|off] 1418Specify SMBIOS type 0 fields 1419 1420@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}] 1421Specify SMBIOS type 1 fields 1422 1423@item -smbios type=2[,manufacturer=@var{str}][,product=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,location=@var{str}][,family=@var{str}] 1424Specify SMBIOS type 2 fields 1425 1426@item -smbios type=3[,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,sku=@var{str}] 1427Specify SMBIOS type 3 fields 1428 1429@item -smbios type=4[,sock_pfx=@var{str}][,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,part=@var{str}] 1430Specify SMBIOS type 4 fields 1431 1432@item -smbios type=17[,loc_pfx=@var{str}][,bank=@var{str}][,manufacturer=@var{str}][,serial=@var{str}][,asset=@var{str}][,part=@var{str}][,speed=@var{%d}] 1433Specify SMBIOS type 17 fields 1434ETEXI 1435 1436STEXI 1437@end table 1438ETEXI 1439DEFHEADING() 1440 1441DEFHEADING(Network options:) 1442STEXI 1443@table @option 1444ETEXI 1445 1446HXCOMM Legacy slirp options (now moved to -net user): 1447#ifdef CONFIG_SLIRP 1448DEF("tftp", HAS_ARG, QEMU_OPTION_tftp, "", QEMU_ARCH_ALL) 1449DEF("bootp", HAS_ARG, QEMU_OPTION_bootp, "", QEMU_ARCH_ALL) 1450DEF("redir", HAS_ARG, QEMU_OPTION_redir, "", QEMU_ARCH_ALL) 1451#ifndef _WIN32 1452DEF("smb", HAS_ARG, QEMU_OPTION_smb, "", QEMU_ARCH_ALL) 1453#endif 1454#endif 1455 1456DEF("netdev", HAS_ARG, QEMU_OPTION_netdev, 1457#ifdef CONFIG_SLIRP 1458 "-netdev user,id=str[,net=addr[/mask]][,host=addr][,restrict=on|off]\n" 1459 " [,hostname=host][,dhcpstart=addr][,dns=addr][,dnssearch=domain][,tftp=dir]\n" 1460 " [,bootfile=f][,hostfwd=rule][,guestfwd=rule]" 1461#ifndef _WIN32 1462 "[,smb=dir[,smbserver=addr]]\n" 1463#endif 1464 " configure a user mode network backend with ID 'str',\n" 1465 " its DHCP server and optional services\n" 1466#endif 1467#ifdef _WIN32 1468 "-netdev tap,id=str,ifname=name\n" 1469 " configure a host TAP network backend with ID 'str'\n" 1470#else 1471 "-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n" 1472 " [,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n" 1473 " [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n" 1474 " configure a host TAP network backend with ID 'str'\n" 1475 " use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n" 1476 " to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n" 1477 " to deconfigure it\n" 1478 " use '[down]script=no' to disable script execution\n" 1479 " use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n" 1480 " configure it\n" 1481 " use 'fd=h' to connect to an already opened TAP interface\n" 1482 " use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n" 1483 " use 'sndbuf=nbytes' to limit the size of the send buffer (the\n" 1484 " default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n" 1485 " use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n" 1486 " use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n" 1487 " use vhost=on to enable experimental in kernel accelerator\n" 1488 " (only has effect for virtio guests which use MSIX)\n" 1489 " use vhostforce=on to force vhost on for non-MSIX virtio guests\n" 1490 " use 'vhostfd=h' to connect to an already opened vhost net device\n" 1491 " use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n" 1492 " use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n" 1493 "-netdev bridge,id=str[,br=bridge][,helper=helper]\n" 1494 " configure a host TAP network backend with ID 'str' that is\n" 1495 " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n" 1496 " using the program 'helper (default=" DEFAULT_BRIDGE_HELPER ")\n" 1497#endif 1498#ifdef __linux__ 1499 "-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n" 1500 " [,rxsession=rxsession],txsession=txsession[,ipv6=on/off][,udp=on/off]\n" 1501 " [,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie]\n" 1502 " [,rxcookie=rxcookie][,offset=offset]\n" 1503 " configure a network backend with ID 'str' connected to\n" 1504 " an Ethernet over L2TPv3 pseudowire.\n" 1505 " Linux kernel 3.3+ as well as most routers can talk\n" 1506 " L2TPv3. This transport allows connecting a VM to a VM,\n" 1507 " VM to a router and even VM to Host. It is a nearly-universal\n" 1508 " standard (RFC3391). Note - this implementation uses static\n" 1509 " pre-configured tunnels (same as the Linux kernel).\n" 1510 " use 'src=' to specify source address\n" 1511 " use 'dst=' to specify destination address\n" 1512 " use 'udp=on' to specify udp encapsulation\n" 1513 " use 'srcport=' to specify source udp port\n" 1514 " use 'dstport=' to specify destination udp port\n" 1515 " use 'ipv6=on' to force v6\n" 1516 " L2TPv3 uses cookies to prevent misconfiguration as\n" 1517 " well as a weak security measure\n" 1518 " use 'rxcookie=0x012345678' to specify a rxcookie\n" 1519 " use 'txcookie=0x012345678' to specify a txcookie\n" 1520 " use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n" 1521 " use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n" 1522 " use 'pincounter=on' to work around broken counter handling in peer\n" 1523 " use 'offset=X' to add an extra offset between header and data\n" 1524#endif 1525 "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n" 1526 " configure a network backend to connect to another network\n" 1527 " using a socket connection\n" 1528 "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n" 1529 " configure a network backend to connect to a multicast maddr and port\n" 1530 " use 'localaddr=addr' to specify the host address to send packets from\n" 1531 "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n" 1532 " configure a network backend to connect to another network\n" 1533 " using an UDP tunnel\n" 1534#ifdef CONFIG_VDE 1535 "-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n" 1536 " configure a network backend to connect to port 'n' of a vde switch\n" 1537 " running on host and listening for incoming connections on 'socketpath'.\n" 1538 " Use group 'groupname' and mode 'octalmode' to change default\n" 1539 " ownership and permissions for communication port.\n" 1540#endif 1541#ifdef CONFIG_NETMAP 1542 "-netdev netmap,id=str,ifname=name[,devname=nmname]\n" 1543 " attach to the existing netmap-enabled network interface 'name', or to a\n" 1544 " VALE port (created on the fly) called 'name' ('nmname' is name of the \n" 1545 " netmap device, defaults to '/dev/netmap')\n" 1546#endif 1547 "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n" 1548 " configure a vhost-user network, backed by a chardev 'dev'\n" 1549 "-netdev hubport,id=str,hubid=n\n" 1550 " configure a hub port on QEMU VLAN 'n'\n", QEMU_ARCH_ALL) 1551DEF("net", HAS_ARG, QEMU_OPTION_net, 1552 "-net nic[,vlan=n][,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n" 1553 " old way to create a new NIC and connect it to VLAN 'n'\n" 1554 " (use the '-device devtype,netdev=str' option if possible instead)\n" 1555 "-net dump[,vlan=n][,file=f][,len=n]\n" 1556 " dump traffic on vlan 'n' to file 'f' (max n bytes per packet)\n" 1557 "-net none use it alone to have zero network devices. If no -net option\n" 1558 " is provided, the default is '-net nic -net user'\n" 1559 "-net [" 1560#ifdef CONFIG_SLIRP 1561 "user|" 1562#endif 1563 "tap|" 1564 "bridge|" 1565#ifdef CONFIG_VDE 1566 "vde|" 1567#endif 1568#ifdef CONFIG_NETMAP 1569 "netmap|" 1570#endif 1571 "socket][,vlan=n][,option][,option][,...]\n" 1572 " old way to initialize a host network interface\n" 1573 " (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL) 1574STEXI 1575@item -net nic[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}] 1576@findex -net 1577Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n} 1578= 0 is the default). The NIC is an e1000 by default on the PC 1579target. Optionally, the MAC address can be changed to @var{mac}, the 1580device address set to @var{addr} (PCI cards only), 1581and a @var{name} can be assigned for use in monitor commands. 1582Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors 1583that the card should have; this option currently only affects virtio cards; set 1584@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single 1585NIC is created. QEMU can emulate several different models of network card. 1586Valid values for @var{type} are 1587@code{virtio}, @code{i82551}, @code{i82557b}, @code{i82559er}, 1588@code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139}, 1589@code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}. 1590Not all devices are supported on all targets. Use @code{-net nic,model=help} 1591for a list of available devices for your target. 1592 1593@item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...] 1594@findex -netdev 1595@item -net user[,@var{option}][,@var{option}][,...] 1596Use the user mode network stack which requires no administrator 1597privilege to run. Valid options are: 1598 1599@table @option 1600@item vlan=@var{n} 1601Connect user mode stack to VLAN @var{n} (@var{n} = 0 is the default). 1602 1603@item id=@var{id} 1604@item name=@var{name} 1605Assign symbolic name for use in monitor commands. 1606 1607@item net=@var{addr}[/@var{mask}] 1608Set IP network address the guest will see. Optionally specify the netmask, 1609either in the form a.b.c.d or as number of valid top-most bits. Default is 161010.0.2.0/24. 1611 1612@item host=@var{addr} 1613Specify the guest-visible address of the host. Default is the 2nd IP in the 1614guest network, i.e. x.x.x.2. 1615 1616@item restrict=on|off 1617If this option is enabled, the guest will be isolated, i.e. it will not be 1618able to contact the host and no guest IP packets will be routed over the host 1619to the outside. This option does not affect any explicitly set forwarding rules. 1620 1621@item hostname=@var{name} 1622Specifies the client hostname reported by the built-in DHCP server. 1623 1624@item dhcpstart=@var{addr} 1625Specify the first of the 16 IPs the built-in DHCP server can assign. Default 1626is the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31. 1627 1628@item dns=@var{addr} 1629Specify the guest-visible address of the virtual nameserver. The address must 1630be different from the host address. Default is the 3rd IP in the guest network, 1631i.e. x.x.x.3. 1632 1633@item dnssearch=@var{domain} 1634Provides an entry for the domain-search list sent by the built-in 1635DHCP server. More than one domain suffix can be transmitted by specifying 1636this option multiple times. If supported, this will cause the guest to 1637automatically try to append the given domain suffix(es) in case a domain name 1638can not be resolved. 1639 1640Example: 1641@example 1642qemu -net user,dnssearch=mgmt.example.org,dnssearch=example.org [...] 1643@end example 1644 1645@item tftp=@var{dir} 1646When using the user mode network stack, activate a built-in TFTP 1647server. The files in @var{dir} will be exposed as the root of a TFTP server. 1648The TFTP client on the guest must be configured in binary mode (use the command 1649@code{bin} of the Unix TFTP client). 1650 1651@item bootfile=@var{file} 1652When using the user mode network stack, broadcast @var{file} as the BOOTP 1653filename. In conjunction with @option{tftp}, this can be used to network boot 1654a guest from a local directory. 1655 1656Example (using pxelinux): 1657@example 1658qemu-system-i386 -hda linux.img -boot n -net user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0 1659@end example 1660 1661@item smb=@var{dir}[,smbserver=@var{addr}] 1662When using the user mode network stack, activate a built-in SMB 1663server so that Windows OSes can access to the host files in @file{@var{dir}} 1664transparently. The IP address of the SMB server can be set to @var{addr}. By 1665default the 4th IP in the guest network is used, i.e. x.x.x.4. 1666 1667In the guest Windows OS, the line: 1668@example 166910.0.2.4 smbserver 1670@end example 1671must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me) 1672or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000). 1673 1674Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}. 1675 1676Note that a SAMBA server must be installed on the host OS. 1677QEMU was tested successfully with smbd versions from Red Hat 9, 1678Fedora Core 3 and OpenSUSE 11.x. 1679 1680@item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport} 1681Redirect incoming TCP or UDP connections to the host port @var{hostport} to 1682the guest IP address @var{guestaddr} on guest port @var{guestport}. If 1683@var{guestaddr} is not specified, its value is x.x.x.15 (default first address 1684given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can 1685be bound to a specific host interface. If no connection type is set, TCP is 1686used. This option can be given multiple times. 1687 1688For example, to redirect host X11 connection from screen 1 to guest 1689screen 0, use the following: 1690 1691@example 1692# on the host 1693qemu-system-i386 -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...] 1694# this host xterm should open in the guest X11 server 1695xterm -display :1 1696@end example 1697 1698To redirect telnet connections from host port 5555 to telnet port on 1699the guest, use the following: 1700 1701@example 1702# on the host 1703qemu-system-i386 -net user,hostfwd=tcp::5555-:23 [...] 1704telnet localhost 5555 1705@end example 1706 1707Then when you use on the host @code{telnet localhost 5555}, you 1708connect to the guest telnet server. 1709 1710@item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev} 1711@item guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command} 1712Forward guest TCP connections to the IP address @var{server} on port @var{port} 1713to the character device @var{dev} or to a program executed by @var{cmd:command} 1714which gets spawned for each connection. This option can be given multiple times. 1715 1716You can either use a chardev directly and have that one used throughout QEMU's 1717lifetime, like in the following example: 1718 1719@example 1720# open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever 1721# the guest accesses it 1722qemu -net user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 [...] 1723@end example 1724 1725Or you can execute a command on every TCP connection established by the guest, 1726so that QEMU behaves similar to an inetd process for that virtual server: 1727 1728@example 1729# call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234 1730# and connect the TCP stream to its stdin/stdout 1731qemu -net 'user,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321' 1732@end example 1733 1734@end table 1735 1736Note: Legacy stand-alone options -tftp, -bootp, -smb and -redir are still 1737processed and applied to -net user. Mixing them with the new configuration 1738syntax gives undefined results. Their use for new applications is discouraged 1739as they will be removed from future versions. 1740 1741@item -netdev tap,id=@var{id}[,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,helper=@var{helper}] 1742@item -net tap[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,helper=@var{helper}] 1743Connect the host TAP network interface @var{name} to VLAN @var{n}. 1744 1745Use the network script @var{file} to configure it and the network script 1746@var{dfile} to deconfigure it. If @var{name} is not provided, the OS 1747automatically provides one. The default network configure script is 1748@file{/etc/qemu-ifup} and the default network deconfigure script is 1749@file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no} 1750to disable script execution. 1751 1752If running QEMU as an unprivileged user, use the network helper 1753@var{helper} to configure the TAP interface. The default network 1754helper executable is @file{/path/to/qemu-bridge-helper}. 1755 1756@option{fd}=@var{h} can be used to specify the handle of an already 1757opened host TAP interface. 1758 1759Examples: 1760 1761@example 1762#launch a QEMU instance with the default network script 1763qemu-system-i386 linux.img -net nic -net tap 1764@end example 1765 1766@example 1767#launch a QEMU instance with two NICs, each one connected 1768#to a TAP device 1769qemu-system-i386 linux.img \ 1770 -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \ 1771 -net nic,vlan=1 -net tap,vlan=1,ifname=tap1 1772@end example 1773 1774@example 1775#launch a QEMU instance with the default network helper to 1776#connect a TAP device to bridge br0 1777qemu-system-i386 linux.img \ 1778 -net nic -net tap,"helper=/path/to/qemu-bridge-helper" 1779@end example 1780 1781@item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}] 1782@item -net bridge[,vlan=@var{n}][,name=@var{name}][,br=@var{bridge}][,helper=@var{helper}] 1783Connect a host TAP network interface to a host bridge device. 1784 1785Use the network helper @var{helper} to configure the TAP interface and 1786attach it to the bridge. The default network helper executable is 1787@file{/path/to/qemu-bridge-helper} and the default bridge 1788device is @file{br0}. 1789 1790Examples: 1791 1792@example 1793#launch a QEMU instance with the default network helper to 1794#connect a TAP device to bridge br0 1795qemu-system-i386 linux.img -net bridge -net nic,model=virtio 1796@end example 1797 1798@example 1799#launch a QEMU instance with the default network helper to 1800#connect a TAP device to bridge qemubr0 1801qemu-system-i386 linux.img -net bridge,br=qemubr0 -net nic,model=virtio 1802@end example 1803 1804@item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}] 1805@item -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}] [,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}] 1806 1807Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual 1808machine using a TCP socket connection. If @option{listen} is 1809specified, QEMU waits for incoming connections on @var{port} 1810(@var{host} is optional). @option{connect} is used to connect to 1811another QEMU instance using the @option{listen} option. @option{fd}=@var{h} 1812specifies an already opened TCP socket. 1813 1814Example: 1815@example 1816# launch a first QEMU instance 1817qemu-system-i386 linux.img \ 1818 -net nic,macaddr=52:54:00:12:34:56 \ 1819 -net socket,listen=:1234 1820# connect the VLAN 0 of this instance to the VLAN 0 1821# of the first instance 1822qemu-system-i386 linux.img \ 1823 -net nic,macaddr=52:54:00:12:34:57 \ 1824 -net socket,connect=127.0.0.1:1234 1825@end example 1826 1827@item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]] 1828@item -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]] 1829 1830Create a VLAN @var{n} shared with another QEMU virtual 1831machines using a UDP multicast socket, effectively making a bus for 1832every QEMU with same multicast address @var{maddr} and @var{port}. 1833NOTES: 1834@enumerate 1835@item 1836Several QEMU can be running on different hosts and share same bus (assuming 1837correct multicast setup for these hosts). 1838@item 1839mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see 1840@url{http://user-mode-linux.sf.net}. 1841@item 1842Use @option{fd=h} to specify an already opened UDP multicast socket. 1843@end enumerate 1844 1845Example: 1846@example 1847# launch one QEMU instance 1848qemu-system-i386 linux.img \ 1849 -net nic,macaddr=52:54:00:12:34:56 \ 1850 -net socket,mcast=230.0.0.1:1234 1851# launch another QEMU instance on same "bus" 1852qemu-system-i386 linux.img \ 1853 -net nic,macaddr=52:54:00:12:34:57 \ 1854 -net socket,mcast=230.0.0.1:1234 1855# launch yet another QEMU instance on same "bus" 1856qemu-system-i386 linux.img \ 1857 -net nic,macaddr=52:54:00:12:34:58 \ 1858 -net socket,mcast=230.0.0.1:1234 1859@end example 1860 1861Example (User Mode Linux compat.): 1862@example 1863# launch QEMU instance (note mcast address selected 1864# is UML's default) 1865qemu-system-i386 linux.img \ 1866 -net nic,macaddr=52:54:00:12:34:56 \ 1867 -net socket,mcast=239.192.168.1:1102 1868# launch UML 1869/path/to/linux ubd0=/path/to/root_fs eth0=mcast 1870@end example 1871 1872Example (send packets from host's 1.2.3.4): 1873@example 1874qemu-system-i386 linux.img \ 1875 -net nic,macaddr=52:54:00:12:34:56 \ 1876 -net socket,mcast=239.192.168.1:1102,localaddr=1.2.3.4 1877@end example 1878 1879@item -netdev l2tpv3,id=@var{id},src=@var{srcaddr},dst=@var{dstaddr}[,srcport=@var{srcport}][,dstport=@var{dstport}],txsession=@var{txsession}[,rxsession=@var{rxsession}][,ipv6][,udp][,cookie64][,counter][,pincounter][,txcookie=@var{txcookie}][,rxcookie=@var{rxcookie}][,offset=@var{offset}] 1880@item -net l2tpv3[,vlan=@var{n}][,name=@var{name}],src=@var{srcaddr},dst=@var{dstaddr}[,srcport=@var{srcport}][,dstport=@var{dstport}],txsession=@var{txsession}[,rxsession=@var{rxsession}][,ipv6][,udp][,cookie64][,counter][,pincounter][,txcookie=@var{txcookie}][,rxcookie=@var{rxcookie}][,offset=@var{offset}] 1881Connect VLAN @var{n} to L2TPv3 pseudowire. L2TPv3 (RFC3391) is a popular 1882protocol to transport Ethernet (and other Layer 2) data frames between 1883two systems. It is present in routers, firewalls and the Linux kernel 1884(from version 3.3 onwards). 1885 1886This transport allows a VM to communicate to another VM, router or firewall directly. 1887 1888@item src=@var{srcaddr} 1889 source address (mandatory) 1890@item dst=@var{dstaddr} 1891 destination address (mandatory) 1892@item udp 1893 select udp encapsulation (default is ip). 1894@item srcport=@var{srcport} 1895 source udp port. 1896@item dstport=@var{dstport} 1897 destination udp port. 1898@item ipv6 1899 force v6, otherwise defaults to v4. 1900@item rxcookie=@var{rxcookie} 1901@item txcookie=@var{txcookie} 1902 Cookies are a weak form of security in the l2tpv3 specification. 1903Their function is mostly to prevent misconfiguration. By default they are 32 1904bit. 1905@item cookie64 1906 Set cookie size to 64 bit instead of the default 32 1907@item counter=off 1908 Force a 'cut-down' L2TPv3 with no counter as in 1909draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00 1910@item pincounter=on 1911 Work around broken counter handling in peer. This may also help on 1912networks which have packet reorder. 1913@item offset=@var{offset} 1914 Add an extra offset between header and data 1915 1916For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan 1917on the remote Linux host 1.2.3.4: 1918@example 1919# Setup tunnel on linux host using raw ip as encapsulation 1920# on 1.2.3.4 1921ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \ 1922 encap udp udp_sport 16384 udp_dport 16384 1923ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \ 1924 0xFFFFFFFF peer_session_id 0xFFFFFFFF 1925ifconfig vmtunnel0 mtu 1500 1926ifconfig vmtunnel0 up 1927brctl addif br-lan vmtunnel0 1928 1929 1930# on 4.3.2.1 1931# launch QEMU instance - if your network has reorder or is very lossy add ,pincounter 1932 1933qemu-system-i386 linux.img -net nic -net l2tpv3,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter 1934 1935 1936@end example 1937 1938@item -netdev vde,id=@var{id}[,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}] 1939@item -net vde[,vlan=@var{n}][,name=@var{name}][,sock=@var{socketpath}] [,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}] 1940Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and 1941listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname} 1942and MODE @var{octalmode} to change default ownership and permissions for 1943communication port. This option is only available if QEMU has been compiled 1944with vde support enabled. 1945 1946Example: 1947@example 1948# launch vde switch 1949vde_switch -F -sock /tmp/myswitch 1950# launch QEMU instance 1951qemu-system-i386 linux.img -net nic -net vde,sock=/tmp/myswitch 1952@end example 1953 1954@item -netdev hubport,id=@var{id},hubid=@var{hubid} 1955 1956Create a hub port on QEMU "vlan" @var{hubid}. 1957 1958The hubport netdev lets you connect a NIC to a QEMU "vlan" instead of a single 1959netdev. @code{-net} and @code{-device} with parameter @option{vlan} create the 1960required hub automatically. 1961 1962@item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off][,queues=n] 1963 1964Establish a vhost-user netdev, backed by a chardev @var{id}. The chardev should 1965be a unix domain socket backed one. The vhost-user uses a specifically defined 1966protocol to pass vhost ioctl replacement messages to an application on the other 1967end of the socket. On non-MSIX guests, the feature can be forced with 1968@var{vhostforce}. Use 'queues=@var{n}' to specify the number of queues to 1969be created for multiqueue vhost-user. 1970 1971Example: 1972@example 1973qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \ 1974 -numa node,memdev=mem \ 1975 -chardev socket,path=/path/to/socket \ 1976 -netdev type=vhost-user,id=net0,chardev=chr0 \ 1977 -device virtio-net-pci,netdev=net0 1978@end example 1979 1980@item -net dump[,vlan=@var{n}][,file=@var{file}][,len=@var{len}] 1981Dump network traffic on VLAN @var{n} to file @var{file} (@file{qemu-vlan0.pcap} by default). 1982At most @var{len} bytes (64k by default) per packet are stored. The file format is 1983libpcap, so it can be analyzed with tools such as tcpdump or Wireshark. 1984 1985@item -net none 1986Indicate that no network devices should be configured. It is used to 1987override the default configuration (@option{-net nic -net user}) which 1988is activated if no @option{-net} options are provided. 1989ETEXI 1990 1991STEXI 1992@end table 1993ETEXI 1994DEFHEADING() 1995 1996DEFHEADING(Character device options:) 1997STEXI 1998 1999The general form of a character device option is: 2000@table @option 2001ETEXI 2002 2003DEF("chardev", HAS_ARG, QEMU_OPTION_chardev, 2004 "-chardev null,id=id[,mux=on|off]\n" 2005 "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4][,ipv6][,nodelay][,reconnect=seconds]\n" 2006 " [,server][,nowait][,telnet][,reconnect=seconds][,mux=on|off] (tcp)\n" 2007 "-chardev socket,id=id,path=path[,server][,nowait][,telnet][,reconnect=seconds][,mux=on|off] (unix)\n" 2008 "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n" 2009 " [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n" 2010 "-chardev msmouse,id=id[,mux=on|off]\n" 2011 "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n" 2012 " [,mux=on|off]\n" 2013 "-chardev ringbuf,id=id[,size=size]\n" 2014 "-chardev file,id=id,path=path[,mux=on|off]\n" 2015 "-chardev pipe,id=id,path=path[,mux=on|off]\n" 2016#ifdef _WIN32 2017 "-chardev console,id=id[,mux=on|off]\n" 2018 "-chardev serial,id=id,path=path[,mux=on|off]\n" 2019#else 2020 "-chardev pty,id=id[,mux=on|off]\n" 2021 "-chardev stdio,id=id[,mux=on|off][,signal=on|off]\n" 2022#endif 2023#ifdef CONFIG_BRLAPI 2024 "-chardev braille,id=id[,mux=on|off]\n" 2025#endif 2026#if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \ 2027 || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__) 2028 "-chardev serial,id=id,path=path[,mux=on|off]\n" 2029 "-chardev tty,id=id,path=path[,mux=on|off]\n" 2030#endif 2031#if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__) 2032 "-chardev parallel,id=id,path=path[,mux=on|off]\n" 2033 "-chardev parport,id=id,path=path[,mux=on|off]\n" 2034#endif 2035#if defined(CONFIG_SPICE) 2036 "-chardev spicevmc,id=id,name=name[,debug=debug]\n" 2037 "-chardev spiceport,id=id,name=name[,debug=debug]\n" 2038#endif 2039 , QEMU_ARCH_ALL 2040) 2041 2042STEXI 2043@item -chardev @var{backend} ,id=@var{id} [,mux=on|off] [,@var{options}] 2044@findex -chardev 2045Backend is one of: 2046@option{null}, 2047@option{socket}, 2048@option{udp}, 2049@option{msmouse}, 2050@option{vc}, 2051@option{ringbuf}, 2052@option{file}, 2053@option{pipe}, 2054@option{console}, 2055@option{serial}, 2056@option{pty}, 2057@option{stdio}, 2058@option{braille}, 2059@option{tty}, 2060@option{parallel}, 2061@option{parport}, 2062@option{spicevmc}. 2063@option{spiceport}. 2064The specific backend will determine the applicable options. 2065 2066All devices must have an id, which can be any string up to 127 characters long. 2067It is used to uniquely identify this device in other command line directives. 2068 2069A character device may be used in multiplexing mode by multiple front-ends. 2070The key sequence of @key{Control-a} and @key{c} will rotate the input focus 2071between attached front-ends. Specify @option{mux=on} to enable this mode. 2072 2073Options to each backend are described below. 2074 2075@item -chardev null ,id=@var{id} 2076A void device. This device will not emit any data, and will drop any data it 2077receives. The null backend does not take any options. 2078 2079@item -chardev socket ,id=@var{id} [@var{TCP options} or @var{unix options}] [,server] [,nowait] [,telnet] [,reconnect=@var{seconds}] 2080 2081Create a two-way stream socket, which can be either a TCP or a unix socket. A 2082unix socket will be created if @option{path} is specified. Behaviour is 2083undefined if TCP options are specified for a unix socket. 2084 2085@option{server} specifies that the socket shall be a listening socket. 2086 2087@option{nowait} specifies that QEMU should not block waiting for a client to 2088connect to a listening socket. 2089 2090@option{telnet} specifies that traffic on the socket should interpret telnet 2091escape sequences. 2092 2093@option{reconnect} sets the timeout for reconnecting on non-server sockets when 2094the remote end goes away. qemu will delay this many seconds and then attempt 2095to reconnect. Zero disables reconnecting, and is the default. 2096 2097TCP and unix socket options are given below: 2098 2099@table @option 2100 2101@item TCP options: port=@var{port} [,host=@var{host}] [,to=@var{to}] [,ipv4] [,ipv6] [,nodelay] 2102 2103@option{host} for a listening socket specifies the local address to be bound. 2104For a connecting socket species the remote host to connect to. @option{host} is 2105optional for listening sockets. If not specified it defaults to @code{0.0.0.0}. 2106 2107@option{port} for a listening socket specifies the local port to be bound. For a 2108connecting socket specifies the port on the remote host to connect to. 2109@option{port} can be given as either a port number or a service name. 2110@option{port} is required. 2111 2112@option{to} is only relevant to listening sockets. If it is specified, and 2113@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up 2114to and including @option{to} until it succeeds. @option{to} must be specified 2115as a port number. 2116 2117@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used. 2118If neither is specified the socket may use either protocol. 2119 2120@option{nodelay} disables the Nagle algorithm. 2121 2122@item unix options: path=@var{path} 2123 2124@option{path} specifies the local path of the unix socket. @option{path} is 2125required. 2126 2127@end table 2128 2129@item -chardev udp ,id=@var{id} [,host=@var{host}] ,port=@var{port} [,localaddr=@var{localaddr}] [,localport=@var{localport}] [,ipv4] [,ipv6] 2130 2131Sends all traffic from the guest to a remote host over UDP. 2132 2133@option{host} specifies the remote host to connect to. If not specified it 2134defaults to @code{localhost}. 2135 2136@option{port} specifies the port on the remote host to connect to. @option{port} 2137is required. 2138 2139@option{localaddr} specifies the local address to bind to. If not specified it 2140defaults to @code{0.0.0.0}. 2141 2142@option{localport} specifies the local port to bind to. If not specified any 2143available local port will be used. 2144 2145@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used. 2146If neither is specified the device may use either protocol. 2147 2148@item -chardev msmouse ,id=@var{id} 2149 2150Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not 2151take any options. 2152 2153@item -chardev vc ,id=@var{id} [[,width=@var{width}] [,height=@var{height}]] [[,cols=@var{cols}] [,rows=@var{rows}]] 2154 2155Connect to a QEMU text console. @option{vc} may optionally be given a specific 2156size. 2157 2158@option{width} and @option{height} specify the width and height respectively of 2159the console, in pixels. 2160 2161@option{cols} and @option{rows} specify that the console be sized to fit a text 2162console with the given dimensions. 2163 2164@item -chardev ringbuf ,id=@var{id} [,size=@var{size}] 2165 2166Create a ring buffer with fixed size @option{size}. 2167@var{size} must be a power of two, and defaults to @code{64K}). 2168 2169@item -chardev file ,id=@var{id} ,path=@var{path} 2170 2171Log all traffic received from the guest to a file. 2172 2173@option{path} specifies the path of the file to be opened. This file will be 2174created if it does not already exist, and overwritten if it does. @option{path} 2175is required. 2176 2177@item -chardev pipe ,id=@var{id} ,path=@var{path} 2178 2179Create a two-way connection to the guest. The behaviour differs slightly between 2180Windows hosts and other hosts: 2181 2182On Windows, a single duplex pipe will be created at 2183@file{\\.pipe\@option{path}}. 2184 2185On other hosts, 2 pipes will be created called @file{@option{path}.in} and 2186@file{@option{path}.out}. Data written to @file{@option{path}.in} will be 2187received by the guest. Data written by the guest can be read from 2188@file{@option{path}.out}. QEMU will not create these fifos, and requires them to 2189be present. 2190 2191@option{path} forms part of the pipe path as described above. @option{path} is 2192required. 2193 2194@item -chardev console ,id=@var{id} 2195 2196Send traffic from the guest to QEMU's standard output. @option{console} does not 2197take any options. 2198 2199@option{console} is only available on Windows hosts. 2200 2201@item -chardev serial ,id=@var{id} ,path=@option{path} 2202 2203Send traffic from the guest to a serial device on the host. 2204 2205On Unix hosts serial will actually accept any tty device, 2206not only serial lines. 2207 2208@option{path} specifies the name of the serial device to open. 2209 2210@item -chardev pty ,id=@var{id} 2211 2212Create a new pseudo-terminal on the host and connect to it. @option{pty} does 2213not take any options. 2214 2215@option{pty} is not available on Windows hosts. 2216 2217@item -chardev stdio ,id=@var{id} [,signal=on|off] 2218Connect to standard input and standard output of the QEMU process. 2219 2220@option{signal} controls if signals are enabled on the terminal, that includes 2221exiting QEMU with the key sequence @key{Control-c}. This option is enabled by 2222default, use @option{signal=off} to disable it. 2223 2224@option{stdio} is not available on Windows hosts. 2225 2226@item -chardev braille ,id=@var{id} 2227 2228Connect to a local BrlAPI server. @option{braille} does not take any options. 2229 2230@item -chardev tty ,id=@var{id} ,path=@var{path} 2231 2232@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and 2233DragonFlyBSD hosts. It is an alias for @option{serial}. 2234 2235@option{path} specifies the path to the tty. @option{path} is required. 2236 2237@item -chardev parallel ,id=@var{id} ,path=@var{path} 2238@item -chardev parport ,id=@var{id} ,path=@var{path} 2239 2240@option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts. 2241 2242Connect to a local parallel port. 2243 2244@option{path} specifies the path to the parallel port device. @option{path} is 2245required. 2246 2247@item -chardev spicevmc ,id=@var{id} ,debug=@var{debug}, name=@var{name} 2248 2249@option{spicevmc} is only available when spice support is built in. 2250 2251@option{debug} debug level for spicevmc 2252 2253@option{name} name of spice channel to connect to 2254 2255Connect to a spice virtual machine channel, such as vdiport. 2256 2257@item -chardev spiceport ,id=@var{id} ,debug=@var{debug}, name=@var{name} 2258 2259@option{spiceport} is only available when spice support is built in. 2260 2261@option{debug} debug level for spicevmc 2262 2263@option{name} name of spice port to connect to 2264 2265Connect to a spice port, allowing a Spice client to handle the traffic 2266identified by a name (preferably a fqdn). 2267ETEXI 2268 2269STEXI 2270@end table 2271ETEXI 2272DEFHEADING() 2273 2274DEFHEADING(Device URL Syntax:) 2275STEXI 2276 2277In addition to using normal file images for the emulated storage devices, 2278QEMU can also use networked resources such as iSCSI devices. These are 2279specified using a special URL syntax. 2280 2281@table @option 2282@item iSCSI 2283iSCSI support allows QEMU to access iSCSI resources directly and use as 2284images for the guest storage. Both disk and cdrom images are supported. 2285 2286Syntax for specifying iSCSI LUNs is 2287``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>'' 2288 2289By default qemu will use the iSCSI initiator-name 2290'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from the command 2291line or a configuration file. 2292 2293 2294Example (without authentication): 2295@example 2296qemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \ 2297 -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \ 2298 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 2299@end example 2300 2301Example (CHAP username/password via URL): 2302@example 2303qemu-system-i386 -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1 2304@end example 2305 2306Example (CHAP username/password via environment variables): 2307@example 2308LIBISCSI_CHAP_USERNAME="user" \ 2309LIBISCSI_CHAP_PASSWORD="password" \ 2310qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 2311@end example 2312 2313iSCSI support is an optional feature of QEMU and only available when 2314compiled and linked against libiscsi. 2315ETEXI 2316DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi, 2317 "-iscsi [user=user][,password=password]\n" 2318 " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n" 2319 " [,initiator-name=initiator-iqn][,id=target-iqn]\n" 2320 " iSCSI session parameters\n", QEMU_ARCH_ALL) 2321STEXI 2322 2323iSCSI parameters such as username and password can also be specified via 2324a configuration file. See qemu-doc for more information and examples. 2325 2326@item NBD 2327QEMU supports NBD (Network Block Devices) both using TCP protocol as well 2328as Unix Domain Sockets. 2329 2330Syntax for specifying a NBD device using TCP 2331``nbd:<server-ip>:<port>[:exportname=<export>]'' 2332 2333Syntax for specifying a NBD device using Unix Domain Sockets 2334``nbd:unix:<domain-socket>[:exportname=<export>]'' 2335 2336 2337Example for TCP 2338@example 2339qemu-system-i386 --drive file=nbd:192.0.2.1:30000 2340@end example 2341 2342Example for Unix Domain Sockets 2343@example 2344qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket 2345@end example 2346 2347@item SSH 2348QEMU supports SSH (Secure Shell) access to remote disks. 2349 2350Examples: 2351@example 2352qemu-system-i386 -drive file=ssh://user@@host/path/to/disk.img 2353qemu-system-i386 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img 2354@end example 2355 2356Currently authentication must be done using ssh-agent. Other 2357authentication methods may be supported in future. 2358 2359@item Sheepdog 2360Sheepdog is a distributed storage system for QEMU. 2361QEMU supports using either local sheepdog devices or remote networked 2362devices. 2363 2364Syntax for specifying a sheepdog device 2365@example 2366sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag] 2367@end example 2368 2369Example 2370@example 2371qemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine 2372@end example 2373 2374See also @url{http://http://www.osrg.net/sheepdog/}. 2375 2376@item GlusterFS 2377GlusterFS is an user space distributed file system. 2378QEMU supports the use of GlusterFS volumes for hosting VM disk images using 2379TCP, Unix Domain Sockets and RDMA transport protocols. 2380 2381Syntax for specifying a VM disk image on GlusterFS volume is 2382@example 2383gluster[+transport]://[server[:port]]/volname/image[?socket=...] 2384@end example 2385 2386 2387Example 2388@example 2389qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img 2390@end example 2391 2392See also @url{http://www.gluster.org}. 2393 2394@item HTTP/HTTPS/FTP/FTPS/TFTP 2395QEMU supports read-only access to files accessed over http(s), ftp(s) and tftp. 2396 2397Syntax using a single filename: 2398@example 2399<protocol>://[<username>[:<password>]@@]<host>/<path> 2400@end example 2401 2402where: 2403@table @option 2404@item protocol 2405'http', 'https', 'ftp', 'ftps', or 'tftp'. 2406 2407@item username 2408Optional username for authentication to the remote server. 2409 2410@item password 2411Optional password for authentication to the remote server. 2412 2413@item host 2414Address of the remote server. 2415 2416@item path 2417Path on the remote server, including any query string. 2418@end table 2419 2420The following options are also supported: 2421@table @option 2422@item url 2423The full URL when passing options to the driver explicitly. 2424 2425@item readahead 2426The amount of data to read ahead with each range request to the remote server. 2427This value may optionally have the suffix 'T', 'G', 'M', 'K', 'k' or 'b'. If it 2428does not have a suffix, it will be assumed to be in bytes. The value must be a 2429multiple of 512 bytes. It defaults to 256k. 2430 2431@item sslverify 2432Whether to verify the remote server's certificate when connecting over SSL. It 2433can have the value 'on' or 'off'. It defaults to 'on'. 2434 2435@item cookie 2436Send this cookie (it can also be a list of cookies separated by ';') with 2437each outgoing request. Only supported when using protocols such as HTTP 2438which support cookies, otherwise ignored. 2439 2440@item timeout 2441Set the timeout in seconds of the CURL connection. This timeout is the time 2442that CURL waits for a response from the remote server to get the size of the 2443image to be downloaded. If not set, the default timeout of 5 seconds is used. 2444@end table 2445 2446Note that when passing options to qemu explicitly, @option{driver} is the value 2447of <protocol>. 2448 2449Example: boot from a remote Fedora 20 live ISO image 2450@example 2451qemu-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 2452 2453qemu-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 2454@end example 2455 2456Example: boot from a remote Fedora 20 cloud image using a local overlay for 2457writes, copy-on-read, and a readahead of 64k 2458@example 2459qemu-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 2460 2461qemu-system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on 2462@end example 2463 2464Example: boot from an image stored on a VMware vSphere server with a self-signed 2465certificate using a local overlay for writes, a readahead of 64k and a timeout 2466of 10 seconds. 2467@example 2468qemu-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 2469 2470qemu-system-x86_64 -drive file=/tmp/test.qcow2 2471@end example 2472ETEXI 2473 2474STEXI 2475@end table 2476ETEXI 2477 2478DEFHEADING(Bluetooth(R) options:) 2479STEXI 2480@table @option 2481ETEXI 2482 2483DEF("bt", HAS_ARG, QEMU_OPTION_bt, \ 2484 "-bt hci,null dumb bluetooth HCI - doesn't respond to commands\n" \ 2485 "-bt hci,host[:id]\n" \ 2486 " use host's HCI with the given name\n" \ 2487 "-bt hci[,vlan=n]\n" \ 2488 " emulate a standard HCI in virtual scatternet 'n'\n" \ 2489 "-bt vhci[,vlan=n]\n" \ 2490 " add host computer to virtual scatternet 'n' using VHCI\n" \ 2491 "-bt device:dev[,vlan=n]\n" \ 2492 " emulate a bluetooth device 'dev' in scatternet 'n'\n", 2493 QEMU_ARCH_ALL) 2494STEXI 2495@item -bt hci[...] 2496@findex -bt 2497Defines the function of the corresponding Bluetooth HCI. -bt options 2498are matched with the HCIs present in the chosen machine type. For 2499example when emulating a machine with only one HCI built into it, only 2500the first @code{-bt hci[...]} option is valid and defines the HCI's 2501logic. The Transport Layer is decided by the machine type. Currently 2502the machines @code{n800} and @code{n810} have one HCI and all other 2503machines have none. 2504 2505@anchor{bt-hcis} 2506The following three types are recognized: 2507 2508@table @option 2509@item -bt hci,null 2510(default) The corresponding Bluetooth HCI assumes no internal logic 2511and will not respond to any HCI commands or emit events. 2512 2513@item -bt hci,host[:@var{id}] 2514(@code{bluez} only) The corresponding HCI passes commands / events 2515to / from the physical HCI identified by the name @var{id} (default: 2516@code{hci0}) on the computer running QEMU. Only available on @code{bluez} 2517capable systems like Linux. 2518 2519@item -bt hci[,vlan=@var{n}] 2520Add a virtual, standard HCI that will participate in the Bluetooth 2521scatternet @var{n} (default @code{0}). Similarly to @option{-net} 2522VLANs, devices inside a bluetooth network @var{n} can only communicate 2523with other devices in the same network (scatternet). 2524@end table 2525 2526@item -bt vhci[,vlan=@var{n}] 2527(Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached 2528to the host bluetooth stack instead of to the emulated target. This 2529allows the host and target machines to participate in a common scatternet 2530and communicate. Requires the Linux @code{vhci} driver installed. Can 2531be used as following: 2532 2533@example 2534qemu-system-i386 [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5 2535@end example 2536 2537@item -bt device:@var{dev}[,vlan=@var{n}] 2538Emulate a bluetooth device @var{dev} and place it in network @var{n} 2539(default @code{0}). QEMU can only emulate one type of bluetooth devices 2540currently: 2541 2542@table @option 2543@item keyboard 2544Virtual wireless keyboard implementing the HIDP bluetooth profile. 2545@end table 2546ETEXI 2547 2548STEXI 2549@end table 2550ETEXI 2551DEFHEADING() 2552 2553#ifdef CONFIG_TPM 2554DEFHEADING(TPM device options:) 2555 2556DEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \ 2557 "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n" 2558 " use path to provide path to a character device; default is /dev/tpm0\n" 2559 " use cancel-path to provide path to TPM's cancel sysfs entry; if\n" 2560 " not provided it will be searched for in /sys/class/misc/tpm?/device\n", 2561 QEMU_ARCH_ALL) 2562STEXI 2563 2564The general form of a TPM device option is: 2565@table @option 2566 2567@item -tpmdev @var{backend} ,id=@var{id} [,@var{options}] 2568@findex -tpmdev 2569Backend type must be: 2570@option{passthrough}. 2571 2572The specific backend type will determine the applicable options. 2573The @code{-tpmdev} option creates the TPM backend and requires a 2574@code{-device} option that specifies the TPM frontend interface model. 2575 2576Options to each backend are described below. 2577 2578Use 'help' to print all available TPM backend types. 2579@example 2580qemu -tpmdev help 2581@end example 2582 2583@item -tpmdev passthrough, id=@var{id}, path=@var{path}, cancel-path=@var{cancel-path} 2584 2585(Linux-host only) Enable access to the host's TPM using the passthrough 2586driver. 2587 2588@option{path} specifies the path to the host's TPM device, i.e., on 2589a Linux host this would be @code{/dev/tpm0}. 2590@option{path} is optional and by default @code{/dev/tpm0} is used. 2591 2592@option{cancel-path} specifies the path to the host TPM device's sysfs 2593entry allowing for cancellation of an ongoing TPM command. 2594@option{cancel-path} is optional and by default QEMU will search for the 2595sysfs entry to use. 2596 2597Some notes about using the host's TPM with the passthrough driver: 2598 2599The TPM device accessed by the passthrough driver must not be 2600used by any other application on the host. 2601 2602Since the host's firmware (BIOS/UEFI) has already initialized the TPM, 2603the VM's firmware (BIOS/UEFI) will not be able to initialize the 2604TPM again and may therefore not show a TPM-specific menu that would 2605otherwise allow the user to configure the TPM, e.g., allow the user to 2606enable/disable or activate/deactivate the TPM. 2607Further, if TPM ownership is released from within a VM then the host's TPM 2608will get disabled and deactivated. To enable and activate the 2609TPM again afterwards, the host has to be rebooted and the user is 2610required to enter the firmware's menu to enable and activate the TPM. 2611If the TPM is left disabled and/or deactivated most TPM commands will fail. 2612 2613To create a passthrough TPM use the following two options: 2614@example 2615-tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0 2616@end example 2617Note that the @code{-tpmdev} id is @code{tpm0} and is referenced by 2618@code{tpmdev=tpm0} in the device option. 2619 2620@end table 2621 2622ETEXI 2623 2624DEFHEADING() 2625 2626#endif 2627 2628DEFHEADING(Linux/Multiboot boot specific:) 2629STEXI 2630 2631When using these options, you can use a given Linux or Multiboot 2632kernel without installing it in the disk image. It can be useful 2633for easier testing of various kernels. 2634 2635@table @option 2636ETEXI 2637 2638DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \ 2639 "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL) 2640STEXI 2641@item -kernel @var{bzImage} 2642@findex -kernel 2643Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel 2644or in multiboot format. 2645ETEXI 2646 2647DEF("append", HAS_ARG, QEMU_OPTION_append, \ 2648 "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL) 2649STEXI 2650@item -append @var{cmdline} 2651@findex -append 2652Use @var{cmdline} as kernel command line 2653ETEXI 2654 2655DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \ 2656 "-initrd file use 'file' as initial ram disk\n", QEMU_ARCH_ALL) 2657STEXI 2658@item -initrd @var{file} 2659@findex -initrd 2660Use @var{file} as initial ram disk. 2661 2662@item -initrd "@var{file1} arg=foo,@var{file2}" 2663 2664This syntax is only available with multiboot. 2665 2666Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the 2667first module. 2668ETEXI 2669 2670DEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \ 2671 "-dtb file use 'file' as device tree image\n", QEMU_ARCH_ALL) 2672STEXI 2673@item -dtb @var{file} 2674@findex -dtb 2675Use @var{file} as a device tree binary (dtb) image and pass it to the kernel 2676on boot. 2677ETEXI 2678 2679STEXI 2680@end table 2681ETEXI 2682DEFHEADING() 2683 2684DEFHEADING(Debug/Expert options:) 2685STEXI 2686@table @option 2687ETEXI 2688 2689DEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg, 2690 "-fw_cfg [name=]<name>,file=<file>\n" 2691 " add named fw_cfg entry from file\n", 2692 QEMU_ARCH_ALL) 2693STEXI 2694@item -fw_cfg [name=]@var{name},file=@var{file} 2695@findex -fw_cfg 2696Add named fw_cfg entry from file. @var{name} determines the name of 2697the entry in the fw_cfg file directory exposed to the guest. 2698ETEXI 2699 2700DEF("serial", HAS_ARG, QEMU_OPTION_serial, \ 2701 "-serial dev redirect the serial port to char device 'dev'\n", 2702 QEMU_ARCH_ALL) 2703STEXI 2704@item -serial @var{dev} 2705@findex -serial 2706Redirect the virtual serial port to host character device 2707@var{dev}. The default device is @code{vc} in graphical mode and 2708@code{stdio} in non graphical mode. 2709 2710This option can be used several times to simulate up to 4 serial 2711ports. 2712 2713Use @code{-serial none} to disable all serial ports. 2714 2715Available character devices are: 2716@table @option 2717@item vc[:@var{W}x@var{H}] 2718Virtual console. Optionally, a width and height can be given in pixel with 2719@example 2720vc:800x600 2721@end example 2722It is also possible to specify width or height in characters: 2723@example 2724vc:80Cx24C 2725@end example 2726@item pty 2727[Linux only] Pseudo TTY (a new PTY is automatically allocated) 2728@item none 2729No device is allocated. 2730@item null 2731void device 2732@item chardev:@var{id} 2733Use a named character device defined with the @code{-chardev} option. 2734@item /dev/XXX 2735[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port 2736parameters are set according to the emulated ones. 2737@item /dev/parport@var{N} 2738[Linux only, parallel port only] Use host parallel port 2739@var{N}. Currently SPP and EPP parallel port features can be used. 2740@item file:@var{filename} 2741Write output to @var{filename}. No character can be read. 2742@item stdio 2743[Unix only] standard input/output 2744@item pipe:@var{filename} 2745name pipe @var{filename} 2746@item COM@var{n} 2747[Windows only] Use host serial port @var{n} 2748@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}] 2749This implements UDP Net Console. 2750When @var{remote_host} or @var{src_ip} are not specified 2751they default to @code{0.0.0.0}. 2752When not using a specified @var{src_port} a random port is automatically chosen. 2753 2754If you just want a simple readonly console you can use @code{netcat} or 2755@code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as: 2756@code{nc -u -l -p 4555}. Any time QEMU writes something to that port it 2757will appear in the netconsole session. 2758 2759If you plan to send characters back via netconsole or you want to stop 2760and start QEMU a lot of times, you should have QEMU use the same 2761source port each time by using something like @code{-serial 2762udp::4555@@:4556} to QEMU. Another approach is to use a patched 2763version of netcat which can listen to a TCP port and send and receive 2764characters via udp. If you have a patched version of netcat which 2765activates telnet remote echo and single char transfer, then you can 2766use the following options to step up a netcat redirector to allow 2767telnet on port 5555 to access the QEMU port. 2768@table @code 2769@item QEMU Options: 2770-serial udp::4555@@:4556 2771@item netcat options: 2772-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T 2773@item telnet options: 2774localhost 5555 2775@end table 2776 2777@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}] 2778The TCP Net Console has two modes of operation. It can send the serial 2779I/O to a location or wait for a connection from a location. By default 2780the TCP Net Console is sent to @var{host} at the @var{port}. If you use 2781the @var{server} option QEMU will wait for a client socket application 2782to connect to the port before continuing, unless the @code{nowait} 2783option was specified. The @code{nodelay} option disables the Nagle buffering 2784algorithm. The @code{reconnect} option only applies if @var{noserver} is 2785set, if the connection goes down it will attempt to reconnect at the 2786given interval. If @var{host} is omitted, 0.0.0.0 is assumed. Only 2787one TCP connection at a time is accepted. You can use @code{telnet} to 2788connect to the corresponding character device. 2789@table @code 2790@item Example to send tcp console to 192.168.0.2 port 4444 2791-serial tcp:192.168.0.2:4444 2792@item Example to listen and wait on port 4444 for connection 2793-serial tcp::4444,server 2794@item Example to not wait and listen on ip 192.168.0.100 port 4444 2795-serial tcp:192.168.0.100:4444,server,nowait 2796@end table 2797 2798@item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay] 2799The telnet protocol is used instead of raw tcp sockets. The options 2800work the same as if you had specified @code{-serial tcp}. The 2801difference is that the port acts like a telnet server or client using 2802telnet option negotiation. This will also allow you to send the 2803MAGIC_SYSRQ sequence if you use a telnet that supports sending the break 2804sequence. Typically in unix telnet you do it with Control-] and then 2805type "send break" followed by pressing the enter key. 2806 2807@item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}] 2808A unix domain socket is used instead of a tcp socket. The option works the 2809same as if you had specified @code{-serial tcp} except the unix domain socket 2810@var{path} is used for connections. 2811 2812@item mon:@var{dev_string} 2813This is a special option to allow the monitor to be multiplexed onto 2814another serial port. The monitor is accessed with key sequence of 2815@key{Control-a} and then pressing @key{c}. 2816@var{dev_string} should be any one of the serial devices specified 2817above. An example to multiplex the monitor onto a telnet server 2818listening on port 4444 would be: 2819@table @code 2820@item -serial mon:telnet::4444,server,nowait 2821@end table 2822When the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate 2823QEMU any more but will be passed to the guest instead. 2824 2825@item braille 2826Braille device. This will use BrlAPI to display the braille output on a real 2827or fake device. 2828 2829@item msmouse 2830Three button serial mouse. Configure the guest to use Microsoft protocol. 2831@end table 2832ETEXI 2833 2834DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \ 2835 "-parallel dev redirect the parallel port to char device 'dev'\n", 2836 QEMU_ARCH_ALL) 2837STEXI 2838@item -parallel @var{dev} 2839@findex -parallel 2840Redirect the virtual parallel port to host device @var{dev} (same 2841devices as the serial port). On Linux hosts, @file{/dev/parportN} can 2842be used to use hardware devices connected on the corresponding host 2843parallel port. 2844 2845This option can be used several times to simulate up to 3 parallel 2846ports. 2847 2848Use @code{-parallel none} to disable all parallel ports. 2849ETEXI 2850 2851DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \ 2852 "-monitor dev redirect the monitor to char device 'dev'\n", 2853 QEMU_ARCH_ALL) 2854STEXI 2855@item -monitor @var{dev} 2856@findex -monitor 2857Redirect the monitor to host device @var{dev} (same devices as the 2858serial port). 2859The default device is @code{vc} in graphical mode and @code{stdio} in 2860non graphical mode. 2861Use @code{-monitor none} to disable the default monitor. 2862ETEXI 2863DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \ 2864 "-qmp dev like -monitor but opens in 'control' mode\n", 2865 QEMU_ARCH_ALL) 2866STEXI 2867@item -qmp @var{dev} 2868@findex -qmp 2869Like -monitor but opens in 'control' mode. 2870ETEXI 2871DEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \ 2872 "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n", 2873 QEMU_ARCH_ALL) 2874STEXI 2875@item -qmp-pretty @var{dev} 2876@findex -qmp-pretty 2877Like -qmp but uses pretty JSON formatting. 2878ETEXI 2879 2880DEF("mon", HAS_ARG, QEMU_OPTION_mon, \ 2881 "-mon [chardev=]name[,mode=readline|control][,default]\n", QEMU_ARCH_ALL) 2882STEXI 2883@item -mon [chardev=]name[,mode=readline|control][,default] 2884@findex -mon 2885Setup monitor on chardev @var{name}. 2886ETEXI 2887 2888DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \ 2889 "-debugcon dev redirect the debug console to char device 'dev'\n", 2890 QEMU_ARCH_ALL) 2891STEXI 2892@item -debugcon @var{dev} 2893@findex -debugcon 2894Redirect the debug console to host device @var{dev} (same devices as the 2895serial port). The debug console is an I/O port which is typically port 28960xe9; writing to that I/O port sends output to this device. 2897The default device is @code{vc} in graphical mode and @code{stdio} in 2898non graphical mode. 2899ETEXI 2900 2901DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \ 2902 "-pidfile file write PID to 'file'\n", QEMU_ARCH_ALL) 2903STEXI 2904@item -pidfile @var{file} 2905@findex -pidfile 2906Store the QEMU process PID in @var{file}. It is useful if you launch QEMU 2907from a script. 2908ETEXI 2909 2910DEF("singlestep", 0, QEMU_OPTION_singlestep, \ 2911 "-singlestep always run in singlestep mode\n", QEMU_ARCH_ALL) 2912STEXI 2913@item -singlestep 2914@findex -singlestep 2915Run the emulation in single step mode. 2916ETEXI 2917 2918DEF("S", 0, QEMU_OPTION_S, \ 2919 "-S freeze CPU at startup (use 'c' to start execution)\n", 2920 QEMU_ARCH_ALL) 2921STEXI 2922@item -S 2923@findex -S 2924Do not start CPU at startup (you must type 'c' in the monitor). 2925ETEXI 2926 2927DEF("realtime", HAS_ARG, QEMU_OPTION_realtime, 2928 "-realtime [mlock=on|off]\n" 2929 " run qemu with realtime features\n" 2930 " mlock=on|off controls mlock support (default: on)\n", 2931 QEMU_ARCH_ALL) 2932STEXI 2933@item -realtime mlock=on|off 2934@findex -realtime 2935Run qemu with realtime features. 2936mlocking qemu and guest memory can be enabled via @option{mlock=on} 2937(enabled by default). 2938ETEXI 2939 2940DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \ 2941 "-gdb dev wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL) 2942STEXI 2943@item -gdb @var{dev} 2944@findex -gdb 2945Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical 2946connections will likely be TCP-based, but also UDP, pseudo TTY, or even 2947stdio are reasonable use case. The latter is allowing to start QEMU from 2948within gdb and establish the connection via a pipe: 2949@example 2950(gdb) target remote | exec qemu-system-i386 -gdb stdio ... 2951@end example 2952ETEXI 2953 2954DEF("s", 0, QEMU_OPTION_s, \ 2955 "-s shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n", 2956 QEMU_ARCH_ALL) 2957STEXI 2958@item -s 2959@findex -s 2960Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234 2961(@pxref{gdb_usage}). 2962ETEXI 2963 2964DEF("d", HAS_ARG, QEMU_OPTION_d, \ 2965 "-d item1,... enable logging of specified items (use '-d help' for a list of log items)\n", 2966 QEMU_ARCH_ALL) 2967STEXI 2968@item -d @var{item1}[,...] 2969@findex -d 2970Enable logging of specified items. Use '-d help' for a list of log items. 2971ETEXI 2972 2973DEF("D", HAS_ARG, QEMU_OPTION_D, \ 2974 "-D logfile output log to logfile (default stderr)\n", 2975 QEMU_ARCH_ALL) 2976STEXI 2977@item -D @var{logfile} 2978@findex -D 2979Output log in @var{logfile} instead of to stderr 2980ETEXI 2981 2982DEF("L", HAS_ARG, QEMU_OPTION_L, \ 2983 "-L path set the directory for the BIOS, VGA BIOS and keymaps\n", 2984 QEMU_ARCH_ALL) 2985STEXI 2986@item -L @var{path} 2987@findex -L 2988Set the directory for the BIOS, VGA BIOS and keymaps. 2989ETEXI 2990 2991DEF("bios", HAS_ARG, QEMU_OPTION_bios, \ 2992 "-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL) 2993STEXI 2994@item -bios @var{file} 2995@findex -bios 2996Set the filename for the BIOS. 2997ETEXI 2998 2999DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \ 3000 "-enable-kvm enable KVM full virtualization support\n", QEMU_ARCH_ALL) 3001STEXI 3002@item -enable-kvm 3003@findex -enable-kvm 3004Enable KVM full virtualization support. This option is only available 3005if KVM support is enabled when compiling. 3006ETEXI 3007 3008DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid, 3009 "-xen-domid id specify xen guest domain id\n", QEMU_ARCH_ALL) 3010DEF("xen-create", 0, QEMU_OPTION_xen_create, 3011 "-xen-create create domain using xen hypercalls, bypassing xend\n" 3012 " warning: should not be used when xend is in use\n", 3013 QEMU_ARCH_ALL) 3014DEF("xen-attach", 0, QEMU_OPTION_xen_attach, 3015 "-xen-attach attach to existing xen domain\n" 3016 " xend will use this when starting QEMU\n", 3017 QEMU_ARCH_ALL) 3018STEXI 3019@item -xen-domid @var{id} 3020@findex -xen-domid 3021Specify xen guest domain @var{id} (XEN only). 3022@item -xen-create 3023@findex -xen-create 3024Create domain using xen hypercalls, bypassing xend. 3025Warning: should not be used when xend is in use (XEN only). 3026@item -xen-attach 3027@findex -xen-attach 3028Attach to existing xen domain. 3029xend will use this when starting QEMU (XEN only). 3030ETEXI 3031 3032DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \ 3033 "-no-reboot exit instead of rebooting\n", QEMU_ARCH_ALL) 3034STEXI 3035@item -no-reboot 3036@findex -no-reboot 3037Exit instead of rebooting. 3038ETEXI 3039 3040DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \ 3041 "-no-shutdown stop before shutdown\n", QEMU_ARCH_ALL) 3042STEXI 3043@item -no-shutdown 3044@findex -no-shutdown 3045Don't exit QEMU on guest shutdown, but instead only stop the emulation. 3046This allows for instance switching to monitor to commit changes to the 3047disk image. 3048ETEXI 3049 3050DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \ 3051 "-loadvm [tag|id]\n" \ 3052 " start right away with a saved state (loadvm in monitor)\n", 3053 QEMU_ARCH_ALL) 3054STEXI 3055@item -loadvm @var{file} 3056@findex -loadvm 3057Start right away with a saved state (@code{loadvm} in monitor) 3058ETEXI 3059 3060#ifndef _WIN32 3061DEF("daemonize", 0, QEMU_OPTION_daemonize, \ 3062 "-daemonize daemonize QEMU after initializing\n", QEMU_ARCH_ALL) 3063#endif 3064STEXI 3065@item -daemonize 3066@findex -daemonize 3067Daemonize the QEMU process after initialization. QEMU will not detach from 3068standard IO until it is ready to receive connections on any of its devices. 3069This option is a useful way for external programs to launch QEMU without having 3070to cope with initialization race conditions. 3071ETEXI 3072 3073DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \ 3074 "-option-rom rom load a file, rom, into the option ROM space\n", 3075 QEMU_ARCH_ALL) 3076STEXI 3077@item -option-rom @var{file} 3078@findex -option-rom 3079Load the contents of @var{file} as an option ROM. 3080This option is useful to load things like EtherBoot. 3081ETEXI 3082 3083HXCOMM Silently ignored for compatibility 3084DEF("clock", HAS_ARG, QEMU_OPTION_clock, "", QEMU_ARCH_ALL) 3085 3086HXCOMM Options deprecated by -rtc 3087DEF("localtime", 0, QEMU_OPTION_localtime, "", QEMU_ARCH_ALL) 3088DEF("startdate", HAS_ARG, QEMU_OPTION_startdate, "", QEMU_ARCH_ALL) 3089 3090DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \ 3091 "-rtc [base=utc|localtime|date][,clock=host|rt|vm][,driftfix=none|slew]\n" \ 3092 " set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n", 3093 QEMU_ARCH_ALL) 3094 3095STEXI 3096 3097@item -rtc [base=utc|localtime|@var{date}][,clock=host|vm][,driftfix=none|slew] 3098@findex -rtc 3099Specify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current 3100UTC or local time, respectively. @code{localtime} is required for correct date in 3101MS-DOS or Windows. To start at a specific point in time, provide @var{date} in the 3102format @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC. 3103 3104By default the RTC is driven by the host system time. This allows using of the 3105RTC as accurate reference clock inside the guest, specifically if the host 3106time is smoothly following an accurate external reference clock, e.g. via NTP. 3107If you want to isolate the guest time from the host, you can set @option{clock} 3108to @code{rt} instead. To even prevent it from progressing during suspension, 3109you can set it to @code{vm}. 3110 3111Enable @option{driftfix} (i386 targets only) if you experience time drift problems, 3112specifically with Windows' ACPI HAL. This option will try to figure out how 3113many timer interrupts were not processed by the Windows guest and will 3114re-inject them. 3115ETEXI 3116 3117DEF("icount", HAS_ARG, QEMU_OPTION_icount, \ 3118 "-icount [shift=N|auto][,align=on|off][,sleep=no]\n" \ 3119 " enable virtual instruction counter with 2^N clock ticks per\n" \ 3120 " instruction, enable aligning the host and virtual clocks\n" \ 3121 " or disable real time cpu sleeping\n", QEMU_ARCH_ALL) 3122STEXI 3123@item -icount [shift=@var{N}|auto] 3124@findex -icount 3125Enable virtual instruction counter. The virtual cpu will execute one 3126instruction every 2^@var{N} ns of virtual time. If @code{auto} is specified 3127then the virtual cpu speed will be automatically adjusted to keep virtual 3128time within a few seconds of real time. 3129 3130When the virtual cpu is sleeping, the virtual time will advance at default 3131speed unless @option{sleep=no} is specified. 3132With @option{sleep=no}, the virtual time will jump to the next timer deadline 3133instantly whenever the virtual cpu goes to sleep mode and will not advance 3134if no timer is enabled. This behavior give deterministic execution times from 3135the guest point of view. 3136 3137Note that while this option can give deterministic behavior, it does not 3138provide cycle accurate emulation. Modern CPUs contain superscalar out of 3139order cores with complex cache hierarchies. The number of instructions 3140executed often has little or no correlation with actual performance. 3141 3142@option{align=on} will activate the delay algorithm which will try to 3143to synchronise the host clock and the virtual clock. The goal is to 3144have a guest running at the real frequency imposed by the shift option. 3145Whenever the guest clock is behind the host clock and if 3146@option{align=on} is specified then we print a message to the user 3147to inform about the delay. 3148Currently this option does not work when @option{shift} is @code{auto}. 3149Note: The sync algorithm will work for those shift values for which 3150the guest clock runs ahead of the host clock. Typically this happens 3151when the shift value is high (how high depends on the host machine). 3152ETEXI 3153 3154DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \ 3155 "-watchdog i6300esb|ib700\n" \ 3156 " enable virtual hardware watchdog [default=none]\n", 3157 QEMU_ARCH_ALL) 3158STEXI 3159@item -watchdog @var{model} 3160@findex -watchdog 3161Create a virtual hardware watchdog device. Once enabled (by a guest 3162action), the watchdog must be periodically polled by an agent inside 3163the guest or else the guest will be restarted. 3164 3165The @var{model} is the model of hardware watchdog to emulate. Choices 3166for model are: @code{ib700} (iBASE 700) which is a very simple ISA 3167watchdog with a single timer, or @code{i6300esb} (Intel 6300ESB I/O 3168controller hub) which is a much more featureful PCI-based dual-timer 3169watchdog. Choose a model for which your guest has drivers. 3170 3171Use @code{-watchdog help} to list available hardware models. Only one 3172watchdog can be enabled for a guest. 3173ETEXI 3174 3175DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \ 3176 "-watchdog-action reset|shutdown|poweroff|pause|debug|none\n" \ 3177 " action when watchdog fires [default=reset]\n", 3178 QEMU_ARCH_ALL) 3179STEXI 3180@item -watchdog-action @var{action} 3181@findex -watchdog-action 3182 3183The @var{action} controls what QEMU will do when the watchdog timer 3184expires. 3185The default is 3186@code{reset} (forcefully reset the guest). 3187Other possible actions are: 3188@code{shutdown} (attempt to gracefully shutdown the guest), 3189@code{poweroff} (forcefully poweroff the guest), 3190@code{pause} (pause the guest), 3191@code{debug} (print a debug message and continue), or 3192@code{none} (do nothing). 3193 3194Note that the @code{shutdown} action requires that the guest responds 3195to ACPI signals, which it may not be able to do in the sort of 3196situations where the watchdog would have expired, and thus 3197@code{-watchdog-action shutdown} is not recommended for production use. 3198 3199Examples: 3200 3201@table @code 3202@item -watchdog i6300esb -watchdog-action pause 3203@item -watchdog ib700 3204@end table 3205ETEXI 3206 3207DEF("echr", HAS_ARG, QEMU_OPTION_echr, \ 3208 "-echr chr set terminal escape character instead of ctrl-a\n", 3209 QEMU_ARCH_ALL) 3210STEXI 3211 3212@item -echr @var{numeric_ascii_value} 3213@findex -echr 3214Change the escape character used for switching to the monitor when using 3215monitor and serial sharing. The default is @code{0x01} when using the 3216@code{-nographic} option. @code{0x01} is equal to pressing 3217@code{Control-a}. You can select a different character from the ascii 3218control keys where 1 through 26 map to Control-a through Control-z. For 3219instance you could use the either of the following to change the escape 3220character to Control-t. 3221@table @code 3222@item -echr 0x14 3223@item -echr 20 3224@end table 3225ETEXI 3226 3227DEF("virtioconsole", HAS_ARG, QEMU_OPTION_virtiocon, \ 3228 "-virtioconsole c\n" \ 3229 " set virtio console\n", QEMU_ARCH_ALL) 3230STEXI 3231@item -virtioconsole @var{c} 3232@findex -virtioconsole 3233Set virtio console. 3234 3235This option is maintained for backward compatibility. 3236 3237Please use @code{-device virtconsole} for the new way of invocation. 3238ETEXI 3239 3240DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \ 3241 "-show-cursor show cursor\n", QEMU_ARCH_ALL) 3242STEXI 3243@item -show-cursor 3244@findex -show-cursor 3245Show cursor. 3246ETEXI 3247 3248DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \ 3249 "-tb-size n set TB size\n", QEMU_ARCH_ALL) 3250STEXI 3251@item -tb-size @var{n} 3252@findex -tb-size 3253Set TB size. 3254ETEXI 3255 3256DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \ 3257 "-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]\n" \ 3258 "-incoming rdma:host:port[,ipv4][,ipv6]\n" \ 3259 "-incoming unix:socketpath\n" \ 3260 " prepare for incoming migration, listen on\n" \ 3261 " specified protocol and socket address\n" \ 3262 "-incoming fd:fd\n" \ 3263 "-incoming exec:cmdline\n" \ 3264 " accept incoming migration on given file descriptor\n" \ 3265 " or from given external command\n" \ 3266 "-incoming defer\n" \ 3267 " wait for the URI to be specified via migrate_incoming\n", 3268 QEMU_ARCH_ALL) 3269STEXI 3270@item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6] 3271@item -incoming rdma:@var{host}:@var{port}[,ipv4][,ipv6] 3272@findex -incoming 3273Prepare for incoming migration, listen on a given tcp port. 3274 3275@item -incoming unix:@var{socketpath} 3276Prepare for incoming migration, listen on a given unix socket. 3277 3278@item -incoming fd:@var{fd} 3279Accept incoming migration from a given filedescriptor. 3280 3281@item -incoming exec:@var{cmdline} 3282Accept incoming migration as an output from specified external command. 3283 3284@item -incoming defer 3285Wait for the URI to be specified via migrate_incoming. The monitor can 3286be used to change settings (such as migration parameters) prior to issuing 3287the migrate_incoming to allow the migration to begin. 3288ETEXI 3289 3290DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \ 3291 "-nodefaults don't create default devices\n", QEMU_ARCH_ALL) 3292STEXI 3293@item -nodefaults 3294@findex -nodefaults 3295Don't create default devices. Normally, QEMU sets the default devices like serial 3296port, parallel port, virtual console, monitor device, VGA adapter, floppy and 3297CD-ROM drive and others. The @code{-nodefaults} option will disable all those 3298default devices. 3299ETEXI 3300 3301#ifndef _WIN32 3302DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \ 3303 "-chroot dir chroot to dir just before starting the VM\n", 3304 QEMU_ARCH_ALL) 3305#endif 3306STEXI 3307@item -chroot @var{dir} 3308@findex -chroot 3309Immediately before starting guest execution, chroot to the specified 3310directory. Especially useful in combination with -runas. 3311ETEXI 3312 3313#ifndef _WIN32 3314DEF("runas", HAS_ARG, QEMU_OPTION_runas, \ 3315 "-runas user change to user id user just before starting the VM\n", 3316 QEMU_ARCH_ALL) 3317#endif 3318STEXI 3319@item -runas @var{user} 3320@findex -runas 3321Immediately before starting guest execution, drop root privileges, switching 3322to the specified user. 3323ETEXI 3324 3325DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env, 3326 "-prom-env variable=value\n" 3327 " set OpenBIOS nvram variables\n", 3328 QEMU_ARCH_PPC | QEMU_ARCH_SPARC) 3329STEXI 3330@item -prom-env @var{variable}=@var{value} 3331@findex -prom-env 3332Set OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only). 3333ETEXI 3334DEF("semihosting", 0, QEMU_OPTION_semihosting, 3335 "-semihosting semihosting mode\n", 3336 QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32) 3337STEXI 3338@item -semihosting 3339@findex -semihosting 3340Enable semihosting mode (ARM, M68K, Xtensa only). 3341ETEXI 3342DEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config, 3343 "-semihosting-config [enable=on|off,]target=native|gdb|auto semihosting configuration\n", 3344QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32) 3345STEXI 3346@item -semihosting-config [enable=on|off,]target=native|gdb|auto 3347@findex -semihosting-config 3348Enable semihosting and define where the semihosting calls will be addressed, 3349to QEMU (@code{native}) or to GDB (@code{gdb}). The default is @code{auto}, which means 3350@code{gdb} during debug sessions and @code{native} otherwise (ARM, M68K, Xtensa only). 3351ETEXI 3352DEF("old-param", 0, QEMU_OPTION_old_param, 3353 "-old-param old param mode\n", QEMU_ARCH_ARM) 3354STEXI 3355@item -old-param 3356@findex -old-param (ARM) 3357Old param mode (ARM only). 3358ETEXI 3359 3360DEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \ 3361 "-sandbox <arg> Enable seccomp mode 2 system call filter (default 'off').\n", 3362 QEMU_ARCH_ALL) 3363STEXI 3364@item -sandbox @var{arg} 3365@findex -sandbox 3366Enable Seccomp mode 2 system call filter. 'on' will enable syscall filtering and 'off' will 3367disable it. The default is 'off'. 3368ETEXI 3369 3370DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig, 3371 "-readconfig <file>\n", QEMU_ARCH_ALL) 3372STEXI 3373@item -readconfig @var{file} 3374@findex -readconfig 3375Read device configuration from @var{file}. This approach is useful when you want to spawn 3376QEMU process with many command line options but you don't want to exceed the command line 3377character limit. 3378ETEXI 3379DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig, 3380 "-writeconfig <file>\n" 3381 " read/write config file\n", QEMU_ARCH_ALL) 3382STEXI 3383@item -writeconfig @var{file} 3384@findex -writeconfig 3385Write device configuration to @var{file}. The @var{file} can be either filename to save 3386command line and device configuration into file or dash @code{-}) character to print the 3387output to stdout. This can be later used as input file for @code{-readconfig} option. 3388ETEXI 3389DEF("nodefconfig", 0, QEMU_OPTION_nodefconfig, 3390 "-nodefconfig\n" 3391 " do not load default config files at startup\n", 3392 QEMU_ARCH_ALL) 3393STEXI 3394@item -nodefconfig 3395@findex -nodefconfig 3396Normally QEMU loads configuration files from @var{sysconfdir} and @var{datadir} at startup. 3397The @code{-nodefconfig} option will prevent QEMU from loading any of those config files. 3398ETEXI 3399DEF("no-user-config", 0, QEMU_OPTION_nouserconfig, 3400 "-no-user-config\n" 3401 " do not load user-provided config files at startup\n", 3402 QEMU_ARCH_ALL) 3403STEXI 3404@item -no-user-config 3405@findex -no-user-config 3406The @code{-no-user-config} option makes QEMU not load any of the user-provided 3407config files on @var{sysconfdir}, but won't make it skip the QEMU-provided config 3408files from @var{datadir}. 3409ETEXI 3410DEF("trace", HAS_ARG, QEMU_OPTION_trace, 3411 "-trace [events=<file>][,file=<file>]\n" 3412 " specify tracing options\n", 3413 QEMU_ARCH_ALL) 3414STEXI 3415HXCOMM This line is not accurate, as some sub-options are backend-specific but 3416HXCOMM HX does not support conditional compilation of text. 3417@item -trace [events=@var{file}][,file=@var{file}] 3418@findex -trace 3419 3420Specify tracing options. 3421 3422@table @option 3423@item events=@var{file} 3424Immediately enable events listed in @var{file}. 3425The file must contain one event name (as listed in the @var{trace-events} file) 3426per line. 3427This option is only available if QEMU has been compiled with 3428either @var{simple} or @var{stderr} tracing backend. 3429@item file=@var{file} 3430Log output traces to @var{file}. 3431 3432This option is only available if QEMU has been compiled with 3433the @var{simple} tracing backend. 3434@end table 3435ETEXI 3436 3437HXCOMM Internal use 3438DEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL) 3439DEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL) 3440 3441#ifdef __linux__ 3442DEF("enable-fips", 0, QEMU_OPTION_enablefips, 3443 "-enable-fips enable FIPS 140-2 compliance\n", 3444 QEMU_ARCH_ALL) 3445#endif 3446STEXI 3447@item -enable-fips 3448@findex -enable-fips 3449Enable FIPS 140-2 compliance mode. 3450ETEXI 3451 3452HXCOMM Deprecated by -machine accel=tcg property 3453DEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386) 3454 3455HXCOMM Deprecated by kvm-pit driver properties 3456DEF("no-kvm-pit-reinjection", 0, QEMU_OPTION_no_kvm_pit_reinjection, 3457 "", QEMU_ARCH_I386) 3458 3459HXCOMM Deprecated (ignored) 3460DEF("no-kvm-pit", 0, QEMU_OPTION_no_kvm_pit, "", QEMU_ARCH_I386) 3461 3462HXCOMM Deprecated by -machine kernel_irqchip=on|off property 3463DEF("no-kvm-irqchip", 0, QEMU_OPTION_no_kvm_irqchip, "", QEMU_ARCH_I386) 3464 3465HXCOMM Deprecated (ignored) 3466DEF("tdf", 0, QEMU_OPTION_tdf,"", QEMU_ARCH_ALL) 3467 3468DEF("object", HAS_ARG, QEMU_OPTION_object, 3469 "-object TYPENAME[,PROP1=VALUE1,...]\n" 3470 " create an new object of type TYPENAME setting properties\n" 3471 " in the order they are specified. Note that the 'id'\n" 3472 " property must be set. These objects are placed in the\n" 3473 " '/objects' path.\n", 3474 QEMU_ARCH_ALL) 3475STEXI 3476@item -object @var{typename}[,@var{prop1}=@var{value1},...] 3477@findex -object 3478Create an new object of type @var{typename} setting properties 3479in the order they are specified. Note that the 'id' 3480property must be set. These objects are placed in the 3481'/objects' path. 3482ETEXI 3483 3484DEF("msg", HAS_ARG, QEMU_OPTION_msg, 3485 "-msg timestamp[=on|off]\n" 3486 " change the format of messages\n" 3487 " on|off controls leading timestamps (default:on)\n", 3488 QEMU_ARCH_ALL) 3489STEXI 3490@item -msg timestamp[=on|off] 3491@findex -msg 3492prepend a timestamp to each log message.(default:on) 3493ETEXI 3494 3495DEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate, 3496 "-dump-vmstate <file>\n" 3497 " Output vmstate information in JSON format to file.\n" 3498 " Use the scripts/vmstate-static-checker.py file to\n" 3499 " check for possible regressions in migration code\n" 3500 " by comparing two such vmstate dumps.", 3501 QEMU_ARCH_ALL) 3502STEXI 3503@item -dump-vmstate @var{file} 3504@findex -dump-vmstate 3505Dump json-encoded vmstate information for current machine type to file 3506in @var{file} 3507ETEXI 3508 3509HXCOMM This is the last statement. Insert new options before this line! 3510STEXI 3511@end table 3512ETEXI 3513
