qemu-options.hx

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