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