1HXCOMM Use DEFHEADING() to define headings in both help text and texi 2HXCOMM Text between STEXI and ETEXI are copied to texi version and 3HXCOMM discarded from C version 4HXCOMM DEF(option, HAS_ARG/0, opt_enum, opt_help, arch_mask) is used to 5HXCOMM construct option structures, enums and help message for specified 6HXCOMM architectures. 7HXCOMM HXCOMM can be used for comments, discarded from both texi and C 8 9DEFHEADING(Standard options:) 10STEXI 11@table @option 12ETEXI 13 14DEF("help", 0, QEMU_OPTION_h, 15 "-h or -help display this help and exit\n", QEMU_ARCH_ALL) 16STEXI 17@item -h 18@findex -h 19Display help and exit 20ETEXI 21 22DEF("version", 0, QEMU_OPTION_version, 23 "-version display version information and exit\n", QEMU_ARCH_ALL) 24STEXI 25@item -version 26@findex -version 27Display version information and exit 28ETEXI 29 30DEF("machine", HAS_ARG, QEMU_OPTION_machine, \ 31 "-machine [type=]name[,prop[=value][,...]]\n" 32 " selects emulated machine ('-machine help' for list)\n" 33 " property accel=accel1[:accel2[:...]] selects accelerator\n" 34 " supported accelerators are kvm, xen, tcg (default: tcg)\n" 35 " kernel_irqchip=on|off controls accelerated irqchip support\n" 36 " kvm_shadow_mem=size of KVM shadow MMU\n" 37 " dump-guest-core=on|off include guest memory in a core dump (default=on)\n" 38 " mem-merge=on|off controls memory merge support (default: on)\n", 39 QEMU_ARCH_ALL) 40STEXI 41@item -machine [type=]@var{name}[,prop=@var{value}[,...]] 42@findex -machine 43Select the emulated machine by @var{name}. Use @code{-machine help} to list 44available machines. Supported machine properties are: 45@table @option 46@item accel=@var{accels1}[:@var{accels2}[:...]] 47This is used to enable an accelerator. Depending on the target architecture, 48kvm, xen, or tcg can be available. By default, tcg is used. If there is more 49than one accelerator specified, the next one is used if the previous one fails 50to initialize. 51@item kernel_irqchip=on|off 52Enables in-kernel irqchip support for the chosen accelerator when available. 53@item kvm_shadow_mem=size 54Defines the size of the KVM shadow MMU. 55@item dump-guest-core=on|off 56Include guest memory in a core dump. The default is on. 57@item mem-merge=on|off 58Enables or disables memory merge support. This feature, when supported by 59the host, de-duplicates identical memory pages among VMs instances 60(enabled by default). 61@end table 62ETEXI 63 64HXCOMM Deprecated by -machine 65DEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL) 66 67DEF("cpu", HAS_ARG, QEMU_OPTION_cpu, 68 "-cpu cpu select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL) 69STEXI 70@item -cpu @var{model} 71@findex -cpu 72Select CPU model (@code{-cpu help} for list and additional feature selection) 73ETEXI 74 75DEF("smp", HAS_ARG, QEMU_OPTION_smp, 76 "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,sockets=sockets]\n" 77 " set the number of CPUs to 'n' [default=1]\n" 78 " maxcpus= maximum number of total cpus, including\n" 79 " offline CPUs for hotplug, etc\n" 80 " cores= number of CPU cores on one socket\n" 81 " threads= number of threads on one CPU core\n" 82 " sockets= number of discrete sockets in the system\n", 83 QEMU_ARCH_ALL) 84STEXI 85@item -smp [cpus=]@var{n}[,cores=@var{cores}][,threads=@var{threads}][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}] 86@findex -smp 87Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255 88CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs 89to 4. 90For the PC target, the number of @var{cores} per socket, the number 91of @var{threads} per cores and the total number of @var{sockets} can be 92specified. Missing values will be computed. If any on the three values is 93given, the total number of CPUs @var{n} can be omitted. @var{maxcpus} 94specifies the maximum number of hotpluggable CPUs. 95ETEXI 96 97DEF("numa", HAS_ARG, QEMU_OPTION_numa, 98 "-numa node[,mem=size][,cpus=cpu[-cpu]][,nodeid=node]\n", QEMU_ARCH_ALL) 99STEXI 100@item -numa @var{opts} 101@findex -numa 102Simulate a multi node NUMA system. If mem and cpus are omitted, resources 103are split equally. 104ETEXI 105 106DEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd, 107 "-add-fd fd=fd,set=set[,opaque=opaque]\n" 108 " Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL) 109STEXI 110@item -add-fd fd=@var{fd},set=@var{set}[,opaque=@var{opaque}] 111@findex -add-fd 112 113Add a file descriptor to an fd set. Valid options are: 114 115@table @option 116@item fd=@var{fd} 117This option defines the file descriptor of which a duplicate is added to fd set. 118The file descriptor cannot be stdin, stdout, or stderr. 119@item set=@var{set} 120This option defines the ID of the fd set to add the file descriptor to. 121@item opaque=@var{opaque} 122This option defines a free-form string that can be used to describe @var{fd}. 123@end table 124 125You can open an image using pre-opened file descriptors from an fd set: 126@example 127qemu-system-i386 128-add-fd fd=3,set=2,opaque="rdwr:/path/to/file" 129-add-fd fd=4,set=2,opaque="rdonly:/path/to/file" 130-drive file=/dev/fdset/2,index=0,media=disk 131@end example 132ETEXI 133 134DEF("set", HAS_ARG, QEMU_OPTION_set, 135 "-set group.id.arg=value\n" 136 " set <arg> parameter for item <id> of type <group>\n" 137 " i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL) 138STEXI 139@item -set @var{group}.@var{id}.@var{arg}=@var{value} 140@findex -set 141Set parameter @var{arg} for item @var{id} of type @var{group}\n" 142ETEXI 143 144DEF("global", HAS_ARG, QEMU_OPTION_global, 145 "-global driver.prop=value\n" 146 " set a global default for a driver property\n", 147 QEMU_ARCH_ALL) 148STEXI 149@item -global @var{driver}.@var{prop}=@var{value} 150@findex -global 151Set default value of @var{driver}'s property @var{prop} to @var{value}, e.g.: 152 153@example 154qemu-system-i386 -global ide-drive.physical_block_size=4096 -drive file=file,if=ide,index=0,media=disk 155@end example 156 157In particular, you can use this to set driver properties for devices which are 158created automatically by the machine model. To create a device which is not 159created automatically and set properties on it, use -@option{device}. 160ETEXI 161 162DEF("boot", HAS_ARG, QEMU_OPTION_boot, 163 "-boot [order=drives][,once=drives][,menu=on|off]\n" 164 " [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n" 165 " 'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n" 166 " 'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n" 167 " 'sp_time': the period that splash picture last if menu=on, unit is ms\n" 168 " 'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n", 169 QEMU_ARCH_ALL) 170STEXI 171@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] 172@findex -boot 173Specify boot order @var{drives} as a string of drive letters. Valid 174drive letters depend on the target achitecture. The x86 PC uses: a, b 175(floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p (Etherboot 176from network adapter 1-4), hard disk boot is the default. To apply a 177particular boot order only on the first startup, specify it via 178@option{once}. 179 180Interactive boot menus/prompts can be enabled via @option{menu=on} as far 181as firmware/BIOS supports them. The default is non-interactive boot. 182 183A splash picture could be passed to bios, enabling user to show it as logo, 184when option splash=@var{sp_name} is given and menu=on, If firmware/BIOS 185supports them. Currently Seabios for X86 system support it. 186limitation: The splash file could be a jpeg file or a BMP file in 24 BPP 187format(true color). The resolution should be supported by the SVGA mode, so 188the recommended is 320x240, 640x480, 800x640. 189 190A timeout could be passed to bios, guest will pause for @var{rb_timeout} ms 191when boot failed, then reboot. If @var{rb_timeout} is '-1', guest will not 192reboot, qemu passes '-1' to bios by default. Currently Seabios for X86 193system support it. 194 195Do strict boot via @option{strict=on} as far as firmware/BIOS 196supports it. This only effects when boot priority is changed by 197bootindex options. The default is non-strict boot. 198 199@example 200# try to boot from network first, then from hard disk 201qemu-system-i386 -boot order=nc 202# boot from CD-ROM first, switch back to default order after reboot 203qemu-system-i386 -boot once=d 204# boot with a splash picture for 5 seconds. 205qemu-system-i386 -boot menu=on,splash=/root/boot.bmp,splash-time=5000 206@end example 207 208Note: The legacy format '-boot @var{drives}' is still supported but its 209use is discouraged as it may be removed from future versions. 210ETEXI 211 212DEF("m", HAS_ARG, QEMU_OPTION_m, 213 "-m megs set virtual RAM size to megs MB [default=" 214 stringify(DEFAULT_RAM_SIZE) "]\n", QEMU_ARCH_ALL) 215STEXI 216@item -m @var{megs} 217@findex -m 218Set virtual RAM size to @var{megs} megabytes. Default is 128 MiB. Optionally, 219a suffix of ``M'' or ``G'' can be used to signify a value in megabytes or 220gigabytes respectively. 221ETEXI 222 223DEF("mem-path", HAS_ARG, QEMU_OPTION_mempath, 224 "-mem-path FILE provide backing storage for guest RAM\n", QEMU_ARCH_ALL) 225STEXI 226@item -mem-path @var{path} 227@findex -mem-path 228Allocate guest RAM from a temporarily created file in @var{path}. 229ETEXI 230 231DEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc, 232 "-mem-prealloc preallocate guest memory (use with -mem-path)\n", 233 QEMU_ARCH_ALL) 234STEXI 235@item -mem-prealloc 236@findex -mem-prealloc 237Preallocate memory when using -mem-path. 238ETEXI 239 240DEF("k", HAS_ARG, QEMU_OPTION_k, 241 "-k language use keyboard layout (for example 'fr' for French)\n", 242 QEMU_ARCH_ALL) 243STEXI 244@item -k @var{language} 245@findex -k 246Use keyboard layout @var{language} (for example @code{fr} for 247French). This option is only needed where it is not easy to get raw PC 248keycodes (e.g. on Macs, with some X11 servers or with a VNC 249display). You don't normally need to use it on PC/Linux or PC/Windows 250hosts. 251 252The available layouts are: 253@example 254ar de-ch es fo fr-ca hu ja mk no pt-br sv 255da en-gb et fr fr-ch is lt nl pl ru th 256de en-us fi fr-be hr it lv nl-be pt sl tr 257@end example 258 259The default is @code{en-us}. 260ETEXI 261 262 263DEF("audio-help", 0, QEMU_OPTION_audio_help, 264 "-audio-help print list of audio drivers and their options\n", 265 QEMU_ARCH_ALL) 266STEXI 267@item -audio-help 268@findex -audio-help 269Will show the audio subsystem help: list of drivers, tunable 270parameters. 271ETEXI 272 273DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw, 274 "-soundhw c1,... enable audio support\n" 275 " and only specified sound cards (comma separated list)\n" 276 " use '-soundhw help' to get the list of supported cards\n" 277 " use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL) 278STEXI 279@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all 280@findex -soundhw 281Enable audio and selected sound hardware. Use 'help' to print all 282available sound hardware. 283 284@example 285qemu-system-i386 -soundhw sb16,adlib disk.img 286qemu-system-i386 -soundhw es1370 disk.img 287qemu-system-i386 -soundhw ac97 disk.img 288qemu-system-i386 -soundhw hda disk.img 289qemu-system-i386 -soundhw all disk.img 290qemu-system-i386 -soundhw help 291@end example 292 293Note that Linux's i810_audio OSS kernel (for AC97) module might 294require manually specifying clocking. 295 296@example 297modprobe i810_audio clocking=48000 298@end example 299ETEXI 300 301DEF("balloon", HAS_ARG, QEMU_OPTION_balloon, 302 "-balloon none disable balloon device\n" 303 "-balloon virtio[,addr=str]\n" 304 " enable virtio balloon device (default)\n", QEMU_ARCH_ALL) 305STEXI 306@item -balloon none 307@findex -balloon 308Disable balloon device. 309@item -balloon virtio[,addr=@var{addr}] 310Enable virtio balloon device (default), optionally with PCI address 311@var{addr}. 312ETEXI 313 314DEF("device", HAS_ARG, QEMU_OPTION_device, 315 "-device driver[,prop[=value][,...]]\n" 316 " add device (based on driver)\n" 317 " prop=value,... sets driver properties\n" 318 " use '-device help' to print all possible drivers\n" 319 " use '-device driver,help' to print all possible properties\n", 320 QEMU_ARCH_ALL) 321STEXI 322@item -device @var{driver}[,@var{prop}[=@var{value}][,...]] 323@findex -device 324Add device @var{driver}. @var{prop}=@var{value} sets driver 325properties. Valid properties depend on the driver. To get help on 326possible drivers and properties, use @code{-device help} and 327@code{-device @var{driver},help}. 328ETEXI 329 330DEF("name", HAS_ARG, QEMU_OPTION_name, 331 "-name string1[,process=string2][,debug-threads=on|off]\n" 332 " set the name of the guest\n" 333 " string1 sets the window title and string2 the process name (on Linux)\n" 334 " When debug-threads is enabled, individual threads are given a separate name (on Linux)\n" 335 " NOTE: The thread names are for debugging and not a stable API.\n", 336 QEMU_ARCH_ALL) 337STEXI 338@item -name @var{name} 339@findex -name 340Sets the @var{name} of the guest. 341This name will be displayed in the SDL window caption. 342The @var{name} will also be used for the VNC server. 343Also optionally set the top visible process name in Linux. 344Naming of individual threads can also be enabled on Linux to aid debugging. 345ETEXI 346 347DEF("uuid", HAS_ARG, QEMU_OPTION_uuid, 348 "-uuid %08x-%04x-%04x-%04x-%012x\n" 349 " specify machine UUID\n", QEMU_ARCH_ALL) 350STEXI 351@item -uuid @var{uuid} 352@findex -uuid 353Set system UUID. 354ETEXI 355 356STEXI 357@end table 358ETEXI 359DEFHEADING() 360 361DEFHEADING(Block device options:) 362STEXI 363@table @option 364ETEXI 365 366DEF("fda", HAS_ARG, QEMU_OPTION_fda, 367 "-fda/-fdb file use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL) 368DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL) 369STEXI 370@item -fda @var{file} 371@item -fdb @var{file} 372@findex -fda 373@findex -fdb 374Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}). You can 375use the host floppy by using @file{/dev/fd0} as filename (@pxref{host_drives}). 376ETEXI 377 378DEF("hda", HAS_ARG, QEMU_OPTION_hda, 379 "-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL) 380DEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL) 381DEF("hdc", HAS_ARG, QEMU_OPTION_hdc, 382 "-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL) 383DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL) 384STEXI 385@item -hda @var{file} 386@item -hdb @var{file} 387@item -hdc @var{file} 388@item -hdd @var{file} 389@findex -hda 390@findex -hdb 391@findex -hdc 392@findex -hdd 393Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}). 394ETEXI 395 396DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom, 397 "-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n", 398 QEMU_ARCH_ALL) 399STEXI 400@item -cdrom @var{file} 401@findex -cdrom 402Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and 403@option{-cdrom} at the same time). You can use the host CD-ROM by 404using @file{/dev/cdrom} as filename (@pxref{host_drives}). 405ETEXI 406 407DEF("drive", HAS_ARG, QEMU_OPTION_drive, 408 "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n" 409 " [,cyls=c,heads=h,secs=s[,trans=t]][,snapshot=on|off]\n" 410 " [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n" 411 " [,serial=s][,addr=A][,id=name][,aio=threads|native]\n" 412 " [,readonly=on|off][,copy-on-read=on|off]\n" 413 " [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n" 414 " [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n" 415 " [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n" 416 " [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n" 417 " [[,iops_size=is]]\n" 418 " use 'file' as a drive image\n", QEMU_ARCH_ALL) 419STEXI 420@item -drive @var{option}[,@var{option}[,@var{option}[,...]]] 421@findex -drive 422 423Define a new drive. Valid options are: 424 425@table @option 426@item file=@var{file} 427This option defines which disk image (@pxref{disk_images}) to use with 428this drive. If the filename contains comma, you must double it 429(for instance, "file=my,,file" to use file "my,file"). 430 431Special files such as iSCSI devices can be specified using protocol 432specific URLs. See the section for "Device URL Syntax" for more information. 433@item if=@var{interface} 434This option defines on which type on interface the drive is connected. 435Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio. 436@item bus=@var{bus},unit=@var{unit} 437These options define where is connected the drive by defining the bus number and 438the unit id. 439@item index=@var{index} 440This option defines where is connected the drive by using an index in the list 441of available connectors of a given interface type. 442@item media=@var{media} 443This option defines the type of the media: disk or cdrom. 444@item cyls=@var{c},heads=@var{h},secs=@var{s}[,trans=@var{t}] 445These options have the same definition as they have in @option{-hdachs}. 446@item snapshot=@var{snapshot} 447@var{snapshot} is "on" or "off" and allows to enable snapshot for given drive (see @option{-snapshot}). 448@item cache=@var{cache} 449@var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough" and controls how the host cache is used to access block data. 450@item aio=@var{aio} 451@var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO. 452@item discard=@var{discard} 453@var{discard} is one of "ignore" (or "off") or "unmap" (or "on") and controls whether @dfn{discard} (also known as @dfn{trim} or @dfn{unmap}) requests are ignored or passed to the filesystem. Some machine types may not support discard requests. 454@item format=@var{format} 455Specify which disk @var{format} will be used rather than detecting 456the format. Can be used to specifiy format=raw to avoid interpreting 457an untrusted format header. 458@item serial=@var{serial} 459This option specifies the serial number to assign to the device. 460@item addr=@var{addr} 461Specify the controller's PCI address (if=virtio only). 462@item werror=@var{action},rerror=@var{action} 463Specify which @var{action} to take on write and read errors. Valid actions are: 464"ignore" (ignore the error and try to continue), "stop" (pause QEMU), 465"report" (report the error to the guest), "enospc" (pause QEMU only if the 466host disk is full; report the error to the guest otherwise). 467The default setting is @option{werror=enospc} and @option{rerror=report}. 468@item readonly 469Open drive @option{file} as read-only. Guest write attempts will fail. 470@item copy-on-read=@var{copy-on-read} 471@var{copy-on-read} is "on" or "off" and enables whether to copy read backing 472file sectors into the image file. 473@end table 474 475By default, the @option{cache=writeback} mode is used. It will report data 476writes as completed as soon as the data is present in the host page cache. 477This is safe as long as your guest OS makes sure to correctly flush disk caches 478where needed. If your guest OS does not handle volatile disk write caches 479correctly and your host crashes or loses power, then the guest may experience 480data corruption. 481 482For such guests, you should consider using @option{cache=writethrough}. This 483means that the host page cache will be used to read and write data, but write 484notification will be sent to the guest only after QEMU has made sure to flush 485each write to the disk. Be aware that this has a major impact on performance. 486 487The host page cache can be avoided entirely with @option{cache=none}. This will 488attempt to do disk IO directly to the guest's memory. QEMU may still perform 489an internal copy of the data. Note that this is considered a writeback mode and 490the guest OS must handle the disk write cache correctly in order to avoid data 491corruption on host crashes. 492 493The host page cache can be avoided while only sending write notifications to 494the guest when the data has been flushed to the disk using 495@option{cache=directsync}. 496 497In case you don't care about data integrity over host failures, use 498@option{cache=unsafe}. This option tells QEMU that it never needs to write any 499data to the disk but can instead keep things in cache. If anything goes wrong, 500like your host losing power, the disk storage getting disconnected accidentally, 501etc. your image will most probably be rendered unusable. When using 502the @option{-snapshot} option, unsafe caching is always used. 503 504Copy-on-read avoids accessing the same backing file sectors repeatedly and is 505useful when the backing file is over a slow network. By default copy-on-read 506is off. 507 508Instead of @option{-cdrom} you can use: 509@example 510qemu-system-i386 -drive file=file,index=2,media=cdrom 511@end example 512 513Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can 514use: 515@example 516qemu-system-i386 -drive file=file,index=0,media=disk 517qemu-system-i386 -drive file=file,index=1,media=disk 518qemu-system-i386 -drive file=file,index=2,media=disk 519qemu-system-i386 -drive file=file,index=3,media=disk 520@end example 521 522You can open an image using pre-opened file descriptors from an fd set: 523@example 524qemu-system-i386 525-add-fd fd=3,set=2,opaque="rdwr:/path/to/file" 526-add-fd fd=4,set=2,opaque="rdonly:/path/to/file" 527-drive file=/dev/fdset/2,index=0,media=disk 528@end example 529 530You can connect a CDROM to the slave of ide0: 531@example 532qemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom 533@end example 534 535If you don't specify the "file=" argument, you define an empty drive: 536@example 537qemu-system-i386 -drive if=ide,index=1,media=cdrom 538@end example 539 540You can connect a SCSI disk with unit ID 6 on the bus #0: 541@example 542qemu-system-i386 -drive file=file,if=scsi,bus=0,unit=6 543@end example 544 545Instead of @option{-fda}, @option{-fdb}, you can use: 546@example 547qemu-system-i386 -drive file=file,index=0,if=floppy 548qemu-system-i386 -drive file=file,index=1,if=floppy 549@end example 550 551By default, @var{interface} is "ide" and @var{index} is automatically 552incremented: 553@example 554qemu-system-i386 -drive file=a -drive file=b" 555@end example 556is interpreted like: 557@example 558qemu-system-i386 -hda a -hdb b 559@end example 560ETEXI 561 562DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock, 563 "-mtdblock file use 'file' as on-board Flash memory image\n", 564 QEMU_ARCH_ALL) 565STEXI 566@item -mtdblock @var{file} 567@findex -mtdblock 568Use @var{file} as on-board Flash memory image. 569ETEXI 570 571DEF("sd", HAS_ARG, QEMU_OPTION_sd, 572 "-sd file use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL) 573STEXI 574@item -sd @var{file} 575@findex -sd 576Use @var{file} as SecureDigital card image. 577ETEXI 578 579DEF("pflash", HAS_ARG, QEMU_OPTION_pflash, 580 "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL) 581STEXI 582@item -pflash @var{file} 583@findex -pflash 584Use @var{file} as a parallel flash image. 585ETEXI 586 587DEF("snapshot", 0, QEMU_OPTION_snapshot, 588 "-snapshot write to temporary files instead of disk image files\n", 589 QEMU_ARCH_ALL) 590STEXI 591@item -snapshot 592@findex -snapshot 593Write to temporary files instead of disk image files. In this case, 594the raw disk image you use is not written back. You can however force 595the write back by pressing @key{C-a s} (@pxref{disk_images}). 596ETEXI 597 598DEF("hdachs", HAS_ARG, QEMU_OPTION_hdachs, \ 599 "-hdachs c,h,s[,t]\n" \ 600 " force hard disk 0 physical geometry and the optional BIOS\n" \ 601 " translation (t=none or lba) (usually QEMU can guess them)\n", 602 QEMU_ARCH_ALL) 603STEXI 604@item -hdachs @var{c},@var{h},@var{s},[,@var{t}] 605@findex -hdachs 606Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <= 607@var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS 608translation mode (@var{t}=none, lba or auto). Usually QEMU can guess 609all those parameters. This option is useful for old MS-DOS disk 610images. 611ETEXI 612 613DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev, 614 "-fsdev fsdriver,id=id[,path=path,][security_model={mapped-xattr|mapped-file|passthrough|none}]\n" 615 " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd]\n", 616 QEMU_ARCH_ALL) 617 618STEXI 619 620@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}] 621@findex -fsdev 622Define a new file system device. Valid options are: 623@table @option 624@item @var{fsdriver} 625This option specifies the fs driver backend to use. 626Currently "local", "handle" and "proxy" file system drivers are supported. 627@item id=@var{id} 628Specifies identifier for this device 629@item path=@var{path} 630Specifies the export path for the file system device. Files under 631this path will be available to the 9p client on the guest. 632@item security_model=@var{security_model} 633Specifies the security model to be used for this export path. 634Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none". 635In "passthrough" security model, files are stored using the same 636credentials as they are created on the guest. This requires QEMU 637to run as root. In "mapped-xattr" security model, some of the file 638attributes like uid, gid, mode bits and link target are stored as 639file attributes. For "mapped-file" these attributes are stored in the 640hidden .virtfs_metadata directory. Directories exported by this security model cannot 641interact with other unix tools. "none" security model is same as 642passthrough except the sever won't report failures if it fails to 643set file attributes like ownership. Security model is mandatory 644only for local fsdriver. Other fsdrivers (like handle, proxy) don't take 645security model as a parameter. 646@item writeout=@var{writeout} 647This is an optional argument. The only supported value is "immediate". 648This means that host page cache will be used to read and write data but 649write notification will be sent to the guest only when the data has been 650reported as written by the storage subsystem. 651@item readonly 652Enables exporting 9p share as a readonly mount for guests. By default 653read-write access is given. 654@item socket=@var{socket} 655Enables proxy filesystem driver to use passed socket file for communicating 656with virtfs-proxy-helper 657@item sock_fd=@var{sock_fd} 658Enables proxy filesystem driver to use passed socket descriptor for 659communicating with virtfs-proxy-helper. Usually a helper like libvirt 660will create socketpair and pass one of the fds as sock_fd 661@end table 662 663-fsdev option is used along with -device driver "virtio-9p-pci". 664@item -device virtio-9p-pci,fsdev=@var{id},mount_tag=@var{mount_tag} 665Options for virtio-9p-pci driver are: 666@table @option 667@item fsdev=@var{id} 668Specifies the id value specified along with -fsdev option 669@item mount_tag=@var{mount_tag} 670Specifies the tag name to be used by the guest to mount this export point 671@end table 672 673ETEXI 674 675DEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs, 676 "-virtfs local,path=path,mount_tag=tag,security_model=[mapped-xattr|mapped-file|passthrough|none]\n" 677 " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd]\n", 678 QEMU_ARCH_ALL) 679 680STEXI 681 682@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}] 683@findex -virtfs 684 685The general form of a Virtual File system pass-through options are: 686@table @option 687@item @var{fsdriver} 688This option specifies the fs driver backend to use. 689Currently "local", "handle" and "proxy" file system drivers are supported. 690@item id=@var{id} 691Specifies identifier for this device 692@item path=@var{path} 693Specifies the export path for the file system device. Files under 694this path will be available to the 9p client on the guest. 695@item security_model=@var{security_model} 696Specifies the security model to be used for this export path. 697Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none". 698In "passthrough" security model, files are stored using the same 699credentials as they are created on the guest. This requires QEMU 700to run as root. In "mapped-xattr" security model, some of the file 701attributes like uid, gid, mode bits and link target are stored as 702file attributes. For "mapped-file" these attributes are stored in the 703hidden .virtfs_metadata directory. Directories exported by this security model cannot 704interact with other unix tools. "none" security model is same as 705passthrough except the sever won't report failures if it fails to 706set file attributes like ownership. Security model is mandatory only 707for local fsdriver. Other fsdrivers (like handle, proxy) don't take security 708model as a parameter. 709@item writeout=@var{writeout} 710This is an optional argument. The only supported value is "immediate". 711This means that host page cache will be used to read and write data but 712write notification will be sent to the guest only when the data has been 713reported as written by the storage subsystem. 714@item readonly 715Enables exporting 9p share as a readonly mount for guests. By default 716read-write access is given. 717@item socket=@var{socket} 718Enables proxy filesystem driver to use passed socket file for 719communicating with virtfs-proxy-helper. Usually a helper like libvirt 720will create socketpair and pass one of the fds as sock_fd 721@item sock_fd 722Enables proxy filesystem driver to use passed 'sock_fd' as the socket 723descriptor for interfacing with virtfs-proxy-helper 724@end table 725ETEXI 726 727DEF("virtfs_synth", 0, QEMU_OPTION_virtfs_synth, 728 "-virtfs_synth Create synthetic file system image\n", 729 QEMU_ARCH_ALL) 730STEXI 731@item -virtfs_synth 732@findex -virtfs_synth 733Create synthetic file system image 734ETEXI 735 736STEXI 737@end table 738ETEXI 739DEFHEADING() 740 741DEFHEADING(USB options:) 742STEXI 743@table @option 744ETEXI 745 746DEF("usb", 0, QEMU_OPTION_usb, 747 "-usb enable the USB driver (will be the default soon)\n", 748 QEMU_ARCH_ALL) 749STEXI 750@item -usb 751@findex -usb 752Enable the USB driver (will be the default soon) 753ETEXI 754 755DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice, 756 "-usbdevice name add the host or guest USB device 'name'\n", 757 QEMU_ARCH_ALL) 758STEXI 759 760@item -usbdevice @var{devname} 761@findex -usbdevice 762Add the USB device @var{devname}. @xref{usb_devices}. 763 764@table @option 765 766@item mouse 767Virtual Mouse. This will override the PS/2 mouse emulation when activated. 768 769@item tablet 770Pointer device that uses absolute coordinates (like a touchscreen). This 771means QEMU is able to report the mouse position without having to grab the 772mouse. Also overrides the PS/2 mouse emulation when activated. 773 774@item disk:[format=@var{format}]:@var{file} 775Mass storage device based on file. The optional @var{format} argument 776will be used rather than detecting the format. Can be used to specifiy 777@code{format=raw} to avoid interpreting an untrusted format header. 778 779@item host:@var{bus}.@var{addr} 780Pass through the host device identified by @var{bus}.@var{addr} (Linux only). 781 782@item host:@var{vendor_id}:@var{product_id} 783Pass through the host device identified by @var{vendor_id}:@var{product_id} 784(Linux only). 785 786@item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev} 787Serial converter to host character device @var{dev}, see @code{-serial} for the 788available devices. 789 790@item braille 791Braille device. This will use BrlAPI to display the braille output on a real 792or fake device. 793 794@item net:@var{options} 795Network adapter that supports CDC ethernet and RNDIS protocols. 796 797@end table 798ETEXI 799 800STEXI 801@end table 802ETEXI 803DEFHEADING() 804 805DEFHEADING(Display options:) 806STEXI 807@table @option 808ETEXI 809 810DEF("display", HAS_ARG, QEMU_OPTION_display, 811 "-display sdl[,frame=on|off][,alt_grab=on|off][,ctrl_grab=on|off]\n" 812 " [,window_close=on|off]|curses|none|\n" 813 " gtk[,grab_on_hover=on|off]|\n" 814 " vnc=<display>[,<optargs>]\n" 815 " select display type\n", QEMU_ARCH_ALL) 816STEXI 817@item -display @var{type} 818@findex -display 819Select type of display to use. This option is a replacement for the 820old style -sdl/-curses/... options. Valid values for @var{type} are 821@table @option 822@item sdl 823Display video output via SDL (usually in a separate graphics 824window; see the SDL documentation for other possibilities). 825@item curses 826Display video output via curses. For graphics device models which 827support a text mode, QEMU can display this output using a 828curses/ncurses interface. Nothing is displayed when the graphics 829device is in graphical mode or if the graphics device does not support 830a text mode. Generally only the VGA device models support text mode. 831@item none 832Do not display video output. The guest will still see an emulated 833graphics card, but its output will not be displayed to the QEMU 834user. This option differs from the -nographic option in that it 835only affects what is done with video output; -nographic also changes 836the destination of the serial and parallel port data. 837@item gtk 838Display video output in a GTK window. This interface provides drop-down 839menus and other UI elements to configure and control the VM during 840runtime. 841@item vnc 842Start a VNC server on display <arg> 843@end table 844ETEXI 845 846DEF("nographic", 0, QEMU_OPTION_nographic, 847 "-nographic disable graphical output and redirect serial I/Os to console\n", 848 QEMU_ARCH_ALL) 849STEXI 850@item -nographic 851@findex -nographic 852Normally, QEMU uses SDL to display the VGA output. With this option, 853you can totally disable graphical output so that QEMU is a simple 854command line application. The emulated serial port is redirected on 855the console and muxed with the monitor (unless redirected elsewhere 856explicitly). Therefore, you can still use QEMU to debug a Linux kernel 857with a serial console. Use @key{C-a h} for help on switching between 858the console and monitor. 859ETEXI 860 861DEF("curses", 0, QEMU_OPTION_curses, 862 "-curses use a curses/ncurses interface instead of SDL\n", 863 QEMU_ARCH_ALL) 864STEXI 865@item -curses 866@findex -curses 867Normally, QEMU uses SDL to display the VGA output. With this option, 868QEMU can display the VGA output when in text mode using a 869curses/ncurses interface. Nothing is displayed in graphical mode. 870ETEXI 871 872DEF("no-frame", 0, QEMU_OPTION_no_frame, 873 "-no-frame open SDL window without a frame and window decorations\n", 874 QEMU_ARCH_ALL) 875STEXI 876@item -no-frame 877@findex -no-frame 878Do not use decorations for SDL windows and start them using the whole 879available screen space. This makes the using QEMU in a dedicated desktop 880workspace more convenient. 881ETEXI 882 883DEF("alt-grab", 0, QEMU_OPTION_alt_grab, 884 "-alt-grab use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt)\n", 885 QEMU_ARCH_ALL) 886STEXI 887@item -alt-grab 888@findex -alt-grab 889Use Ctrl-Alt-Shift to grab mouse (instead of Ctrl-Alt). Note that this also 890affects the special keys (for fullscreen, monitor-mode switching, etc). 891ETEXI 892 893DEF("ctrl-grab", 0, QEMU_OPTION_ctrl_grab, 894 "-ctrl-grab use Right-Ctrl to grab mouse (instead of Ctrl-Alt)\n", 895 QEMU_ARCH_ALL) 896STEXI 897@item -ctrl-grab 898@findex -ctrl-grab 899Use Right-Ctrl to grab mouse (instead of Ctrl-Alt). Note that this also 900affects the special keys (for fullscreen, monitor-mode switching, etc). 901ETEXI 902 903DEF("no-quit", 0, QEMU_OPTION_no_quit, 904 "-no-quit disable SDL window close capability\n", QEMU_ARCH_ALL) 905STEXI 906@item -no-quit 907@findex -no-quit 908Disable SDL window close capability. 909ETEXI 910 911DEF("sdl", 0, QEMU_OPTION_sdl, 912 "-sdl enable SDL\n", QEMU_ARCH_ALL) 913STEXI 914@item -sdl 915@findex -sdl 916Enable SDL. 917ETEXI 918 919DEF("spice", HAS_ARG, QEMU_OPTION_spice, 920 "-spice [port=port][,tls-port=secured-port][,x509-dir=<dir>]\n" 921 " [,x509-key-file=<file>][,x509-key-password=<file>]\n" 922 " [,x509-cert-file=<file>][,x509-cacert-file=<file>]\n" 923 " [,x509-dh-key-file=<file>][,addr=addr][,ipv4|ipv6]\n" 924 " [,tls-ciphers=<list>]\n" 925 " [,tls-channel=[main|display|cursor|inputs|record|playback]]\n" 926 " [,plaintext-channel=[main|display|cursor|inputs|record|playback]]\n" 927 " [,sasl][,password=<secret>][,disable-ticketing]\n" 928 " [,image-compression=[auto_glz|auto_lz|quic|glz|lz|off]]\n" 929 " [,jpeg-wan-compression=[auto|never|always]]\n" 930 " [,zlib-glz-wan-compression=[auto|never|always]]\n" 931 " [,streaming-video=[off|all|filter]][,disable-copy-paste]\n" 932 " [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n" 933 " [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n" 934 " enable spice\n" 935 " at least one of {port, tls-port} is mandatory\n", 936 QEMU_ARCH_ALL) 937STEXI 938@item -spice @var{option}[,@var{option}[,...]] 939@findex -spice 940Enable the spice remote desktop protocol. Valid options are 941 942@table @option 943 944@item port=<nr> 945Set the TCP port spice is listening on for plaintext channels. 946 947@item addr=<addr> 948Set the IP address spice is listening on. Default is any address. 949 950@item ipv4 951@item ipv6 952Force using the specified IP version. 953 954@item password=<secret> 955Set the password you need to authenticate. 956 957@item sasl 958Require that the client use SASL to authenticate with the spice. 959The exact choice of authentication method used is controlled from the 960system / user's SASL configuration file for the 'qemu' service. This 961is typically found in /etc/sasl2/qemu.conf. If running QEMU as an 962unprivileged user, an environment variable SASL_CONF_PATH can be used 963to make it search alternate locations for the service config. 964While some SASL auth methods can also provide data encryption (eg GSSAPI), 965it is recommended that SASL always be combined with the 'tls' and 966'x509' settings to enable use of SSL and server certificates. This 967ensures a data encryption preventing compromise of authentication 968credentials. 969 970@item disable-ticketing 971Allow client connects without authentication. 972 973@item disable-copy-paste 974Disable copy paste between the client and the guest. 975 976@item disable-agent-file-xfer 977Disable spice-vdagent based file-xfer between the client and the guest. 978 979@item tls-port=<nr> 980Set the TCP port spice is listening on for encrypted channels. 981 982@item x509-dir=<dir> 983Set the x509 file directory. Expects same filenames as -vnc $display,x509=$dir 984 985@item x509-key-file=<file> 986@item x509-key-password=<file> 987@item x509-cert-file=<file> 988@item x509-cacert-file=<file> 989@item x509-dh-key-file=<file> 990The x509 file names can also be configured individually. 991 992@item tls-ciphers=<list> 993Specify which ciphers to use. 994 995@item tls-channel=[main|display|cursor|inputs|record|playback] 996@item plaintext-channel=[main|display|cursor|inputs|record|playback] 997Force specific channel to be used with or without TLS encryption. The 998options can be specified multiple times to configure multiple 999channels. The special name "default" can be used to set the default 1000mode. For channels which are not explicitly forced into one mode the 1001spice client is allowed to pick tls/plaintext as he pleases. 1002 1003@item image-compression=[auto_glz|auto_lz|quic|glz|lz|off] 1004Configure image compression (lossless). 1005Default is auto_glz. 1006 1007@item jpeg-wan-compression=[auto|never|always] 1008@item zlib-glz-wan-compression=[auto|never|always] 1009Configure wan image compression (lossy for slow links). 1010Default is auto. 1011 1012@item streaming-video=[off|all|filter] 1013Configure video stream detection. Default is filter. 1014 1015@item agent-mouse=[on|off] 1016Enable/disable passing mouse events via vdagent. Default is on. 1017 1018@item playback-compression=[on|off] 1019Enable/disable audio stream compression (using celt 0.5.1). Default is on. 1020 1021@item seamless-migration=[on|off] 1022Enable/disable spice seamless migration. Default is off. 1023 1024@end table 1025ETEXI 1026 1027DEF("portrait", 0, QEMU_OPTION_portrait, 1028 "-portrait rotate graphical output 90 deg left (only PXA LCD)\n", 1029 QEMU_ARCH_ALL) 1030STEXI 1031@item -portrait 1032@findex -portrait 1033Rotate graphical output 90 deg left (only PXA LCD). 1034ETEXI 1035 1036DEF("rotate", HAS_ARG, QEMU_OPTION_rotate, 1037 "-rotate <deg> rotate graphical output some deg left (only PXA LCD)\n", 1038 QEMU_ARCH_ALL) 1039STEXI 1040@item -rotate @var{deg} 1041@findex -rotate 1042Rotate graphical output some deg left (only PXA LCD). 1043ETEXI 1044 1045DEF("vga", HAS_ARG, QEMU_OPTION_vga, 1046 "-vga [std|cirrus|vmware|qxl|xenfb|tcx|cg3|none]\n" 1047 " select video card type\n", QEMU_ARCH_ALL) 1048STEXI 1049@item -vga @var{type} 1050@findex -vga 1051Select type of VGA card to emulate. Valid values for @var{type} are 1052@table @option 1053@item cirrus 1054Cirrus Logic GD5446 Video card. All Windows versions starting from 1055Windows 95 should recognize and use this graphic card. For optimal 1056performances, use 16 bit color depth in the guest and the host OS. 1057(This one is the default) 1058@item std 1059Standard VGA card with Bochs VBE extensions. If your guest OS 1060supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want 1061to use high resolution modes (>= 1280x1024x16) then you should use 1062this option. 1063@item vmware 1064VMWare SVGA-II compatible adapter. Use it if you have sufficiently 1065recent XFree86/XOrg server or Windows guest with a driver for this 1066card. 1067@item qxl 1068QXL paravirtual graphic card. It is VGA compatible (including VESA 10692.0 VBE support). Works best with qxl guest drivers installed though. 1070Recommended choice when using the spice protocol. 1071@item tcx 1072(sun4m only) Sun TCX framebuffer. This is the default framebuffer for 1073sun4m machines and offers both 8-bit and 24-bit colour depths at a 1074fixed resolution of 1024x768. 1075@item cg3 1076(sun4m only) Sun cgthree framebuffer. This is a simple 8-bit framebuffer 1077for sun4m machines available in both 1024x768 (OpenBIOS) and 1152x900 (OBP) 1078resolutions aimed at people wishing to run older Solaris versions. 1079@item none 1080Disable VGA card. 1081@end table 1082ETEXI 1083 1084DEF("full-screen", 0, QEMU_OPTION_full_screen, 1085 "-full-screen start in full screen\n", QEMU_ARCH_ALL) 1086STEXI 1087@item -full-screen 1088@findex -full-screen 1089Start in full screen. 1090ETEXI 1091 1092DEF("g", 1, QEMU_OPTION_g , 1093 "-g WxH[xDEPTH] Set the initial graphical resolution and depth\n", 1094 QEMU_ARCH_PPC | QEMU_ARCH_SPARC) 1095STEXI 1096@item -g @var{width}x@var{height}[x@var{depth}] 1097@findex -g 1098Set the initial graphical resolution and depth (PPC, SPARC only). 1099ETEXI 1100 1101DEF("vnc", HAS_ARG, QEMU_OPTION_vnc , 1102 "-vnc display start a VNC server on display\n", QEMU_ARCH_ALL) 1103STEXI 1104@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]] 1105@findex -vnc 1106Normally, QEMU uses SDL to display the VGA output. With this option, 1107you can have QEMU listen on VNC display @var{display} and redirect the VGA 1108display over the VNC session. It is very useful to enable the usb 1109tablet device when using this option (option @option{-usbdevice 1110tablet}). When using the VNC display, you must use the @option{-k} 1111parameter to set the keyboard layout if you are not using en-us. Valid 1112syntax for the @var{display} is 1113 1114@table @option 1115 1116@item @var{host}:@var{d} 1117 1118TCP connections will only be allowed from @var{host} on display @var{d}. 1119By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can 1120be omitted in which case the server will accept connections from any host. 1121 1122@item unix:@var{path} 1123 1124Connections will be allowed over UNIX domain sockets where @var{path} is the 1125location of a unix socket to listen for connections on. 1126 1127@item none 1128 1129VNC is initialized but not started. The monitor @code{change} command 1130can be used to later start the VNC server. 1131 1132@end table 1133 1134Following the @var{display} value there may be one or more @var{option} flags 1135separated by commas. Valid options are 1136 1137@table @option 1138 1139@item reverse 1140 1141Connect to a listening VNC client via a ``reverse'' connection. The 1142client is specified by the @var{display}. For reverse network 1143connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument 1144is a TCP port number, not a display number. 1145 1146@item websocket 1147 1148Opens an additional TCP listening port dedicated to VNC Websocket connections. 1149By definition the Websocket port is 5700+@var{display}. If @var{host} is 1150specified connections will only be allowed from this host. 1151As an alternative the Websocket port could be specified by using 1152@code{websocket}=@var{port}. 1153TLS encryption for the Websocket connection is supported if the required 1154certificates are specified with the VNC option @option{x509}. 1155 1156@item password 1157 1158Require that password based authentication is used for client connections. 1159 1160The password must be set separately using the @code{set_password} command in 1161the @ref{pcsys_monitor}. The syntax to change your password is: 1162@code{set_password <protocol> <password>} where <protocol> could be either 1163"vnc" or "spice". 1164 1165If you would like to change <protocol> password expiration, you should use 1166@code{expire_password <protocol> <expiration-time>} where expiration time could 1167be one of the following options: now, never, +seconds or UNIX time of 1168expiration, e.g. +60 to make password expire in 60 seconds, or 1335196800 1169to make password expire on "Mon Apr 23 12:00:00 EDT 2012" (UNIX time for this 1170date and time). 1171 1172You can also use keywords "now" or "never" for the expiration time to 1173allow <protocol> password to expire immediately or never expire. 1174 1175@item tls 1176 1177Require that client use TLS when communicating with the VNC server. This 1178uses anonymous TLS credentials so is susceptible to a man-in-the-middle 1179attack. It is recommended that this option be combined with either the 1180@option{x509} or @option{x509verify} options. 1181 1182@item x509=@var{/path/to/certificate/dir} 1183 1184Valid if @option{tls} is specified. Require that x509 credentials are used 1185for negotiating the TLS session. The server will send its x509 certificate 1186to the client. It is recommended that a password be set on the VNC server 1187to provide authentication of the client when this is used. The path following 1188this option specifies where the x509 certificates are to be loaded from. 1189See the @ref{vnc_security} section for details on generating certificates. 1190 1191@item x509verify=@var{/path/to/certificate/dir} 1192 1193Valid if @option{tls} is specified. Require that x509 credentials are used 1194for negotiating the TLS session. The server will send its x509 certificate 1195to the client, and request that the client send its own x509 certificate. 1196The server will validate the client's certificate against the CA certificate, 1197and reject clients when validation fails. If the certificate authority is 1198trusted, this is a sufficient authentication mechanism. You may still wish 1199to set a password on the VNC server as a second authentication layer. The 1200path following this option specifies where the x509 certificates are to 1201be loaded from. See the @ref{vnc_security} section for details on generating 1202certificates. 1203 1204@item sasl 1205 1206Require that the client use SASL to authenticate with the VNC server. 1207The exact choice of authentication method used is controlled from the 1208system / user's SASL configuration file for the 'qemu' service. This 1209is typically found in /etc/sasl2/qemu.conf. If running QEMU as an 1210unprivileged user, an environment variable SASL_CONF_PATH can be used 1211to make it search alternate locations for the service config. 1212While some SASL auth methods can also provide data encryption (eg GSSAPI), 1213it is recommended that SASL always be combined with the 'tls' and 1214'x509' settings to enable use of SSL and server certificates. This 1215ensures a data encryption preventing compromise of authentication 1216credentials. See the @ref{vnc_security} section for details on using 1217SASL authentication. 1218 1219@item acl 1220 1221Turn on access control lists for checking of the x509 client certificate 1222and SASL party. For x509 certs, the ACL check is made against the 1223certificate's distinguished name. This is something that looks like 1224@code{C=GB,O=ACME,L=Boston,CN=bob}. For SASL party, the ACL check is 1225made against the username, which depending on the SASL plugin, may 1226include a realm component, eg @code{bob} or @code{bob@@EXAMPLE.COM}. 1227When the @option{acl} flag is set, the initial access list will be 1228empty, with a @code{deny} policy. Thus no one will be allowed to 1229use the VNC server until the ACLs have been loaded. This can be 1230achieved using the @code{acl} monitor command. 1231 1232@item lossy 1233 1234Enable lossy compression methods (gradient, JPEG, ...). If this 1235option is set, VNC client may receive lossy framebuffer updates 1236depending on its encoding settings. Enabling this option can save 1237a lot of bandwidth at the expense of quality. 1238 1239@item non-adaptive 1240 1241Disable adaptive encodings. Adaptive encodings are enabled by default. 1242An adaptive encoding will try to detect frequently updated screen regions, 1243and send updates in these regions using a lossy encoding (like JPEG). 1244This can be really helpful to save bandwidth when playing videos. Disabling 1245adaptive encodings allows to restore the original static behavior of encodings 1246like Tight. 1247 1248@item share=[allow-exclusive|force-shared|ignore] 1249 1250Set display sharing policy. 'allow-exclusive' allows clients to ask 1251for exclusive access. As suggested by the rfb spec this is 1252implemented by dropping other connections. Connecting multiple 1253clients in parallel requires all clients asking for a shared session 1254(vncviewer: -shared switch). This is the default. 'force-shared' 1255disables exclusive client access. Useful for shared desktop sessions, 1256where you don't want someone forgetting specify -shared disconnect 1257everybody else. 'ignore' completely ignores the shared flag and 1258allows everybody connect unconditionally. Doesn't conform to the rfb 1259spec but is traditional QEMU behavior. 1260 1261@end table 1262ETEXI 1263 1264STEXI 1265@end table 1266ETEXI 1267ARCHHEADING(, QEMU_ARCH_I386) 1268 1269ARCHHEADING(i386 target only:, QEMU_ARCH_I386) 1270STEXI 1271@table @option 1272ETEXI 1273 1274DEF("win2k-hack", 0, QEMU_OPTION_win2k_hack, 1275 "-win2k-hack use it when installing Windows 2000 to avoid a disk full bug\n", 1276 QEMU_ARCH_I386) 1277STEXI 1278@item -win2k-hack 1279@findex -win2k-hack 1280Use it when installing Windows 2000 to avoid a disk full bug. After 1281Windows 2000 is installed, you no longer need this option (this option 1282slows down the IDE transfers). 1283ETEXI 1284 1285HXCOMM Deprecated by -rtc 1286DEF("rtc-td-hack", 0, QEMU_OPTION_rtc_td_hack, "", QEMU_ARCH_I386) 1287 1288DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk, 1289 "-no-fd-bootchk disable boot signature checking for floppy disks\n", 1290 QEMU_ARCH_I386) 1291STEXI 1292@item -no-fd-bootchk 1293@findex -no-fd-bootchk 1294Disable boot signature checking for floppy disks in BIOS. May 1295be needed to boot from old floppy disks. 1296ETEXI 1297 1298DEF("no-acpi", 0, QEMU_OPTION_no_acpi, 1299 "-no-acpi disable ACPI\n", QEMU_ARCH_I386) 1300STEXI 1301@item -no-acpi 1302@findex -no-acpi 1303Disable ACPI (Advanced Configuration and Power Interface) support. Use 1304it if your guest OS complains about ACPI problems (PC target machine 1305only). 1306ETEXI 1307 1308DEF("no-hpet", 0, QEMU_OPTION_no_hpet, 1309 "-no-hpet disable HPET\n", QEMU_ARCH_I386) 1310STEXI 1311@item -no-hpet 1312@findex -no-hpet 1313Disable HPET support. 1314ETEXI 1315 1316DEF("acpitable", HAS_ARG, QEMU_OPTION_acpitable, 1317 "-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" 1318 " ACPI table description\n", QEMU_ARCH_I386) 1319STEXI 1320@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}]...] 1321@findex -acpitable 1322Add ACPI table with specified header fields and context from specified files. 1323For file=, take whole ACPI table from the specified files, including all 1324ACPI headers (possible overridden by other options). 1325For data=, only data 1326portion of the table is used, all header information is specified in the 1327command line. 1328ETEXI 1329 1330DEF("smbios", HAS_ARG, QEMU_OPTION_smbios, 1331 "-smbios file=binary\n" 1332 " load SMBIOS entry from binary file\n" 1333 "-smbios type=0[,vendor=str][,version=str][,date=str][,release=%d.%d]\n" 1334 " specify SMBIOS type 0 fields\n" 1335 "-smbios type=1[,manufacturer=str][,product=str][,version=str][,serial=str]\n" 1336 " [,uuid=uuid][,sku=str][,family=str]\n" 1337 " specify SMBIOS type 1 fields\n", QEMU_ARCH_I386) 1338STEXI 1339@item -smbios file=@var{binary} 1340@findex -smbios 1341Load SMBIOS entry from binary file. 1342 1343@item -smbios type=0[,vendor=@var{str}][,version=@var{str}][,date=@var{str}][,release=@var{%d.%d}] 1344Specify SMBIOS type 0 fields 1345 1346@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}] 1347Specify SMBIOS type 1 fields 1348ETEXI 1349 1350STEXI 1351@end table 1352ETEXI 1353DEFHEADING() 1354 1355DEFHEADING(Network options:) 1356STEXI 1357@table @option 1358ETEXI 1359 1360HXCOMM Legacy slirp options (now moved to -net user): 1361#ifdef CONFIG_SLIRP 1362DEF("tftp", HAS_ARG, QEMU_OPTION_tftp, "", QEMU_ARCH_ALL) 1363DEF("bootp", HAS_ARG, QEMU_OPTION_bootp, "", QEMU_ARCH_ALL) 1364DEF("redir", HAS_ARG, QEMU_OPTION_redir, "", QEMU_ARCH_ALL) 1365#ifndef _WIN32 1366DEF("smb", HAS_ARG, QEMU_OPTION_smb, "", QEMU_ARCH_ALL) 1367#endif 1368#endif 1369 1370DEF("net", HAS_ARG, QEMU_OPTION_net, 1371 "-net nic[,vlan=n][,macaddr=mac][,model=type][,name=str][,addr=str][,vectors=v]\n" 1372 " create a new Network Interface Card and connect it to VLAN 'n'\n" 1373#ifdef CONFIG_SLIRP 1374 "-net user[,vlan=n][,name=str][,net=addr[/mask]][,host=addr][,restrict=on|off]\n" 1375 " [,hostname=host][,dhcpstart=addr][,dns=addr][,dnssearch=domain][,tftp=dir]\n" 1376 " [,bootfile=f][,hostfwd=rule][,guestfwd=rule]" 1377#ifndef _WIN32 1378 "[,smb=dir[,smbserver=addr]]\n" 1379#endif 1380 " connect the user mode network stack to VLAN 'n', configure its\n" 1381 " DHCP server and enabled optional services\n" 1382#endif 1383#ifdef _WIN32 1384 "-net tap[,vlan=n][,name=str],ifname=name\n" 1385 " connect the host TAP network interface to VLAN 'n'\n" 1386#else 1387 "-net tap[,vlan=n][,name=str][,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off][,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n" 1388 " connect the host TAP network interface to VLAN 'n'\n" 1389 " use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n" 1390 " to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n" 1391 " to deconfigure it\n" 1392 " use '[down]script=no' to disable script execution\n" 1393 " use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n" 1394 " configure it\n" 1395 " use 'fd=h' to connect to an already opened TAP interface\n" 1396 " use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n" 1397 " use 'sndbuf=nbytes' to limit the size of the send buffer (the\n" 1398 " default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n" 1399 " use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n" 1400 " use vnet_hdr=on to make the lack of IFF_VNET_HDR support an error condition\n" 1401 " use vhost=on to enable experimental in kernel accelerator\n" 1402 " (only has effect for virtio guests which use MSIX)\n" 1403 " use vhostforce=on to force vhost on for non-MSIX virtio guests\n" 1404 " use 'vhostfd=h' to connect to an already opened vhost net device\n" 1405 " use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n" 1406 " use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n" 1407 "-net bridge[,vlan=n][,name=str][,br=bridge][,helper=helper]\n" 1408 " connects a host TAP network interface to a host bridge device 'br'\n" 1409 " (default=" DEFAULT_BRIDGE_INTERFACE ") using the program 'helper'\n" 1410 " (default=" DEFAULT_BRIDGE_HELPER ")\n" 1411#endif 1412 "-net socket[,vlan=n][,name=str][,fd=h][,listen=[host]:port][,connect=host:port]\n" 1413 " connect the vlan 'n' to another VLAN using a socket connection\n" 1414 "-net socket[,vlan=n][,name=str][,fd=h][,mcast=maddr:port[,localaddr=addr]]\n" 1415 " connect the vlan 'n' to multicast maddr and port\n" 1416 " use 'localaddr=addr' to specify the host address to send packets from\n" 1417 "-net socket[,vlan=n][,name=str][,fd=h][,udp=host:port][,localaddr=host:port]\n" 1418 " connect the vlan 'n' to another VLAN using an UDP tunnel\n" 1419#ifdef CONFIG_VDE 1420 "-net vde[,vlan=n][,name=str][,sock=socketpath][,port=n][,group=groupname][,mode=octalmode]\n" 1421 " connect the vlan 'n' to port 'n' of a vde switch running\n" 1422 " on host and listening for incoming connections on 'socketpath'.\n" 1423 " Use group 'groupname' and mode 'octalmode' to change default\n" 1424 " ownership and permissions for communication port.\n" 1425#endif 1426#ifdef CONFIG_NETMAP 1427 "-net netmap,ifname=name[,devname=nmname]\n" 1428 " attach to the existing netmap-enabled network interface 'name', or to a\n" 1429 " VALE port (created on the fly) called 'name' ('nmname' is name of the \n" 1430 " netmap device, defaults to '/dev/netmap')\n" 1431#endif 1432 "-net dump[,vlan=n][,file=f][,len=n]\n" 1433 " dump traffic on vlan 'n' to file 'f' (max n bytes per packet)\n" 1434 "-net none use it alone to have zero network devices. If no -net option\n" 1435 " is provided, the default is '-net nic -net user'\n", QEMU_ARCH_ALL) 1436DEF("netdev", HAS_ARG, QEMU_OPTION_netdev, 1437 "-netdev [" 1438#ifdef CONFIG_SLIRP 1439 "user|" 1440#endif 1441 "tap|" 1442 "bridge|" 1443#ifdef CONFIG_VDE 1444 "vde|" 1445#endif 1446#ifdef CONFIG_NETMAP 1447 "netmap|" 1448#endif 1449 "socket|" 1450 "hubport],id=str[,option][,option][,...]\n", QEMU_ARCH_ALL) 1451STEXI 1452@item -net nic[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}] 1453@findex -net 1454Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n} 1455= 0 is the default). The NIC is an e1000 by default on the PC 1456target. Optionally, the MAC address can be changed to @var{mac}, the 1457device address set to @var{addr} (PCI cards only), 1458and a @var{name} can be assigned for use in monitor commands. 1459Optionally, for PCI cards, you can specify the number @var{v} of MSI-X vectors 1460that the card should have; this option currently only affects virtio cards; set 1461@var{v} = 0 to disable MSI-X. If no @option{-net} option is specified, a single 1462NIC is created. QEMU can emulate several different models of network card. 1463Valid values for @var{type} are 1464@code{virtio}, @code{i82551}, @code{i82557b}, @code{i82559er}, 1465@code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139}, 1466@code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}. 1467Not all devices are supported on all targets. Use @code{-net nic,model=help} 1468for a list of available devices for your target. 1469 1470@item -netdev user,id=@var{id}[,@var{option}][,@var{option}][,...] 1471@findex -netdev 1472@item -net user[,@var{option}][,@var{option}][,...] 1473Use the user mode network stack which requires no administrator 1474privilege to run. Valid options are: 1475 1476@table @option 1477@item vlan=@var{n} 1478Connect user mode stack to VLAN @var{n} (@var{n} = 0 is the default). 1479 1480@item id=@var{id} 1481@item name=@var{name} 1482Assign symbolic name for use in monitor commands. 1483 1484@item net=@var{addr}[/@var{mask}] 1485Set IP network address the guest will see. Optionally specify the netmask, 1486either in the form a.b.c.d or as number of valid top-most bits. Default is 148710.0.2.0/24. 1488 1489@item host=@var{addr} 1490Specify the guest-visible address of the host. Default is the 2nd IP in the 1491guest network, i.e. x.x.x.2. 1492 1493@item restrict=on|off 1494If this option is enabled, the guest will be isolated, i.e. it will not be 1495able to contact the host and no guest IP packets will be routed over the host 1496to the outside. This option does not affect any explicitly set forwarding rules. 1497 1498@item hostname=@var{name} 1499Specifies the client hostname reported by the built-in DHCP server. 1500 1501@item dhcpstart=@var{addr} 1502Specify the first of the 16 IPs the built-in DHCP server can assign. Default 1503is the 15th to 31st IP in the guest network, i.e. x.x.x.15 to x.x.x.31. 1504 1505@item dns=@var{addr} 1506Specify the guest-visible address of the virtual nameserver. The address must 1507be different from the host address. Default is the 3rd IP in the guest network, 1508i.e. x.x.x.3. 1509 1510@item dnssearch=@var{domain} 1511Provides an entry for the domain-search list sent by the built-in 1512DHCP server. More than one domain suffix can be transmitted by specifying 1513this option multiple times. If supported, this will cause the guest to 1514automatically try to append the given domain suffix(es) in case a domain name 1515can not be resolved. 1516 1517Example: 1518@example 1519qemu -net user,dnssearch=mgmt.example.org,dnssearch=example.org [...] 1520@end example 1521 1522@item tftp=@var{dir} 1523When using the user mode network stack, activate a built-in TFTP 1524server. The files in @var{dir} will be exposed as the root of a TFTP server. 1525The TFTP client on the guest must be configured in binary mode (use the command 1526@code{bin} of the Unix TFTP client). 1527 1528@item bootfile=@var{file} 1529When using the user mode network stack, broadcast @var{file} as the BOOTP 1530filename. In conjunction with @option{tftp}, this can be used to network boot 1531a guest from a local directory. 1532 1533Example (using pxelinux): 1534@example 1535qemu-system-i386 -hda linux.img -boot n -net user,tftp=/path/to/tftp/files,bootfile=/pxelinux.0 1536@end example 1537 1538@item smb=@var{dir}[,smbserver=@var{addr}] 1539When using the user mode network stack, activate a built-in SMB 1540server so that Windows OSes can access to the host files in @file{@var{dir}} 1541transparently. The IP address of the SMB server can be set to @var{addr}. By 1542default the 4th IP in the guest network is used, i.e. x.x.x.4. 1543 1544In the guest Windows OS, the line: 1545@example 154610.0.2.4 smbserver 1547@end example 1548must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me) 1549or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000). 1550 1551Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}. 1552 1553Note that a SAMBA server must be installed on the host OS. 1554QEMU was tested successfully with smbd versions from Red Hat 9, 1555Fedora Core 3 and OpenSUSE 11.x. 1556 1557@item hostfwd=[tcp|udp]:[@var{hostaddr}]:@var{hostport}-[@var{guestaddr}]:@var{guestport} 1558Redirect incoming TCP or UDP connections to the host port @var{hostport} to 1559the guest IP address @var{guestaddr} on guest port @var{guestport}. If 1560@var{guestaddr} is not specified, its value is x.x.x.15 (default first address 1561given by the built-in DHCP server). By specifying @var{hostaddr}, the rule can 1562be bound to a specific host interface. If no connection type is set, TCP is 1563used. This option can be given multiple times. 1564 1565For example, to redirect host X11 connection from screen 1 to guest 1566screen 0, use the following: 1567 1568@example 1569# on the host 1570qemu-system-i386 -net user,hostfwd=tcp:127.0.0.1:6001-:6000 [...] 1571# this host xterm should open in the guest X11 server 1572xterm -display :1 1573@end example 1574 1575To redirect telnet connections from host port 5555 to telnet port on 1576the guest, use the following: 1577 1578@example 1579# on the host 1580qemu-system-i386 -net user,hostfwd=tcp::5555-:23 [...] 1581telnet localhost 5555 1582@end example 1583 1584Then when you use on the host @code{telnet localhost 5555}, you 1585connect to the guest telnet server. 1586 1587@item guestfwd=[tcp]:@var{server}:@var{port}-@var{dev} 1588@item guestfwd=[tcp]:@var{server}:@var{port}-@var{cmd:command} 1589Forward guest TCP connections to the IP address @var{server} on port @var{port} 1590to the character device @var{dev} or to a program executed by @var{cmd:command} 1591which gets spawned for each connection. This option can be given multiple times. 1592 1593You can either use a chardev directly and have that one used throughout QEMU's 1594lifetime, like in the following example: 1595 1596@example 1597# open 10.10.1.1:4321 on bootup, connect 10.0.2.100:1234 to it whenever 1598# the guest accesses it 1599qemu -net user,guestfwd=tcp:10.0.2.100:1234-tcp:10.10.1.1:4321 [...] 1600@end example 1601 1602Or you can execute a command on every TCP connection established by the guest, 1603so that QEMU behaves similar to an inetd process for that virtual server: 1604 1605@example 1606# call "netcat 10.10.1.1 4321" on every TCP connection to 10.0.2.100:1234 1607# and connect the TCP stream to its stdin/stdout 1608qemu -net 'user,guestfwd=tcp:10.0.2.100:1234-cmd:netcat 10.10.1.1 4321' 1609@end example 1610 1611@end table 1612 1613Note: Legacy stand-alone options -tftp, -bootp, -smb and -redir are still 1614processed and applied to -net user. Mixing them with the new configuration 1615syntax gives undefined results. Their use for new applications is discouraged 1616as they will be removed from future versions. 1617 1618@item -netdev tap,id=@var{id}[,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,helper=@var{helper}] 1619@item -net tap[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}][,helper=@var{helper}] 1620Connect the host TAP network interface @var{name} to VLAN @var{n}. 1621 1622Use the network script @var{file} to configure it and the network script 1623@var{dfile} to deconfigure it. If @var{name} is not provided, the OS 1624automatically provides one. The default network configure script is 1625@file{/etc/qemu-ifup} and the default network deconfigure script is 1626@file{/etc/qemu-ifdown}. Use @option{script=no} or @option{downscript=no} 1627to disable script execution. 1628 1629If running QEMU as an unprivileged user, use the network helper 1630@var{helper} to configure the TAP interface. The default network 1631helper executable is @file{/path/to/qemu-bridge-helper}. 1632 1633@option{fd}=@var{h} can be used to specify the handle of an already 1634opened host TAP interface. 1635 1636Examples: 1637 1638@example 1639#launch a QEMU instance with the default network script 1640qemu-system-i386 linux.img -net nic -net tap 1641@end example 1642 1643@example 1644#launch a QEMU instance with two NICs, each one connected 1645#to a TAP device 1646qemu-system-i386 linux.img \ 1647 -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \ 1648 -net nic,vlan=1 -net tap,vlan=1,ifname=tap1 1649@end example 1650 1651@example 1652#launch a QEMU instance with the default network helper to 1653#connect a TAP device to bridge br0 1654qemu-system-i386 linux.img \ 1655 -net nic -net tap,"helper=/path/to/qemu-bridge-helper" 1656@end example 1657 1658@item -netdev bridge,id=@var{id}[,br=@var{bridge}][,helper=@var{helper}] 1659@item -net bridge[,vlan=@var{n}][,name=@var{name}][,br=@var{bridge}][,helper=@var{helper}] 1660Connect a host TAP network interface to a host bridge device. 1661 1662Use the network helper @var{helper} to configure the TAP interface and 1663attach it to the bridge. The default network helper executable is 1664@file{/path/to/qemu-bridge-helper} and the default bridge 1665device is @file{br0}. 1666 1667Examples: 1668 1669@example 1670#launch a QEMU instance with the default network helper to 1671#connect a TAP device to bridge br0 1672qemu-system-i386 linux.img -net bridge -net nic,model=virtio 1673@end example 1674 1675@example 1676#launch a QEMU instance with the default network helper to 1677#connect a TAP device to bridge qemubr0 1678qemu-system-i386 linux.img -net bridge,br=qemubr0 -net nic,model=virtio 1679@end example 1680 1681@item -netdev socket,id=@var{id}[,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}] 1682@item -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}] [,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}] 1683 1684Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual 1685machine using a TCP socket connection. If @option{listen} is 1686specified, QEMU waits for incoming connections on @var{port} 1687(@var{host} is optional). @option{connect} is used to connect to 1688another QEMU instance using the @option{listen} option. @option{fd}=@var{h} 1689specifies an already opened TCP socket. 1690 1691Example: 1692@example 1693# launch a first QEMU instance 1694qemu-system-i386 linux.img \ 1695 -net nic,macaddr=52:54:00:12:34:56 \ 1696 -net socket,listen=:1234 1697# connect the VLAN 0 of this instance to the VLAN 0 1698# of the first instance 1699qemu-system-i386 linux.img \ 1700 -net nic,macaddr=52:54:00:12:34:57 \ 1701 -net socket,connect=127.0.0.1:1234 1702@end example 1703 1704@item -netdev socket,id=@var{id}[,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]] 1705@item -net socket[,vlan=@var{n}][,name=@var{name}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}[,localaddr=@var{addr}]] 1706 1707Create a VLAN @var{n} shared with another QEMU virtual 1708machines using a UDP multicast socket, effectively making a bus for 1709every QEMU with same multicast address @var{maddr} and @var{port}. 1710NOTES: 1711@enumerate 1712@item 1713Several QEMU can be running on different hosts and share same bus (assuming 1714correct multicast setup for these hosts). 1715@item 1716mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see 1717@url{http://user-mode-linux.sf.net}. 1718@item 1719Use @option{fd=h} to specify an already opened UDP multicast socket. 1720@end enumerate 1721 1722Example: 1723@example 1724# launch one QEMU instance 1725qemu-system-i386 linux.img \ 1726 -net nic,macaddr=52:54:00:12:34:56 \ 1727 -net socket,mcast=230.0.0.1:1234 1728# launch another QEMU instance on same "bus" 1729qemu-system-i386 linux.img \ 1730 -net nic,macaddr=52:54:00:12:34:57 \ 1731 -net socket,mcast=230.0.0.1:1234 1732# launch yet another QEMU instance on same "bus" 1733qemu-system-i386 linux.img \ 1734 -net nic,macaddr=52:54:00:12:34:58 \ 1735 -net socket,mcast=230.0.0.1:1234 1736@end example 1737 1738Example (User Mode Linux compat.): 1739@example 1740# launch QEMU instance (note mcast address selected 1741# is UML's default) 1742qemu-system-i386 linux.img \ 1743 -net nic,macaddr=52:54:00:12:34:56 \ 1744 -net socket,mcast=239.192.168.1:1102 1745# launch UML 1746/path/to/linux ubd0=/path/to/root_fs eth0=mcast 1747@end example 1748 1749Example (send packets from host's 1.2.3.4): 1750@example 1751qemu-system-i386 linux.img \ 1752 -net nic,macaddr=52:54:00:12:34:56 \ 1753 -net socket,mcast=239.192.168.1:1102,localaddr=1.2.3.4 1754@end example 1755 1756@item -netdev vde,id=@var{id}[,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}] 1757@item -net vde[,vlan=@var{n}][,name=@var{name}][,sock=@var{socketpath}] [,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}] 1758Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and 1759listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname} 1760and MODE @var{octalmode} to change default ownership and permissions for 1761communication port. This option is only available if QEMU has been compiled 1762with vde support enabled. 1763 1764Example: 1765@example 1766# launch vde switch 1767vde_switch -F -sock /tmp/myswitch 1768# launch QEMU instance 1769qemu-system-i386 linux.img -net nic -net vde,sock=/tmp/myswitch 1770@end example 1771 1772@item -netdev hubport,id=@var{id},hubid=@var{hubid} 1773 1774Create a hub port on QEMU "vlan" @var{hubid}. 1775 1776The hubport netdev lets you connect a NIC to a QEMU "vlan" instead of a single 1777netdev. @code{-net} and @code{-device} with parameter @option{vlan} create the 1778required hub automatically. 1779 1780@item -net dump[,vlan=@var{n}][,file=@var{file}][,len=@var{len}] 1781Dump network traffic on VLAN @var{n} to file @var{file} (@file{qemu-vlan0.pcap} by default). 1782At most @var{len} bytes (64k by default) per packet are stored. The file format is 1783libpcap, so it can be analyzed with tools such as tcpdump or Wireshark. 1784 1785@item -net none 1786Indicate that no network devices should be configured. It is used to 1787override the default configuration (@option{-net nic -net user}) which 1788is activated if no @option{-net} options are provided. 1789ETEXI 1790 1791STEXI 1792@end table 1793ETEXI 1794DEFHEADING() 1795 1796DEFHEADING(Character device options:) 1797STEXI 1798 1799The general form of a character device option is: 1800@table @option 1801ETEXI 1802 1803DEF("chardev", HAS_ARG, QEMU_OPTION_chardev, 1804 "-chardev null,id=id[,mux=on|off]\n" 1805 "-chardev socket,id=id[,host=host],port=host[,to=to][,ipv4][,ipv6][,nodelay]\n" 1806 " [,server][,nowait][,telnet][,mux=on|off] (tcp)\n" 1807 "-chardev socket,id=id,path=path[,server][,nowait][,telnet],[mux=on|off] (unix)\n" 1808 "-chardev udp,id=id[,host=host],port=port[,localaddr=localaddr]\n" 1809 " [,localport=localport][,ipv4][,ipv6][,mux=on|off]\n" 1810 "-chardev msmouse,id=id[,mux=on|off]\n" 1811 "-chardev vc,id=id[[,width=width][,height=height]][[,cols=cols][,rows=rows]]\n" 1812 " [,mux=on|off]\n" 1813 "-chardev ringbuf,id=id[,size=size]\n" 1814 "-chardev file,id=id,path=path[,mux=on|off]\n" 1815 "-chardev pipe,id=id,path=path[,mux=on|off]\n" 1816#ifdef _WIN32 1817 "-chardev console,id=id[,mux=on|off]\n" 1818 "-chardev serial,id=id,path=path[,mux=on|off]\n" 1819#else 1820 "-chardev pty,id=id[,mux=on|off]\n" 1821 "-chardev stdio,id=id[,mux=on|off][,signal=on|off]\n" 1822#endif 1823#ifdef CONFIG_BRLAPI 1824 "-chardev braille,id=id[,mux=on|off]\n" 1825#endif 1826#if defined(__linux__) || defined(__sun__) || defined(__FreeBSD__) \ 1827 || defined(__NetBSD__) || defined(__OpenBSD__) || defined(__DragonFly__) 1828 "-chardev serial,id=id,path=path[,mux=on|off]\n" 1829 "-chardev tty,id=id,path=path[,mux=on|off]\n" 1830#endif 1831#if defined(__linux__) || defined(__FreeBSD__) || defined(__DragonFly__) 1832 "-chardev parallel,id=id,path=path[,mux=on|off]\n" 1833 "-chardev parport,id=id,path=path[,mux=on|off]\n" 1834#endif 1835#if defined(CONFIG_SPICE) 1836 "-chardev spicevmc,id=id,name=name[,debug=debug]\n" 1837 "-chardev spiceport,id=id,name=name[,debug=debug]\n" 1838#endif 1839 , QEMU_ARCH_ALL 1840) 1841 1842STEXI 1843@item -chardev @var{backend} ,id=@var{id} [,mux=on|off] [,@var{options}] 1844@findex -chardev 1845Backend is one of: 1846@option{null}, 1847@option{socket}, 1848@option{udp}, 1849@option{msmouse}, 1850@option{vc}, 1851@option{ringbuf}, 1852@option{file}, 1853@option{pipe}, 1854@option{console}, 1855@option{serial}, 1856@option{pty}, 1857@option{stdio}, 1858@option{braille}, 1859@option{tty}, 1860@option{parallel}, 1861@option{parport}, 1862@option{spicevmc}. 1863@option{spiceport}. 1864The specific backend will determine the applicable options. 1865 1866All devices must have an id, which can be any string up to 127 characters long. 1867It is used to uniquely identify this device in other command line directives. 1868 1869A character device may be used in multiplexing mode by multiple front-ends. 1870The key sequence of @key{Control-a} and @key{c} will rotate the input focus 1871between attached front-ends. Specify @option{mux=on} to enable this mode. 1872 1873Options to each backend are described below. 1874 1875@item -chardev null ,id=@var{id} 1876A void device. This device will not emit any data, and will drop any data it 1877receives. The null backend does not take any options. 1878 1879@item -chardev socket ,id=@var{id} [@var{TCP options} or @var{unix options}] [,server] [,nowait] [,telnet] 1880 1881Create a two-way stream socket, which can be either a TCP or a unix socket. A 1882unix socket will be created if @option{path} is specified. Behaviour is 1883undefined if TCP options are specified for a unix socket. 1884 1885@option{server} specifies that the socket shall be a listening socket. 1886 1887@option{nowait} specifies that QEMU should not block waiting for a client to 1888connect to a listening socket. 1889 1890@option{telnet} specifies that traffic on the socket should interpret telnet 1891escape sequences. 1892 1893TCP and unix socket options are given below: 1894 1895@table @option 1896 1897@item TCP options: port=@var{port} [,host=@var{host}] [,to=@var{to}] [,ipv4] [,ipv6] [,nodelay] 1898 1899@option{host} for a listening socket specifies the local address to be bound. 1900For a connecting socket species the remote host to connect to. @option{host} is 1901optional for listening sockets. If not specified it defaults to @code{0.0.0.0}. 1902 1903@option{port} for a listening socket specifies the local port to be bound. For a 1904connecting socket specifies the port on the remote host to connect to. 1905@option{port} can be given as either a port number or a service name. 1906@option{port} is required. 1907 1908@option{to} is only relevant to listening sockets. If it is specified, and 1909@option{port} cannot be bound, QEMU will attempt to bind to subsequent ports up 1910to and including @option{to} until it succeeds. @option{to} must be specified 1911as a port number. 1912 1913@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used. 1914If neither is specified the socket may use either protocol. 1915 1916@option{nodelay} disables the Nagle algorithm. 1917 1918@item unix options: path=@var{path} 1919 1920@option{path} specifies the local path of the unix socket. @option{path} is 1921required. 1922 1923@end table 1924 1925@item -chardev udp ,id=@var{id} [,host=@var{host}] ,port=@var{port} [,localaddr=@var{localaddr}] [,localport=@var{localport}] [,ipv4] [,ipv6] 1926 1927Sends all traffic from the guest to a remote host over UDP. 1928 1929@option{host} specifies the remote host to connect to. If not specified it 1930defaults to @code{localhost}. 1931 1932@option{port} specifies the port on the remote host to connect to. @option{port} 1933is required. 1934 1935@option{localaddr} specifies the local address to bind to. If not specified it 1936defaults to @code{0.0.0.0}. 1937 1938@option{localport} specifies the local port to bind to. If not specified any 1939available local port will be used. 1940 1941@option{ipv4} and @option{ipv6} specify that either IPv4 or IPv6 must be used. 1942If neither is specified the device may use either protocol. 1943 1944@item -chardev msmouse ,id=@var{id} 1945 1946Forward QEMU's emulated msmouse events to the guest. @option{msmouse} does not 1947take any options. 1948 1949@item -chardev vc ,id=@var{id} [[,width=@var{width}] [,height=@var{height}]] [[,cols=@var{cols}] [,rows=@var{rows}]] 1950 1951Connect to a QEMU text console. @option{vc} may optionally be given a specific 1952size. 1953 1954@option{width} and @option{height} specify the width and height respectively of 1955the console, in pixels. 1956 1957@option{cols} and @option{rows} specify that the console be sized to fit a text 1958console with the given dimensions. 1959 1960@item -chardev ringbuf ,id=@var{id} [,size=@var{size}] 1961 1962Create a ring buffer with fixed size @option{size}. 1963@var{size} must be a power of two, and defaults to @code{64K}). 1964 1965@item -chardev file ,id=@var{id} ,path=@var{path} 1966 1967Log all traffic received from the guest to a file. 1968 1969@option{path} specifies the path of the file to be opened. This file will be 1970created if it does not already exist, and overwritten if it does. @option{path} 1971is required. 1972 1973@item -chardev pipe ,id=@var{id} ,path=@var{path} 1974 1975Create a two-way connection to the guest. The behaviour differs slightly between 1976Windows hosts and other hosts: 1977 1978On Windows, a single duplex pipe will be created at 1979@file{\\.pipe\@option{path}}. 1980 1981On other hosts, 2 pipes will be created called @file{@option{path}.in} and 1982@file{@option{path}.out}. Data written to @file{@option{path}.in} will be 1983received by the guest. Data written by the guest can be read from 1984@file{@option{path}.out}. QEMU will not create these fifos, and requires them to 1985be present. 1986 1987@option{path} forms part of the pipe path as described above. @option{path} is 1988required. 1989 1990@item -chardev console ,id=@var{id} 1991 1992Send traffic from the guest to QEMU's standard output. @option{console} does not 1993take any options. 1994 1995@option{console} is only available on Windows hosts. 1996 1997@item -chardev serial ,id=@var{id} ,path=@option{path} 1998 1999Send traffic from the guest to a serial device on the host. 2000 2001On Unix hosts serial will actually accept any tty device, 2002not only serial lines. 2003 2004@option{path} specifies the name of the serial device to open. 2005 2006@item -chardev pty ,id=@var{id} 2007 2008Create a new pseudo-terminal on the host and connect to it. @option{pty} does 2009not take any options. 2010 2011@option{pty} is not available on Windows hosts. 2012 2013@item -chardev stdio ,id=@var{id} [,signal=on|off] 2014Connect to standard input and standard output of the QEMU process. 2015 2016@option{signal} controls if signals are enabled on the terminal, that includes 2017exiting QEMU with the key sequence @key{Control-c}. This option is enabled by 2018default, use @option{signal=off} to disable it. 2019 2020@option{stdio} is not available on Windows hosts. 2021 2022@item -chardev braille ,id=@var{id} 2023 2024Connect to a local BrlAPI server. @option{braille} does not take any options. 2025 2026@item -chardev tty ,id=@var{id} ,path=@var{path} 2027 2028@option{tty} is only available on Linux, Sun, FreeBSD, NetBSD, OpenBSD and 2029DragonFlyBSD hosts. It is an alias for @option{serial}. 2030 2031@option{path} specifies the path to the tty. @option{path} is required. 2032 2033@item -chardev parallel ,id=@var{id} ,path=@var{path} 2034@item -chardev parport ,id=@var{id} ,path=@var{path} 2035 2036@option{parallel} is only available on Linux, FreeBSD and DragonFlyBSD hosts. 2037 2038Connect to a local parallel port. 2039 2040@option{path} specifies the path to the parallel port device. @option{path} is 2041required. 2042 2043@item -chardev spicevmc ,id=@var{id} ,debug=@var{debug}, name=@var{name} 2044 2045@option{spicevmc} is only available when spice support is built in. 2046 2047@option{debug} debug level for spicevmc 2048 2049@option{name} name of spice channel to connect to 2050 2051Connect to a spice virtual machine channel, such as vdiport. 2052 2053@item -chardev spiceport ,id=@var{id} ,debug=@var{debug}, name=@var{name} 2054 2055@option{spiceport} is only available when spice support is built in. 2056 2057@option{debug} debug level for spicevmc 2058 2059@option{name} name of spice port to connect to 2060 2061Connect to a spice port, allowing a Spice client to handle the traffic 2062identified by a name (preferably a fqdn). 2063ETEXI 2064 2065STEXI 2066@end table 2067ETEXI 2068DEFHEADING() 2069 2070DEFHEADING(Device URL Syntax:) 2071STEXI 2072 2073In addition to using normal file images for the emulated storage devices, 2074QEMU can also use networked resources such as iSCSI devices. These are 2075specified using a special URL syntax. 2076 2077@table @option 2078@item iSCSI 2079iSCSI support allows QEMU to access iSCSI resources directly and use as 2080images for the guest storage. Both disk and cdrom images are supported. 2081 2082Syntax for specifying iSCSI LUNs is 2083``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>'' 2084 2085By default qemu will use the iSCSI initiator-name 2086'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from the command 2087line or a configuration file. 2088 2089 2090Example (without authentication): 2091@example 2092qemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \ 2093 -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \ 2094 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 2095@end example 2096 2097Example (CHAP username/password via URL): 2098@example 2099qemu-system-i386 -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1 2100@end example 2101 2102Example (CHAP username/password via environment variables): 2103@example 2104LIBISCSI_CHAP_USERNAME="user" \ 2105LIBISCSI_CHAP_PASSWORD="password" \ 2106qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 2107@end example 2108 2109iSCSI support is an optional feature of QEMU and only available when 2110compiled and linked against libiscsi. 2111ETEXI 2112DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi, 2113 "-iscsi [user=user][,password=password]\n" 2114 " [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n" 2115 " [,initiator-name=initiator-iqn][,id=target-iqn]\n" 2116 " iSCSI session parameters\n", QEMU_ARCH_ALL) 2117STEXI 2118 2119iSCSI parameters such as username and password can also be specified via 2120a configuration file. See qemu-doc for more information and examples. 2121 2122@item NBD 2123QEMU supports NBD (Network Block Devices) both using TCP protocol as well 2124as Unix Domain Sockets. 2125 2126Syntax for specifying a NBD device using TCP 2127``nbd:<server-ip>:<port>[:exportname=<export>]'' 2128 2129Syntax for specifying a NBD device using Unix Domain Sockets 2130``nbd:unix:<domain-socket>[:exportname=<export>]'' 2131 2132 2133Example for TCP 2134@example 2135qemu-system-i386 --drive file=nbd:192.0.2.1:30000 2136@end example 2137 2138Example for Unix Domain Sockets 2139@example 2140qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket 2141@end example 2142 2143@item SSH 2144QEMU supports SSH (Secure Shell) access to remote disks. 2145 2146Examples: 2147@example 2148qemu-system-i386 -drive file=ssh://user@@host/path/to/disk.img 2149qemu-system-i386 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img 2150@end example 2151 2152Currently authentication must be done using ssh-agent. Other 2153authentication methods may be supported in future. 2154 2155@item Sheepdog 2156Sheepdog is a distributed storage system for QEMU. 2157QEMU supports using either local sheepdog devices or remote networked 2158devices. 2159 2160Syntax for specifying a sheepdog device 2161@example 2162sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag] 2163@end example 2164 2165Example 2166@example 2167qemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine 2168@end example 2169 2170See also @url{http://http://www.osrg.net/sheepdog/}. 2171 2172@item GlusterFS 2173GlusterFS is an user space distributed file system. 2174QEMU supports the use of GlusterFS volumes for hosting VM disk images using 2175TCP, Unix Domain Sockets and RDMA transport protocols. 2176 2177Syntax for specifying a VM disk image on GlusterFS volume is 2178@example 2179gluster[+transport]://[server[:port]]/volname/image[?socket=...] 2180@end example 2181 2182 2183Example 2184@example 2185qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img 2186@end example 2187 2188See also @url{http://www.gluster.org}. 2189ETEXI 2190 2191STEXI 2192@end table 2193ETEXI 2194 2195DEFHEADING(Bluetooth(R) options:) 2196STEXI 2197@table @option 2198ETEXI 2199 2200DEF("bt", HAS_ARG, QEMU_OPTION_bt, \ 2201 "-bt hci,null dumb bluetooth HCI - doesn't respond to commands\n" \ 2202 "-bt hci,host[:id]\n" \ 2203 " use host's HCI with the given name\n" \ 2204 "-bt hci[,vlan=n]\n" \ 2205 " emulate a standard HCI in virtual scatternet 'n'\n" \ 2206 "-bt vhci[,vlan=n]\n" \ 2207 " add host computer to virtual scatternet 'n' using VHCI\n" \ 2208 "-bt device:dev[,vlan=n]\n" \ 2209 " emulate a bluetooth device 'dev' in scatternet 'n'\n", 2210 QEMU_ARCH_ALL) 2211STEXI 2212@item -bt hci[...] 2213@findex -bt 2214Defines the function of the corresponding Bluetooth HCI. -bt options 2215are matched with the HCIs present in the chosen machine type. For 2216example when emulating a machine with only one HCI built into it, only 2217the first @code{-bt hci[...]} option is valid and defines the HCI's 2218logic. The Transport Layer is decided by the machine type. Currently 2219the machines @code{n800} and @code{n810} have one HCI and all other 2220machines have none. 2221 2222@anchor{bt-hcis} 2223The following three types are recognized: 2224 2225@table @option 2226@item -bt hci,null 2227(default) The corresponding Bluetooth HCI assumes no internal logic 2228and will not respond to any HCI commands or emit events. 2229 2230@item -bt hci,host[:@var{id}] 2231(@code{bluez} only) The corresponding HCI passes commands / events 2232to / from the physical HCI identified by the name @var{id} (default: 2233@code{hci0}) on the computer running QEMU. Only available on @code{bluez} 2234capable systems like Linux. 2235 2236@item -bt hci[,vlan=@var{n}] 2237Add a virtual, standard HCI that will participate in the Bluetooth 2238scatternet @var{n} (default @code{0}). Similarly to @option{-net} 2239VLANs, devices inside a bluetooth network @var{n} can only communicate 2240with other devices in the same network (scatternet). 2241@end table 2242 2243@item -bt vhci[,vlan=@var{n}] 2244(Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached 2245to the host bluetooth stack instead of to the emulated target. This 2246allows the host and target machines to participate in a common scatternet 2247and communicate. Requires the Linux @code{vhci} driver installed. Can 2248be used as following: 2249 2250@example 2251qemu-system-i386 [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5 2252@end example 2253 2254@item -bt device:@var{dev}[,vlan=@var{n}] 2255Emulate a bluetooth device @var{dev} and place it in network @var{n} 2256(default @code{0}). QEMU can only emulate one type of bluetooth devices 2257currently: 2258 2259@table @option 2260@item keyboard 2261Virtual wireless keyboard implementing the HIDP bluetooth profile. 2262@end table 2263ETEXI 2264 2265STEXI 2266@end table 2267ETEXI 2268DEFHEADING() 2269 2270#ifdef CONFIG_TPM 2271DEFHEADING(TPM device options:) 2272 2273DEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \ 2274 "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n" 2275 " use path to provide path to a character device; default is /dev/tpm0\n" 2276 " use cancel-path to provide path to TPM's cancel sysfs entry; if\n" 2277 " not provided it will be searched for in /sys/class/misc/tpm?/device\n", 2278 QEMU_ARCH_ALL) 2279STEXI 2280 2281The general form of a TPM device option is: 2282@table @option 2283 2284@item -tpmdev @var{backend} ,id=@var{id} [,@var{options}] 2285@findex -tpmdev 2286Backend type must be: 2287@option{passthrough}. 2288 2289The specific backend type will determine the applicable options. 2290The @code{-tpmdev} option creates the TPM backend and requires a 2291@code{-device} option that specifies the TPM frontend interface model. 2292 2293Options to each backend are described below. 2294 2295Use 'help' to print all available TPM backend types. 2296@example 2297qemu -tpmdev help 2298@end example 2299 2300@item -tpmdev passthrough, id=@var{id}, path=@var{path}, cancel-path=@var{cancel-path} 2301 2302(Linux-host only) Enable access to the host's TPM using the passthrough 2303driver. 2304 2305@option{path} specifies the path to the host's TPM device, i.e., on 2306a Linux host this would be @code{/dev/tpm0}. 2307@option{path} is optional and by default @code{/dev/tpm0} is used. 2308 2309@option{cancel-path} specifies the path to the host TPM device's sysfs 2310entry allowing for cancellation of an ongoing TPM command. 2311@option{cancel-path} is optional and by default QEMU will search for the 2312sysfs entry to use. 2313 2314Some notes about using the host's TPM with the passthrough driver: 2315 2316The TPM device accessed by the passthrough driver must not be 2317used by any other application on the host. 2318 2319Since the host's firmware (BIOS/UEFI) has already initialized the TPM, 2320the VM's firmware (BIOS/UEFI) will not be able to initialize the 2321TPM again and may therefore not show a TPM-specific menu that would 2322otherwise allow the user to configure the TPM, e.g., allow the user to 2323enable/disable or activate/deactivate the TPM. 2324Further, if TPM ownership is released from within a VM then the host's TPM 2325will get disabled and deactivated. To enable and activate the 2326TPM again afterwards, the host has to be rebooted and the user is 2327required to enter the firmware's menu to enable and activate the TPM. 2328If the TPM is left disabled and/or deactivated most TPM commands will fail. 2329 2330To create a passthrough TPM use the following two options: 2331@example 2332-tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0 2333@end example 2334Note that the @code{-tpmdev} id is @code{tpm0} and is referenced by 2335@code{tpmdev=tpm0} in the device option. 2336 2337@end table 2338 2339ETEXI 2340 2341DEFHEADING() 2342 2343#endif 2344 2345DEFHEADING(Linux/Multiboot boot specific:) 2346STEXI 2347 2348When using these options, you can use a given Linux or Multiboot 2349kernel without installing it in the disk image. It can be useful 2350for easier testing of various kernels. 2351 2352@table @option 2353ETEXI 2354 2355DEF("kernel", HAS_ARG, QEMU_OPTION_kernel, \ 2356 "-kernel bzImage use 'bzImage' as kernel image\n", QEMU_ARCH_ALL) 2357STEXI 2358@item -kernel @var{bzImage} 2359@findex -kernel 2360Use @var{bzImage} as kernel image. The kernel can be either a Linux kernel 2361or in multiboot format. 2362ETEXI 2363 2364DEF("append", HAS_ARG, QEMU_OPTION_append, \ 2365 "-append cmdline use 'cmdline' as kernel command line\n", QEMU_ARCH_ALL) 2366STEXI 2367@item -append @var{cmdline} 2368@findex -append 2369Use @var{cmdline} as kernel command line 2370ETEXI 2371 2372DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \ 2373 "-initrd file use 'file' as initial ram disk\n", QEMU_ARCH_ALL) 2374STEXI 2375@item -initrd @var{file} 2376@findex -initrd 2377Use @var{file} as initial ram disk. 2378 2379@item -initrd "@var{file1} arg=foo,@var{file2}" 2380 2381This syntax is only available with multiboot. 2382 2383Use @var{file1} and @var{file2} as modules and pass arg=foo as parameter to the 2384first module. 2385ETEXI 2386 2387DEF("dtb", HAS_ARG, QEMU_OPTION_dtb, \ 2388 "-dtb file use 'file' as device tree image\n", QEMU_ARCH_ALL) 2389STEXI 2390@item -dtb @var{file} 2391@findex -dtb 2392Use @var{file} as a device tree binary (dtb) image and pass it to the kernel 2393on boot. 2394ETEXI 2395 2396STEXI 2397@end table 2398ETEXI 2399DEFHEADING() 2400 2401DEFHEADING(Debug/Expert options:) 2402STEXI 2403@table @option 2404ETEXI 2405 2406DEF("serial", HAS_ARG, QEMU_OPTION_serial, \ 2407 "-serial dev redirect the serial port to char device 'dev'\n", 2408 QEMU_ARCH_ALL) 2409STEXI 2410@item -serial @var{dev} 2411@findex -serial 2412Redirect the virtual serial port to host character device 2413@var{dev}. The default device is @code{vc} in graphical mode and 2414@code{stdio} in non graphical mode. 2415 2416This option can be used several times to simulate up to 4 serial 2417ports. 2418 2419Use @code{-serial none} to disable all serial ports. 2420 2421Available character devices are: 2422@table @option 2423@item vc[:@var{W}x@var{H}] 2424Virtual console. Optionally, a width and height can be given in pixel with 2425@example 2426vc:800x600 2427@end example 2428It is also possible to specify width or height in characters: 2429@example 2430vc:80Cx24C 2431@end example 2432@item pty 2433[Linux only] Pseudo TTY (a new PTY is automatically allocated) 2434@item none 2435No device is allocated. 2436@item null 2437void device 2438@item chardev:@var{id} 2439Use a named character device defined with the @code{-chardev} option. 2440@item /dev/XXX 2441[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port 2442parameters are set according to the emulated ones. 2443@item /dev/parport@var{N} 2444[Linux only, parallel port only] Use host parallel port 2445@var{N}. Currently SPP and EPP parallel port features can be used. 2446@item file:@var{filename} 2447Write output to @var{filename}. No character can be read. 2448@item stdio 2449[Unix only] standard input/output 2450@item pipe:@var{filename} 2451name pipe @var{filename} 2452@item COM@var{n} 2453[Windows only] Use host serial port @var{n} 2454@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}] 2455This implements UDP Net Console. 2456When @var{remote_host} or @var{src_ip} are not specified 2457they default to @code{0.0.0.0}. 2458When not using a specified @var{src_port} a random port is automatically chosen. 2459 2460If you just want a simple readonly console you can use @code{netcat} or 2461@code{nc}, by starting QEMU with: @code{-serial udp::4555} and nc as: 2462@code{nc -u -l -p 4555}. Any time QEMU writes something to that port it 2463will appear in the netconsole session. 2464 2465If you plan to send characters back via netconsole or you want to stop 2466and start QEMU a lot of times, you should have QEMU use the same 2467source port each time by using something like @code{-serial 2468udp::4555@@:4556} to QEMU. Another approach is to use a patched 2469version of netcat which can listen to a TCP port and send and receive 2470characters via udp. If you have a patched version of netcat which 2471activates telnet remote echo and single char transfer, then you can 2472use the following options to step up a netcat redirector to allow 2473telnet on port 5555 to access the QEMU port. 2474@table @code 2475@item QEMU Options: 2476-serial udp::4555@@:4556 2477@item netcat options: 2478-u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T 2479@item telnet options: 2480localhost 5555 2481@end table 2482 2483@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay] 2484The TCP Net Console has two modes of operation. It can send the serial 2485I/O to a location or wait for a connection from a location. By default 2486the TCP Net Console is sent to @var{host} at the @var{port}. If you use 2487the @var{server} option QEMU will wait for a client socket application 2488to connect to the port before continuing, unless the @code{nowait} 2489option was specified. The @code{nodelay} option disables the Nagle buffering 2490algorithm. If @var{host} is omitted, 0.0.0.0 is assumed. Only 2491one TCP connection at a time is accepted. You can use @code{telnet} to 2492connect to the corresponding character device. 2493@table @code 2494@item Example to send tcp console to 192.168.0.2 port 4444 2495-serial tcp:192.168.0.2:4444 2496@item Example to listen and wait on port 4444 for connection 2497-serial tcp::4444,server 2498@item Example to not wait and listen on ip 192.168.0.100 port 4444 2499-serial tcp:192.168.0.100:4444,server,nowait 2500@end table 2501 2502@item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay] 2503The telnet protocol is used instead of raw tcp sockets. The options 2504work the same as if you had specified @code{-serial tcp}. The 2505difference is that the port acts like a telnet server or client using 2506telnet option negotiation. This will also allow you to send the 2507MAGIC_SYSRQ sequence if you use a telnet that supports sending the break 2508sequence. Typically in unix telnet you do it with Control-] and then 2509type "send break" followed by pressing the enter key. 2510 2511@item unix:@var{path}[,server][,nowait] 2512A unix domain socket is used instead of a tcp socket. The option works the 2513same as if you had specified @code{-serial tcp} except the unix domain socket 2514@var{path} is used for connections. 2515 2516@item mon:@var{dev_string} 2517This is a special option to allow the monitor to be multiplexed onto 2518another serial port. The monitor is accessed with key sequence of 2519@key{Control-a} and then pressing @key{c}. 2520@var{dev_string} should be any one of the serial devices specified 2521above. An example to multiplex the monitor onto a telnet server 2522listening on port 4444 would be: 2523@table @code 2524@item -serial mon:telnet::4444,server,nowait 2525@end table 2526When the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate 2527QEMU any more but will be passed to the guest instead. 2528 2529@item braille 2530Braille device. This will use BrlAPI to display the braille output on a real 2531or fake device. 2532 2533@item msmouse 2534Three button serial mouse. Configure the guest to use Microsoft protocol. 2535@end table 2536ETEXI 2537 2538DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, \ 2539 "-parallel dev redirect the parallel port to char device 'dev'\n", 2540 QEMU_ARCH_ALL) 2541STEXI 2542@item -parallel @var{dev} 2543@findex -parallel 2544Redirect the virtual parallel port to host device @var{dev} (same 2545devices as the serial port). On Linux hosts, @file{/dev/parportN} can 2546be used to use hardware devices connected on the corresponding host 2547parallel port. 2548 2549This option can be used several times to simulate up to 3 parallel 2550ports. 2551 2552Use @code{-parallel none} to disable all parallel ports. 2553ETEXI 2554 2555DEF("monitor", HAS_ARG, QEMU_OPTION_monitor, \ 2556 "-monitor dev redirect the monitor to char device 'dev'\n", 2557 QEMU_ARCH_ALL) 2558STEXI 2559@item -monitor @var{dev} 2560@findex -monitor 2561Redirect the monitor to host device @var{dev} (same devices as the 2562serial port). 2563The default device is @code{vc} in graphical mode and @code{stdio} in 2564non graphical mode. 2565Use @code{-monitor none} to disable the default monitor. 2566ETEXI 2567DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \ 2568 "-qmp dev like -monitor but opens in 'control' mode\n", 2569 QEMU_ARCH_ALL) 2570STEXI 2571@item -qmp @var{dev} 2572@findex -qmp 2573Like -monitor but opens in 'control' mode. 2574ETEXI 2575 2576DEF("mon", HAS_ARG, QEMU_OPTION_mon, \ 2577 "-mon [chardev=]name[,mode=readline|control][,default]\n", QEMU_ARCH_ALL) 2578STEXI 2579@item -mon [chardev=]name[,mode=readline|control][,default] 2580@findex -mon 2581Setup monitor on chardev @var{name}. 2582ETEXI 2583 2584DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \ 2585 "-debugcon dev redirect the debug console to char device 'dev'\n", 2586 QEMU_ARCH_ALL) 2587STEXI 2588@item -debugcon @var{dev} 2589@findex -debugcon 2590Redirect the debug console to host device @var{dev} (same devices as the 2591serial port). The debug console is an I/O port which is typically port 25920xe9; writing to that I/O port sends output to this device. 2593The default device is @code{vc} in graphical mode and @code{stdio} in 2594non graphical mode. 2595ETEXI 2596 2597DEF("pidfile", HAS_ARG, QEMU_OPTION_pidfile, \ 2598 "-pidfile file write PID to 'file'\n", QEMU_ARCH_ALL) 2599STEXI 2600@item -pidfile @var{file} 2601@findex -pidfile 2602Store the QEMU process PID in @var{file}. It is useful if you launch QEMU 2603from a script. 2604ETEXI 2605 2606DEF("singlestep", 0, QEMU_OPTION_singlestep, \ 2607 "-singlestep always run in singlestep mode\n", QEMU_ARCH_ALL) 2608STEXI 2609@item -singlestep 2610@findex -singlestep 2611Run the emulation in single step mode. 2612ETEXI 2613 2614DEF("S", 0, QEMU_OPTION_S, \ 2615 "-S freeze CPU at startup (use 'c' to start execution)\n", 2616 QEMU_ARCH_ALL) 2617STEXI 2618@item -S 2619@findex -S 2620Do not start CPU at startup (you must type 'c' in the monitor). 2621ETEXI 2622 2623DEF("realtime", HAS_ARG, QEMU_OPTION_realtime, 2624 "-realtime [mlock=on|off]\n" 2625 " run qemu with realtime features\n" 2626 " mlock=on|off controls mlock support (default: on)\n", 2627 QEMU_ARCH_ALL) 2628STEXI 2629@item -realtime mlock=on|off 2630@findex -realtime 2631Run qemu with realtime features. 2632mlocking qemu and guest memory can be enabled via @option{mlock=on} 2633(enabled by default). 2634ETEXI 2635 2636DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \ 2637 "-gdb dev wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL) 2638STEXI 2639@item -gdb @var{dev} 2640@findex -gdb 2641Wait for gdb connection on device @var{dev} (@pxref{gdb_usage}). Typical 2642connections will likely be TCP-based, but also UDP, pseudo TTY, or even 2643stdio are reasonable use case. The latter is allowing to start QEMU from 2644within gdb and establish the connection via a pipe: 2645@example 2646(gdb) target remote | exec qemu-system-i386 -gdb stdio ... 2647@end example 2648ETEXI 2649 2650DEF("s", 0, QEMU_OPTION_s, \ 2651 "-s shorthand for -gdb tcp::" DEFAULT_GDBSTUB_PORT "\n", 2652 QEMU_ARCH_ALL) 2653STEXI 2654@item -s 2655@findex -s 2656Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234 2657(@pxref{gdb_usage}). 2658ETEXI 2659 2660DEF("d", HAS_ARG, QEMU_OPTION_d, \ 2661 "-d item1,... enable logging of specified items (use '-d help' for a list of log items)\n", 2662 QEMU_ARCH_ALL) 2663STEXI 2664@item -d @var{item1}[,...] 2665@findex -d 2666Enable logging of specified items. Use '-d help' for a list of log items. 2667ETEXI 2668 2669DEF("D", HAS_ARG, QEMU_OPTION_D, \ 2670 "-D logfile output log to logfile (default stderr)\n", 2671 QEMU_ARCH_ALL) 2672STEXI 2673@item -D @var{logfile} 2674@findex -D 2675Output log in @var{logfile} instead of to stderr 2676ETEXI 2677 2678DEF("L", HAS_ARG, QEMU_OPTION_L, \ 2679 "-L path set the directory for the BIOS, VGA BIOS and keymaps\n", 2680 QEMU_ARCH_ALL) 2681STEXI 2682@item -L @var{path} 2683@findex -L 2684Set the directory for the BIOS, VGA BIOS and keymaps. 2685ETEXI 2686 2687DEF("bios", HAS_ARG, QEMU_OPTION_bios, \ 2688 "-bios file set the filename for the BIOS\n", QEMU_ARCH_ALL) 2689STEXI 2690@item -bios @var{file} 2691@findex -bios 2692Set the filename for the BIOS. 2693ETEXI 2694 2695DEF("enable-kvm", 0, QEMU_OPTION_enable_kvm, \ 2696 "-enable-kvm enable KVM full virtualization support\n", QEMU_ARCH_ALL) 2697STEXI 2698@item -enable-kvm 2699@findex -enable-kvm 2700Enable KVM full virtualization support. This option is only available 2701if KVM support is enabled when compiling. 2702ETEXI 2703 2704DEF("xen-domid", HAS_ARG, QEMU_OPTION_xen_domid, 2705 "-xen-domid id specify xen guest domain id\n", QEMU_ARCH_ALL) 2706DEF("xen-create", 0, QEMU_OPTION_xen_create, 2707 "-xen-create create domain using xen hypercalls, bypassing xend\n" 2708 " warning: should not be used when xend is in use\n", 2709 QEMU_ARCH_ALL) 2710DEF("xen-attach", 0, QEMU_OPTION_xen_attach, 2711 "-xen-attach attach to existing xen domain\n" 2712 " xend will use this when starting QEMU\n", 2713 QEMU_ARCH_ALL) 2714STEXI 2715@item -xen-domid @var{id} 2716@findex -xen-domid 2717Specify xen guest domain @var{id} (XEN only). 2718@item -xen-create 2719@findex -xen-create 2720Create domain using xen hypercalls, bypassing xend. 2721Warning: should not be used when xend is in use (XEN only). 2722@item -xen-attach 2723@findex -xen-attach 2724Attach to existing xen domain. 2725xend will use this when starting QEMU (XEN only). 2726ETEXI 2727 2728DEF("no-reboot", 0, QEMU_OPTION_no_reboot, \ 2729 "-no-reboot exit instead of rebooting\n", QEMU_ARCH_ALL) 2730STEXI 2731@item -no-reboot 2732@findex -no-reboot 2733Exit instead of rebooting. 2734ETEXI 2735 2736DEF("no-shutdown", 0, QEMU_OPTION_no_shutdown, \ 2737 "-no-shutdown stop before shutdown\n", QEMU_ARCH_ALL) 2738STEXI 2739@item -no-shutdown 2740@findex -no-shutdown 2741Don't exit QEMU on guest shutdown, but instead only stop the emulation. 2742This allows for instance switching to monitor to commit changes to the 2743disk image. 2744ETEXI 2745 2746DEF("loadvm", HAS_ARG, QEMU_OPTION_loadvm, \ 2747 "-loadvm [tag|id]\n" \ 2748 " start right away with a saved state (loadvm in monitor)\n", 2749 QEMU_ARCH_ALL) 2750STEXI 2751@item -loadvm @var{file} 2752@findex -loadvm 2753Start right away with a saved state (@code{loadvm} in monitor) 2754ETEXI 2755 2756#ifndef _WIN32 2757DEF("daemonize", 0, QEMU_OPTION_daemonize, \ 2758 "-daemonize daemonize QEMU after initializing\n", QEMU_ARCH_ALL) 2759#endif 2760STEXI 2761@item -daemonize 2762@findex -daemonize 2763Daemonize the QEMU process after initialization. QEMU will not detach from 2764standard IO until it is ready to receive connections on any of its devices. 2765This option is a useful way for external programs to launch QEMU without having 2766to cope with initialization race conditions. 2767ETEXI 2768 2769DEF("option-rom", HAS_ARG, QEMU_OPTION_option_rom, \ 2770 "-option-rom rom load a file, rom, into the option ROM space\n", 2771 QEMU_ARCH_ALL) 2772STEXI 2773@item -option-rom @var{file} 2774@findex -option-rom 2775Load the contents of @var{file} as an option ROM. 2776This option is useful to load things like EtherBoot. 2777ETEXI 2778 2779DEF("clock", HAS_ARG, QEMU_OPTION_clock, \ 2780 "-clock force the use of the given methods for timer alarm.\n" \ 2781 " To see what timers are available use '-clock help'\n", 2782 QEMU_ARCH_ALL) 2783STEXI 2784@item -clock @var{method} 2785@findex -clock 2786Force the use of the given methods for timer alarm. To see what timers 2787are available use @code{-clock help}. 2788ETEXI 2789 2790HXCOMM Options deprecated by -rtc 2791DEF("localtime", 0, QEMU_OPTION_localtime, "", QEMU_ARCH_ALL) 2792DEF("startdate", HAS_ARG, QEMU_OPTION_startdate, "", QEMU_ARCH_ALL) 2793 2794DEF("rtc", HAS_ARG, QEMU_OPTION_rtc, \ 2795 "-rtc [base=utc|localtime|date][,clock=host|rt|vm][,driftfix=none|slew]\n" \ 2796 " set the RTC base and clock, enable drift fix for clock ticks (x86 only)\n", 2797 QEMU_ARCH_ALL) 2798 2799STEXI 2800 2801@item -rtc [base=utc|localtime|@var{date}][,clock=host|vm][,driftfix=none|slew] 2802@findex -rtc 2803Specify @option{base} as @code{utc} or @code{localtime} to let the RTC start at the current 2804UTC or local time, respectively. @code{localtime} is required for correct date in 2805MS-DOS or Windows. To start at a specific point in time, provide @var{date} in the 2806format @code{2006-06-17T16:01:21} or @code{2006-06-17}. The default base is UTC. 2807 2808By default the RTC is driven by the host system time. This allows to use the 2809RTC as accurate reference clock inside the guest, specifically if the host 2810time is smoothly following an accurate external reference clock, e.g. via NTP. 2811If you want to isolate the guest time from the host, you can set @option{clock} 2812to @code{rt} instead. To even prevent it from progressing during suspension, 2813you can set it to @code{vm}. 2814 2815Enable @option{driftfix} (i386 targets only) if you experience time drift problems, 2816specifically with Windows' ACPI HAL. This option will try to figure out how 2817many timer interrupts were not processed by the Windows guest and will 2818re-inject them. 2819ETEXI 2820 2821DEF("icount", HAS_ARG, QEMU_OPTION_icount, \ 2822 "-icount [N|auto]\n" \ 2823 " enable virtual instruction counter with 2^N clock ticks per\n" \ 2824 " instruction\n", QEMU_ARCH_ALL) 2825STEXI 2826@item -icount [@var{N}|auto] 2827@findex -icount 2828Enable virtual instruction counter. The virtual cpu will execute one 2829instruction every 2^@var{N} ns of virtual time. If @code{auto} is specified 2830then the virtual cpu speed will be automatically adjusted to keep virtual 2831time within a few seconds of real time. 2832 2833Note that while this option can give deterministic behavior, it does not 2834provide cycle accurate emulation. Modern CPUs contain superscalar out of 2835order cores with complex cache hierarchies. The number of instructions 2836executed often has little or no correlation with actual performance. 2837ETEXI 2838 2839DEF("watchdog", HAS_ARG, QEMU_OPTION_watchdog, \ 2840 "-watchdog i6300esb|ib700\n" \ 2841 " enable virtual hardware watchdog [default=none]\n", 2842 QEMU_ARCH_ALL) 2843STEXI 2844@item -watchdog @var{model} 2845@findex -watchdog 2846Create a virtual hardware watchdog device. Once enabled (by a guest 2847action), the watchdog must be periodically polled by an agent inside 2848the guest or else the guest will be restarted. 2849 2850The @var{model} is the model of hardware watchdog to emulate. Choices 2851for model are: @code{ib700} (iBASE 700) which is a very simple ISA 2852watchdog with a single timer, or @code{i6300esb} (Intel 6300ESB I/O 2853controller hub) which is a much more featureful PCI-based dual-timer 2854watchdog. Choose a model for which your guest has drivers. 2855 2856Use @code{-watchdog help} to list available hardware models. Only one 2857watchdog can be enabled for a guest. 2858ETEXI 2859 2860DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \ 2861 "-watchdog-action reset|shutdown|poweroff|pause|debug|none\n" \ 2862 " action when watchdog fires [default=reset]\n", 2863 QEMU_ARCH_ALL) 2864STEXI 2865@item -watchdog-action @var{action} 2866@findex -watchdog-action 2867 2868The @var{action} controls what QEMU will do when the watchdog timer 2869expires. 2870The default is 2871@code{reset} (forcefully reset the guest). 2872Other possible actions are: 2873@code{shutdown} (attempt to gracefully shutdown the guest), 2874@code{poweroff} (forcefully poweroff the guest), 2875@code{pause} (pause the guest), 2876@code{debug} (print a debug message and continue), or 2877@code{none} (do nothing). 2878 2879Note that the @code{shutdown} action requires that the guest responds 2880to ACPI signals, which it may not be able to do in the sort of 2881situations where the watchdog would have expired, and thus 2882@code{-watchdog-action shutdown} is not recommended for production use. 2883 2884Examples: 2885 2886@table @code 2887@item -watchdog i6300esb -watchdog-action pause 2888@item -watchdog ib700 2889@end table 2890ETEXI 2891 2892DEF("echr", HAS_ARG, QEMU_OPTION_echr, \ 2893 "-echr chr set terminal escape character instead of ctrl-a\n", 2894 QEMU_ARCH_ALL) 2895STEXI 2896 2897@item -echr @var{numeric_ascii_value} 2898@findex -echr 2899Change the escape character used for switching to the monitor when using 2900monitor and serial sharing. The default is @code{0x01} when using the 2901@code{-nographic} option. @code{0x01} is equal to pressing 2902@code{Control-a}. You can select a different character from the ascii 2903control keys where 1 through 26 map to Control-a through Control-z. For 2904instance you could use the either of the following to change the escape 2905character to Control-t. 2906@table @code 2907@item -echr 0x14 2908@item -echr 20 2909@end table 2910ETEXI 2911 2912DEF("virtioconsole", HAS_ARG, QEMU_OPTION_virtiocon, \ 2913 "-virtioconsole c\n" \ 2914 " set virtio console\n", QEMU_ARCH_ALL) 2915STEXI 2916@item -virtioconsole @var{c} 2917@findex -virtioconsole 2918Set virtio console. 2919 2920This option is maintained for backward compatibility. 2921 2922Please use @code{-device virtconsole} for the new way of invocation. 2923ETEXI 2924 2925DEF("show-cursor", 0, QEMU_OPTION_show_cursor, \ 2926 "-show-cursor show cursor\n", QEMU_ARCH_ALL) 2927STEXI 2928@item -show-cursor 2929@findex -show-cursor 2930Show cursor. 2931ETEXI 2932 2933DEF("tb-size", HAS_ARG, QEMU_OPTION_tb_size, \ 2934 "-tb-size n set TB size\n", QEMU_ARCH_ALL) 2935STEXI 2936@item -tb-size @var{n} 2937@findex -tb-size 2938Set TB size. 2939ETEXI 2940 2941DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \ 2942 "-incoming p prepare for incoming migration, listen on port p\n", 2943 QEMU_ARCH_ALL) 2944STEXI 2945@item -incoming @var{port} 2946@findex -incoming 2947Prepare for incoming migration, listen on @var{port}. 2948ETEXI 2949 2950DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \ 2951 "-nodefaults don't create default devices\n", QEMU_ARCH_ALL) 2952STEXI 2953@item -nodefaults 2954@findex -nodefaults 2955Don't create default devices. Normally, QEMU sets the default devices like serial 2956port, parallel port, virtual console, monitor device, VGA adapter, floppy and 2957CD-ROM drive and others. The @code{-nodefaults} option will disable all those 2958default devices. 2959ETEXI 2960 2961#ifndef _WIN32 2962DEF("chroot", HAS_ARG, QEMU_OPTION_chroot, \ 2963 "-chroot dir chroot to dir just before starting the VM\n", 2964 QEMU_ARCH_ALL) 2965#endif 2966STEXI 2967@item -chroot @var{dir} 2968@findex -chroot 2969Immediately before starting guest execution, chroot to the specified 2970directory. Especially useful in combination with -runas. 2971ETEXI 2972 2973#ifndef _WIN32 2974DEF("runas", HAS_ARG, QEMU_OPTION_runas, \ 2975 "-runas user change to user id user just before starting the VM\n", 2976 QEMU_ARCH_ALL) 2977#endif 2978STEXI 2979@item -runas @var{user} 2980@findex -runas 2981Immediately before starting guest execution, drop root privileges, switching 2982to the specified user. 2983ETEXI 2984 2985DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env, 2986 "-prom-env variable=value\n" 2987 " set OpenBIOS nvram variables\n", 2988 QEMU_ARCH_PPC | QEMU_ARCH_SPARC) 2989STEXI 2990@item -prom-env @var{variable}=@var{value} 2991@findex -prom-env 2992Set OpenBIOS nvram @var{variable} to given @var{value} (PPC, SPARC only). 2993ETEXI 2994DEF("semihosting", 0, QEMU_OPTION_semihosting, 2995 "-semihosting semihosting mode\n", QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA) 2996STEXI 2997@item -semihosting 2998@findex -semihosting 2999Semihosting mode (ARM, M68K, Xtensa only). 3000ETEXI 3001DEF("old-param", 0, QEMU_OPTION_old_param, 3002 "-old-param old param mode\n", QEMU_ARCH_ARM) 3003STEXI 3004@item -old-param 3005@findex -old-param (ARM) 3006Old param mode (ARM only). 3007ETEXI 3008 3009DEF("sandbox", HAS_ARG, QEMU_OPTION_sandbox, \ 3010 "-sandbox <arg> Enable seccomp mode 2 system call filter (default 'off').\n", 3011 QEMU_ARCH_ALL) 3012STEXI 3013@item -sandbox @var{arg} 3014@findex -sandbox 3015Enable Seccomp mode 2 system call filter. 'on' will enable syscall filtering and 'off' will 3016disable it. The default is 'off'. 3017ETEXI 3018 3019DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig, 3020 "-readconfig <file>\n", QEMU_ARCH_ALL) 3021STEXI 3022@item -readconfig @var{file} 3023@findex -readconfig 3024Read device configuration from @var{file}. This approach is useful when you want to spawn 3025QEMU process with many command line options but you don't want to exceed the command line 3026character limit. 3027ETEXI 3028DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig, 3029 "-writeconfig <file>\n" 3030 " read/write config file\n", QEMU_ARCH_ALL) 3031STEXI 3032@item -writeconfig @var{file} 3033@findex -writeconfig 3034Write device configuration to @var{file}. The @var{file} can be either filename to save 3035command line and device configuration into file or dash @code{-}) character to print the 3036output to stdout. This can be later used as input file for @code{-readconfig} option. 3037ETEXI 3038DEF("nodefconfig", 0, QEMU_OPTION_nodefconfig, 3039 "-nodefconfig\n" 3040 " do not load default config files at startup\n", 3041 QEMU_ARCH_ALL) 3042STEXI 3043@item -nodefconfig 3044@findex -nodefconfig 3045Normally QEMU loads configuration files from @var{sysconfdir} and @var{datadir} at startup. 3046The @code{-nodefconfig} option will prevent QEMU from loading any of those config files. 3047ETEXI 3048DEF("no-user-config", 0, QEMU_OPTION_nouserconfig, 3049 "-no-user-config\n" 3050 " do not load user-provided config files at startup\n", 3051 QEMU_ARCH_ALL) 3052STEXI 3053@item -no-user-config 3054@findex -no-user-config 3055The @code{-no-user-config} option makes QEMU not load any of the user-provided 3056config files on @var{sysconfdir}, but won't make it skip the QEMU-provided config 3057files from @var{datadir}. 3058ETEXI 3059DEF("trace", HAS_ARG, QEMU_OPTION_trace, 3060 "-trace [events=<file>][,file=<file>]\n" 3061 " specify tracing options\n", 3062 QEMU_ARCH_ALL) 3063STEXI 3064HXCOMM This line is not accurate, as some sub-options are backend-specific but 3065HXCOMM HX does not support conditional compilation of text. 3066@item -trace [events=@var{file}][,file=@var{file}] 3067@findex -trace 3068 3069Specify tracing options. 3070 3071@table @option 3072@item events=@var{file} 3073Immediately enable events listed in @var{file}. 3074The file must contain one event name (as listed in the @var{trace-events} file) 3075per line. 3076This option is only available if QEMU has been compiled with 3077either @var{simple} or @var{stderr} tracing backend. 3078@item file=@var{file} 3079Log output traces to @var{file}. 3080 3081This option is only available if QEMU has been compiled with 3082the @var{simple} tracing backend. 3083@end table 3084ETEXI 3085 3086HXCOMM Internal use 3087DEF("qtest", HAS_ARG, QEMU_OPTION_qtest, "", QEMU_ARCH_ALL) 3088DEF("qtest-log", HAS_ARG, QEMU_OPTION_qtest_log, "", QEMU_ARCH_ALL) 3089 3090#ifdef __linux__ 3091DEF("enable-fips", 0, QEMU_OPTION_enablefips, 3092 "-enable-fips enable FIPS 140-2 compliance\n", 3093 QEMU_ARCH_ALL) 3094#endif 3095STEXI 3096@item -enable-fips 3097@findex -enable-fips 3098Enable FIPS 140-2 compliance mode. 3099ETEXI 3100 3101HXCOMM Deprecated by -machine accel=tcg property 3102DEF("no-kvm", 0, QEMU_OPTION_no_kvm, "", QEMU_ARCH_I386) 3103 3104HXCOMM Deprecated by kvm-pit driver properties 3105DEF("no-kvm-pit-reinjection", 0, QEMU_OPTION_no_kvm_pit_reinjection, 3106 "", QEMU_ARCH_I386) 3107 3108HXCOMM Deprecated (ignored) 3109DEF("no-kvm-pit", 0, QEMU_OPTION_no_kvm_pit, "", QEMU_ARCH_I386) 3110 3111HXCOMM Deprecated by -machine kernel_irqchip=on|off property 3112DEF("no-kvm-irqchip", 0, QEMU_OPTION_no_kvm_irqchip, "", QEMU_ARCH_I386) 3113 3114HXCOMM Deprecated (ignored) 3115DEF("tdf", 0, QEMU_OPTION_tdf,"", QEMU_ARCH_ALL) 3116 3117DEF("object", HAS_ARG, QEMU_OPTION_object, 3118 "-object TYPENAME[,PROP1=VALUE1,...]\n" 3119 " create an new object of type TYPENAME setting properties\n" 3120 " in the order they are specified. Note that the 'id'\n" 3121 " property must be set. These objects are placed in the\n" 3122 " '/objects' path.\n", 3123 QEMU_ARCH_ALL) 3124STEXI 3125@item -object @var{typename}[,@var{prop1}=@var{value1},...] 3126@findex -object 3127Create an new object of type @var{typename} setting properties 3128in the order they are specified. Note that the 'id' 3129property must be set. These objects are placed in the 3130'/objects' path. 3131ETEXI 3132 3133DEF("msg", HAS_ARG, QEMU_OPTION_msg, 3134 "-msg timestamp[=on|off]\n" 3135 " change the format of messages\n" 3136 " on|off controls leading timestamps (default:on)\n", 3137 QEMU_ARCH_ALL) 3138STEXI 3139@item -msg timestamp[=on|off] 3140@findex -msg 3141prepend a timestamp to each log message.(default:on) 3142ETEXI 3143 3144HXCOMM This is the last statement. Insert new options before this line! 3145STEXI 3146@end table 3147ETEXI 3148
