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