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