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