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