1HXCOMM Use DEFHEADING() to define headings in both help text and texi 2HXCOMM Text between STEXI and ETEXI are copied to texi version and 3HXCOMM discarded from C version 4HXCOMM DEF(option, HAS_ARG/0, opt_enum, opt_help, arch_mask) is used to 5HXCOMM construct option structures, enums and help message for specified 6HXCOMM architectures. 7HXCOMM HXCOMM can be used for comments, discarded from both texi and C 8 9DEFHEADING(Standard options:) 10STEXI 11@table @option 12ETEXI 13 14DEF("help", 0, QEMU_OPTION_h, 15 "-h or -help display this help and exit\n", QEMU_ARCH_ALL) 16STEXI 17@item -h 18@findex -h 19Display help and exit 20ETEXI 21 22DEF("version", 0, QEMU_OPTION_version, 23 "-version display version information and exit\n", QEMU_ARCH_ALL) 24STEXI 25@item -version 26@findex -version 27Display version information and exit 28ETEXI 29 30DEF("machine", HAS_ARG, QEMU_OPTION_machine, \ 31 "-machine [type=]name[,prop[=value][,...]]\n" 32 " selects emulated machine ('-machine help' for list)\n" 33 " property accel=accel1[:accel2[:...]] selects accelerator\n" 34 " supported accelerators are kvm, xen, hax, hvf, whpx or tcg (default: tcg)\n" 35 " kernel_irqchip=on|off|split controls accelerated irqchip support (default=off)\n" 36 " vmport=on|off|auto controls emulation of vmport (default: auto)\n" 37 " kvm_shadow_mem=size of KVM shadow MMU in bytes\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 " igd-passthru=on|off controls IGD GFX passthrough 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 " nvdimm=on|off controls NVDIMM support (default=off)\n" 45 " enforce-config-section=on|off enforce configuration section migration (default=off)\n" 46 " memory-encryption=@var{} memory encryption object to use (default=none)\n", 47 QEMU_ARCH_ALL) 48STEXI 49@item -machine [type=]@var{name}[,prop=@var{value}[,...]] 50@findex -machine 51Select the emulated machine by @var{name}. Use @code{-machine help} to list 52available machines. 53 54For architectures which aim to support live migration compatibility 55across releases, each release will introduce a new versioned machine 56type. For example, the 2.8.0 release introduced machine types 57``pc-i440fx-2.8'' and ``pc-q35-2.8'' for the x86_64/i686 architectures. 58 59To allow live migration of guests from QEMU version 2.8.0, to QEMU 60version 2.9.0, the 2.9.0 version must support the ``pc-i440fx-2.8'' 61and ``pc-q35-2.8'' machines too. To allow users live migrating VMs 62to skip multiple intermediate releases when upgrading, new releases 63of QEMU will support machine types from many previous versions. 64 65Supported machine properties are: 66@table @option 67@item accel=@var{accels1}[:@var{accels2}[:...]] 68This is used to enable an accelerator. Depending on the target architecture, 69kvm, xen, hax, hvf, whpx or tcg can be available. By default, tcg is used. If there is 70more than one accelerator specified, the next one is used if the previous one 71fails to initialize. 72@item kernel_irqchip=on|off 73Controls in-kernel irqchip support for the chosen accelerator when available. 74@item gfx_passthru=on|off 75Enables IGD GFX passthrough support for the chosen machine when available. 76@item vmport=on|off|auto 77Enables emulation of VMWare IO port, for vmmouse etc. auto says to select the 78value based on accel. For accel=xen the default is off otherwise the default 79is on. 80@item kvm_shadow_mem=size 81Defines the size of the KVM shadow MMU. 82@item dump-guest-core=on|off 83Include guest memory in a core dump. The default is on. 84@item mem-merge=on|off 85Enables or disables memory merge support. This feature, when supported by 86the host, de-duplicates identical memory pages among VMs instances 87(enabled by default). 88@item aes-key-wrap=on|off 89Enables or disables AES key wrapping support on s390-ccw hosts. This feature 90controls whether AES wrapping keys will be created to allow 91execution of AES cryptographic functions. The default is on. 92@item dea-key-wrap=on|off 93Enables or disables DEA key wrapping support on s390-ccw hosts. This feature 94controls whether DEA wrapping keys will be created to allow 95execution of DEA cryptographic functions. The default is on. 96@item nvdimm=on|off 97Enables or disables NVDIMM support. The default is off. 98@item enforce-config-section=on|off 99If @option{enforce-config-section} is set to @var{on}, force migration 100code to send configuration section even if the machine-type sets the 101@option{migration.send-configuration} property to @var{off}. 102NOTE: this parameter is deprecated. Please use @option{-global} 103@option{migration.send-configuration}=@var{on|off} instead. 104@item memory-encryption=@var{} 105Memory encryption object to use. The default is none. 106@end table 107ETEXI 108 109HXCOMM Deprecated by -machine 110DEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL) 111 112DEF("cpu", HAS_ARG, QEMU_OPTION_cpu, 113 "-cpu cpu select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL) 114STEXI 115@item -cpu @var{model} 116@findex -cpu 117Select CPU model (@code{-cpu help} for list and additional feature selection) 118ETEXI 119 120DEF("accel", HAS_ARG, QEMU_OPTION_accel, 121 "-accel [accel=]accelerator[,thread=single|multi]\n" 122 " select accelerator (kvm, xen, hax, hvf, whpx or tcg; use 'help' for a list)\n" 123 " thread=single|multi (enable multi-threaded TCG)\n", QEMU_ARCH_ALL) 124STEXI 125@item -accel @var{name}[,prop=@var{value}[,...]] 126@findex -accel 127This is used to enable an accelerator. Depending on the target architecture, 128kvm, xen, hax, hvf, whpx or tcg can be available. By default, tcg is used. If there is 129more than one accelerator specified, the next one is used if the previous one 130fails to initialize. 131@table @option 132@item thread=single|multi 133Controls number of TCG threads. When the TCG is multi-threaded there will be one 134thread per vCPU therefor taking advantage of additional host cores. The default 135is to enable multi-threading where both the back-end and front-ends support it and 136no incompatible TCG features have been enabled (e.g. icount/replay). 137@end table 138ETEXI 139 140DEF("smp", HAS_ARG, QEMU_OPTION_smp, 141 "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,sockets=sockets]\n" 142 " set the number of CPUs to 'n' [default=1]\n" 143 " maxcpus= maximum number of total cpus, including\n" 144 " offline CPUs for hotplug, etc\n" 145 " cores= number of CPU cores on one socket\n" 146 " threads= number of threads on one CPU core\n" 147 " sockets= number of discrete sockets in the system\n", 148 QEMU_ARCH_ALL) 149STEXI 150@item -smp [cpus=]@var{n}[,cores=@var{cores}][,threads=@var{threads}][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}] 151@findex -smp 152Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255 153CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs 154to 4. 155For the PC target, the number of @var{cores} per socket, the number 156of @var{threads} per cores and the total number of @var{sockets} can be 157specified. Missing values will be computed. If any on the three values is 158given, the total number of CPUs @var{n} can be omitted. @var{maxcpus} 159specifies the maximum number of hotpluggable CPUs. 160ETEXI 161 162DEF("numa", HAS_ARG, QEMU_OPTION_numa, 163 "-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n" 164 "-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node]\n" 165 "-numa dist,src=source,dst=destination,val=distance\n" 166 "-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]\n", 167 QEMU_ARCH_ALL) 168STEXI 169@item -numa node[,mem=@var{size}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}] 170@itemx -numa node[,memdev=@var{id}][,cpus=@var{firstcpu}[-@var{lastcpu}]][,nodeid=@var{node}] 171@itemx -numa dist,src=@var{source},dst=@var{destination},val=@var{distance} 172@itemx -numa cpu,node-id=@var{node}[,socket-id=@var{x}][,core-id=@var{y}][,thread-id=@var{z}] 173@findex -numa 174Define a NUMA node and assign RAM and VCPUs to it. 175Set the NUMA distance from a source node to a destination node. 176 177Legacy VCPU assignment uses @samp{cpus} option where 178@var{firstcpu} and @var{lastcpu} are CPU indexes. Each 179@samp{cpus} option represent a contiguous range of CPU indexes 180(or a single VCPU if @var{lastcpu} is omitted). A non-contiguous 181set of VCPUs can be represented by providing multiple @samp{cpus} 182options. If @samp{cpus} is omitted on all nodes, VCPUs are automatically 183split between them. 184 185For example, the following option assigns VCPUs 0, 1, 2 and 5 to 186a NUMA node: 187@example 188-numa node,cpus=0-2,cpus=5 189@end example 190 191@samp{cpu} option is a new alternative to @samp{cpus} option 192which uses @samp{socket-id|core-id|thread-id} properties to assign 193CPU objects to a @var{node} using topology layout properties of CPU. 194The set of properties is machine specific, and depends on used 195machine type/@samp{smp} options. It could be queried with 196@samp{hotpluggable-cpus} monitor command. 197@samp{node-id} property specifies @var{node} to which CPU object 198will be assigned, it's required for @var{node} to be declared 199with @samp{node} option before it's used with @samp{cpu} option. 200 201For example: 202@example 203-M pc \ 204-smp 1,sockets=2,maxcpus=2 \ 205-numa node,nodeid=0 -numa node,nodeid=1 \ 206-numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1 207@end example 208 209@samp{mem} assigns a given RAM amount to a node. @samp{memdev} 210assigns RAM from a given memory backend device to a node. If 211@samp{mem} and @samp{memdev} are omitted in all nodes, RAM is 212split equally between them. 213 214@samp{mem} and @samp{memdev} are mutually exclusive. Furthermore, 215if one node uses @samp{memdev}, all of them have to use it. 216 217@var{source} and @var{destination} are NUMA node IDs. 218@var{distance} is the NUMA distance from @var{source} to @var{destination}. 219The distance from a node to itself is always 10. If any pair of nodes is 220given a distance, then all pairs must be given distances. Although, when 221distances are only given in one direction for each pair of nodes, then 222the distances in the opposite directions are assumed to be the same. If, 223however, an asymmetrical pair of distances is given for even one node 224pair, then all node pairs must be provided distance values for both 225directions, even when they are symmetrical. When a node is unreachable 226from another node, set the pair's distance to 255. 227 228Note that the -@option{numa} option doesn't allocate any of the 229specified resources, it just assigns existing resources to NUMA 230nodes. This means that one still has to use the @option{-m}, 231@option{-smp} options to allocate RAM and VCPUs respectively. 232 233ETEXI 234 235DEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd, 236 "-add-fd fd=fd,set=set[,opaque=opaque]\n" 237 " Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL) 238STEXI 239@item -add-fd fd=@var{fd},set=@var{set}[,opaque=@var{opaque}] 240@findex -add-fd 241 242Add a file descriptor to an fd set. Valid options are: 243 244@table @option 245@item fd=@var{fd} 246This option defines the file descriptor of which a duplicate is added to fd set. 247The file descriptor cannot be stdin, stdout, or stderr. 248@item set=@var{set} 249This option defines the ID of the fd set to add the file descriptor to. 250@item opaque=@var{opaque} 251This option defines a free-form string that can be used to describe @var{fd}. 252@end table 253 254You can open an image using pre-opened file descriptors from an fd set: 255@example 256qemu-system-i386 257-add-fd fd=3,set=2,opaque="rdwr:/path/to/file" 258-add-fd fd=4,set=2,opaque="rdonly:/path/to/file" 259-drive file=/dev/fdset/2,index=0,media=disk 260@end example 261ETEXI 262 263DEF("set", HAS_ARG, QEMU_OPTION_set, 264 "-set group.id.arg=value\n" 265 " set <arg> parameter for item <id> of type <group>\n" 266 " i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL) 267STEXI 268@item -set @var{group}.@var{id}.@var{arg}=@var{value} 269@findex -set 270Set parameter @var{arg} for item @var{id} of type @var{group} 271ETEXI 272 273DEF("global", HAS_ARG, QEMU_OPTION_global, 274 "-global driver.property=value\n" 275 "-global driver=driver,property=property,value=value\n" 276 " set a global default for a driver property\n", 277 QEMU_ARCH_ALL) 278STEXI 279@item -global @var{driver}.@var{prop}=@var{value} 280@itemx -global driver=@var{driver},property=@var{property},value=@var{value} 281@findex -global 282Set default value of @var{driver}'s property @var{prop} to @var{value}, e.g.: 283 284@example 285qemu-system-i386 -global ide-hd.physical_block_size=4096 disk-image.img 286@end example 287 288In particular, you can use this to set driver properties for devices which are 289created automatically by the machine model. To create a device which is not 290created automatically and set properties on it, use -@option{device}. 291 292-global @var{driver}.@var{prop}=@var{value} is shorthand for -global 293driver=@var{driver},property=@var{prop},value=@var{value}. The 294longhand syntax works even when @var{driver} contains a dot. 295ETEXI 296 297DEF("boot", HAS_ARG, QEMU_OPTION_boot, 298 "-boot [order=drives][,once=drives][,menu=on|off]\n" 299 " [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n" 300 " 'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n" 301 " 'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n" 302 " 'sp_time': the period that splash picture last if menu=on, unit is ms\n" 303 " 'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n", 304 QEMU_ARCH_ALL) 305STEXI 306@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] 307@findex -boot 308Specify boot order @var{drives} as a string of drive letters. Valid 309drive letters depend on the target architecture. The x86 PC uses: a, b 310(floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot 311from network adapter 1-4), hard disk boot is the default. To apply a 312particular boot order only on the first startup, specify it via 313@option{once}. Note that the @option{order} or @option{once} parameter 314should not be used together with the @option{bootindex} property of 315devices, since the firmware implementations normally do not support both 316at the same time. 317 318Interactive boot menus/prompts can be enabled via @option{menu=on} as far 319as firmware/BIOS supports them. The default is non-interactive boot. 320 321A splash picture could be passed to bios, enabling user to show it as logo, 322when option splash=@var{sp_name} is given and menu=on, If firmware/BIOS 323supports them. Currently Seabios for X86 system support it. 324limitation: The splash file could be a jpeg file or a BMP file in 24 BPP 325format(true color). The resolution should be supported by the SVGA mode, so 326the recommended is 320x240, 640x480, 800x640. 327 328A timeout could be passed to bios, guest will pause for @var{rb_timeout} ms 329when boot failed, then reboot. If @var{rb_timeout} is '-1', guest will not 330reboot, qemu passes '-1' to bios by default. Currently Seabios for X86 331system support it. 332 333Do strict boot via @option{strict=on} as far as firmware/BIOS 334supports it. This only effects when boot priority is changed by 335bootindex options. The default is non-strict boot. 336 337@example 338# try to boot from network first, then from hard disk 339qemu-system-i386 -boot order=nc 340# boot from CD-ROM first, switch back to default order after reboot 341qemu-system-i386 -boot once=d 342# boot with a splash picture for 5 seconds. 343qemu-system-i386 -boot menu=on,splash=/root/boot.bmp,splash-time=5000 344@end example 345 346Note: The legacy format '-boot @var{drives}' is still supported but its 347use is discouraged as it may be removed from future versions. 348ETEXI 349 350DEF("m", HAS_ARG, QEMU_OPTION_m, 351 "-m [size=]megs[,slots=n,maxmem=size]\n" 352 " configure guest RAM\n" 353 " size: initial amount of guest memory\n" 354 " slots: number of hotplug slots (default: none)\n" 355 " maxmem: maximum amount of guest memory (default: none)\n" 356 "NOTE: Some architectures might enforce a specific granularity\n", 357 QEMU_ARCH_ALL) 358STEXI 359@item -m [size=]@var{megs}[,slots=n,maxmem=size] 360@findex -m 361Sets guest startup RAM size to @var{megs} megabytes. Default is 128 MiB. 362Optionally, a suffix of ``M'' or ``G'' can be used to signify a value in 363megabytes or gigabytes respectively. Optional pair @var{slots}, @var{maxmem} 364could be used to set amount of hotpluggable memory slots and maximum amount of 365memory. Note that @var{maxmem} must be aligned to the page size. 366 367For example, the following command-line sets the guest startup RAM size to 3681GB, creates 3 slots to hotplug additional memory and sets the maximum 369memory the guest can reach to 4GB: 370 371@example 372qemu-system-x86_64 -m 1G,slots=3,maxmem=4G 373@end example 374 375If @var{slots} and @var{maxmem} are not specified, memory hotplug won't 376be enabled and the guest startup RAM will never increase. 377ETEXI 378 379DEF("mem-path", HAS_ARG, QEMU_OPTION_mempath, 380 "-mem-path FILE provide backing storage for guest RAM\n", QEMU_ARCH_ALL) 381STEXI 382@item -mem-path @var{path} 383@findex -mem-path 384Allocate guest RAM from a temporarily created file in @var{path}. 385ETEXI 386 387DEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc, 388 "-mem-prealloc preallocate guest memory (use with -mem-path)\n", 389 QEMU_ARCH_ALL) 390STEXI 391@item -mem-prealloc 392@findex -mem-prealloc 393Preallocate memory when using -mem-path. 394ETEXI 395 396DEF("k", HAS_ARG, QEMU_OPTION_k, 397 "-k language use keyboard layout (for example 'fr' for French)\n", 398 QEMU_ARCH_ALL) 399STEXI 400@item -k @var{language} 401@findex -k 402Use keyboard layout @var{language} (for example @code{fr} for 403French). This option is only needed where it is not easy to get raw PC 404keycodes (e.g. on Macs, with some X11 servers or with a VNC or curses 405display). You don't normally need to use it on PC/Linux or PC/Windows 406hosts. 407 408The available layouts are: 409@example 410ar de-ch es fo fr-ca hu ja mk no pt-br sv 411da en-gb et fr fr-ch is lt nl pl ru th 412de en-us fi fr-be hr it lv nl-be pt sl tr 413@end example 414 415The default is @code{en-us}. 416ETEXI 417 418 419HXCOMM Deprecated by -audiodev 420DEF("audio-help", 0, QEMU_OPTION_audio_help, 421 "-audio-help show -audiodev equivalent of the currently specified audio settings\n", 422 QEMU_ARCH_ALL) 423STEXI 424@item -audio-help 425@findex -audio-help 426Will show the -audiodev equivalent of the currently specified 427(deprecated) environment variables. 428ETEXI 429 430DEF("audiodev", HAS_ARG, QEMU_OPTION_audiodev, 431 "-audiodev [driver=]driver,id=id[,prop[=value][,...]]\n" 432 " specifies the audio backend to use\n" 433 " id= identifier of the backend\n" 434 " timer-period= timer period in microseconds\n" 435 " in|out.fixed-settings= use fixed settings for host audio\n" 436 " in|out.frequency= frequency to use with fixed settings\n" 437 " in|out.channels= number of channels to use with fixed settings\n" 438 " in|out.format= sample format to use with fixed settings\n" 439 " valid values: s8, s16, s32, u8, u16, u32\n" 440 " in|out.voices= number of voices to use\n" 441 " in|out.buffer-len= length of buffer in microseconds\n" 442 "-audiodev none,id=id,[,prop[=value][,...]]\n" 443 " dummy driver that discards all output\n" 444#ifdef CONFIG_AUDIO_ALSA 445 "-audiodev alsa,id=id[,prop[=value][,...]]\n" 446 " in|out.dev= name of the audio device to use\n" 447 " in|out.period-len= length of period in microseconds\n" 448 " in|out.try-poll= attempt to use poll mode\n" 449 " threshold= threshold (in microseconds) when playback starts\n" 450#endif 451#ifdef CONFIG_AUDIO_COREAUDIO 452 "-audiodev coreaudio,id=id[,prop[=value][,...]]\n" 453 " in|out.buffer-count= number of buffers\n" 454#endif 455#ifdef CONFIG_AUDIO_DSOUND 456 "-audiodev dsound,id=id[,prop[=value][,...]]\n" 457 " latency= add extra latency to playback in microseconds\n" 458#endif 459#ifdef CONFIG_AUDIO_OSS 460 "-audiodev oss,id=id[,prop[=value][,...]]\n" 461 " in|out.dev= path of the audio device to use\n" 462 " in|out.buffer-count= number of buffers\n" 463 " in|out.try-poll= attempt to use poll mode\n" 464 " try-mmap= try using memory mapped access\n" 465 " exclusive= open device in exclusive mode\n" 466 " dsp-policy= set timing policy (0..10), -1 to use fragment mode\n" 467#endif 468#ifdef CONFIG_AUDIO_PA 469 "-audiodev pa,id=id[,prop[=value][,...]]\n" 470 " server= PulseAudio server address\n" 471 " in|out.name= source/sink device name\n" 472#endif 473#ifdef CONFIG_AUDIO_SDL 474 "-audiodev sdl,id=id[,prop[=value][,...]]\n" 475#endif 476#ifdef CONFIG_SPICE 477 "-audiodev spice,id=id[,prop[=value][,...]]\n" 478#endif 479 "-audiodev wav,id=id[,prop[=value][,...]]\n" 480 " path= path of wav file to record\n", 481 QEMU_ARCH_ALL) 482STEXI 483@item -audiodev [driver=]@var{driver},id=@var{id}[,@var{prop}[=@var{value}][,...]] 484@findex -audiodev 485Adds a new audio backend @var{driver} identified by @var{id}. There are 486global and driver specific properties. Some values can be set 487differently for input and output, they're marked with @code{in|out.}. 488You can set the input's property with @code{in.@var{prop}} and the 489output's property with @code{out.@var{prop}}. For example: 490@example 491-audiodev alsa,id=example,in.frequency=44110,out.frequency=8000 492-audiodev alsa,id=example,out.channels=1 # leaves in.channels unspecified 493@end example 494 495Valid global options are: 496 497@table @option 498@item id=@var{identifier} 499Identifies the audio backend. 500 501@item timer-period=@var{period} 502Sets the timer @var{period} used by the audio subsystem in microseconds. 503Default is 10000 (10 ms). 504 505@item in|out.fixed-settings=on|off 506Use fixed settings for host audio. When off, it will change based on 507how the guest opens the sound card. In this case you must not specify 508@var{frequency}, @var{channels} or @var{format}. Default is on. 509 510@item in|out.frequency=@var{frequency} 511Specify the @var{frequency} to use when using @var{fixed-settings}. 512Default is 44100Hz. 513 514@item in|out.channels=@var{channels} 515Specify the number of @var{channels} to use when using 516@var{fixed-settings}. Default is 2 (stereo). 517 518@item in|out.format=@var{format} 519Specify the sample @var{format} to use when using @var{fixed-settings}. 520Valid values are: @code{s8}, @code{s16}, @code{s32}, @code{u8}, 521@code{u16}, @code{u32}. Default is @code{s16}. 522 523@item in|out.voices=@var{voices} 524Specify the number of @var{voices} to use. Default is 1. 525 526@item in|out.buffer=@var{usecs} 527Sets the size of the buffer in microseconds. 528 529@end table 530 531@item -audiodev none,id=@var{id}[,@var{prop}[=@var{value}][,...]] 532Creates a dummy backend that discards all outputs. This backend has no 533backend specific properties. 534 535@item -audiodev alsa,id=@var{id}[,@var{prop}[=@var{value}][,...]] 536Creates backend using the ALSA. This backend is only available on 537Linux. 538 539ALSA specific options are: 540 541@table @option 542 543@item in|out.dev=@var{device} 544Specify the ALSA @var{device} to use for input and/or output. Default 545is @code{default}. 546 547@item in|out.period-len=@var{usecs} 548Sets the period length in microseconds. 549 550@item in|out.try-poll=on|off 551Attempt to use poll mode with the device. Default is on. 552 553@item threshold=@var{threshold} 554Threshold (in microseconds) when playback starts. Default is 0. 555 556@end table 557 558@item -audiodev coreaudio,id=@var{id}[,@var{prop}[=@var{value}][,...]] 559Creates a backend using Apple's Core Audio. This backend is only 560available on Mac OS and only supports playback. 561 562Core Audio specific options are: 563 564@table @option 565 566@item in|out.buffer-count=@var{count} 567Sets the @var{count} of the buffers. 568 569@end table 570 571@item -audiodev dsound,id=@var{id}[,@var{prop}[=@var{value}][,...]] 572Creates a backend using Microsoft's DirectSound. This backend is only 573available on Windows and only supports playback. 574 575DirectSound specific options are: 576 577@table @option 578 579@item latency=@var{usecs} 580Add extra @var{usecs} microseconds latency to playback. Default is 58110000 (10 ms). 582 583@end table 584 585@item -audiodev oss,id=@var{id}[,@var{prop}[=@var{value}][,...]] 586Creates a backend using OSS. This backend is available on most 587Unix-like systems. 588 589OSS specific options are: 590 591@table @option 592 593@item in|out.dev=@var{device} 594Specify the file name of the OSS @var{device} to use. Default is 595@code{/dev/dsp}. 596 597@item in|out.buffer-count=@var{count} 598Sets the @var{count} of the buffers. 599 600@item in|out.try-poll=on|of 601Attempt to use poll mode with the device. Default is on. 602 603@item try-mmap=on|off 604Try using memory mapped device access. Default is off. 605 606@item exclusive=on|off 607Open the device in exclusive mode (vmix won't work in this case). 608Default is off. 609 610@item dsp-policy=@var{policy} 611Sets the timing policy (between 0 and 10, where smaller number means 612smaller latency but higher CPU usage). Use -1 to use buffer sizes 613specified by @code{buffer} and @code{buffer-count}. This option is 614ignored if you do not have OSS 4. Default is 5. 615 616@end table 617 618@item -audiodev pa,id=@var{id}[,@var{prop}[=@var{value}][,...]] 619Creates a backend using PulseAudio. This backend is available on most 620systems. 621 622PulseAudio specific options are: 623 624@table @option 625 626@item server=@var{server} 627Sets the PulseAudio @var{server} to connect to. 628 629@item in|out.name=@var{sink} 630Use the specified source/sink for recording/playback. 631 632@end table 633 634@item -audiodev sdl,id=@var{id}[,@var{prop}[=@var{value}][,...]] 635Creates a backend using SDL. This backend is available on most systems, 636but you should use your platform's native backend if possible. This 637backend has no backend specific properties. 638 639@item -audiodev spice,id=@var{id}[,@var{prop}[=@var{value}][,...]] 640Creates a backend that sends audio through SPICE. This backend requires 641@code{-spice} and automatically selected in that case, so usually you 642can ignore this option. This backend has no backend specific 643properties. 644 645@item -audiodev wav,id=@var{id}[,@var{prop}[=@var{value}][,...]] 646Creates a backend that writes audio to a WAV file. 647 648Backend specific options are: 649 650@table @option 651 652@item path=@var{path} 653Write recorded audio into the specified file. Default is 654@code{qemu.wav}. 655 656@end table 657ETEXI 658 659DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw, 660 "-soundhw c1,... enable audio support\n" 661 " and only specified sound cards (comma separated list)\n" 662 " use '-soundhw help' to get the list of supported cards\n" 663 " use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL) 664STEXI 665@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all 666@findex -soundhw 667Enable audio and selected sound hardware. Use 'help' to print all 668available sound hardware. 669 670@example 671qemu-system-i386 -soundhw sb16,adlib disk.img 672qemu-system-i386 -soundhw es1370 disk.img 673qemu-system-i386 -soundhw ac97 disk.img 674qemu-system-i386 -soundhw hda disk.img 675qemu-system-i386 -soundhw all disk.img 676qemu-system-i386 -soundhw help 677@end example 678 679Note that Linux's i810_audio OSS kernel (for AC97) module might 680require manually specifying clocking. 681 682@example 683modprobe i810_audio clocking=48000 684@end example 685ETEXI 686 687DEF("device", HAS_ARG, QEMU_OPTION_device, 688 "-device driver[,prop[=value][,...]]\n" 689 " add device (based on driver)\n" 690 " prop=value,... sets driver properties\n" 691 " use '-device help' to print all possible drivers\n" 692 " use '-device driver,help' to print all possible properties\n", 693 QEMU_ARCH_ALL) 694STEXI 695@item -device @var{driver}[,@var{prop}[=@var{value}][,...]] 696@findex -device 697Add device @var{driver}. @var{prop}=@var{value} sets driver 698properties. Valid properties depend on the driver. To get help on 699possible drivers and properties, use @code{-device help} and 700@code{-device @var{driver},help}. 701 702Some drivers are: 703@item -device ipmi-bmc-sim,id=@var{id}[,slave_addr=@var{val}][,sdrfile=@var{file}][,furareasize=@var{val}][,furdatafile=@var{file}] 704 705Add an IPMI BMC. This is a simulation of a hardware management 706interface processor that normally sits on a system. It provides 707a watchdog and the ability to reset and power control the system. 708You need to connect this to an IPMI interface to make it useful 709 710The IPMI slave address to use for the BMC. The default is 0x20. 711This address is the BMC's address on the I2C network of management 712controllers. If you don't know what this means, it is safe to ignore 713it. 714 715@table @option 716@item bmc=@var{id} 717The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above. 718@item slave_addr=@var{val} 719Define slave address to use for the BMC. The default is 0x20. 720@item sdrfile=@var{file} 721file containing raw Sensor Data Records (SDR) data. The default is none. 722@item fruareasize=@var{val} 723size of a Field Replaceable Unit (FRU) area. The default is 1024. 724@item frudatafile=@var{file} 725file containing raw Field Replaceable Unit (FRU) inventory data. The default is none. 726@end table 727 728@item -device ipmi-bmc-extern,id=@var{id},chardev=@var{id}[,slave_addr=@var{val}] 729 730Add a connection to an external IPMI BMC simulator. Instead of 731locally emulating the BMC like the above item, instead connect 732to an external entity that provides the IPMI services. 733 734A connection is made to an external BMC simulator. If you do this, it 735is strongly recommended that you use the "reconnect=" chardev option 736to reconnect to the simulator if the connection is lost. Note that if 737this is not used carefully, it can be a security issue, as the 738interface has the ability to send resets, NMIs, and power off the VM. 739It's best if QEMU makes a connection to an external simulator running 740on a secure port on localhost, so neither the simulator nor QEMU is 741exposed to any outside network. 742 743See the "lanserv/README.vm" file in the OpenIPMI library for more 744details on the external interface. 745 746@item -device isa-ipmi-kcs,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}] 747 748Add a KCS IPMI interafce on the ISA bus. This also adds a 749corresponding ACPI and SMBIOS entries, if appropriate. 750 751@table @option 752@item bmc=@var{id} 753The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above. 754@item ioport=@var{val} 755Define the I/O address of the interface. The default is 0xca0 for KCS. 756@item irq=@var{val} 757Define the interrupt to use. The default is 5. To disable interrupts, 758set this to 0. 759@end table 760 761@item -device isa-ipmi-bt,bmc=@var{id}[,ioport=@var{val}][,irq=@var{val}] 762 763Like the KCS interface, but defines a BT interface. The default port is 7640xe4 and the default interrupt is 5. 765 766ETEXI 767 768DEF("name", HAS_ARG, QEMU_OPTION_name, 769 "-name string1[,process=string2][,debug-threads=on|off]\n" 770 " set the name of the guest\n" 771 " string1 sets the window title and string2 the process name\n" 772 " When debug-threads is enabled, individual threads are given a separate name\n" 773 " NOTE: The thread names are for debugging and not a stable API.\n", 774 QEMU_ARCH_ALL) 775STEXI 776@item -name @var{name} 777@findex -name 778Sets the @var{name} of the guest. 779This name will be displayed in the SDL window caption. 780The @var{name} will also be used for the VNC server. 781Also optionally set the top visible process name in Linux. 782Naming of individual threads can also be enabled on Linux to aid debugging. 783ETEXI 784 785DEF("uuid", HAS_ARG, QEMU_OPTION_uuid, 786 "-uuid %08x-%04x-%04x-%04x-%012x\n" 787 " specify machine UUID\n", QEMU_ARCH_ALL) 788STEXI 789@item -uuid @var{uuid} 790@findex -uuid 791Set system UUID. 792ETEXI 793 794STEXI 795@end table 796ETEXI 797DEFHEADING() 798 799DEFHEADING(Block device options:) 800STEXI 801@table @option 802ETEXI 803 804DEF("fda", HAS_ARG, QEMU_OPTION_fda, 805 "-fda/-fdb file use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL) 806DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL) 807STEXI 808@item -fda @var{file} 809@itemx -fdb @var{file} 810@findex -fda 811@findex -fdb 812Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}). 813ETEXI 814 815DEF("hda", HAS_ARG, QEMU_OPTION_hda, 816 "-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL) 817DEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL) 818DEF("hdc", HAS_ARG, QEMU_OPTION_hdc, 819 "-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL) 820DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL) 821STEXI 822@item -hda @var{file} 823@itemx -hdb @var{file} 824@itemx -hdc @var{file} 825@itemx -hdd @var{file} 826@findex -hda 827@findex -hdb 828@findex -hdc 829@findex -hdd 830Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}). 831ETEXI 832 833DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom, 834 "-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n", 835 QEMU_ARCH_ALL) 836STEXI 837@item -cdrom @var{file} 838@findex -cdrom 839Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and 840@option{-cdrom} at the same time). You can use the host CD-ROM by 841using @file{/dev/cdrom} as filename (@pxref{host_drives}). 842ETEXI 843 844DEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev, 845 "-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]\n" 846 " [,cache.direct=on|off][,cache.no-flush=on|off]\n" 847 " [,read-only=on|off][,detect-zeroes=on|off|unmap]\n" 848 " [,driver specific parameters...]\n" 849 " configure a block backend\n", QEMU_ARCH_ALL) 850STEXI 851@item -blockdev @var{option}[,@var{option}[,@var{option}[,...]]] 852@findex -blockdev 853 854Define a new block driver node. Some of the options apply to all block drivers, 855other options are only accepted for a specific block driver. See below for a 856list of generic options and options for the most common block drivers. 857 858Options that expect a reference to another node (e.g. @code{file}) can be 859given in two ways. Either you specify the node name of an already existing node 860(file=@var{node-name}), or you define a new node inline, adding options 861for the referenced node after a dot (file.filename=@var{path},file.aio=native). 862 863A block driver node created with @option{-blockdev} can be used for a guest 864device by specifying its node name for the @code{drive} property in a 865@option{-device} argument that defines a block device. 866 867@table @option 868@item Valid options for any block driver node: 869 870@table @code 871@item driver 872Specifies the block driver to use for the given node. 873@item node-name 874This defines the name of the block driver node by which it will be referenced 875later. The name must be unique, i.e. it must not match the name of a different 876block driver node, or (if you use @option{-drive} as well) the ID of a drive. 877 878If no node name is specified, it is automatically generated. The generated node 879name is not intended to be predictable and changes between QEMU invocations. 880For the top level, an explicit node name must be specified. 881@item read-only 882Open the node read-only. Guest write attempts will fail. 883@item cache.direct 884The host page cache can be avoided with @option{cache.direct=on}. This will 885attempt to do disk IO directly to the guest's memory. QEMU may still perform an 886internal copy of the data. 887@item cache.no-flush 888In case you don't care about data integrity over host failures, you can use 889@option{cache.no-flush=on}. This option tells QEMU that it never needs to write 890any data to the disk but can instead keep things in cache. If anything goes 891wrong, like your host losing power, the disk storage getting disconnected 892accidentally, etc. your image will most probably be rendered unusable. 893@item discard=@var{discard} 894@var{discard} is one of "ignore" (or "off") or "unmap" (or "on") and controls 895whether @code{discard} (also known as @code{trim} or @code{unmap}) requests are 896ignored or passed to the filesystem. Some machine types may not support 897discard requests. 898@item detect-zeroes=@var{detect-zeroes} 899@var{detect-zeroes} is "off", "on" or "unmap" and enables the automatic 900conversion of plain zero writes by the OS to driver specific optimized 901zero write commands. You may even choose "unmap" if @var{discard} is set 902to "unmap" to allow a zero write to be converted to an @code{unmap} operation. 903@end table 904 905@item Driver-specific options for @code{file} 906 907This is the protocol-level block driver for accessing regular files. 908 909@table @code 910@item filename 911The path to the image file in the local filesystem 912@item aio 913Specifies the AIO backend (threads/native, default: threads) 914@item locking 915Specifies whether the image file is protected with Linux OFD / POSIX locks. The 916default is to use the Linux Open File Descriptor API if available, otherwise no 917lock is applied. (auto/on/off, default: auto) 918@end table 919Example: 920@example 921-blockdev driver=file,node-name=disk,filename=disk.img 922@end example 923 924@item Driver-specific options for @code{raw} 925 926This is the image format block driver for raw images. It is usually 927stacked on top of a protocol level block driver such as @code{file}. 928 929@table @code 930@item file 931Reference to or definition of the data source block driver node 932(e.g. a @code{file} driver node) 933@end table 934Example 1: 935@example 936-blockdev driver=file,node-name=disk_file,filename=disk.img 937-blockdev driver=raw,node-name=disk,file=disk_file 938@end example 939Example 2: 940@example 941-blockdev driver=raw,node-name=disk,file.driver=file,file.filename=disk.img 942@end example 943 944@item Driver-specific options for @code{qcow2} 945 946This is the image format block driver for qcow2 images. It is usually 947stacked on top of a protocol level block driver such as @code{file}. 948 949@table @code 950@item file 951Reference to or definition of the data source block driver node 952(e.g. a @code{file} driver node) 953 954@item backing 955Reference to or definition of the backing file block device (default is taken 956from the image file). It is allowed to pass @code{null} here in order to disable 957the default backing file. 958 959@item lazy-refcounts 960Whether to enable the lazy refcounts feature (on/off; default is taken from the 961image file) 962 963@item cache-size 964The maximum total size of the L2 table and refcount block caches in bytes 965(default: the sum of l2-cache-size and refcount-cache-size) 966 967@item l2-cache-size 968The maximum size of the L2 table cache in bytes 969(default: if cache-size is not specified - 32M on Linux platforms, and 8M on 970non-Linux platforms; otherwise, as large as possible within the cache-size, 971while permitting the requested or the minimal refcount cache size) 972 973@item refcount-cache-size 974The maximum size of the refcount block cache in bytes 975(default: 4 times the cluster size; or if cache-size is specified, the part of 976it which is not used for the L2 cache) 977 978@item cache-clean-interval 979Clean unused entries in the L2 and refcount caches. The interval is in seconds. 980The default value is 600 on supporting platforms, and 0 on other platforms. 981Setting it to 0 disables this feature. 982 983@item pass-discard-request 984Whether discard requests to the qcow2 device should be forwarded to the data 985source (on/off; default: on if discard=unmap is specified, off otherwise) 986 987@item pass-discard-snapshot 988Whether discard requests for the data source should be issued when a snapshot 989operation (e.g. deleting a snapshot) frees clusters in the qcow2 file (on/off; 990default: on) 991 992@item pass-discard-other 993Whether discard requests for the data source should be issued on other 994occasions where a cluster gets freed (on/off; default: off) 995 996@item overlap-check 997Which overlap checks to perform for writes to the image 998(none/constant/cached/all; default: cached). For details or finer 999granularity control refer to the QAPI documentation of @code{blockdev-add}. 1000@end table 1001 1002Example 1: 1003@example 1004-blockdev driver=file,node-name=my_file,filename=/tmp/disk.qcow2 1005-blockdev driver=qcow2,node-name=hda,file=my_file,overlap-check=none,cache-size=16777216 1006@end example 1007Example 2: 1008@example 1009-blockdev driver=qcow2,node-name=disk,file.driver=http,file.filename=http://example.com/image.qcow2 1010@end example 1011 1012@item Driver-specific options for other drivers 1013Please refer to the QAPI documentation of the @code{blockdev-add} QMP command. 1014 1015@end table 1016 1017ETEXI 1018 1019DEF("drive", HAS_ARG, QEMU_OPTION_drive, 1020 "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n" 1021 " [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n" 1022 " [,snapshot=on|off][,rerror=ignore|stop|report]\n" 1023 " [,werror=ignore|stop|report|enospc][,id=name][,aio=threads|native]\n" 1024 " [,readonly=on|off][,copy-on-read=on|off]\n" 1025 " [,discard=ignore|unmap][,detect-zeroes=on|off|unmap]\n" 1026 " [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n" 1027 " [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n" 1028 " [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n" 1029 " [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n" 1030 " [[,iops_size=is]]\n" 1031 " [[,group=g]]\n" 1032 " use 'file' as a drive image\n", QEMU_ARCH_ALL) 1033STEXI 1034@item -drive @var{option}[,@var{option}[,@var{option}[,...]]] 1035@findex -drive 1036 1037Define a new drive. This includes creating a block driver node (the backend) as 1038well as a guest device, and is mostly a shortcut for defining the corresponding 1039@option{-blockdev} and @option{-device} options. 1040 1041@option{-drive} accepts all options that are accepted by @option{-blockdev}. In 1042addition, it knows the following options: 1043 1044@table @option 1045@item file=@var{file} 1046This option defines which disk image (@pxref{disk_images}) to use with 1047this drive. If the filename contains comma, you must double it 1048(for instance, "file=my,,file" to use file "my,file"). 1049 1050Special files such as iSCSI devices can be specified using protocol 1051specific URLs. See the section for "Device URL Syntax" for more information. 1052@item if=@var{interface} 1053This option defines on which type on interface the drive is connected. 1054Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio, none. 1055@item bus=@var{bus},unit=@var{unit} 1056These options define where is connected the drive by defining the bus number and 1057the unit id. 1058@item index=@var{index} 1059This option defines where is connected the drive by using an index in the list 1060of available connectors of a given interface type. 1061@item media=@var{media} 1062This option defines the type of the media: disk or cdrom. 1063@item snapshot=@var{snapshot} 1064@var{snapshot} is "on" or "off" and controls snapshot mode for the given drive 1065(see @option{-snapshot}). 1066@item cache=@var{cache} 1067@var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough" 1068and controls how the host cache is used to access block data. This is a 1069shortcut that sets the @option{cache.direct} and @option{cache.no-flush} 1070options (as in @option{-blockdev}), and additionally @option{cache.writeback}, 1071which provides a default for the @option{write-cache} option of block guest 1072devices (as in @option{-device}). The modes correspond to the following 1073settings: 1074 1075@c Our texi2pod.pl script doesn't support @multitable, so fall back to using 1076@c plain ASCII art (well, UTF-8 art really). This looks okay both in the manpage 1077@c and the HTML output. 1078@example 1079@ │ cache.writeback cache.direct cache.no-flush 1080─────────────┼───────────────────────────────────────────────── 1081writeback │ on off off 1082none │ on on off 1083writethrough │ off off off 1084directsync │ off on off 1085unsafe │ on off on 1086@end example 1087 1088The default mode is @option{cache=writeback}. 1089 1090@item aio=@var{aio} 1091@var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO. 1092@item format=@var{format} 1093Specify which disk @var{format} will be used rather than detecting 1094the format. Can be used to specify format=raw to avoid interpreting 1095an untrusted format header. 1096@item werror=@var{action},rerror=@var{action} 1097Specify which @var{action} to take on write and read errors. Valid actions are: 1098"ignore" (ignore the error and try to continue), "stop" (pause QEMU), 1099"report" (report the error to the guest), "enospc" (pause QEMU only if the 1100host disk is full; report the error to the guest otherwise). 1101The default setting is @option{werror=enospc} and @option{rerror=report}. 1102@item copy-on-read=@var{copy-on-read} 1103@var{copy-on-read} is "on" or "off" and enables whether to copy read backing 1104file sectors into the image file. 1105@item bps=@var{b},bps_rd=@var{r},bps_wr=@var{w} 1106Specify bandwidth throttling limits in bytes per second, either for all request 1107types or for reads or writes only. Small values can lead to timeouts or hangs 1108inside the guest. A safe minimum for disks is 2 MB/s. 1109@item bps_max=@var{bm},bps_rd_max=@var{rm},bps_wr_max=@var{wm} 1110Specify bursts in bytes per second, either for all request types or for reads 1111or writes only. Bursts allow the guest I/O to spike above the limit 1112temporarily. 1113@item iops=@var{i},iops_rd=@var{r},iops_wr=@var{w} 1114Specify request rate limits in requests per second, either for all request 1115types or for reads or writes only. 1116@item iops_max=@var{bm},iops_rd_max=@var{rm},iops_wr_max=@var{wm} 1117Specify bursts in requests per second, either for all request types or for reads 1118or writes only. Bursts allow the guest I/O to spike above the limit 1119temporarily. 1120@item iops_size=@var{is} 1121Let every @var{is} bytes of a request count as a new request for iops 1122throttling purposes. Use this option to prevent guests from circumventing iops 1123limits by sending fewer but larger requests. 1124@item group=@var{g} 1125Join a throttling quota group with given name @var{g}. All drives that are 1126members of the same group are accounted for together. Use this option to 1127prevent guests from circumventing throttling limits by using many small disks 1128instead of a single larger disk. 1129@end table 1130 1131By default, the @option{cache.writeback=on} mode is used. It will report data 1132writes as completed as soon as the data is present in the host page cache. 1133This is safe as long as your guest OS makes sure to correctly flush disk caches 1134where needed. If your guest OS does not handle volatile disk write caches 1135correctly and your host crashes or loses power, then the guest may experience 1136data corruption. 1137 1138For such guests, you should consider using @option{cache.writeback=off}. This 1139means that the host page cache will be used to read and write data, but write 1140notification will be sent to the guest only after QEMU has made sure to flush 1141each write to the disk. Be aware that this has a major impact on performance. 1142 1143When using the @option{-snapshot} option, unsafe caching is always used. 1144 1145Copy-on-read avoids accessing the same backing file sectors repeatedly and is 1146useful when the backing file is over a slow network. By default copy-on-read 1147is off. 1148 1149Instead of @option{-cdrom} you can use: 1150@example 1151qemu-system-i386 -drive file=file,index=2,media=cdrom 1152@end example 1153 1154Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can 1155use: 1156@example 1157qemu-system-i386 -drive file=file,index=0,media=disk 1158qemu-system-i386 -drive file=file,index=1,media=disk 1159qemu-system-i386 -drive file=file,index=2,media=disk 1160qemu-system-i386 -drive file=file,index=3,media=disk 1161@end example 1162 1163You can open an image using pre-opened file descriptors from an fd set: 1164@example 1165qemu-system-i386 1166-add-fd fd=3,set=2,opaque="rdwr:/path/to/file" 1167-add-fd fd=4,set=2,opaque="rdonly:/path/to/file" 1168-drive file=/dev/fdset/2,index=0,media=disk 1169@end example 1170 1171You can connect a CDROM to the slave of ide0: 1172@example 1173qemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom 1174@end example 1175 1176If you don't specify the "file=" argument, you define an empty drive: 1177@example 1178qemu-system-i386 -drive if=ide,index=1,media=cdrom 1179@end example 1180 1181Instead of @option{-fda}, @option{-fdb}, you can use: 1182@example 1183qemu-system-i386 -drive file=file,index=0,if=floppy 1184qemu-system-i386 -drive file=file,index=1,if=floppy 1185@end example 1186 1187By default, @var{interface} is "ide" and @var{index} is automatically 1188incremented: 1189@example 1190qemu-system-i386 -drive file=a -drive file=b" 1191@end example 1192is interpreted like: 1193@example 1194qemu-system-i386 -hda a -hdb b 1195@end example 1196ETEXI 1197 1198DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock, 1199 "-mtdblock file use 'file' as on-board Flash memory image\n", 1200 QEMU_ARCH_ALL) 1201STEXI 1202@item -mtdblock @var{file} 1203@findex -mtdblock 1204Use @var{file} as on-board Flash memory image. 1205ETEXI 1206 1207DEF("sd", HAS_ARG, QEMU_OPTION_sd, 1208 "-sd file use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL) 1209STEXI 1210@item -sd @var{file} 1211@findex -sd 1212Use @var{file} as SecureDigital card image. 1213ETEXI 1214 1215DEF("pflash", HAS_ARG, QEMU_OPTION_pflash, 1216 "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL) 1217STEXI 1218@item -pflash @var{file} 1219@findex -pflash 1220Use @var{file} as a parallel flash image. 1221ETEXI 1222 1223DEF("snapshot", 0, QEMU_OPTION_snapshot, 1224 "-snapshot write to temporary files instead of disk image files\n", 1225 QEMU_ARCH_ALL) 1226STEXI 1227@item -snapshot 1228@findex -snapshot 1229Write to temporary files instead of disk image files. In this case, 1230the raw disk image you use is not written back. You can however force 1231the write back by pressing @key{C-a s} (@pxref{disk_images}). 1232ETEXI 1233 1234DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev, 1235 "-fsdev fsdriver,id=id[,path=path,][security_model={mapped-xattr|mapped-file|passthrough|none}]\n" 1236 " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd][,fmode=fmode][,dmode=dmode]\n" 1237 " [[,throttling.bps-total=b]|[[,throttling.bps-read=r][,throttling.bps-write=w]]]\n" 1238 " [[,throttling.iops-total=i]|[[,throttling.iops-read=r][,throttling.iops-write=w]]]\n" 1239 " [[,throttling.bps-total-max=bm]|[[,throttling.bps-read-max=rm][,throttling.bps-write-max=wm]]]\n" 1240 " [[,throttling.iops-total-max=im]|[[,throttling.iops-read-max=irm][,throttling.iops-write-max=iwm]]]\n" 1241 " [[,throttling.iops-size=is]]\n", 1242 QEMU_ARCH_ALL) 1243 1244STEXI 1245 1246@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}][,fmode=@var{fmode}][,dmode=@var{dmode}] 1247@findex -fsdev 1248Define a new file system device. Valid options are: 1249@table @option 1250@item @var{fsdriver} 1251This option specifies the fs driver backend to use. 1252Currently "local" and "proxy" file system drivers are supported. 1253@item id=@var{id} 1254Specifies identifier for this device 1255@item path=@var{path} 1256Specifies the export path for the file system device. Files under 1257this path will be available to the 9p client on the guest. 1258@item security_model=@var{security_model} 1259Specifies the security model to be used for this export path. 1260Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none". 1261In "passthrough" security model, files are stored using the same 1262credentials as they are created on the guest. This requires QEMU 1263to run as root. In "mapped-xattr" security model, some of the file 1264attributes like uid, gid, mode bits and link target are stored as 1265file attributes. For "mapped-file" these attributes are stored in the 1266hidden .virtfs_metadata directory. Directories exported by this security model cannot 1267interact with other unix tools. "none" security model is same as 1268passthrough except the sever won't report failures if it fails to 1269set file attributes like ownership. Security model is mandatory 1270only for local fsdriver. Other fsdrivers (like proxy) don't take 1271security model as a parameter. 1272@item writeout=@var{writeout} 1273This is an optional argument. The only supported value is "immediate". 1274This means that host page cache will be used to read and write data but 1275write notification will be sent to the guest only when the data has been 1276reported as written by the storage subsystem. 1277@item readonly 1278Enables exporting 9p share as a readonly mount for guests. By default 1279read-write access is given. 1280@item socket=@var{socket} 1281Enables proxy filesystem driver to use passed socket file for communicating 1282with virtfs-proxy-helper 1283@item sock_fd=@var{sock_fd} 1284Enables proxy filesystem driver to use passed socket descriptor for 1285communicating with virtfs-proxy-helper. Usually a helper like libvirt 1286will create socketpair and pass one of the fds as sock_fd 1287@item fmode=@var{fmode} 1288Specifies the default mode for newly created files on the host. Works only 1289with security models "mapped-xattr" and "mapped-file". 1290@item dmode=@var{dmode} 1291Specifies the default mode for newly created directories on the host. Works 1292only with security models "mapped-xattr" and "mapped-file". 1293@end table 1294 1295-fsdev option is used along with -device driver "virtio-9p-pci". 1296@item -device virtio-9p-pci,fsdev=@var{id},mount_tag=@var{mount_tag} 1297Options for virtio-9p-pci driver are: 1298@table @option 1299@item fsdev=@var{id} 1300Specifies the id value specified along with -fsdev option 1301@item mount_tag=@var{mount_tag} 1302Specifies the tag name to be used by the guest to mount this export point 1303@end table 1304 1305ETEXI 1306 1307DEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs, 1308 "-virtfs local,path=path,mount_tag=tag,security_model=[mapped-xattr|mapped-file|passthrough|none]\n" 1309 " [,id=id][,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd][,fmode=fmode][,dmode=dmode]\n", 1310 QEMU_ARCH_ALL) 1311 1312STEXI 1313 1314@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}][,fmode=@var{fmode}][,dmode=@var{dmode}] 1315@findex -virtfs 1316 1317The general form of a Virtual File system pass-through options are: 1318@table @option 1319@item @var{fsdriver} 1320This option specifies the fs driver backend to use. 1321Currently "local" and "proxy" file system drivers are supported. 1322@item id=@var{id} 1323Specifies identifier for this device 1324@item path=@var{path} 1325Specifies the export path for the file system device. Files under 1326this path will be available to the 9p client on the guest. 1327@item security_model=@var{security_model} 1328Specifies the security model to be used for this export path. 1329Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none". 1330In "passthrough" security model, files are stored using the same 1331credentials as they are created on the guest. This requires QEMU 1332to run as root. In "mapped-xattr" security model, some of the file 1333attributes like uid, gid, mode bits and link target are stored as 1334file attributes. For "mapped-file" these attributes are stored in the 1335hidden .virtfs_metadata directory. Directories exported by this security model cannot 1336interact with other unix tools. "none" security model is same as 1337passthrough except the sever won't report failures if it fails to 1338set file attributes like ownership. Security model is mandatory only 1339for local fsdriver. Other fsdrivers (like proxy) don't take security 1340model as a parameter. 1341@item writeout=@var{writeout} 1342This is an optional argument. The only supported value is "immediate". 1343This means that host page cache will be used to read and write data but 1344write notification will be sent to the guest only when the data has been 1345reported as written by the storage subsystem. 1346@item readonly 1347Enables exporting 9p share as a readonly mount for guests. By default 1348read-write access is given. 1349@item socket=@var{socket} 1350Enables proxy filesystem driver to use passed socket file for 1351communicating with virtfs-proxy-helper. Usually a helper like libvirt 1352will create socketpair and pass one of the fds as sock_fd 1353@item sock_fd 1354Enables proxy filesystem driver to use passed 'sock_fd' as the socket 1355descriptor for interfacing with virtfs-proxy-helper 1356@item fmode=@var{fmode} 1357Specifies the default mode for newly created files on the host. Works only 1358with security models "mapped-xattr" and "mapped-file". 1359@item dmode=@var{dmode} 1360Specifies the default mode for newly created directories on the host. Works 1361only with security models "mapped-xattr" and "mapped-file". 1362@end table 1363ETEXI 1364 1365DEF("virtfs_synth", 0, QEMU_OPTION_virtfs_synth, 1366 "-virtfs_synth Create synthetic file system image\n", 1367 QEMU_ARCH_ALL) 1368STEXI 1369@item -virtfs_synth 1370@findex -virtfs_synth 1371Create synthetic file system image 1372ETEXI 1373 1374DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi, 1375 "-iscsi [user=user][,password=password]\n" 1376 " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n" 1377 " [,initiator-name=initiator-iqn][,id=target-iqn]\n" 1378 " [,timeout=timeout]\n" 1379 " iSCSI session parameters\n", QEMU_ARCH_ALL) 1380 1381STEXI 1382@item -iscsi 1383@findex -iscsi 1384Configure iSCSI session parameters. 1385ETEXI 1386 1387STEXI 1388@end table 1389ETEXI 1390DEFHEADING() 1391 1392DEFHEADING(USB options:) 1393STEXI 1394@table @option 1395ETEXI 1396 1397DEF("usb", 0, QEMU_OPTION_usb, 1398 "-usb enable the USB driver (if it is not used by default yet)\n", 1399 QEMU_ARCH_ALL) 1400STEXI 1401@item -usb 1402@findex -usb 1403Enable the USB driver (if it is not used by default yet). 1404ETEXI 1405 1406DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice, 1407 "-usbdevice name add the host or guest USB device 'name'\n", 1408 QEMU_ARCH_ALL) 1409STEXI 1410 1411@item -usbdevice @var{devname} 1412@findex -usbdevice 1413Add the USB device @var{devname}. Note that this option is deprecated, 1414please use @code{-device usb-...} instead. @xref{usb_devices}. 1415 1416@table @option 1417 1418@item mouse 1419Virtual Mouse. This will override the PS/2 mouse emulation when activated. 1420 1421@item tablet 1422Pointer device that uses absolute coordinates (like a touchscreen). This 1423means QEMU is able to report the mouse position without having to grab the 1424mouse. Also overrides the PS/2 mouse emulation when activated. 1425 1426@item braille 1427Braille device. This will use BrlAPI to display the braille output on a real 1428or fake device. 1429 1430@end table 1431ETEXI 1432 1433STEXI 1434@end table 1435ETEXI 1436DEFHEADING() 1437 1438DEFHEADING(Display options:) 1439STEXI 1440@table @option 1441ETEXI 1442 1443DEF("display", HAS_ARG, QEMU_OPTION_display, 1444 "-display spice-app[,gl=on|off]\n" 1445 "-display sdl[,frame=on|off][,alt_grab=on|off][,ctrl_grab=on|off]\n" 1446 " [,window_close=on|off][,gl=on|core|es|off]\n" 1447 "-display gtk[,grab_on_hover=on|off][,gl=on|off]|\n" 1448 "-display vnc=<display>[,<optargs>]\n" 1449 "-display curses[,charset=<encoding>]\n" 1450 "-display none\n" 1451 "-display egl-headless[,rendernode=<file>]" 1452 " select display type\n" 1453 "The default display is equivalent to\n" 1454#if defined(CONFIG_GTK) 1455 "\t\"-display gtk\"\n" 1456#elif defined(CONFIG_SDL) 1457 "\t\"-display sdl\"\n" 1458#elif defined(CONFIG_COCOA) 1459 "\t\"-display cocoa\"\n" 1460#elif defined(CONFIG_VNC) 1461 "\t\"-vnc localhost:0,to=99,id=default\"\n" 1462#else 1463 "\t\"-display none\"\n" 1464#endif 1465 , QEMU_ARCH_ALL) 1466STEXI 1467@item -display @var{type} 1468@findex -display 1469Select type of display to use. This option is a replacement for the 1470old style -sdl/-curses/... options. Valid values for @var{type} are 1471@table @option 1472@item sdl 1473Display video output via SDL (usually in a separate graphics 1474window; see the SDL documentation for other possibilities). 1475@item curses 1476Display video output via curses. For graphics device models which 1477support a text mode, QEMU can display this output using a 1478curses/ncurses interface. Nothing is displayed when the graphics 1479device is in graphical mode or if the graphics device does not support 1480a text mode. Generally only the VGA device models support text mode. 1481The font charset used by the guest can be specified with the 1482@code{charset} option, for example @code{charset=CP850} for IBM CP850 1483encoding. The default is @code{CP437}. 1484@item none 1485Do not display video output. The guest will still see an emulated 1486graphics card, but its output will not be displayed to the QEMU 1487user. This option differs from the -nographic option in that it 1488only affects what is done with video output; -nographic also changes 1489the destination of the serial and parallel port data. 1490@item gtk 1491Display video output in a GTK window. This interface provides drop-down 1492menus and other UI elements to configure and control the VM during 1493runtime. 1494@item vnc 1495Start a VNC server on display <arg> 1496@item egl-headless 1497Offload all OpenGL operations to a local DRI device. For any graphical display, 1498this display needs to be paired with either VNC or SPICE displays. 1499@item spice-app 1500Start QEMU as a Spice server and launch the default Spice client 1501application. The Spice server will redirect the serial consoles and 1502QEMU monitors. (Since 4.0) 1503@end table 1504ETEXI 1505 1506DEF("nographic", 0, QEMU_OPTION_nographic, 1507 "-nographic disable graphical output and redirect serial I/Os to console\n", 1508 QEMU_ARCH_ALL) 1509STEXI 1510@item -nographic 1511@findex -nographic 1512Normally, if QEMU is compiled with graphical window support, it displays 1513output such as guest graphics, guest console, and the QEMU monitor in a 1514window. With this option, you can totally disable graphical output so 1515that QEMU is a simple command line application. The emulated serial port 1516is redirected on the console and muxed with the monitor (unless 1517redirected elsewhere explicitly). Therefore, you can still use QEMU to 1518debug a Linux kernel with a serial console. Use @key{C-a h} for help on 1519switching between the console and monitor. 1520ETEXI 1521 1522DEF("curses", 0, QEMU_OPTION_curses, 1523 "-curses shorthand for -display curses\n", 1524 QEMU_ARCH_ALL) 1525STEXI 1526@item -curses 1527@findex -curses 1528Normally, if QEMU is compiled with graphical window support, it displays 1529output such as guest graphics, guest console, and the QEMU monitor in a 1530window. With this option, QEMU can display the VGA output when in text 1531mode using a curses/ncurses interface. Nothing is displayed in graphical 1532mode. 1533ETEXI 1534 1535DEF("alt-grab", 0, QEMU_OPTION_alt_grab, 1536 "-alt-grab use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n", 1537 QEMU_ARCH_ALL) 1538STEXI 1539@item -alt-grab 1540@findex -alt-grab 1541Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also 1542affects the special keys (for fullscreen, monitor-mode switching, etc). 1543ETEXI 1544 1545DEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab, 1546 "-ctrl-grab use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n", 1547 QEMU_ARCH_ALL) 1548STEXI 1549@item -ctrl-grab 1550@findex -ctrl-grab 1551Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also 1552affects the special keys (for fullscreen, monitor-mode switching, etc). 1553ETEXI 1554 1555DEF("no-quit", 0, QEMU_OPTION_no_quit, 1556 "-no-quit disable SDL window close capability\n", QEMU_ARCH_ALL) 1557STEXI 1558@item -no-quit 1559@findex -no-quit 1560Disable SDL window close capability. 1561ETEXI 1562 1563DEF("sdl", 0, QEMU_OPTION_sdl, 1564 "-sdl shorthand for -display sdl\n", QEMU_ARCH_ALL) 1565STEXI 1566@item -sdl 1567@findex -sdl 1568Enable SDL. 1569ETEXI 1570 1571DEF("spice", HAS_ARG, QEMU_OPTION_spice, 1572 "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n" 1573 " [,x509-key-file=<file>][,x509-key-password=<file>]\n" 1574 " [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n" 1575 " [,x509-dh-key-file=<file>][,addr=addr][,ipv4|ipv6|unix]\n" 1576 " [,tls-ciphers=<list>]\n" 1577 " [,tls-channel=[main|display|cursor|inputs|record|playback]]\n" 1578 " [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n" 1579 " [,sasl][,password=<secret>][,disable-ticketing]\n" 1580 " [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n" 1581 " [,jpeg-wan-compression=[auto|never|always]]\n" 1582 " [,zlib-glz-wan-compression=[auto|never|always]]\n" 1583 " [,streaming-video=[off|all|filter]][,disable-copy-paste]\n" 1584 " [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n" 1585 " [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n" 1586 " [,gl=[on|off]][,rendernode=<file>]\n" 1587 " enable spice\n" 1588 " at least one of {port, tls-port} is mandatory\n", 1589 QEMU_ARCH_ALL) 1590STEXI 1591@item -spice @var{option}[,@var{option}[,...]] 1592@findex -spice 1593Enable the spice remote desktop protocol. Valid options are 1594 1595@table @option 1596 1597@item port=<nr> 1598Set the TCP port spice is listening on for plaintext channels. 1599 1600@item addr=<addr> 1601Set the IP address spice is listening on. Default is any address. 1602 1603@item ipv4 1604@itemx ipv6 1605@itemx unix 1606Force using the specified IP version. 1607 1608@item password=<secret> 1609Set the password you need to authenticate. 1610 1611@item sasl 1612Require that the client use SASL to authenticate with the spice. 1613The exact choice of authentication method used is controlled from the 1614system / user's SASL configuration file for the 'qemu' service. This 1615is typically found in /etc/sasl2/qemu.conf. If running QEMU as an 1616unprivileged user, an environment variable SASL_CONF_PATH can be used 1617to make it search alternate locations for the service config. 1618While some SASL auth methods can also provide data encryption (eg GSSAPI), 1619it is recommended that SASL always be combined with the 'tls' and 1620'x509' settings to enable use of SSL and server certificates. This 1621ensures a data encryption preventing compromise of authentication 1622credentials. 1623 1624@item disable-ticketing 1625Allow client connects without authentication. 1626 1627@item disable-copy-paste 1628Disable copy paste between the client and the guest. 1629 1630@item disable-agent-file-xfer 1631Disable spice-vdagent based file-xfer between the client and the guest. 1632 1633@item tls-port=<nr> 1634Set the TCP port spice is listening on for encrypted channels. 1635 1636@item x509-dir=<dir> 1637Set the x509 file directory. Expects same filenames as -vnc $display,x509=$dir 1638 1639@item x509-key-file=<file> 1640@itemx x509-key-password=<file> 1641@itemx x509-cert-file=<file> 1642@itemx x509-cacert-file=<file> 1643@itemx x509-dh-key-file=<file> 1644The x509 file names can also be configured individually. 1645 1646@item tls-ciphers=<list> 1647Specify which ciphers to use. 1648 1649@item tls-channel=[main|display|cursor|inputs|record|playback] 1650@itemx plaintext-channel=[main|display|cursor|inputs|record|playback] 1651Force specific channel to be used with or without TLS encryption. The 1652options can be specified multiple times to configure multiple 1653channels. The special name "default" can be used to set the default 1654mode. For channels which are not explicitly forced into one mode the 1655spice client is allowed to pick tls/plaintext as he pleases. 1656 1657@item image-compression=[auto_glz|auto_lz|quic|glz|lz|off] 1658Configure image compression (lossless). 1659Default is auto_glz. 1660 1661@item jpeg-wan-compression=[auto|never|always] 1662@itemx zlib-glz-wan-compression=[auto|never|always] 1663Configure wan image compression (lossy for slow links). 1664Default is auto. 1665 1666@item streaming-video=[off|all|filter] 1667Configure video stream detection. Default is off. 1668 1669@item agent-mouse=[on|off] 1670Enable/disable passing mouse events via vdagent. Default is on. 1671 1672@item playback-compression=[on|off] 1673Enable/disable audio stream compression (using celt 0.5.1). Default is on. 1674 1675@item seamless-migration=[on|off] 1676Enable/disable spice seamless migration. Default is off. 1677 1678@item gl=[on|off] 1679Enable/disable OpenGL context. Default is off. 1680 1681@item rendernode=<file> 1682DRM render node for OpenGL rendering. If not specified, it will pick 1683the first available. (Since 2.9) 1684 1685@end table 1686ETEXI 1687 1688DEF("portrait", 0, QEMU_OPTION_portrait, 1689 "-portrait rotate graphical output 90 deg left (only PXA LCD)\n", 1690 QEMU_ARCH_ALL) 1691STEXI 1692@item -portrait 1693@findex -portrait 1694Rotate graphical output 90 deg left (only PXA LCD). 1695ETEXI 1696 1697DEF("rotate", HAS_ARG, QEMU_OPTION_rotate, 1698 "-rotate <deg> rotate graphical output some deg left (only PXA LCD)\n", 1699 QEMU_ARCH_ALL) 1700STEXI 1701@item -rotate @var{deg} 1702@findex -rotate 1703Rotate graphical output some deg left (only PXA LCD). 1704ETEXI 1705 1706DEF("vga", HAS_ARG, QEMU_OPTION_vga, 1707 "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|virtio|none]\n" 1708 " select video card type\n", QEMU_ARCH_ALL) 1709STEXI 1710@item -vga @var{type} 1711@findex -vga 1712Select type of VGA card to emulate. Valid values for @var{type} are 1713@table @option 1714@item cirrus 1715Cirrus Logic GD5446 Video card. All Windows versions starting from 1716Windows 95 should recognize and use this graphic card. For optimal 1717performances, use 16 bit color depth in the guest and the host OS. 1718(This card was the default before QEMU 2.2) 1719@item std 1720Standard VGA card with Bochs VBE extensions. If your guest OS 1721supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want 1722to use high resolution modes (>= 1280x1024x16) then you should use 1723this option. (This card is the default since QEMU 2.2) 1724@item vmware 1725VMWare SVGA-II compatible adapter. Use it if you have sufficiently 1726recent XFree86/XOrg server or Windows guest with a driver for this 1727card. 1728@item qxl 1729QXL paravirtual graphic card. It is VGA compatible (including VESA 17302.0 VBE support). Works best with qxl guest drivers installed though. 1731Recommended choice when using the spice protocol. 1732@item tcx 1733(sun4m only) Sun TCX framebuffer. This is the default framebuffer for 1734sun4m machines and offers both 8-bit and 24-bit colour depths at a 1735fixed resolution of 1024x768. 1736@item cg3 1737(sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer 1738for sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP) 1739resolutions aimed at people wishing to run older Solaris versions. 1740@item virtio 1741Virtio VGA card. 1742@item none 1743Disable VGA card. 1744@end table 1745ETEXI 1746 1747DEF("full-screen", 0, QEMU_OPTION_full_screen, 1748 "-full-screen start in full screen\n", QEMU_ARCH_ALL) 1749STEXI 1750@item -full-screen 1751@findex -full-screen 1752Start in full screen. 1753ETEXI 1754 1755DEF("g", 1, QEMU_OPTION_g , 1756 "-g WxH[xDEPTH] Set the initial graphical resolution and depth\n", 1757 QEMU_ARCH_PPC | QEMU_ARCH_SPARC) 1758STEXI 1759@item -g @var{width}x@var{height}[x@var{depth}] 1760@findex -g 1761Set the initial graphical resolution and depth (PPC, SPARC only). 1762ETEXI 1763 1764DEF("vnc", HAS_ARG, QEMU_OPTION_vnc , 1765 "-vnc <display> shorthand for -display vnc=<display>\n", QEMU_ARCH_ALL) 1766STEXI 1767@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]] 1768@findex -vnc 1769Normally, if QEMU is compiled with graphical window support, it displays 1770output such as guest graphics, guest console, and the QEMU monitor in a 1771window. With this option, you can have QEMU listen on VNC display 1772@var{display} and redirect the VGA display over the VNC session. It is 1773very useful to enable the usb tablet device when using this option 1774(option @option{-device usb-tablet}). When using the VNC display, you 1775must use the @option{-k} parameter to set the keyboard layout if you are 1776not using en-us. Valid syntax for the @var{display} is 1777 1778@table @option 1779 1780@item to=@var{L} 1781 1782With this option, QEMU will try next available VNC @var{display}s, until the 1783number @var{L}, if the origianlly defined "-vnc @var{display}" is not 1784available, e.g. port 5900+@var{display} is already used by another 1785application. By default, to=0. 1786 1787@item @var{host}:@var{d} 1788 1789TCP connections will only be allowed from @var{host} on display @var{d}. 1790By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can 1791be omitted in which case the server will accept connections from any host. 1792 1793@item unix:@var{path} 1794 1795Connections will be allowed over UNIX domain sockets where @var{path} is the 1796location of a unix socket to listen for connections on. 1797 1798@item none 1799 1800VNC is initialized but not started. The monitor @code{change} command 1801can be used to later start the VNC server. 1802 1803@end table 1804 1805Following the @var{display} value there may be one or more @var{option} flags 1806separated by commas. Valid options are 1807 1808@table @option 1809 1810@item reverse 1811 1812Connect to a listening VNC client via a ``reverse'' connection. The 1813client is specified by the @var{display}. For reverse network 1814connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument 1815is a TCP port number, not a display number. 1816 1817@item websocket 1818 1819Opens an additional TCP listening port dedicated to VNC Websocket connections. 1820If a bare @var{websocket} option is given, the Websocket port is 18215700+@var{display}. An alternative port can be specified with the 1822syntax @code{websocket}=@var{port}. 1823 1824If @var{host} is specified connections will only be allowed from this host. 1825It is possible to control the websocket listen address independently, using 1826the syntax @code{websocket}=@var{host}:@var{port}. 1827 1828If no TLS credentials are provided, the websocket connection runs in 1829unencrypted mode. If TLS credentials are provided, the websocket connection 1830requires encrypted client connections. 1831 1832@item password 1833 1834Require that password based authentication is used for client connections. 1835 1836The password must be set separately using the @code{set_password} command in 1837the @ref{pcsys_monitor}. The syntax to change your password is: 1838@code{set_password <protocol> <password>} where <protocol> could be either 1839"vnc" or "spice". 1840 1841If you would like to change <protocol> password expiration, you should use 1842@code{expire_password <protocol> <expiration-time>} where expiration time could 1843be one of the following options: now, never, +seconds or UNIX time of 1844expiration, e.g. +60 to make password expire in 60 seconds, or 1335196800 1845to make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this 1846date and time). 1847 1848You can also use keywords "now" or "never" for the expiration time to 1849allow <protocol> password to expire immediately or never expire. 1850 1851@item tls-creds=@var{ID} 1852 1853Provides the ID of a set of TLS credentials to use to secure the 1854VNC server. They will apply to both the normal VNC server socket 1855and the websocket socket (if enabled). Setting TLS credentials 1856will cause the VNC server socket to enable the VeNCrypt auth 1857mechanism. The credentials should have been previously created 1858using the @option{-object tls-creds} argument. 1859 1860@item tls-authz=@var{ID} 1861 1862Provides the ID of the QAuthZ authorization object against which 1863the client's x509 distinguished name will validated. This object is 1864only resolved at time of use, so can be deleted and recreated on the 1865fly while the VNC server is active. If missing, it will default 1866to denying access. 1867 1868@item sasl 1869 1870Require that the client use SASL to authenticate with the VNC server. 1871The exact choice of authentication method used is controlled from the 1872system / user's SASL configuration file for the 'qemu' service. This 1873is typically found in /etc/sasl2/qemu.conf. If running QEMU as an 1874unprivileged user, an environment variable SASL_CONF_PATH can be used 1875to make it search alternate locations for the service config. 1876While some SASL auth methods can also provide data encryption (eg GSSAPI), 1877it is recommended that SASL always be combined with the 'tls' and 1878'x509' settings to enable use of SSL and server certificates. This 1879ensures a data encryption preventing compromise of authentication 1880credentials. See the @ref{vnc_security} section for details on using 1881SASL authentication. 1882 1883@item sasl-authz=@var{ID} 1884 1885Provides the ID of the QAuthZ authorization object against which 1886the client's SASL username will validated. This object is 1887only resolved at time of use, so can be deleted and recreated on the 1888fly while the VNC server is active. If missing, it will default 1889to denying access. 1890 1891@item acl 1892 1893Legacy method for enabling authorization of clients against the 1894x509 distinguished name and SASL username. It results in the creation 1895of two @code{authz-list} objects with IDs of @code{vnc.username} and 1896@code{vnc.x509dname}. The rules for these objects must be configured 1897with the HMP ACL commands. 1898 1899This option is deprecated and should no longer be used. The new 1900@option{sasl-authz} and @option{tls-authz} options are a 1901replacement. 1902 1903@item lossy 1904 1905Enable lossy compression methods (gradient, JPEG, ...). If this 1906option is set, VNC client may receive lossy framebuffer updates 1907depending on its encoding settings. Enabling this option can save 1908a lot of bandwidth at the expense of quality. 1909 1910@item non-adaptive 1911 1912Disable adaptive encodings. Adaptive encodings are enabled by default. 1913An adaptive encoding will try to detect frequently updated screen regions, 1914and send updates in these regions using a lossy encoding (like JPEG). 1915This can be really helpful to save bandwidth when playing videos. Disabling 1916adaptive encodings restores the original static behavior of encodings 1917like Tight. 1918 1919@item share=[allow-exclusive|force-shared|ignore] 1920 1921Set display sharing policy. 'allow-exclusive' allows clients to ask 1922for exclusive access. As suggested by the rfb spec this is 1923implemented by dropping other connections. Connecting multiple 1924clients in parallel requires all clients asking for a shared session 1925(vncviewer: -shared switch). This is the default. 'force-shared' 1926disables exclusive client access. Useful for shared desktop sessions, 1927where you don't want someone forgetting specify -shared disconnect 1928everybody else. 'ignore' completely ignores the shared flag and 1929allows everybody connect unconditionally. Doesn't conform to the rfb 1930spec but is traditional QEMU behavior. 1931 1932@item key-delay-ms 1933 1934Set keyboard delay, for key down and key up events, in milliseconds. 1935Default is 10. Keyboards are low-bandwidth devices, so this slowdown 1936can help the device and guest to keep up and not lose events in case 1937events are arriving in bulk. Possible causes for the latter are flaky 1938network connections, or scripts for automated testing. 1939 1940@end table 1941ETEXI 1942 1943STEXI 1944@end table 1945ETEXI 1946ARCHHEADING(, QEMU_ARCH_I386) 1947 1948ARCHHEADING(i386 target only:, QEMU_ARCH_I386) 1949STEXI 1950@table @option 1951ETEXI 1952 1953DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack, 1954 "-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n", 1955 QEMU_ARCH_I386) 1956STEXI 1957@item -win2k-hack 1958@findex -win2k-hack 1959Use it when installing Windows 2000 to avoid a disk full bug. After 1960Windows 2000 is installed, you no longer need this option (this option 1961slows down the IDE transfers). 1962ETEXI 1963 1964DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk, 1965 "-no-fd-bootchk disable boot signature checking for floppy disks\n", 1966 QEMU_ARCH_I386) 1967STEXI 1968@item -no-fd-bootchk 1969@findex -no-fd-bootchk 1970Disable boot signature checking for floppy disks in BIOS. May 1971be needed to boot from old floppy disks. 1972ETEXI 1973 1974DEF("no-acpi", 0, QEMU_OPTION_no_acpi, 1975 "-no-acpi disable ACPI\n", QEMU_ARCH_I386 | QEMU_ARCH_ARM) 1976STEXI 1977@item -no-acpi 1978@findex -no-acpi 1979Disable ACPI (Advanced Configuration and Power Interface) support. Use 1980it if your guest OS complains about ACPI problems (PC target machine 1981only). 1982ETEXI 1983 1984DEF("no-hpet", 0, QEMU_OPTION_no_hpet, 1985 "-no-hpet disable HPET\n", QEMU_ARCH_I386) 1986STEXI 1987@item -no-hpet 1988@findex -no-hpet 1989Disable HPET support. 1990ETEXI 1991 1992DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable, 1993 "-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" 1994 " ACPI table description\n", QEMU_ARCH_I386) 1995STEXI 1996@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}]...] 1997@findex -acpitable 1998Add ACPI table with specified header fields and context from specified files. 1999For file=, take whole ACPI table from the specified files, including all 2000ACPI headers (possible overridden by other options). 2001For data=, only data 2002portion of the table is used, all header information is specified in the 2003command line. 2004If a SLIC table is supplied to QEMU, then the SLIC's oem_id and oem_table_id 2005fields will override the same in the RSDT and the FADT (a.k.a. FACP), in order 2006to ensure the field matches required by the Microsoft SLIC spec and the ACPI 2007spec. 2008ETEXI 2009 2010DEF("smbios", HAS_ARG, QEMU_OPTION_smbios, 2011 "-smbios file=binary\n" 2012 " load SMBIOS entry from binary file\n" 2013 "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n" 2014 " [,uefi=on|off]\n" 2015 " specify SMBIOS type 0 fields\n" 2016 "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n" 2017 " [,uuid=uuid][,sku=str][,family=str]\n" 2018 " specify SMBIOS type 1 fields\n" 2019 "-smbios type=2[,manufacturer=str][,product=str][,version=str][,serial=str]\n" 2020 " [,asset=str][,location=str]\n" 2021 " specify SMBIOS type 2 fields\n" 2022 "-smbios type=3[,manufacturer=str][,version=str][,serial=str][,asset=str]\n" 2023 " [,sku=str]\n" 2024 " specify SMBIOS type 3 fields\n" 2025 "-smbios type=4[,sock_pfx=str][,manufacturer=str][,version=str][,serial=str]\n" 2026 " [,asset=str][,part=str]\n" 2027 " specify SMBIOS type 4 fields\n" 2028 "-smbios type=17[,loc_pfx=str][,bank=str][,manufacturer=str][,serial=str]\n" 2029 " [,asset=str][,part=str][,speed=%d]\n" 2030 " specify SMBIOS type 17 fields\n", 2031 QEMU_ARCH_I386 | QEMU_ARCH_ARM) 2032STEXI 2033@item -smbios file=@var{binary} 2034@findex -smbios 2035Load SMBIOS entry from binary file. 2036 2037@item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}][,uefi=on|off] 2038Specify SMBIOS type 0 fields 2039 2040@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}] 2041Specify SMBIOS type 1 fields 2042 2043@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}] 2044Specify SMBIOS type 2 fields 2045 2046@item -smbios type=3[,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,sku=@var{str}] 2047Specify SMBIOS type 3 fields 2048 2049@item -smbios type=4[,sock_pfx=@var{str}][,manufacturer=@var{str}][,version=@var{str}][,serial=@var{str}][,asset=@var{str}][,part=@var{str}] 2050Specify SMBIOS type 4 fields 2051 2052@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}] 2053Specify SMBIOS type 17 fields 2054ETEXI 2055 2056STEXI 2057@end table 2058ETEXI 2059DEFHEADING() 2060 2061DEFHEADING(Network options:) 2062STEXI 2063@table @option 2064ETEXI 2065 2066DEF("netdev", HAS_ARG, QEMU_OPTION_netdev, 2067#ifdef CONFIG_SLIRP 2068 "-netdev user,id=str[,ipv4[=on|off]][,net=addr[/mask]][,host=addr]\n" 2069 " [,ipv6[=on|off]][,ipv6-net=addr[/int]][,ipv6-host=addr]\n" 2070 " [,restrict=on|off][,hostname=host][,dhcpstart=addr]\n" 2071 " [,dns=addr][,ipv6-dns=addr][,dnssearch=domain][,domainname=domain]\n" 2072 " [,tftp=dir][,tftp-server-name=name][,bootfile=f][,hostfwd=rule][,guestfwd=rule]" 2073#ifndef _WIN32 2074 "[,smb=dir[,smbserver=addr]]\n" 2075#endif 2076 " configure a user mode network backend with ID 'str',\n" 2077 " its DHCP server and optional services\n" 2078#endif 2079#ifdef _WIN32 2080 "-netdev tap,id=str,ifname=name\n" 2081 " configure a host TAP network backend with ID 'str'\n" 2082#else 2083 "-netdev tap,id=str[,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile]\n" 2084 " [,br=bridge][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off]\n" 2085 " [,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n" 2086 " [,poll-us=n]\n" 2087 " configure a host TAP network backend with ID 'str'\n" 2088 " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n" 2089 " use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n" 2090 " to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n" 2091 " to deconfigure it\n" 2092 " use '[down]script=no' to disable script execution\n" 2093 " use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n" 2094 " configure it\n" 2095 " use 'fd=h' to connect to an already opened TAP interface\n" 2096 " use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n" 2097 " use 'sndbuf=nbytes' to limit the size of the send buffer (the\n" 2098 " default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n" 2099 " use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n" 2100 " use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n" 2101 " use vhost=on to enable experimental in kernel accelerator\n" 2102 " (only has effect for virtio guests which use MSIX)\n" 2103 " use vhostforce=on to force vhost on for non-MSIX virtio guests\n" 2104 " use 'vhostfd=h' to connect to an already opened vhost net device\n" 2105 " use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n" 2106 " use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n" 2107 " use 'poll-us=n' to speciy the maximum number of microseconds that could be\n" 2108 " spent on busy polling for vhost net\n" 2109 "-netdev bridge,id=str[,br=bridge][,helper=helper]\n" 2110 " configure a host TAP network backend with ID 'str' that is\n" 2111 " connected to a bridge (default=" DEFAULT_BRIDGE_INTERFACE ")\n" 2112 " using the program 'helper (default=" DEFAULT_BRIDGE_HELPER ")\n" 2113#endif 2114#ifdef __linux__ 2115 "-netdev l2tpv3,id=str,src=srcaddr,dst=dstaddr[,srcport=srcport][,dstport=dstport]\n" 2116 " [,rxsession=rxsession],txsession=txsession[,ipv6=on/off][,udp=on/off]\n" 2117 " [,cookie64=on/off][,counter][,pincounter][,txcookie=txcookie]\n" 2118 " [,rxcookie=rxcookie][,offset=offset]\n" 2119 " configure a network backend with ID 'str' connected to\n" 2120 " an Ethernet over L2TPv3 pseudowire.\n" 2121 " Linux kernel 3.3+ as well as most routers can talk\n" 2122 " L2TPv3. This transport allows connecting a VM to a VM,\n" 2123 " VM to a router and even VM to Host. It is a nearly-universal\n" 2124 " standard (RFC3391). Note - this implementation uses static\n" 2125 " pre-configured tunnels (same as the Linux kernel).\n" 2126 " use 'src=' to specify source address\n" 2127 " use 'dst=' to specify destination address\n" 2128 " use 'udp=on' to specify udp encapsulation\n" 2129 " use 'srcport=' to specify source udp port\n" 2130 " use 'dstport=' to specify destination udp port\n" 2131 " use 'ipv6=on' to force v6\n" 2132 " L2TPv3 uses cookies to prevent misconfiguration as\n" 2133 " well as a weak security measure\n" 2134 " use 'rxcookie=0x012345678' to specify a rxcookie\n" 2135 " use 'txcookie=0x012345678' to specify a txcookie\n" 2136 " use 'cookie64=on' to set cookie size to 64 bit, otherwise 32\n" 2137 " use 'counter=off' to force a 'cut-down' L2TPv3 with no counter\n" 2138 " use 'pincounter=on' to work around broken counter handling in peer\n" 2139 " use 'offset=X' to add an extra offset between header and data\n" 2140#endif 2141 "-netdev socket,id=str[,fd=h][,listen=[host]:port][,connect=host:port]\n" 2142 " configure a network backend to connect to another network\n" 2143 " using a socket connection\n" 2144 "-netdev socket,id=str[,fd=h][,mcast=maddr:port[,localaddr=addr]]\n" 2145 " configure a network backend to connect to a multicast maddr and port\n" 2146 " use 'localaddr=addr' to specify the host address to send packets from\n" 2147 "-netdev socket,id=str[,fd=h][,udp=host:port][,localaddr=host:port]\n" 2148 " configure a network backend to connect to another network\n" 2149 " using an UDP tunnel\n" 2150#ifdef CONFIG_VDE 2151 "-netdev vde,id=str[,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n" 2152 " configure a network backend to connect to port 'n' of a vde switch\n" 2153 " running on host and listening for incoming connections on 'socketpath'.\n" 2154 " Use group 'groupname' and mode 'octalmode' to change default\n" 2155 " ownership and permissions for communication port.\n" 2156#endif 2157#ifdef CONFIG_NETMAP 2158 "-netdev netmap,id=str,ifname=name[,devname=nmname]\n" 2159 " attach to the existing netmap-enabled network interface 'name', or to a\n" 2160 " VALE port (created on the fly) called 'name' ('nmname' is name of the \n" 2161 " netmap device, defaults to '/dev/netmap')\n" 2162#endif 2163#ifdef CONFIG_POSIX 2164 "-netdev vhost-user,id=str,chardev=dev[,vhostforce=on|off]\n" 2165 " configure a vhost-user network, backed by a chardev 'dev'\n" 2166#endif 2167 "-netdev hubport,id=str,hubid=n[,netdev=nd]\n" 2168 " configure a hub port on the hub with ID 'n'\n", QEMU_ARCH_ALL) 2169DEF("nic", HAS_ARG, QEMU_OPTION_nic, 2170 "-nic [tap|bridge|" 2171#ifdef CONFIG_SLIRP 2172 "user|" 2173#endif 2174#ifdef __linux__ 2175 "l2tpv3|" 2176#endif 2177#ifdef CONFIG_VDE 2178 "vde|" 2179#endif 2180#ifdef CONFIG_NETMAP 2181 "netmap|" 2182#endif 2183#ifdef CONFIG_POSIX 2184 "vhost-user|" 2185#endif 2186 "socket][,option][,...][mac=macaddr]\n" 2187 " initialize an on-board / default host NIC (using MAC address\n" 2188 " macaddr) and connect it to the given host network backend\n" 2189 "-nic none use it alone to have zero network devices (the default is to\n" 2190 " provided a 'user' network connection)\n", 2191 QEMU_ARCH_ALL) 2192DEF("net", HAS_ARG, QEMU_OPTION_net, 2193 "-net nic[,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n" 2194 " configure or create an on-board (or machine default) NIC and\n" 2195 " connect it to hub 0 (please use -nic unless you need a hub)\n" 2196 "-net [" 2197#ifdef CONFIG_SLIRP 2198 "user|" 2199#endif 2200 "tap|" 2201 "bridge|" 2202#ifdef CONFIG_VDE 2203 "vde|" 2204#endif 2205#ifdef CONFIG_NETMAP 2206 "netmap|" 2207#endif 2208 "socket][,option][,option][,...]\n" 2209 " old way to initialize a host network interface\n" 2210 " (use the -netdev option if possible instead)\n", QEMU_ARCH_ALL) 2211STEXI 2212@item -nic [tap|bridge|user|l2tpv3|vde|netmap|vhost-user|socket][,...][,mac=macaddr][,model=mn] 2213@findex -nic 2214This option is a shortcut for configuring both the on-board (default) guest 2215NIC hardware and the host network backend in one go. The host backend options 2216are the same as with the corresponding @option{-netdev} options below. 2217The guest NIC model can be set with @option{model=@var{modelname}}. 2218Use @option{model=help} to list the available device types. 2219The hardware MAC address can be set with @option{mac=@var{macaddr}}. 2220 2221The following two example do exactly the same, to show how @option{-nic} can 2222be used to shorten the command line length (note that the e1000 is the default 2223on i386, so the @option{model=e1000} parameter could even be omitted here, too): 2224@example 2225qemu-system-i386 -netdev user,id=n1,ipv6=off -device e1000,netdev=n1,mac=52:54:98:76:54:32 2226qemu-system-i386 -nic user,ipv6=off,model=e1000,mac=52:54:98:76:54:32 2227@end example 2228 2229@item -nic none 2230Indicate that no network devices should be configured. It is used to override 2231the default configuration (default NIC with ``user'' host network backend) 2232which is activated if no other networking options are provided. 2233 2234@item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...] 2235@findex -netdev 2236Configure user mode host network backend which requires no administrator 2237privilege to run. Valid options are: 2238 2239@table @option 2240@item id=@var{id} 2241Assign symbolic name for use in monitor commands. 2242 2243@item ipv4=on|off and ipv6=on|off 2244Specify that either IPv4 or IPv6 must be enabled. If neither is specified 2245both protocols are enabled. 2246 2247@item net=@var{addr}[/@var{mask}] 2248Set IP network address the guest will see. Optionally specify the netmask, 2249either in the form a.b.c.d or as number of valid top-most bits. Default is 225010.0.2.0/24. 2251 2252@item host=@var{addr} 2253Specify the guest-visible address of the host. Default is the 2nd IP in the 2254guest network, i.e. x.x.x.2. 2255 2256@item ipv6-net=@var{addr}[/@var{int}] 2257Set IPv6 network address the guest will see (default is fec0::/64). The 2258network prefix is given in the usual hexadecimal IPv6 address 2259notation. The prefix size is optional, and is given as the number of 2260valid top-most bits (default is 64). 2261 2262@item ipv6-host=@var{addr} 2263Specify the guest-visible IPv6 address of the host. Default is the 2nd IPv6 in 2264the guest network, i.e. xxxx::2. 2265 2266@item restrict=on|off 2267If this option is enabled, the guest will be isolated, i.e. it will not be 2268able to contact the host and no guest IP packets will be routed over the host 2269to the outside. This option does not affect any explicitly set forwarding rules. 2270 2271@item hostname=@var{name} 2272Specifies the client hostname reported by the built-in DHCP server. 2273 2274@item dhcpstart=@var{addr} 2275Specify the first of the 16 IPs the built-in DHCP server can assign. Default 2276is the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31. 2277 2278@item dns=@var{addr} 2279Specify the guest-visible address of the virtual nameserver. The address must 2280be different from the host address. Default is the 3rd IP in the guest network, 2281i.e. x.x.x.3. 2282 2283@item ipv6-dns=@var{addr} 2284Specify the guest-visible address of the IPv6 virtual nameserver. The address 2285must be different from the host address. Default is the 3rd IP in the guest 2286network, i.e. xxxx::3. 2287 2288@item dnssearch=@var{domain} 2289Provides an entry for the domain-search list sent by the built-in 2290DHCP server. More than one domain suffix can be transmitted by specifying 2291this option multiple times. If supported, this will cause the guest to 2292automatically try to append the given domain suffix(es) in case a domain name 2293can not be resolved. 2294 2295Example: 2296@example 2297qemu-system-i386 -nic user,dnssearch=mgmt.example.org,dnssearch=example.org 2298@end example 2299 2300@item domainname=@var{domain} 2301Specifies the client domain name reported by the built-in DHCP server. 2302 2303@item tftp=@var{dir} 2304When using the user mode network stack, activate a built-in TFTP 2305server. The files in @var{dir} will be exposed as the root of a TFTP server. 2306The TFTP client on the guest must be configured in binary mode (use the command 2307@code{bin} of the Unix TFTP client). 2308 2309@item tftp-server-name=@var{name} 2310In BOOTP reply, broadcast @var{name} as the "TFTP server name" (RFC2132 option 231166). This can be used to advise the guest to load boot files or configurations 2312from a different server than the host address. 2313 2314@item bootfile=@var{file} 2315When using the user mode network stack, broadcast @var{file} as the BOOTP 2316filename. In conjunction with @option{tftp}, this can be used to network boot 2317a guest from a local directory. 2318 2319Example (using pxelinux): 2320@example 2321qemu-system-i386 -hda linux.img -boot n -device e1000,netdev=n1 \ 2322 -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0 2323@end example 2324 2325@item smb=@var{dir}[,smbserver=@var{addr}] 2326When using the user mode network stack, activate a built-in SMB 2327server so that Windows OSes can access to the host files in @file{@var{dir}} 2328transparently. The IP address of the SMB server can be set to @var{addr}. By 2329default the 4th IP in the guest network is used, i.e. x.x.x.4. 2330 2331In the guest Windows OS, the line: 2332@example 233310.0.2.4 smbserver 2334@end example 2335must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me) 2336or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000). 2337 2338Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}. 2339 2340Note that a SAMBA server must be installed on the host OS. 2341 2342@item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport} 2343Redirect incoming TCP or UDP connections to the host port @var{hostport} to 2344the guest IP address @var{guestaddr} on guest port @var{guestport}. If 2345@var{guestaddr} is not specified, its value is x.x.x.15 (default first address 2346given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can 2347be bound to a specific host interface. If no connection type is set, TCP is 2348used. This option can be given multiple times. 2349 2350For example, to redirect host X11 connection from screen 1 to guest 2351screen 0, use the following: 2352 2353@example 2354# on the host 2355qemu-system-i386 -nic user,hostfwd=tcp:127.0.0.1:6001-:6000 2356# this host xterm should open in the guest X11 server 2357xterm -display :1 2358@end example 2359 2360To redirect telnet connections from host port 5555 to telnet port on 2361the guest, use the following: 2362 2363@example 2364# on the host 2365qemu-system-i386 -nic user,hostfwd=tcp::5555-:23 2366telnet localhost 5555 2367@end example 2368 2369Then when you use on the host @code{telnet localhost 5555}, you 2370connect to the guest telnet server. 2371 2372@item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev} 2373@itemx guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command} 2374Forward guest TCP connections to the IP address @var{server} on port @var{port} 2375to the character device @var{dev} or to a program executed by @var{cmd:command} 2376which gets spawned for each connection. This option can be given multiple times. 2377 2378You can either use a chardev directly and have that one used throughout QEMU's 2379lifetime, like in the following example: 2380 2381@example 2382# open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever 2383# the guest accesses it 2384qemu-system-i386 -nic user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 2385@end example 2386 2387Or you can execute a command on every TCP connection established by the guest, 2388so that QEMU behaves similar to an inetd process for that virtual server: 2389 2390@example 2391# call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234 2392# and connect the TCP stream to its stdin/stdout 2393qemu-system-i386 -nic 'user,id=n1,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321' 2394@end example 2395 2396@end table 2397 2398@item -netdev tap,id=@var{id}[,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,br=@var{bridge}][,helper=@var{helper}] 2399Configure a host TAP network backend with ID @var{id}. 2400 2401Use the network script @var{file} to configure it and the network script 2402@var{dfile} to deconfigure it. If @var{name} is not provided, the OS 2403automatically provides one. The default network configure script is 2404@file{/etc/qemu-ifup} and the default network deconfigure script is 2405@file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no} 2406to disable script execution. 2407 2408If running QEMU as an unprivileged user, use the network helper 2409@var{helper} to configure the TAP interface and attach it to the bridge. 2410The default network helper executable is @file{/path/to/qemu-bridge-helper} 2411and the default bridge device is @file{br0}. 2412 2413@option{fd}=@var{h} can be used to specify the handle of an already 2414opened host TAP interface. 2415 2416Examples: 2417 2418@example 2419#launch a QEMU instance with the default network script 2420qemu-system-i386 linux.img -nic tap 2421@end example 2422 2423@example 2424#launch a QEMU instance with two NICs, each one connected 2425#to a TAP device 2426qemu-system-i386 linux.img \ 2427 -netdev tap,id=nd0,ifname=tap0 -device e1000,netdev=nd0 \ 2428 -netdev tap,id=nd1,ifname=tap1 -device rtl8139,netdev=nd1 2429@end example 2430 2431@example 2432#launch a QEMU instance with the default network helper to 2433#connect a TAP device to bridge br0 2434qemu-system-i386 linux.img -device virtio-net-pci,netdev=n1 \ 2435 -netdev tap,id=n1,"helper=/path/to/qemu-bridge-helper" 2436@end example 2437 2438@item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}] 2439Connect a host TAP network interface to a host bridge device. 2440 2441Use the network helper @var{helper} to configure the TAP interface and 2442attach it to the bridge. The default network helper executable is 2443@file{/path/to/qemu-bridge-helper} and the default bridge 2444device is @file{br0}. 2445 2446Examples: 2447 2448@example 2449#launch a QEMU instance with the default network helper to 2450#connect a TAP device to bridge br0 2451qemu-system-i386 linux.img -netdev bridge,id=n1 -device virtio-net,netdev=n1 2452@end example 2453 2454@example 2455#launch a QEMU instance with the default network helper to 2456#connect a TAP device to bridge qemubr0 2457qemu-system-i386 linux.img -netdev bridge,br=qemubr0,id=n1 -device virtio-net,netdev=n1 2458@end example 2459 2460@item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}] 2461 2462This host network backend can be used to connect the guest's network to 2463another QEMU virtual machine using a TCP socket connection. If @option{listen} 2464is specified, QEMU waits for incoming connections on @var{port} 2465(@var{host} is optional). @option{connect} is used to connect to 2466another QEMU instance using the @option{listen} option. @option{fd}=@var{h} 2467specifies an already opened TCP socket. 2468 2469Example: 2470@example 2471# launch a first QEMU instance 2472qemu-system-i386 linux.img \ 2473 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 2474 -netdev socket,id=n1,listen=:1234 2475# connect the network of this instance to the network of the first instance 2476qemu-system-i386 linux.img \ 2477 -device e1000,netdev=n2,mac=52:54:00:12:34:57 \ 2478 -netdev socket,id=n2,connect=127.0.0.1:1234 2479@end example 2480 2481@item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]] 2482 2483Configure a socket host network backend to share the guest's network traffic 2484with another QEMU virtual machines using a UDP multicast socket, effectively 2485making a bus for every QEMU with same multicast address @var{maddr} and @var{port}. 2486NOTES: 2487@enumerate 2488@item 2489Several QEMU can be running on different hosts and share same bus (assuming 2490correct multicast setup for these hosts). 2491@item 2492mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see 2493@url{http://user-mode-linux.sf.net}. 2494@item 2495Use @option{fd=h} to specify an already opened UDP multicast socket. 2496@end enumerate 2497 2498Example: 2499@example 2500# launch one QEMU instance 2501qemu-system-i386 linux.img \ 2502 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 2503 -netdev socket,id=n1,mcast=230.0.0.1:1234 2504# launch another QEMU instance on same "bus" 2505qemu-system-i386 linux.img \ 2506 -device e1000,netdev=n2,mac=52:54:00:12:34:57 \ 2507 -netdev socket,id=n2,mcast=230.0.0.1:1234 2508# launch yet another QEMU instance on same "bus" 2509qemu-system-i386 linux.img \ 2510 -device e1000,netdev=n3,mac=52:54:00:12:34:58 \ 2511 -netdev socket,id=n3,mcast=230.0.0.1:1234 2512@end example 2513 2514Example (User Mode Linux compat.): 2515@example 2516# launch QEMU instance (note mcast address selected is UML's default) 2517qemu-system-i386 linux.img \ 2518 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 2519 -netdev socket,id=n1,mcast=239.192.168.1:1102 2520# launch UML 2521/path/to/linux ubd0=/path/to/root_fs eth0=mcast 2522@end example 2523 2524Example (send packets from host's 1.2.3.4): 2525@example 2526qemu-system-i386 linux.img \ 2527 -device e1000,netdev=n1,mac=52:54:00:12:34:56 \ 2528 -netdev socket,id=n1,mcast=239.192.168.1:1102,localaddr=1.2.3.4 2529@end example 2530 2531@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}] 2532Configure a L2TPv3 pseudowire host network backend. L2TPv3 (RFC3391) is a 2533popular protocol to transport Ethernet (and other Layer 2) data frames between 2534two systems. It is present in routers, firewalls and the Linux kernel 2535(from version 3.3 onwards). 2536 2537This transport allows a VM to communicate to another VM, router or firewall directly. 2538 2539@table @option 2540@item src=@var{srcaddr} 2541 source address (mandatory) 2542@item dst=@var{dstaddr} 2543 destination address (mandatory) 2544@item udp 2545 select udp encapsulation (default is ip). 2546@item srcport=@var{srcport} 2547 source udp port. 2548@item dstport=@var{dstport} 2549 destination udp port. 2550@item ipv6 2551 force v6, otherwise defaults to v4. 2552@item rxcookie=@var{rxcookie} 2553@itemx txcookie=@var{txcookie} 2554 Cookies are a weak form of security in the l2tpv3 specification. 2555Their function is mostly to prevent misconfiguration. By default they are 32 2556bit. 2557@item cookie64 2558 Set cookie size to 64 bit instead of the default 32 2559@item counter=off 2560 Force a 'cut-down' L2TPv3 with no counter as in 2561draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00 2562@item pincounter=on 2563 Work around broken counter handling in peer. This may also help on 2564networks which have packet reorder. 2565@item offset=@var{offset} 2566 Add an extra offset between header and data 2567@end table 2568 2569For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan 2570on the remote Linux host 1.2.3.4: 2571@example 2572# Setup tunnel on linux host using raw ip as encapsulation 2573# on 1.2.3.4 2574ip l2tp add tunnel remote 4.3.2.1 local 1.2.3.4 tunnel_id 1 peer_tunnel_id 1 \ 2575 encap udp udp_sport 16384 udp_dport 16384 2576ip l2tp add session tunnel_id 1 name vmtunnel0 session_id \ 2577 0xFFFFFFFF peer_session_id 0xFFFFFFFF 2578ifconfig vmtunnel0 mtu 1500 2579ifconfig vmtunnel0 up 2580brctl addif br-lan vmtunnel0 2581 2582 2583# on 4.3.2.1 2584# launch QEMU instance - if your network has reorder or is very lossy add ,pincounter 2585 2586qemu-system-i386 linux.img -device e1000,netdev=n1 \ 2587 -netdev l2tpv3,id=n1,src=4.2.3.1,dst=1.2.3.4,udp,srcport=16384,dstport=16384,rxsession=0xffffffff,txsession=0xffffffff,counter 2588 2589@end example 2590 2591@item -netdev vde,id=@var{id}[,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}] 2592Configure VDE backend to connect to PORT @var{n} of a vde switch running on host and 2593listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname} 2594and MODE @var{octalmode} to change default ownership and permissions for 2595communication port. This option is only available if QEMU has been compiled 2596with vde support enabled. 2597 2598Example: 2599@example 2600# launch vde switch 2601vde_switch -F -sock /tmp/myswitch 2602# launch QEMU instance 2603qemu-system-i386 linux.img -nic vde,sock=/tmp/myswitch 2604@end example 2605 2606@item -netdev vhost-user,chardev=@var{id}[,vhostforce=on|off][,queues=n] 2607 2608Establish a vhost-user netdev, backed by a chardev @var{id}. The chardev should 2609be a unix domain socket backed one. The vhost-user uses a specifically defined 2610protocol to pass vhost ioctl replacement messages to an application on the other 2611end of the socket. On non-MSIX guests, the feature can be forced with 2612@var{vhostforce}. Use 'queues=@var{n}' to specify the number of queues to 2613be created for multiqueue vhost-user. 2614 2615Example: 2616@example 2617qemu -m 512 -object memory-backend-file,id=mem,size=512M,mem-path=/hugetlbfs,share=on \ 2618 -numa node,memdev=mem \ 2619 -chardev socket,id=chr0,path=/path/to/socket \ 2620 -netdev type=vhost-user,id=net0,chardev=chr0 \ 2621 -device virtio-net-pci,netdev=net0 2622@end example 2623 2624@item -netdev hubport,id=@var{id},hubid=@var{hubid}[,netdev=@var{nd}] 2625 2626Create a hub port on the emulated hub with ID @var{hubid}. 2627 2628The hubport netdev lets you connect a NIC to a QEMU emulated hub instead of a 2629single netdev. Alternatively, you can also connect the hubport to another 2630netdev with ID @var{nd} by using the @option{netdev=@var{nd}} option. 2631 2632@item -net nic[,netdev=@var{nd}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}] 2633@findex -net 2634Legacy option to configure or create an on-board (or machine default) Network 2635Interface Card(NIC) and connect it either to the emulated hub with ID 0 (i.e. 2636the default hub), or to the netdev @var{nd}. 2637The NIC is an e1000 by default on the PC target. Optionally, the MAC address 2638can be changed to @var{mac}, the device address set to @var{addr} (PCI cards 2639only), and a @var{name} can be assigned for use in monitor commands. 2640Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors 2641that the card should have; this option currently only affects virtio cards; set 2642@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single 2643NIC is created. QEMU can emulate several different models of network card. 2644Use @code{-net nic,model=help} for a list of available devices for your target. 2645 2646@item -net user|tap|bridge|socket|l2tpv3|vde[,...][,name=@var{name}] 2647Configure a host network backend (with the options corresponding to the same 2648@option{-netdev} option) and connect it to the emulated hub 0 (the default 2649hub). Use @var{name} to specify the name of the hub port. 2650ETEXI 2651 2652STEXI 2653@end table 2654ETEXI 2655DEFHEADING() 2656 2657DEFHEADING(Character device options:) 2658 2659DEF("chardev", HAS_ARG, QEMU_OPTION_chardev, 2660 "-chardev help\n" 2661 "-chardev null,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2662 "-chardev socket,id=id[,host=host],port=port[,to=to][,ipv4][,ipv6][,nodelay][,reconnect=seconds]\n" 2663 " [,server][,nowait][,telnet][,websocket][,reconnect=seconds][,mux=on|off]\n" 2664 " [,logfile=PATH][,logappend=on|off][,tls-creds=ID][,tls-authz=ID] (tcp)\n" 2665 "-chardev socket,id=id,path=path[,server][,nowait][,telnet][,websocket][,reconnect=seconds]\n" 2666 " [,mux=on|off][,logfile=PATH][,logappend=on|off] (unix)\n" 2667 "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n" 2668 " [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n" 2669 " [,logfile=PATH][,logappend=on|off]\n" 2670 "-chardev msmouse,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2671 "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n" 2672 " [,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2673 "-chardev ringbuf,id=id[,size=size][,logfile=PATH][,logappend=on|off]\n" 2674 "-chardev file,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2675 "-chardev pipe,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2676#ifdef _WIN32 2677 "-chardev console,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2678 "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2679#else 2680 "-chardev pty,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2681 "-chardev stdio,id=id[,mux=on|off][,signal=on|off][,logfile=PATH][,logappend=on|off]\n" 2682#endif 2683#ifdef CONFIG_BRLAPI 2684 "-chardev braille,id=id[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2685#endif 2686#if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \ 2687 || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__) 2688 "-chardev serial,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2689 "-chardev tty,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2690#endif 2691#if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__) 2692 "-chardev parallel,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2693 "-chardev parport,id=id,path=path[,mux=on|off][,logfile=PATH][,logappend=on|off]\n" 2694#endif 2695#if defined(CONFIG_SPICE) 2696 "-chardev spicevmc,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n" 2697 "-chardev spiceport,id=id,name=name[,debug=debug][,logfile=PATH][,logappend=on|off]\n" 2698#endif 2699 , QEMU_ARCH_ALL 2700) 2701 2702STEXI 2703 2704The general form of a character device option is: 2705@table @option 2706@item -chardev @var{backend},id=@var{id}[,mux=on|off][,@var{options}] 2707@findex -chardev 2708Backend is one of: 2709@option{null}, 2710@option{socket}, 2711@option{udp}, 2712@option{msmouse}, 2713@option{vc}, 2714@option{ringbuf}, 2715@option{file}, 2716@option{pipe}, 2717@option{console}, 2718@option{serial}, 2719@option{pty}, 2720@option{stdio}, 2721@option{braille}, 2722@option{tty}, 2723@option{parallel}, 2724@option{parport}, 2725@option{spicevmc}, 2726@option{spiceport}. 2727The specific backend will determine the applicable options. 2728 2729Use @code{-chardev help} to print all available chardev backend types. 2730 2731All devices must have an id, which can be any string up to 127 characters long. 2732It is used to uniquely identify this device in other command line directives. 2733 2734A character device may be used in multiplexing mode by multiple front-ends. 2735Specify @option{mux=on} to enable this mode. 2736A multiplexer is a "1:N" device, and here the "1" end is your specified chardev 2737backend, and the "N" end is the various parts of QEMU that can talk to a chardev. 2738If you create a chardev with @option{id=myid} and @option{mux=on}, QEMU will 2739create a multiplexer with your specified ID, and you can then configure multiple 2740front ends to use that chardev ID for their input/output. Up to four different 2741front ends can be connected to a single multiplexed chardev. (Without 2742multiplexing enabled, a chardev can only be used by a single front end.) 2743For instance you could use this to allow a single stdio chardev to be used by 2744two serial ports and the QEMU monitor: 2745 2746@example 2747-chardev stdio,mux=on,id=char0 \ 2748-mon chardev=char0,mode=readline \ 2749-serial chardev:char0 \ 2750-serial chardev:char0 2751@end example 2752 2753You can have more than one multiplexer in a system configuration; for instance 2754you could have a TCP port multiplexed between UART 0 and UART 1, and stdio 2755multiplexed between the QEMU monitor and a parallel port: 2756 2757@example 2758-chardev stdio,mux=on,id=char0 \ 2759-mon chardev=char0,mode=readline \ 2760-parallel chardev:char0 \ 2761-chardev tcp,...,mux=on,id=char1 \ 2762-serial chardev:char1 \ 2763-serial chardev:char1 2764@end example 2765 2766When you're using a multiplexed character device, some escape sequences are 2767interpreted in the input. @xref{mux_keys, Keys in the character backend 2768multiplexer}. 2769 2770Note that some other command line options may implicitly create multiplexed 2771character backends; for instance @option{-serial mon:stdio} creates a 2772multiplexed stdio backend connected to the serial port and the QEMU monitor, 2773and @option{-nographic} also multiplexes the console and the monitor to 2774stdio. 2775 2776There is currently no support for multiplexing in the other direction 2777(where a single QEMU front end takes input and output from multiple chardevs). 2778 2779Every backend supports the @option{logfile} option, which supplies the path 2780to a file to record all data transmitted via the backend. The @option{logappend} 2781option controls whether the log file will be truncated or appended to when 2782opened. 2783 2784@end table 2785 2786The available backends are: 2787 2788@table @option 2789@item -chardev null,id=@var{id} 2790A void device. This device will not emit any data, and will drop any data it 2791receives. The null backend does not take any options. 2792 2793@item -chardev socket,id=@var{id}[,@var{TCP options} or @var{unix options}][,server][,nowait][,telnet][,websocket][,reconnect=@var{seconds}][,tls-creds=@var{id}][,tls-authz=@var{id}] 2794 2795Create a two-way stream socket, which can be either a TCP or a unix socket. A 2796unix socket will be created if @option{path} is specified. Behaviour is 2797undefined if TCP options are specified for a unix socket. 2798 2799@option{server} specifies that the socket shall be a listening socket. 2800 2801@option{nowait} specifies that QEMU should not block waiting for a client to 2802connect to a listening socket. 2803 2804@option{telnet} specifies that traffic on the socket should interpret telnet 2805escape sequences. 2806 2807@option{websocket} specifies that the socket uses WebSocket protocol for 2808communication. 2809 2810@option{reconnect} sets the timeout for reconnecting on non-server sockets when 2811the remote end goes away. qemu will delay this many seconds and then attempt 2812to reconnect. Zero disables reconnecting, and is the default. 2813 2814@option{tls-creds} requests enablement of the TLS protocol for encryption, 2815and specifies the id of the TLS credentials to use for the handshake. The 2816credentials must be previously created with the @option{-object tls-creds} 2817argument. 2818 2819@option{tls-auth} provides the ID of the QAuthZ authorization object against 2820which the client's x509 distinguished name will be validated. This object is 2821only resolved at time of use, so can be deleted and recreated on the fly 2822while the chardev server is active. If missing, it will default to denying 2823access. 2824 2825TCP and unix socket options are given below: 2826 2827@table @option 2828 2829@item TCP options: port=@var{port}[,host=@var{host}][,to=@var{to}][,ipv4][,ipv6][,nodelay] 2830 2831@option{host} for a listening socket specifies the local address to be bound. 2832For a connecting socket species the remote host to connect to. @option{host} is 2833optional for listening sockets. If not specified it defaults to @code{0.0.0.0}. 2834 2835@option{port} for a listening socket specifies the local port to be bound. For a 2836connecting socket specifies the port on the remote host to connect to. 2837@option{port} can be given as either a port number or a service name. 2838@option{port} is required. 2839 2840@option{to} is only relevant to listening sockets. If it is specified, and 2841@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up 2842to and including @option{to} until it succeeds. @option{to} must be specified 2843as a port number. 2844 2845@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used. 2846If neither is specified the socket may use either protocol. 2847 2848@option{nodelay} disables the Nagle algorithm. 2849 2850@item unix options: path=@var{path} 2851 2852@option{path} specifies the local path of the unix socket. @option{path} is 2853required. 2854 2855@end table 2856 2857@item -chardev udp,id=@var{id}[,host=@var{host}],port=@var{port}[,localaddr=@var{localaddr}][,localport=@var{localport}][,ipv4][,ipv6] 2858 2859Sends all traffic from the guest to a remote host over UDP. 2860 2861@option{host} specifies the remote host to connect to. If not specified it 2862defaults to @code{localhost}. 2863 2864@option{port} specifies the port on the remote host to connect to. @option{port} 2865is required. 2866 2867@option{localaddr} specifies the local address to bind to. If not specified it 2868defaults to @code{0.0.0.0}. 2869 2870@option{localport} specifies the local port to bind to. If not specified any 2871available local port will be used. 2872 2873@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used. 2874If neither is specified the device may use either protocol. 2875 2876@item -chardev msmouse,id=@var{id} 2877 2878Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not 2879take any options. 2880 2881@item -chardev vc,id=@var{id}[[,width=@var{width}][,height=@var{height}]][[,cols=@var{cols}][,rows=@var{rows}]] 2882 2883Connect to a QEMU text console. @option{vc} may optionally be given a specific 2884size. 2885 2886@option{width} and @option{height} specify the width and height respectively of 2887the console, in pixels. 2888 2889@option{cols} and @option{rows} specify that the console be sized to fit a text 2890console with the given dimensions. 2891 2892@item -chardev ringbuf,id=@var{id}[,size=@var{size}] 2893 2894Create a ring buffer with fixed size @option{size}. 2895@var{size} must be a power of two and defaults to @code{64K}. 2896 2897@item -chardev file,id=@var{id},path=@var{path} 2898 2899Log all traffic received from the guest to a file. 2900 2901@option{path} specifies the path of the file to be opened. This file will be 2902created if it does not already exist, and overwritten if it does. @option{path} 2903is required. 2904 2905@item -chardev pipe,id=@var{id},path=@var{path} 2906 2907Create a two-way connection to the guest. The behaviour differs slightly between 2908Windows hosts and other hosts: 2909 2910On Windows, a single duplex pipe will be created at 2911@file{\\.pipe\@option{path}}. 2912 2913On other hosts, 2 pipes will be created called @file{@option{path}.in} and 2914@file{@option{path}.out}. Data written to @file{@option{path}.in} will be 2915received by the guest. Data written by the guest can be read from 2916@file{@option{path}.out}. QEMU will not create these fifos, and requires them to 2917be present. 2918 2919@option{path} forms part of the pipe path as described above. @option{path} is 2920required. 2921 2922@item -chardev console,id=@var{id} 2923 2924Send traffic from the guest to QEMU's standard output. @option{console} does not 2925take any options. 2926 2927@option{console} is only available on Windows hosts. 2928 2929@item -chardev serial,id=@var{id},path=@option{path} 2930 2931Send traffic from the guest to a serial device on the host. 2932 2933On Unix hosts serial will actually accept any tty device, 2934not only serial lines. 2935 2936@option{path} specifies the name of the serial device to open. 2937 2938@item -chardev pty,id=@var{id} 2939 2940Create a new pseudo-terminal on the host and connect to it. @option{pty} does 2941not take any options. 2942 2943@option{pty} is not available on Windows hosts. 2944 2945@item -chardev stdio,id=@var{id}[,signal=on|off] 2946Connect to standard input and standard output of the QEMU process. 2947 2948@option{signal} controls if signals are enabled on the terminal, that includes 2949exiting QEMU with the key sequence @key{Control-c}. This option is enabled by 2950default, use @option{signal=off} to disable it. 2951 2952@item -chardev braille,id=@var{id} 2953 2954Connect to a local BrlAPI server. @option{braille} does not take any options. 2955 2956@item -chardev tty,id=@var{id},path=@var{path} 2957 2958@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and 2959DragonFlyBSD hosts. It is an alias for @option{serial}. 2960 2961@option{path} specifies the path to the tty. @option{path} is required. 2962 2963@item -chardev parallel,id=@var{id},path=@var{path} 2964@itemx -chardev parport,id=@var{id},path=@var{path} 2965 2966@option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts. 2967 2968Connect to a local parallel port. 2969 2970@option{path} specifies the path to the parallel port device. @option{path} is 2971required. 2972 2973@item -chardev spicevmc,id=@var{id},debug=@var{debug},name=@var{name} 2974 2975@option{spicevmc} is only available when spice support is built in. 2976 2977@option{debug} debug level for spicevmc 2978 2979@option{name} name of spice channel to connect to 2980 2981Connect to a spice virtual machine channel, such as vdiport. 2982 2983@item -chardev spiceport,id=@var{id},debug=@var{debug},name=@var{name} 2984 2985@option{spiceport} is only available when spice support is built in. 2986 2987@option{debug} debug level for spicevmc 2988 2989@option{name} name of spice port to connect to 2990 2991Connect to a spice port, allowing a Spice client to handle the traffic 2992identified by a name (preferably a fqdn). 2993ETEXI 2994 2995STEXI 2996@end table 2997ETEXI 2998DEFHEADING() 2999 3000DEFHEADING(Bluetooth(R) options:) 3001STEXI 3002@table @option 3003ETEXI 3004 3005DEF("bt", HAS_ARG, QEMU_OPTION_bt, \ 3006 "-bt hci,null dumb bluetooth HCI - doesn't respond to commands\n" \ 3007 "-bt hci,host[:id]\n" \ 3008 " use host's HCI with the given name\n" \ 3009 "-bt hci[,vlan=n]\n" \ 3010 " emulate a standard HCI in virtual scatternet 'n'\n" \ 3011 "-bt vhci[,vlan=n]\n" \ 3012 " add host computer to virtual scatternet 'n' using VHCI\n" \ 3013 "-bt device:dev[,vlan=n]\n" \ 3014 " emulate a bluetooth device 'dev' in scatternet 'n'\n", 3015 QEMU_ARCH_ALL) 3016STEXI 3017@item -bt hci[...] 3018@findex -bt 3019Defines the function of the corresponding Bluetooth HCI. -bt options 3020are matched with the HCIs present in the chosen machine type. For 3021example when emulating a machine with only one HCI built into it, only 3022the first @code{-bt hci[...]} option is valid and defines the HCI's 3023logic. The Transport Layer is decided by the machine type. Currently 3024the machines @code{n800} and @code{n810} have one HCI and all other 3025machines have none. 3026 3027Note: This option and the whole bluetooth subsystem is considered as deprecated. 3028If you still use it, please send a mail to @email{qemu-devel@@nongnu.org} where 3029you describe your usecase. 3030 3031@anchor{bt-hcis} 3032The following three types are recognized: 3033 3034@table @option 3035@item -bt hci,null 3036(default) The corresponding Bluetooth HCI assumes no internal logic 3037and will not respond to any HCI commands or emit events. 3038 3039@item -bt hci,host[:@var{id}] 3040(@code{bluez} only) The corresponding HCI passes commands / events 3041to / from the physical HCI identified by the name @var{id} (default: 3042@code{hci0}) on the computer running QEMU. Only available on @code{bluez} 3043capable systems like Linux. 3044 3045@item -bt hci[,vlan=@var{n}] 3046Add a virtual, standard HCI that will participate in the Bluetooth 3047scatternet @var{n} (default @code{0}). Similarly to @option{-net} 3048VLANs, devices inside a bluetooth network @var{n} can only communicate 3049with other devices in the same network (scatternet). 3050@end table 3051 3052@item -bt vhci[,vlan=@var{n}] 3053(Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached 3054to the host bluetooth stack instead of to the emulated target. This 3055allows the host and target machines to participate in a common scatternet 3056and communicate. Requires the Linux @code{vhci} driver installed. Can 3057be used as following: 3058 3059@example 3060qemu-system-i386 [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5 3061@end example 3062 3063@item -bt device:@var{dev}[,vlan=@var{n}] 3064Emulate a bluetooth device @var{dev} and place it in network @var{n} 3065(default @code{0}). QEMU can only emulate one type of bluetooth devices 3066currently: 3067 3068@table @option 3069@item keyboard 3070Virtual wireless keyboard implementing the HIDP bluetooth profile. 3071@end table 3072ETEXI 3073 3074STEXI 3075@end table 3076ETEXI 3077DEFHEADING() 3078 3079#ifdef CONFIG_TPM 3080DEFHEADING(TPM device options:) 3081 3082DEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \ 3083 "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n" 3084 " use path to provide path to a character device; default is /dev/tpm0\n" 3085 " use cancel-path to provide path to TPM's cancel sysfs entry; if\n" 3086 " not provided it will be searched for in /sys/class/misc/tpm?/device\n" 3087 "-tpmdev emulator,id=id,chardev=dev\n" 3088 " configure the TPM device using chardev backend\n", 3089 QEMU_ARCH_ALL) 3090STEXI 3091 3092The general form of a TPM device option is: 3093@table @option 3094 3095@item -tpmdev @var{backend},id=@var{id}[,@var{options}] 3096@findex -tpmdev 3097 3098The specific backend type will determine the applicable options. 3099The @code{-tpmdev} option creates the TPM backend and requires a 3100@code{-device} option that specifies the TPM frontend interface model. 3101 3102Use @code{-tpmdev help} to print all available TPM backend types. 3103 3104@end table 3105 3106The available backends are: 3107 3108@table @option 3109 3110@item -tpmdev passthrough,id=@var{id},path=@var{path},cancel-path=@var{cancel-path} 3111 3112(Linux-host only) Enable access to the host's TPM using the passthrough 3113driver. 3114 3115@option{path} specifies the path to the host's TPM device, i.e., on 3116a Linux host this would be @code{/dev/tpm0}. 3117@option{path} is optional and by default @code{/dev/tpm0} is used. 3118 3119@option{cancel-path} specifies the path to the host TPM device's sysfs 3120entry allowing for cancellation of an ongoing TPM command. 3121@option{cancel-path} is optional and by default QEMU will search for the 3122sysfs entry to use. 3123 3124Some notes about using the host's TPM with the passthrough driver: 3125 3126The TPM device accessed by the passthrough driver must not be 3127used by any other application on the host. 3128 3129Since the host's firmware (BIOS/UEFI) has already initialized the TPM, 3130the VM's firmware (BIOS/UEFI) will not be able to initialize the 3131TPM again and may therefore not show a TPM-specific menu that would 3132otherwise allow the user to configure the TPM, e.g., allow the user to 3133enable/disable or activate/deactivate the TPM. 3134Further, if TPM ownership is released from within a VM then the host's TPM 3135will get disabled and deactivated. To enable and activate the 3136TPM again afterwards, the host has to be rebooted and the user is 3137required to enter the firmware's menu to enable and activate the TPM. 3138If the TPM is left disabled and/or deactivated most TPM commands will fail. 3139 3140To create a passthrough TPM use the following two options: 3141@example 3142-tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0 3143@end example 3144Note that the @code{-tpmdev} id is @code{tpm0} and is referenced by 3145@code{tpmdev=tpm0} in the device option. 3146 3147@item -tpmdev emulator,id=@var{id},chardev=@var{dev} 3148 3149(Linux-host only) Enable access to a TPM emulator using Unix domain socket based 3150chardev backend. 3151 3152@option{chardev} specifies the unique ID of a character device backend that provides connection to the software TPM server. 3153 3154To create a TPM emulator backend device with chardev socket backend: 3155@example 3156 3157-chardev socket,id=chrtpm,path=/tmp/swtpm-sock -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0 3158 3159@end example 3160 3161ETEXI 3162 3163STEXI 3164@end table 3165ETEXI 3166DEFHEADING() 3167 3168#endif 3169 3170DEFHEADING(Linux/Multiboot boot specific:) 3171STEXI 3172 3173When using these options, you can use a given Linux or Multiboot 3174kernel without installing it in the disk image. It can be useful 3175for easier testing of various kernels. 3176 3177@table @option 3178ETEXI 3179 3180DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \ 3181 "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL) 3182STEXI 3183@item -kernel @var{bzImage} 3184@findex -kernel 3185Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel 3186or in multiboot format. 3187ETEXI 3188 3189DEF("append", HAS_ARG, QEMU_OPTION_append, \ 3190 "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL) 3191STEXI 3192@item -append @var{cmdline} 3193@findex -append 3194Use @var{cmdline} as kernel command line 3195ETEXI 3196 3197DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \ 3198 "-initrd file use 'file' as initial ram disk\n", QEMU_ARCH_ALL) 3199STEXI 3200@item -initrd @var{file} 3201@findex -initrd 3202Use @var{file} as initial ram disk. 3203 3204@item -initrd "@var{file1} arg=foo,@var{file2}" 3205 3206This syntax is only available with multiboot. 3207 3208Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the 3209first module. 3210ETEXI 3211 3212DEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \ 3213 "-dtb file use 'file' as device tree image\n", QEMU_ARCH_ALL) 3214STEXI 3215@item -dtb @var{file} 3216@findex -dtb 3217Use @var{file} as a device tree binary (dtb) image and pass it to the kernel 3218on boot. 3219ETEXI 3220 3221STEXI 3222@end table 3223ETEXI 3224DEFHEADING() 3225 3226DEFHEADING(Debug/Expert options:) 3227STEXI 3228@table @option 3229ETEXI 3230 3231DEF("fw_cfg", HAS_ARG, QEMU_OPTION_fwcfg, 3232 "-fw_cfg [name=]<name>,file=<file>\n" 3233 " add named fw_cfg entry with contents from file\n" 3234 "-fw_cfg [name=]<name>,string=<str>\n" 3235 " add named fw_cfg entry with contents from string\n", 3236 QEMU_ARCH_ALL) 3237STEXI 3238 3239@item -fw_cfg [name=]@var{name},file=@var{file} 3240@findex -fw_cfg 3241Add named fw_cfg entry with contents from file @var{file}. 3242 3243@item -fw_cfg [name=]@var{name},string=@var{str} 3244Add named fw_cfg entry with contents from string @var{str}. 3245 3246The terminating NUL character of the contents of @var{str} will not be 3247included as part of the fw_cfg item data. To insert contents with 3248embedded NUL characters, you have to use the @var{file} parameter. 3249 3250The fw_cfg entries are passed by QEMU through to the guest. 3251 3252Example: 3253@example 3254 -fw_cfg name=opt/com.mycompany/blob,file=./my_blob.bin 3255@end example 3256creates an fw_cfg entry named opt/com.mycompany/blob with contents 3257from ./my_blob.bin. 3258 3259ETEXI 3260 3261DEF("serial", HAS_ARG, QEMU_OPTION_serial, \ 3262 "-serial dev redirect the serial port to char device 'dev'\n", 3263 QEMU_ARCH_ALL) 3264STEXI 3265@item -serial @var{dev} 3266@findex -serial 3267Redirect the virtual serial port to host character device 3268@var{dev}. The default device is @code{vc} in graphical mode and 3269@code{stdio} in non graphical mode. 3270 3271This option can be used several times to simulate up to 4 serial 3272ports. 3273 3274Use @code{-serial none} to disable all serial ports. 3275 3276Available character devices are: 3277@table @option 3278@item vc[:@var{W}x@var{H}] 3279Virtual console. Optionally, a width and height can be given in pixel with 3280@example 3281vc:800x600 3282@end example 3283It is also possible to specify width or height in characters: 3284@example 3285vc:80Cx24C 3286@end example 3287@item pty 3288[Linux only] Pseudo TTY (a new PTY is automatically allocated) 3289@item none 3290No device is allocated. 3291@item null 3292void device 3293@item chardev:@var{id} 3294Use a named character device defined with the @code{-chardev} option. 3295@item /dev/XXX 3296[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port 3297parameters are set according to the emulated ones. 3298@item /dev/parport@var{N} 3299[Linux only, parallel port only] Use host parallel port 3300@var{N}. Currently SPP and EPP parallel port features can be used. 3301@item file:@var{filename} 3302Write output to @var{filename}. No character can be read. 3303@item stdio 3304[Unix only] standard input/output 3305@item pipe:@var{filename} 3306name pipe @var{filename} 3307@item COM@var{n} 3308[Windows only] Use host serial port @var{n} 3309@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}] 3310This implements UDP Net Console. 3311When @var{remote_host} or @var{src_ip} are not specified 3312they default to @code{0.0.0.0}. 3313When not using a specified @var{src_port} a random port is automatically chosen. 3314 3315If you just want a simple readonly console you can use @code{netcat} or 3316@code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as: 3317@code{nc -u -l -p 4555}. Any time QEMU writes something to that port it 3318will appear in the netconsole session. 3319 3320If you plan to send characters back via netconsole or you want to stop 3321and start QEMU a lot of times, you should have QEMU use the same 3322source port each time by using something like @code{-serial 3323udp::4555@@:4556} to QEMU. Another approach is to use a patched 3324version of netcat which can listen to a TCP port and send and receive 3325characters via udp. If you have a patched version of netcat which 3326activates telnet remote echo and single char transfer, then you can 3327use the following options to set up a netcat redirector to allow 3328telnet on port 5555 to access the QEMU port. 3329@table @code 3330@item QEMU Options: 3331-serial udp::4555@@:4556 3332@item netcat options: 3333-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T 3334@item telnet options: 3335localhost 5555 3336@end table 3337 3338@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay][,reconnect=@var{seconds}] 3339The TCP Net Console has two modes of operation. It can send the serial 3340I/O to a location or wait for a connection from a location. By default 3341the TCP Net Console is sent to @var{host} at the @var{port}. If you use 3342the @var{server} option QEMU will wait for a client socket application 3343to connect to the port before continuing, unless the @code{nowait} 3344option was specified. The @code{nodelay} option disables the Nagle buffering 3345algorithm. The @code{reconnect} option only applies if @var{noserver} is 3346set, if the connection goes down it will attempt to reconnect at the 3347given interval. If @var{host} is omitted, 0.0.0.0 is assumed. Only 3348one TCP connection at a time is accepted. You can use @code{telnet} to 3349connect to the corresponding character device. 3350@table @code 3351@item Example to send tcp console to 192.168.0.2 port 4444 3352-serial tcp:192.168.0.2:4444 3353@item Example to listen and wait on port 4444 for connection 3354-serial tcp::4444,server 3355@item Example to not wait and listen on ip 192.168.0.100 port 4444 3356-serial tcp:192.168.0.100:4444,server,nowait 3357@end table 3358 3359@item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay] 3360The telnet protocol is used instead of raw tcp sockets. The options 3361work the same as if you had specified @code{-serial tcp}. The 3362difference is that the port acts like a telnet server or client using 3363telnet option negotiation. This will also allow you to send the 3364MAGIC_SYSRQ sequence if you use a telnet that supports sending the break 3365sequence. Typically in unix telnet you do it with Control-] and then 3366type "send break" followed by pressing the enter key. 3367 3368@item websocket:@var{host}:@var{port},server[,nowait][,nodelay] 3369The WebSocket protocol is used instead of raw tcp socket. The port acts as 3370a WebSocket server. Client mode is not supported. 3371 3372@item unix:@var{path}[,server][,nowait][,reconnect=@var{seconds}] 3373A unix domain socket is used instead of a tcp socket. The option works the 3374same as if you had specified @code{-serial tcp} except the unix domain socket 3375@var{path} is used for connections. 3376 3377@item mon:@var{dev_string} 3378This is a special option to allow the monitor to be multiplexed onto 3379another serial port. The monitor is accessed with key sequence of 3380@key{Control-a} and then pressing @key{c}. 3381@var{dev_string} should be any one of the serial devices specified 3382above. An example to multiplex the monitor onto a telnet server 3383listening on port 4444 would be: 3384@table @code 3385@item -serial mon:telnet::4444,server,nowait 3386@end table 3387When the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate 3388QEMU any more but will be passed to the guest instead. 3389 3390@item braille 3391Braille device. This will use BrlAPI to display the braille output on a real 3392or fake device. 3393 3394@item msmouse 3395Three button serial mouse. Configure the guest to use Microsoft protocol. 3396@end table 3397ETEXI 3398 3399DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \ 3400 "-parallel dev redirect the parallel port to char device 'dev'\n", 3401 QEMU_ARCH_ALL) 3402STEXI 3403@item -parallel @var{dev} 3404@findex -parallel 3405Redirect the virtual parallel port to host device @var{dev} (same 3406devices as the serial port). On Linux hosts, @file{/dev/parportN} can 3407be used to use hardware devices connected on the corresponding host 3408parallel port. 3409 3410This option can be used several times to simulate up to 3 parallel 3411ports. 3412 3413Use @code{-parallel none} to disable all parallel ports. 3414ETEXI 3415 3416DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \ 3417 "-monitor dev redirect the monitor to char device 'dev'\n", 3418 QEMU_ARCH_ALL) 3419STEXI 3420@item -monitor @var{dev} 3421@findex -monitor 3422Redirect the monitor to host device @var{dev} (same devices as the 3423serial port). 3424The default device is @code{vc} in graphical mode and @code{stdio} in 3425non graphical mode. 3426Use @code{-monitor none} to disable the default monitor. 3427ETEXI 3428DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \ 3429 "-qmp dev like -monitor but opens in 'control' mode\n", 3430 QEMU_ARCH_ALL) 3431STEXI 3432@item -qmp @var{dev} 3433@findex -qmp 3434Like -monitor but opens in 'control' mode. 3435ETEXI 3436DEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \ 3437 "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n", 3438 QEMU_ARCH_ALL) 3439STEXI 3440@item -qmp-pretty @var{dev} 3441@findex -qmp-pretty 3442Like -qmp but uses pretty JSON formatting. 3443ETEXI 3444 3445DEF("mon", HAS_ARG, QEMU_OPTION_mon, \ 3446 "-mon [chardev=]name[,mode=readline|control][,pretty[=on|off]]\n", QEMU_ARCH_ALL) 3447STEXI 3448@item -mon [chardev=]name[,mode=readline|control][,pretty[=on|off]] 3449@findex -mon 3450Setup monitor on chardev @var{name}. @code{pretty} turns on JSON pretty printing 3451easing human reading and debugging. 3452ETEXI 3453 3454DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \ 3455 "-debugcon dev redirect the debug console to char device 'dev'\n", 3456 QEMU_ARCH_ALL) 3457STEXI 3458@item -debugcon @var{dev} 3459@findex -debugcon 3460Redirect the debug console to host device @var{dev} (same devices as the 3461serial port). The debug console is an I/O port which is typically port 34620xe9; writing to that I/O port sends output to this device. 3463The default device is @code{vc} in graphical mode and @code{stdio} in 3464non graphical mode. 3465ETEXI 3466 3467DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \ 3468 "-pidfile file write PID to 'file'\n", QEMU_ARCH_ALL) 3469STEXI 3470@item -pidfile @var{file} 3471@findex -pidfile 3472Store the QEMU process PID in @var{file}. It is useful if you launch QEMU 3473from a script. 3474ETEXI 3475 3476DEF("singlestep", 0, QEMU_OPTION_singlestep, \ 3477 "-singlestep always run in singlestep mode\n", QEMU_ARCH_ALL) 3478STEXI 3479@item -singlestep 3480@findex -singlestep 3481Run the emulation in single step mode. 3482ETEXI 3483 3484DEF("preconfig", 0, QEMU_OPTION_preconfig, \ 3485 "--preconfig pause QEMU before machine is initialized (experimental)\n", 3486 QEMU_ARCH_ALL) 3487STEXI 3488@item --preconfig 3489@findex --preconfig 3490Pause QEMU for interactive configuration before the machine is created, 3491which allows querying and configuring properties that will affect 3492machine initialization. Use QMP command 'x-exit-preconfig' to exit 3493the preconfig state and move to the next state (i.e. run guest if -S 3494isn't used or pause the second time if -S is used). This option is 3495experimental. 3496ETEXI 3497 3498DEF("S", 0, QEMU_OPTION_S, \ 3499 "-S freeze CPU at startup (use 'c' to start execution)\n", 3500 QEMU_ARCH_ALL) 3501STEXI 3502@item -S 3503@findex -S 3504Do not start CPU at startup (you must type 'c' in the monitor). 3505ETEXI 3506 3507DEF("realtime", HAS_ARG, QEMU_OPTION_realtime, 3508 "-realtime [mlock=on|off]\n" 3509 " run qemu with realtime features\n" 3510 " mlock=on|off controls mlock support (default: on)\n", 3511 QEMU_ARCH_ALL) 3512STEXI 3513@item -realtime mlock=on|off 3514@findex -realtime 3515Run qemu with realtime features. 3516mlocking qemu and guest memory can be enabled via @option{mlock=on} 3517(enabled by default). 3518ETEXI 3519 3520DEF("overcommit", HAS_ARG, QEMU_OPTION_overcommit, 3521 "-overcommit [mem-lock=on|off][cpu-pm=on|off]\n" 3522 " run qemu with overcommit hints\n" 3523 " mem-lock=on|off controls memory lock support (default: off)\n" 3524 " cpu-pm=on|off controls cpu power management (default: off)\n", 3525 QEMU_ARCH_ALL) 3526STEXI 3527@item -overcommit mem-lock=on|off 3528@item -overcommit cpu-pm=on|off 3529@findex -overcommit 3530Run qemu with hints about host resource overcommit. The default is 3531to assume that host overcommits all resources. 3532 3533Locking qemu and guest memory can be enabled via @option{mem-lock=on} (disabled 3534by default). This works when host memory is not overcommitted and reduces the 3535worst-case latency for guest. This is equivalent to @option{realtime}. 3536 3537Guest ability to manage power state of host cpus (increasing latency for other 3538processes on the same host cpu, but decreasing latency for guest) can be 3539enabled via @option{cpu-pm=on} (disabled by default). This works best when 3540host CPU is not overcommitted. When used, host estimates of CPU cycle and power 3541utilization will be incorrect, not taking into account guest idle time. 3542ETEXI 3543 3544DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \ 3545 "-gdb dev wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL) 3546STEXI 3547@item -gdb @var{dev} 3548@findex -gdb 3549Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical 3550connections will likely be TCP-based, but also UDP, pseudo TTY, or even 3551stdio are reasonable use case. The latter is allowing to start QEMU from 3552within gdb and establish the connection via a pipe: 3553@example 3554(gdb) target remote | exec qemu-system-i386 -gdb stdio ... 3555@end example 3556ETEXI 3557 3558DEF("s", 0, QEMU_OPTION_s, \ 3559 "-s shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n", 3560 QEMU_ARCH_ALL) 3561STEXI 3562@item -s 3563@findex -s 3564Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234 3565(@pxref{gdb_usage}). 3566ETEXI 3567 3568DEF("d", HAS_ARG, QEMU_OPTION_d, \ 3569 "-d item1,... enable logging of specified items (use '-d help' for a list of log items)\n", 3570 QEMU_ARCH_ALL) 3571STEXI 3572@item -d @var{item1}[,...] 3573@findex -d 3574Enable logging of specified items. Use '-d help' for a list of log items. 3575ETEXI 3576 3577DEF("D", HAS_ARG, QEMU_OPTION_D, \ 3578 "-D logfile output log to logfile (default stderr)\n", 3579 QEMU_ARCH_ALL) 3580STEXI 3581@item -D @var{logfile} 3582@findex -D 3583Output log in @var{logfile} instead of to stderr 3584ETEXI 3585 3586DEF("dfilter", HAS_ARG, QEMU_OPTION_DFILTER, \ 3587 "-dfilter range,.. filter debug output to range of addresses (useful for -d cpu,exec,etc..)\n", 3588 QEMU_ARCH_ALL) 3589STEXI 3590@item -dfilter @var{range1}[,...] 3591@findex -dfilter 3592Filter debug output to that relevant to a range of target addresses. The filter 3593spec can be either @var{start}+@var{size}, @var{start}-@var{size} or 3594@var{start}..@var{end} where @var{start} @var{end} and @var{size} are the 3595addresses and sizes required. For example: 3596@example 3597 -dfilter 0x8000..0x8fff,0xffffffc000080000+0x200,0xffffffc000060000-0x1000 3598@end example 3599Will dump output for any code in the 0x1000 sized block starting at 0x8000 and 3600the 0x200 sized block starting at 0xffffffc000080000 and another 0x1000 sized 3601block starting at 0xffffffc00005f000. 3602ETEXI 3603 3604DEF("L", HAS_ARG, QEMU_OPTION_L, \ 3605 "-L path set the directory for the BIOS, VGA BIOS and keymaps\n", 3606 QEMU_ARCH_ALL) 3607STEXI 3608@item -L @var{path} 3609@findex -L 3610Set the directory for the BIOS, VGA BIOS and keymaps. 3611 3612To list all the data directories, use @code{-L help}. 3613ETEXI 3614 3615DEF("bios", HAS_ARG, QEMU_OPTION_bios, \ 3616 "-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL) 3617STEXI 3618@item -bios @var{file} 3619@findex -bios 3620Set the filename for the BIOS. 3621ETEXI 3622 3623DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \ 3624 "-enable-kvm enable KVM full virtualization support\n", QEMU_ARCH_ALL) 3625STEXI 3626@item -enable-kvm 3627@findex -enable-kvm 3628Enable KVM full virtualization support. This option is only available 3629if KVM support is enabled when compiling. 3630ETEXI 3631 3632DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid, 3633 "-xen-domid id specify xen guest domain id\n", QEMU_ARCH_ALL) 3634DEF("xen-attach", 0, QEMU_OPTION_xen_attach, 3635 "-xen-attach attach to existing xen domain\n" 3636 " libxl will use this when starting QEMU\n", 3637 QEMU_ARCH_ALL) 3638DEF("xen-domid-restrict", 0, QEMU_OPTION_xen_domid_restrict, 3639 "-xen-domid-restrict restrict set of available xen operations\n" 3640 " to specified domain id. (Does not affect\n" 3641 " xenpv machine type).\n", 3642 QEMU_ARCH_ALL) 3643STEXI 3644@item -xen-domid @var{id} 3645@findex -xen-domid 3646Specify xen guest domain @var{id} (XEN only). 3647@item -xen-attach 3648@findex -xen-attach 3649Attach to existing xen domain. 3650libxl will use this when starting QEMU (XEN only). 3651@findex -xen-domid-restrict 3652Restrict set of available xen operations to specified domain id (XEN only). 3653ETEXI 3654 3655DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \ 3656 "-no-reboot exit instead of rebooting\n", QEMU_ARCH_ALL) 3657STEXI 3658@item -no-reboot 3659@findex -no-reboot 3660Exit instead of rebooting. 3661ETEXI 3662 3663DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \ 3664 "-no-shutdown stop before shutdown\n", QEMU_ARCH_ALL) 3665STEXI 3666@item -no-shutdown 3667@findex -no-shutdown 3668Don't exit QEMU on guest shutdown, but instead only stop the emulation. 3669This allows for instance switching to monitor to commit changes to the 3670disk image. 3671ETEXI 3672 3673DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \ 3674 "-loadvm [tag|id]\n" \ 3675 " start right away with a saved state (loadvm in monitor)\n", 3676 QEMU_ARCH_ALL) 3677STEXI 3678@item -loadvm @var{file} 3679@findex -loadvm 3680Start right away with a saved state (@code{loadvm} in monitor) 3681ETEXI 3682 3683#ifndef _WIN32 3684DEF("daemonize", 0, QEMU_OPTION_daemonize, \ 3685 "-daemonize daemonize QEMU after initializing\n", QEMU_ARCH_ALL) 3686#endif 3687STEXI 3688@item -daemonize 3689@findex -daemonize 3690Daemonize the QEMU process after initialization. QEMU will not detach from 3691standard IO until it is ready to receive connections on any of its devices. 3692This option is a useful way for external programs to launch QEMU without having 3693to cope with initialization race conditions. 3694ETEXI 3695 3696DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \ 3697 "-option-rom rom load a file, rom, into the option ROM space\n", 3698 QEMU_ARCH_ALL) 3699STEXI 3700@item -option-rom @var{file} 3701@findex -option-rom 3702Load the contents of @var{file} as an option ROM. 3703This option is useful to load things like EtherBoot. 3704ETEXI 3705 3706DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \ 3707 "-rtc [base=utc|localtime|<datetime>][,clock=host|rt|vm][,driftfix=none|slew]\n" \ 3708 " set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n", 3709 QEMU_ARCH_ALL) 3710 3711STEXI 3712 3713@item -rtc [base=utc|localtime|@var{datetime}][,clock=host|rt|vm][,driftfix=none|slew] 3714@findex -rtc 3715Specify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current 3716UTC or local time, respectively. @code{localtime} is required for correct date in 3717MS-DOS or Windows. To start at a specific point in time, provide @var{datetime} in the 3718format @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC. 3719 3720By default the RTC is driven by the host system time. This allows using of the 3721RTC as accurate reference clock inside the guest, specifically if the host 3722time is smoothly following an accurate external reference clock, e.g. via NTP. 3723If you want to isolate the guest time from the host, you can set @option{clock} 3724to @code{rt} instead, which provides a host monotonic clock if host support it. 3725To even prevent the RTC from progressing during suspension, you can set @option{clock} 3726to @code{vm} (virtual clock). @samp{clock=vm} is recommended especially in 3727icount mode in order to preserve determinism; however, note that in icount mode 3728the speed of the virtual clock is variable and can in general differ from the 3729host clock. 3730 3731Enable @option{driftfix} (i386 targets only) if you experience time drift problems, 3732specifically with Windows' ACPI HAL. This option will try to figure out how 3733many timer interrupts were not processed by the Windows guest and will 3734re-inject them. 3735ETEXI 3736 3737DEF("icount", HAS_ARG, QEMU_OPTION_icount, \ 3738 "-icount [shift=N|auto][,align=on|off][,sleep=on|off,rr=record|replay,rrfile=<filename>,rrsnapshot=<snapshot>]\n" \ 3739 " enable virtual instruction counter with 2^N clock ticks per\n" \ 3740 " instruction, enable aligning the host and virtual clocks\n" \ 3741 " or disable real time cpu sleeping\n", QEMU_ARCH_ALL) 3742STEXI 3743@item -icount [shift=@var{N}|auto][,rr=record|replay,rrfile=@var{filename},rrsnapshot=@var{snapshot}] 3744@findex -icount 3745Enable virtual instruction counter. The virtual cpu will execute one 3746instruction every 2^@var{N} ns of virtual time. If @code{auto} is specified 3747then the virtual cpu speed will be automatically adjusted to keep virtual 3748time within a few seconds of real time. 3749 3750When the virtual cpu is sleeping, the virtual time will advance at default 3751speed unless @option{sleep=on|off} is specified. 3752With @option{sleep=on|off}, the virtual time will jump to the next timer deadline 3753instantly whenever the virtual cpu goes to sleep mode and will not advance 3754if no timer is enabled. This behavior give deterministic execution times from 3755the guest point of view. 3756 3757Note that while this option can give deterministic behavior, it does not 3758provide cycle accurate emulation. Modern CPUs contain superscalar out of 3759order cores with complex cache hierarchies. The number of instructions 3760executed often has little or no correlation with actual performance. 3761 3762@option{align=on} will activate the delay algorithm which will try 3763to synchronise the host clock and the virtual clock. The goal is to 3764have a guest running at the real frequency imposed by the shift option. 3765Whenever the guest clock is behind the host clock and if 3766@option{align=on} is specified then we print a message to the user 3767to inform about the delay. 3768Currently this option does not work when @option{shift} is @code{auto}. 3769Note: The sync algorithm will work for those shift values for which 3770the guest clock runs ahead of the host clock. Typically this happens 3771when the shift value is high (how high depends on the host machine). 3772 3773When @option{rr} option is specified deterministic record/replay is enabled. 3774Replay log is written into @var{filename} file in record mode and 3775read from this file in replay mode. 3776 3777Option rrsnapshot is used to create new vm snapshot named @var{snapshot} 3778at the start of execution recording. In replay mode this option is used 3779to load the initial VM state. 3780ETEXI 3781 3782DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \ 3783 "-watchdog model\n" \ 3784 " enable virtual hardware watchdog [default=none]\n", 3785 QEMU_ARCH_ALL) 3786STEXI 3787@item -watchdog @var{model} 3788@findex -watchdog 3789Create a virtual hardware watchdog device. Once enabled (by a guest 3790action), the watchdog must be periodically polled by an agent inside 3791the guest or else the guest will be restarted. Choose a model for 3792which your guest has drivers. 3793 3794The @var{model} is the model of hardware watchdog to emulate. Use 3795@code{-watchdog help} to list available hardware models. Only one 3796watchdog can be enabled for a guest. 3797 3798The following models may be available: 3799@table @option 3800@item ib700 3801iBASE 700 is a very simple ISA watchdog with a single timer. 3802@item i6300esb 3803Intel 6300ESB I/O controller hub is a much more featureful PCI-based 3804dual-timer watchdog. 3805@item diag288 3806A virtual watchdog for s390x backed by the diagnose 288 hypercall 3807(currently KVM only). 3808@end table 3809ETEXI 3810 3811DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \ 3812 "-watchdog-action reset|shutdown|poweroff|inject-nmi|pause|debug|none\n" \ 3813 " action when watchdog fires [default=reset]\n", 3814 QEMU_ARCH_ALL) 3815STEXI 3816@item -watchdog-action @var{action} 3817@findex -watchdog-action 3818 3819The @var{action} controls what QEMU will do when the watchdog timer 3820expires. 3821The default is 3822@code{reset} (forcefully reset the guest). 3823Other possible actions are: 3824@code{shutdown} (attempt to gracefully shutdown the guest), 3825@code{poweroff} (forcefully poweroff the guest), 3826@code{inject-nmi} (inject a NMI into the guest), 3827@code{pause} (pause the guest), 3828@code{debug} (print a debug message and continue), or 3829@code{none} (do nothing). 3830 3831Note that the @code{shutdown} action requires that the guest responds 3832to ACPI signals, which it may not be able to do in the sort of 3833situations where the watchdog would have expired, and thus 3834@code{-watchdog-action shutdown} is not recommended for production use. 3835 3836Examples: 3837 3838@table @code 3839@item -watchdog i6300esb -watchdog-action pause 3840@itemx -watchdog ib700 3841@end table 3842ETEXI 3843 3844DEF("echr", HAS_ARG, QEMU_OPTION_echr, \ 3845 "-echr chr set terminal escape character instead of ctrl-a\n", 3846 QEMU_ARCH_ALL) 3847STEXI 3848 3849@item -echr @var{numeric_ascii_value} 3850@findex -echr 3851Change the escape character used for switching to the monitor when using 3852monitor and serial sharing. The default is @code{0x01} when using the 3853@code{-nographic} option. @code{0x01} is equal to pressing 3854@code{Control-a}. You can select a different character from the ascii 3855control keys where 1 through 26 map to Control-a through Control-z. For 3856instance you could use the either of the following to change the escape 3857character to Control-t. 3858@table @code 3859@item -echr 0x14 3860@itemx -echr 20 3861@end table 3862ETEXI 3863 3864DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \ 3865 "-show-cursor show cursor\n", QEMU_ARCH_ALL) 3866STEXI 3867@item -show-cursor 3868@findex -show-cursor 3869Show cursor. 3870ETEXI 3871 3872DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \ 3873 "-tb-size n set TB size\n", QEMU_ARCH_ALL) 3874STEXI 3875@item -tb-size @var{n} 3876@findex -tb-size 3877Set TB size. 3878ETEXI 3879 3880DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \ 3881 "-incoming tcp:[host]:port[,to=maxport][,ipv4][,ipv6]\n" \ 3882 "-incoming rdma:host:port[,ipv4][,ipv6]\n" \ 3883 "-incoming unix:socketpath\n" \ 3884 " prepare for incoming migration, listen on\n" \ 3885 " specified protocol and socket address\n" \ 3886 "-incoming fd:fd\n" \ 3887 "-incoming exec:cmdline\n" \ 3888 " accept incoming migration on given file descriptor\n" \ 3889 " or from given external command\n" \ 3890 "-incoming defer\n" \ 3891 " wait for the URI to be specified via migrate_incoming\n", 3892 QEMU_ARCH_ALL) 3893STEXI 3894@item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6] 3895@itemx -incoming rdma:@var{host}:@var{port}[,ipv4][,ipv6] 3896@findex -incoming 3897Prepare for incoming migration, listen on a given tcp port. 3898 3899@item -incoming unix:@var{socketpath} 3900Prepare for incoming migration, listen on a given unix socket. 3901 3902@item -incoming fd:@var{fd} 3903Accept incoming migration from a given filedescriptor. 3904 3905@item -incoming exec:@var{cmdline} 3906Accept incoming migration as an output from specified external command. 3907 3908@item -incoming defer 3909Wait for the URI to be specified via migrate_incoming. The monitor can 3910be used to change settings (such as migration parameters) prior to issuing 3911the migrate_incoming to allow the migration to begin. 3912ETEXI 3913 3914DEF("only-migratable", 0, QEMU_OPTION_only_migratable, \ 3915 "-only-migratable allow only migratable devices\n", QEMU_ARCH_ALL) 3916STEXI 3917@item -only-migratable 3918@findex -only-migratable 3919Only allow migratable devices. Devices will not be allowed to enter an 3920unmigratable state. 3921ETEXI 3922 3923DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \ 3924 "-nodefaults don't create default devices\n", QEMU_ARCH_ALL) 3925STEXI 3926@item -nodefaults 3927@findex -nodefaults 3928Don't create default devices. Normally, QEMU sets the default devices like serial 3929port, parallel port, virtual console, monitor device, VGA adapter, floppy and 3930CD-ROM drive and others. The @code{-nodefaults} option will disable all those 3931default devices. 3932ETEXI 3933 3934#ifndef _WIN32 3935DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \ 3936 "-chroot dir chroot to dir just before starting the VM\n", 3937 QEMU_ARCH_ALL) 3938#endif 3939STEXI 3940@item -chroot @var{dir} 3941@findex -chroot 3942Immediately before starting guest execution, chroot to the specified 3943directory. Especially useful in combination with -runas. 3944ETEXI 3945 3946#ifndef _WIN32 3947DEF("runas", HAS_ARG, QEMU_OPTION_runas, \ 3948 "-runas user change to user id user just before starting the VM\n" \ 3949 " user can be numeric uid:gid instead\n", 3950 QEMU_ARCH_ALL) 3951#endif 3952STEXI 3953@item -runas @var{user} 3954@findex -runas 3955Immediately before starting guest execution, drop root privileges, switching 3956to the specified user. 3957ETEXI 3958 3959DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env, 3960 "-prom-env variable=value\n" 3961 " set OpenBIOS nvram variables\n", 3962 QEMU_ARCH_PPC | QEMU_ARCH_SPARC) 3963STEXI 3964@item -prom-env @var{variable}=@var{value} 3965@findex -prom-env 3966Set OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only). 3967ETEXI 3968DEF("semihosting", 0, QEMU_OPTION_semihosting, 3969 "-semihosting semihosting mode\n", 3970 QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 | 3971 QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2) 3972STEXI 3973@item -semihosting 3974@findex -semihosting 3975Enable semihosting mode (ARM, M68K, Xtensa, MIPS, Nios II only). 3976ETEXI 3977DEF("semihosting-config", HAS_ARG, QEMU_OPTION_semihosting_config, 3978 "-semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]]\n" \ 3979 " semihosting configuration\n", 3980QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA | QEMU_ARCH_LM32 | 3981QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2) 3982STEXI 3983@item -semihosting-config [enable=on|off][,target=native|gdb|auto][,arg=str[,...]] 3984@findex -semihosting-config 3985Enable and configure semihosting (ARM, M68K, Xtensa, MIPS, Nios II only). 3986@table @option 3987@item target=@code{native|gdb|auto} 3988Defines where the semihosting calls will be addressed, to QEMU (@code{native}) 3989or to GDB (@code{gdb}). The default is @code{auto}, which means @code{gdb} 3990during debug sessions and @code{native} otherwise. 3991@item arg=@var{str1},arg=@var{str2},... 3992Allows the user to pass input arguments, and can be used multiple times to build 3993up a list. The old-style @code{-kernel}/@code{-append} method of passing a 3994command line is still supported for backward compatibility. If both the 3995@code{--semihosting-config arg} and the @code{-kernel}/@code{-append} are 3996specified, the former is passed to semihosting as it always takes precedence. 3997@end table 3998ETEXI 3999DEF("old-param", 0, QEMU_OPTION_old_param, 4000 "-old-param old param mode\n", QEMU_ARCH_ARM) 4001STEXI 4002@item -old-param 4003@findex -old-param (ARM) 4004Old param mode (ARM only). 4005ETEXI 4006 4007DEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \ 4008 "-sandbox on[,obsolete=allow|deny][,elevateprivileges=allow|deny|children]\n" \ 4009 " [,spawn=allow|deny][,resourcecontrol=allow|deny]\n" \ 4010 " Enable seccomp mode 2 system call filter (default 'off').\n" \ 4011 " use 'obsolete' to allow obsolete system calls that are provided\n" \ 4012 " by the kernel, but typically no longer used by modern\n" \ 4013 " C library implementations.\n" \ 4014 " use 'elevateprivileges' to allow or deny QEMU process to elevate\n" \ 4015 " its privileges by blacklisting all set*uid|gid system calls.\n" \ 4016 " The value 'children' will deny set*uid|gid system calls for\n" \ 4017 " main QEMU process but will allow forks and execves to run unprivileged\n" \ 4018 " use 'spawn' to avoid QEMU to spawn new threads or processes by\n" \ 4019 " blacklisting *fork and execve\n" \ 4020 " use 'resourcecontrol' to disable process affinity and schedular priority\n", 4021 QEMU_ARCH_ALL) 4022STEXI 4023@item -sandbox @var{arg}[,obsolete=@var{string}][,elevateprivileges=@var{string}][,spawn=@var{string}][,resourcecontrol=@var{string}] 4024@findex -sandbox 4025Enable Seccomp mode 2 system call filter. 'on' will enable syscall filtering and 'off' will 4026disable it. The default is 'off'. 4027@table @option 4028@item obsolete=@var{string} 4029Enable Obsolete system calls 4030@item elevateprivileges=@var{string} 4031Disable set*uid|gid system calls 4032@item spawn=@var{string} 4033Disable *fork and execve 4034@item resourcecontrol=@var{string} 4035Disable process affinity and schedular priority 4036@end table 4037ETEXI 4038 4039DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig, 4040 "-readconfig <file>\n", QEMU_ARCH_ALL) 4041STEXI 4042@item -readconfig @var{file} 4043@findex -readconfig 4044Read device configuration from @var{file}. This approach is useful when you want to spawn 4045QEMU process with many command line options but you don't want to exceed the command line 4046character limit. 4047ETEXI 4048DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig, 4049 "-writeconfig <file>\n" 4050 " read/write config file\n", QEMU_ARCH_ALL) 4051STEXI 4052@item -writeconfig @var{file} 4053@findex -writeconfig 4054Write device configuration to @var{file}. The @var{file} can be either filename to save 4055command line and device configuration into file or dash @code{-}) character to print the 4056output to stdout. This can be later used as input file for @code{-readconfig} option. 4057ETEXI 4058 4059DEF("no-user-config", 0, QEMU_OPTION_nouserconfig, 4060 "-no-user-config\n" 4061 " do not load default user-provided config files at startup\n", 4062 QEMU_ARCH_ALL) 4063STEXI 4064@item -no-user-config 4065@findex -no-user-config 4066The @code{-no-user-config} option makes QEMU not load any of the user-provided 4067config files on @var{sysconfdir}. 4068ETEXI 4069 4070DEF("trace", HAS_ARG, QEMU_OPTION_trace, 4071 "-trace [[enable=]<pattern>][,events=<file>][,file=<file>]\n" 4072 " specify tracing options\n", 4073 QEMU_ARCH_ALL) 4074STEXI 4075HXCOMM This line is not accurate, as some sub-options are backend-specific but 4076HXCOMM HX does not support conditional compilation of text. 4077@item -trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}] 4078@findex -trace 4079@include qemu-option-trace.texi 4080ETEXI 4081 4082HXCOMM Internal use 4083DEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL) 4084DEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL) 4085 4086#ifdef __linux__ 4087DEF("enable-fips", 0, QEMU_OPTION_enablefips, 4088 "-enable-fips enable FIPS 140-2 compliance\n", 4089 QEMU_ARCH_ALL) 4090#endif 4091STEXI 4092@item -enable-fips 4093@findex -enable-fips 4094Enable FIPS 140-2 compliance mode. 4095ETEXI 4096 4097HXCOMM Deprecated by -machine accel=tcg property 4098DEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386) 4099 4100DEF("msg", HAS_ARG, QEMU_OPTION_msg, 4101 "-msg timestamp[=on|off]\n" 4102 " change the format of messages\n" 4103 " on|off controls leading timestamps (default:on)\n", 4104 QEMU_ARCH_ALL) 4105STEXI 4106@item -msg timestamp[=on|off] 4107@findex -msg 4108prepend a timestamp to each log message.(default:on) 4109ETEXI 4110 4111DEF("dump-vmstate", HAS_ARG, QEMU_OPTION_dump_vmstate, 4112 "-dump-vmstate <file>\n" 4113 " Output vmstate information in JSON format to file.\n" 4114 " Use the scripts/vmstate-static-checker.py file to\n" 4115 " check for possible regressions in migration code\n" 4116 " by comparing two such vmstate dumps.\n", 4117 QEMU_ARCH_ALL) 4118STEXI 4119@item -dump-vmstate @var{file} 4120@findex -dump-vmstate 4121Dump json-encoded vmstate information for current machine type to file 4122in @var{file} 4123ETEXI 4124 4125DEF("enable-sync-profile", 0, QEMU_OPTION_enable_sync_profile, 4126 "-enable-sync-profile\n" 4127 " enable synchronization profiling\n", 4128 QEMU_ARCH_ALL) 4129STEXI 4130@item -enable-sync-profile 4131@findex -enable-sync-profile 4132Enable synchronization profiling. 4133ETEXI 4134 4135STEXI 4136@end table 4137ETEXI 4138DEFHEADING() 4139 4140DEFHEADING(Generic object creation:) 4141STEXI 4142@table @option 4143ETEXI 4144 4145DEF("object", HAS_ARG, QEMU_OPTION_object, 4146 "-object TYPENAME[,PROP1=VALUE1,...]\n" 4147 " create a new object of type TYPENAME setting properties\n" 4148 " in the order they are specified. Note that the 'id'\n" 4149 " property must be set. These objects are placed in the\n" 4150 " '/objects' path.\n", 4151 QEMU_ARCH_ALL) 4152STEXI 4153@item -object @var{typename}[,@var{prop1}=@var{value1},...] 4154@findex -object 4155Create a new object of type @var{typename} setting properties 4156in the order they are specified. Note that the 'id' 4157property must be set. These objects are placed in the 4158'/objects' path. 4159 4160@table @option 4161 4162@item -object memory-backend-file,id=@var{id},size=@var{size},mem-path=@var{dir},share=@var{on|off},discard-data=@var{on|off},merge=@var{on|off},dump=@var{on|off},prealloc=@var{on|off},host-nodes=@var{host-nodes},policy=@var{default|preferred|bind|interleave},align=@var{align} 4163 4164Creates a memory file backend object, which can be used to back 4165the guest RAM with huge pages. 4166 4167The @option{id} parameter is a unique ID that will be used to reference this 4168memory region when configuring the @option{-numa} argument. 4169 4170The @option{size} option provides the size of the memory region, and accepts 4171common suffixes, eg @option{500M}. 4172 4173The @option{mem-path} provides the path to either a shared memory or huge page 4174filesystem mount. 4175 4176The @option{share} boolean option determines whether the memory 4177region is marked as private to QEMU, or shared. The latter allows 4178a co-operating external process to access the QEMU memory region. 4179 4180The @option{share} is also required for pvrdma devices due to 4181limitations in the RDMA API provided by Linux. 4182 4183Setting share=on might affect the ability to configure NUMA 4184bindings for the memory backend under some circumstances, see 4185Documentation/vm/numa_memory_policy.txt on the Linux kernel 4186source tree for additional details. 4187 4188Setting the @option{discard-data} boolean option to @var{on} 4189indicates that file contents can be destroyed when QEMU exits, 4190to avoid unnecessarily flushing data to the backing file. Note 4191that @option{discard-data} is only an optimization, and QEMU 4192might not discard file contents if it aborts unexpectedly or is 4193terminated using SIGKILL. 4194 4195The @option{merge} boolean option enables memory merge, also known as 4196MADV_MERGEABLE, so that Kernel Samepage Merging will consider the pages for 4197memory deduplication. 4198 4199Setting the @option{dump} boolean option to @var{off} excludes the memory from 4200core dumps. This feature is also known as MADV_DONTDUMP. 4201 4202The @option{prealloc} boolean option enables memory preallocation. 4203 4204The @option{host-nodes} option binds the memory range to a list of NUMA host 4205nodes. 4206 4207The @option{policy} option sets the NUMA policy to one of the following values: 4208 4209@table @option 4210@item @var{default} 4211default host policy 4212 4213@item @var{preferred} 4214prefer the given host node list for allocation 4215 4216@item @var{bind} 4217restrict memory allocation to the given host node list 4218 4219@item @var{interleave} 4220interleave memory allocations across the given host node list 4221@end table 4222 4223The @option{align} option specifies the base address alignment when 4224QEMU mmap(2) @option{mem-path}, and accepts common suffixes, eg 4225@option{2M}. Some backend store specified by @option{mem-path} 4226requires an alignment different than the default one used by QEMU, eg 4227the device DAX /dev/dax0.0 requires 2M alignment rather than 4K. In 4228such cases, users can specify the required alignment via this option. 4229 4230The @option{pmem} option specifies whether the backing file specified 4231by @option{mem-path} is in host persistent memory that can be accessed 4232using the SNIA NVM programming model (e.g. Intel NVDIMM). 4233If @option{pmem} is set to 'on', QEMU will take necessary operations to 4234guarantee the persistence of its own writes to @option{mem-path} 4235(e.g. in vNVDIMM label emulation and live migration). 4236Also, we will map the backend-file with MAP_SYNC flag, which ensures the 4237file metadata is in sync for @option{mem-path} in case of host crash 4238or a power failure. MAP_SYNC requires support from both the host kernel 4239(since Linux kernel 4.15) and the filesystem of @option{mem-path} mounted 4240with DAX option. 4241 4242@item -object memory-backend-ram,id=@var{id},merge=@var{on|off},dump=@var{on|off},share=@var{on|off},prealloc=@var{on|off},size=@var{size},host-nodes=@var{host-nodes},policy=@var{default|preferred|bind|interleave} 4243 4244Creates a memory backend object, which can be used to back the guest RAM. 4245Memory backend objects offer more control than the @option{-m} option that is 4246traditionally used to define guest RAM. Please refer to 4247@option{memory-backend-file} for a description of the options. 4248 4249@item -object memory-backend-memfd,id=@var{id},merge=@var{on|off},dump=@var{on|off},share=@var{on|off},prealloc=@var{on|off},size=@var{size},host-nodes=@var{host-nodes},policy=@var{default|preferred|bind|interleave},seal=@var{on|off},hugetlb=@var{on|off},hugetlbsize=@var{size} 4250 4251Creates an anonymous memory file backend object, which allows QEMU to 4252share the memory with an external process (e.g. when using 4253vhost-user). The memory is allocated with memfd and optional 4254sealing. (Linux only) 4255 4256The @option{seal} option creates a sealed-file, that will block 4257further resizing the memory ('on' by default). 4258 4259The @option{hugetlb} option specify the file to be created resides in 4260the hugetlbfs filesystem (since Linux 4.14). Used in conjunction with 4261the @option{hugetlb} option, the @option{hugetlbsize} option specify 4262the hugetlb page size on systems that support multiple hugetlb page 4263sizes (it must be a power of 2 value supported by the system). 4264 4265In some versions of Linux, the @option{hugetlb} option is incompatible 4266with the @option{seal} option (requires at least Linux 4.16). 4267 4268Please refer to @option{memory-backend-file} for a description of the 4269other options. 4270 4271The @option{share} boolean option is @var{on} by default with memfd. 4272 4273@item -object rng-random,id=@var{id},filename=@var{/dev/random} 4274 4275Creates a random number generator backend which obtains entropy from 4276a device on the host. The @option{id} parameter is a unique ID that 4277will be used to reference this entropy backend from the @option{virtio-rng} 4278device. The @option{filename} parameter specifies which file to obtain 4279entropy from and if omitted defaults to @option{/dev/random}. 4280 4281@item -object rng-egd,id=@var{id},chardev=@var{chardevid} 4282 4283Creates a random number generator backend which obtains entropy from 4284an external daemon running on the host. The @option{id} parameter is 4285a unique ID that will be used to reference this entropy backend from 4286the @option{virtio-rng} device. The @option{chardev} parameter is 4287the unique ID of a character device backend that provides the connection 4288to the RNG daemon. 4289 4290@item -object tls-creds-anon,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},verify-peer=@var{on|off} 4291 4292Creates a TLS anonymous credentials object, which can be used to provide 4293TLS support on network backends. The @option{id} parameter is a unique 4294ID which network backends will use to access the credentials. The 4295@option{endpoint} is either @option{server} or @option{client} depending 4296on whether the QEMU network backend that uses the credentials will be 4297acting as a client or as a server. If @option{verify-peer} is enabled 4298(the default) then once the handshake is completed, the peer credentials 4299will be verified, though this is a no-op for anonymous credentials. 4300 4301The @var{dir} parameter tells QEMU where to find the credential 4302files. For server endpoints, this directory may contain a file 4303@var{dh-params.pem} providing diffie-hellman parameters to use 4304for the TLS server. If the file is missing, QEMU will generate 4305a set of DH parameters at startup. This is a computationally 4306expensive operation that consumes random pool entropy, so it is 4307recommended that a persistent set of parameters be generated 4308upfront and saved. 4309 4310@item -object tls-creds-psk,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/keys/dir}[,username=@var{username}] 4311 4312Creates a TLS Pre-Shared Keys (PSK) credentials object, which can be used to provide 4313TLS support on network backends. The @option{id} parameter is a unique 4314ID which network backends will use to access the credentials. The 4315@option{endpoint} is either @option{server} or @option{client} depending 4316on whether the QEMU network backend that uses the credentials will be 4317acting as a client or as a server. For clients only, @option{username} 4318is the username which will be sent to the server. If omitted 4319it defaults to ``qemu''. 4320 4321The @var{dir} parameter tells QEMU where to find the keys file. 4322It is called ``@var{dir}/keys.psk'' and contains ``username:key'' 4323pairs. This file can most easily be created using the GnuTLS 4324@code{psktool} program. 4325 4326For server endpoints, @var{dir} may also contain a file 4327@var{dh-params.pem} providing diffie-hellman parameters to use 4328for the TLS server. If the file is missing, QEMU will generate 4329a set of DH parameters at startup. This is a computationally 4330expensive operation that consumes random pool entropy, so it is 4331recommended that a persistent set of parameters be generated 4332up front and saved. 4333 4334@item -object tls-creds-x509,id=@var{id},endpoint=@var{endpoint},dir=@var{/path/to/cred/dir},priority=@var{priority},verify-peer=@var{on|off},passwordid=@var{id} 4335 4336Creates a TLS anonymous credentials object, which can be used to provide 4337TLS support on network backends. The @option{id} parameter is a unique 4338ID which network backends will use to access the credentials. The 4339@option{endpoint} is either @option{server} or @option{client} depending 4340on whether the QEMU network backend that uses the credentials will be 4341acting as a client or as a server. If @option{verify-peer} is enabled 4342(the default) then once the handshake is completed, the peer credentials 4343will be verified. With x509 certificates, this implies that the clients 4344must be provided with valid client certificates too. 4345 4346The @var{dir} parameter tells QEMU where to find the credential 4347files. For server endpoints, this directory may contain a file 4348@var{dh-params.pem} providing diffie-hellman parameters to use 4349for the TLS server. If the file is missing, QEMU will generate 4350a set of DH parameters at startup. This is a computationally 4351expensive operation that consumes random pool entropy, so it is 4352recommended that a persistent set of parameters be generated 4353upfront and saved. 4354 4355For x509 certificate credentials the directory will contain further files 4356providing the x509 certificates. The certificates must be stored 4357in PEM format, in filenames @var{ca-cert.pem}, @var{ca-crl.pem} (optional), 4358@var{server-cert.pem} (only servers), @var{server-key.pem} (only servers), 4359@var{client-cert.pem} (only clients), and @var{client-key.pem} (only clients). 4360 4361For the @var{server-key.pem} and @var{client-key.pem} files which 4362contain sensitive private keys, it is possible to use an encrypted 4363version by providing the @var{passwordid} parameter. This provides 4364the ID of a previously created @code{secret} object containing the 4365password for decryption. 4366 4367The @var{priority} parameter allows to override the global default 4368priority used by gnutls. This can be useful if the system administrator 4369needs to use a weaker set of crypto priorities for QEMU without 4370potentially forcing the weakness onto all applications. Or conversely 4371if one wants wants a stronger default for QEMU than for all other 4372applications, they can do this through this parameter. Its format is 4373a gnutls priority string as described at 4374@url{https://gnutls.org/manual/html_node/Priority-Strings.html}. 4375 4376@item -object filter-buffer,id=@var{id},netdev=@var{netdevid},interval=@var{t}[,queue=@var{all|rx|tx}][,status=@var{on|off}] 4377 4378Interval @var{t} can't be 0, this filter batches the packet delivery: all 4379packets arriving in a given interval on netdev @var{netdevid} are delayed 4380until the end of the interval. Interval is in microseconds. 4381@option{status} is optional that indicate whether the netfilter is 4382on (enabled) or off (disabled), the default status for netfilter will be 'on'. 4383 4384queue @var{all|rx|tx} is an option that can be applied to any netfilter. 4385 4386@option{all}: the filter is attached both to the receive and the transmit 4387 queue of the netdev (default). 4388 4389@option{rx}: the filter is attached to the receive queue of the netdev, 4390 where it will receive packets sent to the netdev. 4391 4392@option{tx}: the filter is attached to the transmit queue of the netdev, 4393 where it will receive packets sent by the netdev. 4394 4395@item -object filter-mirror,id=@var{id},netdev=@var{netdevid},outdev=@var{chardevid},queue=@var{all|rx|tx}[,vnet_hdr_support] 4396 4397filter-mirror on netdev @var{netdevid},mirror net packet to chardev@var{chardevid}, if it has the vnet_hdr_support flag, filter-mirror will mirror packet with vnet_hdr_len. 4398 4399@item -object filter-redirector,id=@var{id},netdev=@var{netdevid},indev=@var{chardevid},outdev=@var{chardevid},queue=@var{all|rx|tx}[,vnet_hdr_support] 4400 4401filter-redirector on netdev @var{netdevid},redirect filter's net packet to chardev 4402@var{chardevid},and redirect indev's packet to filter.if it has the vnet_hdr_support flag, 4403filter-redirector will redirect packet with vnet_hdr_len. 4404Create a filter-redirector we need to differ outdev id from indev id, id can not 4405be the same. we can just use indev or outdev, but at least one of indev or outdev 4406need to be specified. 4407 4408@item -object filter-rewriter,id=@var{id},netdev=@var{netdevid},queue=@var{all|rx|tx},[vnet_hdr_support] 4409 4410Filter-rewriter is a part of COLO project.It will rewrite tcp packet to 4411secondary from primary to keep secondary tcp connection,and rewrite 4412tcp packet to primary from secondary make tcp packet can be handled by 4413client.if it has the vnet_hdr_support flag, we can parse packet with vnet header. 4414 4415usage: 4416colo secondary: 4417-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 4418-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 4419-object filter-rewriter,id=rew0,netdev=hn0,queue=all 4420 4421@item -object filter-dump,id=@var{id},netdev=@var{dev}[,file=@var{filename}][,maxlen=@var{len}] 4422 4423Dump the network traffic on netdev @var{dev} to the file specified by 4424@var{filename}. At most @var{len} bytes (64k by default) per packet are stored. 4425The file format is libpcap, so it can be analyzed with tools such as tcpdump 4426or Wireshark. 4427 4428@item -object colo-compare,id=@var{id},primary_in=@var{chardevid},secondary_in=@var{chardevid},outdev=@var{chardevid},iothread=@var{id}[,vnet_hdr_support] 4429 4430Colo-compare gets packet from primary_in@var{chardevid} and secondary_in@var{chardevid}, than compare primary packet with 4431secondary packet. If the packets are same, we will output primary 4432packet to outdev@var{chardevid}, else we will notify colo-frame 4433do checkpoint and send primary packet to outdev@var{chardevid}. 4434In order to improve efficiency, we need to put the task of comparison 4435in another thread. If it has the vnet_hdr_support flag, colo compare 4436will send/recv packet with vnet_hdr_len. 4437 4438we must use it with the help of filter-mirror and filter-redirector. 4439 4440@example 4441 4442primary: 4443-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown 4444-device e1000,id=e0,netdev=hn0,mac=52:a4:00:12:78:66 4445-chardev socket,id=mirror0,host=3.3.3.3,port=9003,server,nowait 4446-chardev socket,id=compare1,host=3.3.3.3,port=9004,server,nowait 4447-chardev socket,id=compare0,host=3.3.3.3,port=9001,server,nowait 4448-chardev socket,id=compare0-0,host=3.3.3.3,port=9001 4449-chardev socket,id=compare_out,host=3.3.3.3,port=9005,server,nowait 4450-chardev socket,id=compare_out0,host=3.3.3.3,port=9005 4451-object iothread,id=iothread1 4452-object filter-mirror,id=m0,netdev=hn0,queue=tx,outdev=mirror0 4453-object filter-redirector,netdev=hn0,id=redire0,queue=rx,indev=compare_out 4454-object filter-redirector,netdev=hn0,id=redire1,queue=rx,outdev=compare0 4455-object colo-compare,id=comp0,primary_in=compare0-0,secondary_in=compare1,outdev=compare_out0,iothread=iothread1 4456 4457secondary: 4458-netdev tap,id=hn0,vhost=off,script=/etc/qemu-ifup,down script=/etc/qemu-ifdown 4459-device e1000,netdev=hn0,mac=52:a4:00:12:78:66 4460-chardev socket,id=red0,host=3.3.3.3,port=9003 4461-chardev socket,id=red1,host=3.3.3.3,port=9004 4462-object filter-redirector,id=f1,netdev=hn0,queue=tx,indev=red0 4463-object filter-redirector,id=f2,netdev=hn0,queue=rx,outdev=red1 4464 4465@end example 4466 4467If you want to know the detail of above command line, you can read 4468the colo-compare git log. 4469 4470@item -object cryptodev-backend-builtin,id=@var{id}[,queues=@var{queues}] 4471 4472Creates a cryptodev backend which executes crypto opreation from 4473the QEMU cipher APIS. The @var{id} parameter is 4474a unique ID that will be used to reference this cryptodev backend from 4475the @option{virtio-crypto} device. The @var{queues} parameter is optional, 4476which specify the queue number of cryptodev backend, the default of 4477@var{queues} is 1. 4478 4479@example 4480 4481 # qemu-system-x86_64 \ 4482 [...] \ 4483 -object cryptodev-backend-builtin,id=cryptodev0 \ 4484 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \ 4485 [...] 4486@end example 4487 4488@item -object cryptodev-vhost-user,id=@var{id},chardev=@var{chardevid}[,queues=@var{queues}] 4489 4490Creates a vhost-user cryptodev backend, backed by a chardev @var{chardevid}. 4491The @var{id} parameter is a unique ID that will be used to reference this 4492cryptodev backend from the @option{virtio-crypto} device. 4493The chardev should be a unix domain socket backed one. The vhost-user uses 4494a specifically defined protocol to pass vhost ioctl replacement messages 4495to an application on the other end of the socket. 4496The @var{queues} parameter is optional, which specify the queue number 4497of cryptodev backend for multiqueue vhost-user, the default of @var{queues} is 1. 4498 4499@example 4500 4501 # qemu-system-x86_64 \ 4502 [...] \ 4503 -chardev socket,id=chardev0,path=/path/to/socket \ 4504 -object cryptodev-vhost-user,id=cryptodev0,chardev=chardev0 \ 4505 -device virtio-crypto-pci,id=crypto0,cryptodev=cryptodev0 \ 4506 [...] 4507@end example 4508 4509@item -object secret,id=@var{id},data=@var{string},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}] 4510@item -object secret,id=@var{id},file=@var{filename},format=@var{raw|base64}[,keyid=@var{secretid},iv=@var{string}] 4511 4512Defines a secret to store a password, encryption key, or some other sensitive 4513data. The sensitive data can either be passed directly via the @var{data} 4514parameter, or indirectly via the @var{file} parameter. Using the @var{data} 4515parameter is insecure unless the sensitive data is encrypted. 4516 4517The sensitive data can be provided in raw format (the default), or base64. 4518When encoded as JSON, the raw format only supports valid UTF-8 characters, 4519so base64 is recommended for sending binary data. QEMU will convert from 4520which ever format is provided to the format it needs internally. eg, an 4521RBD password can be provided in raw format, even though it will be base64 4522encoded when passed onto the RBD sever. 4523 4524For added protection, it is possible to encrypt the data associated with 4525a secret using the AES-256-CBC cipher. Use of encryption is indicated 4526by providing the @var{keyid} and @var{iv} parameters. The @var{keyid} 4527parameter provides the ID of a previously defined secret that contains 4528the AES-256 decryption key. This key should be 32-bytes long and be 4529base64 encoded. The @var{iv} parameter provides the random initialization 4530vector used for encryption of this particular secret and should be a 4531base64 encrypted string of the 16-byte IV. 4532 4533The simplest (insecure) usage is to provide the secret inline 4534 4535@example 4536 4537 # $QEMU -object secret,id=sec0,data=letmein,format=raw 4538 4539@end example 4540 4541The simplest secure usage is to provide the secret via a file 4542 4543 # printf "letmein" > mypasswd.txt 4544 # $QEMU -object secret,id=sec0,file=mypasswd.txt,format=raw 4545 4546For greater security, AES-256-CBC should be used. To illustrate usage, 4547consider the openssl command line tool which can encrypt the data. Note 4548that when encrypting, the plaintext must be padded to the cipher block 4549size (32 bytes) using the standard PKCS#5/6 compatible padding algorithm. 4550 4551First a master key needs to be created in base64 encoding: 4552 4553@example 4554 # openssl rand -base64 32 > key.b64 4555 # KEY=$(base64 -d key.b64 | hexdump -v -e '/1 "%02X"') 4556@end example 4557 4558Each secret to be encrypted needs to have a random initialization vector 4559generated. These do not need to be kept secret 4560 4561@example 4562 # openssl rand -base64 16 > iv.b64 4563 # IV=$(base64 -d iv.b64 | hexdump -v -e '/1 "%02X"') 4564@end example 4565 4566The secret to be defined can now be encrypted, in this case we're 4567telling openssl to base64 encode the result, but it could be left 4568as raw bytes if desired. 4569 4570@example 4571 # SECRET=$(printf "letmein" | 4572 openssl enc -aes-256-cbc -a -K $KEY -iv $IV) 4573@end example 4574 4575When launching QEMU, create a master secret pointing to @code{key.b64} 4576and specify that to be used to decrypt the user password. Pass the 4577contents of @code{iv.b64} to the second secret 4578 4579@example 4580 # $QEMU \ 4581 -object secret,id=secmaster0,format=base64,file=key.b64 \ 4582 -object secret,id=sec0,keyid=secmaster0,format=base64,\ 4583 data=$SECRET,iv=$(<iv.b64) 4584@end example 4585 4586@item -object sev-guest,id=@var{id},cbitpos=@var{cbitpos},reduced-phys-bits=@var{val},[sev-device=@var{string},policy=@var{policy},handle=@var{handle},dh-cert-file=@var{file},session-file=@var{file}] 4587 4588Create a Secure Encrypted Virtualization (SEV) guest object, which can be used 4589to provide the guest memory encryption support on AMD processors. 4590 4591When memory encryption is enabled, one of the physical address bit (aka the 4592C-bit) is utilized to mark if a memory page is protected. The @option{cbitpos} 4593is used to provide the C-bit position. The C-bit position is Host family dependent 4594hence user must provide this value. On EPYC, the value should be 47. 4595 4596When memory encryption is enabled, we loose certain bits in physical address space. 4597The @option{reduced-phys-bits} is used to provide the number of bits we loose in 4598physical address space. Similar to C-bit, the value is Host family dependent. 4599On EPYC, the value should be 5. 4600 4601The @option{sev-device} provides the device file to use for communicating with 4602the SEV firmware running inside AMD Secure Processor. The default device is 4603'/dev/sev'. If hardware supports memory encryption then /dev/sev devices are 4604created by CCP driver. 4605 4606The @option{policy} provides the guest policy to be enforced by the SEV firmware 4607and restrict what configuration and operational commands can be performed on this 4608guest by the hypervisor. The policy should be provided by the guest owner and is 4609bound to the guest and cannot be changed throughout the lifetime of the guest. 4610The default is 0. 4611 4612If guest @option{policy} allows sharing the key with another SEV guest then 4613@option{handle} can be use to provide handle of the guest from which to share 4614the key. 4615 4616The @option{dh-cert-file} and @option{session-file} provides the guest owner's 4617Public Diffie-Hillman key defined in SEV spec. The PDH and session parameters 4618are used for establishing a cryptographic session with the guest owner to 4619negotiate keys used for attestation. The file must be encoded in base64. 4620 4621e.g to launch a SEV guest 4622@example 4623 # $QEMU \ 4624 ...... 4625 -object sev-guest,id=sev0,cbitpos=47,reduced-phys-bits=5 \ 4626 -machine ...,memory-encryption=sev0 4627 ..... 4628 4629@end example 4630 4631 4632@item -object authz-simple,id=@var{id},identity=@var{string} 4633 4634Create an authorization object that will control access to network services. 4635 4636The @option{identity} parameter is identifies the user and its format 4637depends on the network service that authorization object is associated 4638with. For authorizing based on TLS x509 certificates, the identity must 4639be the x509 distinguished name. Note that care must be taken to escape 4640any commas in the distinguished name. 4641 4642An example authorization object to validate a x509 distinguished name 4643would look like: 4644@example 4645 # $QEMU \ 4646 ... 4647 -object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,O=Example Org,,L=London,,ST=London,,C=GB' \ 4648 ... 4649@end example 4650 4651Note the use of quotes due to the x509 distinguished name containing 4652whitespace, and escaping of ','. 4653 4654@item -object authz-listfile,id=@var{id},filename=@var{path},refresh=@var{yes|no} 4655 4656Create an authorization object that will control access to network services. 4657 4658The @option{filename} parameter is the fully qualified path to a file 4659containing the access control list rules in JSON format. 4660 4661An example set of rules that match against SASL usernames might look 4662like: 4663 4664@example 4665 @{ 4666 "rules": [ 4667 @{ "match": "fred", "policy": "allow", "format": "exact" @}, 4668 @{ "match": "bob", "policy": "allow", "format": "exact" @}, 4669 @{ "match": "danb", "policy": "deny", "format": "glob" @}, 4670 @{ "match": "dan*", "policy": "allow", "format": "exact" @}, 4671 ], 4672 "policy": "deny" 4673 @} 4674@end example 4675 4676When checking access the object will iterate over all the rules and 4677the first rule to match will have its @option{policy} value returned 4678as the result. If no rules match, then the default @option{policy} 4679value is returned. 4680 4681The rules can either be an exact string match, or they can use the 4682simple UNIX glob pattern matching to allow wildcards to be used. 4683 4684If @option{refresh} is set to true the file will be monitored 4685and automatically reloaded whenever its content changes. 4686 4687As with the @code{authz-simple} object, the format of the identity 4688strings being matched depends on the network service, but is usually 4689a TLS x509 distinguished name, or a SASL username. 4690 4691An example authorization object to validate a SASL username 4692would look like: 4693@example 4694 # $QEMU \ 4695 ... 4696 -object authz-simple,id=auth0,filename=/etc/qemu/vnc-sasl.acl,refresh=yes 4697 ... 4698@end example 4699 4700@item -object authz-pam,id=@var{id},service=@var{string} 4701 4702Create an authorization object that will control access to network services. 4703 4704The @option{service} parameter provides the name of a PAM service to use 4705for authorization. It requires that a file @code{/etc/pam.d/@var{service}} 4706exist to provide the configuration for the @code{account} subsystem. 4707 4708An example authorization object to validate a TLS x509 distinguished 4709name would look like: 4710 4711@example 4712 # $QEMU \ 4713 ... 4714 -object authz-pam,id=auth0,service=qemu-vnc 4715 ... 4716@end example 4717 4718There would then be a corresponding config file for PAM at 4719@code{/etc/pam.d/qemu-vnc} that contains: 4720 4721@example 4722account requisite pam_listfile.so item=user sense=allow \ 4723 file=/etc/qemu/vnc.allow 4724@end example 4725 4726Finally the @code{/etc/qemu/vnc.allow} file would contain 4727the list of x509 distingished names that are permitted 4728access 4729 4730@example 4731CN=laptop.example.com,O=Example Home,L=London,ST=London,C=GB 4732@end example 4733 4734 4735@end table 4736 4737ETEXI 4738 4739 4740HXCOMM This is the last statement. Insert new options before this line! 4741STEXI 4742@end table 4743ETEXI 4744
