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