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