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