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